Jump to content

User:Monster Iestyn/Source Code Documentation/doomtype.h

From SRB2 Wiki
This article or section is incomplete. It doesn't have all of the necessary core information on this topic. Please help the SRB2 Wiki by finishing this article.
Online link GitHub entry
File type C header file
#include guard __DOOMTYPE__

This file defines or includes standard types and features used by SRB2's source code in general, such as integer types, the boolean type, and attributes given to functions or variables by the compiler. Some other types such as RGBA_t and postimg_t are defined in this file, using it as a convenient location for them to be included from.

Includes

Special macros defined for this file:
  • RPC_NO_WINDOWS_H: prevents <rpc.h> (a file included by <windows.h>) from itself including <windows.h>
  • <nds.h>: Nintendo DS only
  • <arch/types.h>: Dreamcast only
  • <stdint.h>: included only if not compiling with Visual C++ or DJGPP, and not compiling for Dreamcast
Special macros defined for this file:
  • __STDC_LIMIT_MACROS: makes <stdint.h> define the limit macros (see below), even if __cplusplus is defined

Exact-width integer types and limits

In SRB2's source code, macros such as "UINT8" and "INT32" are nearly always used in place of basic types such as char, short, int and long (with some exceptions), because their actual sizes are implementation defined and may vary across different systems. Therefore, these macros are defined differently depending on the compiler that SRB2 is being compiled with, in order for them to consistently be the same size regardless.

A set of limit macros representing minimum and maximum values for these integer types may also be defined if they don't already exist. Note that if not compiling with either Visual C++ or DJGPP, and not compiling for Dreamcast (via KOS), <stdint.h> is included to define them for us; the macro __STDC_LIMIT_MACROS is defined beforehand to allow them to be defined even if the C++ compiler is in use.

Type macros

Integer type Description Minimum value Maximum value Size (bytes) Defined as
Visual C++ Dreamcast (KOS) DJGPP Other
UINT8 Unsigned 8-bit integer 0 UINT8_MAX 1 unsigned __int8 unsigned char uint8_t
SINT8 Signed 8-bit integer INT8_MIN INT8_MAX signed __int8 signed char int8_t
UINT16 Unsigned 16-bit integer 0 UINT16_MAX 2 unsigned __int16 uint16 unsigned short int uint16_t
INT16 Signed 16-bit integer INT16_MIN INT16_MAX __int16 int16 signed short int int16_t
UINT32 Unsigned 32-bit integer 0 UINT32_MAX 4 unsigned __int32 unsigned int unsigned long uint32_t
INT32 Signed 32-bit integer INT32_MIN INT32_MAX __int32 int signed long int32_t
UINT64 Unsigned 64-bit integer 0 UINT64_MAX 8 unsigned __int64 uint64 unsigned long long uint64_t
INT64 Signed 64-bit integer INT64_MIN INT64_MAX __int64 int64 signed long long int64_t

Limit macros

Macro Defined as
INT8_MIN (-128)
INT16_MIN (-32768)
INT32_MIN (-2147483647 - 1) (-2147483648)
INT64_MIN (-9223372036854775807LL - 1) (-9223372036854775808)
INT8_MAX 127
INT16_MAX 32767
INT32_MAX 2147483647
INT64_MAX 9223372036854775807LL (9223372036854775807)
UINT8_MAX 0xff (255)
UINT16_MAX 0xffff (65535)
UINT32_MAX 0xffffffff (4294967295)
UINT64_MAX 0xffffffffffffffffULL (18446744073709551615)

Boolean type

In SRB2's source code, the macros boolean, true and false are together used to represent the boolean data type. Depending on the port that SRB2 is being compiled for, doomtype.h may set these macros to other pre-defined macros provided by any included files (if boolean, true and false themselves are not already defined by them), or otherwise to arbitrary values if none exist.

Macro Defined as
Win32 Mac OS1 NDS2 PS32 Other
false FALSE 0 0 0 0
true TRUE 1 1 1 1
boolean BOOL INT32 bool bool enum {false, true}
1 These definitions are possibly not used at all, due to a possible error in the source code?
2 true and false are already defined in <stdbool.h>

Other data types

Name Type Attributes Description
ssize_t long A signed version of size_t.
RGBA_t
union FColorRGBA 		union ATTRPACK A special union used for handling RGBA colors (using the byte-order scheme). This is used mainly for getting the real color codes of palette indexes, and is also frequently used by the OpenGL rendering code in the context of lighting and colormapping.
postimg_t enum Image post-processing types.
lumpnum_t UINT32
tic_t UINT32

RGBA_t

Data name Data type Description
rgba UINT32 Combined value of red, green, blue and alpha levels.
s struct Struct for editing red, green, blue and alpha levels separately.
{
s red UINT8 The level of red.
green UINT8 The level of green.
blue UINT8 The level of blue.
alpha UINT8 The level of alpha.
}

postimg_t

Number Name Description
0 postimg_none No effect
1 postimg_water Water distortion effect
2 postimg_motion Motion blur (disabled)
3 postimg_flip Screen flipped upside-down
4 postimg_heat Heat wave effect

Macros

Macro Defined as Description
LUMPERROR UINT32_MAX Maximum value for lumpnum_t.
INFTICS UINT32_MAX Maximum value for tic_t.
UINT2RGBA(a) Big endian: 
a

Little endian: 

(UINT32)((a&0xff)<<24)|((a&0xff00)<<8)|((a&0xff0000)>>8)|(((UINT32)a&0xff000000)>>24)

String functions

As well as the C standard functions for handling strings included through string.h, SRB2 also uses various non-standard string functions such as strupr and strlwr. Some of these functions' names depend on what SRB2 is compiled with or the port SRB2 is compiled for (e.g.: strcasecmp and stricmp can both refer to the same function), and in some cases the functions need to be declared and defined in SRB2's code itself.

Macros

Macro Defined as Description
Visual C++/OS/2
snprintf _snprintf Visual C++, MSVC 2013 and below only

Variation of sprintf that writes a specific number of characters of the formatted data to a string buffer.

vsnprintf _vsnprintf Visual C++, v12.00 and below only

Variation of vsprintf that writes a specific number of characters of the formatted data to a string buffer.

strncasecmp strnicmp Case-insensitive version of strncmp.
strcasecmp stricmp Case-insensitive version of strcmp.
Watcom C/C++
strncasecmp strnicmp Case-insensitive version of strncmp.
strcasecmp strcmpi Case-insensitive version of strcmp.
Unix (non-MS-DOS)/Apple
stricmp(x,y) strcasecmp(x,y) Case-insensitive version of strcmp.
strnicmp(x,y,n) strncasecmp(x,y,n) Case-insensitive version of strncmp.
Windows CE
stricmp(x,y) _stricmp(x,y) Non-GCC compilers only

Case-insensitive version of strcmp.

strnicmp _strnicmp Non-GCC compilers only

Case-insensitive version of strncmp.

strdup _strdup Duplicates a string.
strupr _strupr Converts a string to uppercase.
strlwr _strlwr Converts a string to lowercase.
Mac OS
stricmp strcmp Case-insensitive version of strcmp. (Not supported?)
strnicmp strncmp Case-insensitive version of strncmp. (Not supported?)
Common
STRBUFCPY(dst,src) 
strlcpy(dst, src, sizeof dst)
Copies src to the string buffer dst. This should only be used with fixed-length buffers, i.e. char example[size], and not char * buffers – sizeof dst in the latter case will return the size of a pointer, rather than the number of bytes in the buffer.

Function prototypes

Function name Return type Params Defined in Description/Other notes
strupr int char *n
  • sdl/dosstr.c
  • sdl12/dosstr.c
 Declared only if HAVE_DOSSTR_FUNCS is undefined

Prototype of strupr for systems that do not have the function.

Converts a string to uppercase.

strlwr int char *n
  • sdl/dosstr.c
  • sdl12/dosstr.c
 Declared only if HAVE_DOSSTR_FUNCS is undefined

Prototype of strlwr for systems that do not have the function.

Converts a string to lowercase.

strlcat size_t char *dst,
const char *src,
size_t siz 		string.c Non-Apple systems only

Prototype of strlcat for systems that do not have the function.

A secure version of strncat that cannot overflow the destination buffer. Returns the length of the source string.

strlcpy size_t char *dst,
const char *src,
size_t siz 		string.c Non-Apple systems only

Prototype of strlcpy for systems that do not have the function.

A secure version of strncpy that cannot overflow the destination buffer. Returns the length of the source string.

Attributes and other compiler-specific macros

These are special macros that have effects specific to a particular compiler – in other compilers they will still be defined for compatibility, but will not be defined as anything meaningful at all. The majority of these macros apply special attributes to functions, variables or types, which may affect how they are compiled.

GCC-specific macros

Macro Defined as Description
FUNCPRINTF GCC 4.4 and above, MinGW 32-bit: 
__attribute__ ((format(ms_printf, 1, 2)))

Other GCC versions: 

__attribute__ ((format(printf, 1, 2)))
Assigns printf-like characteristics to a variadic function, allowing the compiler to check the format string against the following parameters provided. This is meant to be used only with functions where the first parameter is the "format string", and the second parameter onwards are variadic parameters.
FUNCDEBUG GCC 4.4 and above, MinGW 32-bit: 
__attribute__ ((format(ms_printf, 2, 3)))

Other GCC versions: 

__attribute__ ((format(printf, 2, 3)))
Same as FUNCPRINTF, but for functions where the second parameter is the "format string" and the third parameter onwards are variadic parameters. This macro is used with debugging functions such as CONS_Alert or CONS_Debug.
FUNCNORETURN 
__attribute__ ((noreturn))
Tells the compiler that the function never returns, suppressing errors about code paths not being reached. This macro is used for the function D_SRB2Loop (the main game loop function), I_Quit, and any functions that call I_Error or I_Quit.
FUNCIERROR GCC 4.4 and above, MinGW 32-bit: 
__attribute__ ((format(ms_printf, 1, 2),noreturn))

Other GCC versions: 

__attribute__ ((format(printf, 1, 2),noreturn))
Has the same effects as FUNCPRINTF and FUNCNORETURN combined. This macro is used on the function I_Error, hence the name of the macro.
FUNCMATH 
__attribute__((const))
This is to be used on math functions that have no static state or side effects and do not examine any values except their arguments. This mainly allows the compiler to optimize repeated calls to them when the compiler knows they will return the same value repeatedly. Examples of functions that use this macro are FixedMul, FixedDiv, and other fixed-point math functions with prototypes in m_fixed.h.
FUNCDEAD 
__attribute__ ((deprecated))
(GCC 3.1 and above only)

Results in a warning if the function is used anywhere in the source file.

FUNCINLINE 
__attribute__((always_inline))
(GCC 3.1 and above only)

For functions declared inline, this macro inlines the function even if no optimization level was specified.

FUNCNONNULL 
__attribute__((nonnull))
(GCC 3.1 and above only)

Specifies that some function parameters should be non-null pointers.

FUNCNOINLINE 
__attribute__((noinline))
Prevents a function from being considered for inlining.
FUNCTARGET(X) 
__attribute__ ((__target__ (X)))
(GCC 4.4 and above only, i386 only)

Used to specify that a function is to be compiled with different target options than specified on the command line.

ATTRPACK GCC 3.4 and above, MinGW 32-bit: 
__attribute__((packed, gcc_struct))

Other GCC versions: 

__attribute__((packed))
For a variable or structure field, this macro specifies that it should have the smallest possible alignment.

When attached to struct or union type definition, this macro specifies that each member of the structure or union is placed to minimize the memory required.

ATTRUNUSED 
__attribute__((unused))
GCC will not produce warnings if the function/variable/type is unused.
XBOXSTATIC 
static
The variable is static only for Xbox. (Xbox-only)
FILESTAMP 
I_OutputMsg("%s:%d\n",__FILE__,__LINE__);
Writes the current file name and line to the output device. (Xbox-only)

Visual C++ compiler-specific macros

Macro Defined as Description
ATTRNORETURN 
__declspec(noreturn)
Tells the compiler that the function never returns, suppressing errors about control paths not being reached.
ATTRINLINE 
__forceinline
Forces the compiler to inline a function. In other compilers this is defined as just inline.
ATTRNOINLINE 
__declspec(noinline)
Tells the compiler to never inline a particular member function. (v12.00 and above only)

Other macros

Macro Defined as Description
DWORD_PTR DWORD Visual C++, v12.00 and below only, defined only if DWORD_PTR is not already defined
PDWORD_PTR PDWORD Visual C++, v12.00 and below only, defined only if PDWORD_PTR is not already defined
DIRECTFULLSCREEN 1 __APPLE_CC__ only
DEBUG_LOG 1 __APPLE_CC__ only
NOIPX 1 __APPLE_CC__ only
inline __inline Visual C++ or OS/2 only
min(x,y) 
(((x)<(y)) ? (x) : (y))
Mac OS only
max(x,y) 
(((x)>(y)) ? (x) : (y))
Mac OS only
O_BINARY 0 Mac OS only, defined only if O_BINARY is not already defined
HAVE_DOSSTR_FUNCS 1 DOS, Win32, Wii, PSP, Dreamcast, Haiku, NDS or PS3 only

If this defined, no prototypes for strupr and strlwr are needed in this file. If they are needed however, sdl/dosstr.c provides the definitions for these functions.

Retrieved from "https://wiki.srb2.org/w/index.php?title=User:Monster_Iestyn/Source_Code_Documentation/doomtype.h&oldid=114524"