@woosh/meep-engine 3.38.0 → 3.40.0

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

@@ -0,0 +1,92 @@
+import { assert } from "../../../../../core/assert.js";
+import { halton_sequence } from "../../../../../core/math/statistics/halton_sequence.js";
+import { SH_EXP_FIT_SAMPLE_FLOATS } from "./sh_exp_layout.js";
+
+/**
+ * Smallest `dot(normal, view)` a sample is given. At exactly grazing the reflection lies in the
+ * tangent plane and the reference integral has nothing to say that a sample a hair above does not.
+ *
+ * @type {number}
+ */
+const MINIMUM_COS_VIEW = 0.01;
+
+/**
+ * The fixed set of shading configurations `(normal, view, alpha)` the SH-exponential fit is solved
+ * over. Silvennoinen et al. (HPG 2025, https://doi.org/10.1111/cgf.70219) sample view and normal
+ * directions uniformly and roughness uniformly over a range relaxed below the one used (Section 5.1:
+ * 64 x 64 directions, 4 roughness values in [0.20, 1.0]); this draws the same distribution from a
+ * five-dimensional Halton sequence, so that the system matrix is a constant of the configuration
+ * (see {@link sh_exp_solve_matrix}), built once rather than per environment.
+ *
+ * - `normal`: uniform over the sphere;
+ * - `view`: uniform over the hemisphere about the normal; floored at {@link MINIMUM_COS_VIEW};
+ * - `alpha`: GGX alpha (roughness squared), uniform over `[alpha_min, alpha_max]`.
+ *
+ * Until 2026-10-03 views were cosine-weighted about the normal (the screen footprint of a sphere) and
+ * alpha spanned [0.25, 1]. Measured with this module's fit on the Venice-sunset map (held-out views
+ * cosine-weighted, alpha in [0.25, 1], tonemapped error by roughness third), the paper's distribution
+ * is better at the low end, where reflections are sharpest, and worse at the rough end: 0.048 / 0.038 /
+ * 0.091 against 0.063 / 0.035 / 0.073; Rustig-Koppie the same way, smaller. Changed to the paper's on
+ * that trade.
+ *
+ * Written as `(normal.xyz, alpha, view.xyz, 0)` per sample ({@link SH_EXP_FIT_SAMPLE_FLOATS}).
+ *
+ * @param {Float32Array} output length at least `sample_count * SH_EXP_FIT_SAMPLE_FLOATS`
+ * @param {number} sample_count
+ * @param {number} alpha_min
+ * @param {number} alpha_max
+ */
+export function sh_exp_fit_samples(output, sample_count, alpha_min, alpha_max) {
+    assert.isNonNegativeInteger(sample_count, 'sample_count');
+    assert.greaterThanOrEqual(output.length, sample_count * SH_EXP_FIT_SAMPLE_FLOATS, 'output.length');
+    assert.greaterThan(alpha_min, 0, 'alpha_min');
+    assert.greaterThanOrEqual(alpha_max, alpha_min, 'alpha_max');
+
+    for (let i = 0; i < sample_count; i++) {
+        // index 0 is the origin in every base; start at 1
+        const u_normal_z = halton_sequence(2, i + 1);
+        const u_normal_phi = halton_sequence(3, i + 1);
+        const u_view_cos = halton_sequence(5, i + 1);
+        const u_view_phi = halton_sequence(7, i + 1);
+        const u_alpha = halton_sequence(11, i + 1);
+
+        const nz = 1 - 2 * u_normal_z;
+        const n_sin = Math.sqrt(Math.max(0, 1 - nz * nz));
+        const n_phi = 2 * Math.PI * u_normal_phi;
+
+        const nx = n_sin * Math.cos(n_phi);
+        const ny = n_sin * Math.sin(n_phi);
+
+        // Duff et al., "Building an Orthonormal Basis, Revisited", JCGT 6(1), 2017
+        const sign = nz >= 0 ? 1 : -1;
+        const a = -1 / (sign + nz);
+        const b = nx * ny * a;
+
+        const tx = 1 + sign * nx * nx * a;
+        const ty = sign * b;
+        const tz = -sign * nx;
+
+        const bx = b;
+        const by = sign + ny * ny * a;
+        const bz = -ny;
+
+        // uniform over the hemisphere: cos_theta is uniform
+        const v_cos = Math.max(MINIMUM_COS_VIEW, u_view_cos);
+        const v_sin = Math.sqrt(1 - v_cos * v_cos);
+        const v_phi = 2 * Math.PI * u_view_phi;
+
+        const vt = v_sin * Math.cos(v_phi);
+        const vb = v_sin * Math.sin(v_phi);
+
+        const o = i * SH_EXP_FIT_SAMPLE_FLOATS;
+
+        output[o] = nx;
+        output[o + 1] = ny;
+        output[o + 2] = nz;
+        output[o + 3] = alpha_min + (alpha_max - alpha_min) * u_alpha;
+        output[o + 4] = tx * vt + bx * vb + nx * v_cos;
+        output[o + 5] = ty * vt + by * vb + ny * v_cos;
+        output[o + 6] = tz * vt + bz * vb + nz * v_cos;
+        output[o + 7] = 0;
+    }
+}

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

@@ -0,0 +1,39 @@
+/**
+ * Unknowns of the fit, per colour channel: every P coefficient and every Q coefficient but Q's band
+ * 0. Band 0 of either term is the same constant function — `exp(a) * exp(b)` cannot tell `a` from `b`
+ * — so the least-squares system is singular unless one of them goes; P keeps it, as the paper does
+ * (Section 4.1.1 omits Q's DC term). Its five-and-three-band configuration (degrees 4 and 2) is
+ * 25 + 9 - 1 = 33, the "33 coefficients per color channel" of its Figure 1.
+ *
+ * Index `j < p_band_count²` is P's coefficient `j`; past that, `j - p_band_count² + 1` is Q's.
+ *
+ * @param {number} p_band_count
+ * @param {number} q_band_count
+ * @returns {number}
+ */
+export function sh_exp_coefficient_count(p_band_count: number, q_band_count: number): number;
+/**
+ * `vec4<f32>` elements of an encoded probe:
+ *
+ * - `[0]`: `(alpha_min, alpha_max, p_band_count, q_band_count)`, the roughness range the probe was
+ *   fitted over (reconstruction clamps to it) and its shape;
+ * - `[1, 1 + P)`: P's coefficients, RGB in `.xyz`, band-major (`sh_index`), `P = p_band_count²`;
+ * - `[1 + P, 1 + P + Q)`: Q's, the same way, `Q = q_band_count²`. Q's band 0 is stored, always zero,
+ *   so that both terms are a plain `array<vec3<f32>, N²>` for the generated `sh{N}_color_evaluate_vmf`.
+ *
+ * A `vec3` array in WGSL strides 16 bytes, so the layout is that of a struct of a `vec4` header and two
+ * `array<vec3<f32>, N²>` — what `SH_EXP_P4Q2_PROBE_STRUCT` declares for the default configuration.
+ *
+ * @param {number} p_band_count
+ * @param {number} q_band_count
+ * @returns {number}
+ */
+export function sh_exp_probe_vec4_count(p_band_count: number, q_band_count: number): number;
+/**
+ * Floats per fit sample in the buffer {@link sh_exp_fit_samples} fills and the encoder's kernels read
+ * as two `vec4<f32>`: `(normal.xyz, alpha)` then `(view.xyz, unused)`.
+ *
+ * @type {number}
+ */
+export const SH_EXP_FIT_SAMPLE_FLOATS: number;
+//# sourceMappingURL=sh_exp_layout.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sh_exp_layout.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/light/environment/sh_exponential/sh_exp_layout.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;GAYG;AACH,uDAJW,MAAM,gBACN,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;;;;;;;;;;GAeG;AACH,sDAJW,MAAM,gBACN,MAAM,GACJ,MAAM,CAIlB;AA3CD;;;;;GAKG;AACH,uCAFU,MAAM,CAE0B"}

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

@@ -0,0 +1,44 @@
+/**
+ * Floats per fit sample in the buffer {@link sh_exp_fit_samples} fills and the encoder's kernels read
+ * as two `vec4<f32>`: `(normal.xyz, alpha)` then `(view.xyz, unused)`.
+ *
+ * @type {number}
+ */
+export const SH_EXP_FIT_SAMPLE_FLOATS = 8;
+
+/**
+ * Unknowns of the fit, per colour channel: every P coefficient and every Q coefficient but Q's band
+ * 0. Band 0 of either term is the same constant function — `exp(a) * exp(b)` cannot tell `a` from `b`
+ * — so the least-squares system is singular unless one of them goes; P keeps it, as the paper does
+ * (Section 4.1.1 omits Q's DC term). Its five-and-three-band configuration (degrees 4 and 2) is
+ * 25 + 9 - 1 = 33, the "33 coefficients per color channel" of its Figure 1.
+ *
+ * Index `j < p_band_count²` is P's coefficient `j`; past that, `j - p_band_count² + 1` is Q's.
+ *
+ * @param {number} p_band_count
+ * @param {number} q_band_count
+ * @returns {number}
+ */
+export function sh_exp_coefficient_count(p_band_count, q_band_count) {
+    return p_band_count * p_band_count + q_band_count * q_band_count - 1;
+}
+
+/**
+ * `vec4<f32>` elements of an encoded probe:
+ *
+ * - `[0]`: `(alpha_min, alpha_max, p_band_count, q_band_count)`, the roughness range the probe was
+ *   fitted over (reconstruction clamps to it) and its shape;
+ * - `[1, 1 + P)`: P's coefficients, RGB in `.xyz`, band-major (`sh_index`), `P = p_band_count²`;
+ * - `[1 + P, 1 + P + Q)`: Q's, the same way, `Q = q_band_count²`. Q's band 0 is stored, always zero,
+ *   so that both terms are a plain `array<vec3<f32>, N²>` for the generated `sh{N}_color_evaluate_vmf`.
+ *
+ * A `vec3` array in WGSL strides 16 bytes, so the layout is that of a struct of a `vec4` header and two
+ * `array<vec3<f32>, N²>` — what `SH_EXP_P4Q2_PROBE_STRUCT` declares for the default configuration.
+ *
+ * @param {number} p_band_count
+ * @param {number} q_band_count
+ * @returns {number}
+ */
+export function sh_exp_probe_vec4_count(p_band_count, q_band_count) {
+    return 1 + p_band_count * p_band_count + q_band_count * q_band_count;
+}

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

@@ -0,0 +1,42 @@
+/**
+ * The matrix that takes the fit's right-hand side to its coefficients: `(AᵀA / S + λD)⁻¹`, where row
+ * `i` of `A` is {@link sh_exp_design_row} at fit sample `i`, `S` is the sample count, and `D` is the
+ * identity but for a zero at the constant band.
+ *
+ * The least-squares system of Silvennoinen et al. (HPG 2025, https://doi.org/10.1111/cgf.70219) is
+ * linear in log space, and its matrix depends on the samples alone — never on the environment. With
+ * the samples fixed ({@link sh_exp_fit_samples}), this is a constant of the configuration: built once,
+ * in f64, and handed to the GPU, so that encoding an environment is a reduction and a matrix-vector
+ * product there rather than a factorization in f32. The encoder's right-hand side is
+ * `Aᵀ log E0 / S` to match.
+ *
+ * Inverted rather than factored: the GPU applies it with one dot product per coefficient. At the
+ * condition numbers {@link SH_EXP_RIDGE} leaves, applying it in f32 moves coefficients by ~5e-5
+ * (measured, five-and-three bands, coefficients up to 9).
+ *
+ * @param {Float32Array} output `coefficient_count²`, row-major (it is symmetric)
+ * @param {Float32Array} samples as written by {@link sh_exp_fit_samples} — the same values the GPU reads
+ * @param {number} sample_count
+ * @param {number} p_band_count
+ * @param {number} q_band_count
+ */
+export function sh_exp_solve_matrix(output: Float32Array, samples: Float32Array, sample_count: number, p_band_count: number, q_band_count: number): void;
+/**
+ * Ridge term, as a fraction of the normal matrix' mean diagonal.
+ *
+ * Wherever the view is near the normal, `h_r` is near `r`, so the P and Q columns of one `(l, m)` are
+ * nearly collinear. Over {@link sh_exp_fit_samples}' set the normal matrix' condition number is 1.1e3
+ * at the paper's five-and-three bands and 1.8e10 at ten-and-ten (2026-10-03; the matrix does not
+ * depend on the environment). Under the cosine-weighted views the set used before, an unregularized
+ * ten-and-ten fit of the Venice-sunset map ran coefficients to 2.4e4 (f64 prototype). With this ridge,
+ * this module's own fit of that map (quadrature `E0` over a 64 grid, 4096 and 8192 samples) keeps the
+ * largest coefficient at 4.7 for five-and-three and 13.7 for ten-and-ten, at a tonemapped
+ * reconstruction error by roughness third of 0.048 / 0.038 / 0.091 for both. On a target the model
+ * represents exactly, the ridge moves coefficients by up to 2.3e-3 (five-and-three) and 0.11
+ * (ten-and-ten) along those near-collinear directions, and the reconstruction at the fit samples by at
+ * most 4e-4 and 1.6e-3 in log space.
+ *
+ * @type {number}
+ */
+export const SH_EXP_RIDGE: number;
+//# sourceMappingURL=sh_exp_solve_matrix.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sh_exp_solve_matrix.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/light/environment/sh_exponential/sh_exp_solve_matrix.js"],"names":[],"mappings":"AAyBA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,4CANW,YAAY,WACZ,YAAY,gBACZ,MAAM,gBACN,MAAM,gBACN,MAAM,QA6EhB;AApHD;;;;;;;;;;;;;;;;GAgBG;AACH,2BAFU,MAAM,CAEiB"}

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

@@ -0,0 +1,123 @@
+import { assert } from "../../../../../core/assert.js";
+import { lu_factor_linear_system } from "../../../../../core/math/linalg/lu_factor_linear_system.js";
+import { lu_solve_linear_system } from "../../../../../core/math/linalg/lu_solve_linear_system.js";
+import { sh_exp_design_row, sh_exp_reflection_frame } from "./sh_exp_design_row.js";
+import { SH_EXP_FIT_SAMPLE_FLOATS, sh_exp_coefficient_count } from "./sh_exp_layout.js";
+
+/**
+ * Ridge term, as a fraction of the normal matrix' mean diagonal.
+ *
+ * Wherever the view is near the normal, `h_r` is near `r`, so the P and Q columns of one `(l, m)` are
+ * nearly collinear. Over {@link sh_exp_fit_samples}' set the normal matrix' condition number is 1.1e3
+ * at the paper's five-and-three bands and 1.8e10 at ten-and-ten (2026-10-03; the matrix does not
+ * depend on the environment). Under the cosine-weighted views the set used before, an unregularized
+ * ten-and-ten fit of the Venice-sunset map ran coefficients to 2.4e4 (f64 prototype). With this ridge,
+ * this module's own fit of that map (quadrature `E0` over a 64 grid, 4096 and 8192 samples) keeps the
+ * largest coefficient at 4.7 for five-and-three and 13.7 for ten-and-ten, at a tonemapped
+ * reconstruction error by roughness third of 0.048 / 0.038 / 0.091 for both. On a target the model
+ * represents exactly, the ridge moves coefficients by up to 2.3e-3 (five-and-three) and 0.11
+ * (ten-and-ten) along those near-collinear directions, and the reconstruction at the fit samples by at
+ * most 4e-4 and 1.6e-3 in log space.
+ *
+ * @type {number}
+ */
+export const SH_EXP_RIDGE = 1e-4;
+
+/**
+ * The matrix that takes the fit's right-hand side to its coefficients: `(AᵀA / S + λD)⁻¹`, where row
+ * `i` of `A` is {@link sh_exp_design_row} at fit sample `i`, `S` is the sample count, and `D` is the
+ * identity but for a zero at the constant band.
+ *
+ * The least-squares system of Silvennoinen et al. (HPG 2025, https://doi.org/10.1111/cgf.70219) is
+ * linear in log space, and its matrix depends on the samples alone — never on the environment. With
+ * the samples fixed ({@link sh_exp_fit_samples}), this is a constant of the configuration: built once,
+ * in f64, and handed to the GPU, so that encoding an environment is a reduction and a matrix-vector
+ * product there rather than a factorization in f32. The encoder's right-hand side is
+ * `Aᵀ log E0 / S` to match.
+ *
+ * Inverted rather than factored: the GPU applies it with one dot product per coefficient. At the
+ * condition numbers {@link SH_EXP_RIDGE} leaves, applying it in f32 moves coefficients by ~5e-5
+ * (measured, five-and-three bands, coefficients up to 9).
+ *
+ * @param {Float32Array} output `coefficient_count²`, row-major (it is symmetric)
+ * @param {Float32Array} samples as written by {@link sh_exp_fit_samples} — the same values the GPU reads
+ * @param {number} sample_count
+ * @param {number} p_band_count
+ * @param {number} q_band_count
+ */
+export function sh_exp_solve_matrix(output, samples, sample_count, p_band_count, q_band_count) {
+    assert.isPositiveInteger(sample_count, 'sample_count');
+    assert.isPositiveInteger(p_band_count, 'p_band_count');
+    assert.isPositiveInteger(q_band_count, 'q_band_count');
+
+    const N = sh_exp_coefficient_count(p_band_count, q_band_count);
+
+    assert.greaterThanOrEqual(output.length, N * N, 'output.length');
+
+    const M = new Float64Array(N * N);
+    const row = new Float64Array(N);
+    const frame = new Float64Array(6);
+
+    for (let s = 0; s < sample_count; s++) {
+        const o = s * SH_EXP_FIT_SAMPLE_FLOATS;
+
+        sh_exp_reflection_frame(
+            frame,
+            samples[o], samples[o + 1], samples[o + 2],
+            samples[o + 4], samples[o + 5], samples[o + 6]
+        );
+
+        sh_exp_design_row(row, 0, p_band_count, q_band_count, frame, samples[o + 3]);
+
+        for (let i = 0; i < N; i++) {
+            const ri = row[i];
+
+            for (let j = i; j < N; j++) {
+                M[i * N + j] += ri * row[j];
+            }
+        }
+    }
+
+    let trace = 0;
+
+    for (let i = 0; i < N; i++) {
+        for (let j = i; j < N; j++) {
+            const value = M[i * N + j] / sample_count;
+
+            M[i * N + j] = value;
+            M[j * N + i] = value;
+        }
+
+        trace += M[i * N + i];
+    }
+
+    const ridge = SH_EXP_RIDGE * trace / N;
+
+    // Not on coefficient 0, P's constant band — ridge regression leaves the intercept alone. Then the
+    // inverse maps the constant column of the design straight back to itself, so an environment k
+    // times brighter (log E0 + log k everywhere) moves that one coefficient by log k / Y(0, 0) and no
+    // other.
+    for (let i = 1; i < N; i++) {
+        M[i * N + i] += ridge;
+    }
+
+    const pivots = new Uint32Array(N);
+
+    if (!lu_factor_linear_system(M, pivots, N)) {
+        throw new Error(`SH-exponential system matrix (${N}x${N}) did not factor`);
+    }
+
+    const column = new Float64Array(N);
+
+    for (let j = 0; j < N; j++) {
+        column.fill(0);
+        column[j] = 1;
+
+        lu_solve_linear_system(M, pivots, column, N);
+
+        // column j of the inverse; the inverse of a symmetric matrix is symmetric, so this is row j too
+        for (let i = 0; i < N; i++) {
+            output[j * N + i] = column[i];
+        }
+    }
+}

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

@@ -0,0 +1,30 @@
+/**
+ * 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: number;
+/**
+ * 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;
+import { ComputeShader } from "../../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_sh_exp_environment_cells.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shader_sh_exp_environment_cells.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/light/environment/sh_exponential/shader_sh_exp_environment_cells.js"],"names":[],"mappings":"AAUA;;;;;;;;;GASG;AACH,8CAFU,MAAM,CAEkC;AA0GlD;;;;;;;;;;;;;;;GAeG;AACH,8CAFU,aAAa,CAMpB;8BA/I2B,kCAAkC"}

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