Skip to main content

qualia_core_db/shaders/
mod.rs

1//! WGSL shader sources embedded in the Qualia WASM binary and canonical Etalon shader registry (`RM-03`).
2//!
3//! - **Root** (`*.wgsl`) — U0/U1 compute (LLM, tensor query, physics/HUD)
4//! - **`wasm/`** — copies of WASM LLM inference shaders (fused attention/FFN/transformer, GEMV, dequant, top-K, ternary, LoRA)
5//! - **`viewport/`** — U2 display (retired `RM-03` (`R`) and re-exported directly from [`etalon_render::shaders`])
6//!
7//! Canonical `etalon_nquin` and `etalon_render` shader constants are exposed here with compile-time
8//! and unit-tested byte-for-byte parity guarantees.
9
10pub mod viewport;
11
12pub const PGA_SCLERP_EVAL_WGSL: &str = include_str!("pga_sclerp_eval.wgsl");
13pub const SPRING_DAMPER_GRID_WGSL: &str = include_str!("spring_damper_grid.wgsl");
14pub const HUD_GLASS_BLUR_WGSL: &str = include_str!("hud_glass_blur.wgsl");
15pub const WAVE_INTERFERENCE_WGSL: &str = include_str!("wave_interference.wgsl");
16
17/// Canonical 48-byte `NQuinWire` warp-scan sieve compute shader from [`etalon_nquin`].
18pub const NQUIN_WARP_SCAN_WGSL: &str = etalon_nquin::NQUIN_WARP_SCAN_WGSL;
19
20/// Legacy 27-word bitmask sieve compute shader retained for `platform::npu_ffi` compatibility.
21pub const SIEVE_WGSL: &str = include_str!("sieve.wgsl");
22
23/// Canonical composite Holographic 3D semantic graph shader (`spectral.wgsl` + `holographic.wgsl`) from [`etalon_render::shaders`].
24pub const HOLOGRAPHIC_WGSL: &str = viewport::HOLOGRAPHIC_WGSL;
25
26/// Canonical standalone volumetric Holographic shader from [`etalon_render::volumetric`].
27#[cfg(feature = "gpu-runtime")]
28pub const HOLOGRAPHIC_STANDALONE_WGSL: &str = etalon_render::HOLOGRAPHIC_WGSL;
29#[cfg(not(feature = "gpu-runtime"))]
30pub const HOLOGRAPHIC_STANDALONE_WGSL: &str = viewport::HOLOGRAPHIC_WGSL;
31
32/// Canonical 4D EMF volumetric slice shader from [`etalon_render::shaders`].
33pub const EMF_VOLUMETRIC_WGSL: &str = viewport::EMF_VOLUMETRIC_WGSL;
34
35/// Canonical 64-byte Stokes v2 EMF volumetric shader from [`etalon_render::emf`].
36#[cfg(feature = "gpu-runtime")]
37pub const EMF_VOLUMETRIC_STOKES_WGSL: &str = etalon_render::EMF_VOLUMETRIC_WGSL;
38#[cfg(not(feature = "gpu-runtime"))]
39pub const EMF_VOLUMETRIC_STOKES_WGSL: &str = viewport::EMF_VOLUMETRIC_WGSL;
40
41/// Canonical GEMM substrate compute shader.
42pub const GEMM_SUBSTRATE_WGSL: &str = include_str!("gemm_substrate.wgsl");
43
44/// Canonical top-K reduction compute shader.
45pub const TOPK_REDUCTION_WGSL: &str = include_str!("topk_reduction.wgsl");
46
47/// Canonical graph sieve field compute shader.
48pub const GRAPH_SIEVE_FIELD_WGSL: &str = include_str!("graph_sieve_field.wgsl");
49
50/// Canonical graph radix histogram compute shader.
51pub const GRAPH_RADIX_HIST_WGSL: &str = include_str!("graph_radix_hist.wgsl");
52
53/// Canonical graph radix scatter compute shader.
54pub const GRAPH_RADIX_SCATTER_WGSL: &str = include_str!("graph_radix_scatter.wgsl");
55
56/// Return the canonical [`etalon_nquin::NQUIN_WARP_SCAN_WGSL`] source.
57#[inline]
58pub const fn canonical_nquin_warp_scan_wgsl() -> &'static str {
59    NQUIN_WARP_SCAN_WGSL
60}
61
62/// Return the canonical [`etalon_render::shaders::HOLOGRAPHIC_WGSL`] source.
63#[inline]
64pub const fn canonical_holographic_wgsl() -> &'static str {
65    HOLOGRAPHIC_WGSL
66}
67
68/// Return the canonical [`etalon_render::shaders::EMF_VOLUMETRIC_WGSL`] source.
69#[inline]
70pub const fn canonical_emf_volumetric_wgsl() -> &'static str {
71    EMF_VOLUMETRIC_WGSL
72}
73
74/// Zero-heap lookup of a canonical shader source by logical registry name.
75#[inline]
76pub fn canonical_shader_source(name: &str) -> Option<&'static str> {
77    match name {
78        "nquin_warp_scan.wgsl" | "nquin_warp_scan" => Some(NQUIN_WARP_SCAN_WGSL),
79        "sieve.wgsl" | "sieve" => Some(SIEVE_WGSL),
80        "holographic.wgsl" | "holographic" => Some(HOLOGRAPHIC_WGSL),
81        "holographic_standalone.wgsl" | "holographic_standalone" => {
82            Some(HOLOGRAPHIC_STANDALONE_WGSL)
83        }
84        "emf_volumetric.wgsl" | "emf_volumetric" => Some(EMF_VOLUMETRIC_WGSL),
85        "emf_volumetric_stokes.wgsl" | "emf_volumetric_stokes" => Some(EMF_VOLUMETRIC_STOKES_WGSL),
86        "spectral.wgsl" | "spectral" => Some(viewport::SPECTRAL_WGSL),
87        "ambient.wgsl" | "ambient" => Some(viewport::AMBIENT_WGSL),
88        "projector.wgsl" | "projector" => Some(viewport::PROJECTOR_WGSL),
89        "epistemic.wgsl" | "epistemic" => Some(viewport::EPISTEMIC_WGSL),
90        "screen.wgsl" | "screen" => Some(viewport::SCREEN_WGSL),
91        "water.wgsl" | "water" | "water_surface.wgsl" | "water_surface" => {
92            Some(viewport::WATER_WGSL)
93        }
94        "mesh.wgsl" | "mesh" => Some(viewport::MESH_WGSL),
95        "bloom.wgsl" | "bloom" => Some(viewport::BLOOM_WGSL),
96        "temporal_resolve.wgsl" | "temporal_resolve" => Some(viewport::TEMPORAL_RESOLVE_WGSL),
97        "instance_cull_indirect.wgsl"
98        | "instance_cull_indirect"
99        | "indirect_cull.wgsl"
100        | "indirect_cull" => Some(viewport::INSTANCE_CULL_INDIRECT_WGSL),
101        "gemm_substrate.wgsl" | "gemm_substrate" => Some(GEMM_SUBSTRATE_WGSL),
102        "topk_reduction.wgsl" | "topk_reduction" => Some(TOPK_REDUCTION_WGSL),
103        "pga_sclerp_eval.wgsl" | "pga_sclerp_eval" => Some(PGA_SCLERP_EVAL_WGSL),
104        "spring_damper_grid.wgsl" | "spring_damper_grid" => Some(SPRING_DAMPER_GRID_WGSL),
105        "hud_glass_blur.wgsl" | "hud_glass_blur" => Some(HUD_GLASS_BLUR_WGSL),
106        "wave_interference.wgsl" | "wave_interference" => Some(WAVE_INTERFERENCE_WGSL),
107        _ => None,
108    }
109}
110
111#[cfg(test)]
112mod tests {
113    use super::*;
114
115    #[test]
116    fn rm03_canonical_shader_exports_match_etalon_byte_for_byte() {
117        // 1. NQuin warp-scan sieve parity with etalon_nquin
118        assert_eq!(
119            NQUIN_WARP_SCAN_WGSL.as_bytes(),
120            etalon_nquin::NQUIN_WARP_SCAN_WGSL.as_bytes(),
121            "NQUIN_WARP_SCAN_WGSL must be byte-for-byte identical to etalon_nquin::NQUIN_WARP_SCAN_WGSL"
122        );
123        assert_eq!(
124            canonical_nquin_warp_scan_wgsl().as_bytes(),
125            etalon_nquin::NQUIN_WARP_SCAN_WGSL.as_bytes()
126        );
127
128        // 2. Holographic shader parity with etalon_render
129        assert_eq!(
130            HOLOGRAPHIC_WGSL.as_bytes(),
131            etalon_render::shaders::HOLOGRAPHIC_WGSL.as_bytes(),
132            "HOLOGRAPHIC_WGSL must be byte-for-byte identical to etalon_render::shaders::HOLOGRAPHIC_WGSL"
133        );
134        assert_eq!(
135            viewport::HOLOGRAPHIC_WGSL.as_bytes(),
136            etalon_render::shaders::HOLOGRAPHIC_WGSL.as_bytes()
137        );
138        #[cfg(feature = "gpu-runtime")]
139        assert_eq!(
140            HOLOGRAPHIC_STANDALONE_WGSL.as_bytes(),
141            etalon_render::HOLOGRAPHIC_WGSL.as_bytes(),
142            "HOLOGRAPHIC_STANDALONE_WGSL must be byte-for-byte identical to etalon_render::volumetric::HOLOGRAPHIC_WGSL"
143        );
144        #[cfg(feature = "gpu-runtime")]
145        assert_eq!(
146            HOLOGRAPHIC_STANDALONE_WGSL.as_bytes(),
147            crate::render::gpu::holographic::ETALON_HOLOGRAPHIC_WGSL.as_bytes()
148        );
149
150        // 3. EMF volumetric shader parity with etalon_render
151        assert_eq!(
152            EMF_VOLUMETRIC_WGSL.as_bytes(),
153            etalon_render::shaders::EMF_VOLUMETRIC_WGSL.as_bytes(),
154            "EMF_VOLUMETRIC_WGSL must be byte-for-byte identical to etalon_render::shaders::EMF_VOLUMETRIC_WGSL"
155        );
156        assert_eq!(
157            viewport::EMF_VOLUMETRIC_WGSL.as_bytes(),
158            etalon_render::shaders::EMF_VOLUMETRIC_WGSL.as_bytes()
159        );
160        #[cfg(feature = "gpu-runtime")]
161        assert_eq!(
162            EMF_VOLUMETRIC_STOKES_WGSL.as_bytes(),
163            etalon_render::EMF_VOLUMETRIC_WGSL.as_bytes(),
164            "EMF_VOLUMETRIC_STOKES_WGSL must be byte-for-byte identical to etalon_render::emf::EMF_VOLUMETRIC_WGSL"
165        );
166
167        #[cfg(not(feature = "gpu-runtime"))]
168        {
169            assert_eq!(HOLOGRAPHIC_STANDALONE_WGSL, viewport::HOLOGRAPHIC_WGSL);
170            assert_eq!(EMF_VOLUMETRIC_STOKES_WGSL, viewport::EMF_VOLUMETRIC_WGSL);
171        }
172
173        // 4. Full viewport shader registry byte-for-byte parity with etalon_render::shaders
174        let pairs: &[(&str, &str, &str)] = &[
175            ("SPECTRAL_WGSL", viewport::SPECTRAL_WGSL, etalon_render::shaders::SPECTRAL_WGSL),
176            ("AMBIENT_WGSL", viewport::AMBIENT_WGSL, etalon_render::shaders::AMBIENT_WGSL),
177            ("PROJECTOR_WGSL", viewport::PROJECTOR_WGSL, etalon_render::shaders::PROJECTOR_WGSL),
178            ("EPISTEMIC_WGSL", viewport::EPISTEMIC_WGSL, etalon_render::shaders::EPISTEMIC_WGSL),
179            ("SCREEN_WGSL", viewport::SCREEN_WGSL, etalon_render::shaders::SCREEN_WGSL),
180            ("WATER_WGSL", viewport::WATER_WGSL, etalon_render::shaders::WATER_WGSL),
181            ("MESH_WGSL", viewport::MESH_WGSL, etalon_render::shaders::MESH_WGSL),
182            ("BLOOM_WGSL", viewport::BLOOM_WGSL, etalon_render::shaders::BLOOM_WGSL),
183            ("CLUSTER_LIGHT_WGSL", viewport::CLUSTER_LIGHT_WGSL, etalon_render::shaders::CLUSTER_LIGHT_WGSL),
184            ("AO_PREPASS_WGSL", viewport::AO_PREPASS_WGSL, etalon_render::shaders::AO_PREPASS_WGSL),
185            ("AO_GENERATE_WGSL", viewport::AO_GENERATE_WGSL, etalon_render::shaders::AO_GENERATE_WGSL),
186            ("DEFERRED_RESOLVE_WGSL", viewport::DEFERRED_RESOLVE_WGSL, etalon_render::shaders::DEFERRED_RESOLVE_WGSL),
187            ("TEMPORAL_RESOLVE_WGSL", viewport::TEMPORAL_RESOLVE_WGSL, etalon_render::shaders::TEMPORAL_RESOLVE_WGSL),
188            ("TEMPORAL_DEPTH_WGSL", viewport::TEMPORAL_DEPTH_WGSL, etalon_render::shaders::TEMPORAL_DEPTH_WGSL),
189            ("TEMPORAL_OUTPUT_WGSL", viewport::TEMPORAL_OUTPUT_WGSL, etalon_render::shaders::TEMPORAL_OUTPUT_WGSL),
190            ("TEMPORAL_MOTION_WGSL", viewport::TEMPORAL_MOTION_WGSL, etalon_render::shaders::TEMPORAL_MOTION_WGSL),
191            ("TEMPORAL_REACTIVE_WGSL", viewport::TEMPORAL_REACTIVE_WGSL, etalon_render::shaders::TEMPORAL_REACTIVE_WGSL),
192            ("TEMPORAL_WARP_WGSL", viewport::TEMPORAL_WARP_WGSL, etalon_render::shaders::TEMPORAL_WARP_WGSL),
193            ("INSTANCE_CULL_INDIRECT_WGSL", viewport::INSTANCE_CULL_INDIRECT_WGSL, etalon_render::shaders::INSTANCE_CULL_INDIRECT_WGSL),
194            ("OUTPUT_TRANSFORM_WGSL", viewport::OUTPUT_TRANSFORM_WGSL, etalon_render::shaders::OUTPUT_TRANSFORM_WGSL),
195            ("SUN_SHADOW_WGSL", viewport::SUN_SHADOW_WGSL, etalon_render::shaders::SUN_SHADOW_WGSL),
196            ("SKY_WGSL", viewport::SKY_WGSL, etalon_render::shaders::SKY_WGSL),
197            ("PRECIPITATION_WGSL", viewport::PRECIPITATION_WGSL, etalon_render::shaders::PRECIPITATION_WGSL),
198            ("FOLIAGE_LOD_WGSL", viewport::FOLIAGE_LOD_WGSL, etalon_render::shaders::FOLIAGE_LOD_WGSL),
199            ("TILE_COMPACTION_WGSL", viewport::TILE_COMPACTION_WGSL, etalon_render::shaders::TILE_COMPACTION_WGSL),
200            ("HYDROLOGIC_OPTICS_WGSL", viewport::HYDROLOGIC_OPTICS_WGSL, etalon_render::shaders::HYDROLOGIC_OPTICS_WGSL),
201            ("SGGX_MICROFLAKE_WGSL", viewport::SGGX_MICROFLAKE_WGSL, etalon_render::shaders::SGGX_MICROFLAKE_WGSL),
202            ("SWE_SOLVER_WGSL", viewport::SWE_SOLVER_WGSL, etalon_render::shaders::SWE_SOLVER_WGSL),
203            ("SURFEL_INSTANCED_WGSL", viewport::SURFEL_INSTANCED_WGSL, etalon_render::shaders::SURFEL_INSTANCED_WGSL),
204            ("ACOUSTIC_VOXEL_CONE_WGSL", viewport::ACOUSTIC_VOXEL_CONE_WGSL, etalon_render::shaders::ACOUSTIC_VOXEL_CONE_WGSL),
205        ];
206        for &(name, qualia_export, etalon_export) in pairs {
207            assert_eq!(
208                qualia_export.as_bytes(),
209                etalon_export.as_bytes(),
210                "viewport::{name} diverged from etalon_render::shaders::{name}"
211            );
212        }
213    }
214
215    #[test]
216    fn rm03_on_disk_viewport_wgsl_files_never_diverge_from_canonical_etalon_render() {
217        // RM-03 retired (`R`): `crates/qualia-core-db/src/shaders/viewport/*.wgsl` duplicates are removed
218        // and all viewport shaders are sourced directly from `etalon_render::shaders::*`.
219        assert_eq!(
220            viewport::SPECTRAL_WGSL.as_bytes(),
221            etalon_render::shaders::SPECTRAL_WGSL.as_bytes()
222        );
223        assert_eq!(
224            viewport::HOLOGRAPHIC_WGSL.as_bytes(),
225            etalon_render::shaders::HOLOGRAPHIC_WGSL.as_bytes()
226        );
227        assert_eq!(
228            viewport::EMF_VOLUMETRIC_WGSL.as_bytes(),
229            etalon_render::shaders::EMF_VOLUMETRIC_WGSL.as_bytes()
230        );
231        assert_eq!(
232            viewport::TEMPORAL_RESOLVE_WGSL.as_bytes(),
233            etalon_render::shaders::TEMPORAL_RESOLVE_WGSL.as_bytes()
234        );
235        assert_eq!(
236            viewport::INDIRECT_CULL_WGSL.as_bytes(),
237            etalon_render::shaders::INSTANCE_CULL_INDIRECT_WGSL.as_bytes()
238        );
239        assert_eq!(
240            viewport::WATER_SURFACE_WGSL.as_bytes(),
241            etalon_render::shaders::WATER_WGSL.as_bytes()
242        );
243
244        for (name, src) in [
245            ("SPECTRAL_WGSL", viewport::SPECTRAL_WGSL),
246            ("HOLOGRAPHIC_WGSL", viewport::HOLOGRAPHIC_WGSL),
247            ("EMF_VOLUMETRIC_WGSL", viewport::EMF_VOLUMETRIC_WGSL),
248            ("TEMPORAL_RESOLVE_WGSL", viewport::TEMPORAL_RESOLVE_WGSL),
249            ("INDIRECT_CULL_WGSL", viewport::INDIRECT_CULL_WGSL),
250            ("WATER_SURFACE_WGSL", viewport::WATER_SURFACE_WGSL),
251        ] {
252            let module = naga::front::wgsl::parse_str(src)
253                .unwrap_or_else(|e| panic!("viewport::{name} failed Naga WGSL frontend parse: {e}"));
254            let mut validator = naga::valid::Validator::new(
255                naga::valid::ValidationFlags::all(),
256                naga::valid::Capabilities::all(),
257            );
258            validator
259                .validate(&module)
260                .unwrap_or_else(|e| panic!("viewport::{name} failed Naga validation: {e}"));
261        }
262    }
263
264    #[test]
265    fn rm03_canonical_registry_lookup_and_wgsl_validation() {
266        assert_eq!(
267            canonical_shader_source("nquin_warp_scan.wgsl").unwrap().as_bytes(),
268            NQUIN_WARP_SCAN_WGSL.as_bytes()
269        );
270        assert_eq!(
271            canonical_shader_source("sieve.wgsl").unwrap().as_bytes(),
272            SIEVE_WGSL.as_bytes()
273        );
274        assert_eq!(
275            canonical_shader_source("holographic.wgsl").unwrap().as_bytes(),
276            HOLOGRAPHIC_WGSL.as_bytes()
277        );
278        assert_eq!(
279            canonical_shader_source("emf_volumetric.wgsl").unwrap().as_bytes(),
280            EMF_VOLUMETRIC_WGSL.as_bytes()
281        );
282        assert!(canonical_shader_source("nonexistent.wgsl").is_none());
283
284        for (name, wgsl) in [
285            ("nquin_warp_scan.wgsl", NQUIN_WARP_SCAN_WGSL),
286            ("sieve.wgsl", SIEVE_WGSL),
287            ("holographic.wgsl", HOLOGRAPHIC_WGSL),
288            ("holographic_standalone.wgsl", HOLOGRAPHIC_STANDALONE_WGSL),
289            ("emf_volumetric.wgsl", EMF_VOLUMETRIC_WGSL),
290            ("emf_volumetric_stokes.wgsl", EMF_VOLUMETRIC_STOKES_WGSL),
291            ("gemm_substrate.wgsl", GEMM_SUBSTRATE_WGSL),
292            ("topk_reduction.wgsl", TOPK_REDUCTION_WGSL),
293        ] {
294            let module = naga::front::wgsl::parse_str(wgsl)
295                .unwrap_or_else(|e| panic!("RM-03 shader {name} failed WGSL parse: {e}"));
296            let mut validator = naga::valid::Validator::new(
297                naga::valid::ValidationFlags::all(),
298                naga::valid::Capabilities::all(),
299            );
300            validator
301                .validate(&module)
302                .unwrap_or_else(|e| panic!("RM-03 shader {name} failed Naga validation: {e}"));
303        }
304    }
305}