From c168ccc3c34a9e745dedbfed163ea2ae6d9c6da4 Mon Sep 17 00:00:00 2001
From: SDL Wiki Bot <icculus-sdlwikibot@icculus.org>
Date: Mon, 27 May 2024 02:00:01 +0000
Subject: [PATCH] Sync SDL3 wiki -> header

---
 include/SDL3/SDL_mutex.h   |  8 ++++
 include/SDL3/SDL_stdinc.h  | 86 ++++++++++++++++++++++++++++++++++++++
 include/SDL3/SDL_surface.h | 16 +++++++
 3 files changed, 110 insertions(+)

diff --git a/include/SDL3/SDL_mutex.h b/include/SDL3/SDL_mutex.h
index 485b8fe193..5723d39948 100644
--- a/include/SDL3/SDL_mutex.h
+++ b/include/SDL3/SDL_mutex.h
@@ -714,6 +714,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyCondition(SDL_Condition *cond);
  * \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_BroadcastCondition
@@ -729,6 +731,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SignalCondition(SDL_Condition *cond);
  * \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_SignalCondition
@@ -757,6 +761,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_BroadcastCondition(SDL_Condition *cond);
  * \returns 0 when it is signaled 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_BroadcastCondition
@@ -786,6 +792,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_WaitCondition(SDL_Condition *cond, SDL_Mutex
  *          the condition is not signaled in the allotted time, 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_BroadcastCondition
diff --git a/include/SDL3/SDL_stdinc.h b/include/SDL3/SDL_stdinc.h
index b9f7bfb9e3..97ed793c3b 100644
--- a/include/SDL3/SDL_stdinc.h
+++ b/include/SDL3/SDL_stdinc.h
@@ -1262,6 +1262,8 @@ extern SDL_DECLSPEC double SDLCALL SDL_acos(double x);
  * \param x floating point value.
  * \returns arc cosine of `x`, in radians
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_acos
@@ -1290,6 +1292,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_acosf(float x);
  * \param x floating point value.
  * \returns arc sine of `x`, in radians.
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_asinf
@@ -1318,6 +1322,8 @@ extern SDL_DECLSPEC double SDLCALL SDL_asin(double x);
  * \param x floating point value.
  * \returns arc sine of `x`, in radians.
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_asin
@@ -1348,6 +1354,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_asinf(float x);
  * \param x floating point value.
  * \returns arc tangent of of `x` in radians, or 0 if `x = 0`.
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_atanf
@@ -1378,6 +1386,8 @@ extern SDL_DECLSPEC double SDLCALL SDL_atan(double x);
  * \param x floating point value.
  * \returns arc tangent of of `x` in radians, or 0 if `x = 0`
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_atan
@@ -1412,6 +1422,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_atanf(float x);
  * \returns arc tangent of of `y / x` in radians, or, if `x = 0`, either
  *          `-Pi/2`, `0`, or `Pi/2`, depending on the value of `y`.
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_atan2f
@@ -1446,6 +1458,8 @@ extern SDL_DECLSPEC double SDLCALL SDL_atan2(double y, double x);
  * \returns arc tangent of of `y / x` in radians, or, if `x = 0`, either
  *          `-Pi/2`, `0`, or `Pi/2`, depending on the value of `y`.
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_atan2f
@@ -1470,6 +1484,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_atan2f(float y, float x);
  * \param x floating point value
  * \returns the ceiling of `x`
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_ceilf
@@ -1496,6 +1512,8 @@ extern SDL_DECLSPEC double SDLCALL SDL_ceil(double x);
  * \param x floating point value
  * \returns the ceiling of `x`
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_ceil
@@ -1522,6 +1540,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_ceilf(float x);
  * \param y floating point value to use as the sign
  * \returns the floating point value with the sign of y and the magnitude of x
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_copysignf
@@ -1545,6 +1565,8 @@ extern SDL_DECLSPEC double SDLCALL SDL_copysign(double x, double y);
  * \param y floating point value to use as the sign
  * \returns the floating point value with the sign of y and the magnitude of x
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_copysignf
@@ -1570,6 +1592,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_copysignf(float x, float y);
  * \param x floating point value, in radians
  * \returns cosine of `x`
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_cosf
@@ -1596,6 +1620,8 @@ extern SDL_DECLSPEC double SDLCALL SDL_cos(double x);
  * \param x floating point value, in radians
  * \returns cosine of `x`
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_cos
@@ -1627,6 +1653,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_cosf(float x);
  * \param x floating point value
  * \returns value of `e^x`
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_expf
@@ -1657,6 +1685,8 @@ extern SDL_DECLSPEC double SDLCALL SDL_exp(double x);
  * \param x floating point value
  * \returns value of `e^x`
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_exp
@@ -1677,6 +1707,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_expf(float x);
  * \param x floating point value to use as the magnitude
  * \returns the absolute value of `x`
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_fabsf
@@ -1696,6 +1728,8 @@ extern SDL_DECLSPEC double SDLCALL SDL_fabs(double x);
  * \param x floating point value to use as the magnitude
  * \returns the absolute value of `x`
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_fabs
@@ -1718,6 +1752,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_fabsf(float x);
  * \param x floating point value
  * \returns the floor of `x`
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_floorf
@@ -1744,6 +1780,8 @@ extern SDL_DECLSPEC double SDLCALL SDL_floor(double x);
  * \param x floating point value
  * \returns the floor of `x`
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_floor
@@ -1770,6 +1808,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_floorf(float x);
  * \param x floating point value
  * \returns `x` truncated to an integer
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_truncf
@@ -1797,6 +1837,8 @@ extern SDL_DECLSPEC double SDLCALL SDL_trunc(double x);
  * \param x floating point value
  * \returns `x` truncated to an integer
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_trunc
@@ -1824,6 +1866,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_truncf(float x);
  * \param y the denominator. Must not be 0.
  * \returns the remainder of `x / y`
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_fmodf
@@ -1852,6 +1896,8 @@ extern SDL_DECLSPEC double SDLCALL SDL_fmod(double x, double y);
  * \param y the denominator. Must not be 0.
  * \returns the remainder of `x / y`
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_fmod
@@ -1884,6 +1930,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_fmodf(float x, float y);
  * \param x floating point value. Must be greater than 0.
  * \returns the natural logarithm of `x`
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_logf
@@ -1912,6 +1960,8 @@ extern SDL_DECLSPEC double SDLCALL SDL_log(double x);
  * \param x floating point value. Must be greater than 0.
  * \returns the natural logarithm of `x`
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_log
@@ -1939,6 +1989,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_logf(float x);
  * \param x floating point value. Must be greater than 0.
  * \returns the logarithm of `x`
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_log10f
@@ -1967,6 +2019,8 @@ extern SDL_DECLSPEC double SDLCALL SDL_log10(double x);
  * \param x floating point value. Must be greater than 0.
  * \returns the logarithm of `x`
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_log10
@@ -1985,6 +2039,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_log10f(float x);
  * \param y output pointer to store the integer part of `x`
  * \returns the fractional part of `x`
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_modff
@@ -2003,6 +2059,8 @@ extern SDL_DECLSPEC double SDLCALL SDL_modf(double x, double *y);
  * \param y output pointer to store the integer part of `x`
  * \returns the fractional part of `x`
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_modf
@@ -2033,6 +2091,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_modff(float x, float *y);
  * \param y the exponent
  * \returns `x` raised to the power `y`
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_powf
@@ -2063,6 +2123,8 @@ extern SDL_DECLSPEC double SDLCALL SDL_pow(double x, double y);
  * \param y the exponent
  * \returns `x` raised to the power `y`
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_pow
@@ -2088,6 +2150,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_powf(float x, float y);
  * \param x floating point value
  * \returns the nearest integer to `x`
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_roundf
@@ -2115,6 +2179,8 @@ extern SDL_DECLSPEC double SDLCALL SDL_round(double x);
  * \param x floating point value
  * \returns the nearest integer to `x`
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_round
@@ -2142,6 +2208,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_roundf(float x);
  * \param x floating point value
  * \returns the nearest integer to `x`
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_lroundf
@@ -2169,6 +2237,8 @@ extern SDL_DECLSPEC long SDLCALL SDL_lround(double x);
  * \param x floating point value
  * \returns the nearest integer to `x`
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_lround
@@ -2195,6 +2265,8 @@ extern SDL_DECLSPEC long SDLCALL SDL_lroundf(float x);
  * \param n integer exponent
  * \returns `x * 2^n`
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_scalbnf
@@ -2218,6 +2290,8 @@ extern SDL_DECLSPEC double SDLCALL SDL_scalbn(double x, int n);
  * \param n integer exponent
  * \returns `x * 2^n`
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_scalbn
@@ -2243,6 +2317,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_scalbnf(float x, int n);
  * \param x floating point value, in radians
  * \returns sine of `x`
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_sinf
@@ -2269,6 +2345,8 @@ extern SDL_DECLSPEC double SDLCALL SDL_sin(double x);
  * \param x floating point value, in radians
  * \returns sine of `x`
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_sin
@@ -2295,6 +2373,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_sinf(float x);
  * \param x floating point value. Must be greater than or equal to 0.
  * \returns square root of `x`
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_sqrtf
@@ -2319,6 +2399,8 @@ extern SDL_DECLSPEC double SDLCALL SDL_sqrt(double x);
  * \param x floating point value. Must be greater than or equal to 0.
  * \returns square root of `x`
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_sqrt
@@ -2343,6 +2425,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_sqrtf(float x);
  * \param x floating point value, in radians
  * \returns tangent of `x`
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_tanf
@@ -2371,6 +2455,8 @@ extern SDL_DECLSPEC double SDLCALL SDL_tan(double x);
  * \param x floating point value, in radians
  * \returns tangent of `x`
  *
+ * \threadsafety It is safe to call this function from any thread.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_tan
diff --git a/include/SDL3/SDL_surface.h b/include/SDL3/SDL_surface.h
index 45fe3167cf..9e95bf3df1 100644
--- a/include/SDL3/SDL_surface.h
+++ b/include/SDL3/SDL_surface.h
@@ -924,6 +924,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_FillSurfaceRects(SDL_Surface *dst, const SDL
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
+ * \threadsafety The same destination surface should not be used from two
+ *               threads at once. It is safe to use the same source surface
+ *               from multiple threads.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_BlitSurfaceScaled
@@ -945,6 +949,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_BlitSurface(SDL_Surface *src, const SDL_Rect
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
+ * \threadsafety The same destination surface should not be used from two
+ *               threads at once. It is safe to use the same source surface
+ *               from multiple threads.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_BlitSurface
@@ -988,6 +996,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_SoftStretch(SDL_Surface *src, const SDL_Rect
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
+ * \threadsafety The same destination surface should not be used from two
+ *               threads at once. It is safe to use the same source surface
+ *               from multiple threads.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_BlitSurface
@@ -1010,6 +1022,10 @@ extern SDL_DECLSPEC int SDLCALL SDL_BlitSurfaceScaled(SDL_Surface *src, const SD
  * \returns 0 on success or a negative error code on failure; call
  *          SDL_GetError() for more information.
  *
+ * \threadsafety The same destination surface should not be used from two
+ *               threads at once. It is safe to use the same source surface
+ *               from multiple threads.
+ *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_BlitSurfaceScaled