SDL: Sync SDL3 wiki -> header (98354)

From 983544a53e42ed136d1518c62402dad4c2f1958a Mon Sep 17 00:00:00 2001
From: SDL Wiki Bot <[EMAIL REDACTED]>
Date: Wed, 22 May 2024 00:41:09 +0000
Subject: [PATCH] Sync SDL3 wiki -> header

---
 include/SDL3/SDL_atomic.h  | 14 ++++++++++++++
 include/SDL3/SDL_events.h  |  4 ++++
 include/SDL3/SDL_gamepad.h |  6 ++++++
 include/SDL3/SDL_hints.h   |  3 +++
 include/SDL3/SDL_render.h  |  3 +++
 include/SDL3/SDL_system.h  | 12 ++++++++++++
 include/SDL3/SDL_timer.h   |  2 ++
 7 files changed, 44 insertions(+)

diff --git a/include/SDL3/SDL_atomic.h b/include/SDL3/SDL_atomic.h
index 575391ef0ec52..5bf0cf9aa1e48 100644
--- a/include/SDL3/SDL_atomic.h
+++ b/include/SDL3/SDL_atomic.h
@@ -338,6 +338,8 @@ typedef struct SDL_AtomicInt { int value; } SDL_AtomicInt;
  * \param newval the new value
  * \returns SDL_TRUE if the atomic variable was set, SDL_FALSE otherwise.
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_AtomicCompareAndSwapPointer
@@ -356,6 +358,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AtomicCompareAndSwap(SDL_AtomicInt *a,
  * \param v the desired value
  * \returns the previous value of the atomic variable.
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_AtomicGet
@@ -371,6 +375,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_AtomicSet(SDL_AtomicInt *a, int v);
  * \param a a pointer to an SDL_AtomicInt variable
  * \returns the current value of an atomic variable.
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_AtomicSet
@@ -389,6 +395,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_AtomicGet(SDL_AtomicInt *a);
  * \param v the desired value to add
  * \returns the previous value of the atomic variable.
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_AtomicDecRef
@@ -442,6 +450,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_AtomicAdd(SDL_AtomicInt *a, int v);
  * \param newval the new pointer value
  * \returns SDL_TRUE if the pointer was set, SDL_FALSE otherwise.
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_AtomicCompareAndSwap
@@ -460,6 +470,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AtomicCompareAndSwapPointer(void **a, v
  * \param v the desired pointer value
  * \returns the previous value of the pointer.
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_AtomicCompareAndSwapPointer
@@ -476,6 +488,8 @@ extern SDL_DECLSPEC void* SDLCALL SDL_AtomicSetPtr(void **a, void* v);
  * \param a a pointer to a pointer
  * \returns the current value of a pointer.
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_AtomicCompareAndSwapPointer
diff --git a/include/SDL3/SDL_events.h b/include/SDL3/SDL_events.h
index 41d3684fd6673..7d0a52e286c07 100644
--- a/include/SDL3/SDL_events.h
+++ b/include/SDL3/SDL_events.h
@@ -1273,6 +1273,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetEventFilter(SDL_EventFilter *filter,
  * \returns 0 on success, or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_DelEventWatch
@@ -1361,6 +1363,8 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_RegisterEvents(int numevents);
  * \returns a pointer to the memory allocated or NULL on failure; call
  *          SDL_GetError() for more information.
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  */
 extern SDL_DECLSPEC void * SDLCALL SDL_AllocateEventMemory(size_t size);
diff --git a/include/SDL3/SDL_gamepad.h b/include/SDL3/SDL_gamepad.h
index 9bf6081bab0c8..8f3c04e67b9d2 100644
--- a/include/SDL3/SDL_gamepad.h
+++ b/include/SDL3/SDL_gamepad.h
@@ -303,6 +303,8 @@ typedef struct SDL_GamepadBinding
  * \returns 1 if a new mapping is added, 0 if an existing mapping is updated,
  *          -1 on error; call SDL_GetError() for more information.
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_GetGamepadMapping
@@ -333,6 +335,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMapping(const char *mapping);
  * \returns the number of mappings added or -1 on error; call SDL_GetError()
  *          for more information.
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_AddGamepadMapping
@@ -359,6 +363,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMappingsFromIO(SDL_IOStream *src,
  * \returns the number of mappings added or -1 on error; call SDL_GetError()
  *          for more information.
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_AddGamepadMapping
diff --git a/include/SDL3/SDL_hints.h b/include/SDL3/SDL_hints.h
index 5ea53643efcf1..fb6d41a93e046 100644
--- a/include/SDL3/SDL_hints.h
+++ b/include/SDL3/SDL_hints.h
@@ -3853,6 +3853,9 @@ typedef void (SDLCALL *SDL_HintCallback)(void *userdata, const char *name, const
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
+ * \threadsafety It is **NOT** safe to call this function from two threads at
+ *               once.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_DelHintCallback
diff --git a/include/SDL3/SDL_render.h b/include/SDL3/SDL_render.h
index 4ba090ae74f31..1e5dd593f0782 100644
--- a/include/SDL3/SDL_render.h
+++ b/include/SDL3/SDL_render.h
@@ -2130,6 +2130,9 @@ extern SDL_DECLSPEC void *SDLCALL SDL_GetRenderMetalCommandEncoder(SDL_Renderer
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
+ * \threadsafety It is **NOT** safe to call this function from two threads at
+ *               once.
+ *
  * \since This function is available since SDL 3.0.0.
  */
 extern SDL_DECLSPEC int SDLCALL SDL_AddVulkanRenderSemaphores(SDL_Renderer *renderer, Uint32 wait_stage_mask, Sint64 wait_semaphore, Sint64 signal_semaphore);
diff --git a/include/SDL3/SDL_system.h b/include/SDL3/SDL_system.h
index d9f9109546f09..9e8b145b2646e 100644
--- a/include/SDL3/SDL_system.h
+++ b/include/SDL3/SDL_system.h
@@ -264,6 +264,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_iOSSetEventPump(SDL_bool enabled);
  * \returns a pointer to Java native interface object (JNIEnv) to which the
  *          current thread is attached, or 0 on error.
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_AndroidGetActivity
@@ -286,6 +288,8 @@ extern SDL_DECLSPEC void * SDLCALL SDL_AndroidGetJNIEnv(void);
  * \returns the jobject representing the instance of the Activity class of the
  *          Android application, or NULL on error.
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_AndroidGetJNIEnv
@@ -357,6 +361,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_IsDeXMode(void);
 /**
  * Trigger the Android system back button behavior.
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  */
 extern SDL_DECLSPEC void SDLCALL SDL_AndroidBackButton(void);
@@ -454,6 +460,8 @@ typedef void (SDLCALL *SDL_AndroidRequestPermissionCallback)(void *userdata, con
  *          submitting. The result of the request is only ever reported
  *          through the callback, not this return value.
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  */
 extern SDL_DECLSPEC int SDLCALL SDL_AndroidRequestPermission(const char *permission, SDL_AndroidRequestPermissionCallback cb, void *userdata);
@@ -480,6 +488,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_AndroidRequestPermission(const char *permiss
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  */
 extern SDL_DECLSPEC int SDLCALL SDL_AndroidShowToast(const char* message, int duration, int gravity, int xoffset, int yoffset);
@@ -494,6 +504,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_AndroidShowToast(const char* message, int du
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  */
 extern SDL_DECLSPEC int SDLCALL SDL_AndroidSendMessage(Uint32 command, int param);
diff --git a/include/SDL3/SDL_timer.h b/include/SDL3/SDL_timer.h
index a522857273388..ecaa305c08371 100644
--- a/include/SDL3/SDL_timer.h
+++ b/include/SDL3/SDL_timer.h
@@ -183,6 +183,8 @@ typedef Uint32 SDL_TimerID;
  * \returns a timer ID or 0 if an error occurs; call SDL_GetError() for more
  *          information.
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_RemoveTimer