|
| void | bj_srand (unsigned int seed) |
| int | bj_rand (void) |
| void | bj_seed_pcg32 (struct bj_pcg32 *generator, uint64_t seed, uint64_t seq) |
| uint32_t | bj_next_pcg32 (struct bj_pcg32 *generator) |
| void | bj_discard_pcg32 (struct bj_pcg32 *generator, uint64_t z) |
| uint32_t | bj_pcg32_min (void) |
| uint32_t | bj_pcg32_max (void) |
| uint32_t | bj_min_pcg32 (void) |
| uint32_t | bj_max_pcg32 (void) |
| static uint32_t | bj_pcg32_generator (void *state) |
| static uint32_t | bj_rand_generator (void *state) |
| int32_t | bj_random_uniform_i32 (bj_random_u32_fn next, void *state, int32_t low, int32_t high) |
| uint32_t | bj_random_uniform_u32 (bj_random_u32_fn next, void *state, uint32_t low, uint32_t high) |
| float | bj_random_uniform_f32 (bj_random_u32_fn next, void *state, float low, float high) |
| double | bj_random_uniform_f64 (bj_random_u32_fn next, void *state, double low, double high) |
| long double | bj_random_uniform_ld (bj_random_u32_fn next, void *state, long double low, long double high) |
| int | bj_random_bernoulli (bj_random_u32_fn next, void *state, bj_real probability) |
| float | bj_random_normal_f32 (bj_random_u32_fn next, void *state, float mean, float standard_deviation) |
| double | bj_random_normal_f64 (bj_random_u32_fn next, void *state, double mean, double standard_deviation) |
| long double | bj_random_normal_ld (bj_random_u32_fn next, void *state, long double mean, long double standard_deviation) |
| float | bj_random_normal_range_f32 (bj_random_u32_fn next, void *state, float min, float max) |
| double | bj_random_normal_range_f64 (bj_random_u32_fn next, void *state, double min, double max) |
| long double | bj_random_normal_range_ld (bj_random_u32_fn next, void *state, long double min, long double max) |
| int32_t | bj_uniform_int32_distribution (bj_random_u32_fn next, void *state, int32_t low, int32_t high) |
| uint32_t | bj_uniform_uint32_distribution (bj_random_u32_fn next, void *state, uint32_t low, uint32_t high) |
| float | bj_uniform_float_distribution (bj_random_u32_fn next, void *state, float low, float high) |
| double | bj_uniform_double_distribution (bj_random_u32_fn next, void *state, double low, double high) |
| long double | bj_uniform_long_double_distribution (bj_random_u32_fn next, void *state, long double low, long double high) |
| int | bj_bernoulli_distribution (bj_random_u32_fn next, void *state, bj_real probability) |
| float | bj_normal_float_distribution (bj_random_u32_fn next, void *state, float mean, float standard_deviation) |
| double | bj_normal_double_distribution (bj_random_u32_fn next, void *state, double mean, double standard_deviation) |
| long double | bj_normal_long_double_distribution (bj_random_u32_fn next, void *state, long double mean, long double standard_deviation) |
| float | bj_normal_float_minmax_distribution (bj_random_u32_fn next, void *state, float min, float max) |
| double | bj_normal_double_minmax_distribution (bj_random_u32_fn next, void *state, double min, double max) |
| long double | bj_normal_long_double_minmax_distribution (bj_random_u32_fn next, void *state, long double min, long double max) |
Generate random-looking numbers from a generator, then shape them into useful distributions.
Computers can't produce truly random numbers; they produce pseudo-random numbers: a deterministic sequence that looks random enough to be useful. The function that produces the next number from the previous one is called a pseudo-random number generator (PRNG). Banjo gives you two PRNGs to choose from, plus helpers to turn raw random numbers into the shapes you actually want (a die roll between 1 and 6, a coordinate inside a circle, a normally distributed measurement…).
Two generators: pick one
- bj_rand / bj_srand work like C's standard rand / srand: one process-wide generator state, one function call to get a number. Cheap, but its sequence has well-known weaknesses, so don't use it for anything where statistical quality matters (cryptographic anything, scientific simulation, procedural content where players might detect patterns).
- bj_pcg32 is the modern PCG32 generator. You manage one or more bj_pcg32 objects yourself (each is just a struct holding the state), initialise them with bj_seed_pcg32, and draw the next 32-bit value with bj_next_pcg32. Much better statistical quality than bj_rand, still very fast.
PCG32 supports independent streams: each bj_pcg32 can be given a different seq value at seeding time, and the resulting sequences will be independent of each other even if seeded from the same number. Useful for giving each subsystem of a game (terrain, AI, loot drops) its own generator so that adding code to one doesn't shift the randomness of the others, which makes replays and reproducible bugs much easier.
Distributions: turn raw random numbers into useful ones
A PRNG hands you flat 32-bit integers. You usually want something shaped differently: an integer in a range, a float between two bounds, a bool that's true 30% of the time, a number on a bell-curve around a mean. Each shape is called a distribution, and Banjo provides the common ones:
The type suffixes are i32 / u32 for the integer draws and f32 / f64 / ld for float / double / long double.
Distribution functions don't care which generator you use; they take a callback (bj_random_u32_fn) that returns the next 32-bit value, plus an opaque state pointer. For PCG32 the adapter bj_pcg32_generator does the right thing: pass that with your bj_pcg32* and the distributions work straight away:
float bj_real
Selected real type for float configuration.
void bj_seed_pcg32(struct bj_pcg32 *generator, uint64_t seed, uint64_t seq)
Set the generator state from seed and sequence.
#define bj_random_normal
Normal N(mean, stddev^2) for the active bj_real precision.
static uint32_t bj_pcg32_generator(void *state)
Adapter for distribution API (void* state).
int32_t bj_random_uniform_i32(bj_random_u32_fn next, void *state, int32_t low, int32_t high)
Uniform signed 32-bit integer in [low, high].
double bj_random_uniform_f64(bj_random_u32_fn next, void *state, double low, double high)
Uniform double in [low, high).
- See also
random.c and random_distribution.c for runnable demos.
◆ bj_pcg32
PCG32 generator state.
- Examples
- random.c.
Definition at line 117 of file random.h.
| Data Fields |
|
uint64_t |
inc |
Stream selector; odd recommended, 0 allowed. |
|
uint64_t |
state |
Current internal state (updated each step). |
◆ bj_normal_real_distribution
◆ bj_normal_real_minmax_distribution
◆ BJ_RAND_MAX
| #define BJ_RAND_MAX 0x7FFF |
Maximum value returned by bj_rand().
Matches the stdlib idea of RAND_MAX. Values from bj_rand() are distributed in [0, BJ_RAND_MAX].
Definition at line 94 of file random.h.
◆ bj_random_normal
◆ bj_random_normal_range
Min/max normal for the active bj_real precision.
Maps to:
Definition at line 499 of file random.h.
◆ bj_random_uniform
Uniform real in [low, high) for the active bj_real precision.
Maps to:
Definition at line 332 of file random.h.
◆ bj_uniform_real_distribution
◆ bj_random_u32_fn
| typedef uint32_t(* bj_random_u32_fn) (void *state) |
RNG callback type for generator-agnostic distributions.
- Parameters
-
| state | Opaque engine state pointer. |
- Returns
- Next 32-bit pseudo-random value.
Definition at line 223 of file random.h.
◆ bj_bernoulli_distribution()
◆ bj_discard_pcg32()
| void bj_discard_pcg32 |
( |
struct bj_pcg32 * | generator, |
|
|
uint64_t | z ) |
Advance the generator state by z steps.
- Parameters
-
| generator | Generator to advance, or NULL for the shared default one (see bj_seed_pcg32). |
| z | Number of steps to skip ahead. |
- Examples
- random.c.
Referenced by main().
◆ bj_max_pcg32()
| uint32_t bj_max_pcg32 |
( |
void | | ) |
|
◆ bj_min_pcg32()
| uint32_t bj_min_pcg32 |
( |
void | | ) |
|
◆ bj_next_pcg32()
| uint32_t bj_next_pcg32 |
( |
struct bj_pcg32 * | generator | ) |
|
◆ bj_normal_double_distribution()
| double bj_normal_double_distribution |
( |
bj_random_u32_fn | next, |
|
|
void * | state, |
|
|
double | mean, |
|
|
double | standard_deviation ) |
◆ bj_normal_double_minmax_distribution()
| double bj_normal_double_minmax_distribution |
( |
bj_random_u32_fn | next, |
|
|
void * | state, |
|
|
double | min, |
|
|
double | max ) |
◆ bj_normal_float_distribution()
| float bj_normal_float_distribution |
( |
bj_random_u32_fn | next, |
|
|
void * | state, |
|
|
float | mean, |
|
|
float | standard_deviation ) |
◆ bj_normal_float_minmax_distribution()
| float bj_normal_float_minmax_distribution |
( |
bj_random_u32_fn | next, |
|
|
void * | state, |
|
|
float | min, |
|
|
float | max ) |
◆ bj_normal_long_double_distribution()
| long double bj_normal_long_double_distribution |
( |
bj_random_u32_fn | next, |
|
|
void * | state, |
|
|
long double | mean, |
|
|
long double | standard_deviation ) |
◆ bj_normal_long_double_minmax_distribution()
| long double bj_normal_long_double_minmax_distribution |
( |
bj_random_u32_fn | next, |
|
|
void * | state, |
|
|
long double | min, |
|
|
long double | max ) |
◆ bj_pcg32_generator()
| uint32_t bj_pcg32_generator |
( |
void * | state | ) |
|
|
inlinestatic |
◆ bj_pcg32_max()
| uint32_t bj_pcg32_max |
( |
void | | ) |
|
Largest possible value returned by the generator.
- Returns
- Always 0xFFFFFFFF.
- Examples
- random.c.
Referenced by main().
◆ bj_pcg32_min()
| uint32_t bj_pcg32_min |
( |
void | | ) |
|
Smallest possible value returned by the generator.
- Returns
- Always 0.
- Examples
- random.c.
Referenced by main().
◆ bj_rand()
Generate a pseudo-random integer in [0, BJ_RAND_MAX].
Linear congruential generator (LCG) using: X_{n+1} = (1103515245 * X_n + 12345) mod 2^31
Returns the high-order bits truncated to BJ_RAND_MAX range.
- Returns
- Integer in [0, BJ_RAND_MAX].
- Examples
- random.c.
Referenced by bj_rand_generator(), and main().
◆ bj_rand_generator()
| uint32_t bj_rand_generator |
( |
void * | state | ) |
|
|
inlinestatic |
Adapter exposing the global bj_rand engine to the distribution API.
Use this when a caller wants randomness without carrying an engine of its own; state is ignored and the shared state seeded by bj_srand is used instead. That state is global, so sequences are not reproducible when several parts of a program draw from it, and concurrent use is unsafe. Prefer bj_pcg32_generator with a caller-owned bj_pcg32 whenever either matters.
bj_rand only yields 15 bits per call (see BJ_RAND_MAX), while the distributions consume a full 32-bit word and read its high bits. Three draws are therefore combined into one result; a plain cast of a single bj_rand call leaves the high bits clear and collapses those distributions onto their lower bound.
- Parameters
-
- Returns
- Next 32-bit pseudo-random value.
Definition at line 209 of file random.h.
◆ bj_random_bernoulli()
Bernoulli(probability).
- Parameters
-
| next | RNG callback (e.g., bj_pcg32_generator), or NULL to draw from the global bj_rand engine. |
| state | Opaque engine state for next, given to it as is, NULL included; ignored when next is NULL. |
| probability | Probability in [0,1]; 0 or less always gives 0, and 1 or more always 1, without drawing. |
- Returns
- 1 with the given probability, else 0.
- Examples
- random_distribution.c.
Referenced by run_distributions().
◆ bj_random_normal_f32()
| float bj_random_normal_f32 |
( |
bj_random_u32_fn | next, |
|
|
void * | state, |
|
|
float | mean, |
|
|
float | standard_deviation ) |
Normal float N(mean, standard_deviation^2).
- Parameters
-
| next | RNG callback (e.g., bj_pcg32_generator), or NULL to draw from the global bj_rand engine. |
| state | Opaque engine state for next, given to it as is, NULL included; ignored when next is NULL. |
| mean | Mean. |
| standard_deviation | Standard deviation; 0 or less gives mean without drawing. |
- Returns
- float sample.
◆ bj_random_normal_f64()
| double bj_random_normal_f64 |
( |
bj_random_u32_fn | next, |
|
|
void * | state, |
|
|
double | mean, |
|
|
double | standard_deviation ) |
Normal double N(mean, standard_deviation^2).
- Parameters
-
| next | RNG callback (e.g., bj_pcg32_generator), or NULL to draw from the global bj_rand engine. |
| state | Opaque engine state for next, given to it as is, NULL included; ignored when next is NULL. |
| mean | Mean. |
| standard_deviation | Standard deviation; 0 or less gives mean without drawing. |
- Returns
- double sample.
◆ bj_random_normal_ld()
| long double bj_random_normal_ld |
( |
bj_random_u32_fn | next, |
|
|
void * | state, |
|
|
long double | mean, |
|
|
long double | standard_deviation ) |
Normal long double N(mean, standard_deviation^2).
- Parameters
-
| next | RNG callback (e.g., bj_pcg32_generator), or NULL to draw from the global bj_rand engine. |
| state | Opaque engine state for next, given to it as is, NULL included; ignored when next is NULL. |
| mean | Mean. |
| standard_deviation | Standard deviation; 0 or less gives mean without drawing. |
- Returns
- long double sample.
◆ bj_random_normal_range_f32()
| float bj_random_normal_range_f32 |
( |
bj_random_u32_fn | next, |
|
|
void * | state, |
|
|
float | min, |
|
|
float | max ) |
Normal float from a min/max pair (μ ≈ (min+max)/2, σ ≈ (max-min)/6).
Interprets min ≈ μ − 3σ and max ≈ μ + 3σ, then calls the typed normal distribution. Samples are not guaranteed to lie inside [min, max].
- Parameters
-
| next | RNG callback (e.g., bj_pcg32_generator), or NULL to draw from the global bj_rand engine. |
| state | Opaque engine state for next, given to it as is, NULL included; ignored when next is NULL. |
| min | Approximate lower limit (treated as μ − 3σ). |
| max | Approximate upper limit (treated as μ + 3σ). |
- Returns
- One sample from N(μ, σ²) with μ,σ derived from min/max.
◆ bj_random_normal_range_f64()
| double bj_random_normal_range_f64 |
( |
bj_random_u32_fn | next, |
|
|
void * | state, |
|
|
double | min, |
|
|
double | max ) |
Normal double from a min/max pair (μ ≈ (min+max)/2, σ ≈ (max-min)/6).
Interprets min ≈ μ − 3σ and max ≈ μ + 3σ, then calls the typed normal distribution. Samples are not guaranteed to lie inside [min, max].
- Parameters
-
| next | RNG callback (e.g., bj_pcg32_generator), or NULL to draw from the global bj_rand engine. |
| state | Opaque engine state for next, given to it as is, NULL included; ignored when next is NULL. |
| min | Approximate lower limit (treated as μ − 3σ). |
| max | Approximate upper limit (treated as μ + 3σ). |
- Returns
- One sample from N(μ, σ²) with μ,σ derived from min/max.
◆ bj_random_normal_range_ld()
| long double bj_random_normal_range_ld |
( |
bj_random_u32_fn | next, |
|
|
void * | state, |
|
|
long double | min, |
|
|
long double | max ) |
Normal long double from a min/max pair (μ ≈ (min+max)/2, σ ≈ (max-min)/6).
Interprets min ≈ μ − 3σ and max ≈ μ + 3σ, then calls the typed normal distribution. Samples are not guaranteed to lie inside [min, max].
- Parameters
-
| next | RNG callback (e.g., bj_pcg32_generator), or NULL to draw from the global bj_rand engine. |
| state | Opaque engine state for next, given to it as is, NULL included; ignored when next is NULL. |
| min | Approximate lower limit (treated as μ − 3σ). |
| max | Approximate upper limit (treated as μ + 3σ). |
- Returns
- One sample from N(μ, σ²) with μ,σ derived from min/max.
◆ bj_random_uniform_f32()
| float bj_random_uniform_f32 |
( |
bj_random_u32_fn | next, |
|
|
void * | state, |
|
|
float | low, |
|
|
float | high ) |
Uniform float in [low, high).
- Parameters
-
| next | RNG callback (e.g., bj_pcg32_generator), or NULL to draw from the global bj_rand engine. |
| state | Opaque engine state for next, given to it as is, NULL included; ignored when next is NULL. |
| low | Inclusive lower bound. |
| high | Exclusive upper bound. |
- Returns
- float in [low, high). Reversed bounds are swapped, and equal bounds give
low without drawing.
◆ bj_random_uniform_f64()
| double bj_random_uniform_f64 |
( |
bj_random_u32_fn | next, |
|
|
void * | state, |
|
|
double | low, |
|
|
double | high ) |
Uniform double in [low, high).
- Parameters
-
| next | RNG callback (e.g., bj_pcg32_generator), or NULL to draw from the global bj_rand engine. |
| state | Opaque engine state for next, given to it as is, NULL included; ignored when next is NULL. |
| low | Inclusive lower bound. |
| high | Exclusive upper bound. |
- Returns
- double in [low, high). Reversed bounds are swapped, and equal bounds give
low without drawing.
◆ bj_random_uniform_i32()
| int32_t bj_random_uniform_i32 |
( |
bj_random_u32_fn | next, |
|
|
void * | state, |
|
|
int32_t | low, |
|
|
int32_t | high ) |
Uniform signed 32-bit integer in [low, high].
- Parameters
-
| next | RNG callback (e.g., bj_pcg32_generator), or NULL to draw from the global bj_rand engine. |
| state | Opaque engine state for next, given to it as is, NULL included; ignored when next is NULL. |
| low | Inclusive lower bound. |
| high | Inclusive upper bound. |
- Returns
- int32 in [low, high]. Reversed bounds are swapped.
- Examples
- random_distribution.c.
Referenced by run_distributions().
◆ bj_random_uniform_ld()
| long double bj_random_uniform_ld |
( |
bj_random_u32_fn | next, |
|
|
void * | state, |
|
|
long double | low, |
|
|
long double | high ) |
Uniform long double in [low, high).
- Parameters
-
| next | RNG callback (e.g., bj_pcg32_generator), or NULL to draw from the global bj_rand engine. |
| state | Opaque engine state for next, given to it as is, NULL included; ignored when next is NULL. |
| low | Inclusive lower bound. |
| high | Exclusive upper bound. |
- Returns
- long double in [low, high). Reversed bounds are swapped, and equal bounds give
low without drawing.
◆ bj_random_uniform_u32()
| uint32_t bj_random_uniform_u32 |
( |
bj_random_u32_fn | next, |
|
|
void * | state, |
|
|
uint32_t | low, |
|
|
uint32_t | high ) |
Uniform unsigned 32-bit integer in [low, high].
Same unbiased method as bj_random_uniform_i32, over the full unsigned range. Use it when the values being drawn are naturally unsigned (array indices, counts) and can exceed INT32_MAX.
- Parameters
-
| next | RNG callback (e.g., bj_pcg32_generator), or NULL to draw from the global bj_rand engine. |
| state | Opaque engine state for next, given to it as is, NULL included; ignored when next is NULL. |
| low | Inclusive lower bound. |
| high | Inclusive upper bound. |
- Returns
- uint32 in [low, high]. Reversed bounds are swapped.
◆ bj_seed_pcg32()
| void bj_seed_pcg32 |
( |
struct bj_pcg32 * | generator, |
|
|
uint64_t | seed, |
|
|
uint64_t | seq ) |
Set the generator state from seed and sequence.
- Parameters
-
| generator | Generator to seed, or NULL for the default generator that the whole process shares, apart from bj_rand. |
| seed | Initial seed value. |
| seq | Stream selector (LSB forced to 1 internally). |
- Examples
- random.c.
Referenced by main().
◆ bj_srand()
| void bj_srand |
( |
unsigned int | seed | ) |
|
Seed the standard PRNG.
- Parameters
-
| seed | Seed value. Same seed reproduces the same sequence. |
- Examples
- maze.c, and random.c.
Referenced by main(), and setup().
◆ bj_uniform_double_distribution()
| double bj_uniform_double_distribution |
( |
bj_random_u32_fn | next, |
|
|
void * | state, |
|
|
double | low, |
|
|
double | high ) |
◆ bj_uniform_float_distribution()
| float bj_uniform_float_distribution |
( |
bj_random_u32_fn | next, |
|
|
void * | state, |
|
|
float | low, |
|
|
float | high ) |
◆ bj_uniform_int32_distribution()
| int32_t bj_uniform_int32_distribution |
( |
bj_random_u32_fn | next, |
|
|
void * | state, |
|
|
int32_t | low, |
|
|
int32_t | high ) |
◆ bj_uniform_long_double_distribution()
| long double bj_uniform_long_double_distribution |
( |
bj_random_u32_fn | next, |
|
|
void * | state, |
|
|
long double | low, |
|
|
long double | high ) |
◆ bj_uniform_uint32_distribution()
| uint32_t bj_uniform_uint32_distribution |
( |
bj_random_u32_fn | next, |
|
|
void * | state, |
|
|
uint32_t | low, |
|
|
uint32_t | high ) |