Skip to main content

openqmc/
lib.rs

1//! # openqmc
2//!
3//! A faithful Rust port of [AcademySoftwareFoundation/openqmc][upstream]
4//! (Apache-2.0), the quasi-Monte Carlo sampling library. It provides three base
5//! samplers — Owen-scrambled [`SobolSampler`], rank-1 [`LatticeSampler`], and
6//! progressive multi-jittered [`PmjSampler`] — each with a blue-noise variant
7//! ([`SobolBnSampler`], [`LatticeBnSampler`], [`PmjBnSampler`]), all behind a
8//! single pass-by-value **domain-tree** API ([`Sampler`]).
9//!
10//! ## Domain-tree usage
11//!
12//! Construct a root sampler per (pixel, frame, sample-index), derive independent
13//! 4-dimensional sub-patterns with [`Sampler::new_domain`] (padding), and draw up
14//! to four dimensions per domain:
15//!
16//! ```
17//! use openqmc::SobolSampler;
18//!
19//! let root = SobolSampler::new(/* x */ 12, /* y */ 34, /* frame */ 0, /* index */ 7);
20//! let camera = root.new_domain(0);
21//! let [jitter_x, jitter_y, lens_u, lens_v] = camera.draw_sample_f32::<4>();
22//! let bounce = root.new_domain(1);
23//! let dir = bounce.draw_sample_f32::<2>();
24//! # let _ = (jitter_x, jitter_y, lens_u, lens_v, dir);
25//! ```
26//!
27//! Use [`Sampler::draw_sample`] for the high-quality stratified dimensions and
28//! [`Sampler::draw_rnd`] / [`Sampler::rng`] for incidental or unbounded random
29//! draws (Russian roulette, delta tracking) where stratification does not apply.
30//!
31//! ## Relationship to the C++ headers
32//!
33//! Modules map one-to-one to the upstream `oqmc/*.h` headers, with the same
34//! algorithms and (bit-for-bit) the same sample values. Two idiomatic
35//! adaptations: the caller-allocated `void*` cache — a GPU memory-management
36//! concern — becomes a lazily-initialised process global, so every [`Sampler`]
37//! stays a small `Copy + Send` value; and the sequential PRNG (`pcg::Rng`) is
38//! surfaced as a named type. The bundled blue-noise tables under `src/data/` are
39//! the upstream optimised tables converted verbatim to little-endian blobs.
40//!
41//! [upstream]: https://github.com/AcademySoftwareFoundation/openqmc
42
43#![forbid(unsafe_code)]
44#![warn(missing_docs)]
45#![deny(rustdoc::broken_intra_doc_links)]
46
47// Utilities (oqmc/*.h leaf headers).
48pub mod encode;
49pub mod float;
50pub mod pcg;
51pub mod permute;
52pub mod range;
53pub mod reverse;
54pub mod rotate;
55
56// Sequence cores.
57pub mod lookup;
58pub mod owen;
59pub mod rank1;
60pub mod stochastic;
61
62// State + generic interface.
63pub mod sampler;
64pub mod state;
65
66// Samplers.
67pub mod bntables;
68pub mod lattice;
69pub mod latticebn;
70pub mod pmj;
71pub mod pmjbn;
72pub mod sobol;
73pub mod sobolbn;
74
75// Re-export the public surface at the crate root, mirroring the `oqmc::`
76// namespace.
77pub use sampler::{Sampler, SamplerImpl};
78pub use state::State64Bit;
79
80pub use lattice::LatticeSampler;
81pub use latticebn::LatticeBnSampler;
82pub use pmj::PmjSampler;
83pub use pmjbn::PmjBnSampler;
84pub use sobol::SobolSampler;
85pub use sobolbn::SobolBnSampler;