@woosh/meep-engine 3.58.0 → 3.59.0

package/src/shade/renderer/global_illumination/probe_clipmap/brick/vgeo/shader_vgeo_brick_distance.js

@@ -0,0 +1,273 @@
+import { MESH_SDF_BRICK_TEXEL_COUNT, MESH_SDF_BRICK_TEXELS } from "../../../../geometry/sdf/MESH_SDF.js";
+import { GEOMETRY_ATTRIBUTE_DATA_TYPE } from "../../../../geometry/GEOMETRY_ATTRIBUTE_DATA_TYPE.js";
+import { MESHLET_METADATA_STRUCT } from "../../../../geometry/meshlet/encoding/MESHLET_METADATA_STRUCT.js";
+import { VGEO_MAX_CLUSTER_TRIANGLE_COUNT } from "../../../../geometry/virtual/format/cluster/VGEO_MAX_CLUSTER_TRIANGLE_COUNT.js";
+import { VGEO_INSTANCE_OFFSET } from "../../../../geometry/virtual/runtime/layout/VGEO_INSTANCE_OFFSET.js";
+import { VGEO_INSTANCE_WORDS } from "../../../../geometry/virtual/runtime/layout/VGEO_INSTANCE_WORDS.js";
+import { MATERIAL_METADATA_STRUCT } from "../../../../material/MATERIAL_METADATA_STRUCT.js";
+import { ShadeDrawSide } from "../../../../material/ShadeDrawSide.js";
+import { chunk_triangle_winding_is_reversed } from "../../../../rasterize/chunk_triangle_winding_is_reversed.js";
+import { chunk_scene_database_access } from "../../../../scene/chunk_scene_database_access.js";
+import { CLIPMAP_LEVEL_ARRAY } from "../../../../shader/chunk/clipmap/CLIPMAP_LEVEL_STRUCT.js";
+import {
+    chunk_read_meshlet_triangle_positions
+} from "../../../../shader/chunk/geometry/meshlet/chunk_read_meshlet_triangle_positions.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 { BRICK_OBJECT_CELLS, BRICK_OBJECT_CELLS_PER_AXIS } from "../BRICK_CLIPMAP.js";
+import { COLLECTION_U32_STRUCT_READ } from "../../../../gpu_primitive/COLLECTION_U32_STRUCT_READ.js";
+import { COLLECTION_U32_STRUCT_WRITE } from "../../../../gpu_primitive/COLLECTION_U32_STRUCT_WRITE.js";
+import { BRICK_STAGING_RESOURCE, chunk_brick_clipmap } from "../chunk_brick_clipmap.js";
+import { chunk_brick_object } from "../chunk_brick_object.js";
+import { chunk_brick_provider_cell } from "../chunk_brick_provider.js";
+import { chunk_vgeo_brick_texel } from "./chunk_vgeo_brick_texel.js";
+import { chunk_vgeo_brick_triangle, VGEO_BRICK_TRIANGLE_STRUCT } from "./chunk_vgeo_brick_triangle.js";
+import {
+    VGEO_BRICK_CELL_CLUSTERS,
+    VGEO_BRICK_CELL_OFFSET,
+    VGEO_BRICK_CELL_TRIANGLES,
+    VGEO_BRICK_CELL_WORDS,
+    VGEO_BRICK_DISTANCE_WORKGROUP_SIZE,
+    VGEO_BRICK_SETTINGS,
+    VGEO_BRICK_STATISTIC_TRIANGLES_DROPPED,
+    VGEO_BRICK_STATISTIC_WAITS_DROPPED,
+    VGEO_BRICK_WAIT_WORDS
+} from "./VGEO_BRICK.js";
+
+const CLUSTERS_PER_STEP = VGEO_BRICK_DISTANCE_WORKGROUP_SIZE / VGEO_MAX_CLUSTER_TRIANGLE_COUNT;
+const TEXELS_PER_LANE = MESH_SDF_BRICK_TEXEL_COUNT / VGEO_BRICK_DISTANCE_WORKGROUP_SIZE;
+const T = MESH_SDF_BRICK_TEXELS;
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate("settings", VGEO_BRICK_SETTINGS);
+
+resources.createGroup()
+    .add(BRICK_STAGING_RESOURCE)
+    .addUniform("brick_levels", CLIPMAP_LEVEL_ARRAY)
+    .addStorageBuffer("vgeo_brick_statistics", WebGPUArray.from(atomic_u32), true);
+
+resources.createGroup()
+    // the taken cells a cluster went onto the list of, and their lists, as the cut left them
+    .addStorageBuffer("vgeo_brick_filled", COLLECTION_U32_STRUCT_READ)
+    .addStorageBuffer("vgeo_brick_cells", WebGPUArray.from(u32))
+    // the pair records
+    .addStorageBuffer("instances", WebGPUArray.from(u32))
+    .addStorageBuffer("scene_database", WebGPUArray.from(u32))
+    .addStorageBuffer("materials", WebGPUArray.from(MATERIAL_METADATA_STRUCT))
+    .addStorageBuffer("meshlet_metadata", WebGPUArray.from(MESHLET_METADATA_STRUCT))
+    .addStorageBuffer("meshlet_data", GEOMETRY_ATTRIBUTE_DATA_TYPE)
+    // the cells waiting to be built again, `VGEO_BRICK_WAIT_WORDS` each: the next frame's
+    .addStorageBuffer("vgeo_brick_waiting", COLLECTION_U32_STRUCT_WRITE, true);
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+const VGEO_BRICK_CELL_TRIANGLES = ${VGEO_BRICK_CELL_TRIANGLES}u;
+
+var<workgroup> cell_count: u32;
+
+/** the cut's triangles that come within the band, as the lanes found them, and their count, past the array too */
+var<workgroup> triangles: array<${VGEO_BRICK_TRIANGLE_STRUCT.wgsl_ref}, VGEO_BRICK_CELL_TRIANGLES>;
+var<workgroup> triangle_count: atomic<u32>;
+var<workgroup> triangle_total: u32;
+
+/** the provider's bytes, as the staging packs them; per object cell, its nearest texel's key and its staged minimum */
+var<workgroup> texel_bytes: array<atomic<u32>, BRICK_STAGING_DISTANCE_WORDS>;
+var<workgroup> object_best: array<atomic<u32>, ${BRICK_OBJECT_CELLS}u>;
+var<workgroup> object_staged: array<atomic<u32>, ${BRICK_OBJECT_CELLS}u>;
+
+fn vgeo_brick_triangle_at(i: u32) -> ${VGEO_BRICK_TRIANGLE_STRUCT.wgsl_ref} {
+    return triangles[i];
+}
+
+/** texel \`t\`'s object cell: x fastest, then y, then z, a cell 2³ texels */
+fn vgeo_brick_object_of(t: u32) -> u32 {
+    let x = t % ${T}u;
+    let y = (t / ${T}u) % ${T}u;
+    let z = t / ${T * T}u;
+
+    return (x / 2u) + ${BRICK_OBJECT_CELLS_PER_AXIS}u * ((y / 2u) + ${BRICK_OBJECT_CELLS_PER_AXIS}u * (z / 2u));
+}
+
+@compute @workgroup_size(${VGEO_BRICK_DISTANCE_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) {
+        cell_count = vgeo_brick_filled.count;
+    }
+
+    // a folded dispatch's tail leaves whole
+    if (index >= workgroupUniformLoad(&cell_count)) {
+        return;
+    }
+
+    let build = vgeo_brick_filled.elements[index];
+    let list = build * ${VGEO_BRICK_CELL_WORDS}u;
+    let key = vgeo_brick_cells[list + ${VGEO_BRICK_CELL_OFFSET.KEY}u];
+
+    let at = brick_provider_cell(key, settings.resolution);
+    let clusters = min(vgeo_brick_cells[list + ${VGEO_BRICK_CELL_OFFSET.COUNT}u], ${VGEO_BRICK_CELL_CLUSTERS}u);
+
+    // a cell built with a stand-in waits to be built again, on the list the next frame's wait reads
+    if (lane == 0u && vgeo_brick_cells[list + ${VGEO_BRICK_CELL_OFFSET.WAITS}u] > 0u) {
+        let wait = atomicAdd(&vgeo_brick_waiting.count, 1u);
+
+        if (wait < settings.wait_capacity) {
+            // the header keeps the cell as a waiting cell's words
+            for (var w = 0u; w < ${VGEO_BRICK_WAIT_WORDS}u; w++) {
+                vgeo_brick_waiting.elements[${VGEO_BRICK_WAIT_WORDS}u * wait + w] = vgeo_brick_cells[list + ${VGEO_BRICK_CELL_OFFSET.WAIT}u + w];
+            }
+        } else {
+            atomicAdd(&vgeo_brick_statistics[${VGEO_BRICK_STATISTIC_WAITS_DROPPED}u], 1u);
+        }
+    }
+
+    // ----- the cut's triangles that come within the band: a lane a triangle, of ${CLUSTERS_PER_STEP} clusters at a time -----
+
+    let member = lane % ${VGEO_MAX_CLUSTER_TRIANGLE_COUNT}u;
+
+    for (var k = lane / ${VGEO_MAX_CLUSTER_TRIANGLE_COUNT}u; k < clusters; k += ${CLUSTERS_PER_STEP}u) {
+        let entry = list + ${VGEO_BRICK_CELL_OFFSET.ENTRIES}u + 2u * k;
+        let pair_base = vgeo_brick_cells[entry] * ${VGEO_INSTANCE_WORDS}u;
+        let meshlet = vgeo_brick_cells[entry + 1u];
+
+        if (member >= meshlet_metadata[meshlet].primitive_count) {
+            continue;
+        }
+
+        let positions = read_meshlet_triangle_positions(meshlet, member);
+
+        if (!vgeo_brick_triangle_reaches(pair_base, positions)) {
+            continue;
+        }
+
+        let row = instances[pair_base + ${VGEO_INSTANCE_OFFSET.MESH_INDEX}u];
+        let mesh = scene_read_mesh(&scene_database, row);
+        let node = scene_read_node(&scene_database, mesh.node);
+        let side = materials[mesh.material].draw_side;
+
+        let slot = atomicAdd(&triangle_count, 1u);
+
+        if (slot < VGEO_BRICK_CELL_TRIANGLES) {
+            triangles[slot] = vgeo_brick_triangle(
+                positions, node.global, at.corner,
+                triangle_winding_is_reversed(node, side), side != ${ShadeDrawSide.Double}u,
+                row
+            );
+        }
+    }
+
+    workgroupBarrier();
+
+    if (lane == 0u) {
+        let total = atomicLoad(&triangle_count);
+
+        triangle_total = total;
+
+        if (total > VGEO_BRICK_CELL_TRIANGLES) {
+            atomicAdd(&vgeo_brick_statistics[${VGEO_BRICK_STATISTIC_TRIANGLES_DROPPED}u], total - VGEO_BRICK_CELL_TRIANGLES);
+        }
+    }
+
+    let count = min(workgroupUniformLoad(&triangle_total), VGEO_BRICK_CELL_TRIANGLES);
+
+    // no triangle of the cut comes near the cell: a provider with nothing in a cell writes nothing
+    if (count == 0u) {
+        return;
+    }
+
+    // ----- the texels, ${TEXELS_PER_LANE} a lane, in the cell's own space: texel 0 at its corner -----
+
+    for (var h = 0u; h < ${TEXELS_PER_LANE}u; h++) {
+        let t = lane + h * ${VGEO_BRICK_DISTANCE_WORKGROUP_SIZE}u;
+        let p = vec3<f32>(f32(t % ${T}u), f32((t / ${T}u) % ${T}u), f32(t / ${T * T}u)) * at.voxel;
+
+        let texel = vgeo_brick_texel(p, count, at.band);
+        let byte = brick_encode(texel.distance, at.band);
+
+        atomicOr(&texel_bytes[t / 4u], byte << (8u * (t % 4u)));
+        atomicMax(&object_best[vgeo_brick_object_of(t)], brick_object_key(byte, texel.row));
+    }
+
+    workgroupBarrier();
+
+    // ----- contracts 1 and 2: a lane a staged word, each byte the least of the staged and the provider's -----
+
+    if (lane < BRICK_STAGING_DISTANCE_WORDS) {
+        let word = build * BRICK_STAGING_WORDS + lane;
+        let staged = brick_staging[word];
+        let provided = atomicLoad(&texel_bytes[lane]);
+
+        var merged = 0u;
+
+        for (var b = 0u; b < 4u; b++) {
+            let shift = 8u * b;
+            let s = (staged >> shift) & 0xffu;
+
+            merged |= min(s, (provided >> shift) & 0xffu) << shift;
+
+            // contract 3 weighs the staged minimum from before this provider's merge
+            atomicMax(&object_staged[vgeo_brick_object_of(4u * lane + b)], 255u - s);
+        }
+
+        brick_staging[word] = merged;
+    }
+
+    workgroupBarrier();
+
+    // ----- contract 3: a lane an object cell, the provider's row where its nearest texel is nearer than the staged -----
+
+    if (lane < ${BRICK_OBJECT_CELLS}u) {
+        let nearest = atomicLoad(&object_best[lane]);
+
+        if (brick_object_key_byte(nearest) < 255u - atomicLoad(&object_staged[lane])) {
+            brick_staging[build * BRICK_STAGING_WORDS + BRICK_STAGING_DISTANCE_WORDS + lane] = brick_object_key_row(nearest);
+        }
+    }
+}
+`, [
+    chunk_brick_clipmap,
+    chunk_brick_provider_cell,
+    chunk_brick_object,
+    chunk_folded_workgroup_index,
+    chunk_scene_database_access,
+    chunk_triangle_winding_is_reversed,
+    chunk_read_meshlet_triangle_positions,
+    chunk_vgeo_brick_triangle,
+    chunk_vgeo_brick_texel,
+]);
+
+/**
+ * The vgeo provider's distances (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §7.8): a workgroup a taken cell the box cut
+ * put a cluster on the list of, dispatched by their count (`vgeo_brick_filled`), so the cells without virtual
+ * geometry cost nothing here.
+ *
+ * **Triangles.** A lane a triangle of as many of the list's clusters at a time as the lanes hold whole. A triangle
+ * whose box misses its pair's, the cell grown by the band in the instance's space, is skipped
+ * (`vgeo_brick_triangle_reaches`); the rest go into workgroup memory placed in the cell's own space and wound out
+ * of the surface their instance draws (`vgeo_brick_triangle`), up to {@link VGEO_BRICK_CELL_TRIANGLES}. Past it
+ * they are dropped and counted. A cell none comes near writes nothing.
+ *
+ * **512 texels**, shared out evenly, each `vgeo_brick_texel`: the distance to the nearest triangle within the band,
+ * signed by its side, and its row.
+ *
+ * **The merge.** The provider's bytes meet in workgroup memory, then a lane a staged word takes each byte's least
+ * (contracts 1 and 2), and a lane an object cell writes the provider's row where its nearest texel is nearer than
+ * the staged minimum from before the merge; ties keep the staged object (contract 3).
+ *
+ * @type {ComputeShader}
+ */
+export const shader_vgeo_brick_distance = ComputeShader.from({
+    label: "Brick Clipmap VGeo Distance",
+    resources,
+    body,
+});

package/src/shade/renderer/global_illumination/probe_clipmap/brick/vgeo/shader_vgeo_brick_gather.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The vgeo provider's gather (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §7.8): a 64-lane workgroup a taken cell,
+ * dispatched by take. A cooperative TLAS query with the cell grown by the cascade's band, every leaf filtered by
+ * `vgeo_brick_accept`, and a pair record for each candidate (`vgeo_brick_pair`): the instance cut at a world error
+ * under half the cascade's voxel, within the cell grown by the band. The records and their claim widths are a cut's
+ * collect, so the camera cut's scan, seed and descent run them. Pairs past the records' capacity, and what the query
+ * itself dropped, are counted.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_vgeo_brick_gather: ComputeShader;
+import { ComputeShader } from "../../../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_vgeo_brick_gather.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shader_vgeo_brick_gather.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/brick/vgeo/shader_vgeo_brick_gather.js"],"names":[],"mappings":"AAwIA;;;;;;;;;GASG;AACH,uCAFU,aAAa,CAMpB;8BA3I2B,qCAAqC"}

package/src/shade/renderer/global_illumination/probe_clipmap/brick/vgeo/shader_vgeo_brick_gather.js

@@ -0,0 +1,151 @@
+import { assert } from "../../../../../../core/assert.js";
+import { WebGPUExtensionType } from "../../../../../descriptor/WebGPUExtensionType.js";
+import { GEOMETRY_METADATA_STRUCT } from "../../../../geometry/GEOMETRY_METADATA_STRUCT.js";
+import { COLLECTION_U32_STRUCT_WRITE } from "../../../../gpu_primitive/COLLECTION_U32_STRUCT_WRITE.js";
+import { BVH2_NODE_STRUCT } from "../../../../shader/chunk/bvh/BVH2_NODE_STRUCT.js";
+import { BVH_STRUCT } from "../../../../shader/chunk/bvh/BVH_STRUCT.js";
+import { chunk_bvh_query_aabb_cooperative } from "../../../../shader/chunk/bvh/chunk_bvh_query_aabb_cooperative.js";
+import { BVH_QUERY_AABB_WORKGROUP_SIZE } 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 { 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 { BRICK_CELL_WORKGROUP_SIZE } from "../BRICK_CLIPMAP.js";
+import { BRICK_RING_RESOURCE, BRICK_TAKE_RESOURCE, chunk_brick_clipmap } from "../chunk_brick_clipmap.js";
+import { chunk_brick_provider } from "../chunk_brick_provider.js";
+import { chunk_vgeo_brick_pair } from "./chunk_vgeo_brick_pair.js";
+import {
+    VGEO_BRICK_CELL_OFFSET,
+    VGEO_BRICK_CELL_WORDS,
+    VGEO_BRICK_SETTINGS,
+    VGEO_BRICK_STATISTIC_CANDIDATES_DROPPED,
+    VGEO_BRICK_STATISTIC_NODES_DROPPED,
+    VGEO_BRICK_STATISTIC_PAIRS_DROPPED
+} from "./VGEO_BRICK.js";
+
+// the gather is the whole workgroup's: a cell's workgroup is the query's
+assert.equal(BRICK_CELL_WORKGROUP_SIZE, BVH_QUERY_AABB_WORKGROUP_SIZE, 'a taken cell\'s workgroup runs the cooperative query');
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.setImmediate("settings", VGEO_BRICK_SETTINGS);
+
+resources.createGroup()
+    .add(BRICK_TAKE_RESOURCE)
+    .add(BRICK_RING_RESOURCE)
+    .addUniform("brick_levels", CLIPMAP_LEVEL_ARRAY)
+    .addStorageBuffer("vgeo_brick_statistics", WebGPUArray.from(atomic_u32), true);
+
+resources.createGroup()
+    .addStorageBuffer("tlas", BVH_STRUCT)
+    .addStorageBuffer("scene_database", WebGPUArray.from(u32))
+    .addStorageBuffer("geometries", WebGPUArray.from(GEOMETRY_METADATA_STRUCT))
+    .addStorageBuffer("vg_geometries", WebGPUArray.from(u32));
+
+resources.createGroup()
+    // the pair records, a cut's instance records, in the order the cells reserve them
+    .addStorageBuffer("instances", WebGPUArray.from(u32), true)
+    .addStorageBuffer("claim_widths", COLLECTION_U32_STRUCT_WRITE, true)
+    // the taken cells' lists, whose counts the gather starts at zero for the cells it takes
+    .addStorageBuffer("vgeo_brick_cells", WebGPUArray.from(atomic_u32), true);
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+const VGEO_BRICK_CELL_WORDS = ${VGEO_BRICK_CELL_WORDS}u;
+
+/** the cascade's voxel, the same for the whole workgroup: what the gather's resolution cull weighs a box by */
+var<private> vgeo_brick_voxel: f32;
+
+var<workgroup> cell_taken: u32;
+
+fn bvh_query_aabb_node(index: u32) -> ${BVH2_NODE_STRUCT.wgsl_ref} {
+    return tlas.nodes[index];
+}
+
+fn bvh_query_aabb_accept_leaf(payload: u32, bounds: array<f32, 6>) -> bool {
+    return vgeo_brick_accept(payload, bounds, vgeo_brick_voxel);
+}
+
+@compute @workgroup_size(${BRICK_CELL_WORKGROUP_SIZE})
+fn main(
+    @builtin(workgroup_id) workgroup_id: vec3<u32>,
+    @builtin(local_invocation_index) lane: u32,
+) {
+    let build = folded_workgroup_index(workgroup_id);
+
+    if (lane == 0u) {
+        cell_taken = brick_take[BRICK_TAKE_COUNT];
+    }
+
+    // a folded dispatch's tail leaves whole
+    if (build >= workgroupUniformLoad(&cell_taken)) {
+        return;
+    }
+
+    let key = brick_provider_key(build, settings.ring_capacity);
+    let at = brick_provider_cell(key, settings.resolution);
+
+    vgeo_brick_voxel = at.voxel;
+
+    // this cell's list, empty and waiting on nothing before the cut fills it, and the key it is the list of: only the
+    // taken cells' lists are read
+    if (lane == 0u) {
+        let list = build * VGEO_BRICK_CELL_WORDS;
+
+        atomicStore(&vgeo_brick_cells[list + ${VGEO_BRICK_CELL_OFFSET.COUNT}u], 0u);
+        atomicStore(&vgeo_brick_cells[list + ${VGEO_BRICK_CELL_OFFSET.KEY}u], key);
+        atomicStore(&vgeo_brick_cells[list + ${VGEO_BRICK_CELL_OFFSET.WAITS}u], 0u);
+    }
+
+    // every vgeo instance whose box comes within the band of the cell, and the box each is cut in
+    let lower = at.corner - vec3<f32>(at.band);
+    let upper = at.far + vec3<f32>(at.band);
+
+    let gathered = bvh_query_aabb_cooperative(tlas.root, array<f32, 6>(lower.x, lower.y, lower.z, upper.x, upper.y, upper.z), lane);
+
+    // a lane a candidate, over the query's whole list
+    for (var i = lane; i < gathered.candidate_count; i += ${BRICK_CELL_WORKGROUP_SIZE}u) {
+        if (!vgeo_brick_pair(bvh_query_aabb_candidates[i], build, lower, upper, at.voxel, settings.pair_capacity)) {
+            atomicAdd(&vgeo_brick_statistics[${VGEO_BRICK_STATISTIC_PAIRS_DROPPED}u], 1u);
+        }
+    }
+
+    if (lane == 0u) {
+        if (gathered.candidates_dropped > 0u) {
+            atomicAdd(&vgeo_brick_statistics[${VGEO_BRICK_STATISTIC_CANDIDATES_DROPPED}u], gathered.candidates_dropped);
+        }
+
+        if (gathered.nodes_dropped > 0u) {
+            atomicAdd(&vgeo_brick_statistics[${VGEO_BRICK_STATISTIC_NODES_DROPPED}u], gathered.nodes_dropped);
+        }
+    }
+}
+`, [
+    chunk_brick_clipmap,
+    chunk_brick_provider,
+    chunk_folded_workgroup_index,
+    chunk_bvh_query_aabb_cooperative,
+    chunk_vgeo_brick_pair,
+]);
+
+body.addExtension(WebGPUExtensionType.Subgroups);
+
+/**
+ * The vgeo provider's gather (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §7.8): a 64-lane workgroup a taken cell,
+ * dispatched by take. A cooperative TLAS query with the cell grown by the cascade's band, every leaf filtered by
+ * `vgeo_brick_accept`, and a pair record for each candidate (`vgeo_brick_pair`): the instance cut at a world error
+ * under half the cascade's voxel, within the cell grown by the band. The records and their claim widths are a cut's
+ * collect, so the camera cut's scan, seed and descent run them. Pairs past the records' capacity, and what the query
+ * itself dropped, are counted.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_vgeo_brick_gather = ComputeShader.from({
+    label: "Brick Clipmap VGeo Gather",
+    resources,
+    body,
+});

package/src/shade/renderer/global_illumination/probe_clipmap/brick/vgeo/shader_vgeo_brick_traverse.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The vgeo provider's box cut (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §7.8): the camera cut's descent
+ * (`chunk_vgeo_cut_descent`) over the gather's pair records, culled against each pair's box, at the world error
+ * its record's projection constant sets against a τ of 1. A cluster in the cut, a stand-in for a page not yet
+ * resident too, goes onto its taken cell's list; a clamp wants its page through the cut's own feedback slot, as
+ * the camera's do. A cell's first stand-in goes into its list's header with what its want was made of, so that
+ * the wait can want that page again while the cell waits (`VGEO_BRICK_WAIT_OFFSET`).
+ *
+ * @type {ComputeShader}
+ */
+export const shader_vgeo_brick_traverse: ComputeShader;
+import { ComputeShader } from "../../../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_vgeo_brick_traverse.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shader_vgeo_brick_traverse.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/brick/vgeo/shader_vgeo_brick_traverse.js"],"names":[],"mappings":"AAsHA;;;;;;;;;GASG;AACH,yCAFU,aAAa,CAMpB;8BA3H2B,qCAAqC"}

package/src/shade/renderer/global_illumination/probe_clipmap/brick/vgeo/shader_vgeo_brick_traverse.js

@@ -0,0 +1,133 @@
+import { WebGPUExtensionType } from "../../../../../descriptor/WebGPUExtensionType.js";
+import { chunk_vgeo_cut_access } from "../../../../geometry/virtual/runtime/cut/chunk_vgeo_cut_access.js";
+import { chunk_vgeo_cut_descent } from "../../../../geometry/virtual/runtime/cut/chunk_vgeo_cut_descent.js";
+import { VGEO_CUT_PARAMS_STRUCT } from "../../../../geometry/virtual/runtime/cut/VGEO_CUT_PARAMS_STRUCT.js";
+import { VGEO_CUT_STAT } from "../../../../geometry/virtual/runtime/layout/VGEO_CUT_STAT.js";
+import { VGEO_PAGE_ROW_OFFSET } from "../../../../geometry/virtual/runtime/layout/VGEO_PAGE_ROW_OFFSET.js";
+import { COLLECTION_U32_STRUCT_READ } from "../../../../gpu_primitive/COLLECTION_U32_STRUCT_READ.js";
+import { COLLECTION_U32_STRUCT_WRITE } from "../../../../gpu_primitive/COLLECTION_U32_STRUCT_WRITE.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 { chunk_vgeo_brick_box } from "./chunk_vgeo_brick_box.js";
+import { VGEO_INSTANCE_OFFSET } from "../../../../geometry/virtual/runtime/layout/VGEO_INSTANCE_OFFSET.js";
+import {
+    VGEO_BRICK_CELL_CLUSTERS,
+    VGEO_BRICK_CELL_OFFSET,
+    VGEO_BRICK_CELL_WORDS,
+    VGEO_BRICK_PAIR_BUILD,
+    VGEO_BRICK_WAIT_OFFSET
+} from "./VGEO_BRICK.js";
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.createGroup()
+    .addUniform("params", VGEO_CUT_PARAMS_STRUCT)
+    .addStorageBuffer("vg_lookup", WebGPUArray.from(u32), false)
+    .addStorageBuffer("vg_arena", WebGPUArray.from(u32), false)
+;
+
+resources.createGroup()
+    .addStorageBuffer("instances", WebGPUArray.from(u32), false)
+    .addStorageBuffer("queue_in", COLLECTION_U32_STRUCT_READ, false)
+    .addStorageBuffer("queue_out", COLLECTION_U32_STRUCT_WRITE, true)
+;
+
+resources.createGroup()
+    .addStorageBuffer("claim", WebGPUArray.from(atomic_u32), true)
+    .addStorageBuffer("feedback", WebGPUArray.from(atomic_u32), true)
+    .addStorageBuffer("vg_want_stamps", WebGPUArray.from(atomic_u32), true)
+    // a list a taken cell: its count, its key, then a cluster's pair and meshlet row each
+    .addStorageBuffer("vgeo_brick_cells", WebGPUArray.from(atomic_u32), true)
+    // the cells a cluster went onto the list of, each once: the distance pass's
+    .addStorageBuffer("vgeo_brick_filled", COLLECTION_U32_STRUCT_WRITE, true)
+;
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+/**
+ * The rule's culls, against the pair's box in the instance's object space: a subtree whose bound lies wholly
+ * past one of the box's six faces has nothing within the cell's band. The camera's frustum tests with the box's
+ * faces for the frustum's planes; conservative where a bound passes the box's corner without crossing any one face.
+ *
+ * Against axis-aligned faces a sphere is exactly its cube, so a sphere is tested as one. A cluster's subtree box
+ * lies within its sphere's cube, so there the box decides; a node, which has only its sphere, is culled by it alone.
+ */
+fn vg_cut_sphere_outside(instance_base: u32, sphere: vec4<f32>) -> bool {
+    return vg_cut_box_outside(instance_base, sphere.xyz - vec3<f32>(sphere.w), sphere.xyz + vec3<f32>(sphere.w));
+}
+
+fn vg_cut_box_outside(instance_base: u32, lower: vec3<f32>, upper: vec3<f32>) -> bool {
+    return any(upper < vgeo_brick_box_lower(instance_base)) || any(lower > vgeo_brick_box_upper(instance_base));
+}
+
+/**
+ * A cluster in the cut, a stand-in's too, onto its cell's list as its pair and its meshlet row. A list keeps
+ * counting past what it holds, so its reader takes the least of its count and its size. A cell's first cluster
+ * puts the cell on the distance pass's list, once.
+ *
+ * A stand-in, for a page not resident (a clamp) or a group not selectable (held), makes the cell wait: it is built
+ * again once that page is resident and that group selectable. The cell's first stand-in is the one it waits on; a
+ * cell rebuilt with others still standing in waits again, on one of them.
+ */
+fn vg_cut_take(instance_base: u32, page_row: u32, verdict: VGVerdict) {
+    let build = instances[instance_base + ${VGEO_BRICK_PAIR_BUILD}u];
+    let list = build * ${VGEO_BRICK_CELL_WORDS}u;
+
+    let slot = atomicAdd(&vgeo_brick_cells[list + ${VGEO_BRICK_CELL_OFFSET.COUNT}u], 1u);
+
+    if (slot == 0u) {
+        vgeo_brick_filled.elements[atomicAdd(&vgeo_brick_filled.count, 1u)] = build;
+    }
+
+    // the first stand-in: what the cell waits on, and what wants it while it is away
+    if (verdict.kind != VG_VERDICT_TAKE && atomicAdd(&vgeo_brick_cells[list + ${VGEO_BRICK_CELL_OFFSET.WAITS}u], 1u) == 0u) {
+        let wait = list + ${VGEO_BRICK_CELL_OFFSET.WAIT}u;
+
+        atomicStore(&vgeo_brick_cells[wait + ${VGEO_BRICK_WAIT_OFFSET.LOOKUP}u], instances[instance_base + ${VGEO_INSTANCE_OFFSET.LOOKUP_WORD_OFFSET}u]);
+        atomicStore(&vgeo_brick_cells[wait + ${VGEO_BRICK_WAIT_OFFSET.PAGE}u], verdict.child_page_index);
+        atomicStore(&vgeo_brick_cells[wait + ${VGEO_BRICK_WAIT_OFFSET.GROUP}u], verdict.child_group);
+        atomicStore(&vgeo_brick_cells[wait + ${VGEO_BRICK_WAIT_OFFSET.SOURCE}u], page_row);
+        atomicStore(&vgeo_brick_cells[wait + ${VGEO_BRICK_WAIT_OFFSET.SOURCE_PAGE}u], vg_page_field(page_row, ${VGEO_PAGE_ROW_OFFSET.PAGE_INDEX}u));
+        atomicStore(&vgeo_brick_cells[wait + ${VGEO_BRICK_WAIT_OFFSET.REF}u], verdict.child_ref);
+        atomicStore(&vgeo_brick_cells[wait + ${VGEO_BRICK_WAIT_OFFSET.ERROR}u], bitcast<u32>(verdict.projected));
+    }
+
+    if (slot >= ${VGEO_BRICK_CELL_CLUSTERS}u) {
+        vg_stat(${VGEO_CUT_STAT.MESHLETS_DROPPED}u, 1u);
+        return;
+    }
+
+    let entry = list + ${VGEO_BRICK_CELL_OFFSET.ENTRIES}u + 2u * slot;
+
+    atomicStore(&vgeo_brick_cells[entry], instance_base / VG_INSTANCE_WORDS);
+    atomicStore(&vgeo_brick_cells[entry + 1u], vg_page_field(page_row, ${VGEO_PAGE_ROW_OFFSET.MESHLET_BASE}u) + verdict.cluster);
+
+    vg_stat(${VGEO_CUT_STAT.DRAWN}u, 1u);
+}
+`, [
+    chunk_vgeo_cut_descent,
+    chunk_vgeo_cut_access,
+    chunk_vgeo_brick_box,
+]);
+
+body.addExtension(WebGPUExtensionType.Subgroups);
+
+/**
+ * The vgeo provider's box cut (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §7.8): the camera cut's descent
+ * (`chunk_vgeo_cut_descent`) over the gather's pair records, culled against each pair's box, at the world error
+ * its record's projection constant sets against a τ of 1. A cluster in the cut, a stand-in for a page not yet
+ * resident too, goes onto its taken cell's list; a clamp wants its page through the cut's own feedback slot, as
+ * the camera's do. A cell's first stand-in goes into its list's header with what its want was made of, so that
+ * the wait can want that page again while the cell waits (`VGEO_BRICK_WAIT_OFFSET`).
+ *
+ * @type {ComputeShader}
+ */
+export const shader_vgeo_brick_traverse = ComputeShader.from({
+    label: "Brick Clipmap VGeo Cut",
+    resources,
+    body,
+});

package/src/shade/renderer/global_illumination/probe_clipmap/brick/vgeo/shader_vgeo_brick_wait.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Lanes of the wait: a waiting cell each.
+ * @type {number}
+ */
+export const VGEO_BRICK_WAIT_WORKGROUP_SIZE: number;
+/**
+ * The vgeo provider's wait (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §7.6 contract 6, §7.8): a thread a cell the last
+ * frame left waiting, built while a cluster of its cut stood in for a page not resident or a group not selectable.
+ * A cell whose page is resident and whose group is selectable now is queued again with `brick_clipmap_enqueue`, so
+ * exactly the cells that stood something in are built again, once what they waited on is there. The rest wait on,
+ * onto the list this frame's distance pass adds its own to (and counts those past its capacity).
+ *
+ * A want lasts the reading it is in (`VGeoResidency.apply` drops what its budgets defer), so a cell waiting on a page
+ * not resident wants it again, each frame, through the provider's cut's slot (`vg_want`): through the page its
+ * stand-in was found in, while that row still holds that page. Once it holds another, the cell is queued again
+ * instead, and its cut finds the way down anew. A group held back carries no want, as in the cut.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_vgeo_brick_wait: ComputeShader;
+import { ComputeShader } from "../../../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_vgeo_brick_wait.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shader_vgeo_brick_wait.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/brick/vgeo/shader_vgeo_brick_wait.js"],"names":[],"mappings":"AAqBA;;;GAGG;AACH,6CAFU,MAAM,CAEiC;AA2FjD;;;;;;;;;;;;;GAaG;AACH,qCAFU,aAAa,CAMpB;8BA9H2B,qCAAqC"}