@woosh/meep-engine 3.39.0 → 3.41.0

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

@@ -18,12 +18,15 @@ import { POSE_ACCUMULATOR_SLOT_BYTES } from "./POSE_ACCUMULATOR_LAYOUT.js";
 import { GPUStateAuthorityFlags } from "../../../engine/ecs/gpu/GPUStateAuthorityFlags.js";
 import { gpu_authority_grant } from "../../../engine/ecs/gpu/gpu_authority_grant.js";
 import { gpu_authority_revoke } from "../../../engine/ecs/gpu/gpu_authority_revoke.js";
+import { gpu_authority_held } from "../../../engine/ecs/gpu/gpu_authority_held.js";
+import { GPU_AUTHORITY_EVENT_HOLD_CHANGE } from "../../../engine/ecs/gpu/GPU_AUTHORITY_EVENT_HOLD_CHANGE.js";
 import { row_of_entity } from "../scene/rows/GPUSceneRows.js";
 import { gpu_authority_declare } from "../../../engine/ecs/gpu/gpu_authority_declare.js";
 import { TransformAttachment } from "../../../engine/ecs/transform-attachment/TransformAttachment.js";
 import { TRANSFORM_ATTACHMENT_EVENT_CHANGE } from "../../../engine/ecs/transform-attachment/TRANSFORM_ATTACHMENT_EVENT_CHANGE.js";
 import { Transform64 } from "../../../engine/ecs/transform/Transform64.js";
 import { pose_evaluate_local } from "./pose/pose_evaluate_local.js";
+import { PosePlayback } from "./pose/PosePlayback.js";
 import {
     shader_animation_apply,
     WORKGROUP_SIZE as ANIMATION_APPLY_WORKGROUP_SIZE,
@@ -61,12 +64,45 @@ const SEED = new Transform64();
  * The one playback a released joint is evaluated against: the clip that just left it, at the
  * time and weight it was last set to.
  *
- * @type {{clip: ShadeAnimationClip|null, time: number, weight: number}}
+ * @type {PosePlayback}
  */
-const SEED_PLAYBACK = { clip: null, time: 0, weight: 1 };
+const SEED_PLAYBACK = new PosePlayback();
 
 const SEED_PLAYBACKS = [SEED_PLAYBACK];
 
+/**
+ * The pose an entity rests at: the rest the CPU twin is handed for it (`pose_evaluate_local`'s
+ * `rest`, chosen as `t64_evaluate_world` and `T64WorldCache` choose it) — its offset from its
+ * parent, or its own pose when it is attached to nothing.
+ *
+ * @param {EntityComponentDataset} dataset
+ * @param {number} entity
+ * @returns {Transform64}
+ */
+function rest_of(dataset, entity) {
+    const attachment = dataset.getComponent(entity, TransformAttachment);
+
+    return attachment !== undefined && attachment !== null && dataset.entityExists(attachment.parent)
+        ? attachment.transform
+        : dataset.getComponent(entity, Transform64);
+}
+
+/**
+ * The rotation an entity rests at, `[x, y, z, w]` — see {@link rest_of}. Read when a clip binds
+ * the entity, which is when its offset becomes the GPU's: this side writes no local pose into a
+ * driven entity's row after that. And read again when a CPU writer's hold on it ends, which is
+ * when its offset becomes the GPU's again — see {@link GPUAnimationManager#unmute}.
+ *
+ * @param {EntityComponentDataset} dataset
+ * @param {number} entity
+ * @returns {number[]}
+ */
+function rest_rotation_of(dataset, entity) {
+    const rest = rest_of(dataset, entity);
+
+    return [rest.rotation_x, rest.rotation_y, rest.rotation_z, rest.rotation_w];
+}
+
 /*
  Generated writers for the rows a registration adds as a run. Through `add_run` every row is a
  reflective walk of its type, and a run is one row per keyframe, binding or joint where a chain
@@ -96,10 +132,40 @@ const CLIP_BINDINGS_WRITER = generate_record_writer(ANIMATION_CLIP_STATE_STRUCT,
  */
 const CLIP_FLAGS_WORD = ANIMATION_CLIP_STATE_STRUCT.get('flags').offset / 4;
 
+/**
+ * Word of a clip record holding the first row of its bindings — where a target's binding is found.
+ */
+const CLIP_BINDINGS_FIRST_WORD = ANIMATION_CLIP_STATE_STRUCT.get('bindings_first').offset / 4;
+
+/**
+ * A binding's `instance` alone: what muting a held target's binding writes.
+ */
+const BINDING_INSTANCE_WRITER = generate_record_writer(ANIMATION_TRACK_BINDING_STRUCT, ['instance']);
+
+/**
+ * Scratch record for {@link BINDING_INSTANCE_WRITER}.
+ *
+ * @type {{instance: number}}
+ */
+const BINDING_INSTANCE = { instance: 0 };
+
+/**
+ * A binding's `instance` and `rest_rotation`: what unmuting it when its target's hold ends writes.
+ */
+const BINDING_UNMUTE_WRITER = generate_record_writer(ANIMATION_TRACK_BINDING_STRUCT, ['instance', 'rest_rotation']);
+
+/**
+ * Scratch record for {@link BINDING_UNMUTE_WRITER}.
+ *
+ * @type {{instance: number, rest_rotation: number[]}}
+ */
+const BINDING_UNMUTE = { instance: 0, rest_rotation: [0, 0, 0, 1] };
+
 /**
  * Word of a skin record holding its first joint row — where its matrices start.
  */
 const SKIN_JOINTS_FIRST_WORD = ANIMATION_SKIN_STRUCT.get('joints_first').offset / 4;
+const SKIN_JOINT_COUNT_WORD = ANIMATION_SKIN_STRUCT.get('joint_count').offset / 4;
 
 /**
  * A joint's `node` alone — what naming a pending skin's nodes writes, and all it uploads.
@@ -260,12 +326,14 @@ export class GPUAnimationManager {
     #skin_matrix_count = 0;
 
     /**
-     * How many bound clips drive each entity, by entity. An entity's local TRS is the GPU's for
-     * as long as this is above zero: the first clip to bind grants `GPUStateAuthority`'s
-     * TransformAttachment bit, the last to unbind revokes it and marks the row so the CPU writes
-     * the rest pose back. Stated on the entity, never inferred from the bindings.
+     * The bound clips that drive each entity, by entity — counted by the list's length, and named
+     * so that a hold can find the bindings to mute. An entity's local TRS is the GPU's while the
+     * list is not empty and no CPU writer holds it: the first clip to bind grants
+     * `GPUStateAuthority`'s TransformAttachment bit, the last to unbind revokes it and marks the
+     * row so the CPU writes the rest pose back. Stated on the entity, never inferred from the
+     * bindings.
      *
-     * @type {Map<number, number>}
+     * @type {Map<number, number[]>}
      */
     #clips_driving = new Map();
 
@@ -295,7 +363,9 @@ export class GPUAnimationManager {
      *
      * Lazily allocated on first {@link ensure_pose_accumulator_capacity};
      * grows by doubling. Grow destroys the old buffer — since resolve
-     * always leaves it zero, no copy is needed on grow.
+     * drains every sum and dirty mask, and the rest rotations are stored
+     * afresh by the contributions of the frame that reads them, no copy
+     * is needed on grow.
      *
      * @type {GPUBuffer|null}
      */
@@ -510,9 +580,10 @@ export class GPUAnimationManager {
      * by the per-frame dispatch driver after `scene.build` has
      * stabilised the transforms-table size for the frame.
      *
-     * Grow destroys the previous GPU buffer; resolve always leaves the
-     * accumulator zeroed at the end of each frame, so there's nothing
-     * to copy across the realloc.
+     * Grow destroys the previous GPU buffer; resolve drains every sum
+     * and dirty mask at the end of each frame, and a slot's rest
+     * rotation is stored afresh by every frame that reads it, so there's
+     * nothing to copy across the realloc.
      *
      * @param {number} row_count
      */
@@ -580,6 +651,23 @@ export class GPUAnimationManager {
         return joints_first;
     }
 
+    /**
+     * How many joints the skin has — rows of the `skin_matrices` scratch buffer from
+     * {@link get_skin_matrix_offset}. Fixed once the skin is registered.
+     *
+     * @param {number} skin_id
+     * @returns {number}
+     */
+    get_skin_joint_count(skin_id) {
+        assert.isNonNegativeInteger(skin_id, 'skin_id');
+
+        const joint_count = this.#database.get('animation_skins').get_word(skin_id, SKIN_JOINT_COUNT_WORD);
+
+        assert.defined(joint_count, `unknown skin_id ${skin_id}`);
+
+        return joint_count;
+    }
+
     /**
      * Add an animation curve. Its keyframes go into `animation_keyframes` as one run of rows, in
      * order, and the curve's header names the run.
@@ -667,11 +755,15 @@ export class GPUAnimationManager {
      * playing, not looping). The clip is inert at creation — call
      * {@link start} to begin GPU-side time advancement.
      *
+     * Each binding states its target's `rest_rotation`, `[x, y, z, w]`: what a Node3D target's
+     * rotation resolves to in a frame where every rotation contributed to it sums to nothing. Only
+     * a Node3D rotation binding reads it; {@link register_clip} takes it from the target entity.
+     *
      * @param {{
      *     time?: number,
      *     time_start?: number,
      *     time_end?: number,
-     *     bindings: Array<{ track: number, instance: number, property: number }>,
+     *     bindings: Array<{ track: number, instance: number, property: number, rest_rotation: ArrayLike<number> }>,
      * }} clip
      * @returns {number} clip id (index into the `animation_clips` table)
      */
@@ -706,8 +798,15 @@ export class GPUAnimationManager {
             assert.isNonNegativeInteger(b.track, `clip.bindings[${i}].track`);
             assert.isNonNegativeInteger(b.instance, `clip.bindings[${i}].instance`);
             assert.isNonNegativeInteger(b.property, `clip.bindings[${i}].property`);
+            assert.equal(b.rest_rotation.length, 4, `clip.bindings[${i}].rest_rotation.length`);
 
-            rows[i] = { track: b.track, instance: b.instance, property: b.property, clip: clip_id };
+            rows[i] = {
+                track: b.track,
+                instance: b.instance,
+                property: b.property,
+                clip: clip_id,
+                rest_rotation: b.rest_rotation
+            };
         }
 
         const bindings_first = this.#database.get('animation_bindings').add_run_records(rows, BINDING_WRITER);
@@ -1176,6 +1275,7 @@ export class GPUAnimationManager {
      */
     #try_complete_clip(pending) {
         const rows = this.#scene_context.rows;
+        const dataset = rows.dataset;
         const channels = pending.channels;
         const clip_id = pending.clip_id;
 
@@ -1190,9 +1290,15 @@ export class GPUAnimationManager {
 
             bindings[i] = {
                 track: ch.track,
-                instance: row_of_entity(target),
+                // a target a CPU writer holds is bound muted: see #mute
+                instance: gpu_authority_held(dataset, target, GPUStateAuthorityFlags.TransformAttachment)
+                    ? GPU_DATABASE_NULL
+                    : row_of_entity(target),
                 property: ch.property,
                 clip: clip_id,
+                // a held target's rest is the holder's pose of the moment, taken again when the
+                // hold ends: see #unmute
+                rest_rotation: rest_rotation_of(rows.dataset, target),
             };
         }
 
@@ -1209,8 +1315,9 @@ export class GPUAnimationManager {
 
     /**
      * Hand the entities a clip drives to the GPU: the first clip to bind an entity grants its
-     * TransformAttachment authority. Counted per entity, because two clips can drive one joint
-     * and it is the GPU's until the last of them leaves.
+     * TransformAttachment authority — unless a CPU writer holds it, which the grant leaves be.
+     * Listed per entity, because two clips can drive one joint and it is the GPU's until the last
+     * of them leaves.
      *
      * @param {number} clip_id
      * @param {Array<{target: number}>} channels
@@ -1231,9 +1338,13 @@ export class GPUAnimationManager {
 
             targets.push(target);
 
-            const count = driving.get(target) ?? 0;
+            let clips = driving.get(target);
+
+            if (clips === undefined) {
+                clips = [];
+
+                driving.set(target, clips);
 
-            if (count === 0) {
                 /*
                  The first clip to drive a joint takes its offset, and with it the joint's world
                  and every world below: the hierarchy pass composes the subtree from the rows, and
@@ -1246,15 +1357,22 @@ export class GPUAnimationManager {
                     GPUStateAuthorityFlags.TransformAttachment | GPUStateAuthorityFlags.Transform64
                 );
 
+                // The offset as it stands is the clip's rest, and the row's on every axis it does
+                // not key: an announcement still waiting for the flush is skipped once the bit is set.
+                rows.mark_handover(target);
+
                 rows.for_each_descendant(target, descendant => {
                     // a prefab declares its animated subtree; an entity attached under a joint
                     // from elsewhere is declared here, at the one moment it is taken
                     gpu_authority_declare(dataset, descendant);
                     gpu_authority_grant(dataset, descendant, GPUStateAuthorityFlags.Transform64);
                 });
+
+                // A CPU writer may hold the offset now or later; it says so on the entity.
+                dataset.addEntityEventListener(target, GPU_AUTHORITY_EVENT_HOLD_CHANGE, this.#hold_changed, this);
             }
 
-            driving.set(target, count + 1);
+            clips.push(clip_id);
         }
 
         this.#targets_by_clip.set(clip_id, targets);
@@ -1313,11 +1431,11 @@ export class GPUAnimationManager {
 
         for (let i = 0; i < targets.length; i++) {
             const target = targets[i];
-            const count = driving.get(target) - 1;
+            const clips = driving.get(target);
 
-            if (count > 0) {
-                driving.set(target, count);
+            clips.splice(clips.indexOf(clip_id), 1);
 
+            if (clips.length > 0) {
                 continue;
             }
 
@@ -1327,6 +1445,8 @@ export class GPUAnimationManager {
                 continue;
             }
 
+            dataset.removeEntityEventListener(target, GPU_AUTHORITY_EVENT_HOLD_CHANGE, this.#hold_changed, this);
+
             /*
              The joint's offset comes back to the CPU seeded with the pose the clip left it in,
              evaluated at the clip's own last time and weight — what the accumulator last
@@ -1334,10 +1454,22 @@ export class GPUAnimationManager {
              snapping to the rest pose. Then the world of the joint and of everything under it
              that no other clip still drives from above, and the announcement that recomposes
              the returned subtree on this side and marks the row.
+
+             Unless a CPU writer holds the offset — a cloth simulating a cape joint the clip also
+             keyed. Then the offset was never the clip's to hand back, and what the holder last
+             wrote stands, after the hold as well: nothing binds the joint to take it back when the
+             hold ends, so it stays the CPU's wherever the holder left it. That is the seed's own
+             rule rather than an exception to it. The seed carries on from what is on screen, and a
+             held joint shows its holder: the clip has been muted since the hold began, or since it
+             bound, so its last pose is one the joint has not shown since, and seeding it would
+             snap the joint there until the holder's next write put its own back. A holder that
+             wants another offset left behind — one it captured — writes it before it lets go.
             */
             const attachment = dataset.getComponent(target, TransformAttachment);
 
-            if (attachment !== undefined && attachment !== null && shadow !== undefined) {
+            const held = gpu_authority_held(dataset, target, GPUStateAuthorityFlags.TransformAttachment);
+
+            if (!held && attachment !== undefined && attachment !== null && shadow !== undefined) {
                 SEED_PLAYBACK.clip = shadow.clip;
                 SEED_PLAYBACK.time = shadow.time;
                 SEED_PLAYBACK.weight = shadow.weight;
@@ -1370,6 +1502,120 @@ export class GPUAnimationManager {
         }
     }
 
+    /**
+     * A CPU writer took or gave back the offset of an entity a clip drives — see
+     * `GPUStateAuthority#held`. Listened for on every driven entity, from the first clip that binds
+     * it to the last that leaves.
+     *
+     * Taken: every binding naming the entity is muted, and the hold has already cleared the bit,
+     * so from the next frame the row is the holder's offset and nothing else; the row is marked so
+     * the flush carries it whether or not the holder has announced a write yet. Given back with a
+     * clip still bound: unmuted with the rest the holder left, the row marked so that offset goes
+     * up with it (`GPUSceneRows#mark_handover`), and the joint is the clip's again.
+     *
+     * @param {number} _event the entity, as {@link gpu_authority_hold} sends it
+     * @param {number} entity
+     */
+    #hold_changed(_event, entity) {
+        const rows = this.#scene_context.rows;
+        const dataset = rows.dataset;
+
+        if (gpu_authority_held(dataset, entity, GPUStateAuthorityFlags.TransformAttachment)) {
+            this.#mute(entity);
+
+            rows.mark_local(entity);
+        } else {
+            this.#unmute(entity, dataset);
+
+            rows.mark_handover(entity);
+
+            gpu_authority_grant(dataset, entity, GPUStateAuthorityFlags.TransformAttachment);
+        }
+    }
+
+    /**
+     * Point every binding that names `entity` — in every clip driving it — at
+     * {@link GPU_DATABASE_NULL}.
+     *
+     * **The bit does not stop a clip on the GPU.** No pass reads `GPUStateAuthority`: the apply
+     * pass adds every binding into its target's accumulator slot and the resolve writes the row,
+     * after the CPU's flush, every frame, whatever its weight. So a held joint whose bindings still
+     * named its row would show the clip and not its holder. A muted binding names no object —
+     * `write_object_property` writes nothing for the type bits of {@link GPU_DATABASE_NULL} —
+     * so its target's slot stays empty and the resolve leaves the row as the flush wrote it. The
+     * rest of the clip plays as before.
+     *
+     * Only the `instance` word of each binding is written.
+     *
+     * @param {number} entity
+     */
+    #mute(entity) {
+        BINDING_INSTANCE.instance = GPU_DATABASE_NULL;
+
+        this.#write_bindings(entity, BINDING_INSTANCE, BINDING_INSTANCE_WRITER);
+    }
+
+    /**
+     * The reverse of {@link #mute}, when the hold ends: every binding naming `entity` names its row
+     * again, and carries the rest the entity has now.
+     *
+     * The rest a binding took when it bound is not the rest any more. The holder wrote the offset
+     * all through the hold and leaves it where it leaves it — its last pose, or one it captured and
+     * put back — and that offset is the rest the CPU twin reads from here on. A binding that bound
+     * before the hold took the rest from before it; one that bound during it, muted, took the
+     * holder's pose of that moment. Either would resolve a rotation summing to nothing somewhere the
+     * twin does not, and a socket would sit off the drawn mesh.
+     *
+     * @param {number} entity
+     * @param {EntityComponentDataset} dataset
+     */
+    #unmute(entity, dataset) {
+        const rest = rest_of(dataset, entity);
+        const rest_rotation = BINDING_UNMUTE.rest_rotation;
+
+        BINDING_UNMUTE.instance = row_of_entity(entity);
+
+        rest_rotation[0] = rest.rotation_x;
+        rest_rotation[1] = rest.rotation_y;
+        rest_rotation[2] = rest.rotation_z;
+        rest_rotation[3] = rest.rotation_w;
+
+        this.#write_bindings(entity, BINDING_UNMUTE, BINDING_UNMUTE_WRITER);
+    }
+
+    /**
+     * Write `fields` into every binding that names `entity`, in every clip driving it. A binding's
+     * place in its clip's run is its channel's, so the clip's own channels say which rows of the
+     * run to touch.
+     *
+     * @param {number} entity
+     * @param {object} fields
+     * @param {GPURecordWriter} writer
+     */
+    #write_bindings(entity, fields, writer) {
+        const clips = this.#clips_driving.get(entity);
+
+        if (clips === undefined) {
+            return;
+        }
+
+        const clips_table = this.#database.get('animation_clips');
+        const bindings = this.#database.get('animation_bindings');
+
+        for (let c = 0; c < clips.length; c++) {
+            const clip_id = clips[c];
+
+            const first = clips_table.get_word(clip_id, CLIP_BINDINGS_FIRST_WORD);
+            const channels = this.#playback_by_clip.get(clip_id).clip.channels;
+
+            for (let i = 0; i < channels.length; i++) {
+                if (channels[i].target === entity) {
+                    bindings.set_fields(first + i, fields, writer);
+                }
+            }
+        }
+    }
+
     /**
      * Drop a clip from the manager: its row, and with it the run of its bindings — the clip's range
      * owns the run, so the table removes it. Tolerates the clip still being pending (drains it from

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

@@ -11,15 +11,22 @@
  * Per-axis dirty bits live in a single dirty u32 (atomicOr to set,
  * atomicLoad in resolve, atomicStore(0) to clear).
  *
- * Layout in u32 indices (slot stride = 16 u32s = 64 bytes — 5 u32s of
- * tail padding give the slot a power-of-two stride so addressing is a
+ * Layout in u32 indices (slot stride = 16 u32s = 64 bytes — one u32 of
+ * tail padding gives the slot a power-of-two stride so addressing is a
  * shift, not a multiply):
  *
  *   [0..3]   translation.xyz       (3 atomic<u32>, f32 bitcast)
  *   [3..7]   rotation.xyzw         (4 atomic<u32>, f32 bitcast)
  *   [7..10]  scale.xyz             (3 atomic<u32>, f32 bitcast)
  *   [10]     dirty_mask            (atomic<u32>, see flag bits below)
- *   [11..16] padding
+ *   [11..15] rest_rotation.xyzw    (4 atomic<u32>, f32 bitcast)
+ *   [15]     padding
+ *
+ * `rest_rotation` is not a sum. Every rotation contribution stores its
+ * target's rest rotation there, whatever its weight, and the resolve
+ * writes it to the row when the rotation sum has length zero. It is not
+ * drained: a row is only rotation-dirty in a frame some contribution
+ * stored it afresh.
  *
  * `dirty_mask` bit layout:
  *   bits 0–2: translation x/y/z written this frame
@@ -35,7 +42,7 @@
  */
 /**
  * u32-stride per pose-accumulator slot. Picked to be a power of two so
- * `row << 4` works as the slot offset. 11 u32s are used, 5 are padding.
+ * `row << 4` works as the slot offset. 15 u32s are used, 1 is padding.
  * @type {number}
  */
 export const POSE_ACCUMULATOR_STRIDE: number;
@@ -51,6 +58,7 @@ export const POSE_ACCUMULATOR_OFFSET_TRANSLATION: 0;
 export const POSE_ACCUMULATOR_OFFSET_ROTATION: 3;
 export const POSE_ACCUMULATOR_OFFSET_SCALE: 7;
 export const POSE_ACCUMULATOR_OFFSET_DIRTY: 10;
+export const POSE_ACCUMULATOR_OFFSET_REST_ROTATION: 11;
 /**
  * Dirty-mask bit layout. Per-axis for T/S, single bit for R.
  */

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

@@ -1 +1 @@
-{"version":3,"file":"POSE_ACCUMULATOR_LAYOUT.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/animation/POSE_ACCUMULATOR_LAYOUT.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH;;;;GAIG;AACH,sCAFU,MAAM,CAE0B;AAE1C;;;;;GAKG;AACH,0CAFU,MAAM,CAEuD;AAEvE,gDAAgD;AAChD,oDAAqD;AACrD,iDAAkD;AAClD,8CAA+C;AAC/C,+CAAgD;AAEhD;;GAEG;AACH,mCAAoC;AACpC,mCAAoC;AACpC,mCAAoC;AACpC,kCAAmC;AACnC,mCAAoC;AACpC,mCAAoC;AACpC,mCAAoC"}
+{"version":3,"file":"POSE_ACCUMULATOR_LAYOUT.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/animation/POSE_ACCUMULATOR_LAYOUT.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH;;;;GAIG;AACH,sCAFU,MAAM,CAE0B;AAE1C;;;;;GAKG;AACH,0CAFU,MAAM,CAEuD;AAEvE,gDAAgD;AAChD,oDAAqD;AACrD,iDAAkD;AAClD,8CAA+C;AAC/C,+CAAgD;AAChD,uDAAwD;AAExD;;GAEG;AACH,mCAAoC;AACpC,mCAAoC;AACpC,mCAAoC;AACpC,kCAAmC;AACnC,mCAAoC;AACpC,mCAAoC;AACpC,mCAAoC"}

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

@@ -11,15 +11,22 @@
  * Per-axis dirty bits live in a single dirty u32 (atomicOr to set,
  * atomicLoad in resolve, atomicStore(0) to clear).
  *
- * Layout in u32 indices (slot stride = 16 u32s = 64 bytes — 5 u32s of
- * tail padding give the slot a power-of-two stride so addressing is a
+ * Layout in u32 indices (slot stride = 16 u32s = 64 bytes — one u32 of
+ * tail padding gives the slot a power-of-two stride so addressing is a
  * shift, not a multiply):
  *
  *   [0..3]   translation.xyz       (3 atomic<u32>, f32 bitcast)
  *   [3..7]   rotation.xyzw         (4 atomic<u32>, f32 bitcast)
  *   [7..10]  scale.xyz             (3 atomic<u32>, f32 bitcast)
  *   [10]     dirty_mask            (atomic<u32>, see flag bits below)
- *   [11..16] padding
+ *   [11..15] rest_rotation.xyzw    (4 atomic<u32>, f32 bitcast)
+ *   [15]     padding
+ *
+ * `rest_rotation` is not a sum. Every rotation contribution stores its
+ * target's rest rotation there, whatever its weight, and the resolve
+ * writes it to the row when the rotation sum has length zero. It is not
+ * drained: a row is only rotation-dirty in a frame some contribution
+ * stored it afresh.
  *
  * `dirty_mask` bit layout:
  *   bits 0–2: translation x/y/z written this frame
@@ -36,7 +43,7 @@
 
 /**
  * u32-stride per pose-accumulator slot. Picked to be a power of two so
- * `row << 4` works as the slot offset. 11 u32s are used, 5 are padding.
+ * `row << 4` works as the slot offset. 15 u32s are used, 1 is padding.
  * @type {number}
  */
 export const POSE_ACCUMULATOR_STRIDE = 16;
@@ -54,6 +61,7 @@ export const POSE_ACCUMULATOR_OFFSET_TRANSLATION = 0;
 export const POSE_ACCUMULATOR_OFFSET_ROTATION = 3;
 export const POSE_ACCUMULATOR_OFFSET_SCALE = 7;
 export const POSE_ACCUMULATOR_OFFSET_DIRTY = 10;
+export const POSE_ACCUMULATOR_OFFSET_REST_ROTATION = 11;
 
 /**
  * Dirty-mask bit layout. Per-axis for T/S, single bit for R.

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

@@ -1 +1 @@
-{"version":3,"file":"chunk_pose_accumulator.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/animation/chunk_pose_accumulator.js"],"names":[],"mappings":"AAiBA;;;;;;;;;;;;;;;;GAgBG;AACH,qCAFU,SAAS,CA4FgB;0BA5HT,iCAAiC"}
+{"version":3,"file":"chunk_pose_accumulator.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/animation/chunk_pose_accumulator.js"],"names":[],"mappings":"AAkBA;;;;;;;;;;;;;;;;GAgBG;AACH,qCAFU,SAAS,CAwGgB;0BAzIT,iCAAiC"}

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

@@ -2,6 +2,7 @@ import { CodeChunk } from "../shader/compiler/CodeChunk.js";
 import { chunk_atomic_add_f32_storage } from "../shader/chunk/atomic/chunk_atomic_add_f32_storage.js";
 import {
     POSE_ACCUMULATOR_OFFSET_DIRTY,
+    POSE_ACCUMULATOR_OFFSET_REST_ROTATION,
     POSE_ACCUMULATOR_OFFSET_ROTATION,
     POSE_ACCUMULATOR_OFFSET_SCALE,
     POSE_ACCUMULATOR_OFFSET_TRANSLATION,
@@ -40,6 +41,7 @@ const POSE_OFFSET_TRANSLATION: u32 = ${POSE_ACCUMULATOR_OFFSET_TRANSLATION}u;
 const POSE_OFFSET_ROTATION: u32 = ${POSE_ACCUMULATOR_OFFSET_ROTATION}u;
 const POSE_OFFSET_SCALE: u32 = ${POSE_ACCUMULATOR_OFFSET_SCALE}u;
 const POSE_OFFSET_DIRTY: u32 = ${POSE_ACCUMULATOR_OFFSET_DIRTY}u;
+const POSE_OFFSET_REST_ROTATION: u32 = ${POSE_ACCUMULATOR_OFFSET_REST_ROTATION}u;
 
 const POSE_DIRTY_TX: u32 = ${POSE_DIRTY_TX}u;
 const POSE_DIRTY_TY: u32 = ${POSE_DIRTY_TY}u;
@@ -75,7 +77,7 @@ fn pose_accumulator_add_translation(row: u32, value: vec3<f32>, mask: u32) {
     }
 }
 
-fn pose_accumulator_add_rotation(row: u32, value: vec4<f32>, mask: u32, weight: f32) {
+fn pose_accumulator_add_rotation(row: u32, value: vec4<f32>, mask: u32, weight: f32, rest: vec4<f32>) {
     // Rotation tracks normally cover all four channels (quaternion is one
     // unit). Channels missing from the mask must default to the identity
     // quaternion (0, 0, 0, 1): the evaluator leaves them at 0, which is
@@ -100,6 +102,17 @@ fn pose_accumulator_add_rotation(row: u32, value: vec4<f32>, mask: u32, weight:
     atomic_add_f32_storage(&pose_accumulator[base + 1u], value.y);
     atomic_add_f32_storage(&pose_accumulator[base + 2u], value.z);
     atomic_add_f32_storage(&pose_accumulator[base + 3u], w);
+
+    // The target's rest rotation, stored rather than added, by every contribution whatever its
+    // weight: the resolve writes it when the sum has length zero, which is every clip rotating the
+    // joint playing at weight zero, and by then the row holds the last clip's pose rather than the
+    // rest. Every binding of one target carries the same rest, so concurrent stores agree.
+    let rest_base = pose_accumulator_slot_base(row) + POSE_OFFSET_REST_ROTATION;
+    atomicStore(&pose_accumulator[rest_base + 0u], bitcast<u32>(rest.x));
+    atomicStore(&pose_accumulator[rest_base + 1u], bitcast<u32>(rest.y));
+    atomicStore(&pose_accumulator[rest_base + 2u], bitcast<u32>(rest.z));
+    atomicStore(&pose_accumulator[rest_base + 3u], bitcast<u32>(rest.w));
+
     atomicOr(&pose_accumulator[pose_accumulator_slot_base(row) + POSE_OFFSET_DIRTY], POSE_DIRTY_R);
 }
 

package/src/shade/renderer/animation/pose/PoseChannelIndex.d.ts

@@ -0,0 +1,78 @@
+/**
+ * @typedef {import("../ShadeAnimationChannel.js").ShadeAnimationChannel} ShadeAnimationChannel
+ * @typedef {import("../ShadeAnimationClip.js").ShadeAnimationClip} ShadeAnimationClip
+ */
+/**
+ * What {@link PoseChannelIndex#group_of} answers for an entity the clip has no track for.
+ *
+ * @type {number}
+ */
+export const POSE_CHANNEL_GROUP_NONE: number;
+/**
+ * A clip's channels grouped by the entity each names, for the CPU pose twin to look one entity up
+ * in, rather than scan the whole clip for it once per level of every query.
+ *
+ * The groups are laid end to end in one array, each in the clip's own order, with a table of where
+ * each starts and a {@link Uint32Map} from entity to group: on a 70-joint clip of 210 channels it
+ * holds a few KiB, against the ~25 KiB of the clip itself, and nothing in it is handed out to be
+ * written. Read it with {@link group_of}, {@link first}, {@link end} and {@link channel}.
+ *
+ * Built once per clip ({@link of}) and checked, not rebuilt, each time a playback takes the clip
+ * again.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class PoseChannelIndex {
+    /**
+     * The clip's index, as the clip holds its channels now: the one built before when it still
+     * holds, a new one otherwise.
+     *
+     * @param {ShadeAnimationClip} clip
+     * @returns {PoseChannelIndex}
+     */
+    static of(clip: ShadeAnimationClip): PoseChannelIndex;
+    /**
+     * @param {ShadeAnimationChannel[]} channels a clip's channels
+     */
+    constructor(channels: ShadeAnimationChannel[]);
+    /**
+     * The group of channels naming `entity`, or {@link POSE_CHANNEL_GROUP_NONE} where the clip has no
+     * track for it — which is most entities for most clips.
+     *
+     * @param {number} entity
+     * @returns {number}
+     */
+    group_of(entity: number): number;
+    /**
+     * @param {number} group
+     * @returns {number} the position of the group's first channel
+     */
+    first(group: number): number;
+    /**
+     * @param {number} group
+     * @returns {number} one past the position of the group's last channel
+     */
+    end(group: number): number;
+    /**
+     * @param {number} position from {@link first} up to {@link end}
+     * @returns {ShadeAnimationChannel}
+     */
+    channel(position: number): ShadeAnimationChannel;
+    /**
+     * Whether this still describes `channels`: every channel naming an entity is where this put it
+     * — the same channel, naming the same entity, in the same order among that entity's — and there
+     * are as many as there were. A walk of the clip without allocation.
+     *
+     * @param {ShadeAnimationChannel[]} channels
+     * @returns {boolean}
+     */
+    holds(channels: ShadeAnimationChannel[]): boolean;
+    #private;
+}
+export namespace PoseChannelIndex {
+    let EMPTY: PoseChannelIndex;
+}
+export type ShadeAnimationChannel = import("../ShadeAnimationChannel.js").ShadeAnimationChannel;
+export type ShadeAnimationClip = import("../ShadeAnimationClip.js").ShadeAnimationClip;
+//# sourceMappingURL=PoseChannelIndex.d.ts.map