Renamed SDL_rand() to SDL_rand_bits() and updated tests

Author: JKaniarz

include/SDL3/SDL_stdinc.h

@@ -1260,25 +1260,27 @@ extern SDL_DECLSPEC int SDLCALL SDL_asprintf(char **strp, SDL_PRINTF_FORMAT_STRI
 extern SDL_DECLSPEC int SDLCALL SDL_vasprintf(char **strp, SDL_PRINTF_FORMAT_STRING const char *fmt, va_list ap) SDL_PRINTF_VARARG_FUNCV(2);
 
 /**
- * Seed the pseudo-random number generator.
+ * Seeds the pseudo-random number generator.
  *
- * Reusing the seed number will cause SDL_rand() to repeat the same stream of
- * 'random' numbers.
+ * Reusing the seed number will cause SDL_rand_*()  to repeat the same stream
+ * of 'random' numbers.
  *
  * \param seed the value to use as a random number seed, or 0 to use
  *             SDL_GetPerformanceCounter().
  *
  * \threadsafety This should be called on the same thread that calls
- *               SDL_rand()
+ *               SDL_rand*()
  *
  * \since This function is available since SDL 3.0.0.
  *
- * \sa SDL_rand
+ * \sa SDL_rand_n
+ * \sa SDL_rand_float
+ * \sa SDL_rand_bits
  */
 extern SDL_DECLSPEC void SDLCALL SDL_srand(Uint64 seed);
 
 /**
- * Get 32 pseudo-random bits.
+ * Generates 32 pseudo-random bits.
  *
  * You likely want to use SDL_rand_n() to get a psuedo-randum number instead.
  *
@@ -1301,38 +1303,44 @@ extern SDL_DECLSPEC void SDLCALL SDL_srand(Uint64 seed);
  * \sa SDL_rand_n
  * \sa SDL_rand_float
  */
-extern SDL_DECLSPEC Uint32 SDLCALL SDL_rand(void);
+extern SDL_DECLSPEC Uint32 SDLCALL SDL_rand_bits(void);
 
 /**
- * Generates a pseudo-random number less than n
+ * Generates a pseudo-random number less than n for positive n
  *
- * 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() 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.
  *
- * \param n the number of possible values.
- * \returns a random value in the range of [0 .. n-1].
+ * \param n the number of possible outcomes. n must be positive.
+ *
+ * \returns a random value in the range of [0 ..  n-1]
  *
  * \threadsafety All calls should be made from a single thread
  *
  * \since This function is available since SDL 3.0.0.
  *
- * \sa SDL_rand
+ * \sa SDL_srand
+ * \sa SDL_rand_float
  */
-extern SDL_DECLSPEC Uint32 SDLCALL SDL_rand_n(Uint32 n);
+extern SDL_DECLSPEC Sint32 SDLCALL SDL_rand_n(Sint32 n);
 
 /**
  * Generates a uniform pseudo-random floating point number less than 1.0
  *
+ * If you want reproducible output, be sure to initialize with 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
@@ -1345,7 +1353,8 @@ extern SDL_DECLSPEC Uint32 SDLCALL SDL_rand_n(Uint32 n);
  *
  * \since This function is available since SDL 3.0.0.
  *
- * \sa SDL_rand
+ * \sa SDL_srand
+ * \sa SDL_rand_n
  */
 extern SDL_DECLSPEC float SDLCALL SDL_rand_float(void);
 

src/dynapi/SDL_dynapi.sym

@@ -955,8 +955,9 @@ SDL3_0.0.0 {
     SDL_powf;
     SDL_qsort;
     SDL_qsort_r;
-    SDL_rand;
-    SDL_rand_r;
+    SDL_rand_bits;
+    SDL_rand_float;
+    SDL_rand_n;  
     SDL_realloc;
     SDL_round;
     SDL_roundf;

src/dynapi/SDL_dynapi_overrides.h

@@ -980,7 +980,7 @@
 #define SDL_powf SDL_powf_REAL
 #define SDL_qsort SDL_qsort_REAL
 #define SDL_qsort_r SDL_qsort_r_REAL
-#define SDL_rand SDL_rand_REAL
+#define SDL_rand_bits SDL_rand_bits_REAL
 #define SDL_rand_float SDL_rand_float_REAL
 #define SDL_rand_n SDL_rand_n_REAL
 #define SDL_realloc SDL_realloc_REAL

src/dynapi/SDL_dynapi_procs.h

@@ -989,9 +989,9 @@ SDL_DYNAPI_PROC(double,SDL_pow,(double a, double b),(a,b),return)
 SDL_DYNAPI_PROC(float,SDL_powf,(float a, float b),(a,b),return)
 SDL_DYNAPI_PROC(void,SDL_qsort,(void *a, size_t b, size_t c, SDL_CompareCallback d),(a,b,c,d),)
 SDL_DYNAPI_PROC(void,SDL_qsort_r,(void *a, size_t b, size_t c, SDL_CompareCallback_r d, void *e),(a,b,c,d,e),)
-SDL_DYNAPI_PROC(Uint32,SDL_rand,(void),(),return)
+SDL_DYNAPI_PROC(Uint32,SDL_rand_bits,(void),(),return)
 SDL_DYNAPI_PROC(float,SDL_rand_float,(void),(),return)
-SDL_DYNAPI_PROC(Uint32,SDL_rand_n,(Uint32 a),(a),return)
+SDL_DYNAPI_PROC(Sint32,SDL_rand_n,(Sint32 a),(a),return)
 SDL_DYNAPI_PROC(void*,SDL_realloc,(void *a, size_t b),(a,b),return)
 SDL_DYNAPI_PROC(double,SDL_round,(double a),(a),return)
 SDL_DYNAPI_PROC(float,SDL_roundf,(float a),(a),return)

src/stdlib/SDL_random.c

@@ -34,7 +34,7 @@ void SDL_srand(Uint64 seed)
     SDL_rand_initialized = SDL_TRUE;
 }
 
-Uint32 SDL_rand(void)
+Uint32 SDL_rand_bits(void)
 {
     if(!SDL_rand_initialized) {
         SDL_srand(0);
@@ -61,14 +61,14 @@ Uint32 SDL_rand(void)
     return (Uint32)(SDL_rand_state >> 32);
 }
 
-Uint32 SDL_rand_n(Uint32 n)
+Sint32 SDL_rand_n(Sint32 n)
 {
 	// On 32-bit arch, the compiler will optimize to a single 32-bit multiply
-	Uint64 val = (Uint64)SDL_rand() * n;
-	return (Uint32)(val >> 32);
+	Uint64 val = (Uint64)SDL_rand_bits() * n;
+	return (Sint32)(val >> 32);
 }
 
 float SDL_rand_float(void)
 {
-	return (SDL_rand() >> (32-24)) * 0x1p-24f;
+	return (SDL_rand_bits() >> (32-24)) * 0x1p-24f;
 }

test/checkkeysthreads.c

@@ -206,7 +206,7 @@ static void loop(void)
         default:
             break;
         }
-       SDL_Log("waiting new event\n");
+        SDL_Log("waiting new event\n");
     }
     SDL_Log("exiting event loop\n");
 #ifdef SDL_PLATFORM_EMSCRIPTEN
@@ -227,7 +227,7 @@ static int SDLCALL ping_thread(void *ptr)
         sdlevent.type = SDL_EVENT_KEY_DOWN;
         sdlevent.key.keysym.sym = SDLK_1;
         SDL_PushEvent(&sdlevent);
-        SDL_Delay(1000 + SDL_rand() % 1000);
+        SDL_Delay(1000 + SDL_rand_n(1000));
     }
     return cnt;
 }

test/testdraw.c

@@ -72,8 +72,8 @@ static void DrawPoints(SDL_Renderer *renderer)
         SDL_SetRenderDrawColor(renderer, 255, (Uint8)current_color,
                                (Uint8)current_color, (Uint8)current_alpha);
 
-        x = (float)(SDL_rand() % viewport.w);
-        y = (float)(SDL_rand() % viewport.h);
+        x = (float)SDL_rand_n(viewport.w);
+        y = (float)SDL_rand_n(viewport.h);
         SDL_RenderPoint(renderer, x, y);
     }
 }
@@ -120,10 +120,10 @@ static void DrawLines(SDL_Renderer *renderer)
             SDL_RenderLine(renderer, 0.0f, (float)(viewport.h / 2), (float)(viewport.w - 1), (float)(viewport.h / 2));
             SDL_RenderLine(renderer, (float)(viewport.w / 2), 0.0f, (float)(viewport.w / 2), (float)(viewport.h - 1));
         } else {
-            x1 = (float)((SDL_rand() % (viewport.w * 2)) - viewport.w);
-            x2 = (float)((SDL_rand() % (viewport.w * 2)) - viewport.w);
-            y1 = (float)((SDL_rand() % (viewport.h * 2)) - viewport.h);
-            y2 = (float)((SDL_rand() % (viewport.h * 2)) - viewport.h);
+            x1 = (float)(SDL_rand_n(viewport.w * 2) - viewport.w);
+            x2 = (float)(SDL_rand_n(viewport.w * 2) - viewport.w);
+            y1 = (float)(SDL_rand_n(viewport.h * 2) - viewport.h);
+            y2 = (float)(SDL_rand_n(viewport.h * 2) - viewport.h);
             SDL_RenderLine(renderer, x1, y1, x2, y2);
         }
     }
@@ -165,10 +165,10 @@ static void DrawRects(SDL_Renderer *renderer)
         SDL_SetRenderDrawColor(renderer, 255, (Uint8)current_color,
                                (Uint8)current_color, (Uint8)current_alpha);
 
-        rect.w = (float)(SDL_rand() % (viewport.h / 2));
-        rect.h = (float)(SDL_rand() % (viewport.h / 2));
-        rect.x = (float)((SDL_rand() % (viewport.w * 2) - viewport.w) - (rect.w / 2));
-        rect.y = (float)((SDL_rand() % (viewport.h * 2) - viewport.h) - (rect.h / 2));
+        rect.w = (float)SDL_rand_n(viewport.h / 2);
+        rect.h = (float)SDL_rand_n(viewport.h / 2);
+        rect.x = (float)((SDL_rand_n(viewport.w * 2) - viewport.w) - (rect.w / 2));
+        rect.y = (float)((SDL_rand_n(viewport.h * 2) - viewport.h) - (rect.h / 2));
         SDL_RenderFillRect(renderer, &rect);
     }
 }