Skip to main content

openqmc/
bntables.rs

1//! Port of `oqmc/bntables.h` — pre-computed, optimised blue-noise key/rank
2//! tables used to give the base samplers a spatial blue-noise error
3//! distribution (generalising Belcour & Heitz). A single table pair serves all
4//! domains: the lookup is shifted toroidally per domain by a random offset.
5//!
6//! The upstream tables ship as text headers; this port bundles them as
7//! little-endian binary blobs (converted 1:1 from `include/oqmc/data/**`) and
8//! decodes them lazily into process globals.
9
10use std::sync::OnceLock;
11
12use crate::encode::{EncodeKey, decode_bits16, encode_bits16};
13
14/// Pixel-x precision for the tables (256 pixels).
15pub const XBITS: u32 = 8;
16/// Pixel-y precision for the tables (256 pixels).
17pub const YBITS: u32 = 8;
18/// Table length (2^16).
19pub const SIZE: usize = 1 << (XBITS + YBITS);
20
21/// A key/rank pair used to randomise a sequence.
22#[derive(Clone, Copy, Debug)]
23pub struct TableReturnValue {
24    /// Scramble key for the sequence at this pixel.
25    pub key: u32,
26    /// Sample-index rank (XORed into the index) for this pixel.
27    pub rank: u32,
28}
29
30/// Look up a key/rank pair, shifting the pixel coordinate toroidally by `shift`.
31#[inline]
32pub fn table_value<const XB: u32, const YB: u32, const ZB: u32>(
33    pixel: u16,
34    shift: u16,
35    key_table: &[u32],
36    rank_table: &[u32],
37) -> TableReturnValue {
38    let p = decode_bits16::<XB, YB, ZB>(pixel);
39    let s = decode_bits16::<XB, YB, ZB>(shift);
40    let index = encode_bits16::<XB, YB, ZB>(EncodeKey {
41        x: p.x + s.x,
42        y: p.y + s.y,
43        z: p.z + s.z,
44    }) as usize;
45
46    TableReturnValue {
47        key: key_table[index],
48        rank: rank_table[index],
49    }
50}
51
52fn decode_table(bytes: &'static [u8]) -> Box<[u32]> {
53    debug_assert_eq!(bytes.len(), SIZE * 4);
54    bytes
55        .chunks_exact(4)
56        .map(|c| u32::from_le_bytes([c[0], c[1], c[2], c[3]]))
57        .collect()
58}
59
60macro_rules! table_pair {
61    ($module:ident, $keys:literal, $ranks:literal) => {
62        #[doc = concat!("Optimised blue-noise key/rank tables for the ", stringify!($module), " sampler, decoded lazily from the bundled blobs.")]
63        pub mod $module {
64            use super::{OnceLock, decode_table};
65
66            /// Optimised blue-noise key table.
67            pub fn key_table() -> &'static [u32] {
68                static T: OnceLock<Box<[u32]>> = OnceLock::new();
69                T.get_or_init(|| decode_table(include_bytes!($keys)))
70            }
71
72            /// Optimised blue-noise rank table.
73            pub fn rank_table() -> &'static [u32] {
74                static T: OnceLock<Box<[u32]>> = OnceLock::new();
75                T.get_or_init(|| decode_table(include_bytes!($ranks)))
76            }
77        }
78    };
79}
80
81table_pair!(sobol, "data/sobol_keys.bin", "data/sobol_ranks.bin");
82table_pair!(lattice, "data/lattice_keys.bin", "data/lattice_ranks.bin");
83table_pair!(pmj, "data/pmj_keys.bin", "data/pmj_ranks.bin");
84
85#[cfg(test)]
86mod tests {
87    use super::*;
88
89    #[test]
90    fn tables_decode_to_full_length() {
91        assert_eq!(sobol::key_table().len(), SIZE);
92        assert_eq!(sobol::rank_table().len(), SIZE);
93        assert_eq!(lattice::key_table().len(), SIZE);
94        assert_eq!(pmj::rank_table().len(), SIZE);
95    }
96
97    #[test]
98    fn tables_decode_little_endian() {
99        let raw: &[u8] = include_bytes!("data/sobol_keys.bin");
100        let first = u32::from_le_bytes([raw[0], raw[1], raw[2], raw[3]]);
101        let last = u32::from_le_bytes([
102            raw[raw.len() - 4],
103            raw[raw.len() - 3],
104            raw[raw.len() - 2],
105            raw[raw.len() - 1],
106        ]);
107        assert_eq!(sobol::key_table()[0], first);
108        assert_eq!(sobol::key_table()[SIZE - 1], last);
109    }
110
111    #[test]
112    fn all_six_blobs_have_the_expected_size() {
113        assert_eq!(include_bytes!("data/sobol_keys.bin").len(), SIZE * 4);
114        assert_eq!(include_bytes!("data/sobol_ranks.bin").len(), SIZE * 4);
115        assert_eq!(include_bytes!("data/lattice_keys.bin").len(), SIZE * 4);
116        assert_eq!(include_bytes!("data/lattice_ranks.bin").len(), SIZE * 4);
117        assert_eq!(include_bytes!("data/pmj_keys.bin").len(), SIZE * 4);
118        assert_eq!(include_bytes!("data/pmj_ranks.bin").len(), SIZE * 4);
119    }
120
121    #[test]
122    fn tables_are_decoded_once() {
123        assert!(std::ptr::eq(pmj::key_table(), pmj::key_table()));
124        assert!(std::ptr::eq(lattice::rank_table(), lattice::rank_table()));
125    }
126
127    #[test]
128    fn ranks_are_below_128() {
129        for t in [
130            sobol::rank_table(),
131            lattice::rank_table(),
132            pmj::rank_table(),
133        ] {
134            assert!(t.iter().all(|&r| r < 128));
135        }
136    }
137
138    #[test]
139    fn table_value_with_zero_shift_is_a_direct_index() {
140        let keys = sobol::key_table();
141        let ranks = sobol::rank_table();
142        for p in [0u16, 1, 255, 256, 65535] {
143            let t = table_value::<XBITS, YBITS, 0>(p, 0, keys, ranks);
144            assert_eq!(t.key, keys[p as usize]);
145            assert_eq!(t.rank, ranks[p as usize]);
146        }
147    }
148
149    #[test]
150    fn table_value_shift_wraps_toroidally() {
151        let keys = sobol::key_table();
152        let ranks = sobol::rank_table();
153        // pixel (255, 255) shifted by (1, 1) lands on (0, 0).
154        let t = table_value::<XBITS, YBITS, 0>(0xffff, 0x0101, keys, ranks);
155        assert_eq!(t.key, keys[0]);
156        assert_eq!(t.rank, ranks[0]);
157    }
158}