1use std::sync::OnceLock;
11
12use crate::encode::{EncodeKey, decode_bits16, encode_bits16};
13
14pub const XBITS: u32 = 8;
16pub const YBITS: u32 = 8;
18pub const SIZE: usize = 1 << (XBITS + YBITS);
20
21#[derive(Clone, Copy, Debug)]
23pub struct TableReturnValue {
24 pub key: u32,
26 pub rank: u32,
28}
29
30#[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 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 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 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}