Skip to main content

openqmc/
pmjbn.rs

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