From f0fad41f2cb599aab2fd458e3c0192551c591365 Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Sun, 22 Dec 2024 01:57:07 -0500
Subject: [PATCH] include: Filled in all remaining missing documentation!
---
include/SDL3/SDL_assert.h | 115 ++++-
include/SDL3/SDL_atomic.h | 82 +++-
include/SDL3/SDL_audio.h | 69 ++-
include/SDL3/SDL_begin_code.h | 9 +-
include/SDL3/SDL_gpu.h | 40 +-
include/SDL3/SDL_haptic.h | 14 +-
include/SDL3/SDL_hints.h | 9 +
include/SDL3/SDL_init.h | 60 +++
include/SDL3/SDL_intrin.h | 66 ++-
include/SDL3/SDL_main.h | 126 ++++--
include/SDL3/SDL_mutex.h | 158 ++++++-
include/SDL3/SDL_pixels.h | 426 ++++++++++++++++--
include/SDL3/SDL_platform_defines.h | 10 +-
include/SDL3/SDL_process.h | 7 +
include/SDL3/SDL_stdinc.h | 674 +++++++++++++++++++++++++++-
include/SDL3/SDL_system.h | 41 +-
include/SDL3/SDL_video.h | 104 ++++-
17 files changed, 1871 insertions(+), 139 deletions(-)
diff --git a/include/SDL3/SDL_assert.h b/include/SDL3/SDL_assert.h
index 6f6cd19e9071c..167c64f5a60bb 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 14ba31fad83db..32eb4ca9594f1 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 45881e8345d51..3b66fed48fa1f 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 396838fc43e18..bfb1c2cc2ce3d 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 1ed93023f1003..6b03a28a110bf 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 c123cd90cb39d..533f3bcee7408 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 1fee3d95488c9..1e03207d7d753 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 e936f9097860b..92ced243ea739 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 5f5805cc6f92e..77466b809f769 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 d51977b63f01e..b244af1cd1b76 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 <SDL3/SDL_error.h>
#include <SDL3/SDL_events.h>
+#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,39 +222,33 @@
#endif
#endif /* SDL_MAIN_HANDLED */
-#ifdef 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
-#else
-/* usually this is empty */
-#define SDLMAIN_DECLSPEC
-#endif /* SDL_MAIN_EXPORTED */
#ifdef SDL_WIKI_DOCUMENTATION_SECTION
/**
- * Inform SDL to use the main callbacks instead of main.
+ * A macro to tag a main entry point function as exported.
*
- * SDL does not
(Patch may be truncated, please check the link at the top of this post.)