Skip to main content

qualia_core_db/render/gpu/
emf_cue_bridge.rs

1//! GPU Uniform/Voxel Packer for EMF, Acoustic & Physical Field Cues (`BS-40`).
2//!
3//! Provides zero-heap GPU layout translation for physical field cues into 64-byte
4//! flat `repr(C)` descriptors for WebGPU / Etalon storage and uniform buffers.
5//! Enforces honest calibration flags: uncalibrated bands are either rejected or
6//! tagged with `uncalibrated_flag = 1` for warning overlay rendering.
7//!
8//! Strictly zero heap in hot paths (Tier-1 contract, `AGENTS.md` ยง0-A).
9
10#[cfg(test)]
11use crate::modalities::typed_cue_profile::{
12    CalibrationStatus, PhysicalCueDomain, PhysicalUnitKind,
13};
14use crate::modalities::typed_cue_profile::{CueEvaluationError, PhysicalCueEmission};
15use bytemuck::{Pod, Zeroable};
16
17/// 64-byte GPU storage/uniform buffer descriptor for physical cues.
18///
19/// Layout is aligned to 8 bytes and exactly 64 bytes in size for direct GPU buffer upload.
20/// `uncalibrated_flag = 1` triggers HUD warning badges for uncalibrated overlay modes.
21#[repr(C)]
22#[derive(Debug, Clone, Copy, PartialEq, Pod, Zeroable)]
23pub struct EmfAcousticGpuDescriptor {
24    pub source_entity_did: u64,
25    pub source_organ_id: u64,
26    pub band_min: f32,
27    pub band_max: f32,
28    pub magnitude: f32,
29    pub polarization_deg: f32,
30    pub domain_code: u32,
31    pub unit_code: u32,
32    pub calibration_code: u32,
33    pub uncalibrated_flag: u32,
34    pub _reserved: [u32; 4],
35}
36
37const _: () = {
38    assert!(std::mem::size_of::<EmfAcousticGpuDescriptor>() == 64);
39    assert!(std::mem::align_of::<EmfAcousticGpuDescriptor>() == 8);
40};
41
42impl Default for EmfAcousticGpuDescriptor {
43    fn default() -> Self {
44        Self {
45            source_entity_did: 0,
46            source_organ_id: 0,
47            band_min: 0.0,
48            band_max: 0.0,
49            magnitude: 0.0,
50            polarization_deg: -1.0,
51            domain_code: 0,
52            unit_code: 0,
53            calibration_code: 0,
54            uncalibrated_flag: 0,
55            _reserved: [0; 4],
56        }
57    }
58}
59
60impl EmfAcousticGpuDescriptor {
61    #[inline(always)]
62    pub fn is_uncalibrated(&self) -> bool {
63        self.uncalibrated_flag != 0
64    }
65}
66
67/// Packs physical cue emissions into GPU descriptors with zero heap allocations.
68///
69/// # Mandatory BS-40 Negative Cases
70/// - If `allow_uncalibrated_overlay == false` and any cue in `cues` is uncalibrated
71///   (`UncalibratedTheoretical` or `OutOfSensorRange`), returns `Err(CueEvaluationError::UncalibratedBand)`.
72/// - If `allow_uncalibrated_overlay == true`, uncalibrated cues are packed with `uncalibrated_flag = 1`.
73/// - If `out_descriptors.len() < cues.len()`, returns `Err(CueEvaluationError::BufferOverflow)`.
74pub fn pack_calibrated_cues_for_gpu_zero_heap(
75    cues: &[PhysicalCueEmission],
76    allow_uncalibrated_overlay: bool,
77    out_descriptors: &mut [EmfAcousticGpuDescriptor],
78) -> Result<usize, CueEvaluationError> {
79    if out_descriptors.len() < cues.len() {
80        return Err(CueEvaluationError::BufferOverflow);
81    }
82
83    for (i, cue) in cues.iter().enumerate() {
84        let is_cal = cue.calibration.is_calibrated();
85        let uncalibrated_flag = if !is_cal {
86            if !allow_uncalibrated_overlay {
87                return Err(CueEvaluationError::UncalibratedBand);
88            }
89            1u32
90        } else {
91            0u32
92        };
93
94        let pol = cue.polarization_deg.unwrap_or(-1.0);
95
96        out_descriptors[i] = EmfAcousticGpuDescriptor {
97            source_entity_did: cue.source_entity_did,
98            source_organ_id: cue.source_organ_id,
99            band_min: cue.band_min as f32,
100            band_max: cue.band_max as f32,
101            magnitude: cue.magnitude as f32,
102            polarization_deg: pol,
103            domain_code: cue.domain as u32,
104            unit_code: cue.unit as u32,
105            calibration_code: cue.calibration as u32,
106            uncalibrated_flag,
107            _reserved: [0; 4],
108        };
109    }
110
111    Ok(cues.len())
112}
113
114#[cfg(test)]
115mod tests {
116    use super::*;
117    use crate::specialized_libs::computational_geometry::allocation_counter::assert_zero_alloc;
118
119    fn sample_calibrated_cues() -> [PhysicalCueEmission; 2] {
120        [
121            PhysicalCueEmission {
122                source_entity_did: 0x1111_2222_3333_4444,
123                source_organ_id: 10,
124                domain: PhysicalCueDomain::ElectromagneticOptical,
125                unit: PhysicalUnitKind::WattsPerSquareMeterIrradiance,
126                band_min: 400.0,
127                band_max: 700.0,
128                magnitude: 120.0,
129                polarization_deg: Some(45.0),
130                calibration: CalibrationStatus::LaboratoryCalibrated,
131            },
132            PhysicalCueEmission {
133                source_entity_did: 0x5555_6666_7777_8888,
134                source_organ_id: 20,
135                domain: PhysicalCueDomain::AcousticMechanical,
136                unit: PhysicalUnitKind::DecibelSplAcoustic,
137                band_min: 20.0,
138                band_max: 20000.0,
139                magnitude: 65.0,
140                polarization_deg: None,
141                calibration: CalibrationStatus::FieldCalibrated,
142            },
143        ]
144    }
145
146    #[test]
147    fn test_descriptor_layout_and_size() {
148        assert_eq!(std::mem::size_of::<EmfAcousticGpuDescriptor>(), 64);
149        assert_eq!(std::mem::align_of::<EmfAcousticGpuDescriptor>(), 8);
150
151        let desc = EmfAcousticGpuDescriptor::default();
152        let bytes = bytemuck::bytes_of(&desc);
153        assert_eq!(bytes.len(), 64);
154
155        let recovered: &EmfAcousticGpuDescriptor = bytemuck::from_bytes(bytes);
156        assert_eq!(recovered, &desc);
157        assert!(!recovered.is_uncalibrated());
158    }
159
160    #[test]
161    fn test_pack_calibrated_cues_success() {
162        let cues = sample_calibrated_cues();
163        let mut out = [EmfAcousticGpuDescriptor::default(); 2];
164
165        let count = pack_calibrated_cues_for_gpu_zero_heap(&cues, false, &mut out).unwrap();
166        assert_eq!(count, 2);
167
168        assert_eq!(out[0].source_entity_did, 0x1111_2222_3333_4444);
169        assert_eq!(
170            out[0].domain_code,
171            PhysicalCueDomain::ElectromagneticOptical as u32
172        );
173        assert_eq!(
174            out[0].unit_code,
175            PhysicalUnitKind::WattsPerSquareMeterIrradiance as u32
176        );
177        assert_eq!(out[0].magnitude, 120.0);
178        assert_eq!(out[0].polarization_deg, 45.0);
179        assert_eq!(out[0].uncalibrated_flag, 0);
180        assert!(!out[0].is_uncalibrated());
181
182        assert_eq!(out[1].source_entity_did, 0x5555_6666_7777_8888);
183        assert_eq!(
184            out[1].domain_code,
185            PhysicalCueDomain::AcousticMechanical as u32
186        );
187        assert_eq!(
188            out[1].unit_code,
189            PhysicalUnitKind::DecibelSplAcoustic as u32
190        );
191        assert_eq!(out[1].magnitude, 65.0);
192        assert_eq!(out[1].polarization_deg, -1.0);
193        assert_eq!(out[1].uncalibrated_flag, 0);
194        assert!(!out[1].is_uncalibrated());
195    }
196
197    #[test]
198    fn test_pack_uncalibrated_disallowed_fails_closed() {
199        let mut cues = sample_calibrated_cues();
200        cues[0].calibration = CalibrationStatus::UncalibratedTheoretical;
201        let mut out = [EmfAcousticGpuDescriptor::default(); 2];
202
203        let res = pack_calibrated_cues_for_gpu_zero_heap(&cues, false, &mut out);
204        assert_eq!(res, Err(CueEvaluationError::UncalibratedBand));
205
206        cues[0].calibration = CalibrationStatus::OutOfSensorRange;
207        let res2 = pack_calibrated_cues_for_gpu_zero_heap(&cues, false, &mut out);
208        assert_eq!(res2, Err(CueEvaluationError::UncalibratedBand));
209    }
210
211    #[test]
212    fn test_pack_uncalibrated_allowed_sets_flag() {
213        let mut cues = sample_calibrated_cues();
214        cues[0].calibration = CalibrationStatus::UncalibratedTheoretical;
215        let mut out = [EmfAcousticGpuDescriptor::default(); 2];
216
217        let count = pack_calibrated_cues_for_gpu_zero_heap(&cues, true, &mut out).unwrap();
218        assert_eq!(count, 2);
219
220        assert_eq!(out[0].uncalibrated_flag, 1);
221        assert!(out[0].is_uncalibrated());
222        assert_eq!(out[1].uncalibrated_flag, 0);
223        assert!(!out[1].is_uncalibrated());
224    }
225
226    #[test]
227    fn test_pack_buffer_overflow() {
228        let cues = sample_calibrated_cues();
229        let mut small_out = [EmfAcousticGpuDescriptor::default(); 1];
230
231        let res = pack_calibrated_cues_for_gpu_zero_heap(&cues, false, &mut small_out);
232        assert_eq!(res, Err(CueEvaluationError::BufferOverflow));
233    }
234
235    #[test]
236    fn test_zero_alloc_gpu_packing() {
237        let cues = sample_calibrated_cues();
238        let mut out = [EmfAcousticGpuDescriptor::default(); 2];
239
240        assert_zero_alloc("pack_calibrated_cues_for_gpu", || {
241            let count = pack_calibrated_cues_for_gpu_zero_heap(&cues, false, &mut out).unwrap();
242            assert_eq!(count, 2);
243        });
244
245        assert_zero_alloc("pack_uncalibrated_overlay_for_gpu", || {
246            let mut uncal = cues;
247            uncal[0].calibration = CalibrationStatus::UncalibratedTheoretical;
248            let count = pack_calibrated_cues_for_gpu_zero_heap(&uncal, true, &mut out).unwrap();
249            assert_eq!(count, 2);
250        });
251    }
252}