@woosh/meep-engine 3.38.0 → 3.39.0

package/src/shade/renderer/shader/chunk/screen_space/chunk_screen_space_newton_ray.js

@@ -29,41 +29,76 @@ fn screen_space_ray_projectable(p: vec3<f32>, projection: mat4x4<f32>) -> bool {
     return clip.w > 1e-6 && all(abs(clip) < vec4<f32>(1e30));
 }
 
-// Reconstruct the receiver at the subpixel lookup on its local tangent plane.
-// A texel-center position is a different surface point: projecting its nearest
-// point on the ray can exceed one pixel at grazing angles even for an exact hit.
-fn screen_space_ray_validate(
-    ray: Ray, uv: vec2<f32>, depth: texture_2d<f32>, normals: texture_2d<u32>,
-    projection: mat4x4<f32>, inverse_projection: mat4x4<f32>, world_to_view: mat4x4<f32>,
-    distance_tolerance: f32,
-) -> ScreenSpaceRayHit {
-    var hit = ScreenSpaceRayHit(uv, 0.0, 1e20, 0u, 1u);
-    if (!screen_space_ray_in_bounds(uv)) { return hit; }
+// The receiver sampled at one lookup: its device depth and its local tangent plane.
+struct ScreenSpaceRayReceiver {
+    depth: f32,
+    plane: vec4<f32>,
+}
+
+// One G-buffer fetch. Depth is stored at the texel center; .zw is the geometric
+// face normal, while .xy includes material normal mapping.
+fn screen_space_ray_load_receiver(
+    uv: vec2<f32>, depth: texture_2d<f32>, normals: texture_2d<u32>,
+    inverse_projection: mat4x4<f32>, world_to_view: mat4x4<f32>,
+) -> ScreenSpaceRayReceiver {
     let size = textureDimensions(depth, 0);
     let coord = vec2<i32>(uv * vec2<f32>(size));
     let d = textureLoad(depth, coord, 0).r;
-    if (is_background(d)) { hit.status = 2u; return hit; }
     let center = (vec2<f32>(coord) + 0.5) / vec2<f32>(size);
-    let center_position = inv_project_position(vec3<f32>(center, d), inverse_projection);
-    let normal = (world_to_view * vec4f(decode_g_buffer_normal(textureLoad(normals, coord, 0).zw), 0.0)).xyz;
-    let lookup_ray = inv_project_position(vec3f(uv, d), inverse_projection);
-    let denominator = dot(normal, lookup_ray);
-    if (!(abs(denominator) > 1e-6)) { hit.status = 3u; return hit; }
-    let scale = dot(normal, center_position) / denominator;
-    if (!(scale > 0.0)) { hit.status = 3u; return hit; }
-    let p = lookup_ray * scale;
+    let position = inv_project_position(vec3<f32>(center, d), inverse_projection);
+    let normal = (world_to_view * vec4<f32>(decode_g_buffer_normal(textureLoad(normals, coord, 0).zw), 0.0)).xyz;
+    return ScreenSpaceRayReceiver(d, plane_from_normal_and_point(normal, position));
+}
+
+// Reconstruct the receiver at the subpixel lookup on its local tangent plane, where the
+// lookup's camera ray meets it. A texel-center position is a different surface point:
+// projecting its nearest point on the ray can exceed one pixel at grazing angles even for
+// an exact hit. w is the scale along the camera ray. Where it is not positive the plane
+// has no intersection in front of the eye, and xyz is the depth sample under the lookup.
+fn screen_space_ray_lookup_position(
+    uv: vec2<f32>, receiver: ScreenSpaceRayReceiver, inverse_projection: mat4x4<f32>,
+) -> vec4<f32> {
+    let lookup_ray = inv_project_position(vec3f(uv, receiver.depth), inverse_projection);
+    let denominator = dot(receiver.plane.xyz, lookup_ray);
+    if (!(abs(denominator) > 1e-6)) { return vec4<f32>(lookup_ray, 0.0); }
+    let scale = -receiver.plane.w / denominator;
+    return vec4<f32>(select(lookup_ray, lookup_ray * scale, scale > 0.0), scale);
+}
+
+fn screen_space_ray_accept(
+    ray: Ray, uv: vec2<f32>, receiver: ScreenSpaceRayReceiver, size: vec2<f32>,
+    projection: mat4x4<f32>, inverse_projection: mat4x4<f32>, distance_tolerance: f32,
+) -> ScreenSpaceRayHit {
+    var hit = ScreenSpaceRayHit(uv, 0.0, 1e20, 0u, 1u);
+    let lookup = screen_space_ray_lookup_position(uv, receiver, inverse_projection);
+    if (!(lookup.w > 0.0)) { hit.status = 3u; return hit; }
+    let p = lookup.xyz;
     let travel = dot(p - ray.origin, ray.direction);
     hit.distance = travel;
     if (!(travel > 1e-4 && travel <= ray.tmax)) { hit.status = 4u; return hit; }
     let nearest = ray_nearest_point(ray, p);
     if (!screen_space_ray_projectable(nearest, projection)) { return hit; }
-    let pixel_error = length((project_position(nearest, projection).xy - uv) * vec2<f32>(size));
+    let pixel_error = length((project_position(nearest, projection).xy - uv) * size);
     hit.residual = distance(p, nearest);
     hit.status = 5u;
     if (pixel_error <= 1.0 && hit.residual <= distance_tolerance) { hit.status = 0u; }
     return hit;
 }
 
+fn screen_space_ray_validate(
+    ray: Ray, uv: vec2<f32>, depth: texture_2d<f32>, normals: texture_2d<u32>,
+    projection: mat4x4<f32>, inverse_projection: mat4x4<f32>, world_to_view: mat4x4<f32>,
+    distance_tolerance: f32,
+) -> ScreenSpaceRayHit {
+    if (!screen_space_ray_in_bounds(uv)) { return ScreenSpaceRayHit(uv, 0.0, 1e20, 0u, 1u); }
+    let receiver = screen_space_ray_load_receiver(uv, depth, normals, inverse_projection, world_to_view);
+    if (is_background(receiver.depth)) { return ScreenSpaceRayHit(uv, 0.0, 1e20, 0u, 2u); }
+    return screen_space_ray_accept(ray, uv, receiver, vec2<f32>(textureDimensions(depth, 0)),
+        projection, inverse_projection, distance_tolerance);
+}
+
+// One G-buffer fetch per lookup, as in the paper: the plane that rejects lookup n
+// is also the tangent plane of update n+1. max_updates updates read max_updates+1 texels.
 fn screen_space_newton_ray(
     ray: Ray, seed_uv: vec2<f32>, depth: texture_2d<f32>, normals: texture_2d<u32>,
     projection: mat4x4<f32>, inverse_projection: mat4x4<f32>, world_to_view: mat4x4<f32>,
@@ -71,28 +106,27 @@ fn screen_space_newton_ray(
 ) -> ScreenSpaceRayHit {
     var uv = seed_uv;
     var hit = ScreenSpaceRayHit(uv, 0.0, 1e20, 0u, 5u);
-    let size = textureDimensions(depth, 0);
-    for (var i = 0u; i < min(max_updates, 16u); i++) {
+    let size = vec2<f32>(textureDimensions(depth, 0));
+    let updates = min(max_updates, 16u);
+    if (updates == 0u) { return hit; }
+    for (var i = 0u; i <= updates; i++) {
+        let iterations = max(i, 1u);
+        if (!screen_space_ray_in_bounds(uv)) { return ScreenSpaceRayHit(uv, 0.0, 1e20, iterations, 1u); }
+        let receiver = screen_space_ray_load_receiver(uv, depth, normals, inverse_projection, world_to_view);
+        if (is_background(receiver.depth)) { return ScreenSpaceRayHit(uv, 0.0, 1e20, iterations, 2u); }
+        // The seed is the undisplaced background, not an update; only updated lookups are accepted.
+        if (i > 0u) {
+            hit = screen_space_ray_accept(ray, uv, receiver, size, projection, inverse_projection, distance_tolerance);
+            hit.iterations = i;
+            if (hit.status == 0u || hit.status == 1u || i == updates) { return hit; }
+        }
         hit.iterations = i + 1u;
-        if (!screen_space_ray_in_bounds(uv)) { hit.status = 1u; return hit; }
-        let coord = vec2<i32>(uv * vec2<f32>(size));
-        let d = textureLoad(depth, coord, 0).r;
-        if (is_background(d)) { hit.status = 2u; return hit; }
-        let center = (vec2<f32>(coord) + 0.5) / vec2<f32>(size);
-        let receiver = inv_project_position(vec3<f32>(center, d), inverse_projection);
-        // .zw is the geometric face normal; .xy includes material normal mapping.
-        let world_normal = decode_g_buffer_normal(textureLoad(normals, coord, 0).zw);
-        let normal = (world_to_view * vec4<f32>(world_normal, 0.0)).xyz;
-        if (!(abs(dot(ray.direction, normal)) > 1e-4)) { hit.status = 3u; return hit; }
-        let plane = plane_from_normal_and_point(normal, receiver);
-        let travel = plane_ray_raycast(ray.origin, ray.direction, plane);
+        if (!(abs(dot(ray.direction, receiver.plane.xyz)) > 1e-4)) { hit.status = 3u; return hit; }
+        let travel = plane_ray_raycast(ray.origin, ray.direction, receiver.plane);
         if (!(travel > 1e-4 && travel <= ray.tmax)) { hit.status = 4u; return hit; }
         let next = ray_at(ray.origin, ray.direction, travel);
         if (!screen_space_ray_projectable(next, projection)) { hit.status = 1u; return hit; }
         uv = project_position(next, projection).xy;
-        hit = screen_space_ray_validate(ray, uv, depth, normals, projection, inverse_projection, world_to_view, distance_tolerance);
-        hit.iterations = i + 1u;
-        if (hit.status == 0u || hit.status == 1u || hit.status == 2u) { return hit; }
     }
     return hit;
 }

package/src/shade/renderer/shader/chunk/spherical_harmonics/chunk_sh_band_of_index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The band `l` a band-major coefficient index belongs to — the inverse of `sh_index(m, l)` up to `m`,
+ * which is then `index - l * (l + 1)`.
+ *
+ * `floor(sqrt(index))`, corrected by one either way: `f32` square roots of perfect squares are exact,
+ * but the correction keeps the answer integer-exact rather than trusting rounding near a square — for
+ * every index below 65535², past which `(l + 1)²` wraps in `u32`. The ten bands the engine generates
+ * stop at index 99.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_sh_band_of_index: CodeChunk;
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_sh_band_of_index.d.ts.map

package/src/shade/renderer/shader/chunk/spherical_harmonics/chunk_sh_band_of_index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_sh_band_of_index.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/chunk/spherical_harmonics/chunk_sh_band_of_index.js"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH,qCAFU,SAAS,CAkBhB;0BA7BuB,6BAA6B"}

package/src/shade/renderer/shader/chunk/spherical_harmonics/chunk_sh_band_of_index.js

@@ -0,0 +1,30 @@
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+
+/**
+ * The band `l` a band-major coefficient index belongs to — the inverse of `sh_index(m, l)` up to `m`,
+ * which is then `index - l * (l + 1)`.
+ *
+ * `floor(sqrt(index))`, corrected by one either way: `f32` square roots of perfect squares are exact,
+ * but the correction keeps the answer integer-exact rather than trusting rounding near a square — for
+ * every index below 65535², past which `(l + 1)²` wraps in `u32`. The ten bands the engine generates
+ * stop at index 99.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_sh_band_of_index = CodeChunk.from(
+    //language=WGSL
+    `
+fn sh_band_of_index(index: u32) -> u32 {
+    var l = u32(sqrt(f32(index)));
+
+    if ((l + 1u) * (l + 1u) <= index) {
+        l += 1u;
+    }
+
+    if (l * l > index) {
+        l -= 1u;
+    }
+
+    return l;
+}
+`);

package/src/shade/renderer/shader/chunk/spherical_harmonics/chunk_sh_basis_function.d.ts

@@ -0,0 +1,19 @@
+/**
+ * One real spherical harmonic `Y(l, m)` at a unit direction, for any band — the general form of the
+ * fixed-order `sh2_basis_at`/`sh3_basis_at` and of the generated `sh{N}_basis_at` chunks, in the same
+ * convention: all-positive (no Condon-Shortley phase), zonal axis +Z, `m` signed as in `sh_index(m, l)`
+ * (negative `m` is the `sin`/`y` family).
+ *
+ * Fully normalized associated Legendre recurrence plus `(x + iy)^|m|` for the azimuth, so there is no
+ * trigonometry and no factorial: `|m|` steps to the sectoral term, then `l - |m|` steps up the band.
+ * The work is `O(l)`; at the ten bands the SH-exponential encoder uses that is at most nineteen steps.
+ * Meant for kernels that run once (projection, fitting), where one function serving every order beats
+ * a chunk per order. Per-pixel reconstruction should use the unrolled `sh{N}_*` chunks instead.
+ *
+ * CPU twin: `core/geom/3d/sphere/harmonics/sh_basis_at.js`, which documents the recurrence.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_sh_basis_function: CodeChunk;
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_sh_basis_function.d.ts.map

package/src/shade/renderer/shader/chunk/spherical_harmonics/chunk_sh_basis_function.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_sh_basis_function.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/chunk/spherical_harmonics/chunk_sh_basis_function.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AACH,sCAFU,SAAS,CAwDhB;0BAxEuB,6BAA6B"}

package/src/shade/renderer/shader/chunk/spherical_harmonics/chunk_sh_basis_function.js

@@ -0,0 +1,73 @@
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+
+/**
+ * One real spherical harmonic `Y(l, m)` at a unit direction, for any band — the general form of the
+ * fixed-order `sh2_basis_at`/`sh3_basis_at` and of the generated `sh{N}_basis_at` chunks, in the same
+ * convention: all-positive (no Condon-Shortley phase), zonal axis +Z, `m` signed as in `sh_index(m, l)`
+ * (negative `m` is the `sin`/`y` family).
+ *
+ * Fully normalized associated Legendre recurrence plus `(x + iy)^|m|` for the azimuth, so there is no
+ * trigonometry and no factorial: `|m|` steps to the sectoral term, then `l - |m|` steps up the band.
+ * The work is `O(l)`; at the ten bands the SH-exponential encoder uses that is at most nineteen steps.
+ * Meant for kernels that run once (projection, fitting), where one function serving every order beats
+ * a chunk per order. Per-pixel reconstruction should use the unrolled `sh{N}_*` chunks instead.
+ *
+ * CPU twin: `core/geom/3d/sphere/harmonics/sh_basis_at.js`, which documents the recurrence.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_sh_basis_function = CodeChunk.from(
+    //language=WGSL
+    `
+fn sh_basis_function(m: i32, l: i32, direction: vec3<f32>) -> f32 {
+    let order = u32(abs(m));
+    let band = u32(l);
+
+    let x = direction.x;
+    let y = direction.y;
+    let z = direction.z;
+
+    // (x + iy)^|m| = c + i s, and Q(|m|, |m|) / sqrt(2|m| + 1)
+    var c = 1.0;
+    var s = 0.0;
+    var sectoral = 0.28209479177387814; // 1 / sqrt(4 pi)
+
+    for (var k = 1u; k <= order; k++) {
+        let c_next = x * c - y * s;
+        s = x * s + y * c;
+        c = c_next;
+
+        sectoral *= sqrt(f32(2u * k - 1u) / f32(2u * k));
+    }
+
+    var q_previous = 0.0;
+    var q = sectoral * sqrt(f32(2u * order + 1u));
+
+    if (band > order) {
+        q_previous = q;
+        q = sqrt(f32(2u * order + 3u)) * z * q;
+    }
+
+    let mm = f32(order * order);
+
+    for (var k = order + 2u; k <= band; k++) {
+        let kk = f32(k * k);
+        let k1 = f32((k - 1u) * (k - 1u));
+
+        let a = sqrt((4.0 * kk - 1.0) / (kk - mm));
+        let b = sqrt((k1 - mm) / (4.0 * k1 - 1.0));
+
+        let q_next = a * (z * q - b * q_previous);
+
+        q_previous = q;
+        q = q_next;
+    }
+
+    if (m == 0) {
+        return q;
+    }
+
+    // sqrt(2), the real basis' factor on every m != 0 term
+    return 1.4142135623730951 * q * select(s, c, m > 0);
+}
+`);

package/src/shade/renderer/shader/chunk/spherical_harmonics/chunk_sh_vmf_window.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Band `l`'s attenuation under convolution with a von Mises-Fisher lobe of concentration `kappa`:
+ * `exp(-l(l+1) / (2 kappa))`. Band 0 is never attenuated.
+ *
+ * The large-kappa form of the vMF's zonal coefficients — Ref-NeRF's integrated directional encoding
+ * (Verbin et al., CVPR 2022, [VHM*22]), which Silvennoinen, Sloan, Iwanicki and Nowrouzezahrai use to
+ * encode roughness continuously in "Spherical Harmonic Exponentials for Efficient Glossy Reflections"
+ * (HPG 2025, https://doi.org/10.1111/cgf.70219), with `kappa = 1 / alpha`.
+ *
+ * The generated `sh{N}_color_evaluate_vmf` chunks fold the same factor into their unrolled bands;
+ * this is the one-band form for kernels that walk coefficients by index.
+ *
+ * CPU twin: `core/geom/3d/sphere/harmonics/sh_vmf_window.js`.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_sh_vmf_window: CodeChunk;
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_sh_vmf_window.d.ts.map

package/src/shade/renderer/shader/chunk/spherical_harmonics/chunk_sh_vmf_window.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_sh_vmf_window.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/shader/chunk/spherical_harmonics/chunk_sh_vmf_window.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AACH,kCAFU,SAAS,CAQhB;0BAxBuB,6BAA6B"}

package/src/shade/renderer/shader/chunk/spherical_harmonics/chunk_sh_vmf_window.js

@@ -0,0 +1,25 @@
+import { CodeChunk } from "../../compiler/CodeChunk.js";
+
+/**
+ * Band `l`'s attenuation under convolution with a von Mises-Fisher lobe of concentration `kappa`:
+ * `exp(-l(l+1) / (2 kappa))`. Band 0 is never attenuated.
+ *
+ * The large-kappa form of the vMF's zonal coefficients — Ref-NeRF's integrated directional encoding
+ * (Verbin et al., CVPR 2022, [VHM*22]), which Silvennoinen, Sloan, Iwanicki and Nowrouzezahrai use to
+ * encode roughness continuously in "Spherical Harmonic Exponentials for Efficient Glossy Reflections"
+ * (HPG 2025, https://doi.org/10.1111/cgf.70219), with `kappa = 1 / alpha`.
+ *
+ * The generated `sh{N}_color_evaluate_vmf` chunks fold the same factor into their unrolled bands;
+ * this is the one-band form for kernels that walk coefficients by index.
+ *
+ * CPU twin: `core/geom/3d/sphere/harmonics/sh_vmf_window.js`.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_sh_vmf_window = CodeChunk.from(
+    //language=WGSL
+    `
+fn sh_vmf_window(l: f32, kappa: f32) -> f32 {
+    return exp(-l * (l + 1.0) / (2.0 * kappa));
+}
+`);

package/src/shade/renderer/shader/chunk/spherical_harmonics/exponential/SH_EXP_P4Q2_PROBE_STRUCT.d.ts

@@ -0,0 +1,17 @@
+/**
+ * A spherical-harmonic-exponential reflection probe in the configuration of Silvennoinen et al.'s
+ * results (HPG 2025, https://doi.org/10.1111/cgf.70219): P to degree 4, Q to degree 2 — five and three
+ * bands. What `SHExpEncoder` writes with `SH_EXP_P4Q2_SETTINGS` (see `sh_exp_probe_vec4_count` for the
+ * layout), 560 bytes:
+ *
+ * - `header`: `(alpha_min, alpha_max, 5, 3)` — the GGX alpha range the probe was fitted over and its band counts;
+ * - `p`: log-radiance coefficients of the reflection term, RGB, band-major;
+ * - `q`: those of the half-reflection term; `q[0]` is always zero, its band 0 being folded into `p[0]`.
+ *
+ * 33 of the 35 slots carry information, three floats each; `vec3` arrays stride 16 bytes in WGSL.
+ *
+ * @type {WebGPUStruct}
+ */
+export const SH_EXP_P4Q2_PROBE_STRUCT: WebGPUStruct;
+import { WebGPUStruct } from "../../../type/WebGPUStruct.js";
+//# sourceMappingURL=SH_EXP_P4Q2_PROBE_STRUCT.d.ts.map

package/src/shade/renderer/shader/chunk/spherical_harmonics/exponential/SH_EXP_P4Q2_PROBE_STRUCT.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SH_EXP_P4Q2_PROBE_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/spherical_harmonics/exponential/SH_EXP_P4Q2_PROBE_STRUCT.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;GAaG;AACH,uCAFU,YAAY,CAMD;6BApBQ,+BAA+B"}

package/src/shade/renderer/shader/chunk/spherical_harmonics/exponential/SH_EXP_P4Q2_PROBE_STRUCT.js

@@ -0,0 +1,23 @@
+import { vec3f, vec4f } from "../../../type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../../type/WebGPUArray.js";
+import { WebGPUStruct } from "../../../type/WebGPUStruct.js";
+
+/**
+ * A spherical-harmonic-exponential reflection probe in the configuration of Silvennoinen et al.'s
+ * results (HPG 2025, https://doi.org/10.1111/cgf.70219): P to degree 4, Q to degree 2 — five and three
+ * bands. What `SHExpEncoder` writes with `SH_EXP_P4Q2_SETTINGS` (see `sh_exp_probe_vec4_count` for the
+ * layout), 560 bytes:
+ *
+ * - `header`: `(alpha_min, alpha_max, 5, 3)` — the GGX alpha range the probe was fitted over and its band counts;
+ * - `p`: log-radiance coefficients of the reflection term, RGB, band-major;
+ * - `q`: those of the half-reflection term; `q[0]` is always zero, its band 0 being folded into `p[0]`.
+ *
+ * 33 of the 35 slots carry information, three floats each; `vec3` arrays stride 16 bytes in WGSL.
+ *
+ * @type {WebGPUStruct}
+ */
+export const SH_EXP_P4Q2_PROBE_STRUCT = WebGPUStruct.from({
+    header: vec4f,
+    p: WebGPUArray.from(vec3f, 25),
+    q: WebGPUArray.from(vec3f, 9),
+}, "SHExpProbeP4Q2");

package/src/shade/renderer/shader/chunk/spherical_harmonics/exponential/chunk_sh_exp_p4q2_base_reflectance.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Reconstructs the GGX base reflectance of a spherical-harmonic-exponential probe
+ * ({@link SH_EXP_P4Q2_PROBE_STRUCT}):
+ *
+ *     E0(v, n, alpha) ≈ exp(<vMF(1/alpha) ⊙ Y(r), p>) · exp(<vMF(1/alpha) ⊙ Y(h_r), q>)
+ *     r = reflect(-v, n),  h_r = normalize(n + r)
+ *
+ * — Silvennoinen, Sloan, Iwanicki and Nowrouzezahrai, "Spherical Harmonic Exponentials for Efficient
+ * Glossy Reflections", HPG 2025 (https://doi.org/10.1111/cgf.70219, "Runtime Reconstruction"; talk:
+ * https://www.youtube.com/watch?v=THVMMNZ68iA). The two exponentials share one `exp`.
+ *
+ * `E0` is the environment reflected by the GGX BRDF without Fresnel, `∫ L(l) f_DV(v, n, l, alpha) <l, n> dl`:
+ * radiance already weighted by the BRDF's directional albedo. `sh_exp_specular` applies Fresnel;
+ * `sh_exp_radiance` divides the albedo out for code that wants the split sum's prefiltered radiance.
+ *
+ * `alpha` is GGX alpha (roughness²) and is clamped to the range in the probe's header: the fit says
+ * nothing outside it, and below it the windows open onto bands fitted under attenuation.
+ * `view_direction` points from the surface towards the viewer; both vectors are unit length.
+ *
+ * Cost: two generated 5- and 3-band vMF evaluations (34 terms, two `exp` for the windows) and one `exp`.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_sh_exp_p4q2_base_reflectance: CodeChunk;
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_sh_exp_p4q2_base_reflectance.d.ts.map

package/src/shade/renderer/shader/chunk/spherical_harmonics/exponential/chunk_sh_exp_p4q2_base_reflectance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_sh_exp_p4q2_base_reflectance.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/spherical_harmonics/exponential/chunk_sh_exp_p4q2_base_reflectance.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,iDAFU,SAAS,CA4BhB;0BAtDuB,gCAAgC"}

package/src/shade/renderer/shader/chunk/spherical_harmonics/exponential/chunk_sh_exp_p4q2_base_reflectance.js

@@ -0,0 +1,55 @@
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+import { chunk_sh3_color_evaluate_vmf } from "../generated/chunk_sh3_color_evaluate_vmf.js";
+import { chunk_sh5_color_evaluate_vmf } from "../generated/chunk_sh5_color_evaluate_vmf.js";
+import { SH_EXP_P4Q2_PROBE_STRUCT } from "./SH_EXP_P4Q2_PROBE_STRUCT.js";
+
+/**
+ * Reconstructs the GGX base reflectance of a spherical-harmonic-exponential probe
+ * ({@link SH_EXP_P4Q2_PROBE_STRUCT}):
+ *
+ *     E0(v, n, alpha) ≈ exp(<vMF(1/alpha) ⊙ Y(r), p>) · exp(<vMF(1/alpha) ⊙ Y(h_r), q>)
+ *     r = reflect(-v, n),  h_r = normalize(n + r)
+ *
+ * — Silvennoinen, Sloan, Iwanicki and Nowrouzezahrai, "Spherical Harmonic Exponentials for Efficient
+ * Glossy Reflections", HPG 2025 (https://doi.org/10.1111/cgf.70219, "Runtime Reconstruction"; talk:
+ * https://www.youtube.com/watch?v=THVMMNZ68iA). The two exponentials share one `exp`.
+ *
+ * `E0` is the environment reflected by the GGX BRDF without Fresnel, `∫ L(l) f_DV(v, n, l, alpha) <l, n> dl`:
+ * radiance already weighted by the BRDF's directional albedo. `sh_exp_specular` applies Fresnel;
+ * `sh_exp_radiance` divides the albedo out for code that wants the split sum's prefiltered radiance.
+ *
+ * `alpha` is GGX alpha (roughness²) and is clamped to the range in the probe's header: the fit says
+ * nothing outside it, and below it the windows open onto bands fitted under attenuation.
+ * `view_direction` points from the surface towards the viewer; both vectors are unit length.
+ *
+ * Cost: two generated 5- and 3-band vMF evaluations (34 terms, two `exp` for the windows) and one `exp`.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_sh_exp_p4q2_base_reflectance = CodeChunk.from(
+    //language=WGSL
+    `
+fn sh_exp_p4q2_base_reflectance(
+    probe: SHExpProbeP4Q2,
+    view_direction: vec3<f32>,
+    normal: vec3<f32>,
+    alpha: f32
+) -> vec3<f32> {
+    let r = reflect(-view_direction, normal);
+
+    // |n + r|^2 = 2 + 2 dot(n, v): zero only for a view straight through the surface
+    let normal_plus_r = normal + r;
+    let h_r = normal_plus_r * inverseSqrt(max(dot(normal_plus_r, normal_plus_r), 1e-12));
+
+    let kappa = 1.0 / clamp(alpha, probe.header.x, probe.header.y);
+
+    return exp(
+        sh5_color_evaluate_vmf(probe.p, r, kappa)
+        + sh3_color_evaluate_vmf(probe.q, h_r, kappa)
+    );
+}
+`, [
+    SH_EXP_P4Q2_PROBE_STRUCT.declaration_chunk,
+    chunk_sh5_color_evaluate_vmf,
+    chunk_sh3_color_evaluate_vmf,
+]);

package/src/shade/renderer/shader/chunk/spherical_harmonics/exponential/chunk_sh_exp_split_sum.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Specular reflection from an SH-exponential probe's base reflectance `E0`, with Fresnel.
+ *
+ * Silvennoinen et al. (HPG 2025, https://doi.org/10.1111/cgf.70219, "Fresnel Tail Reflectance") split
+ * reflected radiance as `E = F0 E0 + (1 - F0) E1` and model only `E0`; the Fresnel tail
+ * `E1 = ∫ L f_DV (1 - <v,h>)^5 <l,n> dl` is approximated, as in the split sum [Kar13], by assuming the
+ * tail-weighted lobe sees the same mean radiance as the base one. With the split sum's scale and bias
+ * `A = ∫ f_DV (1 - Fc) <l,n>` and `B = ∫ f_DV Fc <l,n>`, so that `A + B` is the BRDF's directional
+ * albedo, that is `E1 ≈ E0 · B / (A + B)` and
+ *
+ *     E ≈ E0 · (F0 · A + F90 · B) / (A + B)
+ *
+ * The paper (Section 4.2, eq. 15) writes `E1 ≈ E0 · ∫ f_DV Fc <l,n>`: it takes the environment as a
+ * constant equal to `E0`. But a constant environment `c` has `E0 = c (A + B)`, so that constant is
+ * `E0 / (A + B)`; written without the division the tail is undercounted by a factor `A + B` — the
+ * energy the paper's Figure 3 says its tail loses at grazing angles. For a white environment the form
+ * here is exact (`E1 / E0` equals `B / (A + B)` to four decimals across alpha and NoV). Against a
+ * quadrature reference on the Venice-sunset map, with exact `E0` and F0 = 0.04, its log RMSE was 0.058
+ * against the paper form's 0.067 at NoV >= 0.5 and 0.206 against 0.226 in [0.2, 0.5); below 0.2, where
+ * `A + B` is near 1 and the two forms nearly coincide, 0.317 against 0.315 (f64 prototype, 2026-10-03).
+ *
+ * A split stays here by design. Fitting the tail with an SH exponential of its own (P4 Q2, twice the
+ * storage) instead was measured too: up to three times the error at grazing (tonemapped 0.245 against
+ * 0.083 below NoV 0.2 on Venice, 0.164 against 0.106 on Rustig-Koppie), because the tail's weight
+ * depends on `n·v`, which `P(r) Q(h_r)` cannot represent and the 2-D factor `B / (A + B)` carries exactly.
+ *
+ * `dfg` is a split-sum LUT read at `(NoV, roughness)`: `.x` the F0 scale A, `.y` the F90 bias B.
+ * The engine's `tSplitSum` (`assets/textures/split_sum.bin`) weights both by `F_Hauber`'s `(1 - VoH)^4`,
+ * as `chunk_integrate_brdf` does, so its `A + B` is the directional albedo to within 0.06% (against an f64
+ * quadrature, 2026-10-03; held by `split_sum_asset.spec.js`). And this is single scattering:
+ * `compute_indirect_specular` adds Turquin's multiple-scattering term, `1 + F0 (1 - Ess) / Ess`, which this
+ * does not.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_sh_exp_specular: CodeChunk;
+/**
+ * The view-dependent prefiltered radiance an SH-exponential probe encodes: its base reflectance `E0`
+ * with the BRDF's directional albedo `A + B` divided out — the BRDF-weighted mean radiance the split
+ * sum's prefiltered map stands for, but for this view rather than for `v = n`.
+ *
+ * This is what to hand `compute_indirect_specular` in place of a prefiltered map's radiance. That
+ * applies `F0 · A + F90 · B` and Turquin's multiple scattering on top, so its result is
+ * {@link chunk_sh_exp_specular}'s times the multiple-scattering factor: at alpha 1 and normal
+ * incidence 3.16 times for a white metal, 1.09 times for F0 = 0.04. `dfg` is the split-sum LUT at
+ * `(NoV, roughness)`; the engine's carries the albedo to within 0.06% (see there).
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_sh_exp_radiance: CodeChunk;
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_sh_exp_split_sum.d.ts.map

package/src/shade/renderer/shader/chunk/spherical_harmonics/exponential/chunk_sh_exp_split_sum.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_sh_exp_split_sum.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/spherical_harmonics/exponential/chunk_sh_exp_split_sum.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,oCAFU,SAAS,CAQhB;AAEH;;;;;;;;;;;;GAYG;AACH,oCAFU,SAAS,CAQhB;0BAhEuB,gCAAgC"}

package/src/shade/renderer/shader/chunk/spherical_harmonics/exponential/chunk_sh_exp_split_sum.js

@@ -0,0 +1,65 @@
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+
+/**
+ * Specular reflection from an SH-exponential probe's base reflectance `E0`, with Fresnel.
+ *
+ * Silvennoinen et al. (HPG 2025, https://doi.org/10.1111/cgf.70219, "Fresnel Tail Reflectance") split
+ * reflected radiance as `E = F0 E0 + (1 - F0) E1` and model only `E0`; the Fresnel tail
+ * `E1 = ∫ L f_DV (1 - <v,h>)^5 <l,n> dl` is approximated, as in the split sum [Kar13], by assuming the
+ * tail-weighted lobe sees the same mean radiance as the base one. With the split sum's scale and bias
+ * `A = ∫ f_DV (1 - Fc) <l,n>` and `B = ∫ f_DV Fc <l,n>`, so that `A + B` is the BRDF's directional
+ * albedo, that is `E1 ≈ E0 · B / (A + B)` and
+ *
+ *     E ≈ E0 · (F0 · A + F90 · B) / (A + B)
+ *
+ * The paper (Section 4.2, eq. 15) writes `E1 ≈ E0 · ∫ f_DV Fc <l,n>`: it takes the environment as a
+ * constant equal to `E0`. But a constant environment `c` has `E0 = c (A + B)`, so that constant is
+ * `E0 / (A + B)`; written without the division the tail is undercounted by a factor `A + B` — the
+ * energy the paper's Figure 3 says its tail loses at grazing angles. For a white environment the form
+ * here is exact (`E1 / E0` equals `B / (A + B)` to four decimals across alpha and NoV). Against a
+ * quadrature reference on the Venice-sunset map, with exact `E0` and F0 = 0.04, its log RMSE was 0.058
+ * against the paper form's 0.067 at NoV >= 0.5 and 0.206 against 0.226 in [0.2, 0.5); below 0.2, where
+ * `A + B` is near 1 and the two forms nearly coincide, 0.317 against 0.315 (f64 prototype, 2026-10-03).
+ *
+ * A split stays here by design. Fitting the tail with an SH exponential of its own (P4 Q2, twice the
+ * storage) instead was measured too: up to three times the error at grazing (tonemapped 0.245 against
+ * 0.083 below NoV 0.2 on Venice, 0.164 against 0.106 on Rustig-Koppie), because the tail's weight
+ * depends on `n·v`, which `P(r) Q(h_r)` cannot represent and the 2-D factor `B / (A + B)` carries exactly.
+ *
+ * `dfg` is a split-sum LUT read at `(NoV, roughness)`: `.x` the F0 scale A, `.y` the F90 bias B.
+ * The engine's `tSplitSum` (`assets/textures/split_sum.bin`) weights both by `F_Hauber`'s `(1 - VoH)^4`,
+ * as `chunk_integrate_brdf` does, so its `A + B` is the directional albedo to within 0.06% (against an f64
+ * quadrature, 2026-10-03; held by `split_sum_asset.spec.js`). And this is single scattering:
+ * `compute_indirect_specular` adds Turquin's multiple-scattering term, `1 + F0 (1 - Ess) / Ess`, which this
+ * does not.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_sh_exp_specular = CodeChunk.from(
+    //language=WGSL
+    `
+fn sh_exp_specular(base_reflectance: vec3<f32>, f0: vec3<f32>, f90: f32, dfg: vec2<f32>) -> vec3<f32> {
+    return base_reflectance * (f0 * dfg.x + f90 * dfg.y) / max(dfg.x + dfg.y, 1e-6);
+}
+`);
+
+/**
+ * The view-dependent prefiltered radiance an SH-exponential probe encodes: its base reflectance `E0`
+ * with the BRDF's directional albedo `A + B` divided out — the BRDF-weighted mean radiance the split
+ * sum's prefiltered map stands for, but for this view rather than for `v = n`.
+ *
+ * This is what to hand `compute_indirect_specular` in place of a prefiltered map's radiance. That
+ * applies `F0 · A + F90 · B` and Turquin's multiple scattering on top, so its result is
+ * {@link chunk_sh_exp_specular}'s times the multiple-scattering factor: at alpha 1 and normal
+ * incidence 3.16 times for a white metal, 1.09 times for F0 = 0.04. `dfg` is the split-sum LUT at
+ * `(NoV, roughness)`; the engine's carries the albedo to within 0.06% (see there).
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_sh_exp_radiance = CodeChunk.from(
+    //language=WGSL
+    `
+fn sh_exp_radiance(base_reflectance: vec3<f32>, dfg: vec2<f32>) -> vec3<f32> {
+    return base_reflectance / max(dfg.x + dfg.y, 1e-6);
+}
+`);

package/src/shade/renderer/shader/chunk/spherical_harmonics/generated/chunk_sh10_basis_at.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The 10-band real spherical harmonic basis at a unit direction: 100 values, band-major, index
+ * `l * (l + 1) + m`, in the engine's all-positive convention (the first nine are `sh3_basis_at`).
+ *
+ * Unrolled from the normalized associated Legendre recurrence documented in
+ * `core/geom/3d/sphere/harmonics/sh_basis_at.js`, which is its CPU twin. For one coefficient of any
+ * band, `sh_basis_function`.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_sh10_basis_at: CodeChunk;
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_sh10_basis_at.d.ts.map

package/src/shade/renderer/shader/chunk/spherical_harmonics/generated/chunk_sh10_basis_at.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_sh10_basis_at.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/spherical_harmonics/generated/chunk_sh10_basis_at.js"],"names":[],"mappings":"AAIA;;;;;;;;;GASG;AACH,kCAFU,SAAS,CAwNhB;0BAlOuB,gCAAgC"}