Skip to main content

qualia_core_db/render/gpu/
holographic.rs

1//! Holographic 3D Engine for Semantic Graphs — Procedural Volumetric Light Field.
2//!
3//! Architected per `docs/Holographic 3D Engine for Semantic Graphs.md`:
4//! - Proxy wireframe bounding volumes with zero CPU triangle meshing.
5//! - Resolution-independent procedural fragment raymarching using C¹ smooth-min SDFs.
6//! - Wave interference for N3Logic reasoning (constructive focal points and luminous bridges).
7//! - Direct EMF spectral frequency emission into the CIE 1931 XYZ -> linear sRGB spectrum.
8
9use bytemuck::{Pod, Zeroable};
10
11pub use etalon_render::scene_contract::{FrameCameraPod, ManifoldProjectionPod};
12pub use etalon_render::volumetric::{
13    CameraUniform as EtalonCameraUniform,
14    ObserverStandpointUniform as EtalonObserverStandpointUniform,
15    VolumetricPipeline as EtalonVolumetricPipeline, HOLOGRAPHIC_WGSL as ETALON_HOLOGRAPHIC_WGSL,
16};
17
18/// Primitive geometric archetype evaluated procedurally inside the holographic shader.
19#[repr(u32)]
20#[derive(Debug, Clone, Copy, PartialEq, Eq)]
21pub enum HolographicPrimitive {
22    /// Harmonic pulsating sphere.
23    Sphere = 0,
24    /// Axis-aligned rounded box with continuous edge blending.
25    RoundedBox = 1,
26    /// Dynamic directional capsule.
27    Capsule = 2,
28    /// Multi-harmonic organic metaball field.
29    Metaball = 3,
30    /// Relational interference bridge linking two semantic entities.
31    InterferenceBridge = 4,
32}
33
34/// 96-byte std140/std430 aligned GPU representation of a semantic holographic entity.
35#[repr(C)]
36#[derive(Debug, Clone, Copy, Pod, Zeroable)]
37pub struct HolographicNodeGpu {
38    /// World position xyz, bounding radius / proxy scale w.
39    pub position_scale: [f32; 4],
40    /// Half-extents xyz, primitive type w (`HolographicPrimitive` as u32/f32).
41    pub half_extents_primitive: [f32; 4],
42    /// Frequency x, amplitude y, phase z, manifold curvature w.
43    pub frequency_amplitude: [f32; 4],
44    /// 10D Manifold tensor: epistemic_q x, topological_spin y, temporal_decay z, density_threshold w.
45    pub manifold_tensor: [f32; 4],
46    /// Target endpoint xyz (for relational bridges), coherence weight w.
47    pub connection_endpoint: [f32; 4],
48    /// Modality emissive color rgba.
49    pub emissive_color: [f32; 4],
50}
51
52const _: [(); 96] = [(); std::mem::size_of::<HolographicNodeGpu>()];
53
54impl Default for HolographicNodeGpu {
55    fn default() -> Self {
56        Self {
57            position_scale: [0.0, 0.0, 0.0, 1.0],
58            half_extents_primitive: [1.0, 1.0, 1.0, HolographicPrimitive::Sphere as u32 as f32],
59            frequency_amplitude: [1.0, 1.0, 0.0, 1.0],
60            manifold_tensor: [1.0, 0.0, 0.0, 0.5],
61            connection_endpoint: [0.0, 0.0, 0.0, 1.0],
62            emissive_color: [0.0, 0.9, 1.0, 1.0],
63        }
64    }
65}
66
67impl HolographicNodeGpu {
68    /// Constructs a holographic node in the hot path without heap allocation.
69    #[inline]
70    pub const fn new(
71        position: [f32; 3],
72        scale: f32,
73        half_extents: [f32; 3],
74        primitive: HolographicPrimitive,
75        frequency: f32,
76        amplitude: f32,
77        phase: f32,
78        curvature: f32,
79        epistemic_q: f32,
80        color: [f32; 4],
81    ) -> Self {
82        Self {
83            position_scale: [position[0], position[1], position[2], scale],
84            half_extents_primitive: [
85                half_extents[0],
86                half_extents[1],
87                half_extents[2],
88                primitive as u32 as f32,
89            ],
90            frequency_amplitude: [frequency, amplitude, phase, curvature],
91            manifold_tensor: [epistemic_q, 0.0, 0.0, 0.5],
92            connection_endpoint: [0.0, 0.0, 0.0, 0.0],
93            emissive_color: color,
94        }
95    }
96
97    /// Configures a relational interference bridge linking this node to a target node.
98    #[inline]
99    pub fn with_interference_bridge(mut self, target: [f32; 3], coherence_weight: f32) -> Self {
100        self.half_extents_primitive[3] = HolographicPrimitive::InterferenceBridge as u32 as f32;
101        self.connection_endpoint = [target[0], target[1], target[2], coherence_weight];
102        self
103    }
104}
105
106impl From<HolographicNodeGpu> for etalon_render::volumetric::HolographicNodeGpu {
107    #[inline]
108    fn from(node: HolographicNodeGpu) -> Self {
109        Self {
110            position_scale: node.position_scale,
111            half_extents_primitive: node.half_extents_primitive,
112            frequency_amplitude: node.frequency_amplitude,
113            manifold_tensor: node.manifold_tensor,
114            connection_endpoint: node.connection_endpoint,
115            emissive_color: node.emissive_color,
116        }
117    }
118}
119
120impl From<etalon_render::volumetric::HolographicNodeGpu> for HolographicNodeGpu {
121    #[inline]
122    fn from(node: etalon_render::volumetric::HolographicNodeGpu) -> Self {
123        Self {
124            position_scale: node.position_scale,
125            half_extents_primitive: node.half_extents_primitive,
126            frequency_amplitude: node.frequency_amplitude,
127            manifold_tensor: node.manifold_tensor,
128            connection_endpoint: node.connection_endpoint,
129            emissive_color: node.emissive_color,
130        }
131    }
132}
133
134pub use etalon_render::holographic::HolographicPipelineGpu;
135
136#[cfg(test)]
137mod tests {
138    use super::*;
139
140    #[test]
141    fn holographic_wgsl_parses_and_outputs_frag_depth_with_voronoi() {
142        let src = crate::shaders::viewport::HOLOGRAPHIC_WGSL;
143        assert!(src.contains("proc_voronoi_f1_3d"));
144        assert!(src.contains("@builtin(frag_depth)"));
145        let module = naga::front::wgsl::parse_str(src).expect("HOLOGRAPHIC_WGSL must parse");
146        let mut validator = naga::valid::Validator::new(
147            naga::valid::ValidationFlags::all(),
148            naga::valid::Capabilities::all(),
149        );
150        validator
151            .validate(&module)
152            .expect("HOLOGRAPHIC_WGSL must validate cleanly");
153    }
154
155    #[test]
156    fn holographic_node_gpu_layout_and_bridge_builder() {
157        let node = HolographicNodeGpu::new(
158            [1.0, 2.0, 3.0],
159            1.5,
160            [0.5, 0.5, 0.5],
161            HolographicPrimitive::Sphere,
162            2.0,
163            1.0,
164            0.0,
165            1.2,
166            0.9,
167            [0.2, 0.8, 1.0, 1.0],
168        )
169        .with_interference_bridge([4.0, 5.0, 6.0], 0.75);
170        assert_eq!(std::mem::size_of::<HolographicNodeGpu>(), 96);
171        assert_eq!(
172            node.half_extents_primitive[3] as u32,
173            HolographicPrimitive::InterferenceBridge as u32
174        );
175        assert_eq!(node.connection_endpoint, [4.0, 5.0, 6.0, 0.75]);
176    }
177
178    #[test]
179    fn holographic_node_gpu_roundtrip_conversion() {
180        let node = HolographicNodeGpu::new(
181            [1.0, 2.0, 3.0],
182            1.5,
183            [0.5, 0.5, 0.5],
184            HolographicPrimitive::Sphere,
185            2.0,
186            1.0,
187            0.0,
188            1.2,
189            0.9,
190            [0.2, 0.8, 1.0, 1.0],
191        )
192        .with_interference_bridge([4.0, 5.0, 6.0], 0.75);
193
194        let etalon_node: etalon_render::volumetric::HolographicNodeGpu = node.into();
195        assert_eq!(etalon_node.position_scale, node.position_scale);
196        assert_eq!(
197            etalon_node.half_extents_primitive,
198            node.half_extents_primitive
199        );
200        assert_eq!(etalon_node.frequency_amplitude, node.frequency_amplitude);
201        assert_eq!(etalon_node.manifold_tensor, node.manifold_tensor);
202        assert_eq!(etalon_node.connection_endpoint, [4.0, 5.0, 6.0, 0.75]);
203        assert_eq!(etalon_node.emissive_color, node.emissive_color);
204
205        let roundtrip: HolographicNodeGpu = etalon_node.into();
206        assert_eq!(roundtrip.position_scale, node.position_scale);
207        assert_eq!(
208            roundtrip.half_extents_primitive,
209            node.half_extents_primitive
210        );
211        assert_eq!(roundtrip.frequency_amplitude, node.frequency_amplitude);
212        assert_eq!(roundtrip.manifold_tensor, node.manifold_tensor);
213        assert_eq!(roundtrip.connection_endpoint, node.connection_endpoint);
214        assert_eq!(roundtrip.emissive_color, node.emissive_color);
215    }
216}