Infinity::Engine::PRNG Class Reference

Pseudo-random number generator for procedural generation. More...

#include <PRNG.hpp>

Public Types
typedef uint32_t	result_type
	Result type for compatibility with standard library distributions.

Public Member Functions
	PRNG ()
	Default constructor.
	PRNG (uint64_t seed, uint64_t stream=0)
	Constructs a PRNG with the specified seed and stream.
	~PRNG ()
	Destructor.
void	setSeed (uint64_t seed, uint64_t stream=0)
	Sets the seed and stream for the random number generator.
uint64_t	getSeed () const
	Gets the current seed value.
uint64_t	getStream () const
	Gets the current stream identifier.
uint32_t	operator() ()
	Function call operator for generating random uint32 values.
uint32_t	operator() (uint32_t upper_bound)
	Function call operator for generating bounded random uint32 values.
uint32_t	next ()
	Generates the next random uint32 value.
int	nextInt ()
	Generates a random integer value.
float	nextFloat ()
	Generates a random float value in the range [0, 1).
uint32_t	nextBounded (uint32_t l, uint32_t u)
	Generates a random uint32 value within the specified inclusive range.
int	nextIntBounded (int l, int u)
	Generates a random integer value within the specified inclusive range.
float	nextFloatBounded (float l, float u)
	Generates a random float value within the specified inclusive range.
void	advance (uint64_t delta)
	Advances the generator state forward by delta steps.
void	backstep (uint64_t delta)
	Steps the generator state backward by delta steps.
void	discard (uint64_t delta)
	Discards delta random values from the sequence.

Static Public Member Functions
static uint64_t	createSeed ()
	Creates a new random seed using system entropy.
static constexpr size_t	period_pow2 ()
	Returns the period of the generator as a power of 2.
static constexpr uint32_t	min ()
	Returns the minimum value the generator can produce.
static constexpr uint32_t	max ()
	Returns the maximum value the generator can produce.

Detailed Description

Pseudo-random number generator for procedural generation.

PRNG provides a high-quality, fast pseudo-random number generator based on the PCG (Permuted Congruential Generator) algorithm. It offers excellent statistical properties, good performance, and reproducibility from seeds, making it ideal for procedural generation workflows.

The generator supports:

• Seeded generation for reproducible results
• Multiple independent streams from the same seed
• Various output types (uint32, int, float)
• Bounded random values within specific ranges
• Stream advancement and backstep operations

Streams: PCG generators support multiple independent streams, allowing you to use the same seed but get completely different, uncorrelated sequences. This is useful for generating different aspects of procedural content (e.g., terrain, vegetation, weather) from a single master seed while maintaining independence between systems.

Example usage:

PRNG rng(12345);  // Create with specific seed, default stream 0
PRNG rng2(12345, 1);  // Same seed, different stream - produces different sequence
 
uint32_t randomUInt = rng();
int randomInt = rng.nextInt();
float randomFloat = rng.nextFloat();  // Returns value in [0, 1)
 
// Generate bounded random values
int diceRoll = rng.nextIntBounded(1, 6);  // 1 to 6 inclusive
float position = rng.nextFloatBounded(-1.0f, 1.0f);

Member Typedef Documentation

result_type

typedef uint32_t Infinity::Engine::PRNG::result_type

Result type for compatibility with standard library distributions.

Constructor & Destructor Documentation

PRNG() [1/2]

Infinity::Engine::PRNG::PRNG

(

)

Default constructor.

Creates a PRNG with a seed generated from PRNG::createSeed() and stream 0.

PRNG() [2/2]

Infinity::Engine::PRNG::PRNG	(	uint64_t	seed,
		uint64_t	stream = 0
	)

Constructs a PRNG with the specified seed and stream.

Parameters

seed	The seed value for reproducible random number generation.
stream	The stream identifier (default 0). Different streams with the same seed produce independent, uncorrelated sequences.

~PRNG()

Infinity::Engine::PRNG::~PRNG

(

)

Destructor.

Member Function Documentation

advance()

void Infinity::Engine::PRNG::advance ( uint64_t  delta )

inline

Advances the generator state forward by delta steps.

Efficiently jumps ahead in the random number sequence without generating intermediate values. Useful for parallel generation or skipping ahead.

Parameters

delta

Number of steps to advance.

backstep()

void Infinity::Engine::PRNG::backstep ( uint64_t  delta )

inline

Steps the generator state backward by delta steps.

Efficiently jumps backward in the random number sequence.

Parameters

delta

Number of steps to backstep.

createSeed()

static uint64_t Infinity::Engine::PRNG::createSeed ( )

static

Creates a new random seed using system entropy.

Warning

This function is relatively expensive (~microseconds) as it gathers entropy from 13 different system sources and performs cryptographic mixing. It should be used sparingly - typically once to seed a master RNG, which can then efficiently generate many seeds. Avoid calling this in hot paths or performance-critical loops.

Note

We use multiple entropy sources rather than relying solely on std::random_device because:

• std::random_device is platform-dependent and unreliable (e.g., broken on MinGW)
• Some implementations are deterministic or low-quality
• Combining multiple sources provides defense-in-depth against weak implementations
• Even if some sources are predictable, the cryptographic mixing in seed_seq_fe ensures the final seed has high quality as long as ANY source provides entropy

Entropy sources by quality:

High-quality (always varying):

• hitime: nanosecond-resolution clock
• random_int: incremented counter seeded from OS entropy
• cpu: CPU cycle counter
• heap: dynamic allocation addresses
• stack: stack frame addresses

Medium-quality (varies per run):

• self_data: object address (ASLR-dependent)
• thread_id: current thread identifier
• pid: process ID

Low-quality (rarely changes):

• exit_func: system library function address
• time_func: system library function address
• self_func: local function address (constant without -fPIC)
• type_id: RTTI hash (implementation-dependent)

Constant per build:

• compile_stamp: hash of DATE TIME FILE

Returns

A randomly generated 64-bit seed suitable for initializing PRNGs.

discard()

void Infinity::Engine::PRNG::discard ( uint64_t  delta )

inline

Discards delta random values from the sequence.

Equivalent to calling next() delta times, but more efficient.

Parameters

delta

Number of values to discard.

getSeed()

uint64_t Infinity::Engine::PRNG::getSeed ( ) const

inline

Gets the current seed value.

Returns

The seed value used to initialize this generator.

getStream()

uint64_t Infinity::Engine::PRNG::getStream ( ) const

inline

Gets the current stream identifier.

Returns

The stream identifier for this generator.

max()

static constexpr uint32_t Infinity::Engine::PRNG::max ( )

inlinestaticconstexpr

Returns the maximum value the generator can produce.

Returns

The maximum uint32_t value (typically UINT32_MAX).

min()

static constexpr uint32_t Infinity::Engine::PRNG::min ( )

inlinestaticconstexpr

Returns the minimum value the generator can produce.

Returns

The minimum uint32_t value (typically 0).

next()

uint32_t Infinity::Engine::PRNG::next ( )

inline

Generates the next random uint32 value.

Returns

A random uint32_t value in the full uint32 range.

nextBounded()

uint32_t Infinity::Engine::PRNG::nextBounded	(	uint32_t	l,
		uint32_t	u
	)

Generates a random uint32 value within the specified inclusive range.

Parameters

l	Lower bound (inclusive).
u	Upper bound (inclusive).

Returns

A random uint32_t value in the range [l, u].

nextFloat()

float Infinity::Engine::PRNG::nextFloat

(

)

Generates a random float value in the range [0, 1).

Returns

A random float value uniformly distributed in [0, 1).

nextFloatBounded()

float Infinity::Engine::PRNG::nextFloatBounded	(	float	l,
		float	u
	)

Generates a random float value within the specified inclusive range.

Parameters

l	Lower bound (inclusive).
u	Upper bound (inclusive).

Returns

A random float value in the range [l, u].

nextInt()

int Infinity::Engine::PRNG::nextInt

(

)

Generates a random integer value.

Returns

A random int value across the full int range.

nextIntBounded()

int Infinity::Engine::PRNG::nextIntBounded	(	int	l,
		int	u
	)

Generates a random integer value within the specified inclusive range.

Parameters

l	Lower bound (inclusive).
u	Upper bound (inclusive).

Returns

A random int value in the range [l, u].

operator()() [1/2]

uint32_t Infinity::Engine::PRNG::operator() ( )

inline

Function call operator for generating random uint32 values.

Returns

A random uint32_t value in the full uint32 range.

operator()() [2/2]

uint32_t Infinity::Engine::PRNG::operator() ( uint32_t  upper_bound )

inline

Function call operator for generating bounded random uint32 values.

Parameters

upper_bound

Exclusive upper bound (result will be in [0, upper_bound)).

Returns

A random uint32_t value in the range [0, upper_bound).

period_pow2()

static constexpr size_t Infinity::Engine::PRNG::period_pow2 ( )

inlinestaticconstexpr

Returns the period of the generator as a power of 2.

Returns

The period exponent (the period is 2^period_pow2()).

setSeed()

void Infinity::Engine::PRNG::setSeed	(	uint64_t	seed,
		uint64_t	stream = 0
	)

Sets the seed and stream for the random number generator.

Resets the generator state to produce a deterministic sequence from the given seed and stream combination.

Parameters

seed	The new seed value.
stream	The stream identifier (default 0).