Skip to main content

openqmc/
sobolbn.rs

1//! Port of `oqmc/sobolbn.h` — the blue-noise variant of the Sobol sampler.
2//! Same sequence as [`SobolSampler`](crate::SobolSampler), plus spatial
3//! blue-noise dithering between pixels (progressive pixel sampling). Note it
4//! does *not* pixel-decorrelate the state; the per-pixel (key, rank) table
5//! lookup provides the decorrelation.
6
7use crate::bntables::{self, table_value};
8use crate::owen::shuffled_scrambled_sobol;
9use crate::pcg;
10use crate::sampler::{Sampler, SamplerImpl};
11use crate::state::State64Bit;
12
13/// Implementation behind [`SobolBnSampler`]. Use it through [`Sampler`].
14#[derive(Clone, Copy, Debug)]
15pub struct SobolBnImpl {
16    state: State64Bit,
17    key_table: &'static [u32],
18    rank_table: &'static [u32],
19}
20
21impl SamplerImpl for SobolBnImpl {
22    #[inline]
23    fn from_pixel(x: i32, y: i32, frame: i32, index: i32) -> Self {
24        Self {
25            state: State64Bit::new(x, y, frame, index),
26            key_table: bntables::sobol::key_table(),
27            rank_table: bntables::sobol::rank_table(),
28        }
29    }
30
31    #[inline]
32    fn new_domain(&self, key: i32) -> Self {
33        Self {
34            state: self.state.new_domain(key),
35            ..*self
36        }
37    }
38
39    #[inline]
40    fn new_domain_split(&self, key: i32, size: i32, index: i32) -> Self {
41        Self {
42            state: self.state.new_domain_split(key, size, index),
43            ..*self
44        }
45    }
46
47    #[inline]
48    fn new_domain_distrib(&self, key: i32, index: i32) -> Self {
49        Self {
50            state: self.state.new_domain_distrib(key, index),
51            ..*self
52        }
53    }
54
55    #[inline]
56    fn draw_block(&self) -> [u32; 4] {
57        let t = table_value::<8, 8, 0>(
58            self.state.pixel_id,
59            pcg::output(self.state.pattern_id) as u16,
60            self.key_table,
61            self.rank_table,
62        );
63        shuffled_scrambled_sobol::<4>(self.state.sample_id as u32 ^ t.rank, t.key)
64    }
65
66    #[inline]
67    fn draw_rnd_block(&self) -> [u32; 4] {
68        self.state
69            .new_domain(self.state.pixel_id as i32)
70            .draw_rnd::<4>()
71    }
72
73    #[inline]
74    fn rng(&self) -> pcg::Rng {
75        self.state.new_domain(self.state.pixel_id as i32).rng()
76    }
77
78    fn warm_cache() {
79        bntables::sobol::key_table();
80        bntables::sobol::rank_table();
81    }
82}
83
84/// Blue-noise variant of the [`SobolSampler`](crate::SobolSampler).
85///
86/// Same sequence, plus a per-pixel key/rank table lookup that distributes the
87/// residual error as blue noise across the image — easier on the eye and on
88/// denoisers. A good default if you are unsure which sampler to pick. The
89/// tables decode lazily on first draw; call `SobolBnSampler::warm_cache()` to
90/// pay that cost up front.
91///
92/// ```
93/// use openqmc::SobolBnSampler;
94///
95/// let root = SobolBnSampler::new(12, 34, 0, 7);
96/// let [u, v] = root.new_domain(0).draw_sample_f32::<2>();
97/// assert!((0.0..1.0).contains(&u) && (0.0..1.0).contains(&v));
98/// ```
99pub type SobolBnSampler = Sampler<SobolBnImpl>;
100
101#[cfg(test)]
102mod tests {
103    use super::*;
104
105    #[test]
106    fn from_pixel_keeps_the_state_correlated() {
107        let imp = SobolBnImpl::from_pixel(3, 4, 5, 6);
108        assert_eq!(imp.state, State64Bit::new(3, 4, 5, 6));
109        assert!(std::ptr::eq(imp.key_table, bntables::sobol::key_table()));
110        assert!(std::ptr::eq(imp.rank_table, bntables::sobol::rank_table()));
111    }
112
113    #[test]
114    fn domain_methods_keep_the_tables() {
115        let imp = SobolBnImpl::from_pixel(3, 4, 5, 6);
116        for child in [
117            imp.new_domain(1),
118            imp.new_domain_split(1, 2, 1),
119            imp.new_domain_distrib(1, 2),
120        ] {
121            assert!(std::ptr::eq(child.key_table, imp.key_table));
122            assert!(std::ptr::eq(child.rank_table, imp.rank_table));
123        }
124        assert_eq!(imp.new_domain(1).state, imp.state.new_domain(1));
125    }
126
127    #[test]
128    fn draw_block_reads_the_table_shifted_by_the_pattern() {
129        let imp = SobolBnImpl::from_pixel(3, 4, 5, 6).new_domain(2);
130        let t = table_value::<8, 8, 0>(
131            imp.state.pixel_id,
132            pcg::output(imp.state.pattern_id) as u16,
133            imp.key_table,
134            imp.rank_table,
135        );
136        assert_eq!(
137            imp.draw_block(),
138            shuffled_scrambled_sobol::<4>(imp.state.sample_id as u32 ^ t.rank, t.key)
139        );
140    }
141
142    #[test]
143    fn rnd_paths_decorrelate_by_pixel() {
144        let imp = SobolBnImpl::from_pixel(3, 4, 5, 6).new_domain(2);
145        let expected = imp.state.new_domain(imp.state.pixel_id as i32);
146        assert_eq!(imp.draw_rnd_block(), expected.draw_rnd::<4>());
147        assert_eq!(imp.rng().next_u32(), expected.rng().next_u32());
148    }
149
150    #[test]
151    fn warm_cache_decodes_the_tables() {
152        SobolBnImpl::warm_cache();
153        SobolBnSampler::warm_cache();
154        assert_eq!(bntables::sobol::key_table().len(), bntables::SIZE);
155    }
156}