Random Number Generation

Functions
uint32	pcgRandom (PcgState *rng)
uint32	pcgBounded (PcgState *rng, uint32 bound)
bool	pcgFlip (PcgState *rng)
int32	pcgSBounded (PcgState *rng, int32 bound)
uint32	pcgRange (PcgState *rng, uint32 lower, uint32 upper)
int32	pcgSRange (PcgState *rng, int32 lower, int32 upper)
uint64	pcgRandom64 (PcgState *rng)
uint64	pcgBounded64 (PcgState *rng, uint64 bound)
uint64	pcgRange64 (PcgState *rng, uint64 lower, uint64 upper)
int64	pcgSRange64 (PcgState *rng, int64 lower, int64 upper)
float32	pcgFRange (PcgState *rng, float32 lower, float32 upper)
float64	pcgFRange64 (PcgState *rng, float64 lower, float64 upper)

Detailed Description

Core random number generation functions.

Function Documentation

pcgBounded()

uint32 pcgBounded	(	PcgState *	rng,
		uint32	bound
	)

Generates a uniformly distributed random integer in the range [0..bound)

Uses an unbiased rejection sampling algorithm to ensure perfect uniformity. Unlike the naive approach of using pcgRandom() % bound, this function eliminates modulo bias that would otherwise favor smaller values.

On average, this function completes in 1.33 iterations or less for any bound. The worst case (bound = 2^31 + 1) requires ~2 iterations on average.

Parameters

rng	Pointer to initialized PCG state
bound	Upper bound (exclusive) - must be > 0 for meaningful results

Returns

Random uint32 value in range [0..bound-1], or 0 if bound is 0

Referenced by pcgRange(), pcgSBounded(), and pcgSRange().

pcgBounded64()

uint64 pcgBounded64	(	PcgState *	rng,
		uint64	bound
	)

Generates a uniformly distributed random 64-bit integer in the range [0..bound)

64-bit version of pcgBounded(). Uses the same unbiased rejection sampling algorithm to ensure perfect uniformity across the full 64-bit range.

Parameters

rng	Pointer to initialized PCG state
bound	Upper bound (exclusive) - must be > 0 for meaningful results

Returns

Random uint64 value in range [0..bound-1], or 0 if bound is 0

Referenced by pcgRange64(), and pcgSRange64().

pcgFlip()

bool pcgFlip

(

PcgState *

rng

)

Simulates a coin flip with 50/50 probability

Efficiently generates a random boolean value by testing a single bit from the random number generator output.

Parameters

rng	Pointer to initialized PCG state

Returns

true or false with equal probability

pcgFRange()

float32 pcgFRange	(	PcgState *	rng,
		float32	lower,
		float32	upper
	)

Generates a uniformly distributed random floating-point number in the range [lower..upper]

Produces float32 values with uniform distribution. The precision is limited by the underlying 32-bit random integer and IEEE 754 float32 representation.

If lower >= upper, returns lower.

Example:

float32 speed = pcgFRange(&rng, 0.5f, 2.5f);  // Random speed multiplier
float32 angle = pcgFRange(&rng, 0.0f, 6.28f); // Random angle in radians

Parameters

rng	Pointer to initialized PCG state
lower	Lower bound (inclusive)
upper	Upper bound (inclusive)

Returns

Random float32 value in range [lower..upper]

pcgFRange64()

float64 pcgFRange64	(	PcgState *	rng,
		float64	lower,
		float64	upper
	)

Generates a uniformly distributed random double-precision floating-point number in the range [lower..upper]

Produces float64 values with uniform distribution. Uses pcgRandom64() for higher precision than pcgFRange().

If lower >= upper, returns lower.

Parameters

rng	Pointer to initialized PCG state
lower	Lower bound (inclusive)
upper	Upper bound (inclusive)

Returns

Random float64 value in range [lower..upper]

pcgRandom()

uint32 pcgRandom

(

PcgState *

rng

)

Generates a uniformly distributed random 32-bit integer

Produces random values in the full range [0..UINT32_MAX]. This is the fundamental generation function that all other PCG functions build upon.

Parameters

rng	Pointer to initialized PCG state

Returns

Random uint32 value in range [0..UINT32_MAX]

pcgRandom64()

uint64 pcgRandom64

(

PcgState *

rng

)

Generates a uniformly distributed random 64-bit integer

Produces random values in the full range [0..UINT64_MAX] by combining two 32-bit random values. Slightly slower than pcgRandom() due to requiring two generation steps.

Parameters

rng	Pointer to initialized PCG state

Returns

Random uint64 value in range [0..UINT64_MAX]

pcgRange()

uint32 pcgRange ( PcgState *  rng, uint32  lower, uint32  upper  )

inline

uint32 pcgRange(PcgState *rng, uint32 lower, uint32 upper)

Generates a uniformly distributed random integer in the range [lower..upper]

Both bounds are inclusive. If lower >= upper, returns lower. Useful for generating values in an arbitrary range, such as dice rolls.

Example:

uint32 d6 = pcgRange(&rng, 1, 6);      // Roll a 6-sided die
uint32 d20 = pcgRange(&rng, 1, 20);    // Roll a 20-sided die
uint32 percent = pcgRange(&rng, 0, 99); // Random percentage [0..99]

Parameters

rng	Pointer to initialized PCG state
lower	Lower bound (inclusive)
upper	Upper bound (inclusive)

Returns

Random uint32 value in range [lower..upper]

Definition at line 166 of file pcg.h.

References pcgBounded().

pcgRange64()

uint64 pcgRange64 ( PcgState *  rng, uint64  lower, uint64  upper  )

inline

uint64 pcgRange64(PcgState *rng, uint64 lower, uint64 upper)

Generates a uniformly distributed random 64-bit integer in the range [lower..upper]

Both bounds are inclusive. If lower >= upper, returns lower. 64-bit version of pcgRange().

Parameters

rng	Pointer to initialized PCG state
lower	Lower bound (inclusive)
upper	Upper bound (inclusive)

Returns

Random uint64 value in range [lower..upper]

Definition at line 230 of file pcg.h.

References pcgBounded64().

pcgSBounded()

int32 pcgSBounded ( PcgState *  rng, int32  bound  )

inline

int32 pcgSBounded(PcgState *rng, int32 bound)

Generates a uniformly distributed signed random integer in the range [0..bound)

Signed integer version of pcgBounded(). The bound must be non-negative. Uses the same unbiased rejection sampling algorithm as pcgBounded().

Parameters

rng	Pointer to initialized PCG state
bound	Upper bound (exclusive) - must be >= 0

Returns

Random int32 value in range [0..bound-1]

Definition at line 142 of file pcg.h.

References devAssert, and pcgBounded().

pcgSRange()

int32 pcgSRange ( PcgState *  rng, int32  lower, int32  upper  )

inline

int32 pcgSRange(PcgState *rng, int32 lower, int32 upper)

Generates a uniformly distributed signed random integer in the range [lower..upper]

Both bounds are inclusive. If lower >= upper, returns lower. Signed integer version of pcgRange().

Example:

int32 temp = pcgSRange(&rng, -20, 40);  // Random temperature in Celsius
int32 offset = pcgSRange(&rng, -5, 5);  // Small random offset

Parameters

rng	Pointer to initialized PCG state
lower	Lower bound (inclusive)
upper	Upper bound (inclusive)

Returns

Random int32 value in range [lower..upper]

Definition at line 191 of file pcg.h.

References pcgBounded().

pcgSRange64()

int64 pcgSRange64 ( PcgState *  rng, int64  lower, int64  upper  )

inline

int64 pcgSRange64(PcgState *rng, int64 lower, int64 upper)

Generates a uniformly distributed signed 64-bit random integer in the range [lower..upper]

Both bounds are inclusive. If lower >= upper, returns lower. Signed 64-bit version of pcgRange64().

Parameters

rng	Pointer to initialized PCG state
lower	Lower bound (inclusive)
upper	Upper bound (inclusive)

Returns

Random int64 value in range [lower..upper]

Definition at line 249 of file pcg.h.

References pcgBounded64().