@woosh/meep-engine 3.23.0 → 3.24.0

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

@@ -1,132 +0,0 @@
-import { assert } from "../../../core/assert.js";
-import { m4_invert } from "../../../core/geom/3d/mat4/m4_invert.js";
-import { m4_multiply } from "../../../core/geom/3d/mat4/m4_multiply.js";
-import { m4_rigidity_defect } from "../../../core/geom/3d/mat4/m4_rigidity_defect.js";
-import { skin_joint_matrix } from "./skin_joint_matrix.js";
-
-/**
- * Scratch, so that walking a sixty-five-joint skeleton does not allocate per joint. Nothing here
- * re-enters, and none of it outlives the call.
- */
-const _inverse_frame = new Float64Array(16);
-const _joint_matrix = new Float64Array(16);
-const _folded = new Float64Array(16);
-
-/**
- * Whether a frame is one this skin can be deformed in — and if not, by how much it is not.
- *
- * The skinning pass converts `frame⁻¹ × joint.global × inverse_bind` to a dual quaternion, and a
- * dual quaternion carries a rotation and a translation and nothing else. So that product must be
- * rigid for every joint. This is that condition as a number: zero when the frame works, and growing
- * with whatever the conversion would have to throw away. `SKINNING_FRAME_PLAN.md` §1 is what
- * happens when it does.
- *
- * **This, and not "do the joints agree", is the precondition.** A file whose rest pose is not its
- * bind pose has joints whose skin matrices differ — by *rigid* motions, which cost nothing here.
- * What cannot be absorbed is a scale or a shear, and this sees exactly that.
- *
- * Reads the joints' `transform_global`, so it answers for whatever pose the skeleton is standing in.
- * At rest that is the registration-time question. Handed a posed skeleton it answers the runtime one
- * — a clip that scales a joint, which no frame can fix (§4).
- *
- * @param {Skin} skin
- * @param {ArrayLike<number>} frame 16 elements, column-major — the transform the renderer re-applies
- * @returns {number} the largest {@link m4_rigidity_defect} over the skin's joints; `Infinity` if
- *          `frame` has no inverse, or if any joint's fold comes out a reflection — which scores zero
- *          on the defect and is unrepresentable all the same
- */
-export function skin_frame_defect(skin, frame) {
-    assert.defined(skin, 'skin');
-    assert.equal(skin.isSkin, true, 'skin.isSkin !== true');
-    assert.isArrayLike(frame, 'frame');
-
-    if (!m4_invert(_inverse_frame, frame)) {
-        // a frame with no inverse is not a frame; the skinning pass would divide by that determinant
-        return Infinity;
-    }
-
-    const joint_count = skin.joints.length;
-
-    let worst = 0;
-
-    for (let j = 0; j < joint_count; j++) {
-        skin_joint_matrix(_joint_matrix, skin, j);
-
-        m4_multiply(_folded, _inverse_frame, _joint_matrix);
-
-        if (m4_linear_determinant(_folded) < 0) {
-            /*
-             A reflection. {@link m4_rigidity_defect} reads zero for one — it measures orthonormality,
-             and a reflection is orthonormal — so this is the one way a fold can be unrepresentable
-             and still score perfectly. `quat_from_m3` would answer with a *rotation*, silently, which
-             is precisely the class of failure this check exists to end.
-
-             Not fixable by a frame either: a reflection shared by the frame and every joint cancels
-             and never reaches here, so one that does reach here is a skeleton whose joints disagree
-             about handedness.
-            */
-            return Infinity;
-        }
-
-        const defect = m4_rigidity_defect(_folded);
-
-        if (defect > worst) {
-            worst = defect;
-        }
-    }
-
-    return worst;
-}
-
-/**
- * The determinant of a matrix's upper 3×3 — negative exactly when the transform turns a
- * right-handed basis left-handed.
- *
- * @param {ArrayLike<number>} mat4 column-major
- * @returns {number}
- */
-function m4_linear_determinant(mat4) {
-    const a = mat4[0], b = mat4[4], c = mat4[8];
-    const d = mat4[1], e = mat4[5], f = mat4[9];
-    const g = mat4[2], h = mat4[6], i = mat4[10];
-
-    return a * (e * i - f * h) - b * (d * i - f * g) + c * (d * h - e * g);
-}
-
-/**
- * The same question of one joint, freshly allocated — for a caller that wants to say *which* joint
- * and by how much rather than only the worst of them.
- *
- * @param {Skin} skin
- * @param {ArrayLike<number>} frame
- * @returns {number[]} one defect per joint, in joint order
- */
-export function skin_frame_defect_by_joint(skin, frame) {
-    assert.defined(skin, 'skin');
-    assert.equal(skin.isSkin, true, 'skin.isSkin !== true');
-
-    // f64 throughout: a 100× frame inverted in f32 reports a defect of its own rounding, and this
-    // number is read against a tolerance small enough to see one
-    const inverse_frame = new Float64Array(16);
-
-    if (!m4_invert(inverse_frame, frame)) {
-        return skin.joints.map(() => Infinity);
-    }
-
-    const joint_matrix = new Float64Array(16);
-    const folded = new Float64Array(16);
-
-    return skin.joints.map((_joint, j) => {
-        skin_joint_matrix(joint_matrix, skin, j);
-
-        m4_multiply(folded, inverse_frame, joint_matrix);
-
-        // the same refusal {@link skin_frame_defect} makes, so that the gate and the diagnostic
-        // that explains it cannot disagree about which joints are the problem
-        if (m4_linear_determinant(folded) < 0) {
-            return Infinity;
-        }
-
-        return m4_rigidity_defect(folded);
-    });
-}

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

@@ -1,46 +0,0 @@
-import { assert } from "../../../core/assert.js";
-import { m4_multiply } from "../../../core/geom/3d/mat4/m4_multiply.js";
-
-/**
- * One joint's skin matrix, in the pose its node currently holds: `joint.global × inverse_bind`.
- *
- * The same quantity `shader_skin_matrix_prep` writes to the GPU's `skin_matrices` buffer, and the
- * same one `compute_skin_world_bounds` composes its box out of — kept here so the CPU-side callers
- * that reason about a skin's geometry all read it from one place rather than three.
- *
- * It maps a vertex from the skin's mesh space into **world** space. The mesh node's own transform
- * does not appear and must not: glTF says a skinned mesh's node transform is ignored, and this
- * engine's arrangement is that the skinning pass folds its inverse in and the rasterizer re-applies
- * it, so the two cancel. See `SKINNING_FRAME_PLAN.md` for what that fold requires of an asset.
- *
- * Not a per-frame path. Joints the pose accumulator drives are {@link TransformAuthority.GPU} and
- * their `transform_global` holds the rest pose the CPU seeded, so what this answers for an animated
- * character is the rest-pose matrix — which is exactly what the frame arithmetic wants, and is not
- * what a renderer wants.
- *
- * @param {Float64Array|Float32Array|number[]} out 16 elements, column-major
- * @param {Skin} skin
- * @param {number} joint_index
- * @returns {Float64Array|Float32Array|number[]} `out`
- */
-export function skin_joint_matrix(out, skin, joint_index) {
-    assert.isArrayLike(out, 'out');
-    assert.defined(skin, 'skin');
-    assert.equal(skin.isSkin, true, 'skin.isSkin !== true');
-    assert.isNonNegativeInteger(joint_index, 'joint_index');
-    assert.lessThan(joint_index, skin.joints.length, 'joint_index');
-
-    const offset = joint_index * 16;
-
-    assert.greaterThanOrEqual(
-        skin.inverse_bind_matrices.length, offset + 16,
-        'skin.inverse_bind_matrices.length'
-    );
-
-    // a Transform64's matrix starts at element 0, so the transform is its own mat4 argument
-    return m4_multiply(
-        out,
-        skin.joints[joint_index].transform_global,
-        skin.inverse_bind_matrices.subarray(offset, offset + 16)
-    );
-}

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

@@ -1,216 +0,0 @@
-import { assert } from "../../../core/assert.js";
-import { m4_invert } from "../../../core/geom/3d/mat4/m4_invert.js";
-import { m4_multiply } from "../../../core/geom/3d/mat4/m4_multiply.js";
-import { m4_rigidity_defect } from "../../../core/geom/3d/mat4/m4_rigidity_defect.js";
-import { Transform64 } from "../../../engine/ecs/transform/Transform64.js";
-import { skin_bind_transform } from "./skin_bind_transform.js";
-import { skin_frame_defect } from "./skin_frame_defect.js";
-
-/**
- * How far from the bind transform a mesh node may sit and still be left alone, and how large a
- * residual counts as landed.
- *
- * A `Transform64` recomposes its local matrix from f32-ish components, and the correction is applied
- * through that round trip, so the frame arrives with rounding on it. `1e-4` is far below anything
- * that shows — the smallest real violation seen is `99` — and far above the noise.
- *
- * @type {number}
- */
-const TOLERANCE = 1e-4;
-
-/**
- * Put a skin's meshes into the frame the skin actually deforms in.
- *
- * ## What it does and why
- *
- * The skinning pass writes each clone's vertices in `inverse(mesh.global)` space and the rasterizer
- * re-applies `mesh.global`, so `mesh.global` is the *frame* a skinned mesh's vertices live in. The
- * pass gets there by converting `inverse(mesh.global) × joint.global × inverse_bind` to a dual
- * quaternion, which carries a rotation and a translation and **nothing else** — so that product has
- * to be rigid, and whether it is depends entirely on `mesh.global`.
- *
- * glTF says a skinned mesh's node transform is ignored, so it is not the asset's to choose. This
- * makes it the engine's, and sets it to the one frame that is guaranteed to work: the skin's own
- * bind transform, `joint.global × inverse_bind` at rest — see {@link skin_bind_transform}. After
- * this, `inverse(mesh.global) × joint.global × inverse_bind` is the joint's **displacement from
- * bind**, which is rigid whenever the clip rotates and translates and does not scale. That is the
- * honest precondition of dual-quaternion skinning, and it is a property of the animation rather than
- * of the exporter's unit conventions.
- *
- * `SKINNING_FRAME_PLAN.md` is the whole argument, including what a violation looks like on screen.
- *
- * ## Properties worth knowing
- *
- * - **Idempotent.** Afterwards `mesh.global` *is* the bind transform, so a second call computes the
- *   identity and changes nothing. Re-registering a skin is free.
- * - **Placement-invariant.** The correction is `mesh.global⁻¹ × bind`, and anything applied above
- *   both the mesh node and the joints — a placement, a walk cycle moving the character — multiplies
- *   both on the left and cancels. Computed once, correct forever.
- * - **A no-op for an asset that already agrees.** A file whose inverse-bind matrices are authored
- *   before its root's unit conversion has `bind == mesh.global` already and is not touched. That is
- *   the shape this engine's creature models are said to have, and it is what keeps this from being
- *   a change to them.
- *
- * ## What it cannot fix
- *
- * A skin whose *own* bind frame does not work — a rest pose carrying a non-uniform scale or a shear,
- * or joints that disagree about more than a rigid motion. No choice of frame fixes those; a dual
- * quaternion cannot represent them at all. `frame_defect` in the report is that case, and when it
- * fires nothing is written: the mesh is left as the asset had it rather than moved somewhere equally
- * wrong. See `SKINNING_FRAME_PLAN.md` §4 for the ladder out.
- *
- * @param {Skin} skin its joints and meshes must have been walked — this reads `transform_global`,
- *        which is derived. A skin that has never been walked at all is refused rather than
- *        measured; one walked and then moved is the caller's to walk again, and the residual
- *        below is what notices if the mesh half of that was missed
- * @returns {{
- *     frame_defect: number,
- *     absorbed: number,
- *     corrected: number,
- *     unchanged: number,
- *     residual: number,
- *     obstructed: Node3D[],
- *     unwalked: Node3D[],
- * }} `frame_defect` — how far the skin is from being deformable in *any* frame, zero when it is
- *    fine and `NaN` when `unwalked` stopped it being asked; `absorbed` — how far from rigid the largest correction was, which for a violation is the
- *    number the soup was made of; `corrected` and `unchanged` — meshes moved and meshes already
- *    right; `residual` — the worst `|mesh.global − bind|` left afterwards; `obstructed` — corrected
- *    mesh nodes that had children, which have been scaled along with them; `unwalked` — joints or
- *    meshes whose `transform_global` has never been derived, which stops everything else
- */
-export function skin_normalize_mesh_frame(skin) {
-    assert.defined(skin, 'skin');
-    assert.equal(skin.isSkin, true, 'skin.isSkin !== true');
-
-    const unwalked = skin.joints.filter(joint => joint.version === 0)
-        .concat(skin.meshes.filter(mesh => mesh.version === 0));
-
-    const report = {
-        // not measured until there is something worth measuring — see the refusal below
-        frame_defect: Number.NaN,
-        absorbed: 0,
-        corrected: 0,
-        unchanged: 0,
-        residual: 0,
-        obstructed: [],
-        unwalked,
-    };
-
-    if (unwalked.length > 0) {
-        /*
-         Everything below reads `transform_global`, which is derived and starts at the **identity** —
-         not at zero. A skeleton nobody has walked therefore answers "every joint is at the origin"
-         rather than answering with a singular matrix, and that answer is well-formed enough to pass
-         every check here: the folds come out `inverse_bind_0⁻¹ × inverse_bind_j`, which for a real
-         character differ by rigid motions and so read as perfectly rigid. A correction would then be
-         computed from nothing and applied, and the residual below would agree with itself, because
-         both halves of it come from the same unwalked state.
-
-         `version` is the one thing that tells the two apart: `updateMatrices` bumps it, and nothing
-         else does. Refusing here rather than asserting because a caller who has not walked has a
-         scene that is not ready, not a bug in this.
-        */
-        return report;
-    }
-
-    const bind = new Float64Array(16);
-
-    skin_bind_transform(bind, skin);
-
-    report.frame_defect = skin_frame_defect(skin, bind);
-
-    if (!(report.frame_defect <= TOLERANCE)) {
-        // `!(x <= t)` rather than `x > t` so that a NaN — a singular joint matrix — lands here too
-        return report;
-    }
-
-    const inverse_global = new Float64Array(16);
-    const correction_matrix = new Float64Array(16);
-
-    const correction = new Transform64();
-
-    const meshes = skin.meshes;
-
-    for (let i = 0; i < meshes.length; i++) {
-        const mesh = meshes[i];
-
-        if (!m4_invert(inverse_global, mesh.transform_global)) {
-            // a mesh node with no inverse is not a frame either; the skinning pass inverts this
-            report.residual = Infinity;
-            continue;
-        }
-
-        m4_multiply(correction_matrix, inverse_global, bind);
-
-        const absorbed = m4_rigidity_defect(correction_matrix);
-
-        report.absorbed = Math.max(report.absorbed, absorbed);
-
-        if (matrix_distance(correction_matrix, IDENTITY) <= TOLERANCE) {
-            report.unchanged++;
-            continue;
-        }
-
-        /*
-         The correction goes on the **local** transform, on the right. `transform_global` is derived —
-         `updateMatrices` recomputes it from the local and the parent chain — so a frame written
-         there is discarded by the next walk; and the mesh node is the last node on the mesh-only
-         path, so this is the one place a correction reaches the mesh without reaching the joints.
-        */
-        correction.fromMatrix(correction_matrix);
-
-        mesh.transform_local.multiply(correction);
-
-        mesh.updateMatrices();
-
-        report.corrected++;
-        report.residual = Math.max(report.residual, matrix_distance(mesh.transform_global, bind));
-
-        if (mesh.children.length > 0) {
-            /*
-             Children of a skinned mesh node inherit the correction, and it is not a transform they
-             asked for. In this engine sockets, effect anchors and projectile spawns are authored as
-             bones, so a skinned mesh node should have none — but that is a convention, and this is
-             where it would be broken silently.
-            */
-            report.obstructed.push(mesh);
-        }
-    }
-
-    return report;
-}
-
-/**
- * @type {Float64Array}
- */
-const IDENTITY = new Float64Array([
-    1, 0, 0, 0,
-    0, 1, 0, 0,
-    0, 0, 1, 0,
-    0, 0, 0, 1,
-]);
-
-/**
- * The largest element-wise difference between two matrices.
- *
- * Element-wise rather than a norm because it is read against a tolerance, and because the two things
- * it has to catch — a linear part that did not land and a translation that did not — are both
- * element-wise. Mixing units is the point: any of them being wrong is the same answer.
- *
- * @param {ArrayLike<number>} a
- * @param {ArrayLike<number>} b
- * @returns {number}
- */
-function matrix_distance(a, b) {
-    let worst = 0;
-
-    for (let i = 0; i < 16; i++) {
-        const difference = Math.abs(a[i] - b[i]);
-
-        if (difference > worst) {
-            worst = difference;
-        }
-    }
-
-    return worst;
-}

package/src/shade/renderer/scene/InstanceBatch.js

@@ -1,235 +0,0 @@
-import { assert } from "../../../core/assert.js";
-import { array_remove_first } from "../../../core/collection/array/array_remove_first.js";
-import { isArrayEqualStrict } from "../../../core/collection/array/isArrayEqualStrict.js";
-import { AABB3 } from "../../../core/geom/3d/aabb/AABB3.js";
-
-/**
- * @typedef {import("../material/ShadeMaterial.js").ShadeMaterial} ShadeMaterial
- * @typedef {import("./Mesh.js").Mesh} Mesh
- * @typedef {import("./Node3D.js").Node3D} Node3D
- */
-
-/**
- * The renderable side of a {@link Scene} — every {@link Node3D} that the
- * GPU's `transforms` table needs a row for, plus the cached mesh-only
- * filter rendering iterates.
- *
- * Storage is a flat `Node3D[]`. Anything `Mesh`-shaped feeds the
- * {@link instances} view (the renderable subset); everything else (anchor
- * rigs, attachment points, future skeleton joints) still earns a row in
- * the GPU scene-graph because the propagation pass needs to walk the
- * whole hierarchy regardless of which nodes happen to carry geometry.
- *
- * Lights live in {@link Scene.lights}, separately, and are not added
- * here — they have their own GPU pipeline that doesn't share the
- * `transforms` table.
- */
-export class InstanceBatch {
-    /**
-     * Every node ever added — meshes and non-mesh Node3Ds alike. Ordered
-     * by insertion. Consumers that only need geometry-bearing instances
-     * should go through {@link instances} instead, which caches a Mesh-
-     * only filter of this list.
-     *
-     * @type {Node3D[]}
-     */
-    #nodes = [];
-
-    /**
-     *
-     * @type {number}
-     */
-    #version = 0;
-
-    /**
-     * Cached mesh-only view of {@link #nodes}, refreshed lazily on read
-     * whenever {@link #version} drifts.
-     *
-     * @type {Mesh[]}
-     */
-    #cached_instances = [];
-
-    /**
-     * @type {number}
-     */
-    #cached_instances_version = -1;
-
-    /**
-     *
-     * @type {ShadeMaterial[]}
-     */
-    #cached_materials = [];
-
-    /**
-     * @type {number}
-     */
-    #cached_materials_version = -1;
-
-    /**
-     * Set of all materials used in this scene.
-     * Primarily useful for rendering.
-     * @type {ShadeMaterial[]}
-     */
-    get materials() {
-        if (this.#cached_materials_version !== this.#version) {
-            const set = new Set();
-
-            const meshes = this.instances;
-            for (let i = 0; i < meshes.length; i++) {
-                set.add(meshes[i].material);
-            }
-
-            this.#cached_materials_version = this.#version;
-            this.#cached_materials = Array.from(set);
-        }
-
-        return this.#cached_materials;
-    }
-
-    /**
-     *
-     * @param {boolean} v
-     */
-    set needsUpdate(v) {
-        assert.isBoolean(v, 'v');
-
-        if (v) {
-            this.#version++;
-        }
-    }
-
-    /**
-     *
-     * @return {number}
-     */
-    get version() {
-        return this.#version;
-    }
-
-    /**
-     * The mesh-only subset of {@link nodes} — what the rasterization
-     * pipeline iterates. Cached so repeated calls within the same
-     * version are O(1).
-     *
-     * @returns {Mesh[]}
-     */
-    get instances() {
-        if (this.#cached_instances_version !== this.#version) {
-            const out = [];
-            const all = this.#nodes;
-            const n = all.length;
-            for (let i = 0; i < n; i++) {
-                const node = all[i];
-                if (node.isMesh === true) {
-                    out.push(node);
-                }
-            }
-            this.#cached_instances = out;
-            this.#cached_instances_version = this.#version;
-        }
-        return this.#cached_instances;
-    }
-
-    /**
-     * Every node in the batch — the input the GPU scene-graph propagation
-     * pass iterates. Order is insertion order; {@link instances} is
-     * a stable subset.
-     *
-     * @returns {Node3D[]}
-     */
-    get nodes() {
-        return this.#nodes;
-    }
-
-
-    /**
-     * Add a node. Accepts any {@link Node3D} — meshes, anchors, future
-     * skeleton joints. Meshes will additionally appear in
-     * {@link instances} (cached).
-     *
-     * @param {Node3D} node
-     */
-    add(node) {
-        assert.defined(node, 'node');
-        assert.equal(node.isNode3D, true, 'node.isNode3D !== true');
-
-        this.#nodes.push(node);
-
-        this.#version++;
-    }
-
-    /**
-     *
-     * @return {AABB3}
-     */
-    get bounding_box() {
-        const result = new AABB3();
-        result.setNegativelyInfiniteBounds();
-
-        const meshes = this.instances;
-        const n = meshes.length;
-        for (let i = 0; i < n; i++) {
-
-            const box = new AABB3(...meshes[i].bounding_box);
-
-            if (box.width === 0 && box.height === 0 && box.depth === 0) {
-                // ignore 0-size elements as they do not contribute visually
-                continue;
-            }
-
-            result.expandToFit(box);
-
-        }
-
-        return result;
-    }
-
-    /**
-     *
-     * @returns {number}
-     */
-    computeTriangleCount() {
-        let result = 0;
-
-        const meshes = this.instances;
-        const count = meshes.length;
-        for (let i = 0; i < count; i++) {
-            const mesh = meshes[i];
-
-            result += mesh.geometry.getIndexCount() / 3;
-        }
-
-        return result;
-    }
-
-    /**
-     * Remove a node (mesh or otherwise). Returns true if the node was
-     * found and dropped.
-     *
-     * @param {Node3D} node
-     * @returns {boolean}
-     */
-    remove(node) {
-
-        const removed = array_remove_first(this.#nodes, node);
-
-        if (removed) {
-            this.#version++;
-        }
-
-        return removed;
-    }
-
-    hash() {
-        return 0;
-    }
-
-    /**
-     *
-     * @param {InstanceBatch} other
-     */
-    equals(other) {
-        return isArrayEqualStrict(this.#nodes, other.#nodes);
-    }
-
-}