@zephyr3d/scene 0.9.27 → 0.10.0

package/dist/animation/animation_bank.js

@@ -0,0 +1,634 @@
+import { Matrix4x4, Vector3, Quaternion, Disposable } from '@zephyr3d/base';
+import { getDevice } from '../app/api.js';
+import { BoundingBox } from '../utility/bounding_volume.js';
+import { SkinPaletteAtlas } from './skin_palette_atlas.js';
+import { AnimationBankGpuEvaluator } from './animation_bank_gpu.js';
+
+/** Rate clips are sampled at when baked into a bank */ const ANIMATION_BANK_SAMPLE_RATE = 30;
+/** Floats in one baked joint key: position xyz, rotation quaternion xyzw, scale xyz */ const KEY_FLOATS = 10;
+const tmpMatrix = new Matrix4x4();
+const tmpMatrix2 = new Matrix4x4();
+const tmpPosition = new Vector3();
+const tmpRotation = new Quaternion();
+const tmpScale = new Vector3();
+const tmpPoint = new Vector3();
+const tmpPoint2 = new Vector3();
+const tmpHeader = new Float32Array(16);
+/**
+ * Skeletal animation clips of one skin baked into joint poses, played back without the joint
+ * scene nodes the clips were made for.
+ *
+ * @remarks
+ * Every clip is sampled at {@link ANIMATION_BANK_SAMPLE_RATE} frames per second into joint poses
+ * relative to the root of the skin, so that a pose is evaluated per joint without walking the
+ * joint hierarchy.
+ *
+ * A bank is played by {@link AnimationBankTrack}s. Each track owns one palette in the skin palette
+ * atlas, and any number of instances of the model skin their meshes by it, so a crowd costs the
+ * evaluation of its tracks rather than of its characters.
+ *
+ * Meshes skinned by a track do not run IK, joint dynamics or any other skeleton modifier, and do
+ * not blend clips.
+ *
+ * @public
+ */ class AnimationBank extends Disposable {
+    _jointCount;
+    _jointNames;
+    _inverseBindMatrices;
+    _entries;
+    _tracks;
+    _version;
+    /**
+   * Bake clips of an animation set into a bank for one skin.
+   *
+   * @remarks
+   * Sampling poses the joints of the skin; their transforms are restored afterwards. Only tracks
+   * targeting the joints of the skin, or the root joint of its rig, are sampled, and skeleton
+   * modifiers do not run.
+   *
+   * @param animationSet - Animation set holding the clips
+   * @param binding - Skin binding whose joints the clips animate
+   * @param clipNames - Names of the clips to bake, default all clips of the set. More can be added
+   *   later with {@link addClip}
+   */ constructor(animationSet, binding, clipNames){
+        super();
+        this._jointCount = binding.joints.length;
+        this._jointNames = binding.joints.map((joint)=>joint.name);
+        this._inverseBindMatrices = binding.inverseBindMatrices.map((m)=>new Matrix4x4(new Float32Array(m)));
+        this._entries = [];
+        this._tracks = new Set();
+        this._version = 0;
+        const names = clipNames ?? animationSet.getAnimationNames();
+        for (const name of names){
+            this.addClip(animationSet, binding, name);
+        }
+    }
+    /**
+   * Bake one more clip into the bank.
+   *
+   * @param animationSet - Animation set holding the clip
+   * @param binding - Skin binding the bank was baked for, or a compatible one
+   * @param name - Name of the clip
+   * @returns Index of the entry, the existing one if the clip has been baked already, or -1 if
+   *   the clip does not animate the joints of the skin
+   */ addClip(animationSet, binding, name) {
+        const index = this.getEntryIndex(name);
+        if (index >= 0) {
+            return index;
+        }
+        const entry = this.bakeClip(animationSet, binding, name);
+        if (!entry) {
+            return -1;
+        }
+        this._entries.push(entry);
+        this._version++;
+        return this._entries.length - 1;
+    }
+    /** Increased each time a clip is added */ get version() {
+        return this._version;
+    }
+    /** Number of joints of the skin */ get jointCount() {
+        return this._jointCount;
+    }
+    /** Baked clips */ get entries() {
+        return this._entries;
+    }
+    /** Inverse bind matrices of the joints of the skin */ get inverseBindMatrices() {
+        return this._inverseBindMatrices;
+    }
+    /**
+   * Gets the index of a baked clip by name.
+   *
+   * @param name - Name of the clip
+   * @returns Index of the entry, or -1 if the clip has not been baked
+   */ getEntryIndex(name) {
+        return this._entries.findIndex((entry)=>entry.name === name);
+    }
+    /**
+   * Whether a skin binding has the joints this bank was baked for, in the same order.
+   *
+   * @param binding - Skin binding to check
+   */ isCompatible(binding) {
+        const joints = binding.joints;
+        return joints.length === this._jointCount && joints.every((joint, i)=>joint.name === this._jointNames[i]) && // Skins sharing a rig differ by their inverse bind matrices
+        binding.inverseBindMatrices.every((m, i)=>m.equalsTo(this._inverseBindMatrices[i], 1e-4));
+    }
+    /**
+   * Create a track playing a baked clip.
+   *
+   * @param clip - Name or entry index of the clip
+   * @param options - Playback options
+   * @returns The track
+   */ createTrack(clip, options) {
+        const index = typeof clip === 'number' ? clip : this.getEntryIndex(clip);
+        if (index < 0 || index >= this._entries.length) {
+            throw new Error(`AnimationBank.createTrack(): clip not baked: ${clip}`);
+        }
+        const track = new AnimationBankTrack(this, index, options);
+        this._tracks.add(track);
+        return track;
+    }
+    /**
+   * Write the skinning palette of a pose to the skin palette atlas.
+   *
+   * @remarks
+   * The two keys around the position are blended, positions and scales linearly and rotations by
+   * normalized linear interpolation along the shorter arc, and the pose is followed by the inverse
+   * bind matrix.
+   *
+   * @internal
+   */ writePalette(entryIndex, position, slot, out) {
+        const entry = this._entries[entryIndex];
+        const { key0, key1, alpha } = getKeyIndicesFromTime(position, entry.frameCount, entry.playLength);
+        const keys = entry.keys;
+        const n = this._jointCount;
+        for(let i = 0; i < n; i++){
+            blendKeys(keys, (key0 * n + i) * KEY_FLOATS, (key1 * n + i) * KEY_FLOATS, alpha, tmpMatrix);
+            Matrix4x4.multiplyAffine(tmpMatrix, this._inverseBindMatrices[i], tmpMatrix2);
+            out.set(tmpMatrix2, i * 16);
+        }
+        SkinPaletteAtlas.instance.writeSlots(slot, out);
+    }
+    /**
+   * Compute the bounds of a mesh over all frames of a baked clip.
+   *
+   * @param entryIndex - Index of the baked clip
+   * @param mesh - Mesh skinned by the bank
+   * @param binding - Skin binding of the mesh, whose reference node the keys are relative to
+   * @returns Bounds in the local space of the mesh, or null if the mesh has no skinned bounding data
+   * @internal
+   */ computeBoundingBox(entryIndex, mesh, binding) {
+        const info = mesh.skinnedBoundingInfo;
+        if (!info) {
+            return null;
+        }
+        const entry = this._entries[entryIndex];
+        const skinSpace = mesh.getSkinSpaceMatrix(binding);
+        const influenceCount = Math.max(1, info.influenceCount ?? 4);
+        const n = this._jointCount;
+        const box = new BoundingBox();
+        box.beginExtend();
+        for(let frame = 0; frame < entry.frameCount; frame++){
+            for(let v = 0; v < info.boundingVertices.length; v++){
+                tmpPoint.setXYZ(0, 0, 0);
+                for(let j = 0; j < influenceCount; j++){
+                    const weight = Number(info.boundingVertexJointWeights[v * influenceCount + j]) || 0;
+                    const joint = Number(info.boundingVertexBlendIndices[v * influenceCount + j]) || 0;
+                    if (weight <= 0 || joint >= n) {
+                        continue;
+                    }
+                    const offset = (frame * n + joint) * KEY_FLOATS;
+                    blendKeys(entry.keys, offset, offset, 0, tmpMatrix);
+                    Matrix4x4.multiplyAffine(tmpMatrix, this._inverseBindMatrices[joint], tmpMatrix2);
+                    tmpMatrix2.transformPointAffine(info.boundingVertices[v], tmpPoint2).scaleBy(weight);
+                    tmpPoint.addBy(tmpPoint2);
+                }
+                box.extend(skinSpace.transformPointAffine(tmpPoint, tmpPoint));
+            }
+        }
+        return box.isValid() ? box : null;
+    }
+    /** @internal */ removeTrack(track) {
+        this._tracks.delete(track);
+    }
+    /** Dispose all tracks of the bank */ onDispose() {
+        super.onDispose();
+        for (const track of [
+            ...this._tracks
+        ]){
+            track.dispose();
+        }
+    }
+    bakeClip(animationSet, binding, name) {
+        const clip = animationSet.get(name);
+        if (!clip) {
+            console.error(`AnimationBank: animation not found: ${name}`);
+            return null;
+        }
+        const rig = binding.rig;
+        const joints = new Set(binding.joints);
+        if (rig.rootJoint) {
+            joints.add(rig.rootJoint);
+        }
+        const tracks = [
+            ...clip.tracks
+        ].filter(([target])=>joints.has(target));
+        if (tracks.length === 0) {
+            return null;
+        }
+        // Keep the joint transforms so baking leaves the model as it was
+        const saved = [
+            ...joints
+        ].map((joint)=>{
+            const node = joint;
+            return {
+                node,
+                position: node.position.clone(),
+                rotation: node.rotation.clone(),
+                scale: node.scale.clone()
+            };
+        });
+        const playLength = clip.timeDuration;
+        const frameCount = Math.max(1, Math.round(playLength * ANIMATION_BANK_SAMPLE_RATE) + 1);
+        const n = binding.joints.length;
+        const keys = new Float32Array(frameCount * n * KEY_FLOATS);
+        const reference = binding.referenceNode;
+        try {
+            rig.computeBindPose();
+            for(let frame = 0; frame < frameCount; frame++){
+                const time = frameCount > 1 ? playLength * frame / (frameCount - 1) : 0;
+                for (const [target, targetTracks] of tracks){
+                    for (const track of targetTracks){
+                        const t = playLength > 0 ? time / playLength * track.getDuration() : 0;
+                        track.applyState(target, track.calculateState(target, t));
+                    }
+                }
+                const invReference = reference ? Matrix4x4.invertAffine(reference.worldMatrix, tmpMatrix2) : null;
+                for(let i = 0; i < n; i++){
+                    const world = binding.joints[i].worldMatrix;
+                    if (invReference) {
+                        Matrix4x4.multiplyAffine(invReference, world, tmpMatrix);
+                    } else {
+                        tmpMatrix.set(world);
+                    }
+                    tmpMatrix.decompose(tmpScale, tmpRotation, tmpPosition);
+                    const offset = (frame * n + i) * KEY_FLOATS;
+                    keys[offset] = tmpPosition.x;
+                    keys[offset + 1] = tmpPosition.y;
+                    keys[offset + 2] = tmpPosition.z;
+                    keys[offset + 3] = tmpRotation.x;
+                    keys[offset + 4] = tmpRotation.y;
+                    keys[offset + 5] = tmpRotation.z;
+                    keys[offset + 6] = tmpRotation.w;
+                    keys[offset + 7] = tmpScale.x;
+                    keys[offset + 8] = tmpScale.y;
+                    keys[offset + 9] = tmpScale.z;
+                }
+            }
+        } finally{
+            for (const { node, position, rotation, scale } of saved){
+                node.position.set(position);
+                node.rotation.set(rotation);
+                node.scale.set(scale);
+            }
+        }
+        return {
+            name,
+            frameCount,
+            playLength: frameCount > 1 ? playLength : 0,
+            keys
+        };
+    }
+}
+/**
+ * A playing clip of an animation bank, owning one skinning palette that any number of meshes
+ * of compatible skins are skinned by.
+ *
+ * @remarks
+ * Tracks advance once per frame before the skin palette atlas is uploaded. The palette keeps
+ * the previous pose as well, for motion vectors.
+ *
+ * Where supported (WebGPU), palettes are evaluated in a compute pass, see
+ * {@link AnimationBankTrackOptions.evaluation}; elsewhere on the CPU. Both produce the same pose.
+ *
+ * @public
+ */ class AnimationBankTrack extends Disposable {
+    static _activeTracks = new Set();
+    static _updateFrame = -1;
+    _bank;
+    _entryIndex;
+    _position;
+    /** Position at the previous evaluation, for the previous pose of GPU evaluation */ _previousPosition;
+    /** Position the palette was last evaluated at */ _evaluatedPosition;
+    /** Whether the palette is evaluated on the GPU, into fixed current and previous sets */ _gpu;
+    _playRate;
+    _loop;
+    _autoPlay;
+    _block;
+    /** Offsets of the current and previous sets in the block, as `SkinBinding` keeps them */ _offsets;
+    _dirty;
+    _palette;
+    _meshes;
+    /** @internal */ constructor(bank, entryIndex, options){
+        super();
+        this._bank = bank;
+        this._entryIndex = entryIndex;
+        this._playRate = options?.playRate ?? 1;
+        this._loop = options?.loop ?? true;
+        this._autoPlay = options?.autoPlay ?? true;
+        this._position = this.wrap(options?.position ?? 0);
+        this._previousPosition = this._position;
+        this._evaluatedPosition = this._position;
+        this._gpu = (options?.evaluation ?? 'auto') === 'auto' && AnimationBankGpuEvaluator.isSupported();
+        this._block = SkinPaletteAtlas.instance.allocate(bank.jointCount * 2 + 1);
+        this._offsets = [
+            0,
+            0
+        ];
+        this._dirty = true;
+        this._palette = new Float32Array(this._gpu ? 0 : bank.jointCount * 16);
+        this._meshes = new Map();
+        AnimationBankTrack._activeTracks.add(this);
+        if (this._gpu) {
+            // Fixed sets, both rewritten by every dispatch
+            this._offsets[0] = 1;
+            this._offsets[1] = 1 + bank.jointCount;
+            this.writeHeader();
+            AnimationBankGpuEvaluator.addTrack(this);
+        } else {
+            this.evaluate();
+        }
+    }
+    /**
+   * Advance all tracks by the frame time, once per device frame.
+   *
+   * @internal
+   */ static updateAll(deltaInSeconds) {
+        const frame = getDevice().frameInfo.frameCounter;
+        if (frame !== this._updateFrame) {
+            this._updateFrame = frame;
+            for (const track of this._activeTracks){
+                track.update(deltaInSeconds);
+            }
+        }
+    }
+    /** The bank this track plays */ get bank() {
+        return this._bank;
+    }
+    /** Name of the clip playing */ get clipName() {
+        return this._bank.entries[this._entryIndex].name;
+    }
+    /** Length of the clip in seconds */ get playLength() {
+        return this._bank.entries[this._entryIndex].playLength;
+    }
+    /** Playback position in seconds */ get position() {
+        return this._position;
+    }
+    set position(val) {
+        this._position = this.wrap(val);
+        this._dirty = true;
+    }
+    /** Playback rate, negative values play backwards */ get playRate() {
+        return this._playRate;
+    }
+    set playRate(val) {
+        this._playRate = val;
+    }
+    /** Whether playback wraps around at either end */ get loop() {
+        return this._loop;
+    }
+    set loop(val) {
+        this._loop = val;
+    }
+    /** Whether the position advances with time */ get autoPlay() {
+        return this._autoPlay;
+    }
+    set autoPlay(val) {
+        this._autoPlay = val;
+    }
+    /** Slot index of the palette header in the skin palette atlas */ get paletteBase() {
+        return this._block?.base ?? 0;
+    }
+    /** Whether the palette is evaluated on the GPU */ get gpuEvaluated() {
+        return this._gpu;
+    }
+    /** @internal */ get entryIndex() {
+        return this._entryIndex;
+    }
+    /** @internal Position of the previous pose */ get previousPosition() {
+        return this._previousPosition;
+    }
+    /**
+   * Play another clip of the bank, keeping the playback options.
+   *
+   * @remarks
+   * The pose changes at once; tracks do not blend clips. The bounds of attached meshes are
+   * recomputed for the new clip.
+   *
+   * @param clip - Name or entry index of the clip
+   * @param position - Position to start at in seconds, default 0
+   */ setClip(clip, position = 0) {
+        const index = typeof clip === 'number' ? clip : this._bank.getEntryIndex(clip);
+        if (index < 0 || index >= this._bank.entries.length) {
+            throw new Error(`AnimationBankTrack.setClip(): clip not baked: ${clip}`);
+        }
+        this._entryIndex = index;
+        this._position = this.wrap(position);
+        // The previous pose belonged to another clip, so the new one starts still
+        this._previousPosition = this._position;
+        this._evaluatedPosition = this._position;
+        this._dirty = true;
+        for (const mesh of this._meshes.keys()){
+            this.attachMesh(mesh);
+        }
+    }
+    /**
+   * Skin all meshes under a node by this track.
+   *
+   * @remarks
+   * Meshes whose skin binding has other joints than the bank are skipped. The skin bindings of the
+   * attached meshes stop updating their own palettes until detached.
+   *
+   * @param node - Root of the model, typically an instance of the model the bank was baked from
+   * @param binding - If given, only meshes skinned by this binding are attached
+   * @returns Number of meshes attached
+   */ attach(node, binding) {
+        let count = 0;
+        node.iterate((child)=>{
+            if (child.isMesh() && this.attachMesh(child, binding)) {
+                count++;
+            }
+            return false;
+        });
+        return count;
+    }
+    /**
+   * Skin the meshes under a node by their skin bindings again.
+   *
+   * @param node - Node passed to {@link attach}
+   */ detach(node) {
+        node.iterate((child)=>{
+            if (child.isMesh() && this._meshes.has(child)) {
+                this.detachMesh(child);
+            }
+            return false;
+        });
+    }
+    /**
+   * Advance the position by the frame time and write the new pose.
+   *
+   * @internal
+   */ update(deltaInSeconds) {
+        if (this._autoPlay && this._playRate !== 0) {
+            this._position = this.wrap(this._position + this._playRate * deltaInSeconds);
+            this._dirty = true;
+        }
+        if (this._gpu) {
+            // Evaluated by the next dispatch; a still pose evaluates to the same matrices twice
+            this._previousPosition = this._evaluatedPosition;
+            this._evaluatedPosition = this._position;
+            this._dirty = false;
+        } else if (this._dirty) {
+            this.evaluate();
+        } else if (this._offsets[1] !== this._offsets[0]) {
+            // A still pose: point the previous set at the current one so motion vectors become zero
+            this._offsets[1] = this._offsets[0];
+            this.writeHeader();
+        }
+    }
+    /** Release the palette and skin the attached meshes by their skin bindings again */ onDispose() {
+        super.onDispose();
+        for (const mesh of [
+            ...this._meshes.keys()
+        ]){
+            this.detachMesh(mesh);
+        }
+        AnimationBankTrack._activeTracks.delete(this);
+        if (this._gpu) {
+            AnimationBankGpuEvaluator.removeTrack(this);
+        }
+        this._bank.removeTrack(this);
+        if (this._block) {
+            SkinPaletteAtlas.instance.free(this._block);
+            this._block = null;
+        }
+    }
+    attachMesh(mesh, only) {
+        const binding = mesh.findSkinBindingById(mesh.skinBindingName);
+        if (!binding || only && binding !== only || !this._bank.isCompatible(binding)) {
+            return false;
+        }
+        const previous = mesh.getSkinPaletteOverride();
+        if (previous?.owner && previous.owner !== this) {
+            previous.owner.detachMesh(mesh);
+        }
+        if (!this._meshes.has(mesh)) {
+            binding.suspendPalette(true);
+        }
+        const boundingBox = this._bank.computeBoundingBox(this._entryIndex, mesh, binding);
+        this._meshes.set(mesh, boundingBox);
+        mesh.setSkinPaletteOverride({
+            paletteBase: this.paletteBase,
+            boundingBox,
+            owner: this
+        });
+        return true;
+    }
+    /** @internal */ detachMesh(mesh) {
+        if (this._meshes.delete(mesh)) {
+            mesh.findSkinBindingById(mesh.skinBindingName)?.suspendPalette(false);
+            if (mesh.getSkinPaletteOverride()?.owner === this) {
+                mesh.setSkinPaletteOverride(null);
+            }
+        }
+    }
+    /** Write the pose at the position into the set not holding the previous pose */ evaluate() {
+        if (!this._block) {
+            return;
+        }
+        const n = this._bank.jointCount;
+        if (this._offsets[0] === 0) {
+            this._offsets[0] = 1;
+            this._offsets[1] = 1;
+        } else {
+            this._offsets[1] = this._offsets[0];
+            this._offsets[0] = n - this._offsets[0] + 2;
+        }
+        this._bank.writePalette(this._entryIndex, this._position, this._block.base + this._offsets[0], this._palette);
+        this.writeHeader();
+        this._dirty = false;
+    }
+    writeHeader() {
+        const base = this._block.base;
+        tmpHeader[0] = base + this._offsets[0];
+        tmpHeader[1] = base + this._offsets[1];
+        SkinPaletteAtlas.instance.writeSlots(base, tmpHeader);
+    }
+    wrap(position) {
+        const length = this.playLength;
+        if (this._loop) {
+            position = length === 0 ? 0 : position % length;
+            if (position < 0) {
+                position += length;
+            }
+            return position;
+        }
+        return Math.min(Math.max(position, 0), length);
+    }
+}
+function getKeyIndicesFromTime(time, numKeys, sequenceLength) {
+    if (time <= 0 || numKeys === 1) {
+        return {
+            key0: 0,
+            key1: 0,
+            alpha: 0
+        };
+    }
+    const lastIndex = numKeys - 1;
+    if (time >= sequenceLength) {
+        return {
+            key0: lastIndex,
+            key1: 0,
+            alpha: 0
+        };
+    }
+    const keyPos = time * (lastIndex / sequenceLength);
+    const key0 = Math.min(Math.max(Math.floor(keyPos), 0), lastIndex);
+    const alpha = keyPos - key0;
+    const key1 = key0 + 1 === numKeys ? key0 : key0 + 1;
+    return {
+        key0,
+        key1,
+        alpha
+    };
+}
+/** Blend two keys into a joint pose matrix */ function blendKeys(keys, a, b, alpha, out) {
+    const beta = 1 - alpha;
+    // Rotations are normalized before and after blending, along the shorter arc
+    let ax = keys[a + 3], ay = keys[a + 4], az = keys[a + 5], aw = keys[a + 6];
+    let bx = keys[b + 3], by = keys[b + 4], bz = keys[b + 5], bw = keys[b + 6];
+    let len = Math.hypot(ax, ay, az, aw) || 1;
+    ax /= len;
+    ay /= len;
+    az /= len;
+    aw /= len;
+    len = Math.hypot(bx, by, bz, bw) || 1;
+    const sign = ax * bx + ay * by + az * bz + aw * bw < 0 ? -1 / len : 1 / len;
+    bx *= sign;
+    by *= sign;
+    bz *= sign;
+    bw *= sign;
+    let x = ax * beta + bx * alpha;
+    let y = ay * beta + by * alpha;
+    let z = az * beta + bz * alpha;
+    let w = aw * beta + bw * alpha;
+    len = Math.hypot(x, y, z, w) || 1;
+    x /= len;
+    y /= len;
+    z /= len;
+    w /= len;
+    const sx = keys[a + 7] * beta + keys[b + 7] * alpha;
+    const sy = keys[a + 8] * beta + keys[b + 8] * alpha;
+    const sz = keys[a + 9] * beta + keys[b + 9] * alpha;
+    // Column-major translation * rotation * scale
+    out[0] = (1 - 2 * (y * y + z * z)) * sx;
+    out[1] = 2 * (x * y + z * w) * sx;
+    out[2] = 2 * (x * z - y * w) * sx;
+    out[3] = 0;
+    out[4] = 2 * (x * y - z * w) * sy;
+    out[5] = (1 - 2 * (x * x + z * z)) * sy;
+    out[6] = 2 * (y * z + x * w) * sy;
+    out[7] = 0;
+    out[8] = 2 * (x * z + y * w) * sz;
+    out[9] = 2 * (y * z - x * w) * sz;
+    out[10] = (1 - 2 * (x * x + y * y)) * sz;
+    out[11] = 0;
+    out[12] = keys[a] * beta + keys[b] * alpha;
+    out[13] = keys[a + 1] * beta + keys[b + 1] * alpha;
+    out[14] = keys[a + 2] * beta + keys[b + 2] * alpha;
+    out[15] = 1;
+    return out;
+}
+
+export { ANIMATION_BANK_SAMPLE_RATE, AnimationBank, AnimationBankTrack };
+//# sourceMappingURL=animation_bank.js.map