Skip to main content

openqmc/
lattice.rs

1//! Port of `oqmc/lattice.h` — the rank-1 lattice sampler.
2//!
3//! No cache: samples are computed on the fly with a low per-draw cost. Runtime
4//! performance is high, though the rate of integration per pixel can be lower
5//! than the Sobol or PMJ samplers.
6
7use crate::pcg;
8use crate::rank1::shuffled_rotated_lattice;
9use crate::sampler::{Sampler, SamplerImpl};
10use crate::state::State64Bit;
11
12/// Implementation behind [`LatticeSampler`]. Use it through [`Sampler`].
13#[derive(Clone, Copy, Debug)]
14pub struct LatticeImpl {
15    state: State64Bit,
16}
17
18impl SamplerImpl for LatticeImpl {
19    #[inline]
20    fn from_pixel(x: i32, y: i32, frame: i32, index: i32) -> Self {
21        Self {
22            state: State64Bit::new(x, y, frame, index).pixel_decorrelate(),
23        }
24    }
25
26    #[inline]
27    fn new_domain(&self, key: i32) -> Self {
28        Self {
29            state: self.state.new_domain(key),
30        }
31    }
32
33    #[inline]
34    fn new_domain_split(&self, key: i32, size: i32, index: i32) -> Self {
35        Self {
36            state: self.state.new_domain_split(key, size, index),
37        }
38    }
39
40    #[inline]
41    fn new_domain_distrib(&self, key: i32, index: i32) -> Self {
42        Self {
43            state: self.state.new_domain_distrib(key, index),
44        }
45    }
46
47    #[inline]
48    fn draw_block(&self) -> [u32; 4] {
49        // The lattice takes the raw pattern id (it applies pcg::output / pcg::rng
50        // internally for the shuffle seed and the toroidal shifts).
51        shuffled_rotated_lattice::<4>(self.state.sample_id as u32, self.state.pattern_id)
52    }
53
54    #[inline]
55    fn draw_rnd_block(&self) -> [u32; 4] {
56        self.state.draw_rnd::<4>()
57    }
58
59    #[inline]
60    fn rng(&self) -> pcg::Rng {
61        self.state.rng()
62    }
63}
64
65/// Rank-1 lattice sampler (Hickernell et al.).
66///
67/// Cache-free and the cheapest per draw of the six samplers; the rate of
68/// integration per pixel can be lower than Sobol or PMJ. Prefer it when draw
69/// cost dominates. See [`LatticeBnSampler`](crate::LatticeBnSampler) for the
70/// blue-noise variant.
71///
72/// ```
73/// use openqmc::LatticeSampler;
74///
75/// let root = LatticeSampler::new(12, 34, 0, 7);
76/// let [u, v] = root.new_domain(0).draw_sample_f32::<2>();
77/// assert!((0.0..1.0).contains(&u) && (0.0..1.0).contains(&v));
78/// ```
79pub type LatticeSampler = Sampler<LatticeImpl>;
80
81#[cfg(test)]
82mod tests {
83    use super::*;
84
85    #[test]
86    fn from_pixel_decorrelates_the_state() {
87        let imp = LatticeImpl::from_pixel(3, 4, 5, 6);
88        assert_eq!(imp.state, State64Bit::new(3, 4, 5, 6).pixel_decorrelate());
89    }
90
91    #[test]
92    fn draw_block_is_the_core_on_the_raw_pattern() {
93        let imp = LatticeImpl::from_pixel(3, 4, 5, 6).new_domain(2);
94        assert_eq!(
95            imp.draw_block(),
96            shuffled_rotated_lattice::<4>(imp.state.sample_id as u32, imp.state.pattern_id)
97        );
98        assert_eq!(imp.draw_rnd_block(), imp.state.draw_rnd::<4>());
99        assert_eq!(imp.rng().next_u32(), imp.state.rng().next_u32());
100    }
101
102    #[test]
103    fn domain_methods_forward_to_the_state() {
104        let imp = LatticeImpl::from_pixel(3, 4, 5, 6);
105        assert_eq!(imp.new_domain(1).state, imp.state.new_domain(1));
106        assert_eq!(
107            imp.new_domain_split(1, 2, 1).state,
108            imp.state.new_domain_split(1, 2, 1)
109        );
110        assert_eq!(
111            imp.new_domain_distrib(1, 2).state,
112            imp.state.new_domain_distrib(1, 2)
113        );
114    }
115
116    #[test]
117    fn impl_is_eight_bytes() {
118        assert_eq!(std::mem::size_of::<LatticeImpl>(), 8);
119    }
120}