@woosh/meep-engine 3.38.0 → 3.40.0

package/src/shade/renderer/light/LIGHT_DATABASE_SPEC.js

@@ -1,13 +1,14 @@
-import { vec4f } from "../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
-import { WebGPUArray } from "../shader/type/WebGPUArray.js";
+import { u32, vec2i, vec4f } from "../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
 import { GPUDatabaseDefinition } from "../buffer/table/GPUDatabaseDefinition.js";
 import { SCENE_DATABASE_SPEC } from "../scene/SCENE_DATABASE_SPEC.js";
 import { DIRECTIONAL_LIGHT_STRUCT } from "../shader/chunk/light/DIRECTIONAL_LIGHT_STRUCT.js";
 import { POINT_LIGHT_STRUCT } from "../shader/chunk/light/POINT_LIGHT_STRUCT.js";
 import { SPOT_LIGHT_STRUCT } from "../shader/chunk/light/SPOT_LIGHT_STRUCT.js";
-import { CSM_CASTER_RANGE_STRUCT } from "../shadow/map/csm/CSM_CASTER_RANGE_STRUCT.js";
-import { SHADOWMAP_CSM_CASCADE_COUNT } from "../shadow/map/csm/SHADOWMAP_CSM_CASCADE_COUNT.js";
+import { CSM_CASCADE_STRUCT } from "../shadow/map/csm/CSM_CASCADE_STRUCT.js";
+import { DIRECTIONAL_SHADOWMAP_STRUCT } from "../shadow/map/DIRECTIONAL_SHADOWMAP_STRUCT.js";
 import { SHADOWMAP_VIEW_METADATA_STRUCT } from "../shadow/map/shader/SHADOWMAP_VIEW_METADATA_STRUCT.js";
+import { VSM_RECORD_STRUCT } from "../shadow/vsm/VSM_RECORD_STRUCT.js";
+import { VSM_SLOT_STRUCT } from "../shadow/vsm/VSM_SLOT_STRUCT.js";
 
 export const LIGHT_DATABASE_SPEC = GPUDatabaseDefinition.from({
     light_point: POINT_LIGHT_STRUCT,
@@ -16,16 +17,83 @@ export const LIGHT_DATABASE_SPEC = GPUDatabaseDefinition.from({
 
     // shadow metadata, indexed by `light.shadow_id` from the matching light record.
     // Point lights store only the atlas rect — sampling is direction-based and uses no
-    // projection. Spot/directional store atlas + projection per view (1 for spot,
-    // SHADOWMAP_CSM_CASCADE_COUNT cascades for directional).
+    // projection. Spot lights store atlas + projection for their one view. Directional lights
+    // store where their cascades are, as a range over `shadow_cascade`, or which virtual shadow map
+    // they have, as a link into `shadow_virtual`.
     shadow_point: vec4f,
     shadow_spot: SHADOWMAP_VIEW_METADATA_STRUCT,
-    shadow_directional: WebGPUArray.from(SHADOWMAP_VIEW_METADATA_STRUCT, SHADOWMAP_CSM_CASCADE_COUNT),
+    shadow_directional: DIRECTIONAL_SHADOWMAP_STRUCT,
 
-    // per directional shadow map, what the GPU measured of the casters in front of each cascade —
-    // written by the caster-range pass, read back to fit the next frame's near planes; one row per
-    // map, claimed and released by the shadow context
-    shadow_csm_caster_range: CSM_CASTER_RANGE_STRUCT,
+    // one row per cascade of a directional shadow map, a map's cascades a run of consecutive rows
+    // claimed and released by the shadow context: atlas + projection from the CPU, and what the GPU
+    // measured of the casters in front of the cascade, read back to fit the next frame's near plane
+    shadow_cascade: CSM_CASCADE_STRUCT,
+
+    // one row per virtual shadow map: its light space, clipmap windows, pool, and the main view it
+    // selects levels for
+    shadow_virtual: VSM_RECORD_STRUCT,
+
+    // a virtual shadow map's clipmap windows, a run per map, one row per level: the corner of the
+    // level's window in its own pages — written by the CPU when the window scrolls
+    shadow_virtual_level: vec2i,
+
+    // a virtual shadow map's page table, a run per map, one page-table entry per cell of every
+    // level's window — written by the CPU as pages are installed, evicted and scrolled away
+    shadow_virtual_page: u32,
+
+    // what each slot of a virtual shadow map's pool holds, a run per map — written by the CPU with
+    // the page table, read by the pass that finds pages under moving casters
+    shadow_virtual_slot: VSM_SLOT_STRUCT,
+});
+
+// A directional light's virtual shadow map. Not owning, for the reason the cascade range is not.
+LIGHT_DATABASE_SPEC.add_link({
+    table: 'shadow_directional',
+    field: 'virtual_map',
+    target_database: LIGHT_DATABASE_SPEC,
+    target_table: 'shadow_virtual',
+    nullable: true,
+    owning: false,
+});
+
+// A virtual shadow map's level, page table and slot rows. The shadow context claims the runs with the
+// map and gives them back when it evicts it.
+LIGHT_DATABASE_SPEC.add_range({
+    table: 'shadow_virtual',
+    first_field: 'first_level',
+    count_field: 'level_count',
+    target_database: LIGHT_DATABASE_SPEC,
+    target_table: 'shadow_virtual_level',
+    owning: false,
+});
+
+LIGHT_DATABASE_SPEC.add_range({
+    table: 'shadow_virtual',
+    first_field: 'first_page',
+    count_field: 'page_count',
+    target_database: LIGHT_DATABASE_SPEC,
+    target_table: 'shadow_virtual_page',
+    owning: false,
+});
+
+LIGHT_DATABASE_SPEC.add_range({
+    table: 'shadow_virtual',
+    first_field: 'first_slot',
+    count_field: 'slot_count',
+    target_database: LIGHT_DATABASE_SPEC,
+    target_table: 'shadow_virtual_slot',
+    owning: false,
+});
+
+// A directional shadow map's cascades. Not owning: the shadow context holds the run for the life of
+// the map, while the record naming it sits in a slot reassigned densely as maps come and go.
+LIGHT_DATABASE_SPEC.add_range({
+    table: 'shadow_directional',
+    first_field: 'first_cascade',
+    count_field: 'cascade_count',
+    target_database: LIGHT_DATABASE_SPEC,
+    target_table: 'shadow_cascade',
+    owning: false,
 });
 
 for (const kind of ['point', 'spot', 'directional']) {

package/src/shade/renderer/light/environment/rgbe/load_environment_map.d.ts

@@ -1,5 +1,6 @@
 /**
- * TODO make a conversion tool, to avoid having to do this in main thread every time
+ * An equirectangular map is resampled to octahedral here, on the main thread, on every load;
+ * `tools/environment/convert_equirectangular_to_octahedral.mjs` does the same conversion once, offline.
  * @param {string} url
  * @param {ProjectionMappingType} [projection]
  * @returns {Promise<ShadeTexture>}

package/src/shade/renderer/light/environment/rgbe/load_environment_map.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"load_environment_map.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/light/environment/rgbe/load_environment_map.js"],"names":[],"mappings":"AAyCA;;;;;GAKG;AACH,0CAJW,MAAM,eACN,qBAAqB,GACnB,QAAQ,YAAY,CAAC,CA2CjC;oCAzES,MAAM;;;;;6BARa,kCAAkC"}
+{"version":3,"file":"load_environment_map.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/light/environment/rgbe/load_environment_map.js"],"names":[],"mappings":"AAyCA;;;;;;GAMG;AACH,0CAJW,MAAM,eACN,qBAAqB,GACnB,QAAQ,YAAY,CAAC,CA2CjC;oCA1ES,MAAM;;;;;6BARa,kCAAkC"}

package/src/shade/renderer/light/environment/rgbe/load_environment_map.js

@@ -40,7 +40,8 @@ function download_env_map(data, width, height, file_name = 'env_map',) {
 
 
 /**
- * TODO make a conversion tool, to avoid having to do this in main thread every time
+ * An equirectangular map is resampled to octahedral here, on the main thread, on every load;
+ * `tools/environment/convert_equirectangular_to_octahedral.mjs` does the same conversion once, offline.
  * @param {string} url
  * @param {ProjectionMappingType} [projection]
  * @returns {Promise<ShadeTexture>}

package/src/shade/renderer/light/environment/rgbe/parse_rgbe.d.ts

@@ -8,7 +8,7 @@
 export function parse_rgbe(buffer: ArrayBuffer, type?: BinaryDataType.Float16 | BinaryDataType.Float32): {
     width: number;
     height: number;
-    data: Float32Array | Uint16Array;
+    data: any;
     header: string;
     gamma: number;
     exposure: number;

package/src/shade/renderer/light/environment/rgbe/parse_rgbe.js

@@ -48,7 +48,7 @@ export function parse_rgbe(
         case BinaryDataType.Float16:
 
             numElements = image_rgba_data.length / 4;
-            const halfArray = new Uint16Array(numElements * 4);
+            const halfArray = new Float16Array(numElements * 4);
 
             for (let j = 0; j < numElements; j++) {
 
@@ -76,4 +76,4 @@ export function parse_rgbe(
         type: type
     };
 
-}
+}

package/src/shade/renderer/light/environment/rgbe/rgbe_byte_to_rgb_half.d.ts

@@ -2,8 +2,8 @@
  *
  * @param {Uint8Array} sourceArray
  * @param {number} sourceOffset
- * @param {Uint16Array} destArray
+ * @param {Float16Array} destArray
  * @param {number} destOffset
  */
-export function rgbe_byte_to_rgb_half(sourceArray: Uint8Array, sourceOffset: number, destArray: Uint16Array, destOffset: number): void;
+export function rgbe_byte_to_rgb_half(sourceArray: Uint8Array, sourceOffset: number, destArray: Float16Array, destOffset: number): void;
 //# sourceMappingURL=rgbe_byte_to_rgb_half.d.ts.map

package/src/shade/renderer/light/environment/rgbe/rgbe_byte_to_rgb_half.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rgbe_byte_to_rgb_half.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/light/environment/rgbe/rgbe_byte_to_rgb_half.js"],"names":[],"mappings":"AAQA;;;;;;GAMG;AACH,mDALW,UAAU,gBACV,MAAM,aACN,WAAW,cACX,MAAM,QAchB"}
+{"version":3,"file":"rgbe_byte_to_rgb_half.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/light/environment/rgbe/rgbe_byte_to_rgb_half.js"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,mDALW,UAAU,gBACV,MAAM,uCAEN,MAAM,QAchB"}

package/src/shade/renderer/light/environment/rgbe/rgbe_byte_to_rgb_half.js

@@ -1,16 +1,8 @@
-import { to_half_float_uint16 } from "../../../../../core/binary/to_half_float_uint16.js";
-
-/**
- * Precomputed for simplicity
- * @type {number}
- */
-const F16_1 = to_half_float_uint16(1);
-
 /**
  *
  * @param {Uint8Array} sourceArray
  * @param {number} sourceOffset
- * @param {Uint16Array} destArray
+ * @param {Float16Array} destArray
  * @param {number} destOffset
  */
 export function rgbe_byte_to_rgb_half(sourceArray, sourceOffset, destArray, destOffset) {
@@ -19,10 +11,10 @@ export function rgbe_byte_to_rgb_half(sourceArray, sourceOffset, destArray, dest
     const scale = Math.pow(2.0, e - 128.0) / 255.0;
 
     // clamping to 65504, the maximum representable value in float16
-    destArray[destOffset + 0] = to_half_float_uint16(Math.min(sourceArray[sourceOffset + 0] * scale, 65504));
-    destArray[destOffset + 1] = to_half_float_uint16(Math.min(sourceArray[sourceOffset + 1] * scale, 65504));
-    destArray[destOffset + 2] = to_half_float_uint16(Math.min(sourceArray[sourceOffset + 2] * scale, 65504));
+    destArray[destOffset + 0] = Math.min(sourceArray[sourceOffset + 0] * scale, 65504);
+    destArray[destOffset + 1] = Math.min(sourceArray[sourceOffset + 1] * scale, 65504);
+    destArray[destOffset + 2] = Math.min(sourceArray[sourceOffset + 2] * scale, 65504);
 
-    destArray[destOffset + 3] = F16_1;
+    destArray[destOffset + 3] = 1;
 
-}
+}

package/src/shade/renderer/light/environment/sh_exponential/README.md

@@ -0,0 +1,171 @@
+# Spherical harmonic exponential reflection probes
+
+An implementation of
+
+> Ari Silvennoinen, Peter-Pike Sloan, Michał Iwanicki, Derek Nowrouzezahrai.
+> **Spherical Harmonic Exponentials for Efficient Glossy Reflections.** High-Performance Graphics 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
+
+An environment's glossy reflection for every GGX roughness in a range, view-dependent, in 33 RGB
+coefficients at the paper's configuration: what a split-sum prefiltered map stores in a mip chain, a
+few hundred bytes instead, without the `v = n` assumption and without aliasing.
+
+## The method
+
+Reflected radiance is split as in the split sum [Kar13], `E ≈ F0·E0 + (1 − F0)·E1`, and only the
+base reflectance is modelled:
+
+    E0(v, n, α) = ∫ L(l) f_DV(v, n, l, α) ⟨l, n⟩ dl              (GGX without Fresnel)
+               ≈ P(r, α) · Q(h_r, α)                                [MAA01]
+    P(r, α)    = exp(⟨vMF(1/α) ⊙ Y(r),   p⟩)
+    Q(h_r, α)  = exp(⟨vMF(1/α) ⊙ Y(h_r), q⟩)
+
+`r = reflect(−v, n)` and `h_r = normalize(n + r)` (the paper's reflection-half-reflection
+parametrization), `Y` the real SH basis, `vMF_l(κ) = exp(−l(l+1) / 2κ)` the band window of a von
+Mises-Fisher lobe (Ref-NeRF's directional encoding [VHM*22]), so one set of coefficients covers every
+roughness. Taking logs makes it linear in `[p; q]`, solved by least squares over many `(v, n, α)`.
+
+## Where things are
+
+| | |
+|---|---|
+| `SHExpEncoder.js` | host side: builds the configuration's constants, records the five passes |
+| `sh_exp_fit_samples.js`, `sh_exp_design_row.js`, `sh_exp_solve_matrix.js` | the fit's fixed samples, its rows, and the inverse of its normal matrix (CPU, f64) |
+| `shader_sh_exp_*.js` | the passes: environment cells → reference `E0` → log floor → projection → solve |
+| `../../../shader/chunk/spherical_harmonics/exponential/` | reconstruction: `sh_exp_p4q2_base_reflectance`, `sh_exp_specular`, `sh_exp_radiance`, the probe struct |
+| `../../../shader/chunk/spherical_harmonics/generated/` | `sh{N}_color_evaluate_vmf` and `sh{N}_basis_at`, generated by `tools/codegen/spherical_harmonics/` |
+| `../../../../playground/sh_exponential/` | sphere grid: reference, SH exponential, the engine's split-sum IBL, error |
+
+Encoding, with the default configuration:
+
+```js
+const encoder = new SHExpEncoder(device, SH_EXP_P4Q2_SETTINGS); // once: 8 ms of CPU
+encoder.encode({ encoder: cmd, environment: lights.environment.obtainView(), output: probes, output_offset: 0 });
+```
+
+Reconstruction, in WGSL, with the probe bound as `SH_EXP_P4Q2_PROBE_STRUCT`:
+
+```wgsl
+let e0 = sh_exp_p4q2_base_reflectance(probe, view_direction, normal, alpha);   // alpha = roughness²
+let specular = sh_exp_specular(e0, f0, f90, dfg);   // dfg: tSplitSum at (NoV, roughness)
+```
+
+## Decisions
+
+Measured with an f64 prototype of the method and with these modules' own CPU fit, on the octahedral
+Venice-sunset and Rustig-Koppie maps and a synthetic sun-and-sky (2026-10-03). Error is the RMSE of
+Reinhard-tonemapped luminance (exposure at the mean), over held-out `(v, n, α)` with α in [0.25, 1] and
+views cosine-weighted about the normal (the screen footprint of a sphere), by α third unless stated.
+
+1. **What is fitted: `E0`, as the paper says.** Fitting `E0 / (A + B)` — the BRDF's directional albedo
+   divided out — looked attractive, since the albedo depends on `n·v`, which `P(r)·Q(h_r)` cannot
+   represent. Measured, it is not a win: tonemapped error 0.045 / 0.023 / 0.042 against 0.067 / 0.037 /
+   0.068 on Venice (α in [0.25, 0.45), [0.45, 0.7), [0.7, 1]), but 0.099 / 0.077 / 0.119 against
+   0.085 / 0.078 / 0.100 on Rustig-Koppie, and slightly worse on the synthetic sun. Reversal: divide `E0` by the albedo the
+   reference pass can integrate alongside it, and multiply it back in `sh_exp_radiance`'s place.
+2. **The Fresnel tail is `E0 · B / (A + B)`** — the paper's own assumption, made consistent. Section 4.2
+   (eq. 15) approximates the tail by taking the environment as a constant equal to `E0`, which gives
+   `E0 · ∫ f_DV Fc ⟨l,n⟩ = E0 · B`. A constant environment `c` has `E0 = c (A + B)`, so the constant is
+   `E0 / (A + B)`; the paper's form undercounts the tail by `A + B`, the energy its Figure 3 says the
+   tail loses at grazing angles. See `chunk_sh_exp_split_sum.js` for the numbers. This is the one split
+   the method keeps: E0 itself is modelled whole (Section 4: no prefiltered map, no `v = n`), and the
+   tail's factor, like the split sum's second integral, depends on no environment (Section 3.2: Karis
+   tabulates it, Lazarov fits it analytically). `sh_exp_specular` is single
+   scattering; handing `sh_exp_radiance` to `compute_indirect_specular` adds the engine's
+   multiple-scattering term on top. The engine's `split_sum.bin` weights its scale and bias both by
+   Hauber's fourth power, so its `A + B` is the albedo to within 0.06% (measured; see the chunk).
+3. **A fixed, deterministic sample set** (5-D Halton) instead of fresh random samples per encode: the
+   least-squares matrix then depends on the configuration only, and is inverted once on the CPU in f64
+   (8–14 ms for 33 unknowns at 4096 samples, 141 ms for 199 at 8192). The GPU does a reduction and a
+   matrix-vector product per environment. 1024, 4096 and 16384 samples fitted the synthetic map to the
+   same error within 0.02 in log space, so 4096 where the paper takes 64 × 64 × 4 = 16384.
+4. **The paper's sample distribution** (Section 5.1): views uniform over the hemisphere about the
+   normal, normals uniform over the sphere, α uniform over a range relaxed below the one used — [0.20, 1]
+   for use over [0.25, 1]. The first version cosine-weighted the views (a sphere's screen footprint) and
+   fitted α over [0.25, 1]; with the paper's, this module's fit of Venice moved from 0.063 / 0.035 /
+   0.073 to 0.048 / 0.038 / 0.091 by roughness third (held-out views cosine-weighted), and the playground
+   below from as-close-or-worse than the engine's IBL everywhere to closer over α 0.36–0.64: better
+   where reflections are sharpest, worse at the rough end, as Section 5.4 describes.
+5. **The reference `E0` is a quadrature** over a 64×64 octahedral grid of the map, cells weighted by
+   exact texel solid angle. Noise-free, and a 128 grid fitted to the same error to the third decimal.
+6. **A ridge of `1e-4` of the mean diagonal**, constant band unpenalised. 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: condition
+   number 1.1e3 at five-and-three bands, 1.8e10 at ten-and-ten (3e3 and 8e11 under the earlier
+   cosine-weighted views, where an unregularized ten-and-ten fit ran coefficients to 2.4e4). Leaving
+   band 0 unpenalised keeps brightness scaling exact (`k·L` adds `ln k / Y00` to `p[0]`).
+7. **`log E0` is floored at 1e-3 of its mean luminance**, so a black lower hemisphere cannot pull the fit
+   towards `log 0`, and the encoding stays scale-invariant.
+8. **Probe layout**: a `vec4` header (fitted `α` range, band counts) and P and Q as `array<vec3<f32>>`
+   with Q's band 0 stored as zero, 560 bytes at the default — the paper's 33 × 3 floats would be 396.
+   Plain arrays so the generated `sh{N}_color_evaluate_vmf` take them as they are.
+
+## What limits it — measured
+
+The model's error across a roughness range is set by **how it couples roughness, not by its SH
+degree**. With `v = n` and α over [0.25, 1], five bands and ten bands reconstruct to the same
+tonemapped error, 0.066; at one fixed α = 0.1, ten bands are four times better than five (0.0066 against
+0.0285). And over the paper's sampling, ten-and-ten bands match five-and-three within 0.001 (0.048 /
+0.038 / 0.091 for both on Venice). The constant band has no window (`vMF_0 = 1`), so it cannot follow
+the GGX albedo's dependence on α — `E0` of a white environment at normal incidence falls from 0.92 at
+α = 0.25 to 0.31 at α = 1. The paper's Figure 6 shows the same: at α 0.81 and 1.0 its reconstruction
+stays bright where the reference darkens; and Section 5.4 notes the fit favours the low-roughness end,
+whose errors are larger.
+
+Below the fitted range, reconstruction clamps α to it (0.20 by default) and so stays blurrier than the
+surface.
+
+## On the device
+
+RTX 4090, Chrome, the Venice-sunset map at 1024² (2026-10-03, one-off headless run of the playground):
+
+- Encoding takes 0.11 ms of GPU time by timestamps (2026-10-04): reference reflectance 72 µs,
+  environment cells 24 µs, projection 11 µs, log floor and solve 2–3 µs each, no gaps between the
+  passes. Later in the same browser launch, after seconds of light load, the same encode of either map
+  reads 0.33–0.36 ms — the GPU's clock state, not the data. The paper reports 0.33 ms for its
+  precomputation on an RTX A6000 (CUDA) over the same number of BRDF evaluations, 16.8 million
+  (64 × 64 × 4 configurations × 1,024 directions; here 4,096 configurations × 4,096 cells).
+- The 3.0–3.7 ms this page and the playground reported before 2026-10-04 was submit-to-done wall time,
+  not GPU time: a 256-byte `clearBuffer` alone reads 0.5–4.6 ms that way (median 2.4 ms), which is
+  Chrome's completion latency. The playground now times the encode by timestamps.
+- Building the encoder takes 8–13 ms of CPU.
+- The probe the GPU writes for a 64² synthetic map matches the WGSL emulator's run of the same kernels
+  to 4.5e-5 on coefficients up to 10.8.
+- Against the playground's reference (quadrature over a 128² grid; tonemapped luminance RMSE over a
+  sphere seen head-on), by GGX α, the probe fitted with the paper's sample distribution:
+
+  | α | 0.09* | 0.16* | 0.25 | 0.36 | 0.49 | 0.64 | 0.81 | 1.00 |
+  |---|---|---|---|---|---|---|---|---|
+  | SH exponential, P4 Q2 | 0.082 | 0.061 | 0.041 | 0.025 | 0.022 | 0.030 | 0.049 | 0.074 |
+  | engine IBL (split sum) | 0.021 | 0.025 | 0.036 | 0.033 | 0.027 | 0.032 | 0.036 | 0.039 |
+  | SH exponential, first version | 0.083 | 0.059 | 0.042 | 0.033 | 0.033 | 0.035 | 0.045 | 0.064 |
+
+  \* below the fitted range. The probe is closer than the engine's prefiltered map over α 0.36–0.64;
+  the engine's is closer at 0.25 and from 0.81 up, where the exponential's constant band cannot follow
+  the albedo's fall with α (see above) and the split sum's LUT carries it per `n·v` and α. The error
+  image shows the exponential too bright at high α, as the paper's Figure 6 does. This is one view of
+  one map, E0 without Fresnel, against the engine's cone-filtered map — not the paper's test (chrome and
+  glass spheres against a GGX-prefiltered octahedral mip chain, MSE, 192 cases, lower in 95%).
+
+## Tests
+
+- `sh_exp_encoder_kernels.spec.js` — every pass under the WGSL emulator against an independent f64
+  oracle. The emulator's subgroups are one lane wide and its barrier is a no-op, so the workgroup
+  reduction's cross-lane half (`chunk_sh_exp_workgroup_sum`) is not exercised there; the one-off
+  device run below is what covers it. Pinned: cells tile the sphere, keep its integral, and take the
+  texels whose centres they hold at any pair of sizes; a white map at α = 1 reflects
+  `1 − n·v ln(1 + 1/n·v)`; the probe is the f64 least-squares fit of the kernels' own `E0`; scaling the
+  map moves only the constant band.
+- `sh_exp_solve_matrix.spec.js`, `sh_exp_fit_samples.spec.js`, `sh_exp_design_row.spec.js` — the CPU side.
+- `SHExpEncoder.spec.js` — the five dispatches, their sizes and buffers, on `SoftwareGPUDevice`.
+- `chunk_sh_exp_p4q2_base_reflectance.spec.js` — reconstruction against the CPU design row.
+
+## References
+
+- [Kar13] Brian Karis, "Real Shading in Unreal Engine 4", SIGGRAPH 2013 course notes.
+- [MAA01] Michael McCool, Jason Ang, Anis Ahmad, "Homomorphic Factorization of BRDFs for
+  High-Performance Rendering", SIGGRAPH 2001.
+- [VHM*22] Dor Verbin, Peter Hedman, Ben Mildenhall, Todd Zickler, Jonathan Barron, Pratul Srinivasan,
+  "Ref-NeRF: Structured View-Dependent Appearance for Neural Radiance Fields", CVPR 2022.
+- Peter-Pike Sloan, "Efficient Spherical Harmonic Evaluation", JCGT 2(2), 2013 — the basis recurrence.

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"}