three-vat 0.1.0 → 1.0.0

package/dist/index.js

@@ -1,24 +1,152 @@
-import { FloatType, AnimationMixer, Box3, Vector4, Matrix4, Vector3, DataTexture, RGBAFormat, NearestFilter, DataUtils, HalfFloatType } from 'three';
+export { addVATInstanceAttributes } from './chunk-SXTVASKG.js';
+import { FloatType, Matrix4, AnimationMixer, Box3, Vector4, Vector3, Sphere, DataTexture, RGBAFormat, NearestFilter, BufferGeometry, BufferAttribute } from 'three';
 
-// src/bake.ts
 var MAX_TEXTURE_SIZE = 16384;
-function bakeVAT(root, skinnedMesh, clips, { fps = 30 } = {}) {
-  const geometry = skinnedMesh.geometry;
-  const vertexCount = geometry.attributes.position.count;
-  if (vertexCount > MAX_TEXTURE_SIZE) {
+function asAttribute(value, mesh, name) {
+  if (!(value instanceof BufferAttribute)) {
     throw new Error(
-      `three-vat: vertexCount ${vertexCount} exceeds MAX_TEXTURE_SIZE ${MAX_TEXTURE_SIZE}; row wrapping is not implemented`
+      `three-vat: mesh "${mesh.name || "(unnamed)"}" has an interleaved or unsupported "${name}" attribute; VAT bakes plain BufferAttributes`
+    );
+  }
+  return value;
+}
+function collectParts(root) {
+  const found = [];
+  root.traverse((o) => {
+    const mesh = o;
+    if (mesh.isMesh && mesh.geometry) found.push(mesh);
+  });
+  if (found.length === 0) {
+    throw new Error("three-vat: no Mesh found under root; nothing to bake");
+  }
+  const materials = [];
+  const parts = [];
+  for (const mesh of found) {
+    if (Array.isArray(mesh.material)) {
+      throw new Error(
+        `three-vat: mesh "${mesh.name || "(unnamed)"}" uses a material array; split it into one mesh per material before baking`
+      );
+    }
+    const geometry = mesh.geometry;
+    if (!geometry.attributes.normal) geometry.computeVertexNormals();
+    const material = mesh.material;
+    let materialIndex = materials.indexOf(material);
+    if (materialIndex === -1) materialIndex = materials.push(material) - 1;
+    const skinned = mesh;
+    parts.push({
+      mesh,
+      material,
+      materialIndex,
+      vertexStart: 0,
+      // assigned below, after material sorting
+      vertexCount: geometry.attributes.position.count,
+      basePos: asAttribute(geometry.attributes.position, mesh, "position"),
+      baseNrm: asAttribute(geometry.attributes.normal, mesh, "normal"),
+      isSkinned: !!geometry.attributes.skinWeight && !!skinned.skeleton,
+      skeleton: skinned.skeleton,
+      skinIndex: geometry.attributes.skinIndex,
+      skinWeight: geometry.attributes.skinWeight,
+      morphPos: geometry.morphAttributes.position,
+      morphNrm: geometry.morphAttributes.normal,
+      morphRelative: geometry.morphTargetsRelative
+    });
+  }
+  parts.sort((a, b) => a.materialIndex - b.materialIndex);
+  let offset = 0;
+  for (const part of parts) {
+    part.vertexStart = offset;
+    offset += part.vertexCount;
+  }
+  return parts;
+}
+function mergeGeometry(parts, restMatrices, total) {
+  const position = new Float32Array(total * 3);
+  const normal = new Float32Array(total * 3);
+  const wantUV = parts.every((p) => !!p.mesh.geometry.attributes.uv);
+  const wantColor = parts.every((p) => !!p.mesh.geometry.attributes.color);
+  const uv = wantUV ? new Float32Array(total * 2) : null;
+  const color = wantColor ? new Float32Array(total * 3) : null;
+  const indices = [];
+  const groups = [];
+  const _v = new Vector3();
+  const _n = new Vector3();
+  parts.forEach((part, pi) => {
+    const m = restMatrices[pi];
+    const geometry = part.mesh.geometry;
+    const start = part.vertexStart;
+    const srcUV = uv ? asAttribute(geometry.attributes.uv, part.mesh, "uv") : null;
+    const srcColor = color ? asAttribute(geometry.attributes.color, part.mesh, "color") : null;
+    for (let v = 0; v < part.vertexCount; v++) {
+      _v.fromBufferAttribute(part.basePos, v).applyMatrix4(m);
+      _n.fromBufferAttribute(part.baseNrm, v).transformDirection(m);
+      const o3 = (start + v) * 3;
+      position[o3] = _v.x;
+      position[o3 + 1] = _v.y;
+      position[o3 + 2] = _v.z;
+      normal[o3] = _n.x;
+      normal[o3 + 1] = _n.y;
+      normal[o3 + 2] = _n.z;
+      if (uv && srcUV) {
+        uv[(start + v) * 2] = srcUV.getX(v);
+        uv[(start + v) * 2 + 1] = srcUV.getY(v);
+      }
+      if (color && srcColor) {
+        color[o3] = srcColor.getX(v);
+        color[o3 + 1] = srcColor.getY(v);
+        color[o3 + 2] = srcColor.getZ(v);
+      }
+    }
+    const groupStart = indices.length;
+    const index = geometry.index;
+    if (index) {
+      for (let i = 0; i < index.count; i++) indices.push(start + index.getX(i));
+    } else {
+      for (let v = 0; v < part.vertexCount; v++) indices.push(start + v);
+    }
+    const last = groups[groups.length - 1];
+    if (last && last.materialIndex === part.materialIndex) {
+      last.count += indices.length - groupStart;
+    } else {
+      groups.push({
+        start: groupStart,
+        count: indices.length - groupStart,
+        materialIndex: part.materialIndex
+      });
+    }
+  });
+  const merged = new BufferGeometry();
+  merged.setAttribute("position", new BufferAttribute(position, 3));
+  merged.setAttribute("normal", new BufferAttribute(normal, 3));
+  if (uv) merged.setAttribute("uv", new BufferAttribute(uv, 2));
+  if (color) merged.setAttribute("color", new BufferAttribute(color, 3));
+  merged.setIndex(indices);
+  for (const g of groups) merged.addGroup(g.start, g.count, g.materialIndex);
+  return merged;
+}
+function bakeVAT(root, clips, { fps = 30, maxTextureSize = MAX_TEXTURE_SIZE } = {}) {
+  root.updateMatrixWorld(true);
+  const parts = collectParts(root);
+  const vertexCount = parts.reduce((n, p) => n + p.vertexCount, 0);
+  if (vertexCount > maxTextureSize) {
+    throw new Error(
+      `three-vat: vertexCount ${vertexCount} exceeds maxTextureSize ${maxTextureSize}; row wrapping is not implemented`
     );
   }
   const frameCounts = clips.map((c) => Math.max(2, Math.round(c.duration * fps)));
   const totalFrames = frameCounts.reduce((a, b) => a + b, 0);
+  if (totalFrames > maxTextureSize) {
+    throw new Error(
+      `three-vat: totalFrames ${totalFrames} exceeds maxTextureSize ${maxTextureSize}; lower fps or bake fewer clips`
+    );
+  }
+  const rootInverse = root.matrixWorld.clone().invert();
+  const restMatrices = parts.map(
+    (p) => new Matrix4().multiplyMatrices(rootInverse, p.mesh.matrixWorld)
+  );
+  const geometry = mergeGeometry(parts, restMatrices, vertexCount);
+  const mergedBase = geometry.attributes.position;
   const posData = new Float32Array(vertexCount * totalFrames * 4);
   const nrmData = new Float32Array(vertexCount * totalFrames * 4);
-  const basePos = geometry.attributes.position;
-  const baseNrm = geometry.attributes.normal;
-  const skinIndex = geometry.attributes.skinIndex;
-  const skinWeight = geometry.attributes.skinWeight;
-  const skeleton = skinnedMesh.skeleton;
   const mixer = new AnimationMixer(root);
   const bounds = new Box3();
   const clipTable = [];
@@ -27,9 +155,15 @@ function bakeVAT(root, skinnedMesh, clips, { fps = 30 } = {}) {
   const _bone = new Matrix4();
   const _acc = new Matrix4();
   const _skin = new Matrix4();
+  const _partMatrix = new Matrix4();
   const _p = new Vector3();
   const _bp = new Vector3();
   const _n = new Vector3();
+  const _mt = new Vector3();
+  const _mb = new Vector3();
+  const _mbn = new Vector3();
+  const influencers = parts.filter((p) => p.isSkinned && p.skeleton).map(influencedBones);
+  let warnedNonUniformScale = false;
   let rowOffset = 0;
   clips.forEach((clip, ci) => {
     const frames = frameCounts[ci];
@@ -40,37 +174,76 @@ function bakeVAT(root, skinnedMesh, clips, { fps = 30 } = {}) {
       mixer.setTime(f / frames * clip.duration);
       root.updateMatrixWorld(true);
       const row = rowOffset + f;
-      for (let v = 0; v < vertexCount; v++) {
-        _si.fromBufferAttribute(skinIndex, v);
-        _sw.fromBufferAttribute(skinWeight, v);
-        _acc.elements.fill(0);
-        for (let i = 0; i < 4; i++) {
-          const w = _sw.getComponent(i);
-          if (w === 0) continue;
-          const bi = _si.getComponent(i);
-          _bone.multiplyMatrices(skeleton.bones[bi].matrixWorld, skeleton.boneInverses[bi]);
-          const ae = _acc.elements;
-          const be = _bone.elements;
-          for (let e = 0; e < 16; e++) ae[e] += be[e] * w;
+      if (!warnedNonUniformScale) {
+        warnedNonUniformScale = warnOnNonUniformBoneScale(influencers, _bone);
+      }
+      for (const part of parts) {
+        _partMatrix.multiplyMatrices(rootInverse, part.mesh.matrixWorld);
+        const influences = part.mesh.morphTargetInfluences;
+        const { morphPos, morphNrm, morphRelative, isSkinned, skeleton, skinIndex, skinWeight } = part;
+        const morphCount = influences ? Math.min(influences.length, Math.max(morphPos?.length ?? 0, morphNrm?.length ?? 0)) : 0;
+        for (let v = 0; v < part.vertexCount; v++) {
+          const vi = part.vertexStart + v;
+          _p.fromBufferAttribute(part.basePos, v);
+          _n.fromBufferAttribute(part.baseNrm, v);
+          if (influences && morphCount > 0) {
+            if (!morphRelative) {
+              _mb.fromBufferAttribute(part.basePos, v);
+              _mbn.fromBufferAttribute(part.baseNrm, v);
+            }
+            for (let t = 0; t < morphCount; t++) {
+              const w = influences[t];
+              if (w === 0) continue;
+              const targetPos = morphPos?.[t];
+              if (targetPos) {
+                _mt.fromBufferAttribute(targetPos, v);
+                if (!morphRelative) _mt.sub(_mb);
+                _p.addScaledVector(_mt, w);
+              }
+              const targetNrm = morphNrm?.[t];
+              if (targetNrm) {
+                _mt.fromBufferAttribute(targetNrm, v);
+                if (!morphRelative) _mt.sub(_mbn);
+                _n.addScaledVector(_mt, w);
+              }
+            }
+          }
+          if (isSkinned && skeleton) {
+            const skinned = part.mesh;
+            _si.fromBufferAttribute(skinIndex, v);
+            _sw.fromBufferAttribute(skinWeight, v);
+            _acc.elements.fill(0);
+            for (let i = 0; i < 4; i++) {
+              const w = _sw.getComponent(i);
+              if (w === 0) continue;
+              const bi = _si.getComponent(i);
+              _bone.multiplyMatrices(skeleton.bones[bi].matrixWorld, skeleton.boneInverses[bi]);
+              const ae = _acc.elements;
+              const be = _bone.elements;
+              for (let e = 0; e < 16; e++) ae[e] += be[e] * w;
+            }
+            _skin.multiplyMatrices(_acc, skinned.bindMatrix).premultiply(skinned.bindMatrixInverse);
+            _p.applyMatrix4(_skin);
+            _n.transformDirection(_skin);
+          }
+          _p.applyMatrix4(_partMatrix);
+          _n.transformDirection(_partMatrix);
+          bounds.expandByPoint(_p);
+          _bp.fromBufferAttribute(mergedBase, vi);
+          const o = (row * vertexCount + vi) * 4;
+          const dx = _p.x - _bp.x;
+          const dy = _p.y - _bp.y;
+          const dz = _p.z - _bp.z;
+          maxDeltaSq = Math.max(maxDeltaSq, dx * dx + dy * dy + dz * dz);
+          posData[o] = dx;
+          posData[o + 1] = dy;
+          posData[o + 2] = dz;
+          posData[o + 3] = 1;
+          nrmData[o] = _n.x;
+          nrmData[o + 1] = _n.y;
+          nrmData[o + 2] = _n.z;
+          nrmData[o + 3] = 1;
         }
-        _skin.multiplyMatrices(_acc, skinnedMesh.bindMatrix).premultiply(skinnedMesh.bindMatrixInverse);
-        _bp.fromBufferAttribute(basePos, v);
-        _p.copy(_bp).applyMatrix4(_skin);
-        bounds.expandByPoint(_p);
-        _n.fromBufferAttribute(baseNrm, v).transformDirection(_skin);
-        const o = (row * vertexCount + v) * 4;
-        const dx = _p.x - _bp.x;
-        const dy = _p.y - _bp.y;
-        const dz = _p.z - _bp.z;
-        maxDeltaSq = Math.max(maxDeltaSq, dx * dx + dy * dy + dz * dz);
-        posData[o] = dx;
-        posData[o + 1] = dy;
-        posData[o + 2] = dz;
-        posData[o + 3] = 1;
-        nrmData[o] = _n.x;
-        nrmData[o + 1] = _n.y;
-        nrmData[o + 2] = _n.z;
-        nrmData[o + 3] = 1;
       }
     }
     action.stop();
@@ -87,6 +260,10 @@ function bakeVAT(root, skinnedMesh, clips, { fps = 30 } = {}) {
   mixer.stopAllAction();
   mixer.setTime(0);
   root.updateMatrixWorld(true);
+  geometry.boundingBox = bounds.clone();
+  geometry.boundingSphere = bounds.getBoundingSphere(new Sphere());
+  const materials = [];
+  for (const part of parts) materials[part.materialIndex] = part.material;
   return {
     positionTexture: makeVATTexture(posData, vertexCount, totalFrames),
     normalTexture: makeVATTexture(nrmData, vertexCount, totalFrames),
@@ -94,9 +271,44 @@ function bakeVAT(root, skinnedMesh, clips, { fps = 30 } = {}) {
     bounds,
     vertexCount,
     totalFrames,
-    encoding: "delta"
+    encoding: "delta",
+    geometry,
+    materials
   };
 }
+function influencedBones(part) {
+  const used = /* @__PURE__ */ new Set();
+  const index = part.skinIndex;
+  const weight = part.skinWeight;
+  for (let v = 0; v < part.vertexCount; v++) {
+    for (let i = 0; i < 4; i++) {
+      if (weight.getComponent(v, i) !== 0) used.add(index.getComponent(v, i));
+    }
+  }
+  return { skeleton: part.skeleton, bones: [...used] };
+}
+var SCALE_UNIFORMITY_EPSILON = 1e-4;
+function hasNonUniformScale(m) {
+  const e = m.elements;
+  const x = e[0] * e[0] + e[1] * e[1] + e[2] * e[2];
+  const y = e[4] * e[4] + e[5] * e[5] + e[6] * e[6];
+  const z = e[8] * e[8] + e[9] * e[9] + e[10] * e[10];
+  const max = Math.max(x, y, z);
+  return max - Math.min(x, y, z) > SCALE_UNIFORMITY_EPSILON * max;
+}
+function warnOnNonUniformBoneScale(influencers, scratch) {
+  for (const { skeleton, bones } of influencers) {
+    for (const b of bones) {
+      scratch.multiplyMatrices(skeleton.bones[b].matrixWorld, skeleton.boneInverses[b]);
+      if (!hasNonUniformScale(scratch)) continue;
+      console.warn(
+        `three-vat: bone "${skeleton.bones[b].name || "(unnamed)"}" animates with non-uniform scale; baked normals under it are approximate, because linear-blend skinning transforms a normal by the skin matrix rather than its inverse-transpose \u2014 the same shortcut three's own skinning shader takes. Positions are exact.`
+      );
+      return true;
+    }
+  }
+  return false;
+}
 function makeVATTexture(data, width, height, type = FloatType) {
   const tex = new DataTexture(data, width, height, RGBAFormat, type);
   tex.minFilter = NearestFilter;
@@ -105,50 +317,5 @@ function makeVATTexture(data, width, height, type = FloatType) {
   tex.needsUpdate = true;
   return tex;
 }
-function serializeVAT(vat, { precision = "float16" } = {}) {
-  const pos = vat.positionTexture.image.data;
-  const nrm = vat.normalTexture.image.data;
-  const manifest = {
-    version: 1,
-    vertexCount: vat.vertexCount,
-    totalFrames: vat.totalFrames,
-    encoding: vat.encoding,
-    precision,
-    clips: vat.clips,
-    bounds: {
-      min: [vat.bounds.min.x, vat.bounds.min.y, vat.bounds.min.z],
-      max: [vat.bounds.max.x, vat.bounds.max.y, vat.bounds.max.z]
-    }
-  };
-  return { manifest, position: encode(pos, precision), normal: encode(nrm, precision) };
-}
-function encode(src, precision) {
-  if (precision === "float32") {
-    return src.slice().buffer;
-  }
-  const half = new Uint16Array(src.length);
-  for (let i = 0; i < src.length; i++) half[i] = DataUtils.toHalfFloat(src[i]);
-  return half.buffer;
-}
-function loadVAT(serialized) {
-  const { manifest, position, normal } = serialized;
-  const { vertexCount, totalFrames, precision } = manifest;
-  const type = precision === "float32" ? FloatType : HalfFloatType;
-  const posData = precision === "float32" ? new Float32Array(position) : new Uint16Array(position);
-  const nrmData = precision === "float32" ? new Float32Array(normal) : new Uint16Array(normal);
-  const bounds = new Box3(
-    new Vector3().fromArray(manifest.bounds.min),
-    new Vector3().fromArray(manifest.bounds.max)
-  );
-  return {
-    positionTexture: makeVATTexture(posData, vertexCount, totalFrames, type),
-    normalTexture: makeVATTexture(nrmData, vertexCount, totalFrames, type),
-    clips: manifest.clips,
-    bounds,
-    vertexCount,
-    totalFrames,
-    encoding: manifest.encoding
-  };
-}
 
-export { MAX_TEXTURE_SIZE, bakeVAT, loadVAT, makeVATTexture, serializeVAT };
+export { MAX_TEXTURE_SIZE, bakeVAT, makeVATTexture };

package/dist/instance-playback-BrGBIKLe.d.ts

@@ -0,0 +1,109 @@
+import { DataTexture, BufferGeometry, Material, Box3, InstancedMesh } from 'three';
+
+/** One baked animation range within a VAT's stacked frame rows. */
+interface VATClip {
+    /** Clip name, taken from the source `AnimationClip`. */
+    name: string;
+    /** First frame row (y) of this clip in the texture. */
+    startFrame: number;
+    /** Number of frame rows baked for this clip. */
+    frames: number;
+    /** Effective frames-per-second of the bake (`frames / duration`). */
+    fps: number;
+    /** Source clip duration in seconds. */
+    duration: number;
+    /**
+     * Largest per-vertex position-delta magnitude (metres) across the clip.
+     * Near-zero means the clip baked as a frozen pose — the diagnostic for a
+     * mis-targeted or genuinely static clip.
+     */
+    maxDelta: number;
+}
+/**
+ * A baked Vertex Animation Texture: the position/normal `DataTexture`s, the
+ * geometry they are indexed by, and the clip table and bounds needed to decode
+ * and render them. Produced exactly one way — {@link bakeVAT}, at runtime, from
+ * a loaded glTF (ADR-0010).
+ *
+ * The merged vertex ordering is the baker's own invention and the textures are
+ * indexed by it (`x = gl_VertexID`), so the caller cannot bring its own
+ * geometry — it must render the one baked here. `materials` is ordered to match
+ * `geometry.groups[].materialIndex`, giving one draw call per material.
+ */
+interface VAT {
+    /** RGBA float texture of per-vertex position deltas (`x = vertex`, `y = frame`). */
+    positionTexture: DataTexture;
+    /** RGBA float texture of per-vertex absolute normals (`x = vertex`, `y = frame`). */
+    normalTexture: DataTexture;
+    /** Merged, root-space rest-pose geometry. Its `position` is the delta reference. */
+    geometry: BufferGeometry;
+    /** Source materials, indexed by `geometry.groups[].materialIndex`. */
+    materials: Material[];
+    /** Clip table: name → `{ startFrame, frames, fps, ... }`. */
+    clips: VATClip[];
+    /** Union of every baked frame's bounds; use as the geometry bounding box. */
+    bounds: Box3;
+    /** Vertex count (texture width). */
+    vertexCount: number;
+    /** Total frame rows across all clips (texture height). */
+    totalFrames: number;
+    /** Position encoding. Only `'delta'` in v1. */
+    encoding: 'delta';
+}
+/**
+ * The shared playback clock: one `{ value }` in seconds, read by every material
+ * of every VAT mesh driven by it. Set it once per frame. Deliberately the
+ * narrowest shape both decode paths satisfy — a WebGL `IUniform<number>` and a
+ * TSL uniform node are both one of these — so `createVATMesh` returns the same
+ * thing on either renderer.
+ */
+interface VATClock {
+    value: number;
+}
+/**
+ * A **crowd** ready to render: the mesh to add to the scene, and the clock to
+ * advance. What `createVATMesh` returns on either decode path, so moving a
+ * crowd between renderers is an import change and nothing else. Named for what
+ * it is rather than for its `mesh` field — the clock is half of it.
+ */
+interface VATCrowd {
+    /** Add to the scene. Its instance matrices are yours to write. */
+    mesh: InstancedMesh;
+    /** The shared playback clock — set `.value` once per frame. */
+    time: VATClock;
+}
+
+/** Per-instance playback state consumed by both decode paths. */
+interface VATInstance {
+    clip: Pick<VAT['clips'][number], 'startFrame' | 'frames' | 'fps'>;
+    /** Phase offset in seconds — desyncs the crowd. */
+    timeOffset: number;
+    /** Playback rate multiplier. */
+    speed: number;
+}
+/**
+ * Attach the instance-playback attributes to an instanced geometry. Call once
+ * before rendering, on the geometry you hand to the `InstancedMesh`.
+ *
+ * The attribute names and layout below are the shared contract, spelled once in
+ * {@link PLAYBACK_ATTRIBUTES}. Both decode paths read exactly these five —
+ * `DECODE_PRELUDE` in `src/webgl.ts` as GLSL attributes, `vatNodes` in
+ * `src/tsl.ts` as TSL attribute nodes, when it is handed this geometry.
+ *
+ * | Attribute     | Type          | Source                |
+ * | ------------- | ------------- | --------------------- |
+ * | `aClipStart`  | `float` (x 1) | `instance.clip.startFrame` — first texture row of the clip's frame band |
+ * | `aClipFrames` | `float` (x 1) | `instance.clip.frames` — rows in the band |
+ * | `aClipFps`    | `float` (x 1) | `instance.clip.fps` — with `frames`, the clip's duration |
+ * | `aTimeOffset` | `float` (x 1) | `instance.timeOffset` — phase, in seconds |
+ * | `aSpeed`      | `float` (x 1) | `instance.speed` — rate multiplier |
+ *
+ * Every entry is a one-component `InstancedBufferAttribute` of `Float32Array`,
+ * one element per instance, in instance order. Adding a field — crossfade's
+ * reserved second clip index being the known case (ADR-0007) — means adding it
+ * here, in the table above, and in each decode path's own attribute
+ * declarations.
+ */
+declare function addVATInstanceAttributes(geometry: BufferGeometry, instances: VATInstance[]): void;
+
+export { type VAT as V, type VATClip as a, type VATClock as b, type VATCrowd as c, type VATInstance as d, addVATInstanceAttributes as e };