From d321e19ee5f6978f58ed9af9f9ccc28234a1a10e Mon Sep 17 00:00:00 2001
From: David Gow <david@ingeniumdigital.com>
Date: Sun, 4 Feb 2024 13:05:25 +0800
Subject: [PATCH] stdinc: Document maths functions

SDL_stdinc.h has a documentation comment for SDL_acos(), but nothing else. Expand on
that comment, and add comments for the remaining maths functions.
---
 include/SDL3/SDL_stdinc.h | 1071 ++++++++++++++++++++++++++++++++++++-
 1 file changed, 1068 insertions(+), 3 deletions(-)

diff --git a/include/SDL3/SDL_stdinc.h b/include/SDL3/SDL_stdinc.h
index b7a406a52..338b27128 100644
--- a/include/SDL3/SDL_stdinc.h
+++ b/include/SDL3/SDL_stdinc.h
@@ -1151,7 +1151,7 @@ extern DECLSPEC int SDLCALL SDL_vasprintf(char **strp, SDL_PRINTF_FORMAT_STRING
 #endif
 
 /**
- * Use this function to compute arc cosine of `x`.
+ * Compute the arc cosine of `x`.
  *
  * The definition of `y = acos(x)` is `x = cos(y)`.
  *
@@ -1159,56 +1159,1121 @@ extern DECLSPEC int SDLCALL SDL_vasprintf(char **strp, SDL_PRINTF_FORMAT_STRING
  *
  * Range: `0 <= y <= Pi`
  *
- * \param x floating point value, in radians.
- * \returns arc cosine of `x`.
+ * This function operates on double-precision floating point values, use
+ * SDL_acosf for single-precision floats.
+ *
+ * This function may use a different approximation across different versions,
+ * platforms and configurations. i.e, it can return a different value given
+ * the same input on different machines or operating systems, or if SDL is
+ * updated.
+ *
+ * \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_acosf
+ * \sa SDL_asin
+ * \sa SDL_cos
  */
 extern DECLSPEC double SDLCALL SDL_acos(double x);
+/**
+ * Compute the arc cosine of `x`.
+ *
+ * The definition of `y = acos(x)` is `x = cos(y)`.
+ *
+ * Domain: `-1 <= x <= 1`
+ *
+ * Range: `0 <= y <= Pi`
+ *
+ * This function operates on single-precision floating point values, use
+ * SDL_acos for double-precision floats.
+ *
+ * This function may use a different approximation across different versions,
+ * platforms and configurations. i.e, it can return a different value given
+ * the same input on different machines or operating systems, or if SDL is
+ * updated.
+ *
+ * \param x floating point value.
+ * \returns arc cosine of `x`, in radians
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_acos
+ * \sa SDL_asinf
+ * \sa SDL_cosf
+ */
 extern DECLSPEC float SDLCALL SDL_acosf(float x);
+/**
+ * Compute the arc sine of `x`.
+ *
+ * The definition of `y = asin(x)` is `x = sin(y)`.
+ *
+ * Domain: `-1 <= x <= 1`
+ *
+ * Range: `-Pi/2 <= y <= Pi/2`
+ *
+ * This function operates on double-precision floating point values, use
+ * SDL_asinf for single-precision floats.
+ *
+ * This function may use a different approximation across different versions,
+ * platforms and configurations. i.e, it can return a different value given
+ * the same input on different machines or operating systems, or if SDL is
+ * updated.
+ *
+ * \param x floating point value.
+ * \returns arc sine of `x`, in radians.
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_asinf
+ * \sa SDL_acos
+ * \sa SDL_sin
+ */
 extern DECLSPEC double SDLCALL SDL_asin(double x);
+/**
+ * Compute the arc sine of `x`.
+ *
+ * The definition of `y = asin(x)` is `x = sin(y)`.
+ *
+ * Domain: `-1 <= x <= 1`
+ *
+ * Range: `-Pi/2 <= y <= Pi/2`
+ *
+ * This function operates on single-precision floating point values, use
+ * SDL_asin for double-precision floats.
+ *
+ * This function may use a different approximation across different versions,
+ * platforms and configurations. i.e, it can return a different value given
+ * the same input on different machines or operating systems, or if SDL is
+ * updated.
+ *
+ * \param x floating point value.
+ * \returns arc sine of `x`, in radians.
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_asin
+ * \sa SDL_acosf
+ * \sa SDL_sinf
+ */
 extern DECLSPEC float SDLCALL SDL_asinf(float x);
+/**
+ * Compute the arc tangent of `x`.
+ *
+ * The definition of `y = atan(x)` is `x = tan(y)`.
+ *
+ * Domain: `-INF <= x <= INF`
+ *
+ * Range: `-Pi/2 <= y <= Pi/2`
+ *
+ * This function operates on double-precision floating point values, use
+ * SDL_atanf for single-precision floats.
+ *
+ * To calculate the arc tangent of y / x, use SDL_atan2.
+ *
+ * This function may use a different approximation across different versions,
+ * platforms and configurations. i.e, it can return a different value given
+ * the same input on different machines or operating systems, or if SDL is
+ * updated.
+ *
+ * \param x floating point value.
+ * \returns arc tangent of of `x` in radians, or 0 if `x = 0`.
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_atanf
+ * \sa SDL_atan2
+ * \sa SDL_tan
+ */
 extern DECLSPEC double SDLCALL SDL_atan(double x);
+/**
+ * Compute the arc tangent of `x`.
+ *
+ * The definition of `y = atan(x)` is `x = tan(y)`.
+ *
+ * Domain: `-INF <= x <= INF`
+ *
+ * Range: `-Pi/2 <= y <= Pi/2`
+ *
+ * This function operates on single-precision floating point values, use
+ * SDL_atan for dboule-precision floats.
+ *
+ * To calculate the arc tangent of y / x, use SDL_atan2f.
+ *
+ * This function may use a different approximation across different versions,
+ * platforms and configurations. i.e, it can return a different value given
+ * the same input on different machines or operating systems, or if SDL is
+ * updated.
+ *
+ * \param x floating point value.
+ * \returns arc tangent of of `x` in radians, or 0 if `x = 0`
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_atan
+ * \sa SDL_atan2f
+ * \sa SDL_tanf
+ */
 extern DECLSPEC float SDLCALL SDL_atanf(float x);
+/**
+ * Compute the arc tangent of `y / x`, using the signs of x and y to adjust
+ * the result's quadrant.
+ *
+ * The definition of `z = atan2(x, y)` is `y = x tan(z)`, where the quadrant of z
+ * is determined based on the signs of x and y.
+ *
+ * Domain: `-INF <= x <= INF`, `-INF <= y <= INF`
+ *
+ * Range: `-Pi/2 <= y <= Pi/2`
+ *
+ * This function operates on double-precision floating point values, use
+ * SDL_atan2f for single-precision floats.
+ *
+ * To calculate the arc tangent of a single value, use SDL_atan.
+ *
+ * This function may use a different approximation across different versions,
+ * platforms and configurations. i.e, it can return a different value given
+ * the same input on different machines or operating systems, or if SDL is
+ * updated.
+ *
+ * \param x floating point value of the denominator (x coordinate).
+ * \param y floating point value of the numerator (y coordinate)
+ * \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`.
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_atan2f
+ * \sa SDL_atan
+ * \sa SDL_tan
+ */
 extern DECLSPEC double SDLCALL SDL_atan2(double y, double x);
+/**
+ * Compute the arc tangent of `y / x`, using the signs of x and y to adjust
+ * the result's quadrant.
+ *
+ * The definition of `z = atan2(x, y)` is `y = x tan(z)`, where the quadrant of z
+ * is determined based on the signs of x and y.
+ *
+ * Domain: `-INF <= x <= INF`, `-INF <= y <= INF`
+ *
+ * Range: `-Pi/2 <= y <= Pi/2`
+ *
+ * This function operates on single-precision floating point values, use
+ * SDL_atan2 for double-precision floats.
+ *
+ * To calculate the arc tangent of a single value, use SDL_atanf.
+ *
+ * This function may use a different approximation across different versions,
+ * platforms and configurations. i.e, it can return a different value given
+ * the same input on different machines or operating systems, or if SDL is
+ * updated.
+ *
+ * \param x floating point value of the denominator (x coordinate).
+ * \param y floating point value of the numerator (y coordinate)
+ * \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`.
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_atan2f
+ * \sa SDL_atan
+ * \sa SDL_tan
+ */
 extern DECLSPEC float SDLCALL SDL_atan2f(float y, float x);
+/**
+ * Compute the ceiling of `x`.
+ *
+ * The ceiling of `x` is the smallest integer `y` such that `y > x`, i.e `x`
+ * rounded up to the nearest integer.
+ *
+ * Domain: `-INF <= x <= INF`
+ *
+ * Range: `-INF <= y <= INF`, y integer
+ *
+ * This function operates on double-precision floating point values, use
+ * SDL_ceilf for single-precision floats.
+ *
+ * \param x floating point value
+ * \returns the ceiling of `x`
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_ceilf
+ * \sa SDL_floor
+ * \sa SDL_trunc
+ * \sa SDL_round
+ * \sa SDL_lround
+ */
 extern DECLSPEC double SDLCALL SDL_ceil(double x);
+/**
+ * Compute the ceiling of `x`.
+ *
+ * The ceiling of `x` is the smallest integer `y` such that `y > x`, i.e `x`
+ * rounded up to the nearest integer.
+ *
+ * Domain: `-INF <= x <= INF`
+ *
+ * Range: `-INF <= y <= INF`, y integer
+ *
+ * This function operates on single-precision floating point values, use
+ * SDL_ceil for double-precision floats.
+ *
+ * \param x floating point value
+ * \returns the ceiling of `x`
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_ceil
+ * \sa SDL_floorf
+ * \sa SDL_truncf
+ * \sa SDL_roundf
+ * \sa SDL_lroundf
+ */
 extern DECLSPEC float SDLCALL SDL_ceilf(float x);
+/**
+ * Copy the sign of one floating-point value to another.
+ *
+ * The definition of copysign is that ``copysign(x, y) = abs(x) * sign(y)``.
+ *
+ * Domain: `-INF <= x <= INF`, ``-INF <= y <= f``
+ *
+ * Range: `-INF <= z <= INF`
+ *
+ * This function operates on double-precision floating point values, use
+ * SDL_copysignf for single-precision floats.
+ *
+ * \param x floating point value to use as the magnitude
+ * \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
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_copysignf
+ * \sa SDL_fabs
+ */
 extern DECLSPEC double SDLCALL SDL_copysign(double x, double y);
+/**
+ * Copy the sign of one floating-point value to another.
+ *
+ * The definition of copysign is that ``copysign(x, y) = abs(x) * sign(y)``.
+ *
+ * Domain: `-INF <= x <= INF`, ``-INF <= y <= f``
+ *
+ * Range: `-INF <= z <= INF`
+ *
+ * This function operates on single-precision floating point values, use
+ * SDL_copysign for double-precision floats.
+ *
+ * \param x floating point value to use as the magnitude
+ * \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
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_copysignf
+ * \sa SDL_fabsf
+ */
 extern DECLSPEC float SDLCALL SDL_copysignf(float x, float y);
+/**
+ * Compute the cosine of `x`.
+ *
+ * Domain: `-INF <= x <= INF`
+ *
+ * Range: `-1 <= y <= 1`
+ *
+ * This function operates on double-precision floating point values, use
+ * SDL_cosf for single-precision floats.
+ *
+ * This function may use a different approximation across different versions,
+ * platforms and configurations. i.e, it can return a different value given
+ * the same input on different machines or operating systems, or if SDL is
+ * updated.
+ *
+ * \param x floating point value, in radians
+ * \returns cosine of `x`
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_cosf
+ * \sa SDL_acos
+ * \sa SDL_sin
+ */
 extern DECLSPEC double SDLCALL SDL_cos(double x);
+/**
+ * Compute the cosine of `x`.
+ *
+ * Domain: `-INF <= x <= INF`
+ *
+ * Range: `-1 <= y <= 1`
+ *
+ * This function operates on single-precision floating point values, use
+ * SDL_cos for double-precision floats.
+ *
+ * This function may use a different approximation across different versions,
+ * platforms and configurations. i.e, it can return a different value given
+ * the same input on different machines or operating systems, or if SDL is
+ * updated.
+ *
+ * \param x floating point value, in radians
+ * \returns cosine of `x`
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_cos
+ * \sa SDL_acosf
+ * \sa SDL_sinf
+ */
 extern DECLSPEC float SDLCALL SDL_cosf(float x);
+/**
+ * Compute the exponential of `x`.
+ *
+ * The definition of `y = exp(x)` is `y = e^x`, where `e` is the base of the
+ * natural logarithm. The inverse is the natural logarithm, SDL_log.
+ *
+ * Domain: `-INF <= x <= INF`
+ *
+ * Range: `0 <= y <= INF`
+ *
+ * The output will overflow if `exp(x)` is too large to be represented.
+ *
+ * This function operates on double-precision floating point values, use
+ * SDL_expf for single-precision floats.
+ *
+ * This function may use a different approximation across different versions,
+ * platforms and configurations. i.e, it can return a different value given
+ * the same input on different machines or operating systems, or if SDL is
+ * updated.
+ *
+ * \param x floating point value
+ * \returns value of `e^x`
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_expf
+ * \sa SDL_log
+ */
 extern DECLSPEC double SDLCALL SDL_exp(double x);
+/**
+ * Compute the exponential of `x`.
+ *
+ * The definition of `y = exp(x)` is `y = e^x`, where `e` is the base of the
+ * natural logarithm. The inverse is the natural logarithm, SDL_logf.
+ *
+ * Domain: `-INF <= x <= INF`
+ *
+ * Range: `0 <= y <= INF`
+ *
+ * The output will overflow if `exp(x)` is too large to be represented.
+ *
+ * This function operates on single-precision floating point values, use
+ * SDL_exp for double-precision floats.
+ *
+ * This function may use a different approximation across different versions,
+ * platforms and configurations. i.e, it can return a different value given
+ * the same input on different machines or operating systems, or if SDL is
+ * updated.
+ *
+ * \param x floating point value
+ * \returns value of `e^x`
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_exp
+ * \sa SDL_logf
+ */
 extern DECLSPEC float SDLCALL SDL_expf(float x);
+/**
+ * Compute the absolute value of `x`
+ *
+ * Domain: `-INF <= x <= INF`
+ *
+ * Range: `0 <= y <= INF`
+ *
+ * This function operates on double-precision floating point values, use
+ * SDL_copysignf for single-precision floats.
+ *
+ * \param x floating point value to use as the magnitude
+ * \returns the absolute value of `x`
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_fabsf
+ */
 extern DECLSPEC double SDLCALL SDL_fabs(double x);
+/**
+ * Compute the absolute value of `x`
+ *
+ * Domain: `-INF <= x <= INF`
+ *
+ * Range: `0 <= y <= INF`
+ *
+ * This function operates on single-precision floating point values, use
+ * SDL_copysignf for double-precision floats.
+ *
+ * \param x floating point value to use as the magnitude
+ * \returns the absolute value of `x`
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_fabs
+ */
 extern DECLSPEC float SDLCALL SDL_fabsf(float x);
+/**
+ * Compute the floor of `x`.
+ *
+ * The floor of `x` is the largest integer `y` such that `y > x`, i.e `x`
+ * rounded down to the nearest integer.
+ *
+ * Domain: `-INF <= x <= INF`
+ *
+ * Range: `-INF <= y <= INF`, y integer
+ *
+ * This function operates on double-precision floating point values, use
+ * SDL_floorf for single-precision floats.
+ *
+ * \param x floating point value
+ * \returns the floor of `x`
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_floorf
+ * \sa SDL_ceil
+ * \sa SDL_trunc
+ * \sa SDL_round
+ * \sa SDL_lround
+ */
 extern DECLSPEC double SDLCALL SDL_floor(double x);
+/**
+ * Compute the floor of `x`.
+ *
+ * The floor of `x` is the largest integer `y` such that `y > x`, i.e `x`
+ * rounded down to the nearest integer.
+ *
+ * Domain: `-INF <= x <= INF`
+ *
+ * Range: `-INF <= y <= INF`, y integer
+ *
+ * This function operates on single-precision floating point values, use
+ * SDL_floorf for double-precision floats.
+ *
+ * \param x floating point value
+ * \returns the floor of `x`
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_floor
+ * \sa SDL_ceilf
+ * \sa SDL_truncf
+ * \sa SDL_roundf
+ * \sa SDL_lroundf
+ */
 extern DECLSPEC float SDLCALL SDL_floorf(float x);
+/**
+ * Truncate `x` to an integer.
+ *
+ * Rounds `x` to the next closest integer to 0. This is equivalent to
+ * removing the fractional part of `x`, leaving only the integer part.
+ *
+ * Domain: `-INF <= x <= INF`
+ *
+ * Range: `-INF <= y <= INF`, y integer
+ *
+ * This function operates on double-precision floating point values, use
+ * SDL_truncf for single-precision floats.
+ *
+ * \param x floating point value
+ * \returns `x` truncated to an integer
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_truncf
+ * \sa SDL_fmod
+ * \sa SDL_ceil
+ * \sa SDL_floor
+ * \sa SDL_round
+ * \sa SDL_lround
+ */
 extern DECLSPEC double SDLCALL SDL_trunc(double x);
+/**
+ * Truncate `x` to an integer.
+ *
+ * Rounds `x` to the next closest integer to 0. This is equivalent to
+ * removing the fractional part of `x`, leaving only the integer part.
+ *
+ * Domain: `-INF <= x <= INF`
+ *
+ * Range: `-INF <= y <= INF`, y integer
+ *
+ * This function operates on single-precision floating point values, use
+ * SDL_truncf for double-precision floats.
+ *
+ * \param x floating point value
+ * \returns `x` truncated to an integer
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_trunc
+ * \sa SDL_fmodf
+ * \sa SDL_ceilf
+ * \sa SDL_floorf
+ * \sa SDL_roundf
+ * \sa SDL_lroundf
+ */
 extern DECLSPEC float SDLCALL SDL_truncf(float x);
+/**
+ * Return the floating-point remainder of `x / y`
+ *
+ * Divides `x` by `y`, and returns the remainder.
+ *
+ * Domain: `-INF <= x <= INF`, `-INF <= y <= INF`, `y != 0`
+ *
+ * Range: `-y <= z <= y`
+ *
+ * This function operates on double-precision floating point values, use
+ * SDL_fmodf for single-precision floats.
+ *
+ * \param x the numerator
+ * \param y the denominator. Must not be 0.
+ * \returns the remainder of `x / y`
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_fmodf
+ * \sa SDL_modf
+ * \sa SDL_trunc
+ * \sa SDL_ceil
+ * \sa SDL_floor
+ * \sa SDL_round
+ * \sa SDL_lround
+ */
 extern DECLSPEC double SDLCALL SDL_fmod(double x, double y);
+/**
+ * Return the floating-point remainder of `x / y`
+ *
+ * Divides `x` by `y`, and returns the remainder.
+ *
+ * Domain: `-INF <= x <= INF`, `-INF <= y <= INF`, `y != 0`
+ *
+ * Range: `-y <= z <= y`
+ *
+ * This function operates on single-precision floating point values, use
+ * SDL_fmod for single-precision floats.
+ *
+ * \param x the numerator
+ * \param y the denominator. Must not be 0.
+ * \returns the remainder of `x / y`
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_fmod
+ * \sa SDL_truncf
+ * \sa SDL_modff
+ * \sa SDL_ceilf
+ * \sa SDL_floorf
+ * \sa SDL_roundf
+ * \sa SDL_lroundf
+ */
 extern DECLSPEC float SDLCALL SDL_fmodf(float x, float y);
+/**
+ * Compute the natural logarithm of `x`.
+ *
+ * Domain: `0 < x <= INF`
+ *
+ * Range: `-INF <= y <= INF`
+ *
+ * It is an error for `x` to be less than or equal to 0.
+ *
+ * This function operates on double-precision floating point values, use
+ * SDL_logf for single-precision floats.
+ *
+ * This function may use a different approximation across different versions,
+ * platforms and configurations. i.e, it can return a different value given
+ * the same input on different machines or operating systems, or if SDL is
+ * updated.
+ *
+ * \param x floating point value. Must be greater than 0.
+ * \returns the natural logarithm of `x`
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_logf
+ * \sa SDL_log10
+ * \sa SDL_exp
+ */
 extern DECLSPEC double SDLCALL SDL_log(double x);
+/**
+ * Compute the natural logarithm of `x`.
+ *
+ * Domain: `0 < x <= INF`
+ *
+ * Range: `-INF <= y <= INF`
+ *
+ * It is an error for `x` to be less than or equal to 0.
+ *
+ * This function operates on single-precision floating point values, use
+ * SDL_log for double-precision floats.
+ *
+ * This function may use a different approximation across different versions,
+ * platforms and configurations. i.e, it can return a different value given
+ * the same input on different machines or operating systems, or if SDL is
+ * updated.
+ *
+ * \param x floating point value. Must be greater than 0.
+ * \returns the natural logarithm of `x`
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_log
+ * \sa SDL_expf
+ */
 extern DECLSPEC float SDLCALL SDL_logf(float x);
+/**
+ * Compute the base-10 logarithm of `x`.
+ *
+ * Domain: `0 < x <= INF`
+ *
+ * Range: `-INF <= y <= INF`
+ *
+ * It is an error for `x` to be less than or equal to 0.
+ *
+ * This function operates on double-precision floating point values, use
+ * SDL_log10f for single-precision floats.
+ *
+ * This function may use a different approximation across different versions,
+ * platforms and configurations. i.e, it can return a different value given
+ * the same input on different machines or operating systems, or if SDL is
+ * updated.
+ *
+ * \param x floating point value. Must be greater than 0.
+ * \returns the  logarithm of `x`
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_log10f
+ * \sa SDL_log
+ * \sa SDL_pow
+ */
 extern DECLSPEC double SDLCALL SDL_log10(double x);
+/**
+ * Compute the base-10 logarithm of `x`.
+ *
+ * Domain: `0 < x <= INF`
+ *
+ * Range: `-INF <= y <= INF`
+ *
+ * It is an error for `x` to be less than or equal to 0.
+ *
+ * This function operates on single-precision floating point values, use
+ * SDL_log10 for double-precision floats.
+ *
+ * This function may use a different approximation across different versions,
+ * platforms and configurations. i.e, it can return a different value given
+ * the same input on different machines or operating systems, or if SDL is
+ * updated.
+ *
+ * \param x floating point value. Must be greater than 0.
+ * \returns the  logarithm of `x`
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_log10
+ * \sa SDL_logf
+ * \sa SDL_powf
+ */
 extern DECLSPEC float SDLCALL SDL_log10f(float x);
+/**
+ * Split `x` into integer and fractional parts
+ *
+ * This function operates on double-precision floating point values, use
+ * SDL_modff for single-precision floats.
+ *
+ * \param x floating point value
+ * \param y output pointer to store the integer part of `x`
+ * \returns the fractional part of `x`
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_modff
+ * \sa SDL_trunc
+ * \sa SDL_fmod
+ */
 extern DECLSPEC double SDLCALL SDL_modf(double x, double *y);
+/**
+ * Split `x` into integer and fractional parts
+ *
+ * This function operates on single-precision floating point values, use
+ * SDL_modf for double-precision floats.
+ *
+ * \param x floating point value
+ * \param y output pointer to store the integer part of `x`
+ * \returns the fractional part of `x`
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_modf
+ * \sa SDL_truncf
+ * \sa SDL_fmodf
+ */
 extern DECLSPEC float SDLCALL SDL_modff(float x, float *y);
+/**
+ * Raise `x` to the power `y`
+ *
+ * Domain: `-INF <= x <= INF`, `-INF <= y <= INF`
+ *
+ * Range: `-INF <= z <= INF`
+ *
+ * If `y` is the base of the natural logarithm (e), consider using SDL_exp
+ * instead.
+ *
+ * This function operates on double-precision floating point values, use
+ * SDL_powf for single-precision floats.
+ *
+ * This function may use a different approximation across different versions,
+ * platforms and configurations. i.e, it can return a different value given
+ * the same input on different machines or operating systems, or if SDL is
+ * updated.
+ *
+ * \param x the base
+ * \param y the exponent
+ * \returns `x` raised to the power `y`
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_powf
+ * \sa SDL_exp
+ * \sa SDL_log
+ */
 extern DECLSPEC double SDLCALL SDL_pow(double x, double y);
+/**
+ * Raise `x` to the power `y`
+ *
+ * Domain: `-INF <= x <= INF`, `-INF <= y <= INF`
+ *
+ * Range: `-INF <= z <= INF`
+ *
+ * If `y` is the base of the natural logarithm (e), consider using SDL_exp
+ * instead.
+ *
+ * This function operates on single-precision floating point values, use
+ * SDL_powf for double-precision floats.
+ *
+ * This function may use a different approximation across different versions,
+ * platforms and configurations. i.e, it can return a different value given
+ * the same input on different machines or operating systems, or if SDL is
+ * updated.
+ *
+ * \param x the base
+ * \param y the exponent
+ * \returns `x` raised to the power `y`
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_pow
+ * \sa SDL_expf
+ * \sa SDL_logf
+ */
 extern DECLSPEC float SDLCALL SDL_powf(float x, float y);
+/**
+ * Round `x` to the nearest integer.
+ *
+ * Rounds `x` to the nearest integer. Values halfway between integers will be
+ * rounded away from zero.
+ *
+ * Domain: `-INF <= x <= INF`
+ *
+ * Range: `-INF <= y <= INF`, y integer
+ *
+ * This function operates on double-precision floating point values, use
+ * SDL_roundf for single-precision floats. To get the result as an integer
+ * type, use SDL_lround.
+ *
+ * \param x floating point value
+ * \returns the nearest integer to `x`
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_roundf
+ * \sa SDL_lround
+ * \sa SDL_floor
+ * \sa SDL_ceil
+ * \sa SDL_trunc
+ */
 extern DECLSPEC double SDLCALL SDL_round(double x);
+/**
+ * Round `x` to the nearest integer.
+ *
+ * Rounds `x` to the nearest integer. Values halfway between integers will be
+ * rounded away from zero.
+ *
+ * Domain: `-INF <= x <= INF`
+ *
+ * Range: `-INF <= y <= INF`, y integer
+ *
+ * This function operates on double-precision floating point values, use
+ * SDL_roundf for single-precision floats. To get the result as an integer
+ * type, use SDL_lroundf.
+ *
+ * \param x floating point value
+ * \returns the nearest integer to `x`
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_round
+ * \sa SDL_lroundf
+ * \sa SDL_floorf
+ * \sa SDL_ceilf
+ * \sa SDL_truncf
+ */
 extern DECLSPEC float SDLCALL SDL_roundf(float x);
+/**
+ * Round `x` to the nearest integer representable as a long
+ *
+ * Rounds `x` to the nearest integer. Values halfway between integers will be
+ * rounded away from zero.
+ *
+ * Domain: `-INF <= x <= INF`
+ *
+ * Range: `MIN_LONG <= y <= MAX_LONG`
+ *
+ * This function operates on double-precision floating point values, use
+ * SDL_lround for single-precision floats. To get the result as a
+ * floating-point type, use SDL_round.
+ *
+ * \param x floating point value
+ * \returns the nearest integer to `x`
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_lroundf
+ * \sa SDL_round
+ * \sa SDL_floor
+ * \sa SDL_ceil
+ * \sa SDL_trunc
+ */
 extern DECLSPEC long SDLCALL SDL_lround(double x);
+/**
+ * Round `x` to the nearest integer representable as a long
+ *
+ * Rounds `x` to the nearest integer. Values halfway between integers will be
+ * rounded away from zero.
+ *
+ * Domain: `-INF <= x <= INF`
+ *
+ * Range: `MIN_LONG <= y <= MAX_LONG`
+ *
+ * This function operates on single-precision floating point values, use
+ * SDL_lroundf for double-precision floats. To get the result as a
+ * floating-point type, use SDL_roundf,
+ *
+ * \param x floating point value
+ * \returns the nearest integer to `x`
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_lround
+ * \sa SDL_roundf
+ * \sa SDL_floorf
+ * \sa SDL_ceilf
+ * \sa SDL_truncf
+ */
 extern DECLSPEC long SDLCALL SDL_lroundf(float x);
+/**
+ * Scale `x` by an integer power of two.
+ *
+ * Multiplies `x` by the `n`th power of the floating point radix (always 2).
+ *
+ * Domain: `-INF <= x <= INF`, `n` integer
+ *
+ * Range: `-INF <= y <= INF`
+ *
+ * This function operates on double-precision floating point values, use
+ * SDL_scalbnf for single-precision floats.
+ *
+ * \param x floating point value to be scaled
+ * \param n integer exponent
+ * \returns `x * 2^n`
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_scalbnf
+ * \sa SDL_pow
+ */
 extern DECLSPEC double SDLCALL SDL_scalbn(double x, int n);
+/**
+ * Scale `x` by an integer power of two.
+ *
+ * Multiplies `x` by the `n`th power of the floating point radix (always 2).
+ *
+ * Domain: `-INF <= x <= INF`, `n` integer
+ *
+ * Range: `-INF <= y <= INF`
+ *
+ * This function operates on single-precision floating point values, use
+ * SDL_scalbn for double-precision floats.
+ *
+ * \param x floating point value to be scaled
+ * \param n integer exponent
+ * \returns `x * 2^n`
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_scalbn
+ * \sa SDL_powf
+ */
 extern DECLSPEC float SDLCALL SDL_scalbnf(float x, int n);
+/**
+ * Compute the sine of `x`.
+ *
+ * Domain: `-INF <= x <= INF`
+ *
+ * Range: `-1 <= y <= 1`
+ *
+ * This function operates on double-precision floating point values, use
+ * SDL_sinf for single-precision floats.
+ *
+ * This function may use a different approximation across different versions,
+ * platforms and configurations. i.e, it can return a different value given
+ * the same input on different machines or operating systems, or if SDL is
+ * updated.
+ *
+ * \param x floating point value, in radians
+ * \returns sine of `x`
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_sinf
+ * \sa SDL_asin
+ * \sa SDL_cos
+ */
 extern DECLSPEC double SDLCALL SDL_sin(double x);
+/**
+ * Compute the sine of `x`.
+ *
+ * Domain: `-INF <= x <= INF`
+ *
+ * Range: `-1 <= y <= 1`
+ *
+ * This function operates on single-precision floating point values, use
+ * SDL_sinf for double-precision floats.
+ *
+ * This function may use a different approximation across different versions,
+ * platforms and configurations. i.e, it can return a different value given
+ * the same input on different machines or operating systems, or if SDL is
+ * updated.
+ *
+ * \param x floating point value, in radians
+ * \returns sine of `x`
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_sin
+ * \sa SDL_asinf
+ * \sa SDL_cosf
+ */
 extern DECLSPEC float SDLCALL SDL_sinf(float x);
+/**
+ * Compute the square root of `x`.
+ *
+ * Domain: `0 <= x <= INF`
+ *
+ * Range: `0 <= y <= INF`
+ *
+ * This function operates on double-precision floating point values, use
+ * SDL_sqrtf for single-precision floats.
+ *
+ * This function may use a different approximation across different versions,
+ * platforms and configurations. i.e, it can return a different value given
+ * the same input on different machines or operating systems, or if SDL is
+ * updated.
+ *
+ * \param x floating point value. Must be greater than or equal to 0.
+ * \returns square root of `x`
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_sqrtf
+ */
 extern DECLSPEC double SDLCALL SDL_sqrt(double x);
+/**
+ * Compute the square root of `x`.
+ *
+ * Domain: `0 <= x <= INF`
+ *
+ * Range: `0 <= y <= INF`
+ *
+ * This function operates on single-precision floating point values, use
+ * SDL_sqrt for double-precision floats.
+ *
+ * This function may use a different approximation across different versions,
+ * platforms and configurations. i.e, it can return a different value given
+ * the same input on different machines or operating systems, or if SDL is
+ * updated.
+ *
+ * \param x floating point value. Must be greater than or equal to 0.
+ * \returns square root of `x`
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_sqrt
+ */
 extern DECLSPEC float SDLCALL SDL_sqrtf(float x);
+/**
+ * Compute the tangent of `x`.
+ *
+ * Domain: `-INF <= x <= INF`
+ *
+ * Range: `-INF <= y <= INF`
+ *
+ * This function operates on double-precision floating point values, use
+ * SDL_tanf for single-precision floats.
+ *
+ * This function may use a different approximation across different versions,
+ * platforms and configurations. i.e, it can return a different value given
+ * the same input on different machines or operating systems, or if SDL is
+ * updated.
+ *
+ * \param x floating point value, in radians
+ * \returns tangent of `x`
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_tanf
+ * \sa SDL_sin
+ * \sa SDL_cos
+ * \sa SDL_atan
+ * \sa SDL_atan2
+ */
 extern DECLSPEC double SDLCALL SDL_tan(double x);
+/**
+ * Compute the tangent of `x`.
+ *
+ * Domain: `-INF <= x <= INF`
+ *
+ * Range: `-INF <= y <= INF`
+ *
+ * This function operates on single-precision floating point values, use
+ * SDL_tanf for double-precision floats.
+ *
+ * This function may use a different approximation across different versions,
+ * platforms and configurations. i.e, it can return a different value given
+ * the same input on different machines or operating systems, or if SDL is
+ * updated.
+ *
+ * \param x floating point value, in radians
+ * \returns tangent of `x`
+ *
+ * \since This function is available since SDL 3.0.0.
+ *
+ * \sa SDL_tan
+ * \sa SDL_sinf
+ * \sa SDL_cosf
+ * \sa SDL_atanf
+ * \sa SDL_atan2f
+ */
 extern DECLSPEC float SDLCALL SDL_tanf(float x);
 
 /* The SDL implementation of iconv() returns these error codes */