eden-emu/SDL
15
0
Fork 0
mirror of https://github.com/libsdl-org/SDL.git synced 2025-05-28 07:29:09 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

Sync SDL3 wiki -> header

Browse source 
[ci skip]
This commit is contained in:
SDL Wiki Bot 2024-12-22 07:09:56 +00:00
parent f0fad41f2c
commit 56cf8d8dc9
10 changed files with 165 additions and 128 deletions
Download patch file Download diff file Expand all files Collapse all files

12
include/SDL3/SDL_assert.h
View file

@ -157,6 +157,7 @@ extern "C" {
#endif #endif
#ifdef SDL_WIKI_DOCUMENTATION_SECTION #ifdef SDL_WIKI_DOCUMENTATION_SECTION
/** /**
* A macro that reports the current function being compiled. * A macro that reports the current function being compiled.
* *
@ -204,6 +205,7 @@ disable assertions.
*/ */
#ifdef SDL_WIKI_DOCUMENTATION_SECTION #ifdef SDL_WIKI_DOCUMENTATION_SECTION
/** /**
* A macro for wrapping code in `do {} while (0);` without compiler warnings. * A macro for wrapping code in `do {} while (0);` without compiler warnings.
* *
@ -211,7 +213,8 @@ disable assertions.
* compiler complaints. * compiler complaints.
* *
* the `do {} while (0);` trick is useful for wrapping code in a macro that * 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. * may or may not be a single statement, to avoid various C language
* accidents.
* *
* To use: * To use:
* *
@ -311,6 +314,7 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData *
#ifdef SDL_WIKI_DOCUMENTATION_SECTION #ifdef SDL_WIKI_DOCUMENTATION_SECTION
/** /**
* The macro used when an assertion triggers a breakpoint. * The macro used when an assertion triggers a breakpoint.
* *
@ -342,9 +346,9 @@ extern SDL_DECLSPEC SDL_AssertState SDLCALL SDL_ReportAssertion(SDL_AssertData *
* if (x) SDL_assert(y); else blah(); * if (x) SDL_assert(y); else blah();
* ``` * ```
* *
* ... without the do/while, the "else" could attach to this macro's "if". * ... without the do/while, the "else" could attach to this macro's "if". We
* We try to handle just the minimum we need here in a macro...the loop, * try to handle just the minimum we need here in a macro...the loop, the
* the static vars, and break points. The heavy lifting is handled in * static vars, and break points. The heavy lifting is handled in
* SDL_ReportAssertion(). * SDL_ReportAssertion().
* *
* \param condition the condition to assert. * \param condition the condition to assert.

37
include/SDL3/SDL_atomic.h
View file

@ -175,10 +175,10 @@ extern __inline void SDL_CompilerBarrier(void);
* Insert a memory release barrier (function version). * Insert a memory release barrier (function version).
* *
* Please refer to SDL_MemoryBarrierRelease for details. This is a function * Please refer to SDL_MemoryBarrierRelease for details. This is a function
* version, which might be useful if you need to use this functionality from * version, which might be useful if you need to use this functionality from a
* a scripting language, etc. Also, some of the macro versions call this * scripting language, etc. Also, some of the macro versions call this
* function behind the scenes, where more heavy lifting can happen inside * function behind the scenes, where more heavy lifting can happen inside of
* of SDL. Generally, though, an app written in C/C++/etc should use the macro * SDL. Generally, though, an app written in C/C++/etc should use the macro
* version, as it will be more efficient. * version, as it will be more efficient.
* *
* \threadsafety Obviously this function is safe to use from any thread at any * \threadsafety Obviously this function is safe to use from any thread at any
@ -195,10 +195,10 @@ extern SDL_DECLSPEC void SDLCALL SDL_MemoryBarrierReleaseFunction(void);
* Insert a memory acquire barrier (function version). * Insert a memory acquire barrier (function version).
* *
* Please refer to SDL_MemoryBarrierRelease for details. This is a function * Please refer to SDL_MemoryBarrierRelease for details. This is a function
* version, which might be useful if you need to use this functionality from * version, which might be useful if you need to use this functionality from a
* a scripting language, etc. Also, some of the macro versions call this * scripting language, etc. Also, some of the macro versions call this
* function behind the scenes, where more heavy lifting can happen inside * function behind the scenes, where more heavy lifting can happen inside of
* of SDL. Generally, though, an app written in C/C++/etc should use the macro * SDL. Generally, though, an app written in C/C++/etc should use the macro
* version, as it will be more efficient. * version, as it will be more efficient.
* *
* \threadsafety Obviously this function is safe to use from any thread at any * \threadsafety Obviously this function is safe to use from any thread at any
@ -213,6 +213,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_MemoryBarrierAcquireFunction(void);
#ifdef SDL_WIKI_DOCUMENTATION_SECTION #ifdef SDL_WIKI_DOCUMENTATION_SECTION
/** /**
* Insert a memory release barrier (macro version). * Insert a memory release barrier (macro version).
* *
@ -234,11 +235,11 @@ extern SDL_DECLSPEC void SDLCALL SDL_MemoryBarrierAcquireFunction(void);
* For more information on these semantics, take a look at the blog post: * For more information on these semantics, take a look at the blog post:
* http://preshing.com/20120913/acquire-and-release-semantics * http://preshing.com/20120913/acquire-and-release-semantics
* *
* This is the macro version of this functionality; if possible, SDL will * This is the macro version of this functionality; if possible, SDL will use
* use compiler intrinsics or inline assembly, but some platforms might * compiler intrinsics or inline assembly, but some platforms might need to
* need to call the function version of this, SDL_MemoryBarrierReleaseFunction * call the function version of this, SDL_MemoryBarrierReleaseFunction to do
* to do the heavy lifting. Apps that can use the macro should favor it over * the heavy lifting. Apps that can use the macro should favor it over the
* the function. * function.
* *
* \threadsafety Obviously this macro is safe to use from any thread at any * \threadsafety Obviously this macro is safe to use from any thread at any
* time, but if you find yourself needing this, you are probably * time, but if you find yourself needing this, you are probably
@ -257,11 +258,11 @@ extern SDL_DECLSPEC void SDLCALL SDL_MemoryBarrierAcquireFunction(void);
* Please see SDL_MemoryBarrierRelease for the details on what memory barriers * Please see SDL_MemoryBarrierRelease for the details on what memory barriers
* are and when to use them. * are and when to use them.
* *
* This is the macro version of this functionality; if possible, SDL will * This is the macro version of this functionality; if possible, SDL will use
* use compiler intrinsics or inline assembly, but some platforms might * compiler intrinsics or inline assembly, but some platforms might need to
* need to call the function version of this, * call the function version of this, SDL_MemoryBarrierAcquireFunction, to do
* SDL_MemoryBarrierAcquireFunction, to do the heavy lifting. Apps that can * the heavy lifting. Apps that can use the macro should favor it over the
* use the macro should favor it over the function. * function.
* *
* \threadsafety Obviously this macro is safe to use from any thread at any * \threadsafety Obviously this macro is safe to use from any thread at any
* time, but if you find yourself needing this, you are probably * time, but if you find yourself needing this, you are probably

6
include/SDL3/SDL_audio.h
View file

@ -181,9 +181,9 @@ extern "C" {
/** /**
* Define an SDL_AudioFormat value. * Define an SDL_AudioFormat value.
* *
* SDL does not support custom audio formats, so this macro is not of much * SDL does not support custom audio formats, so this macro is not of much use
* use externally, but it can be illustrative as to what the various bits of * externally, but it can be illustrative as to what the various bits of an
* an SDL_AudioFormat mean. * SDL_AudioFormat mean.
* *
* For example, SDL_AUDIO_S32LE looks like this: * For example, SDL_AUDIO_S32LE looks like this:
* *

30
include/SDL3/SDL_gpu.h
View file

@ -2238,24 +2238,24 @@ extern SDL_DECLSPEC SDL_GPUShader *SDLCALL SDL_CreateGPUShader(
* - `SDL_PROP_PROCESS_CREATE_ARGS_POINTER`: an array of strings containing * - `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 * the program to run, any arguments, and a NULL pointer, e.g. const char
* *args[] = { "myprogram", "argument", NULL }. This is a required property. * *args[] = { "myprogram", "argument", NULL }. This is a required property.
* - `SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_R_FLOAT`: (Direct3D 12 only) * - `SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_R_FLOAT`: (Direct3D 12 only) if
* if the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the * the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the texture
* texture to a color with this red intensity. Defaults to zero. * to a color with this red intensity. Defaults to zero.
* - `SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_G_FLOAT`: (Direct3D 12 only) * - `SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_G_FLOAT`: (Direct3D 12 only) if
* if the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the * the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the texture
* texture to a color with this green intensity. Defaults to zero. * to a color with this green intensity. Defaults to zero.
* - `SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_B_FLOAT`: (Direct3D 12 only) * - `SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_B_FLOAT`: (Direct3D 12 only) if
* if the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the * the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the texture
* texture to a color with this blue intensity. Defaults to zero. * to a color with this blue intensity. Defaults to zero.
* - `SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_A_FLOAT`: (Direct3D 12 only) * - `SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_A_FLOAT`: (Direct3D 12 only) if
* if the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the * the texture usage is SDL_GPU_TEXTUREUSAGE_COLOR_TARGET, clear the texture
* texture to a color with this alpha intensity. Defaults to zero. * to a color with this alpha intensity. Defaults to zero.
* - `SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_DEPTH_FLOAT`: (Direct3D 12 only) * - `SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_DEPTH_FLOAT`: (Direct3D 12 only)
* if the texture usage is SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET, clear * if the texture usage is SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET, clear
* the texture to a depth of this value. Defaults to zero. * the texture to a depth of this value. Defaults to zero.
* - `SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_STENCIL_UINT8`: (Direct3D 12 only) * - `SDL_PROP_GPU_CREATETEXTURE_D3D12_CLEAR_STENCIL_UINT8`: (Direct3D 12
* if the texture usage is SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET, clear * only) if the texture usage is SDL_GPU_TEXTUREUSAGE_DEPTH_STENCIL_TARGET,
* the texture to a stencil of this value. Defaults to zero. * clear the texture to a stencil of this value. Defaults to zero.
* *
* \param device a GPU Context. * \param device a GPU Context.
* \param createinfo a struct describing the state of the texture to create. * \param createinfo a struct describing the state of the texture to create.

16
include/SDL3/SDL_init.h
View file

@ -117,8 +117,8 @@ typedef enum SDL_AppResult
* Function pointer typedef for SDL_AppInit. * Function pointer typedef for SDL_AppInit.
* *
* These are used by SDL_EnterAppMainCallbacks. This mechanism operates behind * These are used by SDL_EnterAppMainCallbacks. This mechanism operates behind
* the scenes for apps using the optional main callbacks. Apps that want to use * the scenes for apps using the optional main callbacks. Apps that want to
* this should just implement SDL_AppInit directly. * use this should just implement SDL_AppInit directly.
* *
* \param appstate a place where the app can optionally store a pointer for * \param appstate a place where the app can optionally store a pointer for
* future use. * future use.
@ -136,8 +136,8 @@ typedef SDL_AppResult (SDLCALL *SDL_AppInit_func)(void **appstate, int argc, cha
* Function pointer typedef for SDL_AppIterate. * Function pointer typedef for SDL_AppIterate.
* *
* These are used by SDL_EnterAppMainCallbacks. This mechanism operates behind * These are used by SDL_EnterAppMainCallbacks. This mechanism operates behind
* the scenes for apps using the optional main callbacks. Apps that want to use * the scenes for apps using the optional main callbacks. Apps that want to
* this should just implement SDL_AppIterate directly. * use this should just implement SDL_AppIterate directly.
* *
* \param appstate an optional pointer, provided by the app in SDL_AppInit. * \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 * \returns SDL_APP_FAILURE to terminate with an error, SDL_APP_SUCCESS to
@ -151,8 +151,8 @@ typedef SDL_AppResult (SDLCALL *SDL_AppIterate_func)(void *appstate);
* Function pointer typedef for SDL_AppEvent. * Function pointer typedef for SDL_AppEvent.
* *
* These are used by SDL_EnterAppMainCallbacks. This mechanism operates behind * These are used by SDL_EnterAppMainCallbacks. This mechanism operates behind
* the scenes for apps using the optional main callbacks. Apps that want to use * the scenes for apps using the optional main callbacks. Apps that want to
* this should just implement SDL_AppEvent directly. * use this should just implement SDL_AppEvent directly.
* *
* \param appstate an optional pointer, provided by the app in SDL_AppInit. * \param appstate an optional pointer, provided by the app in SDL_AppInit.
* \param event the new event for the app to examine. * \param event the new event for the app to examine.
@ -167,8 +167,8 @@ typedef SDL_AppResult (SDLCALL *SDL_AppEvent_func)(void *appstate, SDL_Event *ev
* Function pointer typedef for SDL_AppQuit. * Function pointer typedef for SDL_AppQuit.
* *
* These are used by SDL_EnterAppMainCallbacks. This mechanism operates behind * These are used by SDL_EnterAppMainCallbacks. This mechanism operates behind
* the scenes for apps using the optional main callbacks. Apps that want to use * the scenes for apps using the optional main callbacks. Apps that want to
* this should just implement SDL_AppEvent directly. * use this should just implement SDL_AppEvent directly.
* *
* \param appstate an optional pointer, provided by the app in SDL_AppInit. * \param appstate an optional pointer, provided by the app in SDL_AppInit.
* \param result the result code that terminated the app (success or failure). * \param result the result code that terminated the app (success or failure).

6
include/SDL3/SDL_intrin.h
View file

@ -324,9 +324,9 @@ _m_prefetch(void *__P)
* #endif * #endif
* ``` * ```
* *
* The application is, on a whole, built without SSE2 instructions, so it * The application is, on a whole, built without SSE2 instructions, so it will
* will run on Intel machines that don't support SSE2. But then at runtime, * run on Intel machines that don't support SSE2. But then at runtime, it
* it checks if the system supports the instructions, and then calls into a * 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 * function that uses SSE2 opcodes. The ifdefs make sure that this code isn't
* used on platforms that don't have SSE2 at all. * used on platforms that don't have SSE2 at all.
* *

1
include/SDL3/SDL_mutex.h
View file

@ -34,6 +34,7 @@
#include <SDL3/SDL_thread.h> #include <SDL3/SDL_thread.h>
#ifdef SDL_WIKI_DOCUMENTATION_SECTION #ifdef SDL_WIKI_DOCUMENTATION_SECTION
/** /**
* Enable thread safety attributes, only with clang. * Enable thread safety attributes, only with clang.
* *

28
include/SDL3/SDL_pixels.h
View file

@ -244,8 +244,10 @@ typedef enum SDL_PackedLayout
* ``` * ```
* *
* \param type the type of the new format, probably a SDL_PixelType value. * \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 order the order of the new format, probably a SDL_BitmapOrder,
* \param layout the layout of the new format, probably an SDL_PackedLayout value or zero. * 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 bits the number of bits per pixel of the new format.
* \param bytes the number of bytes 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. * \returns a format value in the style of SDL_PixelFormat.
@ -305,8 +307,8 @@ typedef enum SDL_PackedLayout
/** /**
* A macro to retrieve the layout of an SDL_PixelFormat. * A macro to retrieve the layout of an SDL_PixelFormat.
* *
* This is usually a value from the SDL_PackedLayout enumeration, or zero if * This is usually a value from the SDL_PackedLayout enumeration, or zero if a
* a layout doesn't make sense for the format type. * layout doesn't make sense for the format type.
* *
* \param format an SDL_PixelFormat to check. * \param format an SDL_PixelFormat to check.
* \returns the layout of `format`. * \returns the layout of `format`.
@ -833,10 +835,14 @@ typedef enum SDL_ChromaLocation
* *
* \param type the type of the new format, probably an SDL_ColorType value. * \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 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 primaries the primaries of the new format, probably an
* \param transfer the transfer characteristics of the new format, probably an SDL_TransferCharacteristics value. * SDL_ColorPrimaries value.
* \param matrix the matrix coefficients of the new format, probably an SDL_MatrixCoefficients value. * \param transfer the transfer characteristics of the new format, probably an
* \param chroma the chroma sample location of the new format, probably an SDL_ChromaLocation value. * 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. * \returns a format value in the style of SDL_Colorspace.
* *
* \threadsafety It is safe to call this macro from any thread. * \threadsafety It is safe to call this macro from any thread.
@ -920,7 +926,8 @@ typedef enum SDL_ChromaLocation
#define SDL_COLORSPACEMATRIX(cspace) (SDL_MatrixCoefficients)((cspace) & 0x1F) #define SDL_COLORSPACEMATRIX(cspace) (SDL_MatrixCoefficients)((cspace) & 0x1F)
/** /**
* A macro to determine if an SDL_Colorspace uses BT601 (or BT470BG) matrix coefficients. * 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 * Note that this macro double-evaluates its parameter, so do not use
* expressions with side-effects here. * expressions with side-effects here.
@ -947,7 +954,8 @@ typedef enum SDL_ChromaLocation
#define SDL_ISCOLORSPACE_MATRIX_BT709(cspace) (SDL_COLORSPACEMATRIX(cspace) == SDL_MATRIX_COEFFICIENTS_BT709) #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. * A macro to determine if an SDL_Colorspace uses BT2020_NCL matrix
* coefficients.
* *
* \param cspace an SDL_Colorspace to check. * \param cspace an SDL_Colorspace to check.
* \returns true if BT709, false otherwise. * \returns true if BT709, false otherwise.

1
include/SDL3/SDL_platform_defines.h
View file

@ -358,6 +358,7 @@
#endif /* HAVE_WINAPIFAMILY_H */ #endif /* HAVE_WINAPIFAMILY_H */
#ifdef SDL_WIKI_DOCUMENTATION_SECTION #ifdef SDL_WIKI_DOCUMENTATION_SECTION
/** /**
* A preprocessor macro that defined to 1 if compiling for Windows Phone. * A preprocessor macro that defined to 1 if compiling for Windows Phone.
* *

156
include/SDL3/SDL_stdinc.h
View file

@ -826,7 +826,8 @@ SDL_COMPILE_TIME_ASSERT(longlong_size64, sizeof(long long) == 8); /* using I64 f
* and is only written to by the function. The compiler or other analysis * 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. * 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. * 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. * On compilers without this annotation mechanism, this is defined to nothing.
* *
@ -917,13 +918,14 @@ SDL_COMPILE_TIME_ASSERT(longlong_size64, sizeof(long long) == 8); /* using I64 f
* int fprintf(FILE *f, const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2); * 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 `...`. * This notes that the second parameter should be a printf-style format
* The compiler or other analysis tools can warn when this doesn't appear to be the case. * 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. * 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 * This can (and should) be used with SDL_PRINTF_FORMAT_STRING as well, which
* will cover at least Visual Studio, GCC, and Clang. * between them will cover at least Visual Studio, GCC, and Clang.
* *
* \since This macro is available since SDL 3.1.3. * \since This macro is available since SDL 3.1.3.
*/ */
@ -938,13 +940,14 @@ SDL_COMPILE_TIME_ASSERT(longlong_size64, sizeof(long long) == 8); /* using I64 f
* int vfprintf(FILE *f, const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(2); * 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. * This notes that the second parameter should be a printf-style format
* The compiler or other analysis tools can warn when this doesn't appear to be the case. * 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. * 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 * This can (and should) be used with SDL_PRINTF_FORMAT_STRING as well, which
* will cover at least Visual Studio, GCC, and Clang. * between them will cover at least Visual Studio, GCC, and Clang.
* *
* \since This macro is available since SDL 3.1.3. * \since This macro is available since SDL 3.1.3.
*/ */
@ -959,13 +962,14 @@ SDL_COMPILE_TIME_ASSERT(longlong_size64, sizeof(long long) == 8); /* using I64 f
* int fscanf(FILE *f, const char *fmt, ...) SDL_PRINTF_VARARG_FUNCV(2); * 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 `...`. * This notes that the second parameter should be a scanf-style format string,
* The compiler or other analysis tools can warn when this doesn't appear to be the case. * 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. * 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 * This can (and should) be used with SDL_SCANF_FORMAT_STRING as well, which
* will cover at least Visual Studio, GCC, and Clang. * between them will cover at least Visual Studio, GCC, and Clang.
* *
* \since This macro is available since SDL 3.1.3. * \since This macro is available since SDL 3.1.3.
*/ */
@ -980,13 +984,14 @@ SDL_COMPILE_TIME_ASSERT(longlong_size64, sizeof(long long) == 8); /* using I64 f
* int vfscanf(FILE *f, const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(2); * 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. * This notes that the second parameter should be a scanf-style format string,
* The compiler or other analysis tools can warn when this doesn't appear to be the case. * 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. * 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 * This can (and should) be used with SDL_SCANF_FORMAT_STRING as well, which
* will cover at least Visual Studio, GCC, and Clang. * between them will cover at least Visual Studio, GCC, and Clang.
* *
* \since This macro is available since SDL 3.1.3. * \since This macro is available since SDL 3.1.3.
*/ */
@ -1001,13 +1006,14 @@ SDL_COMPILE_TIME_ASSERT(longlong_size64, sizeof(long long) == 8); /* using I64 f
* int fwprintf(FILE *f, const wchar_t *fmt, ...) SDL_WPRINTF_VARARG_FUNC(2); * 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 `...`. * This notes that the second parameter should be a wprintf-style format wide
* The compiler or other analysis tools can warn when this doesn't appear to be the case. * 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. * 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 * This can (and should) be used with SDL_PRINTF_FORMAT_STRING as well, which
* will cover at least Visual Studio, GCC, and Clang. * between them will cover at least Visual Studio, GCC, and Clang.
* *
* \since This macro is available since SDL 3.1.3. * \since This macro is available since SDL 3.1.3.
*/ */
@ -1022,13 +1028,14 @@ SDL_COMPILE_TIME_ASSERT(longlong_size64, sizeof(long long) == 8); /* using I64 f
* int vfwprintf(FILE *f, const wchar_t *fmt, va_list ap) SDL_WPRINTF_VARARG_FUNC(2); * 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. * This notes that the second parameter should be a wprintf-style format wide
* The compiler or other analysis tools can warn when this doesn't appear to be the case. * 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. * 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 * This can (and should) be used with SDL_PRINTF_FORMAT_STRING as well, which
* will cover at least Visual Studio, GCC, and Clang. * between them will cover at least Visual Studio, GCC, and Clang.
* *
* \since This macro is available since SDL 3.1.3. * \since This macro is available since SDL 3.1.3.
*/ */
@ -2582,9 +2589,9 @@ extern SDL_DECLSPEC void * SDLCALL SDL_memset4(void *dst, Uint32 val, size_t dwo
* \param s1 the first buffer to compare. NULL is not permitted! * \param s1 the first buffer to compare. NULL is not permitted!
* \param s2 the second 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. * \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 * \returns less than zero if s1 is "less than" s2, greater than zero if s1 is
* s1 is "greater than" s2, and zero if the buffers match * "greater than" s2, and zero if the buffers match exactly for `len`
* exactly for `len` bytes. * bytes.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
* *
@ -2606,7 +2613,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_memcmp(const void *s1, const void *s2, size_
* bytes on Linux, 2 on Windows, etc). * bytes on Linux, 2 on Windows, etc).
* *
* \param wstr The null-terminated wide string to read. Must not be NULL. * \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`. * \returns the length (in wchar_t values, excluding the null terminator) of
* `wstr`.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
* *
@ -2726,15 +2734,16 @@ extern SDL_DECLSPEC wchar_t * SDLCALL SDL_wcsdup(const wchar_t *wstr);
/** /**
* Search a wide string for the first instance of a specific substring. * Search a wide string for the first instance of a specific substring.
* *
* The search ends once it finds the requested substring, or a null * The search ends once it finds the requested substring, or a null terminator
* terminator byte to end the string. * byte to end the string.
* *
* Note that this looks for strings of _wide characters_, not _codepoints_, so * Note that this looks for strings of _wide characters_, not _codepoints_, so
* it's legal to search for malformed and incomplete UTF-16 sequences. * it's legal to search for malformed and incomplete UTF-16 sequences.
* *
* \param haystack the wide string to search. Must not be NULL. * \param haystack the wide string to search. Must not be NULL.
* \param needle the wide string to search for. 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. * \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. * \threadsafety It is safe to call this function from any thread.
* *
@ -2743,20 +2752,23 @@ extern SDL_DECLSPEC wchar_t * SDLCALL SDL_wcsdup(const wchar_t *wstr);
extern SDL_DECLSPEC wchar_t * SDLCALL SDL_wcsstr(const wchar_t *haystack, const wchar_t *needle); 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. * 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 * The search ends once it finds the requested substring, or a null terminator
* terminator value to end the string, or `maxlen` wide character have been * value to end the string, or `maxlen` wide character have been examined. It
* examined. It is possible to use this function on a wide string without a * is possible to use this function on a wide string without a null
* null terminator. * terminator.
* *
* Note that this looks for strings of _wide characters_, not _codepoints_, so * Note that this looks for strings of _wide characters_, not _codepoints_, so
* it's legal to search for malformed and incomplete UTF-16 sequences. * it's legal to search for malformed and incomplete UTF-16 sequences.
* *
* \param haystack the wide string to search. Must not be NULL. * \param haystack the wide string to search. Must not be NULL.
* \param needle the wide string to search for. 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`. * \param maxlen the maximum number of wide characters to search in
* \returns a pointer to the first instance of `needle` in the string, or NULL if not found. * `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. * \threadsafety It is safe to call this function from any thread.
* *
@ -3064,19 +3076,19 @@ extern SDL_DECLSPEC SDL_MALLOC char * SDLCALL SDL_strdup(const char *str);
* Allocate a copy of a string, up to n characters. * Allocate a copy of a string, up to n characters.
* *
* This allocates enough space for a null-terminated copy of `str`, up to * 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 * `maxlen` bytes, using SDL_malloc, and then makes a copy of the string into
* into this space. * this space.
* *
* If the string is longer than `maxlen` bytes, the returned string will * If the string is longer than `maxlen` bytes, the returned string will be
* be `maxlen` bytes long, plus a null-terminator character that isn't * `maxlen` bytes long, plus a null-terminator character that isn't included
* included in the count. * in the count.
* *
* The returned string is owned by the caller, and should be passed to * The returned string is owned by the caller, and should be passed to
* SDL_free when no longer needed. * SDL_free when no longer needed.
* *
* \param str the string to copy. * \param str the string to copy.
* \param maxlen the maximum length of the copied string, not counting * \param maxlen the maximum length of the copied string, not counting the
* the null-terminator character. * null-terminator character.
* \returns a pointer to the newly-allocated string. * \returns a pointer to the newly-allocated string.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
@ -3998,14 +4010,16 @@ extern SDL_DECLSPEC char * SDLCALL SDL_UCS4ToUTF8(Uint32 codepoint, char *dst);
extern SDL_DECLSPEC int SDLCALL SDL_sscanf(const char *text, SDL_SCANF_FORMAT_STRING const char *fmt, ...) SDL_SCANF_VARARG_FUNC(2); 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. * 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` * Functions identically to SDL_sscanf(), except it takes a `va_list` instead
* instead of using `...` variable arguments. * of using `...` variable arguments.
* *
* \param text the string to scan. Must not be NULL. * \param text the string to scan. Must not be NULL.
* \param fmt a printf-style format string. 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. * \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. * \returns the number of items that matched the format string.
* *
* \threadsafety It is safe to call this function from any thread. * \threadsafety It is safe to call this function from any thread.
@ -4015,14 +4029,15 @@ extern SDL_DECLSPEC int SDLCALL SDL_sscanf(const char *text, SDL_SCANF_FORMAT_ST
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); 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. * 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 * Format a string of up to `maxlen`-1 bytes, converting each '%' item with
* values provided through variable arguments. * values provided through variable arguments.
* *
* While some C runtimes differ on how to deal with too-large strings, * While some C runtimes differ on how to deal with too-large strings, this
* this function null-terminates the output, by treating the null-terminator * function null-terminates the output, by treating the null-terminator as
* as part of the `maxlen` count. Note that if `maxlen` is zero, however, no * part of the `maxlen` count. Note that if `maxlen` is zero, however, no
* bytes will be written at all. * bytes will be written at all.
* *
* This function returns the number of _bytes_ (not _characters_) that should * This function returns the number of _bytes_ (not _characters_) that should
@ -4047,15 +4062,16 @@ extern SDL_DECLSPEC int SDLCALL SDL_vsscanf(const char *text, SDL_SCANF_FORMAT_S
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); 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. * 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 '%' * Format a wide string of up to `maxlen`-1 wchar_t values, converting each
* item with values provided through variable arguments. * '%' item with values provided through variable arguments.
* *
* While some C runtimes differ on how to deal with too-large strings, * While some C runtimes differ on how to deal with too-large strings, this
* this function null-terminates the output, by treating the null-terminator * function null-terminates the output, by treating the null-terminator as
* as part of the `maxlen` count. Note that if `maxlen` is zero, however, no * part of the `maxlen` count. Note that if `maxlen` is zero, however, no wide
* wide characters will be written at all. * characters will be written at all.
* *
* This function returns the number of _wide characters_ (not _codepoints_) * This function returns the number of _wide characters_ (not _codepoints_)
* that should be written, excluding the null-terminator character. If this * that should be written, excluding the null-terminator character. If this
@ -4066,7 +4082,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_snprintf(SDL_OUT_Z_CAP(maxlen) char *text, s
* behavior. * behavior.
* *
* \param text the buffer to write the wide string into. Must not be NULL. * \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 maxlen the maximum wchar_t values to write, including the
* null-terminator.
* \param fmt a printf-style format 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. * \param ... a list of values to be used with the format string.
* \returns the number of wide characters that should be written, not counting * \returns the number of wide characters that should be written, not counting
@ -4079,7 +4096,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_snprintf(SDL_OUT_Z_CAP(maxlen) char *text, s
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); 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. * 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` * Functions identically to SDL_snprintf(), except it takes a `va_list`
* instead of using `...` variable arguments. * instead of using `...` variable arguments.
@ -4098,13 +4116,15 @@ extern SDL_DECLSPEC int SDLCALL SDL_swprintf(SDL_OUT_Z_CAP(maxlen) wchar_t *text
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); 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. * 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` * Functions identically to SDL_swprintf(), except it takes a `va_list`
* instead of using `...` variable arguments. * instead of using `...` variable arguments.
* *
* \param text the buffer to write the string into. Must not be NULL. * \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 maxlen the maximum wide characters to write, including the
* null-terminator.
* \param fmt a printf-style format wide string. Must not be NULL. * \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. * \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 * \returns the number of wide characters that should be written, not counting
@ -4117,7 +4137,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_vsnprintf(SDL_OUT_Z_CAP(maxlen) char *text,
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); 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. * 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 * Functions identically to SDL_snprintf(), except it allocates a buffer large
* enough to hold the output string on behalf of the caller. * enough to hold the output string on behalf of the caller.
@ -4145,7 +4166,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_vswprintf(SDL_OUT_Z_CAP(maxlen) wchar_t *tex
extern SDL_DECLSPEC int SDLCALL SDL_asprintf(char **strp, SDL_PRINTF_FORMAT_STRING const char *fmt, ...) SDL_PRINTF_VARARG_FUNC(2); 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. * 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` * Functions identically to SDL_asprintf(), except it takes a `va_list`
* instead of using `...` variable arguments. * instead of using `...` variable arguments.