Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

Skinned animation: prepare the pose once and validate distinct weight sets

Nguyen Xuan An28ec0d5b0f1d
diff --git a/bench/wasm-skin/.gitignore b/bench/wasm-skin/.gitignore
new file mode 100644
index 00000000..2c96eb1b
--- /dev/null
+++ b/bench/wasm-skin/.gitignore
@@ -0,0 +1,2 @@
+target/
+Cargo.lock
diff --git a/bench/wasm-skin/Cargo.toml b/bench/wasm-skin/Cargo.toml
new file mode 100644
index 00000000..e53a9f3d
--- /dev/null
+++ b/bench/wasm-skin/Cargo.toml
@@ -0,0 +1,14 @@
+[package]
+name = "skin-kernel"
+version = "0.1.0"
+edition = "2021"
+publish = false
+
+[lib]
+crate-type = ["cdylib"]
+
+[profile.release]
+opt-level = 3
+lto = true
+codegen-units = 1
+panic = "abort"
diff --git a/bench/wasm-skin/README.md b/bench/wasm-skin/README.md
new file mode 100644
index 00000000..ccf67653
--- /dev/null
+++ b/bench/wasm-skin/README.md
@@ -0,0 +1,35 @@
+# Skin kernel: JavaScript against Rust and WebAssembly
+
+Issue #572 asked whether moving hot code to Rust pays. This folder ports the per-frame skin kernel of `src/skinning.js`
+(`updateSkinPose` and `validateSkinPose`) to Rust, compiles it to WebAssembly with no crates and no wasm-bindgen, and
+times both on the same frames.
+
+```sh
+cd bench/wasm-skin
+cargo build --release --target wasm32-unknown-unknown
+cd ../..
+node bench/wasm-skin/bench.mjs
+```
+
+The bench records joint matrices from 8 animated RobotExpressive characters (the runtime benchmark's
+`skinned-characters` load: 32 skinned parts, 43 joints each, 8,864 skinned vertices, 1,856 distinct influence sets),
+runs both kernels on those frames, and checks that the palettes match bit for bit. The WebAssembly time includes
+copying each frame's matrices into its memory and the palette out.
+
+## Result (2026-11-08, i7-14700KF, Node 24, machine shared with other jobs)
+
+| Kernel | ms per frame, 8 characters |
+| --- | --- |
+| JavaScript, after #572 | 0.379 (0.361 to 0.442) |
+| Rust to WebAssembly | 0.160 (0.153 to 0.179) |
+
+The Rust kernel is 2.4 times faster and gives identical palettes (0 mismatched bits over 240 frames). The WebAssembly
+file is 25 KB.
+
+## Decision
+
+Not shipped in the engine. After the #572 fix the whole `applyAnimation` for 8 characters is about 1 to 2 ms, and this
+kernel is 0.38 ms of it, so the port saves about 0.2 ms per frame. Shipping it would add a 25 KB binary, an asynchronous
+start-up step and a Rust toolchain to CI for that. The #572 fix itself (one `preparePose` per frame instead of two,
+validating each distinct influence set once, no per-frame snapshot allocation) cut the same path from 4.5 ms to about
+1.5 ms in plain JavaScript. Revisit if a profile shows a pure-math loop above a few milliseconds per frame.
diff --git a/bench/wasm-skin/bench.mjs b/bench/wasm-skin/bench.mjs
new file mode 100644
index 00000000..295cad3d
--- /dev/null
+++ b/bench/wasm-skin/bench.mjs
@@ -0,0 +1,124 @@
+// Compares the per-frame skin kernel in JavaScript (src/skinning.js) with the same kernel in Rust compiled to WebAssembly.
+// Build first: cargo build --release --target wasm32-unknown-unknown (in bench/wasm-skin). Then: node bench/wasm-skin/bench.mjs
+// It records joint matrices from 8 animated RobotExpressive characters (the runtime benchmark's skinned-characters load),
+// runs both kernels on the same frames, checks that the palettes match bit for bit, and prints medians.
+import { readFile } from 'node:fs/promises';
+import { performance } from 'node:perf_hooks';
+import { parseGltf } from '../../src/gltf.js';
+import { createSkinPose, skinInfluenceSets, updateSkinPose, validateSkinPose, matrixDeterminant } from '../../src/skinning.js';
+
+const CHARACTERS = 8;
+const RECORDED_FRAMES = 240;
+const ROUNDS = 7;
+const repository = new URL('../../', import.meta.url);
+
+const fixture = await readFile(new URL('tests/fixtures/RobotExpressive.glb', repository));
+const skinnedParts = [];
+const frames = [];
+for (let character = 0; character < CHARACTERS; character++) {
+ const asset = await parseGltf(fixture.buffer.slice(fixture.byteOffset, fixture.byteOffset + fixture.byteLength), { maxVertices: 500000 });
+ const parts = asset.parts.filter(part => part.skin);
+ for (const part of parts) skinnedParts.push({ asset, character, part });
+}
+for (let frame = 0; frame < RECORDED_FRAMES; frame++) {
+ const time = frame / 60;
+ const assets = new Set(skinnedParts.map(entry => entry.asset));
+ [...assets].forEach((asset, index) => asset.applyAnimation(time + index * 0.37, 0));
+ frames.push(skinnedParts.map(({ part }) => ({ jointWorld: Float32Array.from(part.skin.jointWorldMatrices), meshWorld: Float32Array.from(part.matrix) })));
+}
+const jobs = skinnedParts.map(({ part }) => {
+ const sets = skinInfluenceSets(part.geometry);
+ return {
+ part, count: part.skin.jointMatrices.length / 16, inverseBind: part.skin.inverseBindMatrices, bind: Float32Array.from(part.skin.bindMatrix),
+ sets, setCount: sets.joints.length / 4, jsPose: createSkinPose(part.skin.jointMatrices.length / 16),
+ };
+});
+const skinnedVertices = jobs.reduce((sum, job) => sum + job.part.geometry.skinWeights.length / 4, 0);
+const distinctSets = jobs.reduce((sum, job) => sum + job.setCount, 0);
+
+// JavaScript kernel: the calls prepareSkinBinding makes per skinned part per frame.
+function javascriptFrame(frame) {
+ for (let index = 0; index < jobs.length; index++) {
+ const job = jobs[index];
+ const input = frame[index];
+ updateSkinPose(job.jsPose, input.jointWorld, job.inverseBind, input.meshWorld, job.bind);
+ validateSkinPose(job.jsPose, job.part.geometry, input.meshWorld);
+ }
+}
+
+// WebAssembly kernel: same work, plus copying the frame's matrices in and the palette out.
+const wasmBytes = await readFile(new URL('bench/wasm-skin/target/wasm32-unknown-unknown/release/skin_kernel.wasm', repository));
+const { instance } = await WebAssembly.instantiate(wasmBytes, {});
+const kernel = instance.exports;
+const floats = () => new Float32Array(kernel.memory.buffer);
+const integers = () => new Int32Array(kernel.memory.buffer);
+for (const job of jobs) {
+ job.jointWorldPointer = kernel.allocate(job.count * 64);
+ job.inverseBindPointer = kernel.allocate(job.count * 64);
+ job.meshWorldPointer = kernel.allocate(64);
+ job.bindPointer = kernel.allocate(64);
+ job.palettePointer = kernel.allocate(job.count * 64);
+ job.jointsPointer = kernel.allocate(job.setCount * 16);
+ job.weightsPointer = kernel.allocate(job.setCount * 16);
+ job.wasmPalette = new Float32Array(job.count * 16);
+}
+for (const job of jobs) {
+ floats().set(job.inverseBind, job.inverseBindPointer / 4);
+ floats().set(job.bind, job.bindPointer / 4);
+ integers().set(job.sets.joints, job.jointsPointer / 4);
+ floats().set(job.sets.weights, job.weightsPointer / 4);
+}
+function wasmFrame(frame) {
+ const memory = floats();
+ for (let index = 0; index < jobs.length; index++) {
+ const job = jobs[index];
+ const input = frame[index];
+ memory.set(input.jointWorld, job.jointWorldPointer / 4);
+ memory.set(input.meshWorld, job.meshWorldPointer / 4);
+ let status = kernel.skin_update(job.count, job.jointWorldPointer, job.inverseBindPointer, job.meshWorldPointer, job.bindPointer, job.palettePointer);
+ if (status === 0) status = kernel.skin_validate(job.palettePointer, job.count, job.jointsPointer, job.weightsPointer, job.setCount, matrixDeterminant(input.meshWorld, 0), 1);
+ if (status !== 0) throw new Error(`WebAssembly kernel status ${status}`);
+ job.wasmPalette.set(memory.subarray(job.palettePointer / 4, job.palettePointer / 4 + job.count * 16));
+ }
+}
+
+// Same palettes, bit for bit, on every recorded frame.
+let mismatches = 0;
+for (const frame of frames) {
+ javascriptFrame(frame);
+ wasmFrame(frame);
+ for (const job of jobs) {
+ const left = new Uint32Array(job.jsPose.jointMatrices.buffer, job.jsPose.jointMatrices.byteOffset, job.count * 16);
+ const right = new Uint32Array(job.wasmPalette.buffer);
+ for (let index = 0; index < left.length; index++) if (left[index] !== right[index]) mismatches++;
+ }
+}
+
+function measure(runFrame) {
+ const perFrame = [];
+ for (let round = 0; round < ROUNDS; round++) {
+ const started = performance.now();
+ for (const frame of frames) runFrame(frame);
+ perFrame.push((performance.now() - started) / frames.length);
+ }
+ perFrame.sort((a, b) => a - b);
+ return perFrame;
+}
+// Warm both paths, then alternate the order so neither always runs on a hotter or colder machine.
+measure(javascriptFrame);
+measure(wasmFrame);
+const javascriptTimes = [];
+const wasmTimes = [];
+for (let pass = 0; pass < 3; pass++) {
+ if (pass % 2 === 0) { javascriptTimes.push(...measure(javascriptFrame)); wasmTimes.push(...measure(wasmFrame)); }
+ else { wasmTimes.push(...measure(wasmFrame)); javascriptTimes.push(...measure(javascriptFrame)); }
+}
+const median = values => [...values].sort((a, b) => a - b)[values.length >> 1];
+const range = values => `${Math.min(...values).toFixed(4)} to ${Math.max(...values).toFixed(4)}`;
+console.log(JSON.stringify({
+ characters: CHARACTERS, skinnedParts: jobs.length, jointsPerPart: jobs[0].count, skinnedVertices, distinctInfluenceSets: distinctSets,
+ wasmBytes: wasmBytes.length, paletteMismatches: mismatches,
+ javascriptMsPerFrame: Number(median(javascriptTimes).toFixed(4)), javascriptRange: range(javascriptTimes),
+ wasmMsPerFrame: Number(median(wasmTimes).toFixed(4)), wasmRange: range(wasmTimes),
+ speedup: Number((median(javascriptTimes) / median(wasmTimes)).toFixed(2)),
+}, null, 2));
diff --git a/bench/wasm-skin/src/lib.rs b/bench/wasm-skin/src/lib.rs
new file mode 100644
index 00000000..428a631f
--- /dev/null
+++ b/bench/wasm-skin/src/lib.rs
@@ -0,0 +1,165 @@
+//! The per-frame skin kernel of src/skinning.js in Rust, for the WebAssembly comparison in bench/wasm-skin.
+//! `skin_update` matches `updateSkinPose` and `skin_validate` matches `validateSkinPose` for Float32 inputs:
+//! every product is computed in f64 in gl-matrix order and stored as f32, as the JavaScript does.
+//! Status codes: 0 ok, 1 non-finite value, 2 not affine, 3 singular joint transform, 4 mesh world not invertible,
+//! 5 singular weighted vertex transform, 6 reflected weighted transform.
+
+use std::alloc::{alloc, Layout};
+
+#[no_mangle]
+pub extern "C" fn allocate(bytes: usize) -> *mut u8 {
+ unsafe { alloc(Layout::from_size_align(bytes.max(8), 8).unwrap()) }
+}
+
+fn determinant(values: &[f32]) -> f64 {
+ let (xx, yx, zx) = (values[0] as f64, values[1] as f64, values[2] as f64);
+ let (xy, yy, zy) = (values[4] as f64, values[5] as f64, values[6] as f64);
+ let (xz, yz, zz) = (values[8] as f64, values[9] as f64, values[10] as f64);
+ xx * (yy * zz - yz * zy) - xy * (yx * zz - yz * zx) + xz * (yx * zy - yy * zx)
+}
+
+fn validate_matrices(values: &[f32]) -> i32 {
+ if values.iter().any(|value| !value.is_finite()) {
+ return 1;
+ }
+ for matrix in values.chunks_exact(16) {
+ if matrix[3] != 0.0 || matrix[7] != 0.0 || matrix[11] != 0.0 || matrix[15] != 1.0 {
+ return 2;
+ }
+ if determinant(matrix).abs() < 1e-10 {
+ return 3;
+ }
+ }
+ 0
+}
+
+fn multiply(output: &mut [f32; 16], left: &[f32; 16], right: &[f32; 16]) {
+ let a: [f64; 16] = left.map(|value| value as f64);
+ for column in 0..4 {
+ let b0 = right[column * 4] as f64;
+ let b1 = right[column * 4 + 1] as f64;
+ let b2 = right[column * 4 + 2] as f64;
+ let b3 = right[column * 4 + 3] as f64;
+ for row in 0..4 {
+ output[column * 4 + row] = (b0 * a[row] + b1 * a[4 + row] + b2 * a[8 + row] + b3 * a[12 + row]) as f32;
+ }
+ }
+}
+
+fn invert(output: &mut [f32; 16], matrix: &[f32; 16]) -> bool {
+ let a: [f64; 16] = matrix.map(|value| value as f64);
+ let (a00, a01, a02, a03) = (a[0], a[1], a[2], a[3]);
+ let (a10, a11, a12, a13) = (a[4], a[5], a[6], a[7]);
+ let (a20, a21, a22, a23) = (a[8], a[9], a[10], a[11]);
+ let (a30, a31, a32, a33) = (a[12], a[13], a[14], a[15]);
+ let b00 = a00 * a11 - a01 * a10;
+ let b01 = a00 * a12 - a02 * a10;
+ let b02 = a00 * a13 - a03 * a10;
+ let b03 = a01 * a12 - a02 * a11;
+ let b04 = a01 * a13 - a03 * a11;
+ let b05 = a02 * a13 - a03 * a12;
+ let b06 = a20 * a31 - a21 * a30;
+ let b07 = a20 * a32 - a22 * a30;
+ let b08 = a20 * a33 - a23 * a30;
+ let b09 = a21 * a32 - a22 * a31;
+ let b10 = a21 * a33 - a23 * a31;
+ let b11 = a22 * a33 - a23 * a32;
+ let det = b00 * b11 - b01 * b10 + b02 * b09 + b03 * b08 - b04 * b07 + b05 * b06;
+ if det == 0.0 || det.is_nan() {
+ return false;
+ }
+ let det = 1.0 / det;
+ let values = [
+ (a11 * b11 - a12 * b10 + a13 * b09) * det,
+ (a02 * b10 - a01 * b11 - a03 * b09) * det,
+ (a31 * b05 - a32 * b04 + a33 * b03) * det,
+ (a22 * b04 - a21 * b05 - a23 * b03) * det,
+ (a12 * b08 - a10 * b11 - a13 * b07) * det,
+ (a00 * b11 - a02 * b08 + a03 * b07) * det,
+ (a32 * b02 - a30 * b05 - a33 * b01) * det,
+ (a20 * b05 - a22 * b02 + a23 * b01) * det,
+ (a10 * b10 - a11 * b08 + a13 * b06) * det,
+ (a01 * b08 - a00 * b10 - a03 * b06) * det,
+ (a30 * b04 - a31 * b02 + a33 * b00) * det,
+ (a21 * b02 - a20 * b04 - a23 * b00) * det,
+ (a11 * b07 - a10 * b09 - a12 * b06) * det,
+ (a00 * b09 - a01 * b07 + a02 * b06) * det,
+ (a31 * b01 - a30 * b03 - a32 * b00) * det,
+ (a20 * b03 - a21 * b01 + a22 * b00) * det,
+ ];
+ for index in 0..16 {
+ output[index] = values[index] as f32;
+ }
+ true
+}
+
+fn matrix_at(values: &[f32], index: usize) -> [f32; 16] {
+ values[index * 16..index * 16 + 16].try_into().unwrap()
+}
+
+/// palette = inverse(meshWorld) * jointWorld * inverseBind * bind for each joint, then the palette checks.
+#[no_mangle]
+pub unsafe extern "C" fn skin_update(count: usize, joint_world: *const f32, inverse_bind: *const f32, mesh_world: *const f32, bind: *const f32, palette: *mut f32) -> i32 {
+ let joint_world = std::slice::from_raw_parts(joint_world, count * 16);
+ let inverse_bind = std::slice::from_raw_parts(inverse_bind, count * 16);
+ let mesh_world = std::slice::from_raw_parts(mesh_world, 16);
+ let bind = std::slice::from_raw_parts(bind, 16);
+ let palette = std::slice::from_raw_parts_mut(palette, count * 16);
+ for (values, _) in [(joint_world, 0), (inverse_bind, 0), (mesh_world, 0), (bind, 0)] {
+ let status = validate_matrices(values);
+ if status != 0 {
+ return status;
+ }
+ }
+ let mesh_world = matrix_at(mesh_world, 0);
+ let bind = matrix_at(bind, 0);
+ let mut mesh_inverse = [0.0f32; 16];
+ if !invert(&mut mesh_inverse, &mesh_world) {
+ return 4;
+ }
+ let status = validate_matrices(&mesh_inverse);
+ if status != 0 {
+ return status;
+ }
+ let mut product = [0.0f32; 16];
+ let mut step = [0.0f32; 16];
+ for joint in 0..count {
+ multiply(&mut product, &matrix_at(joint_world, joint), &matrix_at(inverse_bind, joint));
+ multiply(&mut step, &product, &bind);
+ multiply(&mut product, &mesh_inverse, &step);
+ palette[joint * 16..joint * 16 + 16].copy_from_slice(&product);
+ }
+ validate_matrices(palette)
+}
+
+/// The palette checks plus one weighted 3x3 determinant per distinct influence set.
+#[no_mangle]
+pub unsafe extern "C" fn skin_validate(palette: *const f32, joint_count: usize, joints: *const i32, weights: *const f32, set_count: usize, world_determinant: f64, has_world: i32) -> i32 {
+ let matrices = std::slice::from_raw_parts(palette, joint_count * 16);
+ let joints = std::slice::from_raw_parts(joints, set_count * 4);
+ let weights = std::slice::from_raw_parts(weights, set_count * 4);
+ let status = validate_matrices(matrices);
+ if status != 0 {
+ return status;
+ }
+ for set in 0..set_count {
+ let mut sum = [0.0f64; 9];
+ for influence in 0..4 {
+ let weight = weights[set * 4 + influence] as f64;
+ let offset = joints[set * 4 + influence] as usize * 16;
+ let source = [0usize, 1, 2, 4, 5, 6, 8, 9, 10];
+ for (slot, component) in source.iter().enumerate() {
+ sum[slot] += matrices[offset + component] as f64 * weight;
+ }
+ }
+ let [xx, yx, zx, xy, yy, zy, xz, yz, zz] = sum;
+ let det = xx * (yy * zz - yz * zy) - xy * (yx * zz - yz * zx) + xz * (yx * zy - yy * zx);
+ if !det.is_finite() || det.abs() < 1e-8 {
+ return 5;
+ }
+ if has_world != 0 && det * world_determinant < 0.0 {
+ return 6;
+ }
+ }
+ 0
+}
diff --git a/changes/572.md b/changes/572.md
new file mode 100644
index 00000000..ceb6ef04
--- /dev/null
+++ b/changes/572.md
@@ -0,0 +1 @@
+- Animating an imported glTF character costs about a third of the CPU it did: `applyAnimation` prepares the pose once instead of twice, reuses its rollback snapshot, and skin validation checks each distinct set of joint weights once instead of every vertex. Eight RobotExpressive characters went from 4.5 ms to about 1.5 ms per frame.
diff --git a/src/gltf.js b/src/gltf.js
index 5bfc3c5c..e7be8a08 100644
--- a/src/gltf.js
+++ b/src/gltf.js
@@ -1411,11 +1411,31 @@ export async function parseGltf(data, options = {}) {
let pendingTransaction;
let currentAnimation = null;
- function capturePrivatePose() {
- return nodes.map(node => ({ node, translation: node.position.toArray(), rotation: node.quaternion.toArray(),
- scale: node.scale.toArray(), matrix: [...node.matrix.elements], world: [...node.matrixWorld.elements],
- matrixAutoUpdate: node.matrixAutoUpdate, matrixWorldNeedsUpdate: node.matrixWorldNeedsUpdate,
- weights: node.morphTargetInfluences ? [...node.morphTargetInfluences] : null }));
+ /** Snapshot every node's private pose. With `snapshot`, writes into it in place, so a per-frame rollback point allocates nothing. */
+ function capturePrivatePose(snapshot = null) {
+ if (!snapshot) {
+ return nodes.map(node => ({ node, translation: node.position.toArray(), rotation: node.quaternion.toArray(),
+ scale: node.scale.toArray(), matrix: [...node.matrix.elements], world: [...node.matrixWorld.elements],
+ matrixAutoUpdate: node.matrixAutoUpdate, matrixWorldNeedsUpdate: node.matrixWorldNeedsUpdate,
+ weights: node.morphTargetInfluences ? [...node.morphTargetInfluences] : null }));
+ }
+ for (let index = 0; index < nodes.length; index++) {
+ const node = nodes[index];
+ const entry = snapshot[index];
+ copyValues(node.position.values, entry.translation);
+ copyValues(node.quaternion.values, entry.rotation);
+ copyValues(node.scale.values, entry.scale);
+ copyValues(node.matrix.elements, entry.matrix);
+ copyValues(node.matrixWorld.elements, entry.world);
+ entry.matrixAutoUpdate = node.matrixAutoUpdate;
+ entry.matrixWorldNeedsUpdate = node.matrixWorldNeedsUpdate;
+ if (entry.weights) copyValues(node.morphTargetInfluences, entry.weights);
+ }
+ return snapshot;
+ }
+
+ function copyValues(source, target) {
+ for (let index = 0; index < target.length; index++) target[index] = source[index];
}
function restorePrivatePose(snapshot) {
@@ -1652,16 +1672,7 @@ export async function parseGltf(data, options = {}) {
pendingTransaction = null;
throw error;
}
- for (const { matrix, pendingMatrix } of bindings) {
- Float32Array.prototype.set.call(matrix, pendingMatrix);
- }
- for (const binding of skinBindings) {
- commitSkinBinding(binding);
- }
- for (const binding of morphBindings) {
- Float32Array.prototype.set.call(binding.weights, binding.pendingPose.weights);
- }
- currentAnimation = candidate.animation;
+ commitPreparedPose(candidate.animation);
settled = true;
pendingTransaction = null;
return parts;
@@ -1698,7 +1709,41 @@ export async function parseGltf(data, options = {}) {
if (!Number.isInteger(clipIndex) || !clip) {
throw new RangeError('Animation clip index is out of range.');
}
- return stagePose({ animation: { clip: clipIndex, time: Math.max(0, Math.min(time, clip.duration)) } }).commit();
+ if (pendingTransaction) {
+ 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.
+ const animation = { clip: clipIndex, time: Math.max(0, Math.min(time, clip.duration)) };
+ rollbackPose ??= capturePrivatePose();
+ capturePrivatePose(rollbackPose);
+ const previousAnimation = currentAnimation;
+ try {
+ playAnimation(animation);
+ preparePose();
+ } catch (error) {
+ playAnimation(previousAnimation);
+ restorePrivatePose(rollbackPose);
+ throw error;
+ }
+ commitPreparedPose(animation);
+ return parts;
+ }
+
+ let rollbackPose = null;
+
+ /** Copy the prepared candidate pose into the committed parts. */
+ function commitPreparedPose(animation) {
+ for (const { matrix, pendingMatrix } of bindings) {
+ Float32Array.prototype.set.call(matrix, pendingMatrix);
+ }
+ for (const binding of skinBindings) {
+ commitSkinBinding(binding);
+ }
+ for (const binding of morphBindings) {
+ Float32Array.prototype.set.call(binding.weights, binding.pendingPose.weights);
+ }
+ currentAnimation = animation;
}
return { parts, warnings, lights, scaledTextures: textureScaling.scaledTextures, textureFormats: textureFormatsOf(maps), skins: skinBindings.map(binding => binding.skin), animations: gltf.animations,
get nodes() { return structuredClone(nodeMetadata); }, stagePose, applyAnimation, dispose, capabilities: GLTF_CAPABILITIES };
diff --git a/src/skinning.js b/src/skinning.js
index e4fa8b71..de9f5ded 100644
--- a/src/skinning.js
+++ b/src/skinning.js
@@ -26,7 +26,12 @@ export function matrixDeterminant(values, offset) {
function validateMatrices(values, count, label) {
if (values?.length !== count * 16) throw new Error(`${label} must contain one matrix per joint.`);
- for (const value of values) if (!finiteFloat(value)) throw new Error(`${label} must contain finite floats.`);
+ // A Float32Array element is already a float, so finiteness is the whole check; other arrays must also fit a Float32.
+ if (values instanceof Float32Array) {
+ for (let index = 0; index < values.length; index++) if (!Number.isFinite(values[index])) throw new Error(`${label} must contain finite floats.`);
+ } else {
+ for (const value of values) if (!finiteFloat(value)) throw new Error(`${label} must contain finite floats.`);
+ }
for (let offset = 0; offset < values.length; offset += 16) {
if (values[offset + 3] !== 0 || values[offset + 7] !== 0 || values[offset + 11] !== 0 || values[offset + 15] !== 1) throw new Error(`${label} must contain affine matrices.`);
if (Math.abs(matrixDeterminant(values, offset)) < 1e-10) throw new Error(`${label} contains a singular joint transform.`);
@@ -109,12 +114,46 @@ export function validateSkinGeometry(geometry, pose) {
validateSkinPose(pose, geometry);
}
-/** Validate weighted normal transforms without allocating temporary matrices. */
+// Distinct (joints, normalized weights) sets of a geometry, keyed by its weight array. The renderer refuses a changed
+// skinIndices or skinWeights identity and packs influences to the GPU once, so the arrays are fixed for a renderer's life.
+const influenceSetCache = new WeakMap();
+
+/** The distinct influence sets in vertex order of first use. Many vertices share one set, and each set gives one transform. */
+export function skinInfluenceSets(geometry) {
+ const cached = influenceSetCache.get(geometry.skinWeights);
+ if (cached && cached.skinIndices === geometry.skinIndices) return cached;
+ const vertexCount = geometry.skinWeights.length / 4;
+ const seen = new Map();
+ const joints = [];
+ const weights = [];
+ for (let vertex = 0; vertex < vertexCount; vertex++) {
+ let total = 0;
+ for (let influence = 0; influence < 4; influence++) total += geometry.skinWeights[vertex * 4 + influence];
+ const setJoints = [];
+ const setWeights = [];
+ for (let influence = 0; influence < 4; influence++) {
+ setJoints.push(geometry.skinIndices[vertex * 4 + influence]);
+ setWeights.push(Math.fround(geometry.skinWeights[vertex * 4 + influence] / total));
+ }
+ const key = `${setJoints.join(',')}|${setWeights.join(',')}`;
+ if (seen.has(key)) continue;
+ seen.set(key, true);
+ joints.push(...setJoints);
+ weights.push(...setWeights);
+ }
+ const sets = { skinIndices: geometry.skinIndices, joints: Int32Array.from(joints), weights: Float32Array.from(weights) };
+ influenceSetCache.set(geometry.skinWeights, sets);
+ return sets;
+}
+
+/** Validate weighted normal transforms without allocating temporary matrices, once per distinct influence set. */
export function validateSkinPose(pose, geometry, worldMatrix) {
const matrices = pose.jointMatrices;
validateMatrices(matrices, matrices.length / 16, 'Joint palette');
if (!geometry) return;
- for (let vertex = 0; vertex < geometry.skinWeights.length / 4; vertex++) {
+ const { joints, weights } = skinInfluenceSets(geometry);
+ const worldDeterminant = worldMatrix ? matrixDeterminant(worldMatrix, 0) : 0;
+ for (let set = 0; set < joints.length / 4; set++) {
let matrixXX = 0;
let matrixYX = 0;
let matrixZX = 0;
@@ -124,11 +163,9 @@ export function validateSkinPose(pose, geometry, worldMatrix) {
let matrixXZ = 0;
let matrixYZ = 0;
let matrixZZ = 0;
- let total = 0;
- for (let influence = 0; influence < 4; influence++) total += geometry.skinWeights[vertex * 4 + influence];
for (let influence = 0; influence < 4; influence++) {
- const weight = Math.fround(geometry.skinWeights[vertex * 4 + influence] / total);
- const offset = geometry.skinIndices[vertex * 4 + influence] * 16;
+ const weight = weights[set * 4 + influence];
+ const offset = joints[set * 4 + influence] * 16;
matrixXX += matrices[offset] * weight;
matrixYX += matrices[offset + 1] * weight;
matrixZX += matrices[offset + 2] * weight;
@@ -141,7 +178,7 @@ export function validateSkinPose(pose, geometry, worldMatrix) {
}
const determinant = matrixXX * (matrixYY * matrixZZ - matrixYZ * matrixZY) - matrixXY * (matrixYX * matrixZZ - matrixYZ * matrixZX) + matrixXZ * (matrixYX * matrixZY - matrixYY * matrixZX);
if (!Number.isFinite(determinant) || Math.abs(determinant) < 1e-8) throw new Error('Skin pose produces a singular weighted vertex transform.');
- if (worldMatrix && determinant * matrixDeterminant(worldMatrix, 0) < 0) throw new Error('Reflected weighted skin transforms are unsupported.');
+ if (worldMatrix && determinant * worldDeterminant < 0) throw new Error('Reflected weighted skin transforms are unsupported.');
}
}
diff --git a/tests/skinning.test.js b/tests/skinning.test.js
index 7c73f790..89a441cf 100644
--- a/tests/skinning.test.js
+++ b/tests/skinning.test.js
@@ -2,7 +2,7 @@ import test from 'node:test';
import assert from 'node:assert/strict';
import { mat4 } from 'gl-matrix';
import { Bone, Skeleton, SkinnedMesh, BufferGeometry, Float32BufferAttribute, Uint16BufferAttribute, Matrix4, Matrix3, Vector3 } from 'three';
-import { createSkinPose, updateSkinPose, validateSkinGeometry, validateSkinPose, skinTextureLayout, packSkinInfluences } from '../src/skinning.js';
+import { createSkinPose, updateSkinPose, validateSkinGeometry, validateSkinPose, skinTextureLayout, packSkinInfluences, skinInfluenceSets } from '../src/skinning.js';
function influences() {
return { positions: new Float32Array([0.2, 1, 0]), skinIndices: new Uint16Array([0, 1, 0, 0]), skinWeights: new Float32Array([0.3, 0.7, 0, 0]) };
@@ -180,3 +180,24 @@ test('pose calculations use Float32 mesh and bind matrices before inversion and
updateSkinPose(pose, identity, identity, mesh);
assert.deepEqual(Array.from(pose.jointMatrices), Array.from(expectedInverse));
});
+
+test('validateSkinPose checks each distinct influence set once and still finds a singular one', () => {
+ const pose = createSkinPose(2);
+ // Joint 1 mirrors x. Each joint is healthy, but a 50/50 blend with the identity flattens x to zero.
+ pose.jointMatrices.set([-1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1], 16);
+ const repeatedHealthy = Array.from({ length: 50 }, () => [0, 0, 0, 0]).flat();
+ const geometry = {
+ skinIndices: new Uint16Array([...repeatedHealthy, 0, 1, 0, 0]),
+ skinWeights: new Float32Array([...Array.from({ length: 50 }, () => [1, 0, 0, 0]).flat(), 0.5, 0.5, 0, 0]),
+ };
+ assert.equal(skinInfluenceSets(geometry).joints.length / 4, 2);
+ assert.throws(() => validateSkinPose(pose, geometry), /singular weighted vertex transform/);
+});
+
+test('skinInfluenceSets rebuilds when the index array is replaced', () => {
+ const skinWeights = new Float32Array([1, 0, 0, 0, 0.5, 0.5, 0, 0]);
+ const first = skinInfluenceSets({ skinIndices: new Uint16Array([0, 0, 0, 0, 0, 1, 0, 0]), skinWeights });
+ const replaced = skinInfluenceSets({ skinIndices: new Uint16Array([1, 0, 0, 0, 1, 1, 0, 0]), skinWeights });
+ assert.notEqual(first, replaced);
+ assert.deepEqual([...replaced.joints.subarray(0, 4)], [1, 0, 0, 0]);
+});