npm - @woosh/meep-engine - Versions diffs - 3.21.0 → 3.23.0 - Mend

@woosh/meep-engine 3.21.0 → 3.23.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1803) hide show

package/src/shade/renderer/geometry/GPUGeometryManager.js CHANGED Viewed

@@ -1,591 +1,642 @@
-import { HashMap } from "../../../core/collection/map/HashMap.js";
-import { BLAS_EMPTY_TREE_ADDRESS } from "./bvh/GPUGeometryBVHManager.js";
-import { assert } from "../../../core/assert.js";
-import { BufferDescriptor } from "../../descriptor/buffer/BufferDescriptor.js";
-import { write_gpu_typed_buffer } from "../shader/type/serde/write_gpu_typed_buffer.js";
-import { inspect_gpu_buffer_typed } from "../buffer/inspect_gpu_buffer_typed.js";
-import { GPUGeometryBVHManager } from "./bvh/GPUGeometryBVHManager.js";
-import { GEOMETRY_METADATA_STRUCT } from "./GEOMETRY_METADATA_STRUCT.js";
-import { GPUGeometryMetadata } from "./GPUGeometryMetadata.js";
-import { GPUMeshletManager } from "./meshlet/GPUMeshletManager.js";
-const WORDS_PER_MEGABYTE = 1024 * 1024 / 4;
-/**
- * Manages geometry for indirect draw
- * Context represents a collection of geometries that are resident on the GPU and are ready to be used in indirect draw to draw entire scenes
- * @see https://gpuweb.github.io/gpuweb/#dom-gpurendercommandsmixin-drawindexedindirect
- */
-export class GPUGeometryManager {
-    /**
-     * @type {GPUDevice}
-     */
-    #device;
-    /**
-     * TODO make use of {@link GPUTypedTable} instead
-     * @type {GPUBuffer|null}
-     */
-    buffer_metadata = null;
-    /**
-     *
-     * @type {Map<MeshletGeometry, GPUGeometryMetadata>}
-     */
-    #geometries = new Map();
-    /**
-     * The source records by what their geometry *is*: keyed by meshlet content ({@link MeshletGeometry#hash}
-     * and {@link MeshletGeometry#equals}), holding every record with those meshlets — more than one
-     * only when the same meshlets arrived under trees of different sizes, which do not share.
-     *
-     * {@link #geometries} answers "is this object registered"; this answers "is this *geometry*
-     * registered, under any object". A character loaded from a file N times is N parses, each with
-     * its own `MeshletGeometry` of the same bytes; by object they were N rows, N vertex regions and
-     * N trees in the arena, and by content they are one record with N names.
-     *
-     * @type {HashMap<MeshletGeometry, GPUGeometryMetadata[]>}
-     */
-    #records_by_content = new HashMap();
-    /**
-     * Per-instance geometry clones — same source as a regular registered
-     * geometry, but with their own GPU vertex/metadata range so a
-     * skinning pass can deform them independently. Stored separately
-     * from {@link #geometries} because multiple clones can share one
-     * source `MeshletGeometry`, which the Map's by-object keying can't
-     * represent.
-     *
-     * Each entry's `geometry` field still points at the source's CPU
-     * `MeshletGeometry` (so bounds and index_count come from the same
-     * place) but `meshlets` is a fresh
-     * {@link MeshletBatchAllocationRecord} produced by
-     * {@link GPUMeshletManager#clone_batch_allocation}. The two
-     * collections share the same `index` space — `__last_geometry_index`
-     * advances for both.
-     *
-     * @type {GPUGeometryMetadata[]}
-     */
-    #clone_metadata = [];
-    /**
-     * Do not modify. The data is managed by this class, access in read-only mode.
-     * @return {Map<Readonly<MeshletGeometry>, Readonly<GPUGeometryMetadata>>}
-     */
-    get managed() {
-        return this.#geometries;
-    }
-    /**
-     *
-     * @type {number}
-     * @private
-     */
-    __last_geometry_index = 0;
-    /**
-     *
-     * @type {boolean}
-     * @private
-     */
-    __needs_update = true;
-    /**
-     * @type {GPUMeshletManager}
-     */
-    #meshlets;
-    /**
-     *
-     * @return {GPUMeshletManager}
-     */
-    get meshlets() {
-        return this.#meshlets;
-    }
-    /**
-     * To support RTX, this needs to be enabled
-     * @type {boolean}
-     */
-    #enable_bvh = true;
-    /**
-     * The BLAS manager's {@link GPUGeometryBVHManager#residency_version} the lookup was last
-     * published at. The lookup names an arena address per geometry id, and those change exactly
-     * when that version moves — on a scene edit, and on a tree arriving after its geometry did.
-     *
-     * @type {number}
-     */
-    #published_residency_version = -1;
-    /**
-     * Bottom-level acceleration structure (BVH for ray casting)
-     * @type {GPUGeometryBVHManager}
-     */
-    #blas
-    /**
-     *
-     * @returns {GPUGeometryBVHManager}
-     */
-    get blas() {
-        return this.#blas;
-    }
-    /**
-     *
-     * @return {GPUGeometrySDFManager}
-     */
-    get sdf() {
-        throw new Error("Not implemented");
-    }
-    /**
-     *
-     * @return {number} in bytes
-     */
-    get gpu_memory_usage() {
-        let r = 0;
-        if (this.buffer_metadata !== null) {
-            r += this.buffer_metadata.size;
-        }
-        if (this.#meshlets) {
-            r += this.#meshlets.gpu_memory_usage;
-        }
-        if (this.#blas) {
-            r += this.#blas.gpu_memory_usage;
-        }
-        return r;
-    }
-    /**
-     *
-     * @param {GPUDevice} device
-     */
-    constructor(device) {
-        this.#device = device;
-        this.#blas = new GPUGeometryBVHManager(device);
-        this.#meshlets = new GPUMeshletManager({ device });
-        this.buffer_metadata = device.createBuffer(BufferDescriptor.fromJSON({
-            label: "GPUGeometryContext/metadata",
-            size: 0,
-            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC,
-        }));
-    }
-    /**
-     *
-     * @param {GPUGeometryMetadata} geometry
-     * @return {number}
-     */
-    getAddress(geometry) {
-        const metadata = this.#geometries.get(geometry);
-        return metadata.index;
-    }
-    /**
-     *
-     * @param {MeshletGeometry} geometry
-     * @return {boolean}
-     */
-    has(geometry) {
-        return this.#geometries.has(geometry);
-    }
-    /**
-     *
-     * @param {MeshletGeometry} geometry
-     * @returns {boolean}
-     */
-    add(geometry) {
-        assert.defined(geometry, 'geometry');
-        assert.equal(geometry.isMeshletGeometry, true, 'geometry.isMeshletGeometry !== true');
-        if (this.has(geometry)) {
-            return false;
-        }
-        // Another object with the same meshlets under a tree of the same size is the same geometry
-        // as far as the GPU is concerned: one row, one vertex region, one tree in the arena — and
-        // this object becomes one more name for that record. The tree is measured, not compared:
-        // equal meshlets from one builder give one tree, and what must not share is the same
-        // meshlets with a tree and without one, which trace differently.
-        let bucket = this.#records_by_content.get(geometry);
-        if (bucket !== undefined) {
-            const tree_bytes = geometry.bvh?.byteLength ?? 0;
-            const shared = bucket.find(record => (record.geometry.bvh?.byteLength ?? 0) === tree_bytes);
-            if (shared !== undefined) {
-                shared.references += 1;
-                this.#geometries.set(geometry, shared);
-                return true;
-            }
-        }
-        const metadata = new GPUGeometryMetadata();
-        metadata.geometry = geometry;
-        metadata.references = 1;
-        metadata.allocated = false;
-        metadata.index = this.__last_geometry_index++;
-        const meshlets = geometry.meshlets;
-        metadata.meshlets = this.#meshlets.add_batch(meshlets);
-        // watch for data migration
-        metadata.meshlets.changed.add(() => {
-            // TODO need to handle this properly
-            console.warn('Meshlet GPU address changed.')
-        });
-        this.#geometries.set(geometry, metadata);
-        if (bucket === undefined) {
-            bucket = [];
-            this.#records_by_content.set(geometry, bucket);
-        }
-        bucket.push(metadata);
-        this.__needs_update = true;
-        return true;
-    }
-    /**
-     * Register a per-instance clone of `source_geometry`. The clone is
-     * a brand-new GPU geometry id that points at a fresh vertex /
-     * metadata range (allocated via
-     * {@link GPUMeshletManager#clone_batch_allocation}); the actual
-     * GPU-side memcpy + address-patch happens lazily on the next
-     * {@link update update(command_ctx)}.
-     *
-     * Use this when you need an instance to render against a *different
-     * copy* of the same mesh data — the canonical case being a
-     * `SkinnedMesh` whose vertex region needs to be deformed each frame
-     * without touching the source. Bounds and primitive count are
-     * inherited from `source_geometry`'s CPU object so they stay
-     * accurate under the initial copy; downstream passes refresh them
-     * once vertices actually move.
-     *
-     * Source registration is implicit — the source is `add()`-ed if it
-     * isn't already, so callers don't need to order things.
-     *
-     * @param {MeshletGeometry} source_geometry
-     * @returns {GPUGeometryMetadata} clone's metadata record. `.index`
-     *     is the geometry id to assign to an instance; `.meshlets`
-     *     carries the clone's GPU allocation (data + metadata offsets,
-     *     meshlet count) — needed by the skinning subsystem to wire
-     *     bindings against the right meshlet records.
-     */
-    add_clone(source_geometry) {
-        assert.defined(source_geometry, 'source_geometry');
-        assert.equal(source_geometry.isMeshletGeometry, true, 'source_geometry.isMeshletGeometry !== true');
-        // Idempotent — returns false if source is already registered.
-        // Either way, the source's metadata is in the map by the next
-        // line's lookup.
-        this.add(source_geometry);
-        const source_metadata = this.#geometries.get(source_geometry);
-        const clone_meshlets = this.#meshlets.clone_batch_allocation(source_metadata.meshlets);
-        const metadata = new GPUGeometryMetadata();
-        // The record's geometry, not the object the caller passed: the two are equal in content,
-        // but the BLAS manager keys a tree's *shape* by geometry object, and every clone of one
-        // record sharing one shape is what keeps N dancers from deriving and uploading N copies of it.
-        metadata.geometry = source_metadata.geometry;
-        metadata.allocated = false;
-        metadata.index = this.__last_geometry_index++;
-        metadata.meshlets = clone_meshlets;
-        this.#clone_metadata.push(metadata);
-        this.__needs_update = true;
-        return metadata;
-    }
-    /**
-     * Look up the source-side metadata record for a registered
-     * `MeshletGeometry`. Returns `undefined` if the geometry hasn't
-     * been registered.
-     *
-     * @param {MeshletGeometry} geometry
-     * @returns {GPUGeometryMetadata|undefined}
-     */
-    get_metadata(geometry) {
-        return this.#geometries.get(geometry);
-    }
-    /**
-     *
-     * @param {MeshletGeometry} geometry
-     * @returns {boolean}
-     */
-    remove(geometry) {
-        const metadata = this.#geometries.get(geometry);
-        if (metadata === undefined) {
-            return false;
-        }
-        this.#geometries.delete(geometry);
-        metadata.references -= 1;
-        if (metadata.references > 0) {
-            // other objects still name this record; nothing on the GPU changes
-            return true;
-        }
-        this.#forget_content(metadata);
-        // reclaim the meshlet data + metadata allocation (compaction-deferred) and the BLAS
-        // slot. Safe to free before the table rebuild below: the allocators hand out disjoint
-        // slices so other geometries are unaffected, and the rebuild drops this geometry's
-        // metadata row so nothing references the freed ranges afterward.
-        if (metadata.meshlets !== undefined) {
-            this.#meshlets.remove_batch(metadata.meshlets);
-        }
-        this.#blas.remove(metadata);
-        // rebuild the GPU metadata table without this entry — without the dirty flag the
-        // removed geometry's row stayed addressable with stale data until an unrelated add()
-        this.__needs_update = true;
-        // TODO context indices need to be updated
-        // NOTE: the BLAS append-only data region is not compacted, so its bytes for this
-        //       geometry are unreferenced until a future BVH buffer rebuild (bounded residual).
-        return true;
-    }
-    /**
-     * Take a record out of the by-content index, once nothing names it any more.
-     *
-     * @param {GPUGeometryMetadata} metadata
-     */
-    #forget_content(metadata) {
-        const bucket = this.#records_by_content.get(metadata.geometry);
-        if (bucket === undefined) {
-            return;
-        }
-        const index = bucket.indexOf(metadata);
-        if (index !== -1) {
-            bucket.splice(index, 1);
-        }
-        if (bucket.length === 0) {
-            this.#records_by_content.delete(metadata.geometry);
-        }
-    }
-    destroy() {
-        if (this.buffer_metadata !== null) {
-            this.buffer_metadata.destroy();
-        }
-        this.#meshlets.destroy();
-        // TODO ensure BVH and others are destroyed
-        this.__needs_update = true;
-    }
-    /**
-     * @param {ShadeGPUCommandContext} [command_ctx] — required when there
-     *     are queued meshlet clones to flush; passed through to
-     *     {@link GPUMeshletManager#update}. Older call sites that don't
-     *     register clones can omit it (the meshlet flush is a no-op when
-     *     nothing's pending).
-     */
-    update(command_ctx) {
-        const rebuilt = this.__needs_update;
-        if (rebuilt) {
-            console.time('Geometry build');
-            this.build();
-            console.timeEnd('Geometry build');
-            // this.#update_sdf(command_ctx);
-            this.__needs_update = false;
-        }
-        // Every call, not only after a scene edit: a tree whose bytes arrived after its geometry was
-        // registered uploads here, and the lookup follows it. Cheap when nothing is pending — a walk
-        // over the shapes and a look at the queue.
-        this.#blas.update();
-        // The lookup has a row per geometry id and an arena address in each, so it is republished
-        // when the ids changed (a rebuild) and when the addresses did (the residency version).
-        if (this.#enable_bvh && (rebuilt || this.#published_residency_version !== this.#blas.residency_version)) {
-            // after `#blas.update()`, which is what turns registrations into arena addresses
-            this.#publish_blas_lookup();
-            this.#published_residency_version = this.#blas.residency_version;
-        }
-        // Always drain — clones can be queued without `__needs_update`
-        // tripping (e.g. by direct callers of `meshlets.clone_batch_allocation`).
-        // No-op when the queue is empty.
-        if (command_ctx !== undefined) {
-            this.#meshlets.update(command_ctx);
-        }
-    }
-    /**
-     * Every geometry this manager has handed an id to — sources and per-instance clones alike —
-     * in index order.
-     *
-     * The two share the `__last_geometry_index` space, so every buffer laid out "by geometry id"
-     * is laid out over this one list: the geometry metadata rows, and the BLAS lookup. Having one
-     * answer to "what ids are there" is what keeps those two from drifting apart, which is exactly
-     * what happened while the BLAS lookup was indexed by a pool of its own.
-     *
-     * @returns {GPUGeometryMetadata[]}
-     */
-    #all_metadata_by_index() {
-        // a record with several names is one record, and one row
-        const all = [
-            ...new Set(this.#geometries.values()),
-            ...this.#clone_metadata,
-        ];
-        all.sort((a, b) => a.index - b.index);
-        return all;
-    }
-    /**
-     * Point every geometry id at the arena address of the tree it should trace against.
-     *
-     * One id, one tree, and the id is the key — which is the whole answer to a clone. A clone has a
-     * geometry id of its own because it has a vertex region of its own, and a tree of its own for
-     * the same reason: what deformation changes is its bounds, and those cannot be written into the
-     * tree every other instance is still tracing. What it does *not* need its own of is the shape,
-     * which the BLAS manager shares between them.
-     *
-     * Must run after {@link GPUGeometryBVHManager#update}, which is what makes addresses real.
-     */
-    #publish_blas_lookup() {
-        const all = this.#all_metadata_by_index();
-        const addresses = new Uint32Array(Math.max(1, this.__last_geometry_index));
-        for (const meta of all) {
-            // A geometry whose tree is not resident yet — registered before its bytes existed —
-            // traces the empty tree until it is. Every traversal starts walking from whatever the
-            // lookup names, so "no tree" has to be a tree, and not the one at the arena's end.
-            addresses[meta.index] = this.#blas.get_address(meta) ?? BLAS_EMPTY_TREE_ADDRESS;
-        }
-        this.#blas.publish_lookup(addresses);
-    }
-    build() {
-        // release currently-held resources
-        this.buffer_metadata.destroy();
-        const device = this.#device;
-        const all_metadata = this.#all_metadata_by_index();
-        // One tree per geometry id, clones included — keyed by the metadata row rather than by the
-        // geometry, because a clone and its source share a `MeshletGeometry` and would otherwise
-        // collide on it. The nodes are duplicated per clone on purpose (they are what deformation
-        // rewrites); the shape behind them is not.
-        if (this.#enable_bvh) {
-            for (const meta of all_metadata) {
-                this.#blas.obtain(meta, meta.geometry);
-            }
-        }
-        this.buffer_metadata = device.createBuffer(BufferDescriptor.fromJSON({
-            label: this.buffer_metadata.label,
-            size: Math.max(1, this.__last_geometry_index) * GEOMETRY_METADATA_STRUCT.size,
-            usage: this.buffer_metadata.usage,
-            mappedAtCreation: true
-        }));
-        // TODO limit mapped range
-        // TODO consider using queue.writeBuffer
-        const metadata = new DataView(this.buffer_metadata.getMappedRange());
-        // write metadata
-        for (let i = 0; i < all_metadata.length; i++) {
-            this.#write_geometry_metadata(all_metadata[i], metadata);
-        }
-        this.buffer_metadata.unmap();
-    }
-    async debug_inspect_gpu_metadata() {
-        const data = await inspect_gpu_buffer_typed({
-            buffer: this.buffer_metadata,
-            device: this.#device,
-            type: GEOMETRY_METADATA_STRUCT,
-            // one row per geometry id — sources and clones — not one per registered object, of
-            // which a record may have several
-            count: this.__last_geometry_index,
-        });
-        return data;
-    }
-    /**
-     * Write one row of the geometry metadata buffer. Works for both
-     * source geometries and clones — `g_meta.geometry` always points
-     * at the source's CPU `MeshletGeometry` (clones share it for bounds
-     * + primitive_count), while `g_meta.meshlets` carries the clone's
-     * own GPU allocation when this is a clone.
-     *
-     * @param {GPUGeometryMetadata} g_meta
-     * @param {DataView} metadata
-     */
-    #write_geometry_metadata(g_meta, metadata) {
-        const geometry = g_meta.geometry;
-        const idx = g_meta.index;
-        const offset = idx * GEOMETRY_METADATA_STRUCT.size;
-        // TODO fix this, assumes triangles currently
-        const indexCount = geometry.primitive_count * 3;
-        write_gpu_typed_buffer({
-            index_count: indexCount,
-            bounding_sphere: geometry.bounding_sphere,
-            bounding_box: geometry.bounding_box,
-            meshlets_address: g_meta.meshlets.metadata.offset,
-            meshlets_count: g_meta.meshlets.meshlet_count,
-        }, GEOMETRY_METADATA_STRUCT, metadata.buffer, offset);
-    }
-}
+import { HashMap } from "../../../core/collection/map/HashMap.js";
+import { BLAS_EMPTY_TREE_ADDRESS } from "./bvh/GPUGeometryBVHManager.js";
+import { assert } from "../../../core/assert.js";
+import { BufferDescriptor } from "../../descriptor/buffer/BufferDescriptor.js";
+import { write_gpu_typed_buffer } from "../shader/type/serde/write_gpu_typed_buffer.js";
+import { inspect_gpu_buffer_typed } from "../buffer/inspect_gpu_buffer_typed.js";
+import { GPUGeometryBVHManager } from "./bvh/GPUGeometryBVHManager.js";
+import { GEOMETRY_METADATA_STRUCT } from "./GEOMETRY_METADATA_STRUCT.js";
+import { GPUGeometryMetadata } from "./GPUGeometryMetadata.js";
+import { GPUMeshletManager } from "./meshlet/GPUMeshletManager.js";
+/**
+ * @typedef {import("../../device/ShadeGPUCommandContext.js").ShadeGPUCommandContext} ShadeGPUCommandContext
+ * @typedef {import("./MeshletGeometry.js").MeshletGeometry} MeshletGeometry
+ * @typedef {import("./sdf/GPUGeometrySDFManager.js").GPUGeometrySDFManager} GPUGeometrySDFManager
+ */
+const WORDS_PER_MEGABYTE = 1024 * 1024 / 4;
+/**
+ * Manages geometry for indirect draw
+ * Context represents a collection of geometries that are resident on the GPU and are ready to be used in indirect draw to draw entire scenes
+ * @see https://gpuweb.github.io/gpuweb/#dom-gpurendercommandsmixin-drawindexedindirect
+ */
+export class GPUGeometryManager {
+    /**
+     * @type {GPUDevice}
+     */
+    #device;
+    /**
+     * TODO make use of {@link GPUTypedTable} instead
+     * @type {GPUBuffer|null}
+     */
+    buffer_metadata = null;
+    /**
+     *
+     * @type {Map<MeshletGeometry, GPUGeometryMetadata>}
+     */
+    #geometries = new Map();
+    /**
+     * The source records by what their geometry *is*: keyed by meshlet content ({@link MeshletGeometry#hash}
+     * and {@link MeshletGeometry#equals}), holding every record with those meshlets — more than one
+     * only when the same meshlets arrived under trees of different sizes, which do not share.
+     *
+     * {@link #geometries} answers "is this object registered"; this answers "is this *geometry*
+     * registered, under any object". A character loaded from a file N times is N parses, each with
+     * its own `MeshletGeometry` of the same bytes; by object they were N rows, N vertex regions and
+     * N trees in the arena, and by content they are one record with N names.
+     *
+     * @type {HashMap<MeshletGeometry, GPUGeometryMetadata[]>}
+     */
+    #records_by_content = new HashMap();
+    /**
+     * Per-instance geometry clones — same source as a regular registered
+     * geometry, but with their own GPU vertex/metadata range so a
+     * skinning pass can deform them independently. Stored separately
+     * from {@link #geometries} because multiple clones can share one
+     * source `MeshletGeometry`, which the Map's by-object keying can't
+     * represent.
+     *
+     * Each entry's `geometry` field still points at the source's CPU
+     * `MeshletGeometry` (so bounds and index_count come from the same
+     * place) but `meshlets` is a fresh
+     * {@link MeshletBatchAllocationRecord} produced by
+     * {@link GPUMeshletManager#clone_batch_allocation}. The two
+     * collections share the same `index` space — `__last_geometry_index`
+     * advances for both.
+     *
+     * @type {GPUGeometryMetadata[]}
+     */
+    #clone_metadata = [];
+    /**
+     * Do not modify. The data is managed by this class, access in read-only mode.
+     * @return {Map<Readonly<MeshletGeometry>, Readonly<GPUGeometryMetadata>>}
+     */
+    get managed() {
+        return this.#geometries;
+    }
+    /**
+     *
+     * @type {number}
+     * @private
+     */
+    __last_geometry_index = 0;
+    /**
+     *
+     * @type {boolean}
+     * @private
+     */
+    __needs_update = true;
+    /**
+     * @type {GPUMeshletManager}
+     */
+    #meshlets;
+    /**
+     *
+     * @return {GPUMeshletManager}
+     */
+    get meshlets() {
+        return this.#meshlets;
+    }
+    /**
+     * To support RTX, this needs to be enabled
+     * @type {boolean}
+     */
+    #enable_bvh = true;
+    /**
+     * The BLAS manager's {@link GPUGeometryBVHManager#residency_version} the lookup was last
+     * published at. The lookup names an arena address per geometry id, and those change exactly
+     * when that version moves — on a scene edit, and on a tree arriving after its geometry did.
+     *
+     * @type {number}
+     */
+    #published_residency_version = -1;
+    /**
+     * Bottom-level acceleration structure (BVH for ray casting)
+     * @type {GPUGeometryBVHManager}
+     */
+    #blas
+    /**
+     *
+     * @returns {GPUGeometryBVHManager}
+     */
+    get blas() {
+        return this.#blas;
+    }
+    /**
+     *
+     * @return {GPUGeometrySDFManager}
+     */
+    get sdf() {
+        throw new Error("Not implemented");
+    }
+    /**
+     *
+     * @return {number} in bytes
+     */
+    get gpu_memory_usage() {
+        let r = 0;
+        if (this.buffer_metadata !== null) {
+            r += this.buffer_metadata.size;
+        }
+        if (this.#meshlets) {
+            r += this.#meshlets.gpu_memory_usage;
+        }
+        if (this.#blas) {
+            r += this.#blas.gpu_memory_usage;
+        }
+        return r;
+    }
+    /**
+     *
+     * @param {GPUDevice} device
+     */
+    constructor(device) {
+        this.#device = device;
+        this.#blas = new GPUGeometryBVHManager(device);
+        this.#meshlets = new GPUMeshletManager({ device });
+        this.buffer_metadata = device.createBuffer(BufferDescriptor.fromJSON({
+            label: "GPUGeometryContext/metadata",
+            size: 0,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC,
+        }));
+    }
+    /**
+     *
+     * @param {GPUGeometryMetadata} geometry
+     * @return {number}
+     */
+    getAddress(geometry) {
+        const metadata = this.#geometries.get(geometry);
+        return metadata.index;
+    }
+    /**
+     *
+     * @param {MeshletGeometry} geometry
+     * @return {boolean}
+     */
+    has(geometry) {
+        return this.#geometries.has(geometry);
+    }
+    /**
+     *
+     * @param {MeshletGeometry} geometry
+     * @returns {boolean}
+     */
+    add(geometry) {
+        assert.defined(geometry, 'geometry');
+        assert.equal(geometry.isMeshletGeometry, true, 'geometry.isMeshletGeometry !== true');
+        if (this.has(geometry)) {
+            return false;
+        }
+        // Another object with the same meshlets under a tree of the same size is the same geometry
+        // as far as the GPU is concerned: one row, one vertex region, one tree in the arena — and
+        // this object becomes one more name for that record. The tree is measured, not compared:
+        // equal meshlets from one builder give one tree, and what must not share is the same
+        // meshlets with a tree and without one, which trace differently.
+        let bucket = this.#records_by_content.get(geometry);
+        if (bucket !== undefined) {
+            const tree_bytes = geometry.bvh?.byteLength ?? 0;
+            const shared = bucket.find(record => (record.geometry.bvh?.byteLength ?? 0) === tree_bytes);
+            if (shared !== undefined) {
+                shared.references += 1;
+                this.#geometries.set(geometry, shared);
+                return true;
+            }
+        }
+        const metadata = new GPUGeometryMetadata();
+        metadata.geometry = geometry;
+        metadata.references = 1;
+        metadata.allocated = false;
+        metadata.index = this.__last_geometry_index++;
+        const meshlets = geometry.meshlets;
+        metadata.meshlets = this.#meshlets.add_batch(meshlets);
+        // watch for data migration
+        metadata.meshlets.changed.add(() => {
+            // TODO need to handle this properly
+            console.warn('Meshlet GPU address changed.')
+        });
+        this.#geometries.set(geometry, metadata);
+        if (bucket === undefined) {
+            bucket = [];
+            this.#records_by_content.set(geometry, bucket);
+        }
+        bucket.push(metadata);
+        this.__needs_update = true;
+        return true;
+    }
+    /**
+     * Register a per-instance clone of `source_geometry`. The clone is
+     * a brand-new GPU geometry id that points at a fresh vertex /
+     * metadata range (allocated via
+     * {@link GPUMeshletManager#clone_batch_allocation}); the actual
+     * GPU-side memcpy + address-patch happens lazily on the next
+     * {@link update update(command_ctx)}.
+     *
+     * Use this when you need an instance to render against a *different
+     * copy* of the same mesh data — the canonical case being a
+     * `SkinnedMesh` whose vertex region needs to be deformed each frame
+     * without touching the source. Bounds and primitive count are
+     * inherited from `source_geometry`'s CPU object so they stay
+     * accurate under the initial copy; downstream passes refresh them
+     * once vertices actually move.
+     *
+     * Source registration is implicit — the source is `add()`-ed if it
+     * isn't already, so callers don't need to order things.
+     *
+     * @param {MeshletGeometry} source_geometry
+     * @returns {GPUGeometryMetadata} clone's metadata record. `.index`
+     *     is the geometry id to assign to an instance; `.meshlets`
+     *     carries the clone's GPU allocation (data + metadata offsets,
+     *     meshlet count) — needed by the skinning subsystem to wire
+     *     bindings against the right meshlet records.
+     */
+    add_clone(source_geometry) {
+        assert.defined(source_geometry, 'source_geometry');
+        assert.equal(source_geometry.isMeshletGeometry, true, 'source_geometry.isMeshletGeometry !== true');
+        // Idempotent — returns false if source is already registered.
+        // Either way, the source's metadata is in the map by the next
+        // line's lookup.
+        this.add(source_geometry);
+        const source_metadata = this.#geometries.get(source_geometry);
+        const clone_meshlets = this.#meshlets.clone_batch_allocation(source_metadata.meshlets);
+        const metadata = new GPUGeometryMetadata();
+        // The record's geometry, not the object the caller passed: the two are equal in content,
+        // but the BLAS manager keys a tree's *shape* by geometry object, and every clone of one
+        // record sharing one shape is what keeps N dancers from deriving and uploading N copies of it.
+        metadata.geometry = source_metadata.geometry;
+        metadata.allocated = false;
+        metadata.index = this.__last_geometry_index++;
+        metadata.meshlets = clone_meshlets;
+        this.#clone_metadata.push(metadata);
+        this.__needs_update = true;
+        return metadata;
+    }
+    /**
+     * Release a per-instance clone: its meshlet data + metadata ranges go back to the
+     * allocators and its BLAS slot is dropped. The mirror of {@link add_clone}, and the
+     * clone half of what {@link remove} does for sources.
+     *
+     * No refcount and no by-content bookkeeping, unlike {@link remove}: a clone exists
+     * because exactly one instance needed a vertex region nobody else writes to, so the
+     * caller giving it back is the last reference by construction.
+     *
+     * The clone's geometry id is not recycled — ids are handed out monotonically and are
+     * baked into instance records, so reusing one would need to prove nothing still names
+     * it. What that leaves behind is one dead metadata row and one dead BLAS-lookup slot,
+     * tens of bytes against the vertex region this reclaims; the lookup already answers
+     * `BLAS_EMPTY_TREE_ADDRESS` for an id with no record, which is the empty tree.
+     *
+     * **The caller must have stopped naming it first.** A clone is named by the meshes-table
+     * row of the instance that renders it and by the skinning binding that deforms it; both
+     * have to be gone before the bytes are handed back, or a live pass reads a region that
+     * has been given to somebody else. {@link GPUMeshSkinningContext#release_clone} is the
+     * path that gets that order right.
+     *
+     * @param {GPUGeometryMetadata} metadata a record returned by {@link add_clone}
+     * @returns {boolean} true if the record was a clone of this manager's and was released
+     */
+    remove_clone(metadata) {
+        assert.defined(metadata, 'metadata');
+        const index = this.#clone_metadata.indexOf(metadata);
+        if (index === -1) {
+            return false;
+        }
+        this.#clone_metadata.splice(index, 1);
+        this.#meshlets.remove_batch(metadata.meshlets);
+        this.#blas.remove(metadata);
+        // without this the released clone's row stays addressable with stale data until an
+        // unrelated add() rebuilds the table — the same reason `remove` sets it
+        this.__needs_update = true;
+        return true;
+    }
+    /**
+     * Look up the source-side metadata record for a registered
+     * `MeshletGeometry`. Returns `undefined` if the geometry hasn't
+     * been registered.
+     *
+     * @param {MeshletGeometry} geometry
+     * @returns {GPUGeometryMetadata|undefined}
+     */
+    get_metadata(geometry) {
+        return this.#geometries.get(geometry);
+    }
+    /**
+     *
+     * @param {MeshletGeometry} geometry
+     * @returns {boolean}
+     */
+    remove(geometry) {
+        const metadata = this.#geometries.get(geometry);
+        if (metadata === undefined) {
+            return false;
+        }
+        this.#geometries.delete(geometry);
+        metadata.references -= 1;
+        if (metadata.references > 0) {
+            // other objects still name this record; nothing on the GPU changes
+            return true;
+        }
+        this.#forget_content(metadata);
+        // reclaim the meshlet data + metadata allocation (compaction-deferred) and the BLAS
+        // slot. Safe to free before the table rebuild below: the allocators hand out disjoint
+        // slices so other geometries are unaffected, and the rebuild drops this geometry's
+        // metadata row so nothing references the freed ranges afterward.
+        if (metadata.meshlets !== undefined) {
+            this.#meshlets.remove_batch(metadata.meshlets);
+        }
+        this.#blas.remove(metadata);
+        // rebuild the GPU metadata table without this entry — without the dirty flag the
+        // removed geometry's row stayed addressable with stale data until an unrelated add()
+        this.__needs_update = true;
+        // TODO context indices need to be updated
+        // NOTE: the BLAS append-only data region is not compacted, so its bytes for this
+        //       geometry are unreferenced until a future BVH buffer rebuild (bounded residual).
+        return true;
+    }
+    /**
+     * Take a record out of the by-content index, once nothing names it any more.
+     *
+     * @param {GPUGeometryMetadata} metadata
+     */
+    #forget_content(metadata) {
+        const bucket = this.#records_by_content.get(metadata.geometry);
+        if (bucket === undefined) {
+            return;
+        }
+        const index = bucket.indexOf(metadata);
+        if (index !== -1) {
+            bucket.splice(index, 1);
+        }
+        if (bucket.length === 0) {
+            this.#records_by_content.delete(metadata.geometry);
+        }
+    }
+    destroy() {
+        if (this.buffer_metadata !== null) {
+            this.buffer_metadata.destroy();
+        }
+        this.#meshlets.destroy();
+        // TODO ensure BVH and others are destroyed
+        this.__needs_update = true;
+    }
+    /**
+     * @param {ShadeGPUCommandContext} [command_ctx] — required when there
+     *     are queued meshlet clones to flush; passed through to
+     *     {@link GPUMeshletManager#update}. Older call sites that don't
+     *     register clones can omit it (the meshlet flush is a no-op when
+     *     nothing's pending).
+     */
+    update(command_ctx) {
+        const rebuilt = this.__needs_update;
+        if (rebuilt) {
+            console.time('Geometry build');
+            this.build();
+            console.timeEnd('Geometry build');
+            // this.#update_sdf(command_ctx);
+            this.__needs_update = false;
+        }
+        // Every call, not only after a scene edit: a tree whose bytes arrived after its geometry was
+        // registered uploads here, and the lookup follows it. Cheap when nothing is pending — a walk
+        // over the shapes and a look at the queue.
+        this.#blas.update();
+        // The lookup has a row per geometry id and an arena address in each, so it is republished
+        // when the ids changed (a rebuild) and when the addresses did (the residency version).
+        if (this.#enable_bvh && (rebuilt || this.#published_residency_version !== this.#blas.residency_version)) {
+            // after `#blas.update()`, which is what turns registrations into arena addresses
+            this.#publish_blas_lookup();
+            this.#published_residency_version = this.#blas.residency_version;
+        }
+        // Always drain — clones can be queued without `__needs_update`
+        // tripping (e.g. by direct callers of `meshlets.clone_batch_allocation`).
+        // No-op when the queue is empty.
+        if (command_ctx !== undefined) {
+            this.#meshlets.update(command_ctx);
+        }
+    }
+    /**
+     * Every geometry this manager has handed an id to — sources and per-instance clones alike —
+     * in index order.
+     *
+     * The two share the `__last_geometry_index` space, so every buffer laid out "by geometry id"
+     * is laid out over this one list: the geometry metadata rows, and the BLAS lookup. Having one
+     * answer to "what ids are there" is what keeps those two from drifting apart, which is exactly
+     * what happened while the BLAS lookup was indexed by a pool of its own.
+     *
+     * @returns {GPUGeometryMetadata[]}
+     */
+    #all_metadata_by_index() {
+        // a record with several names is one record, and one row
+        const all = [
+            ...new Set(this.#geometries.values()),
+            ...this.#clone_metadata,
+        ];
+        all.sort((a, b) => a.index - b.index);
+        return all;
+    }
+    /**
+     * Point every geometry id at the arena address of the tree it should trace against.
+     *
+     * One id, one tree, and the id is the key — which is the whole answer to a clone. A clone has a
+     * geometry id of its own because it has a vertex region of its own, and a tree of its own for
+     * the same reason: what deformation changes is its bounds, and those cannot be written into the
+     * tree every other instance is still tracing. What it does *not* need its own of is the shape,
+     * which the BLAS manager shares between them.
+     *
+     * Must run after {@link GPUGeometryBVHManager#update}, which is what makes addresses real.
+     */
+    #publish_blas_lookup() {
+        const all = this.#all_metadata_by_index();
+        const addresses = new Uint32Array(Math.max(1, this.__last_geometry_index));
+        for (const meta of all) {
+            // A geometry whose tree is not resident yet — registered before its bytes existed —
+            // traces the empty tree until it is. Every traversal starts walking from whatever the
+            // lookup names, so "no tree" has to be a tree, and not the one at the arena's end.
+            addresses[meta.index] = this.#blas.get_address(meta) ?? BLAS_EMPTY_TREE_ADDRESS;
+        }
+        this.#blas.publish_lookup(addresses);
+    }
+    build() {
+        // release currently-held resources
+        this.buffer_metadata.destroy();
+        const device = this.#device;
+        const all_metadata = this.#all_metadata_by_index();
+        // One tree per geometry id, clones included — keyed by the metadata row rather than by the
+        // geometry, because a clone and its source share a `MeshletGeometry` and would otherwise
+        // collide on it. The nodes are duplicated per clone on purpose (they are what deformation
+        // rewrites); the shape behind them is not.
+        if (this.#enable_bvh) {
+            for (const meta of all_metadata) {
+                this.#blas.obtain(meta, meta.geometry);
+            }
+        }
+        this.buffer_metadata = device.createBuffer(BufferDescriptor.fromJSON({
+            label: this.buffer_metadata.label,
+            size: Math.max(1, this.__last_geometry_index) * GEOMETRY_METADATA_STRUCT.size,
+            usage: this.buffer_metadata.usage,
+            mappedAtCreation: true
+        }));
+        // TODO limit mapped range
+        // TODO consider using queue.writeBuffer
+        const metadata = new DataView(this.buffer_metadata.getMappedRange());
+        // write metadata
+        for (let i = 0; i < all_metadata.length; i++) {
+            this.#write_geometry_metadata(all_metadata[i], metadata);
+        }
+        this.buffer_metadata.unmap();
+    }
+    async debug_inspect_gpu_metadata() {
+        const data = await inspect_gpu_buffer_typed({
+            buffer: this.buffer_metadata,
+            device: this.#device,
+            type: GEOMETRY_METADATA_STRUCT,
+            // one row per geometry id — sources and clones — not one per registered object, of
+            // which a record may have several
+            count: this.__last_geometry_index,
+        });
+        return data;
+    }
+    /**
+     * Write one row of the geometry metadata buffer. Works for both
+     * source geometries and clones — `g_meta.geometry` always points
+     * at the source's CPU `MeshletGeometry` (clones share it for bounds
+     * + primitive_count), while `g_meta.meshlets` carries the clone's
+     * own GPU allocation when this is a clone.
+     *
+     * @param {GPUGeometryMetadata} g_meta
+     * @param {DataView} metadata
+     */
+    #write_geometry_metadata(g_meta, metadata) {
+        const geometry = g_meta.geometry;
+        const idx = g_meta.index;
+        const offset = idx * GEOMETRY_METADATA_STRUCT.size;
+        // TODO fix this, assumes triangles currently
+        const indexCount = geometry.primitive_count * 3;
+        write_gpu_typed_buffer({
+            index_count: indexCount,
+            bounding_sphere: geometry.bounding_sphere,
+            bounding_box: geometry.bounding_box,
+            meshlets_address: g_meta.meshlets.metadata.offset,
+            meshlets_count: g_meta.meshlets.meshlet_count,
+        }, GEOMETRY_METADATA_STRUCT, metadata.buffer, offset);
+    }
+}