Banjo API 1.1.0-alpha
Low-level C99 game development API
Loading...
Searching...
No Matches
Random

Data Structures

struct  bj_pcg32

Macros

#define BJ_RAND_MAX   0x7FFF
#define bj_random_uniform   bj_random_uniform_f32
#define bj_random_normal   bj_random_normal_f32
#define bj_random_normal_range   bj_random_normal_range_f32
#define bj_uniform_real_distribution   bj_random_uniform
#define bj_normal_real_distribution   bj_random_normal
#define bj_normal_real_minmax_distribution   bj_random_normal_range

Typedefs

typedef uint32_t(* bj_random_u32_fn) (void *state)

Functions

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)

Detailed Description

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:

bj_seed_pcg32(&rng, 42, 0);
double noise = bj_random_uniform_f64(bj_pcg32_generator, &rng, -1.0, 1.0);
bj_real iq = bj_random_normal(bj_pcg32_generator, &rng, 100.0, 15.0);
float bj_real
Selected real type for float configuration.
Definition math.h:80
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.
Definition random.h:419
static uint32_t bj_pcg32_generator(void *state)
Adapter for distribution API (void* state).
Definition random.h:185
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).
PCG32 generator state.
Definition random.h:117
static void roll(void)
See also
random.c and random_distribution.c for runnable demos.

Data Structure Documentation

◆ bj_pcg32

struct 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).

Macro Definition Documentation

◆ bj_normal_real_distribution

#define bj_normal_real_distribution   bj_random_normal
Deprecated
Renamed to bj_random_normal. Removed in 2.0.

Definition at line 543 of file random.h.

◆ bj_normal_real_minmax_distribution

#define bj_normal_real_minmax_distribution   bj_random_normal_range
Deprecated
Renamed to bj_random_normal_range. Removed in 2.0.

Definition at line 545 of file random.h.

◆ 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

#define bj_random_normal   bj_random_normal_f32

Normal N(mean, stddev^2) for the active bj_real precision.

Maps to:

Examples
random_distribution.c.

Definition at line 419 of file random.h.

Referenced by run_distributions().

◆ bj_random_normal_range

#define bj_random_normal_range   bj_random_normal_range_f32

Min/max normal for the active bj_real precision.

Maps to:

Definition at line 499 of file random.h.

◆ bj_random_uniform

#define bj_random_uniform   bj_random_uniform_f32

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

#define bj_uniform_real_distribution   bj_random_uniform
Deprecated
Renamed to bj_random_uniform. Removed in 2.0.

Definition at line 541 of file random.h.

Typedef Documentation

◆ bj_random_u32_fn

typedef uint32_t(* bj_random_u32_fn) (void *state)

RNG callback type for generator-agnostic distributions.

Parameters
stateOpaque engine state pointer.
Returns
Next 32-bit pseudo-random value.

Definition at line 223 of file random.h.

Function Documentation

◆ bj_bernoulli_distribution()

int bj_bernoulli_distribution ( bj_random_u32_fn next,
void * state,
bj_real probability )
Deprecated
Renamed to bj_random_bernoulli. Removed in 2.0.

◆ bj_discard_pcg32()

void bj_discard_pcg32 ( struct bj_pcg32 * generator,
uint64_t z )

Advance the generator state by z steps.

Parameters
generatorGenerator to advance, or NULL for the shared default one (see bj_seed_pcg32).
zNumber of steps to skip ahead.
Examples
random.c.

Referenced by main().

◆ bj_max_pcg32()

uint32_t bj_max_pcg32 ( void )
Deprecated
Renamed to bj_pcg32_max. Removed in 2.0.

◆ bj_min_pcg32()

uint32_t bj_min_pcg32 ( void )
Deprecated
Renamed to bj_pcg32_min. Removed in 2.0.

◆ bj_next_pcg32()

uint32_t bj_next_pcg32 ( struct bj_pcg32 * generator)

Advance the generator and return the next 32-bit value.

Parameters
generatorGenerator to advance, or NULL for the shared default one (see bj_seed_pcg32).
Returns
Next 32-bit pseudo-random value.
Examples
random.c.

Referenced by bj_pcg32_generator(), main(), and pcg32_u64().

◆ bj_normal_double_distribution()

double bj_normal_double_distribution ( bj_random_u32_fn next,
void * state,
double mean,
double standard_deviation )
Deprecated
Renamed to bj_random_normal_f64. Removed in 2.0.

◆ bj_normal_double_minmax_distribution()

double bj_normal_double_minmax_distribution ( bj_random_u32_fn next,
void * state,
double min,
double max )
Deprecated
Renamed to bj_random_normal_range_f64. Removed in 2.0.

◆ bj_normal_float_distribution()

float bj_normal_float_distribution ( bj_random_u32_fn next,
void * state,
float mean,
float standard_deviation )
Deprecated
Renamed to bj_random_normal_f32. Removed in 2.0.

◆ bj_normal_float_minmax_distribution()

float bj_normal_float_minmax_distribution ( bj_random_u32_fn next,
void * state,
float min,
float max )
Deprecated
Renamed to bj_random_normal_range_f32. Removed in 2.0.

◆ 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 )
Deprecated
Renamed to bj_random_normal_ld. Removed in 2.0.

◆ 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 )
Deprecated
Renamed to bj_random_normal_range_ld. Removed in 2.0.

◆ bj_pcg32_generator()

uint32_t bj_pcg32_generator ( void * state)
inlinestatic

Adapter for distribution API (void* state).

Allows struct bj_pcg32 to be used with callbacks of type uint32_t (*)(void* state).

Parameters
statePointer to struct bj_pcg32, or NULL for the shared default one (see bj_seed_pcg32).
Returns
Next 32-bit pseudo-random value.
Examples
random_distribution.c.

Definition at line 185 of file random.h.

Referenced by run_distributions().

◆ 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()

int bj_rand ( void )

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
stateIgnored; pass NULL.
Returns
Next 32-bit pseudo-random value.

Definition at line 209 of file random.h.

◆ bj_random_bernoulli()

int bj_random_bernoulli ( bj_random_u32_fn next,
void * state,
bj_real probability )

Bernoulli(probability).

Parameters
nextRNG callback (e.g., bj_pcg32_generator), or NULL to draw from the global bj_rand engine.
stateOpaque engine state for next, given to it as is, NULL included; ignored when next is NULL.
probabilityProbability 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
nextRNG callback (e.g., bj_pcg32_generator), or NULL to draw from the global bj_rand engine.
stateOpaque engine state for next, given to it as is, NULL included; ignored when next is NULL.
meanMean.
standard_deviationStandard 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
nextRNG callback (e.g., bj_pcg32_generator), or NULL to draw from the global bj_rand engine.
stateOpaque engine state for next, given to it as is, NULL included; ignored when next is NULL.
meanMean.
standard_deviationStandard 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
nextRNG callback (e.g., bj_pcg32_generator), or NULL to draw from the global bj_rand engine.
stateOpaque engine state for next, given to it as is, NULL included; ignored when next is NULL.
meanMean.
standard_deviationStandard 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
nextRNG callback (e.g., bj_pcg32_generator), or NULL to draw from the global bj_rand engine.
stateOpaque engine state for next, given to it as is, NULL included; ignored when next is NULL.
minApproximate lower limit (treated as μ − 3σ).
maxApproximate 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
nextRNG callback (e.g., bj_pcg32_generator), or NULL to draw from the global bj_rand engine.
stateOpaque engine state for next, given to it as is, NULL included; ignored when next is NULL.
minApproximate lower limit (treated as μ − 3σ).
maxApproximate 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
nextRNG callback (e.g., bj_pcg32_generator), or NULL to draw from the global bj_rand engine.
stateOpaque engine state for next, given to it as is, NULL included; ignored when next is NULL.
minApproximate lower limit (treated as μ − 3σ).
maxApproximate 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
nextRNG callback (e.g., bj_pcg32_generator), or NULL to draw from the global bj_rand engine.
stateOpaque engine state for next, given to it as is, NULL included; ignored when next is NULL.
lowInclusive lower bound.
highExclusive 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
nextRNG callback (e.g., bj_pcg32_generator), or NULL to draw from the global bj_rand engine.
stateOpaque engine state for next, given to it as is, NULL included; ignored when next is NULL.
lowInclusive lower bound.
highExclusive 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
nextRNG callback (e.g., bj_pcg32_generator), or NULL to draw from the global bj_rand engine.
stateOpaque engine state for next, given to it as is, NULL included; ignored when next is NULL.
lowInclusive lower bound.
highInclusive 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
nextRNG callback (e.g., bj_pcg32_generator), or NULL to draw from the global bj_rand engine.
stateOpaque engine state for next, given to it as is, NULL included; ignored when next is NULL.
lowInclusive lower bound.
highExclusive 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
nextRNG callback (e.g., bj_pcg32_generator), or NULL to draw from the global bj_rand engine.
stateOpaque engine state for next, given to it as is, NULL included; ignored when next is NULL.
lowInclusive lower bound.
highInclusive 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
generatorGenerator to seed, or NULL for the default generator that the whole process shares, apart from bj_rand.
seedInitial seed value.
seqStream 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
seedSeed 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 )
Deprecated
Renamed to bj_random_uniform_f64. Removed in 2.0.

◆ bj_uniform_float_distribution()

float bj_uniform_float_distribution ( bj_random_u32_fn next,
void * state,
float low,
float high )
Deprecated
Renamed to bj_random_uniform_f32. Removed in 2.0.

◆ bj_uniform_int32_distribution()

int32_t bj_uniform_int32_distribution ( bj_random_u32_fn next,
void * state,
int32_t low,
int32_t high )
Deprecated
Renamed to bj_random_uniform_i32. Removed in 2.0.

◆ 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 )
Deprecated
Renamed to bj_random_uniform_ld. Removed in 2.0.

◆ bj_uniform_uint32_distribution()

uint32_t bj_uniform_uint32_distribution ( bj_random_u32_fn next,
void * state,
uint32_t low,
uint32_t high )
Deprecated
Renamed to bj_random_uniform_u32. Removed in 2.0.