@woosh/meep-engine 3.14.1 → 3.14.3

package/src/shade/renderer/geometry/bvh/GPUGeometryBVHManager.js

@@ -1,618 +1,731 @@
-import { assert } from "../../../../core/assert.js";
-import { platform_compute_endianness } from "../../../../core/binary/platform_compute_endianness.js";
-import { array_buffer_copy } from "../../../../core/collection/array/typed/array_buffer_copy.js";
-import { Deque } from "../../../../core/collection/queue/Deque.js";
-import { round_up } from "../../../../core/math/round_up.js";
-import { number_format_by_thousands } from "../../../../core/primitives/numbers/number_format_by_thousands.js";
-import { u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
-import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
-import { BVH2_NODE_STRUCT } from "../../shader/chunk/bvh/BVH2_NODE_STRUCT.js";
-import { ensure_buffer_capacity } from "../make_temp_gpu_buffer.js";
-import { bvh2_derive_topology } from "./bvh2_derive_topology.js";
-import { GPUGeometryMeshletsBVH } from "./GPUGeometryMeshletsBVH.js";
-
-/**
- * One row of the lookup table the traversal shaders read as `blas_lookup`.
- *
- * The row holds the arena node index a tree's root sits at. What the table is *indexed* by is not
- * this manager's business — see {@link GPUGeometryBVHManager#publish_lookup}.
- */
-export const BLAS_METADATA_STRUCT = WebGPUStruct.from({
-    // index of root node for BLAS
-    address: u32
-});
-
-const DATA_SIZE_ALIGNMENT = 1024;
-const DATA_INITIAL_CAPACITY = round_up(1024, DATA_SIZE_ALIGNMENT);
-
-const DATA_GROWTH_STEP = 1024;
-const DATA_GROWTH_MULTIPLIER = 1.2;
-
-const endianness = platform_compute_endianness();
-
-/**
- * Residency for BLAS node data: one arena buffer holding every registered tree's nodes, and a
- * lookup buffer that maps *something else's* index onto an arena address.
- *
- * The split matters. This manager owns arena positions — it decides where a tree's nodes land and
- * hands back the node index of its root. It does **not** own the index space the lookup is read by:
- * every traversal shader does `blas_lookup[geometry_index]`, and geometry indices belong to
- * {@link GPUGeometryManager}. So the table is published by whoever owns those indices, through
- * {@link publish_lookup}; this manager only stores and uploads it.
- *
- * It used to allocate the lookup rows itself, from a pool of its own in BLAS-registration order.
- * That agrees with geometry indices exactly until something takes a geometry index without taking a
- * BLAS row — which per-instance clones do — after which every geometry resolved to another
- * geometry's tree. See `blas_lookup_indexing.spec.js`.
- */
-export class GPUGeometryBVHManager {
-
-    /**
-     *
-     * @type {GPUBuffer}
-     */
-    #buffer_metadata;
-
-    /**
-     *
-     * @returns {GPUBuffer}
-     */
-    get buffer_metadata() {
-        return this.#buffer_metadata;
-    }
-
-    /**
-     * @type {GPUBuffer}
-     */
-    #buffer_data;
-
-    /**
-     *
-     * @returns {GPUBuffer}
-     */
-    get buffer_data() {
-        return this.#buffer_data;
-    }
-
-    /**
-     * Used range end pointer
-     * @type {number}
-     */
-    #buffer_data_end = 0;
-
-    /**
-     * Parent of every node, and the node index of every leaf, for each *distinct topology* — one
-     * arena each, addressed like {@link #buffer_data}.
-     *
-     * Separate from the nodes because they are separate things. Node bounds are per instance: a
-     * skinned clone's are its own, recomputed every frame from its own deformed vertices. Parents
-     * and leaf positions are the shape of the tree, and every copy of a geometry has the same
-     * shape, so one derivation serves all of them.
-     *
-     * @type {GPUBuffer}
-     */
-    #buffer_parents;
-
-    /**
-     * @returns {GPUBuffer}
-     */
-    get buffer_parents() {
-        return this.#buffer_parents;
-    }
-
-    /**
-     * @type {GPUBuffer}
-     */
-    #buffer_leaf_nodes;
-
-    /**
-     * @returns {GPUBuffer}
-     */
-    get buffer_leaf_nodes() {
-        return this.#buffer_leaf_nodes;
-    }
-
-    #buffer_parents_end = 0;
-    #buffer_leaf_nodes_end = 0;
-
-    /**
-     * Topology by the geometry whose nodes it was derived from, shared by every copy of it.
-     *
-     * @type {Map<MeshletGeometry, {parents_offset: number, leaf_nodes_offset: number, leaf_count: number, node_count: number, resident: boolean, derived: {parents: Uint32Array, leaf_nodes: Uint32Array}}>}
-     */
-    #topology = new Map();
-
-    /**
-     *
-     * @type {number}
-     */
-    #node_capacity = 0;
-
-    /**
-     * @type {GPUDevice}
-     */
-    #device
-
-    /**
-     *
-     * @type {Map<MeshletGeometry, GPUGeometryMeshletsBVH>}
-     */
-    #map = new Map();
-
-    /**
-     * The queue is processed during {@link update}
-     * @type {Deque<GPUGeometryMeshletsBVH>}
-     */
-    #update_queue = new Deque();
-
-    /**
-     *
-     * @param {GPUDevice} device
-     */
-    constructor(device) {
-        this.#device = device;
-
-        this.#buffer_metadata = device.createBuffer({
-            label: "GPUGeometryBVHManager/metadata",
-            size: BLAS_METADATA_STRUCT.size * 16,
-            usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC | GPUBufferUsage.STORAGE,
-        });
-
-        this.#buffer_data = device.createBuffer({
-            label: "GPUGeometryBVHManager/data",
-            size: DATA_INITIAL_CAPACITY,
-            usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC | GPUBufferUsage.STORAGE,
-        });
-
-        this.#buffer_parents = device.createBuffer({
-            label: "GPUGeometryBVHManager/parents",
-            size: DATA_INITIAL_CAPACITY,
-            usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC | GPUBufferUsage.STORAGE,
-        });
-
-        this.#buffer_leaf_nodes = device.createBuffer({
-            label: "GPUGeometryBVHManager/leaf_nodes",
-            size: DATA_INITIAL_CAPACITY,
-            usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC | GPUBufferUsage.STORAGE,
-        });
-
-    }
-
-    get gpu_memory_usage() {
-        let r = 0;
-
-        if (this.#buffer_metadata) {
-            r += this.#buffer_metadata.size;
-        }
-
-        if (this.#buffer_data) {
-            r += this.#buffer_data.size;
-        }
-
-        if (this.#buffer_parents) {
-            r += this.#buffer_parents.size;
-        }
-
-        if (this.#buffer_leaf_nodes) {
-            r += this.#buffer_leaf_nodes.size;
-        }
-
-        return r;
-    }
-
-    /**
-     * The tree belonging to `owner`, registered against `source`'s shape if it does not exist yet.
-     *
-     * Two arguments rather than one because those are two different questions. `owner` is the
-     * identity the tree is looked up by; `source` is the geometry whose nodes it starts as. They
-     * coincide for anything that owns its geometry outright, and they do not for a per-instance
-     * copy — a skinned clone deforms its own vertices, so its bounds are its own and cannot be
-     * written into the tree everyone else is tracing, but its *shape* is by definition the
-     * source's. Keeping the two separate is what lets one derivation serve every copy.
-     *
-     * @param {object} owner identity to look this tree up by — a geometry, a clone's metadata row
-     * @param {MeshletGeometry} source geometry whose nodes this tree takes its shape and rest-pose
-     * bounds from
-     * @returns {GPUGeometryMeshletsBVH}
-     */
-    obtain(owner, source) {
-        assert.defined(owner, 'owner');
-        assert.equal(source.isMeshletGeometry, true, 'source.isMeshletGeometry !== true');
-
-        let bvh = this.#map.get(owner);
-
-        if (bvh === undefined) {
-            bvh = this.#register(owner, source);
-        }
-
-        return bvh;
-    }
-
-    /**
-     * Register a tree, keyed by whatever owns it.
-     *
-     * `owner` is the identity the tree is looked up by and `source` is the geometry whose nodes it
-     * holds. For an ordinary geometry those are the same object. For a per-instance copy they are
-     * not: the copy needs a node region of its own, because its bounds move independently, while
-     * the *shape* it is a copy of belongs to the source.
-     *
-     * @param {object} owner
-     * @param {MeshletGeometry} source
-     * @returns {GPUGeometryMeshletsBVH}
-     */
-    #register(owner, source) {
-
-        const bvh = new GPUGeometryMeshletsBVH();
-
-        bvh.bvh = source.bvh;
-        bvh.topology = this.#obtain_topology(source);
-
-        this.#map.set(owner, bvh);
-
-        this.#update_queue.add(bvh);
-
-        return bvh;
-    }
-
-    /**
-     * The parents/leaf-nodes derivation for a geometry, made once and shared by every tree that is
-     * a copy of it.
-     *
-     * @param {MeshletGeometry} source
-     * @returns {object} the topology record
-     */
-    #obtain_topology(source) {
-        let topology = this.#topology.get(source);
-
-        if (topology !== undefined) {
-            return topology;
-        }
-
-        // Derivation waits for {@link #upload_pending_topology}, beside the residency decision it
-        // feeds. A geometry can be registered before its BLAS bytes exist — nothing has to have
-        // built one yet — and a record that says "not resident" is the honest answer for that,
-        // rather than an empty derivation cached forever.
-        topology = {
-            source,
-            leaf_count: 0,
-            node_count: 0,
-            parents_offset: 0,
-            leaf_nodes_offset: 0,
-            resident: false,
-        };
-
-        this.#topology.set(source, topology);
-
-        return topology;
-    }
-
-    /**
-     * Everything a refit needs to find a resident tree, or `undefined` while it is not resident.
-     *
-     * @param {object} owner the identity passed to {@link obtain}
-     * @returns {{node_word_offset: number, node_count: number, leaf_count: number, parents_offset: number, leaf_nodes_offset: number}|undefined}
-     */
-    get_refit_target(owner) {
-        const bvh = this.#map.get(owner);
-
-        if (bvh === undefined || bvh.released || !bvh.resident || !bvh.topology.resident) {
-            return undefined;
-        }
-
-        return {
-            node_word_offset: bvh.address * (BVH2_NODE_STRUCT.size / Uint32Array.BYTES_PER_ELEMENT),
-            node_count: bvh.topology.node_count,
-            leaf_count: bvh.topology.leaf_count,
-            parents_offset: bvh.topology.parents_offset,
-            leaf_nodes_offset: bvh.topology.leaf_nodes_offset,
-        };
-    }
-
-    /**
-     * Where a registered tree's root sits in the arena, or `undefined` while nothing is resident
-     * for this owner — either it was never registered, or {@link update} has not run since.
-     *
-     * @param {object} owner the identity passed to {@link obtain}
-     * @returns {number|undefined} arena node index
-     */
-    get_address(owner) {
-        const bvh = this.#map.get(owner);
-
-        if (bvh === undefined || bvh.released || !bvh.resident) {
-            return undefined;
-        }
-
-        return bvh.address;
-    }
-
-    /**
-     * Publish the lookup table the traversal shaders read.
-     *
-     * `addresses[i]` is the arena node index that index `i` resolves to. What `i` means is the
-     * caller's business — today it is a geometry index, and the shaders agree because
-     * {@link GPUGeometryManager} builds the table from the same ids it stamps into the geometry
-     * metadata buffer.
-     *
-     * @param {Uint32Array} addresses
-     */
-    publish_lookup(addresses) {
-        assert.defined(addresses, 'addresses');
-
-        this.#ensure_metadata_capacity(addresses.length);
-
-        this.#device.queue.writeBuffer(this.#buffer_metadata, 0, addresses, 0, addresses.length);
-    }
-
-    /**
-     * Release an owner's BLAS: the map entry is dropped, and the next {@link publish_lookup}
-     * stops naming its arena address. The append-only data region ({@link #buffer_data}) is not
-     * reclaimed — those bytes become unreferenced and are only recovered on a future buffer
-     * rebuild, a bounded residual versus the previous total leak (no entry was ever freed).
-     *
-     * @param {object} owner the identity passed to {@link obtain}
-     * @returns {boolean} true if a BLAS was registered for this owner and released
-     */
-    remove(owner) {
-        const bvh = this.#map.get(owner);
-
-        if (bvh === undefined) {
-            return false;
-        }
-
-        // may still be sitting in #update_queue if removed the same frame it was registered;
-        // the update pass skips released records
-        bvh.released = true;
-
-        this.#map.delete(owner);
-
-        this.#release_topology_if_orphaned(bvh.topology);
-
-        return true;
-    }
-
-    /**
-     * Drop a shape once the last tree that had it is gone.
-     *
-     * The arena bytes are not reclaimed — same append-only story as the nodes — but the map entry
-     * holds a strong reference to the geometry it is keyed by, so leaving it would keep every
-     * geometry a scene ever loaded alive for as long as the manager is.
-     *
-     * @param {object} topology
-     */
-    #release_topology_if_orphaned(topology) {
-        for (const bvh of this.#map.values()) {
-            if (bvh.topology === topology) {
-                return;
-            }
-        }
-
-        for (const [source, candidate] of this.#topology) {
-            if (candidate === topology) {
-                this.#topology.delete(source);
-
-                return;
-            }
-        }
-    }
-
-    /**
-     *
-     * @param {number} size
-     */
-    #ensure_data_capacity(size) {
-        if (this.#node_capacity >= size) {
-            // big enough already
-            return;
-        }
-
-        let new_size = size;
-
-        this.#node_capacity = new_size;
-
-        this.#buffer_data = ensure_buffer_capacity(
-            this.#device,
-            this.#buffer_data,
-            new_size * BVH2_NODE_STRUCT.size,
-            DATA_SIZE_ALIGNMENT,
-            DATA_GROWTH_STEP,
-            DATA_GROWTH_MULTIPLIER
-        );
-
-    }
-
-    /**
-     *
-     * @param {number} size
-     */
-    #ensure_metadata_capacity(row_count) {
-        this.#buffer_metadata = ensure_buffer_capacity(
-            this.#device,
-            this.#buffer_metadata,
-            Math.max(1, row_count) * BLAS_METADATA_STRUCT.size,
-            BLAS_METADATA_STRUCT.align,
-            16,
-            1.2
-        );
-    }
-
-    /**
-     * Append every topology derived but not yet uploaded to its arena.
-     *
-     * Queue-free: the map is small (one entry per distinct geometry) and a `resident` flag says what
-     * is left to do, which is one fewer thing to keep in step than a second queue would be.
-     */
-    #upload_pending_topology() {
-        const queue = this.#device.queue;
-
-        for (const topology of this.#topology.values()) {
-            if (topology.resident) {
-                continue;
-            }
-
-            const bytes = topology.source.bvh;
-
-            if (bytes === undefined || bytes.byteLength === 0) {
-                // no tree to take the shape of yet; try again next time
-                continue;
-            }
-
-            const { parents, leaf_nodes } = bvh2_derive_topology(bytes);
-
-            this.#buffer_parents = ensure_buffer_capacity(
-                this.#device,
-                this.#buffer_parents,
-                (this.#buffer_parents_end + parents.length) * Uint32Array.BYTES_PER_ELEMENT,
-                DATA_SIZE_ALIGNMENT,
-                DATA_GROWTH_STEP,
-                DATA_GROWTH_MULTIPLIER
-            );
-
-            this.#buffer_leaf_nodes = ensure_buffer_capacity(
-                this.#device,
-                this.#buffer_leaf_nodes,
-                (this.#buffer_leaf_nodes_end + leaf_nodes.length) * Uint32Array.BYTES_PER_ELEMENT,
-                DATA_SIZE_ALIGNMENT,
-                DATA_GROWTH_STEP,
-                DATA_GROWTH_MULTIPLIER
-            );
-
-            topology.parents_offset = this.#buffer_parents_end;
-            topology.leaf_nodes_offset = this.#buffer_leaf_nodes_end;
-
-            queue.writeBuffer(
-                this.#buffer_parents,
-                topology.parents_offset * Uint32Array.BYTES_PER_ELEMENT,
-                parents, 0, parents.length
-            );
-
-            queue.writeBuffer(
-                this.#buffer_leaf_nodes,
-                topology.leaf_nodes_offset * Uint32Array.BYTES_PER_ELEMENT,
-                leaf_nodes, 0, leaf_nodes.length
-            );
-
-            this.#buffer_parents_end += parents.length;
-            this.#buffer_leaf_nodes_end += leaf_nodes.length;
-
-            topology.leaf_count = leaf_nodes.length;
-            // slots, not tree nodes — the arena numbers a tree's nodes with the free list's holes
-            // in, and a refit's arrival counters are indexed by that numbering
-            topology.node_count = parents.length;
-            topology.resident = true;
-        }
-    }
-
-    update() {
-
-        // Ahead of the early return below: topology residency is its own question, and leaving it
-        // behind a queue of node uploads would make it depend on there happening to be one.
-        this.#upload_pending_topology();
-
-        const queue = this.#update_queue;
-
-        const queue_size = queue.size();
-
-        if (queue_size === 0) {
-            // nothing to do
-            return;
-        }
-
-        console.log(`GPUGeometryBVHManager#update, queue=${queue_size}`);
-
-        let used_node_count = 0;
-
-        // figure out how large a copy buffer will need to be
-        let total_byte_size = 0;
-        const temp_buffer_offsets = new Uint32Array(queue_size);
-        for (let i = 0; i < queue_size; i++) {
-            const blas = queue.getElementByIndex(i);
-
-            if (blas.released) { continue; }
-
-
-            temp_buffer_offsets[i] = total_byte_size;
-
-            const node_count = blas.bvh.byteLength / BVH2_NODE_STRUCT.size;
-
-            assert.isNonNegativeInteger(node_count, "node_count");
-
-            total_byte_size += node_count * BVH2_NODE_STRUCT.size;
-
-            used_node_count += node_count;
-        }
-
-        this.#ensure_data_capacity(this.#node_capacity + used_node_count);
-
-
-        const device = this.#device;
-        const encoder = device.createCommandEncoder({
-            label: "GPUGeometryBVHManager#update"
-        });
-
-        const temp_data_buffer = device.createBuffer({
-            label: "temp_data_buffer",
-            usage: GPUBufferUsage.COPY_SRC,
-            size: total_byte_size,
-            mappedAtCreation: true
-        });
-
-        const mapped_temp_data = temp_data_buffer.getMappedRange();
-
-
-        // write to temp buffer
-        for (let i = 0; i < queue_size; i++) {
-            const blas = queue.getElementByIndex(i);
-
-            if (blas.released) { continue; }
-
-            const offset = temp_buffer_offsets[i];
-
-            array_buffer_copy(
-                blas.bvh, 0,
-                mapped_temp_data, offset,
-                blas.bvh.byteLength
-            );
-        }
-
-        temp_data_buffer.unmap();
-
-        // copy data from temp buffer to where it needs to go
-
-        for (let i = 0; i < queue_size; i++) {
-            const blas = queue.getElementByIndex(i);
-
-            if (blas.released) { continue; }
-
-            const address = this.#buffer_data_end;
-
-            blas.address = address / BVH2_NODE_STRUCT.size;
-            blas.resident = true;
-
-            const blas_size = blas.bvh.byteLength;
-
-            // this.#buffer_data_end = roundUp(BVH8_INODE_STRUCT.align, this.#buffer_data_end + blas_size);
-            this.#buffer_data_end = this.#buffer_data_end + blas_size;
-
-            const temp_offset = temp_buffer_offsets[i];
-
-            encoder.copyBufferToBuffer(
-                temp_data_buffer, temp_offset,
-                this.#buffer_data, address,
-                blas_size
-            );
-        }
-
-        console.warn(`BLAS size: ${number_format_by_thousands(this.#buffer_data_end)} bytes`);
-
-        device.queue.submit([encoder.finish()])
-
-        // free up the temp buffer
-        temp_data_buffer.destroy();
-
-        // drain: everything queued is now resident. Leaving entries in the queue re-uploads
-        // every BLAS ever registered on each update and appends fresh copies at
-        // #buffer_data_end — quadratic memory growth until createBuffer fails.
-        queue.clear();
-
-    }
+import { assert } from "../../../../core/assert.js";
+import { platform_compute_endianness } from "../../../../core/binary/platform_compute_endianness.js";
+import { array_buffer_copy } from "../../../../core/collection/array/typed/array_buffer_copy.js";
+import { Deque } from "../../../../core/collection/queue/Deque.js";
+import { round_up } from "../../../../core/math/round_up.js";
+import { number_format_by_thousands } from "../../../../core/primitives/numbers/number_format_by_thousands.js";
+import { u32 } from "../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+import { BVH2_NODE_STRUCT } from "../../shader/chunk/bvh/BVH2_NODE_STRUCT.js";
+import {
+    BVH_NODE_BOUNDS_WORD,
+    BVH_NODE_CHILD_1_WORD,
+    BVH_NODE_CHILD_2_WORD
+} from "../../gpu_primitive/bvh/BVH_BUFFER_LAYOUT.js";
+import { ensure_buffer_capacity } from "../make_temp_gpu_buffer.js";
+import { bvh2_derive_topology } from "./bvh2_derive_topology.js";
+import { GPUGeometryMeshletsBVH } from "./GPUGeometryMeshletsBVH.js";
+
+/**
+ * One row of the lookup table the traversal shaders read as `blas_lookup`.
+ *
+ * The row holds the arena node index a tree's root sits at. What the table is *indexed* by is not
+ * this manager's business — see {@link GPUGeometryBVHManager#publish_lookup}.
+ */
+export const BLAS_METADATA_STRUCT = WebGPUStruct.from({
+    // index of root node for BLAS
+    address: u32
+});
+
+/**
+ * Arena node index of the empty tree: what the lookup names for a geometry that has no tree yet.
+ *
+ * One internal node whose box is +inf below and -inf above. No ray enters it, so the ray queries
+ * pop it and miss; no point is within any distance of it, so the point queries prune it; and it is
+ * internal, so nothing ever fetches a triangle for it. Its children are itself, and are never
+ * descended into. Every traversal reads `blas_lookup[geometry_index]` and starts walking without a
+ * null check, so "no tree" has to be a tree — and it must not be whatever tree happens to sit at
+ * the arena's end, which is what a record resident over zero bytes used to point at.
+ *
+ * @type {number}
+ */
+export const BLAS_EMPTY_TREE_ADDRESS = 0;
+
+const DATA_SIZE_ALIGNMENT = 1024;
+const DATA_INITIAL_CAPACITY = round_up(1024, DATA_SIZE_ALIGNMENT);
+
+const DATA_GROWTH_STEP = 1024;
+const DATA_GROWTH_MULTIPLIER = 1.2;
+
+const endianness = platform_compute_endianness();
+
+/**
+ * Residency for BLAS node data: one arena buffer holding every registered tree's nodes, and a
+ * lookup buffer that maps *something else's* index onto an arena address.
+ *
+ * The split matters. This manager owns arena positions — it decides where a tree's nodes land and
+ * hands back the node index of its root. It does **not** own the index space the lookup is read by:
+ * every traversal shader does `blas_lookup[geometry_index]`, and geometry indices belong to
+ * {@link GPUGeometryManager}. So the table is published by whoever owns those indices, through
+ * {@link publish_lookup}; this manager only stores and uploads it.
+ *
+ * It used to allocate the lookup rows itself, from a pool of its own in BLAS-registration order.
+ * That agrees with geometry indices exactly until something takes a geometry index without taking a
+ * BLAS row — which per-instance clones do — after which every geometry resolved to another
+ * geometry's tree. See `blas_lookup_indexing.spec.js`.
+ */
+export class GPUGeometryBVHManager {
+
+    /**
+     *
+     * @type {GPUBuffer}
+     */
+    #buffer_metadata;
+
+    /**
+     *
+     * @returns {GPUBuffer}
+     */
+    get buffer_metadata() {
+        return this.#buffer_metadata;
+    }
+
+    /**
+     * @type {GPUBuffer}
+     */
+    #buffer_data;
+
+    /**
+     *
+     * @returns {GPUBuffer}
+     */
+    get buffer_data() {
+        return this.#buffer_data;
+    }
+
+    /**
+     * Used range end pointer
+     * @type {number}
+     */
+    #buffer_data_end = 0;
+
+    /**
+     * Parent of every node, and the node index of every leaf, for each *distinct topology* — one
+     * arena each, addressed like {@link #buffer_data}.
+     *
+     * Separate from the nodes because they are separate things. Node bounds are per instance: a
+     * skinned clone's are its own, recomputed every frame from its own deformed vertices. Parents
+     * and leaf positions are the shape of the tree, and every copy of a geometry has the same
+     * shape, so one derivation serves all of them.
+     *
+     * @type {GPUBuffer}
+     */
+    #buffer_parents;
+
+    /**
+     * @returns {GPUBuffer}
+     */
+    get buffer_parents() {
+        return this.#buffer_parents;
+    }
+
+    /**
+     * @type {GPUBuffer}
+     */
+    #buffer_leaf_nodes;
+
+    /**
+     * @returns {GPUBuffer}
+     */
+    get buffer_leaf_nodes() {
+        return this.#buffer_leaf_nodes;
+    }
+
+    #buffer_parents_end = 0;
+    #buffer_leaf_nodes_end = 0;
+
+    /**
+     * Topology by the geometry whose nodes it was derived from, shared by every copy of it.
+     *
+     * @type {Map<MeshletGeometry, {parents_offset: number, leaf_nodes_offset: number, leaf_count: number, node_count: number, resident: boolean, derived: {parents: Uint32Array, leaf_nodes: Uint32Array}}>}
+     */
+    #topology = new Map();
+
+    /**
+     *
+     * @type {number}
+     */
+    #node_capacity = 0;
+
+    /**
+     * Moves whenever the answer of {@link get_refit_target} may have changed for any owner: a tree's
+     * nodes uploaded, a shape uploaded, an owner removed. Registration alone does not move it —
+     * nothing a refit can read has changed until {@link update} runs.
+     *
+     * A consumer that builds tables from those answers keeps them until this moves. Coarse on
+     * purpose: one number to compare per frame, against asking per owner per frame. The price is a
+     * rebuild on any tree's residency change, not only on the consumer's own — accepted, and pinned.
+     *
+     * @type {number}
+     */
+    #residency_version = 0;
+
+    /**
+     * @returns {number}
+     */
+    get residency_version() {
+        return this.#residency_version;
+    }
+
+    /**
+     * @type {GPUDevice}
+     */
+    #device
+
+    /**
+     *
+     * @type {Map<MeshletGeometry, GPUGeometryMeshletsBVH>}
+     */
+    #map = new Map();
+
+    /**
+     * The queue is processed during {@link update}
+     * @type {Deque<GPUGeometryMeshletsBVH>}
+     */
+    #update_queue = new Deque();
+
+    /**
+     *
+     * @param {GPUDevice} device
+     */
+    constructor(device) {
+        this.#device = device;
+
+        this.#buffer_metadata = device.createBuffer({
+            label: "GPUGeometryBVHManager/metadata",
+            size: BLAS_METADATA_STRUCT.size * 16,
+            usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC | GPUBufferUsage.STORAGE,
+        });
+
+        this.#buffer_data = device.createBuffer({
+            label: "GPUGeometryBVHManager/data",
+            size: DATA_INITIAL_CAPACITY,
+            usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC | GPUBufferUsage.STORAGE,
+        });
+
+        this.#buffer_parents = device.createBuffer({
+            label: "GPUGeometryBVHManager/parents",
+            size: DATA_INITIAL_CAPACITY,
+            usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC | GPUBufferUsage.STORAGE,
+        });
+
+        this.#buffer_leaf_nodes = device.createBuffer({
+            label: "GPUGeometryBVHManager/leaf_nodes",
+            size: DATA_INITIAL_CAPACITY,
+            usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC | GPUBufferUsage.STORAGE,
+        });
+
+        // Node 0 is the empty tree, reserved before anything is appended — see BLAS_EMPTY_TREE_ADDRESS.
+        const empty_tree = new Uint32Array(BVH2_NODE_STRUCT.size / Uint32Array.BYTES_PER_ELEMENT);
+
+        new Float32Array(empty_tree.buffer, BVH_NODE_BOUNDS_WORD * Uint32Array.BYTES_PER_ELEMENT, 6)
+            .set([Infinity, Infinity, Infinity, -Infinity, -Infinity, -Infinity]);
+
+        empty_tree[BVH_NODE_CHILD_1_WORD] = BLAS_EMPTY_TREE_ADDRESS;
+        empty_tree[BVH_NODE_CHILD_2_WORD] = BLAS_EMPTY_TREE_ADDRESS;
+
+        device.queue.writeBuffer(this.#buffer_data, BLAS_EMPTY_TREE_ADDRESS * BVH2_NODE_STRUCT.size, empty_tree);
+
+        this.#buffer_data_end = BVH2_NODE_STRUCT.size;
+        this.#node_capacity = 1;
+    }
+
+    /**
+     * Arena node index of the tree a geometry traces while it has none of its own.
+     *
+     * @returns {number}
+     */
+    get empty_tree_address() {
+        return BLAS_EMPTY_TREE_ADDRESS;
+    }
+
+    get gpu_memory_usage() {
+        let r = 0;
+
+        if (this.#buffer_metadata) {
+            r += this.#buffer_metadata.size;
+        }
+
+        if (this.#buffer_data) {
+            r += this.#buffer_data.size;
+        }
+
+        if (this.#buffer_parents) {
+            r += this.#buffer_parents.size;
+        }
+
+        if (this.#buffer_leaf_nodes) {
+            r += this.#buffer_leaf_nodes.size;
+        }
+
+        return r;
+    }
+
+    /**
+     * The tree belonging to `owner`, registered against `source`'s shape if it does not exist yet.
+     *
+     * Two arguments rather than one because those are two different questions. `owner` is the
+     * identity the tree is looked up by; `source` is the geometry whose nodes it starts as. They
+     * coincide for anything that owns its geometry outright, and they do not for a per-instance
+     * copy — a skinned clone deforms its own vertices, so its bounds are its own and cannot be
+     * written into the tree everyone else is tracing, but its *shape* is by definition the
+     * source's. Keeping the two separate is what lets one derivation serve every copy.
+     *
+     * @param {object} owner identity to look this tree up by — a geometry, a clone's metadata row
+     * @param {MeshletGeometry} source geometry whose nodes this tree takes its shape and rest-pose
+     * bounds from
+     * @returns {GPUGeometryMeshletsBVH}
+     */
+    obtain(owner, source) {
+        assert.defined(owner, 'owner');
+        assert.equal(source.isMeshletGeometry, true, 'source.isMeshletGeometry !== true');
+
+        let bvh = this.#map.get(owner);
+
+        if (bvh === undefined) {
+            bvh = this.#register(owner, source);
+        }
+
+        return bvh;
+    }
+
+    /**
+     * Register a tree, keyed by whatever owns it.
+     *
+     * `owner` is the identity the tree is looked up by and `source` is the geometry whose nodes it
+     * holds. For an ordinary geometry those are the same object. For a per-instance copy they are
+     * not: the copy needs a node region of its own, because its bounds move independently, while
+     * the *shape* it is a copy of belongs to the source.
+     *
+     * @param {object} owner
+     * @param {MeshletGeometry} source
+     * @returns {GPUGeometryMeshletsBVH}
+     */
+    #register(owner, source) {
+
+        const bvh = new GPUGeometryMeshletsBVH();
+
+        // No bytes are taken now. The upload reads the geometry's tree as it is *then*, so a tree
+        // that arrives after registration is uploaded once it exists rather than never — and a
+        // geometry with none is not resident over nothing.
+        bvh.topology = this.#obtain_topology(source);
+
+        this.#map.set(owner, bvh);
+
+        this.#update_queue.add(bvh);
+
+        return bvh;
+    }
+
+    /**
+     * The parents/leaf-nodes derivation for a geometry, made once and shared by every tree that is
+     * a copy of it.
+     *
+     * @param {MeshletGeometry} source
+     * @returns {object} the topology record
+     */
+    #obtain_topology(source) {
+        let topology = this.#topology.get(source);
+
+        if (topology !== undefined) {
+            return topology;
+        }
+
+        // Derivation waits for {@link #upload_pending_topology}, beside the residency decision it
+        // feeds. A geometry can be registered before its BLAS bytes exist — nothing has to have
+        // built one yet — and a record that says "not resident" is the honest answer for that,
+        // rather than an empty derivation cached forever.
+        topology = {
+            source,
+            leaf_count: 0,
+            node_count: 0,
+            parents_offset: 0,
+            leaf_nodes_offset: 0,
+            resident: false,
+        };
+
+        this.#topology.set(source, topology);
+
+        return topology;
+    }
+
+    /**
+     * Everything a refit needs to find a resident tree, or `undefined` while it is not resident.
+     *
+     * "Resident" means the owner's nodes and its shape are both in their arenas, and that they are
+     * the same tree. A record snapshots its geometry's bytes when it is registered, and a geometry
+     * registered before its tree exists is uploaded as nothing — resident over zero bytes, at the
+     * arena's end. Its shape is derived later, from the bytes as they are then. Answering with that
+     * shape's counts at that record's address would hand a refit whichever tree was appended next,
+     * so the answer is withheld until the nodes actually uploaded are the tree the shape describes.
+     *
+     * @param {object} owner the identity passed to {@link obtain}
+     * @returns {{node_word_offset: number, node_count: number, leaf_count: number, parents_offset: number, leaf_nodes_offset: number}|undefined}
+     */
+    get_refit_target(owner) {
+        const bvh = this.#map.get(owner);
+
+        if (bvh === undefined || bvh.released || !bvh.resident || !bvh.topology.resident) {
+            return undefined;
+        }
+
+        if (bvh.uploaded_byte_length !== bvh.topology.node_count * BVH2_NODE_STRUCT.size) {
+            // the nodes in the arena are not the tree the shape was derived from
+            return undefined;
+        }
+
+        return {
+            node_word_offset: bvh.address * (BVH2_NODE_STRUCT.size / Uint32Array.BYTES_PER_ELEMENT),
+            node_count: bvh.topology.node_count,
+            leaf_count: bvh.topology.leaf_count,
+            parents_offset: bvh.topology.parents_offset,
+            leaf_nodes_offset: bvh.topology.leaf_nodes_offset,
+        };
+    }
+
+    /**
+     * Where a registered tree's root sits in the arena, or `undefined` while nothing is resident
+     * for this owner — either it was never registered, or {@link update} has not run since.
+     *
+     * @param {object} owner the identity passed to {@link obtain}
+     * @returns {number|undefined} arena node index
+     */
+    get_address(owner) {
+        const bvh = this.#map.get(owner);
+
+        if (bvh === undefined || bvh.released || !bvh.resident) {
+            return undefined;
+        }
+
+        return bvh.address;
+    }
+
+    /**
+     * Publish the lookup table the traversal shaders read.
+     *
+     * `addresses[i]` is the arena node index that index `i` resolves to. What `i` means is the
+     * caller's business — today it is a geometry index, and the shaders agree because
+     * {@link GPUGeometryManager} builds the table from the same ids it stamps into the geometry
+     * metadata buffer.
+     *
+     * @param {Uint32Array} addresses
+     */
+    publish_lookup(addresses) {
+        assert.defined(addresses, 'addresses');
+
+        this.#ensure_metadata_capacity(addresses.length);
+
+        this.#device.queue.writeBuffer(this.#buffer_metadata, 0, addresses, 0, addresses.length);
+    }
+
+    /**
+     * Release an owner's BLAS: the map entry is dropped, and the next {@link publish_lookup}
+     * stops naming its arena address. The append-only data region ({@link #buffer_data}) is not
+     * reclaimed — those bytes become unreferenced and are only recovered on a future buffer
+     * rebuild, a bounded residual versus the previous total leak (no entry was ever freed).
+     *
+     * @param {object} owner the identity passed to {@link obtain}
+     * @returns {boolean} true if a BLAS was registered for this owner and released
+     */
+    remove(owner) {
+        const bvh = this.#map.get(owner);
+
+        if (bvh === undefined) {
+            return false;
+        }
+
+        // may still be sitting in #update_queue if removed the same frame it was registered;
+        // the update pass skips released records
+        bvh.released = true;
+
+        this.#map.delete(owner);
+
+        this.#release_topology_if_orphaned(bvh.topology);
+
+        // a refit target that answered a moment ago answers `undefined` now
+        this.#residency_version += 1;
+
+        return true;
+    }
+
+    /**
+     * Drop a shape once the last tree that had it is gone.
+     *
+     * The arena bytes are not reclaimed — same append-only story as the nodes — but the map entry
+     * holds a strong reference to the geometry it is keyed by, so leaving it would keep every
+     * geometry a scene ever loaded alive for as long as the manager is.
+     *
+     * @param {object} topology
+     */
+    #release_topology_if_orphaned(topology) {
+        for (const bvh of this.#map.values()) {
+            if (bvh.topology === topology) {
+                return;
+            }
+        }
+
+        for (const [source, candidate] of this.#topology) {
+            if (candidate === topology) {
+                this.#topology.delete(source);
+
+                return;
+            }
+        }
+    }
+
+    /**
+     *
+     * @param {number} size
+     */
+    #ensure_data_capacity(size) {
+        if (this.#node_capacity >= size) {
+            // big enough already
+            return;
+        }
+
+        let new_size = size;
+
+        this.#node_capacity = new_size;
+
+        this.#buffer_data = ensure_buffer_capacity(
+            this.#device,
+            this.#buffer_data,
+            new_size * BVH2_NODE_STRUCT.size,
+            DATA_SIZE_ALIGNMENT,
+            DATA_GROWTH_STEP,
+            DATA_GROWTH_MULTIPLIER
+        );
+
+    }
+
+    /**
+     *
+     * @param {number} size
+     */
+    #ensure_metadata_capacity(row_count) {
+        this.#buffer_metadata = ensure_buffer_capacity(
+            this.#device,
+            this.#buffer_metadata,
+            Math.max(1, row_count) * BLAS_METADATA_STRUCT.size,
+            BLAS_METADATA_STRUCT.align,
+            16,
+            1.2
+        );
+    }
+
+    /**
+     * Append every topology derived but not yet uploaded to its arena.
+     *
+     * Queue-free: the map is small (one entry per distinct geometry) and a `resident` flag says what
+     * is left to do, which is one fewer thing to keep in step than a second queue would be.
+     *
+     * @returns {boolean} whether any shape became resident
+     */
+    #upload_pending_topology() {
+        const queue = this.#device.queue;
+
+        let uploaded = false;
+
+        for (const topology of this.#topology.values()) {
+            if (topology.resident) {
+                continue;
+            }
+
+            const bytes = topology.source.bvh;
+
+            if (bytes === undefined || bytes.byteLength === 0) {
+                // no tree to take the shape of yet; try again next time
+                continue;
+            }
+
+            const { parents, leaf_nodes } = bvh2_derive_topology(bytes);
+
+            this.#buffer_parents = ensure_buffer_capacity(
+                this.#device,
+                this.#buffer_parents,
+                (this.#buffer_parents_end + parents.length) * Uint32Array.BYTES_PER_ELEMENT,
+                DATA_SIZE_ALIGNMENT,
+                DATA_GROWTH_STEP,
+                DATA_GROWTH_MULTIPLIER
+            );
+
+            this.#buffer_leaf_nodes = ensure_buffer_capacity(
+                this.#device,
+                this.#buffer_leaf_nodes,
+                (this.#buffer_leaf_nodes_end + leaf_nodes.length) * Uint32Array.BYTES_PER_ELEMENT,
+                DATA_SIZE_ALIGNMENT,
+                DATA_GROWTH_STEP,
+                DATA_GROWTH_MULTIPLIER
+            );
+
+            topology.parents_offset = this.#buffer_parents_end;
+            topology.leaf_nodes_offset = this.#buffer_leaf_nodes_end;
+
+            queue.writeBuffer(
+                this.#buffer_parents,
+                topology.parents_offset * Uint32Array.BYTES_PER_ELEMENT,
+                parents, 0, parents.length
+            );
+
+            queue.writeBuffer(
+                this.#buffer_leaf_nodes,
+                topology.leaf_nodes_offset * Uint32Array.BYTES_PER_ELEMENT,
+                leaf_nodes, 0, leaf_nodes.length
+            );
+
+            this.#buffer_parents_end += parents.length;
+            this.#buffer_leaf_nodes_end += leaf_nodes.length;
+
+            topology.leaf_count = leaf_nodes.length;
+            // slots, not tree nodes — the arena numbers a tree's nodes with the free list's holes
+            // in, and a refit's arrival counters are indexed by that numbering
+            topology.node_count = parents.length;
+            topology.resident = true;
+
+            uploaded = true;
+        }
+
+        return uploaded;
+    }
+
+    /**
+     * Bring the arenas up to date with everything registered since the last call, and move the
+     * residency version if anything a refit reads has changed.
+     *
+     * Shapes first, and as their own question: they are not behind the node queue, so a frame in
+     * which a shape arrives for an already-uploaded record still uploads it — and still moves the
+     * version, because that record's refit answer has changed all the same.
+     */
+    update() {
+        const topology_uploaded = this.#upload_pending_topology();
+        const nodes_uploaded = this.#upload_pending_nodes();
+
+        if (topology_uploaded || nodes_uploaded) {
+            this.#residency_version += 1;
+        }
+    }
+
+    /**
+     * Append the nodes of every queued record whose geometry has a tree to the node arena.
+     *
+     * A record whose geometry has no tree yet stays queued: there is nothing to upload, and a record
+     * resident over zero bytes would answer with an address the next tree then occupies. It uploads
+     * on the first update after its bytes exist, from the bytes as they are then. A record removed
+     * before it was uploaded leaves the queue without uploading.
+     *
+     * @returns {boolean} whether anything became resident
+     */
+    #upload_pending_nodes() {
+        const queue = this.#update_queue;
+
+        const queue_size = queue.size();
+
+        if (queue_size === 0) {
+            // nothing to do
+            return false;
+        }
+
+        /** @type {{record: GPUGeometryMeshletsBVH, bytes: ArrayBuffer, offset: number}[]} */
+        const uploads = [];
+
+        /** @type {GPUGeometryMeshletsBVH[]} */
+        const waiting = [];
+
+        let total_byte_size = 0;
+        let used_node_count = 0;
+
+        for (let i = 0; i < queue_size; i++) {
+            const record = queue.getElementByIndex(i);
+
+            if (record.released) { continue; }
+
+            const bytes = record.topology.source.bvh;
+
+            if (bytes === undefined || bytes.byteLength === 0) {
+                // no tree yet; try again next time
+                waiting.push(record);
+
+                continue;
+            }
+
+            const node_count = bytes.byteLength / BVH2_NODE_STRUCT.size;
+
+            assert.isNonNegativeInteger(node_count, "node_count");
+
+            uploads.push({ record, bytes, offset: total_byte_size });
+
+            total_byte_size += bytes.byteLength;
+            used_node_count += node_count;
+        }
+
+        // Drained: what waits goes back in, what was released is gone. Leaving uploaded entries in
+        // the queue re-uploads every BLAS ever registered on each update and appends fresh copies
+        // at #buffer_data_end — quadratic memory growth until createBuffer fails.
+        queue.clear();
+
+        for (const record of waiting) {
+            queue.add(record);
+        }
+
+        if (uploads.length === 0) {
+            // nothing became resident, so nothing a refit reads has changed, and no consumer needs
+            // to ask again
+            return false;
+        }
+
+        console.log(`GPUGeometryBVHManager#update, uploading ${uploads.length} of ${queue_size} queued`);
+
+        this.#ensure_data_capacity(this.#node_capacity + used_node_count);
+
+
+        const device = this.#device;
+        const encoder = device.createCommandEncoder({
+            label: "GPUGeometryBVHManager#update"
+        });
+
+        const temp_data_buffer = device.createBuffer({
+            label: "temp_data_buffer",
+            usage: GPUBufferUsage.COPY_SRC,
+            size: total_byte_size,
+            mappedAtCreation: true
+        });
+
+        const mapped_temp_data = temp_data_buffer.getMappedRange();
+
+        // write to temp buffer
+        for (const { bytes, offset } of uploads) {
+            array_buffer_copy(bytes, 0, mapped_temp_data, offset, bytes.byteLength);
+        }
+
+        temp_data_buffer.unmap();
+
+        // copy data from temp buffer to where it needs to go
+        for (const { record, bytes, offset } of uploads) {
+            const address = this.#buffer_data_end;
+
+            record.address = address / BVH2_NODE_STRUCT.size;
+            record.resident = true;
+            record.bvh = bytes;
+            // what actually went into the arena, for `get_refit_target` to hold against the shape
+            record.uploaded_byte_length = bytes.byteLength;
+
+            // this.#buffer_data_end = roundUp(BVH8_INODE_STRUCT.align, this.#buffer_data_end + blas_size);
+            this.#buffer_data_end = address + bytes.byteLength;
+
+            encoder.copyBufferToBuffer(
+                temp_data_buffer, offset,
+                this.#buffer_data, address,
+                bytes.byteLength
+            );
+        }
+
+        console.warn(`BLAS size: ${number_format_by_thousands(this.#buffer_data_end)} bytes`);
+
+        device.queue.submit([encoder.finish()])
+
+        // free up the temp buffer
+        temp_data_buffer.destroy();
+
+        return true;
+    }
 }