Sync SDL3 header -> wiki

SDL3/SDL_isinf.md

@@ -0,0 +1,40 @@
+###### (This is the documentation for SDL3, which is under heavy development and the API is changing! [SDL2](https://wiki.libsdl.org/SDL2/) is the current stable version!)
+# SDL_isinf
+
+Return whether the value is infinity.
+
+## Header File
+
+Defined in [<SDL3/SDL_stdinc.h>](https://github.com/libsdl-org/SDL/blob/main/include/SDL3/SDL_stdinc.h)
+
+## Syntax
+
+```c
+int SDL_isinf(double x);
+```
+
+## Function Parameters
+
+|        |       |                                        |
+| ------ | ----- | -------------------------------------- |
+| double | **x** | double-precision floating point value. |
+
+## Return Value
+
+(int) Returns non-zero if the value is infinity, 0 otherwise.
+
+## Thread Safety
+
+It is safe to call this function from any thread.
+
+## Version
+
+This function is available since SDL 3.0.0.
+
+## See Also
+
+- [SDL_isinff](SDL_isinff)
+
+----
+[CategoryAPI](CategoryAPI), [CategoryAPIFunction](CategoryAPIFunction), [CategoryStdinc](CategoryStdinc)
+

SDL3/SDL_isinff.md

@@ -0,0 +1,40 @@
+###### (This is the documentation for SDL3, which is under heavy development and the API is changing! [SDL2](https://wiki.libsdl.org/SDL2/) is the current stable version!)
+# SDL_isinff
+
+Return whether the value is infinity.
+
+## Header File
+
+Defined in [<SDL3/SDL_stdinc.h>](https://github.com/libsdl-org/SDL/blob/main/include/SDL3/SDL_stdinc.h)
+
+## Syntax
+
+```c
+int SDL_isinff(float x);
+```
+
+## Function Parameters
+
+|       |       |                       |
+| ----- | ----- | --------------------- |
+| float | **x** | floating point value. |
+
+## Return Value
+
+(int) Returns non-zero if the value is infinity, 0 otherwise.
+
+## Thread Safety
+
+It is safe to call this function from any thread.
+
+## Version
+
+This function is available since SDL 3.0.0.
+
+## See Also
+
+- [SDL_isinf](SDL_isinf)
+
+----
+[CategoryAPI](CategoryAPI), [CategoryAPIFunction](CategoryAPIFunction), [CategoryStdinc](CategoryStdinc)
+

SDL3/SDL_isnan.md

@@ -0,0 +1,40 @@
+###### (This is the documentation for SDL3, which is under heavy development and the API is changing! [SDL2](https://wiki.libsdl.org/SDL2/) is the current stable version!)
+# SDL_isnan
+
+Return whether the value is NaN.
+
+## Header File
+
+Defined in [<SDL3/SDL_stdinc.h>](https://github.com/libsdl-org/SDL/blob/main/include/SDL3/SDL_stdinc.h)
+
+## Syntax
+
+```c
+int SDL_isnan(double x);
+```
+
+## Function Parameters
+
+|        |       |                                        |
+| ------ | ----- | -------------------------------------- |
+| double | **x** | double-precision floating point value. |
+
+## Return Value
+
+(int) Returns non-zero if the value is NaN, 0 otherwise.
+
+## Thread Safety
+
+It is safe to call this function from any thread.
+
+## Version
+
+This function is available since SDL 3.0.0.
+
+## See Also
+
+- [SDL_isnanf](SDL_isnanf)
+
+----
+[CategoryAPI](CategoryAPI), [CategoryAPIFunction](CategoryAPIFunction), [CategoryStdinc](CategoryStdinc)
+

SDL3/SDL_isnanf.md

@@ -0,0 +1,40 @@
+###### (This is the documentation for SDL3, which is under heavy development and the API is changing! [SDL2](https://wiki.libsdl.org/SDL2/) is the current stable version!)
+# SDL_isnanf
+
+Return whether the value is NaN.
+
+## Header File
+
+Defined in [<SDL3/SDL_stdinc.h>](https://github.com/libsdl-org/SDL/blob/main/include/SDL3/SDL_stdinc.h)
+
+## Syntax
+
+```c
+int SDL_isnanf(float x);
+```
+
+## Function Parameters
+
+|       |       |                       |
+| ----- | ----- | --------------------- |
+| float | **x** | floating point value. |
+
+## Return Value
+
+(int) Returns non-zero if the value is NaN, 0 otherwise.
+
+## Thread Safety
+
+It is safe to call this function from any thread.
+
+## Version
+
+This function is available since SDL 3.0.0.
+
+## See Also
+
+- [SDL_isnan](SDL_isnan)
+
+----
+[CategoryAPI](CategoryAPI), [CategoryAPIFunction](CategoryAPIFunction), [CategoryStdinc](CategoryStdinc)
+

SDL3/SDL_rand.md

@@ -1,7 +1,7 @@
 ###### (This is the documentation for SDL3, which is under heavy development and the API is changing! [SDL2](https://wiki.libsdl.org/SDL2/) is the current stable version!)
 # SDL_rand
 
-Get 32 pseudo-random bits.
+Generate a pseudo-random number less than n for positive n
 
 ## Header File
 
@@ -10,18 +10,30 @@ Defined in [<SDL3/SDL_stdinc.h>](https://github.com/libsdl-org/SDL/blob/main/inc
 ## Syntax
 
 ```c
-Uint32 SDL_rand(void);
+Sint32 SDL_rand(Sint32 n);
 ```
 
+## Function Parameters
+
+|        |       |                                                      |
+| ------ | ----- | ---------------------------------------------------- |
+| Sint32 | **n** | the number of possible outcomes. n must be positive. |
+
 ## Return Value
 
-(Uint32) Returns a random value in the range of
-[0-[SDL_MAX_UINT32](SDL_MAX_UINT32)].
+(Sint32) Returns a random value in the range of [0 .. n-1].
 
 ## Remarks
 
-You likely want to use [SDL_rand_n](SDL_rand_n)() to get a psuedo-randum
-number instead.
+The method used is faster and of better quality than `rand() % n`. Odds are
+roughly 99.9% even for n = 1 million. Evenness is better for smaller n, and
+much worse as n gets bigger.
+
+Example: to simulate a d6 use `SDL_rand(6) + 1` The +1 converts 0..5 to
+1..6
+
+If you want to generate a pseudo-random number in the full range of Sint32,
+you should use: (Sint32)[SDL_rand_bits](SDL_rand_bits)()
 
 If you want reproducible output, be sure to initialize with
 [SDL_srand](SDL_srand)() first.
@@ -43,8 +55,7 @@ This function is available since SDL 3.0.0.
 ## See Also
 
 - [SDL_srand](SDL_srand)
-- [SDL_rand_n](SDL_rand_n)
-- [SDL_rand_float](SDL_rand_float)
+- [SDL_randf](SDL_randf)
 
 ----
 [CategoryAPI](CategoryAPI), [CategoryAPIFunction](CategoryAPIFunction), [CategoryStdinc](CategoryStdinc)

SDL3/SDL_rand_bits.md

@@ -1,7 +1,7 @@
 ###### (This is the documentation for SDL3, which is under heavy development and the API is changing! [SDL2](https://wiki.libsdl.org/SDL2/) is the current stable version!)
 # SDL_rand_bits
 
-Generates 32 pseudo-random bits.
+Generate 32 pseudo-random bits.
 
 ## Header File
 
@@ -20,11 +20,8 @@ Uint32 SDL_rand_bits(void);
 
 ## Remarks
 
-You likely want to use [SDL_rand_n](SDL_rand_n)() to get a psuedo-randum
-number instead.
-
-If you want reproducible output, be sure to initialize with
-[SDL_srand](SDL_srand)() first.
+You likely want to use [SDL_rand](SDL_rand)() to get a psuedo-random number
+instead.
 
 There are no guarantees as to the quality of the random sequence produced,
 and this should not be used for security (cryptography, passwords) or where
@@ -42,9 +39,9 @@ This function is available since SDL 3.0.0.
 
 ## See Also
 
+- [SDL_rand](SDL_rand)
+- [SDL_randf](SDL_randf)
 - [SDL_srand](SDL_srand)
-- [SDL_rand_n](SDL_rand_n)
-- [SDL_rand_float](SDL_rand_float)
 
 ----
 [CategoryAPI](CategoryAPI), [CategoryAPIFunction](CategoryAPIFunction), [CategoryStdinc](CategoryStdinc)

SDL3/SDL_rand_bits_r.md

@@ -0,0 +1,54 @@
+###### (This is the documentation for SDL3, which is under heavy development and the API is changing! [SDL2](https://wiki.libsdl.org/SDL2/) is the current stable version!)
+# SDL_rand_bits_r
+
+Generate 32 pseudo-random bits.
+
+## Header File
+
+Defined in [<SDL3/SDL_stdinc.h>](https://github.com/libsdl-org/SDL/blob/main/include/SDL3/SDL_stdinc.h)
+
+## Syntax
+
+```c
+Uint32 SDL_rand_bits_r(Uint64 *state);
+```
+
+## Function Parameters
+
+|          |           |                                                                     |
+| -------- | --------- | ------------------------------------------------------------------- |
+| Uint64 * | **state** | a pointer to the current random number state, this may not be NULL. |
+
+## Return Value
+
+(Uint32) Returns a random value in the range of
+[0-[SDL_MAX_UINT32](SDL_MAX_UINT32)].
+
+## Remarks
+
+You likely want to use [SDL_rand_r](SDL_rand_r)() to get a psuedo-random
+number instead.
+
+There are no guarantees as to the quality of the random sequence produced,
+and this should not be used for security (cryptography, passwords) or where
+money is on the line (loot-boxes, casinos). There are many random number
+libraries available with different characteristics and you should pick one
+of those to meet any serious needs.
+
+## Thread Safety
+
+This function is thread-safe, as long as the state pointer isn't shared
+between threads.
+
+## Version
+
+This function is available since SDL 3.0.0.
+
+## See Also
+
+- [SDL_rand_r](SDL_rand_r)
+- [SDL_randf_r](SDL_randf_r)
+
+----
+[CategoryAPI](CategoryAPI), [CategoryAPIFunction](CategoryAPIFunction), [CategoryStdinc](CategoryStdinc)
+

SDL3/SDL_rand_r.md

@@ -1,7 +1,7 @@
 ###### (This is the documentation for SDL3, which is under heavy development and the API is changing! [SDL2](https://wiki.libsdl.org/SDL2/) is the current stable version!)
 # SDL_rand_r
 
-Get a pseudo-random number.
+Generate a pseudo-random number less than n for positive n
 
 ## Header File
 
@@ -10,32 +10,42 @@ Defined in [<SDL3/SDL_stdinc.h>](https://github.com/libsdl-org/SDL/blob/main/inc
 ## Syntax
 
 ```c
-Uint32 SDL_rand_r(Uint64 *state);
+Sint32 SDL_rand_r(Uint64 *state, Sint32 n);
 ```
 
 ## Function Parameters
 
-|          |           |                                                                                                                                                                                                                          |
-| -------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Uint64 * | **state** | a pointer to a 64-bit seed value that will be updated with each call to [SDL_rand_r](SDL_rand_r)(). If the value of the seed is 0, it will be initialized with [SDL_GetPerformanceCounter](SDL_GetPerformanceCounter)(). |
+|          |           |                                                                     |
+| -------- | --------- | ------------------------------------------------------------------- |
+| Uint64 * | **state** | a pointer to the current random number state, this may not be NULL. |
+| Sint32   | **n**     | the number of possible outcomes. n must be positive.                |
 
 ## Return Value
 
-(Uint32) Returns a random value in the range of
-[0-[SDL_MAX_UINT32](SDL_MAX_UINT32)], or 0 if state is NULL.
+(Sint32) Returns a random value in the range of [0 .. n-1].
 
 ## Remarks
 
+The method used is faster and of better quality than `rand() % n`. Odds are
+roughly 99.9% even for n = 1 million. Evenness is better for smaller n, and
+much worse as n gets bigger.
+
+Example: to simulate a d6 use `SDL_rand_r(state, 6) + 1` The +1 converts
+0..5 to 1..6
+
+If you want to generate a pseudo-random number in the full range of Sint32,
+you should use: (Sint32)[SDL_rand_bits_r](SDL_rand_bits_r)(state)
+
 There are no guarantees as to the quality of the random sequence produced,
-and this should not be used for cryptography or anything that requires good
-random distribution. There are many random number libraries available with
-different characteristics and you should pick one of those to meet any
-serious needs.
+and this should not be used for security (cryptography, passwords) or where
+money is on the line (loot-boxes, casinos). There are many random number
+libraries available with different characteristics and you should pick one
+of those to meet any serious needs.
 
 ## Thread Safety
 
-This can be called from any thread, however each thread should pass its own
-state pointer.
+This function is thread-safe, as long as the state pointer isn't shared
+between threads.
 
 ## Version
 
@@ -44,6 +54,8 @@ This function is available since SDL 3.0.0.
 ## See Also
 
 - [SDL_rand](SDL_rand)
+- [SDL_rand_bits_r](SDL_rand_bits_r)
+- [SDL_randf_r](SDL_randf_r)
 
 ----
 [CategoryAPI](CategoryAPI), [CategoryAPIFunction](CategoryAPIFunction), [CategoryStdinc](CategoryStdinc)