Random Module | BWSL Docs

Hash-based random number generation and GPU-friendly random distributions.

Import

bwsl

import Random

This module has no module imports.

Usage Examples

Stable Per-Instance Variation

Use Random when the same object, particle, tile, or draw id needs deterministic variation without uploading extra random attributes.

bwsl

import Random

uint seed = uint(input.instance_id) + resources.frameSeed;
float hueShift = Random::rand_range(seed, -0.08, 0.08);
float scaleJitter = Random::rand_range(seed + 17u, 0.85, 1.15);

float3 baseColor = resources.baseColor + float3(hueShift, 0.0, -hueShift);
float alpha = saturate(resources.opacity * scaleJitter);

output.color = float4(baseColor, alpha);

Sample Directions for Lighting or Particles

Use the distribution helpers when you need random points or directions with useful geometric meaning, such as hemisphere rays or spawn offsets.

bwsl

import Random

uint seed = uint(input.vertex_id) ^ resources.frameSeed;
float3 N = normalize(input.normal);
float3 bounceDir = Random::rand_cosine_hemisphere(seed, N);
float2 diskOffset = Random::rand_in_circle(seed + 31u) * resources.spawnRadius;

float3 spawnedPosition = input.worldPos + input.tangent * diskOffset.x + input.bitangent * diskOffset.y;
float diffuseProbe = max(dot(N, bounceDir), 0.0);

output.color = float4(resources.probeColor * diffuseProbe, 1.0);

Constants

const uint GOLDEN_RATIO = 0x9E3779B9uconst uint PCG_MULT = 0x5851F42Duconst uint PCG_INC = 0x14057B7Euconst float INV_UINT_MAX = 2.3283064365386963e-10; // 1.0 / (2^32 - 1)

Structs

No structs found.

Enums

No enums found.

Functions

pcg_hash

Based on PCG (Permuted Congruential Generator)

bwsl

pcg_hash :: (uint seed) -> uint

wang_hash

Wang hash - simple and fast, good for spatial hashing

bwsl

wang_hash :: (uint seed) -> uint

xxhash

xxHash-inspired single round - very fast

bwsl

xxhash :: (uint seed) -> uint

hash_combine

Combine two seeds into one (for multi-dimensional seeding)

bwsl

hash_combine :: (uint a, uint b) -> uint

hash2d

Hash a 2D coordinate to a single uint

bwsl

hash2d :: (uint x, uint y) -> uint

hash3d

Hash a 3D coordinate to a single uint

bwsl

hash3d :: (uint x, uint y, uint z) -> uint

uint_to_float

Convert uint hash to float in [0, 1)

bwsl

uint_to_float :: (uint h) -> float

uint_to_float_range

Convert uint hash to float in [lo, hi)

bwsl

uint_to_float_range :: (uint h, float lo, float hi) -> float

rand

Generate random float [0, 1) from seed

bwsl

rand :: (uint seed) -> float

rand_range

Generate random float in [lo, hi) from seed

bwsl

rand_range :: (uint seed, float lo, float hi) -> float

rand2d

Generate random float [0, 1) from 2D position (good for textures/UV)

bwsl

rand2d :: (float2 uv, uint seed) -> float

rand3d

Generate random float [0, 1) from 3D position

bwsl

rand3d :: (float3 pos, uint seed) -> float

rand_float2

Generate random float2 in [0, 1) x [0, 1)

bwsl

rand_float2 :: (uint seed) -> float2

rand_float3

Generate random float3 in [0, 1) x [0, 1) x [0, 1)

bwsl

rand_float3 :: (uint seed) -> float3

rand_float4

Generate random float4 in [0, 1)^4

bwsl

rand_float4 :: (uint seed) -> float4

rand_in_circle

Random point uniformly distributed in unit circle

bwsl

rand_in_circle :: (uint seed) -> float2

rand_on_circle

Random point on unit circle (edge only)

bwsl

rand_on_circle :: (uint seed) -> float2

rand_in_sphere

Random point uniformly distributed in unit sphere

bwsl

rand_in_sphere :: (uint seed) -> float3

rand_direction

Random direction on unit sphere surface (for random directions)

bwsl

rand_direction :: (uint seed) -> float3

rand_hemisphere

Random direction in hemisphere around normal

bwsl

rand_hemisphere :: (uint seed, float3 normal) -> float3

rand_cosine_hemisphere

Cosine-weighted hemisphere sampling (for diffuse lighting)

bwsl

rand_cosine_hemisphere :: (uint seed, float3 normal) -> float3

chance

Returns true with probability p (0.0 to 1.0)

bwsl

chance :: (uint seed, float p) -> bool

rand_index

Returns index [0, count) with uniform probability

bwsl

rand_index :: (uint seed, uint count) -> uint

value_noise

Good for procedural textures

bwsl

value_noise :: (float2 p) -> float

value_noise3d

Value noise 3D (use distinct name to avoid overload resolution issues across modules)

bwsl

value_noise3d :: (float3 p) -> float

fbm

Fractal Brownian Motion (fBm) - layered noise for natural textures

bwsl

fbm :: (float2 p, uint octaves) -> float

fbm3d

3D fBm (use distinct name to avoid overload resolution issues across modules)

bwsl

fbm3d :: (float3 p, uint octaves) -> float

sequence

Each call with same base_seed and different index gives different but deterministic value

bwsl

sequence :: (uint base_seed, uint index) -> float

sequence_float3

Get Nth float3 in a sequence

bwsl

sequence_float3 :: (uint base_seed, uint index) -> float3

interleaved_gradient

From Jimenez 2014 "Next Generation Post Processing in Call of Duty"

bwsl

interleaved_gradient :: (float2 screen_pos) -> float

r2_sequence

Good for sampling patterns

bwsl

r2_sequence :: (uint index) -> float2

Source

Generated from compiler-reference/modules/Random.bwsl.