Expand description
§openqmc
A faithful Rust port of AcademySoftwareFoundation/openqmc
(Apache-2.0), the quasi-Monte Carlo sampling library. It provides three base
samplers — Owen-scrambled SobolSampler, rank-1 LatticeSampler, and
progressive multi-jittered PmjSampler — each with a blue-noise variant
(SobolBnSampler, LatticeBnSampler, PmjBnSampler), all behind a
single pass-by-value domain-tree API (Sampler).
§Domain-tree usage
Construct a root sampler per (pixel, frame, sample-index), derive independent
4-dimensional sub-patterns with Sampler::new_domain (padding), and draw up
to four dimensions per domain:
use openqmc::SobolSampler;
let root = SobolSampler::new(/* x */ 12, /* y */ 34, /* frame */ 0, /* index */ 7);
let camera = root.new_domain(0);
let [jitter_x, jitter_y, lens_u, lens_v] = camera.draw_sample_f32::<4>();
let bounce = root.new_domain(1);
let dir = bounce.draw_sample_f32::<2>();Use Sampler::draw_sample for the high-quality stratified dimensions and
Sampler::draw_rnd / Sampler::rng for incidental or unbounded random
draws (Russian roulette, delta tracking) where stratification does not apply.
§Relationship to the C++ headers
Modules map one-to-one to the upstream oqmc/*.h headers, with the same
algorithms and (bit-for-bit) the same sample values. Two idiomatic
adaptations: the caller-allocated void* cache — a GPU memory-management
concern — becomes a lazily-initialised process global, so every Sampler
stays a small Copy + Send value; and the sequential PRNG (pcg::Rng) is
surfaced as a named type. The bundled blue-noise tables under src/data/ are
the upstream optimised tables converted verbatim to little-endian blobs.
Re-exports§
pub use sampler::Sampler;pub use sampler::SamplerImpl;pub use state::State64Bit;pub use lattice::LatticeSampler;pub use latticebn::LatticeBnSampler;pub use pmj::PmjSampler;pub use pmjbn::PmjBnSampler;pub use sobol::SobolSampler;pub use sobolbn::SobolBnSampler;
Modules§
- bntables
- Port of
oqmc/bntables.h— pre-computed, optimised blue-noise key/rank tables used to give the base samplers a spatial blue-noise error distribution (generalising Belcour & Heitz). A single table pair serves all domains: the lookup is shifted toroidally per domain by a random offset. - encode
- Port of
oqmc/encode.h— pack/unpack a 3-axis integer coordinate key into a single 16-bit value. Used to store pixel coordinates compactly. The sum of the per-axis bit precisions must not exceed 16. - float
- Port of
oqmc/float.h— integer to[0, 1)float conversion. - lattice
- Port of
oqmc/lattice.h— the rank-1 lattice sampler. - latticebn
- Port of
oqmc/latticebn.h— the blue-noise variant of the rank-1 lattice sampler. Same sequence asLatticeSampler, plus spatial blue-noise dithering between pixels. State is not pixel-decorrelated (the table lookup does that). - lookup
- Port of
oqmc/lookup.h— randomised table lookups. A single pre-computed table (PMJ samples, blue-noise ranks) can be re-used across domains by shuffling the index and XOR-scrambling the value (random digit scramble, Kollig & Keller). - owen
- Port of
oqmc/owen.h— Owen-scrambled SZ sequences via Brent Burley’s hash-based construction (“Practical Hash-based Owen Scrambling”). - pcg
- Port of
oqmc/pcg.h— the PCG-RXS-M-XS-32 PRNG by Melissa O’Neill, used both as a classic sequential PRNG and (viahash) as a stateless parallel hash function per Jarzynski & Olano, “Hash Functions for GPU Rendering”. Constants are taken from https://github.com/imneme/pcg-c. - permute
- Port of
oqmc/permute.h— hash-based permutations. A Laine & Karras style permutation (from “Stratified Sampling for Stochastic Transparency”), with the improved constants from Nathan Vegdahl’s “Building a Better LK Hash”. Combined with bit reversal before and after, this forms an efficient hash-based Owen scramble. - pmj
- Port of
oqmc/pmj.h— the progressive multi-jittered (0,2) sampler. - pmjbn
- Port of
oqmc/pmjbn.h— the blue-noise variant of the PMJ sampler. Same sequence asPmjSampler, plus spatial blue-noise dithering between pixels. It shares the PMJ sample cache and adds the blue-noise key/rank tables. State is not pixel-decorrelated (the table lookup does that). - range
- Port of
oqmc/range.h— map a full-range 32-bit integer into a bounded range using the high-bits-preserving multiplication method (Lemire 2019), which keeps the good high-order bits of QMC sequences and weak PRNGs alike. Prefer this over modulo. A small bias remains at large non-power-of-two ranges (no rejection loop, by design). - rank1
- Port of
oqmc/rank1.h— a rank-1 lattice (Hickernell et al., “Weighted Compound Integration Rules with Higher Order Convergence for all N”) made progressive with a radical inversion of the sample index, randomised with toroidal shifts. - reverse
- Port of
oqmc/reverse.h— bit reversal (radical inversion / Van der Corput). - rotate
- Port of
oqmc/rotate.h— bit/byte rotation, used to extract fresh random values from an existing hash or RNG number. - sampler
- Port of
oqmc/sampler.h— the public, static-polymorphic sampler interface. - sobol
- Port of
oqmc/sobol.h— the Owen-scrambled Sobol sampler. - sobolbn
- Port of
oqmc/sobolbn.h— the blue-noise variant of the Sobol sampler. Same sequence asSobolSampler, plus spatial blue-noise dithering between pixels (progressive pixel sampling). Note it does not pixel-decorrelate the state; the per-pixel (key, rank) table lookup provides the decorrelation. - state
- Port of
oqmc/state.h— the generic 8-byte sampler state shared by all sampler implementations. Small enough to pass by value; carries the pattern/sample/pixel identifiers and the domain-tree mutations. - stochastic
- Port of
oqmc/stochastic.h— progressive multi-jittered (0,2) sequence construction (Helmer et al., “Stochastic Generation of (t,s) Sample Sequences”). Builds the first pair of dimensions; the second pair is a randomisation of the first. Used to fill the PMJ sampler’s cache.