@woosh/meep-engine 3.0.2 → 3.2.0

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

@@ -1,531 +1,531 @@
-import { assert } from "../../../core/assert.js";
-import { m4_multiply } from "../../../core/geom/3d/mat4/m4_multiply.js";
-import {
-    computeBoundingSphereOfSpheres
-} from "../../../core/geom/packing/computeBoundingSphereOfSpheres.js";
-import {
-    computeBoundingSphereFromVertexData
-} from "../../../engine/graphics/geometry/computeBoundingSphereFromVertexData.js";
-import {
-    mesh_apply_skeletal_vertex_skinning
-} from "../../../engine/graphics/geometry/skining/mesh_apply_skeletal_vertex_skinning.js";
-
-/**
- * Identity 4×4 column-major matrix. The
- * `mesh_apply_skeletal_vertex_skinning` helper takes `m4_bind` and
- * `m4_bind_inv` arguments; both are identity for our use because the
- * per-joint `bone_matrices` already encode the full skin transform
- * (`joint_world × inverse_bind`) and the consumer of the resulting
- * sphere re-applies `mesh.transform_global` on its side.
- *
- * @type {Float32Array}
- */
-const IDENTITY_M4 = (() => {
-    const m = new Float32Array(16);
-    m[0] = 1; m[5] = 1; m[10] = 1; m[15] = 1;
-    return m;
-})();
-
-/**
- * 4×4 scratch buffer used by the per-tick bone-matrix construction.
- * Module-level rather than allocated per call so a long clip's
- * thousands of ticks don't churn the heap.
- *
- * @type {Float32Array}
- */
-const _scratch_mat4_b = new Float32Array(16);
-
-/**
- * Joint-world matrix accumulator. Grown on demand; `length / 16`
- * is the joint count it can hold. Re-allocated only when the
- * current capacity is too small — never shrunk.
- *
- * @type {Float32Array}
- */
-let _scratch_joint_world = new Float32Array(0);
-
-/**
- * Bone-matrix scratch in the row-major 3×4 form
- * {@link mesh_apply_skeletal_vertex_skinning} expects (12 floats per
- * joint). Grown on demand alongside `_scratch_joint_world`.
- *
- * @type {Float32Array}
- */
-let _scratch_bone_matrices = new Float32Array(0);
-
-/**
- * Skinned-vertex output buffer for one pose. Sized to the largest
- * `vertex_count × 3` we've seen so far. Reused across ticks.
- *
- * @type {Float32Array}
- */
-let _scratch_skinned_positions = new Float32Array(0);
-
-/**
- * Accumulator for per-tick `(cx, cy, cz, r)` spheres. Grown on
- * demand to fit the largest tick count we've processed.
- *
- * @type {Float32Array}
- */
-let _scratch_tick_spheres = new Float32Array(0);
-
-/**
- * Per-tick sphere written by {@link computeBoundingSphereFromVertexData}.
- * The function expects a `.set(x, y, z, w)`-compatible target;
- * this tiny class is the minimum that satisfies it without
- * pulling in Vector4. Reused every tick.
- */
-const _scratch_tick_sphere = {
-    x: 0, y: 0, z: 0, w: 0,
-    set(x, y, z, w) {
-        this.x = x;
-        this.y = y;
-        this.z = z;
-        this.w = w;
-    },
-};
-
-/**
- * Bind-pose snapshots for joints touched by a clip. Saved on entry
- * to {@link compute_skinned_mesh_clip_bounding_sphere} and restored
- * on exit, so this routine never permanently mutates the caller's
- * Node3D's. Module-level pool keyed by per-call slot index; grows
- * to hold the largest channel count we've seen.
- *
- * Three parallel typed arrays — position (3 f32), rotation
- * (4 f32 quaternion), scale (3 f32) — flattened so save/restore
- * is a tight loop with no per-joint object allocation.
- *
- * @type {Float32Array}
- */
-let _scratch_bind_position = new Float32Array(0);
-let _scratch_bind_rotation = new Float32Array(0);
-let _scratch_bind_scale    = new Float32Array(0);
-
-/**
- * Per-call joint set in topological order. `_scratch_joint_order[k]`
- * holds the index (into `skin.joints`) of the k-th joint to
- * process — parents always precede their children. Computed once
- * per call (skin hierarchy is static across ticks) and reused
- * across all ticks of that call.
- *
- * @type {Int32Array}
- */
-let _scratch_joint_order = new Int32Array(0);
-
-/**
- * Per-call parent index lookup. `_scratch_parent_in_set[i]` is the
- * index of `skin.joints[i]`'s parent within `skin.joints`, or `-1`
- * if the parent isn't part of the skin (an "outer" parent like the
- * SkinnedMesh node or an armature anchor).
- *
- * @type {Int32Array}
- */
-let _scratch_parent_in_set = new Int32Array(0);
-
-/**
- * DFS visited markers for the topo-sort pass. Cleared at the start
- * of each call; module-level so we don't allocate per call.
- *
- * @type {Uint8Array}
- */
-let _scratch_joint_visited = new Uint8Array(0);
-
-/**
- * Ensure each module-level scratch typed array can hold at least
- * `min_length` elements. Grow-only — never shrinks. Doubling
- * strategy mirrors the GPU-side scratch buffers' policy.
- *
- * @param {Float32Array|Int32Array} buffer
- * @param {number} min_length
- * @param {function(number):Float32Array|Int32Array} make
- * @returns {Float32Array|Int32Array} new buffer (or the input if it already fit)
- */
-function _ensure_capacity(buffer, min_length, make) {
-    if (buffer.length >= min_length) return buffer;
-    let cap = Math.max(buffer.length, 1);
-    while (cap < min_length) cap *= 2;
-    return make(cap);
-}
-
-/**
- * Inflate a column-major 4×4 matrix `m` into the row-major 3×4 form
- * `mesh_apply_skeletal_vertex_skinning` reads per bone. Writes
- * 12 floats starting at `out[out_offset]`.
- *
- * Mapping: the meep skinner does
- * `sx = b[0]*x + b[1]*y + b[2]*z + b[3]` etc., which is row-major
- * 3×4 (`b[r*4 + c]`). Our `m` is column-major 4×4, so column `c`
- * lives at `m[c*4 + r]`. Hence `b[r*4 + c] = m[c*4 + r]`.
- *
- * Exported (with leading underscore) for direct test coverage.
- *
- * @param {Float32Array} m column-major 4×4
- * @param {Float32Array} out
- * @param {number} out_offset
- */
-export function _pack_mat4_to_bone_3x4(m, out, out_offset) {
-    out[out_offset +  0] = m[0];   // m00
-    out[out_offset +  1] = m[4];   // m01
-    out[out_offset +  2] = m[8];   // m02
-    out[out_offset +  3] = m[12];  // m03 (tx)
-    out[out_offset +  4] = m[1];   // m10
-    out[out_offset +  5] = m[5];   // m11
-    out[out_offset +  6] = m[9];   // m12
-    out[out_offset +  7] = m[13];  // m13 (ty)
-    out[out_offset +  8] = m[2];   // m20
-    out[out_offset +  9] = m[6];   // m21
-    out[out_offset + 10] = m[10];  // m22
-    out[out_offset + 11] = m[14];  // m23 (tz)
-}
-
-/**
- * 4-float scratch slot used to receive the union sphere from
- * {@link computeBoundingSphereOfSpheres}. The meep helper writes
- * `[cx, cy, cz, r]` into a `result` array-like; we then copy
- * those four floats into the caller's `out` via `.set(x, y, z, w)`.
- *
- * @type {Float32Array}
- */
-const _scratch_union_result = new Float32Array(4);
-
-/**
- * CPU skinning + bounding-sphere computation for a single pose.
- *
- * Pure-function sub-step. Takes pre-built `bone_matrices` (already
- * in the row-major 3×4 form `mesh_apply_skeletal_vertex_skinning`
- * expects, with `joint_world × inverse_bind` baked in per bone)
- * plus the bind-pose vertex data, performs CPU skinning into an
- * internal scratch buffer, and writes the resulting tight bounding
- * sphere into `out_sphere` via miniball.
- *
- * Doesn't allocate (beyond the one-time scratch growth on first
- * call with larger-than-seen-before inputs).
- *
- * @param {object} args
- * @param {Float32Array} args.positions       bind-pose vertex positions, flat `3 × vertex_count`
- * @param {Uint32Array|number[]} args.joint_indices flat `4 × vertex_count` joint indices
- * @param {Float32Array} args.joint_weights   flat `4 × vertex_count` weights
- * @param {number} args.vertex_count
- * @param {Float32Array} args.bone_matrices   row-major 3×4 (12 floats) per joint
- * @param {{ set: function(number,number,number,number):void }} out_sphere
- */
-export function compute_skinned_pose_bounding_sphere({
-                                                        positions,
-                                                        joint_indices,
-                                                        joint_weights,
-                                                        vertex_count,
-                                                        bone_matrices,
-                                                    }, out_sphere) {
-
-    const required_positions = vertex_count * 3;
-    _scratch_skinned_positions = _ensure_capacity(
-        _scratch_skinned_positions,
-        required_positions,
-        (n) => new Float32Array(n),
-    );
-
-    // m4_bind / m4_bind_inv are identity for our use — the full
-    // skin transform is already inside each entry of bone_matrices
-    // (see compute_skinned_mesh_clip_bounding_sphere). The meep
-    // skinner's pre/post-bind multiplies then become no-ops.
-    mesh_apply_skeletal_vertex_skinning(
-        _scratch_skinned_positions,
-        0,
-        positions,
-        vertex_count,
-        joint_weights,
-        joint_indices,
-        bone_matrices,
-        IDENTITY_M4,
-        IDENTITY_M4,
-        4,
-    );
-
-    // miniball over the skinned positions. computeBoundingSphereFromVertexData
-    // calls result.set(cx, cy, cz, radius). The subarray view keeps
-    // the call bounded to the vertices we actually wrote (the
-    // scratch buffer may be larger from a previous call).
-    const view = _scratch_skinned_positions.subarray(0, required_positions);
-    computeBoundingSphereFromVertexData(view, out_sphere);
-}
-
-/**
- * Tight-ish bounding sphere over an entire clip's worth of poses.
- * Steps the clip at a fixed `dt`, CPU-skins the bind-pose vertices
- * at each tick, computes a per-tick miniball sphere, and unions
- * them into one final sphere.
- *
- * The output sphere is in the mesh's **local space** — the bone
- * matrices encode `joint_world × inverse_bind` only, with no mesh-
- * node factor. Multiplying the sphere by the SkinnedMesh's runtime
- * `transform_global` produces the world-space sphere a frustum-cull
- * pass can compare against. This matches the rasterizer's
- * convention (clone vertices are mesh-local; world placement comes
- * from `mesh.transform_global` at draw time).
- *
- * Mutates the joint Node3D's `transform_local` while stepping —
- * bind-pose values are saved on entry and restored on exit. Doesn't
- * touch joints not driven by the clip.
- *
- * Allocation: zero per-call. Module-level scratch grows once on
- * first call with a new largest size; subsequent calls reuse it.
- *
- * For the per-clip cost: this is intended for one-time computation
- * at scene-setup time, so the bounding sphere can be uploaded to
- * the GPU for skinning-workload culling. Per-frame use isn't
- * supported (would have to deal with concurrent users of the
- * module-level scratch).
- *
- * @param {object} args
- * @param {Float32Array} args.positions       bind-pose vertex positions, flat `3 × vertex_count`
- * @param {Uint32Array|number[]} args.joint_indices  flat `4 × vertex_count` joint indices
- * @param {Float32Array} args.joint_weights   flat `4 × vertex_count` weights
- * @param {number} args.vertex_count
- * @param {Skin} args.skin                    joints + inverse-bind matrices (column-major, 16 each)
- * @param {ShadeAnimationClip} args.clip
- * @param {number} [args.dt]                  time step in seconds (default `1/60`)
- * @param {{ set: function(number,number,number,number):void }} out_sphere
- */
-export function compute_skinned_mesh_clip_bounding_sphere({
-                                                              positions,
-                                                              joint_indices,
-                                                              joint_weights,
-                                                              vertex_count,
-                                                              skin,
-                                                              clip,
-                                                              dt = 1 / 60,
-                                                          }, out_sphere) {
-
-    assert.defined(positions, 'positions');
-    assert.defined(joint_indices, 'joint_indices');
-    assert.defined(joint_weights, 'joint_weights');
-    assert.isNonNegativeInteger(vertex_count, 'vertex_count');
-    assert.defined(skin, 'skin');
-    assert.equal(skin.isSkin, true, 'skin.isSkin !== true');
-    assert.defined(clip, 'clip');
-    assert.equal(clip.isShadeAnimationClip, true, 'clip.isShadeAnimationClip !== true');
-    assert.greaterThan(dt, 0, 'dt');
-    assert.defined(out_sphere, 'out_sphere');
-
-    const joints = skin.joints;
-    const joint_count = joints.length;
-    const channels = clip.channels;
-    const channel_count = channels.length;
-
-    // ── Topological order over the joint set ──────────────────
-    //
-    // Computed once per call; the skin's joint hierarchy is static.
-    // For each joint we also note whether its parent is itself a
-    // skin joint — outer parents (SkinnedMesh node, armature
-    // anchor) are handled separately so we can fold their current
-    // transform_global into the walk without confusing it with
-    // an intra-skin link.
-    _scratch_joint_order = _ensure_capacity(
-        _scratch_joint_order, joint_count,
-        (n) => new Int32Array(n),
-    );
-    _scratch_parent_in_set = _ensure_capacity(
-        _scratch_parent_in_set, joint_count,
-        (n) => new Int32Array(n),
-    );
-
-    const joint_index_map = new Map();
-    for (let i = 0; i < joint_count; i++) joint_index_map.set(joints[i], i);
-    for (let i = 0; i < joint_count; i++) {
-        const parent = joints[i].parent;
-        const p = parent !== null ? joint_index_map.get(parent) : undefined;
-        _scratch_parent_in_set[i] = p === undefined ? -1 : p;
-    }
-
-    // DFS-based topo sort: visit parent before child. The visited
-    // marker array is module-level scratch; grow if needed and
-    // clear the joint_count prefix at the start of each call.
-    _scratch_joint_visited = _ensure_capacity(
-        _scratch_joint_visited, joint_count,
-        (n) => new Uint8Array(n),
-    );
-    for (let i = 0; i < joint_count; i++) _scratch_joint_visited[i] = 0;
-
-    let order_cursor = 0;
-    const visit = (i) => {
-        if (_scratch_joint_visited[i]) return;
-        const parent_in_set = _scratch_parent_in_set[i];
-        if (parent_in_set >= 0) visit(parent_in_set);
-        _scratch_joint_visited[i] = 1;
-        _scratch_joint_order[order_cursor++] = i;
-    };
-    for (let i = 0; i < joint_count; i++) visit(i);
-
-    // ── Save bind-pose TRS for every channel-driven joint ──────
-    //
-    // Only the joints the clip actually animates are at risk of
-    // being mutated — others stay at their bind values throughout.
-    // Grow the snapshot buffers to fit one slot per channel
-    // (channels are 1-to-1 with target Node3Ds in practice; the
-    // same target can in theory show up across multiple channels
-    // for different properties, but we still need only one snapshot
-    // per channel).
-    _scratch_bind_position = _ensure_capacity(
-        _scratch_bind_position, channel_count * 3,
-        (n) => new Float32Array(n),
-    );
-    _scratch_bind_rotation = _ensure_capacity(
-        _scratch_bind_rotation, channel_count * 4,
-        (n) => new Float32Array(n),
-    );
-    _scratch_bind_scale = _ensure_capacity(
-        _scratch_bind_scale, channel_count * 3,
-        (n) => new Float32Array(n),
-    );
-
-    for (let c = 0; c < channel_count; c++) {
-        const tl = channels[c].target.transform_local;
-        _scratch_bind_position[c * 3 + 0] = tl.translation_x;
-        _scratch_bind_position[c * 3 + 1] = tl.translation_y;
-        _scratch_bind_position[c * 3 + 2] = tl.translation_z;
-        _scratch_bind_rotation[c * 4 + 0] = tl.rotation_x;
-        _scratch_bind_rotation[c * 4 + 1] = tl.rotation_y;
-        _scratch_bind_rotation[c * 4 + 2] = tl.rotation_z;
-        _scratch_bind_rotation[c * 4 + 3] = tl.rotation_w;
-        _scratch_bind_scale[c * 3 + 0] = tl.scale_x;
-        _scratch_bind_scale[c * 3 + 1] = tl.scale_y;
-        _scratch_bind_scale[c * 3 + 2] = tl.scale_z;
-    }
-
-    // ── Allocate scratch sized to the joint count + clip extent ─
-    _scratch_joint_world = _ensure_capacity(
-        _scratch_joint_world, joint_count * 16,
-        (n) => new Float32Array(n),
-    );
-    _scratch_bone_matrices = _ensure_capacity(
-        _scratch_bone_matrices, joint_count * 12,
-        (n) => new Float32Array(n),
-    );
-
-    // ── Step the clip ────────────────────────────────────────
-    const t_start = clip.start_time;
-    const t_end = clip.end_time;
-    const span = Math.max(t_end - t_start, 0);
-    // Plus 1 to include both endpoints when (span % dt) == 0.
-    const tick_count = Math.max(1, Math.floor(span / dt) + 1);
-
-    _scratch_tick_spheres = _ensure_capacity(
-        _scratch_tick_spheres, tick_count * 4,
-        (n) => new Float32Array(n),
-    );
-
-    for (let tick = 0; tick < tick_count; tick++) {
-        // Last tick lands exactly on t_end so the clip's endpoint
-        // pose is included even when (span / dt) doesn't divide
-        // evenly.
-        const t = (tick === tick_count - 1) ? t_end : t_start + tick * dt;
-
-        // Apply the clip to each channel's target Node3D. Mutates
-        // bind-pose TRS on the animated joints — snapshot/restore
-        // outside the tick loop covers it.
-        clip.apply(t);
-
-        // Walk the skin's joints in topological order, composing
-        // each joint's world matrix from its parent's world matrix
-        // and its own local. Outer parents (parent_in_set < 0)
-        // contribute their current `transform_global.matrix` so the
-        // sphere lands in the right outer frame; if the joint has
-        // no parent at all, its world is just its local.
-        for (let oi = 0; oi < joint_count; oi++) {
-            const i = _scratch_joint_order[oi];
-            const joint = joints[i];
-
-            // Refresh the joint's matrix from its (possibly clip-
-            // mutated) TRS.
-            joint.transform_local.updateMatrix();
-            const local = joint.transform_local.matrix;
-            const parent_in_set = _scratch_parent_in_set[i];
-            const out_offset = i * 16;
-
-            if (parent_in_set >= 0) {
-                const parent_world = _scratch_joint_world.subarray(
-                    parent_in_set * 16, parent_in_set * 16 + 16,
-                );
-                const out_view = _scratch_joint_world.subarray(out_offset, out_offset + 16);
-                m4_multiply(out_view, parent_world, local);
-            } else {
-                const parent = joint.parent;
-                if (parent !== null) {
-                    const out_view = _scratch_joint_world.subarray(out_offset, out_offset + 16);
-                    m4_multiply(out_view, parent.transform_global.matrix, local);
-                } else {
-                    for (let k = 0; k < 16; k++) {
-                        _scratch_joint_world[out_offset + k] = local[k];
-                    }
-                }
-            }
-        }
-
-        // Build per-joint bone matrices in the 3×4 form the meep
-        // skinner reads:
-        //   skin_matrix_i = joint_world_i × inverse_bind_i
-        // No mesh-node factor — the consumer of `out_sphere` applies
-        // `mesh.transform_global` on its side, matching the
-        // rasterizer convention.
-        const inverse_bind = skin.inverse_bind_matrices;
-        for (let i = 0; i < joint_count; i++) {
-            const joint_world = _scratch_joint_world.subarray(i * 16, i * 16 + 16);
-            const inv_bind = inverse_bind.subarray(i * 16, i * 16 + 16);
-
-            m4_multiply(_scratch_mat4_b, joint_world, inv_bind);
-            _pack_mat4_to_bone_3x4(_scratch_mat4_b, _scratch_bone_matrices, i * 12);
-        }
-
-        // Skin + miniball sphere for this tick.
-        compute_skinned_pose_bounding_sphere({
-            positions,
-            joint_indices,
-            joint_weights,
-            vertex_count,
-            bone_matrices: _scratch_bone_matrices,
-        }, _scratch_tick_sphere);
-
-        const o = tick * 4;
-        _scratch_tick_spheres[o + 0] = _scratch_tick_sphere.x;
-        _scratch_tick_spheres[o + 1] = _scratch_tick_sphere.y;
-        _scratch_tick_spheres[o + 2] = _scratch_tick_sphere.z;
-        _scratch_tick_spheres[o + 3] = _scratch_tick_sphere.w;
-    }
-
-    // ── Union the per-tick spheres into one ──────────────────
-    //
-    // Layout: `_scratch_tick_spheres[tick * 4 + (0..3)] = (cx, cy, cz, r)`,
-    // so each sphere is 4 floats wide. We pass `dimensions = 3` to
-    // describe the spatial dimensionality of the centres.
-    computeBoundingSphereOfSpheres(
-        _scratch_union_result, _scratch_tick_spheres, 0, tick_count, 3,
-    );
-    out_sphere.set(
-        _scratch_union_result[0],
-        _scratch_union_result[1],
-        _scratch_union_result[2],
-        _scratch_union_result[3],
-    );
-
-    // ── Restore bind-pose TRS ──────────────────────────────────
-    for (let c = 0; c < channel_count; c++) {
-        const tl = channels[c].target.transform_local;
-        tl.setTranslation(
-            _scratch_bind_position[c * 3 + 0],
-            _scratch_bind_position[c * 3 + 1],
-            _scratch_bind_position[c * 3 + 2],
-        );
-        tl.setRotation(
-            _scratch_bind_rotation[c * 4 + 0],
-            _scratch_bind_rotation[c * 4 + 1],
-            _scratch_bind_rotation[c * 4 + 2],
-            _scratch_bind_rotation[c * 4 + 3],
-        );
-        tl.setScale(
-            _scratch_bind_scale[c * 3 + 0],
-            _scratch_bind_scale[c * 3 + 1],
-            _scratch_bind_scale[c * 3 + 2],
-        );
-    }
-}
+import { assert } from "../../../core/assert.js";
+import { m4_multiply } from "../../../core/geom/3d/mat4/m4_multiply.js";
+import {
+    computeBoundingSphereOfSpheres
+} from "../../../core/geom/packing/computeBoundingSphereOfSpheres.js";
+import {
+    computeBoundingSphereFromVertexData
+} from "../../../engine/graphics/geometry/computeBoundingSphereFromVertexData.js";
+import {
+    mesh_apply_skeletal_vertex_skinning
+} from "../../../engine/graphics/geometry/skining/mesh_apply_skeletal_vertex_skinning.js";
+
+/**
+ * Identity 4×4 column-major matrix. The
+ * `mesh_apply_skeletal_vertex_skinning` helper takes `m4_bind` and
+ * `m4_bind_inv` arguments; both are identity for our use because the
+ * per-joint `bone_matrices` already encode the full skin transform
+ * (`joint_world × inverse_bind`) and the consumer of the resulting
+ * sphere re-applies `mesh.transform_global` on its side.
+ *
+ * @type {Float32Array}
+ */
+const IDENTITY_M4 = (() => {
+    const m = new Float32Array(16);
+    m[0] = 1; m[5] = 1; m[10] = 1; m[15] = 1;
+    return m;
+})();
+
+/**
+ * 4×4 scratch buffer used by the per-tick bone-matrix construction.
+ * Module-level rather than allocated per call so a long clip's
+ * thousands of ticks don't churn the heap.
+ *
+ * @type {Float32Array}
+ */
+const _scratch_mat4_b = new Float32Array(16);
+
+/**
+ * Joint-world matrix accumulator. Grown on demand; `length / 16`
+ * is the joint count it can hold. Re-allocated only when the
+ * current capacity is too small — never shrunk.
+ *
+ * @type {Float32Array}
+ */
+let _scratch_joint_world = new Float32Array(0);
+
+/**
+ * Bone-matrix scratch in the row-major 3×4 form
+ * {@link mesh_apply_skeletal_vertex_skinning} expects (12 floats per
+ * joint). Grown on demand alongside `_scratch_joint_world`.
+ *
+ * @type {Float32Array}
+ */
+let _scratch_bone_matrices = new Float32Array(0);
+
+/**
+ * Skinned-vertex output buffer for one pose. Sized to the largest
+ * `vertex_count × 3` we've seen so far. Reused across ticks.
+ *
+ * @type {Float32Array}
+ */
+let _scratch_skinned_positions = new Float32Array(0);
+
+/**
+ * Accumulator for per-tick `(cx, cy, cz, r)` spheres. Grown on
+ * demand to fit the largest tick count we've processed.
+ *
+ * @type {Float32Array}
+ */
+let _scratch_tick_spheres = new Float32Array(0);
+
+/**
+ * Per-tick sphere written by {@link computeBoundingSphereFromVertexData}.
+ * The function expects a `.set(x, y, z, w)`-compatible target;
+ * this tiny class is the minimum that satisfies it without
+ * pulling in Vector4. Reused every tick.
+ */
+const _scratch_tick_sphere = {
+    x: 0, y: 0, z: 0, w: 0,
+    set(x, y, z, w) {
+        this.x = x;
+        this.y = y;
+        this.z = z;
+        this.w = w;
+    },
+};
+
+/**
+ * Bind-pose snapshots for joints touched by a clip. Saved on entry
+ * to {@link compute_skinned_mesh_clip_bounding_sphere} and restored
+ * on exit, so this routine never permanently mutates the caller's
+ * Node3D's. Module-level pool keyed by per-call slot index; grows
+ * to hold the largest channel count we've seen.
+ *
+ * Three parallel typed arrays — position (3 f32), rotation
+ * (4 f32 quaternion), scale (3 f32) — flattened so save/restore
+ * is a tight loop with no per-joint object allocation.
+ *
+ * @type {Float32Array}
+ */
+let _scratch_bind_position = new Float32Array(0);
+let _scratch_bind_rotation = new Float32Array(0);
+let _scratch_bind_scale    = new Float32Array(0);
+
+/**
+ * Per-call joint set in topological order. `_scratch_joint_order[k]`
+ * holds the index (into `skin.joints`) of the k-th joint to
+ * process — parents always precede their children. Computed once
+ * per call (skin hierarchy is static across ticks) and reused
+ * across all ticks of that call.
+ *
+ * @type {Int32Array}
+ */
+let _scratch_joint_order = new Int32Array(0);
+
+/**
+ * Per-call parent index lookup. `_scratch_parent_in_set[i]` is the
+ * index of `skin.joints[i]`'s parent within `skin.joints`, or `-1`
+ * if the parent isn't part of the skin (an "outer" parent like the
+ * SkinnedMesh node or an armature anchor).
+ *
+ * @type {Int32Array}
+ */
+let _scratch_parent_in_set = new Int32Array(0);
+
+/**
+ * DFS visited markers for the topo-sort pass. Cleared at the start
+ * of each call; module-level so we don't allocate per call.
+ *
+ * @type {Uint8Array}
+ */
+let _scratch_joint_visited = new Uint8Array(0);
+
+/**
+ * Ensure each module-level scratch typed array can hold at least
+ * `min_length` elements. Grow-only — never shrinks. Doubling
+ * strategy mirrors the GPU-side scratch buffers' policy.
+ *
+ * @param {Float32Array|Int32Array} buffer
+ * @param {number} min_length
+ * @param {function(number):Float32Array|Int32Array} make
+ * @returns {Float32Array|Int32Array} new buffer (or the input if it already fit)
+ */
+function _ensure_capacity(buffer, min_length, make) {
+    if (buffer.length >= min_length) return buffer;
+    let cap = Math.max(buffer.length, 1);
+    while (cap < min_length) cap *= 2;
+    return make(cap);
+}
+
+/**
+ * Inflate a column-major 4×4 matrix `m` into the row-major 3×4 form
+ * `mesh_apply_skeletal_vertex_skinning` reads per bone. Writes
+ * 12 floats starting at `out[out_offset]`.
+ *
+ * Mapping: the meep skinner does
+ * `sx = b[0]*x + b[1]*y + b[2]*z + b[3]` etc., which is row-major
+ * 3×4 (`b[r*4 + c]`). Our `m` is column-major 4×4, so column `c`
+ * lives at `m[c*4 + r]`. Hence `b[r*4 + c] = m[c*4 + r]`.
+ *
+ * Exported (with leading underscore) for direct test coverage.
+ *
+ * @param {Float32Array} m column-major 4×4
+ * @param {Float32Array} out
+ * @param {number} out_offset
+ */
+export function _pack_mat4_to_bone_3x4(m, out, out_offset) {
+    out[out_offset +  0] = m[0];   // m00
+    out[out_offset +  1] = m[4];   // m01
+    out[out_offset +  2] = m[8];   // m02
+    out[out_offset +  3] = m[12];  // m03 (tx)
+    out[out_offset +  4] = m[1];   // m10
+    out[out_offset +  5] = m[5];   // m11
+    out[out_offset +  6] = m[9];   // m12
+    out[out_offset +  7] = m[13];  // m13 (ty)
+    out[out_offset +  8] = m[2];   // m20
+    out[out_offset +  9] = m[6];   // m21
+    out[out_offset + 10] = m[10];  // m22
+    out[out_offset + 11] = m[14];  // m23 (tz)
+}
+
+/**
+ * 4-float scratch slot used to receive the union sphere from
+ * {@link computeBoundingSphereOfSpheres}. The meep helper writes
+ * `[cx, cy, cz, r]` into a `result` array-like; we then copy
+ * those four floats into the caller's `out` via `.set(x, y, z, w)`.
+ *
+ * @type {Float32Array}
+ */
+const _scratch_union_result = new Float32Array(4);
+
+/**
+ * CPU skinning + bounding-sphere computation for a single pose.
+ *
+ * Pure-function sub-step. Takes pre-built `bone_matrices` (already
+ * in the row-major 3×4 form `mesh_apply_skeletal_vertex_skinning`
+ * expects, with `joint_world × inverse_bind` baked in per bone)
+ * plus the bind-pose vertex data, performs CPU skinning into an
+ * internal scratch buffer, and writes the resulting tight bounding
+ * sphere into `out_sphere` via miniball.
+ *
+ * Doesn't allocate (beyond the one-time scratch growth on first
+ * call with larger-than-seen-before inputs).
+ *
+ * @param {object} args
+ * @param {Float32Array} args.positions       bind-pose vertex positions, flat `3 × vertex_count`
+ * @param {Uint32Array|number[]} args.joint_indices flat `4 × vertex_count` joint indices
+ * @param {Float32Array} args.joint_weights   flat `4 × vertex_count` weights
+ * @param {number} args.vertex_count
+ * @param {Float32Array} args.bone_matrices   row-major 3×4 (12 floats) per joint
+ * @param {{ set: function(number,number,number,number):void }} out_sphere
+ */
+export function compute_skinned_pose_bounding_sphere({
+                                                        positions,
+                                                        joint_indices,
+                                                        joint_weights,
+                                                        vertex_count,
+                                                        bone_matrices,
+                                                    }, out_sphere) {
+
+    const required_positions = vertex_count * 3;
+    _scratch_skinned_positions = _ensure_capacity(
+        _scratch_skinned_positions,
+        required_positions,
+        (n) => new Float32Array(n),
+    );
+
+    // m4_bind / m4_bind_inv are identity for our use — the full
+    // skin transform is already inside each entry of bone_matrices
+    // (see compute_skinned_mesh_clip_bounding_sphere). The meep
+    // skinner's pre/post-bind multiplies then become no-ops.
+    mesh_apply_skeletal_vertex_skinning(
+        _scratch_skinned_positions,
+        0,
+        positions,
+        vertex_count,
+        joint_weights,
+        joint_indices,
+        bone_matrices,
+        IDENTITY_M4,
+        IDENTITY_M4,
+        4,
+    );
+
+    // miniball over the skinned positions. computeBoundingSphereFromVertexData
+    // calls result.set(cx, cy, cz, radius). The subarray view keeps
+    // the call bounded to the vertices we actually wrote (the
+    // scratch buffer may be larger from a previous call).
+    const view = _scratch_skinned_positions.subarray(0, required_positions);
+    computeBoundingSphereFromVertexData(view, out_sphere);
+}
+
+/**
+ * Tight-ish bounding sphere over an entire clip's worth of poses.
+ * Steps the clip at a fixed `dt`, CPU-skins the bind-pose vertices
+ * at each tick, computes a per-tick miniball sphere, and unions
+ * them into one final sphere.
+ *
+ * The output sphere is in the mesh's **local space** — the bone
+ * matrices encode `joint_world × inverse_bind` only, with no mesh-
+ * node factor. Multiplying the sphere by the SkinnedMesh's runtime
+ * `transform_global` produces the world-space sphere a frustum-cull
+ * pass can compare against. This matches the rasterizer's
+ * convention (clone vertices are mesh-local; world placement comes
+ * from `mesh.transform_global` at draw time).
+ *
+ * Mutates the joint Node3D's `transform_local` while stepping —
+ * bind-pose values are saved on entry and restored on exit. Doesn't
+ * touch joints not driven by the clip.
+ *
+ * Allocation: zero per-call. Module-level scratch grows once on
+ * first call with a new largest size; subsequent calls reuse it.
+ *
+ * For the per-clip cost: this is intended for one-time computation
+ * at scene-setup time, so the bounding sphere can be uploaded to
+ * the GPU for skinning-workload culling. Per-frame use isn't
+ * supported (would have to deal with concurrent users of the
+ * module-level scratch).
+ *
+ * @param {object} args
+ * @param {Float32Array} args.positions       bind-pose vertex positions, flat `3 × vertex_count`
+ * @param {Uint32Array|number[]} args.joint_indices  flat `4 × vertex_count` joint indices
+ * @param {Float32Array} args.joint_weights   flat `4 × vertex_count` weights
+ * @param {number} args.vertex_count
+ * @param {Skin} args.skin                    joints + inverse-bind matrices (column-major, 16 each)
+ * @param {ShadeAnimationClip} args.clip
+ * @param {number} [args.dt]                  time step in seconds (default `1/60`)
+ * @param {{ set: function(number,number,number,number):void }} out_sphere
+ */
+export function compute_skinned_mesh_clip_bounding_sphere({
+                                                              positions,
+                                                              joint_indices,
+                                                              joint_weights,
+                                                              vertex_count,
+                                                              skin,
+                                                              clip,
+                                                              dt = 1 / 60,
+                                                          }, out_sphere) {
+
+    assert.defined(positions, 'positions');
+    assert.defined(joint_indices, 'joint_indices');
+    assert.defined(joint_weights, 'joint_weights');
+    assert.isNonNegativeInteger(vertex_count, 'vertex_count');
+    assert.defined(skin, 'skin');
+    assert.equal(skin.isSkin, true, 'skin.isSkin !== true');
+    assert.defined(clip, 'clip');
+    assert.equal(clip.isShadeAnimationClip, true, 'clip.isShadeAnimationClip !== true');
+    assert.greaterThan(dt, 0, 'dt');
+    assert.defined(out_sphere, 'out_sphere');
+
+    const joints = skin.joints;
+    const joint_count = joints.length;
+    const channels = clip.channels;
+    const channel_count = channels.length;
+
+    // ── Topological order over the joint set ──────────────────
+    //
+    // Computed once per call; the skin's joint hierarchy is static.
+    // For each joint we also note whether its parent is itself a
+    // skin joint — outer parents (SkinnedMesh node, armature
+    // anchor) are handled separately so we can fold their current
+    // transform_global into the walk without confusing it with
+    // an intra-skin link.
+    _scratch_joint_order = _ensure_capacity(
+        _scratch_joint_order, joint_count,
+        (n) => new Int32Array(n),
+    );
+    _scratch_parent_in_set = _ensure_capacity(
+        _scratch_parent_in_set, joint_count,
+        (n) => new Int32Array(n),
+    );
+
+    const joint_index_map = new Map();
+    for (let i = 0; i < joint_count; i++) joint_index_map.set(joints[i], i);
+    for (let i = 0; i < joint_count; i++) {
+        const parent = joints[i].parent;
+        const p = parent !== null ? joint_index_map.get(parent) : undefined;
+        _scratch_parent_in_set[i] = p === undefined ? -1 : p;
+    }
+
+    // DFS-based topo sort: visit parent before child. The visited
+    // marker array is module-level scratch; grow if needed and
+    // clear the joint_count prefix at the start of each call.
+    _scratch_joint_visited = _ensure_capacity(
+        _scratch_joint_visited, joint_count,
+        (n) => new Uint8Array(n),
+    );
+    for (let i = 0; i < joint_count; i++) _scratch_joint_visited[i] = 0;
+
+    let order_cursor = 0;
+    const visit = (i) => {
+        if (_scratch_joint_visited[i]) return;
+        const parent_in_set = _scratch_parent_in_set[i];
+        if (parent_in_set >= 0) visit(parent_in_set);
+        _scratch_joint_visited[i] = 1;
+        _scratch_joint_order[order_cursor++] = i;
+    };
+    for (let i = 0; i < joint_count; i++) visit(i);
+
+    // ── Save bind-pose TRS for every channel-driven joint ──────
+    //
+    // Only the joints the clip actually animates are at risk of
+    // being mutated — others stay at their bind values throughout.
+    // Grow the snapshot buffers to fit one slot per channel
+    // (channels are 1-to-1 with target Node3Ds in practice; the
+    // same target can in theory show up across multiple channels
+    // for different properties, but we still need only one snapshot
+    // per channel).
+    _scratch_bind_position = _ensure_capacity(
+        _scratch_bind_position, channel_count * 3,
+        (n) => new Float32Array(n),
+    );
+    _scratch_bind_rotation = _ensure_capacity(
+        _scratch_bind_rotation, channel_count * 4,
+        (n) => new Float32Array(n),
+    );
+    _scratch_bind_scale = _ensure_capacity(
+        _scratch_bind_scale, channel_count * 3,
+        (n) => new Float32Array(n),
+    );
+
+    for (let c = 0; c < channel_count; c++) {
+        const tl = channels[c].target.transform_local;
+        _scratch_bind_position[c * 3 + 0] = tl.translation_x;
+        _scratch_bind_position[c * 3 + 1] = tl.translation_y;
+        _scratch_bind_position[c * 3 + 2] = tl.translation_z;
+        _scratch_bind_rotation[c * 4 + 0] = tl.rotation_x;
+        _scratch_bind_rotation[c * 4 + 1] = tl.rotation_y;
+        _scratch_bind_rotation[c * 4 + 2] = tl.rotation_z;
+        _scratch_bind_rotation[c * 4 + 3] = tl.rotation_w;
+        _scratch_bind_scale[c * 3 + 0] = tl.scale_x;
+        _scratch_bind_scale[c * 3 + 1] = tl.scale_y;
+        _scratch_bind_scale[c * 3 + 2] = tl.scale_z;
+    }
+
+    // ── Allocate scratch sized to the joint count + clip extent ─
+    _scratch_joint_world = _ensure_capacity(
+        _scratch_joint_world, joint_count * 16,
+        (n) => new Float32Array(n),
+    );
+    _scratch_bone_matrices = _ensure_capacity(
+        _scratch_bone_matrices, joint_count * 12,
+        (n) => new Float32Array(n),
+    );
+
+    // ── Step the clip ────────────────────────────────────────
+    const t_start = clip.start_time;
+    const t_end = clip.end_time;
+    const span = Math.max(t_end - t_start, 0);
+    // Plus 1 to include both endpoints when (span % dt) == 0.
+    const tick_count = Math.max(1, Math.floor(span / dt) + 1);
+
+    _scratch_tick_spheres = _ensure_capacity(
+        _scratch_tick_spheres, tick_count * 4,
+        (n) => new Float32Array(n),
+    );
+
+    for (let tick = 0; tick < tick_count; tick++) {
+        // Last tick lands exactly on t_end so the clip's endpoint
+        // pose is included even when (span / dt) doesn't divide
+        // evenly.
+        const t = (tick === tick_count - 1) ? t_end : t_start + tick * dt;
+
+        // Apply the clip to each channel's target Node3D. Mutates
+        // bind-pose TRS on the animated joints — snapshot/restore
+        // outside the tick loop covers it.
+        clip.apply(t);
+
+        // Walk the skin's joints in topological order, composing
+        // each joint's world matrix from its parent's world matrix
+        // and its own local. Outer parents (parent_in_set < 0)
+        // contribute their current `transform_global.matrix` so the
+        // sphere lands in the right outer frame; if the joint has
+        // no parent at all, its world is just its local.
+        for (let oi = 0; oi < joint_count; oi++) {
+            const i = _scratch_joint_order[oi];
+            const joint = joints[i];
+
+            // Refresh the joint's matrix from its (possibly clip-
+            // mutated) TRS.
+            joint.transform_local.updateMatrix();
+            const local = joint.transform_local.matrix;
+            const parent_in_set = _scratch_parent_in_set[i];
+            const out_offset = i * 16;
+
+            if (parent_in_set >= 0) {
+                const parent_world = _scratch_joint_world.subarray(
+                    parent_in_set * 16, parent_in_set * 16 + 16,
+                );
+                const out_view = _scratch_joint_world.subarray(out_offset, out_offset + 16);
+                m4_multiply(out_view, parent_world, local);
+            } else {
+                const parent = joint.parent;
+                if (parent !== null) {
+                    const out_view = _scratch_joint_world.subarray(out_offset, out_offset + 16);
+                    m4_multiply(out_view, parent.transform_global.matrix, local);
+                } else {
+                    for (let k = 0; k < 16; k++) {
+                        _scratch_joint_world[out_offset + k] = local[k];
+                    }
+                }
+            }
+        }
+
+        // Build per-joint bone matrices in the 3×4 form the meep
+        // skinner reads:
+        //   skin_matrix_i = joint_world_i × inverse_bind_i
+        // No mesh-node factor — the consumer of `out_sphere` applies
+        // `mesh.transform_global` on its side, matching the
+        // rasterizer convention.
+        const inverse_bind = skin.inverse_bind_matrices;
+        for (let i = 0; i < joint_count; i++) {
+            const joint_world = _scratch_joint_world.subarray(i * 16, i * 16 + 16);
+            const inv_bind = inverse_bind.subarray(i * 16, i * 16 + 16);
+
+            m4_multiply(_scratch_mat4_b, joint_world, inv_bind);
+            _pack_mat4_to_bone_3x4(_scratch_mat4_b, _scratch_bone_matrices, i * 12);
+        }
+
+        // Skin + miniball sphere for this tick.
+        compute_skinned_pose_bounding_sphere({
+            positions,
+            joint_indices,
+            joint_weights,
+            vertex_count,
+            bone_matrices: _scratch_bone_matrices,
+        }, _scratch_tick_sphere);
+
+        const o = tick * 4;
+        _scratch_tick_spheres[o + 0] = _scratch_tick_sphere.x;
+        _scratch_tick_spheres[o + 1] = _scratch_tick_sphere.y;
+        _scratch_tick_spheres[o + 2] = _scratch_tick_sphere.z;
+        _scratch_tick_spheres[o + 3] = _scratch_tick_sphere.w;
+    }
+
+    // ── Union the per-tick spheres into one ──────────────────
+    //
+    // Layout: `_scratch_tick_spheres[tick * 4 + (0..3)] = (cx, cy, cz, r)`,
+    // so each sphere is 4 floats wide. We pass `dimensions = 3` to
+    // describe the spatial dimensionality of the centres.
+    computeBoundingSphereOfSpheres(
+        _scratch_union_result, _scratch_tick_spheres, 0, tick_count, 3,
+    );
+    out_sphere.set(
+        _scratch_union_result[0],
+        _scratch_union_result[1],
+        _scratch_union_result[2],
+        _scratch_union_result[3],
+    );
+
+    // ── Restore bind-pose TRS ──────────────────────────────────
+    for (let c = 0; c < channel_count; c++) {
+        const tl = channels[c].target.transform_local;
+        tl.setTranslation(
+            _scratch_bind_position[c * 3 + 0],
+            _scratch_bind_position[c * 3 + 1],
+            _scratch_bind_position[c * 3 + 2],
+        );
+        tl.setRotation(
+            _scratch_bind_rotation[c * 4 + 0],
+            _scratch_bind_rotation[c * 4 + 1],
+            _scratch_bind_rotation[c * 4 + 2],
+            _scratch_bind_rotation[c * 4 + 3],
+        );
+        tl.setScale(
+            _scratch_bind_scale[c * 3 + 0],
+            _scratch_bind_scale[c * 3 + 1],
+            _scratch_bind_scale[c * 3 + 2],
+        );
+    }
+}