@woosh/meep-engine 3.2.0 → 3.4.0

package/src/shade/renderer/animation/GPUAnimationManager.js

@@ -287,7 +287,7 @@ export class GPUAnimationManager {
      *
      * Low-level `add_curve` deliberately stays uncached — every call
      * uploads — so existing callers that pre-build curves with
-     * distinct IDs (e.g. animation_prototype_stress's track pool)
+     * distinct IDs (e.g. a pre-built track pool)
      * keep their behavior.
      *
      * @type {WeakMap<AnimationCurve, number>}
@@ -972,7 +972,11 @@ export class GPUAnimationManager {
      *
      * Mesh→skin bindings register immediately via
      * {@link GPUMeshSkinningContext#bind}; the skinning context
-     * already tolerates pre-scene-build registration.
+     * already tolerates pre-scene-build registration. Each mesh also
+     * gets its {@link SkinnedMesh#skin} reference and a fresh set of
+     * bounds off it, synchronously — that part does not wait for
+     * `id_mapping`, because it reads the joints' `transform_global`
+     * rather than any GPU row.
      *
      * @param {Skin} skin
      * @returns {number} skin id (index into the `animation_skins` table)
@@ -1009,10 +1013,31 @@ export class GPUAnimationManager {
         // Bind every mesh into the skinning context. Idempotent and
         // pre-build tolerant — the binding upload defers until
         // id_mapping is ready.
+        //
+        // Each mesh also takes a reference to the CPU-side skin and
+        // re-derives its bounds off it. From here on the skin's
+        // formula is what places the mesh's vertices, and `Mesh`'s
+        // composition — rest-pose geometry under `transform_global` —
+        // is the wrong one, because the skinning pass cancels that
+        // transform back out (see {@link SkinnedMesh#updateBoundsBasic}).
+        // Nothing else would notice: bounds are refreshed by
+        // `updateMatrices`, and a character does not move again just
+        // because it finished loading.
         const skinning = this.#scene_context.skinning;
         const meshes = skin.meshes;
         for (let i = 0; i < meshes.length; i++) {
-            skinning.bind(meshes[i], skin_id);
+            const mesh = meshes[i];
+
+            skinning.bind(mesh, skin_id);
+
+            mesh.skin = skin;
+            mesh.updateBoundsBasic();
+
+            // The row the scene context published for this mesh holds the pre-skin bounds, and
+            // nothing about binding a skin looks like movement — `updateBoundsBasic` is not
+            // `updateMatrices` and does not touch the version the sync compares against. Without
+            // this the corrected box sits on the CPU object and never reaches the table.
+            mesh.needsUpdate = true;
         }
 
         // Try to complete now. If id_mapping is ready for every

package/src/shade/renderer/animation/Skin.d.ts

@@ -6,9 +6,12 @@
  *
  * Pure data. Knows nothing about the GPU. Consumed by
  * {@link GPUAnimationManager#register_skin}, which resolves each
- * joint's Node3D row from the scene context, stamps `skin_id` onto
- * every entry in {@link meshes}, and registers a skinning binding for
- * each one.
+ * joint's Node3D row from the scene context, registers a skinning
+ * binding for every entry in {@link meshes}, and points each of those
+ * meshes back here through {@link SkinnedMesh#skin} — the skin's
+ * joints are how a skinned mesh's world bounds are composed, so the
+ * mesh has to be able to reach them. The GPU-side `skin_id` is not
+ * stamped anywhere: it belongs to {@link GPUMeshSkinningContext}.
  *
  * Multiple meshes can share a skin (e.g. a character's body plus its
  * hair, both bound to the same skeleton). The loader populates
@@ -70,10 +73,9 @@ export class Skin {
     /**
      * Meshes that deform against this skin. Populated by the loader
      * (or by hand if you're constructing a skin programmatically).
-     * Used by {@link GPUAnimationManager#register_skin} to stamp the
-     * resolved `skin_id` onto each mesh and register its skinning
-     * binding — register_skin does not walk the scene graph looking
-     * for users.
+     * Used by {@link GPUAnimationManager#register_skin} to register
+     * each mesh's skinning binding and point it back at this skin —
+     * register_skin does not walk the scene graph looking for users.
      *
      * @type {SkinnedMesh[]}
      */

package/src/shade/renderer/animation/Skin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Skin.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/animation/Skin.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IA+CI;;;;;;;;;;;OAWG;IACH,6DARW;QACV,IAAU,CAAC,EAAE,MAAM,CAAC;QACpB,MAAY,EAAE,QAAQ,CAAC;QACvB,qBAA2B,EAAE,YAAY,CAAC;QAC1C,MAAY,CAAC,EAAE,aAAa,CAAC;KAC1B,GACS,IAAI,CAiBhB;IAxED;;;;OAIG;IACH,MAFU,MAAM,CAEN;IAEV;;;;;;;OAOG;IACH,QAFU,QAAQ,CAEN;IAEZ;;;;;;;;;;;;;OAaG;IACH,uBAFU,YAAY,CAEsB;IAE5C;;;;;;;;;OASG;IACH,QAFU,aAAa,CAEX;IA+BZ;;;;;;;;;;OAUG;IACH,YAFW,IAAI,QASd;IAED;;;;;;;OAOG;IACH,SAFa,IAAI,CAMhB;IAGL;;;OAGG;IACH,iBAFU,OAAO,CAEI;CANpB"}
+{"version":3,"file":"Skin.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/animation/Skin.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH;IA8CI;;;;;;;;;;;OAWG;IACH,6DARW;QACV,IAAU,CAAC,EAAE,MAAM,CAAC;QACpB,MAAY,EAAE,QAAQ,CAAC;QACvB,qBAA2B,EAAE,YAAY,CAAC;QAC1C,MAAY,CAAC,EAAE,aAAa,CAAC;KAC1B,GACS,IAAI,CAiBhB;IAvED;;;;OAIG;IACH,MAFU,MAAM,CAEN;IAEV;;;;;;;OAOG;IACH,QAFU,QAAQ,CAEN;IAEZ;;;;;;;;;;;;;OAaG;IACH,uBAFU,YAAY,CAEsB;IAE5C;;;;;;;;OAQG;IACH,QAFU,aAAa,CAEX;IA+BZ;;;;;;;;;;OAUG;IACH,YAFW,IAAI,QASd;IAED;;;;;;;OAOG;IACH,SAFa,IAAI,CAMhB;IAGL;;;OAGG;IACH,iBAFU,OAAO,CAEI;CANpB"}

package/src/shade/renderer/animation/Skin.js

@@ -8,9 +8,12 @@ import { assert } from "../../../core/assert.js";
  *
  * Pure data. Knows nothing about the GPU. Consumed by
  * {@link GPUAnimationManager#register_skin}, which resolves each
- * joint's Node3D row from the scene context, stamps `skin_id` onto
- * every entry in {@link meshes}, and registers a skinning binding for
- * each one.
+ * joint's Node3D row from the scene context, registers a skinning
+ * binding for every entry in {@link meshes}, and points each of those
+ * meshes back here through {@link SkinnedMesh#skin} — the skin's
+ * joints are how a skinned mesh's world bounds are composed, so the
+ * mesh has to be able to reach them. The GPU-side `skin_id` is not
+ * stamped anywhere: it belongs to {@link GPUMeshSkinningContext}.
  *
  * Multiple meshes can share a skin (e.g. a character's body plus its
  * hair, both bound to the same skeleton). The loader populates
@@ -58,10 +61,9 @@ export class Skin {
     /**
      * Meshes that deform against this skin. Populated by the loader
      * (or by hand if you're constructing a skin programmatically).
-     * Used by {@link GPUAnimationManager#register_skin} to stamp the
-     * resolved `skin_id` onto each mesh and register its skinning
-     * binding — register_skin does not walk the scene graph looking
-     * for users.
+     * Used by {@link GPUAnimationManager#register_skin} to register
+     * each mesh's skinning binding and point it back at this skin —
+     * register_skin does not walk the scene graph looking for users.
      *
      * @type {SkinnedMesh[]}
      */

package/src/shade/renderer/animation/compute_skin_world_bounds.d.ts

@@ -0,0 +1,35 @@
+/**
+ * World-space bounds of a mesh deformed by `skin`, in the pose the skin's joint nodes currently
+ * hold.
+ *
+ * **The mesh node's own transform does not appear here, and that is the point.** A skinned vertex
+ * lands at `mesh.global × inverse(mesh.global) × joint.global × inverse_bind × v` — the skinning
+ * pass applies the leftmost inverse (see `chunk_skin_blend_mesh_local`) and the rasterizer
+ * re-applies `mesh.global` afterwards, so the two cancel and the vertex is at
+ * `joint.global × inverse_bind × v`. Bounding a skinned mesh by putting its rest-pose geometry
+ * under `mesh.transform_global` therefore applies a transform the renderer cancels: on an
+ * FBX-derived glTF whose root node carries the file's centimetre→metre scale, it comes out 100×
+ * too small.
+ *
+ * The bound is the union over joints of `joint.global × inverse_bind` applied to the mesh-space
+ * geometry bounds. Conservative: each joint's product maps the whole geometry rather than the
+ * vertices that joint actually weights, and a skinned vertex is a convex combination of those
+ * per-joint images, which the enclosing (convex) AABB contains. In the case that matters it is also
+ * *tight* — with every joint at its bind pose `joint.global × inverse_bind` collapses to one and
+ * the same matrix, the character's placement in the world, so the union is a single exact box.
+ *
+ * **Pose freshness is the caller's problem.** Joints driven by the GPU pose accumulator are
+ * {@link TransformAuthority.GPU}, and their `transform_global` stays at the rest pose the CPU
+ * seeded — so for an animated character this is a rest-pose bound that tracks placement, not the
+ * deformed silhouette. The per-frame deformed world box lives in the scene database's `meshes` row,
+ * published by the skinning pass's bounds-refresh chain, and anything that needs the real thing
+ * reads it there.
+ *
+ * @param {Skin} skin
+ * @param {ArrayLike<number>} mesh_box mesh-space AABB, 6 floats — `(low_x, low_y, low_z, high_x, high_y, high_z)`
+ * @param {ArrayLike<number>} mesh_sphere mesh-space sphere, 4 floats — `(x, y, z, radius)`
+ * @param {Float32Array|number[]} out_box receives the world AABB, 6 floats
+ * @param {Float32Array|number[]} out_sphere receives the world sphere, 4 floats
+ */
+export function compute_skin_world_bounds(skin: Skin, mesh_box: ArrayLike<number>, mesh_sphere: ArrayLike<number>, out_box: Float32Array | number[], out_sphere: Float32Array | number[]): void;
+//# sourceMappingURL=compute_skin_world_bounds.d.ts.map

package/src/shade/renderer/animation/compute_skin_world_bounds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compute_skin_world_bounds.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/animation/compute_skin_world_bounds.js"],"names":[],"mappings":"AAgDA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,gEALW,UAAU,MAAM,CAAC,eACjB,UAAU,MAAM,CAAC,WACjB,YAAY,GAAC,MAAM,EAAE,cACrB,YAAY,GAAC,MAAM,EAAE,QAkE/B"}

package/src/shade/renderer/animation/compute_skin_world_bounds.js

@@ -0,0 +1,146 @@
+import { assert } from "../../../core/assert.js";
+import { aabb3_matrix4_project } from "../../../core/geom/3d/aabb/aabb3_matrix4_project.js";
+import { m4_multiply } from "../../../core/geom/3d/mat4/m4_multiply.js";
+import { sphere_matrix4_transform } from "../../../core/geom/3d/sphere/sphere_matrix4_transform.js";
+import {
+    sphere_compute_bounding_of_spheres
+} from "../../../core/geom/packing/sphere_compute_bounding_of_spheres.js";
+
+/**
+ * One joint's `joint.global × inverse_bind`, rebuilt per joint. Module-level so a walk over a
+ * 65-joint skeleton does not allocate a matrix per joint.
+ *
+ * @type {Float64Array}
+ */
+const _scratch_skin_matrix = new Float64Array(16);
+
+/**
+ * One joint's inverse-bind matrix, copied out of the skin's flat array. A `subarray` view would
+ * read the same 16 floats but allocate an object per joint per call, and this runs whenever a
+ * character moves.
+ *
+ * @type {Float64Array}
+ */
+const _scratch_inverse_bind = new Float64Array(16);
+
+/**
+ * One joint's projected AABB, before it is folded into the running union.
+ *
+ * @type {Float64Array}
+ */
+const _scratch_box = new Float64Array(6);
+
+/**
+ * One joint's projected sphere, before it is copied into {@link _scratch_spheres}.
+ *
+ * @type {Float64Array}
+ */
+const _scratch_sphere = new Float64Array(4);
+
+/**
+ * Per-joint `(cx, cy, cz, r)` spheres, handed to
+ * {@link sphere_compute_bounding_of_spheres} in one go. Grown to the largest joint count seen so
+ * far and never shrunk.
+ *
+ * @type {Float64Array}
+ */
+let _scratch_spheres = new Float64Array(0);
+
+/**
+ * World-space bounds of a mesh deformed by `skin`, in the pose the skin's joint nodes currently
+ * hold.
+ *
+ * **The mesh node's own transform does not appear here, and that is the point.** A skinned vertex
+ * lands at `mesh.global × inverse(mesh.global) × joint.global × inverse_bind × v` — the skinning
+ * pass applies the leftmost inverse (see `chunk_skin_blend_mesh_local`) and the rasterizer
+ * re-applies `mesh.global` afterwards, so the two cancel and the vertex is at
+ * `joint.global × inverse_bind × v`. Bounding a skinned mesh by putting its rest-pose geometry
+ * under `mesh.transform_global` therefore applies a transform the renderer cancels: on an
+ * FBX-derived glTF whose root node carries the file's centimetre→metre scale, it comes out 100×
+ * too small.
+ *
+ * The bound is the union over joints of `joint.global × inverse_bind` applied to the mesh-space
+ * geometry bounds. Conservative: each joint's product maps the whole geometry rather than the
+ * vertices that joint actually weights, and a skinned vertex is a convex combination of those
+ * per-joint images, which the enclosing (convex) AABB contains. In the case that matters it is also
+ * *tight* — with every joint at its bind pose `joint.global × inverse_bind` collapses to one and
+ * the same matrix, the character's placement in the world, so the union is a single exact box.
+ *
+ * **Pose freshness is the caller's problem.** Joints driven by the GPU pose accumulator are
+ * {@link TransformAuthority.GPU}, and their `transform_global` stays at the rest pose the CPU
+ * seeded — so for an animated character this is a rest-pose bound that tracks placement, not the
+ * deformed silhouette. The per-frame deformed world box lives in the scene database's `meshes` row,
+ * published by the skinning pass's bounds-refresh chain, and anything that needs the real thing
+ * reads it there.
+ *
+ * @param {Skin} skin
+ * @param {ArrayLike<number>} mesh_box mesh-space AABB, 6 floats — `(low_x, low_y, low_z, high_x, high_y, high_z)`
+ * @param {ArrayLike<number>} mesh_sphere mesh-space sphere, 4 floats — `(x, y, z, radius)`
+ * @param {Float32Array|number[]} out_box receives the world AABB, 6 floats
+ * @param {Float32Array|number[]} out_sphere receives the world sphere, 4 floats
+ */
+export function compute_skin_world_bounds(skin, mesh_box, mesh_sphere, out_box, out_sphere) {
+    assert.defined(skin, 'skin');
+    assert.equal(skin.isSkin, true, 'skin.isSkin !== true');
+    assert.isArrayLike(mesh_box, 'mesh_box');
+    assert.isArrayLike(mesh_sphere, 'mesh_sphere');
+    assert.notEqual(out_box, mesh_box, 'out_box and mesh_box must be different objects');
+
+    const joints = skin.joints;
+    const joint_count = joints.length;
+
+    assert.greaterThan(joint_count, 0, 'skin.joints.length');
+
+    const inverse_bind = skin.inverse_bind_matrices;
+
+    assert.greaterThanOrEqual(
+        inverse_bind.length, joint_count * 16,
+        'skin.inverse_bind_matrices.length'
+    );
+
+    if (_scratch_spheres.length < joint_count * 4) {
+        _scratch_spheres = new Float64Array(joint_count * 4);
+    }
+
+    let low_x = Infinity, low_y = Infinity, low_z = Infinity;
+    let high_x = -Infinity, high_y = -Infinity, high_z = -Infinity;
+
+    for (let j = 0; j < joint_count; j++) {
+
+        const inverse_bind_offset = j * 16;
+
+        for (let k = 0; k < 16; k++) {
+            _scratch_inverse_bind[k] = inverse_bind[inverse_bind_offset + k];
+        }
+
+        // a Transform64's matrix starts at element 0, so the transform is its own mat4 argument
+        m4_multiply(_scratch_skin_matrix, joints[j].transform_global, _scratch_inverse_bind);
+
+        aabb3_matrix4_project(_scratch_box, mesh_box, _scratch_skin_matrix);
+
+        if (_scratch_box[0] < low_x) low_x = _scratch_box[0];
+        if (_scratch_box[1] < low_y) low_y = _scratch_box[1];
+        if (_scratch_box[2] < low_z) low_z = _scratch_box[2];
+        if (_scratch_box[3] > high_x) high_x = _scratch_box[3];
+        if (_scratch_box[4] > high_y) high_y = _scratch_box[4];
+        if (_scratch_box[5] > high_z) high_z = _scratch_box[5];
+
+        sphere_matrix4_transform(_scratch_sphere, mesh_sphere, _scratch_skin_matrix);
+
+        const sphere_offset = j * 4;
+
+        _scratch_spheres[sphere_offset] = _scratch_sphere[0];
+        _scratch_spheres[sphere_offset + 1] = _scratch_sphere[1];
+        _scratch_spheres[sphere_offset + 2] = _scratch_sphere[2];
+        _scratch_spheres[sphere_offset + 3] = _scratch_sphere[3];
+    }
+
+    out_box[0] = low_x;
+    out_box[1] = low_y;
+    out_box[2] = low_z;
+    out_box[3] = high_x;
+    out_box[4] = high_y;
+    out_box[5] = high_z;
+
+    sphere_compute_bounding_of_spheres(out_sphere, _scratch_spheres, 0, joint_count, 3);
+}

package/src/shade/renderer/animation/skinning/GPUMeshSkinningContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUMeshSkinningContext.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/animation/skinning/GPUMeshSkinningContext.js"],"names":[],"mappings":"AAyEA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;IA2MI;;;;;;;OAOG;IACH,sEAPW;QACV,UAAgB,qBAAqB;QACrC,iBAAuB,sBAAsB;QAC7C,aAAmB,kBAAkB;QACrC,MAAY,YAAY;KACrB,EAYH;IAED;;;;;;OAMG;IACH,iCAEC;IAED;;;;;;OAMG;IACH,2BAEC;IAED;;;;;;;OAOG;IACH,wCAEC;IAED;;;;;;;;;;;;;;OAcG;IACH,mCAFa,MAAM,CAelB;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,iCAFW,MAAM,QAmBhB;IAED;;;;;;;OAOG;IACH,gCAFa,MAAM,GAAC,SAAS,CAI5B;IAED;;;;;;;;;;OAUG;IACH,gCAYC;IAED;;;;;;;;OAQG;IACH,4BAFW,MAAM,QAYhB;IAyCD;;;;;;;;;;;;;;;OAeG;IACH,8CA+MC;IA0QD,gBAiBC;;CACJ"}
+{"version":3,"file":"GPUMeshSkinningContext.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/animation/skinning/GPUMeshSkinningContext.js"],"names":[],"mappings":"AA0EA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH;IA2MI;;;;;;;OAOG;IACH,sEAPW;QACV,UAAgB,qBAAqB;QACrC,iBAAuB,sBAAsB;QAC7C,aAAmB,kBAAkB;QACrC,MAAY,YAAY;KACrB,EAYH;IAED;;;;;;OAMG;IACH,iCAEC;IAED;;;;;;OAMG;IACH,2BAEC;IAED;;;;;;;OAOG;IACH,wCAEC;IAED;;;;;;;;;;;;;;OAcG;IACH,mCAFa,MAAM,CAelB;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,iCAFW,MAAM,QAmBhB;IAED;;;;;;;OAOG;IACH,gCAFa,MAAM,GAAC,SAAS,CAI5B;IAED;;;;;;;;;;OAUG;IACH,gCAYC;IAED;;;;;;;;OAQG;IACH,4BAFW,MAAM,QAYhB;IAyCD;;;;;;;;;;;;;;;OAeG;IACH,8CA2NC;IAsSD,gBAiBC;;CACJ"}

package/src/shade/renderer/animation/skinning/GPUMeshSkinningContext.js

@@ -26,6 +26,7 @@ import {
 import {
     MESHLET_METADATA_STRUCT
 } from "../../geometry/meshlet/encoding/MESHLET_METADATA_STRUCT.js";
+import { record_blas_refit } from "../../geometry/bvh/record_blas_refit.js";
 
 /**
  * Initial bindings-buffer capacity (in binding records). 16 × 16 bytes
@@ -737,6 +738,44 @@ export class GPUMeshSkinningContext {
                 });
             }
         }
+
+        // ── 5. BLAS refit: the clone's tree catches up with its vertices ──
+        //
+        // The chain above fixes what the *rasterizer* culls by — meshlet boxes, a mesh sphere. A
+        // ray does not consult any of those; it walks the clone's BLAS, whose boxes still describe
+        // the rest pose. Left alone, a deformed limb traces against the tree of the pose it is no
+        // longer in: rays miss where the mesh now is and hit where it no longer is.
+        //
+        // Topology is untouched. Refitting a tree whose triangles moved but whose shape did not is
+        // two dispatches, against the full build's sort-and-emit — which is why a clone gets a copy
+        // of the source's nodes rather than a build of its own.
+        this.#record_blas_refits(cmd_ctx);
+    }
+
+    /**
+     * Refit every skinned clone's BLAS against the vertices this frame's skinning just deformed.
+     *
+     * Per binding rather than per dispatch-pair: a refit is scoped to a tree, and a clone has one.
+     *
+     * @param {ShadeGPUCommandContext} cmd_ctx
+     */
+    #record_blas_refits(cmd_ctx) {
+        const geometries = this.#geometries;
+        const blas = geometries.blas;
+
+        if (blas === undefined) {
+            // BVH support is off; nothing traces these trees
+            return;
+        }
+
+        for (const binding of this.#bindings) {
+            record_blas_refit(cmd_ctx, {
+                blas,
+                geometries,
+                owner: binding.clone_metadata,
+                geometry_index: binding.clone_geometry_index,
+            });
+        }
     }
 
     /**
@@ -758,6 +797,8 @@ export class GPUMeshSkinningContext {
             clone_meshlet_metadata_offset,
             meshlet_count,
             clone_geometry_index: clone_metadata.index,
+            // the identity the clone's BLAS is registered under, for the per-frame refit
+            clone_metadata,
         });
         this.#total_meshlet_count += meshlet_count;
         this.#bindings_dirty = true;

package/src/shade/renderer/geometry/GPUGeometryManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUGeometryManager.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/geometry/GPUGeometryManager.js"],"names":[],"mappings":"AAWA;;;;GAIG;AACH;IA8HI;;;OAGG;IACH,+BAUC;IAtID;;;OAGG;IACH,iBAFU,YAAU,IAAI,CAED;IA4BvB;;;OAGG;IACH,mEAEC;IAED;;;;OAIG;IACH,8BAA0B;IAE1B;;;;OAIG;IACH,uBAAsB;IAOtB;;;OAGG;IACH,kCAEC;IAeD;;;OAGG;IACH,kCAEC;IAGD;;;OAGG;IACH,iCAEC;IAED;;;OAGG;IACH,+BAiBC;IAkBD;;;;OAIG;IACH,qBAHW,mBAAmB,GAClB,MAAM,CAMjB;IAED;;;;OAIG;IACH,gCAFY,OAAO,CAIlB;IAGD;;;;OAIG;IACH,gCAFa,OAAO,CAqCnB;IAED;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,6CANa,mBAAmB,CA8B/B;IAED;;;;;;;OAOG;IACH,yCAFa,mBAAmB,GAAC,SAAS,CAIzC;IAED;;;;OAIG;IACH,mCAFa,OAAO,CA6BnB;IAED,gBAWC;IAED;;;;;;OAMG;IACH,mDAqBC;IAED,cA0CC;IAED,0CASC;;CA+BJ;oCAxbmC,0BAA0B;kCAC5B,gCAAgC;sCAH5B,gCAAgC"}
+{"version":3,"file":"GPUGeometryManager.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/geometry/GPUGeometryManager.js"],"names":[],"mappings":"AAWA;;;;GAIG;AACH;IA8HI;;;OAGG;IACH,+BAUC;IAtID;;;OAGG;IACH,iBAFU,YAAU,IAAI,CAED;IA4BvB;;;OAGG;IACH,mEAEC;IAED;;;;OAIG;IACH,8BAA0B;IAE1B;;;;OAIG;IACH,uBAAsB;IAOtB;;;OAGG;IACH,kCAEC;IAeD;;;OAGG;IACH,kCAEC;IAGD;;;OAGG;IACH,iCAEC;IAED;;;OAGG;IACH,+BAiBC;IAkBD;;;;OAIG;IACH,qBAHW,mBAAmB,GAClB,MAAM,CAMjB;IAED;;;;OAIG;IACH,gCAFY,OAAO,CAIlB;IAGD;;;;OAIG;IACH,gCAFa,OAAO,CAqCnB;IAED;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,6CANa,mBAAmB,CA8B/B;IAED;;;;;;;OAOG;IACH,yCAFa,mBAAmB,GAAC,SAAS,CAIzC;IAED;;;;OAIG;IACH,mCAFa,OAAO,CA6BnB;IAED,gBAWC;IAED;;;;;;OAMG;IACH,mDA0BC;IAsDD,cAmCC;IAED,0CASC;;CA+BJ;oCA1emC,0BAA0B;kCAC5B,gCAAgC;sCAH5B,gCAAgC"}

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

@@ -304,7 +304,7 @@ export class GPUGeometryManager {
         if (metadata.meshlets !== undefined) {
             this.#meshlets.remove_batch(metadata.meshlets);
         }
-        this.#blas.remove(geometry);
+        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()
@@ -347,6 +347,11 @@ export class GPUGeometryManager {
             this.#blas.update();
             console.timeEnd('BVH update');
 
+            if (this.#enable_bvh) {
+                // after `#blas.update()`, which is what turns registrations into arena addresses
+                this.#publish_blas_lookup();
+            }
+
             // this.#update_sdf(command_ctx);
 
             this.__needs_update = false;
@@ -360,28 +365,73 @@ export class GPUGeometryManager {
         }
     }
 
+    /**
+     * 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() {
+        const all = [
+            ...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) {
+            const address = this.#blas.get_address(meta);
+
+            assert.defined(
+                address,
+                `geometry ${meta.index} has no BLAS; every geometry a ray can hit needs one`
+            );
+
+            addresses[meta.index] = address;
+        }
+
+        this.#blas.publish_lookup(addresses);
+    }
+
     build() {
         // release currently-held resources
         this.buffer_metadata.destroy();
 
         const device = this.#device;
 
-        // Walk both source geometries and per-instance clones in a
-        // single index-sorted pass. They share the `__last_geometry_index`
-        // space, so the metadata buffer's row layout is just "everything
-        // by index" — the consumer doesn't see the distinction.
-        const all_metadata = [
-            ...this.#geometries.values(),
-            ...this.#clone_metadata,
-        ];
-
-        all_metadata.sort((a, b) => a.index - b.index);
+        const all_metadata = this.#all_metadata_by_index();
 
-        // BVH only needs source geometries — clones share the source's
-        // shape, so building a BLAS per clone would be wasted work.
+        // 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 this.#geometries.values()) {
-                this.#blas.obtain(meta.geometry);
+            for (const meta of all_metadata) {
+                this.#blas.obtain(meta, meta.geometry);
             }
         }
 

package/src/shade/renderer/geometry/bvh/GPUGeometryBVHManager.d.ts

@@ -1,4 +1,25 @@
+/**
+ * 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;
+/**
+ * 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 {
     /**
      *
@@ -15,23 +36,73 @@ export class GPUGeometryBVHManager {
      * @returns {GPUBuffer}
      */
     get buffer_data(): GPUBuffer;
+    /**
+     * @returns {GPUBuffer}
+     */
+    get buffer_parents(): GPUBuffer;
+    /**
+     * @returns {GPUBuffer}
+     */
+    get buffer_leaf_nodes(): GPUBuffer;
     get gpu_memory_usage(): number;
     /**
+     * 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 {MeshletGeometry} meshlets
+     * @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(meshlets: MeshletGeometry): GPUGeometryMeshletsBVH;
+    obtain(owner: object, source: MeshletGeometry): GPUGeometryMeshletsBVH;
+    /**
+     * 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: object): {
+        node_word_offset: number;
+        node_count: number;
+        leaf_count: number;
+        parents_offset: number;
+        leaf_nodes_offset: number;
+    } | undefined;
+    /**
+     * 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: object): number | undefined;
+    /**
+     * 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: Uint32Array): void;
     /**
-     * Release a geometry's BLAS. The metadata slot is returned to the pool for reuse and the
-     * map entry is dropped. The append-only data region ({@link #buffer_data}) is not
+     * 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 {MeshletGeometry} meshlets the key passed to {@link obtain}
-     * @returns {boolean} true if a BLAS was registered for this geometry and released
+     * @param {object} owner the identity passed to {@link obtain}
+     * @returns {boolean} true if a BLAS was registered for this owner and released
      */
-    remove(meshlets: MeshletGeometry): boolean;
+    remove(owner: object): boolean;
     update(): void;
     #private;
 }

package/src/shade/renderer/geometry/bvh/GPUGeometryBVHManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUGeometryBVHManager.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/bvh/GPUGeometryBVHManager.js"],"names":[],"mappings":"AAaA,gDAGG;AAUH;IA4DI;;;OAGG;IACH,+BAeC;IAvED;;;OAGG;IACH,iCAEC;IAOD;;;OAGG;IACH,6BAEC;IAsDD,+BAYC;IAED;;;;OAIG;IACH,mCAFa,sBAAsB,CAYlC;IAqBD;;;;;;;;OAQG;IACH,mCAFa,OAAO,CAiBnB;IA6DD,eAqJC;;CACJ;6BAhY4B,mCAAmC;uCAGzB,6BAA6B"}
+{"version":3,"file":"GPUGeometryBVHManager.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/bvh/GPUGeometryBVHManager.js"],"names":[],"mappings":"AAaA;;;;;GAKG;AACH,gDAGG;AAUH;;;;;;;;;;;;;;GAcG;AACH;IAoGI;;;OAGG;IACH,+BA2BC;IA3HD;;;OAGG;IACH,iCAEC;IAOD;;;OAGG;IACH,6BAEC;IAqBD;;OAEG;IACH,gCAEC;IAOD;;OAEG;IACH,mCAEC;IAoED,+BAoBC;IAED;;;;;;;;;;;;;;OAcG;IACH,cALW,MAAM,4BAGJ,sBAAsB,CAalC;IA4DD;;;;;OAKG;IACH,wBAHW,MAAM,GACJ;QAAC,gBAAgB,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAC;QAAC,iBAAiB,EAAE,MAAM,CAAA;KAAC,GAAC,SAAS,CAgB3I;IAED;;;;;;OAMG;IACH,mBAHW,MAAM,GACJ,MAAM,GAAC,SAAS,CAU5B;IAED;;;;;;;;;OASG;IACH,0BAFW,WAAW,QAQrB;IAED;;;;;;;;OAQG;IACH,cAHW,MAAM,GACJ,OAAO,CAkBnB;IAsID,eAgHC;;CACJ;6BAlmB4B,mCAAmC;uCAIzB,6BAA6B"}