@woosh/meep-engine 3.58.0 → 3.60.0

package/src/shade/renderer/gpu_primitive/sort/verify_radix_sort.js

@@ -1,188 +1,387 @@
-import { FrameGraph } from "../../../../engine/graphics/render/frame_graph/FrameGraph.js";
-import { ShadeGPUCommandContext } from "../../../device/ShadeGPUCommandContext.js";
-import { u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
-import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
-import { graph_inspect_gpu_buffer } from "../../buffer/graph_inspect_gpu_buffer.js";
-import { graph_import_typed_buffer } from "../../shader/graph/graph_import_typed_buffer.js";
-import { SORT_TILE_SIZE } from "./defs.js";
-import { graph_radix_sort } from "./graph_radix_sort.js";
-
-/**
- * The element counts one run covers. The interesting ones are all at tile boundaries — the scatter's
- * tail tile is padded, and a count one either side of an exact multiple is what exercises the
- * padding guard from both directions.
- *
- * @type {number[]}
- */
-const ELEMENT_COUNTS = [
-    2, 3, 255, 256, 257,
-    SORT_TILE_SIZE - 1, SORT_TILE_SIZE, SORT_TILE_SIZE + 1,
-    SORT_TILE_SIZE * 4 + 13,
-    100003,
-];
-
-/**
- * @param {number} seed
- * @returns {function(): number} LCG, so a failing run is reproducible
- */
-function make_random(seed) {
-    let state = seed >>> 0;
-
-    return () => (state = (state * 1664525 + 1013904223) >>> 0);
-}
-
-/**
- * The key distribution for one case. Three shapes, because a radix sort fails differently under
- * each: dense duplicates stress stability and the in-tile split's equal-digit runs, a single
- * repeated key makes every tile one bin, and full-range keys are the only ones that reach the top
- * digit pass at all.
- *
- * @param {number} element_count
- * @param {number} variant
- * @returns {Uint32Array}
- */
-function make_keys(element_count, variant) {
-    const random = make_random(0x9e3779b9 ^ (element_count * 31 + variant));
-
-    const keys = new Uint32Array(element_count);
-
-    for (let i = 0; i < element_count; i++) {
-        if (variant === 0) {
-            keys[i] = random() % 1000;
-        } else if (variant === 1) {
-            keys[i] = 0x2a2a2a2a;
-        } else {
-            keys[i] = random();
-        }
-    }
-
-    return keys;
-}
-
-/**
- * @param {Uint32Array} input_keys
- * @param {Uint32Array|number[]} sorted_keys
- * @param {Uint32Array|number[]} sorted_values
- * @returns {string[]} one entry per distinct problem found, empty when the sort is correct
- */
-function problems_with(input_keys, sorted_keys, sorted_values) {
-    const element_count = input_keys.length;
-
-    const problems = [];
-
-    for (let i = 1; i < element_count; i++) {
-        if (sorted_keys[i] < sorted_keys[i - 1]) {
-            problems.push(`keys not ascending at [${i}]: ${sorted_keys[i - 1]} -> ${sorted_keys[i]}`);
-            break;
-        }
-    }
-
-    const seen = new Uint8Array(element_count);
-    for (let i = 0; i < element_count; i++) {
-        const value = sorted_values[i];
-
-        if (value >= element_count || seen[value] === 1) {
-            problems.push(`payload is not a permutation at [${i}]: ${value}`);
-            break;
-        }
-
-        seen[value] = 1;
-    }
-
-    for (let i = 0; i < element_count; i++) {
-        if (input_keys[sorted_values[i]] !== sorted_keys[i]) {
-            problems.push(`key/payload pairing broken at [${i}]: payload ${sorted_values[i]} `
-                + `had key ${input_keys[sorted_values[i]]}, sorted key is ${sorted_keys[i]}`);
-            break;
-        }
-    }
-
-    // payload is the input index, so a stable sort leaves equal keys with ascending payloads
-    for (let i = 1; i < element_count; i++) {
-        if (sorted_keys[i] === sorted_keys[i - 1] && sorted_values[i] < sorted_values[i - 1]) {
-            problems.push(`not stable at [${i}]: key ${sorted_keys[i]} came from index `
-                + `${sorted_values[i - 1]} then ${sorted_values[i]}`);
-            break;
-        }
-    }
-
-    return problems;
-}
-
-/**
- * On-device verification of {@link graph_radix_sort}: sorts deterministic key/payload sets across
- * tile-boundary element counts and three key distributions, reads the results back, and checks on
- * the CPU that the keys are ascending, that the payload is a permutation of the input indices, that
- * every payload still sits next to ITS key, and that equal keys kept their input order.
- *
- * Logs one `[SORT]` PASS/FAIL line per case.
- *
- * @param {GraphicsContext} graphics
- */
-export function verify_radix_sort(graphics) {
-
-    const graph = new FrameGraph();
-    const cmd = ShadeGPUCommandContext.create(graphics, 'verify/radix sort');
-
-    const usage = GPUBufferUsage.COPY_SRC | GPUBufferUsage.STORAGE;
-
-    for (const element_count of ELEMENT_COUNTS) {
-        for (let variant = 0; variant < 3; variant++) {
-
-            const input_keys = make_keys(element_count, variant);
-            const input_values = new Uint32Array(element_count);
-            for (let i = 0; i < element_count; i++) {
-                input_values[i] = i;
-            }
-
-            const type = WebGPUArray.from(u32, element_count);
-            const label = `n=${element_count} variant=${variant}`;
-
-            const keys = graph_import_typed_buffer({
-                graph, type, value: input_keys, label: `verify sort keys ${label}`, usage
-            });
-            const values = graph_import_typed_buffer({
-                graph, type, value: input_values, label: `verify sort values ${label}`, usage
-            });
-
-            const sorted = graph_radix_sort({ graph, keys, values, element_count });
-
-            let sorted_keys;
-            let sorted_values;
-
-            function validate() {
-                if (sorted_keys === undefined || sorted_values === undefined) {
-                    // wait for both readbacks
-                    return;
-                }
-
-                const problems = problems_with(input_keys, sorted_keys, sorted_values);
-
-                if (problems.length === 0) {
-                    console.log(`%c[SORT] PASS ${label}`, 'color: #0c0');
-                } else {
-                    console.error(`[SORT] FAIL ${label}:\n  ${problems.join('\n  ')}`);
-                }
-            }
-
-            graph_inspect_gpu_buffer({
-                graph, type, buffer: sorted.keys,
-                callback([data]) {
-                    sorted_keys = data;
-                    validate();
-                }
-            });
-
-            graph_inspect_gpu_buffer({
-                graph, type, buffer: sorted.values,
-                callback([data]) {
-                    sorted_values = data;
-                    validate();
-                }
-            });
-        }
-    }
-
-    cmd.encodeGraph(graph);
-    cmd.finish();
-}
+import { FrameGraph } from "../../../../engine/graphics/render/frame_graph/FrameGraph.js";
+import { ShadeGPUCommandContext } from "../../../device/ShadeGPUCommandContext.js";
+import { u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { graph_inspect_gpu_buffer } from "../../buffer/graph_inspect_gpu_buffer.js";
+import { graph_import_typed_buffer } from "../../shader/graph/graph_import_typed_buffer.js";
+import { SORT_TILE_SIZE } from "./defs.js";
+import { graph_radix_sort } from "./graph_radix_sort.js";
+
+/**
+ * The element counts one run covers. The interesting ones are all at tile boundaries — the scatter's
+ * tail tile is padded, and a count one either side of an exact multiple is what exercises the
+ * padding guard from both directions.
+ *
+ * @type {number[]}
+ */
+const ELEMENT_COUNTS = [
+    2, 3, 255, 256, 257,
+    SORT_TILE_SIZE - 1, SORT_TILE_SIZE, SORT_TILE_SIZE + 1,
+    SORT_TILE_SIZE * 4 + 13,
+    100003,
+];
+
+/**
+ * Sorts by part of the key. Every key carries random bits above `key_bits`, which the order must not
+ * see; an odd number of digit passes leaves the result in the sort's own scratch.
+ *
+ * @type {{element_count: number, key_bits: number}[]}
+ */
+const KEY_WIDTH_CASES = [
+    { element_count: 3, key_bits: 1 },
+    { element_count: SORT_TILE_SIZE * 4 + 13, key_bits: 8 },
+    { element_count: SORT_TILE_SIZE * 4 + 13, key_bits: 20 },
+    { element_count: SORT_TILE_SIZE * 4 + 13, key_bits: 24 },
+    { element_count: 100003, key_bits: 24 },
+    { element_count: 100003, key_bits: 30 },
+];
+
+/**
+ * Sorts over a count the device holds, the `u32` at byte 4 of a buffer of its own, in buffers that
+ * hold `element_max_count`. Where the result is in the caller's buffers (an even number of digit
+ * passes), the entries past the count must be as they went in.
+ *
+ * @type {{element_max_count: number, count: number, key_bits: number, variant: number}[]}
+ */
+const DEVICE_COUNT_CASES = [
+    { element_max_count: 100003, count: 0, key_bits: 32, variant: 2 },
+    { element_max_count: 100003, count: 1, key_bits: 32, variant: 2 },
+    { element_max_count: 100003, count: SORT_TILE_SIZE * 4 + 13, key_bits: 32, variant: 0 },
+    { element_max_count: 100003, count: 100003, key_bits: 32, variant: 2 },
+    // past what the memory holds: the first element_max_count are sorted
+    { element_max_count: 5000, count: 9000, key_bits: 32, variant: 2 },
+    // the probe rays' budget, by a 24-bit key
+    { element_max_count: 131072, count: 0, key_bits: 24, variant: 2 },
+    { element_max_count: 131072, count: 70001, key_bits: 24, variant: 0 },
+    { element_max_count: 131072, count: 131072, key_bits: 24, variant: 2 },
+    { element_max_count: 131072, count: 70001, key_bits: 16, variant: 0 },
+];
+
+/**
+ * @param {number} seed
+ * @returns {function(): number} LCG, so a failing run is reproducible
+ */
+function make_random(seed) {
+    let state = seed >>> 0;
+
+    return () => (state = (state * 1664525 + 1013904223) >>> 0);
+}
+
+/**
+ * @param {number} key_bits
+ * @returns {number} the key's low `key_bits` set
+ */
+function key_mask_of(key_bits) {
+    return 2 ** key_bits - 1;
+}
+
+/**
+ * The key distribution for one case. Three shapes, because a radix sort fails differently under
+ * each: dense duplicates stress stability and the in-tile split's equal-digit runs, a single
+ * repeated key makes every tile one bin, and full-range keys are the only ones that reach the top
+ * digit pass at all.
+ *
+ * Whatever the shape, the bits above `key_bits` are random, so a sort that looked at them would
+ * order by them. They come from a generator of their own, so a whole-key case is the keys it always
+ * was.
+ *
+ * @param {number} element_count
+ * @param {number} variant
+ * @param {number} key_bits
+ * @returns {Uint32Array}
+ */
+function make_keys(element_count, variant, key_bits) {
+    const random = make_random(0x9e3779b9 ^ (element_count * 31 + variant));
+    const noise = make_random(0x85ebca6b ^ (element_count * 31 + variant + key_bits));
+
+    const key_mask = key_mask_of(key_bits);
+
+    const keys = new Uint32Array(element_count);
+
+    for (let i = 0; i < element_count; i++) {
+        let key;
+
+        if (variant === 0) {
+            key = random() % 1000;
+        } else if (variant === 1) {
+            key = 0x2a2a2a2a;
+        } else {
+            key = random();
+        }
+
+        keys[i] = ((key & key_mask) | (noise() & ~key_mask)) >>> 0;
+    }
+
+    return keys;
+}
+
+/**
+ * @param {Uint32Array} input_keys the keys that were sorted, and no more
+ * @param {number} key_mask the bits of a key the order is by
+ * @param {Uint32Array|number[]} sorted_keys at least as many as `input_keys`
+ * @param {Uint32Array|number[]} sorted_values at least as many as `input_keys`
+ * @returns {string[]} one entry per distinct problem found, empty when the sort is correct
+ */
+function problems_with(input_keys, key_mask, sorted_keys, sorted_values) {
+    const element_count = input_keys.length;
+
+    const problems = [];
+
+    const order = i => (sorted_keys[i] & key_mask) >>> 0;
+
+    for (let i = 1; i < element_count; i++) {
+        if (order(i) < order(i - 1)) {
+            problems.push(`keys not ascending at [${i}]: ${order(i - 1)} -> ${order(i)}`);
+            break;
+        }
+    }
+
+    const seen = new Uint8Array(element_count);
+    for (let i = 0; i < element_count; i++) {
+        const value = sorted_values[i];
+
+        if (value >= element_count || seen[value] === 1) {
+            problems.push(`payload is not a permutation at [${i}]: ${value}`);
+            break;
+        }
+
+        seen[value] = 1;
+    }
+
+    // the whole key travels with its payload, the bits the order ignores included
+    for (let i = 0; i < element_count; i++) {
+        if (input_keys[sorted_values[i]] !== sorted_keys[i]) {
+            problems.push(`key/payload pairing broken at [${i}]: payload ${sorted_values[i]} `
+                + `had key ${input_keys[sorted_values[i]]}, sorted key is ${sorted_keys[i]}`);
+            break;
+        }
+    }
+
+    // payload is the input index, so a stable sort leaves equal keys with ascending payloads
+    for (let i = 1; i < element_count; i++) {
+        if (order(i) === order(i - 1) && sorted_values[i] < sorted_values[i - 1]) {
+            problems.push(`not stable at [${i}]: key ${order(i)} came from index `
+                + `${sorted_values[i - 1]} then ${sorted_values[i]}`);
+            break;
+        }
+    }
+
+    return problems;
+}
+
+/**
+ * @param {Uint32Array} input_keys
+ * @param {Uint32Array} input_values
+ * @param {number} from the first entry the sort must not have written
+ * @param {Uint32Array|number[]} sorted_keys
+ * @param {Uint32Array|number[]} sorted_values
+ * @returns {string[]}
+ */
+function problems_past(input_keys, input_values, from, sorted_keys, sorted_values) {
+    for (let i = from; i < input_keys.length; i++) {
+        if (sorted_keys[i] !== input_keys[i] || sorted_values[i] !== input_values[i]) {
+            return [`written past the count at [${i}]: (${sorted_keys[i]}, ${sorted_values[i]}), `
+            + `was (${input_keys[i]}, ${input_values[i]})`];
+        }
+    }
+
+    return [];
+}
+
+/**
+ * Read a sort's result back and check it.
+ *
+ * @param {Object} options
+ * @param {FrameGraph} options.graph
+ * @param {string} options.label
+ * @param {{keys:number, values:number}} options.sorted
+ * @param {number} options.capacity entries in each buffer
+ * @param {Uint32Array} options.input_keys the whole of the caller's keys, `capacity` of them
+ * @param {Uint32Array} options.input_values the whole of the caller's values
+ * @param {number} options.sorted_count how many of them were sorted
+ * @param {number} options.key_mask
+ * @param {boolean} options.check_past whether the entries past `sorted_count` must be untouched — they
+ * are where the result is in the caller's buffers
+ */
+function check_sorted({
+                          graph,
+                          label,
+                          sorted,
+                          capacity,
+                          input_keys,
+                          input_values,
+                          sorted_count,
+                          key_mask,
+                          check_past,
+                      }) {
+    const type = WebGPUArray.from(u32, capacity);
+
+    let sorted_keys;
+    let sorted_values;
+
+    function validate() {
+        if (sorted_keys === undefined || sorted_values === undefined) {
+            // wait for both readbacks
+            return;
+        }
+
+        const problems = problems_with(input_keys.subarray(0, sorted_count), key_mask, sorted_keys, sorted_values);
+
+        if (check_past) {
+            problems.push(...problems_past(input_keys, input_values, sorted_count, sorted_keys, sorted_values));
+        }
+
+        if (problems.length === 0) {
+            console.log(`%c[SORT] PASS ${label}`, 'color: #0c0');
+        } else {
+            console.error(`[SORT] FAIL ${label}:\n  ${problems.join('\n  ')}`);
+        }
+    }
+
+    graph_inspect_gpu_buffer({
+        graph, type, buffer: sorted.keys, count: 1,
+        callback([data]) {
+            sorted_keys = data;
+            validate();
+        }
+    });
+
+    graph_inspect_gpu_buffer({
+        graph, type, buffer: sorted.values, count: 1,
+        callback([data]) {
+            sorted_values = data;
+            validate();
+        }
+    });
+}
+
+/**
+ * @param {number} element_count
+ * @returns {Uint32Array} `[0, element_count)`, so a payload names the input it came from
+ */
+function make_indices(element_count) {
+    const values = new Uint32Array(element_count);
+
+    for (let i = 0; i < element_count; i++) {
+        values[i] = i;
+    }
+
+    return values;
+}
+
+/**
+ * On-device verification of {@link graph_radix_sort}: sorts deterministic key/payload sets across
+ * tile-boundary element counts and three key distributions, reads the results back, and checks on
+ * the CPU that the keys are ascending, that the payload is a permutation of the input indices, that
+ * every payload still sits next to ITS key, and that equal keys kept their input order. Then the same
+ * by part of the key, with random bits above it, and over counts that live on the device — where the
+ * entries past the count must also come back as they went in.
+ *
+ * Logs one `[SORT]` PASS/FAIL line per case.
+ *
+ * @param {GraphicsContext} graphics
+ */
+export function verify_radix_sort(graphics) {
+
+    const graph = new FrameGraph();
+    const cmd = ShadeGPUCommandContext.create(graphics, 'verify/radix sort');
+
+    const usage = GPUBufferUsage.COPY_SRC | GPUBufferUsage.STORAGE;
+
+    /**
+     * @param {Uint32Array} data
+     * @param {string} label
+     * @returns {number}
+     */
+    function upload(data, label) {
+        return graph_import_typed_buffer({
+            graph, type: WebGPUArray.from(u32, data.length), value: data, label, usage
+        });
+    }
+
+    for (const element_count of ELEMENT_COUNTS) {
+        for (let variant = 0; variant < 3; variant++) {
+
+            const input_keys = make_keys(element_count, variant, 32);
+            const input_values = make_indices(element_count);
+
+            const label = `n=${element_count} variant=${variant}`;
+
+            const sorted = graph_radix_sort({
+                graph,
+                keys: upload(input_keys, `verify sort keys ${label}`),
+                values: upload(input_values, `verify sort values ${label}`),
+                element_count,
+            });
+
+            check_sorted({
+                graph, label, sorted,
+                capacity: element_count,
+                input_keys, input_values,
+                sorted_count: element_count,
+                key_mask: key_mask_of(32),
+                check_past: false,
+            });
+        }
+    }
+
+    for (const { element_count, key_bits } of KEY_WIDTH_CASES) {
+        for (let variant = 0; variant < 3; variant++) {
+
+            const input_keys = make_keys(element_count, variant, key_bits);
+            const input_values = make_indices(element_count);
+
+            const label = `n=${element_count} key_bits=${key_bits} variant=${variant}`;
+
+            const sorted = graph_radix_sort({
+                graph,
+                keys: upload(input_keys, `verify sort keys ${label}`),
+                values: upload(input_values, `verify sort values ${label}`),
+                element_count,
+                key_bits,
+            });
+
+            check_sorted({
+                graph, label, sorted,
+                capacity: element_count,
+                input_keys, input_values,
+                sorted_count: element_count,
+                key_mask: key_mask_of(key_bits),
+                check_past: false,
+            });
+        }
+    }
+
+    for (const { element_max_count, count, key_bits, variant } of DEVICE_COUNT_CASES) {
+
+        const input_keys = make_keys(element_max_count, variant, key_bits);
+        const input_values = make_indices(element_max_count);
+
+        const label = `device count=${count} of ${element_max_count} key_bits=${key_bits} variant=${variant}`;
+
+        const sorted = graph_radix_sort({
+            graph,
+            keys: upload(input_keys, `verify sort keys ${label}`),
+            values: upload(input_values, `verify sort values ${label}`),
+            count_buffer: upload(Uint32Array.of(0xdeadbeef, count, 0xdeadbeef, 0xdeadbeef), `verify sort count ${label}`),
+            count_offset: 4,
+            element_max_count,
+            key_bits,
+        });
+
+        const pass_count = Math.ceil(key_bits / 8);
+
+        check_sorted({
+            graph, label, sorted,
+            capacity: element_max_count,
+            input_keys, input_values,
+            sorted_count: Math.min(count, element_max_count),
+            key_mask: key_mask_of(key_bits),
+            // an even number of passes ends in the caller's buffers, and their tail is the caller's
+            check_past: pass_count % 2 === 0,
+        });
+    }
+
+    cmd.encodeGraph(graph);
+    cmd.finish();
+}

package/src/shade/renderer/light/world_cluster/chunk_world_light_cluster_lookup.d.ts

@@ -7,6 +7,19 @@ export const WORLD_CLUSTER_DATA_RESOURCE: ShaderResourceDescriptor;
  * @type {CodeChunk}
  */
 export const chunk_world_light_cluster_lookup: CodeChunk;
+/**
+ * The world-space light cluster cell holding a world position, in cascade `cascade` of the clipmap the
+ * clusters were built over: `level` is that cascade's window, `border` the build's.
+ *
+ * ```wgsl
+ * fn world_light_cluster_metadata_at(cascade: u32, level: ClipmapLevel, border: f32, position: vec3<f32>) -> LightClusterMetadata
+ * ```
+ *
+ * A position past the cascade's cells takes the nearest one.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_world_light_cluster_lookup_at: CodeChunk;
 import { ShaderResourceDescriptor } from "../../shader/resource/ShaderResourceDescriptor.js";
 import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
 //# sourceMappingURL=chunk_world_light_cluster_lookup.d.ts.map

package/src/shade/renderer/light/world_cluster/chunk_world_light_cluster_lookup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_world_light_cluster_lookup.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/light/world_cluster/chunk_world_light_cluster_lookup.js"],"names":[],"mappings":"AAQA,qEAIE;AAEF,mEAIE;AAEF;;;;;GAKG;AACH,+CAFU,SAAS,CA6BjB;yCAnDuC,mDAAmD;0BADlE,oCAAoC"}
+{"version":3,"file":"chunk_world_light_cluster_lookup.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/light/world_cluster/chunk_world_light_cluster_lookup.js"],"names":[],"mappings":"AASA,qEAIE;AAEF,mEAIE;AAEF;;;;;GAKG;AACH,+CAFU,SAAS,CA6BjB;AAIF;;;;;;;;;;;GAWG;AACH,kDAFU,SAAS,CAyBjB;yCA1FuC,mDAAmD;0BADlE,oCAAoC"}

package/src/shade/renderer/light/world_cluster/chunk_world_light_cluster_lookup.js

@@ -1,3 +1,4 @@
+import { CLIPMAP_LEVEL_STRUCT } from "../../shader/chunk/clipmap/CLIPMAP_LEVEL_STRUCT.js";
 import { chunk_grid3d_to_index } from "../../shader/chunk/grid/chunk_grid3d_to_index.js";
 import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
 import { ShaderResourceDescriptor } from "../../shader/resource/ShaderResourceDescriptor.js";
@@ -54,3 +55,42 @@ fn world_light_cluster_metadata_by_texel(
 );
 
 chunk_world_light_cluster_lookup.requireResource(WORLD_CLUSTER_LOOKUP_RESOURCE);
+
+/**
+ * The world-space light cluster cell holding a world position, in cascade `cascade` of the clipmap the
+ * clusters were built over: `level` is that cascade's window, `border` the build's.
+ *
+ * ```wgsl
+ * fn world_light_cluster_metadata_at(cascade: u32, level: ClipmapLevel, border: f32, position: vec3<f32>) -> LightClusterMetadata
+ * ```
+ *
+ * A position past the cascade's cells takes the nearest one.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_world_light_cluster_lookup_at = CodeChunk.from(
+    //language=WGSL
+    `
+fn world_light_cluster_metadata_at(
+    cascade: u32,
+    level: ${CLIPMAP_LEVEL_STRUCT.wgsl_ref},
+    border: f32,
+    position: vec3<f32>,
+) -> ${LIGHT_CLUSTER_METADATA.wgsl_ref} {
+    let box_min = (vec3<f32>(level.corner) - vec3<f32>(border)) * level.cell_size;
+    let cluster_cell_size = (vec3<f32>(level.size) + vec3<f32>(2.0 * border)) * (level.cell_size / ${WORLD_LIGHT_CLUSTER_GRID_SIZE}.0);
+    let cell = vec3<u32>(clamp(floor((position - box_min) / cluster_cell_size), vec3<f32>(0.0), vec3<f32>(${WORLD_LIGHT_CLUSTER_GRID_SIZE - 1}.0)));
+
+    return world_cluster_lookup[grid3d_to_index(
+        vec3<u32>(cell.xy, cascade * ${WORLD_LIGHT_CLUSTER_GRID_SIZE}u + cell.z),
+        vec2<u32>(${WORLD_LIGHT_CLUSTER_GRID_SIZE}u)
+    )];
+}
+`, [
+        CLIPMAP_LEVEL_STRUCT.declaration_chunk,
+        LIGHT_CLUSTER_METADATA.declaration_chunk,
+        chunk_grid3d_to_index,
+    ]
+);
+
+chunk_world_light_cluster_lookup_at.requireResource(WORLD_CLUSTER_LOOKUP_RESOURCE);