From c7dafb1556acc964222e9fa6ff9e262e0f17158a Mon Sep 17 00:00:00 2001
From: SDL Wiki Bot <[EMAIL REDACTED]>
Date: Wed, 27 Oct 2021 01:36:05 +0000
Subject: [PATCH] Sync wiki -> header
---
include/SDL.h | 10 +++
include/SDL_assert.h | 6 ++
include/SDL_atomic.h | 16 +++++
include/SDL_audio.h | 56 ++++++++++++++++
include/SDL_blendmode.h | 2 +-
include/SDL_clipboard.h | 4 ++
include/SDL_cpuinfo.h | 32 +++++++++
include/SDL_error.h | 8 +++
include/SDL_events.h | 32 +++++++++
include/SDL_gamecontroller.h | 70 ++++++++++++++++++++
include/SDL_haptic.h | 20 ++++++
include/SDL_hints.h | 8 +++
include/SDL_joystick.h | 94 ++++++++++++++++++++++++++
include/SDL_keyboard.h | 22 ++++++
include/SDL_loadso.h | 6 ++
include/SDL_locale.h | 2 +
include/SDL_log.h | 28 ++++++++
include/SDL_main.h | 6 ++
include/SDL_messagebox.h | 2 +
include/SDL_metal.h | 8 +++
include/SDL_misc.h | 2 +-
include/SDL_mouse.h | 22 ++++++
include/SDL_mutex.h | 36 ++++++++++
include/SDL_pixels.h | 26 ++++++++
include/SDL_platform.h | 2 +
include/SDL_power.h | 2 +
include/SDL_rect.h | 6 ++
include/SDL_render.h | 125 +++++++++++++++++++++++++++++++++++
include/SDL_rwops.h | 52 ++++++++++++++-
include/SDL_sensor.h | 30 +++++++++
include/SDL_shape.h | 8 +++
include/SDL_stdinc.h | 8 +++
include/SDL_surface.h | 72 ++++++++++++++++++++
include/SDL_system.h | 20 +++++-
include/SDL_thread.h | 16 +++++
include/SDL_timer.h | 10 +++
include/SDL_touch.h | 4 ++
include/SDL_version.h | 6 ++
include/SDL_video.h | 119 +++++++++++++++++++++++++++++++++
include/SDL_vulkan.h | 12 ++--
40 files changed, 1001 insertions(+), 9 deletions(-)
diff --git a/include/SDL.h b/include/SDL.h
index 222a8bd999..07d3356bf8 100644
--- a/include/SDL.h
+++ b/include/SDL.h
@@ -132,6 +132,8 @@ extern "C" {
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
+ * \since This function is available since SDL 2.0.0.
+ *
* \sa SDL_InitSubSystem
* \sa SDL_Quit
* \sa SDL_SetMainReady
@@ -148,6 +150,8 @@ extern DECLSPEC int SDLCALL SDL_Init(Uint32 flags);
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
+ * \since This function is available since SDL 2.0.0.
+ *
* \sa SDL_Init
* \sa SDL_Quit
* \sa SDL_QuitSubSystem
@@ -169,6 +173,8 @@ extern DECLSPEC int SDLCALL SDL_InitSubSystem(Uint32 flags);
*
* \param flags any of the flags used by SDL_Init(); see SDL_Init for details.
*
+ * \since This function is available since SDL 2.0.0.
+ *
* \sa SDL_InitSubSystem
* \sa SDL_Quit
*/
@@ -183,6 +189,8 @@ extern DECLSPEC void SDLCALL SDL_QuitSubSystem(Uint32 flags);
*
* The return value does not include SDL_INIT_NOPARACHUTE.
*
+ * \since This function is available since SDL 2.0.0.
+ *
* \sa SDL_Init
* \sa SDL_InitSubSystem
*/
@@ -205,6 +213,8 @@ extern DECLSPEC Uint32 SDLCALL SDL_WasInit(Uint32 flags);
* application is shutdown, but it is not wise to do this from a library or
* other dynamically loaded code.
*
+ * \since This function is available since SDL 2.0.0.
+ *
* \sa SDL_Init
* \sa SDL_QuitSubSystem
*/
diff --git a/include/SDL_assert.h b/include/SDL_assert.h
index a627b17869..4c20993022 100644
--- a/include/SDL_assert.h
+++ b/include/SDL_assert.h
@@ -217,6 +217,8 @@ typedef SDL_AssertState (SDLCALL *SDL_AssertionHandler)(
* fails or NULL for the default handler
* \param userdata a pointer that is passed to `handler`
*
+ * \since This function is available since SDL 2.0.0.
+ *
* \sa SDL_GetAssertionHandler
*/
extern DECLSPEC void SDLCALL SDL_SetAssertionHandler(
@@ -285,6 +287,8 @@ extern DECLSPEC SDL_AssertionHandler SDLCALL SDL_GetAssertionHandler(void **puse
* \returns a list of all failed assertions or NULL if the list is empty. This
* memory should not be modified or freed by the application.
*
+ * \since This function is available since SDL 2.0.0.
+ *
* \sa SDL_ResetAssertionReport
*/
extern DECLSPEC const SDL_AssertData * SDLCALL SDL_GetAssertionReport(void);
@@ -297,6 +301,8 @@ extern DECLSPEC const SDL_AssertData * SDLCALL SDL_GetAssertionReport(void);
* no items. In addition, any previously-triggered assertions will be reset to
* a trigger_count of zero, and their always_ignore state will be false.
*
+ * \since This function is available since SDL 2.0.0.
+ *
* \sa SDL_GetAssertionReport
*/
extern DECLSPEC void SDLCALL SDL_ResetAssertionReport(void);
diff --git a/include/SDL_atomic.h b/include/SDL_atomic.h
index 5e1eae7735..db0dbe95d6 100644
--- a/include/SDL_atomic.h
+++ b/include/SDL_atomic.h
@@ -98,6 +98,8 @@ typedef int SDL_SpinLock;
* \returns SDL_TRUE if the lock succeeded, SDL_FALSE if the lock is already
* held.
*
+ * \since This function is available since SDL 2.0.0.
+ *
* \sa SDL_AtomicLock
* \sa SDL_AtomicUnlock
*/
@@ -111,6 +113,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_AtomicTryLock(SDL_SpinLock *lock);
*
* \param lock a pointer to a lock variable
*
+ * \since This function is available since SDL 2.0.0.
+ *
* \sa SDL_AtomicTryLock
* \sa SDL_AtomicUnlock
*/
@@ -173,6 +177,8 @@ 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
+ *
+ * \since This function is available since SDL 2.0.6.
*/
extern DECLSPEC void SDLCALL SDL_MemoryBarrierReleaseFunction(void);
extern DECLSPEC void SDLCALL SDL_MemoryBarrierAcquireFunction(void);
@@ -268,6 +274,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_AtomicCAS(SDL_atomic_t *a, int oldval, int
* \param v the desired value
* \returns the previous value of the atomic variable.
*
+ * \since This function is available since SDL 2.0.2.
+ *
* \sa SDL_AtomicGet
*/
extern DECLSPEC int SDLCALL SDL_AtomicSet(SDL_atomic_t *a, int v);
@@ -281,6 +289,8 @@ extern DECLSPEC int SDLCALL SDL_AtomicSet(SDL_atomic_t *a, int v);
* \param a a pointer to an SDL_atomic_t variable
* \returns the current value of an atomic variable.
*
+ * \since This function is available since SDL 2.0.2.
+ *
* \sa SDL_AtomicSet
*/
extern DECLSPEC int SDLCALL SDL_AtomicGet(SDL_atomic_t *a);
@@ -297,6 +307,8 @@ extern DECLSPEC int SDLCALL SDL_AtomicGet(SDL_atomic_t *a);
* \param v the desired value to add
* \returns the previous value of the atomic variable.
*
+ * \since This function is available since SDL 2.0.2.
+ *
* \sa SDL_AtomicDecRef
* \sa SDL_AtomicIncRef
*/
@@ -348,6 +360,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_AtomicCASPtr(void **a, void *oldval, void *
* \param v the desired pointer value
* \returns the previous value of the pointer.
*
+ * \since This function is available since SDL 2.0.2.
+ *
* \sa SDL_AtomicCASPtr
* \sa SDL_AtomicGetPtr
*/
@@ -362,6 +376,8 @@ extern DECLSPEC void* SDLCALL SDL_AtomicSetPtr(void **a, void* v);
* \param a a pointer to a pointer
* \returns the current value of a pointer.
*
+ * \since This function is available since SDL 2.0.2.
+ *
* \sa SDL_AtomicCASPtr
* \sa SDL_AtomicSetPtr
*/
diff --git a/include/SDL_audio.h b/include/SDL_audio.h
index dd815d0310..7bfb2daa11 100644
--- a/include/SDL_audio.h
+++ b/include/SDL_audio.h
@@ -291,6 +291,8 @@ extern DECLSPEC int SDLCALL SDL_GetNumAudioDrivers(void);
* \returns the name of the audio driver at the requested index, or NULL if an
* invalid index was specified.
*
+ * \since This function is available since SDL 2.0.0.
+ *
* \sa SDL_GetNumAudioDrivers
*/
extern DECLSPEC const char *SDLCALL SDL_GetAudioDriver(int index);
@@ -316,6 +318,8 @@ extern DECLSPEC const char *SDLCALL SDL_GetAudioDriver(int index);
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
+ * \since This function is available since SDL 2.0.0.
+ *
* \sa SDL_AudioQuit
*/
extern DECLSPEC int SDLCALL SDL_AudioInit(const char *driver_name);
@@ -328,6 +332,8 @@ extern DECLSPEC int SDLCALL SDL_AudioInit(const char *driver_name);
* specific need to specify the audio driver you want to use. You should
* normally use SDL_Quit() or SDL_QuitSubSystem().
*
+ * \since This function is available since SDL 2.0.0.
+ *
* \sa SDL_AudioInit
*/
extern DECLSPEC void SDLCALL SDL_AudioQuit(void);
@@ -391,6 +397,8 @@ extern DECLSPEC const char *SDLCALL SDL_GetCurrentAudioDriver(void);
* audio device or failure to set up the audio thread; call
* SDL_GetError() for more information.
*
+ * \since This function is available since SDL 2.0.0.
+ *
* \sa SDL_CloseAudio
* \sa SDL_LockAudio
* \sa SDL_PauseAudio
@@ -476,6 +484,8 @@ extern DECLSPEC int SDLCALL SDL_GetNumAudioDevices(int iscapture);
* \returns the name of the audio device at the requested index, or NULL on
* error.
*
+ * \since This function is available since SDL 2.0.0.
+ *
* \sa SDL_GetNumAudioDevices
*/
extern DECLSPEC const char *SDLCALL SDL_GetAudioDeviceName(int index,
@@ -656,6 +666,8 @@ typedef enum
*
* \returns the SDL_AudioStatus of the audio device opened by SDL_OpenAudio().
*
+ * \since This function is available since SDL 2.0.0.
+ *
* \sa SDL_GetAudioDeviceStatus
*/
extern DECLSPEC SDL_AudioStatus SDLCALL SDL_GetAudioStatus(void);
@@ -667,6 +679,8 @@ extern DECLSPEC SDL_AudioStatus SDLCALL SDL_GetAudioStatus(void);
* SDL_OpenAudioDevice()
* \returns the SDL_AudioStatus of the specified audio device.
*
+ * \since This function is available since SDL 2.0.0.
+ *
* \sa SDL_PauseAudioDevice
*/
extern DECLSPEC SDL_AudioStatus SDLCALL SDL_GetAudioDeviceStatus(SDL_AudioDeviceID dev);
@@ -697,6 +711,8 @@ extern DECLSPEC SDL_AudioStatus SDLCALL SDL_GetAudioDeviceStatus(SDL_AudioDevice
*
* \param pause_on non-zero to pause, 0 to unpause
*
+ * \since This function is available since SDL 2.0.0.
+ *
* \sa SDL_GetAudioStatus
* \sa SDL_PauseAudioDevice
*/
@@ -726,6 +742,8 @@ extern DECLSPEC void SDLCALL SDL_PauseAudio(int pause_on);
* \param dev a device opened by SDL_OpenAudioDevice()
* \param pause_on non-zero to pause, 0 to unpause
*
+ * \since This function is available since SDL 2.0.0.
+ *
* \sa SDL_LockAudioDevice
*/
extern DECLSPEC void SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev,
@@ -808,6 +826,8 @@ extern DECLSPEC void SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev,
* When the application is done with the data returned in
* `audio_buf`, it should call SDL_FreeWAV() to dispose of it.
*
+ * \since This function is available since SDL 2.0.0.
+ *
* \sa SDL_FreeWAV
* \sa SDL_LoadWAV
*/
@@ -834,6 +854,8 @@ extern DECLSPEC SDL_AudioSpec *SDLCALL SDL_LoadWAV_RW(SDL_RWops * src,
* \param audio_buf a pointer to the buffer created by SDL_LoadWAV() or
* SDL_LoadWAV_RW()
*
+ * \since This function is available since SDL 2.0.0.
+ *
* \sa SDL_LoadWAV
* \sa SDL_LoadWAV_RW
*/
@@ -867,6 +889,8 @@ extern DECLSPEC void SDLCALL SDL_FreeWAV(Uint8 * audio_buf);
* or a negative error code on failure; call SDL_GetError() for more
* information.
*
+ * \since This function is available since SDL 2.0.0.
+ *
* \sa SDL_ConvertAudio
*/
extern DECLSPEC int SDLCALL SDL_BuildAudioCVT(SDL_AudioCVT * cvt,
@@ -911,6 +935,8 @@ extern DECLSPEC int SDLCALL SDL_BuildAudioCVT(SDL_AudioCVT * cvt,
* \returns 0 if the conversion was completed successfully or a negative error
* code on failure; call SDL_GetError() for more information.
*
+ * \since This function is available since SDL 2.0.0.
+ *
* \sa SDL_BuildAudioCVT
*/
extern DECLSPEC int SDLCALL SDL_ConvertAudio(SDL_AudioCVT * cvt);
@@ -937,6 +963,8 @@ typedef struct _SDL_AudioStream SDL_AudioStream;
* \param dst_rate The sampling rate of the desired audio output
* \returns 0 on success, or -1 on error.
*
+ * \since This function is available since SDL 2.0.7.
+ *
* \sa SDL_AudioStreamPut
* \sa SDL_AudioStreamGet
* \sa SDL_AudioStreamAvailable
@@ -959,6 +987,8 @@ extern DECLSPEC SDL_AudioStream * SDLCALL SDL_NewAudioStream(const SDL_AudioForm
* \param len The number of bytes to write to the stream
* \returns 0 on success, or -1 on error.
*
+ * \since This function is available since SDL 2.0.7.
+ *
* \sa SDL_NewAudioStream
* \sa SDL_AudioStreamGet
* \sa SDL_AudioStreamAvailable
@@ -976,6 +1006,8 @@ extern DECLSPEC int SDLCALL SDL_AudioStreamPut(SDL_AudioStream *stream, const vo
* \param len The maximum number of bytes to fill
* \returns the number of bytes read from the stream, or -1 on error
*
+ * \since This function is available since SDL 2.0.7.
+ *
* \sa SDL_NewAudioStream
* \sa SDL_AudioStreamPut
* \sa SDL_AudioStreamAvailable
@@ -992,6 +1024,8 @@ extern DECLSPEC int SDLCALL SDL_AudioStreamGet(SDL_AudioStream *stream, void *bu
* resample correctly, so this number might be lower than what you expect, or
* even be zero. Add more data or flush the stream if you need the data now.
*
+ * \since This function is available since SDL 2.0.7.
+ *
* \sa SDL_NewAudioStream
* \sa SDL_AudioStreamPut
* \sa SDL_AudioStreamGet
@@ -1009,6 +1043,8 @@ extern DECLSPEC int SDLCALL SDL_AudioStreamAvailable(SDL_AudioStream *stream);
* audio gaps in the output. Generally this is intended to signal the end of
* input, so the complete output becomes available.
*
+ * \since This function is available since SDL 2.0.7.
+ *
* \sa SDL_NewAudioStream
* \sa SDL_AudioStreamPut
* \sa SDL_AudioStreamGet
@@ -1021,6 +1057,8 @@ extern DECLSPEC int SDLCALL SDL_AudioStreamFlush(SDL_AudioStream *stream);
/**
* Clear any pending data in the stream without converting it
*
+ * \since This function is available since SDL 2.0.7.
+ *
* \sa SDL_NewAudioStream
* \sa SDL_AudioStreamPut
* \sa SDL_AudioStreamGet
@@ -1033,6 +1071,8 @@ extern DECLSPEC void SDLCALL SDL_AudioStreamClear(SDL_AudioStream *stream);
/**
* Free an audio stream
*
+ * \since This function is available since SDL 2.0.7.
+ *
* \sa SDL_NewAudioStream
* \sa SDL_AudioStreamPut
* \sa SDL_AudioStreamGet
@@ -1062,6 +1102,8 @@ extern DECLSPEC void SDLCALL SDL_FreeAudioStream(SDL_AudioStream *stream);
* \param volume ranges from 0 - 128, and should be set to SDL_MIX_MAXVOLUME
* for full audio volume
*
+ * \since This function is available since SDL 2.0.0.
+ *
* \sa SDL_MixAudioFormat
*/
extern DECLSPEC void SDLCALL SDL_MixAudio(Uint8 * dst, const Uint8 * src,
@@ -1094,6 +1136,8 @@ extern DECLSPEC void SDLCALL SDL_MixAudio(Uint8 * dst, const Uint8 * src,
* \param len the length of the audio buffer in bytes
* \param volume ranges from 0 - 128, and should be set to SDL_MIX_MAXVOLUME
* for full audio volume
+ *
+ * \since This function is available since SDL 2.0.0.
*/
extern DECLSPEC void SDLCALL SDL_MixAudioFormat(Uint8 * dst,
const Uint8 * src,
@@ -1287,6 +1331,8 @@ extern DECLSPEC void SDLCALL SDL_ClearQueuedAudio(SDL_AudioDeviceID dev);
*
* ...and is only useful if you used the legacy SDL_OpenAudio() function.
*
+ * \since This function is available since SDL 2.0.0.
+ *
* \sa SDL_LockAudioDevice
* \sa SDL_UnlockAudio
* \sa SDL_UnlockAudioDevice
@@ -1326,6 +1372,8 @@ extern DECLSPEC void SDLCALL SDL_LockAudio(void);
*
* \param dev the ID of the device to be locked
*
+ * \since This function is available since SDL 2.0.0.
+ *
* \sa SDL_UnlockAudioDevice
*/
extern DECLSPEC void SDLCALL SDL_LockAudioDevice(SDL_AudioDeviceID dev);
@@ -1342,6 +1390,8 @@ extern DECLSPEC void SDLCALL SDL_LockAudioDevice(SDL_AudioDeviceID dev);
*
* ...and is only useful if you used the legacy SDL_OpenAudio() function.
*
+ * \since This function is available since SDL 2.0.0.
+ *
* \sa SDL_LockAudio
* \sa SDL_UnlockAudioDevice
*/
@@ -1355,6 +1405,8 @@ extern DECLSPEC void SDLCALL SDL_UnlockAudio(void);
*
* \param dev the ID of the device to be unlocked
*
+ * \since This function is available since SDL 2.0.0.
+ *
* \sa SDL_LockAudioDevice
*/
extern DECLSPEC void SDLCALL SDL_UnlockAudioDevice(SDL_AudioDeviceID dev);
@@ -1371,6 +1423,8 @@ extern DECLSPEC void SDLCALL SDL_UnlockAudioDevice(SDL_AudioDeviceID dev);
*
* ...and is only useful if you used the legacy SDL_OpenAudio() function.
*
+ * \since This function is available since SDL 2.0.0.
+ *
* \sa SDL_OpenAudio
*/
extern DECLSPEC void SDLCALL SDL_CloseAudio(void);
@@ -1393,6 +1447,8 @@ extern DECLSPEC void SDLCALL SDL_CloseAudio(void);
*
* \param dev an audio device previously opened with SDL_OpenAudioDevice()
*
+ * \since This function is available since SDL 2.0.0.
+ *
* \sa SDL_OpenAudioDevice
*/
extern DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID dev);
diff --git a/include/SDL_blendmode.h b/include/SDL_blendmode.h
index 374f225a0b..84e3653aac 100644
--- a/include/SDL_blendmode.h
+++ b/include/SDL_blendmode.h
@@ -175,7 +175,7 @@ typedef enum
* \returns an SDL_BlendMode that represents the chosen factors and
* operations.
*
- * \since This function is available in SDL 2.0.6.
+ * \since This function is available since SDL 2.0.6.
*
* \sa SDL_SetRenderDrawBlendMode
* \sa SDL_GetRenderDrawBlendMode
diff --git a/include/SDL_clipboard.h b/include/SDL_clipboard.h
index 1ed8120532..8a574ccb19 100644
--- a/include/SDL_clipboard.h
+++ b/include/SDL_clipboard.h
@@ -45,6 +45,8 @@ extern "C" {
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
+ * \since This function is available since SDL 2.0.0.
+ *
* \sa SDL_GetClipboardText
* \sa SDL_HasClipboardText
*/
@@ -61,6 +63,8 @@ extern DECLSPEC int SDLCALL SDL_SetClipboardText(const char *text);
* on the returned pointer when done with it (even if there was an
* error).
*
+ * \since This function is available since SDL 2.0.0.
+ *
* \sa SDL_HasClipboardText
* \sa SDL_SetClipboardText
*/
diff --git a/include/SDL_cpuinfo.h b/include/SDL_cpuinfo.h
index 9b6ec7003c..89cc74097d 100644
--- a/include/SDL_cpuinfo.h
+++ b/include/SDL_cpuinfo.h
@@ -158,6 +158,8 @@ extern DECLSPEC int SDLCALL SDL_GetCPUCacheLineSize(void);
*
* \returns SDL_TRUE if the CPU has the RDTSC instruction or SDL_FALSE if not.
*
+ * \since This function is available since SDL 2.0.0.
+ *
* \sa SDL_Has3DNow
* \sa SDL_HasAltiVec
* \sa SDL_HasAVX
@@ -179,6 +181,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_HasRDTSC(void);
*
* \returns SDL_TRUE if the CPU has AltiVec features or SDL_FALSE if not.
*
+ * \since This function is available since SDL 2.0.0.
+ *
* \sa SDL_Has3DNow
* \sa SDL_HasAVX
* \sa SDL_HasAVX2
@@ -199,6 +203,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_HasAltiVec(void);
*
* \returns SDL_TRUE if the CPU has MMX features or SDL_FALSE if not.
*
+ * \since This function is available since SDL 2.0.0.
+ *
* \sa SDL_Has3DNow
* \sa SDL_HasAltiVec
* \sa SDL_HasAVX
@@ -219,6 +225,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_HasMMX(void);
*
* \returns SDL_TRUE if the CPU has 3DNow! features or SDL_FALSE if not.
*
+ * \since This function is available since SDL 2.0.0.
+ *
* \sa SDL_HasAltiVec
* \sa SDL_HasAVX
* \sa SDL_HasAVX2
@@ -239,6 +247,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_Has3DNow(void);
*
* \returns SDL_TRUE if the CPU has SSE features or SDL_FALSE if not.
*
+ * \since This function is available since SDL 2.0.0.
+ *
* \sa SDL_Has3DNow
* \sa SDL_HasAltiVec
* \sa SDL_HasAVX
@@ -259,6 +269,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_HasSSE(void);
*
* \returns SDL_TRUE if the CPU has SSE2 features or SDL_FALSE if not.
*
+ * \since This function is available since SDL 2.0.0.
+ *
* \sa SDL_Has3DNow
* \sa SDL_HasAltiVec
* \sa SDL_HasAVX
@@ -279,6 +291,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_HasSSE2(void);
*
* \returns SDL_TRUE if the CPU has SSE3 features or SDL_FALSE if not.
*
+ * \since This function is available since SDL 2.0.0.
+ *
* \sa SDL_Has3DNow
* \sa SDL_HasAltiVec
* \sa SDL_HasAVX
@@ -299,6 +313,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_HasSSE3(void);
*
* \returns SDL_TRUE if the CPU has SSE4.1 features or SDL_FALSE if not.
*
+ * \since This function is available since SDL 2.0.0.
+ *
* \sa SDL_Has3DNow
* \sa SDL_HasAltiVec
* \sa SDL_HasAVX
@@ -319,6 +335,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_HasSSE41(void);
*
* \returns SDL_TRUE if the CPU has SSE4.2 features or SDL_FALSE if not.
*
+ * \since This function is available since SDL 2.0.0.
+ *
* \sa SDL_Has3DNow
* \sa SDL_HasAltiVec
* \sa SDL_HasAVX
@@ -383,6 +401,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_HasAVX2(void);
*
* \returns SDL_TRUE if the CPU has AVX-512F features or SDL_FALSE if not.
*
+ * \since This function is available since SDL 2.0.9.
+ *
* \sa SDL_HasAVX
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasAVX512F(void);
@@ -396,6 +416,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_HasAVX512F(void);
*
* \returns SDL_TRUE if the CPU has ARM SIMD features or SDL_FALSE if not.
*
+ * \since This function is available since SDL 2.0.12.
+ *
* \sa SDL_HasNEON
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasARMSIMD(void);
@@ -406,6 +428,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_HasARMSIMD(void);
* This always returns false on CPUs that aren't using ARM instruction sets.
*
* \returns SDL_TRUE if the CPU has ARM NEON features or SDL_FALSE if not.
+ *
+ * \since This function is available since SDL 2.0.6.
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasNEON(void);
@@ -432,6 +456,8 @@ extern DECLSPEC int SDLCALL SDL_GetSystemRAM(void);
*
* \returns the alignment in bytes needed for available, known SIMD
* instructions.
+ *
+ * \since This function is available since SDL 2.0.10.
*/
extern DECLSPEC size_t SDLCALL SDL_SIMDGetAlignment(void);
@@ -466,6 +492,8 @@ extern DECLSPEC size_t SDLCALL SDL_SIMDGetAlignment(void);
* allocated block might be larger due to padding, etc.
* \returns a pointer to the newly-allocated block, NULL if out of memory.
*
+ * \since This function is available since SDL 2.0.10.
+ *
* \sa SDL_SIMDAlignment
* \sa SDL_SIMDRealloc
* \sa SDL_SIMDFree
@@ -488,6 +516,8 @@ extern DECLSPEC void * SDLCALL SDL_SIMDAlloc(const size_t len);
* memory.
* \returns a pointer to the newly-reallocated block, NULL if out of memory.
*
+ * \since This function is available since SDL 2.0.14.
+ *
* \sa SDL_SIMDAlignment
* \sa SDL_SIMDAlloc
* \sa SDL_SIMDFree
@@ -511,6 +541,8 @@ extern DECLSPEC void * SDLCALL SDL_SIMDRealloc(void *mem, const size_t len);
* \param ptr The pointer, returned from SDL_SIMDAlloc or SDL_SIMDRealloc, to
* deallocate. NULL is a legal no-op.
*
+ * \since This function is available since SDL 2.0.10.
+ *
* \sa SDL_SIMDAlloc
* \sa SDL_SIMDRealloc
*/
diff --git a/include/SDL_error.h b/include/SDL_error.h
index acdf3f6ba7..33277c50b8 100644
--- a/include/SDL_error.h
+++ b/include/SDL_error.h
@@ -58,6 +58,8 @@ extern "C" {
* any
* \returns always -1.
*
+ * \since This function is available since SDL 2.0.0.
+ *
* \sa SDL_ClearError
* \sa SDL_GetError
*/
@@ -93,6 +95,8 @@ extern DECLSPEC int SDLCALL SDL_SetError(SDL_PRINTF_FORMAT_STRING const char *fm
* return values of SDL function calls to determine when to
* appropriately call SDL_GetError().
*
+ * \since This function is available since SDL 2.0.0.
+ *
* \sa SDL_ClearError
* \sa SDL_SetError
*/
@@ -109,6 +113,8 @@ extern DECLSPEC const char *SDLCALL SDL_GetError(void);
* \param maxlen The size of the buffer pointed to by the errstr parameter
* \returns the pointer passed in as the `errstr` parameter.
*
+ * \since This function is available since SDL 2.0.14.
+ *
* \sa SDL_GetError
*/
extern DECLSPEC char * SDLCALL SDL_GetErrorMsg(char *errstr, int maxlen);
@@ -116,6 +122,8 @@ extern DECLSPEC char * SDLCALL SDL_GetErrorMsg(char *errstr, int maxlen);
/**
* Clear any previous error message for this thread.
*
+ * \since This function is available since SDL 2.0.0.
+ *
* \sa SDL_GetError
* \sa SDL_SetError
*/
diff --git a/include/SDL_events.h b/include/SDL_events.h
index c018e3b41a..9718c404ae 100644
--- a/include/SDL_events.h
+++ b/include/SDL_events.h
@@ -662,6 +662,8 @@ SDL_COMPILE_TIME_ASSERT(SDL_Event, sizeof(SDL_Event) == sizeof(((SDL_Event *)NUL
* polling or waiting for events (e.g. you are filtering them), then you must
* call SDL_PumpEvents() to force an event queue update.
*
+ * \since This function is available since SDL 2.0.0.
+ *
* \sa SDL_PollEvent
* \sa SDL_WaitEvent
*/
@@ -707,6 +709,8 @@ typedef enum
* \returns the number of events actually stored or a negative error code on
* failure; call SDL_GetError() for more information.
*
+ * \since This function is available since SDL 2.0.0.
+ *
* \sa SDL_PollEvent
* \sa SDL_PumpEvents
* \sa SDL_PushEvent
@@ -726,6 +730,8 @@ extern DECLSPEC int SDLCALL SDL_PeepEvents(SDL_Event * events, int numevents,
* \returns SDL_TRUE if events matching `type` are present, or SDL_FALSE if
* events matching `type` are not present.
*
+ * \since This function is available since SDL 2.0.0.
+ *
* \sa SDL_HasEvents
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasEvent(Uint32 type);
@@ -743,6 +749,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_HasEvent(Uint32 type);
* \returns SDL_TRUE if events with type >= `minType` and <= `maxType` are
* present, or SDL_FALSE if not.
*
+ * \since This function is available since SDL 2.0.0.
+ *
* \sa SDL_HasEvents
*/
extern DECLSPEC SDL_bool SDLCALL SDL_HasEvents(Uint32 minType, Uint32 maxType);
@@ -763,6 +771,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_HasEvents(Uint32 minType, Uint32 maxType);
*
* \param type the type of event to be cleared; see SDL_EventType for details
*
+ * \since This function is available since SDL 2.0.0.
+ *
* \sa SDL_FlushEvents
*/
extern DECLSPEC void SDLCALL SDL_FlushEvent(Uint32 type);
@@ -786,6 +796,8 @@ extern DECLSPEC void SDLCALL SDL_FlushEvent(Uint32 type);
* \param maxType the high end of event type to be cleared, inclusive; see
* SDL_EventType for details
*
+ * \since This function is available since SDL 2.0.0.
+ *
* \sa SDL_FlushEvent
*/
extern DECLSPEC void SDLCALL SDL_FlushEvents(Uint32 minType, Uint32 maxType);
@@ -826,6 +838,8 @@ extern DECLSPEC void SDLCALL SDL_FlushEvents(Uint32 minType, Uint32 maxType);
* the queue, or NULL
* \returns 1 if there is a pending event or 0 if there are none available.
*
+ * \since This function is available since SDL 2.0.0.
+ *
* \sa SDL_GetEventFilter
* \sa SDL_PeepEvents
* \sa SDL_PushEvent
@@ -849,6 +863,8 @@ extern DECLSPEC int SDLCALL SDL_PollEvent(SDL_Event * event);
* \returns 1 on success or 0 if there was an error while waiting for events;
* call SDL_GetError() for more information.
*
+ * \since This function is available since SDL 2.0.0.
+ *
* \sa SDL_PollEvent
* \sa SDL_PumpEvents
* \sa SDL_WaitEventTimeout
@@ -873,6 +889,8 @@ extern DECLSPEC int SDLCALL SDL_WaitEvent(SDL_Event * event);
* call SDL_GetError() for more information. This also returns 0 if
* the timeout elapsed without an event arriving.
*
+ * \since This function is available since SDL 2.0.0.
+ *
* \sa SDL_PollEvent
* \sa SDL_PumpEvents
* \sa SDL_WaitEvent
@@ -906,6 +924,8 @@ extern DECLSPEC int SDLCALL SDL_WaitEventTimeout(SDL_Event * event,
* code on failure; call SDL_GetError() for more information. A
* common reason for error is the event queue being full.
*
+ * \since This function is available since SDL 2.0.0.
+ *
* \sa SDL_PeepEvents
* \sa SDL_PollEvent
* \sa SDL_RegisterEvents
@@ -960,6 +980,8 @@ typedef int (SDLCALL * SDL_EventFilter) (void *userdata, SDL_Event * event);
* \param filter An SDL_EventFilter function to call when an event happens
* \param userdata a pointer that is passed to `filter`
*
+ * \since This function is available since SDL 2.0.0.
+ *
* \sa SDL_AddEventWatch
* \sa SDL_EventState
* \sa SDL_GetEventFilter
@@ -980,6 +1002,8 @@ extern DECLSPEC void SDLCALL SDL_SetEventFilter(SDL_EventFilter filter,
* be stored here
* \returns SDL_TRUE on success or SDL_FALSE if there is no event filter set.
*
+ * \since This function is available since SDL 2.0.0.
+ *
* \sa SDL_SetEventFilter
*/
extern DECLSPEC SDL_bool SDLCALL SDL_GetEventFilter(SDL_EventFilter * filter,
@@ -1006,6 +1030,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GetEventFilter(SDL_EventFilter * filter,
* \param filter an SDL_EventFilter function to call when an event happens.
* \param userdata a pointer that is passed to `filter`
*
+ * \since This function is available since SDL 2.0.0.
+ *
* \sa SDL_DelEventWatch
* \sa SDL_SetEventFilter
*/
@@ -1021,6 +1047,8 @@ extern DECLSPEC void SDLCALL SDL_AddEventWatch(SDL_EventFilter filter,
* \param filter the function originally passed to SDL_AddEventWatch()
* \param userdata the pointer originally passed to SDL_AddEventWatch()
*
+ * \since This function is available since SDL 2.0.0.
+ *
* \sa SDL_AddEventWatch
*/
extern DECLSPEC void SDLCALL SDL_DelEventWatch(SDL_EventFilter filter,
@@ -1037,6 +1065,8 @@ extern DECLSPEC void SDLCALL SDL_DelEventWatch(SDL_EventFilter filter,
* \param filter the SDL_EventFilter function to call when an event happens
* \param userdata a pointer that is passed to `filter`
*
+ * \since This function is available since SDL 2.0.0.
+ *
* \sa SDL_GetEventFilter
* \sa SDL_SetEventFilter
*/
@@ -1064,6 +1094,8 @@ extern DECLSPEC void SDLCALL SDL_FilterEvents(SDL_EventFilter filter,
* \returns `SDL_DISABLE` or `SDL_ENABLE`, representing the processing state
* of the event before this function makes any changes to it.
*
+ * \since This function is available since SDL 2.0.0.
+ *
* \sa SDL_GetEventState
*/
extern DECLSPEC Uint8 SDLCALL SDL_EventState(Uint32 type, int state);
diff --git a/include/SDL_gamecontroller.h b/include/SDL_gamecontroller.h
index 685bed0d70..695201e56b 100644
--- a/include/SDL_gamecontroller.h
+++ b/include/SDL_gamecontroller.h
@@ -189,6 +189,8 @@ extern DECLSPEC int SDLCALL SDL_GameControllerAddMappingsFromRW(SDL_RWops * rw,
* \returns 1 if a new mapping is added, 0 if an existing mapping is updated,
* -1 on error; call SDL_GetError() for more information.
*
+ * \since This function is available since SDL 2.0.0.
+ *
* \sa SDL_GameControllerMapping
* \sa SDL_GameControllerMappingForGUID
*/
@@ -198,6 +200,8 @@ extern DECLSPEC int SDLCALL SDL_GameControllerAddMapping(const char* mappingStri
* Get the number of mappings installed.
*
* \returns the number of mappings.
+ *
+ * \since This function is available since SDL 2.0.6.
*/
extern DECLSPEC int SDLCALL SDL_GameControllerNumMappings(void);
@@ -206,6 +210,8 @@ extern DECLSPEC int SDLCALL SDL_GameControllerNumMappings(void);
*
* \returns the mapping string. Must be freed with SDL_free(). Returns NULL if
* the index
(Patch may be truncated, please check the link at the top of this post.)