@woosh/meep-engine 3.59.0 → 3.60.0

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

@@ -0,0 +1,439 @@
+import { assert } from "../../../../../../core/assert.js";
+import { WebGPUExtensionType } from "../../../../../descriptor/WebGPUExtensionType.js";
+import { MESH_SDF_HEADERS_RESOURCE } from "../../../../geometry/sdf/MESH_SDF_RESOURCES.js";
+import { BVH2_NODE_STRUCT } from "../../../../shader/chunk/bvh/BVH2_NODE_STRUCT.js";
+import { BVH_NULL_NODE_DEFINITION } from "../../../../shader/chunk/bvh/BVH_NULL_NODE_DEFINITION.js";
+import { BVH_STRUCT } from "../../../../shader/chunk/bvh/BVH_STRUCT.js";
+import {
+    BVH_QUERY_AABB_LEVEL_BUDGET,
+    chunk_bvh_query_aabb_frontier
+} from "../../../../shader/chunk/bvh/chunk_bvh_query_aabb_frontier.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 { chunk_subgroup_reserve_workgroup } from "../../../../shader/chunk/subgroup/chunk_subgroup_reserve_workgroup.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 } from "../BRICK_CLIPMAP.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_walk } from "./chunk_mesh_brick_walk.js";
+import {
+    MESH_BRICK_BATCH,
+    MESH_BRICK_COUNTER_BATCHES,
+    MESH_BRICK_COUNTER_RESOLVES,
+    MESH_BRICK_COUNTER_ROUND_GROUPS,
+    MESH_BRICK_COUNTER_TASKS,
+    MESH_BRICK_FRONTIER,
+    MESH_BRICK_STATISTIC_BATCHES,
+    MESH_BRICK_STATISTIC_BATCHES_DROPPED,
+    MESH_BRICK_STATISTIC_LEVELS_SHORT,
+    MESH_BRICK_STATISTIC_ROUNDS_SHORT,
+    MESH_BRICK_STATISTIC_TASKS,
+    MESH_BRICK_STATISTIC_TASKS_DROPPED
+} from "./MESH_BRICK.js";
+
+/**
+ * @type {WebGPUStruct}
+ */
+export const MESH_BRICK_GATHER_SETTINGS = WebGPUStruct.from({
+    /** keys `brick_ring` holds, a power of two */
+    ring_capacity: u32,
+    /** cells a cascade's window has a side */
+    resolution: u32,
+    /** 0 for the walks from the root, one a taken cell; past it, the walks of the tasks the round before handed on */
+    round: u32,
+    /** 1 for the frame's last round, whose nodes past the frontier have no round to go to */
+    last: u32,
+    /** task records a half of `mesh_brick_tasks` holds */
+    task_capacity: u32,
+    /** batch records `mesh_brick_batches` holds */
+    batch_capacity: u32,
+}, "MeshBrickGatherSettings");
+
+// a walk is a workgroup's, as the cooperative query's is, and its records are a lane an entry
+assert.equal(BRICK_CELL_WORKGROUP_SIZE, MESH_BRICK_BATCH, 'a lane a record entry');
+assert.equal(MESH_BRICK_FRONTIER % MESH_BRICK_BATCH, 0, 'the frontier is expanded in whole rounds of the workgroup');
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate("settings", MESH_BRICK_GATHER_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_tasks", WebGPUArray.u32, true)
+    .addStorageBuffer("mesh_brick_batches", WebGPUArray.u32, true)
+    .addStorageBuffer("mesh_brick_accumulators", WebGPUArray.from(atomic_u32), true)
+    .addStorageBuffer("mesh_brick_resolves", WebGPUArray.u32, true);
+
+resources.createGroup()
+    .addStorageBuffer("tlas", BVH_STRUCT)
+    .addStorageBuffer("scene_database", WebGPUArray.from(u32))
+    .add(MESH_SDF_HEADERS_RESOURCE);
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+/** children an iteration finds at most: two a lane */
+const MESH_BRICK_WALK_SPILL = ${2 * MESH_BRICK_BATCH}u;
+/** rows waiting for their batch: fewer than a batch, and an iteration's at most */
+const MESH_BRICK_WALK_ROWS = ${2 * MESH_BRICK_BATCH}u;
+
+/** what lane 0 hands the workgroup after an iteration */
+struct MeshBrickWalkHandoff {
+    /** the next list's appends so far: where the next iteration's start, and once the level is done, its nodes */
+    end: u32,
+    /** the iteration's children past the frontier, and the task records kept for them: the first, and how many */
+    spilled: u32,
+    tasks: u32,
+    tasks_kept: u32,
+    /** rows from 'rows_from' on the ring, and the batch records kept for them: the first, and how many */
+    rows: u32,
+    rows_from: u32,
+    batches: u32,
+    batches_kept: u32,
+}
+
+// the frontier: two lists of node indices, alternating by level
+var<workgroup> walk_frontier: array<array<u32, MESH_BRICK_FRONTIER>, 2>;
+// appends asked of each list; past the frontier they were handed on
+var<workgroup> walk_reserved: array<atomic<u32>, 2>;
+// the iteration's children past the frontier, on their way to task records
+var<workgroup> walk_spill: array<u32, MESH_BRICK_WALK_SPILL>;
+// accepted rows, a ring from the first not yet in a batch
+var<workgroup> walk_rows: array<u32, MESH_BRICK_WALK_ROWS>;
+var<workgroup> walk_rows_reserved: atomic<u32>;
+
+// lane 0's words, read back through workgroupUniformLoad
+var<workgroup> walk_task: vec3<u32>;
+var<workgroup> walk_handoff: MeshBrickWalkHandoff;
+
+fn bvh_node(index: u32) -> ${BVH2_NODE_STRUCT.wgsl_ref} {
+    return tlas.nodes[index];
+}
+
+/** lane 0: a flag of the cell's for the frame; the first lists the cell for the resolve */
+fn mesh_brick_walk_flag(build: u32, flag: u32) {
+    let flags = atomicOr(&mesh_brick_accumulators[mesh_brick_accumulator(build) + MESH_BRICK_ACCUMULATOR_FLAGS], flag);
+
+    if (flags == 0u) {
+        mesh_brick_resolves[atomicAdd(&mesh_brick_counters[${MESH_BRICK_COUNTER_RESOLVES}u], 1u)] = build;
+    }
+}
+
+/** a task record of the half this round reads */
+fn mesh_brick_task_in(index: u32) -> u32 {
+    return mesh_brick_record(((settings.round + 1u) & 1u) * settings.task_capacity + index);
+}
+
+/** a task record of the half this round writes */
+fn mesh_brick_task_out(index: u32) -> u32 {
+    return mesh_brick_record((settings.round & 1u) * settings.task_capacity + index);
+}
+
+/**
+ * lane 0: 'records' records of a counter's, the first and how many are kept, those below 'capacity'.
+ * Whoever asked for a record below the capacity keeps it, so a command dispatches none that went unwritten.
+ */
+fn mesh_brick_walk_reserve(counter: u32, records: u32, capacity: u32) -> vec2<u32> {
+    let at = atomicAdd(&mesh_brick_counters[counter], records);
+
+    return vec2<u32>(at, min(records, capacity - min(at, capacity)));
+}
+
+/** lane 0: batch records for 'rows' rows */
+fn mesh_brick_walk_batches(build: u32, rows: u32) -> vec2<u32> {
+    if (rows == 0u) {
+        return vec2<u32>(0u);
+    }
+
+    let records = mesh_brick_records(rows);
+    let batches = mesh_brick_walk_reserve(${MESH_BRICK_COUNTER_BATCHES}u, records, settings.batch_capacity);
+
+    atomicAdd(&mesh_brick_counters[${MESH_BRICK_STATISTIC_BATCHES}u], records);
+
+    if (batches.y != 0u) {
+        // the resolve merges this cell's accumulators
+        mesh_brick_walk_flag(build, MESH_BRICK_FLAG_TOUCHED);
+    }
+
+    if (batches.y != records) {
+        // rows not sampled this frame: the cell is asked for again, and the capacity grows
+        atomicAdd(&mesh_brick_counters[${MESH_BRICK_STATISTIC_BATCHES_DROPPED}u], records - batches.y);
+        mesh_brick_walk_flag(build, MESH_BRICK_FLAG_UNFINISHED);
+    }
+
+    return batches;
+}
+
+/** lane 0: task records for an iteration's 'spilled' children */
+fn mesh_brick_walk_tasks(build: u32, spilled: u32) -> vec2<u32> {
+    if (spilled == 0u) {
+        return vec2<u32>(0u);
+    }
+
+    if (settings.last != 0u) {
+        // no round to hand them on to: the cell is asked for again, and the rounds grow
+        atomicAdd(&mesh_brick_counters[${MESH_BRICK_STATISTIC_ROUNDS_SHORT}u], 1u);
+        mesh_brick_walk_flag(build, MESH_BRICK_FLAG_UNFINISHED);
+
+        return vec2<u32>(0u);
+    }
+
+    let records = mesh_brick_records(spilled);
+    let tasks = mesh_brick_walk_reserve(${MESH_BRICK_COUNTER_TASKS}u + (settings.round & 1u), records, settings.task_capacity);
+
+    atomicAdd(&mesh_brick_counters[${MESH_BRICK_STATISTIC_TASKS}u], records);
+
+    if (tasks.y != records) {
+        atomicAdd(&mesh_brick_counters[${MESH_BRICK_STATISTIC_TASKS_DROPPED}u], records - tasks.y);
+        mesh_brick_walk_flag(build, MESH_BRICK_FLAG_UNFINISHED);
+    }
+
+    return tasks;
+}
+
+fn mesh_brick_walk_place(next: u32, slot: u32, start: u32, child: u32) {
+    if (slot < MESH_BRICK_FRONTIER) {
+        walk_frontier[next][slot] = child;
+    } else {
+        walk_spill[mesh_brick_walk_spill_index(slot, start)] = child;
+    }
+}
+
+@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);
+
+    // the round's walks: the taken cells from the root, or the tasks the round before handed on
+    if (lane == 0u) {
+        var walks: u32;
+        var build = index;
+        var roots = select(1u, 0u, tlas.root == BVH_NULL_NODE);
+
+        if (settings.round == 0u) {
+            walks = brick_take[BRICK_TAKE_COUNT];
+
+            if (index < walks) {
+                // the walk from the root opens the cell's frame, before any walk of it flags it
+                atomicStore(&mesh_brick_accumulators[mesh_brick_accumulator(build) + MESH_BRICK_ACCUMULATOR_FLAGS], 0u);
+            }
+        } else {
+            walks = atomicLoad(&mesh_brick_counters[${MESH_BRICK_COUNTER_ROUND_GROUPS}u]);
+
+            if (index < walks) {
+                build = mesh_brick_tasks[mesh_brick_task_in(index)];
+                roots = mesh_brick_tasks[mesh_brick_task_in(index) + 1u];
+            }
+        }
+
+        walk_task = vec3<u32>(walks, build, roots);
+
+        // the first level appends to the second list, and no row is in yet
+        atomicStore(&walk_reserved[1], 0u);
+        atomicStore(&walk_rows_reserved, 0u);
+    }
+
+    let task = workgroupUniformLoad(&walk_task);
+
+    // a folded dispatch's tail leaves whole
+    if (index >= task.x) {
+        return;
+    }
+
+    let build = task.y;
+    let at = brick_provider_cell(brick_provider_key(build, settings.ring_capacity), settings.resolution);
+
+    // every instance whose box comes within the band of the cell
+    let query = array<f32, 6>(at.corner.x - at.band, at.corner.y - at.band, at.corner.z - at.band, at.far.x + at.band, at.far.y + at.band, at.far.z + at.band);
+
+    // the first level's nodes, each read back by the lane that wrote it
+    if (settings.round == 0u) {
+        if (lane == 0u) {
+            walk_frontier[0][0] = tlas.root;
+        }
+    } else if (lane < task.z) {
+        walk_frontier[0][lane] = mesh_brick_tasks[mesh_brick_task_in(index) + MESH_BRICK_RECORD_HEADER_WORDS + lane];
+    }
+
+    var expand_count = task.z;
+    // lane 0's: the rows handed to batches so far
+    var rows_taken = 0u;
+    // the last hand-off copied out of the spill and the ring, which the next iteration fills again
+    var copied = false;
+
+    for (var level = 0u; level < ${BVH_QUERY_AABB_LEVEL_BUDGET}u && expand_count != 0u; level++) {
+        let list = level & 1u;
+        let next = list ^ 1u;
+        let iterations = (expand_count + MESH_BRICK_BATCH - 1u) / MESH_BRICK_BATCH;
+
+        // where this iteration's children start on the next list
+        var start = 0u;
+
+        for (var iteration = 0u; iteration < iterations; iteration++) {
+            let slot = iteration * MESH_BRICK_BATCH + lane;
+
+            var node: ${BVH2_NODE_STRUCT.wgsl_ref};
+            var kind = BVH_QUERY_AABB_SKIP;
+
+            if (slot < expand_count) {
+                node = bvh_node(walk_frontier[list][slot]);
+                kind = bvh_query_aabb_classify(node.bounds, node.child_1, query);
+
+                if (kind == BVH_QUERY_AABB_LEAF && !mesh_brick_accept(node.child_2, node.bounds, at.voxel)) {
+                    kind = BVH_QUERY_AABB_SKIP;
+                }
+            }
+
+            if (copied) {
+                workgroupBarrier();
+            }
+
+            // every lane reserves, asking or not, so the subgroup operations stay uniform
+            let child = subgroup_reserve_workgroup(&walk_reserved[next], select(0u, 2u, kind == BVH_QUERY_AABB_DESCEND));
+            let row = subgroup_reserve_workgroup(&walk_rows_reserved, select(0u, 1u, kind == BVH_QUERY_AABB_LEAF));
+
+            if (kind == BVH_QUERY_AABB_DESCEND) {
+                mesh_brick_walk_place(next, child, start, node.child_1);
+                mesh_brick_walk_place(next, child + 1u, start, node.child_2);
+            }
+
+            if (kind == BVH_QUERY_AABB_LEAF) {
+                walk_rows[row % MESH_BRICK_WALK_ROWS] = node.child_2;
+            }
+
+            // every append of the iteration has landed
+            workgroupBarrier();
+
+            // the level's last iteration settles the next level: no node on it ends the walk, and the rows left go
+            let settles = iteration + 1u == iterations;
+
+            if (lane == 0u) {
+                let end = atomicLoad(&walk_reserved[next]);
+                var ends = false;
+
+                if (settles) {
+                    // the list this level read is the next level's to append to
+                    atomicStore(&walk_reserved[list], 0u);
+
+                    ends = end == 0u || level + 1u == ${BVH_QUERY_AABB_LEVEL_BUDGET}u;
+
+                    if (end != 0u && level + 1u == ${BVH_QUERY_AABB_LEVEL_BUDGET}u) {
+                        // deeper than an LBVH over 2^20 leaves goes: what is left is not walked, and the cell is asked for again
+                        atomicAdd(&mesh_brick_counters[${MESH_BRICK_STATISTIC_LEVELS_SHORT}u], 1u);
+                        mesh_brick_walk_flag(build, MESH_BRICK_FLAG_UNFINISHED);
+                    }
+                }
+
+                let spilled = mesh_brick_walk_spilled(start, end);
+                let waiting = atomicLoad(&walk_rows_reserved) - rows_taken;
+                // whole batches as they fill, and every row left when the walk ends
+                let rows = select((waiting / MESH_BRICK_BATCH) * MESH_BRICK_BATCH, waiting, ends);
+                let tasks = mesh_brick_walk_tasks(build, spilled);
+                let batches = mesh_brick_walk_batches(build, rows);
+
+                walk_handoff = MeshBrickWalkHandoff(end, spilled, tasks.x, tasks.y, rows, rows_taken, batches.x, batches.y);
+                rows_taken += rows;
+            }
+
+            let handoff = workgroupUniformLoad(&walk_handoff);
+
+            for (var k = 0u; k < handoff.tasks_kept; k++) {
+                let i = k * MESH_BRICK_BATCH + lane;
+                let record = mesh_brick_task_out(handoff.tasks + k);
+
+                if (i < handoff.spilled) {
+                    mesh_brick_tasks[record + MESH_BRICK_RECORD_HEADER_WORDS + lane] = walk_spill[i];
+                }
+
+                if (lane == 0u) {
+                    mesh_brick_tasks[record] = build;
+                    mesh_brick_tasks[record + 1u] = min(MESH_BRICK_BATCH, handoff.spilled - k * MESH_BRICK_BATCH);
+                }
+            }
+
+            for (var k = 0u; k < handoff.batches_kept; k++) {
+                let i = k * MESH_BRICK_BATCH + lane;
+                let record = mesh_brick_record(handoff.batches + k);
+
+                if (i < handoff.rows) {
+                    mesh_brick_batches[record + MESH_BRICK_RECORD_HEADER_WORDS + lane] = walk_rows[(handoff.rows_from + i) % MESH_BRICK_WALK_ROWS];
+                }
+
+                if (lane == 0u) {
+                    mesh_brick_batches[record] = build;
+                    mesh_brick_batches[record + 1u] = min(MESH_BRICK_BATCH, handoff.rows - k * MESH_BRICK_BATCH);
+                }
+            }
+
+            start = handoff.end;
+            copied = handoff.tasks_kept + handoff.batches_kept != 0u;
+
+            if (settles) {
+                expand_count = min(handoff.end, MESH_BRICK_FRONTIER);
+            }
+        }
+    }
+}
+`, [
+    chunk_brick_clipmap,
+    chunk_brick_provider,
+    chunk_folded_workgroup_index,
+    chunk_bvh_query_aabb_frontier,
+    BVH_NULL_NODE_DEFINITION,
+    BVH2_NODE_STRUCT.declaration_chunk,
+    chunk_subgroup_reserve_workgroup,
+    chunk_mesh_brick_instance,
+    chunk_mesh_brick_walk,
+]);
+
+body.addExtension(WebGPUExtensionType.Subgroups);
+
+/**
+ * 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.from({
+    label: "Brick Clipmap Mesh Gather",
+    resources,
+    body,
+});

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

@@ -0,0 +1,23 @@
+/**
+ * The mesh provider's resolve (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §7.7, as S9 built it): a workgroup
+ * a cell the walks listed, dispatched by its command after the batches. It merges the cell's
+ * accumulators into the staging as any provider merges (§7.6), and leaves its texel and object words
+ * at 0 for the next frame. A taken cell no walk listed, most of them, had no batch and finished its
+ * walks: its staging stays as it is, and the resolve spends nothing on it.
+ *
+ * - A cell a walk of which did not finish sets its retry word (contract 7): free puts its key back on
+ *   the ring, and the cell is built again.
+ * - Contract 2, per texel of a cell a batch reached: the staged byte becomes the least of itself and
+ *   the batches' byte.
+ * - Contract 3, per 2³ object cell: the batches' nearest row replaces the staged object when its byte
+ *   is below the staged cell minimum taken before the merge; ties keep the staged object. The cell's
+ *   four lanes fold their staged texels in through workgroup atomics, and the last of them decides, so
+ *   that no lane waits on another.
+ *
+ * Eight texels a lane: the staging's two words and the accumulators' eight.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_mesh_brick_resolve: ComputeShader;
+import { ComputeShader } from "../../../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_mesh_brick_resolve.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shader_mesh_brick_resolve.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/brick/mesh/shader_mesh_brick_resolve.js"],"names":[],"mappings":"AAoBA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wCAFU,aAAa,CAgGpB;8BApI2B,qCAAqC"}

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

@@ -0,0 +1,135 @@
+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 } from "../../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../../../shader/type/WebGPUArray.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 { BRICK_STAGING_RESOURCE, chunk_brick_clipmap } from "../chunk_brick_clipmap.js";
+import { chunk_mesh_brick_walk } from "./chunk_mesh_brick_walk.js";
+import { MESH_BRICK_COUNTER_RESOLVE_GROUPS, MESH_BRICK_STATISTIC_CELLS_RETRIED } from "./MESH_BRICK.js";
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.createGroup()
+    .add(BRICK_STAGING_RESOURCE)
+    .addStorageBuffer("mesh_brick_counters", WebGPUArray.from(atomic_u32), true)
+    .addStorageBuffer("mesh_brick_accumulators", WebGPUArray.u32, true)
+    .addStorageBuffer("mesh_brick_resolves", WebGPUArray.u32);
+
+/**
+ * The mesh provider's resolve (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §7.7, as S9 built it): a workgroup
+ * a cell the walks listed, dispatched by its command after the batches. It merges the cell's
+ * accumulators into the staging as any provider merges (§7.6), and leaves its texel and object words
+ * at 0 for the next frame. A taken cell no walk listed, most of them, had no batch and finished its
+ * walks: its staging stays as it is, and the resolve spends nothing on it.
+ *
+ * - A cell a walk of which did not finish sets its retry word (contract 7): free puts its key back on
+ *   the ring, and the cell is built again.
+ * - Contract 2, per texel of a cell a batch reached: the staged byte becomes the least of itself and
+ *   the batches' byte.
+ * - Contract 3, per 2³ object cell: the batches' nearest row replaces the staged object when its byte
+ *   is below the staged cell minimum taken before the merge; ties keep the staged object. The cell's
+ *   four lanes fold their staged texels in through workgroup atomics, and the last of them decides, so
+ *   that no lane waits on another.
+ *
+ * Eight texels a lane: the staging's two words and the accumulators' eight.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_mesh_brick_resolve = ComputeShader.from({
+    label: "Brick Clipmap Mesh Resolve",
+    resources,
+    body: CodeChunk.from(
+        //language=WGSL
+        `
+/** per object cell: its staged minimum before the merge (as 255 less the byte), and its lanes done */
+var<workgroup> object_staged: array<atomic<u32>, ${BRICK_OBJECT_CELLS_PER_AXIS ** 3}>;
+var<workgroup> object_lanes: array<atomic<u32>, ${BRICK_OBJECT_CELLS_PER_AXIS ** 3}>;
+
+@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);
+
+    // a folded dispatch's tail
+    if (index >= atomicLoad(&mesh_brick_counters[${MESH_BRICK_COUNTER_RESOLVE_GROUPS}u])) {
+        return;
+    }
+
+    let build = mesh_brick_resolves[index];
+    let accumulator = mesh_brick_accumulator(build);
+    let flags = mesh_brick_accumulators[accumulator + MESH_BRICK_ACCUMULATOR_FLAGS];
+
+    // contract 7: a walk of the cell that did not finish asks for the cell again
+    if (lane == 0u && (flags & MESH_BRICK_FLAG_UNFINISHED) != 0u) {
+        brick_staging[build * BRICK_STAGING_WORDS + BRICK_STAGING_RETRY_WORD] = 1u;
+
+        atomicAdd(&mesh_brick_counters[${MESH_BRICK_STATISTIC_CELLS_RETRIED}u], 1u);
+    }
+
+    // listed for its retry alone: no batch reached it, and its texel and object words are 0
+    if ((flags & MESH_BRICK_FLAG_TOUCHED) == 0u) {
+        return;
+    }
+
+    // eight texels a lane, x fastest, at y = lane mod 8 and z = lane / 8: the staging's two words
+    let y = lane % 8u;
+    let z = lane / 8u;
+    let first = build * BRICK_STAGING_WORDS + 2u * lane;
+
+    var staged_min = vec4<u32>(255u);
+
+    for (var w = 0u; w < 2u; w++) {
+        var word = brick_staging[first + w];
+
+        for (var b = 0u; b < 4u; b++) {
+            let x = 4u * w + b;
+            let texel = accumulator + x + 8u * (y + 8u * z);
+            let shift = 8u * b;
+            let staged = (word >> shift) & 0xffu;
+            let byte = 255u - mesh_brick_accumulators[texel];
+
+            mesh_brick_accumulators[texel] = 0u;
+
+            // contract 2: the encoding is monotone, so the minimum of the bytes is the byte of the minimum
+            word = (word & ~(0xffu << shift)) | (min(staged, byte) << shift);
+
+            let o = x / 2u;
+
+            staged_min[o] = min(staged_min[o], staged);
+        }
+
+        brick_staging[first + w] = word;
+    }
+
+    // contract 3, per object cell: its four lanes each fold in their staged texels, and the last decides
+    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_staged[object], 255u - staged_min[o]);
+
+        if (atomicAdd(&object_lanes[object], 1u) != 3u) {
+            continue;
+        }
+
+        let key = mesh_brick_accumulators[accumulator + MESH_BRICK_ACCUMULATOR_OBJECTS + object];
+
+        mesh_brick_accumulators[accumulator + MESH_BRICK_ACCUMULATOR_OBJECTS + object] = 0u;
+
+        // a bid is never 0: only a byte below 255 bids. Ties keep the staged object
+        if (key != 0u && brick_object_key_byte(key) < 255u - atomicLoad(&object_staged[object])) {
+            brick_staging[build * BRICK_STAGING_WORDS + BRICK_STAGING_DISTANCE_WORDS + object] = brick_object_key_row(key);
+        }
+    }
+}
+`, [
+            chunk_brick_clipmap,
+            chunk_folded_workgroup_index,
+            chunk_mesh_brick_walk,
+            chunk_brick_object,
+        ]),
+});

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

@@ -10,7 +10,9 @@ export const BRICK_FREE_SETTINGS: WebGPUStruct;
  * the cell is within √3/2 voxel of a texel, and |∇d| ≤ 1, so a surface crossing the cell always
  * qualifies. One that does not holds no slot: a slot it held goes back on the free list, and its
  * entry becomes EMPTY on the side most of its texels are on. One that does and holds no slot is
- * marked for store to pop one. Either way its key leaves the pending set, so a mover may queue it again.
+ * marked for store to pop one. Either way its key leaves the pending set, so a mover may queue it again;
+ * unless a provider set the cell's retry word (§7.6, contract 7), when the key stays pending and goes
+ * back on the ring, and the cell is built again from what this frame stores.
  *
  * The cell's last lane to finish decides, so that nothing waits on a barrier: a lane counts itself
  * finished in the low byte of the workgroup's tally, with a texel within a voxel in the next, and its

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

@@ -1 +1 @@
-{"version":3,"file":"shader_brick_clipmap_free.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/brick/shader_brick_clipmap_free.js"],"names":[],"mappings":"AAmBA;;GAEG;AACH,kCAFU,YAAY,CAOE;AAexB;;;;;;;;;;;;;;;;;GAiBG;AACH,wCAFU,aAAa,CA0EpB;6BA9H0B,sCAAsC;8BAHrC,kCAAkC"}
+{"version":3,"file":"shader_brick_clipmap_free.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/brick/shader_brick_clipmap_free.js"],"names":[],"mappings":"AAoBA;;GAEG;AACH,kCAFU,YAAY,CAOE;AAexB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wCAFU,aAAa,CAgFpB;6BAvI0B,sCAAsC;8BAHrC,kCAAkC"}

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

@@ -14,7 +14,8 @@ import {
     BRICK_STAGING_RESOURCE,
     BRICK_STATE_RESOURCE,
     BRICK_TAKE_RESOURCE,
-    chunk_brick_clipmap
+    chunk_brick_clipmap,
+    chunk_brick_clipmap_requeue_pending
 } from "./chunk_brick_clipmap.js";
 
 /**
@@ -48,7 +49,9 @@ resources.createGroup()
  * the cell is within √3/2 voxel of a texel, and |∇d| ≤ 1, so a surface crossing the cell always
  * qualifies. One that does not holds no slot: a slot it held goes back on the free list, and its
  * entry becomes EMPTY on the side most of its texels are on. One that does and holds no slot is
- * marked for store to pop one. Either way its key leaves the pending set, so a mover may queue it again.
+ * marked for store to pop one. Either way its key leaves the pending set, so a mover may queue it again;
+ * unless a provider set the cell's retry word (§7.6, contract 7), when the key stays pending and goes
+ * back on the ring, and the cell is built again from what this frame stores.
  *
  * The cell's last lane to finish decides, so that nothing waits on a barrier: a lane counts itself
  * finished in the low byte of the workgroup's tally, with a texel within a voxel in the next, and its
@@ -123,10 +126,16 @@ fn main(
         textureStore(brick_map, texel, vec4<u32>(side, 0u, 0u, 0u));
     }
 
-    atomicAnd(&brick_pending[key >> 5u], ~(1u << (key & 31u)));
+    if (brick_staging[build * BRICK_STAGING_WORDS + BRICK_STAGING_RETRY_WORD] != 0u) {
+        // a provider could not finish the cell: built again, its key never out of the pending set
+        brick_clipmap_requeue_pending(key, settings.ring_capacity);
+    } else {
+        atomicAnd(&brick_pending[key >> 5u], ~(1u << (key & 31u)));
+    }
 }
 `, [
             chunk_brick_clipmap,
+            chunk_brick_clipmap_requeue_pending,
             chunk_folded_workgroup_index,
             chunk_slot_stack,
         ]),