@woosh/meep-engine 3.61.1 → 3.61.3

package/src/shade/renderer/geometry/sdf/cards/GPUMeshCardSets.js

@@ -1,1468 +0,0 @@
-import { assert } from "../../../../../core/assert.js";
-import { ALLOCATOR_NO_SPACE, OffsetAllocator } from "../../../../../core/binary/allocator/OffsetAllocator.js";
-import Signal from "../../../../../core/events/signal/Signal.js";
-import IdPool from "../../../../../core/IdPool.js";
-import { warn_limited } from "../../../../util/warn_limited.js";
-import { BufferDescriptor } from "../../../../descriptor/buffer/BufferDescriptor.js";
-import { BindGroupDescriptor } from "../../../binding/BindGroupDescriptor.js";
-import { STRUCT_UNINDEXED_DRAW_COMMAND } from "../../../gpu_primitive/indirect/STRUCT_UNINDEXED_DRAW_COMMAND.js";
-import { WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION } from "../../../gpu_primitive/indirect/WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION.js";
-import { graph_import_texture } from "../../../shader/graph/graph_import_texture.js";
-import { GPUTileAtlas2D } from "../../../texture/atlas/GPUTileAtlas2D.js";
-import { MESH_SDF_BAKE_WORKGROUP_SIZE } from "../bake/MESH_SDF_BAKE.js";
-import { MESH_CARD_PAGE_TEXELS } from "./MESH_CARDS.js";
-import { MESH_CARD_SET_STRUCT } from "./MESH_CARD_SET_STRUCT.js";
-import { MeshCardCaptureMode } from "./MeshCardCaptureMode.js";
-import {
-    MESH_CARD_RASTER_CELLS_X,
-    MESH_CARD_RASTER_CELLS_Y,
-    MESH_CARD_RASTER_DEPTH_FORMAT,
-    MESH_CARD_RASTER_TARGET_FORMATS,
-    MESH_CARDS_RASTER_IMMEDIATE_SIZE,
-    MESH_CARDS_RASTER_LAYOUT,
-    mesh_cards_raster_pass_descriptor
-} from "./mesh_cards_raster_pass_descriptor.js";
-import { shader_mesh_cards_capture } from "./shader_mesh_cards_capture.js";
-import { MESH_CARDS_RASTER_ARGS_WORKGROUP_SIZE, shader_mesh_cards_raster_args } from "./shader_mesh_cards_raster_args.js";
-import { shader_mesh_cards_raster_scatter } from "./shader_mesh_cards_raster_scatter.js";
-
-/**
- * @typedef {import("../../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} FrameGraph
- * @typedef {import("../../../material/ShadeMaterial.js").ShadeMaterial} ShadeMaterial
- * @typedef {import("../../../material/resident/GPUResidentMaterialContext.js").GPUResidentMaterialContext} GPUResidentMaterialContext
- * @typedef {import("../../../material/GPUMaterialManager.js").GPUMaterialManager} GPUMaterialManager
- * @typedef {import("../../../material/GPUMaterialContext.js").GPUMaterialContext} GPUMaterialContext
- * @typedef {import("../../../../../core/binary/allocator/OffsetAllocator.js").Allocation} Allocation
- */
-
-/** The id is free. */
-const SET_NONE = 0;
-/** Its geometry's layout is not placed: nothing to capture into yet. */
-const SET_WAITING = 1;
-/** Its first capture is queued or part done; readers find no card set. */
-const SET_CAPTURING = 2;
-/** Captured; it may be queued for a recapture, and reads the last capture until that is done. */
-const SET_RESIDENT = 3;
-
-/**
- * Texels a page has, and so the capture's threads a page.
- * @type {number}
- */
-const PAGE_THREADS = MESH_CARD_PAGE_TEXELS * MESH_CARD_PAGE_TEXELS;
-
-/**
- * Most pages a frame's capture may take: a workgroup a page, in one dispatch row.
- * @type {number}
- */
-export const MESH_CARD_CAPTURE_BUDGET_MAX = WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION;
-
-/**
- * Texels across the raster scratch, and down it at most: a frame's raster runs are packed into it in
- * shelves, and one that does not fit waits for the next frame. A frame's first run always fits, at
- * whatever size its region is.
- * @type {number}
- */
-const RASTER_SCRATCH_SIDE = 2048;
-
-/**
- * The raster scratch grows in steps of this many texels a side, so a frame a little larger than the
- * last does not make it again.
- * @type {number}
- */
-const RASTER_SCRATCH_STEP = 256;
-
-/**
- * s_e: the largest component of a material's emissive factor, which the capture stores emissive
- * over. 0 for a material that emits nothing, or that has no emissive factor.
- *
- * @param {ShadeMaterial} material
- * @returns {number}
- */
-export function mesh_card_emissive_scale_of(material) {
-    if (material.isStandardShadeMaterial !== true) {
-        return 0;
-    }
-
-    const e = material.emissive_factor;
-
-    return Math.max(0, e.r, e.g, e.b);
-}
-
-/**
- * @template {Uint8Array|Uint32Array} T
- * @param {T} array
- * @param {number} length
- * @returns {T}
- */
-function grow_typed(array, length) {
-    if (array.length >= length) {
-        return array;
-    }
-
-    let size = Math.max(1, array.length);
-
-    while (size < length) {
-        size *= 2;
-    }
-
-    const grown = new array.constructor(size);
-
-    grown.set(array);
-
-    return grown;
-}
-
-/**
- * Card sets (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §6.5): one (geometry, material) pair's capture of
- * its geometry's card layout, by card set id, the storage of which {@link GPUGeometrySDFManager}
- * keeps beside its fields and layouts.
- *
- * - A card set's pages are a run of tiles of the card atlas, one a page of the layout, in the
- *   layout's order, from page_base. The layout's column tables are the geometry's, shared by every
- *   card set of it, so a card set needs no page table of its own.
- * - The atlas is two `rgba8unorm` planes of 8×8 tiles ({@link GPUTileAtlas2D}): √(diffuse albedo)
- *   and depth; emissive / s_e and 0.
- * - Its record (`MESH_CARD_SET_STRUCT`) is written when a capture starts.
- *
- * **Lifetime.** {@link acquire} makes a card set for a pair and {@link release} gives it back; the
- * caller keeps one per pair. A card set of an aliased geometry ({@link alias}) is its source's: it
- * captures the source's layout through the source's meshlets. A card set waits until its geometry's layout is placed
- * ({@link set_layout}), is then captured, and turns resident ({@link onResident}) on the frame its
- * last page is recorded: the capture's writes come before any later pass reads it. A layout that
- * goes ({@link drop_layout}) withdraws its card sets ({@link onWithdrawn}) back to waiting.
- *
- * **Capture** ({@link graph_capture}, once a frame) takes at most `budget` pages, first captures in
- * the order they were asked for, then recaptures in the order queued. A card set's pages may span
- * frames. {@link recapture} queues a resident card set again, which reads its last capture until the
- * new one is done; a card set whose capture is under way starts it again.
- *
- * **Modes** ({@link capture_mode}). A traced card set is a run of pages, a thread a texel. A
- * rastered one is taken whole: its cards are drawn into a region of a scratch, a cell a card, and its
- * pages scattered from there into the atlas; the frame's last one may take the budget past its end.
- */
-export class GPUMeshCardSets {
-
-    /**
-     * @type {GPUDevice}
-     */
-    #device;
-
-    /**
-     * Sent with a card set id when its first capture is recorded in full.
-     * @type {Signal<number>}
-     */
-    onResident = new Signal();
-
-    /**
-     * Sent with a resident card set's id when its layout goes; it waits for the next.
-     * @type {Signal<number>}
-     */
-    onWithdrawn = new Signal();
-
-    #ids = new IdPool();
-
-    /**
-     * The source of each aliased geometry id.
-     * @type {Map<number, number>}
-     */
-    #source_of = new Map();
-
-    // ---- per card set id ----
-
-    #state = new Uint8Array(64);
-    #geometry = new Uint32Array(64);
-    /**
-     * Bumped whenever the id's queue entries go stale: given out, given back, its layout gone.
-     */
-    #ticket = new Uint32Array(64);
-    /** Pages of the capture under way taken so far. */
-    #next_page = new Uint32Array(64);
-    /** Whether a queue holds a live entry of the id. */
-    #queued = new Uint8Array(64);
-
-    /**
-     * @type {(ShadeMaterial|undefined)[]}
-     */
-    #material = [];
-
-    /**
-     * @type {(Allocation|null)[]}
-     */
-    #tiles = [];
-
-    // ---- per geometry id ----
-
-    /**
-     * Pages of each placed layout, by geometry id.
-     * @type {Map<number, number>}
-     */
-    #layout_pages = new Map();
-
-    /**
-     * Texels a side of each placed layout's largest card, by geometry id: the side of a raster cell.
-     * @type {Map<number, number>}
-     */
-    #layout_side = new Map();
-
-    /**
-     * The card sets of each geometry, by geometry id.
-     * @type {Map<number, number[]>}
-     */
-    #sets_of_geometry = new Map();
-
-    /**
-     * @type {MeshCardCaptureMode}
-     */
-    #capture_mode = MeshCardCaptureMode.Raster;
-
-    // ---- the queues: (id, ticket) pairs, from a head ----
-
-    #queue_new = [];
-    #head_new = 0;
-    #queue_re = [];
-    #head_re = 0;
-
-    // ---- device storage, made on first use ----
-
-    /** @type {GPUBuffer|null} */
-    #records = null;
-    #record_capacity = 0;
-    #record_scratch = new DataView(new ArrayBuffer(MESH_CARD_SET_STRUCT.size));
-
-    /** @type {GPUTileAtlas2D|null} */
-    #atlas = null;
-    /** @type {OffsetAllocator|null} */
-    #tile_allocator = null;
-
-    /** @type {GPUBuffer|null} */
-    #runs = null;
-    #run_capacity = 0;
-    #run_scratch = new Uint32Array(4 * 64);
-
-    #frame_runs = 0;
-    #frame_threads = 0;
-    /** Pages of the frame's budget not yet taken. */
-    #frame_left = 0;
-
-    #settings = { run_count: 0, thread_count: 0, groups_x: 0 };
-    #bindings = {};
-    #pass_data = { albedo: -1, emissive: -1 };
-
-    // ---- raster capture: a run a whole card set, (first scatter thread, id, region corner, cell side) ----
-
-    /** @type {GPUBuffer|null} */
-    #raster_runs = null;
-    /** @type {GPUBuffer|null} */
-    #raster_draws = null;
-    #raster_run_capacity = 0;
-    #raster_run_scratch = new Uint32Array(4 * 64);
-
-    /**
-     * The material context each of the frame's raster runs draws with.
-     * @type {GPUMaterialContext[]}
-     */
-    #frame_raster_materials = [];
-
-    #frame_raster_runs = 0;
-    #frame_raster_threads = 0;
-
-    /**
-     * What a frame's capture draws with, for the raster: set by {@link graph_capture}.
-     * @type {GPUMaterialManager|null}
-     */
-    #frame_material_contexts = null;
-
-    /**
-     * What a frame's capture traces with: set by {@link graph_capture}. Only what is traced is made
-     * resident, each run's material as its run is taken, so a frame that traces nothing leaves the
-     * resident materials as they were.
-     * @type {GPUResidentMaterialContext|null}
-     */
-    #frame_materials = null;
-
-    // the frame's shelves in the scratch
-    #shelf_x = 0;
-    #shelf_y = 0;
-    #shelf_height = 0;
-    #frame_scratch_width = 0;
-    #frame_scratch_height = 0;
-
-    /**
-     * √(diffuse albedo) and depth, emissive / s_e, then depth through the slab.
-     * @type {GPUTexture[]}
-     */
-    #raster_targets = [];
-    /** @type {GPUTextureView[]} */
-    #raster_views = [];
-    #raster_width = 0;
-    #raster_height = 0;
-
-    #raster_pass_descriptor = {
-        label: "Mesh Card Capture / Raster",
-        colorAttachments: MESH_CARD_RASTER_TARGET_FORMATS.map(() => ({
-            view: null,
-            loadOp: "clear",
-            storeOp: "store",
-            clearValue: [0, 0, 0, 0],
-        })),
-        depthStencilAttachment: {
-            view: null,
-            depthLoadOp: "clear",
-            depthStoreOp: "discard",
-            depthClearValue: 1,
-        },
-    };
-
-    #raster_immediate = new Uint32Array(MESH_CARDS_RASTER_IMMEDIATE_SIZE / 4);
-    #raster_immediate_f32 = new Float32Array(this.#raster_immediate.buffer);
-
-    #raster_args_settings = { run_count: 0 };
-    #raster_args_bindings = {};
-    #raster_scatter_settings = { run_count: 0, thread_count: 0, groups_x: 0 };
-    #raster_scatter_bindings = {};
-    #raster_pass_data = { arena: -1, albedo: -1, emissive: -1 };
-    /** The buffers group 1 of the draws binds beside the arena, as the frame's capture was recorded. */
-    #raster_group_buffers = { mesh_sdf_headers: null, geometries: null, meshlet_metadata: null, meshlet_data: null };
-
-    /** Card sets turned resident by the frame's capture, sent once it is recorded. */
-    #completed = [];
-
-    // ---- what has been done ----
-
-    #recaptures_requested = 0;
-    #pages_captured = 0;
-    #resident_count = 0;
-
-    /**
-     * @param {GPUDevice} device
-     */
-    constructor(device) {
-        assert.defined(device, 'device');
-
-        this.#device = device;
-    }
-
-    /**
-     * Card sets given out.
-     * @returns {number}
-     */
-    get count() {
-        let count = 0;
-
-        for (let id = 0; id < this.#state.length; id++) {
-            if (this.#state[id] !== SET_NONE) {
-                count++;
-            }
-        }
-
-        return count;
-    }
-
-    /**
-     * @returns {number}
-     */
-    get resident_count() {
-        return this.#resident_count;
-    }
-
-    /**
-     * Recaptures asked of resident card sets, and of captures under way restarted.
-     * @returns {number}
-     */
-    get recaptures_requested() {
-        return this.#recaptures_requested;
-    }
-
-    /**
-     * Pages the captures have recorded.
-     * @returns {number}
-     */
-    get pages_captured() {
-        return this.#pages_captured;
-    }
-
-    /**
-     * Whether a frame's capture has anything to do: pages queued, or card sets turned resident with
-     * nothing to capture, still to be announced.
-     * @returns {boolean}
-     */
-    get has_pending_capture() {
-        return this.#head_new < this.#queue_new.length
-            || this.#head_re < this.#queue_re.length
-            || this.#completed.length > 0;
-    }
-
-    /**
-     * Pages waiting for capture over every queue.
-     * @returns {number}
-     */
-    get pages_queued() {
-        let pages = 0;
-
-        for (const [queue, head] of [[this.#queue_new, this.#head_new], [this.#queue_re, this.#head_re]]) {
-            for (let i = head; i < queue.length; i += 2) {
-                const id = queue[i];
-
-                if (queue[i + 1] === this.#ticket[id]) {
-                    pages += this.#layout_pages.get(this.#geometry[id]) - this.#next_page[id];
-                }
-            }
-        }
-
-        return pages;
-    }
-
-    /**
-     * @returns {MeshCardCaptureMode}
-     */
-    get capture_mode() {
-        return this.#capture_mode;
-    }
-
-    /**
-     * A change captures every card set again in the new mode: resident ones read their last capture
-     * until it is done, and captures under way start again.
-     *
-     * @param {MeshCardCaptureMode} mode
-     */
-    set capture_mode(mode) {
-        assert.enum(mode, MeshCardCaptureMode, 'mode');
-
-        if (mode === this.#capture_mode) {
-            return;
-        }
-
-        this.#capture_mode = mode;
-
-        for (let id = 0; id < this.#state.length; id++) {
-            const state = this.#state[id];
-
-            if (state === SET_CAPTURING || state === SET_RESIDENT) {
-                this.recapture(id);
-            }
-        }
-    }
-
-    /**
-     * Whether readers may use the card set: captured at least once, and its layout still there.
-     *
-     * @param {number} id
-     * @returns {boolean}
-     */
-    is_resident(id) {
-        return this.#state[id] === SET_RESIDENT;
-    }
-
-    /**
-     * The card set's geometry id.
-     *
-     * @param {number} id
-     * @returns {number}
-     */
-    geometry_of(id) {
-        return this.#geometry[id];
-    }
-
-    /**
-     * Every card set's record, by id. Replaced when it grows; take it each frame.
-     * @returns {GPUBuffer}
-     */
-    get records() {
-        this.#ensure_device();
-
-        return this.#records;
-    }
-
-    /**
-     * The card atlas: plane 0 holds √(diffuse albedo) and depth, plane 1 emissive / s_e.
-     * @returns {GPUTileAtlas2D}
-     */
-    get atlas() {
-        this.#ensure_device();
-
-        return this.#atlas;
-    }
-
-    /**
-     * A card set for a pair. The caller keeps one per pair.
-     *
-     * @param {number} geometry the geometry id the pair draws; an aliased one's card set captures its source's
-     *     layout ({@link alias})
-     * @param {ShadeMaterial} material
-     * @returns {number} card set id
-     */
-    acquire(geometry, material) {
-        assert.isNonNegativeInteger(geometry, 'geometry');
-        assert.defined(material, 'material');
-
-        geometry = this.#source_of.get(geometry) ?? geometry;
-
-        const id = this.#ids.get();
-
-        this.#ensure_id(id);
-
-        this.#state[id] = SET_WAITING;
-        this.#geometry[id] = geometry;
-        this.#material[id] = material;
-        this.#ticket[id]++;
-        this.#next_page[id] = 0;
-        this.#queued[id] = 0;
-
-        let sets = this.#sets_of_geometry.get(geometry);
-
-        if (sets === undefined) {
-            sets = [];
-            this.#sets_of_geometry.set(geometry, sets);
-        }
-
-        sets.push(id);
-
-        if (this.#layout_pages.has(geometry)) {
-            this.#start(id);
-        }
-
-        return id;
-    }
-
-    /**
-     * @param {number} id
-     */
-    release(id) {
-        assert.notEqual(this.#state[id] ?? SET_NONE, SET_NONE, `card set ${id} is not given out`);
-
-        if (this.#state[id] === SET_RESIDENT) {
-            this.#resident_count--;
-        }
-
-        this.#free_tiles(id);
-
-        this.#state[id] = SET_NONE;
-        this.#ticket[id]++;
-        this.#queued[id] = 0;
-        this.#material[id] = undefined;
-
-        const sets = this.#sets_of_geometry.get(this.#geometry[id]);
-        const at = sets.indexOf(id);
-
-        sets[at] = sets[sets.length - 1];
-        sets.pop();
-
-        if (sets.length === 0) {
-            this.#sets_of_geometry.delete(this.#geometry[id]);
-        }
-
-        this.#ids.release(id);
-    }
-
-    /**
-     * The card set's material has changed (its version moved): capture it again. A resident card set
-     * reads its last capture until the new one is done.
-     *
-     * @param {number} id
-     */
-    recapture(id) {
-        const state = this.#state[id];
-
-        assert.notEqual(state ?? SET_NONE, SET_NONE, `card set ${id} is not given out`);
-
-        if (state === SET_WAITING) {
-            // its first capture will take the material as it is then
-            return;
-        }
-
-        this.#recaptures_requested++;
-
-        // from its first page, whether queued or not
-        this.#next_page[id] = 0;
-
-        if (this.#queued[id] === 0) {
-            this.#queued[id] = 1;
-            this.#queue_re.push(id, this.#ticket[id]);
-        }
-    }
-
-    /**
-     * A geometry's layout is placed, with `pages` pages: its card sets can be captured.
-     *
-     * @param {number} geometry
-     * @param {number} pages
-     * @param {number} side texels a side of the layout's largest card: its grid's longest axis in
-     *        voxels, plus one, the lattice having a point at either end
-     */
-    set_layout(geometry, pages, side) {
-        assert.isNonNegativeInteger(pages, 'pages');
-        assert.isPositiveInteger(side, 'side');
-
-        this.#layout_pages.set(geometry, pages);
-        this.#layout_side.set(geometry, side);
-
-        const sets = this.#sets_of_geometry.get(geometry);
-
-        if (sets === undefined) {
-            return;
-        }
-
-        for (let i = 0; i < sets.length; i++) {
-            if (this.#state[sets[i]] === SET_WAITING) {
-                this.#start(sets[i]);
-            }
-        }
-    }
-
-    /**
-     * A geometry's layout is gone: its card sets wait for the next.
-     *
-     * @param {number} geometry
-     */
-    drop_layout(geometry) {
-        if (!this.#layout_pages.delete(geometry)) {
-            return;
-        }
-
-        this.#layout_side.delete(geometry);
-
-        const sets = this.#sets_of_geometry.get(geometry);
-
-        if (sets === undefined) {
-            return;
-        }
-
-        for (let i = 0; i < sets.length; i++) {
-            const id = sets[i];
-            const was = this.#state[id];
-
-            this.#free_tiles(id);
-
-            this.#state[id] = SET_WAITING;
-            this.#ticket[id]++;
-            this.#queued[id] = 0;
-            this.#next_page[id] = 0;
-
-            if (was === SET_RESIDENT) {
-                this.#resident_count--;
-                this.onWithdrawn.send1(id);
-            }
-        }
-    }
-
-    /**
-     * The geometry `clone` is drawn as `source` from here on: its card sets, and those acquired for it after, capture
-     * `source`'s layout through `source`'s meshlets, the two being in one local space. A card set of `clone` waits
-     * for `source`'s layout, as one acquired for `source` does.
-     *
-     * @param {number} clone
-     * @param {number} source
-     */
-    alias(clone, source) {
-        assert.notEqual(clone, source, 'a geometry cannot alias itself');
-
-        this.#source_of.set(clone, source);
-
-        // its own layout, if it had one, went with its cache: what it has waits
-        this.drop_layout(clone);
-
-        const sets = this.#sets_of_geometry.get(clone);
-
-        if (sets === undefined) {
-            return;
-        }
-
-        this.#sets_of_geometry.delete(clone);
-
-        for (let i = 0; i < sets.length; i++) {
-            const id = sets[i];
-
-            this.#geometry[id] = source;
-
-            let of_source = this.#sets_of_geometry.get(source);
-
-            if (of_source === undefined) {
-                of_source = [];
-                this.#sets_of_geometry.set(source, of_source);
-            }
-
-            of_source.push(id);
-
-            if (this.#layout_pages.has(source)) {
-                this.#start(id);
-            }
-        }
-    }
-
-    /**
-     * `clone` is no longer aliased: card sets acquired for it from here on capture its own layout. Those it has keep
-     * capturing its source's until they are given back.
-     *
-     * @param {number} clone
-     */
-    unalias(clone) {
-        this.#source_of.delete(clone);
-    }
-
-    /**
-     * Pages from the atlas for a card set whose layout is placed, and its first capture queued.
-     *
-     * @param {number} id
-     */
-    #start(id) {
-        const pages = this.#layout_pages.get(this.#geometry[id]);
-
-        this.#ensure_device();
-
-        const tiles = this.#allocate_tiles(pages);
-
-        if (tiles === null) {
-            // the atlas is at the device's limit; it waits, and is tried again with the next layout
-            return;
-        }
-
-        this.#tiles[id] = tiles;
-        this.#state[id] = SET_CAPTURING;
-        this.#next_page[id] = 0;
-
-        if (pages === 0) {
-            // a layout with nothing to see: resident at once, every lookup missing
-            this.#write_record(id);
-            this.#turn_resident(id);
-            return;
-        }
-
-        this.#queued[id] = 1;
-        this.#queue_new.push(id, this.#ticket[id]);
-    }
-
-    #turn_resident(id) {
-        this.#state[id] = SET_RESIDENT;
-        this.#resident_count++;
-        this.#completed.push(id);
-    }
-
-    /**
-     * @param {number} pages
-     * @returns {Allocation|null}
-     */
-    #allocate_tiles(pages) {
-        const allocator = this.#tile_allocator;
-        const atlas = this.#atlas;
-
-        // a zero-page card set still takes an offset, freed like any other
-        const size = Math.max(1, pages);
-
-        if (!allocator.can_allocate(size)) {
-            const target = allocator.grow_target_for(size);
-
-            atlas.ensure_capacity(target);
-
-            if (atlas.capacity < target) {
-                warn_limited(`GPUMeshCardSets: the card atlas can't hold ${target} pages`);
-                return null;
-            }
-
-            allocator.grow(atlas.capacity);
-        }
-
-        const tiles = allocator.allocate(size);
-
-        assert.notEqual(tiles.offset, ALLOCATOR_NO_SPACE, 'tile allocation after growth');
-
-        return tiles;
-    }
-
-    /**
-     * @param {number} id
-     */
-    #free_tiles(id) {
-        const tiles = this.#tiles[id];
-
-        if (tiles !== null && tiles !== undefined) {
-            // only captures write tiles, in submission order: a later owner's capture comes after
-            this.#tile_allocator.free(tiles);
-            this.#tiles[id] = null;
-        }
-    }
-
-    /**
-     * @param {number} id
-     */
-    #write_record(id) {
-        const view = this.#record_scratch;
-        const material = this.#material[id];
-
-        view.setUint32(MESH_CARD_SET_STRUCT.get("geometry").offset, this.#geometry[id], true);
-        view.setUint32(MESH_CARD_SET_STRUCT.get("material").offset, material.id, true);
-        view.setUint32(MESH_CARD_SET_STRUCT.get("page_base").offset, this.#tiles[id].offset, true);
-        view.setFloat32(MESH_CARD_SET_STRUCT.get("emissive_scale").offset, mesh_card_emissive_scale_of(material), true);
-
-        this.#ensure_records(id + 1);
-
-        this.#device.queue.writeBuffer(this.#records, id * MESH_CARD_SET_STRUCT.size, view.buffer, 0, MESH_CARD_SET_STRUCT.size);
-    }
-
-    /**
-     * Take the frame's pages off the queues into runs: at most `budget`, first captures before
-     * recaptures.
-     *
-     * @param {number} budget
-     */
-    #take(budget) {
-        this.#frame_runs = 0;
-        this.#frame_threads = 0;
-        this.#frame_left = budget;
-
-        this.#frame_raster_runs = 0;
-        this.#frame_raster_threads = 0;
-        this.#shelf_x = 0;
-        this.#shelf_y = 0;
-        this.#shelf_height = 0;
-        this.#frame_scratch_width = 0;
-        this.#frame_scratch_height = 0;
-
-        this.#head_new = this.#compact(this.#queue_new, this.#take_from(this.#queue_new, this.#head_new));
-        this.#head_re = this.#compact(this.#queue_re, this.#take_from(this.#queue_re, this.#head_re));
-
-        this.#pages_captured += budget - this.#frame_left;
-    }
-
-    /**
-     * Take pages off one queue from its head into the frame's runs, while the frame's budget lasts.
-     *
-     * @param {number[]} queue (id, ticket) pairs
-     * @param {number} head
-     * @returns {number} the queue's head after what was taken
-     */
-    #take_from(queue, head) {
-        while (this.#frame_left > 0 && head < queue.length) {
-            const id = queue[head];
-
-            if (queue[head + 1] !== this.#ticket[id] || this.#queued[id] === 0) {
-                // given back, or its layout went, since it was queued
-                head += 2;
-                continue;
-            }
-
-            const pages = this.#layout_pages.get(this.#geometry[id]);
-
-            if (this.#capture_mode === MeshCardCaptureMode.Raster) {
-                // a context is made with its bind group
-                const material = this.#frame_material_contexts.obtain(this.#material[id]);
-
-                if (material.template.surface !== null) {
-                    if (!this.#take_raster(id, pages, material)) {
-                        // the frame's scratch is full: next frame
-                        return head;
-                    }
-
-                    head += 2;
-                    continue;
-                }
-
-                // a template that cannot be drawn this way is traced
-            }
-
-            // its row as the material stands now, repacked if it has moved since
-            this.#frame_materials.obtain_material(this.#material[id]);
-
-            const first = this.#next_page[id];
-            const count = Math.min(pages - first, this.#frame_left);
-
-            if (first === 0) {
-                this.#write_record(id);
-            }
-
-            const runs = this.#frame_runs;
-
-            this.#run_scratch = grow_typed(this.#run_scratch, 4 * (runs + 1));
-            this.#run_scratch[4 * runs] = this.#frame_threads;
-            this.#run_scratch[4 * runs + 1] = id;
-            this.#run_scratch[4 * runs + 2] = first;
-            this.#run_scratch[4 * runs + 3] = 0;
-
-            this.#frame_runs = runs + 1;
-            this.#frame_threads += count * PAGE_THREADS;
-            this.#frame_left -= count;
-
-            this.#next_page[id] = first + count;
-
-            if (first + count < pages) {
-                // the budget ran out inside it: it goes on from here next frame
-                return head;
-            }
-
-            this.#next_page[id] = 0;
-            this.#queued[id] = 0;
-            head += 2;
-
-            if (this.#state[id] === SET_CAPTURING) {
-                this.#turn_resident(id);
-            }
-        }
-
-        return head;
-    }
-
-    /**
-     * Take a whole card set into the frame's raster runs, if its region fits the frame's scratch.
-     *
-     * @param {number} id
-     * @param {number} pages its layout's
-     * @param {GPUMaterialContext} material what its draw binds
-     * @returns {boolean} whether it was taken
-     */
-    #take_raster(id, pages, material) {
-        const side = this.#layout_side.get(this.#geometry[id]);
-        const corner = this.#place_region(MESH_CARD_RASTER_CELLS_X * side, MESH_CARD_RASTER_CELLS_Y * side);
-
-        if (corner === -1) {
-            return false;
-        }
-
-        this.#write_record(id);
-
-        const runs = this.#frame_raster_runs;
-
-        this.#raster_run_scratch = grow_typed(this.#raster_run_scratch, 4 * (runs + 1));
-        this.#raster_run_scratch[4 * runs] = this.#frame_raster_threads;
-        this.#raster_run_scratch[4 * runs + 1] = id;
-        this.#raster_run_scratch[4 * runs + 2] = corner;
-        this.#raster_run_scratch[4 * runs + 3] = side;
-
-        this.#frame_raster_materials[runs] = material;
-
-        this.#frame_raster_runs = runs + 1;
-        this.#frame_raster_threads += pages * PAGE_THREADS;
-        this.#frame_left -= pages;
-
-        this.#next_page[id] = 0;
-        this.#queued[id] = 0;
-
-        if (this.#state[id] === SET_CAPTURING) {
-            this.#turn_resident(id);
-        }
-
-        return true;
-    }
-
-    /**
-     * A corner for a region in the frame's scratch, shelf by shelf.
-     *
-     * @param {number} width
-     * @param {number} height
-     * @returns {number} the corner as x | y << 16, or -1 when the region must wait for the next frame
-     */
-    #place_region(width, height) {
-        if (this.#shelf_x > 0 && this.#shelf_x + width > RASTER_SCRATCH_SIDE) {
-            this.#shelf_y += this.#shelf_height;
-            this.#shelf_x = 0;
-            this.#shelf_height = 0;
-        }
-
-        const fits = this.#shelf_x + width <= RASTER_SCRATCH_SIDE && this.#shelf_y + height <= RASTER_SCRATCH_SIDE;
-
-        if (!fits && this.#frame_raster_runs > 0) {
-            return -1;
-        }
-
-        const corner = this.#shelf_x | (this.#shelf_y << 16);
-
-        this.#shelf_x += width;
-        this.#shelf_height = Math.max(this.#shelf_height, height);
-
-        this.#frame_scratch_width = Math.max(this.#frame_scratch_width, this.#shelf_x);
-        this.#frame_scratch_height = Math.max(this.#frame_scratch_height, this.#shelf_y + height);
-
-        return corner;
-    }
-
-    /**
-     * Drop a queue's taken entries once they are most of it.
-     *
-     * @param {number[]} queue
-     * @param {number} head
-     * @returns {number} the new head
-     */
-    #compact(queue, head) {
-        if (head === queue.length) {
-            queue.length = 0;
-            return 0;
-        }
-
-        if (head > 64 && head * 2 > queue.length) {
-            queue.copyWithin(0, head);
-            queue.length -= head;
-            return 0;
-        }
-
-        return head;
-    }
-
-    /**
-     * Record the frame's capture: at most `budget` pages. Records nothing when nothing waits. Card
-     * sets whose first capture this completes are resident from here, and {@link onResident} is sent
-     * for each.
-     *
-     * @param {Object} options
-     * @param {FrameGraph} options.graph
-     * @param {number} options.budget pages captured at most, `card_capture_budget`
-     * @param {number} options.arena graph handle of the arena, as the frame's bake left it
-     * @param {GPUBuffer} options.headers
-     * @param {GPUResidentMaterialContext} options.materials what the trace shades with: each traced
-     *        material is made resident, and the rows committed, before the trace is recorded
-     * @param {GPUMaterialManager} options.material_contexts what the raster draws with: each
-     *        material's template and bind group
-     * @param {Object} options.blas the geometry bindings `ray_query_blas_nearest` reads, whose
-     *        geometry and meshlet buffers the raster pulls vertices from
-     */
-    graph_capture({ graph, budget, arena, headers, materials, material_contexts, blas }) {
-        assert.defined(graph, 'graph');
-        assert.isPositiveInteger(budget, 'budget');
-        assert.lessThanOrEqual(budget, MESH_CARD_CAPTURE_BUDGET_MAX, 'budget');
-
-        if (this.#capture_mode === MeshCardCaptureMode.Raster) {
-            assert.notNull(material_contexts, 'material_contexts');
-            assert.defined(material_contexts, 'material_contexts');
-        }
-
-        this.#frame_material_contexts = material_contexts;
-        this.#frame_materials = materials;
-
-        this.#take(budget);
-
-        this.#frame_material_contexts = null;
-        this.#frame_materials = null;
-
-        const completed = this.#completed;
-
-        if (this.#frame_runs > 0 || this.#frame_raster_runs > 0) {
-            this.#ensure_device();
-
-            let albedo = graph_import_texture(graph, this.#atlas.texture_at(0), "mesh_card_albedo");
-            let emissive = graph_import_texture(graph, this.#atlas.texture_at(1), "mesh_card_emissive");
-
-            if (this.#frame_runs > 0) {
-                // what the runs' materials made resident, written before the trace reads it
-                materials.commit();
-
-                this.#ensure_runs(this.#frame_runs);
-
-                this.#device.queue.writeBuffer(this.#runs, 0, this.#run_scratch, 0, 4 * this.#frame_runs);
-
-                const data = this.#pass_data;
-                const pass = graph.add("Mesh Card Capture", data, this.#execute);
-
-                pass.read(arena);
-
-                data.arena = arena;
-                albedo = data.albedo = pass.write(albedo);
-                emissive = data.emissive = pass.write(emissive);
-
-                pass.make_side_effect();
-
-                const b = this.#bindings;
-
-                b.mesh_sdf_headers = headers;
-                b.materials = materials.buffer_materials;
-                b.textures = materials.textureView;
-                b.blas_lookup = blas.blas_lookup;
-                b.blas_data = blas.blas_data;
-                b.geometries = blas.geometries;
-                b.meshlet_metadata = blas.meshlet_metadata;
-                b.meshlet_data = blas.meshlet_data;
-            }
-
-            if (this.#frame_raster_runs > 0) {
-                const runs = this.#frame_raster_runs;
-
-                this.#ensure_raster_runs(runs);
-                this.#ensure_raster_scratch(this.#frame_scratch_width, this.#frame_scratch_height);
-
-                this.#device.queue.writeBuffer(this.#raster_runs, 0, this.#raster_run_scratch, 0, 4 * runs);
-
-                const data = this.#raster_pass_data;
-                const pass = graph.add("Mesh Card Capture / Raster", data, this.#execute_raster);
-
-                pass.read(arena);
-
-                data.arena = arena;
-                data.albedo = pass.write(albedo);
-                data.emissive = pass.write(emissive);
-
-                pass.make_side_effect();
-
-                const args = this.#raster_args_bindings;
-
-                args.mesh_sdf_headers = headers;
-                args.geometries = blas.geometries;
-
-                const scatter = this.#raster_scatter_bindings;
-
-                scatter.mesh_sdf_headers = headers;
-                scatter.mesh_card_raster_albedo = this.#raster_views[0];
-                scatter.mesh_card_raster_emissive = this.#raster_views[1];
-
-                this.#raster_group_buffers.mesh_sdf_headers = headers;
-                this.#raster_group_buffers.geometries = blas.geometries;
-                this.#raster_group_buffers.meshlet_metadata = blas.meshlet_metadata;
-                this.#raster_group_buffers.meshlet_data = blas.meshlet_data;
-            }
-        }
-
-        for (let i = 0; i < completed.length; i++) {
-            this.onResident.send1(completed[i]);
-        }
-
-        completed.length = 0;
-    }
-
-    /**
-     * {@link #execute_capture}, bound once.
-     * @type {function(Object, Object, Object): void}
-     */
-    #execute = (data, resources, context) => this.#execute_capture(data, resources, context);
-
-    #execute_capture(data, resources, context) {
-        const b = this.#bindings;
-        const groups = Math.ceil(this.#frame_threads / MESH_SDF_BAKE_WORKGROUP_SIZE);
-        const groups_x = Math.min(groups, WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION);
-        const settings = this.#settings;
-
-        settings.run_count = this.#frame_runs;
-        settings.thread_count = this.#frame_threads;
-        settings.groups_x = groups_x;
-
-        b.settings = settings;
-        b.mesh_sdf_indirection = resources.get(data.arena);
-        b.mesh_card_sets = this.#records;
-        b.mesh_card_runs = this.#runs;
-        b.mesh_card_albedo = resources.get(data.albedo).obtainView();
-        b.mesh_card_emissive = resources.get(data.emissive).obtainView();
-
-        shader_mesh_cards_capture.dispatch({
-            encoder: context.encoder,
-            group_count_x: groups_x,
-            group_count_y: Math.ceil(groups / groups_x),
-            bindings: b,
-        });
-    }
-
-    /**
-     * {@link #execute_raster_capture}, bound once.
-     * @type {function(Object, Object, Object): void}
-     */
-    #execute_raster = (data, resources, context) => this.#execute_raster_capture(data, resources, context);
-
-    /**
-     * A draw a run, every run's cards into the scratch, then every run's pages into the atlas.
-     */
-    #execute_raster_capture(data, resources, context) {
-        const encoder = context.encoder;
-        const graphics = context.graphics;
-        const runs = this.#frame_raster_runs;
-        const arena = resources.get(data.arena);
-
-        const args_settings = this.#raster_args_settings;
-        const args = this.#raster_args_bindings;
-
-        args_settings.run_count = runs;
-
-        args.settings = args_settings;
-        args.mesh_sdf_indirection = arena;
-        args.mesh_card_sets = this.#records;
-        args.mesh_card_raster_runs = this.#raster_runs;
-        args.mesh_card_raster_draws = this.#raster_draws;
-
-        shader_mesh_cards_raster_args.dispatch({
-            encoder,
-            group_count_x: Math.ceil(runs / MESH_CARDS_RASTER_ARGS_WORKGROUP_SIZE),
-            bindings: args,
-        });
-
-        const buffers = this.#raster_group_buffers;
-
-        const group = graphics.bind_groups.obtain(BindGroupDescriptor.from(
-            MESH_CARDS_RASTER_LAYOUT,
-            [
-                { buffer: buffers.mesh_sdf_headers },
-                { buffer: arena },
-                { buffer: this.#records },
-                { buffer: this.#raster_runs },
-                { buffer: buffers.geometries },
-                { buffer: buffers.meshlet_metadata },
-                { buffer: buffers.meshlet_data },
-            ]
-        ));
-
-        const immediate = this.#raster_immediate;
-
-        this.#raster_immediate_f32[1] = this.#raster_width;
-        this.#raster_immediate_f32[2] = this.#raster_height;
-
-        const pass = encoder.beginRenderPass(this.#raster_pass_descriptor);
-
-        pass.setBindGroup(1, group);
-
-        let bound_template = null;
-
-        for (let run = 0; run < runs; run++) {
-            const material = this.#frame_raster_materials[run];
-
-            if (!material.is_built) {
-                // let go since it was taken: its texels stay empty, every lookup missing
-                continue;
-            }
-
-            const template = material.template;
-
-            if (template !== bound_template) {
-                pass.setPipeline(mesh_cards_raster_pass_descriptor.obtain_pipeline(graphics.render_pipelines, template, "none"));
-
-                bound_template = template;
-            }
-
-            // the same group 0 the G-buffer pass binds
-            pass.setBindGroup(0, material.material_binding);
-
-            immediate[0] = run;
-
-            pass.setImmediates(0, immediate, 0, immediate.length);
-            pass.drawIndirect(this.#raster_draws, run * STRUCT_UNINDEXED_DRAW_COMMAND.size);
-        }
-
-        pass.end();
-
-        const groups = Math.ceil(this.#frame_raster_threads / MESH_SDF_BAKE_WORKGROUP_SIZE);
-        const groups_x = Math.min(groups, WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION);
-
-        const scatter_settings = this.#raster_scatter_settings;
-        const scatter = this.#raster_scatter_bindings;
-
-        scatter_settings.run_count = runs;
-        scatter_settings.thread_count = this.#frame_raster_threads;
-        scatter_settings.groups_x = groups_x;
-
-        scatter.settings = scatter_settings;
-        scatter.mesh_sdf_indirection = arena;
-        scatter.mesh_card_sets = this.#records;
-        scatter.mesh_card_raster_runs = this.#raster_runs;
-        scatter.mesh_card_albedo = resources.get(data.albedo).obtainView();
-        scatter.mesh_card_emissive = resources.get(data.emissive).obtainView();
-
-        shader_mesh_cards_raster_scatter.dispatch({
-            encoder,
-            group_count_x: groups_x,
-            group_count_y: Math.ceil(groups / groups_x),
-            bindings: scatter,
-        });
-    }
-
-    #ensure_id(id) {
-        const length = id + 1;
-
-        this.#state = grow_typed(this.#state, length);
-        this.#geometry = grow_typed(this.#geometry, length);
-        this.#ticket = grow_typed(this.#ticket, length);
-        this.#next_page = grow_typed(this.#next_page, length);
-        this.#queued = grow_typed(this.#queued, length);
-    }
-
-    #ensure_device() {
-        if (this.#atlas !== null) {
-            return;
-        }
-
-        this.#atlas = new GPUTileAtlas2D({
-            device: this.#device,
-            formats: ["rgba8unorm", "rgba8unorm"],
-            tile_size: [MESH_CARD_PAGE_TEXELS, MESH_CARD_PAGE_TEXELS],
-            // stored into by the capture, read by the hits
-            usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.STORAGE_BINDING,
-            label: "GPUMeshCardSets/atlas",
-        });
-
-        this.#tile_allocator = new OffsetAllocator(this.#atlas.capacity);
-
-        this.#ensure_records(64);
-    }
-
-    /**
-     * @param {number} count
-     */
-    #ensure_records(count) {
-        if (count <= this.#record_capacity) {
-            return;
-        }
-
-        let capacity = Math.max(64, this.#record_capacity);
-
-        while (capacity < count) {
-            capacity *= 2;
-        }
-
-        const size = MESH_CARD_SET_STRUCT.size * capacity;
-        const buffer = this.#create_buffer("records", size, GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC);
-
-        if (this.#records !== null) {
-            const encoder = this.#device.createCommandEncoder({ label: "GPUMeshCardSets/records growth" });
-
-            encoder.copyBufferToBuffer(this.#records, 0, buffer, 0, this.#records.size);
-            this.#device.queue.submit([encoder.finish()]);
-
-            this.#records.destroy();
-        }
-
-        this.#records = buffer;
-        this.#record_capacity = capacity;
-    }
-
-    /**
-     * @param {number} runs
-     */
-    #ensure_runs(runs) {
-        if (runs <= this.#run_capacity) {
-            return;
-        }
-
-        let capacity = Math.max(64, this.#run_capacity);
-
-        while (capacity < runs) {
-            capacity *= 2;
-        }
-
-        this.#runs?.destroy();
-        this.#runs = this.#create_buffer("runs", 16 * capacity, GPUBufferUsage.COPY_DST);
-        this.#run_capacity = capacity;
-    }
-
-    /**
-     * @param {number} runs
-     */
-    #ensure_raster_runs(runs) {
-        if (runs <= this.#raster_run_capacity) {
-            return;
-        }
-
-        let capacity = Math.max(64, this.#raster_run_capacity);
-
-        while (capacity < runs) {
-            capacity *= 2;
-        }
-
-        this.#raster_runs?.destroy();
-        this.#raster_draws?.destroy();
-
-        this.#raster_runs = this.#create_buffer("raster runs", 16 * capacity, GPUBufferUsage.COPY_DST);
-        this.#raster_draws = this.#create_buffer("raster draws", STRUCT_UNINDEXED_DRAW_COMMAND.size * capacity, GPUBufferUsage.INDIRECT);
-        this.#raster_run_capacity = capacity;
-    }
-
-    /**
-     * The scratch the cards are drawn into, at least `width` × `height`. It only grows.
-     *
-     * @param {number} width
-     * @param {number} height
-     */
-    #ensure_raster_scratch(width, height) {
-        if (width <= this.#raster_width && height <= this.#raster_height) {
-            return;
-        }
-
-        const step = RASTER_SCRATCH_STEP;
-
-        width = Math.max(this.#raster_width, Math.ceil(width / step) * step);
-        height = Math.max(this.#raster_height, Math.ceil(height / step) * step);
-
-        const formats = [...MESH_CARD_RASTER_TARGET_FORMATS, MESH_CARD_RASTER_DEPTH_FORMAT];
-
-        for (let i = 0; i < formats.length; i++) {
-            // a frame already submitted may still be reading it; destroy waits for that
-            this.#raster_targets[i]?.destroy();
-
-            const color = i < MESH_CARD_RASTER_TARGET_FORMATS.length;
-
-            this.#raster_targets[i] = this.#device.createTexture({
-                label: `GPUMeshCardSets/raster scratch ${i}`,
-                size: [width, height],
-                format: formats[i],
-                usage: color
-                    ? GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING
-                    : GPUTextureUsage.RENDER_ATTACHMENT,
-            });
-
-            this.#raster_views[i] = this.#raster_targets[i].createView();
-        }
-
-        const descriptor = this.#raster_pass_descriptor;
-
-        for (let i = 0; i < descriptor.colorAttachments.length; i++) {
-            descriptor.colorAttachments[i].view = this.#raster_views[i];
-        }
-
-        descriptor.depthStencilAttachment.view = this.#raster_views[formats.length - 1];
-
-        this.#raster_width = width;
-        this.#raster_height = height;
-    }
-
-    /**
-     * @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: `GPUMeshCardSets/${name}`,
-            size,
-            usage: GPUBufferUsage.STORAGE | usage,
-        }));
-    }
-
-    /**
-     * @returns {number} bytes
-     */
-    get gpu_memory_usage() {
-        let bytes = 0;
-
-        if (this.#records !== null) {
-            bytes += this.#records.size;
-        }
-
-        if (this.#runs !== null) {
-            bytes += this.#runs.size;
-        }
-
-        if (this.#atlas !== null) {
-            bytes += this.#atlas.gpu_memory_usage;
-        }
-
-        if (this.#raster_runs !== null) {
-            bytes += this.#raster_runs.size + this.#raster_draws.size;
-        }
-
-        // two rgba8 targets and a depth32float, 4 bytes a texel each
-        bytes += this.#raster_width * this.#raster_height * 4 * (MESH_CARD_RASTER_TARGET_FORMATS.length + 1);
-
-        return bytes;
-    }
-
-    destroy() {
-        this.#records?.destroy();
-        this.#runs?.destroy();
-        this.#atlas?.destroy();
-        this.#raster_runs?.destroy();
-        this.#raster_draws?.destroy();
-
-        for (let i = 0; i < this.#raster_targets.length; i++) {
-            this.#raster_targets[i].destroy();
-        }
-
-        this.#records = null;
-        this.#runs = null;
-        this.#atlas = null;
-        this.#raster_runs = null;
-        this.#raster_draws = null;
-        this.#raster_targets.length = 0;
-        this.#raster_views.length = 0;
-        this.#raster_width = 0;
-        this.#raster_height = 0;
-    }
-}