@woosh/meep-engine 3.60.5 → 3.60.7

package/src/shade/renderer/global_illumination/brick4/gpu/encoding/v1/chunk_brick4_sh3_color_decode_from_storage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_brick4_sh3_color_decode_from_storage.d.ts","sourceRoot":"","sources":["../../../../../../../../../src/shade/renderer/global_illumination/brick4/gpu/encoding/v1/chunk_brick4_sh3_color_decode_from_storage.js"],"names":[],"mappings":"AAuBA,mEAuCE;0BA9DwB,6CAA6C"}
+{"version":3,"file":"chunk_brick4_sh3_color_decode_from_storage.d.ts","sourceRoot":"","sources":["../../../../../../../../../src/shade/renderer/global_illumination/brick4/gpu/encoding/v1/chunk_brick4_sh3_color_decode_from_storage.js"],"names":[],"mappings":"AAwBA,mEAiBE;0BAzCwB,6CAA6C"}

package/src/shade/renderer/global_illumination/brick4/gpu/encoding/v1/chunk_brick4_sh3_color_decode_from_storage.js

@@ -1,4 +1,5 @@
 import { CodeChunk } from "../../../../../shader/compiler/CodeChunk.js";
+import { chunk_brick4_sh3_color_decode } from "./chunk_brick4_sh3_color_decode.js";
 
 /*
  * The v1 brick4 SH3 probe encoding: nine RGB coefficients as fourteen f16 pairs.
@@ -28,36 +29,14 @@ fn brick4_sh3_color_decode_from_storage_v1(
     storage_buf: ptr<storage, array<u32>>, 
     offset: u32
 ) -> array<vec3<f32>, 9> {
-    var sh: array<vec3<f32>, 9>;
-
-    // Pre-fetch and unpack all 14 u32 slots into vec2<f16> pairs
-    let v0  = unpack2x16float((*storage_buf)[offset + 0u]);
-    let v1  = unpack2x16float((*storage_buf)[offset + 1u]);
-    let v2  = unpack2x16float((*storage_buf)[offset + 2u]);
-    let v3  = unpack2x16float((*storage_buf)[offset + 3u]);
-    let v4  = unpack2x16float((*storage_buf)[offset + 4u]);
-    let v5  = unpack2x16float((*storage_buf)[offset + 5u]);
-    let v6  = unpack2x16float((*storage_buf)[offset + 6u]);
-    let v7  = unpack2x16float((*storage_buf)[offset + 7u]);
-    let v8  = unpack2x16float((*storage_buf)[offset + 8u]);
-    let v9  = unpack2x16float((*storage_buf)[offset + 9u]);
-    let v10 = unpack2x16float((*storage_buf)[offset + 10u]);
-    let v11 = unpack2x16float((*storage_buf)[offset + 11u]);
-    let v12 = unpack2x16float((*storage_buf)[offset + 12u]);
-    let v13 = unpack2x16float((*storage_buf)[offset + 13u]);
-
-    // Reconstruct the vec3s by bridging the u32 boundaries
-    sh[0] = vec3<f32>(v0.x, v0.y, v1.x);
-    sh[1] = vec3<f32>(v1.y, v2.x, v2.y);
-    sh[2] = vec3<f32>(v3.x, v3.y, v4.x);
-    sh[3] = vec3<f32>(v4.y, v5.x, v5.y);
-    sh[4] = vec3<f32>(v6.x, v6.y, v7.x);
-    sh[5] = vec3<f32>(v7.y, v8.x, v8.y);
-    sh[6] = vec3<f32>(v9.x, v9.y, v10.x);
-    sh[7] = vec3<f32>(v10.y, v11.x, v11.y);
-    sh[8] = vec3<f32>(v12.x, v12.y, v13.x);
-
-    return sh;
+    var packed: array<u32, 14>;
+    for (var i = 0u; i < 14u; i++) {
+        packed[i] = (*storage_buf)[offset + i];
+    }
+    return brick4_sh3_color_decode_v1(packed);
 }
-    `
+    `,
+    [
+        chunk_brick4_sh3_color_decode,
+    ]
 );

package/src/shade/renderer/global_illumination/brick4/gpu/encoding/v1/chunk_brick4_sh3_color_encode_to_storage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_brick4_sh3_color_encode_to_storage.d.ts","sourceRoot":"","sources":["../../../../../../../../../src/shade/renderer/global_illumination/brick4/gpu/encoding/v1/chunk_brick4_sh3_color_encode_to_storage.js"],"names":[],"mappings":"AAuBA,iEAwBC;0BA/CyB,6CAA6C"}
+{"version":3,"file":"chunk_brick4_sh3_color_encode_to_storage.d.ts","sourceRoot":"","sources":["../../../../../../../../../src/shade/renderer/global_illumination/brick4/gpu/encoding/v1/chunk_brick4_sh3_color_encode_to_storage.js"],"names":[],"mappings":"AAwBA,iEAiBC;0BAzCyB,6CAA6C"}

package/src/shade/renderer/global_illumination/brick4/gpu/encoding/v1/chunk_brick4_sh3_color_encode_to_storage.js

@@ -1,4 +1,5 @@
 import { CodeChunk } from "../../../../../shader/compiler/CodeChunk.js";
+import { chunk_brick4_sh3_color_encode } from "./chunk_brick4_sh3_color_encode.js";
 
 /*
  * The v1 brick4 SH3 probe encoding: nine RGB coefficients as fourteen f16 pairs.
@@ -29,20 +30,13 @@ fn brick4_sh3_color_encode_to_storage_v1(
     out_offset: u32,
     sh: array<vec3<f32>,9>
 ){
-    (*out)[out_offset + 0u]  = pack2x16float(vec2<f32>(sh[0].x, sh[0].y));
-    (*out)[out_offset + 1u]  = pack2x16float(vec2<f32>(sh[0].z, sh[1].x));
-    (*out)[out_offset + 2u]  = pack2x16float(vec2<f32>(sh[1].y, sh[1].z));
-    (*out)[out_offset + 3u]  = pack2x16float(vec2<f32>(sh[2].x, sh[2].y));
-    (*out)[out_offset + 4u]  = pack2x16float(vec2<f32>(sh[2].z, sh[3].x));
-    (*out)[out_offset + 5u]  = pack2x16float(vec2<f32>(sh[3].y, sh[3].z));
-    (*out)[out_offset + 6u]  = pack2x16float(vec2<f32>(sh[4].x, sh[4].y));
-    (*out)[out_offset + 7u]  = pack2x16float(vec2<f32>(sh[4].z, sh[5].x));
-    (*out)[out_offset + 8u]  = pack2x16float(vec2<f32>(sh[5].y, sh[5].z));
-    (*out)[out_offset + 9u]  = pack2x16float(vec2<f32>(sh[6].x, sh[6].y));
-    (*out)[out_offset + 10u] = pack2x16float(vec2<f32>(sh[6].z, sh[7].x));
-    (*out)[out_offset + 11u] = pack2x16float(vec2<f32>(sh[7].y, sh[7].z));
-    (*out)[out_offset + 12u] = pack2x16float(vec2<f32>(sh[8].x, sh[8].y));
-    (*out)[out_offset + 13u] = pack2x16float(vec2<f32>(sh[8].z, 0.0));
+    let packed = brick4_sh3_color_encode_v1(sh);
+    for (var i = 0u; i < 14u; i++) {
+        (*out)[out_offset + i] = packed[i];
+    }
 }
-    `
+    `,
+    [
+        chunk_brick4_sh3_color_encode,
+    ]
 )

package/src/shade/renderer/global_illumination/clipmap/shader_debug_clipmap.d.ts

@@ -1,5 +1,6 @@
 /**
- * What the overlay draws: a clipmap's levels, finest first, and the width of their edge bands.
+ * How the overlay draws a clipmap: how many of its levels are in use, and the width of their edge
+ * bands. The levels themselves, finest first, are the uniform `clipmap_levels`, a {@link CLIPMAP_LEVEL_ARRAY}.
  * @type {WebGPUStruct}
  */
 export const CLIPMAP_DEBUG_STRUCT: WebGPUStruct;

package/src/shade/renderer/global_illumination/clipmap/shader_debug_clipmap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shader_debug_clipmap.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/global_illumination/clipmap/shader_debug_clipmap.js"],"names":[],"mappings":"AAaA;;;GAGG;AACH,mCAFU,YAAY,CAYH;AA6DnB;;;;;;;;GAQG;AACH,mCAFU,WAAW,CAWnB;6BA/F2B,mCAAmC;4BAJpC,6BAA6B"}
+{"version":3,"file":"shader_debug_clipmap.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/global_illumination/clipmap/shader_debug_clipmap.js"],"names":[],"mappings":"AAaA;;;;GAIG;AACH,mCAFU,YAAY,CAWH;AA8DnB;;;;;;;;GAQG;AACH,mCAFU,WAAW,CAWnB;6BAhG2B,mCAAmC;4BAJpC,6BAA6B"}

package/src/shade/renderer/global_illumination/clipmap/shader_debug_clipmap.js

@@ -12,25 +12,26 @@ import { f32, u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
 import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
 
 /**
- * What the overlay draws: a clipmap's levels, finest first, and the width of their edge bands.
+ * How the overlay draws a clipmap: how many of its levels are in use, and the width of their edge
+ * bands. The levels themselves, finest first, are the uniform `clipmap_levels`, a {@link CLIPMAP_LEVEL_ARRAY}.
  * @type {WebGPUStruct}
  */
 export const CLIPMAP_DEBUG_STRUCT = WebGPUStruct.from({
     /**
-     * Levels of {@link levels} in use.
+     * Levels of `clipmap_levels` in use.
      */
     level_count: u32,
     /**
      * Cells, positive: how far into a window its edge band reaches.
      */
     band_width: f32,
-    levels: CLIPMAP_LEVEL_ARRAY,
 }, "ClipmapDebug");
 
 const resources = new ShaderResourceSetDescriptor();
 resources.createGroup()
     .addTexture("tDepth")
     .addUniform("clipmap", CLIPMAP_DEBUG_STRUCT)
+    .addUniform("clipmap_levels", CLIPMAP_LEVEL_ARRAY)
     .addUniform("camera", CAMERA_UNIFORM_STRUCT)
 ;
 
@@ -55,7 +56,7 @@ fn main(
 
     let position_ws = project_position_from_depth(uv, device_depth, camera.view_projection_matrix_inverse);
 
-    let selection = clipmap_select_finest(&clipmap.levels, clipmap.level_count, position_ws, clipmap.band_width);
+    let selection = clipmap_select_finest(&clipmap_levels, clipmap.level_count, position_ws, clipmap.band_width);
 
     if(selection.level == CLIPMAP_LEVEL_NONE){
         discard;
@@ -69,7 +70,7 @@ fn main(
     var color = mix(own_color, next_color, selection.edge_weight);
 
     // lines on the level's cell faces, two centimetres wide in the world
-    let cell_size = clipmap.levels[selection.level].cell_size;
+    let cell_size = clipmap_levels[selection.level].cell_size;
     let position_cells = position_ws / cell_size;
     let to_face = min(fract(position_cells), 1.0 - fract(position_cells));
     let nearest_face = min(to_face.x, min(to_face.y, to_face.z));

package/src/shade/renderer/global_illumination/probe/octahedral/convolve/graph_reduce_atlas_to_sh.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph_reduce_atlas_to_sh.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/global_illumination/probe/octahedral/convolve/graph_reduce_atlas_to_sh.js"],"names":[],"mappings":"AAgHA;;;;;;;;;;GAUG;AACH;IAR+B,KAAK;IACF,KAAK;IACH,KAAK;IACd,kBAAkB,EAAlC,MAAM;IACU,kBAAkB,EAAlC,MAAM;IACY,mBAAmB,EAArC,MAAM,EAAE;IACQ,SAAS,EAAzB,MAAM;WAwDhB;AA7ID,sCAaM;0BAxCoB,0CAA0C"}
+{"version":3,"file":"graph_reduce_atlas_to_sh.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/global_illumination/probe/octahedral/convolve/graph_reduce_atlas_to_sh.js"],"names":[],"mappings":"AAiHA;;;;;;;;;;GAUG;AACH;IAR+B,KAAK;IACF,KAAK;IACH,KAAK;IACd,kBAAkB,EAAlC,MAAM;IACU,kBAAkB,EAAlC,MAAM;IACY,mBAAmB,EAArC,MAAM,EAAE;IACQ,SAAS,EAAzB,MAAM;WAwDhB;AA7ID,sCAaM;0BAzCoB,0CAA0C"}

package/src/shade/renderer/global_illumination/probe/octahedral/convolve/graph_reduce_atlas_to_sh.js

@@ -13,6 +13,7 @@ import { graph_compute_pass } from "../../../../shader/graph/compute/graph_compu
 import { ShaderResourceSetDescriptor } from "../../../../shader/resource/ShaderResourceSetDescriptor.js";
 import { chunk_lpv_atlas_read_patch_texel } from "../sample/chunk_lpv_atlas_read_patch_texel.js";
 import { chunk_compute_coefficient_address } from "./chunk_compute_coefficient_address.js";
+import { msb_32 } from "../../../../../../core/binary/msb_32.js";
 
 const PUSH_CONSTANTS = WebGPUStruct.from({
     probe_index_offset: u32,
@@ -145,7 +146,7 @@ export function graph_reduce_atlas_to_sh({
     const probes_per_row = g_buffer_resolution[0] / probe_resolution;
 
     // now convolve
-    const mip_limit = Math.floor(Math.log2(probe_resolution));
+    const mip_limit = msb_32(probe_resolution);
 
     let coefficients = sh_buffer;
 

package/src/shade/renderer/global_illumination/probe_clipmap/GPUProbeClipmapGI.d.ts

@@ -7,8 +7,10 @@
  */
 /**
  * {@link ShadeIndirectLightingMode.ProbeClipmap} for one view (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §5):
- * a {@link GPUBrickClipmap}, the world as rays see it, and a {@link GPUProbeClipmap}, what shading
- * samples, both around the view.
+ * a {@link GPUBrickClipmap}, the world as rays see it, and two {@link GPUProbeClipmap}s around the view
+ * (WORLD_PROBE_CACHE_SCOPE_2026_11_01.md): the frustum's probes, which the frame's pixels want and shading
+ * samples, and the world cache, which the frustum's hits want where the frustum has no probe and which only
+ * the probes' hits sample, in the frustum's windows at 2^k its lattice.
  *
  * The renderer holds one for its main view, as it holds the view's volumetrics, and hands it the view
  * and the settings on every frame the mode runs ({@link graph_update}). The clipmaps are made on the
@@ -26,6 +28,12 @@
  * Until its probes are traced (§13, S4) the mode lights as IBL.
  */
 export class GPUProbeClipmapGI {
+    /**
+     * @param {GPUProbeClipmap} world_cache
+     * @param {ProbeClipmapSettings} settings
+     * @returns {boolean} whether it is what the settings' world cache describes, in their frustum's windows
+     */
+    static "__#206@#world_cache_built_for"(world_cache: GPUProbeClipmap, settings: ProbeClipmapSettings): boolean;
     /**
      * @param {GraphicsContext} graphics
      */
@@ -35,9 +43,13 @@ export class GPUProbeClipmapGI {
      */
     get brick_clipmap(): GPUBrickClipmap;
     /**
-     * @returns {GPUProbeClipmap|undefined} undefined while the mode is not running
+     * @returns {GPUProbeClipmap|undefined} the frustum's probes; undefined while the mode is not running
      */
     get probe_clipmap(): GPUProbeClipmap;
+    /**
+     * @returns {GPUProbeClipmap|undefined} the world cache's probes; undefined while the mode is not running
+     */
+    get world_cache(): GPUProbeClipmap;
     /**
      * @returns {ProbeClipmapSceneHolds|undefined} undefined while the mode is not running
      */

package/src/shade/renderer/global_illumination/probe_clipmap/GPUProbeClipmapGI.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUProbeClipmapGI.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/global_illumination/probe_clipmap/GPUProbeClipmapGI.js"],"names":[],"mappings":"AAeA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IA0DI;;OAEG;IACH,sBAFW,eAAe,EAMzB;IAED;;OAEG;IACH,qCAEC;IAED;;OAEG;IACH,qCAEC;IAED;;OAEG;IACH,oCAEC;IAED;;;;;;;;;;;;;;OAcG;IACH;QAT+B,KAAK,EAAzB,UAAU;QACc,IAAI,EAA5B,cAAc;QACgB,QAAQ,EAAtC,oBAAoB;QACJ,KAAK,EAArB,MAAM;QACU,MAAM,EAAtB,MAAM;QACK,IAAI;QACE,MAAM,GAAvB,MAAM;aA2FhB;IAED;;;OAGG;IACH,0BAEC;IAED;;;;;;;;;OASG;IACH,4CAUC;IAwDD;;;;;;;;;;OAUG;IACH;QAN+B,KAAK,EAAzB,UAAU;QACc,IAAI,EAA5B,cAAc;QACgB,QAAQ,EAAtC,oBAAoB;QACF,UAAU,EAA5B,MAAM,EAAE;QACN,MAAM,CAmBlB;IAED;;;;;OAKG;IACH,uBAFW,aAAa,QASvB;IAED;;;OAGG;IACH,0BAHW,aAAa,GACX,OAAO,CAanB;IAyCD;;;OAGG;IACH,gBAoBC;IAED,gBAcC;;CACJ;yBA9bY,OAAO,8DAA8D,EAAE,UAAU;8BACjF,OAAO,0BAA0B,EAAE,eAAe;6BAClD,OAAO,8BAA8B,EAAE,cAAc;mCACrD,OAAO,2BAA2B,EAAE,oBAAoB;4BACxD,OAAO,4BAA4B,EAAE,aAAa;gCAjB/B,4BAA4B;gCAQ5B,4BAA4B;uCAErB,6BAA6B"}
+{"version":3,"file":"GPUProbeClipmapGI.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/global_illumination/probe_clipmap/GPUProbeClipmapGI.js"],"names":[],"mappings":"AAuBA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;IAoSI;;;;OAIG;IACH,oDAJW,eAAe,YACf,oBAAoB,GAClB,OAAO,CAUnB;IArOD;;OAEG;IACH,sBAFW,eAAe,EAMzB;IAED;;OAEG;IACH,qCAEC;IAED;;OAEG;IACH,qCAEC;IAED;;OAEG;IACH,mCAEC;IAED;;OAEG;IACH,oCAEC;IAED;;;;;;;;;;;;;;OAcG;IACH;QAT+B,KAAK,EAAzB,UAAU;QACc,IAAI,EAA5B,cAAc;QACgB,QAAQ,EAAtC,oBAAoB;QACJ,KAAK,EAArB,MAAM;QACU,MAAM,EAAtB,MAAM;QACK,IAAI;QACE,MAAM,GAAvB,MAAM;aAiIhB;IAqDD;;;OAGG;IACH,0BAEC;IAED;;;;;;;;;OASG;IACH,4CAUC;IAwDD;;;;;;;;;;OAUG;IACH;QAN+B,KAAK,EAAzB,UAAU;QACc,IAAI,EAA5B,cAAc;QACgB,QAAQ,EAAtC,oBAAoB;QACF,UAAU,EAA5B,MAAM,EAAE;QACN,MAAM,CAmBlB;IAED;;;;;OAKG;IACH,uBAFW,aAAa,QASvB;IAED;;;OAGG;IACH,0BAHW,aAAa,GACX,OAAO,CAanB;IAgED;;;OAGG;IACH,gBAuBC;IAED,gBAcC;;CACJ;yBA5kBY,OAAO,8DAA8D,EAAE,UAAU;8BACjF,OAAO,0BAA0B,EAAE,eAAe;6BAClD,OAAO,8BAA8B,EAAE,cAAc;mCACrD,OAAO,2BAA2B,EAAE,oBAAoB;4BACxD,OAAO,4BAA4B,EAAE,aAAa;gCAnB/B,4BAA4B;gCAQ5B,4BAA4B;uCAIrB,6BAA6B"}

package/src/shade/renderer/global_illumination/probe_clipmap/GPUProbeClipmapGI.js

@@ -1,6 +1,12 @@
 import { assert } from "../../../../core/assert.js";
+import { ceilPowerOfTwo } from "../../../../core/binary/operations/ceilPowerOfTwo.js";
 import { BufferDescriptor } from "../../../descriptor/buffer/BufferDescriptor.js";
+import {
+    graph_build_world_light_clusters,
+    world_light_clusters_data_size
+} from "../../light/world_cluster/graph_build_world_light_clusters.js";
 import { CLIPMAP_LEVEL_ARRAY } from "../../shader/chunk/clipmap/CLIPMAP_LEVEL_STRUCT.js";
+import { graph_import_buffer } from "../../shader/graph/graph_import_buffer.js";
 import { GPUBrickClipmap } from "./brick/GPUBrickClipmap.js";
 import { MeshSDFBrickProvider } from "./brick/mesh/MeshSDFBrickProvider.js";
 import { graph_probe_clipmap_debug_brick_clipmap } from "./debug/graph_probe_clipmap_debug_brick_clipmap.js";
@@ -10,7 +16,9 @@ import { ProbeClipmapDebugView } from "./debug/ProbeClipmapDebugView.js";
 import { PROBE_RECORD_STRUCT } from "./probe/chunk_probe_clipmap.js";
 import { PROBE_SAMPLING_STRUCT } from "./probe/chunk_probe_clipmap_pick.js";
 import { GPUProbeClipmap } from "./probe/GPUProbeClipmap.js";
-import { PROBE_DEPTH_TEXEL_RAYS, PROBE_RAYS_PER_TEXEL_MAX, PROBE_RAYS_PER_TEXEL_MIN } from "./probe/PROBE_CLIPMAP.js";
+import { PROBE_DEPTH_TEXEL_RAYS, PROBE_RAY_CASCADE_MASK, PROBE_TEXEL_RAYS } from "./probe/PROBE_CLIPMAP.js";
+import { ProbeClipmapHitWants } from "./probe/ProbeClipmapHitWants.js";
+import { ProbeClipmapScreenWants } from "./probe/ProbeClipmapScreenWants.js";
 import { ProbeClipmapSceneHolds } from "./ProbeClipmapSceneHolds.js";
 
 /**
@@ -23,8 +31,10 @@ import { ProbeClipmapSceneHolds } from "./ProbeClipmapSceneHolds.js";
 
 /**
  * {@link ShadeIndirectLightingMode.ProbeClipmap} for one view (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §5):
- * a {@link GPUBrickClipmap}, the world as rays see it, and a {@link GPUProbeClipmap}, what shading
- * samples, both around the view.
+ * a {@link GPUBrickClipmap}, the world as rays see it, and two {@link GPUProbeClipmap}s around the view
+ * (WORLD_PROBE_CACHE_SCOPE_2026_11_01.md): the frustum's probes, which the frame's pixels want and shading
+ * samples, and the world cache, which the frustum's hits want where the frustum has no probe and which only
+ * the probes' hits sample, in the frustum's windows at 2^k its lattice.
  *
  * The renderer holds one for its main view, as it holds the view's volumetrics, and hands it the view
  * and the settings on every frame the mode runs ({@link graph_update}). The clipmaps are made on the
@@ -53,10 +63,28 @@ export class GPUProbeClipmapGI {
     #brick_clipmap = undefined;
 
     /**
+     * The frustum's probes.
      * @type {GPUProbeClipmap|undefined}
      */
     #probe_clipmap = undefined;
 
+    /**
+     * The world cache's probes.
+     * @type {GPUProbeClipmap|undefined}
+     */
+    #world_cache = undefined;
+
+    /** The frustum's wants, the frame's pixels. */
+    #screen_wants = new ProbeClipmapScreenWants();
+
+    /** The world cache's wants, the frustum's hits. @type {ProbeClipmapHitWants|undefined} */
+    #hit_wants = undefined;
+
+    /** The coarsest brick window's box, metres, which the world light clusters cull lights against. */
+    #clusters_min = [0, 0, 0];
+    #clusters_max = [0, 0, 0];
+    #clusters = { lookup: -1, data: -1 };
+
     /**
      * {@link GPUViewContext#id} of the view the clipmaps were made for: they hold what is around that
      * view's camera, in that view's scene.
@@ -116,12 +144,19 @@ export class GPUProbeClipmapGI {
     }
 
     /**
-     * @returns {GPUProbeClipmap|undefined} undefined while the mode is not running
+     * @returns {GPUProbeClipmap|undefined} the frustum's probes; undefined while the mode is not running
      */
     get probe_clipmap() {
         return this.#probe_clipmap;
     }
 
+    /**
+     * @returns {GPUProbeClipmap|undefined} the world cache's probes; undefined while the mode is not running
+     */
+    get world_cache() {
+        return this.#world_cache;
+    }
+
     /**
      * @returns {ProbeClipmapSceneHolds|undefined} undefined while the mode is not running
      */
@@ -153,10 +188,14 @@ export class GPUProbeClipmapGI {
         assert.notOk(this.#destroyed, 'destroyed');
 
         // the relations between fields, checked here because each setter sees only its own field
-        assert.greaterThanOrEqual(settings.rays_per_probe, PROBE_RAYS_PER_TEXEL_MIN * settings.radiance_resolution * settings.radiance_resolution, 'rays_per_probe must be at least radiance_resolution² / 4');
-        assert.lessThanOrEqual(settings.rays_per_probe, PROBE_RAYS_PER_TEXEL_MAX * settings.radiance_resolution * settings.radiance_resolution, 'rays_per_probe must be at most 4·radiance_resolution²');
-        assert.greaterThanOrEqual(settings.ray_budget, settings.rays_per_probe, 'ray_budget must be at least rays_per_probe');
+        assert.lessThanOrEqual(settings.rays_per_probe, PROBE_TEXEL_RAYS * settings.radiance_resolution * settings.radiance_resolution, 'rays_per_probe must be at most 64·radiance_resolution², the rays a radiance texel gathers');
+        assert.greaterThanOrEqual(settings.frustum_ray_budget, settings.rays_per_probe, 'frustum_ray_budget, FRUSTUM_RAY_BUDGET_FRACTION of ray_budget, must be at least rays_per_probe');
+        assert.lessThanOrEqual(settings.brick_cascade_count, PROBE_RAY_CASCADE_MASK + 1, "brick_cascade_count, the ray's cascade field");
+        assert.lessThanOrEqual(world_light_clusters_data_size(settings.brick_cascade_count), this.#graphics.device.limits.maxStorageBufferBindingSize, "brick_cascade_count, the world light clusters' data past maxStorageBufferBindingSize");
         assert.lessThanOrEqual(settings.rays_per_probe, PROBE_DEPTH_TEXEL_RAYS * settings.depth_resolution * settings.depth_resolution, 'rays_per_probe must be at most 64·depth_resolution², the rays a depth texel gathers');
+        assert.lessThanOrEqual(settings.world_cache_rays_per_probe, PROBE_TEXEL_RAYS * settings.world_cache_radiance_resolution ** 2, 'world_cache_rays_per_probe must be at most 64·world_cache_radiance_resolution², the rays a radiance texel gathers');
+        assert.lessThanOrEqual(settings.world_cache_rays_per_probe, PROBE_DEPTH_TEXEL_RAYS * settings.world_cache_depth_resolution ** 2, 'world_cache_rays_per_probe must be at most 64·world_cache_depth_resolution², the rays a depth texel gathers');
+        assert.greaterThanOrEqual(settings.world_ray_budget, settings.world_cache_rays_per_probe, 'world_ray_budget, the rest of ray_budget, must be at least world_cache_rays_per_probe');
 
         if (
             this.#brick_clipmap !== undefined
@@ -164,6 +203,7 @@ export class GPUProbeClipmapGI {
                 view.id !== this.#view_id
                 || !this.#brick_clipmap.built_for(settings)
                 || !this.#probe_clipmap.built_for(settings)
+                || !GPUProbeClipmapGI.#world_cache_built_for(this.#world_cache, settings)
             )
         ) {
             this.release();
@@ -212,26 +252,110 @@ export class GPUProbeClipmapGI {
             movers,
         });
 
-        // the probes the frame's pixels want, around the same anchor, updated through the bricks (§8)
-        this.#probe_clipmap.graph_update({
+        const clusters = this.#graph_clusters(graph, scene);
+
+        // the probes around the same anchor, updated through the bricks (§8): the frustum's windows, and the
+        // world cache's in them
+        const frustum = this.#probe_clipmap;
+        const world = this.#world_cache;
+
+        frustum.place(transform[12], transform[13], transform[14]);
+        world.place_within(frustum);
+
+        // the world cache first: its wants read the frustum's last-frame rays, which the frustum's lifetime
+        // writes over
+        this.#hit_wants.set({ ray_budget: settings.frustum_ray_budget });
+
+        world.graph_update({
             graph,
-            x: transform[12],
-            y: transform[13],
-            z: transform[14],
-            depth,
-            normal,
-            camera: view.camera.buffer,
+            wants: this.#hit_wants,
+            stbn,
+            response_frames: settings.response_frames,
+            ray_budget: settings.world_ray_budget,
+            rays_per_probe: settings.world_cache_rays_per_probe,
+            brick_clipmap: this.#brick_clipmap,
+            bricks,
+            scene,
+            card_rows: this.#holds.rows_buffer,
+            // a world cache probe re-samples nothing: its radiance has no skirt for the history's taps, and the
+            // rays are the frustum's switch
+            history_resampling: false,
+            ray_resampling: false,
+            clusters,
+            bounce_first: frustum,
+            bounce_fallback: world,
+        });
+
+        this.#screen_wants.set({ depth, normal, camera: view.camera.buffer, stbn, resolution: view.resolution });
+
+        frustum.graph_update({
+            graph,
+            wants: this.#screen_wants,
             stbn,
-            resolution: view.resolution,
             response_frames: settings.response_frames,
-            ray_budget: settings.ray_budget,
+            ray_budget: settings.frustum_ray_budget,
             rays_per_probe: settings.rays_per_probe,
             brick_clipmap: this.#brick_clipmap,
             bricks,
             scene,
             card_rows: this.#holds.rows_buffer,
-            resampling: settings.resampling,
+            history_resampling: settings.history_resampling,
+            ray_resampling: settings.ray_resampling,
+            clusters,
+            bounce_first: frustum,
+            bounce_fallback: world,
+        });
+    }
+
+    /**
+     * The world light clusters over the bricks' cascades, where every hit is, which both clipmaps' hits take
+     * their local lights from (§8.7).
+     *
+     * @param {FrameGraph} graph
+     * @param {import("../../scene/GPUSceneContext.js").GPUSceneContext} scene
+     * @returns {{lookup: number, data: number}} graph handles, held until the next call
+     */
+    #graph_clusters(graph, scene) {
+        const brick_clipmap = this.#brick_clipmap;
+        const coarsest = brick_clipmap.cascade_count - 1;
+        const coarsest_cell = brick_clipmap.cell_size(coarsest);
+
+        for (let axis = 0; axis < 3; axis++) {
+            const corner = brick_clipmap.corner(coarsest, axis);
+
+            this.#clusters_min[axis] = corner * coarsest_cell;
+            this.#clusters_max[axis] = (corner + brick_clipmap.resolution) * coarsest_cell;
+        }
+
+        const built = graph_build_world_light_clusters({
+            graph,
+            lights: scene.lights,
+            levels: graph_import_buffer(graph, brick_clipmap.levels, "probe_brick_levels"),
+            cascade_count: brick_clipmap.cascade_count,
+            border: 0,
+            coarsest_min: this.#clusters_min,
+            coarsest_max: this.#clusters_max,
         });
+
+        this.#clusters.lookup = built.lookup;
+        this.#clusters.data = built.data;
+
+        return this.#clusters;
+    }
+
+    /**
+     * @param {GPUProbeClipmap} world_cache
+     * @param {ProbeClipmapSettings} settings
+     * @returns {boolean} whether it is what the settings' world cache describes, in their frustum's windows
+     */
+    static #world_cache_built_for(world_cache, settings) {
+        const ratio = 2 ** settings.world_cache_spacing_shift;
+
+        return world_cache.cascade_count === settings.probe_cascade_count
+            && world_cache.resolution === settings.probe_cascade_resolution * ratio
+            && world_cache.spacing === settings.probe_spacing / ratio
+            && world_cache.radiance_resolution === settings.world_cache_radiance_resolution
+            && world_cache.depth_resolution === settings.world_cache_depth_resolution;
     }
 
     /**
@@ -408,14 +532,37 @@ export class GPUProbeClipmapGI {
             voxel_size: settings.brick_voxel_size,
         });
 
+        // the frustum's slots start at 2·N²·C, a power of two: a visible surface crosses each cascade as a shell a
+        // cell thick, doubled for the cage. The world cache's start there too: the surfaces that want it are the
+        // frustum's hits', not the screen's, so its own lattice says nothing of how many there are
+        const capacity = ceilPowerOfTwo(2 * settings.probe_cascade_resolution ** 2 * settings.probe_cascade_count);
+
         this.#probe_clipmap = new GPUProbeClipmap(device, {
             cascade_count: settings.probe_cascade_count,
             resolution: settings.probe_cascade_resolution,
             spacing: settings.probe_spacing,
             radiance_resolution: settings.radiance_resolution,
             depth_resolution: settings.depth_resolution,
+            radiance_skirt: true,
+            label: 'Probe clipmap',
+            capacity,
+        });
+
+        const ratio = 2 ** settings.world_cache_spacing_shift;
+
+        this.#world_cache = new GPUProbeClipmap(device, {
+            cascade_count: settings.probe_cascade_count,
+            resolution: settings.probe_cascade_resolution * ratio,
+            spacing: settings.probe_spacing / ratio,
+            radiance_resolution: settings.world_cache_radiance_resolution,
+            depth_resolution: settings.world_cache_depth_resolution,
+            radiance_skirt: false,
+            label: 'Probe world cache',
+            capacity,
         });
 
+        this.#hit_wants = new ProbeClipmapHitWants(this.#probe_clipmap);
+
         this.#view_id = view.id;
     }
 
@@ -435,6 +582,7 @@ export class GPUProbeClipmapGI {
 
         this.#brick_clipmap.destroy();
         this.#probe_clipmap.destroy();
+        this.#world_cache.destroy();
         this.#mesh_provider.destroy();
 
         this.#mesh_provider = undefined;
@@ -442,6 +590,8 @@ export class GPUProbeClipmapGI {
 
         this.#brick_clipmap = undefined;
         this.#probe_clipmap = undefined;
+        this.#world_cache = undefined;
+        this.#hit_wants = undefined;
         this.#view_id = -1;
     }
 

package/src/shade/renderer/global_illumination/probe_clipmap/ProbeClipmapSceneHolds.d.ts

@@ -9,7 +9,8 @@
  *   `GPU_DATABASE_NULL` until then and for a row out of the SDF world.
  *
  * A row is in the SDF world when its `flags` carry `MESH_FLAG_SDF_WORLD`, whatever its geometry: a
- * virtual geometry's cache is held as a mesh's is, and comes from its own source (`VGeoSDFProxies`).
+ * virtual geometry's cache is held as a mesh's is, and is its proxy's once `VGeoSDFProxies` aliases it: the
+ * hold and its side move to the proxy, and the pair's card set captures the proxy's layout.
  * A skinned row draws a clone: the hold and the pair are its source's,
  * whose unskinned field and cards the clone's header is aliased to (§6.3). A row written again moves
  * its hold and its pair, the new ones taken before the old ones go, so a cache or card set a row keeps

package/src/shade/renderer/global_illumination/probe_clipmap/ProbeClipmapSceneHolds.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ProbeClipmapSceneHolds.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/global_illumination/probe_clipmap/ProbeClipmapSceneHolds.js"],"names":[],"mappings":"AAwDA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH;IAwEI;;;OAGG;IACH,mBAHW,eAAe,YACf,eAAe,EASzB;IAED;;OAEG;IACH,sEAEC;IAED;;;OAGG;IACH,yBAEC;IAED;;;OAGG;IACH,yBAEC;IAED;;;OAGG;IACH,mCAEC;IAED;;;OAGG;IACH,qCAEC;IAED,0BAEC;IAED;;;;;;OAMG;IACH,oBAJW,mBAAmB,YACnB,aAAa,GACX,MAAM,GAAC,SAAS,CAI5B;IAED;;;;OAIG;IACH,6BAIC;IAED,eAiBC;IAED,eAuCC;IAED;;OAEG;IACH,cAiBC;;CA4TJ;8BA1mBY,OAAO,gCAAgC,EAAE,eAAe;8BACxD,OAAO,mCAAmC,EAAE,eAAe;kCAC3D,OAAO,uCAAuC,EAAE,mBAAmB;4BACnE,OAAO,iCAAiC,EAAE,aAAa;iCACvD,OAAO,sCAAsC,EAAE,kBAAkB;8BACjE,OAAO,0BAA0B,EAAE,eAAe"}
+{"version":3,"file":"ProbeClipmapSceneHolds.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/global_illumination/probe_clipmap/ProbeClipmapSceneHolds.js"],"names":[],"mappings":"AAwDA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH;IAwEI;;;OAGG;IACH,mBAHW,eAAe,YACf,eAAe,EASzB;IAED;;OAEG;IACH,sEAEC;IAED;;;OAGG;IACH,yBAEC;IAED;;;OAGG;IACH,yBAEC;IAED;;;OAGG;IACH,mCAEC;IAED;;;OAGG;IACH,qCAEC;IAED,0BAEC;IAED;;;;;;OAMG;IACH,oBAJW,mBAAmB,YACnB,aAAa,GACX,MAAM,GAAC,SAAS,CAI5B;IAED;;;;OAIG;IACH,6BAIC;IAED,eAiBC;IAED,eAuCC;IAED;;OAEG;IACH,cAiBC;;CA4TJ;8BA3mBY,OAAO,gCAAgC,EAAE,eAAe;8BACxD,OAAO,mCAAmC,EAAE,eAAe;kCAC3D,OAAO,uCAAuC,EAAE,mBAAmB;4BACnE,OAAO,iCAAiC,EAAE,aAAa;iCACvD,OAAO,sCAAsC,EAAE,kBAAkB;8BACjE,OAAO,0BAA0B,EAAE,eAAe"}

package/src/shade/renderer/global_illumination/probe_clipmap/ProbeClipmapSceneHolds.js

@@ -65,7 +65,8 @@ class Pair {
  *   `GPU_DATABASE_NULL` until then and for a row out of the SDF world.
  *
  * A row is in the SDF world when its `flags` carry `MESH_FLAG_SDF_WORLD`, whatever its geometry: a
- * virtual geometry's cache is held as a mesh's is, and comes from its own source (`VGeoSDFProxies`).
+ * virtual geometry's cache is held as a mesh's is, and is its proxy's once `VGeoSDFProxies` aliases it: the
+ * hold and its side move to the proxy, and the pair's card set captures the proxy's layout.
  * A skinned row draws a clone: the hold and the pair are its source's,
  * whose unskinned field and cards the clone's header is aliased to (§6.3). A row written again moves
  * its hold and its pair, the new ones taken before the old ones go, so a cache or card set a row keeps