@woosh/meep-engine 3.58.0 → 3.60.0

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

@@ -2,26 +2,34 @@ import { chunk_mesh_sdf_sample } from "../../../../geometry/sdf/chunk_mesh_sdf_s
 import { MESH_SDF_HEADERS_RESOURCE } from "../../../../geometry/sdf/MESH_SDF_RESOURCES.js";
 import { F32_MAX_DEFINITION } from "../../../../shader/chunk/math/F32_MAX_DEFINITION.js";
 import { CodeChunk } from "../../../../shader/compiler/CodeChunk.js";
+import { chunk_brick_object } from "../chunk_brick_object.js";
 import { MESH_BRICK_INSTANCE_STRUCT } from "./MESH_BRICK_INSTANCE_STRUCT.js";
 
 /**
  * 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.
  *
@@ -35,19 +43,24 @@ struct MeshBrickTexel {
     row: u32,
 }
 
-fn mesh_brick_texel(p: vec3<f32>, count: u32) -> MeshBrickTexel {
+fn mesh_brick_texel(p: vec3<f32>, count: u32, band: f32) -> MeshBrickTexel {
     var best: MeshBrickTexel;
 
     best.distance = F32_MAX;
     best.row = 0u;
 
+    // the least byte and the lowest row at it, as the largest object key: 0 before any instance
+    var key = 0u;
+
     for (var i = 0u; i < count; i++) {
         let instance = mesh_brick_instance_at(i);
 
         // the box's distance: 0 inside it, where an instance's surface can still lie nearer
         let outside = max(max(instance.box_min - p, p - instance.box_max), vec3<f32>(0.0));
 
-        if (length(outside) > max(best.distance, 0.0)) {
+        // nothing at least that far encodes below the least byte so far, or below the surface's when that
+        // is inside one; a tie in the byte is still sampled
+        if (key != 0u && brick_encode(length(outside), band) > max(brick_object_key_byte(key), brick_encode(0.0, band))) {
             continue;
         }
 
@@ -56,17 +69,18 @@ fn mesh_brick_texel(p: vec3<f32>, count: u32) -> MeshBrickTexel {
 
         let distance = instance.sigma * mesh_sdf_sample(mesh_sdf_headers[instance.geometry], instance.level, local);
 
-        if (distance < best.distance) {
-            best.distance = distance;
-            best.row = instance.row;
-        }
+        best.distance = min(best.distance, distance);
+        key = max(key, brick_object_key(brick_encode(distance, band), instance.row));
     }
 
+    best.row = select(0u, brick_object_key_row(key), key != 0u);
+
     return best;
 }
 `, [
         F32_MAX_DEFINITION,
         chunk_mesh_sdf_sample,
+        chunk_brick_object,
         MESH_BRICK_INSTANCE_STRUCT.declaration_chunk,
     ]);
 

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

@@ -0,0 +1,23 @@
+/**
+ * The arithmetic of the mesh provider's walks and records (`MESH_BRICK.js`), per invocation and pure,
+ * shared by its passes:
+ *
+ * ```wgsl
+ * fn mesh_brick_walk_spilled(start: u32, end: u32) -> u32     // nodes of an iteration past the frontier
+ * fn mesh_brick_walk_spill_index(slot: u32, start: u32) -> u32 // a child's place among them
+ * fn mesh_brick_records(entries: u32) -> u32                  // records that hold that many entries
+ * fn mesh_brick_record(index: u32) -> u32                     // a record's first word
+ * fn mesh_brick_accumulator(build: u32) -> u32                // a build slot's first accumulator word
+ * ```
+ *
+ * An iteration of a level appends the children it finds to the next level's list at places `start`
+ * to `end`, as their reservations came; the frontier keeps the places below
+ * {@link MESH_BRICK_FRONTIER}, and every child at or past it is handed on, at its place counted from
+ * whichever is later of `start` and the frontier. An iteration appends two children a lane at most,
+ * so it hands on at most twice {@link MESH_BRICK_BATCH}.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_mesh_brick_walk: CodeChunk;
+import { CodeChunk } from "../../../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_mesh_brick_walk.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_mesh_brick_walk.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/brick/mesh/chunk_mesh_brick_walk.js"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,oCAFU,SAAS,CAkChB;0BAjEuB,0CAA0C"}

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

@@ -0,0 +1,66 @@
+import { CodeChunk } from "../../../../shader/compiler/CodeChunk.js";
+import {
+    MESH_BRICK_ACCUMULATOR_FLAGS,
+    MESH_BRICK_ACCUMULATOR_OBJECTS,
+    MESH_BRICK_ACCUMULATOR_WORDS,
+    MESH_BRICK_BATCH,
+    MESH_BRICK_FLAG_TOUCHED,
+    MESH_BRICK_FLAG_UNFINISHED,
+    MESH_BRICK_FRONTIER,
+    MESH_BRICK_RECORD_HEADER_WORDS,
+    MESH_BRICK_RECORD_WORDS
+} from "./MESH_BRICK.js";
+
+/**
+ * The arithmetic of the mesh provider's walks and records (`MESH_BRICK.js`), per invocation and pure,
+ * shared by its passes:
+ *
+ * ```wgsl
+ * fn mesh_brick_walk_spilled(start: u32, end: u32) -> u32     // nodes of an iteration past the frontier
+ * fn mesh_brick_walk_spill_index(slot: u32, start: u32) -> u32 // a child's place among them
+ * fn mesh_brick_records(entries: u32) -> u32                  // records that hold that many entries
+ * fn mesh_brick_record(index: u32) -> u32                     // a record's first word
+ * fn mesh_brick_accumulator(build: u32) -> u32                // a build slot's first accumulator word
+ * ```
+ *
+ * An iteration of a level appends the children it finds to the next level's list at places `start`
+ * to `end`, as their reservations came; the frontier keeps the places below
+ * {@link MESH_BRICK_FRONTIER}, and every child at or past it is handed on, at its place counted from
+ * whichever is later of `start` and the frontier. An iteration appends two children a lane at most,
+ * so it hands on at most twice {@link MESH_BRICK_BATCH}.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_mesh_brick_walk = CodeChunk.from(
+    //language=WGSL
+    `
+const MESH_BRICK_BATCH = ${MESH_BRICK_BATCH}u;
+const MESH_BRICK_FRONTIER = ${MESH_BRICK_FRONTIER}u;
+const MESH_BRICK_RECORD_HEADER_WORDS = ${MESH_BRICK_RECORD_HEADER_WORDS}u;
+const MESH_BRICK_RECORD_WORDS = ${MESH_BRICK_RECORD_WORDS}u;
+const MESH_BRICK_ACCUMULATOR_OBJECTS = ${MESH_BRICK_ACCUMULATOR_OBJECTS}u;
+const MESH_BRICK_ACCUMULATOR_FLAGS = ${MESH_BRICK_ACCUMULATOR_FLAGS}u;
+const MESH_BRICK_ACCUMULATOR_WORDS = ${MESH_BRICK_ACCUMULATOR_WORDS}u;
+const MESH_BRICK_FLAG_TOUCHED = ${MESH_BRICK_FLAG_TOUCHED}u;
+const MESH_BRICK_FLAG_UNFINISHED = ${MESH_BRICK_FLAG_UNFINISHED}u;
+
+fn mesh_brick_walk_spilled(start: u32, end: u32) -> u32 {
+    return select(0u, end - max(MESH_BRICK_FRONTIER, start), end > MESH_BRICK_FRONTIER);
+}
+
+fn mesh_brick_walk_spill_index(slot: u32, start: u32) -> u32 {
+    return slot - max(MESH_BRICK_FRONTIER, start);
+}
+
+fn mesh_brick_records(entries: u32) -> u32 {
+    return (entries + MESH_BRICK_BATCH - 1u) / MESH_BRICK_BATCH;
+}
+
+fn mesh_brick_record(index: u32) -> u32 {
+    return index * MESH_BRICK_RECORD_WORDS;
+}
+
+fn mesh_brick_accumulator(build: u32) -> u32 {
+    return build * MESH_BRICK_ACCUMULATOR_WORDS;
+}
+`);

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

@@ -0,0 +1,29 @@
+/**
+ * @type {WebGPUStruct}
+ */
+export const MESH_BRICK_BATCH_SETTINGS: WebGPUStruct;
+/**
+ * The mesh provider's batches (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §7.7, as S9 built it): a workgroup
+ * a batch record the walks wrote, dispatched by its command (`shader_mesh_brick_command`).
+ *
+ * Its up to {@link MESH_BRICK_BATCH} rows, sorted ascending (a bitonic network, a lane a pair), become
+ * instances in workgroup memory, a lane each (`mesh_brick_instance`), and its cell's 512 texels are
+ * sampled over them in that order, eight a lane
+ * (`mesh_brick_texel`: the least distance and its row, the box test first). Each texel's byte goes into
+ * the cell's accumulators by an atomic maximum of 255 less it, and each 2³ object cell's nearest texel
+ * bids its key by another (`brick_object_key`): the least byte and the nearest row over every batch
+ * of the cell, whatever order the batches ran in. The staging is the resolve's to write.
+ *
+ * The order is what keeps a cell of up to {@link MESH_BRICK_BATCH} rows, one batch, the same however the walk
+ * found its rows: the box test is exact only where an instance's field is not negative outside its box,
+ * and where it is, which instances it passes over depends on the order it meets them in.
+ *
+ * Per lane, 21 steps of the sort at most, then eight texels, each at most {@link MESH_BRICK_BATCH} box tests and
+ * as many taps.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_mesh_brick_batch: ComputeShader;
+import { WebGPUStruct } from "../../../../shader/type/WebGPUStruct.js";
+import { ComputeShader } from "../../../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_mesh_brick_batch.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shader_mesh_brick_batch.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/brick/mesh/shader_mesh_brick_batch.js"],"names":[],"mappings":"AAyBA;;GAEG;AACH,wCAFU,YAAY,CAOO;AAuJ7B;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,sCAFU,aAAa,CAMpB;6BAnM0B,yCAAyC;8BAJxC,qCAAqC"}

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

@@ -0,0 +1,210 @@
+import {
+    MESH_SDF_ATLAS_RESOURCE,
+    MESH_SDF_HEADERS_RESOURCE,
+    MESH_SDF_INDIRECTION_RESOURCE,
+    MESH_SDF_SAMPLER_RESOURCE
+} from "../../../../geometry/sdf/MESH_SDF_RESOURCES.js";
+import { chunk_sort_bitonic_comparator } from "../../../../gpu_primitive/sort/chunk_sort_bitonic_comparator.js";
+import { CLIPMAP_LEVEL_ARRAY } from "../../../../shader/chunk/clipmap/CLIPMAP_LEVEL_STRUCT.js";
+import { chunk_folded_workgroup_index } from "../../../../shader/chunk/grid/chunk_folded_workgroup_index.js";
+import { CodeChunk } from "../../../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../../../shader/resource/ShaderResourceSetDescriptor.js";
+import { atomic_u32, u32 } from "../../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../../../shader/type/WebGPUArray.js";
+import { WebGPUStruct } from "../../../../shader/type/WebGPUStruct.js";
+import { BRICK_CELL_WORKGROUP_SIZE, BRICK_OBJECT_CELLS_PER_AXIS } from "../BRICK_CLIPMAP.js";
+import { chunk_brick_object } from "../chunk_brick_object.js";
+import { chunk_brick_provider } from "../chunk_brick_provider.js";
+import { BRICK_RING_RESOURCE, BRICK_TAKE_RESOURCE, chunk_brick_clipmap } from "../chunk_brick_clipmap.js";
+import { chunk_mesh_brick_instance } from "./chunk_mesh_brick_instance.js";
+import { chunk_mesh_brick_texel } from "./chunk_mesh_brick_texel.js";
+import { chunk_mesh_brick_walk } from "./chunk_mesh_brick_walk.js";
+import { MESH_BRICK_COUNTER_BATCH_GROUPS } from "./MESH_BRICK.js";
+import { MESH_BRICK_INSTANCE_STRUCT } from "./MESH_BRICK_INSTANCE_STRUCT.js";
+
+/**
+ * @type {WebGPUStruct}
+ */
+export const MESH_BRICK_BATCH_SETTINGS = WebGPUStruct.from({
+    /** keys `brick_ring` holds, a power of two */
+    ring_capacity: u32,
+    /** cells a cascade's window has a side */
+    resolution: u32,
+}, "MeshBrickBatchSettings");
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate("settings", MESH_BRICK_BATCH_SETTINGS);
+
+resources.createGroup()
+    .add(BRICK_TAKE_RESOURCE)
+    .add(BRICK_RING_RESOURCE)
+    .addUniform("brick_levels", CLIPMAP_LEVEL_ARRAY)
+    .addStorageBuffer("mesh_brick_counters", WebGPUArray.from(atomic_u32), true)
+    .addStorageBuffer("mesh_brick_batches", WebGPUArray.u32)
+    .addStorageBuffer("mesh_brick_accumulators", WebGPUArray.from(atomic_u32), true);
+
+resources.createGroup()
+    .addStorageBuffer("scene_database", WebGPUArray.from(u32))
+    .add(MESH_SDF_HEADERS_RESOURCE)
+    .add(MESH_SDF_INDIRECTION_RESOURCE)
+    .add(MESH_SDF_ATLAS_RESOURCE)
+    .add(MESH_SDF_SAMPLER_RESOURCE);
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+var<workgroup> instances: array<${MESH_BRICK_INSTANCE_STRUCT.wgsl_ref}, MESH_BRICK_BATCH>;
+
+/** the batch's rows, ascending */
+var<workgroup> batch_rows: array<u32, MESH_BRICK_BATCH>;
+
+/** per object cell: its nearest texel's key over the batch, and its lanes done */
+var<workgroup> object_best: array<atomic<u32>, ${BRICK_OBJECT_CELLS_PER_AXIS ** 3}>;
+var<workgroup> object_lanes: array<atomic<u32>, ${BRICK_OBJECT_CELLS_PER_AXIS ** 3}>;
+
+/** lane 0's: the batches, and this one's build slot and rows */
+var<workgroup> batch_header: vec3<u32>;
+
+fn mesh_brick_instance_at(i: u32) -> ${MESH_BRICK_INSTANCE_STRUCT.wgsl_ref} {
+    return instances[i];
+}
+
+@compute @workgroup_size(${BRICK_CELL_WORKGROUP_SIZE})
+fn main(
+    @builtin(workgroup_id) workgroup_id: vec3<u32>,
+    @builtin(local_invocation_index) lane: u32,
+) {
+    let index = folded_workgroup_index(workgroup_id);
+
+    if (lane == 0u) {
+        let batches = atomicLoad(&mesh_brick_counters[${MESH_BRICK_COUNTER_BATCH_GROUPS}u]);
+        var build = 0u;
+        var rows = 0u;
+
+        if (index < batches) {
+            build = mesh_brick_batches[mesh_brick_record(index)];
+            rows = mesh_brick_batches[mesh_brick_record(index) + 1u];
+        }
+
+        batch_header = vec3<u32>(batches, build, rows);
+    }
+
+    let header = workgroupUniformLoad(&batch_header);
+
+    // a folded dispatch's tail leaves whole
+    if (index >= header.x) {
+        return;
+    }
+
+    let build = header.y;
+    let count = header.z;
+    let at = brick_provider_cell(brick_provider_key(build, settings.ring_capacity), settings.resolution);
+
+    // the rows in ascending order, the slots past them last: a texel meets them in the same order however the walk
+    // found them, and its box test with them
+    batch_rows[lane] = select(0xffffffffu, mesh_brick_batches[mesh_brick_record(index) + MESH_BRICK_RECORD_HEADER_WORDS + lane], lane < count);
+
+    workgroupBarrier();
+
+    let size = sort_bitonic_size(count);
+
+    for (var block = 2u; block <= size; block <<= 1u) {
+        for (var stride = block >> 1u; stride > 0u; stride >>= 1u) {
+            if (lane < (size >> 1u)) {
+                let slots = sort_bitonic_comparator(lane, block, stride);
+                let low = batch_rows[slots.x];
+                let high = batch_rows[slots.y];
+
+                if (high < low) {
+                    batch_rows[slots.x] = high;
+                    batch_rows[slots.y] = low;
+                }
+            }
+
+            workgroupBarrier();
+        }
+    }
+
+    if (lane < count) {
+        instances[lane] = mesh_brick_instance(batch_rows[lane], at.voxel);
+    }
+
+    workgroupBarrier();
+
+    // eight texels a lane, x fastest, at y = lane mod 8 and z = lane / 8
+    let y = lane % 8u;
+    let z = lane / 8u;
+    let accumulator = mesh_brick_accumulator(build);
+
+    var best = vec4<u32>(0u);
+
+    for (var x = 0u; x < 8u; x++) {
+        let texel = mesh_brick_texel(at.corner + vec3<f32>(f32(x), f32(y), f32(z)) * at.voxel, count, at.band);
+        let byte = brick_encode(texel.distance, at.band);
+
+        // the cell's least byte over its batches, as the most of 255 less each; +R raises nothing
+        if (byte < 255u) {
+            atomicMax(&mesh_brick_accumulators[accumulator + x + 8u * (y + 8u * z)], 255u - byte);
+        }
+
+        let o = x / 2u;
+
+        best[o] = max(best[o], brick_object_key(byte, texel.row));
+    }
+
+    // per object cell, its four lanes fold in their texels, and the last bids the batch's nearest
+    for (var o = 0u; o < ${BRICK_OBJECT_CELLS_PER_AXIS}u; o++) {
+        let object = o + ${BRICK_OBJECT_CELLS_PER_AXIS}u * ((y / 2u) + ${BRICK_OBJECT_CELLS_PER_AXIS}u * (z / 2u));
+
+        atomicMax(&object_best[object], best[o]);
+
+        if (atomicAdd(&object_lanes[object], 1u) != 3u) {
+            continue;
+        }
+
+        let nearest = atomicLoad(&object_best[object]);
+
+        if (brick_object_key_byte(nearest) < 255u) {
+            atomicMax(&mesh_brick_accumulators[accumulator + MESH_BRICK_ACCUMULATOR_OBJECTS + object], nearest);
+        }
+    }
+}
+`, [
+    chunk_brick_clipmap,
+    chunk_brick_provider,
+    chunk_folded_workgroup_index,
+    chunk_mesh_brick_walk,
+    chunk_mesh_brick_instance,
+    chunk_mesh_brick_texel,
+    chunk_brick_object,
+    chunk_sort_bitonic_comparator,
+]);
+
+/**
+ * The mesh provider's batches (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §7.7, as S9 built it): a workgroup
+ * a batch record the walks wrote, dispatched by its command (`shader_mesh_brick_command`).
+ *
+ * Its up to {@link MESH_BRICK_BATCH} rows, sorted ascending (a bitonic network, a lane a pair), become
+ * instances in workgroup memory, a lane each (`mesh_brick_instance`), and its cell's 512 texels are
+ * sampled over them in that order, eight a lane
+ * (`mesh_brick_texel`: the least distance and its row, the box test first). Each texel's byte goes into
+ * the cell's accumulators by an atomic maximum of 255 less it, and each 2³ object cell's nearest texel
+ * bids its key by another (`brick_object_key`): the least byte and the nearest row over every batch
+ * of the cell, whatever order the batches ran in. The staging is the resolve's to write.
+ *
+ * The order is what keeps a cell of up to {@link MESH_BRICK_BATCH} rows, one batch, the same however the walk
+ * found its rows: the box test is exact only where an instance's field is not negative outside its box,
+ * and where it is, which instances it passes over depends on the order it meets them in.
+ *
+ * Per lane, 21 steps of the sort at most, then eight texels, each at most {@link MESH_BRICK_BATCH} box tests and
+ * as many taps.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_mesh_brick_batch = ComputeShader.from({
+    label: "Brick Clipmap Mesh Batch",
+    resources,
+    body,
+});

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

@@ -0,0 +1,29 @@
+/**
+ * No counter to clear.
+ * @type {number}
+ */
+export const MESH_BRICK_COMMAND_CLEAR_NONE: number;
+/**
+ * Words a command takes in `mesh_brick_commands`: the three workgroup counts, and a word of padding.
+ * @type {number}
+ */
+export const MESH_BRICK_COMMAND_WORDS: number;
+/**
+ * @type {WebGPUStruct}
+ */
+export const MESH_BRICK_COMMAND_SETTINGS: WebGPUStruct;
+/**
+ * The mesh provider's command for a round of walks or for the batches (§7.7, as S9 built it): one
+ * thread, between the pass that asked for the records and the pass that runs a workgroup a record.
+ *
+ * It reads how many records were asked for, writes how many the capacity holds where the dispatched
+ * pass reads its workgroups, keeps the most ever asked for for the host to grow on, clears the counter
+ * the dispatched pass appends to, and writes the folded dispatch (`folded_dispatch`). A pass never
+ * writes the command it is dispatched through.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_mesh_brick_command: ComputeShader;
+import { WebGPUStruct } from "../../../../shader/type/WebGPUStruct.js";
+import { ComputeShader } from "../../../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_mesh_brick_command.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shader_mesh_brick_command.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/brick/mesh/shader_mesh_brick_command.js"],"names":[],"mappings":"AAQA;;;GAGG;AACH,4CAFU,MAAM,CAEwC;AAExD;;;GAGG;AACH,uCAFU,MAAM,CAE0B;AAE1C;;GAEG;AACH,0CAFU,YAAY,CAeS;AAU/B;;;;;;;;;;GAUG;AACH,wCAFU,aAAa,CA8BpB;6BA/E0B,yCAAyC;8BAJxC,qCAAqC"}

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

@@ -0,0 +1,86 @@
+import { chunk_folded_dispatch } from "../../../../gpu_primitive/indirect/chunk_folded_dispatch.js";
+import { CodeChunk } from "../../../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../../../shader/resource/ShaderResourceSetDescriptor.js";
+import { atomic_u32, u32 } from "../../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../../../shader/type/WebGPUArray.js";
+import { WebGPUStruct } from "../../../../shader/type/WebGPUStruct.js";
+
+/**
+ * No counter to clear.
+ * @type {number}
+ */
+export const MESH_BRICK_COMMAND_CLEAR_NONE = 0xffffffff;
+
+/**
+ * Words a command takes in `mesh_brick_commands`: the three workgroup counts, and a word of padding.
+ * @type {number}
+ */
+export const MESH_BRICK_COMMAND_WORDS = 4;
+
+/**
+ * @type {WebGPUStruct}
+ */
+export const MESH_BRICK_COMMAND_SETTINGS = WebGPUStruct.from({
+    /** the counter of the records asked for */
+    asked: u32,
+    /** where the workgroups go: the records asked for, as many as the capacity holds */
+    groups: u32,
+    /** records the buffer holds */
+    capacity: u32,
+    /** the statistic that keeps the most ever asked for */
+    peak: u32,
+    /** a counter the dispatched pass appends to from 0, or {@link MESH_BRICK_COMMAND_CLEAR_NONE} */
+    clear: u32,
+    /** the command's first word in `mesh_brick_commands` */
+    command: u32,
+}, "MeshBrickCommandSettings");
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate("settings", MESH_BRICK_COMMAND_SETTINGS);
+
+resources.createGroup()
+    .addStorageBuffer("mesh_brick_counters", WebGPUArray.from(atomic_u32), true)
+    .addStorageBuffer("mesh_brick_commands", WebGPUArray.u32, true);
+
+/**
+ * The mesh provider's command for a round of walks or for the batches (§7.7, as S9 built it): one
+ * thread, between the pass that asked for the records and the pass that runs a workgroup a record.
+ *
+ * It reads how many records were asked for, writes how many the capacity holds where the dispatched
+ * pass reads its workgroups, keeps the most ever asked for for the host to grow on, clears the counter
+ * the dispatched pass appends to, and writes the folded dispatch (`folded_dispatch`). A pass never
+ * writes the command it is dispatched through.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_mesh_brick_command = ComputeShader.from({
+    label: "Brick Clipmap Mesh Command",
+    resources,
+    body: CodeChunk.from(
+        //language=WGSL
+        `
+@compute @workgroup_size(1)
+fn main() {
+    let asked = atomicLoad(&mesh_brick_counters[settings.asked]);
+    let groups = min(asked, settings.capacity);
+
+    atomicStore(&mesh_brick_counters[settings.groups], groups);
+    atomicMax(&mesh_brick_counters[settings.peak], asked);
+
+    if (settings.clear != ${MESH_BRICK_COMMAND_CLEAR_NONE}u) {
+        atomicStore(&mesh_brick_counters[settings.clear], 0u);
+    }
+
+    let folded = folded_dispatch(groups);
+
+    // word by word: the emulator drops a whole-value store into a storage variable
+    mesh_brick_commands[settings.command] = folded.x;
+    mesh_brick_commands[settings.command + 1u] = folded.y;
+    mesh_brick_commands[settings.command + 2u] = folded.z;
+}
+`, [
+            chunk_folded_dispatch,
+        ]),
+});

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

@@ -0,0 +1,41 @@
+/**
+ * @type {WebGPUStruct}
+ */
+export const MESH_BRICK_GATHER_SETTINGS: WebGPUStruct;
+/**
+ * The mesh provider's walk (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §7.7, as S9 built it): every instance
+ * whose box comes within the band of a taken cell, gathered whole, a workgroup a walk.
+ *
+ * A walk expands the TLAS a level at a time, as the cooperative query does (`chunk_bvh_query_aabb_cooperative`):
+ * each node of the level is tested by a lane against the cell grown by the cascade's band, the children
+ * of an overlapping internal node go on the next level, and an overlapping leaf is a row when
+ * `mesh_brick_accept` takes it. Nothing is dropped:
+ * - a level keeps {@link MESH_BRICK_FRONTIER} nodes, and the children that fall past them are handed on in
+ *   task records of up to {@link MESH_BRICK_BATCH} nodes, each a walk of the next round, which this same
+ *   kernel runs from them;
+ * - rows leave in batch records of {@link MESH_BRICK_BATCH}, and the rows left when the walk ends in one
+ *   more.
+ *
+ * Round 0 walks from the root, a workgroup a taken cell, dispatched by take; a later round's
+ * dispatch comes from its command (`shader_mesh_brick_command`). Round 0's walk of a cell opens the
+ * cell's frame by clearing its flags; the walk that first flags it lists it for the resolve
+ * (`mesh_brick_resolves`), so the resolve runs on the cells a batch reached or a walk could not finish,
+ * and on no other. A record the capacity cannot hold, a level past the walk's budget, or a hand-off in
+ * the frame's last round leaves the walk unfinished: it is counted, and the resolve asks for the cell
+ * again. Of the records a walk asks for at once, those below the capacity are kept, so that every record
+ * a command dispatches was written this frame.
+ *
+ * An iteration of a level costs the workgroup a barrier and a `workgroupUniformLoad`, and a barrier
+ * more after one whose hand-off copied records out: lane 0 hands every lane where the next iteration's
+ * children start and, on the level's last, how many nodes the next level holds.
+ *
+ * Per lane and level, at most {@link MESH_BRICK_FRONTIER} / {@link MESH_BRICK_BATCH} node reads, accepts
+ * and appends, over at most {@link BVH_QUERY_AABB_LEVEL_BUDGET} levels; per iteration, two task entries
+ * and two batch entries copied at most.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_mesh_brick_gather: ComputeShader;
+import { WebGPUStruct } from "../../../../shader/type/WebGPUStruct.js";
+import { ComputeShader } from "../../../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_mesh_brick_gather.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shader_mesh_brick_gather.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/brick/mesh/shader_mesh_brick_gather.js"],"names":[],"mappings":"AAuCA;;GAEG;AACH,yCAFU,YAAY,CAeQ;AA0V9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,uCAFU,aAAa,CAMpB;6BApa0B,yCAAyC;8BAJxC,qCAAqC"}