Skip to main content

qualia_core_db/q42/m64_matter/
banked_lut.rs

1//! Three-Bank 16-KB GPU Constituent Look-Up Table (`BankedConstituentLut`).
2//!
3//! Provides the universal 16-KB GPU UBO/SSBO buffer:
4//! - Bank 0 (`0x00..0x7F`, 128 slots): Pinned global terrestrial baseline.
5//! - Bank 1 (`0x80..0xDF`, 96 slots): Dynamically paged per chunk boundary.
6//! - Bank 2 (`0xE0..0xFF`, 32 slots): Blend window & reactive phase materials.
7
8use super::chunk_directory::M64Error;
9use super::lut_entry::{Q42ConstituentLutEntry, CONSTITUENT_LUT_ENTRY_BYTES};
10
11pub const LUT_TOTAL_ENTRIES: usize = 256;
12pub const BANK_0_PINNED_COUNT: usize = 128;
13pub const BANK_1_PAGED_COUNT: usize = 96;
14pub const BANK_2_BLEND_COUNT: usize = 32;
15
16pub const BANK_0_OFFSET: usize = 0;
17pub const BANK_1_OFFSET: usize = 128;
18pub const BANK_2_OFFSET: usize = 224;
19
20pub const LUT_BUFFER_BYTES: usize = LUT_TOTAL_ENTRIES * CONSTITUENT_LUT_ENTRY_BYTES; // 16,384 bytes (16 KB)
21pub const BANK_1_PAGED_BYTES: usize = BANK_1_PAGED_COUNT * CONSTITUENT_LUT_ENTRY_BYTES; // 6,144 bytes (6 KB)
22
23/// Three-Bank 16-KB Constituent Look-Up Table Manager.
24#[repr(C, align(64))]
25#[derive(Clone, Debug)]
26pub struct BankedConstituentLut {
27    /// 16 KB flat buffer of 256 constituent entries.
28    pub entries: [Q42ConstituentLutEntry; LUT_TOTAL_ENTRIES],
29    /// Epoch identifier of the currently loaded Bank 1 recipe set.
30    pub active_bank_1_epoch_id: u16,
31    /// Dirty flag indicating a GPU DMA re-upload is required.
32    pub is_dirty: bool,
33}
34
35impl Default for BankedConstituentLut {
36    fn default() -> Self {
37        Self::new_with_terrestrial_defaults()
38    }
39}
40
41impl BankedConstituentLut {
42    /// Initialize with certified Australian & terrestrial mineral baseline in Bank 0.
43    pub fn new_with_terrestrial_defaults() -> Self {
44        let mut entries = [Q42ConstituentLutEntry::default(); LUT_TOTAL_ENTRIES];
45
46        // Slot 0: Air / Vacuum
47        entries[0] = Q42ConstituentLutEntry {
48            albedo_rgb_f16: [0, 0, 0],
49            roughness_f16: 0,
50            kubelka_munk_k_s: [0, 0],
51            refractive_index_x100: 100, // 1.00
52            bulk_density_kg_m3: 1,      // 1.2 kg/m³
53            porosity_pct: 100,
54            friction_angle_deg: 0,
55            cohesion_kpa: 0,
56            youngs_modulus_mpa: 0,
57            poissons_ratio_x100: 0,
58            _pad0: 0,
59            permeability_darcy_x100: 65535,
60            suction_head_mm: 0,
61            van_genuchten_n_x100: 0,
62            dielectric_permittivity_x100: 100, // 1.0
63            electrical_conductivity_ms_m: 0,
64            acoustic_p_wave_m_s: 343,
65            ceremonial_permission_mask: 0,
66            canonical_q42_material_hash: 0,
67            provenance_did_hash: 0,
68            _reserved: [0; 4],
69            entry_crc32c: 0,
70        };
71        entries[0].update_crc();
72
73        // Slot 1: Topsoil / Organic Humus
74        entries[1] = Q42ConstituentLutEntry {
75            albedo_rgb_f16: [0x3100, 0x2C00, 0x2800], // Dark rich brown
76            roughness_f16: 0x3C00,                     // 0.8
77            kubelka_munk_k_s: [0x3800, 0x3000],
78            refractive_index_x100: 145,
79            bulk_density_kg_m3: 1300,
80            porosity_pct: 55,
81            friction_angle_deg: 28,
82            cohesion_kpa: 12,
83            youngs_modulus_mpa: 20,
84            poissons_ratio_x100: 35,
85            _pad0: 0,
86            permeability_darcy_x100: 350,
87            suction_head_mm: 250,
88            van_genuchten_n_x100: 130,
89            dielectric_permittivity_x100: 380,
90            electrical_conductivity_ms_m: 25,
91            acoustic_p_wave_m_s: 450,
92            ceremonial_permission_mask: 0,
93            canonical_q42_material_hash: 1,
94            provenance_did_hash: 0,
95            _reserved: [0; 4],
96            entry_crc32c: 0,
97        };
98        entries[1].update_crc();
99
100        // Slot 2: Kaolinite / Silty Clay
101        entries[2] = Q42ConstituentLutEntry {
102            albedo_rgb_f16: [0x3900, 0x3700, 0x3400], // Buff pale tan
103            roughness_f16: 0x3800,
104            kubelka_munk_k_s: [0x3000, 0x3C00],
105            refractive_index_x100: 156,
106            bulk_density_kg_m3: 1750,
107            porosity_pct: 42,
108            friction_angle_deg: 22,
109            cohesion_kpa: 45,
110            youngs_modulus_mpa: 80,
111            poissons_ratio_x100: 40,
112            _pad0: 0,
113            permeability_darcy_x100: 2,
114            suction_head_mm: 800,
115            van_genuchten_n_x100: 115,
116            dielectric_permittivity_x100: 650,
117            electrical_conductivity_ms_m: 120,
118            acoustic_p_wave_m_s: 1450,
119            ceremonial_permission_mask: 0,
120            canonical_q42_material_hash: 2,
121            provenance_did_hash: 0,
122            _reserved: [0; 4],
123            entry_crc32c: 0,
124        };
125        entries[2].update_crc();
126
127        // Slot 3: Quartz Sand / Alluvial Gravel
128        entries[3] = Q42ConstituentLutEntry {
129            albedo_rgb_f16: [0x3A00, 0x3800, 0x3200], // Golden sand
130            roughness_f16: 0x3400,
131            kubelka_munk_k_s: [0x2C00, 0x3E00],
132            refractive_index_x100: 154,
133            bulk_density_kg_m3: 2050,
134            porosity_pct: 32,
135            friction_angle_deg: 36,
136            cohesion_kpa: 0,
137            youngs_modulus_mpa: 150,
138            poissons_ratio_x100: 25,
139            _pad0: 0,
140            permeability_darcy_x100: 850,
141            suction_head_mm: 80,
142            van_genuchten_n_x100: 210,
143            dielectric_permittivity_x100: 450,
144            electrical_conductivity_ms_m: 4,
145            acoustic_p_wave_m_s: 1850,
146            ceremonial_permission_mask: 0,
147            canonical_q42_material_hash: 3,
148            provenance_did_hash: 0,
149            _reserved: [0; 4],
150            entry_crc32c: 0,
151        };
152        entries[3].update_crc();
153
154        // Slot 4: Weathered Clasts / Silcrete
155        entries[4] = Q42ConstituentLutEntry {
156            albedo_rgb_f16: [0x3600, 0x3300, 0x3000],
157            roughness_f16: 0x3A00,
158            kubelka_munk_k_s: [0x3200, 0x3600],
159            refractive_index_x100: 158,
160            bulk_density_kg_m3: 2300,
161            porosity_pct: 18,
162            friction_angle_deg: 40,
163            cohesion_kpa: 150,
164            youngs_modulus_mpa: 12000,
165            poissons_ratio_x100: 22,
166            _pad0: 0,
167            permeability_darcy_x100: 15,
168            suction_head_mm: 350,
169            van_genuchten_n_x100: 160,
170            dielectric_permittivity_x100: 520,
171            electrical_conductivity_ms_m: 10,
172            acoustic_p_wave_m_s: 2900,
173            ceremonial_permission_mask: 0,
174            canonical_q42_material_hash: 4,
175            provenance_did_hash: 0,
176            _reserved: [0; 4],
177            entry_crc32c: 0,
178        };
179        entries[4].update_crc();
180
181        // Slot 5: Fractured Basalt / Monaro Volcanics
182        entries[5] = Q42ConstituentLutEntry {
183            albedo_rgb_f16: [0x2900, 0x2900, 0x2A00], // Dark charcoal/slate
184            roughness_f16: 0x3200,
185            kubelka_munk_k_s: [0x3C00, 0x2800],
186            refractive_index_x100: 162,
187            bulk_density_kg_m3: 2800,
188            porosity_pct: 8,
189            friction_angle_deg: 45,
190            cohesion_kpa: 1200,
191            youngs_modulus_mpa: 45000,
192            poissons_ratio_x100: 20,
193            _pad0: 0,
194            permeability_darcy_x100: 1,
195            suction_head_mm: 50,
196            van_genuchten_n_x100: 140,
197            dielectric_permittivity_x100: 750,
198            electrical_conductivity_ms_m: 2,
199            acoustic_p_wave_m_s: 4800,
200            ceremonial_permission_mask: 0,
201            canonical_q42_material_hash: 5,
202            provenance_did_hash: 0,
203            _reserved: [0; 4],
204            entry_crc32c: 0,
205        };
206        entries[5].update_crc();
207
208        // Slot 6: Solid Granitic Bedrock
209        entries[6] = Q42ConstituentLutEntry {
210            albedo_rgb_f16: [0x3800, 0x3700, 0x3600], // Mottled pale granite
211            roughness_f16: 0x2E00,
212            kubelka_munk_k_s: [0x2E00, 0x3A00],
213            refractive_index_x100: 155,
214            bulk_density_kg_m3: 2700,
215            porosity_pct: 1,
216            friction_angle_deg: 52,
217            cohesion_kpa: 5000,
218            youngs_modulus_mpa: 60000,
219            poissons_ratio_x100: 18,
220            _pad0: 0,
221            permeability_darcy_x100: 0,
222            suction_head_mm: 10,
223            van_genuchten_n_x100: 100,
224            dielectric_permittivity_x100: 600,
225            electrical_conductivity_ms_m: 1,
226            acoustic_p_wave_m_s: 5800,
227            ceremonial_permission_mask: 0,
228            canonical_q42_material_hash: 6,
229            provenance_did_hash: 0,
230            _reserved: [0; 4],
231            entry_crc32c: 0,
232        };
233        entries[6].update_crc();
234
235        // Slot 7: Fresh Water (Surface flow / riverbed)
236        entries[7] = Q42ConstituentLutEntry {
237            albedo_rgb_f16: [0x2800, 0x3400, 0x3800], // Blue-cyan tint
238            roughness_f16: 0x1400,                     // 0.05 mirror smooth
239            kubelka_munk_k_s: [0x1000, 0x1000],
240            refractive_index_x100: 133, // 1.333
241            bulk_density_kg_m3: 1000,
242            porosity_pct: 100,
243            friction_angle_deg: 0,
244            cohesion_kpa: 0,
245            youngs_modulus_mpa: 2200, // Bulk modulus ~2.2 GPa
246            poissons_ratio_x100: 50,
247            _pad0: 0,
248            permeability_darcy_x100: 65535,
249            suction_head_mm: 0,
250            van_genuchten_n_x100: 0,
251            dielectric_permittivity_x100: 8000, // ε_r = 80.0
252            electrical_conductivity_ms_m: 50,
253            acoustic_p_wave_m_s: 1482,
254            ceremonial_permission_mask: 0,
255            canonical_q42_material_hash: 7,
256            provenance_did_hash: 0,
257            _reserved: [0; 4],
258            entry_crc32c: 0,
259        };
260        entries[7].update_crc();
261
262        // Update remaining slots in Bank 0
263        for i in 8..BANK_0_PINNED_COUNT {
264            entries[i].update_crc();
265        }
266
267        Self {
268            entries,
269            active_bank_1_epoch_id: 0,
270            is_dirty: true,
271        }
272    }
273
274    /// Dynamically page Bank 1 (slots 128..223, 6 KB) without modifying Bank 0 or Bank 2.
275    pub fn page_bank_1(
276        &mut self,
277        epoch_id: u16,
278        paged_recipes: &[Q42ConstituentLutEntry; BANK_1_PAGED_COUNT],
279    ) -> Result<(), M64Error> {
280        self.entries[BANK_1_OFFSET..BANK_1_OFFSET + BANK_1_PAGED_COUNT]
281            .copy_from_slice(paged_recipes);
282        self.active_bank_1_epoch_id = epoch_id;
283        self.is_dirty = true;
284        Ok(())
285    }
286
287    /// Zero-copy cast into uniform/storage buffer upload byte slice (16,384 bytes).
288    #[inline]
289    pub fn as_gpu_bytes(&self) -> &[u8] {
290        bytemuck::cast_slice(&self.entries)
291    }
292
293    /// Read entry by index (0..255).
294    #[inline]
295    pub fn entry(&self, index: u8) -> &Q42ConstituentLutEntry {
296        &self.entries[index as usize]
297    }
298
299    /// Mutable access to entry by index.
300    #[inline]
301    pub fn entry_mut(&mut self, index: u8) -> &mut Q42ConstituentLutEntry {
302        self.is_dirty = true;
303        &mut self.entries[index as usize]
304    }
305}