@woosh/meep-engine 3.58.0 → 3.59.0

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

@@ -0,0 +1,139 @@
+import { assert } from "../../../../../../core/assert.js";
+import { MESH_SDF_BRICK_TEXEL_COUNT } from "../../../../geometry/sdf/MESH_SDF.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 { u32 } from "../../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../../../../shader/type/WebGPUStruct.js";
+
+/*
+ The vgeo brick provider's layouts (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §7.8).
+
+ A pair is a taken cell and a vgeo instance whose box reaches it. Its record is a cut's instance record
+ (VGEO_INSTANCE_OFFSET), so the camera cut's seed and descent run it unchanged; what a view keeps for its own
+ culls, the pair keeps for the box's.
+*/
+
+/**
+ * The provider's settings, an immediate of each of its passes.
+ * @type {WebGPUStruct}
+ */
+export const VGEO_BRICK_SETTINGS = WebGPUStruct.from({
+    /** keys `brick_ring` holds, a power of two */
+    ring_capacity: u32,
+    /** cells a cascade's window has a side */
+    resolution: u32,
+    /** pair records the frame holds */
+    pair_capacity: u32,
+    /** waiting cells a waiting list holds */
+    wait_capacity: u32,
+}, "VGeoBrickSettings");
+
+/**
+ * Where a pair record keeps the box it is cut against: the cell grown by the field's band, in the instance's
+ * object space, lower xyz then upper xyz, in the words a view's record keeps its frustum in.
+ * @type {number}
+ */
+export const VGEO_BRICK_PAIR_BOX = VGEO_INSTANCE_OFFSET.FRUSTUM;
+
+/**
+ * Where a pair record keeps its taken cell: the first word a view's record leaves free.
+ * @type {number}
+ */
+export const VGEO_BRICK_PAIR_BUILD = VGEO_INSTANCE_OFFSET.DISTANCE_WEIGHT + 1;
+
+assert.lessThan(VGEO_BRICK_PAIR_BUILD, VGEO_INSTANCE_WORDS, 'a pair record keeps its cell inside the record');
+
+/**
+ * Pair records a frame holds, for each cell of its take budget; past them, pairs are dropped and counted.
+ * @type {number}
+ */
+export const VGEO_BRICK_PAIRS_PER_CELL = 8;
+
+/**
+ * Clusters a taken cell's list holds; past them, clusters are dropped and counted.
+ * @type {number}
+ */
+export const VGEO_BRICK_CELL_CLUSTERS = 64;
+
+/**
+ * A waiting cell: its key, then what the first cluster of its cut that stood something in waits on, and what wants
+ * it. The page it waits on is `PAGE` of the geometry whose page lookup starts at `LOOKUP`, and `GROUP` is the group in
+ * that page. The want for that page goes through the page the cluster was found in: `SOURCE` is its row, `SOURCE_PAGE`
+ * its own page index in the geometry, `REF` the entry of its child table naming the page, and `ERROR` the cluster's
+ * projected error, as the want's priority (`vg_want`). A group held back carries no want, as in the cut, whose rule
+ * leaves a held verdict's `REF` and `ERROR` at zero: the clamp beside it wants the page that holds it back.
+ */
+export const VGEO_BRICK_WAIT_OFFSET = Object.freeze({
+    KEY: 0,
+    LOOKUP: 1,
+    PAGE: 2,
+    GROUP: 3,
+    SOURCE: 4,
+    SOURCE_PAGE: 5,
+    REF: 6,
+    ERROR: 7,
+});
+
+/**
+ * Words of a waiting cell.
+ * @type {number}
+ */
+export const VGEO_BRICK_WAIT_WORDS = 8;
+
+/**
+ * A taken cell's list: its header, then from `ENTRIES` a cluster's pair and meshlet row each. The header holds the
+ * clusters taken (a count that runs past what the list holds), how many of them stood in for a page or a group not
+ * there yet, and from `WAIT` the cell as a waiting cell's words ({@link VGEO_BRICK_WAIT_OFFSET}): its key, then the
+ * first stand-in's wait, which the distances copy onto the waiting list whole.
+ */
+export const VGEO_BRICK_CELL_OFFSET = Object.freeze({
+    COUNT: 0,
+    WAITS: 1,
+    WAIT: 2,
+    KEY: 2 + VGEO_BRICK_WAIT_OFFSET.KEY,
+    ENTRIES: 2 + VGEO_BRICK_WAIT_WORDS,
+});
+
+/**
+ * Words of a taken cell's list.
+ * @type {number}
+ */
+export const VGEO_BRICK_CELL_WORDS = VGEO_BRICK_CELL_OFFSET.ENTRIES + 2 * VGEO_BRICK_CELL_CLUSTERS;
+
+/**
+ * Waiting cells the provider holds, for each cell of the take budget; past them, a cell that stood a cluster in is
+ * dropped and counted, and is not built again when its page arrives.
+ * @type {number}
+ */
+export const VGEO_BRICK_WAITS_PER_CELL = 4;
+
+/**
+ * Triangles of a taken cell's cut that its distances are made from, in workgroup memory (§7.8, chosen): past
+ * them, triangles are dropped and counted, and a dropped triangle can leave a hole. A texel's distance is a loop
+ * over them.
+ * @type {number}
+ */
+export const VGEO_BRICK_CELL_TRIANGLES = 256;
+
+/**
+ * Lanes of the distance pass, a workgroup a taken cell: a lane a triangle, of as many of the cell's clusters at a
+ * time as the lanes hold whole, then the cell's texels shared out evenly.
+ * @type {number}
+ */
+export const VGEO_BRICK_DISTANCE_WORKGROUP_SIZE = 2 * VGEO_MAX_CLUSTER_TRIANGLE_COUNT;
+
+assert.equal(MESH_SDF_BRICK_TEXEL_COUNT % VGEO_BRICK_DISTANCE_WORKGROUP_SIZE, 0, 'the distance pass shares a cell\'s texels out evenly');
+assert.lessThanOrEqual(VGEO_BRICK_DISTANCE_WORKGROUP_SIZE, 256, 'the distance pass\'s workgroup is within WebGPU\'s default invocation limit');
+
+/**
+ * Words of the provider's statistics, every one an atomic that accumulates: pairs dropped (the records were full,
+ * or the instance's transform flattens it), candidates and subtrees the gather's query dropped, triangles the
+ * distance pass dropped past {@link VGEO_BRICK_CELL_TRIANGLES}, and waiting cells dropped past the waiting list.
+ */
+export const VGEO_BRICK_STATISTIC_PAIRS_DROPPED = 0;
+export const VGEO_BRICK_STATISTIC_CANDIDATES_DROPPED = 1;
+export const VGEO_BRICK_STATISTIC_NODES_DROPPED = 2;
+export const VGEO_BRICK_STATISTIC_TRIANGLES_DROPPED = 3;
+export const VGEO_BRICK_STATISTIC_WAITS_DROPPED = 4;
+export const VGEO_BRICK_STATISTIC_WORDS = 8;

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

@@ -0,0 +1,65 @@
+/**
+ * @typedef {import("../GPUBrickClipmap.js").BrickProviderContext} BrickProviderContext
+ * @typedef {import("../../../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} FrameGraph
+ */
+/**
+ * The world's bricks from virtual geometry, which has no cached field (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §7.8): a
+ * {@link BrickProvider} like any plugin, which the probe clipmap GI runs after the mesh provider.
+ *
+ * Per taken cell, the vgeo instances in the SDF world whose boxes reach it are cut at a world error under half the
+ * cascade's voxel, within the cell grown by the field's band, by the camera cut's own descent. The gather writes
+ * their pair records as a cut's collect would; `graph_vgeo_cut_descent` runs the box cut,
+ * `shader_vgeo_brick_traverse`, which puts each cluster in the cut onto its cell's list. The cut is a
+ * {@link VGeoViewCut} of its own, so its wants reach the residency through its own feedback slot, ranked with the
+ * camera's, and its counters come back to it ({@link cut}'s `stats`). Then `shader_vgeo_brick_distance` takes each
+ * list's triangles near its cell and merges the cell's texels into the staging (contracts 1 to 3).
+ *
+ * A cell built while a cluster of its cut stood in for a page not resident, or a group not selectable, waits:
+ * each frame `shader_vgeo_brick_wait` queues it again once that page is resident and that group selectable
+ * (contract 6), so exactly the cells that stood something in are built again, once what they waited on arrived.
+ * Until then it wants the page again each frame, in the cut's slot, since a want lasts one reading.
+ *
+ * It reads the view's scene through the context: the TLAS over the mesh rows, the scene database, the geometries'
+ * rows, the materials, the meshlets and the scene's virtual geometry runtime. With no runtime, or none open this
+ * frame, it records nothing.
+ */
+export class VGeoBrickProvider {
+    /**
+     * @param {GPUDevice} device
+     */
+    constructor(device: GPUDevice);
+    /**
+     * @returns {GPUBuffer}
+     */
+    get statistics(): GPUBuffer;
+    /**
+     * The box cut, whose `stats` say what the last reading of its slot counted.
+     * @returns {VGeoViewCut}
+     */
+    get cut(): VGeoViewCut;
+    /**
+     * The taken cells' lists of the frame last recorded, a resource of its graph, or -1 when it recorded none:
+     * `VGEO_BRICK_CELL_WORDS` words a taken cell, laid out as `VGEO_BRICK_CELL_OFFSET`. A count runs past what its
+     * list holds; read the least of the two.
+     * @returns {number}
+     */
+    get cells(): number;
+    /**
+     * The waiting list the next recorded frame's wait reads: a count, then `VGEO_BRICK_WAIT_WORDS` words a cell, laid
+     * out as `VGEO_BRICK_WAIT_OFFSET`. The count runs past what the list holds. Undefined before the provider first
+     * records.
+     * @returns {GPUBuffer|undefined}
+     */
+    get waiting(): any;
+    /**
+     * @param {FrameGraph} graph
+     * @param {BrickProviderContext} context
+     */
+    graph_write_bricks(graph: FrameGraph, context: BrickProviderContext): void;
+    destroy(): void;
+    #private;
+}
+export type BrickProviderContext = import("../GPUBrickClipmap.js").BrickProviderContext;
+export type FrameGraph = import("../../../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
+import { VGeoViewCut } from "../../../../geometry/virtual/runtime/VGeoViewCut.js";
+//# sourceMappingURL=VGeoBrickProvider.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"VGeoBrickProvider.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/brick/vgeo/VGeoBrickProvider.js"],"names":[],"mappings":"AA0BA;;;GAGG;AAEH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH;IA6CI;;OAEG;IACH,+BAWC;IAED;;OAEG;IACH,4BAEC;IAED;;;OAGG;IACH,uBAEC;IAED;;;;;OAKG;IACH,oBAEC;IAED;;;;;OAKG;IACH,mBAEC;IAED;;;OAGG;IACH,0BAHW,UAAU,WACV,oBAAoB,QAuH9B;IA4GD,gBAcC;;CACJ;mCA7WY,OAAO,uBAAuB,EAAE,oBAAoB;yBACpD,OAAO,oEAAoE,EAAE,UAAU;4BAtBxE,qDAAqD"}

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

@@ -0,0 +1,393 @@
+import { assert } from "../../../../../../core/assert.js";
+import { BufferDescriptor } from "../../../../../descriptor/buffer/BufferDescriptor.js";
+import { BufferResourceDescriptor } from "../../../../../device/graph/BufferResourceDescriptor.js";
+import { graph_vgeo_cut_descent } from "../../../../geometry/virtual/runtime/graph_vgeo_cut_descent.js";
+import { graph_build_indirect_dispatch_command } from "../../../../gpu_primitive/indirect/IndirectComputeCommandBuildPass.js";
+import { VGEO_INSTANCE_WORDS } from "../../../../geometry/virtual/runtime/layout/VGEO_INSTANCE_WORDS.js";
+import { VGeoViewCut } from "../../../../geometry/virtual/runtime/VGeoViewCut.js";
+import {
+    graph_prefix_scan_csdldf,
+    prefix_scan_csdldf_output_descriptor
+} from "../../../../gpu_primitive/prefix_sum/v1/graph_prefix_scan_csdldf.js";
+import { graph_create_buffer } from "../../../../shader/graph/graph_create_buffer.js";
+import { graph_import_buffer } from "../../../../shader/graph/graph_import_buffer.js";
+import { BRICK_TAKE_CELL_DISPATCH } from "../BRICK_CLIPMAP.js";
+import { shader_vgeo_brick_distance } from "./shader_vgeo_brick_distance.js";
+import { shader_vgeo_brick_gather } from "./shader_vgeo_brick_gather.js";
+import { shader_vgeo_brick_traverse } from "./shader_vgeo_brick_traverse.js";
+import { shader_vgeo_brick_wait, VGEO_BRICK_WAIT_WORKGROUP_SIZE } from "./shader_vgeo_brick_wait.js";
+import {
+    VGEO_BRICK_CELL_WORDS,
+    VGEO_BRICK_PAIRS_PER_CELL,
+    VGEO_BRICK_STATISTIC_WORDS,
+    VGEO_BRICK_WAIT_WORDS,
+    VGEO_BRICK_WAITS_PER_CELL
+} from "./VGEO_BRICK.js";
+
+/**
+ * @typedef {import("../GPUBrickClipmap.js").BrickProviderContext} BrickProviderContext
+ * @typedef {import("../../../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} FrameGraph
+ */
+
+/**
+ * The world's bricks from virtual geometry, which has no cached field (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §7.8): a
+ * {@link BrickProvider} like any plugin, which the probe clipmap GI runs after the mesh provider.
+ *
+ * Per taken cell, the vgeo instances in the SDF world whose boxes reach it are cut at a world error under half the
+ * cascade's voxel, within the cell grown by the field's band, by the camera cut's own descent. The gather writes
+ * their pair records as a cut's collect would; `graph_vgeo_cut_descent` runs the box cut,
+ * `shader_vgeo_brick_traverse`, which puts each cluster in the cut onto its cell's list. The cut is a
+ * {@link VGeoViewCut} of its own, so its wants reach the residency through its own feedback slot, ranked with the
+ * camera's, and its counters come back to it ({@link cut}'s `stats`). Then `shader_vgeo_brick_distance` takes each
+ * list's triangles near its cell and merges the cell's texels into the staging (contracts 1 to 3).
+ *
+ * A cell built while a cluster of its cut stood in for a page not resident, or a group not selectable, waits:
+ * each frame `shader_vgeo_brick_wait` queues it again once that page is resident and that group selectable
+ * (contract 6), so exactly the cells that stood something in are built again, once what they waited on arrived.
+ * Until then it wants the page again each frame, in the cut's slot, since a want lasts one reading.
+ *
+ * It reads the view's scene through the context: the TLAS over the mesh rows, the scene database, the geometries'
+ * rows, the materials, the meshlets and the scene's virtual geometry runtime. With no runtime, or none open this
+ * frame, it records nothing.
+ */
+export class VGeoBrickProvider {
+    /** @type {GPUDevice} */
+    #device;
+
+    /** @type {VGeoViewCut} */
+    #cut;
+
+    /**
+     * Counts that accumulate: pairs dropped, and candidates and subtrees the gather dropped
+     * (`VGEO_BRICK_STATISTIC_*`).
+     * @type {GPUBuffer}
+     */
+    #statistics;
+
+    /**
+     * The two waiting lists: the one the next frame's wait reads, `#waiting_read`, and the one it keeps onto, which the
+     * distance pass adds its own to. They trade places each frame the provider records.
+     * @type {GPUBuffer[]}
+     */
+    #waiting = [];
+    #waiting_read = 0;
+    #waiting_capacity = 0;
+
+    #settings = { ring_capacity: 0, resolution: 0, pair_capacity: 0, wait_capacity: 0 };
+    #wait_data = { command: -1, waiting_in: -1, waiting: -1, feedback: -1, state: -1 };
+    #wait_bindings = {};
+    #gather_data = { take: -1, instances: -1, claim_widths: -1, cells: -1 };
+    #gather_bindings = {};
+    #distance_data = { command: -1, filled: -1, cells: -1, instances: -1, waiting: -1, staging: -1 };
+    #distance_bindings = {};
+
+    /**
+     * The taken cells' lists as the last recorded frame's cut left them, or -1.
+     * @type {number}
+     */
+    #cells = -1;
+
+    /**
+     * The context of the frame being recorded, as its passes execute.
+     * @type {BrickProviderContext|null}
+     */
+    #context = null;
+
+    #destroyed = false;
+
+    /**
+     * @param {GPUDevice} device
+     */
+    constructor(device) {
+        assert.defined(device, 'device');
+
+        this.#device = device;
+        this.#cut = new VGeoViewCut({ device, label: 'probe clipmap vgeo bricks' });
+
+        this.#statistics = device.createBuffer(BufferDescriptor.fromJSON({
+            label: 'Probe clipmap / vgeo brick statistics',
+            size: 4 * VGEO_BRICK_STATISTIC_WORDS,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC,
+        }));
+    }
+
+    /**
+     * @returns {GPUBuffer}
+     */
+    get statistics() {
+        return this.#statistics;
+    }
+
+    /**
+     * The box cut, whose `stats` say what the last reading of its slot counted.
+     * @returns {VGeoViewCut}
+     */
+    get cut() {
+        return this.#cut;
+    }
+
+    /**
+     * The taken cells' lists of the frame last recorded, a resource of its graph, or -1 when it recorded none:
+     * `VGEO_BRICK_CELL_WORDS` words a taken cell, laid out as `VGEO_BRICK_CELL_OFFSET`. A count runs past what its
+     * list holds; read the least of the two.
+     * @returns {number}
+     */
+    get cells() {
+        return this.#cells;
+    }
+
+    /**
+     * The waiting list the next recorded frame's wait reads: a count, then `VGEO_BRICK_WAIT_WORDS` words a cell, laid
+     * out as `VGEO_BRICK_WAIT_OFFSET`. The count runs past what the list holds. Undefined before the provider first
+     * records.
+     * @returns {GPUBuffer|undefined}
+     */
+    get waiting() {
+        return this.#waiting[this.#waiting_read];
+    }
+
+    /**
+     * @param {FrameGraph} graph
+     * @param {BrickProviderContext} context
+     */
+    graph_write_bricks(graph, context) {
+        assert.notOk(this.#destroyed, 'destroyed');
+        assert.defined(context.scene, 'context.scene');
+
+        this.#cells = -1;
+
+        const runtime = context.scene.virtual_geometry;
+
+        if (runtime === undefined || !runtime.frame_open) {
+            return;
+        }
+
+        const pair_capacity = context.budget * VGEO_BRICK_PAIRS_PER_CELL;
+
+        // this frame's slot for the cut, and its params: a τ of 1, since its records carry the error's own scale
+        const slot = runtime.slot_of(this.#cut);
+
+        this.#cut.write_params({ runtime, slot, tau: 1 });
+
+        const wait_capacity = context.budget * VGEO_BRICK_WAITS_PER_CELL;
+
+        this.#ensure_waiting(wait_capacity);
+
+        this.#settings.ring_capacity = context.ring_capacity;
+        this.#settings.resolution = context.resolution;
+        this.#settings.pair_capacity = pair_capacity;
+        this.#settings.wait_capacity = wait_capacity;
+        this.#context = context;
+
+        // ----- the wait: the cells the last frame left waiting, queued again once what they waited on is there -----
+
+        const waiting_in = graph_import_buffer(graph, this.#waiting[this.#waiting_read], "vgeo brick waiting");
+        const waiting_out = graph_import_buffer(graph, this.#waiting[1 - this.#waiting_read], "vgeo brick waiting next");
+
+        this.#waiting_read = 1 - this.#waiting_read;
+
+        const wait_command = graph_build_indirect_dispatch_command(graph, waiting_in, VGEO_BRICK_WAIT_WORKGROUP_SIZE, true);
+
+        // the frame's feedback, imported first: the first graph of a frame to import it records its clear there
+        const feedback = runtime.feedback_in(graph);
+
+        const wait_data = this.#wait_data;
+        const wait = graph.add("Brick Clipmap VGeo Wait", wait_data, this.#execute_wait);
+
+        wait_data.command = wait.read(wait_command);
+        wait_data.waiting_in = wait.read(waiting_in);
+        wait_data.waiting = wait.write(waiting_out);
+
+        // it wants the pages its cells wait on, in the cut's slot of the frame's feedback, ahead of the cut's own wants
+        wait_data.feedback = wait.write(feedback);
+        runtime.publish_feedback(graph, wait_data.feedback);
+
+        // it queues cells: what writes the queue after it comes after it
+        wait_data.state = wait.write(context.state);
+        context.state = wait_data.state;
+
+        // ----- gather: a pair record for each vgeo instance whose box reaches a taken cell -----
+
+        const data = this.#gather_data;
+        const gather = graph.add("Brick Clipmap VGeo Gather", data, this.#execute_gather);
+
+        data.take = gather.read(context.take);
+        data.instances = gather.create("vgeo brick pairs", BufferResourceDescriptor.from(
+            pair_capacity * VGEO_INSTANCE_WORDS * 4, GPUBufferUsage.STORAGE
+        ));
+        data.claim_widths = gather.create("vgeo brick claim widths", BufferResourceDescriptor.from(
+            16 + pair_capacity * 4, GPUBufferUsage.STORAGE, 0, 16
+        ));
+        data.cells = gather.create("vgeo brick cells", BufferResourceDescriptor.from(
+            context.budget * VGEO_BRICK_CELL_WORDS * 4, GPUBufferUsage.STORAGE
+        ));
+
+        // ----- the cut: the pairs' claim widths scanned into bases, then the camera cut's own descent -----
+
+        const prefix_sums = graph_prefix_scan_csdldf({
+            graph,
+            input: data.claim_widths,
+            output: graph_create_buffer(graph, "vgeo brick claim offsets", prefix_scan_csdldf_output_descriptor(pair_capacity)),
+            element_max_count: pair_capacity,
+        });
+
+        // the cells the cut puts a cluster on the list of, each once: what the distances follow
+        const filled = graph_create_buffer(graph, "vgeo brick filled", BufferResourceDescriptor.from(
+            16 + context.budget * 4, GPUBufferUsage.STORAGE, 0, 16
+        ));
+
+        const descent = graph_vgeo_cut_descent({
+            graph,
+            runtime,
+            cut: this.#cut,
+            instances: data.instances,
+            prefix_sums,
+            feedback: runtime.feedback_in(graph),
+            traverse: shader_vgeo_brick_traverse,
+            outputs: { vgeo_brick_cells: data.cells, vgeo_brick_filled: filled },
+        });
+
+        runtime.publish_feedback(graph, descent.feedback);
+
+        this.#cells = descent.outputs.vgeo_brick_cells;
+
+        // ----- the distances: a workgroup a filled cell, its list's triangles near it, its texels merged -----
+
+        const command = graph_build_indirect_dispatch_command(graph, descent.outputs.vgeo_brick_filled, 1, true);
+
+        const distance_data = this.#distance_data;
+        const distance = graph.add("Brick Clipmap VGeo Distance", distance_data, this.#execute_distance);
+
+        distance_data.command = distance.read(command);
+        distance_data.filled = distance.read(descent.outputs.vgeo_brick_filled);
+        distance_data.cells = distance.read(this.#cells);
+        distance_data.instances = distance.read(descent.instances);
+        distance_data.waiting = distance.write(wait_data.waiting);
+        distance_data.staging = distance.write(context.staging);
+
+        // the next provider and the store come after this one's merge
+        context.staging = distance_data.staging;
+    }
+
+    #execute_gather = (data, resources, execution) => {
+        const context = this.#context;
+        const scene = context.scene;
+        const take = resources.get(data.take);
+        const b = this.#gather_bindings;
+
+        b.settings = this.#settings;
+        b.brick_take = take;
+        b.brick_ring = context.ring;
+        b.brick_levels = context.levels;
+        b.vgeo_brick_statistics = this.#statistics;
+        b.tlas = scene.tlas.buffer;
+        b.scene_database = scene.scene_database_buffer;
+        b.geometries = scene.geometries.buffer_metadata;
+        b.vg_geometries = scene.virtual_geometry.pool.buffer_geometries;
+        b.instances = resources.get(data.instances);
+        b.claim_widths = resources.get(data.claim_widths);
+        b.vgeo_brick_cells = resources.get(data.cells);
+
+        shader_vgeo_brick_gather.dispatchIndirect({
+            encoder: execution.encoder,
+            command: take,
+            command_offset: 4 * BRICK_TAKE_CELL_DISPATCH,
+            bindings: b,
+        });
+    };
+
+    #execute_distance = (data, resources, execution) => {
+        const context = this.#context;
+        const scene = context.scene;
+        const meshlets = scene.geometries.meshlets;
+        const b = this.#distance_bindings;
+
+        b.settings = this.#settings;
+        b.brick_staging = resources.get(data.staging);
+        b.brick_levels = context.levels;
+        b.vgeo_brick_statistics = this.#statistics;
+        b.vgeo_brick_filled = resources.get(data.filled);
+        b.vgeo_brick_cells = resources.get(data.cells);
+        b.vgeo_brick_waiting = resources.get(data.waiting);
+        b.instances = resources.get(data.instances);
+        b.scene_database = scene.scene_database_buffer;
+        b.materials = scene.materials.metadata_table.buffer;
+        b.meshlet_metadata = meshlets.buffer_metadata;
+        b.meshlet_data = meshlets.buffer_data;
+
+        shader_vgeo_brick_distance.dispatchIndirect({
+            encoder: execution.encoder,
+            command: resources.get(data.command),
+            command_offset: 0,
+            bindings: b,
+        });
+    };
+
+    #execute_wait = (data, resources, execution) => {
+        const context = this.#context;
+        const pool = context.scene.virtual_geometry.pool;
+        const waiting = resources.get(data.waiting);
+        const b = this.#wait_bindings;
+
+        // this frame's list starts empty: the wait keeps its cells onto it, then the distances add theirs
+        execution.encoder.clearBuffer(waiting, 0, 16);
+
+        b.settings = this.#settings;
+        b.params = this.#cut.params_buffer;
+        b.vg_lookup = pool.buffer_lookup;
+        b.vg_arena = pool.buffer_arena;
+        b.feedback = resources.get(data.feedback);
+        b.vg_want_stamps = pool.buffer_want_stamps;
+        b.vgeo_brick_waiting_in = resources.get(data.waiting_in);
+        b.vgeo_brick_waiting = waiting;
+        b.brick_state = resources.get(data.state);
+        b.brick_ring = context.ring;
+        b.brick_pending = context.pending;
+
+        shader_vgeo_brick_wait.dispatchIndirect({
+            encoder: execution.encoder,
+            command: resources.get(data.command),
+            command_offset: 0,
+            bindings: b,
+        });
+    };
+
+    /**
+     * Waiting lists of `capacity` cells each, made again when the capacity changes. A list made again holds no cell:
+     * those that waited are built again only as anything else queues them.
+     * @param {number} capacity
+     */
+    #ensure_waiting(capacity) {
+        if (capacity === this.#waiting_capacity) {
+            return;
+        }
+
+        for (const list of this.#waiting) {
+            list.destroy();
+        }
+
+        this.#waiting = [0, 1].map(i => this.#device.createBuffer(BufferDescriptor.fromJSON({
+            label: `Probe clipmap / vgeo brick waiting ${i}`,
+            size: 16 + 4 * VGEO_BRICK_WAIT_WORDS * capacity,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC,
+        })));
+        this.#waiting_read = 0;
+        this.#waiting_capacity = capacity;
+    }
+
+    destroy() {
+        if (this.#destroyed) {
+            return;
+        }
+
+        this.#destroyed = true;
+        this.#statistics.destroy();
+        this.#cut.destroy();
+
+        for (const list of this.#waiting) {
+            list.destroy();
+        }
+
+        this.#waiting = [];
+    }
+}

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

@@ -0,0 +1,17 @@
+/**
+ * A pair record's box ({@link VGEO_BRICK_PAIR_BOX}) as `vgeo_brick_pair` writes it: the taken cell grown by the
+ * field's band, in the instance's object space (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §7.8).
+ *
+ * ```wgsl
+ * fn vgeo_brick_box_lower(pair_base: u32) -> vec3<f32>
+ * fn vgeo_brick_box_upper(pair_base: u32) -> vec3<f32>
+ * ```
+ *
+ * `pair_base` is the record's first word. Requires the importing shader to declare `instances`, the pair records,
+ * as `array<u32>`.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_vgeo_brick_box: CodeChunk;
+import { CodeChunk } from "../../../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_vgeo_brick_box.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_vgeo_brick_box.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/brick/vgeo/chunk_vgeo_brick_box.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;GAaG;AACH,mCAFU,SAAS,CAoBhB;0BAnCuB,0CAA0C"}

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

@@ -0,0 +1,36 @@
+import { CodeChunk } from "../../../../shader/compiler/CodeChunk.js";
+import { VGEO_BRICK_PAIR_BOX } from "./VGEO_BRICK.js";
+
+/**
+ * A pair record's box ({@link VGEO_BRICK_PAIR_BOX}) as `vgeo_brick_pair` writes it: the taken cell grown by the
+ * field's band, in the instance's object space (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §7.8).
+ *
+ * ```wgsl
+ * fn vgeo_brick_box_lower(pair_base: u32) -> vec3<f32>
+ * fn vgeo_brick_box_upper(pair_base: u32) -> vec3<f32>
+ * ```
+ *
+ * `pair_base` is the record's first word. Requires the importing shader to declare `instances`, the pair records,
+ * as `array<u32>`.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_vgeo_brick_box = CodeChunk.from(
+    //language=WGSL
+    `
+fn vgeo_brick_box_lower(pair_base: u32) -> vec3<f32> {
+    return vec3<f32>(
+        bitcast<f32>(instances[pair_base + ${VGEO_BRICK_PAIR_BOX}u]),
+        bitcast<f32>(instances[pair_base + ${VGEO_BRICK_PAIR_BOX + 1}u]),
+        bitcast<f32>(instances[pair_base + ${VGEO_BRICK_PAIR_BOX + 2}u])
+    );
+}
+
+fn vgeo_brick_box_upper(pair_base: u32) -> vec3<f32> {
+    return vec3<f32>(
+        bitcast<f32>(instances[pair_base + ${VGEO_BRICK_PAIR_BOX + 3}u]),
+        bitcast<f32>(instances[pair_base + ${VGEO_BRICK_PAIR_BOX + 4}u]),
+        bitcast<f32>(instances[pair_base + ${VGEO_BRICK_PAIR_BOX + 5}u])
+    );
+}
+`);