@woosh/meep-engine 3.58.0 → 3.60.0

package/src/shade/renderer/global_illumination/probe_clipmap/brick/mesh/MeshSDFBrickProvider.js

@@ -1,7 +1,35 @@
 import { assert } from "../../../../../../core/assert.js";
+import { ceilPowerOfTwo } from "../../../../../../core/binary/operations/ceilPowerOfTwo.js";
 import { BufferDescriptor } from "../../../../../descriptor/buffer/BufferDescriptor.js";
+import { graph_read_buffer } from "../../../../buffer/graph_read_buffer.js";
+import { graph_import_buffer } from "../../../../shader/graph/graph_import_buffer.js";
 import { BRICK_TAKE_CELL_DISPATCH } from "../BRICK_CLIPMAP.js";
-import { MESH_BRICK_STATISTIC_WORDS, shader_mesh_brick_provider } from "./shader_mesh_brick_provider.js";
+import {
+    MESH_BRICK_ACCUMULATOR_WORDS,
+    MESH_BRICK_COUNTER_BATCH_GROUPS,
+    MESH_BRICK_COUNTER_BATCHES,
+    MESH_BRICK_COUNTER_RESOLVE_GROUPS,
+    MESH_BRICK_COUNTER_RESOLVES,
+    MESH_BRICK_COUNTER_ROUND_GROUPS,
+    MESH_BRICK_COUNTER_TASKS,
+    MESH_BRICK_COUNTER_WORDS,
+    MESH_BRICK_RECORD_WORDS,
+    MESH_BRICK_ROUND_LIMIT,
+    MESH_BRICK_ROUNDS,
+    MESH_BRICK_STATISTIC_BATCHES_PEAK,
+    MESH_BRICK_STATISTIC_RESOLVES_PEAK,
+    MESH_BRICK_STATISTIC_ROUNDS_SHORT,
+    MESH_BRICK_STATISTIC_TASKS_PEAK,
+    MESH_BRICK_STATISTIC_WORDS
+} from "./MESH_BRICK.js";
+import { shader_mesh_brick_batch } from "./shader_mesh_brick_batch.js";
+import {
+    MESH_BRICK_COMMAND_CLEAR_NONE,
+    MESH_BRICK_COMMAND_WORDS,
+    shader_mesh_brick_command
+} from "./shader_mesh_brick_command.js";
+import { shader_mesh_brick_gather } from "./shader_mesh_brick_gather.js";
+import { shader_mesh_brick_resolve } from "./shader_mesh_brick_resolve.js";
 
 /**
  * @typedef {import("../GPUBrickClipmap.js").BrickProviderContext} BrickProviderContext
@@ -9,30 +37,97 @@ import { MESH_BRICK_STATISTIC_WORDS, shader_mesh_brick_provider } from "./shader
  */
 
 /**
- * The world's bricks from the meshes' cached fields (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §7.7): a
- * {@link BrickProvider} like any plugin, registered first. Per taken cell, the instances in the SDF
- * world whose boxes reach it, each sampled at the level of its field that suits the cascade, merged
- * into the staging by the minimum of the bytes, with the nearest instance's row as each 2³ cell's
- * object.
+ * Task records a half of the task buffer starts with. Zorah's fill asks for at most a few hundred a
+ * round; the capacity follows the most asked for.
+ * @type {number}
+ */
+const INITIAL_TASK_CAPACITY = 1024;
+
+/**
+ * Batch records the batch buffer starts with: a batch for each of the default budget's cells. The
+ * capacity follows the most asked for.
+ * @type {number}
+ */
+const INITIAL_BATCH_CAPACITY = 4096;
+
+/**
+ * Which of the commands is the resolve's: past the batches' and the rounds'.
+ * @type {number}
+ */
+const RESOLVE_COMMAND = MESH_BRICK_ROUND_LIMIT;
+
+/**
+ * The world's bricks from the meshes' cached fields (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §7.7, as S9
+ * built it): a {@link BrickProvider} like any plugin, registered first. Every instance in the SDF world
+ * whose box comes within the band of a taken cell is sampled there, at the level of its field that
+ * suits the cascade, however many reach the cell.
+ *
+ * A frame is one pass of dispatches, every one sized by a count on the device:
+ * - **walks** (`shader_mesh_brick_gather`), {@link rounds} of them: the taken cells' TLAS walks from the
+ *   root, a workgroup a cell, then the walks of what each round handed on;
+ * - **batches** (`shader_mesh_brick_batch`): a workgroup a batch of up to 64 rows the walks found,
+ *   merged into the cell's accumulators by atomic maxima;
+ * - **resolve** (`shader_mesh_brick_resolve`): a workgroup a cell the walks listed, one a batch reached
+ *   or a walk of which did not finish, merging its accumulators into the staging by the provider
+ *   contract (§7.6), and asking again for a cell whose walk did not finish. Most taken cells have no
+ *   instance near them, and are not listed;
+ * - **commands** (`shader_mesh_brick_command`), a thread before each dispatch but the walks from the
+ *   root: what the passes before it asked for, as its dispatch.
  *
- * It reads the view's scene through the context: the TLAS over the mesh rows, the scene database and
- * the geometry caches. A cell's instances past {@link MESH_BRICK_INSTANCE_LIMIT} are dropped; they and
- * whatever the gather itself dropped are counted in {@link statistics}.
+ * What the device asked for past a capacity, and walks the last round could not finish, are counted in
+ * {@link statistics}. The counts are read back each frame, and a later frame grows what held work back:
+ * a buffer to the power of two at or past the most asked for, the rounds by one up to
+ * {@link MESH_BRICK_ROUND_LIMIT}. The cells that lost work are asked for again meanwhile, so nothing is
+ * lost for longer than the growth takes.
  */
 export class MeshSDFBrickProvider {
     /** @type {GPUDevice} */
     #device;
 
     /**
-     * Counts that accumulate: instances dropped past the limit, candidates and subtrees the gather
-     * dropped (`shader_mesh_brick_provider.js`).
+     * The statistics, then the frame's counters (`MESH_BRICK.js`).
+     * @type {GPUBuffer}
+     */
+    #counters;
+
+    /**
+     * The batches' command, one a round past the first, and the resolve's: {@link MESH_BRICK_COMMAND_WORDS}
+     * words each.
      * @type {GPUBuffer}
      */
-    #statistics;
+    #commands;
+
+    /** @type {GPUBuffer|null} */
+    #tasks = null;
+    #task_capacity = INITIAL_TASK_CAPACITY;
 
-    #settings = { ring_capacity: 0, resolution: 0 };
+    /** @type {GPUBuffer|null} */
+    #batches = null;
+    #batch_capacity = INITIAL_BATCH_CAPACITY;
+
+    /**
+     * The build slots' accumulators, zero when nothing reached them.
+     * @type {GPUBuffer|null}
+     */
+    #accumulators = null;
+    #accumulator_slots = 0;
+
+    /**
+     * The frame's cells for the resolve, a place a build slot.
+     * @type {GPUBuffer|null}
+     */
+    #resolves = null;
+
+    #rounds = MESH_BRICK_ROUNDS;
+
+    /** What the last readback found: the walks the last round could not finish so far. */
+    #rounds_short = 0;
+
+    #gather_settings = { ring_capacity: 0, resolution: 0, round: 0, last: 0, task_capacity: 0, batch_capacity: 0 };
+    #command_settings = { asked: 0, groups: 0, capacity: 0, peak: 0, clear: 0, command: 0 };
+    #batch_settings = { ring_capacity: 0, resolution: 0 };
     #bindings = {};
-    #data = { take: -1, staging: -1 };
+    #data = { take: -1, staging: -1, counters: -1 };
 
     /**
      * The context of the frame being recorded, as its pass executes.
@@ -50,18 +145,55 @@ export class MeshSDFBrickProvider {
 
         this.#device = device;
 
-        this.#statistics = device.createBuffer(BufferDescriptor.fromJSON({
-            label: 'Probe clipmap / mesh brick statistics',
-            size: 4 * MESH_BRICK_STATISTIC_WORDS,
-            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC,
+        this.#counters = device.createBuffer(BufferDescriptor.fromJSON({
+            label: 'Probe clipmap / mesh brick counters',
+            size: 4 * MESH_BRICK_COUNTER_WORDS,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC | GPUBufferUsage.COPY_DST,
+        }));
+
+        this.#commands = device.createBuffer(BufferDescriptor.fromJSON({
+            label: 'Probe clipmap / mesh brick commands',
+            size: 4 * MESH_BRICK_COMMAND_WORDS * (RESOLVE_COMMAND + 1),
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.INDIRECT,
         }));
+
+        this.#tasks = this.#create_records('mesh brick tasks', 2 * this.#task_capacity);
+        this.#batches = this.#create_records('mesh brick batches', this.#batch_capacity);
     }
 
     /**
+     * Counts that accumulate for the provider's life, {@link MESH_BRICK_STATISTIC_WORDS} words at the start
+     * of the buffer (`MESH_BRICK.js`): the records asked for and the ones past a capacity, walks left
+     * unfinished, cells asked for again, the most records a frame and a round asked for, and the most
+     * cells a frame listed for the resolve.
      * @returns {GPUBuffer}
      */
     get statistics() {
-        return this.#statistics;
+        return this.#counters;
+    }
+
+    /**
+     * Rounds of walks a frame runs: two at first, one more each time the last round could not finish a walk.
+     * @returns {number}
+     */
+    get rounds() {
+        return this.#rounds;
+    }
+
+    /**
+     * Task records a half of the task buffer holds.
+     * @returns {number}
+     */
+    get task_capacity() {
+        return this.#task_capacity;
+    }
+
+    /**
+     * Batch records a frame can sample.
+     * @returns {number}
+     */
+    get batch_capacity() {
+        return this.#batch_capacity;
     }
 
     /**
@@ -71,54 +203,264 @@ export class MeshSDFBrickProvider {
     graph_write_bricks(graph, context) {
         assert.notOk(this.#destroyed, 'destroyed');
         assert.defined(context.scene, 'context.scene');
+        assert.isPositiveInteger(context.staging_capacity, 'context.staging_capacity');
+
+        this.#ensure_records();
+        this.#ensure_accumulators(context.staging_capacity);
 
         const data = this.#data;
         const pass = graph.add("Brick Clipmap Mesh Provider", data, this.#execute);
 
         data.take = pass.read(context.take);
         data.staging = pass.write(context.staging);
+        data.counters = pass.write(graph_import_buffer(graph, this.#counters, "mesh brick counters"));
 
         // the next provider and the store come after this one's merge
         context.staging = data.staging;
 
         this.#context = context;
+
+        // what held work back grows, from a later frame
+        const rounds = this.#rounds;
+
+        graph_read_buffer({ graph, buffer: data.counters, offset: 0, size: 4 * MESH_BRICK_STATISTIC_WORDS })
+            .then(reference => {
+                try {
+                    if (!this.#destroyed) {
+                        this.#apply_statistics(new Uint32Array(reference.getValue()), rounds);
+                    }
+                } finally {
+                    reference.release();
+                }
+            })
+            .catch(() => {
+                // a reading lost to a timeout or a lost device: the counts run on, and a later reading carries them
+            });
+    }
+
+    /**
+     * @param {Uint32Array} words the statistics, read back
+     * @param {number} rounds the rounds the frame they were read from ran
+     */
+    #apply_statistics(words, rounds) {
+        const short = words[MESH_BRICK_STATISTIC_ROUNDS_SHORT];
+
+        // one round more for each frame that ran out of them, not for the frames already in flight
+        if (short !== this.#rounds_short) {
+            this.#rounds_short = short;
+
+            if (rounds === this.#rounds) {
+                this.#rounds = Math.min(this.#rounds + 1, MESH_BRICK_ROUND_LIMIT);
+            }
+        }
+
+        this.#task_capacity = Math.max(this.#task_capacity, ceilPowerOfTwo(words[MESH_BRICK_STATISTIC_TASKS_PEAK]));
+        this.#batch_capacity = Math.max(this.#batch_capacity, ceilPowerOfTwo(words[MESH_BRICK_STATISTIC_BATCHES_PEAK]));
+    }
+
+    /**
+     * @param {string} name
+     * @param {number} records
+     * @returns {GPUBuffer}
+     */
+    #create_records(name, records) {
+        return this.#device.createBuffer(BufferDescriptor.fromJSON({
+            label: `Probe clipmap / ${name}`,
+            size: 4 * MESH_BRICK_RECORD_WORDS * records,
+            usage: GPUBufferUsage.STORAGE,
+        }));
+    }
+
+    /**
+     * Record buffers of the capacities asked for: the records live a frame, so nothing is copied.
+     */
+    #ensure_records() {
+        if (this.#tasks.size < 4 * MESH_BRICK_RECORD_WORDS * 2 * this.#task_capacity) {
+            this.#tasks.destroy();
+            this.#tasks = this.#create_records('mesh brick tasks', 2 * this.#task_capacity);
+        }
+
+        if (this.#batches.size < 4 * MESH_BRICK_RECORD_WORDS * this.#batch_capacity) {
+            this.#batches.destroy();
+            this.#batches = this.#create_records('mesh brick batches', this.#batch_capacity);
+        }
+    }
+
+    /**
+     * Accumulators, and a place on the resolve's list, for every build slot the staging holds. A new
+     * accumulator buffer is zero, which is empty, and the resolve leaves what it merges at zero, so
+     * nothing is cleared.
+     *
+     * @param {number} slots
+     */
+    #ensure_accumulators(slots) {
+        if (this.#accumulators !== null && this.#accumulator_slots >= slots) {
+            return;
+        }
+
+        this.#accumulators?.destroy();
+        this.#accumulator_slots = slots;
+        this.#accumulators = this.#device.createBuffer(BufferDescriptor.fromJSON({
+            label: 'Probe clipmap / mesh brick accumulators',
+            size: 4 * MESH_BRICK_ACCUMULATOR_WORDS * slots,
+            usage: GPUBufferUsage.STORAGE,
+        }));
+
+        this.#resolves?.destroy();
+        this.#resolves = this.#device.createBuffer(BufferDescriptor.fromJSON({
+            label: 'Probe clipmap / mesh brick resolves',
+            size: 4 * slots,
+            usage: GPUBufferUsage.STORAGE,
+        }));
     }
 
     #execute = (data, resources, execution) => {
         const context = this.#context;
         const scene = context.scene;
+        const encoder = execution.encoder;
         const take = resources.get(data.take);
+        const counters = resources.get(data.counters);
+        const rounds = this.#rounds;
 
-        const settings = this.#settings;
-
-        settings.ring_capacity = context.ring_capacity;
-        settings.resolution = context.resolution;
+        // the frame's counters start from nothing; the statistics before them run on
+        encoder.clearBuffer(counters, 4 * MESH_BRICK_COUNTER_BATCHES, 4 * (MESH_BRICK_COUNTER_WORDS - MESH_BRICK_COUNTER_BATCHES));
 
         const b = scene.geometries.sdf.write_bindings(this.#bindings);
 
-        b.settings = settings;
         b.brick_take = take;
         b.brick_ring = context.ring;
-        b.brick_staging = resources.get(data.staging);
         b.brick_levels = context.levels;
-        b.mesh_brick_statistics = this.#statistics;
+        b.brick_staging = resources.get(data.staging);
         b.tlas = scene.tlas.buffer;
         b.scene_database = scene.scene_database_buffer;
+        b.mesh_brick_counters = counters;
+        b.mesh_brick_commands = this.#commands;
+        b.mesh_brick_tasks = this.#tasks;
+        b.mesh_brick_batches = this.#batches;
+        b.mesh_brick_accumulators = this.#accumulators;
+        b.mesh_brick_resolves = this.#resolves;
 
-        shader_mesh_brick_provider.dispatchIndirect({
-            encoder: execution.encoder,
+        const gather = this.#gather_settings;
+
+        gather.ring_capacity = context.ring_capacity;
+        gather.resolution = context.resolution;
+        gather.task_capacity = this.#task_capacity;
+        gather.batch_capacity = this.#batch_capacity;
+
+        for (let round = 0; round < rounds; round++) {
+            gather.round = round;
+            gather.last = round === rounds - 1 ? 1 : 0;
+
+            if (round === 0) {
+                b.settings = gather;
+
+                shader_mesh_brick_gather.dispatchIndirect({
+                    encoder,
+                    bindings: b,
+                    command: take,
+                    command_offset: 4 * BRICK_TAKE_CELL_DISPATCH,
+                });
+
+                continue;
+            }
+
+            // the half the round before wrote is this round's walks; the other half it writes, from 0
+            this.#record_command(encoder, b,
+                MESH_BRICK_COUNTER_TASKS + ((round - 1) & 1),
+                MESH_BRICK_COUNTER_ROUND_GROUPS,
+                this.#task_capacity,
+                MESH_BRICK_STATISTIC_TASKS_PEAK,
+                MESH_BRICK_COUNTER_TASKS + (round & 1),
+                round
+            );
+
+            b.settings = gather;
+
+            shader_mesh_brick_gather.dispatchIndirect({
+                encoder,
+                bindings: b,
+                command: this.#commands,
+                command_offset: 4 * MESH_BRICK_COMMAND_WORDS * round,
+            });
+        }
+
+        // the batches every round asked for, in the command before the rounds'
+        this.#record_command(encoder, b,
+            MESH_BRICK_COUNTER_BATCHES,
+            MESH_BRICK_COUNTER_BATCH_GROUPS,
+            this.#batch_capacity,
+            MESH_BRICK_STATISTIC_BATCHES_PEAK,
+            MESH_BRICK_COMMAND_CLEAR_NONE,
+            0
+        );
+
+        const batch = this.#batch_settings;
+
+        batch.ring_capacity = context.ring_capacity;
+        batch.resolution = context.resolution;
+        b.settings = batch;
+
+        shader_mesh_brick_batch.dispatchIndirect({
+            encoder,
             bindings: b,
-            command: take,
-            command_offset: 4 * BRICK_TAKE_CELL_DISPATCH,
+            command: this.#commands,
+            command_offset: 0,
+        });
+
+        // the cells the walks listed, once every batch is in
+        this.#record_command(encoder, b,
+            MESH_BRICK_COUNTER_RESOLVES,
+            MESH_BRICK_COUNTER_RESOLVE_GROUPS,
+            this.#accumulator_slots,
+            MESH_BRICK_STATISTIC_RESOLVES_PEAK,
+            MESH_BRICK_COMMAND_CLEAR_NONE,
+            RESOLVE_COMMAND
+        );
+
+        shader_mesh_brick_resolve.dispatchIndirect({
+            encoder,
+            bindings: b,
+            command: this.#commands,
+            command_offset: 4 * MESH_BRICK_COMMAND_WORDS * RESOLVE_COMMAND,
         });
     };
 
+    /**
+     * @param {GPUCommandEncoder} encoder
+     * @param {Object} b the bindings
+     * @param {number} asked
+     * @param {number} groups
+     * @param {number} capacity
+     * @param {number} peak
+     * @param {number} clear
+     * @param {number} command which of the commands
+     */
+    #record_command(encoder, b, asked, groups, capacity, peak, clear, command) {
+        const settings = this.#command_settings;
+
+        settings.asked = asked;
+        settings.groups = groups;
+        settings.capacity = capacity;
+        settings.peak = peak;
+        settings.clear = clear;
+        settings.command = MESH_BRICK_COMMAND_WORDS * command;
+
+        b.settings = settings;
+
+        shader_mesh_brick_command.dispatch({ encoder, bindings: b });
+    }
+
     destroy() {
         if (this.#destroyed) {
             return;
         }
 
         this.#destroyed = true;
-        this.#statistics.destroy();
+        this.#counters.destroy();
+        this.#commands.destroy();
+        this.#tasks.destroy();
+        this.#batches.destroy();
+        this.#accumulators?.destroy();
+        this.#resolves?.destroy();
     }
 }

package/src/shade/renderer/global_illumination/probe_clipmap/brick/mesh/chunk_mesh_brick_instance.d.ts

@@ -9,10 +9,9 @@
  *
  * `mesh_brick_accept` is the gather's leaf filter, with `bounds` the row's world box and `voxel` the
  * cascade's: the row is in the SDF world, its geometry's field is resident (a skinned clone's through
- * its source's, the hook), and its box is at least half a voxel across. A virtual geometry has no
- * header, so it is not resident and is the vgeo provider's (§7.8). Under the cull an instance is out
- * of the cascade, emissive or not: the half-voxel hit would make it a lamp a voxel wide, 4 m at
- * cascade 5.
+ * its source's, the hook), and its box resolves in the cascade (`brick_provider_resolves`). A virtual
+ * geometry's field is the one baked for its proxy and adopted into it (§7.8), so its rows are taken as
+ * a mesh's are, once it is resident.
  *
  * `mesh_brick_instance` makes the instance the texels sample: the inverse of its transform, its box,
  * its smallest axis scale, and the coarsest level of its field no coarser than the cascade,

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

@@ -1 +1 @@
-{"version":3,"file":"chunk_mesh_brick_instance.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/brick/mesh/chunk_mesh_brick_instance.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wCAFU,SAAS,CA8DZ;0BAzFmB,0CAA0C"}
+{"version":3,"file":"chunk_mesh_brick_instance.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/brick/mesh/chunk_mesh_brick_instance.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wCAFU,SAAS,CA4DZ;0BAvFmB,0CAA0C"}

package/src/shade/renderer/global_illumination/probe_clipmap/brick/mesh/chunk_mesh_brick_instance.js

@@ -4,6 +4,7 @@ import { chunk_scene_database_access } from "../../../../scene/chunk_scene_datab
 import { MESH_FLAG_SDF_WORLD } from "../../../../scene/MESH_INSTANCE_METADATA_STRUCT.js";
 import { chunk_mat4_inverse } from "../../../../shader/chunk/geometry/mat4/chunk_mat4_inverse.js";
 import { CodeChunk } from "../../../../shader/compiler/CodeChunk.js";
+import { chunk_brick_provider_resolves } from "../chunk_brick_provider.js";
 import { MESH_BRICK_INSTANCE_STRUCT } from "./MESH_BRICK_INSTANCE_STRUCT.js";
 
 /**
@@ -17,10 +18,9 @@ import { MESH_BRICK_INSTANCE_STRUCT } from "./MESH_BRICK_INSTANCE_STRUCT.js";
  *
  * `mesh_brick_accept` is the gather's leaf filter, with `bounds` the row's world box and `voxel` the
  * cascade's: the row is in the SDF world, its geometry's field is resident (a skinned clone's through
- * its source's, the hook), and its box is at least half a voxel across. A virtual geometry has no
- * header, so it is not resident and is the vgeo provider's (§7.8). Under the cull an instance is out
- * of the cascade, emissive or not: the half-voxel hit would make it a lamp a voxel wide, 4 m at
- * cascade 5.
+ * its source's, the hook), and its box resolves in the cascade (`brick_provider_resolves`). A virtual
+ * geometry's field is the one baked for its proxy and adopted into it (§7.8), so its rows are taken as
+ * a mesh's are, once it is resident.
  *
  * `mesh_brick_instance` makes the instance the texels sample: the inverse of its transform, its box,
  * its smallest axis scale, and the coarsest level of its field no coarser than the cascade,
@@ -50,10 +50,7 @@ fn mesh_brick_accept(row: u32, bounds: array<f32, 6>, voxel: f32) -> bool {
         return false;
     }
 
-    // the resolution cull
-    let diagonal = length(vec3<f32>(bounds[3] - bounds[0], bounds[4] - bounds[1], bounds[5] - bounds[2]));
-
-    if (diagonal < 0.5 * voxel) {
+    if (!brick_provider_resolves(bounds, voxel)) {
         return false;
     }
 
@@ -89,6 +86,7 @@ fn mesh_brick_instance(row: u32, voxel: f32) -> ${MESH_BRICK_INSTANCE_STRUCT.wgs
 }
 `, [
         chunk_mesh_sdf,
+        chunk_brick_provider_resolves,
         chunk_scene_database_access,
         chunk_mat4_inverse,
         MESH_BRICK_INSTANCE_STRUCT.declaration_chunk,

package/src/shade/renderer/global_illumination/probe_clipmap/brick/mesh/chunk_mesh_brick_texel.d.ts

@@ -1,21 +1,28 @@
 /**
  * A world brick texel's distance from the mesh provider's instances (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md
- * §7.7): the minimum over them of `sigma · mesh_sdf_sample(header, level, M⁻¹·p)`, and the row it
- * came from.
+ * §7.7): the minimum over them of `sigma · mesh_sdf_sample(header, level, M⁻¹·p)`, and the row it came
+ * from, `band` being the cascade's (the texel's byte is `brick_encode(distance, band)`).
  *
  * ```wgsl
  * struct MeshBrickTexel { distance: f32, row: u32 } // F32_MAX and 0 with no instance
- * fn mesh_brick_texel(p: vec3<f32>, count: u32) -> MeshBrickTexel
+ * fn mesh_brick_texel(p: vec3<f32>, count: u32, band: f32) -> MeshBrickTexel
  * ```
  *
+ * The row is the lowest of the instances whose distance encodes to the texel's byte: the nearest in
+ * the byte the staging keeps, and among equally near ones the lowest row, whatever order the instances
+ * come in. A cell's instances reach it in batches in whatever order the walk found them, so its
+ * objects are the same however they were split.
+ *
  * The instances come through a seam the enclosing shader defines, as the cooperative query's tree
- * does: `fn mesh_brick_instance_at(i: u32) -> MeshBrickInstance`. The provider's kernel answers from
+ * does: `fn mesh_brick_instance_at(i: u32) -> MeshBrickInstance`. The provider's batch answers from
  * workgroup memory; a test, from a buffer.
  *
- * The box test is UE's early-out: an instance whose box lies farther than the running minimum, or
- * than the surface when the minimum is inside one, cannot give less, and is not sampled. At coarse
- * cascades most instances are only this test. Per texel: at most `count` box tests, and one
- * transform, one indirection load and one tap an instance the test lets through. No triangle is read.
+ * The box test is UE's early-out, in bytes: an instance whose box's distance encodes past the least
+ * byte so far, or past the surface's byte when the least is inside one, cannot reach it, and is not
+ * sampled. A box that holds the texel is always sampled, a deeper instance included. At coarse cascades
+ * most instances are only this test. Per
+ * texel: at most `count` box tests, and one transform, one indirection load and one tap an instance
+ * the test lets through. No triangle is read.
  *
  * Reads `mesh_sdf_headers` and what `mesh_sdf_sample` reads.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"chunk_mesh_brick_texel.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/brick/mesh/chunk_mesh_brick_texel.js"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qCAFU,SAAS,CA2CZ;0BAnEmB,0CAA0C"}
+{"version":3,"file":"chunk_mesh_brick_texel.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/brick/mesh/chunk_mesh_brick_texel.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qCAFU,SAAS,CAiDZ;0BAjFmB,0CAA0C"}