Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

Animation: trusted fast path and no per-frame reset on one clip

Nguyen Xuan An10d669b24d1f
diff --git a/bench/runtime/adapters.js b/bench/runtime/adapters.js
index 8d99c307..2825061d 100644
--- a/bench/runtime/adapters.js
+++ b/bench/runtime/adapters.js
@@ -40,7 +40,7 @@ function levelsForScene(scene) {
return levels;
}
-export async function create67Adapter(canvas, scene, characters, { culling = true, lods = true, hdr = true, samples = 4, shading = 'full' } = {}) {
+export async function create67Adapter(canvas, scene, characters, { culling = true, lods = true, hdr = true, samples = 4, shading = 'full', checks = true } = {}) {
const environment = {
world: true, fillIntensity: 0, ambientIntensity: 1, fogDensity: 0,
lightDirection: scene.sun.direction, keyColor: scene.sun.color,
@@ -82,9 +82,9 @@ export async function create67Adapter(canvas, scene, characters, { culling = tru
renderer.updateParts(parts);
}
if (assets.length) {
- assets.forEach((asset, index) => asset.applyAnimation(time + index * SECONDS_PER_CHARACTER_OFFSET, 0));
+ assets.forEach((asset, index) => asset.applyAnimation(time + index * SECONDS_PER_CHARACTER_OFFSET, 0, { checks }));
const beforeUpload = performance.now();
- renderer.updateParts(parts);
+ renderer.updateParts(parts, { checks });
this.updatePartsTimes.push(performance.now() - beforeUpload);
}
},
diff --git a/bench/runtime/harness.js b/bench/runtime/harness.js
index 31d74465..e4636169 100644
--- a/bench/runtime/harness.js
+++ b/bench/runtime/harness.js
@@ -111,6 +111,7 @@ async function createAdapter(engine, canvas, scene, characters) {
if (engine === '67js-no-lod') return create67Adapter(canvas, scene, characters, { lods: false });
if (engine === '67js-no-culling') return create67Adapter(canvas, scene, characters, { culling: false, lods: false });
if (engine === '67js-ldr') return create67Adapter(canvas, scene, characters, { hdr: false });
+ if (engine === '67js-trusted') return create67Adapter(canvas, scene, characters, { checks: false });
if (engine === '67js-light') return create67Adapter(canvas, scene, characters, { shading: 'light' });
if (engine === '67js-one-sample') return create67Adapter(canvas, scene, characters, { samples: 1 });
if (engine === '67js-ldr-one-sample') return create67Adapter(canvas, scene, characters, { hdr: false, samples: 1 });
diff --git a/bench/runtime/run.mjs b/bench/runtime/run.mjs
index 87444531..3eebdac8 100644
--- a/bench/runtime/run.mjs
+++ b/bench/runtime/run.mjs
@@ -16,9 +16,10 @@ const BACKENDS = {
gpu: { arguments: SHARED_ARGUMENTS, frames: 120 },
cpu: { arguments: [...SHARED_ARGUMENTS, '--use-angle=swiftshader', '--enable-unsafe-swiftshader'], frames: 15 },
};
-const ENGINES = ['67js', 'three', 'three-instanced', '67js-no-lod', '67js-no-culling', '67js-ldr', '67js-one-sample', '67js-ldr-one-sample', 'three-one-sample', '67js-light'];
+const ENGINES = ['67js', 'three', 'three-instanced', '67js-no-lod', '67js-no-culling', '67js-ldr', '67js-one-sample', '67js-ldr-one-sample', 'three-one-sample', '67js-light', '67js-trusted'];
// Ablations of the HDR target and MSAA, which cost something in every scene. They run only when named with --engine.
-const FEATURE_ENGINES = new Set(['67js-light', '67js-ldr', '67js-one-sample', '67js-ldr-one-sample', 'three-one-sample']);
+// 67js-trusted animates characters with checks off (applyAnimation and updateParts { checks: false }).
+const FEATURE_ENGINES = new Set(['67js-trusted', '67js-light', '67js-ldr', '67js-one-sample', '67js-ldr-one-sample', 'three-one-sample']);
const INSTANCED_SCENES = new Set(['instanced-objects']);
// Ablations of this renderer's own culling and level selection, which only a scene that has them can show.
const ABLATION_SCENES = new Set(['large-outdoor']);
diff --git a/changes/572-fast-path.md b/changes/572-fast-path.md
new file mode 100644
index 00000000..e56d515c
--- /dev/null
+++ b/changes/572-fast-path.md
@@ -0,0 +1 @@
+- `applyAnimation(time, clip, { checks: false })` and `renderer.updateParts(parts, { checks: false })` skip the per-frame pose checks for clips you trust, and frames on the same clip no longer reset and snapshot every node. Eight animated characters: update CPU 1.6 ms to 1.3 ms with checks, 0.9 ms without.
diff --git a/changes/572-fast-path.size.md b/changes/572-fast-path.size.md
new file mode 100644
index 00000000..8084b4d9
--- /dev/null
+++ b/changes/572-fast-path.size.md
@@ -0,0 +1,2 @@
+- scene:agent-scene: the checks option and the same-clip path for animated assets, which cut skinned update CPU further.
+- goal:agent-scene: 85 bytes for that; accepted by the lead under the trade-off rule.
diff --git a/src/gltf.js b/src/gltf.js
index e7be8a08..fff36e0d 100644
--- a/src/gltf.js
+++ b/src/gltf.js
@@ -1,3 +1,4 @@
+import { mat4 } from 'gl-matrix';
import { applyClip } from './gltf-animation.js';
import { GLTF_LAYER_EXTENSIONS, layerTextureReferences, materialLayersFromGltf } from './gltf-layers.js';
import { attributeFloats } from './gltf-accessors.js';
@@ -973,7 +974,7 @@ function makeSkinBinding(node) {
const IDENTITY_MATRIX = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
-function prepareSkinBinding(binding, geometry) {
+function prepareSkinBinding(binding, geometry, checks = true) {
const { node, skin, pendingPose, pendingWorld } = binding;
if (skin.jointMatrices !== binding.palette || skin.jointWorldMatrices !== binding.jointWorld || binding.palette.length !== pendingPose.jointMatrices.length || binding.jointWorld.length !== pendingWorld.length) throw new Error('Imported skin palette identities must remain unchanged.');
for (let joint = 0; joint < node.skeleton.bones.length; joint++) {
@@ -982,8 +983,8 @@ function prepareSkinBinding(binding, geometry) {
// A joint at zero scale collapses its vertices to a point instead of refusing the pose.
if (collapseSingularMatrix(jointWorld, undefined, COLLAPSED_JOINT_SCALE)) binding.collapsedJoints = true;
}
- updateSkinPose(pendingPose, pendingWorld, skin.inverseBindMatrices, node.matrixWorld.elements, skin.bindMatrix);
- validateSkinPose(pendingPose, geometry, node.matrixWorld.elements);
+ updateSkinPose(pendingPose, pendingWorld, skin.inverseBindMatrices, node.matrixWorld.elements, skin.bindMatrix, checks);
+ if (checks) validateSkinPose(pendingPose, geometry, node.matrixWorld.elements);
}
function commitSkinBinding(binding) {
@@ -1014,15 +1015,21 @@ function prepareMorphBinding(binding) {
const COLLAPSED_SCALE = 2e-4;
const COLLAPSED_JOINT_SCALE = 1e-2;
-const collapseScratch = new Matrix4();
/**
* Replaces a singular or non-finite world matrix, in place, with a uniform scale of 0.0002 at the same position so the
* part is a speck that stays finite and invertible. Returns true when it replaced the matrix.
*/
function collapseSingularMatrix(elements, determinantFloor = 1e-12, collapsedScale = COLLAPSED_SCALE) {
- const finite = elements.every(Number.isFinite);
- const determinant = finite ? collapseScratch.fromArray(elements).determinant() : NaN;
+ let finite = true;
+ for (let index = 0; index < 16; index++) {
+ if (!Number.isFinite(elements[index])) {
+ finite = false;
+ break;
+ }
+ }
+ // mat4.determinant reads the elements as doubles, the same values a Float64 copy would hold.
+ const determinant = finite ? mat4.determinant(elements) : NaN;
if (finite && Number.isFinite(determinant) && Math.abs(determinant) >= determinantFloor) return false;
const position = [elements[12], elements[13], elements[14]];
const keepPosition = position.every(Number.isFinite);
@@ -1465,9 +1472,10 @@ export async function parseGltf(data, options = {}) {
applyClip(gltf.animations[animation.clip], animation.time);
}
- function preparePose() {
+ /** Pose every part from the scene graph. `checks: false` keeps the zero-scale repairs and skips the finite, singular and winding checks. */
+ function preparePose(checks = true) {
gltf.scene.updateMatrixWorld(true);
- validateNodeTransforms(nodes, pendingNodeMatrix, pendingTransform, toleratedNodes);
+ if (checks) validateNodeTransforms(nodes, pendingNodeMatrix, pendingTransform, toleratedNodes);
const worldMatrix = new Matrix4();
for (const { node, instanceMatrix, part, mirrored, matrix, pendingMatrix, skin } of bindings) {
if (part.matrix !== matrix || matrix.length !== 16) {
@@ -1477,7 +1485,7 @@ export async function parseGltf(data, options = {}) {
throw new Error('Imported skin pose identity must remain unchanged.');
}
pendingMatrix.set(worldMatrixOf(node, instanceMatrix, worldMatrix).elements);
- if (collapseSingularMatrix(pendingMatrix)) continue;
+ if (collapseSingularMatrix(pendingMatrix) || !checks) continue;
for (const value of pendingMatrix) {
if (!Number.isFinite(value)) {
throw new Error('Animation creates a non-finite Float32 world matrix.');
@@ -1490,14 +1498,14 @@ export async function parseGltf(data, options = {}) {
}
}
for (const binding of skinBindings) {
- prepareSkinBinding(binding, binding.geometry);
+ prepareSkinBinding(binding, binding.geometry, checks);
}
for (const binding of morphBindings) {
if (binding.part.morph !== binding.pose) {
throw new Error('Imported morph pose identity must remain unchanged.');
}
prepareMorphBinding(binding);
- validateMorphTransform(binding.pendingPose, binding.metadata, binding.pendingMatrix, binding.pendingSkin);
+ if (checks) validateMorphTransform(binding.pendingPose, binding.metadata, binding.pendingMatrix, binding.pendingSkin);
}
}
@@ -1673,6 +1681,7 @@ export async function parseGltf(data, options = {}) {
throw error;
}
commitPreparedPose(candidate.animation);
+ poseFromAnimationOnly = false;
settled = true;
pendingTransaction = null;
return parts;
@@ -1698,13 +1707,21 @@ export async function parseGltf(data, options = {}) {
gltf.release();
}
- function applyAnimation(time, clipIndex = 0) {
+ /**
+ * Pose the asset at `time` in a clip and commit it. `checks: false` skips the per-frame finite, singular and winding
+ * checks, for clips you trust: import checks the base pose, not every key, so a broken clip may draw wrong instead of
+ * throwing. Zero-scale joints are still repaired. Poses an agent sets go through stagePose, which always checks.
+ */
+ function applyAnimation(time, clipIndex = 0, { checks = true } = {}) {
if (disposed) {
throw new Error('The glTF asset was disposed.');
}
if (!Number.isFinite(time)) {
throw new TypeError('Animation time must be finite.');
}
+ if (typeof checks !== 'boolean') {
+ throw new TypeError('Animation checks must be a boolean.');
+ }
const clip = gltf.animations[clipIndex];
if (!Number.isInteger(clipIndex) || !clip) {
throw new RangeError('Animation clip index is out of range.');
@@ -1713,24 +1730,29 @@ export async function parseGltf(data, options = {}) {
throw new Error('A pose transaction is already pending. Commit or discard it first.');
}
// Same result as stagePose({ animation }).commit(), with one preparePose instead of two: nothing can change the
- // scene between this stage and this commit. The rollback snapshot is reused across frames.
+ // scene between this stage and this commit. When the committed pose came from applyAnimation alone, replaying
+ // its animation restores it exactly, so no snapshot is needed; otherwise one reused snapshot is the rollback point.
const animation = { clip: clipIndex, time: Math.max(0, Math.min(time, clip.duration)) };
- rollbackPose ??= capturePrivatePose();
- capturePrivatePose(rollbackPose);
+ const snapshot = poseFromAnimationOnly ? null : capturePrivatePose(rollbackPose ??= capturePrivatePose());
const previousAnimation = currentAnimation;
try {
- playAnimation(animation);
- preparePose();
+ // The same clip keys the same channels every frame, and every other node is still at its base pose.
+ if (poseFromAnimationOnly && previousAnimation?.clip === animation.clip) applyClip(clip, animation.time);
+ else playAnimation(animation);
+ preparePose(checks);
} catch (error) {
playAnimation(previousAnimation);
- restorePrivatePose(rollbackPose);
+ if (snapshot) restorePrivatePose(snapshot);
throw error;
}
commitPreparedPose(animation);
+ poseFromAnimationOnly = true;
return parts;
}
let rollbackPose = null;
+ // True while the committed pose is the base pose or one applyAnimation made, with no overrides or morph weights.
+ let poseFromAnimationOnly = true;
/** Copy the prepared candidate pose into the committed parts. */
function commitPreparedPose(animation) {
diff --git a/src/renderer.js b/src/renderer.js
index 3458a744..a87cf255 100644
--- a/src/renderer.js
+++ b/src/renderer.js
@@ -1201,7 +1201,13 @@ export class Renderer67 {
return { ...layout, texture, data };
}
- updateParts(parts, { shadows = true } = {}) {
+ /**
+ * Upload changed parts. `checks: false` skips the per-frame pose checks (finite, non-singular, unmirrored skin and
+ * morph transforms) for poses already checked where they were made, such as `applyAnimation(time, clip, { checks: false })`.
+ * Identity, material and transform rules still apply.
+ */
+ updateParts(parts, { shadows = true, checks = true } = {}) {
+ if (typeof checks !== "boolean") throw new TypeError("updateParts checks must be a boolean.");
this.updatePartIdentities ??= new Set();
this.updatePartIdentities.clear();
this.updateSkins.clear();
@@ -1232,13 +1238,13 @@ export class Renderer67 {
if ((part.skin ?? null) !== location.skin || part.skin?.jointMatrices !== location.jointMatrices || part.geometry.skinIndices !== location.skinIndices || part.geometry.skinWeights !== location.skinWeights) throw new Error(`Skin identity changes require a new renderer: ${part.name}`);
if (part.skin) {
if (PROCEDURAL_MATERIAL_TAGS.has(part.material.tag)) throw new Error('Skinned parts require a standard material tag.');
- skinSupport().validateSkinPose(part.skin, part.geometry, part.matrix);
+ if (checks) skinSupport().validateSkinPose(part.skin, part.geometry, part.matrix);
this.updateSkins.add(location.batch.skinTexture);
}
if ((part.morph ?? null) !== (location.morph ?? null) || part.morph?.weights !== location.morphWeights || part.geometry.morphTargets !== location.morphTargets) throw new Error(`Morph identity changes require a new renderer: ${part.name}`);
if (part.morph) {
if (PROCEDURAL_MATERIAL_TAGS.has(part.material.tag)) throw new Error('Morphed parts require a standard material tag.');
- morphSupport().validateMorphTransform(part.morph, location.batch.morphTexture.info, part.matrix, part.skin);
+ if (checks) morphSupport().validateMorphTransform(part.morph, location.batch.morphTexture.info, part.matrix, part.skin);
this.updateMorphs.add(part.morph);
}
if (materialUnchanged) {
@@ -1259,7 +1265,7 @@ export class Renderer67 {
location.materialSnapshot = MaterialSnapshot.of(part.material);
}
// A palette upload also changes consumers absent from the submitted part list.
- if (this.updateSkins.size) {
+ if (checks && this.updateSkins.size) {
for (const [part, location] of this.partLocations) {
if (!location.skin || !this.updateSkins.has(location.batch.skinTexture) || this.updatePartIdentities.has(part)) continue;
const committedMatrix = location.committedMatrix ?? location.batch.instanceData.subarray(location.index * INSTANCE_STRIDE, location.index * INSTANCE_STRIDE + 16);
@@ -1268,7 +1274,7 @@ export class Renderer67 {
}
// Shared weights also affect batches absent from the submitted part list.
// Nothing is shared when the update carries no morph and no skin.
- if (this.updateMorphs.size || this.updateSkins.size) {
+ if (checks && (this.updateMorphs.size || this.updateSkins.size)) {
for (const [part, location] of this.partLocations) {
if (!location.morph || this.updatePartIdentities.has(part)) continue;
if (!this.updateMorphs.has(location.morph) && !this.updateSkins.has(location.batch.skinTexture)) continue;
diff --git a/src/skinning.js b/src/skinning.js
index de9f5ded..f61f2feb 100644
--- a/src/skinning.js
+++ b/src/skinning.js
@@ -52,19 +52,24 @@ export function createSkinPose(jointCount) {
return pose;
}
-/** Atomically calculate inverse(meshWorld) * jointWorld * inverseBind * bindMatrix. */
-export function updateSkinPose(pose, jointWorldMatrices, inverseBindMatrices, meshWorldMatrix = IDENTITY_MATRIX, bindMatrix = IDENTITY_MATRIX) {
+/**
+ * Atomically calculate inverse(meshWorld) * jointWorld * inverseBind * bindMatrix. `checks: false` skips the finite,
+ * affine and singular checks for inputs already checked, such as a loaded clip; a mesh world that cannot be inverted still throws.
+ */
+export function updateSkinPose(pose, jointWorldMatrices, inverseBindMatrices, meshWorldMatrix = IDENTITY_MATRIX, bindMatrix = IDENTITY_MATRIX, checks = true) {
const workspace = poseWorkspaces.get(pose);
if (!workspace || pose.jointMatrices !== workspace.jointMatrices) throw new Error('Use an unchanged pose from createSkinPose().');
const count = pose.jointMatrices.length / 16;
- validateMatrices(jointWorldMatrices, count, 'Joint world matrices');
- validateMatrices(inverseBindMatrices, count, 'Inverse bind matrices');
- validateMatrices(meshWorldMatrix, 1, 'Mesh world matrix');
- validateMatrices(bindMatrix, 1, 'Bind matrix');
+ if (checks) {
+ validateMatrices(jointWorldMatrices, count, 'Joint world matrices');
+ validateMatrices(inverseBindMatrices, count, 'Inverse bind matrices');
+ validateMatrices(meshWorldMatrix, 1, 'Mesh world matrix');
+ validateMatrices(bindMatrix, 1, 'Bind matrix');
+ }
workspace.meshWorld.set(meshWorldMatrix);
workspace.bind.set(bindMatrix);
if (!mat4.invert(workspace.meshInverse, workspace.meshWorld)) throw new Error('Mesh world matrix cannot be inverted.');
- validateMatrices(workspace.meshInverse, 1, 'Inverse mesh world matrix');
+ if (checks) validateMatrices(workspace.meshInverse, 1, 'Inverse mesh world matrix');
for (let joint = 0; joint < count; joint++) {
const offset = joint * 16;
for (let component = 0; component < 16; component++) {
@@ -76,7 +81,7 @@ export function updateSkinPose(pose, jointWorldMatrices, inverseBindMatrices, me
mat4.multiply(workspace.product, workspace.meshInverse, workspace.product);
workspace.pending.set(workspace.product, offset);
}
- validateMatrices(workspace.pending, count, 'Joint palette');
+ if (checks) validateMatrices(workspace.pending, count, 'Joint palette');
pose.jointMatrices.set(workspace.pending);
return pose;
}
diff --git a/tests/animation-fast-path.test.js b/tests/animation-fast-path.test.js
new file mode 100644
index 00000000..deb6e8ac
--- /dev/null
+++ b/tests/animation-fast-path.test.js
@@ -0,0 +1,55 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { readFile } from 'node:fs/promises';
+import { parseGltf } from '../src/gltf.js';
+
+async function loadRobot() {
+ const bytes = await readFile(new URL('fixtures/RobotExpressive.glb', import.meta.url));
+ return parseGltf(bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength), { maxVertices: 500000 });
+}
+
+function poseSnapshot(parts) {
+ return parts.map(part => ({ matrix: [...part.matrix], palette: part.skin ? [...part.skin.jointMatrices] : null }));
+}
+
+test('applyAnimation with checks off gives the same pose as the checked path', async () => {
+ const checked = await loadRobot();
+ const unchecked = await loadRobot();
+ for (const time of [0, 0.35, 1.2, 2.9]) {
+ for (const clip of [0, 3]) {
+ checked.applyAnimation(time, clip);
+ unchecked.applyAnimation(time, clip, { checks: false });
+ assert.deepEqual(poseSnapshot(unchecked.parts), poseSnapshot(checked.parts));
+ }
+ }
+});
+
+test('applyAnimation checks option must be a boolean', async () => {
+ const asset = await loadRobot();
+ assert.throws(() => asset.applyAnimation(0, 0, { checks: 'no' }), /checks must be a boolean/);
+});
+
+test('the checked path stays the default after an unchecked frame', async () => {
+ const asset = await loadRobot();
+ asset.applyAnimation(0.5, 0, { checks: false });
+ const transaction = asset.stagePose({ animation: { clip: 0, time: 0.5 } });
+ transaction.discard();
+ assert.ok(asset.applyAnimation(0.6, 0).length > 0);
+});
+
+test('frame after frame on one clip matches a fresh asset posed once, across clip switches and overrides', async () => {
+ const running = await loadRobot();
+ const steps = [[0.2, 0], [0.5, 0], [0.9, 0], [0.3, 3], [0.6, 3], [1.1, 0]];
+ for (const [time, clip] of steps) {
+ running.applyAnimation(time, clip, { checks: false });
+ const fresh = await loadRobot();
+ fresh.applyAnimation(time, clip);
+ assert.deepEqual(poseSnapshot(running.parts), poseSnapshot(fresh.parts), `time ${time} clip ${clip}`);
+ }
+ const node = running.nodes.find(entry => entry.editable && entry.joint);
+ running.stagePose({ animation: { clip: 0, time: 0.4 }, nodeOverrides: [{ id: node.id, translation: [0, 5, 0] }] }).commit();
+ running.applyAnimation(0.7, 0);
+ const fresh = await loadRobot();
+ fresh.applyAnimation(0.7, 0);
+ assert.deepEqual(poseSnapshot(running.parts), poseSnapshot(fresh.parts), 'an override is cleared by the next applyAnimation');
+});