@woosh/meep-engine 3.61.2 → 3.61.3

package/src/shade/renderer/geometry/sdf/surface/GPUMeshSurfaceCaches.js

@@ -0,0 +1,1819 @@
+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 { 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 { graph_import_buffer } from "../../../shader/graph/graph_import_buffer.js";
+import { MESH_SDF_BAKE_WORKGROUP_SIZE } from "../bake/MESH_SDF_BAKE.js";
+import { MESH_SDF_BRICK_TEXEL_COUNT } from "../MESH_SDF.js";
+import { MESH_SDF_SAMPLER } from "../MESH_SDF_RESOURCES.js";
+import { mesh_surface_channels, MeshSurfaceChannels } from "./mesh_surface_channels.js";
+import {
+    MESH_SURFACE_COMMAND_WORDS,
+    MESH_SURFACE_COUNTER_WORDS,
+    MESH_SURFACE_STAGING_WORDS,
+    MESH_SURFACE_SURVEY_RESULT_WORDS,
+    MESH_SURFACE_TEXEL_STRUCT
+} from "./MESH_SURFACE_BAKE.js";
+import {
+    MESH_SURFACE_BRICK_BLOCKS,
+    MESH_SURFACE_PLANE_BLOCK_WORDS,
+    MESH_SURFACE_PRESENCE_BLOCK_WORDS
+} from "./MESH_SURFACE_BLOCK.js";
+import { MESH_SURFACE_STRUCT } from "./MESH_SURFACE_STRUCT.js";
+import { shader_mesh_surface_command } from "./shader_mesh_surface_command.js";
+import { shader_mesh_surface_encode } from "./shader_mesh_surface_encode.js";
+import { shader_mesh_surface_list } from "./shader_mesh_surface_list.js";
+import { shader_mesh_surface_number, shader_mesh_surface_survey } from "./shader_mesh_surface_survey.js";
+import { shader_mesh_surface_trace } from "./shader_mesh_surface_trace.js";
+import {
+    SURFACE_MATERIAL_ALBEDO_PLANE,
+    SURFACE_MATERIAL_EMISSIVE_PLANE,
+    SURFACE_MATERIAL_METAL_ROUGH_PLANE
+} from "./SURFACE_MATERIAL.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
+ * @typedef {import("../bundle/ModelCacheBundle.js").ModelCacheBundleCache} ModelCacheBundleCache
+ */
+
+/** The id is free. */
+const CACHE_NONE = 0;
+/** Its geometry's field is not resident, or not surveyed yet: nothing to lay its blocks out by. */
+const CACHE_WAITING = 1;
+/** Its first bake is queued or part done; readers find no cache. */
+const CACHE_BAKING = 2;
+/** Baked; it may be queued to bake again, and reads the last bake until that is done. */
+const CACHE_RESIDENT = 3;
+
+/**
+ * The planes, in `SURFACE_MATERIAL.js`'s order, and the record's field of each one's blocks.
+ */
+const PLANES = [SURFACE_MATERIAL_ALBEDO_PLANE, SURFACE_MATERIAL_METAL_ROUGH_PLANE, SURFACE_MATERIAL_EMISSIVE_PLANE];
+const PLANE_BLOCK_FIELDS = ["albedo_blocks", "metal_rough_blocks", "emissive_blocks"];
+
+/**
+ * Words the caches' storage starts with: it grows to what its allocations take.
+ * @type {number}
+ */
+const INITIAL_DATA_WORDS = 64 * 1024;
+
+/**
+ * A capacity of at least `count`, doubled from `capacity`, 64 at least.
+ *
+ * @param {number} count
+ * @param {number} capacity
+ * @returns {number}
+ */
+function doubled_capacity(count, capacity) {
+    let grown = Math.max(64, capacity);
+
+    while (grown < count) {
+        grown *= 2;
+    }
+
+    return grown;
+}
+
+/**
+ * @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(64, array.length);
+
+    while (size < length) {
+        size *= 2;
+    }
+
+    const grown = new array.constructor(size);
+
+    grown.set(array);
+
+    return grown;
+}
+
+/**
+ * A run's first `count` words, copied out of the storage read back whole; none for no run.
+ *
+ * @param {Allocation|null|undefined} run
+ * @param {number} count
+ * @param {Uint32Array} words
+ * @returns {Uint32Array}
+ */
+function run_words(run, count, words) {
+    return run === null || run === undefined ? new Uint32Array(0) : words.slice(run.offset, run.offset + count);
+}
+
+/**
+ * Model Surface Caches: one (geometry, material) pair's surface material (`SURFACE_MATERIAL.js`) on its
+ * geometry's field, by cache id, the storage of which {@link GPUGeometrySDFManager} keeps beside the
+ * fields.
+ *
+ * - **Blocks.** A field's bricks are surveyed once (`MESH_SURFACE_BAKE.js`): a brick keeps each of its
+ *   eight 4³ blocks (`MESH_SURFACE_BLOCK.js`) some texel of which can hold surface, numbered in the
+ *   geometry's block table, a word a brick, and the count read back. Every cache of the geometry keeps
+ *   its blocks by those numbers.
+ * - **What a cache keeps** follows its material and its geometry (`mesh_surface_channels`): each plane
+ *   that varies over the surface keeps its blocks, coded, and each other plane only its code in the
+ *   record, the value every texel takes. A cache that keeps any plane keeps a block of presence for each
+ *   block: which texels a bake found surface under. A cache that keeps no plane is never baked.
+ * - **Storage** is one buffer of words, `mesh_surface_data`, for the tables and for each cache's run of
+ *   blocks in its presence and each plane it keeps, each run its own allocation. The record
+ *   (`MESH_SURFACE_STRUCT`) is written when the runs are given.
+ *
+ * **Lifetime.** {@link acquire} makes a cache for a pair and {@link release} gives it back; the caller
+ * keeps one per pair. A cache of an aliased geometry ({@link alias}) is its source's, baked from the
+ * source's triangles. A cache waits until its geometry's field is resident ({@link set_layout}) and,
+ * when it keeps a plane, surveyed ({@link set_blocks}); it is then baked, and turns resident on the frame
+ * its last brick is recorded: the bake's writes come before any later pass reads it. Every bake recorded
+ * in full sends {@link onBaked}, the first and each one after. A field that goes ({@link drop_layout})
+ * withdraws its caches ({@link onWithdrawn}) back to waiting.
+ *
+ * **A frame** ({@link graph_bake}) takes at most `budget` bricks: surveys first, then first bakes in the
+ * order they were asked for, then bakes again in the order queued. A bake is a thread a texel of each
+ * brick, then a workgroup a texel that holds surface, then a workgroup a block. A survey's or a bake's
+ * bricks may span frames. {@link recapture} takes a cache's material as it is now: a resident cache
+ * keeping the same planes is queued again and reads its last bake until the new one is done, a cache
+ * whose bake is under way starts it again, and one keeping other planes than before is withdrawn and
+ * laid out anew. The rays read the geometry's BLAS and the material's resident row: what reads a cache
+ * needs neither.
+ */
+export class GPUMeshSurfaceCaches {
+
+    /**
+     * @type {GPUDevice}
+     */
+    #device;
+
+    /**
+     * Sent with a cache id each time a bake of it is recorded in full, its first and each one after:
+     * what was taken from its last one is to be taken again.
+     * @type {Signal<number>}
+     */
+    onBaked = new Signal();
+
+    /**
+     * Sent with a resident cache's id when what it holds goes: its field went, or its material now
+     * varies in other planes. It is baked again.
+     * @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 cache id ----
+
+    #state = new Uint8Array(64);
+    #geometry = new Uint32Array(64);
+    /**
+     * Bumped whenever the id's queue entries go stale: given out, given back, its field gone.
+     */
+    #ticket = new Uint32Array(64);
+    /** Bricks of the bake under way taken so far. */
+    #next_brick = new Uint32Array(64);
+    /** Whether a queue holds a live entry of the id. */
+    #queued = new Uint8Array(64);
+
+    /** Bit `1 << plane` for each plane the cache keeps, as its runs were given. */
+    #texels = new Uint8Array(64);
+    /** Each plane's code, which a plane it keeps no blocks of takes everywhere, by plane. */
+    #codes = [new Uint32Array(64), new Uint32Array(64), new Uint32Array(64)];
+
+    /**
+     * @type {(ShadeMaterial|undefined)[]}
+     */
+    #material = [];
+
+    /**
+     * Each cache's presence run.
+     * @type {(Allocation|null)[]}
+     */
+    #presence_runs = [];
+
+    /**
+     * Each cache's run of each plane it keeps, by plane.
+     * @type {(Allocation|null)[][]}
+     */
+    #plane_runs = [[], [], []];
+
+    // ---- per geometry id ----
+
+    /**
+     * Bricks each resident field stored, by geometry id.
+     * @type {Map<number, number>}
+     */
+    #stored = new Map();
+
+    /**
+     * Whether each resident field's geometry has vertices of a color other than white, by geometry id.
+     * @type {Map<number, boolean>}
+     */
+    #colored = new Map();
+
+    /**
+     * Blocks each surveyed field's bricks keep, by geometry id.
+     * @type {Map<number, number>}
+     */
+    #blocks = new Map();
+
+    /**
+     * Each resident field's block table, a word a stored brick, by geometry id.
+     * @type {Map<number, Allocation>}
+     */
+    #tables = new Map();
+
+    /**
+     * The ticket each field's survey under way was asked under, by geometry id.
+     * @type {Map<number, number>}
+     */
+    #survey_tickets = new Map();
+
+    /**
+     * Bricks of each survey under way taken so far, by geometry id.
+     * @type {Map<number, number>}
+     */
+    #survey_next = new Map();
+
+    #survey_count = 0;
+
+    /**
+     * The caches of each geometry, by geometry id.
+     * @type {Map<number, number[]>}
+     */
+    #caches_of_geometry = new Map();
+
+    /**
+     * The bundle's caches each field taken from a bundle offers its geometry's caches, by geometry id,
+     * kept while that field is the geometry's ({@link adopt_layout}).
+     * @type {Map<number, {material: ShadeMaterial, cache: ModelCacheBundleCache}[]>}
+     */
+    #provisions = new Map();
+
+    // ---- the queues: (id, ticket) pairs, from a head ----
+
+    #queue_survey = [];
+    #head_survey = 0;
+    #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_SURFACE_STRUCT.size));
+
+    /** @type {GPUBuffer|null} */
+    #data = null;
+    /** @type {OffsetAllocator|null} */
+    #data_allocator = null;
+
+    /** @type {GPUBuffer|null} */
+    #runs = null;
+    #run_capacity = 0;
+    #run_scratch = new Uint32Array(4 * 64);
+
+    /** @type {GPUBuffer|null} */
+    #survey_runs = null;
+    #survey_run_capacity = 0;
+    #survey_run_scratch = new Uint32Array(4 * 64);
+
+    /** @type {GPUBuffer|null} */
+    #number_runs = null;
+    #number_run_capacity = 0;
+    #number_run_scratch = new Uint32Array(4 * 64);
+
+    /** @type {GPUBuffer|null} */
+    #survey_results = null;
+    #survey_result_capacity = 0;
+
+    /** @type {GPUBuffer|null} */
+    #texel_list = null;
+    /** @type {GPUBuffer|null} */
+    #staging = null;
+    #texel_capacity = 0;
+
+    /** @type {GPUBuffer|null} */
+    #counter = null;
+    /** @type {GPUBuffer|null} */
+    #command = null;
+
+    #frame_runs = 0;
+    #frame_threads = 0;
+    #frame_survey_runs = 0;
+    #frame_survey_threads = 0;
+    #frame_number_runs = 0;
+    #frame_number_threads = 0;
+    /** The tables a frame's surveys start with, cleared before them: (word, words) pairs. */
+    #frame_clears = [];
+    /**
+     * The surveys a frame completes: (geometry, ticket) pairs, in their results' order; null for none.
+     * @type {number[]|null}
+     */
+    #frame_completed_surveys = null;
+    /** Bricks of the frame's budget not yet taken. */
+    #frame_left = 0;
+
+    /**
+     * What a frame's bake shades with: set by {@link graph_bake}. Only what is baked is made resident,
+     * each run's material as its run is taken.
+     * @type {GPUResidentMaterialContext|null}
+     */
+    #frame_materials = null;
+
+    #channels = new MeshSurfaceChannels();
+
+    #list_settings = { run_count: 0, thread_count: 0, groups_x: 0, capacity: 0 };
+    #command_settings = { capacity: 0 };
+    #encode_settings = { run_count: 0, brick_count: 0, groups_x: 0 };
+    #survey_settings = { run_count: 0, thread_count: 0, groups_x: 0 };
+    #number_settings = { run_count: 0, thread_count: 0, groups_x: 0 };
+    #bindings = {};
+    #pass_data = { arena: -1 };
+    #survey_pass_data = { arena: -1, results: -1 };
+
+    /** Caches whose bake the frame completes, sent once it is recorded. */
+    #completed = [];
+
+    #count = 0;
+    #resident_count = 0;
+    #bricks_baked = 0;
+    #destroyed = false;
+
+    /**
+     * @param {GPUDevice} device
+     */
+    constructor(device) {
+        assert.defined(device, 'device');
+
+        this.#device = device;
+    }
+
+    /**
+     * Caches given out: acquired and not yet released.
+     * @returns {number}
+     */
+    get count() {
+        return this.#count;
+    }
+
+    /**
+     * Caches readers may use.
+     * @returns {number}
+     */
+    get resident_count() {
+        return this.#resident_count;
+    }
+
+    /**
+     * Bricks baked since this was made, every bake's.
+     * @returns {number}
+     */
+    get bricks_baked() {
+        return this.#bricks_baked;
+    }
+
+    /**
+     * Whether a frame has anything to do: bricks to survey or bake, or caches turned resident with
+     * nothing to bake, still to be announced.
+     * @returns {boolean}
+     */
+    get has_pending_bake() {
+        return this.#head_survey < this.#queue_survey.length
+            || this.#head_new < this.#queue_new.length
+            || this.#head_re < this.#queue_re.length
+            || this.#completed.length > 0;
+    }
+
+    /**
+     * Whether readers may use the cache: baked at least once, and its field still there.
+     *
+     * @param {number} id
+     * @returns {boolean}
+     */
+    is_resident(id) {
+        return this.#state[id] === CACHE_RESIDENT;
+    }
+
+    /**
+     * The cache's geometry id: the source's, for an aliased geometry.
+     *
+     * @param {number} id
+     * @returns {number}
+     */
+    geometry_of(id) {
+        return this.#geometry[id];
+    }
+
+    /**
+     * The material the cache was acquired for: what a bundle exported with it names it by, to offer it
+     * back (`GPUGeometrySDFManager.upload_bundle`).
+     *
+     * @param {number} id
+     * @returns {ShadeMaterial}
+     */
+    material_of(id) {
+        return this.#material[id];
+    }
+
+    /**
+     * The blocks a surveyed field's bricks keep, or undefined before its survey is read back.
+     *
+     * @param {number} geometry
+     * @returns {number|undefined}
+     */
+    blocks_of(geometry) {
+        return this.#blocks.get(geometry);
+    }
+
+    /**
+     * Every cache's record, by id. Replaced when it grows; take it each frame.
+     * @returns {GPUBuffer}
+     */
+    get records() {
+        this.#ensure_device();
+
+        return this.#records;
+    }
+
+    /**
+     * The caches' words: the block tables and the caches' blocks. Replaced when it grows; take it each
+     * frame.
+     * @returns {GPUBuffer}
+     */
+    get data() {
+        this.#ensure_device();
+
+        return this.#data;
+    }
+
+    /**
+     * Put what the caches' readers (`chunk_mesh_surface_sample`) take into their bindings, under the
+     * names they take. The records and the words are replaced as they grow: take them each frame.
+     *
+     * @param {Object} bindings
+     * @returns {Object} bindings
+     */
+    write_bindings(bindings) {
+        this.#ensure_device();
+
+        bindings.mesh_surface_records = this.#records;
+        bindings.mesh_surface_data = this.#data;
+
+        return bindings;
+    }
+
+    /**
+     * A cache for a pair. The caller keeps one per pair.
+     *
+     * @param {number} geometry the geometry id the pair draws; an aliased one's cache is its source's ({@link alias})
+     * @param {ShadeMaterial} material
+     * @returns {number} cache 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.#count++;
+
+        this.#state[id] = CACHE_WAITING;
+        this.#geometry[id] = geometry;
+        this.#material[id] = material;
+        this.#ticket[id]++;
+        this.#next_brick[id] = 0;
+        this.#queued[id] = 0;
+
+        let caches = this.#caches_of_geometry.get(geometry);
+
+        if (caches === undefined) {
+            caches = [];
+            this.#caches_of_geometry.set(geometry, caches);
+        }
+
+        caches.push(id);
+
+        if (this.#stored.has(geometry)) {
+            this.#start(id);
+        }
+
+        return id;
+    }
+
+    /**
+     * @param {number} id
+     */
+    release(id) {
+        assert.notEqual(this.#state[id] ?? CACHE_NONE, CACHE_NONE, `surface cache ${id} is not given out`);
+
+        if (this.#state[id] === CACHE_RESIDENT) {
+            this.#resident_count--;
+        }
+
+        this.#free_runs(id);
+        this.#count--;
+
+        this.#state[id] = CACHE_NONE;
+        this.#ticket[id]++;
+        this.#queued[id] = 0;
+        this.#material[id] = undefined;
+
+        const caches = this.#caches_of_geometry.get(this.#geometry[id]);
+        const at = caches.indexOf(id);
+
+        caches[at] = caches[caches.length - 1];
+        caches.pop();
+
+        if (caches.length === 0) {
+            this.#caches_of_geometry.delete(this.#geometry[id]);
+        }
+
+        this.#ids.release(id);
+    }
+
+    /**
+     * The cache's material has changed (its version moved): take it as it is now. A cache that keeps the
+     * same planes as before is baked again, and a resident one reads its last bake until the new one is
+     * done; one that keeps none has its record's codes rewritten and is announced at once. A cache that
+     * keeps other planes than before is withdrawn and laid out anew.
+     *
+     * @param {number} id
+     */
+    recapture(id) {
+        const state = this.#state[id];
+
+        assert.notEqual(state ?? CACHE_NONE, CACHE_NONE, `surface cache ${id} is not given out`);
+
+        if (state === CACHE_WAITING) {
+            // it takes the material as it is when it is laid out
+            return;
+        }
+
+        const channels = this.#channels_of(id);
+
+        if (channels.texels !== this.#texels[id]) {
+            if (state === CACHE_RESIDENT) {
+                this.#resident_count--;
+                this.onWithdrawn.send1(id);
+            }
+
+            this.#free_runs(id);
+
+            this.#state[id] = CACHE_WAITING;
+            this.#ticket[id]++;
+            this.#queued[id] = 0;
+            this.#next_brick[id] = 0;
+
+            this.#start(id);
+
+            return;
+        }
+
+        this.#keep_codes(id, channels);
+
+        if (!this.#bakes(id)) {
+            // nothing to bake: its codes are all it holds
+            this.#write_record(id, 0);
+            this.#complete(id);
+
+            return;
+        }
+
+        // from its first brick, whether queued or not
+        this.#next_brick[id] = 0;
+
+        if (this.#queued[id] === 0) {
+            this.#queued[id] = 1;
+            this.#queue_re.push(id, this.#ticket[id]);
+        }
+    }
+
+    /**
+     * A geometry's field is resident, having stored `stored` bricks: its caches that keep no plane are
+     * laid out at once, and the first that keeps one has its bricks queued to be surveyed.
+     *
+     * @param {number} geometry
+     * @param {number} stored
+     * @param {boolean} colored whether the geometry has vertices of a color other than white, which the
+     *        diffuse albedo varies with (`meshlet_batch_colored`)
+     */
+    set_layout(geometry, stored, colored) {
+        assert.isNonNegativeInteger(stored, 'stored');
+        assert.isBoolean(colored, 'colored');
+
+        this.#ensure_device();
+
+        if (this.#stored.has(geometry)) {
+            // laid out anew without going: what it had goes first
+            this.drop_layout(geometry);
+        }
+
+        this.#stored.set(geometry, stored);
+        this.#colored.set(geometry, colored);
+
+        if (stored === 0) {
+            // nothing to survey: it keeps no block
+            this.#blocks.set(geometry, 0);
+        }
+
+        this.#start_waiting(geometry);
+    }
+
+    /**
+     * A geometry's field is resident, taken from a bundle (`ModelCacheBundle`) with the survey its
+     * caches were laid out by: `blocks` blocks numbered in `table`, a word a stored brick, or no table
+     * when no cache of it kept a plane, which leaves a cache that keeps one to have the field surveyed.
+     * Each of `provisions` offers a cache of the bundle to the geometry's cache of its material, for as
+     * long as this field is the geometry's: a cache whose material makes it keep the planes the bundle's
+     * did, with the same codes, takes the bundle's blocks and is resident without a bake; any other is
+     * baked as `set_layout` would have it.
+     *
+     * @param {number} geometry
+     * @param {number} stored
+     * @param {boolean} colored whether the geometry has vertices of a color other than white
+     * @param {number} blocks
+     * @param {Uint32Array} table `stored` words, or none
+     * @param {{material: ShadeMaterial, cache: ModelCacheBundleCache}[]} provisions
+     */
+    adopt_layout(geometry, stored, colored, blocks, table, provisions) {
+        assert.isNonNegativeInteger(stored, 'stored');
+        assert.isBoolean(colored, 'colored');
+        assert.isNonNegativeInteger(blocks, 'blocks');
+        assert.ok(table.length === 0 || table.length === stored, 'table: a word a stored brick, or none');
+
+        this.#ensure_device();
+
+        if (this.#stored.has(geometry)) {
+            this.drop_layout(geometry);
+        }
+
+        this.#stored.set(geometry, stored);
+        this.#colored.set(geometry, colored);
+        this.#provisions.set(geometry, provisions);
+
+        if (stored === 0) {
+            this.#blocks.set(geometry, 0);
+        } else if (table.length > 0) {
+            const allocation = this.#allocate_words(stored);
+
+            if (allocation !== null) {
+                this.#device.queue.writeBuffer(this.#data, 4 * allocation.offset, table, 0, stored);
+                this.#tables.set(geometry, allocation);
+                this.#blocks.set(geometry, blocks);
+            }
+        }
+
+        this.#start_waiting(geometry);
+    }
+
+    /**
+     * The bundle's cache offered to a cache laying itself out, when it matches what the cache keeps:
+     * its material's, the same planes, the codes of the planes it keeps none of, and its field's blocks.
+     *
+     * @param {number} id
+     * @param {MeshSurfaceChannels} channels
+     * @param {number} blocks
+     * @returns {ModelCacheBundleCache|null}
+     */
+    #provision_of(id, channels, blocks) {
+        const provisions = this.#provisions.get(this.#geometry[id]);
+
+        if (provisions === undefined) {
+            return null;
+        }
+
+        const codes = [channels.albedo, channels.metal_rough, channels.emissive];
+
+        for (let i = 0; i < provisions.length; i++) {
+            const { material, cache } = provisions[i];
+
+            if (material !== this.#material[id] || cache.texels !== channels.texels) {
+                continue;
+            }
+
+            let matches = cache.texels === 0 || cache.presence.length === blocks * MESH_SURFACE_PRESENCE_BLOCK_WORDS;
+
+            for (let p = 0; p < PLANES.length && matches; p++) {
+                if ((cache.texels & (1 << PLANES[p])) === 0 && cache.codes[PLANES[p]] !== codes[p]) {
+                    matches = false;
+                }
+            }
+
+            if (matches) {
+                return cache;
+            }
+        }
+
+        return null;
+    }
+
+    /**
+     * The block table of a geometry's field as the storage holds it, read back whole as `words`: its
+     * blocks and words, or 0 and none before a survey.
+     *
+     * @param {number} geometry
+     * @param {Uint32Array} words `data` read back
+     * @returns {{blocks: number, table: Uint32Array}}
+     */
+    export_table(geometry, words) {
+        const table = this.#tables.get(geometry);
+        const blocks = this.#blocks.get(geometry);
+
+        if (table === undefined || blocks === undefined) {
+            return { blocks: 0, table: new Uint32Array(0) };
+        }
+
+        return { blocks, table: words.slice(table.offset, table.offset + this.#stored.get(geometry)) };
+    }
+
+    /**
+     * A resident cache as a bundle's cache laid out by bundle field `field`, its blocks as the storage
+     * holds them, read back whole as `words`.
+     *
+     * @param {number} id
+     * @param {number} field
+     * @param {Uint32Array} words `data` read back
+     * @param {ModelCacheBundleCache} out
+     * @returns {ModelCacheBundleCache} out
+     */
+    export_cache(id, field, words, out) {
+        assert.equal(this.#state[id], CACHE_RESIDENT, `surface cache ${id} is not resident`);
+
+        out.field = field;
+        out.texels = this.#texels[id];
+
+        for (let p = 0; p < PLANES.length; p++) {
+            out.codes[PLANES[p]] = this.#codes[PLANES[p]][id];
+        }
+
+        const blocks = this.#blocks.get(this.#geometry[id]) ?? 0;
+
+        out.presence = run_words(this.#presence_runs[id], blocks * MESH_SURFACE_PRESENCE_BLOCK_WORDS, words);
+
+        for (let p = 0; p < PLANES.length; p++) {
+            out.planes[PLANES[p]] = run_words(this.#plane_runs[p][id], blocks * MESH_SURFACE_PLANE_BLOCK_WORDS[PLANES[p]], words);
+        }
+
+        return out;
+    }
+
+    /**
+     * Queue a resident field's survey, unless it is queued or done: its table, and its bricks taken from
+     * the next frame on.
+     *
+     * @param {number} geometry
+     */
+    #request_survey(geometry) {
+        if (this.#survey_tickets.has(geometry) || this.#blocks.has(geometry)) {
+            return;
+        }
+
+        const table = this.#allocate_words(this.#stored.get(geometry));
+
+        if (table === null) {
+            // the storage is at its binding's limit: its caches that keep a plane wait for the next field
+            return;
+        }
+
+        this.#tables.set(geometry, table);
+
+        const ticket = ++this.#survey_count;
+
+        this.#survey_tickets.set(geometry, ticket);
+        this.#survey_next.set(geometry, 0);
+        this.#queue_survey.push(geometry, ticket);
+    }
+
+    /**
+     * A geometry's survey is read back: its field's bricks keep `blocks` blocks, numbered in its table.
+     * Its caches that keep a plane are laid out.
+     *
+     * @param {number} geometry
+     * @param {number} blocks
+     */
+    set_blocks(geometry, blocks) {
+        assert.isNonNegativeInteger(blocks, 'blocks');
+        assert.ok(this.#stored.has(geometry), `geometry ${geometry} has no resident field to have surveyed`);
+
+        this.#blocks.set(geometry, blocks);
+        this.#survey_tickets.delete(geometry);
+        this.#survey_next.delete(geometry);
+
+        this.#start_waiting(geometry);
+    }
+
+    /**
+     * A geometry's field is gone: its caches wait for the next.
+     *
+     * @param {number} geometry
+     */
+    drop_layout(geometry) {
+        if (!this.#stored.delete(geometry)) {
+            return;
+        }
+
+        this.#colored.delete(geometry);
+        this.#blocks.delete(geometry);
+        this.#provisions.delete(geometry);
+        this.#survey_tickets.delete(geometry);
+        this.#survey_next.delete(geometry);
+
+        const table = this.#tables.get(geometry);
+
+        if (table !== undefined) {
+            this.#data_allocator.free(table);
+            this.#tables.delete(geometry);
+        }
+
+        const caches = this.#caches_of_geometry.get(geometry);
+
+        if (caches === undefined) {
+            return;
+        }
+
+        for (let i = 0; i < caches.length; i++) {
+            const id = caches[i];
+            const was = this.#state[id];
+
+            this.#free_runs(id);
+
+            this.#state[id] = CACHE_WAITING;
+            this.#ticket[id]++;
+            this.#queued[id] = 0;
+            this.#next_brick[id] = 0;
+
+            if (was === CACHE_RESIDENT) {
+                this.#resident_count--;
+                this.onWithdrawn.send1(id);
+            }
+        }
+    }
+
+    /**
+     * The geometry `clone` is drawn as `source` from here on: its caches, and those acquired for it after,
+     * follow `source`'s field and are baked from `source`'s triangles, the two being in one local space.
+     * A cache of `clone` waits for `source`'s field, 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 field, if it had one, is gone: what it has waits
+        this.drop_layout(clone);
+
+        const caches = this.#caches_of_geometry.get(clone);
+
+        if (caches === undefined) {
+            return;
+        }
+
+        this.#caches_of_geometry.delete(clone);
+
+        for (let i = 0; i < caches.length; i++) {
+            const id = caches[i];
+
+            this.#geometry[id] = source;
+
+            let of_source = this.#caches_of_geometry.get(source);
+
+            if (of_source === undefined) {
+                of_source = [];
+                this.#caches_of_geometry.set(source, of_source);
+            }
+
+            of_source.push(id);
+
+            if (this.#stored.has(source)) {
+                this.#start(id);
+            }
+        }
+    }
+
+    /**
+     * `clone` is no longer aliased: caches acquired for it from here on follow its own field. Those it has
+     * keep following its source's until they are given back.
+     *
+     * @param {number} clone
+     */
+    unalias(clone) {
+        this.#source_of.delete(clone);
+    }
+
+    /**
+     * @param {number} geometry
+     */
+    #start_waiting(geometry) {
+        const caches = this.#caches_of_geometry.get(geometry);
+
+        if (caches === undefined) {
+            return;
+        }
+
+        for (let i = 0; i < caches.length; i++) {
+            if (this.#state[caches[i]] === CACHE_WAITING) {
+                this.#start(caches[i]);
+            }
+        }
+    }
+
+    /**
+     * What the cache's material and geometry make of its surface material now.
+     *
+     * @param {number} id
+     * @returns {MeshSurfaceChannels} shared scratch, good until the next call
+     */
+    #channels_of(id) {
+        const geometry = this.#geometry[id];
+
+        return mesh_surface_channels(this.#material[id], this.#colored.get(geometry) === true, this.#channels);
+    }
+
+    /**
+     * @param {number} id
+     * @param {MeshSurfaceChannels} channels
+     */
+    #keep_codes(id, channels) {
+        this.#codes[SURFACE_MATERIAL_ALBEDO_PLANE][id] = channels.albedo;
+        this.#codes[SURFACE_MATERIAL_METAL_ROUGH_PLANE][id] = channels.metal_rough;
+        this.#codes[SURFACE_MATERIAL_EMISSIVE_PLANE][id] = channels.emissive;
+    }
+
+    /**
+     * Whether a laid out cache has blocks to bake.
+     *
+     * @param {number} id
+     * @returns {boolean}
+     */
+    #bakes(id) {
+        return this.#texels[id] !== 0 && this.#presence_runs[id] !== null && this.#presence_runs[id] !== undefined;
+    }
+
+    /**
+     * Runs for a cache whose field is resident, and surveyed when it keeps a plane, and its first bake
+     * queued; a cache with no blocks to bake is resident at once.
+     *
+     * @param {number} id
+     */
+    #start(id) {
+        const geometry = this.#geometry[id];
+
+        this.#ensure_device();
+
+        const channels = this.#channels_of(id);
+        const blocks = this.#blocks.get(geometry);
+
+        if (channels.texels !== 0 && blocks === undefined) {
+            // its field's survey is not read back yet: asked for, if no cache has asked
+            this.#request_survey(geometry);
+            return;
+        }
+
+        if (!this.#allocate(id, channels.texels, channels.texels === 0 ? 0 : blocks)) {
+            // the storage is at its binding's limit; it waits, and is tried again with the next field
+            return;
+        }
+
+        this.#texels[id] = channels.texels;
+        this.#keep_codes(id, channels);
+
+        this.#state[id] = CACHE_BAKING;
+        this.#next_brick[id] = 0;
+
+        const provision = this.#provision_of(id, channels, channels.texels === 0 ? 0 : blocks);
+
+        if (provision !== null) {
+            // the bundle's blocks, in the runs just given: resident without a bake
+            this.#write_run(this.#presence_runs[id], provision.presence);
+
+            for (let p = 0; p < PLANES.length; p++) {
+                this.#write_run(this.#plane_runs[p][id], provision.planes[PLANES[p]]);
+            }
+
+            this.#write_record(id, 0);
+            this.#complete(id);
+
+            return;
+        }
+
+        this.#write_record(id, 0);
+
+        if (!this.#bakes(id)) {
+            // nothing that varies, or no block kept: resident at once, its record all it holds
+            this.#complete(id);
+            return;
+        }
+
+        this.#queued[id] = 1;
+        this.#queue_new.push(id, this.#ticket[id]);
+    }
+
+    /**
+     * A bake of the cache is recorded in full.
+     *
+     * @param {number} id
+     */
+    #complete(id) {
+        if (this.#state[id] === CACHE_BAKING) {
+            this.#state[id] = CACHE_RESIDENT;
+            this.#resident_count++;
+        }
+
+        this.#completed.push(id);
+    }
+
+    /**
+     * Give a cache its runs: `blocks` blocks of presence and of each plane in `texels`, none when it
+     * keeps no plane or its field keeps no block. On failure gives back what it took.
+     *
+     * @param {number} id
+     * @param {number} texels
+     * @param {number} blocks
+     * @returns {boolean} whether every run was given
+     */
+    #allocate(id, texels, blocks) {
+        this.#presence_runs[id] = null;
+
+        for (let p = 0; p < PLANES.length; p++) {
+            this.#plane_runs[p][id] = null;
+        }
+
+        if (texels === 0 || blocks === 0) {
+            return true;
+        }
+
+        const presence = this.#allocate_words(blocks * MESH_SURFACE_PRESENCE_BLOCK_WORDS);
+
+        if (presence === null) {
+            return false;
+        }
+
+        this.#presence_runs[id] = presence;
+
+        for (let p = 0; p < PLANES.length; p++) {
+            if ((texels & (1 << PLANES[p])) === 0) {
+                continue;
+            }
+
+            const run = this.#allocate_words(blocks * MESH_SURFACE_PLANE_BLOCK_WORDS[PLANES[p]]);
+
+            if (run === null) {
+                this.#free_runs(id);
+                return false;
+            }
+
+            this.#plane_runs[p][id] = run;
+        }
+
+        return true;
+    }
+
+    /**
+     * Words of the storage, grown to what they take; the words are copied over.
+     *
+     * @param {number} words
+     * @returns {Allocation|null}
+     */
+    #allocate_words(words) {
+        const allocator = this.#data_allocator;
+
+        if (!allocator.can_allocate(words)) {
+            const target = allocator.grow_target_for(words);
+            const bytes = 4 * target;
+
+            if (bytes > this.#device.limits.maxStorageBufferBindingSize) {
+                warn_limited(`GPUMeshSurfaceCaches: the storage can't hold ${target} words`);
+                return null;
+            }
+
+            const buffer = this.#create_buffer("data", bytes, GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC);
+            const encoder = this.#device.createCommandEncoder({ label: "GPUMeshSurfaceCaches/data growth" });
+
+            encoder.copyBufferToBuffer(this.#data, 0, buffer, 0, this.#data.size);
+            this.#device.queue.submit([encoder.finish()]);
+
+            this.#data.destroy();
+            this.#data = buffer;
+
+            allocator.grow(target);
+        }
+
+        const allocation = allocator.allocate(words);
+
+        assert.notEqual(allocation.offset, ALLOCATOR_NO_SPACE, 'storage allocation after growth');
+
+        return allocation;
+    }
+
+    /**
+     * @param {Allocation|null|undefined} run
+     * @param {Uint32Array} words as many as the run was given
+     */
+    #write_run(run, words) {
+        if (run === null || run === undefined) {
+            return;
+        }
+
+        this.#device.queue.writeBuffer(this.#data, 4 * run.offset, words, 0, words.length);
+    }
+
+    /**
+     * @param {number} id
+     */
+    #free_runs(id) {
+        // only bakes write blocks, in submission order: a later owner's bake comes after
+        const presence = this.#presence_runs[id];
+
+        if (presence !== null && presence !== undefined) {
+            this.#data_allocator.free(presence);
+            this.#presence_runs[id] = null;
+        }
+
+        for (let p = 0; p < PLANES.length; p++) {
+            const run = this.#plane_runs[p][id];
+
+            if (run !== null && run !== undefined) {
+                this.#data_allocator.free(run);
+                this.#plane_runs[p][id] = null;
+            }
+        }
+    }
+
+    /**
+     * @param {number} id
+     * @param {number} material the material's resident id, 0 until a bake takes it
+     */
+    #write_record(id, material) {
+        const view = this.#record_scratch;
+        const geometry = this.#geometry[id];
+        const presence = this.#presence_runs[id];
+        const table = this.#tables.get(geometry);
+
+        view.setUint32(MESH_SURFACE_STRUCT.get("geometry").offset, geometry, true);
+        view.setUint32(MESH_SURFACE_STRUCT.get("material").offset, material, true);
+        view.setUint32(MESH_SURFACE_STRUCT.get("tiles").offset, this.#stored.get(geometry), true);
+        view.setUint32(MESH_SURFACE_STRUCT.get("blocks").offset, this.#blocks.get(geometry) ?? 0, true);
+        view.setUint32(MESH_SURFACE_STRUCT.get("texels").offset, this.#texels[id], true);
+        view.setUint32(MESH_SURFACE_STRUCT.get("table").offset, table === undefined ? 0 : table.offset, true);
+        view.setUint32(MESH_SURFACE_STRUCT.get("presence_blocks").offset, presence === null || presence === undefined ? 0 : presence.offset, true);
+
+        for (let p = 0; p < PLANES.length; p++) {
+            const run = this.#plane_runs[p][id];
+
+            view.setUint32(MESH_SURFACE_STRUCT.get(PLANE_BLOCK_FIELDS[p]).offset, run === null || run === undefined ? 0 : run.offset, true);
+        }
+
+        view.setUint32(MESH_SURFACE_STRUCT.get("albedo").offset, this.#codes[SURFACE_MATERIAL_ALBEDO_PLANE][id], true);
+        view.setUint32(MESH_SURFACE_STRUCT.get("metal_rough").offset, this.#codes[SURFACE_MATERIAL_METAL_ROUGH_PLANE][id], true);
+        view.setUint32(MESH_SURFACE_STRUCT.get("emissive").offset, this.#codes[SURFACE_MATERIAL_EMISSIVE_PLANE][id], true);
+
+        this.#ensure_records(id + 1);
+
+        this.#device.queue.writeBuffer(this.#records, id * MESH_SURFACE_STRUCT.size, view.buffer, 0, MESH_SURFACE_STRUCT.size);
+    }
+
+    /**
+     * Take the frame's survey bricks off its queue into runs, while the frame's budget lasts, and the
+     * fields whose surveys they complete into numbering runs.
+     */
+    #take_surveys() {
+        this.#frame_survey_runs = 0;
+        this.#frame_survey_threads = 0;
+        this.#frame_number_runs = 0;
+        this.#frame_number_threads = 0;
+        this.#frame_clears.length = 0;
+        // made when a survey completes: the frame's readback keeps it
+        this.#frame_completed_surveys = null;
+
+        const queue = this.#queue_survey;
+        let head = this.#head_survey;
+
+        while (this.#frame_left > 0 && head < queue.length) {
+            const geometry = queue[head];
+            const ticket = queue[head + 1];
+
+            if (this.#survey_tickets.get(geometry) !== ticket) {
+                // its field went since it was queued
+                head += 2;
+                continue;
+            }
+
+            const stored = this.#stored.get(geometry);
+            const table = this.#tables.get(geometry);
+            const first = this.#survey_next.get(geometry);
+            const count = Math.min(stored - first, this.#frame_left);
+
+            if (first === 0) {
+                this.#frame_clears.push(table.offset, stored);
+            }
+
+            const runs = this.#frame_survey_runs;
+
+            this.#survey_run_scratch = grow_typed(this.#survey_run_scratch, 4 * (runs + 1));
+            this.#survey_run_scratch[4 * runs] = this.#frame_survey_threads;
+            this.#survey_run_scratch[4 * runs + 1] = geometry;
+            this.#survey_run_scratch[4 * runs + 2] = first;
+            this.#survey_run_scratch[4 * runs + 3] = table.offset;
+
+            this.#frame_survey_runs = runs + 1;
+            this.#frame_survey_threads += count * MESH_SDF_BRICK_TEXEL_COUNT;
+            this.#frame_left -= count;
+
+            if (first + count < stored) {
+                // the budget ran out inside it: it goes on from here next frame
+                this.#survey_next.set(geometry, first + count);
+                break;
+            }
+
+            // surveyed in full this frame: numbered after
+            const numbering = this.#frame_number_runs;
+
+            this.#number_run_scratch = grow_typed(this.#number_run_scratch, 4 * (numbering + 1));
+            this.#number_run_scratch[4 * numbering] = this.#frame_number_threads;
+            this.#number_run_scratch[4 * numbering + 1] = table.offset;
+            this.#number_run_scratch[4 * numbering + 2] = numbering;
+            this.#number_run_scratch[4 * numbering + 3] = ticket;
+
+            this.#frame_number_runs = numbering + 1;
+            this.#frame_number_threads += stored;
+
+            if (this.#frame_completed_surveys === null) {
+                this.#frame_completed_surveys = [];
+            }
+
+            this.#frame_completed_surveys.push(geometry, ticket);
+
+            this.#survey_next.delete(geometry);
+            head += 2;
+        }
+
+        this.#head_survey = this.#compact(queue, head);
+    }
+
+    /**
+     * Take bricks off the bake queues from their heads into the frame's runs, while the frame's budget
+     * lasts: first bakes before bakes again.
+     */
+    #take_bakes() {
+        this.#frame_runs = 0;
+        this.#frame_threads = 0;
+
+        const left = this.#frame_left;
+
+        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.#bricks_baked += left - this.#frame_left;
+    }
+
+    /**
+     * Take bricks 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 field went, since it was queued
+                head += 2;
+                continue;
+            }
+
+            const stored = this.#stored.get(this.#geometry[id]);
+            const first = this.#next_brick[id];
+            const count = Math.min(stored - first, this.#frame_left);
+
+            if (first === 0) {
+                // its row as the material stands now, repacked if it has moved since
+                this.#frame_materials.obtain_material(this.#material[id]);
+                this.#write_record(id, this.#material[id].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 * MESH_SDF_BRICK_TEXEL_COUNT;
+            this.#frame_left -= count;
+
+            this.#next_brick[id] = first + count;
+
+            if (first + count < stored) {
+                // the budget ran out inside it: it goes on from here next frame
+                return head;
+            }
+
+            this.#next_brick[id] = 0;
+            this.#queued[id] = 0;
+            head += 2;
+
+            this.#complete(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 surveys and bake: at most `budget` bricks. Records nothing when nothing waits.
+     * Caches whose bake this completes are announced through {@link onBaked}, resident from here; the
+     * surveys it completes are read back.
+     *
+     * @param {Object} options
+     * @param {FrameGraph} options.graph
+     * @param {number} options.budget bricks surveyed and baked at most, `surface_bake_budget`: a frame
+     *        lists every texel of its bricks in one storage binding
+     * @param {number} options.arena graph handle of the fields' indirection, as the frame's bake left it
+     * @param {GPUBuffer} options.headers the fields' headers
+     * @param {GPUTextureView} options.field_atlas the fields' atlas
+     * @param {GPUResidentMaterialContext} options.materials what the trace shades with: each baked
+     *        material is made resident, and the rows committed, before the trace is recorded
+     * @param {Object} options.blas the geometry bindings `ray_query_blas_nearest` reads
+     */
+    graph_bake({ graph, budget, arena, headers, field_atlas, materials, blas }) {
+        assert.defined(graph, 'graph');
+        assert.isPositiveInteger(budget, 'budget');
+        assert.lessThanOrEqual(budget * MESH_SDF_BRICK_TEXEL_COUNT * MESH_SURFACE_TEXEL_STRUCT.aligned_size, this.#device.limits.maxStorageBufferBindingSize, "budget, a frame's texel list of every texel of its bricks past maxStorageBufferBindingSize");
+        assert.defined(materials, 'materials');
+
+        this.#frame_materials = materials;
+        this.#frame_left = budget;
+
+        this.#take_surveys();
+        this.#take_bakes();
+
+        this.#frame_materials = null;
+
+        const b = this.#bindings;
+
+        b.mesh_sdf_headers = headers;
+        b.mesh_sdf_atlas = field_atlas;
+        b.mesh_sdf_sampler = MESH_SDF_SAMPLER;
+
+        if (this.#frame_survey_runs > 0) {
+            this.#record_surveys(graph, arena);
+        }
+
+        if (this.#frame_runs > 0) {
+            this.#ensure_device();
+
+            // what the runs' materials made resident, written before the trace reads it
+            materials.commit();
+
+            if (this.#runs === null || this.#frame_runs > this.#run_capacity) {
+                this.#run_capacity = doubled_capacity(this.#frame_runs, this.#run_capacity);
+                this.#runs?.destroy();
+                this.#runs = this.#create_buffer("runs", 16 * this.#run_capacity, GPUBufferUsage.COPY_DST);
+            }
+
+            this.#ensure_texels(this.#frame_threads);
+
+            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 Surface Bake", data, this.#execute);
+
+            data.arena = pass.read(arena);
+
+            pass.make_side_effect();
+
+            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;
+        }
+
+        const completed = this.#completed;
+
+        for (let i = 0; i < completed.length; i++) {
+            this.onBaked.send1(completed[i]);
+        }
+
+        completed.length = 0;
+    }
+
+    /**
+     * @param {FrameGraph} graph
+     * @param {number} arena
+     */
+    #record_surveys(graph, arena) {
+        this.#ensure_device();
+
+        if (this.#survey_runs === null || this.#frame_survey_runs > this.#survey_run_capacity) {
+            this.#survey_run_capacity = doubled_capacity(this.#frame_survey_runs, this.#survey_run_capacity);
+            this.#survey_runs?.destroy();
+            this.#survey_runs = this.#create_buffer("survey runs", 16 * this.#survey_run_capacity, GPUBufferUsage.COPY_DST);
+        }
+
+        this.#device.queue.writeBuffer(this.#survey_runs, 0, this.#survey_run_scratch, 0, 4 * this.#frame_survey_runs);
+
+        const numbering = this.#frame_number_runs;
+
+        if (numbering > 0) {
+            if (this.#number_runs === null || numbering > this.#number_run_capacity) {
+                this.#number_run_capacity = doubled_capacity(numbering, this.#number_run_capacity);
+                this.#number_runs?.destroy();
+                this.#number_runs = this.#create_buffer("number runs", 16 * this.#number_run_capacity, GPUBufferUsage.COPY_DST);
+            }
+
+            this.#device.queue.writeBuffer(this.#number_runs, 0, this.#number_run_scratch, 0, 4 * numbering);
+            this.#ensure_survey_results(numbering);
+        }
+
+        const data = this.#survey_pass_data;
+        const pass = graph.add("Mesh Surface Survey", data, this.#execute_surveys);
+
+        data.arena = pass.read(arena);
+        data.results = -1;
+
+        pass.make_side_effect();
+
+        if (numbering === 0) {
+            return;
+        }
+
+        data.results = pass.write(graph_import_buffer(graph, this.#survey_results, "mesh_surface_survey_results"));
+
+        const completed = this.#frame_completed_surveys;
+
+        graph_read_buffer({ graph, buffer: data.results, offset: 0, size: 4 * MESH_SURFACE_SURVEY_RESULT_WORDS * numbering })
+            .then(reference => {
+                try {
+                    if (!this.#destroyed) {
+                        this.#apply_surveys(new Uint32Array(reference.getValue()), completed);
+                    }
+                } finally {
+                    reference.release();
+                }
+            })
+            .catch(error => {
+                if (!this.#destroyed) {
+                    // a lost result leaves its field's caches waiting until the field is laid out again; say so
+                    console.warn('GPUMeshSurfaceCaches: survey readback failed', error);
+                }
+            });
+    }
+
+    /**
+     * @param {Uint32Array} words the frame's results
+     * @param {number[]} completed the (geometry, ticket) pairs they were asked for
+     */
+    #apply_surveys(words, completed) {
+        for (let i = 0; i < completed.length; i += 2) {
+            const geometry = completed[i];
+            const ticket = completed[i + 1];
+            const result = (i / 2) * MESH_SURFACE_SURVEY_RESULT_WORDS;
+
+            // a result no pass wrote holds no ticket, and a field gone since holds another
+            if (words[result] !== ticket || this.#survey_tickets.get(geometry) !== ticket) {
+                continue;
+            }
+
+            this.set_blocks(geometry, words[result + 1]);
+        }
+    }
+
+    /**
+     * {@link #execute_surveys_now}, bound once.
+     * @type {function(Object, Object, Object): void}
+     */
+    #execute_surveys = (data, resources, context) => this.#execute_surveys_now(data, resources, context);
+
+    #execute_surveys_now(data, resources, context) {
+        const encoder = context.encoder;
+        const b = this.#bindings;
+
+        // each field's table, before its first bricks set their bits
+        const clears = this.#frame_clears;
+
+        for (let i = 0; i < clears.length; i += 2) {
+            encoder.clearBuffer(this.#data, 4 * clears[i], 4 * clears[i + 1]);
+        }
+
+        b.mesh_sdf_indirection = resources.get(data.arena);
+        b.mesh_surface_data = this.#data;
+        b.mesh_surface_runs = this.#survey_runs;
+
+        const survey = this.#survey_settings;
+        const groups = Math.ceil(this.#frame_survey_threads / MESH_SDF_BAKE_WORKGROUP_SIZE);
+        const groups_x = Math.min(groups, WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION);
+
+        survey.run_count = this.#frame_survey_runs;
+        survey.thread_count = this.#frame_survey_threads;
+        survey.groups_x = groups_x;
+        b.settings = survey;
+
+        shader_mesh_surface_survey.dispatch({
+            encoder,
+            group_count_x: groups_x,
+            group_count_y: Math.ceil(groups / groups_x),
+            bindings: b,
+        });
+
+        if (this.#frame_number_runs === 0) {
+            return;
+        }
+
+        const results = resources.get(data.results);
+
+        encoder.clearBuffer(results, 0, 4 * MESH_SURFACE_SURVEY_RESULT_WORDS * this.#frame_number_runs);
+
+        b.mesh_surface_runs = this.#number_runs;
+        b.mesh_surface_survey_results = results;
+
+        const number = this.#number_settings;
+        const number_groups = Math.ceil(this.#frame_number_threads / MESH_SDF_BAKE_WORKGROUP_SIZE);
+        const number_x = Math.min(number_groups, WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION);
+
+        number.run_count = this.#frame_number_runs;
+        number.thread_count = this.#frame_number_threads;
+        number.groups_x = number_x;
+        b.settings = number;
+
+        shader_mesh_surface_number.dispatch({
+            encoder,
+            group_count_x: number_x,
+            group_count_y: Math.ceil(number_groups / number_x),
+            bindings: b,
+        });
+    }
+
+    /**
+     * {@link #execute_bake}, bound once.
+     * @type {function(Object, Object, Object): void}
+     */
+    #execute = (data, resources, context) => this.#execute_bake(data, resources, context);
+
+    #execute_bake(data, resources, context) {
+        const encoder = context.encoder;
+        const b = this.#bindings;
+
+        encoder.clearBuffer(this.#counter);
+
+        b.mesh_sdf_indirection = resources.get(data.arena);
+        b.mesh_surface_records = this.#records;
+        b.mesh_surface_runs = this.#runs;
+        b.mesh_surface_texels = this.#texel_list;
+        b.mesh_surface_staging = this.#staging;
+        b.mesh_surface_counter = this.#counter;
+        b.mesh_surface_command = this.#command;
+        b.mesh_surface_data = this.#data;
+
+        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 list = this.#list_settings;
+
+        list.run_count = this.#frame_runs;
+        list.thread_count = this.#frame_threads;
+        list.groups_x = groups_x;
+        list.capacity = this.#texel_capacity;
+        b.settings = list;
+
+        shader_mesh_surface_list.dispatch({
+            encoder,
+            group_count_x: groups_x,
+            group_count_y: Math.ceil(groups / groups_x),
+            bindings: b,
+        });
+
+        this.#command_settings.capacity = this.#texel_capacity;
+        b.settings = this.#command_settings;
+
+        shader_mesh_surface_command.dispatch({ encoder, bindings: b });
+
+        shader_mesh_surface_trace.dispatchIndirect({
+            encoder,
+            bindings: b,
+            command: this.#command,
+        });
+
+        // a workgroup a block: 8 a brick
+        const bricks = this.#frame_threads / MESH_SDF_BRICK_TEXEL_COUNT;
+        const blocks = bricks * MESH_SURFACE_BRICK_BLOCKS;
+        const blocks_x = Math.min(blocks, WEBGPU_GUARANTEED_MAX_COMPUTE_WORKGROUPS_PER_DIMENSION);
+        const encode = this.#encode_settings;
+
+        encode.run_count = this.#frame_runs;
+        encode.brick_count = bricks;
+        encode.groups_x = blocks_x;
+        b.settings = encode;
+
+        shader_mesh_surface_encode.dispatch({
+            encoder,
+            group_count_x: blocks_x,
+            group_count_y: Math.ceil(blocks / blocks_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_brick = grow_typed(this.#next_brick, length);
+        this.#queued = grow_typed(this.#queued, length);
+        this.#texels = grow_typed(this.#texels, length);
+
+        for (let p = 0; p < PLANES.length; p++) {
+            this.#codes[p] = grow_typed(this.#codes[p], length);
+        }
+    }
+
+    #ensure_device() {
+        if (this.#records !== null || this.#destroyed) {
+            return;
+        }
+
+        this.#data = this.#create_buffer("data", 4 * INITIAL_DATA_WORDS, GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC);
+        this.#data_allocator = new OffsetAllocator(INITIAL_DATA_WORDS);
+
+        this.#counter = this.#create_buffer("counter", 4 * MESH_SURFACE_COUNTER_WORDS, GPUBufferUsage.COPY_DST);
+        this.#command = this.#create_buffer("command", 4 * MESH_SURFACE_COMMAND_WORDS, GPUBufferUsage.INDIRECT);
+
+        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_SURFACE_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: "GPUMeshSurfaceCaches/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} results
+     */
+    #ensure_survey_results(results) {
+        if (this.#survey_results !== null && results <= this.#survey_result_capacity) {
+            return;
+        }
+
+        const capacity = doubled_capacity(results, this.#survey_result_capacity);
+
+        this.#survey_results?.destroy();
+        this.#survey_results = this.#create_buffer("survey results", 4 * MESH_SURFACE_SURVEY_RESULT_WORDS * capacity, GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC);
+        this.#survey_result_capacity = capacity;
+    }
+
+    /**
+     * @param {number} texels the most a frame may list: every texel of its runs
+     */
+    #ensure_texels(texels) {
+        if (this.#texel_list !== null && this.#texel_capacity >= texels) {
+            return;
+        }
+
+        let capacity = Math.max(MESH_SDF_BRICK_TEXEL_COUNT, this.#texel_capacity);
+
+        while (capacity < texels) {
+            capacity *= 2;
+        }
+
+        // doubled no further than one binding holds; the need itself fits one, by the budget's check
+        const binding = Math.floor(this.#device.limits.maxStorageBufferBindingSize / MESH_SURFACE_TEXEL_STRUCT.aligned_size);
+
+        capacity = Math.max(texels, Math.min(capacity, binding));
+
+        this.#texel_list?.destroy();
+        this.#staging?.destroy();
+        this.#texel_list = this.#create_buffer("texels", MESH_SURFACE_TEXEL_STRUCT.aligned_size * capacity, 0);
+        this.#staging = this.#create_buffer("staging", 4 * MESH_SURFACE_STAGING_WORDS * capacity, 0);
+        this.#texel_capacity = capacity;
+    }
+
+    /**
+     * @param {string} name
+     * @param {number} size
+     * @param {number} usage beside STORAGE
+     * @returns {GPUBuffer}
+     */
+    #create_buffer(name, size, usage) {
+        // bound whole, as storage
+        assert.lessThanOrEqual(size, this.#device.limits.maxStorageBufferBindingSize, `${name} past maxStorageBufferBindingSize`);
+
+        return this.#device.createBuffer(BufferDescriptor.fromJSON({
+            label: `GPUMeshSurfaceCaches/${name}`,
+            size,
+            usage: GPUBufferUsage.STORAGE | usage,
+        }));
+    }
+
+    /**
+     * @returns {number} bytes
+     */
+    get gpu_memory_usage() {
+        let bytes = 0;
+
+        for (const buffer of [this.#records, this.#data, this.#runs, this.#survey_runs, this.#number_runs, this.#survey_results, this.#texel_list, this.#staging, this.#counter, this.#command]) {
+            if (buffer !== null) {
+                bytes += buffer.size;
+            }
+        }
+
+        return bytes;
+    }
+
+    destroy() {
+        for (const buffer of [this.#records, this.#data, this.#runs, this.#survey_runs, this.#number_runs, this.#survey_results, this.#texel_list, this.#staging, this.#counter, this.#command]) {
+            buffer?.destroy();
+        }
+
+        this.#records = null;
+        this.#data = null;
+        this.#runs = null;
+        this.#survey_runs = null;
+        this.#number_runs = null;
+        this.#survey_results = null;
+        this.#texel_list = null;
+        this.#staging = null;
+        this.#counter = null;
+        this.#command = null;
+        this.#destroyed = true;
+    }
+}