@woosh/meep-engine 3.52.0 → 3.54.0

package/src/shade/renderer/hiz/shader_hzb_reduce_mip0_clip.js

@@ -1,112 +1,111 @@
-import { vec2u, vec4u } from "../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
-import { WebGPUStruct } from "../shader/type/WebGPUStruct.js";
-import { CodeChunk } from "../shader/compiler/CodeChunk.js";
-import { ImageShader } from "../shader/ImageShader.js";
-import { ShaderResourceSetDescriptor } from "../shader/resource/ShaderResourceSetDescriptor.js";
-import { ShaderDescriptor } from "../shader/ShaderDescriptor.js";
-import { HZB_TEXTURE_FORMAT } from "./HZB_TEXTURE_FORMAT.js";
-
-/**
- * Per-pass, 24 bytes, read-only.
- *
- * `clip_region` and `output_resolution` were two uniforms, so two buffers per pass. WGSL allows one
- * immediate per entry point, so carrying them as immediate data means carrying them together.
- *
- * @type {WebGPUStruct}
- */
-const HZB_CLIP_SETTINGS = WebGPUStruct.from({
-    // x, y, width, height
-    clip_region: vec4u,
-    output_resolution: vec2u,
-}, 'HzbClipSettings');
-
-const resources = new ShaderResourceSetDescriptor();
-
-resources.setImmediate("settings", HZB_CLIP_SETTINGS);
-
-resources.createGroup()
-    .addTexture("tInput", "unfilterable-float")
-;
-
-const body = CodeChunk.from(
-    //language=WGSL
-    `
-@fragment
-fn main(
-    @builtin(position) coord: vec4<f32>,
-    @location(0) uv: vec2<f32>,
-) -> @location(0) vec2<f32>{
-    
-    // 1. Calculate the UV bounds of the current *output* pixel.
-    //    We use the output resolution to determine how wide one pixel is in UV space.
-    let output_pixel_size2 = 0.5 / vec2<f32>(settings.output_resolution);
-    let uv_min = uv - output_pixel_size2;
-    let uv_max = uv + output_pixel_size2; 
-
-    // minor epsilon to avoid float rounding errors
-    const EPSILON = 1e-6;
-    
-    // Nudge the bounds slightly inward to absorb floating-point drift
-    let safe_uv_min = uv_min + EPSILON;
-    let safe_uv_max = uv_max - EPSILON;
-    
-    // 2. Convert UV bounds to Source Texel coordinates (float).
-    //    We map the 0..1 UVs to the size of the source clip region.
-    let source_size = vec2<f32>(settings.clip_region.zw);
-    let texel_min_f = safe_uv_min * source_size;
-    let texel_max_f = safe_uv_max * source_size;
-
-    // 3. Convert to Integer Loop Bounds.
-    //    Floor the min to find the first pixel.
-    //    Ceil the max to find the exclusive upper bound.
-    //    Example (5px -> 2px):
-    //      Output Px 0 covers UV 0.0-0.5 -> Source 0.0 to 2.5
-    //      Floor(0.0) = 0. Ceil(2.5) = 3. Loop 0, 1, 2. (Pixel 2 is partially covered)
-    //      Output Px 1 covers UV 0.5-1.0 -> Source 2.5 to 5.0
-    //      Floor(2.5) = 2. Ceil(5.0) = 5. Loop 2, 3, 4. (Pixel 2 is partially covered again)
-    let bound_min = vec2<i32>(floor(texel_min_f));
-    let bound_max = vec2<i32>(ceil(texel_max_f));
-
-    // 4. Clamp bounds to the clip region size to be safe.
-    let limit = vec2<i32>(settings.clip_region.zw);
-    
-    let start = max(bound_min, vec2<i32>(0)) + vec2<i32>(settings.clip_region.xy);
-    let end   = min(bound_max, limit) + vec2<i32>(settings.clip_region.xy);
-
-    var output = vec2<f32>(1.0, 0.0); // Initialize min/max
-
-    // 5. Loop. Note strict usage of < end (exclusive) and i32 types.
-    for (var y = start.y; y < end.y; y++) {
-        for (var x = start.x; x < end.x; x++) {
-            
-            // Add the clip region offset (atlas support)
-            let load_coord = vec2<i32>(x, y);
-
-            let v = textureLoad(tInput, load_coord, 0).r;
-            
-            output.x = min(output.x, v);
-            output.y = max(output.y, v);
-        }
-    }
-    
-    return output;
-}
-    `, [
-    ]
-)
-
-/**
- * Same as standard first mip reduction, but with a clipping region.
- * Primarily used for shadow maps where shadows are atlased into a single texture
- * @type {ImageShader}
- */
-export const shader_hzb_reduce_mip0_clip = ImageShader.from({
-    descriptor: ShaderDescriptor.from({
-        label: 'HZB / reduce mip0 with clip',
-        resources,
-        body,
-    }),
-    targets: [
-        { format: HZB_TEXTURE_FORMAT }
-    ]
-});
+import { vec2u, vec4u } from "../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../shader/type/WebGPUStruct.js";
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../shader/resource/ShaderResourceSetDescriptor.js";
+import { HZB_TEXTURE_FORMAT } from "./HZB_TEXTURE_FORMAT.js";
+
+/**
+ * Per-pass, 24 bytes, read-only.
+ *
+ * `clip_region` and `output_resolution` were two uniforms, so two buffers per pass. WGSL allows one
+ * immediate per entry point, so carrying them as immediate data means carrying them together.
+ *
+ * @type {WebGPUStruct}
+ */
+const HZB_CLIP_SETTINGS = WebGPUStruct.from({
+    // x, y, width, height
+    clip_region: vec4u,
+    output_resolution: vec2u,
+}, 'HzbClipSettings');
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate("settings", HZB_CLIP_SETTINGS);
+
+resources.createGroup()
+    .addTexture("tInput", "unfilterable-float")
+    .addStorageTexture("tOutput", HZB_TEXTURE_FORMAT, "2d", "write-only")
+;
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+@compute @workgroup_size(8, 8, 1)
+fn main(
+    @builtin(global_invocation_id) global_id: vec3<u32>,
+) {
+    if (any(global_id.xy >= settings.output_resolution)) {
+        return;
+    }
+
+    // 1. Calculate the UV bounds of the current *output* pixel.
+    //    We use the output resolution to determine how wide one pixel is in UV space.
+    let output_resolution_f = vec2<f32>(settings.output_resolution);
+    let uv = (vec2<f32>(global_id.xy) + 0.5) / output_resolution_f;
+    let output_pixel_size2 = 0.5 / output_resolution_f;
+    let uv_min = uv - output_pixel_size2;
+    let uv_max = uv + output_pixel_size2; 
+
+    // minor epsilon to avoid float rounding errors
+    const EPSILON = 1e-6;
+    
+    // Nudge the bounds slightly inward to absorb floating-point drift
+    let safe_uv_min = uv_min + EPSILON;
+    let safe_uv_max = uv_max - EPSILON;
+    
+    // 2. Convert UV bounds to Source Texel coordinates (float).
+    //    We map the 0..1 UVs to the size of the source clip region.
+    let source_size = vec2<f32>(settings.clip_region.zw);
+    let texel_min_f = safe_uv_min * source_size;
+    let texel_max_f = safe_uv_max * source_size;
+
+    // 3. Convert to Integer Loop Bounds.
+    //    Floor the min to find the first pixel.
+    //    Ceil the max to find the exclusive upper bound.
+    //    Example (5px -> 2px):
+    //      Output Px 0 covers UV 0.0-0.5 -> Source 0.0 to 2.5
+    //      Floor(0.0) = 0. Ceil(2.5) = 3. Loop 0, 1, 2. (Pixel 2 is partially covered)
+    //      Output Px 1 covers UV 0.5-1.0 -> Source 2.5 to 5.0
+    //      Floor(2.5) = 2. Ceil(5.0) = 5. Loop 2, 3, 4. (Pixel 2 is partially covered again)
+    let bound_min = vec2<i32>(floor(texel_min_f));
+    let bound_max = vec2<i32>(ceil(texel_max_f));
+
+    // 4. Clamp bounds to the clip region size to be safe.
+    let limit = vec2<i32>(settings.clip_region.zw);
+    
+    let start = max(bound_min, vec2<i32>(0)) + vec2<i32>(settings.clip_region.xy);
+    let end   = min(bound_max, limit) + vec2<i32>(settings.clip_region.xy);
+
+    var output = vec2<f32>(1.0, 0.0); // Initialize min/max
+
+    // 5. Loop. Note strict usage of < end (exclusive) and i32 types.
+    for (var y = start.y; y < end.y; y++) {
+        for (var x = start.x; x < end.x; x++) {
+            
+            // Add the clip region offset (atlas support)
+            let load_coord = vec2<i32>(x, y);
+
+            let v = textureLoad(tInput, load_coord, 0).r;
+            
+            output.x = min(output.x, v);
+            output.y = max(output.y, v);
+        }
+    }
+    
+    textureStore(tOutput, vec2<i32>(global_id.xy), vec4<f32>(output, 0.0, 0.0));
+}
+    `, [
+    ]
+)
+
+/**
+ * Same as standard first mip reduction, but with a clipping region.
+ * Primarily used for shadow maps where shadows are atlased into a single texture
+ * @type {ComputeShader}
+ */
+export const shader_hzb_reduce_mip0_clip = ComputeShader.from({
+    label: 'HZB / reduce mip0 with clip',
+    resources,
+    body,
+});

package/src/shade/renderer/hiz/shader_hzb_spd.d.ts

@@ -0,0 +1,5 @@
+export const shader_hzb_spd_2: ComputeShader;
+export const shader_hzb_spd_3: ComputeShader;
+export const shader_hzb_spd_4: ComputeShader;
+import { ComputeShader } from "../shader/ComputeShader.js";
+//# sourceMappingURL=shader_hzb_spd.d.ts.map

package/src/shade/renderer/hiz/shader_hzb_spd.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_hzb_spd.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/hiz/shader_hzb_spd.js"],"names":[],"mappings":"AA6JA,6CAAyD;AACzD,6CAAyD;AACzD,6CAAyD;8BA3J3B,4BAA4B"}

package/src/shade/renderer/hiz/shader_hzb_spd.js

@@ -0,0 +1,160 @@
+import { assert } from "../../../core/assert.js";
+import { WebGPUExtensionType } from "../../descriptor/WebGPUExtensionType.js";
+import { chunk_remap_for_wave_reduction } from "../shader/chunk/subgroup/chunk_remap_for_wave_reduction.js";
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../shader/resource/ShaderResourceSetDescriptor.js";
+import { HZB_TEXTURE_FORMAT } from "./HZB_TEXTURE_FORMAT.js";
+
+/**
+ * Builds an SPD compute shader reducing `tInput` (`base_mip`) into `mip_count` consecutive mips
+ * (`tOut1 .. tOut{mip_count}`, where `mip_count` is 2, 3, or 4).
+ *
+ * Each 256-thread workgroup covers up to 32x32 texels of `tInput` (16x16 at `tOut1`):
+ * - `tOut1` (16x16): 256 threads in four 8x8 Morton-ordered sub-tiles each load a 2x2 quad from `tInput`.
+ * - `tOut2` (8x8): reduced in registers across 4-lane quads via `quadSwapX` / `quadSwapY` (no barrier).
+ * - `tOut3` (4x4): after a single `workgroupBarrier()` over a 64-element LDS tile, 16 threads reduce 2x2 quads.
+ * - `tOut4` (2x2): reduced in registers across the 4-lane quads of those 16 threads via `quadSwapX` / `quadSwapY` (no second barrier).
+ *
+ * @param {number} mip_count 2, 3, or 4
+ * @returns {ComputeShader}
+ */
+function create_shader_hzb_spd(mip_count) {
+    assert.isInteger(mip_count, 'mip_count');
+    assert.greaterThanOrEqual(mip_count, 2, 'mip_count');
+    assert.lessThanOrEqual(mip_count, 4, 'mip_count');
+
+    const resources = new ShaderResourceSetDescriptor();
+    const group = resources.createGroup()
+        .addTexture("tInput", "unfilterable-float");
+
+    for (let m = 1; m <= mip_count; m++) {
+        group.addStorageTexture(`tOut${m}`, HZB_TEXTURE_FORMAT, "2d", "write-only");
+    }
+
+    const needs_lds = mip_count >= 3;
+
+    const lds_decl = needs_lds
+        ? `var<workgroup> hzb_spd_lds: array<vec2<f32>, 64>;`
+        : ``;
+
+    const lds_store_mip2 = needs_lds
+        ? `hzb_spd_lds[mip2_local.y * 8u + mip2_local.x] = v2;`
+        : ``;
+
+    const mip3_and_4_code = !needs_lds ? `` : `
+    workgroupBarrier();
+
+    // Map threads 0..15 as four 2x2 quads covering the 4x4 Mip+3 tile so quadSwapX/Y works for Mip+4
+    let mip3_local = vec2<u32>(
+        (local_idx & 1u) | ((local_idx >> 1u) & 2u),
+        ((local_idx >> 1u) & 1u) | ((local_idx >> 2u) & 2u),
+    );
+
+    var v3 = vec2<f32>(1.0, 0.0);
+
+    if (local_idx < 16u) {
+        let lds_base = mip3_local * 2u;
+        let l00 = hzb_spd_lds[(lds_base.y + 0u) * 8u + (lds_base.x + 0u)];
+        let l10 = hzb_spd_lds[(lds_base.y + 0u) * 8u + (lds_base.x + 1u)];
+        let l01 = hzb_spd_lds[(lds_base.y + 1u) * 8u + (lds_base.x + 0u)];
+        let l11 = hzb_spd_lds[(lds_base.y + 1u) * 8u + (lds_base.x + 1u)];
+
+        v3 = vec2<f32>(
+            min(min(l00.x, l10.x), min(l01.x, l11.x)),
+            max(max(l00.y, l10.y), max(l01.y, l11.y)),
+        );
+
+        let mip3_coord = workgroup_id.xy * 4u + mip3_local;
+        let out3_dim = textureDimensions(tOut3);
+        if (all(mip3_coord < out3_dim)) {
+            textureStore(tOut3, vec2<i32>(mip3_coord), vec4<f32>(v3, 0.0, 0.0));
+        }
+    }
+${mip_count === 4 ? `
+    // Mip +4: quad reduction in uniform control flow across the 4-lane quads of threads 0..15
+    let v4 = hzb_spd_quad_reduce(v3);
+
+    if (local_idx < 16u && (local_idx & 3u) == 0u) {
+        let mip4_local = mip3_local >> vec2<u32>(1u);
+        let mip4_coord = workgroup_id.xy * 2u + mip4_local;
+        let out4_dim = textureDimensions(tOut4);
+        if (all(mip4_coord < out4_dim)) {
+            textureStore(tOut4, vec2<i32>(mip4_coord), vec4<f32>(v4, 0.0, 0.0));
+        }
+    }
+` : ``}`;
+
+    const body = CodeChunk.from(
+        //language=WGSL
+        `
+${lds_decl}
+
+fn hzb_spd_quad_reduce(v: vec2<f32>) -> vec2<f32> {
+    let h = vec2<f32>(min(v.x, quadSwapX(v.x)), max(v.y, quadSwapX(v.y)));
+    return vec2<f32>(min(h.x, quadSwapY(h.x)), max(h.y, quadSwapY(h.y)));
+}
+
+@compute @workgroup_size(256, 1, 1)
+fn main(
+    @builtin(workgroup_id) workgroup_id: vec3<u32>,
+    @builtin(local_invocation_index) local_idx: u32,
+) {
+    let src_dim = textureDimensions(tInput);
+    let src_max = vec2<i32>(src_dim) - vec2<i32>(1);
+
+    // 4 sub-tiles of 8x8 (64 threads each), Morton-mapped within each sub-tile
+    let sub_tile = local_idx >> 6u;
+    let sub_offset = vec2<u32>((sub_tile & 1u) * 8u, (sub_tile >> 1u) * 8u);
+    let sub_xy = remap_for_wave_reduction(local_idx & 63u);
+
+    let mip1_local = sub_offset + sub_xy;
+    let mip1_coord = workgroup_id.xy * 16u + mip1_local;
+
+    // Mip +1: 2x2 fetch from tInput
+    let src_base = vec2<i32>(mip1_coord * 2u);
+    let s00 = textureLoad(tInput, min(src_base + vec2<i32>(0, 0), src_max), 0).xy;
+    let s10 = textureLoad(tInput, min(src_base + vec2<i32>(1, 0), src_max), 0).xy;
+    let s01 = textureLoad(tInput, min(src_base + vec2<i32>(0, 1), src_max), 0).xy;
+    let s11 = textureLoad(tInput, min(src_base + vec2<i32>(1, 1), src_max), 0).xy;
+
+    let v1 = vec2<f32>(
+        min(min(s00.x, s10.x), min(s01.x, s11.x)),
+        max(max(s00.y, s10.y), max(s01.y, s11.y)),
+    );
+
+    let out1_dim = textureDimensions(tOut1);
+    if (all(mip1_coord < out1_dim)) {
+        textureStore(tOut1, vec2<i32>(mip1_coord), vec4<f32>(v1, 0.0, 0.0));
+    }
+
+    // Mip +2: 2x2 quad reduction in registers (0 barriers)
+    let v2 = hzb_spd_quad_reduce(v1);
+
+    if ((local_idx & 3u) == 0u) {
+        let mip2_local = mip1_local >> vec2<u32>(1u);
+        let mip2_coord = workgroup_id.xy * 8u + mip2_local;
+        let out2_dim = textureDimensions(tOut2);
+        if (all(mip2_coord < out2_dim)) {
+            textureStore(tOut2, vec2<i32>(mip2_coord), vec4<f32>(v2, 0.0, 0.0));
+        }
+        ${lds_store_mip2}
+    }
+    ${mip3_and_4_code}
+}
+`,
+        [chunk_remap_for_wave_reduction]
+    );
+
+    body.addExtension(WebGPUExtensionType.Subgroups);
+
+    return ComputeShader.from({
+        label: `HZB / SPD ${mip_count}`,
+        resources,
+        body,
+    });
+}
+
+export const shader_hzb_spd_2 = create_shader_hzb_spd(2);
+export const shader_hzb_spd_3 = create_shader_hzb_spd(3);
+export const shader_hzb_spd_4 = create_shader_hzb_spd(4);

package/src/shade/renderer/light/GPULightCollection.d.ts

@@ -57,6 +57,14 @@ export class GPULightCollection {
      * @returns {GPUBuffer}
      */
     get environment_sh(): GPUBuffer;
+    /**
+     * Cached far-field L1 irradiance SH (`METRO_L1_IRRADIANCE_STRUCT`), combining `environment_sh`
+     * (`INDIRECT_LIGHT_INTENSITY`) and directional lights for out-of-cascade particle/volumetric
+     * fallback.
+     *
+     * @returns {GPUBuffer}
+     */
+    get far_field_irradiance_sh(): GPUBuffer;
     get gpu_memory_usage(): any;
     /**
      *

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

@@ -1 +1 @@
-{"version":3,"file":"GPULightCollection.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/light/GPULightCollection.js"],"names":[],"mappings":"AAkDA;IAEI;;;;;OAKG;IACH,iCAFW,eAAe,QAMzB;IAoJD;;;;;;OAMG;IACH,sBALW,eAAe,aACf,eAAe,EAqCzB;IApLD;;;OAGG;IACH,6DAEC;IAeD;;OAEG;IACH,4BAEC;IAED;;;;;;OAMG;IACH,6BAEC;IAED;;;;;;;OAOG;IACH,qFAEC;IAWD;;OAEG;IACH,+CAEC;IAgDD;;;OAGG;IACH,qCAEC;IAED;;;;;;OAMG;IACH,gCAEC;IAGD,4BAKC;IAyKD;;;OAGG;IACH,YAFW,eAAe,QA8BzB;IAED;;;;;;;;;OASG;IACH,gBAFW,OAAO,+BAA+B,EAAE,YAAY,QAkC9D;IAED;;;;;;OAMG;IACH,uBAHW,sBAAsB,mCAyBhC;IAwED,gBASC;;CACJ;8BA1hBY,OAAO,0CAA0C,EAAE,eAAe;8BAClE,OAAO,uBAAuB,EAAE,eAAe;8BAC/C,OAAO,6BAA6B,EAAE,eAAe;8BACrD,OAAO,sBAAsB,EAAE,eAAe;4BA3B/B,gCAAgC;yCACnB,2CAA2C;kCAClD,iCAAiC;uCAH5B,wCAAwC"}
+{"version":3,"file":"GPULightCollection.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/light/GPULightCollection.js"],"names":[],"mappings":"AAsDA;IAEI;;;;;OAKG;IACH,iCAFW,eAAe,QAOzB;IA6KD;;;;;;OAMG;IACH,sBALW,eAAe,aACf,eAAe,EA2CzB;IAnND;;;OAGG;IACH,6DAEC;IAeD;;OAEG;IACH,4BAEC;IAED;;;;;;OAMG;IACH,6BAEC;IAED;;;;;;;OAOG;IACH,qFAEC;IAWD;;OAEG;IACH,+CAEC;IA6DD;;;OAGG;IACH,qCAEC;IAED;;;;;;OAMG;IACH,gCAEC;IAED;;;;;;OAMG;IACH,yCAEC;IAGD,4BAMC;IAmMD;;;OAGG;IACH,YAFW,eAAe,QAoCzB;IAED;;;;;;;;;OASG;IACH,gBAFW,OAAO,+BAA+B,EAAE,YAAY,QAkC9D;IAED;;;;;;OAMG;IACH,uBAHW,sBAAsB,mCA6BhC;IAwED,gBAUC;;CACJ;8BAzlBY,OAAO,0CAA0C,EAAE,eAAe;8BAClE,OAAO,uBAAuB,EAAE,eAAe;8BAC/C,OAAO,6BAA6B,EAAE,eAAe;8BACrD,OAAO,sBAAsB,EAAE,eAAe;4BA/B/B,gCAAgC;yCACnB,2CAA2C;kCAClD,iCAAiC;uCAH5B,wCAAwC"}

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

@@ -14,6 +14,10 @@ import {
 import { SPHERE_PROBE_MIPMAP_LEVELS } from "./environment/DEFINES.js";
 import { octahedral_skirt_matches } from "./environment/octahedral_skirt_matches.js";
 import { ENVIRONMENT_SH_TYPE, shader_project_environment_sh } from "./environment/shader_project_environment_sh.js";
+import { shader_project_far_field_irradiance_sh } from "./environment/shader_project_far_field_irradiance_sh.js";
+import {
+    METRO_L1_IRRADIANCE_STRUCT
+} from "../shader/chunk/spherical_harmonics/l1i/chunk_convert_to_irradiance_sh.js";
 import { LIGHT_DATABASE_SPEC } from "./LIGHT_DATABASE_SPEC.js";
 import { light_record_directional } from "./model/io/light_record_directional.js";
 import { light_record_point } from "./model/io/light_record_point.js";
@@ -59,6 +63,7 @@ export class GPULightCollection {
     static enquirePipelines(enquiry) {
         enquire_filter_environment_map_pipelines(enquiry);
         enquiry.compute.push(shader_project_environment_sh.pipeline);
+        enquiry.compute.push(shader_project_far_field_irradiance_sh.pipeline);
         enquiry.compute.push(shader_refresh_light_poses.pipeline);
     }
 
@@ -180,6 +185,19 @@ export class GPULightCollection {
      */
     #environment_sh;
 
+    /**
+     * Cached far-field L1 irradiance SH (`METRO_L1_IRRADIANCE_STRUCT`): `environment_sh` scaled by
+     * `INDIRECT_LIGHT_INTENSITY` plus all directional lights, updated only when the environment or
+     * directional lights change.
+     * @type {GPUBuffer}
+     */
+    #far_field_irradiance_sh;
+
+    /**
+     * @type {boolean}
+     */
+    #far_field_sh_dirty = true;
+
 
     /**
      *
@@ -200,10 +218,22 @@ export class GPULightCollection {
         return this.#environment_sh;
     }
 
+    /**
+     * Cached far-field L1 irradiance SH (`METRO_L1_IRRADIANCE_STRUCT`), combining `environment_sh`
+     * (`INDIRECT_LIGHT_INTENSITY`) and directional lights for out-of-cascade particle/volumetric
+     * fallback.
+     *
+     * @returns {GPUBuffer}
+     */
+    get far_field_irradiance_sh() {
+        return this.#far_field_irradiance_sh;
+    }
+
 
     get gpu_memory_usage() {
         return this.#environment.gpu_memory_usage
             + this.#environment_sh.size
+            + this.#far_field_irradiance_sh.size
             + this.#database.gpu_memory_usage
             ;
     }
@@ -241,6 +271,12 @@ export class GPULightCollection {
             usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
         });
 
+        this.#far_field_irradiance_sh = device.createBuffer({
+            label: "far-field irradiance SH",
+            size: METRO_L1_IRRADIANCE_STRUCT.size,
+            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC,
+        });
+
         this.#database = new GPUDatabase({
             device,
             label: 'Light Collection / Database',
@@ -285,6 +321,7 @@ export class GPULightCollection {
 
             // what a black environment projects to; nothing to run the projection over
             this.#device.queue.writeBuffer(this.#environment_sh, 0, new Float32Array(this.#environment_sh.size / 4));
+            this.#far_field_sh_dirty = true;
 
             return;
         }
@@ -372,9 +409,28 @@ export class GPULightCollection {
             },
         });
 
+        this.#far_field_sh_dirty = true;
+
         cmd.finish();
     }
 
+    /**
+     * @param {ShadeGPUCommandContext} cmd
+     */
+    #project_far_field_sh(cmd) {
+        shader_project_far_field_irradiance_sh.dispatch({
+            encoder: cmd,
+            group_count_x: 1,
+            bindings: {
+                environment_sh: this.#environment_sh,
+                light_data: this.#database.buffer,
+                far_field_sh: this.#far_field_irradiance_sh,
+            },
+        });
+
+        this.#far_field_sh_dirty = false;
+    }
+
     /**
      *
      * @param {GraphicsContext} ctx
@@ -399,12 +455,18 @@ export class GPULightCollection {
         }
 
         if (this.#committed_version === this.#source.version) {
+            if (this.#far_field_sh_dirty) {
+                const cmd = ShadeGPUCommandContext.create(ctx, 'GPULightCollection/far_field_sh');
+                this.#project_far_field_sh(cmd);
+                cmd.finish();
+            }
             return;
         }
 
         const cmd = ShadeGPUCommandContext.create(ctx, 'GPULightCollection/build');
 
         this.#build(cmd);
+        this.#project_far_field_sh(cmd);
 
         cmd.finish();
     }
@@ -482,6 +544,10 @@ export class GPULightCollection {
                 light_database: database.buffer,
             },
         });
+
+        if (this.#prev_directional_count > 0) {
+            this.#project_far_field_sh(cmd_ctx);
+        }
     }
 
     /**
@@ -563,5 +629,6 @@ export class GPULightCollection {
         this.#database.destroy();
         this.#environment.destroy();
         this.#environment_sh.destroy();
+        this.#far_field_irradiance_sh.destroy();
     }
 }

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

@@ -0,0 +1,7 @@
+/**
+ * The cached far-field irradiance SH (environment + directional lights) held on `GPULightCollection`.
+ * @type {ShaderResourceDescriptor}
+ */
+export const FAR_FIELD_IRRADIANCE_SH_RESOURCE: ShaderResourceDescriptor;
+import { ShaderResourceDescriptor } from "../../shader/resource/ShaderResourceDescriptor.js";
+//# sourceMappingURL=FAR_FIELD_IRRADIANCE_SH_RESOURCE.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"FAR_FIELD_IRRADIANCE_SH_RESOURCE.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/light/environment/FAR_FIELD_IRRADIANCE_SH_RESOURCE.js"],"names":[],"mappings":"AAKA;;;GAGG;AACH,+CAFU,wBAAwB,CAKhC;yCATuC,mDAAmD"}

package/src/shade/renderer/light/environment/FAR_FIELD_IRRADIANCE_SH_RESOURCE.js

@@ -0,0 +1,13 @@
+import {
+    METRO_L1_IRRADIANCE_STRUCT
+} from "../../shader/chunk/spherical_harmonics/l1i/chunk_convert_to_irradiance_sh.js";
+import { ShaderResourceDescriptor } from "../../shader/resource/ShaderResourceDescriptor.js";
+
+/**
+ * The cached far-field irradiance SH (environment + directional lights) held on `GPULightCollection`.
+ * @type {ShaderResourceDescriptor}
+ */
+export const FAR_FIELD_IRRADIANCE_SH_RESOURCE = ShaderResourceDescriptor.uniform(
+    "far_field_irradiance_sh",
+    METRO_L1_IRRADIANCE_STRUCT
+);

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

@@ -0,0 +1,10 @@
+/**
+ * Projects the scene's far-field irradiance (the environment SH scaled by `INDIRECT_LIGHT_INTENSITY`
+ * plus unshadowed directional lights) into a single cached {@link METRO_L1_IRRADIANCE_STRUCT} buffer on
+ * `GPULightCollection`. Updated only when the environment or directional lights change.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_project_far_field_irradiance_sh: ComputeShader;
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_project_far_field_irradiance_sh.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shader_project_far_field_irradiance_sh.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/light/environment/shader_project_far_field_irradiance_sh.js"],"names":[],"mappings":"AA4DA;;;;;;GAMG;AACH,qDAFU,aAAa,CAMpB;8BA5D2B,+BAA+B"}