@woosh/meep-engine 3.38.0 → 3.39.0

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

@@ -0,0 +1,170 @@
+/**
+ * @typedef {import("../../../../device/ShadeGPUCommandContext.js").ShadeGPUCommandContext} ShadeGPUCommandContext
+ */
+/**
+ * The shape of an SH-exponential encoding. Every field is required.
+ *
+ * @typedef {Object} SHExpEncoderSettings
+ * @property {number} p_band_count bands of the P (reflection) term, [1, 10]
+ * @property {number} q_band_count bands of the Q (half-reflection) term, [1, 10]
+ * @property {number} alpha_min smallest GGX alpha (roughness²) the probe is fitted for, > 0
+ * @property {number} alpha_max largest
+ * @property {number} sample_count fit samples, at least the unknown count, at most {@link SH_EXP_MAX_SAMPLE_COUNT}
+ * @property {number} cell_resolution side of the octahedral grid the reference is integrated over,
+ *  [{@link SH_EXP_MIN_CELL_RESOLUTION}, {@link SH_EXP_MAX_CELL_RESOLUTION}]
+ */
+/**
+ * The configuration of Silvennoinen et al.'s results: P to degree 4 and Q to degree 2 — five and three
+ * bands, 33 unknowns per channel. They evaluate it over alpha in [0.25, 1] (below that it blurs what
+ * should be sharp, Section 5.4) and fit it over a range relaxed to [0.20, 1] (Section 5.1), which is
+ * the range here: the probe's header carries it, so reconstruction clamps to 0.20, not 0.25.
+ *
+ * 4096 samples, where the paper takes 64 x 64 x 4 = 16384: the f64 prototype fitted 1024, 4096 and
+ * 16384 to the same reconstruction error within 0.02 in log space, by roughness quarter (a synthetic
+ * sun-and-sky map, 2026-10-03), and 4096 leaves the system 124 rows per unknown. A 64 grid has cells ~3°
+ * across; see `shader_sh_exp_reference_reflectance`.
+ *
+ * @type {Readonly<SHExpEncoderSettings>}
+ */
+export const SH_EXP_P4Q2_SETTINGS: Readonly<SHExpEncoderSettings>;
+/**
+ * Floor under `log E0`, as a fraction of the mean luminance of `E0`; see `shader_sh_exp_log_floor`.
+ * A thousandth keeps ~7 natural-log units of range below the mean, which is darker than anything a
+ * glossy reflection of the rest shows next to it.
+ *
+ * @type {number}
+ */
+export const SH_EXP_LOG_FLOOR_RATIO: number;
+/**
+ * Most bands either term may have: what `sh_exp_design_row` and the generated reconstruction chunks
+ * (`sh{N}_color_evaluate_vmf`, N <= 10) cover. The paper's largest configuration is degree 9.
+ *
+ * @type {number}
+ */
+export const SH_EXP_MAX_BAND_COUNT: number;
+/**
+ * Most fit samples: the single-workgroup log-floor pass and each unknown's projection walk them 256
+ * lanes at a time, so 8192 is 32 steps a lane — the projection's steps each evaluating one SH
+ * coefficient, at most 19 recurrence steps. Twice the default; 41 rows per unknown at ten-and-ten bands.
+ *
+ * @type {number}
+ */
+export const SH_EXP_MAX_SAMPLE_COUNT: number;
+/**
+ * Finest reference grid: the reference pass walks its cells 256 lanes at a time, 16 steps at 64.
+ *
+ * @type {number}
+ */
+export const SH_EXP_MAX_CELL_RESOLUTION: number;
+/**
+ * Coarsest reference grid: an 8 grid's cells are 22° across, already coarse next to the narrowest lobe
+ * the default range fits (alpha 0.20). Below it a cell stops being a fair stand-in for its patch.
+ *
+ * @type {number}
+ */
+export const SH_EXP_MIN_CELL_RESOLUTION: number;
+/**
+ * Encodes an octahedral environment map into a spherical-harmonic-exponential reflection probe, on
+ * the GPU.
+ *
+ * The representation is Silvennoinen, Sloan, Iwanicki and Nowrouzezahrai, "Spherical Harmonic
+ * Exponentials for Efficient Glossy Reflections", HPG 2025 / Computer Graphics Forum 44(8)
+ * (https://doi.org/10.1111/cgf.70219; slides:
+ * https://highperformancegraphics.org/untracked/2025/presentations/Pa5_1_hpg_2025_slides.pdf; talk:
+ * https://www.youtube.com/watch?v=THVMMNZ68iA). The GGX base reflectance of a probe's environment,
+ *
+ *     E0(v, n, alpha) ≈ P(r, alpha) · Q(h_r, alpha)
+ *     P(r, alpha)     = exp(<vMF(1/alpha) ⊙ Y(r),   p>)
+ *     Q(h_r, alpha)   = exp(<vMF(1/alpha) ⊙ Y(h_r), q>)
+ *
+ * with `r` the reflection of the view about the normal and `h_r = normalize(n + r)`, is fitted by
+ * linear least squares in log space over a fixed set of `(n, v, alpha)` samples. A probe is a few
+ * hundred bytes for every roughness in its range, view-dependent, and reconstructs without the
+ * aliasing of a prefiltered map; `chunk_sh_exp_p4q2_base_reflectance` reads it back.
+ *
+ * Construction does the configuration's fixed work on the CPU — the samples, and the inverse of the
+ * least-squares system's matrix, which depends on the samples alone ({@link sh_exp_solve_matrix}) —
+ * and uploads it. {@link encode} then records five dispatches per environment:
+ *
+ * 1. `shader_sh_exp_environment_cells` — the map, integrated down to a `cell_resolution²` octahedral grid;
+ * 2. `shader_sh_exp_reference_reflectance` — `E0` at every sample, by quadrature over that grid;
+ * 3. `shader_sh_exp_log_floor` — the floor `log E0` is taken above;
+ * 4. `shader_sh_exp_project` — the right-hand side `Aᵀ log E0 / S`;
+ * 5. `shader_sh_exp_solve` — the coefficients, written as a probe.
+ *
+ * Needs a device with the `subgroups` feature, as the engine always requests.
+ */
+export class SHExpEncoder {
+    /**
+     * @param {GPUDevice} device
+     * @param {SHExpEncoderSettings} settings
+     */
+    constructor(device: GPUDevice, settings: SHExpEncoderSettings);
+    /**
+     * @returns {Readonly<SHExpEncoderSettings>}
+     */
+    get settings(): Readonly<SHExpEncoderSettings>;
+    /**
+     * Unknowns per colour channel.
+     * @returns {number}
+     */
+    get coefficient_count(): number;
+    /**
+     * Size of one encoded probe, in `vec4<f32>` (16 bytes each); see `sh_exp_probe_vec4_count`.
+     * @returns {number}
+     */
+    get probe_vec4_count(): number;
+    /**
+     * Records the encoding of `environment` into `output`, starting at `vec4` index `output_offset`.
+     *
+     * @param {Object} options
+     * @param {ShadeGPUCommandContext} options.encoder
+     * @param {GPUTextureView|GPUTexture} options.environment octahedral radiance map whose level 0 is
+     *  unfiltered radiance, as `GPULightCollection.environment` holds it; read texel by texel
+     * @param {GPUBuffer} options.output STORAGE; at least `(output_offset + probe_vec4_count) * 16` bytes
+     * @param {number} options.output_offset in `vec4`
+     */
+    encode({ encoder, environment, output, output_offset }: {
+        encoder: ShadeGPUCommandContext;
+        environment: GPUTextureView | GPUTexture;
+        output: GPUBuffer;
+        output_offset: number;
+    }): void;
+    /**
+     * Releases the GPU buffers. The encoder cannot be used afterwards.
+     */
+    destroy(): void;
+    #private;
+}
+export type ShadeGPUCommandContext = import("../../../../device/ShadeGPUCommandContext.js").ShadeGPUCommandContext;
+/**
+ * The shape of an SH-exponential encoding. Every field is required.
+ */
+export type SHExpEncoderSettings = {
+    /**
+     * bands of the P (reflection) term, [1, 10]
+     */
+    p_band_count: number;
+    /**
+     * bands of the Q (half-reflection) term, [1, 10]
+     */
+    q_band_count: number;
+    /**
+     * smallest GGX alpha (roughness²) the probe is fitted for, > 0
+     */
+    alpha_min: number;
+    /**
+     * largest
+     */
+    alpha_max: number;
+    /**
+     * fit samples, at least the unknown count, at most {@link SH_EXP_MAX_SAMPLE_COUNT }
+     */
+    sample_count: number;
+    /**
+     * side of the octahedral grid the reference is integrated over,
+     * [{@link SH_EXP_MIN_CELL_RESOLUTION }, {@link SH_EXP_MAX_CELL_RESOLUTION }]
+     */
+    cell_resolution: number;
+};
+//# sourceMappingURL=SHExpEncoder.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SHExpEncoder.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/light/environment/sh_exponential/SHExpEncoder.js"],"names":[],"mappings":"AAWA;;GAEG;AAEH;;;;;;;;;;;GAWG;AAEH;;;;;;;;;;;;GAYG;AACH,mCAFU,SAAS,oBAAoB,CAAC,CASrC;AAEH;;;;;;GAMG;AACH,qCAFU,MAAM,CAE2B;AAE3C;;;;;GAKG;AACH,oCAFU,MAAM,CAEwB;AAExC;;;;;;GAMG;AACH,sCAFU,MAAM,CAE4B;AAE5C;;;;GAIG;AACH,yCAFU,MAAM,CAE6B;AAE7C;;;;;GAKG;AACH,yCAFU,MAAM,CAE4B;AAE5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH;IAoCI;;;OAGG;IACH,yCAFW,oBAAoB,EA6F9B;IAED;;OAEG;IACH,+CAEC;IAED;;;OAGG;IACH,gCAEC;IAED;;;OAGG;IACH,+BAEC;IAED;;;;;;;;;OASG;IACH;QAN2C,OAAO,EAAvC,sBAAsB;QACa,WAAW,EAA9C,2BAAyB;QAEN,MAAM;QACT,aAAa,EAA7B,MAAM;aA6EhB;IAED;;OAEG;IACH,gBAOC;;CACJ;qCA5WY,OAAO,8CAA8C,EAAE,sBAAsB;;;;;;;;kBAO5E,MAAM;;;;kBACN,MAAM;;;;eACN,MAAM;;;;eACN,MAAM;;;;kBACN,MAAM;;;;;qBACN,MAAM"}

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

@@ -0,0 +1,377 @@
+import { assert } from "../../../../../core/assert.js";
+import { SH_EXP_FIT_SAMPLE_FLOATS, sh_exp_coefficient_count, sh_exp_probe_vec4_count } from "./sh_exp_layout.js";
+import { sh_exp_fit_samples } from "./sh_exp_fit_samples.js";
+import { sh_exp_solve_matrix } from "./sh_exp_solve_matrix.js";
+import { SH_EXP_ENCODE_PARAMETERS_STRUCT } from "./SH_EXP_ENCODE_PARAMETERS_STRUCT.js";
+import { shader_sh_exp_environment_cells } from "./shader_sh_exp_environment_cells.js";
+import { shader_sh_exp_log_floor } from "./shader_sh_exp_log_floor.js";
+import { shader_sh_exp_project } from "./shader_sh_exp_project.js";
+import { shader_sh_exp_reference_reflectance } from "./shader_sh_exp_reference_reflectance.js";
+import { shader_sh_exp_solve } from "./shader_sh_exp_solve.js";
+
+/**
+ * @typedef {import("../../../../device/ShadeGPUCommandContext.js").ShadeGPUCommandContext} ShadeGPUCommandContext
+ */
+
+/**
+ * The shape of an SH-exponential encoding. Every field is required.
+ *
+ * @typedef {Object} SHExpEncoderSettings
+ * @property {number} p_band_count bands of the P (reflection) term, [1, 10]
+ * @property {number} q_band_count bands of the Q (half-reflection) term, [1, 10]
+ * @property {number} alpha_min smallest GGX alpha (roughness²) the probe is fitted for, > 0
+ * @property {number} alpha_max largest
+ * @property {number} sample_count fit samples, at least the unknown count, at most {@link SH_EXP_MAX_SAMPLE_COUNT}
+ * @property {number} cell_resolution side of the octahedral grid the reference is integrated over,
+ *  [{@link SH_EXP_MIN_CELL_RESOLUTION}, {@link SH_EXP_MAX_CELL_RESOLUTION}]
+ */
+
+/**
+ * The configuration of Silvennoinen et al.'s results: P to degree 4 and Q to degree 2 — five and three
+ * bands, 33 unknowns per channel. They evaluate it over alpha in [0.25, 1] (below that it blurs what
+ * should be sharp, Section 5.4) and fit it over a range relaxed to [0.20, 1] (Section 5.1), which is
+ * the range here: the probe's header carries it, so reconstruction clamps to 0.20, not 0.25.
+ *
+ * 4096 samples, where the paper takes 64 x 64 x 4 = 16384: the f64 prototype fitted 1024, 4096 and
+ * 16384 to the same reconstruction error within 0.02 in log space, by roughness quarter (a synthetic
+ * sun-and-sky map, 2026-10-03), and 4096 leaves the system 124 rows per unknown. A 64 grid has cells ~3°
+ * across; see `shader_sh_exp_reference_reflectance`.
+ *
+ * @type {Readonly<SHExpEncoderSettings>}
+ */
+export const SH_EXP_P4Q2_SETTINGS = Object.freeze({
+    p_band_count: 5,
+    q_band_count: 3,
+    alpha_min: 0.20,
+    alpha_max: 1,
+    sample_count: 4096,
+    cell_resolution: 64,
+});
+
+/**
+ * Floor under `log E0`, as a fraction of the mean luminance of `E0`; see `shader_sh_exp_log_floor`.
+ * A thousandth keeps ~7 natural-log units of range below the mean, which is darker than anything a
+ * glossy reflection of the rest shows next to it.
+ *
+ * @type {number}
+ */
+export const SH_EXP_LOG_FLOOR_RATIO = 1e-3;
+
+/**
+ * Most bands either term may have: what `sh_exp_design_row` and the generated reconstruction chunks
+ * (`sh{N}_color_evaluate_vmf`, N <= 10) cover. The paper's largest configuration is degree 9.
+ *
+ * @type {number}
+ */
+export const SH_EXP_MAX_BAND_COUNT = 10;
+
+/**
+ * Most fit samples: the single-workgroup log-floor pass and each unknown's projection walk them 256
+ * lanes at a time, so 8192 is 32 steps a lane — the projection's steps each evaluating one SH
+ * coefficient, at most 19 recurrence steps. Twice the default; 41 rows per unknown at ten-and-ten bands.
+ *
+ * @type {number}
+ */
+export const SH_EXP_MAX_SAMPLE_COUNT = 8192;
+
+/**
+ * Finest reference grid: the reference pass walks its cells 256 lanes at a time, 16 steps at 64.
+ *
+ * @type {number}
+ */
+export const SH_EXP_MAX_CELL_RESOLUTION = 64;
+
+/**
+ * Coarsest reference grid: an 8 grid's cells are 22° across, already coarse next to the narrowest lobe
+ * the default range fits (alpha 0.20). Below it a cell stops being a fair stand-in for its patch.
+ *
+ * @type {number}
+ */
+export const SH_EXP_MIN_CELL_RESOLUTION = 8;
+
+/**
+ * Encodes an octahedral environment map into a spherical-harmonic-exponential reflection probe, on
+ * the GPU.
+ *
+ * The representation is Silvennoinen, Sloan, Iwanicki and Nowrouzezahrai, "Spherical Harmonic
+ * Exponentials for Efficient Glossy Reflections", HPG 2025 / Computer Graphics Forum 44(8)
+ * (https://doi.org/10.1111/cgf.70219; slides:
+ * https://highperformancegraphics.org/untracked/2025/presentations/Pa5_1_hpg_2025_slides.pdf; talk:
+ * https://www.youtube.com/watch?v=THVMMNZ68iA). The GGX base reflectance of a probe's environment,
+ *
+ *     E0(v, n, alpha) ≈ P(r, alpha) · Q(h_r, alpha)
+ *     P(r, alpha)     = exp(<vMF(1/alpha) ⊙ Y(r),   p>)
+ *     Q(h_r, alpha)   = exp(<vMF(1/alpha) ⊙ Y(h_r), q>)
+ *
+ * with `r` the reflection of the view about the normal and `h_r = normalize(n + r)`, is fitted by
+ * linear least squares in log space over a fixed set of `(n, v, alpha)` samples. A probe is a few
+ * hundred bytes for every roughness in its range, view-dependent, and reconstructs without the
+ * aliasing of a prefiltered map; `chunk_sh_exp_p4q2_base_reflectance` reads it back.
+ *
+ * Construction does the configuration's fixed work on the CPU — the samples, and the inverse of the
+ * least-squares system's matrix, which depends on the samples alone ({@link sh_exp_solve_matrix}) —
+ * and uploads it. {@link encode} then records five dispatches per environment:
+ *
+ * 1. `shader_sh_exp_environment_cells` — the map, integrated down to a `cell_resolution²` octahedral grid;
+ * 2. `shader_sh_exp_reference_reflectance` — `E0` at every sample, by quadrature over that grid;
+ * 3. `shader_sh_exp_log_floor` — the floor `log E0` is taken above;
+ * 4. `shader_sh_exp_project` — the right-hand side `Aᵀ log E0 / S`;
+ * 5. `shader_sh_exp_solve` — the coefficients, written as a probe.
+ *
+ * Needs a device with the `subgroups` feature, as the engine always requests.
+ */
+export class SHExpEncoder {
+    /**
+     * @type {Readonly<SHExpEncoderSettings>}
+     */
+    #settings;
+
+    /**
+     * @type {GPUBuffer}
+     */
+    #samples;
+
+    /**
+     * @type {GPUBuffer}
+     */
+    #solve_matrix;
+
+    /**
+     * @type {GPUBuffer}
+     */
+    #cells;
+
+    /**
+     * @type {GPUBuffer}
+     */
+    #reflectance;
+
+    /**
+     * @type {GPUBuffer}
+     */
+    #statistics;
+
+    /**
+     * @type {GPUBuffer}
+     */
+    #projection;
+
+    /**
+     * @param {GPUDevice} device
+     * @param {SHExpEncoderSettings} settings
+     */
+    constructor(device, settings) {
+        assert.defined(device, 'device');
+
+        const {
+            p_band_count,
+            q_band_count,
+            alpha_min,
+            alpha_max,
+            sample_count,
+            cell_resolution,
+        } = settings;
+
+        assert.isPositiveInteger(p_band_count, 'p_band_count');
+        assert.lessThanOrEqual(p_band_count, SH_EXP_MAX_BAND_COUNT, 'p_band_count');
+        assert.isPositiveInteger(q_band_count, 'q_band_count');
+        assert.lessThanOrEqual(q_band_count, SH_EXP_MAX_BAND_COUNT, 'q_band_count');
+
+        assert.isNumber(alpha_min, 'alpha_min');
+        assert.greaterThan(alpha_min, 0, 'alpha_min');
+        assert.isNumber(alpha_max, 'alpha_max');
+        assert.greaterThanOrEqual(alpha_max, alpha_min, 'alpha_max');
+
+        const coefficient_count = sh_exp_coefficient_count(p_band_count, q_band_count);
+
+        assert.isPositiveInteger(sample_count, 'sample_count');
+        assert.greaterThanOrEqual(sample_count, coefficient_count, 'sample_count');
+        assert.lessThanOrEqual(sample_count, SH_EXP_MAX_SAMPLE_COUNT, 'sample_count');
+
+        assert.isPositiveInteger(cell_resolution, 'cell_resolution');
+        assert.greaterThanOrEqual(cell_resolution, SH_EXP_MIN_CELL_RESOLUTION, 'cell_resolution');
+        assert.lessThanOrEqual(cell_resolution, SH_EXP_MAX_CELL_RESOLUTION, 'cell_resolution');
+
+        this.#settings = Object.freeze({
+            p_band_count,
+            q_band_count,
+            alpha_min,
+            alpha_max,
+            sample_count,
+            cell_resolution,
+        });
+
+        const sample_data = new Float32Array(sample_count * SH_EXP_FIT_SAMPLE_FLOATS);
+
+        sh_exp_fit_samples(sample_data, sample_count, alpha_min, alpha_max);
+
+        // built from the f32 samples the GPU reads, not from their f64 originals
+        const solve_matrix = new Float32Array(coefficient_count * coefficient_count);
+
+        sh_exp_solve_matrix(solve_matrix, sample_data, sample_count, p_band_count, q_band_count);
+
+        const STORAGE = GPUBufferUsage.STORAGE;
+        const COPY_DST = GPUBufferUsage.COPY_DST;
+
+        this.#samples = device.createBuffer({
+            label: "SH exponential / fit samples",
+            size: sample_data.byteLength,
+            usage: STORAGE | COPY_DST,
+        });
+
+        this.#solve_matrix = device.createBuffer({
+            label: "SH exponential / solve matrix",
+            size: solve_matrix.byteLength,
+            usage: STORAGE | COPY_DST,
+        });
+
+        device.queue.writeBuffer(this.#samples, 0, sample_data);
+        device.queue.writeBuffer(this.#solve_matrix, 0, solve_matrix);
+
+        this.#cells = device.createBuffer({
+            label: "SH exponential / environment cells",
+            size: 2 * cell_resolution * cell_resolution * 16,
+            usage: STORAGE,
+        });
+
+        this.#reflectance = device.createBuffer({
+            label: "SH exponential / reference reflectance",
+            size: sample_count * 16,
+            usage: STORAGE,
+        });
+
+        this.#statistics = device.createBuffer({
+            label: "SH exponential / statistics",
+            size: 16,
+            usage: STORAGE,
+        });
+
+        this.#projection = device.createBuffer({
+            label: "SH exponential / projection",
+            size: coefficient_count * 16,
+            usage: STORAGE,
+        });
+    }
+
+    /**
+     * @returns {Readonly<SHExpEncoderSettings>}
+     */
+    get settings() {
+        return this.#settings;
+    }
+
+    /**
+     * Unknowns per colour channel.
+     * @returns {number}
+     */
+    get coefficient_count() {
+        return sh_exp_coefficient_count(this.#settings.p_band_count, this.#settings.q_band_count);
+    }
+
+    /**
+     * Size of one encoded probe, in `vec4<f32>` (16 bytes each); see `sh_exp_probe_vec4_count`.
+     * @returns {number}
+     */
+    get probe_vec4_count() {
+        return sh_exp_probe_vec4_count(this.#settings.p_band_count, this.#settings.q_band_count);
+    }
+
+    /**
+     * Records the encoding of `environment` into `output`, starting at `vec4` index `output_offset`.
+     *
+     * @param {Object} options
+     * @param {ShadeGPUCommandContext} options.encoder
+     * @param {GPUTextureView|GPUTexture} options.environment octahedral radiance map whose level 0 is
+     *  unfiltered radiance, as `GPULightCollection.environment` holds it; read texel by texel
+     * @param {GPUBuffer} options.output STORAGE; at least `(output_offset + probe_vec4_count) * 16` bytes
+     * @param {number} options.output_offset in `vec4`
+     */
+    encode({ encoder, environment, output, output_offset }) {
+        assert.defined(encoder, 'encoder');
+        assert.defined(environment, 'environment');
+        assert.defined(output, 'output');
+        assert.isNonNegativeInteger(output_offset, 'output_offset');
+        assert.greaterThanOrEqual(output.size, (output_offset + this.probe_vec4_count) * 16, 'output.size');
+
+        const settings = this.#settings;
+        const coefficient_count = this.coefficient_count;
+
+        const parameters = encoder.allocateTransientValueBuffer(SH_EXP_ENCODE_PARAMETERS_STRUCT, {
+            cell_resolution: settings.cell_resolution,
+            sample_count: settings.sample_count,
+            p_band_count: settings.p_band_count,
+            q_band_count: settings.q_band_count,
+            coefficient_count,
+            output_offset,
+            alpha_min: settings.alpha_min,
+            alpha_max: settings.alpha_max,
+            log_floor_ratio: SH_EXP_LOG_FLOOR_RATIO,
+        }, GPUBufferUsage.UNIFORM);
+
+        shader_sh_exp_environment_cells.dispatch({
+            encoder,
+            group_count_x: settings.cell_resolution * settings.cell_resolution,
+            bindings: {
+                parameters,
+                tEnvironment: environment,
+                cells: this.#cells,
+            },
+        });
+
+        shader_sh_exp_reference_reflectance.dispatch({
+            encoder,
+            group_count_x: settings.sample_count,
+            bindings: {
+                parameters,
+                samples: this.#samples,
+                cells: this.#cells,
+                reflectance: this.#reflectance,
+            },
+        });
+
+        shader_sh_exp_log_floor.dispatch({
+            encoder,
+            group_count_x: 1,
+            bindings: {
+                parameters,
+                reflectance: this.#reflectance,
+                statistics: this.#statistics,
+            },
+        });
+
+        shader_sh_exp_project.dispatch({
+            encoder,
+            group_count_x: coefficient_count,
+            bindings: {
+                parameters,
+                samples: this.#samples,
+                reflectance: this.#reflectance,
+                statistics: this.#statistics,
+                projection: this.#projection,
+            },
+        });
+
+        shader_sh_exp_solve.dispatch({
+            encoder,
+            group_count_x: coefficient_count,
+            bindings: {
+                parameters,
+                solve_matrix: this.#solve_matrix,
+                projection: this.#projection,
+                probe: output,
+            },
+        });
+    }
+
+    /**
+     * Releases the GPU buffers. The encoder cannot be used afterwards.
+     */
+    destroy() {
+        this.#samples.destroy();
+        this.#solve_matrix.destroy();
+        this.#cells.destroy();
+        this.#reflectance.destroy();
+        this.#statistics.destroy();
+        this.#projection.destroy();
+    }
+}

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

@@ -0,0 +1,16 @@
+/**
+ * What every pass of the SH-exponential encoder reads; see `SHExpEncoder`.
+ *
+ * - `cell_resolution`: side of the octahedral grid the environment is integrated over;
+ * - `sample_count`: fit samples, one `(normal, view, alpha)` each;
+ * - `p_band_count`, `q_band_count`: bands of the P and Q terms;
+ * - `coefficient_count`: unknowns per channel, `p_band_count² + q_band_count² - 1`;
+ * - `output_offset`: first `vec4` of the probe in the output buffer;
+ * - `alpha_min`, `alpha_max`: the roughness range fitted, written into the probe's header;
+ * - `log_floor_ratio`: the floor under `log E0`, as a fraction of the mean luminance of `E0`.
+ *
+ * @type {WebGPUStruct}
+ */
+export const SH_EXP_ENCODE_PARAMETERS_STRUCT: WebGPUStruct;
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+//# sourceMappingURL=SH_EXP_ENCODE_PARAMETERS_STRUCT.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SH_EXP_ENCODE_PARAMETERS_STRUCT.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/light/environment/sh_exponential/SH_EXP_ENCODE_PARAMETERS_STRUCT.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;GAYG;AACH,8CAFU,YAAY,CAYM;6BAzBC,sCAAsC"}

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

@@ -0,0 +1,27 @@
+import { f32, u32 } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
+
+/**
+ * What every pass of the SH-exponential encoder reads; see `SHExpEncoder`.
+ *
+ * - `cell_resolution`: side of the octahedral grid the environment is integrated over;
+ * - `sample_count`: fit samples, one `(normal, view, alpha)` each;
+ * - `p_band_count`, `q_band_count`: bands of the P and Q terms;
+ * - `coefficient_count`: unknowns per channel, `p_band_count² + q_band_count² - 1`;
+ * - `output_offset`: first `vec4` of the probe in the output buffer;
+ * - `alpha_min`, `alpha_max`: the roughness range fitted, written into the probe's header;
+ * - `log_floor_ratio`: the floor under `log E0`, as a fraction of the mean luminance of `E0`.
+ *
+ * @type {WebGPUStruct}
+ */
+export const SH_EXP_ENCODE_PARAMETERS_STRUCT = WebGPUStruct.from({
+    cell_resolution: u32,
+    sample_count: u32,
+    p_band_count: u32,
+    q_band_count: u32,
+    coefficient_count: u32,
+    output_offset: u32,
+    alpha_min: f32,
+    alpha_max: f32,
+    log_floor_ratio: f32,
+}, "SHExpEncodeParameters");

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

@@ -0,0 +1,21 @@
+/**
+ * Largest workgroup the SH-exponential encoder's kernels run. The partial-sum array holds one slot per
+ * invocation, which is what a one-lane subgroup needs — the WGSL emulator's, so these kernels run
+ * whole there — at 4 KiB of workgroup memory. A device with 32-lane subgroups fills eight.
+ *
+ * @type {number}
+ */
+export const SH_EXP_WORKGROUP_SIZE: number;
+/**
+ * Sum of a `vec4` over the workgroup, subgroup first: `subgroupAdd`, then one elected lane per
+ * subgroup claims a slot — invocation indices need not map to subgroups in contiguous blocks — and
+ * invocation 0 adds the slots after the barrier. The result is only meaningful in invocation 0.
+ *
+ * Call once per invocation, from uniform control flow. The order the slots are claimed in varies, so
+ * the last bits of a sum can differ between two runs.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_sh_exp_workgroup_sum: CodeChunk;
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_sh_exp_workgroup_sum.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_sh_exp_workgroup_sum.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/light/environment/sh_exponential/chunk_sh_exp_workgroup_sum.js"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH,oCAFU,MAAM,CAEyB;AAEzC;;;;;;;;;GASG;AACH,yCAFU,SAAS,CA8BhB;0BAjDuB,uCAAuC"}

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

@@ -0,0 +1,53 @@
+import { WebGPUExtensionType } from "../../../../descriptor/WebGPUExtensionType.js";
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+
+/**
+ * Largest workgroup the SH-exponential encoder's kernels run. The partial-sum array holds one slot per
+ * invocation, which is what a one-lane subgroup needs — the WGSL emulator's, so these kernels run
+ * whole there — at 4 KiB of workgroup memory. A device with 32-lane subgroups fills eight.
+ *
+ * @type {number}
+ */
+export const SH_EXP_WORKGROUP_SIZE = 256;
+
+/**
+ * Sum of a `vec4` over the workgroup, subgroup first: `subgroupAdd`, then one elected lane per
+ * subgroup claims a slot — invocation indices need not map to subgroups in contiguous blocks — and
+ * invocation 0 adds the slots after the barrier. The result is only meaningful in invocation 0.
+ *
+ * Call once per invocation, from uniform control flow. The order the slots are claimed in varies, so
+ * the last bits of a sum can differ between two runs.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_sh_exp_workgroup_sum = CodeChunk.from(
+    //language=WGSL
+    `
+var<workgroup> sh_exp_partial_count: atomic<u32>;
+var<workgroup> sh_exp_partials: array<vec4<f32>, ${SH_EXP_WORKGROUP_SIZE}>;
+
+fn sh_exp_workgroup_sum(value: vec4<f32>, local_index: u32) -> vec4<f32> {
+    let subgroup_sum = subgroupAdd(value);
+
+    if (subgroupElect()) {
+        let slot = atomicAdd(&sh_exp_partial_count, 1u);
+        sh_exp_partials[slot] = subgroup_sum;
+    }
+
+    workgroupBarrier();
+
+    var sum = vec4<f32>(0.0);
+
+    if (local_index == 0u) {
+        let count = atomicLoad(&sh_exp_partial_count);
+
+        for (var i = 0u; i < count; i++) {
+            sum += sh_exp_partials[i];
+        }
+    }
+
+    return sum;
+}
+`);
+
+chunk_sh_exp_workgroup_sum.addExtension(WebGPUExtensionType.Subgroups);