From 983544a53e42ed136d1518c62402dad4c2f1958a Mon Sep 17 00:00:00 2001 From: SDL Wiki Bot 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 575391ef0..5bf0cf9aa 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 41d3684fd..7d0a52e28 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 9bf6081ba..8f3c04e67 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 5ea53643e..fb6d41a93 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 4ba090ae7..1e5dd593f 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 d9f910954..9e8b145b2 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 a52285727..ecaa305c0 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