Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

Cut skinned frame CPU: offset joint matrix products and an allocation-free joint check (#572)

Nguyen Xuan Anab910020efb5
diff --git a/changes/572-frame.md b/changes/572-frame.md
new file mode 100644
index 00000000..e5747767
--- /dev/null
+++ b/changes/572-frame.md
@@ -0,0 +1 @@
+Skinned character frames cost less CPU: palette math reads joint matrices in place and a normal pose allocates nothing, so eight animated characters update about 0.1 ms faster (#572)
diff --git a/changes/572-frame.size.md b/changes/572-frame.size.md
new file mode 100644
index 00000000..721c45c3
--- /dev/null
+++ b/changes/572-frame.size.md
@@ -0,0 +1,7 @@
+- entry:core: the offset matrix product and the joint check that remove per-joint copies and allocations from the skinned frame.
+- scene:gltf-box: the same skinning and glTF pose code; skinned update CPU about 0.1 ms less for eight characters.
+- scene:gltf-box+lazy: same code as scene:gltf-box.
+- goal:gltf-box: 485 bytes for a faster skinned frame, accepted by the lead under the trade-off rule (a measured speed-up, not a score).
+- scene:agent-scene: the same skinning code, which agent scenes import.
+- scene:agent-scene+lazy: same code as scene:agent-scene.
+- goal:agent-scene: about 200 bytes for the same skinned frame speed-up.
diff --git a/src/gltf.js b/src/gltf.js
index fff36e0d..a04c9715 100644
--- a/src/gltf.js
+++ b/src/gltf.js
@@ -974,14 +974,39 @@ function makeSkinBinding(node) {
const IDENTITY_MATRIX = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
+/** True when collapseSingularMatrix would replace the matrix at this offset: a non-finite value or a determinant below its floor. */
+function needsCollapse(values, offset) {
+ for (let index = offset; index < offset + 16; index++) {
+ if (!Number.isFinite(values[index])) return true;
+ }
+ // The determinant of mat4.determinant, read at an offset.
+ const a00 = values[offset], a01 = values[offset + 1], a02 = values[offset + 2], a03 = values[offset + 3];
+ const a10 = values[offset + 4], a11 = values[offset + 5], a12 = values[offset + 6], a13 = values[offset + 7];
+ const a20 = values[offset + 8], a21 = values[offset + 9], a22 = values[offset + 10], a23 = values[offset + 11];
+ const a30 = values[offset + 12], a31 = values[offset + 13], a32 = values[offset + 14], a33 = values[offset + 15];
+ const b0 = a00 * a11 - a01 * a10;
+ const b1 = a00 * a12 - a02 * a10;
+ const b2 = a01 * a12 - a02 * a11;
+ const b3 = a20 * a31 - a21 * a30;
+ const b4 = a20 * a32 - a22 * a30;
+ const b5 = a21 * a32 - a22 * a31;
+ const b6 = a00 * b5 - a01 * b4 + a02 * b3;
+ const b7 = a10 * b5 - a11 * b4 + a12 * b3;
+ const b8 = a20 * b2 - a21 * b1 + a22 * b0;
+ const b9 = a30 * b2 - a31 * b1 + a32 * b0;
+ const determinant = a13 * b6 - a03 * b7 + a33 * b8 - a23 * b9;
+ return !Number.isFinite(determinant) || Math.abs(determinant) < 1e-12;
+}
+
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++) {
- const jointWorld = pendingWorld.subarray(joint * 16, joint * 16 + 16);
- jointWorld.set(node.skeleton.bones[joint].matrixWorld.elements);
- // 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;
+ const offset = joint * 16;
+ pendingWorld.set(node.skeleton.bones[joint].matrixWorld.elements, offset);
+ // A joint at zero scale collapses its vertices to a point instead of refusing the pose. Only a joint that needs
+ // the repair gets a view, so a normal pose allocates nothing.
+ if (needsCollapse(pendingWorld, offset) && collapseSingularMatrix(pendingWorld.subarray(offset, offset + 16), undefined, COLLAPSED_JOINT_SCALE)) binding.collapsedJoints = true;
}
updateSkinPose(pendingPose, pendingWorld, skin.inverseBindMatrices, node.matrixWorld.elements, skin.bindMatrix, checks);
if (checks) validateSkinPose(pendingPose, geometry, node.matrixWorld.elements);
diff --git a/src/skinning.js b/src/skinning.js
index 77a5a94b..f9c0d02e 100644
--- a/src/skinning.js
+++ b/src/skinning.js
@@ -9,6 +9,34 @@ function finiteFloat(value) {
return Number.isFinite(value) && Number.isFinite(Math.fround(value));
}
+function isIdentityMatrix(values) {
+ for (let index = 0; index < 16; index++) {
+ if (values[index] !== IDENTITY_MATRIX[index]) return false;
+ }
+ return true;
+}
+
+/**
+ * out = a * b for 4x4 matrices at offsets, in the operation order of gl-matrix's mat4.multiply, so the Float32 results
+ * are the same without copying each operand into a workspace first. out may be the same array and offset as a or b.
+ */
+function multiplyAt(out, outOffset, a, aOffset, b, bOffset) {
+ const a00 = a[aOffset], a01 = a[aOffset + 1], a02 = a[aOffset + 2], a03 = a[aOffset + 3];
+ const a10 = a[aOffset + 4], a11 = a[aOffset + 5], a12 = a[aOffset + 6], a13 = a[aOffset + 7];
+ const a20 = a[aOffset + 8], a21 = a[aOffset + 9], a22 = a[aOffset + 10], a23 = a[aOffset + 11];
+ const a30 = a[aOffset + 12], a31 = a[aOffset + 13], a32 = a[aOffset + 14], a33 = a[aOffset + 15];
+ for (let column = 0; column < 16; column += 4) {
+ const b0 = b[bOffset + column];
+ const b1 = b[bOffset + column + 1];
+ const b2 = b[bOffset + column + 2];
+ const b3 = b[bOffset + column + 3];
+ out[outOffset + column] = b0 * a00 + b1 * a10 + b2 * a20 + b3 * a30;
+ out[outOffset + column + 1] = b0 * a01 + b1 * a11 + b2 * a21 + b3 * a31;
+ out[outOffset + column + 2] = b0 * a02 + b1 * a12 + b2 * a22 + b3 * a32;
+ out[outOffset + column + 3] = b0 * a03 + b1 * a13 + b2 * a23 + b3 * a33;
+ }
+}
+
export function matrixDeterminant(values, offset) {
const matrixXX = Math.fround(values[offset]);
const matrixYX = Math.fround(values[offset + 1]);
@@ -70,16 +98,16 @@ export function updateSkinPose(pose, jointWorldMatrices, inverseBindMatrices, me
workspace.bind.set(bindMatrix);
if (!mat4.invert(workspace.meshInverse, workspace.meshWorld)) throw new Error('Mesh world matrix cannot be inverted.');
if (checks) validateMatrices(workspace.meshInverse, 1, 'Inverse mesh world matrix');
+ // Multiplying by an exact identity returns the same Float32 values, so those products are skipped.
+ const bindIsIdentity = isIdentityMatrix(workspace.bind);
+ const meshInverseIsIdentity = isIdentityMatrix(workspace.meshInverse);
+ const product = workspace.product;
for (let joint = 0; joint < count; joint++) {
const offset = joint * 16;
- for (let component = 0; component < 16; component++) {
- workspace.world[component] = jointWorldMatrices[offset + component];
- workspace.inverseBind[component] = inverseBindMatrices[offset + component];
- }
- mat4.multiply(workspace.product, workspace.world, workspace.inverseBind);
- mat4.multiply(workspace.product, workspace.product, workspace.bind);
- mat4.multiply(workspace.product, workspace.meshInverse, workspace.product);
- workspace.pending.set(workspace.product, offset);
+ multiplyAt(product, 0, jointWorldMatrices, offset, inverseBindMatrices, offset);
+ if (!bindIsIdentity) multiplyAt(product, 0, product, 0, workspace.bind, 0);
+ if (meshInverseIsIdentity) workspace.pending.set(product, offset);
+ else multiplyAt(workspace.pending, offset, workspace.meshInverse, 0, product, 0);
}
if (checks) validateMatrices(workspace.pending, count, 'Joint palette');
pose.jointMatrices.set(workspace.pending);
diff --git a/tests/skinning.test.js b/tests/skinning.test.js
index 1cfc1caf..d153529d 100644
--- a/tests/skinning.test.js
+++ b/tests/skinning.test.js
@@ -222,3 +222,27 @@ test('a mirrored weighted vertex draws pinched and is reported instead of failin
assert.equal(reflectedSkinReport(pose), null);
assert.deepEqual(reflectedSkinDiagnostics(new Map([[{ name: "knight" }, { skin: pose }]])), []);
});
+
+test('a palette of many joints equals the four-matrix Float32 product with and without identity bind and mesh matrices (issue #572)', () => {
+ const jointCount = 5;
+ const jointWorld = new Float32Array(jointCount * 16);
+ const inverseBind = new Float32Array(jointCount * 16);
+ for (let joint = 0; joint < jointCount; joint++) {
+ const rotation = mat4.fromRotationTranslationScale(mat4.create(), [0.1 * joint, 0.3, 0.2, 1], [joint * 0.37, 1.1, -0.6 * joint], [1 + joint * 0.1, 1, 0.9]);
+ jointWorld.set(rotation, joint * 16);
+ inverseBind.set(mat4.invert(mat4.create(), rotation), joint * 16);
+ }
+ const transformedMesh = mat4.fromTranslation(mat4.create(), [0.4, -2.3, 1.7]);
+ const transformedBind = mat4.fromScaling(mat4.create(), [1.25, 0.8, 1.1]);
+ for (const [mesh, bind] of [[transformedMesh, transformedBind], [transformedMesh, mat4.create()], [mat4.create(), transformedBind], [mat4.create(), mat4.create()]]) {
+ const pose = createSkinPose(jointCount);
+ updateSkinPose(pose, jointWorld, inverseBind, mesh, bind, false);
+ const meshInverse = mat4.invert(mat4.create(), new Float32Array(mesh));
+ for (let joint = 0; joint < jointCount; joint++) {
+ const product = mat4.multiply(mat4.create(), jointWorld.subarray(joint * 16, joint * 16 + 16), inverseBind.subarray(joint * 16, joint * 16 + 16));
+ mat4.multiply(product, product, new Float32Array(bind));
+ mat4.multiply(product, meshInverse, product);
+ assert.deepEqual(Array.from(pose.jointMatrices.subarray(joint * 16, joint * 16 + 16)), Array.from(product));
+ }
+ }
+});