@woosh/meep-engine 3.57.0 → 3.58.0

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

@@ -0,0 +1,884 @@
+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 { 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 { shader_mesh_cards_capture } from "./shader_mesh_cards_capture.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("../../../../../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;
+
+/**
+ * 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 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.
+ */
+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();
+
+    // ---- 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();
+
+    /**
+     * The card sets of each geometry, by geometry id.
+     * @type {Map<number, number[]>}
+     */
+    #sets_of_geometry = new Map();
+
+    // ---- 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 };
+
+    /** 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;
+    }
+
+    /**
+     * 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 whose layout it captures: the source's, for a skinned row
+     * @param {ShadeMaterial} material
+     * @returns {number} card set id
+     */
+    acquire(geometry, material) {
+        assert.isNonNegativeInteger(geometry, 'geometry');
+        assert.defined(material, 'material');
+
+        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
+     */
+    set_layout(geometry, pages) {
+        assert.isNonNegativeInteger(pages, 'pages');
+
+        this.#layout_pages.set(geometry, pages);
+
+        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;
+        }
+
+        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);
+            }
+        }
+    }
+
+    /**
+     * 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.#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]);
+            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;
+    }
+
+    /**
+     * 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
+     * @param {Object} options.blas the geometry bindings `ray_query_blas_nearest` reads
+     */
+    graph_capture({ graph, budget, arena, headers, materials, blas }) {
+        assert.defined(graph, 'graph');
+        assert.isPositiveInteger(budget, 'budget');
+        assert.lessThanOrEqual(budget, MESH_CARD_CAPTURE_BUDGET_MAX, 'budget');
+
+        this.#take(budget);
+
+        const completed = this.#completed;
+
+        if (this.#frame_runs > 0) {
+            this.#ensure_device();
+            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;
+            data.albedo = pass.write(graph_import_texture(graph, this.#atlas.texture_at(0), "mesh_card_albedo"));
+            data.emissive = pass.write(graph_import_texture(graph, this.#atlas.texture_at(1), "mesh_card_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;
+        }
+
+        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,
+        });
+    }
+
+    #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 {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;
+        }
+
+        return bytes;
+    }
+
+    destroy() {
+        this.#records?.destroy();
+        this.#runs?.destroy();
+        this.#atlas?.destroy();
+
+        this.#records = null;
+        this.#runs = null;
+        this.#atlas = null;
+    }
+}