@woosh/meep-engine 3.64.1 → 3.67.0

package/src/shade/renderer/geometry/sdf/bundle/model_cache_bundle_sort_morton.js

@@ -0,0 +1,247 @@
+import { assert } from "../../../../../core/assert.js";
+import { v3_morton_encode_magicbits } from "../../../../../core/geom/3d/morton/v3_morton_encode_magicbits.js";
+import { MESH_SDF_BRICK_TEXEL_COUNT, MESH_SDF_EMPTY } from "../MESH_SDF.js";
+import {
+    MESH_SURFACE_PLANE_BLOCK_WORDS,
+    MESH_SURFACE_PRESENCE_BLOCK_WORDS,
+    MESH_SURFACE_TABLE_MASK_BITS
+} from "../surface/MESH_SURFACE_BLOCK.js";
+import { ModelCacheBundle, ModelCacheBundleCache, ModelCacheBundleField } from "./ModelCacheBundle.js";
+
+/**
+ * Bricks along an axis a level's Morton code holds: 10 bits an axis.
+ * @type {number}
+ */
+const MORTON_AXIS_LIMIT = 1 << 10;
+
+/**
+ * @param {number} v
+ * @returns {number}
+ */
+function popcount8(v) {
+    let c = 0;
+
+    for (let b = 0; b < 8; b++) {
+        c += (v >>> b) & 1;
+    }
+
+    return c;
+}
+
+/**
+ * Each entry's place in (level, Morton code of its brick) order, levels coarsening as `MeshSDFLayout`'s
+ * do: level k has ⌈bricks / 2^k⌉ along each axis, its entries after every finer level's, x fastest.
+ *
+ * @param {ModelCacheBundleField} field
+ * @returns {Float64Array} a key an entry
+ */
+function entry_keys(field) {
+    const keys = new Float64Array(field.entries.length);
+
+    let e = 0;
+
+    for (let level = 0; level < field.level_count; level++) {
+        const nx = Math.ceil(field.bricks[0] / 2 ** level);
+        const ny = Math.ceil(field.bricks[1] / 2 ** level);
+        const nz = Math.ceil(field.bricks[2] / 2 ** level);
+
+        assert.ok(nx <= MORTON_AXIS_LIMIT && ny <= MORTON_AXIS_LIMIT && nz <= MORTON_AXIS_LIMIT, 'field.bricks: past the 10 bits an axis a Morton code holds');
+
+        for (let z = 0; z < nz; z++) {
+            for (let y = 0; y < ny; y++) {
+                for (let x = 0; x < nx; x++) {
+                    // 30 bits of code under the level: exact in a double
+                    keys[e++] = level * 2 ** 30 + v3_morton_encode_magicbits(x, y, z);
+                }
+            }
+        }
+    }
+
+    assert.equal(e, field.entries.length, 'field.entries: one a brick of its levels');
+
+    return keys;
+}
+
+/**
+ * `words` holding `per_block` words for each block, its blocks moved: run r of `runs` (old first block,
+ * new first block, blocks) from its old place to its new.
+ *
+ * @param {Uint32Array} words
+ * @param {number} per_block
+ * @param {number} blocks
+ * @param {number[]|null} runs null for a field with no table, whose blocks no brick numbers
+ * @returns {Uint32Array}
+ */
+function move_blocks(words, per_block, blocks, runs) {
+    if (words.length === 0 || runs === null) {
+        return words.slice();
+    }
+
+    assert.equal(words.length, blocks * per_block, 'a cache\'s blocks: its field\'s, each of its plane\'s words');
+
+    const out = new Uint32Array(words.length);
+
+    for (let r = 0; r < runs.length; r += 3) {
+        out.set(words.subarray(runs[r] * per_block, (runs[r] + runs[r + 2]) * per_block), runs[r + 1] * per_block);
+    }
+
+    return out;
+}
+
+/**
+ * A copy of a {@link ModelCacheBundle} laid out for locality, holding the same fields and caches: what
+ * every entry reads, the bytes of its brick and its surface blocks, is unchanged.
+ *
+ * - each field's stored bricks are numbered in (level, Morton code of the brick) order, and its block
+ *   table and its caches' blocks follow: a brick's blocks keep its mask and come in number order;
+ * - the bundle's bricks are ordered as the fields first name them, field by field in that numbering,
+ *   with bricks no field names after them. `upload_bundle` places a bundle's bricks in that order, and its
+ *   fresh pass pops their slots in about that order (an atomic a thread), so a field's neighbouring bricks
+ *   mostly sit in neighbouring slots.
+ *
+ * Measured (2026-11-11, a 69k-brick library loaded into the probe clipmap on an RTX 4090 and a Radeon
+ * RDNA2 iGPU): the SDF batch pass does not change, and the brick material gather is about 0.5% faster.
+ * Bake order is already near this one, so the sort is for offline asset preparation, where it costs
+ * nothing at load, and is off unless asked for (`GPUGeometrySDFManager.export_bundle`).
+ *
+ * @param {ModelCacheBundle} bundle
+ * @returns {ModelCacheBundle} a new bundle; `bundle` is left as it was
+ */
+export function model_cache_bundle_sort_morton(bundle) {
+    const out = new ModelCacheBundle();
+
+    out.voxel_size = bundle.voxel_size;
+    out.max_bricks = bundle.max_bricks;
+
+    const brick_count = bundle.brick_count;
+    /** the new index of each old brick, -1 until a field names it */
+    const brick_to = new Int32Array(brick_count).fill(-1);
+    let next_brick = 0;
+
+    /** each field's runs of moved blocks, for its caches */
+    const field_runs = [];
+
+    for (let f = 0; f < bundle.fields.length; f++) {
+        const field = bundle.fields[f];
+        const stored = field.numbered.length;
+        const keys = entry_keys(field);
+
+        // brick n's new number is its place in key order; entries are distinct, so no two keys tie
+        const order = Array.from({ length: stored }, (_, n) => n);
+
+        order.sort((a, b) => keys[field.numbered[a]] - keys[field.numbered[b]]);
+
+        const sorted = new ModelCacheBundleField();
+
+        sorted.origin.set(field.origin);
+        sorted.voxel = field.voxel;
+        sorted.bricks.set(field.bricks);
+        sorted.level_count = field.level_count;
+        sorted.two_sided = field.two_sided;
+        sorted.blocks = field.blocks;
+        sorted.numbered = new Uint32Array(stored);
+
+        for (let m = 0; m < stored; m++) {
+            sorted.numbered[m] = field.numbered[order[m]];
+        }
+
+        // without a table no block is numbered by a brick: a cache's blocks, if any, stay where they are
+        let runs = null;
+
+        if (field.table.length > 0) {
+            runs = [];
+            assert.equal(field.table.length, stored, 'field.table: a word a stored brick, or none');
+
+            sorted.table = new Uint32Array(stored);
+
+            // every block in exactly one brick's run, as a survey hands them out: what moves them losslessly
+            const covered = new Uint8Array(field.blocks);
+
+            let first = 0;
+
+            for (let m = 0; m < stored; m++) {
+                const word = field.table[order[m]];
+                const mask = word & ((1 << MESH_SURFACE_TABLE_MASK_BITS) - 1);
+                const count = popcount8(mask);
+                const from = word >>> MESH_SURFACE_TABLE_MASK_BITS;
+
+                sorted.table[m] = ((first << MESH_SURFACE_TABLE_MASK_BITS) | mask) >>> 0;
+
+                if (count > 0) {
+                    assert.lessThanOrEqual(from + count, field.blocks, 'field.table: a run past the field\'s blocks');
+
+                    for (let b = from; b < from + count; b++) {
+                        assert.equal(covered[b], 0, 'field.table: two bricks\' runs share a block');
+                        covered[b] = 1;
+                    }
+
+                    runs.push(from, first, count);
+                }
+
+                first += count;
+            }
+
+            assert.equal(first, field.blocks, 'field.blocks: the blocks its table\'s masks keep');
+        }
+
+        field_runs.push(runs);
+
+        // the bricks as this field first names them, in its new numbering
+        for (let m = 0; m < stored; m++) {
+            const brick = field.entries[sorted.numbered[m]];
+
+            assert.lessThan(brick, brick_count, 'a numbered entry names a brick of the bundle');
+
+            if (brick_to[brick] === -1) {
+                brick_to[brick] = next_brick++;
+            }
+        }
+
+        out.fields.push(sorted);
+    }
+
+    // bricks no field numbers: after the rest, as they were
+    for (let b = 0; b < brick_count; b++) {
+        if (brick_to[b] === -1) {
+            brick_to[b] = next_brick++;
+        }
+    }
+
+    out.bricks = new Uint8Array(bundle.bricks.length);
+
+    for (let b = 0; b < brick_count; b++) {
+        out.bricks.set(bundle.bricks.subarray(b * MESH_SDF_BRICK_TEXEL_COUNT, (b + 1) * MESH_SDF_BRICK_TEXEL_COUNT), brick_to[b] * MESH_SDF_BRICK_TEXEL_COUNT);
+    }
+
+    for (let f = 0; f < bundle.fields.length; f++) {
+        const entries = bundle.fields[f].entries;
+        const renamed = new Uint32Array(entries.length);
+
+        for (let e = 0; e < entries.length; e++) {
+            const entry = entries[e];
+
+            renamed[e] = entry < MESH_SDF_EMPTY ? brick_to[entry] : entry;
+        }
+
+        out.fields[f].entries = renamed;
+    }
+
+    for (const cache of bundle.caches) {
+        const sorted = new ModelCacheBundleCache();
+        const runs = field_runs[cache.field];
+        const blocks = bundle.fields[cache.field].blocks;
+
+        sorted.field = cache.field;
+        sorted.texels = cache.texels;
+        sorted.codes.set(cache.codes);
+        sorted.presence = move_blocks(cache.presence, MESH_SURFACE_PRESENCE_BLOCK_WORDS, blocks, runs);
+
+        for (let p = 0; p < cache.planes.length; p++) {
+            sorted.planes[p] = move_blocks(cache.planes[p], MESH_SURFACE_PLANE_BLOCK_WORDS[p], blocks, runs);
+        }
+
+        out.caches.push(sorted);
+    }
+
+    return out;
+}

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

@@ -88,6 +88,56 @@ export class GPUProbeClipmapGI {
      * @returns {boolean}
      */
     get has_probes(): boolean;
+    /**
+     * Record the wants of a screen surface drawn apart from the G-buffer whose reader picks the frustum's probes a
+     * pixel (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.3): the water's interface. A pixel of each screen tile wants
+     * the cages its pick reads, as the G-buffer's pixels do (`ProbeClipmapScreenWants`).
+     *
+     * For a pass after this frame's {@link graph_update}, once the surface is drawn. Its wants are taken by the
+     * next frame's lifetime, so a probe the surface newly reads is there a frame after the surface is. Records
+     * nothing where there are no probes ({@link has_probes}): out of the mode it costs nothing.
+     *
+     * @param {Object} options
+     * @param {FrameGraph} options.graph
+     * @param {number} options.depth graph handle of the surface's reverse-Z depth, zero where it has none
+     * @param {number} options.normal graph handle of its normals, a `uint` texture: a channel holds a normal
+     *   octahedral, as the G-buffer packs its own
+     * @param {number} [options.normal_channel] the channel that holds the normal, 0 to 3
+     * @param {boolean} [options.two_sided] whether the reader turns a normal that faces away from the eye to face it
+     * @param {GPUBuffer} options.camera the camera uniform the surface was drawn with
+     * @param {ArrayLike<number>} options.resolution the surface's pixels, x and y
+     */
+    graph_want_surface({ graph, depth, normal, normal_channel, two_sided, camera, resolution }: {
+        graph: FrameGraph;
+        depth: number;
+        normal: number;
+        normal_channel?: number;
+        two_sided?: boolean;
+        camera: GPUBuffer;
+        resolution: ArrayLike<number>;
+    }): void;
+    /**
+     * Record the wants of a list of meshlets a forward pass draws, whose fragments pick the frustum's probes
+     * (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.3): each wants the cages a reader anywhere inside its box can
+     * read (`graph_probe_clipmap_want_meshlets`).
+     *
+     * For a pass after this frame's {@link graph_update}; taken by the next frame's lifetime, as
+     * {@link graph_want_surface}'s are. Records nothing where there are no probes ({@link has_probes}).
+     *
+     * @param {Object} options
+     * @param {FrameGraph} options.graph
+     * @param {import("../../scene/GPUSceneContext.js").GPUSceneContext} options.scene the meshlets' scene
+     * @param {number} options.camera graph handle of the view's camera uniform
+     * @param {number} options.meshlet_collection graph handle of the list, `MESHLET_COLLECTION_STRUCT`
+     * @param {number} options.meshlet_iterator_command graph handle of the indirect dispatch that walks the list
+     */
+    graph_want_meshlets({ graph, scene, camera, meshlet_collection, meshlet_iterator_command }: {
+        graph: FrameGraph;
+        scene: import("../../scene/GPUSceneContext.js").GPUSceneContext;
+        camera: number;
+        meshlet_collection: number;
+        meshlet_iterator_command: number;
+    }): void;
     /**
      * Put what the probes' readers bind into `bindings`, `PROBE_CLIPMAP_SAMPLING_GROUP` but its sampler:
      * once {@link has_probes}, the probes as this frame's {@link graph_update} left them

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":"AA8BA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH;IAwTI;;;;OAIG;IACH,oDAJW,eAAe,YACf,oBAAoB,GAClB,OAAO,CAUnB;IA5OD;;OAEG;IACH,sBAFW,eAAe,EAMzB;IAED;;OAEG;IACH,qCAEC;IAED;;OAEG;IACH,qCAEC;IAED;;OAEG;IACH,mCAEC;IAED;;OAEG;IACH,oCAEC;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH;QAZ+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;QAEU,QAAQ,EAAxB,MAAM;aAsIhB;IAqDD;;;OAGG;IACH,0BAEC;IAED;;;;;;;;;OASG;IACH,4CAUC;IAwDD;;;;;;;;;;;;;;;;OAgBG;IACH;QAR+B,KAAK,EAAzB,UAAU;QACc,IAAI,EAA5B,cAAc;QACgB,QAAQ,EAAtC,oBAAoB;QACF,UAAU,EAA5B,MAAM,EAAE;QACQ,QAAQ;QACtB,MAAM,CA8ClB;IAED;;;;;OAKG;IACH,uBAFW,aAAa,QASvB;IAED;;;OAGG;IACH,0BAHW,aAAa,GACX,OAAO,CAanB;IAqED;;;OAGG;IACH,gBA2BC;IAED,gBAcC;;CACJ;yBA1oBY,OAAO,8DAA8D,EAAE,UAAU;8BACjF,OAAO,0BAA0B,EAAE,eAAe;6BAClD,OAAO,8BAA8B,EAAE,cAAc;mCACrD,OAAO,2BAA2B,EAAE,oBAAoB;4BACxD,OAAO,4BAA4B,EAAE,aAAa;gCA1B/B,4BAA4B;gCAa5B,4BAA4B;uCAKrB,6BAA6B"}
+{"version":3,"file":"GPUProbeClipmapGI.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/global_illumination/probe_clipmap/GPUProbeClipmapGI.js"],"names":[],"mappings":"AA+BA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH;IAsUI;;;;OAIG;IACH,oDAJW,eAAe,YACf,oBAAoB,GAClB,OAAO,CAUnB;IA/OD;;OAEG;IACH,sBAFW,eAAe,EAMzB;IAED;;OAEG;IACH,qCAEC;IAED;;OAEG;IACH,qCAEC;IAED;;OAEG;IACH,mCAEC;IAED;;OAEG;IACH,oCAEC;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH;QAZ+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;QAEU,QAAQ,EAAxB,MAAM;aAyIhB;IAqDD;;;OAGG;IACH,0BAEC;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH;QAT+B,KAAK,EAAzB,UAAU;QACM,KAAK,EAArB,MAAM;QACU,MAAM,EAAtB,MAAM;QAEW,cAAc,GAA/B,MAAM;QACY,SAAS,GAA3B,OAAO;QACY,MAAM;QACE,UAAU,EAArC,UAAU,MAAM,CAAC;aAmC3B;IAED;;;;;;;;;;;;;;OAcG;IACH;QAN+B,KAAK,EAAzB,UAAU;QACwD,KAAK,EAAvE,OAAO,gCAAgC,EAAE,eAAe;QACxC,MAAM,EAAtB,MAAM;QACU,kBAAkB,EAAlC,MAAM;QACU,wBAAwB,EAAxC,MAAM;aAiBhB;IAED;;;;;;;;;OASG;IACH,4CAUC;IAwDD;;;;;;;;;;;;;;;;OAgBG;IACH;QAR+B,KAAK,EAAzB,UAAU;QACc,IAAI,EAA5B,cAAc;QACgB,QAAQ,EAAtC,oBAAoB;QACF,UAAU,EAA5B,MAAM,EAAE;QACQ,QAAQ;QACtB,MAAM,CA8ClB;IAED;;;;;OAKG;IACH,uBAFW,aAAa,QASvB;IAED;;;OAGG;IACH,0BAHW,aAAa,GACX,OAAO,CAanB;IAqED;;;OAGG;IACH,gBA2BC;IAED,gBAcC;;CACJ;yBA9uBY,OAAO,8DAA8D,EAAE,UAAU;8BACjF,OAAO,0BAA0B,EAAE,eAAe;6BAClD,OAAO,8BAA8B,EAAE,cAAc;mCACrD,OAAO,2BAA2B,EAAE,oBAAoB;4BACxD,OAAO,4BAA4B,EAAE,aAAa;gCA3B/B,4BAA4B;gCAa5B,4BAA4B;uCAMrB,6BAA6B"}

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

@@ -21,6 +21,7 @@ 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 { graph_probe_clipmap_want_meshlets } from "./probe/graph_probe_clipmap_want_meshlets.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 { ProbeClipmapIndirectLobe } from "./probe/ProbeClipmapIndirectLobe.js";
@@ -88,6 +89,17 @@ export class GPUProbeClipmapGI {
     /** The world cache's wants, the frustum's hits. @type {ProbeClipmapHitWants|undefined} */
     #hit_wants = undefined;
 
+    /**
+     * The frustum's wants from surfaces drawn apart from the G-buffer ({@link graph_want_surface}), each with what
+     * its pass keeps from frame to frame; the first {@link #surface_wants_used} are this frame's.
+     * @type {{wants: ProbeClipmapScreenWants, data: Object, bindings: Object, execute: function}[]}
+     */
+    #surface_wants = [];
+    #surface_wants_used = 0;
+
+    /** The frame's blue noise, which the surfaces' wants pick their pixels by. */
+    #stbn = null;
+
     /** 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];
@@ -316,6 +328,9 @@ export class GPUProbeClipmapGI {
 
         this.#screen_wants.set({ depth, normal, camera: view.camera.buffer, stbn, resolution: view.resolution });
 
+        this.#stbn = stbn;
+        this.#surface_wants_used = 0;
+
         frustum.graph_update({
             graph,
             wants: this.#screen_wants,
@@ -394,6 +409,92 @@ export class GPUProbeClipmapGI {
         return this.#probe_clipmap !== undefined;
     }
 
+    /**
+     * Record the wants of a screen surface drawn apart from the G-buffer whose reader picks the frustum's probes a
+     * pixel (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.3): the water's interface. A pixel of each screen tile wants
+     * the cages its pick reads, as the G-buffer's pixels do (`ProbeClipmapScreenWants`).
+     *
+     * For a pass after this frame's {@link graph_update}, once the surface is drawn. Its wants are taken by the
+     * next frame's lifetime, so a probe the surface newly reads is there a frame after the surface is. Records
+     * nothing where there are no probes ({@link has_probes}): out of the mode it costs nothing.
+     *
+     * @param {Object} options
+     * @param {FrameGraph} options.graph
+     * @param {number} options.depth graph handle of the surface's reverse-Z depth, zero where it has none
+     * @param {number} options.normal graph handle of its normals, a `uint` texture: a channel holds a normal
+     *   octahedral, as the G-buffer packs its own
+     * @param {number} [options.normal_channel] the channel that holds the normal, 0 to 3
+     * @param {boolean} [options.two_sided] whether the reader turns a normal that faces away from the eye to face it
+     * @param {GPUBuffer} options.camera the camera uniform the surface was drawn with
+     * @param {ArrayLike<number>} options.resolution the surface's pixels, x and y
+     */
+    graph_want_surface({ graph, depth, normal, normal_channel = 0, two_sided = false, camera, resolution }) {
+        assert.defined(graph, 'graph');
+
+        if (!this.has_probes) {
+            return;
+        }
+
+        const index = this.#surface_wants_used++;
+
+        if (index === this.#surface_wants.length) {
+            const entry = {
+                wants: new ProbeClipmapScreenWants(),
+                data: {},
+                bindings: {},
+                execute: (data, resources, context) => {
+                    // as the frustum's clipmap holds its late set now
+                    entry.wants.encode(context.encoder, data, resources, this.#probe_clipmap.write_want_bindings(entry.bindings));
+                },
+            };
+
+            this.#surface_wants.push(entry);
+        }
+
+        const entry = this.#surface_wants[index];
+
+        entry.wants.set({ depth, normal, normal_channel, two_sided, camera, stbn: this.#stbn, resolution });
+
+        const pass = graph.add("Probe Clipmap Want Surface", entry.data, entry.execute);
+
+        entry.wants.graph_declare(pass, entry.data);
+
+        // it writes the clipmap's own late set, which the graph does not hold
+        pass.make_side_effect();
+    }
+
+    /**
+     * Record the wants of a list of meshlets a forward pass draws, whose fragments pick the frustum's probes
+     * (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8.3): each wants the cages a reader anywhere inside its box can
+     * read (`graph_probe_clipmap_want_meshlets`).
+     *
+     * For a pass after this frame's {@link graph_update}; taken by the next frame's lifetime, as
+     * {@link graph_want_surface}'s are. Records nothing where there are no probes ({@link has_probes}).
+     *
+     * @param {Object} options
+     * @param {FrameGraph} options.graph
+     * @param {import("../../scene/GPUSceneContext.js").GPUSceneContext} options.scene the meshlets' scene
+     * @param {number} options.camera graph handle of the view's camera uniform
+     * @param {number} options.meshlet_collection graph handle of the list, `MESHLET_COLLECTION_STRUCT`
+     * @param {number} options.meshlet_iterator_command graph handle of the indirect dispatch that walks the list
+     */
+    graph_want_meshlets({ graph, scene, camera, meshlet_collection, meshlet_iterator_command }) {
+        assert.defined(graph, 'graph');
+
+        if (!this.has_probes) {
+            return;
+        }
+
+        graph_probe_clipmap_want_meshlets({
+            graph,
+            clipmap: this.#probe_clipmap,
+            scene,
+            camera,
+            meshlet_collection,
+            meshlet_iterator_command,
+        });
+    }
+
     /**
      * Put what the probes' readers bind into `bindings`, `PROBE_CLIPMAP_SAMPLING_GROUP` but its sampler:
      * once {@link has_probes}, the probes as this frame's {@link graph_update} left them

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

@@ -210,7 +210,8 @@ export class ProbeClipmapSettings {
     /**
      * Rays the frustum's probes trace a frame at most, `FRUSTUM_RAY_BUDGET_FRACTION` of {@link ray_budget}
      * rounded down, so `floor(frustum_ray_budget / rays_per_probe)` of them update a frame and every wanted one
-     * is traced again after as many frames as that takes.
+     * is traced again after as many frames as that takes, an idle one, live and wanted by nothing, once in
+     * `probe_clipmap_idle_periods` of those.
      * @returns {number}
      */
     get frustum_ray_budget(): number;

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

@@ -1 +1 @@
-{"version":3,"file":"ProbeClipmapSettings.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/global_illumination/probe_clipmap/ProbeClipmapSettings.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;GAgBG;AACH;IAaI;;;OAGG;IACH,mCAIC;IAjBD;;;;OAIG;IACH,kCAEC;IAsBD;;;OAGG;IACH,wCAKC;IAjBD;;;OAGG;IACH,uCAEC;IAyBD;;OAEG;IACH,gCAKC;IAlBD;;;;;OAKG;IACH,+BAEC;IAuBD;;OAEG;IACH,kCAIC;IAhBD;;;;OAIG;IACH,iCAEC;IAuBD;;OAEG;IACH,mCAKC;IAlBD;;;;;OAKG;IACH,kCAEC;IAyBD;;;OAGG;IACH,mCAMC;IArBD;;;;;;OAMG;IACH,kCAEC;IAsCD;;;OAGG;IACH,oCAKC;IA/BD;;;;;;;;;;;;;;;;;OAiBG;IACH,mCAEC;IAsCD;;;OAGG;IACH,mCAIC;IA/BD;;;;;;;;;;;;;;;;;;OAkBG;IACH,kCAEC;IAuBD;;;OAGG;IACH,mCAIC;IAjBD;;;;OAIG;IACH,kCAEC;IAsBD;;;OAGG;IACH,wCAKC;IAjBD;;;OAGG;IACH,uCAEC;IAyBD;;OAEG;IACH,6BAKC;IAlBD;;;;;OAKG;IACH,4BAEC;IAuBD;;;OAGG;IACH,mCAMC;IAnBD;;;;OAIG;IACH,kCAEC;IAyBD;;OAEG;IACH,gCAKC;IAjBD;;;;OAIG;IACH,+BAEC;IAuBD;;;;OAIG;IACH,8BAKC;IAnBD;;;;OAIG;IACH,6BAEC;IAyBD;;;OAGG;IACH,0BAIC;IAjBD;;;;OAIG;IACH,yBAEC;IAYD;;;;;OAKG;IACH,iCAEC;IAED;;;OAGG;IACH,+BAEC;IAeD;;;OAGG;IACH,yCAIC;IAnBD;;;;;;OAMG;IACH,wCAEC;IAuBD;;OAEG;IACH,+CAMC;IAlBD;;;;OAIG;IACH,8CAEC;IAwBD;;OAEG;IACH,4CAKC;IAjBD;;;;OAIG;IACH,2CAEC;IAuBD;;;OAGG;IACH,0CAKC;IAlBD;;;;OAIG;IACH,yCAEC;IA2BD;;OAEG;IACH,+BAKC;IApBD;;;;;;;OAOG;IACH,8BAEC;IAyBD;;OAEG;IACH,mCAIC;IAlBD;;;;;;OAMG;IACH,kCAEC;IAwBD;;OAEG;IACH,+BAIC;IAlBD;;;;;;OAMG;IACH,8BAEC;IAsBD;;OAEG;IACH,0BAIC;IAhBD;;;;OAIG;IACH,yBAEC;;CAUJ"}
+{"version":3,"file":"ProbeClipmapSettings.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/global_illumination/probe_clipmap/ProbeClipmapSettings.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;GAgBG;AACH;IAaI;;;OAGG;IACH,mCAIC;IAjBD;;;;OAIG;IACH,kCAEC;IAsBD;;;OAGG;IACH,wCAKC;IAjBD;;;OAGG;IACH,uCAEC;IAyBD;;OAEG;IACH,gCAKC;IAlBD;;;;;OAKG;IACH,+BAEC;IAuBD;;OAEG;IACH,kCAIC;IAhBD;;;;OAIG;IACH,iCAEC;IAuBD;;OAEG;IACH,mCAKC;IAlBD;;;;;OAKG;IACH,kCAEC;IAyBD;;;OAGG;IACH,mCAMC;IArBD;;;;;;OAMG;IACH,kCAEC;IAsCD;;;OAGG;IACH,oCAKC;IA/BD;;;;;;;;;;;;;;;;;OAiBG;IACH,mCAEC;IAsCD;;;OAGG;IACH,mCAIC;IA/BD;;;;;;;;;;;;;;;;;;OAkBG;IACH,kCAEC;IAuBD;;;OAGG;IACH,mCAIC;IAjBD;;;;OAIG;IACH,kCAEC;IAsBD;;;OAGG;IACH,wCAKC;IAjBD;;;OAGG;IACH,uCAEC;IAyBD;;OAEG;IACH,6BAKC;IAlBD;;;;;OAKG;IACH,4BAEC;IAuBD;;;OAGG;IACH,mCAMC;IAnBD;;;;OAIG;IACH,kCAEC;IAyBD;;OAEG;IACH,gCAKC;IAjBD;;;;OAIG;IACH,+BAEC;IAuBD;;;;OAIG;IACH,8BAKC;IAnBD;;;;OAIG;IACH,6BAEC;IAyBD;;;OAGG;IACH,0BAIC;IAjBD;;;;OAIG;IACH,yBAEC;IAYD;;;;;;OAMG;IACH,iCAEC;IAED;;;OAGG;IACH,+BAEC;IAeD;;;OAGG;IACH,yCAIC;IAnBD;;;;;;OAMG;IACH,wCAEC;IAuBD;;OAEG;IACH,+CAMC;IAlBD;;;;OAIG;IACH,8CAEC;IAwBD;;OAEG;IACH,4CAKC;IAjBD;;;;OAIG;IACH,2CAEC;IAuBD;;;OAGG;IACH,0CAKC;IAlBD;;;;OAIG;IACH,yCAEC;IA2BD;;OAEG;IACH,+BAKC;IApBD;;;;;;;OAOG;IACH,8BAEC;IAyBD;;OAEG;IACH,mCAIC;IAlBD;;;;;;OAMG;IACH,kCAEC;IAwBD;;OAEG;IACH,+BAIC;IAlBD;;;;;;OAMG;IACH,8BAEC;IAsBD;;OAEG;IACH,0BAIC;IAhBD;;;;OAIG;IACH,yBAEC;;CAUJ"}

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

@@ -379,7 +379,8 @@ export class ProbeClipmapSettings {
     /**
      * Rays the frustum's probes trace a frame at most, `FRUSTUM_RAY_BUDGET_FRACTION` of {@link ray_budget}
      * rounded down, so `floor(frustum_ray_budget / rays_per_probe)` of them update a frame and every wanted one
-     * is traced again after as many frames as that takes.
+     * is traced again after as many frames as that takes, an idle one, live and wanted by nothing, once in
+     * `probe_clipmap_idle_periods` of those.
      * @returns {number}
      */
     get frustum_ray_budget() {

package/src/shade/renderer/global_illumination/probe_clipmap/brick/GPUBrickClipmap.d.ts

@@ -121,6 +121,14 @@ export class GPUBrickClipmap {
      * @returns {Object} bindings
      */
     write_bindings(bindings: any): any;
+    /**
+     * The atlas's footprint as `tile_atlas_slot_shift` packs it: what every reader of the bricks takes in
+     * its immediate data as `brick_atlas_shift` and passes to `chunk_brick_clipmap_sample`. It changes
+     * only when a grow widens the atlas, in {@link graph_update}: take it after that, each frame, as the
+     * atlas itself.
+     * @returns {number}
+     */
+    get atlas_shift(): number;
     /**
      * Slots of the atlas.
      * @returns {number}

package/src/shade/renderer/global_illumination/probe_clipmap/brick/GPUBrickClipmap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUBrickClipmap.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/brick/GPUBrickClipmap.js"],"names":[],"mappings":"AA6FA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH;;;GAGG;AAEH;;;;;;;;GAQG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH;IAkKI;;;;;;;;OAQG;IACH;QAN2B,aAAa,EAA7B,MAAM;QACU,UAAU,EAA1B,MAAM;QAGU,UAAU,EAA1B,MAAM;OAgGhB;IAxQD;;;OAGG;IACH,wBAHU,MAAM,CAGF;IAEd;;;;OAIG;IACH,qBAHU,MAAM,CAGL;IAEX;;;;OAIG;IACH,qBAHU,MAAM,CAGL;IAwPX;;OAEG;IACH,4BAEC;IAED;;OAEG;IACH,4BAEC;IAED;;OAEG;IACH,4BAEC;IAED;;;;OAIG;IACH,wBAEC;IAED;;;;;;;OAOG;IACH,mCAQC;IAED;;;OAGG;IACH,uBAEC;IAED;;;;OAIG;IACH,gBAJW,MAAM,QACN,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,mBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;OAMG;IACH,sBAFW,UAAU,MAAM,CAAC,QAiB3B;IAED;;;OAGG;IACH,oBAHW,oBAAoB,GAClB,OAAO,CAMnB;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH;QAb+B,KAAK,EAAzB,UAAU;QACM,CAAC,EAAjB,MAAM;QACU,CAAC,EAAjB,MAAM;QACU,CAAC,EAAjB,MAAM;QACU,MAAM,EAAtB,MAAM;QAC4B,SAAS,EAA3C,UAAU,aAAa,CAAC;QACiB,gBAAgB,GAAzD,UAAU,mBAAmB,CAAC;QACA,KAAK,EAAnC,eAAe,GAAC,IAAI;QACH,MAAM,GAAvB,MAAM;QAEJ,MAAM,CAiHlB;IAgWD,gBAcC;;CACJ;mCAr9BY,OAAO,4BAA4B,EAAE,oBAAoB;yBACzD,OAAO,iEAAiE,EAAE,UAAU;8BACpF,OAAO,mCAAmC,EAAE,eAAe;;;;;;;WA+C1D,UAAU;;;;WACV,MAAM;;;;;;UACN,MAAM;;;;;aAGN,MAAM;;;;sBAEN,MAAM;;;;;mBAEN,MAAM;;;;gBACN,MAAM;mBACN,MAAM;;;;;;;;;;WAGN,eAAe;;;;;;aAEf,eAAe;;;+BAON,UAAU,QAAE,oBAAoB,KAAG,IAAI;;;;;;;;;iCAUvC,UAAU,QAAE,oBAAoB,KAAG,IAAI;;+BA1G/B,0CAA0C"}
+{"version":3,"file":"GPUBrickClipmap.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/brick/GPUBrickClipmap.js"],"names":[],"mappings":"AA8FA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH;;;GAGG;AAEH;;;;;;;;GAQG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH;IAkKI;;;;;;;;OAQG;IACH;QAN2B,aAAa,EAA7B,MAAM;QACU,UAAU,EAA1B,MAAM;QAGU,UAAU,EAA1B,MAAM;OAgGhB;IAxQD;;;OAGG;IACH,wBAHU,MAAM,CAGF;IAEd;;;;OAIG;IACH,qBAHU,MAAM,CAGL;IAEX;;;;OAIG;IACH,qBAHU,MAAM,CAGL;IAwPX;;OAEG;IACH,4BAEC;IAED;;OAEG;IACH,4BAEC;IAED;;OAEG;IACH,4BAEC;IAED;;;;OAIG;IACH,wBAEC;IAED;;;;;;;OAOG;IACH,mCAQC;IAED;;;;;;OAMG;IACH,0BAEC;IAED;;;OAGG;IACH,uBAEC;IAED;;;;OAIG;IACH,gBAJW,MAAM,QACN,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,mBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;OAMG;IACH,sBAFW,UAAU,MAAM,CAAC,QAiB3B;IAED;;;OAGG;IACH,oBAHW,oBAAoB,GAClB,OAAO,CAMnB;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH;QAb+B,KAAK,EAAzB,UAAU;QACM,CAAC,EAAjB,MAAM;QACU,CAAC,EAAjB,MAAM;QACU,CAAC,EAAjB,MAAM;QACU,MAAM,EAAtB,MAAM;QAC4B,SAAS,EAA3C,UAAU,aAAa,CAAC;QACiB,gBAAgB,GAAzD,UAAU,mBAAmB,CAAC;QACA,KAAK,EAAnC,eAAe,GAAC,IAAI;QACH,MAAM,GAAvB,MAAM;QAEJ,MAAM,CAiHlB;IAgWD,gBAcC;;CACJ;mCAh+BY,OAAO,4BAA4B,EAAE,oBAAoB;yBACzD,OAAO,iEAAiE,EAAE,UAAU;8BACpF,OAAO,mCAAmC,EAAE,eAAe;;;;;;;WA+C1D,UAAU;;;;WACV,MAAM;;;;;;UACN,MAAM;;;;;aAGN,MAAM;;;;sBAEN,MAAM;;;;;mBAEN,MAAM;;;;gBACN,MAAM;mBACN,MAAM;;;;;;;;;;WAGN,eAAe;;;;;;aAEf,eAAe;;;+BAON,UAAU,QAAE,oBAAoB,KAAG,IAAI;;;;;;;;;iCAUvC,UAAU,QAAE,oBAAoB,KAAG,IAAI;;+BA3G/B,0CAA0C"}

package/src/shade/renderer/global_illumination/probe_clipmap/brick/GPUBrickClipmap.js

@@ -25,6 +25,7 @@ import {
 } from "../../../shader/chunk/clipmap/CLIPMAP_LEVEL_STRUCT.js";
 import { graph_import_buffer } from "../../../shader/graph/graph_import_buffer.js";
 import { GPUTileAtlas3D } from "../../../texture/atlas/GPUTileAtlas3D.js";
+import { tile_atlas_slot_shift } from "../../../texture/atlas/tile_atlas_slot_shift.js";
 import {
     BRICK_OCCUPANCY_BLOCK,
     BRICK_STAGING_WORDS,
@@ -473,6 +474,17 @@ export class GPUBrickClipmap {
         return bindings;
     }
 
+    /**
+     * The atlas's footprint as `tile_atlas_slot_shift` packs it: what every reader of the bricks takes in
+     * its immediate data as `brick_atlas_shift` and passes to `chunk_brick_clipmap_sample`. It changes
+     * only when a grow widens the atlas, in {@link graph_update}: take it after that, each frame, as the
+     * atlas itself.
+     * @returns {number}
+     */
+    get atlas_shift() {
+        return tile_atlas_slot_shift(this.#atlas.slots_x, this.#atlas.slots_y);
+    }
+
     /**
      * Slots of the atlas.
      * @returns {number}

package/src/shade/renderer/global_illumination/probe_clipmap/brick/chunk_brick_clipmap_trace.d.ts

@@ -45,15 +45,19 @@ export const BRICK_LEVELS_RESOURCE: ShaderResourceDescriptor;
  * A brick's distance at a point of its cell, where its slot sits in the atlas, and the field's gradient.
  *
  * ```wgsl
- * fn brick_clipmap_sample(slot: u32, local: vec3<f32>, voxel: f32) -> f32 // local in voxels from the cell's corner
- * fn brick_clipmap_slot_texel(slot: u32) -> vec3<u32>                      // the slot's texel 0 in the atlas
- * fn brick_clipmap_normal(slot: u32, local: vec3<f32>) -> vec3<f32>       // out of the solid, unit length
+ * fn brick_clipmap_sample(slot: u32, local: vec3<f32>, voxel: f32, atlas_shift: u32) -> f32 // local in voxels from the cell's corner
+ * fn brick_clipmap_slot_texel(slot: u32, atlas_shift: u32) -> vec3<u32>                      // the slot's texel 0 in the atlas
+ * fn brick_clipmap_normal(slot: u32, local: vec3<f32>, atlas_shift: u32) -> vec3<f32>       // out of the solid, unit length
  * ```
  *
  * One hardware trilinear tap of the atlas at texel `slot_origin + 0.5 + local`, `local` clamped to the
  * brick's [0, 7]: it never reads a neighbouring slot (§7.2). The gradient is a tetrahedral one, four
  * taps half a voxel off, each clamped the same way.
  *
+ * `atlas_shift` is the atlas's footprint, `GPUBrickClipmap#atlas_shift`, which every reader takes in its
+ * immediate data and passes down: a slot is found with shifts (`tile_atlas_slot_origin_shift`), with no
+ * texture query and no divide in front of the tap.
+ *
  * @type {CodeChunk}
  */
 export const chunk_brick_clipmap_sample: CodeChunk;
@@ -98,9 +102,11 @@ export const chunk_brick_clipmap_march: CodeChunk;
  * The first surface along a ray through the brick clipmap (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §7.9).
  *
  * ```wgsl
- * fn brick_clipmap_trace(origin: vec3<f32>, direction: vec3<f32>, t_min: f32, t_max: f32, cascade_count: u32) -> BrickClipmapHit
+ * fn brick_clipmap_trace(origin: vec3<f32>, direction: vec3<f32>, t_min: f32, t_max: f32, cascade_count: u32, atlas_shift: u32) -> BrickClipmapHit
  * ```
  *
+ * `atlas_shift` is the atlas's footprint, as {@link chunk_brick_clipmap_sample} takes it.
+ *
  * The march (`brick_clipmap_march`) from `t_min`, at most {@link BRICK_TRACE_STEPS} steps, each
  * reading in a brick one atlas tap:
  * - EMPTY inside is a hit where the march stands: the ray is inside a solid, and its hit is a back
@@ -118,7 +124,7 @@ export const chunk_brick_clipmap_trace: CodeChunk;
  * The finest cascade's signed distance at a point (§7.9), for probe relocation.
  *
  * ```wgsl
- * fn brick_clipmap_distance(position: vec3<f32>, cascade_count: u32) -> f32
+ * fn brick_clipmap_distance(position: vec3<f32>, cascade_count: u32, atlas_shift: u32) -> f32
  * ```
  *
  * The finest window holding the point answers, unless its cell is UNKNOWN, which defers to the
@@ -133,7 +139,7 @@ export const chunk_brick_clipmap_distance: CodeChunk;
  * no slope: for probe relocation (§8.4).
  *
  * ```wgsl
- * fn brick_clipmap_gradient(position: vec3<f32>, cascade_count: u32) -> vec3<f32>
+ * fn brick_clipmap_gradient(position: vec3<f32>, cascade_count: u32, atlas_shift: u32) -> vec3<f32>
  * ```
  *
  * Four taps of {@link chunk_brick_clipmap_distance} at the corners of a tetrahedron a voxel of the finest

package/src/shade/renderer/global_illumination/probe_clipmap/brick/chunk_brick_clipmap_trace.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_brick_clipmap_trace.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/brick/chunk_brick_clipmap_trace.js"],"names":[],"mappings":"AAoBA;;;;GAIG;AACH,gCAFU,MAAM,CAEoB;AAEpC;;;;GAIG;AACH,gCAFU,MAAM,CAEwB;AAExC;;;;GAIG;AACH,qCAFU,MAAM,CAE0B;AAE1C;;;GAGG;AACH,yCAFU,wBAAwB,CAEoE;AAEtG;;;GAGG;AACH,+CAFU,wBAAwB,CAEgF;AAElH;;;GAGG;AACH,2CAFU,wBAAwB,CAEyE;AAE3G;;;GAGG;AACH,qCAFU,wBAAwB,CAEqF;AAEvH;;;GAGG;AACH,oCAFU,wBAAwB,CAEyE;AAE3G;;;;;;;;;;;;;;GAcG;AACH,yCAFU,SAAS,CAyCZ;AAKP;;;;;;;;;;;;GAYG;AACH,yCAFU,SAAS,CAyBZ;AAIP;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wCAFU,SAAS,CAgFZ;AAKP;;;;;;;;;;;;;;;;;;GAkBG;AACH,wCAFU,SAAS,CAoGZ;AAEP;;;;;;;;;;;;GAYG;AACH,2CAFU,SAAS,CAsCZ;AAIP;;;;;;;;;;;;;;GAcG;AACH,2CAFU,SAAS,CA0BZ;yCA7dkC,sDAAsD;0BADrE,uCAAuC"}
+{"version":3,"file":"chunk_brick_clipmap_trace.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/brick/chunk_brick_clipmap_trace.js"],"names":[],"mappings":"AAoBA;;;;GAIG;AACH,gCAFU,MAAM,CAEoB;AAEpC;;;;GAIG;AACH,gCAFU,MAAM,CAEwB;AAExC;;;;GAIG;AACH,qCAFU,MAAM,CAE0B;AAE1C;;;GAGG;AACH,yCAFU,wBAAwB,CAEoE;AAEtG;;;GAGG;AACH,+CAFU,wBAAwB,CAEgF;AAElH;;;GAGG;AACH,2CAFU,wBAAwB,CAEyE;AAE3G;;;GAGG;AACH,qCAFU,wBAAwB,CAEqF;AAEvH;;;GAGG;AACH,oCAFU,wBAAwB,CAEyE;AAE3G;;;;;;;;;;;;;;;;;;GAkBG;AACH,yCAFU,SAAS,CAyCZ;AAKP;;;;;;;;;;;;GAYG;AACH,yCAFU,SAAS,CAyBZ;AAIP;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wCAFU,SAAS,CAgFZ;AAKP;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wCAFU,SAAS,CAoGZ;AAEP;;;;;;;;;;;;GAYG;AACH,2CAFU,SAAS,CAsCZ;AAIP;;;;;;;;;;;;;;GAcG;AACH,2CAFU,SAAS,CA0BZ;yCAnekC,sDAAsD;0BADrE,uCAAuC"}