Sync SDL3 header -> wiki

libsdl-org · Jun 20, 2024 · 900e66f · 900e66f
1 parent 74c3fcb
commit 900e66f
Show file tree

Hide file tree

Showing 4 changed files with 76 additions and 15 deletions.
diff --git a/SDL3/SDL_rand_bits.md b/SDL3/SDL_rand_bits.md
@@ -0,0 +1,51 @@
+###### (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.
+
+## 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(void);
+```
+
+## 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_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.
+
+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
+
+All calls should be made from a single thread
+
+## Version
+
+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)
+
+----
+[CategoryAPI](CategoryAPI), [CategoryAPIFunction](CategoryAPIFunction), [CategoryStdinc](CategoryStdinc)
+
diff --git a/SDL3/SDL_rand_float.md b/SDL3/SDL_rand_float.md
@@ -19,6 +19,9 @@ float SDL_rand_float(void);
 
 ## Remarks
 
+If you want reproducible output, be sure to initialize with
+[SDL_srand](SDL_srand)() first.
+
 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
@@ -35,7 +38,8 @@ This function is available since SDL 3.0.0.
 
 ## See Also
 
-- [SDL_rand](SDL_rand)
+- [SDL_srand](SDL_srand)
+- [SDL_rand_n](SDL_rand_n)
 
 ----
 [CategoryAPI](CategoryAPI), [CategoryAPIFunction](CategoryAPIFunction), [CategoryStdinc](CategoryStdinc)

diff --git a/SDL3/SDL_rand_n.md b/SDL3/SDL_rand_n.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_n
 
-Generates a pseudo-random number less than n
+Generates a pseudo-random number less than n for positive n
 
 ## Header File
 
@@ -10,28 +10,31 @@ Defined in [<SDL3/SDL_stdinc.h>](https://github.com/libsdl-org/SDL/blob/main/inc
 ## Syntax
 
 ```c
-Uint32 SDL_rand_n(Uint32 n);
+Sint32 SDL_rand_n(Sint32 n);
 ```
 
 ## Function Parameters
 
-|        |       |                                |
-| ------ | ----- | ------------------------------ |
-| Uint32 | **n** | the number of possible values. |
+|        |       |                                                      |
+| ------ | ----- | ---------------------------------------------------- |
+| Sint32 | **n** | the number of possible outcomes. n must be positive. |
 
 ## Return Value
 
-(Uint32) Returns a random value in the range of [0 .. n-1].
+(Sint32) Returns a random value in the range of [0 .. n-1].
 
 ## Remarks
 
-The method used is faster and of better quality than `SDL_rand() % n`.
-However just like with `SDL_rand() % n`, bias increases with larger n. Odds
-are better than 99.9% even for n under 1 million.
+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_n(6) + 1` The +1 converts 0..5 to
 1..6
 
+If you want reproducible output, be sure to initialize with
+[SDL_srand](SDL_srand)() first.
+
 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
@@ -48,7 +51,8 @@ This function is available since SDL 3.0.0.
 
 ## See Also
 
-- [SDL_rand](SDL_rand)
+- [SDL_srand](SDL_srand)
+- [SDL_rand_float](SDL_rand_float)
 
 ----
 [CategoryAPI](CategoryAPI), [CategoryAPIFunction](CategoryAPIFunction), [CategoryStdinc](CategoryStdinc)

diff --git a/SDL3/SDL_srand.md b/SDL3/SDL_srand.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_srand
 
-Seed the pseudo-random number generator.
+Seeds the pseudo-random number generator.
 
 ## Header File
 
@@ -21,20 +21,22 @@ void SDL_srand(Uint64 seed);
 
 ## Remarks
 
-Reusing the seed number will cause [SDL_rand](SDL_rand)() to repeat the
+Reusing the seed number will cause [SDL_rand_](SDL_rand_)*() to repeat the
 same stream of 'random' numbers.
 
 ## Thread Safety
 
-This should be called on the same thread that calls [SDL_rand](SDL_rand)()
+This should be called on the same thread that calls [SDL_rand](SDL_rand)*()
 
 ## Version
 
 This function is available since SDL 3.0.0.
 
 ## See Also
 
-- [SDL_rand](SDL_rand)
+- [SDL_rand_n](SDL_rand_n)
+- [SDL_rand_float](SDL_rand_float)
+- [SDL_rand_bits](SDL_rand_bits)
 
 ----
 [CategoryAPI](CategoryAPI), [CategoryAPIFunction](CategoryAPIFunction), [CategoryStdinc](CategoryStdinc)