@woosh/meep-engine 3.57.0 → 3.58.0

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

@@ -0,0 +1,984 @@
+import { assert } from "../../../../../core/assert.js";
+import { ceilPowerOfTwo } from "../../../../../core/binary/operations/ceilPowerOfTwo.js";
+import { ClipmapCascadePlacement } from "../../../../../core/geom/clipmap/ClipmapCascadePlacement.js";
+import { window_scroll_regions } from "../../../../../core/geom/clipmap/window_scroll_regions.js";
+import { BufferDescriptor } from "../../../../descriptor/buffer/BufferDescriptor.js";
+import { graph_read_buffer } from "../../../buffer/graph_read_buffer.js";
+import { MESH_SDF_BRICK_TEXELS, MESH_SDF_BRICK_VOXELS } from "../../../geometry/sdf/MESH_SDF.js";
+import { MESH_SDF_SAMPLER } from "../../../geometry/sdf/MESH_SDF_RESOURCES.js";
+import { WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION } from "../../../gpu_primitive/indirect/WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION.js";
+import { shader_slot_stack_fill, SLOT_STACK_FILL_WORKGROUP_SIZE } from "../../../gpu_primitive/slot_stack/shader_slot_stack_fill.js";
+import {
+    shader_slot_stack_push_range,
+    SLOT_STACK_PUSH_RANGE_WORKGROUP_SIZE
+} from "../../../gpu_primitive/slot_stack/shader_slot_stack_push_range.js";
+import { CLIPMAP_LEVEL_ARRAY, CLIPMAP_LEVEL_STRUCT } from "../../../shader/chunk/clipmap/CLIPMAP_LEVEL_STRUCT.js";
+import { graph_import_buffer } from "../../../shader/graph/graph_import_buffer.js";
+import { SCENE_MOVER_CAPACITY } from "../../../scene/movers/SCENE_MOVER_LAYOUT.js";
+import { GPUTileAtlas3D } from "../../../texture/atlas/GPUTileAtlas3D.js";
+import { PROBE_CLIPMAP_CASCADE_COUNT_MAX, PROBE_CLIPMAP_CASCADE_RESOLUTIONS } from "../ProbeClipmapSettings.js";
+import {
+    BRICK_CLIPMAP_UNKNOWN,
+    BRICK_OBJECT_CELLS,
+    BRICK_OCCUPANCY_BLOCK,
+    BRICK_STAGING_WORDS,
+    BRICK_STATE_FREE,
+    BRICK_STATE_STARVED,
+    BRICK_STATE_WORDS,
+    BRICK_TAKE_CELL_DISPATCH,
+    BRICK_TAKE_WORD_DISPATCH,
+    BRICK_TAKE_WORDS,
+    BRICK_THREAD_WORKGROUP_SIZE
+} from "./BRICK_CLIPMAP.js";
+import { BRICK_MOVERS_PAIR_DISPATCH, BRICK_MOVERS_REQUEUE_DISPATCH, BRICK_MOVERS_WORDS } from "./BRICK_MOVERS.js";
+import { shader_brick_clipmap_clear } from "./shader_brick_clipmap_clear.js";
+import { shader_brick_clipmap_coarse } from "./shader_brick_clipmap_coarse.js";
+import { shader_brick_clipmap_free } from "./shader_brick_clipmap_free.js";
+import { shader_brick_clipmap_movers } from "./shader_brick_clipmap_movers.js";
+import { shader_brick_clipmap_movers_command } from "./shader_brick_clipmap_movers_command.js";
+import { shader_brick_clipmap_requeue } from "./shader_brick_clipmap_requeue.js";
+import { shader_brick_clipmap_scroll } from "./shader_brick_clipmap_scroll.js";
+import { shader_brick_clipmap_store } from "./shader_brick_clipmap_store.js";
+import { shader_brick_clipmap_take } from "./shader_brick_clipmap_take.js";
+
+/**
+ * @typedef {import("../ProbeClipmapSettings.js").ProbeClipmapSettings} ProbeClipmapSettings
+ * @typedef {import("../../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} FrameGraph
+ * @typedef {import("../../../scene/GPUSceneContext.js").GPUSceneContext} GPUSceneContext
+ */
+
+/**
+ * Corner steps of a brick cascade's window: one cell (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §7.1).
+ * @type {number}
+ */
+const BRICK_CASCADE_STEP = 1;
+
+/**
+ * Cells past half a step the anchor goes from a window's centre before it moves: the fluid's value
+ * (§7.1).
+ * @type {number}
+ */
+const BRICK_CASCADE_HYSTERESIS = 0.1;
+
+/**
+ * Parent cells every cascade's window keeps inside its parent's, so that a ray leaving a cascade is
+ * inside the next (§7.1).
+ * @type {number}
+ */
+const BRICK_CASCADE_NEST_MARGIN = 1;
+
+/**
+ * Atlas tiles along x and y; the atlas grows in layers of these.
+ * @type {number}
+ */
+const BRICK_ATLAS_SLOTS_XY = 16;
+
+/**
+ * Boxes a moved window exposes at most: one an axis.
+ * @type {number}
+ */
+const SCROLL_BOXES_PER_CASCADE = 3;
+
+/**
+ * What a provider gets to write the taken cells' staging (§7.6). The handles are the graph's latest
+ * versions: a provider that writes one replaces it here with the handle its pass hands back, so the
+ * next provider and the store come after it.
+ *
+ * @typedef {Object} BrickProviderContext
+ * @property {FrameGraph} graph
+ * @property {number} state `brick_state`'s handle: the ring's head and tail, and the free slots
+ * @property {number} take `brick_take`'s handle: the taken keys' first and count, and the cell dispatch
+ *   at {@link BRICK_TAKE_CELL_DISPATCH}, a workgroup a taken cell. Bind it read-only and dispatch
+ *   through it.
+ * @property {number} staging `brick_staging`'s handle, `BRICK_STAGING_WORDS` words a build slot
+ * @property {GPUBuffer} ring the keys; taken key `b` sits at `(taken_first + b) & (ring_capacity - 1)`
+ * @property {number} ring_capacity
+ * @property {number} resolution cells a cascade's window has a side
+ * @property {number} cascade_count
+ * @property {GPUBuffer} levels the cascades' windows, a {@link CLIPMAP_LEVEL_ARRAY}, finest first, a
+ *   cell one brick of 7 voxels
+ * @property {GPUSceneContext} scene the view's scene: its database, its TLAS over the mesh rows, and
+ *   its geometry caches
+ */
+
+/**
+ * @typedef {Object} BrickProvider
+ * @property {function(FrameGraph, BrickProviderContext): void} graph_write_bricks
+ */
+
+/**
+ * The world as the probe clipmap's rays see it (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §7):
+ * {@link cascade_count} cascades of {@link resolution}³ cells around an anchor, a cell one brick of
+ * 7 voxels a side, every cascade's voxel twice the one inside it, {@link voxel_size} at the finest.
+ *
+ * **Storage** (§7.3), the cascades stacked along z wherever they are cascade-indexed:
+ * - {@link brick_map}, `r32uint`, a texel a cell, in storage that wraps: a slot, EMPTY on a side of
+ *   the surface, or UNKNOWN for a cell not built since it entered its window;
+ * - {@link occupancy}, `r32uint`, a texel a {@link BRICK_OCCUPANCY_BLOCK}³-cell block of storage: how many
+ *   of its cells a ray must read;
+ * - {@link atlas}, `r8unorm` bricks of 8³ texels, the mesh caches' lattice and encoding, its slots
+ *   handed out by a free list on the device;
+ * - {@link objects}, 64 words a slot: the `meshes` row nearest in each 2³-texel cell of the brick.
+ *
+ * **A frame** ({@link graph_update}): the windows are placed around the anchor, coarsest first,
+ * each child a parent cell inside its parent (`ClipmapCascadePlacement`), and what a move exposed is
+ * queued (scroll). Then the frame takes up to its budget of queued cells, clears their staging, has
+ * each provider merge its distances and objects into it, frees what needs no brick, stores what does,
+ * and counts the occupancy of the blocks it built. Every pass after scroll is sized by take's count
+ * on the device, and scroll by the cells the moves exposed: nothing by the clipmap's size.
+ *
+ * **Capacity** (§7.10) starts at `2·N²·C` slots, a ground plane two cells thick through every
+ * cascade. A take the free slots held back is counted on the device and read back, and the next
+ * frame doubles the capacity: the atlas reserves more layers, and the objects and the free list grow
+ * with a copy, the new slots pushed. Nothing shrinks.
+ */
+export class GPUBrickClipmap {
+    /**
+     * @type {number}
+     * @readonly
+     */
+    cascade_count;
+
+    /**
+     * Cells per axis of a cascade.
+     * @type {number}
+     * @readonly
+     */
+    resolution;
+
+    /**
+     * The finest cascade's voxel, metres.
+     * @type {number}
+     * @readonly
+     */
+    voxel_size;
+
+    /** @type {GPUDevice} */
+    #device;
+
+    /** @type {ClipmapCascadePlacement} */
+    #placement;
+
+    /** @type {GPUTexture} */
+    #brick_map;
+
+    /** @type {GPUTexture} */
+    #occupancy;
+
+    /** What the passes bind, made once. @type {GPUTextureView} */
+    #brick_map_view;
+
+    /** @type {GPUTextureView} */
+    #occupancy_view;
+
+    /** @type {GPUTileAtlas3D} */
+    #atlas;
+
+    /** @type {GPUBuffer} */
+    #objects;
+
+    /** @type {GPUBuffer} */
+    #free;
+
+    /** @type {GPUBuffer} */
+    #state;
+
+    /** What take writes for the frame's passes to dispatch through. @type {GPUBuffer} */
+    #take;
+
+    /** What the movers' command writes for the movers and the re-queue to dispatch through. @type {GPUBuffer} */
+    #movers;
+
+    /** The rows invalidated for the frame, as the movers read them. @type {GPUBuffer} */
+    #invalidated;
+
+    /** A mover list with nothing on it, for a frame given none. @type {GPUBuffer} */
+    #no_movers;
+
+    /** The rows invalidated since the last frame, and how many. */
+    #invalidated_rows = new Uint32Array(64);
+    #invalidated_count = 0;
+
+    /** The frame's: its rows' count, as recorded. */
+    #frame_invalidated = 0;
+
+    /** @type {GPUBuffer} */
+    #ring;
+
+    /** @type {GPUBuffer} */
+    #pending;
+
+    /** @type {GPUBuffer|null} */
+    #staging = null;
+
+    /** Build slots the staging holds. */
+    #staging_cells = 0;
+
+    /** @type {GPUBuffer} */
+    #runs;
+
+    /** @type {GPUBuffer} */
+    #levels;
+
+    /** Slots of the atlas and the object cells. */
+    #capacity = 0;
+
+    #ring_capacity = 0;
+
+    /** Whether the brick map still holds what a new texture does, which no scroll may read as a slot. */
+    #fresh = true;
+
+    #fill_pending = true;
+
+    /** Ranges of slots the next frame pushes onto the free list: first, count. @type {number[]} */
+    #pushes = [];
+
+    /** The starved count last read back, and whether one that moved waits to be acted on. */
+    #starved = 0;
+    #grow_pending = false;
+
+    #destroyed = false;
+
+    /** The frame's scroll boxes: the smallest cell and the cascade, then the size and the first thread. */
+    #runs_data;
+    #run_count = 0;
+    #cell_count = 0;
+
+    #old_corner = new Int32Array(3);
+    #new_corner = new Int32Array(3);
+    #size = new Int32Array(3);
+    #boxes = new Int32Array(6 * SCROLL_BOXES_PER_CASCADE);
+
+    #levels_data = new ArrayBuffer(CLIPMAP_LEVEL_ARRAY.size);
+    #levels_i32 = new Int32Array(this.#levels_data);
+    #levels_f32 = new Float32Array(this.#levels_data);
+
+    #scroll_settings = { run_count: 0, cell_count: 0, groups_x: 0, ring_capacity: 0, resolution: 0, fresh: 0 };
+    #take_settings = { budget: 0 };
+    #free_settings = { ring_capacity: 0, resolution: 0 };
+    #store_settings = { ring_capacity: 0, resolution: 0, capacity: 0 };
+    #coarse_settings = { ring_capacity: 0, resolution: 0 };
+    #push_settings = { first: 0, count: 0, counter: BRICK_STATE_FREE };
+
+    #bindings = {};
+
+    #take_data = { state: -1, take: -1, staging: -1, movers: -1 };
+
+    #movers_command_settings = { mover_capacity: SCENE_MOVER_CAPACITY, row_count: 0, block_count: 0, key_count: 0 };
+    #movers_settings = { block_count: 0, resolution: 0, ring_capacity: 0 };
+    #requeue_settings = { key_count: 0, ring_capacity: 0 };
+
+    /** @type {GPUSceneContext|null} */
+    #frame_scene = null;
+    #store_data = { state: -1, take: -1, staging: -1 };
+
+    /** @type {BrickProviderContext} */
+    #context = {
+        graph: null,
+        state: -1,
+        take: -1,
+        staging: -1,
+        ring: null,
+        ring_capacity: 0,
+        resolution: 0,
+        cascade_count: 0,
+        levels: null,
+        scene: null,
+    };
+
+    /**
+     * @param {GPUDevice} device
+     * @param {object} options
+     * @param {number} options.cascade_count
+     * @param {number} options.resolution one of {@link PROBE_CLIPMAP_CASCADE_RESOLUTIONS}
+     * @param {number} options.voxel_size metres
+     */
+    constructor(device, { cascade_count, resolution, voxel_size }) {
+        assert.isPositiveInteger(cascade_count, 'cascade_count');
+        assert.lessThanOrEqual(cascade_count, PROBE_CLIPMAP_CASCADE_COUNT_MAX, 'cascade_count');
+        assert.isOneOf(resolution, PROBE_CLIPMAP_CASCADE_RESOLUTIONS, 'resolution');
+        assert.isFinite(voxel_size, 'voxel_size');
+        assert.greaterThan(voxel_size, 0, 'voxel_size');
+
+        this.cascade_count = cascade_count;
+        this.resolution = resolution;
+        this.voxel_size = voxel_size;
+
+        this.#device = device;
+
+        this.#placement = new ClipmapCascadePlacement({
+            cascade_count,
+            resolution: [resolution, resolution, resolution],
+            cell_size: MESH_SDF_BRICK_VOXELS * voxel_size,
+            step: BRICK_CASCADE_STEP,
+            hysteresis: BRICK_CASCADE_HYSTERESIS,
+            nest_margin: BRICK_CASCADE_NEST_MARGIN,
+        });
+
+        this.#brick_map = device.createTexture({
+            label: 'Probe clipmap / brick map',
+            size: [resolution, resolution, resolution * cascade_count],
+            dimension: '3d',
+            format: 'r32uint',
+            usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.STORAGE_BINDING,
+        });
+
+        const blocks = resolution / BRICK_OCCUPANCY_BLOCK;
+
+        this.#occupancy = device.createTexture({
+            label: 'Probe clipmap / brick occupancy',
+            size: [blocks, blocks, blocks * cascade_count],
+            dimension: '3d',
+            format: 'r32uint',
+            usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.STORAGE_BINDING,
+        });
+
+        this.#brick_map_view = this.#brick_map.createView();
+        this.#occupancy_view = this.#occupancy.createView();
+
+        const capacity = this.#capacity = 2 * resolution * resolution * cascade_count;
+
+        this.#atlas = new GPUTileAtlas3D({
+            device,
+            formats: ["r8unorm"],
+            content_size: [MESH_SDF_BRICK_TEXELS, MESH_SDF_BRICK_TEXELS, MESH_SDF_BRICK_TEXELS],
+            border: 0,
+            slots_x: BRICK_ATLAS_SLOTS_XY,
+            slots_y: BRICK_ATLAS_SLOTS_XY,
+            capacity,
+            // sampled by the rays, stored into by the build's store pass
+            usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.STORAGE_BINDING,
+            label: 'Probe clipmap / brick atlas',
+        });
+
+        this.#atlas.reserve(capacity);
+
+        this.#objects = this.#create_buffer('brick objects', 4 * BRICK_OBJECT_CELLS * capacity, GPUBufferUsage.COPY_SRC);
+        this.#free = this.#create_buffer('brick free list', 4 * capacity, GPUBufferUsage.COPY_SRC);
+
+        const keys = resolution ** 3 * cascade_count;
+
+        this.#ring_capacity = ceilPowerOfTwo(keys);
+        this.#ring = this.#create_buffer('brick ring', 4 * this.#ring_capacity, 0);
+        // cleared by the first frame, before the first scroll queues anything
+        this.#pending = this.#create_buffer('brick pending', 4 * Math.ceil(keys / 32), GPUBufferUsage.COPY_DST);
+
+        this.#state = this.#create_buffer('brick state', 4 * BRICK_STATE_WORDS, GPUBufferUsage.COPY_SRC | GPUBufferUsage.COPY_DST);
+        this.#take = this.#create_buffer('brick take', 4 * BRICK_TAKE_WORDS, GPUBufferUsage.INDIRECT);
+        this.#movers = this.#create_buffer('brick movers', 4 * BRICK_MOVERS_WORDS, GPUBufferUsage.INDIRECT);
+        this.#invalidated = this.#create_buffer('brick invalidated rows', 4 * this.#invalidated_rows.length, GPUBufferUsage.COPY_DST);
+        // the count, then two boxes' worth of room, all zero
+        this.#no_movers = this.#create_buffer('brick no movers', 48, 0);
+
+        // every slot free; nothing queued
+        const state = new Uint32Array(BRICK_STATE_WORDS);
+
+        state[BRICK_STATE_FREE] = capacity;
+
+        device.queue.writeBuffer(this.#state, 0, state);
+
+        this.#runs_data = new Int32Array(8 * SCROLL_BOXES_PER_CASCADE * cascade_count);
+        this.#runs = this.#create_buffer('brick scroll runs', this.#runs_data.byteLength, GPUBufferUsage.COPY_DST);
+
+        this.#levels = device.createBuffer(BufferDescriptor.fromJSON({
+            label: 'Probe clipmap / brick levels',
+            size: CLIPMAP_LEVEL_ARRAY.size,
+            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+        }));
+    }
+
+    /**
+     * @returns {GPUTexture}
+     */
+    get brick_map() {
+        return this.#brick_map;
+    }
+
+    /**
+     * @returns {GPUTexture}
+     */
+    get occupancy() {
+        return this.#occupancy;
+    }
+
+    /**
+     * @returns {GPUTileAtlas3D}
+     */
+    get atlas() {
+        return this.#atlas;
+    }
+
+    /**
+     * @returns {GPUBuffer}
+     */
+    get objects() {
+        return this.#objects;
+    }
+
+    /**
+     * The cascades' windows, a {@link CLIPMAP_LEVEL_ARRAY} as a uniform, finest first: as placed by the
+     * last {@link graph_update}.
+     * @returns {GPUBuffer}
+     */
+    get levels() {
+        return this.#levels;
+    }
+
+    /**
+     * Put what the tracer's chunks read (`chunk_brick_clipmap_trace.js`) into a reader's bindings,
+     * under the names they take: the levels, the map, the occupancy, the atlas, its sampler and the
+     * object cells. The atlas and the objects are replaced when the capacity grows: take them each
+     * frame.
+     *
+     * @param {Object} bindings
+     * @returns {Object} bindings
+     */
+    write_bindings(bindings) {
+        bindings.brick_levels = this.#levels;
+        bindings.brick_map = this.#brick_map_view;
+        bindings.brick_occupancy = this.#occupancy_view;
+        bindings.brick_atlas = this.#atlas.texture.obtainView();
+        bindings.brick_sampler = MESH_SDF_SAMPLER;
+        bindings.brick_objects = this.#objects;
+
+        return bindings;
+    }
+
+    /**
+     * Slots of the atlas and the object cells.
+     * @returns {number}
+     */
+    get capacity() {
+        return this.#capacity;
+    }
+
+    /**
+     * @param {number} cascade
+     * @param {number} axis
+     * @returns {number} the cascade's window's smallest cell on the axis, in its cells
+     */
+    corner(cascade, axis) {
+        return this.#placement.corner(cascade, axis);
+    }
+
+    /**
+     * @param {number} cascade
+     * @returns {number} a cascade's cell, metres: seven of its voxels
+     */
+    cell_size(cascade) {
+        return this.#placement.cell_size(cascade);
+    }
+
+    /**
+     * Have the next frame build again the cells these rows' world boxes reach, as the `meshes` table
+     * has the boxes then: a row whose geometry's field turned resident, or one that joined or left the
+     * SDF world (§6.4, §7.4). A row given twice costs a box twice and queues its cells once.
+     *
+     * @param {ArrayLike<number>} rows `meshes` rows
+     */
+    invalidate_rows(rows) {
+        const count = this.#invalidated_count + rows.length;
+
+        if (count > this.#invalidated_rows.length) {
+            const grown = new Uint32Array(ceilPowerOfTwo(count));
+
+            grown.set(this.#invalidated_rows.subarray(0, this.#invalidated_count));
+            this.#invalidated_rows = grown;
+        }
+
+        for (let i = 0; i < rows.length; i++) {
+            this.#invalidated_rows[this.#invalidated_count + i] = rows[i];
+        }
+
+        this.#invalidated_count = count;
+    }
+
+    /**
+     * @param {ProbeClipmapSettings} settings
+     * @returns {boolean} whether this is what the settings' brick cascades describe
+     */
+    built_for(settings) {
+        return settings.brick_cascade_count === this.cascade_count
+            && settings.brick_cascade_resolution === this.resolution
+            && settings.brick_voxel_size === this.voxel_size;
+    }
+
+    /**
+     * Record the frame's build: place the windows around the anchor and queue what they exposed, then
+     * take up to `budget` queued cells, stage them through `providers` in order, and store what they
+     * need. Allocates nothing per frame once the staging holds the budget.
+     *
+     * @param {Object} options
+     * @param {FrameGraph} options.graph
+     * @param {number} options.x the anchor, world metres
+     * @param {number} options.y
+     * @param {number} options.z
+     * @param {number} options.budget cells built a frame at most, `brick_build_budget`
+     * @param {ArrayLike<BrickProvider>} options.providers merged into the staging in this order
+     * @param {GPUSceneContext|null} options.scene what the providers read: the view's scene
+     * @param {number} [options.movers] the graph handle of the scene's mover list for the frame,
+     *   `GPUSceneContext.graph_movers`; none queues nothing but the invalidated rows
+     * @returns {number} the graph handle of the build's last write, which a pass reading the bricks reads
+     *   to come after it
+     */
+    graph_update({ graph, x, y, z, budget, providers, scene, movers = -1 }) {
+        assert.defined(graph, 'graph');
+        assert.isPositiveInteger(budget, 'budget');
+        assert.notOk(this.#destroyed, 'destroyed');
+
+        if (this.#grow_pending) {
+            this.#grow_pending = false;
+            this.#grow();
+        }
+
+        this.#place(x, y, z);
+        this.#ensure_staging(budget);
+
+        this.#take_settings.budget = budget;
+
+        const device = this.#device;
+
+        if (this.#run_count > 0) {
+            device.queue.writeBuffer(this.#runs, 0, this.#runs_data, 0, 8 * this.#run_count);
+        }
+
+        device.queue.writeBuffer(this.#levels, 0, this.#levels_data);
+
+        // the rows the movers read this frame; what comes after is the next frame's
+        const rows = this.#invalidated_count;
+
+        if (rows > 0) {
+            if (this.#invalidated.size < 4 * rows) {
+                this.#invalidated.destroy();
+                this.#invalidated = this.#create_buffer('brick invalidated rows', 4 * this.#invalidated_rows.length, GPUBufferUsage.COPY_DST);
+            }
+
+            device.queue.writeBuffer(this.#invalidated, 0, this.#invalidated_rows, 0, rows);
+        }
+
+        this.#frame_invalidated = rows;
+        this.#invalidated_count = 0;
+        this.#frame_scene = scene;
+
+        const take_data = this.#take_data;
+        const take = graph.add("Brick Clipmap Take", take_data, this.#execute_take);
+
+        take_data.state = take.write(graph_import_buffer(graph, this.#state, "brick_state"));
+        take_data.take = take.write(graph_import_buffer(graph, this.#take, "brick_take"));
+        take_data.movers = movers >= 0 ? take.read(movers) : -1;
+        take_data.staging = take.write(graph_import_buffer(graph, this.#staging, "brick_staging"));
+
+        take.make_side_effect();
+
+        const context = this.#context;
+
+        context.graph = graph;
+        context.state = take_data.state;
+        context.take = take_data.take;
+        context.staging = take_data.staging;
+        context.ring = this.#ring;
+        context.ring_capacity = this.#ring_capacity;
+        context.resolution = this.resolution;
+        context.cascade_count = this.cascade_count;
+        context.levels = this.#levels;
+        context.scene = scene;
+
+        for (let i = 0; i < providers.length; i++) {
+            providers[i].graph_write_bricks(graph, context);
+        }
+
+        const store_data = this.#store_data;
+        const store = graph.add("Brick Clipmap Store", store_data, this.#execute_store);
+
+        store_data.state = store.write(context.state);
+        store_data.take = store.read(context.take);
+        store_data.staging = store.read(context.staging);
+
+        store.make_side_effect();
+
+        // a starved take grows the capacity, from a later frame
+        graph_read_buffer({ graph, buffer: store_data.state, offset: 4 * BRICK_STATE_STARVED, size: 4 })
+            .then(reference => {
+                try {
+                    const starved = new Uint32Array(reference.getValue())[0];
+
+                    if (!this.#destroyed && starved !== this.#starved) {
+                        this.#starved = starved;
+                        this.#grow_pending = true;
+                    }
+                } finally {
+                    reference.release();
+                }
+            });
+
+        this.#fresh = false;
+
+        return store_data.state;
+    }
+
+    /**
+     * Place every window, coarsest first, and list the cells the moves exposed: every cell of every
+     * window on the first frame.
+     */
+    #place(x, y, z) {
+        const placement = this.#placement;
+        const n = this.resolution;
+        const size = this.#size;
+        const boxes = this.#boxes;
+        const runs = this.#runs_data;
+
+        size.fill(n);
+
+        placement.begin();
+
+        for (let c = this.cascade_count - 1; c >= 0; c--) {
+            placement.place(c, x, y, z);
+        }
+
+        let run_count = 0;
+        let cells = 0;
+
+        for (let c = 0; c < this.cascade_count; c++) {
+            let box_count = 0;
+
+            for (let axis = 0; axis < 3; axis++) {
+                this.#old_corner[axis] = placement.previous_corner(c, axis);
+                this.#new_corner[axis] = placement.corner(c, axis);
+            }
+
+            if (this.#fresh) {
+                for (let axis = 0; axis < 3; axis++) {
+                    boxes[axis] = this.#new_corner[axis];
+                    boxes[3 + axis] = this.#new_corner[axis] + n;
+                }
+
+                box_count = 1;
+            } else if (placement.moved(c)) {
+                box_count = window_scroll_regions(this.#old_corner, this.#new_corner, size, 3, boxes);
+            }
+
+            for (let b = 0; b < box_count; b++) {
+                const at = 8 * run_count;
+
+                for (let axis = 0; axis < 3; axis++) {
+                    runs[at + axis] = boxes[6 * b + axis];
+                    runs[at + 4 + axis] = boxes[6 * b + 3 + axis] - boxes[6 * b + axis];
+                }
+
+                runs[at + 3] = c;
+                runs[at + 7] = cells;
+
+                cells += runs[at + 4] * runs[at + 5] * runs[at + 6];
+                run_count++;
+            }
+
+            // the cascade's window as readers take it: corner, cell size, size
+            const level = (c * CLIPMAP_LEVEL_STRUCT.aligned_size) >>> 2;
+
+            for (let axis = 0; axis < 3; axis++) {
+                this.#levels_i32[level + axis] = this.#new_corner[axis];
+                this.#levels_i32[level + 4 + axis] = n;
+            }
+
+            this.#levels_f32[level + 3] = placement.cell_size(c);
+        }
+
+        this.#run_count = run_count;
+        this.#cell_count = cells;
+    }
+
+    /**
+     * A staging of at least `budget` build slots.
+     */
+    #ensure_staging(budget) {
+        if (this.#staging !== null && this.#staging_cells >= budget) {
+            return;
+        }
+
+        this.#staging?.destroy();
+        this.#staging_cells = budget;
+        this.#staging = this.#create_buffer('brick staging', 4 * BRICK_STAGING_WORDS * budget, 0);
+    }
+
+    /**
+     * Double the capacity: the atlas reserves the slots, the objects and the free list grow with a
+     * copy, and the new slots are pushed by the next frame.
+     */
+    #grow() {
+        const old_capacity = this.#capacity;
+        const capacity = Math.min(2 * old_capacity, this.#atlas.capacity_limit);
+
+        if (capacity <= old_capacity) {
+            return;
+        }
+
+        this.#atlas.reserve(capacity);
+
+        this.#objects = this.#regrow(this.#objects, 'brick objects', 4 * BRICK_OBJECT_CELLS * capacity);
+        this.#free = this.#regrow(this.#free, 'brick free list', 4 * capacity);
+        this.#capacity = capacity;
+        this.#pushes.push(old_capacity, capacity - old_capacity);
+    }
+
+    #execute_take = (data, resources, context) => {
+        const encoder = context.encoder;
+
+        // a fresh clipmap's scroll queues every cell: movers would only find them queued
+        const fresh = this.#fill_fresh_scroll;
+        const state = resources.get(data.state);
+        const b = this.#bindings;
+
+        if (this.#fill_pending) {
+            this.#fill_pending = false;
+
+            shader_slot_stack_fill.dispatch({
+                encoder,
+                group_count_x: Math.min(Math.ceil(this.#capacity / SLOT_STACK_FILL_WORKGROUP_SIZE), WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION),
+                bindings: { capacity: this.#capacity, slots: this.#free },
+            });
+
+            // nothing pending
+            encoder.clearBuffer(this.#pending);
+        }
+
+        const pushes = this.#pushes;
+
+        for (let i = 0; i < pushes.length; i += 2) {
+            const settings = this.#push_settings;
+
+            settings.first = pushes[i];
+            settings.count = pushes[i + 1];
+
+            shader_slot_stack_push_range.dispatch({
+                encoder,
+                group_count_x: Math.min(Math.ceil(settings.count / SLOT_STACK_PUSH_RANGE_WORKGROUP_SIZE), WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION),
+                bindings: { settings, counts: state, slots: this.#free },
+            });
+        }
+
+        pushes.length = 0;
+
+        const take_buffer = resources.get(data.take);
+
+        b.brick_state = state;
+        b.brick_take = take_buffer;
+        b.brick_ring = this.#ring;
+        b.brick_pending = this.#pending;
+        b.brick_free = this.#free;
+        b.brick_staging = resources.get(data.staging);
+        b.brick_objects = this.#objects;
+        b.brick_map = this.#brick_map_view;
+        b.brick_occupancy = this.#occupancy_view;
+        b.brick_atlas_store = this.#atlas.texture;
+        b.brick_scroll_runs = this.#runs;
+
+        if (this.#cell_count > 0) {
+            const groups = Math.ceil(this.#cell_count / BRICK_THREAD_WORKGROUP_SIZE);
+            const groups_x = Math.min(groups, WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION);
+            const settings = this.#scroll_settings;
+
+            settings.run_count = this.#run_count;
+            settings.cell_count = this.#cell_count;
+            settings.groups_x = groups_x;
+            settings.ring_capacity = this.#ring_capacity;
+            settings.resolution = this.resolution;
+            settings.fresh = this.#fill_fresh_scroll ? 1 : 0;
+
+            b.settings = settings;
+
+            shader_brick_clipmap_scroll.dispatch({
+                encoder,
+                group_count_x: groups_x,
+                group_count_y: Math.ceil(groups / groups_x),
+                bindings: b,
+            });
+
+            this.#fill_fresh_scroll = false;
+        }
+
+        if (!fresh) {
+            this.#record_movers(encoder, data.movers >= 0 ? resources.get(data.movers) : this.#no_movers);
+        }
+
+        b.settings = this.#take_settings;
+
+        shader_brick_clipmap_take.dispatch({ encoder, bindings: b });
+
+        shader_brick_clipmap_clear.dispatchIndirect({
+            encoder,
+            bindings: b,
+            command: take_buffer,
+            command_offset: 4 * BRICK_TAKE_WORD_DISPATCH,
+        });
+    };
+
+    /** Whether the next scroll still reads the brick map as a new texture holds it. */
+    #fill_fresh_scroll = true;
+
+    /**
+     * The movers' three passes, after the scroll and before the take: the command, then the pairs or
+     * the full re-queue, as the command found the boxes.
+     *
+     * @param {GPUCommandEncoder} encoder
+     * @param {GPUBuffer} scene_movers
+     */
+    #record_movers(encoder, scene_movers) {
+        const b = this.#bindings;
+        const blocks = (this.resolution / BRICK_OCCUPANCY_BLOCK) ** 3 * this.cascade_count;
+        const keys = this.resolution ** 3 * this.cascade_count;
+
+        b.scene_movers = scene_movers;
+        b.brick_movers = this.#movers;
+        b.brick_invalidated = this.#invalidated;
+        b.brick_levels = this.#levels;
+        b.scene_database = this.#frame_scene?.scene_database_buffer ?? this.#no_movers;
+
+        const command = this.#movers_command_settings;
+
+        command.row_count = this.#frame_invalidated;
+        command.block_count = blocks;
+        command.key_count = keys;
+        b.settings = command;
+
+        shader_brick_clipmap_movers_command.dispatch({ encoder, bindings: b });
+
+        const pairs = this.#movers_settings;
+
+        pairs.block_count = blocks;
+        pairs.resolution = this.resolution;
+        pairs.ring_capacity = this.#ring_capacity;
+        b.settings = pairs;
+
+        shader_brick_clipmap_movers.dispatchIndirect({
+            encoder,
+            bindings: b,
+            command: this.#movers,
+            command_offset: 4 * BRICK_MOVERS_PAIR_DISPATCH,
+        });
+
+        const requeue = this.#requeue_settings;
+
+        requeue.key_count = keys;
+        requeue.ring_capacity = this.#ring_capacity;
+        b.settings = requeue;
+
+        shader_brick_clipmap_requeue.dispatchIndirect({
+            encoder,
+            bindings: b,
+            command: this.#movers,
+            command_offset: 4 * BRICK_MOVERS_REQUEUE_DISPATCH,
+        });
+    }
+
+    #execute_store = (data, resources, context) => {
+        const encoder = context.encoder;
+        const state = resources.get(data.state);
+        const b = this.#bindings;
+
+        const take_buffer = resources.get(data.take);
+
+        b.brick_state = state;
+        b.brick_take = take_buffer;
+        b.brick_ring = this.#ring;
+        b.brick_pending = this.#pending;
+        b.brick_free = this.#free;
+        b.brick_staging = resources.get(data.staging);
+        b.brick_objects = this.#objects;
+        b.brick_map = this.#brick_map_view;
+        b.brick_occupancy = this.#occupancy_view;
+        b.brick_atlas_store = this.#atlas.texture;
+
+        const free = this.#free_settings;
+
+        free.ring_capacity = this.#ring_capacity;
+        free.resolution = this.resolution;
+        b.settings = free;
+
+        shader_brick_clipmap_free.dispatchIndirect({
+            encoder,
+            bindings: b,
+            command: take_buffer,
+            command_offset: 4 * BRICK_TAKE_CELL_DISPATCH,
+        });
+
+        const store = this.#store_settings;
+
+        store.ring_capacity = this.#ring_capacity;
+        store.resolution = this.resolution;
+        store.capacity = this.#capacity;
+        b.settings = store;
+
+        shader_brick_clipmap_store.dispatchIndirect({
+            encoder,
+            bindings: b,
+            command: take_buffer,
+            command_offset: 4 * BRICK_TAKE_CELL_DISPATCH,
+        });
+
+        const coarse = this.#coarse_settings;
+
+        coarse.ring_capacity = this.#ring_capacity;
+        coarse.resolution = this.resolution;
+        b.settings = coarse;
+
+        shader_brick_clipmap_coarse.dispatchIndirect({
+            encoder,
+            bindings: b,
+            command: take_buffer,
+            command_offset: 4 * BRICK_TAKE_CELL_DISPATCH,
+        });
+    };
+
+    /**
+     * @param {string} name
+     * @param {number} size
+     * @param {GPUBufferUsageFlags} usage beside STORAGE
+     * @returns {GPUBuffer}
+     */
+    #create_buffer(name, size, usage) {
+        return this.#device.createBuffer(BufferDescriptor.fromJSON({
+            label: `Probe clipmap / ${name}`,
+            size,
+            usage: GPUBufferUsage.STORAGE | usage,
+        }));
+    }
+
+    /**
+     * A larger buffer with the old one's bytes, copied ahead of the frame's commands; the old one is
+     * destroyed after the copy is submitted.
+     *
+     * @param {GPUBuffer} old
+     * @param {string} name
+     * @param {number} size
+     * @returns {GPUBuffer}
+     */
+    #regrow(old, name, size) {
+        const device = this.#device;
+        const buffer = this.#create_buffer(name, size, GPUBufferUsage.COPY_SRC | GPUBufferUsage.COPY_DST);
+
+        const encoder = device.createCommandEncoder({ label: `Probe clipmap / ${name} growth` });
+
+        encoder.copyBufferToBuffer(old, 0, buffer, 0, old.size);
+        device.queue.submit([encoder.finish()]);
+
+        old.destroy();
+
+        return buffer;
+    }
+
+    destroy() {
+        if (this.#destroyed) {
+            return;
+        }
+
+        this.#destroyed = true;
+
+        this.#brick_map.destroy();
+        this.#occupancy.destroy();
+        this.#atlas.destroy();
+
+        for (const buffer of [this.#objects, this.#free, this.#ring, this.#pending, this.#state, this.#take, this.#movers, this.#invalidated, this.#no_movers, this.#staging, this.#runs, this.#levels]) {
+            buffer?.destroy();
+        }
+    }
+}