Sync SDL3 wiki -> header

2024-05-22 00:41:09 +00:00 · 2024-05-22 00:41:09 +00:00 · 983544a53e
parent 95aa9a79a9
commit 983544a53e
7 changed files with 44 additions and 0 deletions
--- 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
--- 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);
--- 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
--- 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
--- 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);
--- 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);
--- 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