Skip to main content

openqmc/
latticebn.rs

1//! Port of `oqmc/latticebn.h` — the blue-noise variant of the rank-1 lattice
2//! sampler. Same sequence as [`LatticeSampler`](crate::LatticeSampler), plus
3//! spatial blue-noise dithering between pixels. State is not
4//! pixel-decorrelated (the table lookup does that).
5
6use crate::bntables::{self, table_value};
7use crate::pcg;
8use crate::rank1::shuffled_rotated_lattice;
9use crate::sampler::{Sampler, SamplerImpl};
10use crate::state::State64Bit;
11
12/// Implementation behind [`LatticeBnSampler`]. Use it through [`Sampler`].
13#[derive(Clone, Copy, Debug)]
14pub struct LatticeBnImpl {
15    state: State64Bit,
16    key_table: &'static [u32],
17    rank_table: &'static [u32],
18}
19
20impl SamplerImpl for LatticeBnImpl {
21    #[inline]
22    fn from_pixel(x: i32, y: i32, frame: i32, index: i32) -> Self {
23        Self {
24            state: State64Bit::new(x, y, frame, index),
25            key_table: bntables::lattice::key_table(),
26            rank_table: bntables::lattice::rank_table(),
27        }
28    }
29
30    #[inline]
31    fn new_domain(&self, key: i32) -> Self {
32        Self {
33            state: self.state.new_domain(key),
34            ..*self
35        }
36    }
37
38    #[inline]
39    fn new_domain_split(&self, key: i32, size: i32, index: i32) -> Self {
40        Self {
41            state: self.state.new_domain_split(key, size, index),
42            ..*self
43        }
44    }
45
46    #[inline]
47    fn new_domain_distrib(&self, key: i32, index: i32) -> Self {
48        Self {
49            state: self.state.new_domain_distrib(key, index),
50            ..*self
51        }
52    }
53
54    #[inline]
55    fn draw_block(&self) -> [u32; 4] {
56        let t = table_value::<8, 8, 0>(
57            self.state.pixel_id,
58            pcg::output(self.state.pattern_id) as u16,
59            self.key_table,
60            self.rank_table,
61        );
62        shuffled_rotated_lattice::<4>(self.state.sample_id as u32 ^ t.rank, t.key)
63    }
64
65    #[inline]
66    fn draw_rnd_block(&self) -> [u32; 4] {
67        self.state
68            .new_domain(self.state.pixel_id as i32)
69            .draw_rnd::<4>()
70    }
71
72    #[inline]
73    fn rng(&self) -> pcg::Rng {
74        self.state.new_domain(self.state.pixel_id as i32).rng()
75    }
76
77    fn warm_cache() {
78        bntables::lattice::key_table();
79        bntables::lattice::rank_table();
80    }
81}
82
83/// Blue-noise variant of the [`LatticeSampler`](crate::LatticeSampler).
84///
85/// Same sequence, plus a per-pixel key/rank table lookup that distributes the
86/// residual error as blue noise across the image. The tables decode lazily on
87/// first draw; call `LatticeBnSampler::warm_cache()` to pay that cost up front.
88///
89/// ```
90/// use openqmc::LatticeBnSampler;
91///
92/// let root = LatticeBnSampler::new(12, 34, 0, 7);
93/// let [u, v] = root.new_domain(0).draw_sample_f32::<2>();
94/// assert!((0.0..1.0).contains(&u) && (0.0..1.0).contains(&v));
95/// ```
96pub type LatticeBnSampler = Sampler<LatticeBnImpl>;
97
98#[cfg(test)]
99mod tests {
100    use super::*;
101
102    #[test]
103    fn from_pixel_keeps_the_state_correlated() {
104        let imp = LatticeBnImpl::from_pixel(3, 4, 5, 6);
105        assert_eq!(imp.state, State64Bit::new(3, 4, 5, 6));
106        assert!(std::ptr::eq(imp.key_table, bntables::lattice::key_table()));
107        assert!(std::ptr::eq(
108            imp.rank_table,
109            bntables::lattice::rank_table()
110        ));
111    }
112
113    #[test]
114    fn domain_methods_keep_the_tables() {
115        let imp = LatticeBnImpl::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 = LatticeBnImpl::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_rotated_lattice::<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 = LatticeBnImpl::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        LatticeBnImpl::warm_cache();
153        LatticeBnSampler::warm_cache();
154        assert_eq!(bntables::lattice::key_table().len(), bntables::SIZE);
155    }
156}