paul_random.h

Includes:

<stdint.h>
<stddef.h>
<string.h>
<float.h>
<time.h>
<math.h>
<stdlib.h>
<windows.h>
<bcrypt.h>

Introduction

Random number generation and noise functions for C/C++.

Discussion

Implementation is included when PAUL_RANDOM_IMPLEMENTATION or PAUL_IMPLEMENTATION is defined.

Updated:: Saturday, July 19, 2025

Functions

cellular_automata: Generates a cellular automata pattern.
fbm: Computes fractal Brownian motion noise.
fbm2D: Generates a 2D fractal Brownian motion noise map.
fbm3D: Generates a 3D fractal Brownian motion noise volume.
noise_curl3D: Numerically compute the curl of a vector field derived from noise samples.
noise_tileable2D: Produce tileable 2D noise by mapping coordinates onto a torus.
normalize_to_unit_range: Normalize an array of floats in-place to the [0,1] range.
perlin_noise: Computes Perlin noise at the given coordinates.
poisson_disc_free_list: Frees a Poisson disc sampling point list.
poisson_disc_sample_foreach: Generates Poisson disc sampling points and calls a callback for each.
poisson_disc_sample_list: Generates Poisson disc sampling points and returns them in a list.
ridged_multifractal: Ridged multifractal noise built from a base noise function.
rnd_exponential: Samples the exponential distribution with rate parameter lambda.
rnd_normal: Generates a normally-distributed random value using Box–Muller.
rnd_permutation: Fill a buffer with a random permutation of [0..n-1].
rnd_randf: Generates a random float between 0.0 and 1.0.
rnd_randf_range: Generates a random float within a specified range.
rnd_randf_signed: Generates a uniformly-distributed float in [-1.0, 1.0).
rnd_randi: Generates a random 64-bit unsigned integer.
rnd_randi_range: Generates a random integer within a specified range.
rnd_randi_range64: Generates a uniform 64-bit integer in the inclusive range [min, max].
rnd_reseed_from_entropy: Reseed the RNG from OS-provided entropy.
rnd_seed: Initializes the random number generator with a seed.
rnd_shuffle: In-place Fisher–Yates shuffle for a contiguous array.
rnd_shuffle_cb: In-place Fisher–Yates shuffle for an abstract container using a swap callback.
rnd_weighted_choice: Choose an index from an abstract list using a user-supplied weight callback.
rnd_weighted_choice_array: Choose an index from a contiguous float weight array.
simplex_noise: Computes Simplex noise at the given coordinates.
smootherstepf: Higher-order smooth interpolation (smoothstep with zero derivatives at edges).
smoothstepf: Smooth Hermite interpolation between 0 and 1.
turbulence: Turbulence-style noise (sum of absolute-valued octaves) built from a base noise function.
value_noise: Computes value noise at the given coordinates.
white_noise: Computes white noise at the given coordinates.
worley_noise: Computes Worley (cellular) noise at the given coordinates.

cellular_automata

Generates a cellular automata pattern.

void cellular_automata(
    rng_t *rng, 
    unsigned int width,
    unsigned int height, 
    unsigned int fill_chance,
    unsigned int smooth_iterations, 
    unsigned int survive,
    unsigned int starve, 
    uint8_t *dst);

Parameters

rng: Pointer to the initialized rng_t structure.
width: Width of the grid.
height: Height of the grid.
fill_chance: Percentage chance to fill a cell initially (1-99).
smooth_iterations: Number of smoothing iterations.
survive: Minimum neighbors to survive.
starve: Maximum neighbors to starve.
dst: Output buffer for the grid (uint8_t array).

fbm

Computes fractal Brownian motion noise.

float fbm(
    float x,
    float y,
    float z, 
    float lacunarity,
    float gain,
    int octaves, 
    noise_fn_t noise_fn);

Parameters

x: X coordinate.
y: Y coordinate.
z: Z coordinate.
lacunarity: Frequency multiplier between octaves.
gain: Amplitude multiplier between octaves.
octaves: Number of octaves.
noise_fn: Base noise function.

Return Value

FBM noise value.

fbm2D

Generates a 2D fractal Brownian motion noise map.

void fbm2D(
    unsigned int width,
    unsigned int height,
    float z, 
    float offset_x,
    float offset_y, 
    float scale,
    float lacunarity,
    float gain,
    int octaves, 
    noise_fn_t noise_fn,
    uint8_t *dst);

Parameters

width: Width of the output map.
height: Height of the output map.
z: Z coordinate (fixed for 2D slice).
offset_x: X offset.
offset_y: Y offset.
scale: Scale factor.
lacunarity: Frequency multiplier.
gain: Amplitude multiplier.
octaves: Number of octaves.
noise_fn: Base noise function.
dst: Output buffer (uint8_t array).

fbm3D

Generates a 3D fractal Brownian motion noise volume.

void fbm3D(
    unsigned int width,
    unsigned int height,
    unsigned int depth, 
    float offset_x,
    float offset_y,
    float offset_z, 
    float scale,
    float lacunarity,
    float gain,
    int octaves, 
    noise_fn_t noise_fn,
    uint8_t *dst);

Parameters

width: Width of the output volume.
height: Height of the output volume.
depth: Depth of the output volume.
offset_x: X offset.
offset_y: Y offset.
offset_z: Z offset.
scale: Scale factor.
lacunarity: Frequency multiplier.
gain: Amplitude multiplier.
octaves: Number of octaves.
noise_fn: Base noise function.
dst: Output buffer (uint8_t array).

noise_curl3D

Numerically compute the curl of a vector field derived from noise samples.

void noise_curl3D(
    float x,
    float y,
    float z,
    float eps,
    noise_fn_t noise_fn,
    float *out_x,
    float *out_y,
    float *out_z);

Parameters

x: X coordinate.
y: Y coordinate.
z: Z coordinate.
eps: Small epsilon for finite differences.
noise_fn: Base noise function pointer.
out_x: Pointer to receive X component of curl.
out_y: Pointer to receive Y component of curl.
out_z: Pointer to receive Z component of curl.

noise_tileable2D

Produce tileable 2D noise by mapping coordinates onto a torus.

float noise_tileable2D(
    float x,
    float y,
    float width,
    float height,
    noise_fn_t noise_fn);

Parameters

x: X coordinate.
y: Y coordinate.
width: Tile width.
height: Tile height.
noise_fn: Base noise function pointer.

Return Value

Tileable noise value.

normalize_to_unit_range

Normalize an array of floats in-place to the [0,1] range.

void normalize_to_unit_range(
    float *data,
    size_t n);

Parameters

data: Pointer to the float array.
n: Number of elements in the array.

perlin_noise

Computes Perlin noise at the given coordinates.

float perlin_noise(
    float x,
    float y,
    float z);

Parameters

x: X coordinate.
y: Y coordinate.
z: Z coordinate.

Return Value

Perlin noise value in [-1, 1].

poisson_disc_free_list

Frees a Poisson disc sampling point list.

void poisson_disc_free_list(
    poisson_list_t *list);

Parameters

list: The list to free.

poisson_disc_sample_foreach

Generates Poisson disc sampling points and calls a callback for each.

void poisson_disc_sample_foreach(
    float width,
    float height,
    float min_dist, 
    int max_attempts,
    poisson_check_callback_t check_fn, 
    void *check_data,
    poisson_callback_t point_fn, 
    void *point_data);

Parameters

width: Width of the sampling area.
height: Height of the sampling area.
min_dist: Minimum distance between points.
max_attempts: Maximum attempts to place a point around each active point.
check_fn: Optional callback to validate points (NULL to accept all).
check_data: User data passed to the check callback.
point_fn: Callback called for each generated point.
point_data: User data passed to the point callback.

poisson_disc_sample_list

Generates Poisson disc sampling points and returns them in a list.

poisson_list_t *poisson_disc_sample_list(
    float width,
    float height,
    float min_dist, 
    int max_attempts,
    poisson_check_callback_t check_fn, 
    void *user_data);

Parameters

width: Width of the sampling area.
height: Height of the sampling area.
min_dist: Minimum distance between points.
max_attempts: Maximum attempts to place a point around each active point.
check_fn: Optional callback to validate points (NULL to accept all).
user_data: User data passed to the check callback.

Return Value

Allocated list of points (must be freed with poisson_disc_free_list).

ridged_multifractal

Ridged multifractal noise built from a base noise function.

float ridged_multifractal(
    float x,
    float y,
    float z,
    float lacunarity,
    float gain,
    int octaves,
    noise_fn_t noise_fn);

Parameters

x: X coordinate.
y: Y coordinate.
z: Z coordinate.
lacunarity: Frequency multiplier.
gain: Amplitude multiplier.
octaves: Number of octaves.
noise_fn: Base noise function pointer.

Return Value

Ridged multifractal value.

rnd_exponential

Samples the exponential distribution with rate parameter lambda.

float rnd_exponential(
    rng_t *rng,
    float lambda);

Parameters

rng: Pointer to the initialized rng_t structure.
lambda: Rate parameter (lambda > 0).

Return Value

A random float sampled from Exp(lambda).

rnd_normal

Generates a normally-distributed random value using Box–Muller.

float rnd_normal(
    rng_t *rng,
    float mean,
    float stddev);

Parameters

rng: Pointer to the initialized rng_t structure.
mean: Desired mean of the distribution.
stddev: Desired standard deviation of the distribution.

Return Value

A random float approximately distributed N(mean, stddev^2).

rnd_permutation

Fill a buffer with a random permutation of [0..n-1].

void rnd_permutation(
    rng_t *rng,
    uint32_t *out_perm,
    size_t n);

Parameters

rng: Pointer to the initialized rng_t structure.
out_perm: Pointer to a buffer of uint32_t with length >= n.
n: Number of elements in the permutation.

rnd_randf

Generates a random float between 0.0 and 1.0.

float rnd_randf(
    rng_t *rng);

Parameters

rng: Pointer to the initialized rng_t structure.

Return Value

A random float value in [0.0, 1.0).

rnd_randf_range

Generates a random float within a specified range.

float rnd_randf_range(
    rng_t *rng,
    float min,
    float max);

Parameters

rng: Pointer to the initialized rng_t structure.
min: The minimum value (inclusive).
max: The maximum value (inclusive).

Return Value

A random float value between min and max.

rnd_randf_signed

Generates a uniformly-distributed float in [-1.0, 1.0).

float rnd_randf_signed(
    rng_t *rng);

Parameters

rng: Pointer to the initialized rng_t structure.

Return Value

A random float in [-1, 1).

rnd_randi

Generates a random 64-bit unsigned integer.

uint64_t rnd_randi(
    rng_t *rng);

Parameters

rng: Pointer to the initialized rng_t structure.

Return Value

A random uint64_t value.

rnd_randi_range

Generates a random integer within a specified range.

int rnd_randi_range(
    rng_t *rng,
    int min,
    int max);

Parameters

rng: Pointer to the initialized rng_t structure.
min: The minimum value (inclusive).
max: The maximum value (inclusive).

Return Value

A random int value between min and max.

rnd_randi_range64

Generates a uniform 64-bit integer in the inclusive range [min, max].

uint64_t rnd_randi_range64(
    rng_t *rng,
    uint64_t min,
    uint64_t max);

Parameters

rng: Pointer to the initialized rng_t structure.
min: Minimum value (inclusive).
max: Maximum value (inclusive).

Return Value

A random uint64_t in [min, max]. If min >= max returns min.

rnd_reseed_from_entropy

Reseed the RNG from OS-provided entropy.

int rnd_reseed_from_entropy(
    rng_t *rng);

Parameters

rng: Pointer to the rng_t to reseed.

Return Value

Non-zero on success, zero on failure.

rnd_seed

Initializes the random number generator with a seed.

void rnd_seed(
    rng_t *rng,
    uint64_t seed);

Parameters

rng: Pointer to the rng_t structure to initialize.
seed: The seed value for the generator.

rnd_shuffle

In-place Fisher–Yates shuffle for a contiguous array.

void rnd_shuffle(
    rng_t *rng,
    void *array,
    size_t element_count,
    size_t element_size);

Parameters

rng: Pointer to the initialized rng_t structure.
array: Pointer to the array buffer.
element_count: Number of elements in the array.
element_size: Size in bytes of each element.

rnd_shuffle_cb

In-place Fisher–Yates shuffle for an abstract container using a swap callback.

void rnd_shuffle_cb(
    rng_t *rng,
    size_t element_count,
    rnd_swap_fn_t swap_fn,
    void *user_data);

Parameters

rng: Pointer to the initialized rng_t structure.
element_count: Number of elements in the container.
swap_fn: Callback to swap two indices in the container.
user_data: User data passed to swap_fn.

rnd_weighted_choice

Choose an index from an abstract list using a user-supplied weight callback.

int rnd_weighted_choice(
    rng_t *rng,
    size_t n,
    rnd_weight_fn_t weight_fn,
    void *user_data);

Parameters

rng: Pointer to the initialized rng_t structure.
n: Number of items to choose from.
weight_fn: Callback returning a non-negative weight for a given index.
user_data: User data passed to weight_fn.

Return Value

Chosen index in [0,n-1] or -1 on error (e.g., zero total weight).

rnd_weighted_choice_array

Choose an index from a contiguous float weight array.

int rnd_weighted_choice_array(
    rng_t *rng,
    const float *weights,
    size_t n);

Parameters

rng: Pointer to the initialized rng_t structure.
weights: Array of non-negative weights (length n).
n: Number of weights.

Return Value

Chosen index in [0,n-1] or -1 on error.

simplex_noise

Computes Simplex noise at the given coordinates.

float simplex_noise(
    float x,
    float y,
    float z);

Parameters

x: X coordinate.
y: Y coordinate.
z: Z coordinate.

Return Value

Simplex noise value.

smootherstepf

Higher-order smooth interpolation (smoothstep with zero derivatives at edges).

float smootherstepf(
    float edge0,
    float edge1,
    float t);

Parameters

edge0: Lower edge.
edge1: Upper edge.
t: Input value.

Return Value

Interpolated value in [0,1].

smoothstepf

Smooth Hermite interpolation between 0 and 1.

float smoothstepf(
    float edge0,
    float edge1,
    float t);

Parameters

edge0: Lower edge.
edge1: Upper edge.
t: Input value.

Return Value

Interpolated value in [0,1].

turbulence

Turbulence-style noise (sum of absolute-valued octaves) built from a base noise function.

float turbulence(
    float x,
    float y,
    float z,
    float lacunarity,
    float gain,
    int octaves,
    noise_fn_t noise_fn);

Parameters

x: X coordinate.
y: Y coordinate.
z: Z coordinate.
lacunarity: Frequency multiplier.
gain: Amplitude multiplier.
octaves: Number of octaves.
noise_fn: Base noise function pointer.

Return Value

Turbulence noise value.

value_noise

Computes value noise at the given coordinates.

float value_noise(
    float x,
    float y,
    float z);

Parameters

x: X coordinate.
y: Y coordinate.
z: Z coordinate.

Return Value

Value noise value in [-1, 1].

white_noise

Computes white noise at the given coordinates.

float white_noise(
    float x,
    float y,
    float z);

Parameters

x: X coordinate.
y: Y coordinate.
z: Z coordinate.

Return Value

White noise value in [-1, 1].

worley_noise

Computes Worley (cellular) noise at the given coordinates.

float worley_noise(
    float x,
    float y,
    float z);

Parameters

x: X coordinate.
y: Y coordinate.
z: Z coordinate.

Return Value

Worley noise value.

Typedefs

noise_fn_t: Function pointer type for noise functions.
poisson_callback_t: Callback function type for processing each generated point.
poisson_check_callback_t: Callback function type for checking if a point is valid.
poisson_list_t: Structure for storing a list of Poisson disc sampling points.
poisson_point_t: Structure representing a 2D point for Poisson disc sampling.
rnd_swap_fn_t: Callback type used to swap two elements in an abstract container.
rnd_weight_fn_t: Callback type used to provide a weight for a given index when choosing from a list.
rng_t: Random number generator state structure.

noise_fn_t

Function pointer type for noise functions.

typedef float( *noise_fn_t)(
    float,
    float,
    float);

Parameters

x: X coordinate.
y: Y coordinate.
z: Z coordinate.

Return Value

Noise value at the given coordinates.

poisson_callback_t

Callback function type for processing each generated point.

typedef void ( *poisson_callback_t)(
    float x,
    float y,
    void *user_data);

Parameters

x: X coordinate of the point.
y: Y coordinate of the point.
user_data: User-provided data.

poisson_check_callback_t

Callback function type for checking if a point is valid.

typedef int ( *poisson_check_callback_t)(
    float x,
    float y,
    void *user_data);

Parameters

x: X coordinate of the point.
y: Y coordinate of the point.
user_data: User-provided data.

Return Value

Non-zero if the point is valid, zero otherwise.

poisson_list_t

Structure for storing a list of Poisson disc sampling points.

typedef struct poisson_list { 
    poisson_point_t *points; 
    size_t count; 
    size_t capacity; 
} poisson_list_t;

Fields

points: Array of points.
count: Number of points in the list.
capacity: Capacity of the points array.

poisson_point_t

Structure representing a 2D point for Poisson disc sampling.

typedef struct poisson_point { 
    float x; 
    float y; 
} poisson_point_t;

Fields

x: X coordinate of the point.
y: Y coordinate of the point.

rnd_swap_fn_t

Callback type used to swap two elements in an abstract container.

typedef void ( *rnd_swap_fn_t)(
    size_t a,
    size_t b,
    void *user_data);

Parameters

a: Index of the first element to swap.
b: Index of the second element to swap.
user_data: Opaque user-provided pointer passed through by the caller.

rnd_weight_fn_t

Callback type used to provide a weight for a given index when choosing from a list.

typedef double ( *rnd_weight_fn_t)(
    size_t idx,
    void *user_data);

Parameters

idx: Index of the item for which a weight should be returned.
user_data: Opaque user-provided pointer passed through by the caller.

Return Value

A non-negative double weight for the item. Negative values are treated as zero.

rng_t

Random number generator state structure.

typedef struct rng { 
    uint64_t s[_PRNG_RAND_SSIZE]; 
    uint_fast16_t i; 
    uint_fast16_t c; 
} rng_t;

Fields

s: State array for the PRNG.
i: Current index in the state array.
c: Counter for refill cycles.

Last Updated: Saturday, July 19, 2025