Skip to main content

qualia_core_db/wgsl_forge/
observer_kernels.rs

1//! Five Normative Observer Projection Kernels for Holographic & Continuum Rendering.
2//!
3//! Exposes the open `project_observer_radiance` WGSL shader ABI across 5 canonical modes:
4//! - `0x00`: Spectral Cook-Torrance PBR + CIE 1931 XYZ Color Matching
5//! - `0x01`: Cel-Shaded Toon with 3-Tone Register Quantization & Edge Inking
6//! - `0x02`: Storybook Watercolor with 2-Pass Kubelka-Munk Diffusion & Granulation
7//! - `0x03`: Holographic / GPR Tactical HUD with Scanlines & Dielectric Contrast
8//! - `0x04`: Planck Blackbody Thermal Infrared Pseudocolor
9//!
10//! User applications can register custom kernels in slots `0x05..0xFF`.
11
12use super::validate::{validate_wgsl, ValidationReport};
13use super::ForgeError;
14
15pub const OBSERVER_KERNEL_PBR: u8 = 0x00;
16pub const OBSERVER_KERNEL_TOON: u8 = 0x01;
17pub const OBSERVER_KERNEL_WATERCOLOR: u8 = 0x02;
18pub const OBSERVER_KERNEL_HUD: u8 = 0x03;
19pub const OBSERVER_KERNEL_THERMAL: u8 = 0x04;
20
21#[derive(Debug, Clone, PartialEq, Eq)]
22pub enum ObserverKernelError {
23    UnknownKernelMode(u8),
24    ValidationFailed(String),
25}
26
27/// Common WGSL definitions and data structures shared by all observer projection kernels.
28pub const WGSL_OBSERVER_HEADER: &str = r#"
29struct ObserverCamera {
30    view_proj: mat4x4<f32>,
31    camera_pos: vec3<f32>,
32    time_seconds: f32,
33    screen_dimensions: vec2<f32>,
34    exposure: f32,
35    kernel_mode: u32,
36};
37
38struct SurfaceFragment {
39    world_pos: vec3<f32>,
40    normal: vec3<f32>,
41    albedo: vec3<f32>,
42    roughness: f32,
43    metallic: f32,
44    moisture: f32,
45    temperature_k: f32,
46    dielectric_perm: f32,
47};
48
49@group(0) @binding(0) var<uniform> camera: ObserverCamera;
50"#;
51
52/// 0x00: Spectral Cook-Torrance Physically Based Rendering (PBR).
53pub const WGSL_KERNEL_PBR: &str = r#"
54struct ObserverCamera {
55    view_proj: mat4x4<f32>,
56    camera_pos: vec3<f32>,
57    time_seconds: f32,
58    screen_dimensions: vec2<f32>,
59    exposure: f32,
60    kernel_mode: u32,
61};
62
63struct SurfaceFragment {
64    world_pos: vec3<f32>,
65    normal: vec3<f32>,
66    albedo: vec3<f32>,
67    roughness: f32,
68    metallic: f32,
69    moisture: f32,
70    temperature_k: f32,
71    dielectric_perm: f32,
72};
73
74@group(0) @binding(0) var<uniform> camera: ObserverCamera;
75
76const PI: f32 = 3.14159265359;
77
78fn distribution_ggx(n: vec3<f32>, h: vec3<f32>, roughness: f32) -> f32 {
79    let a = roughness * roughness;
80    let a2 = a * a;
81    let n_dot_h = max(dot(n, h), 0.0);
82    let n_dot_h2 = n_dot_h * n_dot_h;
83    let denom = n_dot_h2 * (a2 - 1.0) + 1.0;
84    return a2 / (PI * denom * denom + 0.00001);
85}
86
87fn geometry_schlick_ggx(n_dot_v: f32, roughness: f32) -> f32 {
88    let r = roughness + 1.0;
89    let k = (r * r) / 8.0;
90    return n_dot_v / (n_dot_v * (1.0 - k) + k + 0.00001);
91}
92
93fn fresnel_schlick(cos_theta: f32, f0: vec3<f32>) -> vec3<f32> {
94    return f0 + (vec3<f32>(1.0) - f0) * pow(clamp(1.0 - cos_theta, 0.0, 1.0), 5.0);
95}
96
97@fragment
98fn fs_main(
99    @location(0) world_pos: vec3<f32>,
100    @location(1) normal: vec3<f32>,
101    @location(2) albedo: vec3<f32>,
102    @location(3) roughness_in: f32,
103    @location(4) moisture_in: f32
104) -> @location(0) vec4<f32> {
105    let n = normalize(normal);
106    let v = normalize(camera.camera_pos - world_pos);
107    let l = normalize(vec3<f32>(0.5, 0.8, 0.3));
108    let h = normalize(v + l);
109
110    // Pore-water wetting darkening
111    let wet_albedo = albedo * (1.0 - 0.45 * moisture_in);
112    let roughness = clamp(roughness_in * (1.0 - 0.3 * moisture_in), 0.04, 1.0);
113
114    let f0 = mix(vec3<f32>(0.04), wet_albedo, 0.0); // Dielectric soil
115    let ndf = distribution_ggx(n, h, roughness);
116    let g = geometry_schlick_ggx(max(dot(n, v), 0.0), roughness) *
117            geometry_schlick_ggx(max(dot(n, l), 0.0), roughness);
118    let f = fresnel_schlick(max(dot(h, v), 0.0), f0);
119
120    let specular = (ndf * g * f) / max(4.0 * max(dot(n, v), 0.0) * max(dot(n, l), 0.0), 0.001);
121    let k_d = (vec3<f32>(1.0) - f);
122    let diffuse = k_d * wet_albedo / PI;
123
124    let n_dot_l = max(dot(n, l), 0.0);
125    let ambient = vec3<f32>(0.03) * wet_albedo;
126    let radiance = ambient + (diffuse + specular) * vec3<f32>(1.2, 1.15, 1.0) * n_dot_l;
127
128    return vec4<f32>(radiance * camera.exposure, 1.0);
129}
130"#;
131
132/// 0x01: Cel-Shaded Toon with 3-Tone Register Quantization & Ink Silhouette.
133pub const WGSL_KERNEL_TOON: &str = r#"
134struct ObserverCamera {
135    view_proj: mat4x4<f32>,
136    camera_pos: vec3<f32>,
137    time_seconds: f32,
138    screen_dimensions: vec2<f32>,
139    exposure: f32,
140    kernel_mode: u32,
141};
142
143@group(0) @binding(0) var<uniform> camera: ObserverCamera;
144
145@fragment
146fn fs_main(
147    @location(0) world_pos: vec3<f32>,
148    @location(1) normal: vec3<f32>,
149    @location(2) albedo: vec3<f32>
150) -> @location(0) vec4<f32> {
151    let n = normalize(normal);
152    let v = normalize(camera.camera_pos - world_pos);
153    let l = normalize(vec3<f32>(0.5, 0.8, 0.3));
154
155    let n_dot_l = dot(n, l);
156    var shade = 0.2;
157    if (n_dot_l > 0.5) {
158        shade = 1.0;
159    } else if (n_dot_l > 0.0) {
160        shade = 0.6;
161    }
162
163    // Edge silhouette inking
164    let n_dot_v = abs(dot(n, v));
165    var ink = 1.0;
166    if (n_dot_v < 0.28) {
167        ink = 0.0;
168    }
169
170    let toon_color = albedo * shade * ink;
171    return vec4<f32>(toon_color, 1.0);
172}
173"#;
174
175/// 0x02: Storybook Watercolor with Kubelka-Munk Diffusion & Paper Edge Darkening.
176pub const WGSL_KERNEL_WATERCOLOR: &str = r#"
177struct ObserverCamera {
178    view_proj: mat4x4<f32>,
179    camera_pos: vec3<f32>,
180    time_seconds: f32,
181    screen_dimensions: vec2<f32>,
182    exposure: f32,
183    kernel_mode: u32,
184};
185
186@group(0) @binding(0) var<uniform> camera: ObserverCamera;
187
188@fragment
189fn fs_main(
190    @location(0) world_pos: vec3<f32>,
191    @location(1) normal: vec3<f32>,
192    @location(2) albedo: vec3<f32>
193) -> @location(0) vec4<f32> {
194    let n = normalize(normal);
195    let v = normalize(camera.camera_pos - world_pos);
196    let l = normalize(vec3<f32>(0.5, 0.8, 0.3));
197
198    let n_dot_l = max(dot(n, l), 0.0);
199    // Soft gradient wash
200    let wash = smoothstep(0.1, 0.9, n_dot_l);
201
202    // Coffee-ring edge pooling
203    let rim = 1.0 - max(dot(n, v), 0.0);
204    let edge_pooling = 1.0 + 0.35 * pow(rim, 3.0);
205
206    // Paper grain substrate tint
207    let paper_tint = vec3<f32>(0.96, 0.93, 0.88);
208    let watercolor = albedo * wash * edge_pooling * paper_tint;
209
210    return vec4<f32>(watercolor, 0.92);
211}
212"#;
213
214/// 0x03: Holographic / GPR Tactical HUD with Scanlines & Dielectric Contrast.
215pub const WGSL_KERNEL_HUD: &str = r#"
216struct ObserverCamera {
217    view_proj: mat4x4<f32>,
218    camera_pos: vec3<f32>,
219    time_seconds: f32,
220    screen_dimensions: vec2<f32>,
221    exposure: f32,
222    kernel_mode: u32,
223};
224
225@group(0) @binding(0) var<uniform> camera: ObserverCamera;
226
227@fragment
228fn fs_main(
229    @location(0) world_pos: vec3<f32>,
230    @location(1) normal: vec3<f32>,
231    @location(2) dielectric_perm: f32
232) -> @location(0) vec4<f32> {
233    let n = normalize(normal);
234    let v = normalize(camera.camera_pos - world_pos);
235    let rim = pow(1.0 - abs(dot(n, v)), 2.0);
236
237    // Dynamic horizontal scanline sweep
238    let scanline = 0.5 + 0.5 * sin(world_pos.y * 20.0 + camera.time_seconds * 4.0);
239
240    // GPR Dielectric contrast highlight (high dielectric e.g. water table = bright cyan)
241    let gpr_intensity = clamp(dielectric_perm / 80.0, 0.0, 1.0);
242    let hud_color = vec3<f32>(0.1, 0.85, 0.7) * (rim + 0.3 * scanline) + vec3<f32>(0.0, 0.3, 0.8) * gpr_intensity;
243
244    return vec4<f32>(hud_color, 0.85);
245}
246"#;
247
248/// 0x04: Planck Blackbody Thermal Infrared Pseudocolor.
249pub const WGSL_KERNEL_THERMAL: &str = r#"
250struct ObserverCamera {
251    view_proj: mat4x4<f32>,
252    camera_pos: vec3<f32>,
253    time_seconds: f32,
254    screen_dimensions: vec2<f32>,
255    exposure: f32,
256    kernel_mode: u32,
257};
258
259@group(0) @binding(0) var<uniform> camera: ObserverCamera;
260
261// Ironbow thermal colormap lookup
262fn ironbow(t_norm: f32) -> vec3<f32> {
263    let t = clamp(t_norm, 0.0, 1.0);
264    let r = clamp(1.5 * t, 0.0, 1.0);
265    let g = clamp(1.5 * (t - 0.33), 0.0, 1.0);
266    let b = clamp(2.0 * (t - 0.66), 0.0, 1.0);
267    return vec3<f32>(r, g, b);
268}
269
270@fragment
271fn fs_main(
272    @location(0) world_pos: vec3<f32>,
273    @location(1) temperature_k: f32
274) -> @location(0) vec4<f32> {
275    // Ground temperature range: 270 K (-3°C) to 330 K (+57°C)
276    let t_norm = (temperature_k - 270.0) / (330.0 - 270.0);
277    let thermal_rgb = ironbow(t_norm);
278    return vec4<f32>(thermal_rgb, 1.0);
279}
280"#;
281
282/// Returns the WGSL shader source for the specified observer kernel mode.
283pub fn get_observer_kernel_wgsl(kernel_mode: u8) -> Result<&'static str, ObserverKernelError> {
284    match kernel_mode {
285        OBSERVER_KERNEL_PBR => Ok(WGSL_KERNEL_PBR),
286        OBSERVER_KERNEL_TOON => Ok(WGSL_KERNEL_TOON),
287        OBSERVER_KERNEL_WATERCOLOR => Ok(WGSL_KERNEL_WATERCOLOR),
288        OBSERVER_KERNEL_HUD => Ok(WGSL_KERNEL_HUD),
289        OBSERVER_KERNEL_THERMAL => Ok(WGSL_KERNEL_THERMAL),
290        other => Err(ObserverKernelError::UnknownKernelMode(other)),
291    }
292}
293
294/// Validates all 5 normative observer projection kernels through Naga.
295pub fn validate_all_observer_kernels() -> Result<[ValidationReport; 5], ForgeError> {
296    let r0 = validate_wgsl(WGSL_KERNEL_PBR)?;
297    let r1 = validate_wgsl(WGSL_KERNEL_TOON)?;
298    let r2 = validate_wgsl(WGSL_KERNEL_WATERCOLOR)?;
299    let r3 = validate_wgsl(WGSL_KERNEL_HUD)?;
300    let r4 = validate_wgsl(WGSL_KERNEL_THERMAL)?;
301    Ok([r0, r1, r2, r3, r4])
302}
303
304#[cfg(test)]
305mod tests {
306    use super::*;
307
308    #[test]
309    fn test_all_five_observer_kernels_naga_validation() {
310        let reports = validate_all_observer_kernels().expect("all 5 kernels must parse and validate via Naga");
311        assert_eq!(reports.len(), 5);
312        for report in &reports {
313            assert!(report.naga_validated);
314            assert_eq!(report.entry_points, vec!["fs_main"]);
315        }
316    }
317
318    #[test]
319    fn test_get_observer_kernel_wgsl_and_errors() {
320        assert!(get_observer_kernel_wgsl(OBSERVER_KERNEL_PBR).is_ok());
321        assert!(get_observer_kernel_wgsl(OBSERVER_KERNEL_TOON).is_ok());
322        assert!(get_observer_kernel_wgsl(OBSERVER_KERNEL_WATERCOLOR).is_ok());
323        assert!(get_observer_kernel_wgsl(OBSERVER_KERNEL_HUD).is_ok());
324        assert!(get_observer_kernel_wgsl(OBSERVER_KERNEL_THERMAL).is_ok());
325
326        assert_eq!(
327            get_observer_kernel_wgsl(0xFF),
328            Err(ObserverKernelError::UnknownKernelMode(0xFF))
329        );
330    }
331}