diff --git a/include/SDL3/SDL_assert.h b/include/SDL3/SDL_assert.h index 6f6cd19e90..167c64f5a6 100644 --- a/include/SDL3/SDL_assert.h +++ b/include/SDL3/SDL_assert.h @@ -156,14 +156,36 @@ extern "C" { #define SDL_TriggerBreakpoint() #endif -#if defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L) /* C99 supports __func__ as a standard. */ +#ifdef SDL_WIKI_DOCUMENTATION_SECTION +/** + * A macro that reports the current function being compiled. + * + * If SDL can't figure how the compiler reports this, it will use "???". + * + * \since This macro is available since SDL 3.1.3. + */ +#define SDL_FUNCTION __FUNCTION__ + +#elif defined(__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L) /* C99 supports __func__ as a standard. */ # define SDL_FUNCTION __func__ #elif ((defined(__GNUC__) && (__GNUC__ >= 2)) || defined(_MSC_VER) || defined (__WATCOMC__)) # define SDL_FUNCTION __FUNCTION__ #else # define SDL_FUNCTION "???" #endif + +/** + * A macro that reports the current file being compiled. + * + * \since This macro is available since SDL 3.1.3. + */ #define SDL_FILE __FILE__ + +/** + * A macro that reports the current line number of the file being compiled. + * + * \since This macro is available since SDL 3.1.3. + */ #define SDL_LINE __LINE__ /* @@ -181,14 +203,48 @@ This also solves the problem of... disable assertions. */ +#ifdef SDL_WIKI_DOCUMENTATION_SECTION +/** + * A macro for wrapping code in `do {} while (0);` without compiler warnings. + * + * Visual Studio with really aggressive warnings enabled needs this to avoid + * compiler complaints. + * + * the `do {} while (0);` trick is useful for wrapping code in a macro that + * may or may not be a single statement, to avoid various C language accidents. + * + * To use: + * + * ```c + * do { SomethingOnce(); } while (SDL_NULL_WHILE_LOOP_CONDITION (0)); + * ``` + * + * \since This macro is available since SDL 3.1.3. + */ +#define SDL_NULL_WHILE_LOOP_CONDITION (0) + +#elif defined _MSC_VER /* Avoid /W4 warnings. */ /* "while (0,0)" fools Microsoft's compiler's /W4 warning level into thinking this condition isn't constant. And looks like an owl's face! */ -#ifdef _MSC_VER /* stupid /W4 warnings. */ #define SDL_NULL_WHILE_LOOP_CONDITION (0,0) #else #define SDL_NULL_WHILE_LOOP_CONDITION (0) #endif +/** + * The macro used when an assertion is disabled. + * + * This isn't for direct use by apps, but this is the code that is inserted + * when an SDL_assert is disabled (perhaps in a release build). + * + * The code does nothing, but wraps `condition` in a sizeof operator, which + * generates no code and has no side effects, but avoid compiler warnings + * about unused variables. + * + * \param condition the condition to assert (but not actually run here). + * + * \since This macro is available since SDL 3.1.3. + */ #define SDL_disabled_assert(condition) \ do { (void) sizeof ((condition)); } while (SDL_NULL_WHILE_LOOP_CONDITION) @@ -237,7 +293,7 @@ typedef struct SDL_AssertData /** * Never call this directly. * - * Use the SDL_assert* macros instead. + * Use the SDL_assert macros instead. * * \param data assert data structure. * \param func function name. @@ -253,23 +309,48 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData * const char *func, const char *file, int line) SDL_ANALYZER_NORETURN; -/* Define the trigger breakpoint call used in asserts */ -#ifndef SDL_AssertBreakpoint -#if defined(ANDROID) && defined(assert) -/* Define this as empty in case assert() is defined as SDL_assert */ -#define SDL_AssertBreakpoint() -#else + +#ifdef SDL_WIKI_DOCUMENTATION_SECTION +/** + * The macro used when an assertion triggers a breakpoint. + * + * This isn't for direct use by apps; use SDL_assert or SDL_TriggerBreakpoint + * instead. + * + * \since This macro is available since SDL 3.1.3. + */ #define SDL_AssertBreakpoint() SDL_TriggerBreakpoint() -#endif + +#elif !defined(SDL_AssertBreakpoint) +# if defined(ANDROID) && defined(assert) + /* Define this as empty in case assert() is defined as SDL_assert */ +# define SDL_AssertBreakpoint() +# else +# define SDL_AssertBreakpoint() SDL_TriggerBreakpoint() +# endif #endif /* !SDL_AssertBreakpoint */ -/* the do {} while(0) avoids dangling else problems: - if (x) SDL_assert(y); else blah(); - ... without the do/while, the "else" could attach to this macro's "if". - We try to handle just the minimum we need here in a macro...the loop, - the static vars, and break points. The heavy lifting is handled in - SDL_ReportAssertion(), in SDL_assert.c. -*/ +/** + * The macro used when an assertion is enabled. + * + * This isn't for direct use by apps, but this is the code that is inserted + * when an SDL_assert is enabled. + * + * The `do {} while(0)` avoids dangling else problems: + * + * ```c + * if (x) SDL_assert(y); else blah(); + * ``` + * + * ... without the do/while, the "else" could attach to this macro's "if". + * We try to handle just the minimum we need here in a macro...the loop, + * the static vars, and break points. The heavy lifting is handled in + * SDL_ReportAssertion(). + * + * \param condition the condition to assert. + * + * \since This macro is available since SDL 3.1.3. + */ #define SDL_enabled_assert(condition) \ do { \ while ( !(condition) ) { \ diff --git a/include/SDL3/SDL_atomic.h b/include/SDL3/SDL_atomic.h index 14ba31fad8..32eb4ca959 100644 --- a/include/SDL3/SDL_atomic.h +++ b/include/SDL3/SDL_atomic.h @@ -155,6 +155,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnlockSpinlock(SDL_SpinLock *lock); * \since This macro is available since SDL 3.1.3. */ #define SDL_CompilerBarrier() DoCompilerSpecificReadWriteBarrier() + #elif defined(_MSC_VER) && (_MSC_VER > 1200) && !defined(__clang__) void _ReadWriteBarrier(void); #pragma intrinsic(_ReadWriteBarrier) @@ -171,7 +172,49 @@ extern __inline void SDL_CompilerBarrier(void); #endif /** - * Insert a memory release barrier. + * Insert a memory release barrier (function version). + * + * Please refer to SDL_MemoryBarrierRelease for details. This is a function + * version, which might be useful if you need to use this functionality from + * a scripting language, etc. Also, some of the macro versions call this + * function behind the scenes, where more heavy lifting can happen inside + * of SDL. Generally, though, an app written in C/C++/etc should use the macro + * version, as it will be more efficient. + * + * \threadsafety Obviously this function is safe to use from any thread at any + * time, but if you find yourself needing this, you are probably + * dealing with some very sensitive code; be careful! + * + * \since This function is available since SDL 3.1.3. + * + * \sa SDL_MemoryBarrierRelease + */ +extern SDL_DECLSPEC void SDLCALL SDL_MemoryBarrierReleaseFunction(void); + +/** + * Insert a memory acquire barrier (function version). + * + * Please refer to SDL_MemoryBarrierRelease for details. This is a function + * version, which might be useful if you need to use this functionality from + * a scripting language, etc. Also, some of the macro versions call this + * function behind the scenes, where more heavy lifting can happen inside + * of SDL. Generally, though, an app written in C/C++/etc should use the macro + * version, as it will be more efficient. + * + * \threadsafety Obviously this function is safe to use from any thread at any + * time, but if you find yourself needing this, you are probably + * dealing with some very sensitive code; be careful! + * + * \since This function is available since SDL 3.1.3. + * + * \sa SDL_MemoryBarrierAcquire + */ +extern SDL_DECLSPEC void SDLCALL SDL_MemoryBarrierAcquireFunction(void); + + +#ifdef SDL_WIKI_DOCUMENTATION_SECTION +/** + * Insert a memory release barrier (macro version). * * Memory barriers are designed to prevent reads and writes from being * reordered by the compiler and being seen out of order on multi-core CPUs. @@ -191,31 +234,47 @@ extern __inline void SDL_CompilerBarrier(void); * For more information on these semantics, take a look at the blog post: * http://preshing.com/20120913/acquire-and-release-semantics * + * This is the macro version of this functionality; if possible, SDL will + * use compiler intrinsics or inline assembly, but some platforms might + * need to call the function version of this, SDL_MemoryBarrierReleaseFunction + * to do the heavy lifting. Apps that can use the macro should favor it over + * the function. + * * \threadsafety Obviously this macro is safe to use from any thread at any * time, but if you find yourself needing this, you are probably * dealing with some very sensitive code; be careful! * - * \since This function is available since SDL 3.1.3. + * \since This macro is available since SDL 3.1.3. + * + * \sa SDL_MemoryBarrierAcquire + * \sa SDL_MemoryBarrierReleaseFunction */ -extern SDL_DECLSPEC void SDLCALL SDL_MemoryBarrierReleaseFunction(void); +#define SDL_MemoryBarrierRelease() SDL_MemoryBarrierReleaseFunction() /** - * Insert a memory acquire barrier. + * Insert a memory acquire barrier (macro version). * - * Please refer to SDL_MemoryBarrierReleaseFunction for the details! + * Please see SDL_MemoryBarrierRelease for the details on what memory barriers + * are and when to use them. * - * \threadsafety Obviously this function is safe to use from any thread at any + * This is the macro version of this functionality; if possible, SDL will + * use compiler intrinsics or inline assembly, but some platforms might + * need to call the function version of this, + * SDL_MemoryBarrierAcquireFunction, to do the heavy lifting. Apps that can + * use the macro should favor it over the function. + * + * \threadsafety Obviously this macro is safe to use from any thread at any * time, but if you find yourself needing this, you are probably * dealing with some very sensitive code; be careful! * - * \since This function is available since SDL 3.1.3. + * \since This macro is available since SDL 3.1.3. * - * \sa SDL_MemoryBarrierReleaseFunction + * \sa SDL_MemoryBarrierRelease + * \sa SDL_MemoryBarrierAcquireFunction */ -extern SDL_DECLSPEC void SDLCALL SDL_MemoryBarrierAcquireFunction(void); +#define SDL_MemoryBarrierAcquire() SDL_MemoryBarrierAcquireFunction() -/* !!! FIXME: this should have documentation! */ -#if defined(__GNUC__) && (defined(__powerpc__) || defined(__ppc__)) +#elif defined(__GNUC__) && (defined(__powerpc__) || defined(__ppc__)) #define SDL_MemoryBarrierRelease() __asm__ __volatile__ ("lwsync" : : : "memory") #define SDL_MemoryBarrierAcquire() __asm__ __volatile__ ("lwsync" : : : "memory") #elif defined(__GNUC__) && defined(__aarch64__) @@ -284,6 +343,7 @@ typedef void (*SDL_KernelMemoryBarrierFunc)(); * \since This macro is available since SDL 3.1.3. */ #define SDL_CPUPauseInstruction() DoACPUPauseInACompilerAndArchitectureSpecificWay + #elif (defined(__GNUC__) || defined(__clang__)) && (defined(__i386__) || defined(__x86_64__)) #define SDL_CPUPauseInstruction() __asm__ __volatile__("pause\n") /* Some assemblers can't do REP NOP, so go with PAUSE. */ #elif (defined(__arm__) && defined(__ARM_ARCH) && __ARM_ARCH >= 7) || defined(__aarch64__) diff --git a/include/SDL3/SDL_audio.h b/include/SDL3/SDL_audio.h index 45881e8345..3b66fed48f 100644 --- a/include/SDL3/SDL_audio.h +++ b/include/SDL3/SDL_audio.h @@ -141,14 +141,68 @@ extern "C" { #endif -/* masks for different parts of SDL_AudioFormat. */ +/** + * Mask of bits in an SDL_AudioFormat that contains the format bit size. + * + * Generally one should use SDL_AUDIO_BITSIZE instead of this macro directly. + * + * \since This macro is available since SDL 3.1.3. + */ #define SDL_AUDIO_MASK_BITSIZE (0xFFu) + +/** + * Mask of bits in an SDL_AudioFormat that contain the floating point flag. + * + * Generally one should use SDL_AUDIO_ISFLOAT instead of this macro directly. + * + * \since This macro is available since SDL 3.1.3. + */ #define SDL_AUDIO_MASK_FLOAT (1u<<8) + +/** + * Mask of bits in an SDL_AudioFormat that contain the bigendian flag. + * + * Generally one should use SDL_AUDIO_ISBIGENDIAN or SDL_AUDIO_ISLITTLEENDIAN + * instead of this macro directly. + * + * \since This macro is available since SDL 3.1.3. + */ #define SDL_AUDIO_MASK_BIG_ENDIAN (1u<<12) + +/** + * Mask of bits in an SDL_AudioFormat that contain the signed data flag. + * + * Generally one should use SDL_AUDIO_ISSIGNED instead of this macro directly. + * + * \since This macro is available since SDL 3.1.3. + */ #define SDL_AUDIO_MASK_SIGNED (1u<<15) -#define SDL_DEFINE_AUDIO_FORMAT(signed, bigendian, float, size) \ - (((Uint16)(signed) << 15) | ((Uint16)(bigendian) << 12) | ((Uint16)(float) << 8) | ((size) & SDL_AUDIO_MASK_BITSIZE)) +/** + * Define an SDL_AudioFormat value. + * + * SDL does not support custom audio formats, so this macro is not of much + * use externally, but it can be illustrative as to what the various bits of + * an SDL_AudioFormat mean. + * + * For example, SDL_AUDIO_S32LE looks like this: + * + * ```c + * SDL_DEFINE_AUDIO_FORMAT(1, 0, 0, 32) + * ``` + * + * \param signed 1 for signed data, 0 for unsigned data. + * \param bigendian 1 for bigendian data, 0 for littleendian data. + * \param flt 1 for floating point data, 0 for integer data. + * \param size number of bits per sample. + * \returns a format value in the style of SDL_AudioFormat. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.1.3. + */ +#define SDL_DEFINE_AUDIO_FORMAT(signed, bigendian, flt, size) \ + (((Uint16)(signed) << 15) | ((Uint16)(bigendian) << 12) | ((Uint16)(flt) << 8) | ((size) & SDL_AUDIO_MASK_BITSIZE)) /** * Audio format. @@ -399,14 +453,6 @@ typedef struct SDL_AudioStream SDL_AudioStream; /* Function prototypes */ -/** - * \name Driver discovery functions - * - * These functions return the list of built in audio drivers, in the - * order that they are normally initialized by default. - */ -/* @{ */ - /** * Use this function to get the number of built-in audio drivers. * @@ -453,7 +499,6 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetNumAudioDrivers(void); * \sa SDL_GetNumAudioDrivers */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAudioDriver(int index); -/* @} */ /** * Get the name of the current audio driver. diff --git a/include/SDL3/SDL_begin_code.h b/include/SDL3/SDL_begin_code.h index 396838fc43..bfb1c2cc2c 100644 --- a/include/SDL3/SDL_begin_code.h +++ b/include/SDL3/SDL_begin_code.h @@ -22,9 +22,12 @@ /* WIKI CATEGORY: BeginCode */ /** - * SDL_begin_code.h sets things up for C dynamic library function definitions, - * static inlined functions, and structures aligned at 4-byte alignment. - * If you don't like ugly C preprocessor code, don't look at this file. :) + * # CategoryBeginCode + * + * `SDL_begin_code.h` sets things up for C dynamic library function + * definitions, static inlined functions, and structures aligned at 4-byte + * alignment. If you don't like ugly C preprocessor code, don't look at this + * file. :) * * SDL's headers use this; applications generally should not include this * header directly. diff --git a/include/SDL3/SDL_gpu.h b/include/SDL3/SDL_gpu.h index 1ed93023f1..6b03a28a11 100644 --- a/include/SDL3/SDL_gpu.h +++ b/include/SDL3/SDL_gpu.h @@ -1504,13 +1504,6 @@ typedef struct SDL_GPUTextureCreateInfo SDL_PropertiesID props; /**< A properties ID for extensions. Should be 0 if no extensions are needed. */ } SDL_GPUTextureCreateInfo; -#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_R_FLOAT "SDL.gpu.createtexture.d3d12.clear.r" -#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_G_FLOAT "SDL.gpu.createtexture.d3d12.clear.g" -#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_B_FLOAT "SDL.gpu.createtexture.d3d12.clear.b" -#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_A_FLOAT "SDL.gpu.createtexture.d3d12.clear.a" -#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_DEPTH_FLOAT "SDL.gpu.createtexture.d3d12.clear.depth" -#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_STENCIL_UINT8 "SDL.gpu.createtexture.d3d12.clear.stencil" - /** * A structure specifying the parameters of a buffer. * @@ -2239,6 +2232,31 @@ extern SDL_DECLSPEC SDL_GPUShader *SDLCALL SDL_CreateGPUShader( * implementation will automatically fall back to the highest available sample * count. * + * There are optional properties that can be provided through + * SDL_GPUTextureCreateInfo's `props`. These are the supported properties: + * + * - `SDL_PROP_PROCESS_CREATE_ARGS_POINTER`: an array of strings containing + * the program to run, any arguments, and a NULL pointer, e.g. const char + * *args[] = { "myprogram", "argument", NULL }. This is a required property. + * - `SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_R_FLOAT`: (Direct3D 12 only) + * if the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the + * texture to a color with this red intensity. Defaults to zero. + * - `SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_G_FLOAT`: (Direct3D 12 only) + * if the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the + * texture to a color with this green intensity. Defaults to zero. + * - `SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_B_FLOAT`: (Direct3D 12 only) + * if the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the + * texture to a color with this blue intensity. Defaults to zero. + * - `SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_A_FLOAT`: (Direct3D 12 only) + * if the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the + * texture to a color with this alpha intensity. Defaults to zero. + * - `SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_DEPTH_FLOAT`: (Direct3D 12 only) + * if the texture usage is SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET, clear + * the texture to a depth of this value. Defaults to zero. + * - `SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_STENCIL_UINT8`: (Direct3D 12 only) + * if the texture usage is SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET, clear + * the texture to a stencil of this value. Defaults to zero. + * * \param device a GPU Context. * \param createinfo a struct describing the state of the texture to create. * \returns a texture object on success, or NULL on failure; call @@ -2261,6 +2279,14 @@ extern SDL_DECLSPEC SDL_GPUTexture *SDLCALL SDL_CreateGPUTexture( SDL_GPUDevice *device, const SDL_GPUTextureCreateInfo *createinfo); +#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_R_FLOAT "SDL.gpu.createtexture.d3d12.clear.r" +#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_G_FLOAT "SDL.gpu.createtexture.d3d12.clear.g" +#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_B_FLOAT "SDL.gpu.createtexture.d3d12.clear.b" +#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_A_FLOAT "SDL.gpu.createtexture.d3d12.clear.a" +#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_DEPTH_FLOAT "SDL.gpu.createtexture.d3d12.clear.depth" +#define SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_STENCIL_UINT8 "SDL.gpu.createtexture.d3d12.clear.stencil" + + /** * Creates a buffer object to be used in graphics or compute workflows. * diff --git a/include/SDL3/SDL_haptic.h b/include/SDL3/SDL_haptic.h index c123cd90cb..533f3bcee7 100644 --- a/include/SDL3/SDL_haptic.h +++ b/include/SDL3/SDL_haptic.h @@ -299,12 +299,24 @@ typedef struct SDL_Haptic SDL_Haptic; #define SDL_HAPTIC_LEFTRIGHT (1u<<11) /** - * Reserved for future use + * Reserved for future use. * * \since This macro is available since SDL 3.1.3. */ #define SDL_HAPTIC_RESERVED1 (1u<<12) + +/** + * Reserved for future use. + * + * \since This macro is available since SDL 3.1.3. + */ #define SDL_HAPTIC_RESERVED2 (1u<<13) + +/** + * Reserved for future use. + * + * \since This macro is available since SDL 3.1.3. + */ #define SDL_HAPTIC_RESERVED3 (1u<<14) /** diff --git a/include/SDL3/SDL_hints.h b/include/SDL3/SDL_hints.h index 1fee3d9548..1e03207d7d 100644 --- a/include/SDL3/SDL_hints.h +++ b/include/SDL3/SDL_hints.h @@ -4021,6 +4021,15 @@ extern "C" { * \since This hint is available since SDL 3.1.3. */ #define SDL_HINT_WINDOWS_INTRESOURCE_ICON "SDL_WINDOWS_INTRESOURCE_ICON" + +/** + * A variable to specify custom icon resource id from RC file on Windows + * platform. + * + * This hint should be set before SDL is initialized. + * + * \since This hint is available since SDL 3.1.3. + */ #define SDL_HINT_WINDOWS_INTRESOURCE_ICON_SMALL "SDL_WINDOWS_INTRESOURCE_ICON_SMALL" /** diff --git a/include/SDL3/SDL_init.h b/include/SDL3/SDL_init.h index e936f90978..92ced243ea 100644 --- a/include/SDL3/SDL_init.h +++ b/include/SDL3/SDL_init.h @@ -113,11 +113,71 @@ typedef enum SDL_AppResult SDL_APP_FAILURE /**< Value that requests termination with error from the main callbacks. */ } SDL_AppResult; +/** + * Function pointer typedef for SDL_AppInit. + * + * These are used by SDL_EnterAppMainCallbacks. This mechanism operates behind + * the scenes for apps using the optional main callbacks. Apps that want to use + * this should just implement SDL_AppInit directly. + * + * \param appstate a place where the app can optionally store a pointer for + * future use. + * \param argc the standard ANSI C main's argc; number of elements in `argv`. + * \param argv the standard ANSI C main's argv; array of command line + * arguments. + * \returns SDL_APP_FAILURE to terminate with an error, SDL_APP_SUCCESS to + * terminate with success, SDL_APP_CONTINUE to continue. + * + * \since This datatype is available since SDL 3.1.3. + */ typedef SDL_AppResult (SDLCALL *SDL_AppInit_func)(void **appstate, int argc, char *argv[]); + +/** + * Function pointer typedef for SDL_AppIterate. + * + * These are used by SDL_EnterAppMainCallbacks. This mechanism operates behind + * the scenes for apps using the optional main callbacks. Apps that want to use + * this should just implement SDL_AppIterate directly. + * + * \param appstate an optional pointer, provided by the app in SDL_AppInit. + * \returns SDL_APP_FAILURE to terminate with an error, SDL_APP_SUCCESS to + * terminate with success, SDL_APP_CONTINUE to continue. + * + * \since This datatype is available since SDL 3.1.3. + */ typedef SDL_AppResult (SDLCALL *SDL_AppIterate_func)(void *appstate); + +/** + * Function pointer typedef for SDL_AppEvent. + * + * These are used by SDL_EnterAppMainCallbacks. This mechanism operates behind + * the scenes for apps using the optional main callbacks. Apps that want to use + * this should just implement SDL_AppEvent directly. + * + * \param appstate an optional pointer, provided by the app in SDL_AppInit. + * \param event the new event for the app to examine. + * \returns SDL_APP_FAILURE to terminate with an error, SDL_APP_SUCCESS to + * terminate with success, SDL_APP_CONTINUE to continue. + * + * \since This datatype is available since SDL 3.1.3. + */ typedef SDL_AppResult (SDLCALL *SDL_AppEvent_func)(void *appstate, SDL_Event *event); + +/** + * Function pointer typedef for SDL_AppQuit. + * + * These are used by SDL_EnterAppMainCallbacks. This mechanism operates behind + * the scenes for apps using the optional main callbacks. Apps that want to use + * this should just implement SDL_AppEvent directly. + * + * \param appstate an optional pointer, provided by the app in SDL_AppInit. + * \param result the result code that terminated the app (success or failure). + * + * \since This datatype is available since SDL 3.1.3. + */ typedef void (SDLCALL *SDL_AppQuit_func)(void *appstate, SDL_AppResult result); + /** * Initialize the SDL library. * diff --git a/include/SDL3/SDL_intrin.h b/include/SDL3/SDL_intrin.h index 5f5805cc6f..77466b809f 100644 --- a/include/SDL3/SDL_intrin.h +++ b/include/SDL3/SDL_intrin.h @@ -267,7 +267,21 @@ _m_prefetch(void *__P) #endif #endif /* compiler version */ -#if defined(__clang__) && defined(__has_attribute) +#ifdef SDL_WIKI_DOCUMENTATION_SECTION +/** + * A macro to decide if the compiler supports `__attribute__((target))`. + * + * Even though this is defined in SDL's public headers, it is generally not + * used directly by apps. Apps should probably just use SDL_TARGETING + * directly, instead. + * + * \since This macro is available since SDL 3.1.3. + * + * \sa SDL_TARGETING + */ +#define SDL_HAS_TARGET_ATTRIBS + +#elif defined(__clang__) && defined(__has_attribute) # if __has_attribute(target) # define SDL_HAS_TARGET_ATTRIBS # endif @@ -277,7 +291,55 @@ _m_prefetch(void *__P) # define SDL_HAS_TARGET_ATTRIBS #endif -#ifdef SDL_HAS_TARGET_ATTRIBS + +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * A macro to tag a function as targeting a specific CPU architecture. + * + * This is a hint to the compiler that a function should be built with support + * for a CPU instruction set that might be different than the rest of the + * program. + * + * The particulars of this are explained in the GCC documentation: + * + * https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-target-function-attribute + * + * An example of using this feature is to turn on SSE2 support for a specific + * function, even if the rest of the source code is not compiled to use SSE2 + * code: + * + * ```c + * #ifdef SDL_SSE2_INTRINSICS + * static void SDL_TARGETING("sse2") DoSomethingWithSSE2(char *x) { + * ...use SSE2 intrinsic functions, etc... + * } + * #endif + * + * // later... + * #ifdef SDL_SSE2_INTRINSICS + * if (SDL_HasSSE2()) { + * DoSomethingWithSSE2(str); + * } + * #endif + * ``` + * + * The application is, on a whole, built without SSE2 instructions, so it + * will run on Intel machines that don't support SSE2. But then at runtime, + * it checks if the system supports the instructions, and then calls into a + * function that uses SSE2 opcodes. The ifdefs make sure that this code isn't + * used on platforms that don't have SSE2 at all. + * + * On compilers without target support, this is defined to nothing. + * + * This symbol is used by SDL internally, but apps and other libraries are + * welcome to use it for their own interfaces as well. + * + * \since This macro is available since SDL 3.1.3. + */ +#define SDL_TARGETING(x) __attribute__((target(x))) + +#elif defined(SDL_HAS_TARGET_ATTRIBS) # define SDL_TARGETING(x) __attribute__((target(x))) #else # define SDL_TARGETING(x) diff --git a/include/SDL3/SDL_main.h b/include/SDL3/SDL_main.h index d51977b63f..b244af1cd1 100644 --- a/include/SDL3/SDL_main.h +++ b/include/SDL3/SDL_main.h @@ -28,9 +28,9 @@ * should look like this: * * ```c - * int main(int argc, char *argv[]) - * { - * } + * int main(int argc, char *argv[]) + * { + * } * ``` * * SDL will take care of platform specific details on how it gets called. @@ -55,6 +55,84 @@ #include #include +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * Inform SDL that the app is providing an entry point instead of SDL. + * + * SDL does not define this macro, but will check if it is defined when + * including `SDL_main.h`. If defined, SDL will expect the app to provide the + * proper entry point for the platform, and all the other magic details + * needed, like manually calling SDL_SetMainReady. + * + * Please see [README/main-functions](README/main-functions), (or + * docs/README-main-functions.md in the source tree) for a more detailed + * explanation. + * + * \since This macro is used by the headers since SDL 3.1.3. + */ +#define SDL_MAIN_HANDLED 1 + +/** + * Inform SDL to use the main callbacks instead of main. + * + * SDL does not define this macro, but will check if it is defined when + * including `SDL_main.h`. If defined, SDL will expect the app to provide + * several functions: SDL_AppInit, SDL_AppEvent, SDL_AppIterate, and + * SDL_AppQuit. The app should not provide a `main` function in this case, and + * doing so will likely cause the build to fail. + * + * Please see [README/main-functions](README/main-functions), (or + * docs/README-main-functions.md in the source tree) for a more detailed + * explanation. + * + * \since This macro is used by the headers since SDL 3.1.3. + * + * \sa SDL_AppInit + * \sa SDL_AppEvent + * \sa SDL_AppIterate + * \sa SDL_AppQuit + */ +#define SDL_MAIN_USE_CALLBACKS 1 + +/** + * Defined if the target platform offers a special mainline through SDL. + * + * This won't be defined otherwise. If defined, SDL's headers will redefine + * `main` to `SDL_main`. + * + * This macro is defined by `SDL_main.h`, which is not automatically included + * by `SDL.h`. + * + * Even if available, an app can define SDL_MAIN_HANDLED and provide their + * own, if they know what they're doing. + * + * This macro is used internally by SDL, and apps probably shouldn't rely on it. + * + * \since This macro is available since SDL 3.1.3. + */ +#define SDL_MAIN_AVAILABLE + +/** + * Defined if the target platform _requires_ a special mainline through SDL. + * + * This won't be defined otherwise. If defined, SDL's headers will redefine + * `main` to `SDL_main`. + * + * This macro is defined by `SDL_main.h`, which is not automatically included + * by `SDL.h`. + * + * Even if required, an app can define SDL_MAIN_HANDLED and provide their + * own, if they know what they're doing. + * + * This macro is used internally by SDL, and apps probably shouldn't rely on it. + * + * \since This macro is available since SDL 3.1.3. + */ +#define SDL_MAIN_NEEDED + +#endif + #ifndef SDL_MAIN_HANDLED #if defined(SDL_PLATFORM_PRIVATE_MAIN) /* Private platforms may have their own ideas about entry points. */ @@ -144,7 +222,26 @@ #endif #endif /* SDL_MAIN_HANDLED */ -#ifdef SDL_MAIN_EXPORTED + +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * A macro to tag a main entry point function as exported. + * + * Most platforms don't need this, and the macro will be defined to nothing. + * Some, like Android, keep the entry points in a shared library and need to + * explicitly export the symbols. + * + * External code rarely needs this, and if it needs something, it's almost + * always SDL_DECLSPEC instead. + * + * \since This macro is available since SDL 3.1.3. + * + * \sa SDL_DECLSPEC + */ +#define SDLMAIN_DECLSPEC + +#elif defined(SDL_MAIN_EXPORTED) /* We need to export SDL_main so it can be launched from external code, like SDLActivity.java on Android */ #define SDLMAIN_DECLSPEC SDL_DECLSPEC @@ -153,31 +250,6 @@ #define SDLMAIN_DECLSPEC #endif /* SDL_MAIN_EXPORTED */ -#ifdef SDL_WIKI_DOCUMENTATION_SECTION - -/** - * Inform SDL to use the main callbacks instead of main. - * - * SDL does not define this macro, but will check if it is defined when - * including `SDL_main.h`. If defined, SDL will expect the app to provide - * several functions: SDL_AppInit, SDL_AppEvent, SDL_AppIterate, and - * SDL_AppQuit. The app should not provide a `main` function in this case, and - * doing so will likely cause the build to fail. - * - * Please see [README/main-functions](README/main-functions), (or - * docs/README-main-functions.md in the source tree) for a more detailed - * explanation. - * - * \since This macro is used by the headers since SDL 3.1.3. - * - * \sa SDL_AppInit - * \sa SDL_AppEvent - * \sa SDL_AppIterate - * \sa SDL_AppQuit - */ -#define SDL_MAIN_USE_CALLBACKS 1 -#endif - #if defined(SDL_MAIN_NEEDED) || defined(SDL_MAIN_AVAILABLE) || defined(SDL_MAIN_USE_CALLBACKS) #define main SDL_main #endif diff --git a/include/SDL3/SDL_mutex.h b/include/SDL3/SDL_mutex.h index b3fddeebd3..b6e65731ae 100644 --- a/include/SDL3/SDL_mutex.h +++ b/include/SDL3/SDL_mutex.h @@ -33,78 +33,224 @@ #include #include -/******************************************************************************/ -/* Enable thread safety attributes only with clang. +#ifdef SDL_WIKI_DOCUMENTATION_SECTION +/** + * Enable thread safety attributes, only with clang. + * * The attributes can be safely erased when compiling with other compilers. * * To enable analysis, set these environment variables before running cmake: - * export CC=clang - * export CFLAGS="-DSDL_THREAD_SAFETY_ANALYSIS -Wthread-safety" + * + * ```bash + * export CC=clang + * export CFLAGS="-DSDL_THREAD_SAFETY_ANALYSIS -Wthread-safety" + * ``` */ -#if defined(SDL_THREAD_SAFETY_ANALYSIS) && \ - defined(__clang__) && (!defined(SWIG)) +#define SDL_THREAD_ANNOTATION_ATTRIBUTE__(x) __attribute__((x)) + +#elif defined(SDL_THREAD_SAFETY_ANALYSIS) && defined(__clang__) && (!defined(SWIG)) #define SDL_THREAD_ANNOTATION_ATTRIBUTE__(x) __attribute__((x)) #else #define SDL_THREAD_ANNOTATION_ATTRIBUTE__(x) /* no-op */ #endif +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.1.3. + */ #define SDL_CAPABILITY(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(capability(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.1.3. + */ #define SDL_SCOPED_CAPABILITY \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(scoped_lockable) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.1.3. + */ #define SDL_GUARDED_BY(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(guarded_by(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.1.3. + */ #define SDL_PT_GUARDED_BY(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(pt_guarded_by(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.1.3. + */ #define SDL_ACQUIRED_BEFORE(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(acquired_before(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.1.3. + */ #define SDL_ACQUIRED_AFTER(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(acquired_after(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.1.3. + */ #define SDL_REQUIRES(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(requires_capability(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.1.3. + */ #define SDL_REQUIRES_SHARED(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(requires_shared_capability(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.1.3. + */ #define SDL_ACQUIRE(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(acquire_capability(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.1.3. + */ #define SDL_ACQUIRE_SHARED(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(acquire_shared_capability(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.1.3. + */ #define SDL_RELEASE(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(release_capability(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.1.3. + */ #define SDL_RELEASE_SHARED(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(release_shared_capability(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.1.3. + */ #define SDL_RELEASE_GENERIC(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(release_generic_capability(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.1.3. + */ #define SDL_TRY_ACQUIRE(x, y) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(try_acquire_capability(x, y)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.1.3. + */ #define SDL_TRY_ACQUIRE_SHARED(x, y) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(try_acquire_shared_capability(x, y)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.1.3. + */ #define SDL_EXCLUDES(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(locks_excluded(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.1.3. + */ #define SDL_ASSERT_CAPABILITY(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(assert_capability(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.1.3. + */ #define SDL_ASSERT_SHARED_CAPABILITY(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(assert_shared_capability(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.1.3. + */ #define SDL_RETURN_CAPABILITY(x) \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(lock_returned(x)) +/** + * Wrapper around Clang thread safety analysis annotations. + * + * Please see https://clang.llvm.org/docs/ThreadSafetyAnalysis.html#mutex-h + * + * \since This macro is available since SDL 3.1.3. + */ #define SDL_NO_THREAD_SAFETY_ANALYSIS \ SDL_THREAD_ANNOTATION_ATTRIBUTE__(no_thread_safety_analysis) diff --git a/include/SDL3/SDL_pixels.h b/include/SDL3/SDL_pixels.h index c8d340682e..112f1df23c 100644 --- a/include/SDL3/SDL_pixels.h +++ b/include/SDL3/SDL_pixels.h @@ -213,25 +213,170 @@ typedef enum SDL_PackedLayout SDL_PACKEDLAYOUT_1010102 } SDL_PackedLayout; +/** + * A macro for defining custom FourCC pixel formats. + * + * For example, defining SDL_PIXELFORMAT_YV12 looks like this: + * + * ```c + * SDL_DEFINE_PIXELFOURCC('Y', 'V', '1', '2') + * ``` + * + * \param A the first character of the FourCC code. + * \param B the second character of the FourCC code. + * \param C the third character of the FourCC code. + * \param D the fourth character of the FourCC code. + * \returns a format value in the style of SDL_PixelFormat. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.1.3. + */ #define SDL_DEFINE_PIXELFOURCC(A, B, C, D) SDL_FOURCC(A, B, C, D) +/** + * A macro for defining custom non-FourCC pixel formats. + * + * For example, defining SDL_PIXELFORMAT_RGBA8888 looks like this: + * + * ```c + * SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_RGBA, SDL_PACKEDLAYOUT_8888, 32, 4) + * ``` + * + * \param type the type of the new format, probably a SDL_PixelType value. + * \param order the order of the new format, probably a SDL_BitmapOrder, SDL_PackedOrder, or SDL_ArrayOrder value. + * \param layout the layout of the new format, probably an SDL_PackedLayout value or zero. + * \param bits the number of bits per pixel of the new format. + * \param bytes the number of bytes per pixel of the new format. + * \returns a format value in the style of SDL_PixelFormat. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.1.3. + */ #define SDL_DEFINE_PIXELFORMAT(type, order, layout, bits, bytes) \ ((1 << 28) | ((type) << 24) | ((order) << 20) | ((layout) << 16) | \ ((bits) << 8) | ((bytes) << 0)) -#define SDL_PIXELFLAG(X) (((X) >> 28) & 0x0F) -#define SDL_PIXELTYPE(X) (((X) >> 24) & 0x0F) -#define SDL_PIXELORDER(X) (((X) >> 20) & 0x0F) -#define SDL_PIXELLAYOUT(X) (((X) >> 16) & 0x0F) -#define SDL_BITSPERPIXEL(X) \ - (SDL_ISPIXELFORMAT_FOURCC(X) ? 0 : (((X) >> 8) & 0xFF)) -#define SDL_BYTESPERPIXEL(X) \ - (SDL_ISPIXELFORMAT_FOURCC(X) ? \ - ((((X) == SDL_PIXELFORMAT_YUY2) || \ - ((X) == SDL_PIXELFORMAT_UYVY) || \ - ((X) == SDL_PIXELFORMAT_YVYU) || \ - ((X) == SDL_PIXELFORMAT_P010)) ? 2 : 1) : (((X) >> 0) & 0xFF)) +/** + * A macro to retrieve the flags of an SDL_PixelFormat. + * + * This macro is generally not needed directly by an app, which should use + * specific tests, like SDL_ISPIXELFORMAT_FOURCC, instead. + * + * \param format an SDL_PixelFormat to check. + * \returns the flags of `format`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.1.3. + */ +#define SDL_PIXELFLAG(format) (((format) >> 28) & 0x0F) +/** + * A macro to retrieve the type of an SDL_PixelFormat. + * + * This is usually a value from the SDL_PixelType enumeration. + * + * \param format an SDL_PixelFormat to check. + * \returns the type of `format`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.1.3. + */ +#define SDL_PIXELTYPE(format) (((format) >> 24) & 0x0F) + +/** + * A macro to retrieve the order of an SDL_PixelFormat. + * + * This is usually a value from the SDL_BitmapOrder, SDL_PackedOrder, or + * SDL_ArrayOrder enumerations, depending on the format type. + * + * \param format an SDL_PixelFormat to check. + * \returns the order of `format`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.1.3. + */ +#define SDL_PIXELORDER(format) (((format) >> 20) & 0x0F) + +/** + * A macro to retrieve the layout of an SDL_PixelFormat. + * + * This is usually a value from the SDL_PackedLayout enumeration, or zero if + * a layout doesn't make sense for the format type. + * + * \param format an SDL_PixelFormat to check. + * \returns the layout of `format`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.1.3. + */ +#define SDL_PIXELLAYOUT(format) (((format) >> 16) & 0x0F) + +/** + * A macro to determine an SDL_PixelFormat's bits per pixel. + * + * Note that this macro double-evaluates its parameter, so do not use + * expressions with side-effects here. + * + * FourCC formats will report zero here, as it rarely makes sense to measure + * them per-pixel. + * + * \param format an SDL_PixelFormat to check. + * \returns the bits-per-pixel of `format`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.1.3. + * + * \sa SDL_BYTESPERPIXEL + */ +#define SDL_BITSPERPIXEL(format) \ + (SDL_ISPIXELFORMAT_FOURCC(format) ? 0 : (((format) >> 8) & 0xFF)) + +/** + * A macro to determine an SDL_PixelFormat's bytes per pixel. + * + * Note that this macro double-evaluates its parameter, so do not use + * expressions with side-effects here. + * + * FourCC formats do their best here, but many of them don't have a meaningful + * measurement of bytes per pixel. + * + * \param format an SDL_PixelFormat to check. + * \returns the bytes-per-pixel of `format`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.1.3. + * + * \sa SDL_BITSPERPIXEL + */ +#define SDL_BYTESPERPIXEL(format) \ + (SDL_ISPIXELFORMAT_FOURCC(format) ? \ + ((((format) == SDL_PIXELFORMAT_YUY2) || \ + ((format) == SDL_PIXELFORMAT_UYVY) || \ + ((format) == SDL_PIXELFORMAT_YVYU) || \ + ((format) == SDL_PIXELFORMAT_P010)) ? 2 : 1) : (((format) >> 0) & 0xFF)) + + +/** + * A macro to determine if an SDL_PixelFormat is an indexed format. + * + * Note that this macro double-evaluates its parameter, so do not use + * expressions with side-effects here. + * + * \param format an SDL_PixelFormat to check. + * \returns true if the format is indexed, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.1.3. + */ #define SDL_ISPIXELFORMAT_INDEXED(format) \ (!SDL_ISPIXELFORMAT_FOURCC(format) && \ ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX1) || \ @@ -239,12 +384,38 @@ typedef enum SDL_PackedLayout (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX4) || \ (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_INDEX8))) +/** + * A macro to determine if an SDL_PixelFormat is a packed format. + * + * Note that this macro double-evaluates its parameter, so do not use + * expressions with side-effects here. + * + * \param format an SDL_PixelFormat to check. + * \returns true if the format is packed, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.1.3. + */ #define SDL_ISPIXELFORMAT_PACKED(format) \ (!SDL_ISPIXELFORMAT_FOURCC(format) && \ ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_PACKED8) || \ (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_PACKED16) || \ (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_PACKED32))) +/** + * A macro to determine if an SDL_PixelFormat is an array format. + * + * Note that this macro double-evaluates its parameter, so do not use + * expressions with side-effects here. + * + * \param format an SDL_PixelFormat to check. + * \returns true if the format is an array, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.1.3. + */ #define SDL_ISPIXELFORMAT_ARRAY(format) \ (!SDL_ISPIXELFORMAT_FOURCC(format) && \ ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYU8) || \ @@ -253,16 +424,55 @@ typedef enum SDL_PackedLayout (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYF16) || \ (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYF32))) +/** + * A macro to determine if an SDL_PixelFormat is a 10-bit format. + * + * Note that this macro double-evaluates its parameter, so do not use + * expressions with side-effects here. + * + * \param format an SDL_PixelFormat to check. + * \returns true if the format is 10-bit, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.1.3. + */ #define SDL_ISPIXELFORMAT_10BIT(format) \ (!SDL_ISPIXELFORMAT_FOURCC(format) && \ ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_PACKED32) && \ (SDL_PIXELLAYOUT(format) == SDL_PACKEDLAYOUT_2101010))) +/** + * A macro to determine if an SDL_PixelFormat is a floating point format. + * + * Note that this macro double-evaluates its parameter, so do not use + * expressions with side-effects here. + * + * \param format an SDL_PixelFormat to check. + * \returns true if the format is 10-bit, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.1.3. + */ #define SDL_ISPIXELFORMAT_FLOAT(format) \ (!SDL_ISPIXELFORMAT_FOURCC(format) && \ ((SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYF16) || \ (SDL_PIXELTYPE(format) == SDL_PIXELTYPE_ARRAYF32))) +/** + * A macro to determine if an SDL_PixelFormat has an alpha channel. + * + * Note that this macro double-evaluates its parameter, so do not use + * expressions with side-effects here. + * + * \param format an SDL_PixelFormat to check. + * \returns true if the format has alpha, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.1.3. + */ #define SDL_ISPIXELFORMAT_ALPHA(format) \ ((SDL_ISPIXELFORMAT_PACKED(format) && \ ((SDL_PIXELORDER(format) == SDL_PACKEDORDER_ARGB) || \ @@ -275,8 +485,23 @@ typedef enum SDL_PackedLayout (SDL_PIXELORDER(format) == SDL_ARRAYORDER_ABGR) || \ (SDL_PIXELORDER(format) == SDL_ARRAYORDER_BGRA)))) -/* The flag is set to 1 because 0x1? is not in the printable ASCII range */ -#define SDL_ISPIXELFORMAT_FOURCC(format) \ + +/** + * A macro to determine if an SDL_PixelFormat is a "FourCC" format. + * + * This covers custom and other unusual formats. + * + * Note that this macro double-evaluates its parameter, so do not use + * expressions with side-effects here. + * + * \param format an SDL_PixelFormat to check. + * \returns true if the format has alpha, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.1.3. + */ +#define SDL_ISPIXELFORMAT_FOURCC(format) /* The flag is set to 1 because 0x1? is not in the printable ASCII range */ \ ((format) && (SDL_PIXELFLAG(format) != 1)) /* Note: If you modify this enum, update SDL_GetPixelFormatName() */ @@ -591,22 +816,171 @@ typedef enum SDL_ChromaLocation /* Colorspace definition */ + +/** + * A macro for defining custom SDL_Colorspace formats. + * + * For example, defining SDL_COLORSPACE_SRGB looks like this: + * + * ```c + * SDL_DEFINE_COLORSPACE(SDL_COLOR_TYPE_RGB, + * SDL_COLOR_RANGE_FULL, + * SDL_COLOR_PRIMARIES_BT709, + * SDL_TRANSFER_CHARACTERISTICS_SRGB, + * SDL_MATRIX_COEFFICIENTS_IDENTITY, + * SDL_CHROMA_LOCATION_NONE) + * ``` + * + * \param type the type of the new format, probably an SDL_ColorType value. + * \param range the range of the new format, probably a SDL_ColorRange value. + * \param primaries the primaries of the new format, probably an SDL_ColorPrimaries value. + * \param transfer the transfer characteristics of the new format, probably an SDL_TransferCharacteristics value. + * \param matrix the matrix coefficients of the new format, probably an SDL_MatrixCoefficients value. + * \param chroma the chroma sample location of the new format, probably an SDL_ChromaLocation value. + * \returns a format value in the style of SDL_Colorspace. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.1.3. + */ #define SDL_DEFINE_COLORSPACE(type, range, primaries, transfer, matrix, chroma) \ (((Uint32)(type) << 28) | ((Uint32)(range) << 24) | ((Uint32)(chroma) << 20) | \ ((Uint32)(primaries) << 10) | ((Uint32)(transfer) << 5) | ((Uint32)(matrix) << 0)) -#define SDL_COLORSPACETYPE(X) (SDL_ColorType)(((X) >> 28) & 0x0F) -#define SDL_COLORSPACERANGE(X) (SDL_ColorRange)(((X) >> 24) & 0x0F) -#define SDL_COLORSPACECHROMA(X) (SDL_ChromaLocation)(((X) >> 20) & 0x0F) -#define SDL_COLORSPACEPRIMARIES(X) (SDL_ColorPrimaries)(((X) >> 10) & 0x1F) -#define SDL_COLORSPACETRANSFER(X) (SDL_TransferCharacteristics)(((X) >> 5) & 0x1F) -#define SDL_COLORSPACEMATRIX(X) (SDL_MatrixCoefficients)((X) & 0x1F) +/** + * A macro to retrieve the type of an SDL_Colorspace. + * + * \param cspace an SDL_Colorspace to check. + * \returns the SDL_ColorType for `cspace`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.1.3. + */ +#define SDL_COLORSPACETYPE(cspace) (SDL_ColorType)(((cspace) >> 28) & 0x0F) -#define SDL_ISCOLORSPACE_MATRIX_BT601(X) (SDL_COLORSPACEMATRIX(X) == SDL_MATRIX_COEFFICIENTS_BT601 || SDL_COLORSPACEMATRIX(X) == SDL_MATRIX_COEFFICIENTS_BT470BG) -#define SDL_ISCOLORSPACE_MATRIX_BT709(X) (SDL_COLORSPACEMATRIX(X) == SDL_MATRIX_COEFFICIENTS_BT709) -#define SDL_ISCOLORSPACE_MATRIX_BT2020_NCL(X) (SDL_COLORSPACEMATRIX(X) == SDL_MATRIX_COEFFICIENTS_BT2020_NCL) -#define SDL_ISCOLORSPACE_LIMITED_RANGE(X) (SDL_COLORSPACERANGE(X) != SDL_COLOR_RANGE_FULL) -#define SDL_ISCOLORSPACE_FULL_RANGE(X) (SDL_COLORSPACERANGE(X) == SDL_COLOR_RANGE_FULL) +/** + * A macro to retrieve the range of an SDL_Colorspace. + * + * \param cspace an SDL_Colorspace to check. + * \returns the SDL_ColorRange of `cspace`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.1.3. + */ +#define SDL_COLORSPACERANGE(cspace) (SDL_ColorRange)(((cspace) >> 24) & 0x0F) + +/** + * A macro to retrieve the chroma sample location of an SDL_Colorspace. + * + * \param cspace an SDL_Colorspace to check. + * \returns the SDL_ChromaLocation of `cspace`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.1.3. + */ +#define SDL_COLORSPACECHROMA(cspace) (SDL_ChromaLocation)(((cspace) >> 20) & 0x0F) + +/** + * A macro to retrieve the primaries of an SDL_Colorspace. + * + * \param cspace an SDL_Colorspace to check. + * \returns the SDL_ColorPrimaries of `cspace`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.1.3. + */ +#define SDL_COLORSPACEPRIMARIES(cspace) (SDL_ColorPrimaries)(((cspace) >> 10) & 0x1F) + +/** + * A macro to retrieve the transfer characteristics of an SDL_Colorspace. + * + * \param cspace an SDL_Colorspace to check. + * \returns the SDL_TransferCharacteristics of `cspace`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.1.3. + */ +#define SDL_COLORSPACETRANSFER(cspace) (SDL_TransferCharacteristics)(((cspace) >> 5) & 0x1F) + +/** + * A macro to retrieve the matrix coefficients of an SDL_Colorspace. + * + * \param cspace an SDL_Colorspace to check. + * \returns the SDL_MatrixCoefficients of `cspace`. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.1.3. + */ +#define SDL_COLORSPACEMATRIX(cspace) (SDL_MatrixCoefficients)((cspace) & 0x1F) + +/** + * A macro to determine if an SDL_Colorspace uses BT601 (or BT470BG) matrix coefficients. + * + * Note that this macro double-evaluates its parameter, so do not use + * expressions with side-effects here. + * + * \param cspace an SDL_Colorspace to check. + * \returns true if BT601 or BT470BG, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.1.3. + */ +#define SDL_ISCOLORSPACE_MATRIX_BT601(cspace) (SDL_COLORSPACEMATRIX(cspace) == SDL_MATRIX_COEFFICIENTS_BT601 || SDL_COLORSPACEMATRIX(cspace) == SDL_MATRIX_COEFFICIENTS_BT470BG) + +/** + * A macro to determine if an SDL_Colorspace uses BT709 matrix coefficients. + * + * \param cspace an SDL_Colorspace to check. + * \returns true if BT709, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.1.3. + */ +#define SDL_ISCOLORSPACE_MATRIX_BT709(cspace) (SDL_COLORSPACEMATRIX(cspace) == SDL_MATRIX_COEFFICIENTS_BT709) + +/** + * A macro to determine if an SDL_Colorspace uses BT2020_NCL matrix coefficients. + * + * \param cspace an SDL_Colorspace to check. + * \returns true if BT709, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.1.3. + */ +#define SDL_ISCOLORSPACE_MATRIX_BT2020_NCL(cspace) (SDL_COLORSPACEMATRIX(cspace) == SDL_MATRIX_COEFFICIENTS_BT2020_NCL) + +/** + * A macro to determine if an SDL_Colorspace has a limited range. + * + * \param cspace an SDL_Colorspace to check. + * \returns true if limited range, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.1.3. + */ +#define SDL_ISCOLORSPACE_LIMITED_RANGE(cspace) (SDL_COLORSPACERANGE(cspace) != SDL_COLOR_RANGE_FULL) + +/** + * A macro to determine if an SDL_Colorspace has a full range. + * + * \param cspace an SDL_Colorspace to check. + * \returns true if full range, false otherwise. + * + * \threadsafety It is safe to call this macro from any thread. + * + * \since This macro is available since SDL 3.1.3. + */ +#define SDL_ISCOLORSPACE_FULL_RANGE(cspace) (SDL_COLORSPACERANGE(cspace) == SDL_COLOR_RANGE_FULL) /** * Colorspace definitions. diff --git a/include/SDL3/SDL_platform_defines.h b/include/SDL3/SDL_platform_defines.h index 0030a15fec..ee687215ac 100644 --- a/include/SDL3/SDL_platform_defines.h +++ b/include/SDL3/SDL_platform_defines.h @@ -357,7 +357,15 @@ #define WINAPI_FAMILY_WINRT 0 #endif /* HAVE_WINAPIFAMILY_H */ -#if HAVE_WINAPIFAMILY_H && HAVE_WINAPIFAMILY_H +#ifdef SDL_WIKI_DOCUMENTATION_SECTION +/** + * A preprocessor macro that defined to 1 if compiling for Windows Phone. + * + * \since This macro is available since SDL 3.1.3. + */ +#define SDL_WINAPI_FAMILY_PHONE (WINAPI_FAMILY == WINAPI_FAMILY_PHONE_APP) + +#elif HAVE_WINAPIFAMILY_H && HAVE_WINAPIFAMILY_H #define SDL_WINAPI_FAMILY_PHONE (WINAPI_FAMILY == WINAPI_FAMILY_PHONE_APP) #else #define SDL_WINAPI_FAMILY_PHONE 0 diff --git a/include/SDL3/SDL_process.h b/include/SDL3/SDL_process.h index d86bb372c8..7cabeee04c 100644 --- a/include/SDL3/SDL_process.h +++ b/include/SDL3/SDL_process.h @@ -54,6 +54,13 @@ extern "C" { #endif +/** + * An opaque handle representing a system process. + * + * \since This datatype is available since SDL 3.1.3. + * + * \sa SDL_CreateProcess + */ typedef struct SDL_Process SDL_Process; /** diff --git a/include/SDL3/SDL_stdinc.h b/include/SDL3/SDL_stdinc.h index 73dd80af09..0780528720 100644 --- a/include/SDL3/SDL_stdinc.h +++ b/include/SDL3/SDL_stdinc.h @@ -753,7 +753,288 @@ SDL_COMPILE_TIME_ASSERT(longlong_size64, sizeof(long long) == 8); /* using I64 f #endif /* Annotations to help code analysis tools */ -#ifdef SDL_DISABLE_ANALYZE_MACROS +#ifdef SDL_WIKI_DOCUMENTATION_SECTION + +/** + * Macro that annotates function params with input buffer size. + * + * If we were to annotate `memcpy`: + * + * ```c + * void *memcpy(void *dst, SDL_IN_BYTECAP(len) const void *src, size_t len); + * ``` + * + * This notes that `src` should be `len` bytes in size and is only read by the + * function. The compiler or other analysis tools can warn when this doesn't + * appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * \since This macro is available since SDL 3.1.3. + */ +#define SDL_IN_BYTECAP(x) _In_bytecount_(x) + +/** + * Macro that annotates function params with input/output string buffer size. + * + * If we were to annotate `strlcat`: + * + * ```c + * size_t strlcat(SDL_INOUT_Z_CAP(maxlen) char *dst, const char *src, size_t maxlen); + * ``` + * + * This notes that `dst` is a null-terminated C string, should be `maxlen` + * bytes in size, and is both read from and written to by the function. The + * compiler or other analysis tools can warn when this doesn't appear to be + * the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * \since This macro is available since SDL 3.1.3. + */ +#define SDL_INOUT_Z_CAP(x) _Inout_z_cap_(x) + +/** + * Macro that annotates function params with output string buffer size. + * + * If we were to annotate `snprintf`: + * + * ```c + * int snprintf(SDL_OUT_Z_CAP(maxlen) char *text, size_t maxlen, const char *fmt, ...); + * ``` + * + * This notes that `text` is a null-terminated C string, should be `maxlen` + * bytes in size, and is only written to by the function. The compiler or + * other analysis tools can warn when this doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * \since This macro is available since SDL 3.1.3. + */ +#define SDL_OUT_Z_CAP(x) _Out_z_cap_(x) + +/** + * Macro that annotates function params with output buffer size. + * + * If we were to annotate `wcsncpy`: + * + * ```c + * char *wcscpy(SDL_OUT_CAP(bufsize) wchar_t *dst, const wchar_t *src, size_t bufsize); + * ``` + * + * This notes that `dst` should have a capacity of `bufsize` wchar_t in size, + * and is only written to by the function. The compiler or other analysis + * tools can warn when this doesn't appear to be the case. + * + * This operates on counts of objects, not bytes. Use SDL_OUT_BYTECAP for bytes. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * \since This macro is available since SDL 3.1.3. + */ +#define SDL_OUT_CAP(x) _Out_cap_(x) + +/** + * Macro that annotates function params with output buffer size. + * + * If we were to annotate `memcpy`: + * + * ```c + * void *memcpy(SDL_OUT_BYTECAP(bufsize) void *dst, const void *src, size_t bufsize); + * ``` + * + * This notes that `dst` should have a capacity of `bufsize` bytes in size, + * and is only written to by the function. The compiler or other analysis + * tools can warn when this doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * \since This macro is available since SDL 3.1.3. + */ +#define SDL_OUT_BYTECAP(x) _Out_bytecap_(x) + +/** + * Macro that annotates function params with output buffer string size. + * + * If we were to annotate `strcpy`: + * + * ```c + * char *strcpy(SDL_OUT_Z_BYTECAP(bufsize) char *dst, const char *src, size_t bufsize); + * ``` + * + * This notes that `dst` should have a capacity of `bufsize` bytes in size, + * and a zero-terminated string is written to it by the function. The compiler + * or other analysis tools can warn when this doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * \since This macro is available since SDL 3.1.3. + */ +#define SDL_OUT_Z_BYTECAP(x) _Out_z_bytecap_(x) + +/** + * Macro that annotates function params as printf-style format strings. + * + * If we were to annotate `fprintf`: + * + * ```c + * int fprintf(FILE *f, SDL_PRINTF_FORMAT_STRING const char *fmt, ...); + * ``` + * + * This notes that `fmt` should be a printf-style format string. The compiler + * or other analysis tools can warn when this doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * \since This macro is available since SDL 3.1.3. + */ +#define SDL_PRINTF_FORMAT_STRING _Printf_format_string_ + +/** + * Macro that annotates function params as scanf-style format strings. + * + * If we were to annotate `fscanf`: + * + * ```c + * int fscanf(FILE *f, SDL_SCANF_FORMAT_STRING const char *fmt, ...); + * ``` + * + * This notes that `fmt` should be a scanf-style format string. The compiler + * or other analysis tools can warn when this doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * \since This macro is available since SDL 3.1.3. + */ +#define SDL_SCANF_FORMAT_STRING _Scanf_format_string_impl_ + +/** + * Macro that annotates a vararg function that operates like printf. + * + * If we were to annotate `fprintf`: + * + * ```c + * int fprintf(FILE *f, const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2); + * ``` + * + * This notes that the second parameter should be a printf-style format string, followed by `...`. + * The compiler or other analysis tools can warn when this doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * This can (and should) be used with SDL_PRINTF_FORMAT_STRING as well, which between them + * will cover at least Visual Studio, GCC, and Clang. + * + * \since This macro is available since SDL 3.1.3. + */ +#define SDL_PRINTF_VARARG_FUNC( fmtargnumber ) __attribute__ (( format( __printf__, fmtargnumber, fmtargnumber+1 ))) + +/** + * Macro that annotates a va_list function that operates like printf. + * + * If we were to annotate `vfprintf`: + * + * ```c + * int vfprintf(FILE *f, const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(2); + * ``` + * + * This notes that the second parameter should be a printf-style format string, followed by a va_list. + * The compiler or other analysis tools can warn when this doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * This can (and should) be used with SDL_PRINTF_FORMAT_STRING as well, which between them + * will cover at least Visual Studio, GCC, and Clang. + * + * \since This macro is available since SDL 3.1.3. + */ +#define SDL_PRINTF_VARARG_FUNCV( fmtargnumber ) __attribute__(( format( __printf__, fmtargnumber, 0 ))) + +/** + * Macro that annotates a vararg function that operates like scanf. + * + * If we were to annotate `fscanf`: + * + * ```c + * int fscanf(FILE *f, const char *fmt, ...) SDL_PRINTF_VARARG_FUNCV(2); + * ``` + * + * This notes that the second parameter should be a scanf-style format string, followed by `...`. + * The compiler or other analysis tools can warn when this doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * This can (and should) be used with SDL_SCANF_FORMAT_STRING as well, which between them + * will cover at least Visual Studio, GCC, and Clang. + * + * \since This macro is available since SDL 3.1.3. + */ +#define SDL_SCANF_VARARG_FUNC( fmtargnumber ) __attribute__ (( format( __scanf__, fmtargnumber, fmtargnumber+1 ))) + +/** + * Macro that annotates a va_list function that operates like scanf. + * + * If we were to annotate `vfscanf`: + * + * ```c + * int vfscanf(FILE *f, const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(2); + * ``` + * + * This notes that the second parameter should be a scanf-style format string, followed by a va_list. + * The compiler or other analysis tools can warn when this doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * This can (and should) be used with SDL_SCANF_FORMAT_STRING as well, which between them + * will cover at least Visual Studio, GCC, and Clang. + * + * \since This macro is available since SDL 3.1.3. + */ +#define SDL_SCANF_VARARG_FUNCV( fmtargnumber ) __attribute__(( format( __scanf__, fmtargnumber, 0 ))) + +/** + * Macro that annotates a vararg function that operates like wprintf. + * + * If we were to annotate `fwprintf`: + * + * ```c + * int fwprintf(FILE *f, const wchar_t *fmt, ...) SDL_WPRINTF_VARARG_FUNC(2); + * ``` + * + * This notes that the second parameter should be a wprintf-style format wide string, followed by `...`. + * The compiler or other analysis tools can warn when this doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * This can (and should) be used with SDL_PRINTF_FORMAT_STRING as well, which between them + * will cover at least Visual Studio, GCC, and Clang. + * + * \since This macro is available since SDL 3.1.3. + */ +#define SDL_WPRINTF_VARARG_FUNC( fmtargnumber ) /* __attribute__ (( format( __wprintf__, fmtargnumber, fmtargnumber+1 ))) */ + +/** + * Macro that annotates a va_list function that operates like wprintf. + * + * If we were to annotate `vfwprintf`: + * + * ```c + * int vfwprintf(FILE *f, const wchar_t *fmt, va_list ap) SDL_WPRINTF_VARARG_FUNC(2); + * ``` + * + * This notes that the second parameter should be a wprintf-style format wide string, followed by a va_list. + * The compiler or other analysis tools can warn when this doesn't appear to be the case. + * + * On compilers without this annotation mechanism, this is defined to nothing. + * + * This can (and should) be used with SDL_PRINTF_FORMAT_STRING as well, which between them + * will cover at least Visual Studio, GCC, and Clang. + * + * \since This macro is available since SDL 3.1.3. + */ +#define SDL_WPRINTF_VARARG_FUNCV( fmtargnumber ) /* __attribute__ (( format( __wprintf__, fmtargnumber, 0 ))) */ + +#elif defined(SDL_DISABLE_ANALYZE_MACROS) #define SDL_IN_BYTECAP(x) #define SDL_INOUT_Z_CAP(x) #define SDL_OUT_Z_CAP(x) @@ -2295,9 +2576,77 @@ extern SDL_DECLSPEC void * SDLCALL SDL_memset4(void *dst, Uint32 val, size_t dwo #define SDL_zeroa(x) SDL_memset((x), 0, sizeof((x))) +/** + * Compare two buffers of memory. + * + * \param s1 the first buffer to compare. NULL is not permitted! + * \param s2 the second buffer to compare. NULL is not permitted! + * \param len the number of bytes to compare between the buffers. + * \returns less than zero if s1 is "less than" s2, greater than zero if + * s1 is "greater than" s2, and zero if the buffers match + * exactly for `len` bytes. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.1.3. + */ extern SDL_DECLSPEC int SDLCALL SDL_memcmp(const void *s1, const void *s2, size_t len); +/** + * This works exactly like wcslen() but doesn't require access to a C runtime. + * + * Counts the number of wchar_t values in `wstr`, excluding the null + * terminator. + * + * Like SDL_strlen only counts bytes and not codepoints in a UTF-8 string, + * this counts wchar_t values in a string, even if the string's encoding is of + * variable width, like UTF-16. + * + * Also be aware that wchar_t is different sizes on different platforms (4 + * bytes on Linux, 2 on Windows, etc). + * + * \param wstr The null-terminated wide string to read. Must not be NULL. + * \returns the length (in wchar_t values, excluding the null terminator) of `wstr`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.1.3. + * + * \sa SDL_wcsnlen + * \sa SDL_utf8strlen + * \sa SDL_utf8strnlen + */ extern SDL_DECLSPEC size_t SDLCALL SDL_wcslen(const wchar_t *wstr); + +/** + * This works exactly like wcsnlen() but doesn't require access to a C + * runtime. + * + * Counts up to a maximum of `maxlen` wchar_t values in `wstr`, excluding the + * null terminator. + * + * Like SDL_strnlen only counts bytes and not codepoints in a UTF-8 string, + * this counts wchar_t values in a string, even if the string's encoding is of + * variable width, like UTF-16. + * + * Also be aware that wchar_t is different sizes on different platforms (4 + * bytes on Linux, 2 on Windows, etc). + * + * Also, `maxlen` is a count of wide characters, not bytes! + * + * \param wstr The null-terminated wide string to read. Must not be NULL. + * \param maxlen The maximum amount of wide characters to count. + * \returns the length (in wide characters, excluding the null terminator) of + * `wstr` but never more than `maxlen`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.1.3. + * + * \sa SDL_wcslen + * \sa SDL_utf8strlen + * \sa SDL_utf8strnlen + */ extern SDL_DECLSPEC size_t SDLCALL SDL_wcsnlen(const wchar_t *wstr, size_t maxlen); /** @@ -2316,7 +2665,7 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_wcsnlen(const wchar_t *wstr, size_t maxle * \param src The null-terminated wide string to copy. Must not be NULL, and * must not overlap with `dst`. * \param maxlen The length (in wide characters) of the destination buffer. - * \returns The length (in wide characters, excluding the null terminator) of + * \returns the length (in wide characters, excluding the null terminator) of * `src`. * * \threadsafety It is safe to call this function from any thread. @@ -2345,7 +2694,7 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_wcslcpy(SDL_OUT_Z_CAP(maxlen) wchar_t *ds * \param src The second null-terminated wide string. Must not be NULL, and * must not overlap with `dst`. * \param maxlen The length (in wide characters) of the destination buffer. - * \returns The length (in wide characters, excluding the null terminator) of + * \returns the length (in wide characters, excluding the null terminator) of * the string in `dst` plus the length of `src`. * * \threadsafety It is safe to call this function from any thread. @@ -2356,8 +2705,63 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_wcslcpy(SDL_OUT_Z_CAP(maxlen) wchar_t *ds */ extern SDL_DECLSPEC size_t SDLCALL SDL_wcslcat(SDL_INOUT_Z_CAP(maxlen) wchar_t *dst, const wchar_t *src, size_t maxlen); +/** + * Allocate a copy of a wide string. + * + * This allocates enough space for a null-terminated copy of `wstr`, using + * SDL_malloc, and then makes a copy of the string into this space. + * + * The returned string is owned by the caller, and should be passed to + * SDL_free when no longer needed. + * + * \param wstr the string to copy. + * \returns a pointer to the newly-allocated wide string. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.1.3. + */ extern SDL_DECLSPEC wchar_t * SDLCALL SDL_wcsdup(const wchar_t *wstr); + +/** + * Search a wide string for the first instance of a specific substring. + * + * The search ends once it finds the requested substring, or a null + * terminator byte to end the string. + * + * Note that this looks for strings of _wide characters_, not _codepoints_, so + * it's legal to search for malformed and incomplete UTF-16 sequences. + * + * \param haystack the wide string to search. Must not be NULL. + * \param needle the wide string to search for. Must not be NULL. + * \returns a pointer to the first instance of `needle` in the string, or NULL if not found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.1.3. + */ extern SDL_DECLSPEC wchar_t * SDLCALL SDL_wcsstr(const wchar_t *haystack, const wchar_t *needle); + +/** + * Search a wide string, up to n wide chars, for the first instance of a specific substring. + * + * The search ends once it finds the requested substring, or a null + * terminator value to end the string, or `maxlen` wide character have been + * examined. It is possible to use this function on a wide string without a + * null terminator. + * + * Note that this looks for strings of _wide characters_, not _codepoints_, so + * it's legal to search for malformed and incomplete UTF-16 sequences. + * + * \param haystack the wide string to search. Must not be NULL. + * \param needle the wide string to search for. Must not be NULL. + * \param maxlen the maximum number of wide characters to search in `haystack`. + * \returns a pointer to the first instance of `needle` in the string, or NULL if not found. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.1.3. + */ extern SDL_DECLSPEC wchar_t * SDLCALL SDL_wcsnstr(const wchar_t *haystack, const wchar_t *needle, size_t maxlen); /** @@ -2499,7 +2903,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_wcsncasecmp(const wchar_t *str1, const wchar * to 36 inclusive. If 0, the base will be inferred from the * number's prefix (0x for hexadecimal, 0 for octal, decimal * otherwise). - * \returns The parsed `long`, or 0 if no number could be parsed. + * \returns the parsed `long`, or 0 if no number could be parsed. * * \threadsafety It is safe to call this function from any thread. * @@ -2517,7 +2921,7 @@ extern SDL_DECLSPEC long SDLCALL SDL_wcstol(const wchar_t *str, wchar_t **endp, * If you need the length of a UTF-8 string, consider using SDL_utf8strlen(). * * \param str The null-terminated string to read. Must not be NULL. - * \returns The length (in bytes, excluding the null terminator) of `src`. + * \returns the length (in bytes, excluding the null terminator) of `src`. * * \threadsafety It is safe to call this function from any thread. * @@ -2540,7 +2944,7 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_strlen(const char *str); * * \param str The null-terminated string to read. Must not be NULL. * \param maxlen The maximum amount of bytes to count. - * \returns The length (in bytes, excluding the null terminator) of `src` but + * \returns the length (in bytes, excluding the null terminator) of `src` but * never more than `maxlen`. * * \threadsafety It is safe to call this function from any thread. @@ -2570,7 +2974,7 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_strnlen(const char *str, size_t maxlen); * \param src The null-terminated string to copy. Must not be NULL, and must * not overlap with `dst`. * \param maxlen The length (in characters) of the destination buffer. - * \returns The length (in characters, excluding the null terminator) of + * \returns the length (in characters, excluding the null terminator) of * `src`. * * \threadsafety It is safe to call this function from any thread. @@ -2600,7 +3004,7 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_strlcpy(SDL_OUT_Z_CAP(maxlen) char *dst, * must not overlap with `dst`. * \param dst_bytes The length (in bytes) of the destination buffer. Must not * be 0. - * \returns The number of bytes written, excluding the null terminator. + * \returns the number of bytes written, excluding the null terminator. * * \threadsafety It is safe to call this function from any thread. * @@ -2627,7 +3031,7 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_utf8strlcpy(SDL_OUT_Z_CAP(dst_bytes) char * \param src The second null-terminated string. Must not be NULL, and must * not overlap with `dst`. * \param maxlen The length (in characters) of the destination buffer. - * \returns The length (in characters, excluding the null terminator) of the + * \returns the length (in characters, excluding the null terminator) of the * string in `dst` plus the length of `src`. * * \threadsafety It is safe to call this function from any thread. @@ -2638,8 +3042,68 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_utf8strlcpy(SDL_OUT_Z_CAP(dst_bytes) char */ extern SDL_DECLSPEC size_t SDLCALL SDL_strlcat(SDL_INOUT_Z_CAP(maxlen) char *dst, const char *src, size_t maxlen); +/** + * Allocate a copy of a string. + * + * This allocates enough space for a null-terminated copy of `str`, using + * SDL_malloc, and then makes a copy of the string into this space. + * + * The returned string is owned by the caller, and should be passed to + * SDL_free when no longer needed. + * + * \param str the string to copy. + * \returns a pointer to the newly-allocated string. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.1.3. + */ extern SDL_DECLSPEC SDL_MALLOC char * SDLCALL SDL_strdup(const char *str); + +/** + * Allocate a copy of a string, up to n characters. + * + * This allocates enough space for a null-terminated copy of `str`, up to + * `maxlen` bytes, using SDL_malloc, and then makes a copy of the string + * into this space. + * + * If the string is longer than `maxlen` bytes, the returned string will + * be `maxlen` bytes long, plus a null-terminator character that isn't + * included in the count. + * + * The returned string is owned by the caller, and should be passed to + * SDL_free when no longer needed. + * + * \param str the string to copy. + * \param maxlen the maximum length of the copied string, not counting + * the null-terminator character. + * \returns a pointer to the newly-allocated string. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.1.3. + */ extern SDL_DECLSPEC SDL_MALLOC char * SDLCALL SDL_strndup(const char *str, size_t maxlen); + +/** + * Reverse a string's contents. + * + * This reverses a null-terminated string in-place. Only the content of the + * string is reversed; the null-terminator character remains at the end of the + * reversed string. + * + * **WARNING**: This function reverses the _bytes_ of the string, not the + * codepoints. If `str` is a UTF-8 string with Unicode codepoints > 127, this + * will ruin the string data. You should only use this function on strings + * that are completely comprised of low ASCII characters. + * + * \param str the string to reverse. + * \returns `str`. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.1.3. + */ extern SDL_DECLSPEC char * SDLCALL SDL_strrev(char *str); /** @@ -3059,7 +3523,7 @@ extern SDL_DECLSPEC char * SDLCALL SDL_ulltoa(unsigned long long value, char *st * `(int)SDL_strtol(str, NULL, 10)`. * * \param str The null-terminated string to read. Must not be NULL. - * \returns The parsed `int`. + * \returns the parsed `int`. * * \threadsafety It is safe to call this function from any thread. * @@ -3082,7 +3546,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_atoi(const char *str); * NULL)`. * * \param str The null-terminated string to read. Must not be NULL. - * \returns The parsed `double`. + * \returns the parsed `double`. * * \threadsafety It is safe to call this function from any thread. * @@ -3114,7 +3578,7 @@ extern SDL_DECLSPEC double SDLCALL SDL_atof(const char *str); * to 36 inclusive. If 0, the base will be inferred from the * number's prefix (0x for hexadecimal, 0 for octal, decimal * otherwise). - * \returns The parsed `long`, or 0 if no number could be parsed. + * \returns the parsed `long`, or 0 if no number could be parsed. * * \threadsafety It is safe to call this function from any thread. * @@ -3148,7 +3612,7 @@ extern SDL_DECLSPEC long SDLCALL SDL_strtol(const char *str, char **endp, int ba * to 36 inclusive. If 0, the base will be inferred from the * number's prefix (0x for hexadecimal, 0 for octal, decimal * otherwise). - * \returns The parsed `unsigned long`, or 0 if no number could be parsed. + * \returns the parsed `unsigned long`, or 0 if no number could be parsed. * * \threadsafety It is safe to call this function from any thread. * @@ -3181,7 +3645,7 @@ extern SDL_DECLSPEC unsigned long SDLCALL SDL_strtoul(const char *str, char **en * to 36 inclusive. If 0, the base will be inferred from the * number's prefix (0x for hexadecimal, 0 for octal, decimal * otherwise). - * \returns The parsed `long long`, or 0 if no number could be parsed. + * \returns the parsed `long long`, or 0 if no number could be parsed. * * \threadsafety It is safe to call this function from any thread. * @@ -3214,7 +3678,7 @@ extern SDL_DECLSPEC long long SDLCALL SDL_strtoll(const char *str, char **endp, * to 36 inclusive. If 0, the base will be inferred from the * number's prefix (0x for hexadecimal, 0 for octal, decimal * otherwise). - * \returns The parsed `unsigned long long`, or 0 if no number could be + * \returns the parsed `unsigned long long`, or 0 if no number could be * parsed. * * \threadsafety It is safe to call this function from any thread. @@ -3241,11 +3705,11 @@ extern SDL_DECLSPEC unsigned long long SDLCALL SDL_strtoull(const char *str, cha * - Whether or not INF and NAN can be parsed is unspecified. * - The precision of the result is unspecified. * - * \param str The null-terminated string to read. Must not be NULL. - * \param endp If not NULL, the address of the first invalid character (i.e. + * \param str the null-terminated string to read. Must not be NULL. + * \param endp if not NULL, the address of the first invalid character (i.e. * the next character after the parsed number) will be written to * this pointer. - * \returns The parsed `double`, or 0 if no number could be parsed. + * \returns the parsed `double`, or 0 if no number could be parsed. * * \threadsafety It is safe to call this function from any thread. * @@ -3516,14 +3980,186 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_StepBackUTF8(const char *start, const cha */ extern SDL_DECLSPEC char * SDLCALL SDL_UCS4ToUTF8(Uint32 codepoint, char *dst); - +/** + * This works exactly like sscanf() but doesn't require access to a C runtime. + * + * Scan a string, matching a format string, converting each '%' item and + * storing it to pointers provided through variable arguments. + * + * \param text the string to scan. Must not be NULL. + * \param fmt a printf-style format string. Must not be NULL. + * \param ... a list of pointers to values to be filled in with scanned items. + * \returns the number of items that matched the format string. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.1.3. + */ extern SDL_DECLSPEC int SDLCALL SDL_sscanf(const char *text, SDL_SCANF_FORMAT_STRING const char *fmt, ...) SDL_SCANF_VARARG_FUNC(2); + +/** + * This works exactly like vsscanf() but doesn't require access to a C runtime. + * + * Functions identically to SDL_sscanf(), except it takes a `va_list` + * instead of using `...` variable arguments. + * + * \param text the string to scan. Must not be NULL. + * \param fmt a printf-style format string. Must not be NULL. + * \param ap a `va_list` of pointers to values to be filled in with scanned items. + * \returns the number of items that matched the format string. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.1.3. + */ extern SDL_DECLSPEC int SDLCALL SDL_vsscanf(const char *text, SDL_SCANF_FORMAT_STRING const char *fmt, va_list ap) SDL_SCANF_VARARG_FUNCV(2); + +/** + * This works exactly like snprintf() but doesn't require access to a C runtime. + * + * Format a string of up to `maxlen`-1 bytes, converting each '%' item with + * values provided through variable arguments. + * + * While some C runtimes differ on how to deal with too-large strings, + * this function null-terminates the output, by treating the null-terminator + * as part of the `maxlen` count. Note that if `maxlen` is zero, however, no + * bytes will be written at all. + * + * This function returns the number of _bytes_ (not _characters_) that should + * be written, excluding the null-terminator character. If this returns a + * number >= `maxlen`, it means the output string was truncated. A negative + * return value means an error occurred. + * + * Referencing the output string's pointer with a format item is undefined + * behavior. + * + * \param text the buffer to write the string into. Must not be NULL. + * \param maxlen the maximum bytes to write, including the null-terminator. + * \param fmt a printf-style format string. Must not be NULL. + * \param ... a list of values to be used with the format string. + * \returns the number of bytes that should be written, not counting the + * null-terminator char, or a negative value on error. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.1.3. + */ extern SDL_DECLSPEC int SDLCALL SDL_snprintf(SDL_OUT_Z_CAP(maxlen) char *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(3); + +/** + * This works exactly like swprintf() but doesn't require access to a C runtime. + * + * Format a wide string of up to `maxlen`-1 wchar_t values, converting each '%' + * item with values provided through variable arguments. + * + * While some C runtimes differ on how to deal with too-large strings, + * this function null-terminates the output, by treating the null-terminator + * as part of the `maxlen` count. Note that if `maxlen` is zero, however, no + * wide characters will be written at all. + * + * This function returns the number of _wide characters_ (not _codepoints_) + * that should be written, excluding the null-terminator character. If this + * returns a number >= `maxlen`, it means the output string was truncated. A + * negative return value means an error occurred. + * + * Referencing the output string's pointer with a format item is undefined + * behavior. + * + * \param text the buffer to write the wide string into. Must not be NULL. + * \param maxlen the maximum wchar_t values to write, including the null-terminator. + * \param fmt a printf-style format string. Must not be NULL. + * \param ... a list of values to be used with the format string. + * \returns the number of wide characters that should be written, not counting + * the null-terminator char, or a negative value on error. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.1.3. + */ extern SDL_DECLSPEC int SDLCALL SDL_swprintf(SDL_OUT_Z_CAP(maxlen) wchar_t *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const wchar_t *fmt, ...) SDL_WPRINTF_VARARG_FUNC(3); + +/** + * This works exactly like vsnprintf() but doesn't require access to a C runtime. + * + * Functions identically to SDL_snprintf(), except it takes a `va_list` + * instead of using `...` variable arguments. + * + * \param text the buffer to write the string into. Must not be NULL. + * \param maxlen the maximum bytes to write, including the null-terminator. + * \param fmt a printf-style format string. Must not be NULL. + * \param ap a `va_list` values to be used with the format string. + * \returns the number of bytes that should be written, not counting the + * null-terminator char, or a negative value on error. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.1.3. + */ extern SDL_DECLSPEC int SDLCALL SDL_vsnprintf(SDL_OUT_Z_CAP(maxlen) char *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(3); + +/** + * This works exactly like vswprintf() but doesn't require access to a C runtime. + * + * Functions identically to SDL_swprintf(), except it takes a `va_list` + * instead of using `...` variable arguments. + * + * \param text the buffer to write the string into. Must not be NULL. + * \param maxlen the maximum wide characters to write, including the null-terminator. + * \param fmt a printf-style format wide string. Must not be NULL. + * \param ap a `va_list` values to be used with the format string. + * \returns the number of wide characters that should be written, not counting + * the null-terminator char, or a negative value on error. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.1.3. + */ extern SDL_DECLSPEC int SDLCALL SDL_vswprintf(SDL_OUT_Z_CAP(maxlen) wchar_t *text, size_t maxlen, SDL_PRINTF_FORMAT_STRING const wchar_t *fmt, va_list ap) SDL_WPRINTF_VARARG_FUNCV(3); + +/** + * This works exactly like asprintf() but doesn't require access to a C runtime. + * + * Functions identically to SDL_snprintf(), except it allocates a buffer large + * enough to hold the output string on behalf of the caller. + * + * On success, this function returns the number of bytes (not characters) + * comprising the output string, not counting the null-terminator character, + * and sets `*strp` to the newly-allocated string. + * + * On error, this function returns a negative number, and the value of `*strp` + * is undefined. + * + * The returned string is owned by the caller, and should be passed to + * SDL_free when no longer needed. + * + * \param strp on output, is set to the new string. Must not be NULL. + * \param fmt a printf-style format string. Must not be NULL. + * \param ... a list of values to be used with the format string. + * \returns the number of bytes in the newly-allocated string, not counting + * the null-terminator char, or a negative value on error. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.1.3. + */ extern SDL_DECLSPEC int SDLCALL SDL_asprintf(char **strp, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2); + +/** + * This works exactly like vasprintf() but doesn't require access to a C runtime. + * + * Functions identically to SDL_asprintf(), except it takes a `va_list` + * instead of using `...` variable arguments. + * + * \param strp on output, is set to the new string. Must not be NULL. + * \param fmt a printf-style format string. Must not be NULL. + * \param ap a `va_list` values to be used with the format string. + * \returns the number of bytes in the newly-allocated string, not counting + * the null-terminator char, or a negative value on error. + * + * \threadsafety It is safe to call this function from any thread. + * + * \since This function is available since SDL 3.1.3. + */ extern SDL_DECLSPEC int SDLCALL SDL_vasprintf(char **strp, SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(2); /** diff --git a/include/SDL3/SDL_system.h b/include/SDL3/SDL_system.h index c144fb671d..4e7181df98 100644 --- a/include/SDL3/SDL_system.h +++ b/include/SDL3/SDL_system.h @@ -129,7 +129,29 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetDXGIOutputInfo(SDL_DisplayID displayID, * Platform specific functions for UNIX */ +/* this is defined in Xlib's headers, just need a simple declaration here. */ typedef union _XEvent XEvent; + +/** + * A callback to be used with SDL_SetX11EventHook. + * + * This callback may modify the event, and should return true if the event + * should continue to be processed, or false to prevent further processing. + * + * As this is processing an event directly from the X11 event loop, this + * callback should do the minimum required work and return quickly. + * + * \param userdata the app-defined pointer provided to SDL_SetX11EventHook. + * \param xevent a pointer to an Xlib XEvent union to process. + * \returns true to let event continue on, false to drop it. + * + * \threadsafety This may only be called (by SDL) from the thread handling the + * X11 event loop. + * + * \since This datatype is available since SDL 3.1.3. + * + * \sa SDL_SetX11EventHook + */ typedef bool (SDLCALL *SDL_X11EventHook)(void *userdata, XEvent *xevent); /** @@ -380,6 +402,13 @@ extern SDL_DECLSPEC void SDLCALL SDL_SendAndroidBackButton(void); * \since This macro is available since SDL 3.1.3. */ #define SDL_ANDROID_EXTERNAL_STORAGE_READ 0x01 + +/** + * See the official Android developer guide for more information: + * http://developer.android.com/guide/topics/data/data-storage.html + * + * \since This macro is available since SDL 3.1.3. + */ #define SDL_ANDROID_EXTERNAL_STORAGE_WRITE 0x02 /** @@ -468,7 +497,17 @@ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAndroidExternalStoragePath(void) */ extern SDL_DECLSPEC const char * SDLCALL SDL_GetAndroidCachePath(void); - +/** + * Callback that presents a response from a SDL_RequestAndroidPermission call. + * + * \param userdata an app-controlled pointer that is passed to the callback. + * \param permission the Android-specific permission name that was requested. + * \param granted true if permission is granted, false if denied. + * + * \since This datatype is available since SDL 3.1.3. + * + * \sa SDL_RequestAndroidPermission + */ typedef void (SDLCALL *SDL_RequestAndroidPermissionCallback)(void *userdata, const char *permission, bool granted); /** diff --git a/include/SDL3/SDL_video.h b/include/SDL3/SDL_video.h index 2e6b448c54..388d1e7a93 100644 --- a/include/SDL3/SDL_video.h +++ b/include/SDL3/SDL_video.h @@ -112,7 +112,15 @@ typedef enum SDL_SystemTheme SDL_SYSTEM_THEME_DARK /**< Dark colored system theme */ } SDL_SystemTheme; -/* Internal display mode data */ +/** + * Internal display mode data. + * + * This lives as a field in SDL_DisplayMode, as opaque data. + * + * \since This struct is available since SDL 3.1.3. + * + * \sa SDL_DisplayMode + */ typedef struct SDL_DisplayModeData SDL_DisplayModeData; /** @@ -206,27 +214,87 @@ typedef Uint64 SDL_WindowFlags; /** - * Used to indicate that you don't care what the window position is. + * A magic value used with SDL_WINDOWPOS_UNDEFINED. + * + * Generally this macro isn't used directly, but rather through + * SDL_WINDOWPOS_UNDEFINED or SDL_WINDOWPOS_UNDEFINED_DISPLAY. * * \since This macro is available since SDL 3.1.3. */ #define SDL_WINDOWPOS_UNDEFINED_MASK 0x1FFF0000u -#define SDL_WINDOWPOS_UNDEFINED_DISPLAY(X) (SDL_WINDOWPOS_UNDEFINED_MASK|(X)) -#define SDL_WINDOWPOS_UNDEFINED SDL_WINDOWPOS_UNDEFINED_DISPLAY(0) -#define SDL_WINDOWPOS_ISUNDEFINED(X) \ - (((X)&0xFFFF0000) == SDL_WINDOWPOS_UNDEFINED_MASK) /** - * Used to indicate that the window position should be centered. + * Used to indicate that you don't care what the window position is. + * + * If you _really_ don't care, SDL_WINDOWPOS_UNDEFINED is the same, but always + * uses the primary display instead of specifying one. + * + * \param X the SDL_DisplayID of the display to use. + * + * \since This macro is available since SDL 3.1.3. + */ +#define SDL_WINDOWPOS_UNDEFINED_DISPLAY(X) (SDL_WINDOWPOS_UNDEFINED_MASK|(X)) + +/** + * Used to indicate that you don't care what the window position/display is. + * + * This always uses the primary display. + * + * \since This macro is available since SDL 3.1.3. + */ +#define SDL_WINDOWPOS_UNDEFINED SDL_WINDOWPOS_UNDEFINED_DISPLAY(0) + +/** + * A macro to test if the window position is marked as "undefined." + * + * \param X the window position value. + * + * \since This macro is available since SDL 3.1.3. + */ +#define SDL_WINDOWPOS_ISUNDEFINED(X) (((X)&0xFFFF0000) == SDL_WINDOWPOS_UNDEFINED_MASK) + +/** + * A magic value used with SDL_WINDOWPOS_CENTERED. + * + * Generally this macro isn't used directly, but rather through + * SDL_WINDOWPOS_CENTERED or SDL_WINDOWPOS_CENTERED_DISPLAY. * * \since This macro is available since SDL 3.1.3. */ #define SDL_WINDOWPOS_CENTERED_MASK 0x2FFF0000u + +/** + * Used to indicate that the window position should be centered. + * + * SDL_WINDOWPOS_CENTERED is the same, but always uses the primary display + * instead of specifying one. + * + * \param X the SDL_DisplayID of the display to use. + * + * \since This macro is available since SDL 3.1.3. + */ #define SDL_WINDOWPOS_CENTERED_DISPLAY(X) (SDL_WINDOWPOS_CENTERED_MASK|(X)) + +/** + * Used to indicate that the window position should be centered. + * + * This always uses the primary display. + * + * \since This macro is available since SDL 3.1.3. + */ #define SDL_WINDOWPOS_CENTERED SDL_WINDOWPOS_CENTERED_DISPLAY(0) + +/** + * A macro to test if the window position is marked as "centered." + * + * \param X the window position value. + * + * \since This macro is available since SDL 3.1.3. + */ #define SDL_WINDOWPOS_ISCENTERED(X) \ (((X)&0xFFFF0000) == SDL_WINDOWPOS_CENTERED_MASK) + /** * Window flash operation. * @@ -249,14 +317,38 @@ typedef enum SDL_FlashOperation typedef struct SDL_GLContextState *SDL_GLContext; /** - * Opaque EGL types. + * Opaque type for an EGL display. * * \since This datatype is available since SDL 3.1.3. */ typedef void *SDL_EGLDisplay; + +/** + * Opaque type for an EGL config. + * + * \since This datatype is available since SDL 3.1.3. + */ typedef void *SDL_EGLConfig; + +/** + * Opaque type for an EGL surface. + * + * \since This datatype is available since SDL 3.1.3. + */ typedef void *SDL_EGLSurface; + +/** + * An EGL attribute, used when creating an EGL context. + * + * \since This datatype is available since SDL 3.1.3. + */ typedef intptr_t SDL_EGLAttrib; + +/** + * An EGL integer attribute, used when creating an EGL surface. + * + * \since This datatype is available since SDL 3.1.3. + */ typedef int SDL_EGLint; /**