@woosh/meep-engine 3.38.0 → 3.39.0

package/src/shade/renderer/light/environment/sh_exponential/shader_sh_exp_environment_cells.js

@@ -0,0 +1,147 @@
+import { chunk_octahedral_solid_angle } from "../../../shader/chunk/geometry/octahedron/chunk_octahedral_solid_angle.js";
+import { chunk_uv_octahedral_unit_decode } from "../../../shader/chunk/geometry/octahedron/chunk_uv_octahedral_unit_decode.js";
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../../shader/resource/ShaderResourceSetDescriptor.js";
+import { WebGPUArray } from "../../../shader/type/WebGPUArray.js";
+import { vec4f } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { chunk_sh_exp_workgroup_sum, SH_EXP_WORKGROUP_SIZE } from "./chunk_sh_exp_workgroup_sum.js";
+import { SH_EXP_ENCODE_PARAMETERS_STRUCT } from "./SH_EXP_ENCODE_PARAMETERS_STRUCT.js";
+
+/**
+ * Most source texels a cell reads along one side, so 64 x 64 = 4096 a cell and 16 a lane. Maps up to
+ * 64 times the grid (4096 at the default 64 grid) are read texel by texel; past that every stride-th
+ * texel is read, standing for its stride x stride block by the solid angle of its middle texel —
+ * an 8192 map at a 64 grid reads one texel in four. A smooth field keeps its cell means to 1e-3 that
+ * way (the spec reads a 2048 map at an 8 grid, stride 4); a feature smaller than the stride can be
+ * missed or counted for its whole block.
+ *
+ * @type {number}
+ */
+export const SH_EXP_MAX_TEXELS_PER_CELL_SIDE = 64;
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.createGroup()
+    .addUniform("parameters", SH_EXP_ENCODE_PARAMETERS_STRUCT)
+    .addTexture("tEnvironment")
+    .addStorageBuffer("cells", WebGPUArray.from(vec4f), true);
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+const WORKGROUP_SIZE : u32 = ${SH_EXP_WORKGROUP_SIZE}u;
+
+// Most source texels read along one side of a cell: 64 x 64 is 16 reads a lane. A map more than
+// 64 times the grid is read every stride-th texel, each read standing for its stride x stride block.
+const MAX_TEXELS_PER_SIDE : u32 = ${SH_EXP_MAX_TEXELS_PER_CELL_SIDE}u;
+
+// The first texel whose centre is at or past the grid line edge / resolution:
+// (t + 0.5) / source >= edge / resolution, i.e. t >= (2 edge source - resolution) / (2 resolution).
+fn first_texel_from(edge: u32, source: u32, resolution: u32) -> u32 {
+    let twice = 2u * edge * source;
+
+    if (twice <= resolution) {
+        return 0u;
+    }
+
+    return (twice - resolution + 2u * resolution - 1u) / (2u * resolution);
+}
+
+// One workgroup per cell of the coarse octahedral grid.
+@compute @workgroup_size(${SH_EXP_WORKGROUP_SIZE})
+fn main(
+    @builtin(workgroup_id) workgroup_id: vec3<u32>,
+    @builtin(local_invocation_index) local_index: u32,
+) {
+    let resolution = parameters.cell_resolution;
+    let cell = workgroup_id.x;
+    let cell_x = cell % resolution;
+    let cell_y = cell / resolution;
+
+    let source_resolution = textureDimensions(tEnvironment, 0).x;
+    let inverse_source_resolution = 1.0 / f32(source_resolution);
+
+    // The source texels whose centres fall in this cell. A source coarser than the grid has none in
+    // some cells; those take the texel under their centre.
+    var lo = vec2<u32>(first_texel_from(cell_x, source_resolution, resolution), first_texel_from(cell_y, source_resolution, resolution));
+    var hi = vec2<u32>(first_texel_from(cell_x + 1u, source_resolution, resolution), first_texel_from(cell_y + 1u, source_resolution, resolution));
+
+    let under_centre = ((2u * vec2<u32>(cell_x, cell_y) + 1u) * source_resolution) / (2u * resolution);
+    let empty = hi <= lo;
+
+    lo = select(lo, under_centre, empty);
+    hi = select(hi, under_centre + 1u, empty);
+
+    let span = hi - lo;
+    let stride = (max(span.x, span.y) + MAX_TEXELS_PER_SIDE - 1u) / MAX_TEXELS_PER_SIDE;
+    let blocks = (span + stride - 1u) / stride;
+    let block_count = blocks.x * blocks.y;
+
+    // A cell's bounds come from the workgroup id, so this trip count is uniform; at most 16.
+    let iterations = (block_count + WORKGROUP_SIZE - 1u) / WORKGROUP_SIZE;
+
+    // radiance times solid angle, and solid angle
+    var accumulated = vec4<f32>(0.0);
+
+    for (var k = 0u; k < iterations; k++) {
+        let b = k * WORKGROUP_SIZE + local_index;
+
+        if (b < block_count) {
+            let block_lo = lo + vec2<u32>(b % blocks.x, b / blocks.x) * stride;
+            let block_hi = min(block_lo + stride, hi);
+            let block_size = block_hi - block_lo;
+
+            // the block's middle texel, weighted for the whole block; one texel when the stride is 1
+            let texel = block_lo + (block_size - 1u) / 2u;
+            let uv = (vec2<f32>(texel) + 0.5) * inverse_source_resolution;
+
+            let solid_angle = octahedral_solid_angle(uv, inverse_source_resolution) * f32(block_size.x * block_size.y);
+            let radiance = textureLoad(tEnvironment, texel, 0).rgb;
+
+            accumulated += vec4<f32>(radiance * solid_angle, solid_angle);
+        }
+    }
+
+    let total = sh_exp_workgroup_sum(accumulated, local_index);
+
+    if (local_index != 0u) {
+        return;
+    }
+
+    let cell_uv = (vec2<f32>(f32(cell_x), f32(cell_y)) + 0.5) / f32(resolution);
+    let cell_solid_angle = octahedral_solid_angle(cell_uv, 1.0 / f32(resolution));
+
+    // the solid-angle-weighted mean radiance over the cell, standing for all of it
+    let radiance = total.rgb / total.a;
+
+    cells[2u * cell] = vec4<f32>(uv_octahedral_unit_decode(cell_uv), 0.0);
+    cells[2u * cell + 1u] = vec4<f32>(radiance * cell_solid_angle, cell_solid_angle);
+}
+`, [
+    chunk_octahedral_solid_angle,
+    chunk_uv_octahedral_unit_decode,
+    chunk_sh_exp_workgroup_sum,
+]);
+
+/**
+ * First pass of the SH-exponential encoder: integrates the octahedral environment's level 0 down to a
+ * coarse octahedral grid of `cell_resolution²` cells, each a direction and its radiance times solid
+ * angle — the quadrature the reference reflectance is integrated over.
+ *
+ * Writes two `vec4` per cell into `cells`: `(direction, 0)`, then `(radiance * solid_angle, solid_angle)`.
+ * Radiance is the solid-angle-weighted mean of the source texels whose centres fall in the cell
+ * (`octahedral_solid_angle` per texel, so the octahedral map's area distortion is accounted for), or
+ * of the texel under the cell's centre where a map coarser than the grid leaves none; past
+ * {@link SH_EXP_MAX_TEXELS_PER_CELL_SIDE} texels a side it is read with a stride. The cell's solid
+ * angle is its own, so the grid sums to 4π whatever the source resolution.
+ *
+ * Dispatch `cell_resolution²` workgroups.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_sh_exp_environment_cells = ComputeShader.from({
+    label: "SH exponential / environment cells",
+    resources,
+    body,
+});

package/src/shade/renderer/light/environment/sh_exponential/shader_sh_exp_log_floor.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The floor's own floor, for an environment that is black everywhere: `log` of it is about -69, so
+ * such a probe reconstructs to ~1e-30 rather than to `exp(-inf)` by way of a NaN.
+ *
+ * @type {number}
+ */
+export const SH_EXP_LOG_FLOOR_MINIMUM: number;
+/**
+ * Third pass of the SH-exponential encoder: the floor `log E0` is taken above, relative to the mean
+ * luminance of `E0` over the fit samples.
+ *
+ * The fit is least squares in log space, which weighs a ratio the same at any brightness. A region
+ * that reflects next to nothing — a black lower hemisphere — would otherwise pull the fit towards
+ * reproducing `log 0` there, at the expense of everything visible. A floor relative to the mean keeps
+ * the encoding scale-invariant: an environment `k` times brighter encodes to the same probe with
+ * `log k` added to the constant band, and nothing else changed.
+ *
+ * Writes `(floor, mean luminance, 0, 0)` into `statistics[0]`. Dispatch one workgroup.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_sh_exp_log_floor: ComputeShader;
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_sh_exp_log_floor.d.ts.map

package/src/shade/renderer/light/environment/sh_exponential/shader_sh_exp_log_floor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_sh_exp_log_floor.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/light/environment/sh_exponential/shader_sh_exp_log_floor.js"],"names":[],"mappings":"AAQA;;;;;GAKG;AACH,uCAFU,MAAM,CAE8B;AA8C9C;;;;;;;;;;;;;GAaG;AACH,sCAFU,aAAa,CAMpB;8BA7E2B,kCAAkC"}

package/src/shade/renderer/light/environment/sh_exponential/shader_sh_exp_log_floor.js

@@ -0,0 +1,79 @@
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../../shader/resource/ShaderResourceSetDescriptor.js";
+import { WebGPUArray } from "../../../shader/type/WebGPUArray.js";
+import { vec4f } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { chunk_sh_exp_workgroup_sum, SH_EXP_WORKGROUP_SIZE } from "./chunk_sh_exp_workgroup_sum.js";
+import { SH_EXP_ENCODE_PARAMETERS_STRUCT } from "./SH_EXP_ENCODE_PARAMETERS_STRUCT.js";
+
+/**
+ * The floor's own floor, for an environment that is black everywhere: `log` of it is about -69, so
+ * such a probe reconstructs to ~1e-30 rather than to `exp(-inf)` by way of a NaN.
+ *
+ * @type {number}
+ */
+export const SH_EXP_LOG_FLOOR_MINIMUM = 1e-30;
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.createGroup()
+    .addUniform("parameters", SH_EXP_ENCODE_PARAMETERS_STRUCT)
+    .addStorageBuffer("reflectance", WebGPUArray.from(vec4f), false)
+    .addStorageBuffer("statistics", WebGPUArray.from(vec4f), true);
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+const WORKGROUP_SIZE : u32 = ${SH_EXP_WORKGROUP_SIZE}u;
+
+// Rec. 709 luminance, the weighting the floor is relative to
+const LUMINANCE = vec3<f32>(0.2126, 0.7152, 0.0722);
+
+@compute @workgroup_size(${SH_EXP_WORKGROUP_SIZE})
+fn main(@builtin(local_invocation_index) local_index: u32) {
+    let sample_count = parameters.sample_count;
+
+    // sixteen steps at the default 4096 samples
+    let iterations = (sample_count + WORKGROUP_SIZE - 1u) / WORKGROUP_SIZE;
+
+    var luminance = 0.0;
+
+    for (var k = 0u; k < iterations; k++) {
+        let sample_index = k * WORKGROUP_SIZE + local_index;
+
+        if (sample_index < sample_count) {
+            luminance += dot(reflectance[sample_index].xyz, LUMINANCE);
+        }
+    }
+
+    let total = sh_exp_workgroup_sum(vec4<f32>(luminance, 0.0, 0.0, 0.0), local_index);
+
+    if (local_index == 0u) {
+        let mean = total.x / f32(sample_count);
+
+        statistics[0] = vec4<f32>(max(mean * parameters.log_floor_ratio, ${SH_EXP_LOG_FLOOR_MINIMUM}), mean, 0.0, 0.0);
+    }
+}
+`, [
+    chunk_sh_exp_workgroup_sum,
+]);
+
+/**
+ * Third pass of the SH-exponential encoder: the floor `log E0` is taken above, relative to the mean
+ * luminance of `E0` over the fit samples.
+ *
+ * The fit is least squares in log space, which weighs a ratio the same at any brightness. A region
+ * that reflects next to nothing — a black lower hemisphere — would otherwise pull the fit towards
+ * reproducing `log 0` there, at the expense of everything visible. A floor relative to the mean keeps
+ * the encoding scale-invariant: an environment `k` times brighter encodes to the same probe with
+ * `log k` added to the constant band, and nothing else changed.
+ *
+ * Writes `(floor, mean luminance, 0, 0)` into `statistics[0]`. Dispatch one workgroup.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_sh_exp_log_floor = ComputeShader.from({
+    label: "SH exponential / log floor",
+    resources,
+    body,
+});

package/src/shade/renderer/light/environment/sh_exponential/shader_sh_exp_project.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Fourth pass of the SH-exponential encoder: the right-hand side of the fit's normal equations,
+ * `Aᵀ log E0 / S` — for each unknown, the mean over the fit samples of its design-row entry times
+ * the floored log of the reference reflectance.
+ *
+ * The design row is Silvennoinen et al.'s row constraint (HPG 2025, https://doi.org/10.1111/cgf.70219):
+ * `vMF(1/alpha) ⊙ Y(r)` for P, `vMF(1/alpha) ⊙ Y(h_r)` for Q, built here one coefficient at a time by
+ * `sh_basis_function` so that one kernel serves every band count. Its CPU twin is
+ * `sh_exp_design_row`, which the solve matrix this is multiplied by was built from.
+ *
+ * Writes `(rgb, 0)` per unknown into `projection`. Dispatch `coefficient_count` workgroups.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_sh_exp_project: ComputeShader;
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_sh_exp_project.d.ts.map

package/src/shade/renderer/light/environment/sh_exponential/shader_sh_exp_project.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_sh_exp_project.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/light/environment/sh_exponential/shader_sh_exp_project.js"],"names":[],"mappings":"AAgFA;;;;;;;;;;;;;GAaG;AACH,oCAFU,aAAa,CAMpB;8BA9F2B,kCAAkC"}

package/src/shade/renderer/light/environment/sh_exponential/shader_sh_exp_project.js

@@ -0,0 +1,99 @@
+import { chunk_sh_band_of_index } from "../../../shader/chunk/spherical_harmonics/chunk_sh_band_of_index.js";
+import { chunk_sh_basis_function } from "../../../shader/chunk/spherical_harmonics/chunk_sh_basis_function.js";
+import { chunk_sh_vmf_window } from "../../../shader/chunk/spherical_harmonics/chunk_sh_vmf_window.js";
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../../shader/resource/ShaderResourceSetDescriptor.js";
+import { WebGPUArray } from "../../../shader/type/WebGPUArray.js";
+import { vec4f } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { chunk_sh_exp_workgroup_sum, SH_EXP_WORKGROUP_SIZE } from "./chunk_sh_exp_workgroup_sum.js";
+import { SH_EXP_ENCODE_PARAMETERS_STRUCT } from "./SH_EXP_ENCODE_PARAMETERS_STRUCT.js";
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.createGroup()
+    .addUniform("parameters", SH_EXP_ENCODE_PARAMETERS_STRUCT)
+    .addStorageBuffer("samples", WebGPUArray.from(vec4f), false)
+    .addStorageBuffer("reflectance", WebGPUArray.from(vec4f), false)
+    .addStorageBuffer("statistics", WebGPUArray.from(vec4f), false)
+    .addStorageBuffer("projection", WebGPUArray.from(vec4f), true);
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+const WORKGROUP_SIZE : u32 = ${SH_EXP_WORKGROUP_SIZE}u;
+
+// One workgroup per unknown of the fit.
+@compute @workgroup_size(${SH_EXP_WORKGROUP_SIZE})
+fn main(
+    @builtin(workgroup_id) workgroup_id: vec3<u32>,
+    @builtin(local_invocation_index) local_index: u32,
+) {
+    let coefficient = workgroup_id.x;
+
+    let p_count = parameters.p_band_count * parameters.p_band_count;
+    let in_p = coefficient < p_count;
+
+    // Q's band 0 is P's, so Q's unknowns start at its coefficient 1
+    let index = select(coefficient - p_count + 1u, coefficient, in_p);
+    let l = sh_band_of_index(index);
+    let m = i32(index) - i32(l * (l + 1u));
+
+    let log_floor = statistics[0].x;
+    let sample_count = parameters.sample_count;
+
+    // sixteen steps at the default 4096 samples
+    let iterations = (sample_count + WORKGROUP_SIZE - 1u) / WORKGROUP_SIZE;
+
+    var accumulated = vec3<f32>(0.0);
+
+    for (var k = 0u; k < iterations; k++) {
+        let sample_index = k * WORKGROUP_SIZE + local_index;
+
+        if (sample_index < sample_count) {
+            let normal_alpha = samples[2u * sample_index];
+            let normal = normal_alpha.xyz;
+            let view = samples[2u * sample_index + 1u].xyz;
+
+            // the reflection-half-reflection parametrization: P sees r, Q sees h_r
+            let r = reflect(-view, normal);
+            let h_r = normalize(normal + r);
+
+            let design = sh_vmf_window(f32(l), 1.0 / normal_alpha.w) * sh_basis_function(m, i32(l), select(h_r, r, in_p));
+
+            accumulated += design * log(max(reflectance[sample_index].xyz, vec3<f32>(log_floor)));
+        }
+    }
+
+    let total = sh_exp_workgroup_sum(vec4<f32>(accumulated, 0.0), local_index);
+
+    if (local_index == 0u) {
+        projection[coefficient] = vec4<f32>(total.xyz / f32(sample_count), 0.0);
+    }
+}
+`, [
+    chunk_sh_band_of_index,
+    chunk_sh_basis_function,
+    chunk_sh_vmf_window,
+    chunk_sh_exp_workgroup_sum,
+]);
+
+/**
+ * Fourth pass of the SH-exponential encoder: the right-hand side of the fit's normal equations,
+ * `Aᵀ log E0 / S` — for each unknown, the mean over the fit samples of its design-row entry times
+ * the floored log of the reference reflectance.
+ *
+ * The design row is Silvennoinen et al.'s row constraint (HPG 2025, https://doi.org/10.1111/cgf.70219):
+ * `vMF(1/alpha) ⊙ Y(r)` for P, `vMF(1/alpha) ⊙ Y(h_r)` for Q, built here one coefficient at a time by
+ * `sh_basis_function` so that one kernel serves every band count. Its CPU twin is
+ * `sh_exp_design_row`, which the solve matrix this is multiplied by was built from.
+ *
+ * Writes `(rgb, 0)` per unknown into `projection`. Dispatch `coefficient_count` workgroups.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_sh_exp_project = ComputeShader.from({
+    label: "SH exponential / project",
+    resources,
+    body,
+});

package/src/shade/renderer/light/environment/sh_exponential/shader_sh_exp_reference_reflectance.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Second pass of the SH-exponential encoder: the reference the fit is solved against, Silvennoinen et
+ * al.'s base reflectance
+ *
+ *     E0(v, n, alpha) = ∫ L(l) f_DV(v, n, l, alpha) <l, n> dl
+ *
+ * (HPG 2025, https://doi.org/10.1111/cgf.70219, "Our Factorization"), at every fit sample, by
+ * quadrature over the cells of `shader_sh_exp_environment_cells`. `f_DV` is the engine's GGX
+ * distribution times its height-correlated Smith visibility — the BRDF the split-sum LUT integrates —
+ * without Fresnel, which the reconstruction applies (`sh_exp_specular`).
+ *
+ * A deterministic quadrature rather than importance sampling: no noise in the fit's right-hand side,
+ * and the spec can hold it to a closed form (at `alpha = 1`, `E0` of a white environment is
+ * `1 - NoV * ln(1 + 1 / NoV)`). Cells of a 64 grid are ~3° across; fitting over it or over a 128 grid
+ * gave the same reconstruction error to the third decimal even at alpha 0.1, below the default range
+ * (f64 prototype, Venice-sunset map, 2026-10-03).
+ *
+ * Writes `(E0.rgb, 0)` per sample into `reflectance`. Dispatch `sample_count` workgroups.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_sh_exp_reference_reflectance: ComputeShader;
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_sh_exp_reference_reflectance.d.ts.map

package/src/shade/renderer/light/environment/sh_exponential/shader_sh_exp_reference_reflectance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_sh_exp_reference_reflectance.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/light/environment/sh_exponential/shader_sh_exp_reference_reflectance.js"],"names":[],"mappings":"AA8EA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,kDAFU,aAAa,CAMpB;8BApG2B,kCAAkC"}

package/src/shade/renderer/light/environment/sh_exponential/shader_sh_exp_reference_reflectance.js

@@ -0,0 +1,104 @@
+import { chunk_D_GGX } from "../../../shader/chunk/brdf/chunk_D_GGX.js";
+import { chunk_V_GGX_SmithCorrelated } from "../../../shader/chunk/brdf/chunk_V_GGX_SmithCorrelated.js";
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../../shader/resource/ShaderResourceSetDescriptor.js";
+import { WebGPUArray } from "../../../shader/type/WebGPUArray.js";
+import { vec4f } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { chunk_sh_exp_workgroup_sum, SH_EXP_WORKGROUP_SIZE } from "./chunk_sh_exp_workgroup_sum.js";
+import { SH_EXP_ENCODE_PARAMETERS_STRUCT } from "./SH_EXP_ENCODE_PARAMETERS_STRUCT.js";
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.createGroup()
+    .addUniform("parameters", SH_EXP_ENCODE_PARAMETERS_STRUCT)
+    .addStorageBuffer("samples", WebGPUArray.from(vec4f), false)
+    .addStorageBuffer("cells", WebGPUArray.from(vec4f), false)
+    .addStorageBuffer("reflectance", WebGPUArray.from(vec4f), true);
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+const WORKGROUP_SIZE : u32 = ${SH_EXP_WORKGROUP_SIZE}u;
+
+// One workgroup per fit sample.
+@compute @workgroup_size(${SH_EXP_WORKGROUP_SIZE})
+fn main(
+    @builtin(workgroup_id) workgroup_id: vec3<u32>,
+    @builtin(local_invocation_index) local_index: u32,
+) {
+    let sample_index = workgroup_id.x;
+
+    let normal_alpha = samples[2u * sample_index];
+    let normal = normal_alpha.xyz;
+    let alpha = normal_alpha.w;
+    let view = samples[2u * sample_index + 1u].xyz;
+
+    // the fit samples keep dot(normal, view) at 0.01 or above
+    let NoV = dot(normal, view);
+    let alpha2 = alpha * alpha;
+
+    let cell_count = parameters.cell_resolution * parameters.cell_resolution;
+
+    // sixteen steps at the 64-cell grid
+    let iterations = (cell_count + WORKGROUP_SIZE - 1u) / WORKGROUP_SIZE;
+
+    var reflected = vec3<f32>(0.0);
+
+    for (var k = 0u; k < iterations; k++) {
+        let cell = k * WORKGROUP_SIZE + local_index;
+
+        if (cell < cell_count) {
+            let light = cells[2u * cell].xyz;
+            let NoL = dot(normal, light);
+
+            if (NoL > 0.0) {
+                let half_vector = normalize(light + view);
+                let NoH = saturate(dot(normal, half_vector));
+
+                // f_DV: the GGX microfacet BRDF with the Fresnel term left out
+                let brdf = D_GGX(alpha2, NoH * NoH) * V_GGX_SmithCorrelated(alpha, NoL, NoV);
+
+                reflected += cells[2u * cell + 1u].xyz * (brdf * NoL);
+            }
+        }
+    }
+
+    let total = sh_exp_workgroup_sum(vec4<f32>(reflected, 0.0), local_index);
+
+    if (local_index == 0u) {
+        reflectance[sample_index] = vec4<f32>(total.xyz, 0.0);
+    }
+}
+`, [
+    chunk_D_GGX,
+    chunk_V_GGX_SmithCorrelated,
+    chunk_sh_exp_workgroup_sum,
+]);
+
+/**
+ * Second pass of the SH-exponential encoder: the reference the fit is solved against, Silvennoinen et
+ * al.'s base reflectance
+ *
+ *     E0(v, n, alpha) = ∫ L(l) f_DV(v, n, l, alpha) <l, n> dl
+ *
+ * (HPG 2025, https://doi.org/10.1111/cgf.70219, "Our Factorization"), at every fit sample, by
+ * quadrature over the cells of `shader_sh_exp_environment_cells`. `f_DV` is the engine's GGX
+ * distribution times its height-correlated Smith visibility — the BRDF the split-sum LUT integrates —
+ * without Fresnel, which the reconstruction applies (`sh_exp_specular`).
+ *
+ * A deterministic quadrature rather than importance sampling: no noise in the fit's right-hand side,
+ * and the spec can hold it to a closed form (at `alpha = 1`, `E0` of a white environment is
+ * `1 - NoV * ln(1 + 1 / NoV)`). Cells of a 64 grid are ~3° across; fitting over it or over a 128 grid
+ * gave the same reconstruction error to the third decimal even at alpha 0.1, below the default range
+ * (f64 prototype, Venice-sunset map, 2026-10-03).
+ *
+ * Writes `(E0.rgb, 0)` per sample into `reflectance`. Dispatch `sample_count` workgroups.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_sh_exp_reference_reflectance = ComputeShader.from({
+    label: "SH exponential / reference reflectance",
+    resources,
+    body,
+});

package/src/shade/renderer/light/environment/sh_exponential/shader_sh_exp_solve.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Last pass of the SH-exponential encoder: the coefficients, `x = M⁻¹ · projection` with the solve
+ * matrix built on the CPU (`sh_exp_solve_matrix`), written as a probe in the layout
+ * `sh_exp_probe_vec4_count` describes — header, P, Q — at `output_offset`.
+ *
+ * Dispatch `coefficient_count` workgroups.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_sh_exp_solve: ComputeShader;
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_sh_exp_solve.d.ts.map

package/src/shade/renderer/light/environment/sh_exponential/shader_sh_exp_solve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_sh_exp_solve.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/light/environment/sh_exponential/shader_sh_exp_solve.js"],"names":[],"mappings":"AA+EA;;;;;;;;GAQG;AACH,kCAFU,aAAa,CAMpB;8BA3F2B,kCAAkC"}

package/src/shade/renderer/light/environment/sh_exponential/shader_sh_exp_solve.js

@@ -0,0 +1,93 @@
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../../shader/resource/ShaderResourceSetDescriptor.js";
+import { WebGPUArray } from "../../../shader/type/WebGPUArray.js";
+import { f32, vec4f } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { chunk_sh_exp_workgroup_sum } from "./chunk_sh_exp_workgroup_sum.js";
+import { SH_EXP_ENCODE_PARAMETERS_STRUCT } from "./SH_EXP_ENCODE_PARAMETERS_STRUCT.js";
+
+/**
+ * Invocations per unknown. Ten-and-ten bands is 199 unknowns, four steps each.
+ *
+ * @type {number}
+ */
+const SOLVE_WORKGROUP_SIZE = 64;
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.createGroup()
+    .addUniform("parameters", SH_EXP_ENCODE_PARAMETERS_STRUCT)
+    .addStorageBuffer("solve_matrix", WebGPUArray.from(f32), false)
+    .addStorageBuffer("projection", WebGPUArray.from(vec4f), false)
+    .addStorageBuffer("probe", WebGPUArray.from(vec4f), true);
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+const WORKGROUP_SIZE : u32 = ${SOLVE_WORKGROUP_SIZE}u;
+
+// One workgroup per unknown of the fit.
+@compute @workgroup_size(${SOLVE_WORKGROUP_SIZE})
+fn main(
+    @builtin(workgroup_id) workgroup_id: vec3<u32>,
+    @builtin(local_invocation_index) local_index: u32,
+) {
+    let coefficient = workgroup_id.x;
+    let coefficient_count = parameters.coefficient_count;
+
+    let iterations = (coefficient_count + WORKGROUP_SIZE - 1u) / WORKGROUP_SIZE;
+
+    var accumulated = vec3<f32>(0.0);
+
+    for (var k = 0u; k < iterations; k++) {
+        let j = k * WORKGROUP_SIZE + local_index;
+
+        if (j < coefficient_count) {
+            accumulated += solve_matrix[coefficient * coefficient_count + j] * projection[j].xyz;
+        }
+    }
+
+    let total = sh_exp_workgroup_sum(vec4<f32>(accumulated, 0.0), local_index);
+
+    if (local_index != 0u) {
+        return;
+    }
+
+    let p_count = parameters.p_band_count * parameters.p_band_count;
+    let base = parameters.output_offset;
+
+    // [header][P: p_count][Q: q_count, its band 0 kept at zero]; Q's unknowns start at its coefficient 1,
+    // so unknown j >= p_count lands at 1 + p_count + (j - p_count + 1)
+    let slot = select(2u + coefficient, 1u + coefficient, coefficient < p_count);
+
+    probe[base + slot] = vec4<f32>(total.xyz, 0.0);
+
+    if (coefficient == 0u) {
+        probe[base] = vec4<f32>(
+            parameters.alpha_min,
+            parameters.alpha_max,
+            f32(parameters.p_band_count),
+            f32(parameters.q_band_count)
+        );
+
+        probe[base + 1u + p_count] = vec4<f32>(0.0);
+    }
+}
+`, [
+    chunk_sh_exp_workgroup_sum,
+]);
+
+/**
+ * Last pass of the SH-exponential encoder: the coefficients, `x = M⁻¹ · projection` with the solve
+ * matrix built on the CPU (`sh_exp_solve_matrix`), written as a probe in the layout
+ * `sh_exp_probe_vec4_count` describes — header, P, Q — at `output_offset`.
+ *
+ * Dispatch `coefficient_count` workgroups.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_sh_exp_solve = ComputeShader.from({
+    label: "SH exponential / solve",
+    resources,
+    body,
+});

package/src/shade/renderer/lightmap/GPULightMap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPULightMap.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/lightmap/GPULightMap.js"],"names":[],"mappings":"AAmBA;IAgCI;;;OAGG;IACH,+BA6CC;IA/ED;;;OAGG;IACH,WAFU,iBAAiB,GAAC,IAAI,CAEf;IACjB;;;OAGG;IACH,cAFU,iBAAiB,GAAC,IAAI,CAEZ;IACpB;;;OAGG;IACH,cAFU,iBAAiB,GAAC,IAAI,CAEZ;IAEpB;;;OAGG;IACH,aAFU,iBAAiB,GAAC,IAAI,CAEb;IAEnB;;;OAGG;IACH,yBAEC;IA2ED;;;;OAIG;IACH,wEAmCC;IA6BD;;OAEG;IACH,oBA0DC;IAED,iBA4EC;IAED;;;;OAIG;IACH,kEAQC;;CAEJ;kCAxViC,iCAAiC"}
+{"version":3,"file":"GPULightMap.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/lightmap/GPULightMap.js"],"names":[],"mappings":"AAmBA;IAgCI;;;OAGG;IACH,+BA6CC;IA/ED;;;OAGG;IACH,WAFU,iBAAiB,GAAC,IAAI,CAEf;IACjB;;;OAGG;IACH,cAFU,iBAAiB,GAAC,IAAI,CAEZ;IACpB;;;OAGG;IACH,cAFU,iBAAiB,GAAC,IAAI,CAEZ;IAEpB;;;OAGG;IACH,aAFU,iBAAiB,GAAC,IAAI,CAEb;IAEnB;;;OAGG;IACH,yBAEC;IA2ED;;;;OAIG;IACH,wEAmCC;IA6BD;;OAEG;IACH,oBA2DC;IAED,iBA4EC;IAED;;;;OAIG;IACH,kEAQC;;CAEJ;kCAzViC,iCAAiC"}

package/src/shade/renderer/lightmap/GPULightMap.js

@@ -227,6 +227,7 @@ export class GPULightMap {
                 viz_buffer,
 
                 materials: r_materials.buffer_materials,
+                media: r_materials.buffer_media,
                 textures: r_materials.textureView,
                 tNoise: graphics.textures.obtain(HILBERT_R2_INDEX_TEXTURE).obtainView(),
 

package/src/shade/renderer/lightmap/bake/shader_lightmap_viz_to_irradiance_flat.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_lightmap_viz_to_irradiance_flat.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/lightmap/bake/shader_lightmap_viz_to_irradiance_flat.js"],"names":[],"mappings":"AAkOA,iEASE;4BAnM0B,6BAA6B"}
+{"version":3,"file":"shader_lightmap_viz_to_irradiance_flat.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/lightmap/bake/shader_lightmap_viz_to_irradiance_flat.js"],"names":[],"mappings":"AAsOA,iEASE;4BArM0B,6BAA6B"}