@woosh/meep-engine 3.56.0 → 3.58.0

package/src/shade/renderer/global_illumination/probe_clipmap/probe/GPUProbeClipmap.js

@@ -0,0 +1,982 @@
+import { assert } from "../../../../../core/assert.js";
+import { ClipmapCascadePlacement } from "../../../../../core/geom/clipmap/ClipmapCascadePlacement.js";
+import { BufferDescriptor } from "../../../../descriptor/buffer/BufferDescriptor.js";
+import { graph_read_buffer } from "../../../buffer/graph_read_buffer.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 { GPUTileAtlas2D } from "../../../texture/atlas/GPUTileAtlas2D.js";
+import {
+    PROBE_CLIPMAP_CASCADE_COUNT_MAX,
+    PROBE_CLIPMAP_CASCADE_RESOLUTIONS,
+    PROBE_CLIPMAP_OCTAHEDRAL_RESOLUTION_MAX,
+    PROBE_CLIPMAP_OCTAHEDRAL_RESOLUTION_MIN
+} from "../ProbeClipmapSettings.js";
+import { PROBE_PROJECTION_ROW_STRUCT, PROBE_RAY_STRUCT, PROBE_RECORD_STRUCT } from "./chunk_probe_clipmap.js";
+import {
+    PROBE_COUNTER_FREE,
+    PROBE_COUNTER_STARVED,
+    PROBE_COUNTER_WORDS,
+    PROBE_DISPATCH_ACTIVE,
+    PROBE_DISPATCH_ADMIT,
+    PROBE_DISPATCH_PUBLISH,
+    PROBE_DISPATCH_RAYS,
+    PROBE_DISPATCH_ROWS,
+    PROBE_DISPATCH_TEXELS,
+    PROBE_DISPATCH_TRACED,
+    PROBE_DISPATCH_WORDS,
+    PROBE_WANT_TILE,
+    PROBE_WANT_WORKGROUP_TILES,
+    probe_clipmap_maps_words
+} from "./PROBE_CLIPMAP.js";
+import { shader_probe_clipmap_accumulate } from "./shader_probe_clipmap_accumulate.js";
+import { shader_probe_clipmap_admit, shader_probe_clipmap_admit_command } from "./shader_probe_clipmap_admit.js";
+import { shader_probe_clipmap_due } from "./shader_probe_clipmap_due.js";
+import { shader_probe_clipmap_fill } from "./shader_probe_clipmap_fill.js";
+import { shader_probe_clipmap_project, shader_probe_clipmap_project_rows } from "./shader_probe_clipmap_project.js";
+import { shader_probe_clipmap_publish } from "./shader_probe_clipmap_publish.js";
+import { shader_probe_clipmap_relocate } from "./shader_probe_clipmap_relocate.js";
+import { shader_probe_clipmap_retire } from "./shader_probe_clipmap_retire.js";
+import { shader_probe_clipmap_schedule } from "./shader_probe_clipmap_schedule.js";
+import { shader_probe_clipmap_shade } from "./shader_probe_clipmap_shade.js";
+import { shader_probe_clipmap_trace } from "./shader_probe_clipmap_trace.js";
+import { shader_probe_clipmap_trace_command } from "./shader_probe_clipmap_trace_command.js";
+import { shader_probe_clipmap_want } from "./shader_probe_clipmap_want.js";
+
+/**
+ * @typedef {import("../ProbeClipmapSettings.js").ProbeClipmapSettings} ProbeClipmapSettings
+ * @typedef {import("../../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} FrameGraph
+ */
+
+/**
+ * Corner steps of a probe cascade's window: one lattice cell, as the bricks' (§8.1).
+ * @type {number}
+ */
+const PROBE_CASCADE_STEP = 1;
+
+/**
+ * Cells past half a step the anchor goes from a window's centre before it moves: the bricks' value.
+ * @type {number}
+ */
+const PROBE_CASCADE_HYSTERESIS = 0.1;
+
+/**
+ * Parent cells every cascade's window keeps inside its parent's, so that a cage in a cascade's blend
+ * skirt is inside the next cascade's cage window.
+ * @type {number}
+ */
+const PROBE_CASCADE_NEST_MARGIN = 1;
+
+/**
+ * Bytes before a list's first element: its count, padded to the elements' 16-byte alignment.
+ * @type {number}
+ */
+const LIST_HEADER_BYTES = 16;
+
+/**
+ * What shading samples (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8): {@link cascade_count} cascades of
+ * {@link resolution}³ lattice points around the view, {@link spacing} metres apart in the finest
+ * cascade and twice as far apart in each one around it. A point holds a probe only while something on
+ * screen wants it, so probes are a sparse cache over the lattice.
+ *
+ * **Storage** (§8.2):
+ * - {@link indirection}, `r32uint`, a texel a lattice point in storage that wraps, the cascades
+ *   stacked along z: the slot of the point's probe, or none. Allocated whole, since the lattice follows
+ *   from the structure alone.
+ * - a slot each: a state of two words, the kind and updates and then where relocation moved it
+ *   (`PROBE_CLIPMAP.js`), a 64-byte record (`PROBE_RECORD_STRUCT`), an octahedral radiance tile of
+ *   {@link radiance_resolution}² texels and a depth-moment tile of {@link depth_resolution}², each with
+ *   a one-texel skirt, in two 2-D tile atlases. The slots are handed out by a free list on the device.
+ * - the active lists, double-buffered: each frame's retire reads the last frame's and writes the
+ *   frame's; a wanted bit a lattice point and the wanted list, made again every frame; the trace list
+ *   of the frame's updates, at most U = ⌊ray_budget / rays_per_probe⌋.
+ *
+ * **A frame's lifetime** ({@link graph_update}, §8.3, §8.5): the windows are placed around the anchor,
+ * coarsest first, each a parent cell inside its parent. Retire frees the probes whose points left
+ * their windows or that nobody wanted for `retention_time`, want marks the cages one pixel of each
+ * screen tile reads, admit gives each wanted point without a probe a NEW one, schedule sets the period
+ * T from the wanted count, and the due passes list the frame's updates, NEW probes first.
+ *
+ * **The frame's update** (§8.4, §8.6), once the brick clipmap is built: relocate, then trace, a ray a
+ * thread, R a probe, each with its hit and the suns' soft shadows there.
+ *
+ * Retire, admit, due and the update run through commands written on the device, want over the screen's
+ * tiles: nothing is sized by the capacity.
+ *
+ * **Capacity** starts at `2·N²·C` slots, rounded up to a power of two: a visible surface crosses each
+ * cascade as a shell a cell thick, doubled for the cage. An admission the free list could not serve is
+ * counted on the device and read back, and the next frame doubles the capacity (§7.10's pattern). Nothing
+ * shrinks.
+ */
+export class GPUProbeClipmap {
+    /**
+     * @type {number}
+     * @readonly
+     */
+    cascade_count;
+
+    /**
+     * Lattice points per axis of a cascade.
+     * @type {number}
+     * @readonly
+     */
+    resolution;
+
+    /**
+     * Metres between probes in the finest cascade.
+     * @type {number}
+     * @readonly
+     */
+    spacing;
+
+    /**
+     * Octahedral radiance texels per side of a probe.
+     * @type {number}
+     * @readonly
+     */
+    radiance_resolution;
+
+    /**
+     * Octahedral depth-moment texels per side of a probe.
+     * @type {number}
+     * @readonly
+     */
+    depth_resolution;
+
+    /** @type {GPUDevice} */
+    #device;
+
+    /** @type {ClipmapCascadePlacement} */
+    #placement;
+
+    /** @type {GPUTexture} */
+    #indirection;
+
+    /** @type {GPUTextureView} */
+    #indirection_view;
+
+    /** @type {GPUBuffer} */
+    #levels;
+
+    /** @type {GPUBuffer} */
+    #states;
+
+    /** @type {GPUBuffer} */
+    #records;
+
+    /** @type {GPUBuffer} */
+    #free;
+
+    /** @type {GPUBuffer} */
+    #counters;
+
+    /** What the one-thread passes write for the passes after them to dispatch through. @type {GPUBuffer} */
+    #dispatch;
+
+    /** The two active lists; the frame reads `#active[#parity]` and writes the other. @type {GPUBuffer[]} */
+    #active = [];
+
+    #parity = 0;
+
+    /** @type {GPUBuffer} */
+    #wanted;
+
+    /** @type {GPUBuffer} */
+    #wanted_bits;
+
+    /** The probes the frame updates, at most U. @type {GPUBuffer|null} */
+    #trace = null;
+
+    /** Probes the trace list holds: U as it last grew. */
+    #trace_capacity = 0;
+
+    /** Where relocation left each listed probe, `vec4<f32>(origin, spacing)`, as many as the trace list holds. @type {GPUBuffer|null} */
+    #origins = null;
+
+    /** The listed probes' maps, as accumulation writes them, as many as the trace list holds. @type {GPUBuffer|null} */
+    #maps = null;
+
+    /** The listed probes' projected rows, n_r a probe, as many as the trace list holds. @type {GPUBuffer|null} */
+    #projection = null;
+
+    /** The frame's rays, R a listed probe. @type {GPUBuffer|null} */
+    #rays = null;
+
+    /** Rays the rays buffer holds: U·R as it last grew. */
+    #ray_capacity = 0;
+
+    /** @type {GPUTileAtlas2D} */
+    #radiance;
+
+    /** @type {GPUTileAtlas2D} */
+    #depth;
+
+    /** Slots. */
+    #capacity = 0;
+
+    /** Lattice points over every cascade. */
+    #key_count = 0;
+
+    /** Whether the next frame is the first, which fills the indirection and the free list. */
+    #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;
+
+    /** Frames recorded, and the caller's time at the first: the clock the records keep. */
+    #frame = 0;
+    #time_origin = 0;
+
+    #destroyed = false;
+
+    #levels_data = new ArrayBuffer(CLIPMAP_LEVEL_ARRAY.size);
+    #levels_i32 = new Int32Array(this.#levels_data);
+    #levels_f32 = new Float32Array(this.#levels_data);
+
+    #retire_settings = { capacity: 0, resolution: 0, time: 0, retention_time: 0 };
+    #want_settings = { cascade_count: 0, resolution: 0, frame: 0, key_count: 0 };
+    #admit_command_settings = { key_count: 0 };
+    #admit_settings = { capacity: 0, resolution: 0, key_count: 0, time: 0 };
+    #schedule_settings = { capacity: 0, key_count: 0, trace_capacity: 0 };
+    #due_settings = { capacity: 0, resolution: 0, trace_capacity: 0, frame: 0, new_only: 0 };
+    #trace_command_settings = { trace_capacity: 0, rays_per_probe: 0 };
+    #relocate_settings = { trace_capacity: 0, brick_cascade_count: 0 };
+    #trace_settings = { trace_capacity: 0, rays_per_probe: 0, radiance_resolution: 0, brick_cascade_count: 0, t_max: 0 };
+    #shade_settings = { trace_capacity: 0, rays_per_probe: 0 };
+    #accumulate_settings = { trace_capacity: 0, rays_per_probe: 0, radiance_resolution: 0, depth_resolution: 0, radiance_tiles_per_row: 0, depth_tiles_per_row: 0, time: 0, response_time: 0 };
+    #project_settings = { trace_capacity: 0, radiance_resolution: 0, depth_resolution: 0, time: 0 };
+    #publish_settings = { trace_capacity: 0, radiance_resolution: 0, depth_resolution: 0, radiance_tiles_per_row: 0, depth_tiles_per_row: 0 };
+    #push_settings = { first: 0, count: 0, counter: PROBE_COUNTER_FREE };
+
+    #bindings = {};
+
+    #lifetime_data = { counters: -1, depth: -1, normal: -1, stbn: -1 };
+
+    #update_data = { counters: -1, bricks: -1 };
+
+    /** The frame's brick clipmap, which the update's rays read. @type {import("../brick/GPUBrickClipmap.js").GPUBrickClipmap|null} */
+    #brick_clipmap = null;
+
+    /**
+     * The frame's scene: its light database, the suns the rays' hits trace shadows toward; its environment,
+     * what a miss sees; its rows and geometry caches, what a hit is on.
+     * @type {import("../../../scene/GPUSceneContext.js").GPUSceneContext|null}
+     */
+    #scene = null;
+
+    /** The frame's resident materials, a hit's fallback. @type {import("../../../material/resident/GPUResidentMaterialContext.js").GPUResidentMaterialContext|null} */
+    #materials = null;
+
+    /** The frame's row → card set table. @type {GPUBuffer|null} */
+    #card_rows = null;
+
+    /** The frame's: the want's launch and what it reads. */
+    #want_groups = [0, 0];
+
+    /** @type {GPUBuffer|null} */
+    #camera = 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.spacing metres
+     * @param {number} options.radiance_resolution a power of two
+     * @param {number} options.depth_resolution a power of two
+     */
+    constructor(device, { cascade_count, resolution, spacing, radiance_resolution, depth_resolution }) {
+        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(spacing, 'spacing');
+        assert.greaterThan(spacing, 0, 'spacing');
+        assert.greaterThanOrEqual(radiance_resolution, PROBE_CLIPMAP_OCTAHEDRAL_RESOLUTION_MIN, 'radiance_resolution');
+        assert.lessThanOrEqual(radiance_resolution, PROBE_CLIPMAP_OCTAHEDRAL_RESOLUTION_MAX, 'radiance_resolution');
+        assert.greaterThanOrEqual(depth_resolution, PROBE_CLIPMAP_OCTAHEDRAL_RESOLUTION_MIN, 'depth_resolution');
+        assert.lessThanOrEqual(depth_resolution, PROBE_CLIPMAP_OCTAHEDRAL_RESOLUTION_MAX, 'depth_resolution');
+
+        this.cascade_count = cascade_count;
+        this.resolution = resolution;
+        this.spacing = spacing;
+        this.radiance_resolution = radiance_resolution;
+        this.depth_resolution = depth_resolution;
+
+        this.#device = device;
+
+        this.#placement = new ClipmapCascadePlacement({
+            cascade_count,
+            resolution: [resolution, resolution, resolution],
+            cell_size: spacing,
+            step: PROBE_CASCADE_STEP,
+            hysteresis: PROBE_CASCADE_HYSTERESIS,
+            nest_margin: PROBE_CASCADE_NEST_MARGIN,
+        });
+
+        this.#indirection = device.createTexture({
+            label: 'Probe clipmap / probe indirection',
+            size: [resolution, resolution, resolution * cascade_count],
+            dimension: '3d',
+            format: 'r32uint',
+            usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.STORAGE_BINDING,
+        });
+
+        this.#indirection_view = this.#indirection.createView();
+
+        // a power of two at least 2·N²·C
+        const capacity = this.#capacity = 2 ** Math.ceil(Math.log2(2 * resolution * resolution * cascade_count));
+        const keys = this.#key_count = resolution ** 3 * cascade_count;
+
+        this.#radiance = new GPUTileAtlas2D({
+            device,
+            formats: ['rgba16float'],
+            tile_size: [radiance_resolution + 2, radiance_resolution + 2],
+            // sampled by the readers and the accumulation's history, stored into by publish
+            usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.STORAGE_BINDING,
+            label: 'Probe clipmap / probe radiance',
+            capacity,
+        });
+
+        this.#depth = new GPUTileAtlas2D({
+            device,
+            formats: ['rg16float'],
+            tile_size: [depth_resolution + 2, depth_resolution + 2],
+            usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.STORAGE_BINDING,
+            label: 'Probe clipmap / probe depth',
+            capacity,
+        });
+
+        // two words a slot: the state, then the relocation offset
+        this.#states = this.#create_buffer('probe states', 8 * capacity, GPUBufferUsage.COPY_SRC);
+        this.#records = this.#create_buffer('probe records', PROBE_RECORD_STRUCT.size * capacity, GPUBufferUsage.COPY_SRC);
+        this.#free = this.#create_buffer('probe free list', 4 * capacity, GPUBufferUsage.COPY_SRC);
+        this.#active.push(
+            this.#create_buffer('probe active 0', LIST_HEADER_BYTES + 4 * capacity, GPUBufferUsage.COPY_SRC | GPUBufferUsage.COPY_DST),
+            this.#create_buffer('probe active 1', LIST_HEADER_BYTES + 4 * capacity, GPUBufferUsage.COPY_SRC | GPUBufferUsage.COPY_DST),
+        );
+        this.#wanted = this.#create_buffer('probe wanted', LIST_HEADER_BYTES + 4 * keys, GPUBufferUsage.COPY_DST);
+        this.#wanted_bits = this.#create_buffer('probe wanted bits', 4 * Math.ceil(keys / 32), GPUBufferUsage.COPY_DST);
+        this.#counters = this.#create_buffer('probe counters', 4 * PROBE_COUNTER_WORDS, GPUBufferUsage.COPY_SRC | GPUBufferUsage.COPY_DST);
+        // zero: the first frame's retire dispatches nothing
+        this.#dispatch = this.#create_buffer('probe dispatch', 4 * PROBE_DISPATCH_WORDS, GPUBufferUsage.INDIRECT);
+
+        // every slot free, once the first frame has filled the list
+        const counters = new Uint32Array(PROBE_COUNTER_WORDS);
+
+        counters[PROBE_COUNTER_FREE] = capacity;
+
+        device.queue.writeBuffer(this.#counters, 0, counters);
+
+        this.#levels = device.createBuffer(BufferDescriptor.fromJSON({
+            label: 'Probe clipmap / probe levels',
+            size: CLIPMAP_LEVEL_ARRAY.size,
+            usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
+        }));
+    }
+
+    /**
+     * @returns {GPUTexture}
+     */
+    get indirection() {
+        return this.#indirection;
+    }
+
+    /**
+     * The cascades' cage windows, a {@link CLIPMAP_LEVEL_ARRAY} as a uniform, finest first, as placed by
+     * the last {@link graph_update}: a cell is a cage of eight lattice points, so a window is one cell
+     * short of the lattice's on each axis (`PROBE_LEVELS_RESOURCE`).
+     * @returns {GPUBuffer}
+     */
+    get levels() {
+        return this.#levels;
+    }
+
+    /**
+     * Slots: the probes there can be before the capacity grows.
+     * @returns {number}
+     */
+    get capacity() {
+        return this.#capacity;
+    }
+
+    /**
+     * @param {number} cascade
+     * @param {number} axis
+     * @returns {number} the cascade's lattice window's least point on the axis, in its spacing
+     */
+    corner(cascade, axis) {
+        return this.#placement.corner(cascade, axis);
+    }
+
+    /**
+     * @param {number} cascade
+     * @returns {number} metres between the cascade's probes
+     */
+    cell_size(cascade) {
+        return this.#placement.cell_size(cascade);
+    }
+
+    /**
+     * @param {ProbeClipmapSettings} settings
+     * @returns {boolean} whether this is what the settings' probe cascades and probes describe
+     */
+    built_for(settings) {
+        return settings.probe_cascade_count === this.cascade_count
+            && settings.probe_cascade_resolution === this.resolution
+            && settings.probe_spacing === this.spacing
+            && settings.radiance_resolution === this.radiance_resolution
+            && settings.depth_resolution === this.depth_resolution;
+    }
+
+    /**
+     * Record the frame's lifetime (§8.3): place the windows around the anchor, retire, want from the
+     * G-buffer, admit and schedule; then, once the bricks are built, its updates: relocate, trace and
+     * shade the listed probes' rays (§8.4–§8.7). Allocates nothing per frame.
+     *
+     * @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.depth graph handle of the frame's depth
+     * @param {number} options.normal graph handle of the G-buffer's normals
+     * @param {GPUBuffer} options.camera the view's camera uniform
+     * @param {*} options.stbn the 2-channel spatio-temporal blue noise, `STATIC_GRAPHICS_ENGINE_ASSETS.stbn_vec2`
+     * @param {ArrayLike<number>} options.resolution the frame's pixels, x and y
+     * @param {number} options.time the caller's clock, seconds
+     * @param {number} options.retention_time seconds an unwanted probe keeps its slot
+     * @param {number} options.response_time seconds of the blend's response, τ (§8.8)
+     * @param {number} options.ray_budget rays a frame
+     * @param {number} options.rays_per_probe rays an update, R: the frame updates ⌊ray_budget / R⌋ probes at most
+     * @param {import("../brick/GPUBrickClipmap.js").GPUBrickClipmap} options.brick_clipmap the world the
+     *   rays see, built this frame
+     * @param {number} options.bricks the graph handle of the brick clipmap's last write this frame, which
+     *   the update orders after
+     * @param {import("../../../scene/GPUSceneContext.js").GPUSceneContext} options.scene the scene the rays
+     *   light and shade: its lights, its environment, its rows and their geometry caches' cards
+     * @param {import("../../../material/resident/GPUResidentMaterialContext.js").GPUResidentMaterialContext} options.materials
+     *   the resident materials, updated this frame: what a hit no card sees takes
+     * @param {GPUBuffer} options.card_rows the row → card set table, a word a `meshes` row
+     */
+    graph_update({ graph, x, y, z, depth, normal, camera, stbn, resolution, time, retention_time, response_time, ray_budget, rays_per_probe, brick_clipmap, bricks, scene, materials, card_rows }) {
+        assert.defined(graph, 'graph');
+        assert.defined(camera, 'camera');
+        assert.defined(stbn, 'stbn');
+        assert.isFinite(time, 'time');
+        assert.isFinite(retention_time, 'retention_time');
+        assert.greaterThan(retention_time, 0, 'retention_time');
+        assert.isFinite(response_time, 'response_time');
+        assert.greaterThan(response_time, 0, 'response_time');
+        assert.isPositiveInteger(rays_per_probe, 'rays_per_probe');
+        assert.greaterThanOrEqual(ray_budget, rays_per_probe, 'ray_budget');
+        assert.defined(brick_clipmap, 'brick_clipmap');
+        assert.isNonNegativeInteger(bricks, 'bricks');
+        assert.defined(scene, 'scene');
+        assert.defined(materials, 'materials');
+        assert.defined(card_rows, 'card_rows');
+        assert.notOk(this.#destroyed, 'destroyed');
+
+        if (this.#grow_pending) {
+            this.#grow_pending = false;
+            this.#grow();
+        }
+
+        const trace_capacity = Math.floor(ray_budget / rays_per_probe);
+
+        this.#ensure_trace(trace_capacity);
+        this.#ensure_rays(trace_capacity * rays_per_probe);
+
+        if (this.#frame === 0) {
+            this.#time_origin = time;
+        }
+
+        this.#place(x, y, z);
+
+        this.#device.queue.writeBuffer(this.#levels, 0, this.#levels_data);
+
+        const clock = time - this.#time_origin;
+
+        this.#retire_settings.capacity = this.#capacity;
+        this.#retire_settings.resolution = this.resolution;
+        this.#retire_settings.time = clock;
+        this.#retire_settings.retention_time = retention_time;
+
+        this.#want_settings.cascade_count = this.cascade_count;
+        this.#want_settings.resolution = this.resolution;
+        this.#want_settings.frame = this.#frame;
+        this.#want_settings.key_count = this.#key_count;
+
+        this.#admit_command_settings.key_count = this.#key_count;
+
+        this.#admit_settings.capacity = this.#capacity;
+        this.#admit_settings.resolution = this.resolution;
+        this.#admit_settings.key_count = this.#key_count;
+        this.#admit_settings.time = clock;
+
+        this.#schedule_settings.capacity = this.#capacity;
+        this.#schedule_settings.key_count = this.#key_count;
+        this.#schedule_settings.trace_capacity = trace_capacity;
+
+        this.#due_settings.capacity = this.#capacity;
+        this.#due_settings.resolution = this.resolution;
+        this.#due_settings.trace_capacity = trace_capacity;
+        this.#due_settings.frame = this.#frame;
+
+        this.#trace_command_settings.trace_capacity = trace_capacity;
+        this.#trace_command_settings.rays_per_probe = rays_per_probe;
+        this.#trace_command_settings.radiance_resolution = this.radiance_resolution;
+        this.#trace_command_settings.depth_resolution = this.depth_resolution;
+
+        // past the coarsest window's far corner every ray has left the clipmap
+        const coarsest = brick_clipmap.cascade_count - 1;
+
+        this.#trace_settings.trace_capacity = trace_capacity;
+        this.#trace_settings.rays_per_probe = rays_per_probe;
+        this.#trace_settings.radiance_resolution = this.radiance_resolution;
+        this.#trace_settings.brick_cascade_count = brick_clipmap.cascade_count;
+        this.#trace_settings.t_max = Math.sqrt(3) * brick_clipmap.resolution * brick_clipmap.cell_size(coarsest);
+
+        this.#relocate_settings.trace_capacity = trace_capacity;
+        this.#relocate_settings.brick_cascade_count = brick_clipmap.cascade_count;
+
+        this.#shade_settings.trace_capacity = trace_capacity;
+        this.#shade_settings.rays_per_probe = rays_per_probe;
+
+        const accumulate = this.#accumulate_settings;
+
+        accumulate.trace_capacity = trace_capacity;
+        accumulate.rays_per_probe = rays_per_probe;
+        accumulate.radiance_resolution = this.radiance_resolution;
+        accumulate.depth_resolution = this.depth_resolution;
+        accumulate.radiance_tiles_per_row = this.#radiance.tiles_per_row;
+        accumulate.depth_tiles_per_row = this.#depth.tiles_per_row;
+        accumulate.time = clock;
+        accumulate.response_time = response_time;
+
+        this.#project_settings.trace_capacity = trace_capacity;
+        this.#project_settings.radiance_resolution = this.radiance_resolution;
+        this.#project_settings.depth_resolution = this.depth_resolution;
+        this.#project_settings.time = clock;
+
+        const publish = this.#publish_settings;
+
+        publish.trace_capacity = trace_capacity;
+        publish.radiance_resolution = this.radiance_resolution;
+        publish.depth_resolution = this.depth_resolution;
+        publish.radiance_tiles_per_row = this.#radiance.tiles_per_row;
+        publish.depth_tiles_per_row = this.#depth.tiles_per_row;
+
+        this.#brick_clipmap = brick_clipmap;
+        this.#scene = scene;
+        this.#materials = materials;
+        this.#card_rows = card_rows;
+
+        const tiles_x = Math.ceil(resolution[0] / PROBE_WANT_TILE);
+        const tiles_y = Math.ceil(resolution[1] / PROBE_WANT_TILE);
+
+        this.#want_groups[0] = Math.ceil(tiles_x / PROBE_WANT_WORKGROUP_TILES);
+        this.#want_groups[1] = Math.ceil(tiles_y / PROBE_WANT_WORKGROUP_TILES);
+
+        this.#camera = camera;
+
+        const data = this.#lifetime_data;
+        const pass = graph.add("Probe Clipmap Lifetime", data, this.#execute_lifetime);
+
+        data.counters = pass.write(graph_import_buffer(graph, this.#counters, "probe_counters"));
+        data.depth = pass.read(depth);
+        data.normal = pass.read(normal);
+        data.stbn = stbn;
+
+        pass.make_side_effect();
+
+        // the frame's updates, once its bricks are built
+        const update_data = this.#update_data;
+        const update = graph.add("Probe Clipmap Update", update_data, this.#execute_update);
+
+        update_data.counters = update.write(data.counters);
+        update_data.bricks = update.read(bricks);
+
+        update.make_side_effect();
+
+        // an admission the free list could not serve grows the capacity, from a later frame
+        graph_read_buffer({ graph, buffer: update_data.counters, offset: 4 * PROBE_COUNTER_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.#frame++;
+    }
+
+    /**
+     * Place every window, coarsest first, and write the cage windows the readers take.
+     */
+    #place(x, y, z) {
+        const placement = this.#placement;
+        const n = this.resolution;
+
+        placement.begin();
+
+        for (let c = this.cascade_count - 1; c >= 0; c--) {
+            placement.place(c, x, y, z);
+        }
+
+        for (let c = 0; c < this.cascade_count; c++) {
+            const level = (c * CLIPMAP_LEVEL_STRUCT.aligned_size) >>> 2;
+
+            for (let axis = 0; axis < 3; axis++) {
+                this.#levels_i32[level + axis] = placement.corner(c, axis);
+                // the cages: a cell between two lattice points
+                this.#levels_i32[level + 4 + axis] = n - 1;
+            }
+
+            this.#levels_f32[level + 3] = placement.cell_size(c);
+        }
+    }
+
+    /**
+     * Double the capacity: the atlases add rows, the per-slot buffers 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.#radiance.capacity_limit, this.#depth.capacity_limit);
+
+        if (capacity <= old_capacity) {
+            return;
+        }
+
+        this.#radiance.ensure_capacity(capacity);
+        this.#depth.ensure_capacity(capacity);
+
+        this.#states = this.#regrow(this.#states, 'probe states', 8 * capacity);
+        this.#records = this.#regrow(this.#records, 'probe records', PROBE_RECORD_STRUCT.size * capacity);
+        this.#free = this.#regrow(this.#free, 'probe free list', 4 * capacity);
+        this.#active[0] = this.#regrow(this.#active[0], 'probe active 0', LIST_HEADER_BYTES + 4 * capacity);
+        this.#active[1] = this.#regrow(this.#active[1], 'probe active 1', LIST_HEADER_BYTES + 4 * capacity);
+
+        this.#capacity = capacity;
+        this.#pushes.push(old_capacity, capacity - old_capacity);
+    }
+
+    /**
+     * A trace list of at least `trace_capacity` probes: U follows the ray settings, which change without a
+     * rebuild.
+     */
+    #ensure_trace(trace_capacity) {
+        if (this.#trace !== null && this.#trace_capacity >= trace_capacity) {
+            return;
+        }
+
+        this.#trace?.destroy();
+        this.#origins?.destroy();
+        this.#maps?.destroy();
+        this.#projection?.destroy();
+        this.#trace_capacity = trace_capacity;
+        this.#trace = this.#create_buffer('probe trace', LIST_HEADER_BYTES + 4 * trace_capacity, GPUBufferUsage.COPY_DST);
+        this.#origins = this.#create_buffer('probe origins', 16 * trace_capacity, 0);
+        this.#maps = this.#create_buffer('probe maps', 4 * probe_clipmap_maps_words(this.radiance_resolution, this.depth_resolution) * trace_capacity, 0);
+        this.#projection = this.#create_buffer('probe projection', PROBE_PROJECTION_ROW_STRUCT.size * this.radiance_resolution * trace_capacity, 0);
+    }
+
+    /**
+     * Room for `ray_count` rays, U·R: the update's rays, which the ray settings size.
+     */
+    #ensure_rays(ray_count) {
+        if (this.#rays !== null && this.#ray_capacity >= ray_count) {
+            return;
+        }
+
+        this.#rays?.destroy();
+        this.#ray_capacity = ray_count;
+        this.#rays = this.#create_buffer('probe rays', PROBE_RAY_STRUCT.size * ray_count, 0);
+    }
+
+    #execute_lifetime = (data, resources, context) => {
+        const encoder = context.encoder;
+        const counters = resources.get(data.counters);
+        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 },
+            });
+
+            shader_probe_clipmap_fill.dispatch({
+                encoder,
+                group_count_x: this.resolution,
+                group_count_y: this.resolution * this.cascade_count,
+                bindings: { probe_indirection: this.#indirection_view },
+            });
+        }
+
+        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: counters, slots: this.#free },
+            });
+        }
+
+        pushes.length = 0;
+
+        const active_read = this.#active[this.#parity];
+        const active_write = this.#active[1 - this.#parity];
+
+        this.#parity = 1 - this.#parity;
+
+        // the frame's lists start empty, and no point is wanted yet
+        encoder.clearBuffer(active_write, 0, 4);
+        encoder.clearBuffer(this.#wanted, 0, 4);
+        encoder.clearBuffer(this.#trace, 0, 4);
+        encoder.clearBuffer(this.#wanted_bits);
+
+        b.probe_levels = this.#levels;
+        b.probe_indirection = this.#indirection_view;
+        b.probe_states = this.#states;
+        b.probe_records = this.#records;
+        b.probe_counters = counters;
+        b.probe_free = this.#free;
+        b.probe_active_read = active_read;
+        b.probe_active_write = active_write;
+        b.probe_wanted = this.#wanted;
+        b.probe_wanted_bits = this.#wanted_bits;
+        b.probe_trace = this.#trace;
+        b.probe_dispatch = this.#dispatch;
+
+        b.settings = this.#retire_settings;
+
+        shader_probe_clipmap_retire.dispatchIndirect({
+            encoder,
+            bindings: b,
+            command: this.#dispatch,
+            command_offset: 4 * PROBE_DISPATCH_ACTIVE,
+        });
+
+        b.gBufferDepth = resources.get(data.depth);
+        b.gBufferNormals = resources.get(data.normal);
+        b.camera = this.#camera;
+        b.tSTBN_vec2 = data.stbn;
+        b.settings = this.#want_settings;
+
+        shader_probe_clipmap_want.dispatch({
+            encoder,
+            group_count_x: this.#want_groups[0],
+            group_count_y: this.#want_groups[1],
+            bindings: b,
+        });
+
+        b.settings = this.#admit_command_settings;
+
+        shader_probe_clipmap_admit_command.dispatch({ encoder, bindings: b });
+
+        b.settings = this.#admit_settings;
+
+        shader_probe_clipmap_admit.dispatchIndirect({
+            encoder,
+            bindings: b,
+            command: this.#dispatch,
+            command_offset: 4 * PROBE_DISPATCH_ADMIT,
+        });
+
+        b.settings = this.#schedule_settings;
+
+        shader_probe_clipmap_schedule.dispatch({ encoder, bindings: b });
+
+        // the frame's updates: the NEW probes first, then those whose turn it is
+        const due = this.#due_settings;
+
+        b.settings = due;
+
+        for (const new_only of [1, 0]) {
+            due.new_only = new_only;
+
+            shader_probe_clipmap_due.dispatchIndirect({
+                encoder,
+                bindings: b,
+                command: this.#dispatch,
+                command_offset: 4 * PROBE_DISPATCH_ACTIVE,
+            });
+        }
+
+        b.settings = this.#trace_command_settings;
+
+        shader_probe_clipmap_trace_command.dispatch({ encoder, bindings: b });
+    };
+
+    #execute_update = (data, resources, context) => {
+        const encoder = context.encoder;
+        const b = this.#bindings;
+
+        this.#brick_clipmap.write_bindings(b);
+
+        b.probe_counters = resources.get(data.counters);
+        b.probe_origins = this.#origins;
+        b.settings = this.#relocate_settings;
+
+        shader_probe_clipmap_relocate.dispatchIndirect({
+            encoder,
+            bindings: b,
+            command: this.#dispatch,
+            command_offset: 4 * PROBE_DISPATCH_TRACED,
+        });
+
+        const scene = this.#scene;
+        const lights = scene.lights;
+
+        b.probe_rays = this.#rays;
+        b.light_data = lights.buffer_data;
+        b.settings = this.#trace_settings;
+
+        shader_probe_clipmap_trace.dispatchIndirect({
+            encoder,
+            bindings: b,
+            command: this.#dispatch,
+            command_offset: 4 * PROBE_DISPATCH_RAYS,
+        });
+
+        // what each ray brings back: the buffers taken now, since a table may have been replaced as it grew
+        const sdf = scene.geometries.sdf;
+        const cards = sdf.cards;
+
+        sdf.write_bindings(b);
+
+        b.scene_database = scene.scene_database_buffer;
+        b.mesh_card_rows = this.#card_rows;
+        b.mesh_card_sets = cards.records;
+        b.mesh_card_albedo = cards.atlas.texture_at(0).obtainView();
+        b.mesh_card_emissive = cards.atlas.texture_at(1).obtainView();
+        b.materials = this.#materials.buffer_materials;
+        b.texture_means = this.#materials.buffer_texture_means;
+        b.tEnvironment = lights.environment.obtainView();
+        b.settings = this.#shade_settings;
+
+        shader_probe_clipmap_shade.dispatchIndirect({
+            encoder,
+            bindings: b,
+            command: this.#dispatch,
+            command_offset: 4 * PROBE_DISPATCH_RAYS,
+        });
+
+        // the probes' maps from their rays, against the atlases as they were; their SH and kind from the
+        // maps; then the atlases from the maps
+        b.probe_maps = this.#maps;
+        b.probe_projection = this.#projection;
+        b.probe_radiance = this.#radiance.texture_at(0).obtainView();
+        b.probe_depth = this.#depth.texture_at(0).obtainView();
+        b.settings = this.#accumulate_settings;
+
+        shader_probe_clipmap_accumulate.dispatchIndirect({
+            encoder,
+            bindings: b,
+            command: this.#dispatch,
+            command_offset: 4 * PROBE_DISPATCH_TEXELS,
+        });
+
+        b.settings = this.#project_settings;
+
+        shader_probe_clipmap_project_rows.dispatchIndirect({
+            encoder,
+            bindings: b,
+            command: this.#dispatch,
+            command_offset: 4 * PROBE_DISPATCH_ROWS,
+        });
+
+        shader_probe_clipmap_project.dispatchIndirect({
+            encoder,
+            bindings: b,
+            command: this.#dispatch,
+            command_offset: 4 * PROBE_DISPATCH_TRACED,
+        });
+
+        b.settings = this.#publish_settings;
+
+        shader_probe_clipmap_publish.dispatchIndirect({
+            encoder,
+            bindings: b,
+            command: this.#dispatch,
+            command_offset: 4 * PROBE_DISPATCH_PUBLISH,
+        });
+    };
+
+    /**
+     * @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.#indirection.destroy();
+        this.#radiance.destroy();
+        this.#depth.destroy();
+
+        for (const buffer of [this.#levels, this.#states, this.#records, this.#free, this.#counters, this.#dispatch, ...this.#active, this.#wanted, this.#wanted_bits, this.#trace, this.#origins, this.#maps, this.#projection, this.#rays]) {
+            buffer?.destroy();
+        }
+    }
+}