@woosh/meep-engine 3.37.0 → 3.39.0

package/src/shade/renderer/global_illumination/brick4/gpu/bake/sampling/chunk_direction_by_index_rand1.js

@@ -1,25 +1,26 @@
 import {
     chunk_build_orthonormal_matrix_n
 } from "../../../../../shader/chunk/geometry/normal/chunk_build_orthonormal_matrix_n.js";
+import { chunk_uniform_sample_cone } from "../../../../../shader/chunk/geometry/ray/chunk_uniform_sample_cone.js";
 import {
     chunk_sphere_fibonacci_point
 } from "../../../../../shader/chunk/geometry/sphere/chunk_sphere_fibonacci_point.js";
-import {
-    chunk_spherical_to_cartesian
-} from "../../../../../shader/chunk/geometry/sphere/chunk_spherical_to_cartesian.js";
-import { PI_DECLARATION } from "../../../../../shader/chunk/math/PI_DECLARATION.js";
 import { chunk_random } from "../../../../../shader/chunk/random/chunk_random.js";
 import { CodeChunk } from "../../../../../shader/compiler/CodeChunk.js";
 
+/**
+ * Fibonacci point `index` of `limit`, turned by a frame around a uniformly random axis.
+ *
+ * The axis must be uniform on the sphere: the resolve buckets samples by contiguous index, which is a
+ * latitude band in the frame, and only an isotropic axis makes every band isotropic in the world.
+ * @type {CodeChunk}
+ */
 export const chunk_direction_by_index_rand1 = CodeChunk.from(
     //language=WGSL
     `
 fn direction_by_index(index : u32, limit: u32) -> vec3<f32>{
-    let phi = random() * 2.0 * PI;
-    let cos_theta = random() * 2.0 - 1.0;
-    let theta = acos(cos_theta);
-    
-    let random_direction = spherical_to_cartesian(theta, phi);
+    // a cone of cos(theta_max) = -1 is the whole sphere
+    let random_direction = uniform_sample_cone(vec2(random(), random()), -1.0);
     
     let tbn = build_orthonormal_matrix_n(random_direction);
     
@@ -28,10 +29,9 @@ fn direction_by_index(index : u32, limit: u32) -> vec3<f32>{
     return normalize(tbn * fixed_direction);
 }
     `, [
-        chunk_spherical_to_cartesian,
-        PI_DECLARATION,
+        chunk_uniform_sample_cone,
         chunk_sphere_fibonacci_point,
         chunk_build_orthonormal_matrix_n,
         chunk_random,
     ]
-)
+)

package/src/shade/renderer/global_illumination/brick4/gpu/bake/sampling/chunk_direction_by_index_spherical.d.ts

@@ -1,3 +1,7 @@
+/**
+ * A uniformly random direction on the sphere; `index` and `limit` are ignored.
+ * @type {CodeChunk}
+ */
 export const chunk_direction_by_index_spherical: CodeChunk;
 import { CodeChunk } from "../../../../../shader/compiler/CodeChunk.js";
 //# sourceMappingURL=chunk_direction_by_index_spherical.d.ts.map

package/src/shade/renderer/global_illumination/brick4/gpu/bake/sampling/chunk_direction_by_index_spherical.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_direction_by_index_spherical.d.ts","sourceRoot":"","sources":["../../../../../../../../../src/shade/renderer/global_illumination/brick4/gpu/bake/sampling/chunk_direction_by_index_spherical.js"],"names":[],"mappings":"AAEA,2DAaC;0BAfyB,6CAA6C"}
+{"version":3,"file":"chunk_direction_by_index_spherical.d.ts","sourceRoot":"","sources":["../../../../../../../../../src/shade/renderer/global_illumination/brick4/gpu/bake/sampling/chunk_direction_by_index_spherical.js"],"names":[],"mappings":"AAIA;;;GAGG;AACH,iDAFU,SAAS,CAalB;0BAjByB,6CAA6C"}

package/src/shade/renderer/global_illumination/brick4/gpu/bake/sampling/chunk_direction_by_index_spherical.js

@@ -1,16 +1,20 @@
+import { chunk_uniform_sample_cone } from "../../../../../shader/chunk/geometry/ray/chunk_uniform_sample_cone.js";
+import { chunk_random } from "../../../../../shader/chunk/random/chunk_random.js";
 import { CodeChunk } from "../../../../../shader/compiler/CodeChunk.js";
 
+/**
+ * A uniformly random direction on the sphere; `index` and `limit` are ignored.
+ * @type {CodeChunk}
+ */
 export const chunk_direction_by_index_spherical = CodeChunk.from(
     //language=WGSL
     `
 fn direction_by_index(index : u32, limit: u32) -> vec3<f32>{
-    let phi = random() * 2.0 * PI;
-    let cos_theta = random() * 2.0 - 1.0;
-    let theta = acos(cos_theta);
-    
-    let ray_direction = spherical_to_cartesian(theta, phi);
-    
-    return ray_direction;
+    // a cone of cos(theta_max) = -1 is the whole sphere
+    return uniform_sample_cone(vec2(random(), random()), -1.0);
 }
-    `
-)
+    `, [
+        chunk_uniform_sample_cone,
+        chunk_random,
+    ]
+)

package/src/shade/renderer/global_illumination/brick4/gpu/bake/shader_brick4_bake_probes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_brick4_bake_probes.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/global_illumination/brick4/gpu/bake/shader_brick4_bake_probes.js"],"names":[],"mappings":"AA6GA,sDAIG;8BAnG2B,qCAAqC"}
+{"version":3,"file":"shader_brick4_bake_probes.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/global_illumination/brick4/gpu/bake/shader_brick4_bake_probes.js"],"names":[],"mappings":"AA+GA,sDAIG;8BApG2B,qCAAqC"}

package/src/shade/renderer/global_illumination/brick4/gpu/bake/shader_brick4_bake_probes.js

@@ -2,6 +2,7 @@ import { u32 } from "../../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
 import { WebGPUArray } from "../../../../shader/type/WebGPUArray.js";
 import { WebGPUStruct } from "../../../../shader/type/WebGPUStruct.js";
 import { INDIRECT_MATERIAL_ARRAY_TYPE } from "../../../../material/resident/INDIRECT_MATERIAL_ARRAY_TYPE.js";
+import { MEDIA_TABLE_STRUCT } from "../../../../medium/MEDIA_TABLE_STRUCT.js";
 import { chunk_render_trace_path } from "../../../../path_tracer/shader/chunk_render_trace_path.js";
 import { chunk_rgbe9995_encode } from "../../../../shader/chunk/color/rgbe9995/chunk_rgbe9995_encode.js";
 import {
@@ -23,6 +24,7 @@ resources.addGroup(RESOURCE_GROUP_RTX);
 
 resources.createGroup()
     .addUniform("materials", INDIRECT_MATERIAL_ARRAY_TYPE)
+    .addUniform("media", MEDIA_TABLE_STRUCT)
     .addTexture("textures", "unfilterable-float", "2d-array")
 
 resources.createGroup()

package/src/shade/renderer/global_illumination/lpv/bake/GPULightProbeVolumeRenderer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPULightProbeVolumeRenderer.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/lpv/bake/GPULightProbeVolumeRenderer.js"],"names":[],"mappings":"AAqBA;;;GAGG;AAEH;IA+GI;;;;OAIG;IACH,sBAHW,eAAe,SACf,eAAe,QAQzB;IAhCD;;;;OAIG;IACH,sBAHW,eAAe,SACf,eAAe,EAgBzB;IAtFD;;;OAGG;IACH,sCAEC;IAdD;;;OAGG;IACH,qCAEC;IAoCD;;;OAGG;IACH,6BAEC;IAYD;;;OAGG;IACH,0CASC;IAyDD;;;OAGG;IACH,gCAFW,MAAM,wEAUhB;IAED;;;;;OAKG;IACH,qBAJW,sBAAsB,gBACtB,MAAM,qBACN,MAAM,QA6ChB;IAED,aAgGC;IAED;;;OAGG;IACH,sCAFW,MAAM,QA8ChB;IAED;;;OAGG;IACH,eAFY,MAAM,CAUjB;IAED,gBACC;;CACJ;8BA1XY,OAAO,6BAA6B,EAAE,eAAe;8BACrD,OAAO,mCAAmC,EAAE,eAAe;kCAZtC,uCAAuC;uCAFlC,8CAA8C"}
+{"version":3,"file":"GPULightProbeVolumeRenderer.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/lpv/bake/GPULightProbeVolumeRenderer.js"],"names":[],"mappings":"AAqBA;;;GAGG;AAEH;IA+GI;;;;OAIG;IACH,sBAHW,eAAe,SACf,eAAe,QAQzB;IAhCD;;;;OAIG;IACH,sBAHW,eAAe,SACf,eAAe,EAgBzB;IAtFD;;;OAGG;IACH,sCAEC;IAdD;;;OAGG;IACH,qCAEC;IAoCD;;;OAGG;IACH,6BAEC;IAYD;;;OAGG;IACH,0CASC;IAyDD;;;OAGG;IACH,gCAFW,MAAM,wEAUhB;IAED;;;;;OAKG;IACH,qBAJW,sBAAsB,gBACtB,MAAM,qBACN,MAAM,QA6ChB;IAED,aAmGC;IAED;;;OAGG;IACH,sCAFW,MAAM,QA8ChB;IAED;;;OAGG;IACH,eAFY,MAAM,CAUjB;IAED,gBACC;;CACJ;8BA7XY,OAAO,6BAA6B,EAAE,eAAe;8BACrD,OAAO,mCAAmC,EAAE,eAAe;kCAZtC,uCAAuC;uCAFlC,8CAA8C"}

package/src/shade/renderer/global_illumination/lpv/bake/GPULightProbeVolumeRenderer.js

@@ -297,6 +297,7 @@ export class GPULightProbeVolumeRenderer {
                 lpv_metadata: lpv.buffer_metadata.buffer,
                 lpv_probes: lpv.buffer_probes,
                 materials: r_materials.buffer_materials,
+                media: r_materials.buffer_media,
                 textures: r_materials.textureView,
                 bake_settings: bake_uniform,
                 tEnvironment: this.#environment.obtainView(),
@@ -306,6 +307,8 @@ export class GPULightProbeVolumeRenderer {
                 blas_data: blas.buffer_data,
                 scene_database: scene.scene_database_buffer,
                 geometries: geometries.buffer_metadata,
+                meshlet_metadata: geometries.meshlets.buffer_metadata,
+                meshlet_data: geometries.meshlets.buffer_data,
                 //
                 light_data: scene.lights.buffer_data,
             }

package/src/shade/renderer/global_illumination/lpv/deprecated/probe_trace_compute_shader_code.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"probe_trace_compute_shader_code.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/lpv/deprecated/probe_trace_compute_shader_code.js"],"names":[],"mappings":"AA0BA,sDAIG;AAwKH,4DAIG;6BAxM0B,sCAAsC;8BAkBrC,kCAAkC"}
+{"version":3,"file":"probe_trace_compute_shader_code.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/lpv/deprecated/probe_trace_compute_shader_code.js"],"names":[],"mappings":"AAyBA,sDAIG;AAoKH,4DAIG;6BAnM0B,sCAAsC;8BAiBrC,kCAAkC"}

package/src/shade/renderer/global_illumination/lpv/deprecated/probe_trace_compute_shader_code.js

@@ -1,11 +1,10 @@
 import { u32, vec3f } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
 import { WebGPUArray } from "../../../shader/type/WebGPUArray.js";
 import { WebGPUStruct } from "../../../shader/type/WebGPUStruct.js";
-import { GEOMETRY_METADATA_STRUCT } from "../../../geometry/GEOMETRY_METADATA_STRUCT.js";
+import { sr_create_group_RTX } from "../../../geometry/sr_create_group_RTX.js";
 import { INDIRECT_MATERIAL_ARRAY_TYPE } from "../../../material/resident/INDIRECT_MATERIAL_ARRAY_TYPE.js";
+import { MEDIA_TABLE_STRUCT } from "../../../medium/MEDIA_TABLE_STRUCT.js";
 import { chunk_render_trace_path } from "../../../path_tracer/shader/chunk_render_trace_path.js";
-import { BVH2_NODE_STRUCT } from "../../../shader/chunk/bvh/BVH2_NODE_STRUCT.js";
-import { BVH_STRUCT } from "../../../shader/chunk/bvh/BVH_STRUCT.js";
 import {
     chunk_build_orthonormal_matrix_n
 } from "../../../shader/chunk/geometry/normal/chunk_build_orthonormal_matrix_n.js";
@@ -40,16 +39,12 @@ resources.createGroup({ label: 'LPV & scene' })
     .addUniform("lpv_metadata", LIGHT_PROBE_VOLUME_METADATA_STRUCT)
     .addStorageBuffer('lpv_probes', WebGPUArray.from(LIGHT_PROBE_STRUCT), true)
     .addUniform('materials', INDIRECT_MATERIAL_ARRAY_TYPE)
+    .addUniform('media', MEDIA_TABLE_STRUCT)
     .addTexture('textures', 'unfilterable-float', '2d-array', false)
     .addUniform('bake_settings', PROBE_BAKE_UNIFORMS_STRUCT)
     .addTexture('tEnvironment', 'unfilterable-float')
 
-resources.createGroup({ label: 'RTX' })
-    .addStorageBuffer('tlas', BVH_STRUCT)
-    .addStorageBuffer('blas_lookup', WebGPUArray.u32)
-    .addStorageBuffer('blas_data', WebGPUArray.from(BVH2_NODE_STRUCT))
-    .addStorageBuffer('scene_database', WebGPUArray.from(u32))
-    .addStorageBuffer('geometries', WebGPUArray.from(GEOMETRY_METADATA_STRUCT))
+sr_create_group_RTX(resources);
 
 resources.createGroup({ label: 'lights' })
     .addStorageBuffer('light_data', WebGPUArray.u32)

package/src/shade/renderer/light/LIGHT_DATABASE_SPEC.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"LIGHT_DATABASE_SPEC.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/light/LIGHT_DATABASE_SPEC.js"],"names":[],"mappings":"AAWA,wDAiBG;sCA1BmC,0CAA0C"}
+{"version":3,"file":"LIGHT_DATABASE_SPEC.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/light/LIGHT_DATABASE_SPEC.js"],"names":[],"mappings":"AAUA,wDAiBG;sCA1BmC,0CAA0C"}

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

@@ -1,12 +1,11 @@
 import { vec4f } from "../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
-import { WebGPUArray } from "../shader/type/WebGPUArray.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 { CSM_SHADOWMAP_STRUCT } from "../shadow/map/csm/CSM_SHADOWMAP_STRUCT.js";
 import { SHADOWMAP_VIEW_METADATA_STRUCT } from "../shadow/map/shader/SHADOWMAP_VIEW_METADATA_STRUCT.js";
 
 export const LIGHT_DATABASE_SPEC = GPUDatabaseDefinition.from({
@@ -16,16 +15,27 @@ 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`.
     shadow_point: vec4f,
     shadow_spot: SHADOWMAP_VIEW_METADATA_STRUCT,
-    shadow_directional: WebGPUArray.from(SHADOWMAP_VIEW_METADATA_STRUCT, SHADOWMAP_CSM_CASCADE_COUNT),
+    shadow_directional: CSM_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,
+});
+
+// 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/chunk_roughness_to_mip_ratio.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Input roughness is linear (blender calls it "UI roughness")
+ * @see https://projects.blender.org/blender/blender/src/commit/866ef5b468589587395b1ee7480ea75b4c0fbc26/source/blender/draw/engines/eevee_next/shaders/eevee_lightprobe_sphere_mapping_lib.glsl#L102
+ * @type {CodeChunk}
+ */
+export const chunk_roughness_to_mip_ratio: CodeChunk;
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_roughness_to_mip_ratio.d.ts.map

package/src/shade/renderer/light/environment/chunk_roughness_to_mip_ratio.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_roughness_to_mip_ratio.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/light/environment/chunk_roughness_to_mip_ratio.js"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,2CAFU,SAAS,CAiBjB;0BAvBwB,oCAAoC"}

package/src/shade/renderer/light/environment/chunk_sphere_probe_roughness_to_lod.d.ts

@@ -1,9 +1,3 @@
-/**
- * Input roughness is linear (blender calls it "UI roughness")
- * @see https://projects.blender.org/blender/blender/src/commit/866ef5b468589587395b1ee7480ea75b4c0fbc26/source/blender/draw/engines/eevee_next/shaders/eevee_lightprobe_sphere_mapping_lib.glsl#L102
- * @type {CodeChunk}
- */
-export const chunk_roughness_to_mip_ratio: CodeChunk;
 /**
  * Input roughness is linear (blender calls it "UI roughness")
  * @see https://projects.blender.org/blender/blender/src/commit/866ef5b468589587395b1ee7480ea75b4c0fbc26/source/blender/draw/engines/eevee_next/shaders/eevee_lightprobe_sphere_mapping_lib.glsl#L102

package/src/shade/renderer/light/environment/chunk_sphere_probe_roughness_to_lod.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_sphere_probe_roughness_to_lod.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/light/environment/chunk_sphere_probe_roughness_to_lod.js"],"names":[],"mappings":"AAIA;;;;GAIG;AACH,2CAFU,SAAS,CAkBjB;AAEF;;;;GAIG;AACH,kDAFU,SAAS,CAajB;0BA1CwB,oCAAoC"}
+{"version":3,"file":"chunk_sphere_probe_roughness_to_lod.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/light/environment/chunk_sphere_probe_roughness_to_lod.js"],"names":[],"mappings":"AAIA;;;;GAIG;AACH,kDAFU,SAAS,CAajB;0BApBwB,oCAAoC"}

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/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.