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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.jsindex 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.jsindex 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, meworkspace.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.jsindex 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 failinassert.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));+ }+ }+});