Skip to main content

qualia_core_db/render/gpu/
emf_pipeline.rs

1//! EMF field-family volumetric visualizer pipeline (plan §7.3 W4 / W7).
2//!
3//! Extends [`PortalGpu`] with a render pipeline that draws 2D slices of the
4//! 4D EMF field grid (x×y×z×t) with the full 10D manifold record and 3 Stokes
5//! polarization parameters preserved.
6//! This renderer is one field-family view over the shared scientific manifold;
7//! it does not define or replace astrophysics, wave, diffusion, or other fields.
8//!
9//! The field data is uploaded as a storage buffer of `EmfFieldCell` structs
10//! (64 bytes each: amplitude + phase + frequency + 10D manifold coordinate + 3 Stokes Q/U/V).
11//! A full-screen quad fragment shader samples the grid bilinearly and maps:
12//! - amplitude → brightness (HDR)
13//! - phase → hue as a derived display projection (via Full-Spectrum σ → linear sRGB)
14//! - manifold.scale → display saturation
15//! - manifold.manifold_curvature + Stokes polarization → display rim glow & highlight
16
17#[path = "emf_spectrum.rs"]
18mod emf_spectrum;
19
20use etalon::util::DeviceExt;
21pub use emf_spectrum::{
22    emf_cells_from_loaded, emf_field_cell_from_optical, emf_field_cell_from_record64,
23    evaluate_display_slice_rgba8, full_spectrum_sigma_to_linear_rgb,
24};
25pub use etalon_render::emf::{
26    checked_field_bytes, checked_grid_cell_count, EmfFieldCell, EmfPipeline, EmfPipelineDesc,
27    EmfSliceUniform, EMF_VOLUMETRIC_WGSL,
28};
29/// Fixed grayscale display derivative; exact f64 observations stay in the retained source.
30pub fn emf_field_cell_from_display(cell: &crate::render::portal_emf_state::DisplayEmfCell) -> EmfFieldCell {
31    let brightness = if cell.valid { -(-cell.magnitude_v_per_m).exp_m1() as f32 } else { 0.0 };
32    EmfFieldCell { amplitude: brightness, epistemic_weight: if cell.valid { 1.0 } else { 0.0 },
33        phase: 0.0, frequency: 0.0, scale: 0.0, attention_depth: 0.0,
34        topological_spin: 0.0, temporal_decay: 0.0, entropy_bias: 0.0,
35        spatial_phase: 0.0, recurrence_frequency: 0.0, density_threshold: 0.0,
36        manifold_curvature: 0.0, stokes_q: 0.0, stokes_u: 0.0, stokes_v: 0.0 }
37}
38
39/// Per-portal EMF visualizer state.
40pub(crate) struct EmfState {
41    /// Uploaded field cells (storage buffer).
42    pub field_buf: Option<etalon::Buffer>,
43    pub _field_reservation: Option<crate::gpu_context::VramReservation<'static>>,
44    /// Number of cells in the field buffer.
45    pub cell_count: u32,
46    /// Grid dimensions.
47    pub nx: u32,
48    pub ny: u32,
49    pub nz: u32,
50    pub nt: u32,
51    /// Field bind group (group 1). Rebuilt when field buffer changes.
52    pub field_bind_group: Option<etalon::BindGroup>,
53    /// Inner decoupled EMF pipeline from etalon-render.
54    pub inner: etalon_render::emf::EmfPipeline,
55    pub _param_buffer_reservation: crate::gpu_context::VramReservation<'static>,
56}
57
58impl std::ops::Deref for EmfState {
59    type Target = etalon_render::emf::EmfPipeline;
60
61    fn deref(&self) -> &Self::Target {
62        &self.inner
63    }
64}
65
66impl std::ops::DerefMut for EmfState {
67    fn deref_mut(&mut self) -> &mut Self::Target {
68        &mut self.inner
69    }
70}
71
72impl EmfState {
73    /// Construct the EMF pipeline state on the given device.
74    pub(crate) fn new(
75        device: &etalon::Device,
76        color_format: etalon::TextureFormat,
77    ) -> Result<Self, String> {
78        let param_bytes = std::mem::size_of::<EmfSliceUniform>() as u64;
79        let param_buffer_reservation = crate::gpu_context::global_vram_ledger()
80            .try_reserve_graphics(
81                crate::gpu_context::VramResourceClass::FrameTarget,
82                param_bytes,
83            )
84            .map_err(|e| format!("EMF parameter buffer reservation failed: {e}"))?;
85
86        let inner = etalon_render::emf::EmfPipeline::new(device, color_format);
87
88        Ok(Self {
89            field_buf: None,
90            _field_reservation: None,
91            cell_count: 0,
92            nx: 0,
93            ny: 0,
94            nz: 0,
95            nt: 0,
96            field_bind_group: None,
97            inner,
98            _param_buffer_reservation: param_buffer_reservation,
99        })
100    }
101
102    /// Whether a field has been uploaded.
103    pub fn has_field(&self) -> bool {
104        self.field_buf.is_some()
105    }
106
107    /// Grid dimensions of the uploaded field.
108    pub fn grid_dims(&self) -> (u32, u32, u32, u32) {
109        (self.nx, self.ny, self.nz, self.nt)
110    }
111
112    /// Access the underlying Etalon EMF pipeline.
113    pub fn inner(&self) -> &etalon_render::emf::EmfPipeline {
114        &self.inner
115    }
116
117    /// Mutable access to the underlying Etalon EMF pipeline.
118    pub fn inner_mut(&mut self) -> &mut etalon_render::emf::EmfPipeline {
119        &mut self.inner
120    }
121}
122
123impl super::PortalGpu {
124    /// Upload an EMF field grid to the GPU for volumetric visualization.
125    ///
126    /// `cells` is the flat field array indexed as \[t\]\[z\]\[y\]\[x\], with
127    /// `nx*ny*nz*nt` elements. `bounds` is \[x_min, x_max, y_min, y_max, z_min, z_max\].
128    pub fn emf_upload_field(
129        &mut self,
130        cells: &[EmfFieldCell],
131        nx: u32,
132        ny: u32,
133        nz: u32,
134        nt: u32,
135        bounds: [f32; 6],
136    ) -> Result<(), String> {
137        let expected = checked_grid_cell_count(nx, ny, nz, nt)
138            .ok_or_else(|| "emf_upload_field: grid cell count overflow".to_string())?;
139        if cells.len() as u64 != expected {
140            return Err(format!(
141                "emf_upload_field: expected {expected} cells for {nx}×{ny}×{nz}×{nt}, got {}",
142                cells.len()
143            ));
144        }
145        if expected == 0 {
146            return Err("emf_upload_field: all grid dimensions must be non-zero".into());
147        }
148        if expected > u64::from(u32::MAX) {
149            return Err("emf_upload_field: cell count exceeds the renderer ABI".into());
150        }
151        let field_bytes = checked_field_bytes(expected)
152            .ok_or_else(|| "emf_upload_field: field byte size overflow".to_string())?;
153        let max_binding_bytes = u64::from(self.device.limits().max_storage_buffer_binding_size);
154        let max_buffer_bytes = self.device.limits().max_buffer_size;
155        if field_bytes > max_binding_bytes || field_bytes > max_buffer_bytes {
156            return Err(format!(
157                "emf_upload_field: {field_bytes} bytes exceed this device's storage-buffer limit ({max_binding_bytes})"
158            ));
159        }
160        let field_reservation = crate::gpu_context::global_vram_ledger()
161            .try_reserve_graphics(
162                crate::gpu_context::VramResourceClass::FieldResidency,
163                field_bytes,
164            )
165            .map_err(|e| format!("emf_upload_field: field residency refused: {e}"))?;
166
167        let field_buf = self
168            .device
169            .create_buffer_init(&etalon::util::BufferInitDescriptor {
170                label: Some("emf-field-storage"),
171                contents: bytemuck::cast_slice(cells),
172                usage: etalon::BufferUsages::STORAGE | etalon::BufferUsages::COPY_DST,
173            });
174
175        // Build all replacement handles before swapping out the old field. If
176        // admission or allocation fails, the currently displayed field remains valid.
177        let field_bind_group = self.device.create_bind_group(&etalon::BindGroupDescriptor {
178            label: Some("emf-field-bind"),
179            layout: &self.emf.inner().field_layout,
180            entries: &[etalon::BindGroupEntry {
181                binding: 0,
182                resource: field_buf.as_entire_binding(),
183            }],
184        });
185        self.emf.field_bind_group = Some(field_bind_group);
186        self.emf.field_buf = Some(field_buf);
187        self.emf._field_reservation = Some(field_reservation);
188        self.emf.cell_count = cells.len() as u32;
189        self.emf.nx = nx;
190        self.emf.ny = ny;
191        self.emf.nz = nz;
192        self.emf.nt = nt;
193
194        // Update the slice parameter uniform with default slice (z=0, t=0).
195        self.emf_update_slice_params(0, 0, bounds, 1.0, 0.0, 1.0);
196
197        Ok(())
198    }
199
200    /// Upload an admitted `LoadedEmf` derivative, enabling full-spectrum projection mode `0`
201    /// when spectral/Stokes cells are present (falling back to grayscale mode `1` for static grids).
202    pub fn emf_upload_loaded(
203        &mut self,
204        loaded: &crate::render::portal_emf_state::LoadedEmf,
205    ) -> Result<(), String> {
206        let cells = emf_cells_from_loaded(loaded)?;
207        let [nx, ny, nz, nt] = loaded.dimensions();
208        let bounds = loaded.local_bounds();
209        self.emf_upload_field(&cells, nx, ny, nz, nt, bounds)?;
210        let spectral = loaded.optical_cells().iter().any(|o| {
211            o.valid && (o.spectral_sigma > 0.0 || o.carrier_hz > 0.0 || o.phase_rad != 0.0 || o.stokes_q != 0.0 || o.stokes_u != 0.0 || o.stokes_v != 0.0)
212        });
213        let mode = if spectral { 0 } else { 1 };
214        self.emf_update_slice_params_with_mode(0, 0, bounds, 1.0, 0.0, 1.0, mode);
215        Ok(())
216    }
217
218    /// Parse and upload a verified `Q42EMF64` container directly for volumetric display.
219    pub fn emf_upload_emf64(&mut self, bytes: &[u8]) -> Result<(), String> {
220        let loaded = crate::render::portal_emf_state::decode_emf64_display(bytes)?;
221        self.emf_upload_loaded(&loaded)
222    }
223
224    /// Update the slice parameters (which z/t slice to render, display controls).
225    /// Preserves `projection_mode: 1` grayscale compatibility; use `emf_update_slice_params_with_mode`
226    /// for full volumetric spectral + Stokes mode `0`.
227    pub fn emf_update_slice_params(
228        &mut self,
229        slice_z: u32,
230        slice_t: u32,
231        bounds: [f32; 6],
232        amplitude_scale: f32,
233        phase_offset: f32,
234        manifold_gain: f32,
235    ) {
236        self.emf_update_slice_params_with_mode(
237            slice_z,
238            slice_t,
239            bounds,
240            amplitude_scale,
241            phase_offset,
242            manifold_gain,
243            1,
244        );
245    }
246
247    /// Update slice parameters with explicit `EmfSliceUniform::projection_mode` (`0` volumetric spectral, `1` grayscale).
248    #[allow(clippy::too_many_arguments)]
249    pub fn emf_update_slice_params_with_mode(
250        &mut self,
251        slice_z: u32,
252        slice_t: u32,
253        bounds: [f32; 6],
254        amplitude_scale: f32,
255        phase_offset: f32,
256        manifold_gain: f32,
257        projection_mode: u32,
258    ) {
259        let params = EmfSliceUniform {
260            nx: self.emf.nx,
261            ny: self.emf.ny,
262            nz: self.emf.nz,
263            nt: self.emf.nt,
264            slice_z: slice_z.min(self.emf.nz.saturating_sub(1)),
265            slice_t: slice_t.min(self.emf.nt.saturating_sub(1)),
266            x_min: bounds[0],
267            x_max: bounds[1],
268            y_min: bounds[2],
269            y_max: bounds[3],
270            z_min: bounds[4],
271            z_max: bounds[5],
272            amplitude_scale,
273            phase_offset,
274            manifold_gain,
275            projection_mode,
276        };
277        self.emf.inner_mut().update_params(&self.queue, &params);
278    }
279
280    /// Render the current EMF slice to the portal's color target.
281    ///
282    /// Draws a full-screen quad with the EMF fragment shader. The caller is
283    /// responsible for beginning the render pass and providing a color
284    /// attachment view.
285    pub fn emf_render_slice(&self, render_pass: &mut etalon::RenderPass<'_>) -> Result<(), String> {
286        let Some(field_bind) = &self.emf.field_bind_group else {
287            return Err("emf_render_slice: no field uploaded".into());
288        };
289        render_pass.set_pipeline(&self.emf.inner().pipeline);
290        render_pass.set_bind_group(0, &self.emf.inner().params_bind_group, &[]);
291        render_pass.set_bind_group(1, field_bind, &[]);
292        render_pass.draw(0..6, 0..1);
293        Ok(())
294    }
295
296    /// Whether an EMF field is currently uploaded.
297    pub fn emf_has_field(&self) -> bool {
298        self.emf.has_field()
299    }
300
301    /// EMF grid dimensions (nx, ny, nz, nt).
302    pub fn emf_grid_dims(&self) -> (u32, u32, u32, u32) {
303        self.emf.grid_dims()
304    }
305
306    /// Render the current EMF slice to the offscreen target and read back the
307    /// RGBA8 pixels. This is the combined render+readback path used by the
308    /// `Render.emf_render_slice` invoke handler.
309    pub fn emf_render_slice_to_rgba8(&mut self) -> Result<(u32, u32, Vec<u8>), String> {
310        if !self.emf.has_field() {
311            return Err("no EMF field uploaded".into());
312        }
313        let mut encoder = self
314            .device
315            .create_command_encoder(&etalon::CommandEncoderDescriptor {
316                label: Some("emf-slice-encoder"),
317            });
318        {
319            let view = self
320                .offscreen_texture
321                .as_ref()
322                .ok_or("no offscreen target")?
323                .create_view(&etalon::TextureViewDescriptor::default());
324            let mut pass = encoder.begin_render_pass(&etalon::RenderPassDescriptor {
325                label: Some("emf-slice-pass"),
326                color_attachments: &[Some(etalon::RenderPassColorAttachment {
327                    view: &view,
328                    depth_slice: None,
329                    resolve_target: None,
330                    ops: etalon::Operations {
331                        load: etalon::LoadOp::Clear(etalon::Color::BLACK),
332                        store: etalon::StoreOp::Store,
333                    },
334                })],
335                depth_stencil_attachment: None,
336                multiview_mask: None,
337                timestamp_writes: None,
338                occlusion_query_set: None,
339            });
340            self.emf_render_slice(&mut pass)?;
341        }
342        let submission = self.queue.submit(std::iter::once(encoder.finish()));
343        #[cfg(not(target_arch = "wasm32"))]
344        if submission.is_none() {
345            return Err("EMF rendering: native queue rejected the command submission".to_string());
346        }
347        #[cfg(target_arch = "wasm32")]
348        let _ = submission;
349
350        let (w, h) = self.surface_size();
351        let mut pixels = vec![0u8; (w * h * 4) as usize];
352        self.read_rgba8_into(&mut pixels)
353            .map_err(|e| e.to_string())?;
354        Ok((w, h, pixels))
355    }
356}
357
358#[cfg(test)]
359mod tests {
360    use super::super::PortalGpu;
361    use super::*;
362
363
364    #[test]
365    fn emf_field_cell_size() {
366        // 3 f32 (amp/phase/freq) + 10 f32 (manifold) + 3 f32 (Stokes Q/U/V) = 16 f32 = 64 bytes
367        assert_eq!(std::mem::size_of::<EmfFieldCell>(), 64);
368    }
369
370    #[test]
371    fn display_preserves_valid_zero_and_missing_and_saturates_extreme_fields() {
372        use crate::render::portal_emf_state::DisplayEmfCell;
373        for (magnitude, expected) in [(0.0,0.0),(1.0,1.0-(-1.0f32).exp()),(f64::MAX,1.0),(f64::INFINITY,1.0)] {
374            let cell=emf_field_cell_from_display(&DisplayEmfCell { magnitude_v_per_m:magnitude,valid:true });
375            assert!((cell.amplitude-expected).abs()<1e-6);
376            assert_eq!(cell.epistemic_weight,1.0);
377            assert_eq!(cell.frequency,0.0);
378        }
379        let missing=emf_field_cell_from_display(&DisplayEmfCell { magnitude_v_per_m:0.0,valid:false });
380        assert_eq!(missing.epistemic_weight,0.0);
381    }
382
383    #[test]
384    fn emf_field_cell_size_and_alignment() {
385        assert_eq!(std::mem::size_of::<EmfFieldCell>(), 64);
386        assert_eq!(std::mem::align_of::<EmfFieldCell>(), 4);
387        let migrated = EmfFieldCell::from_v1_13f32([1.0; 13]);
388        assert_eq!(migrated.amplitude, 1.0);
389        assert_eq!(migrated.stokes_q, 0.0);
390        assert_eq!(migrated.stokes_u, 0.0);
391        assert_eq!(migrated.stokes_v, 0.0);
392    }
393
394    #[test]
395    fn emf_grid_and_residency_sizing_is_checked() {
396        assert_eq!(checked_grid_cell_count(4, 4, 1, 1), Some(16));
397        assert_eq!(
398            checked_grid_cell_count(u32::MAX, u32::MAX, u32::MAX, 2),
399            None
400        );
401        assert_eq!(checked_grid_cell_count(0, 4, 1, 1), Some(0));
402        assert_eq!(checked_field_bytes(16), Some(1024));
403        assert_eq!(checked_field_bytes(u64::MAX), None);
404    }
405
406    #[test]
407    fn emf_slice_uniform_size() {
408        assert_eq!(std::mem::size_of::<EmfSliceUniform>(), 64);
409    }
410
411    #[test]
412    fn emf_slice_uniform_alignment() {
413        assert_eq!(std::mem::align_of::<EmfSliceUniform>(), 16);
414    }
415
416    /// End-to-end: create a PortalGpu, upload a small field, render a slice,
417    /// and read back pixels. Skips gracefully when no GPU adapter exists.
418    #[test]
419    fn c_emf_upload_and_render_slice() {
420        if crate::gpu_context::try_shared_gpu().is_none() {
421            eprintln!("[emf_test] no GPU adapter — skipping");
422            return;
423        }
424        let mut portal = PortalGpu::new_offscreen(32, 32, 256).expect("offscreen");
425        // 4×4×1×1 field = 16 cells.
426        let nx = 4u32;
427        let ny = 4u32;
428        let nz = 1u32;
429        let nt = 1u32;
430        let cells: Vec<EmfFieldCell> = (0..16)
431            .map(|i| EmfFieldCell {
432                amplitude: (i as f32) / 16.0,
433                phase: (i as f32) * 0.3927, // π/8 per cell
434                frequency: 1.0e9,
435                scale: 0.5,
436                attention_depth: 0.3,
437                epistemic_weight: 0.7,
438                topological_spin: 0.1,
439                temporal_decay: 0.0,
440                entropy_bias: 0.2,
441                spatial_phase: (i as f32) * 0.1,
442                recurrence_frequency: 0.5,
443                density_threshold: 0.4,
444                manifold_curvature: 0.05,
445                stokes_q: 0.2,
446                stokes_u: 0.1,
447                stokes_v: 0.05,
448            })
449            .collect();
450        let bounds = [-1.0, 1.0, -1.0, 1.0, -1.0, 1.0];
451        portal
452            .emf_upload_field(&cells, nx, ny, nz, nt, bounds)
453            .expect("upload");
454        assert!(portal.emf_has_field());
455        assert_eq!(portal.emf_grid_dims(), (4, 4, 1, 1));
456
457        // Render a slice and read back pixels via the public method.
458        let (w, h, pixels) = portal.emf_render_slice_to_rgba8().expect("render+readback");
459        assert_eq!(w, 32);
460        assert_eq!(h, 32);
461        let non_black = pixels
462            .chunks(4)
463            .filter(|px| px[0] > 0 || px[1] > 0 || px[2] > 0)
464            .count();
465        assert!(
466            non_black > 0,
467            "EMF slice should produce non-black pixels, got {non_black}"
468        );
469    }
470
471    #[test]
472    fn c_emf_render_without_field_errors() {
473        if crate::gpu_context::try_shared_gpu().is_none() {
474            eprintln!("[emf_test] no GPU adapter — skipping");
475            return;
476        }
477        let mut portal = PortalGpu::new_offscreen(16, 16, 64).expect("offscreen");
478        let result = portal.emf_render_slice_to_rgba8();
479        assert!(result.is_err(), "render without field should error");
480    }
481}