three-vat 2.0.0 → 3.0.0

package/dist/{chunk-2PGZ44TP.js → chunk-J5IEUGSB.js}

@@ -15,9 +15,11 @@ function makeVATTexture(data, width, height, type = FloatType) {
 var PACK_TEXELS = {
   clip: 0,
   playback: 1,
-  fade: 2
+  crossfade: 2,
+  outgoingClip: 3,
+  outgoingPlayback: 4
 };
-var PACK_WIDTH = 3;
+var PACK_WIDTH = 5;
 var PACK_STRIDE = PACK_WIDTH * 4;
 var LoopMode = {
   /** Play the clip end to end, forever (or `repetitions` times). */
@@ -34,7 +36,6 @@ var EndMode = {
   Rewind: 1
 };
 var INFINITE_REPETITIONS = -1;
-var MAX_FADE_DURATION = 0.25;
 function defaultRepetitions(loopMode) {
   return loopMode === LoopMode.Repeat ? INFINITE_REPETITIONS : 1;
 }
@@ -56,15 +57,12 @@ function resolvedPlaybackOf(instance) {
     speed: instance.speed ?? clip.speed ?? LIBRARY_PLAYBACK_DEFAULTS.speed
   };
 }
-function fadeOf(instance) {
-  const duration = Math.min(instance.fadeDuration ?? 0, MAX_FADE_DURATION);
+function crossfadeOf(instance) {
   const from = instance.from;
-  if (!from || duration <= 0 || from.frames <= 0) return null;
-  return { from, duration };
-}
-function fadeRowOf(from) {
-  return from.startFrame + Math.max(Math.min(Math.floor(from.phase * from.frames), from.frames - 1), 0);
+  if (!from || !asksToBlend(instance)) return null;
+  return { from, duration: instance.fadeDuration };
 }
+var asksToBlend = (instance) => (instance.fadeDuration ?? 0) > 0;
 function resolveVATFrame(instance, time) {
   const { clip } = instance;
   const frames = clip.frames;
@@ -95,8 +93,8 @@ function resolveVATFrame(instance, time) {
   const f0 = Math.min(Math.floor(f), last);
   const f1 = wraps ? (f0 + 1) % frames : Math.min(f0 + 1, last);
   const row = clip.startFrame + f0;
-  const fading = fadeOf(instance);
-  const elapsed = fading ? (time - instance.startTime) / fading.duration : 0;
+  const crossfade = crossfadeOf(instance);
+  const elapsed = crossfade ? (time - instance.startTime) / crossfade.duration : 0;
   return {
     row,
     rowNext: clip.startFrame + f1,
@@ -104,50 +102,85 @@ function resolveVATFrame(instance, time) {
     wraps,
     finished,
     phase,
-    fadeRow: fading ? fadeRowOf(fading.from) : row,
-    fadeWeight: fading ? 1 - Math.min(Math.max(elapsed, 0), 1) : 0
+    outgoing: crossfade ? { ...resolveVATFrame(crossfade.from, time), weight: 1 - Math.min(Math.max(elapsed, 0), 1) } : null
   };
 }
-function createVATPlaybackTexture(instances) {
-  const count = instances.length;
+var RESERVED_ROW = {
+  clip: { startFrame: 0, frames: 1, fps: 1 },
+  startTime: 0,
+  speed: 0
+};
+function createVATPlaybackTexture(instances, options = {}) {
+  const live = instances.length;
+  const count = options.capacity ?? live;
+  if (count < live) {
+    throw new Error(
+      `three-vat: a capacity of ${count} cannot hold the ${live} instances it was given \u2014 capacity is the crowd ceiling, so it is at least the crowd you start with.`
+    );
+  }
   if (count < 1) {
     throw new Error(
-      "three-vat: a crowd needs at least one instance \u2014 a playback texture is one row per instance, and there is no zero-row texture to carry none"
+      "three-vat: a crowd needs at least one instance \u2014 a playback texture is one row per instance, and there is no zero-row texture to carry none. Pass a capacity to reserve rows for a crowd that has not spawned yet"
     );
   }
   if (count > MAX_TEXTURE_SIZE) {
     throw new Error(
-      `three-vat: a crowd of ${count} instances needs ${count} rows of playback texture, past the ${MAX_TEXTURE_SIZE}-row ceiling \u2014 the playback texture holds one row per instance, so MAX_TEXTURE_SIZE is the instance ceiling.`
+      `three-vat: ${count} rows of playback texture is past the ${MAX_TEXTURE_SIZE}-row ceiling \u2014 the playback texture holds one row per instance, so MAX_TEXTURE_SIZE is the instance ceiling.`
     );
   }
   const data = new Float32Array(count * PACK_STRIDE);
-  for (let i = 0; i < count; i++) writePack(data, i, instances[i]);
+  for (let i = 0; i < count; i++) writePack(data, i, instances[i] ?? RESERVED_ROW);
   return { texture: makeVATTexture(data, PACK_WIDTH, count), count };
 }
 var FORWARD_ONLY_REASON = "a baked band plays forward from its own first row, so a negative speed would freeze it on that row rather than run it backwards \u2014 bake a reversed clip instead. A speed of 0 is a held first row, and is fine";
 var rowStart = (index) => index * PACK_STRIDE;
 var texelStart = (index, field) => rowStart(index) + field * 4;
-function writePack(data, index, instance) {
-  const clip = texelStart(index, PACK_TEXELS.clip);
-  const playback = texelStart(index, PACK_TEXELS.playback);
-  const fade = texelStart(index, PACK_TEXELS.fade);
-  const policy = resolvedPlaybackOf(instance);
+function checkedPolicyOf(state, index, what) {
+  const policy = resolvedPlaybackOf(state);
   if (policy.speed < 0) {
-    throw new Error(`three-vat: instance ${index} has speed ${policy.speed}; ${FORWARD_ONLY_REASON}.`);
+    throw new Error(`three-vat: ${what} ${index} has speed ${policy.speed}; ${FORWARD_ONLY_REASON}.`);
   }
-  data[clip] = instance.clip.startFrame;
-  data[clip + 1] = instance.clip.frames;
-  data[clip + 2] = instance.clip.fps;
+  return policy;
+}
+function putBand(data, index, at, state, policy) {
+  const clip = texelStart(index, at.clip);
+  const playback = texelStart(index, at.playback);
+  data[clip] = state.clip.startFrame;
+  data[clip + 1] = state.clip.frames;
+  data[clip + 2] = state.clip.fps;
   data[clip + 3] = policy.speed;
-  data[playback] = instance.startTime;
+  data[playback] = state.startTime;
   data[playback + 1] = policy.loopMode;
   data[playback + 2] = policy.repetitions;
   data[playback + 3] = policy.endMode;
-  const fading = fadeOf(instance);
-  data[fade] = fading ? fading.from.startFrame : 0;
-  data[fade + 1] = fading ? fading.from.frames : 0;
-  data[fade + 2] = fading ? fading.from.phase : 0;
-  data[fade + 3] = fading ? fading.duration : 0;
+}
+var LIVE_PAIR = { clip: PACK_TEXELS.clip, playback: PACK_TEXELS.playback };
+var OUTGOING_PAIR = { clip: PACK_TEXELS.outgoingClip, playback: PACK_TEXELS.outgoingPlayback };
+function checkedCrossfadeOf(instance, index) {
+  const duration = instance.fadeDuration;
+  if (duration !== void 0 && !(Number.isFinite(duration) && duration >= 0)) {
+    throw new Error(
+      `three-vat: instance ${index} has fadeDuration ${duration}; a transition lasts a finite number of seconds, and 0 (or no fadeDuration at all) is the cut.`
+    );
+  }
+  return crossfadeOf(instance);
+}
+function writePack(data, index, instance) {
+  const crossfade = checkedCrossfadeOf(instance, index);
+  const live = checkedPolicyOf(instance, index, "instance");
+  const outgoing = crossfade ? { state: crossfade.from, policy: checkedPolicyOf(crossfade.from, index, "the outgoing band of instance") } : null;
+  const crossfadeTexel = texelStart(index, PACK_TEXELS.crossfade);
+  putBand(data, index, LIVE_PAIR, instance, live);
+  if (outgoing) putBand(data, index, OUTGOING_PAIR, outgoing.state, outgoing.policy);
+  else clearTexels(data, index, OUTGOING_PAIR);
+  data[crossfadeTexel] = crossfade ? crossfade.duration : 0;
+  data[crossfadeTexel + 1] = 0;
+  data[crossfadeTexel + 2] = 0;
+  data[crossfadeTexel + 3] = 0;
+}
+function clearTexels(data, index, at) {
+  data.fill(0, texelStart(index, at.clip), texelStart(index, at.clip) + 4);
+  data.fill(0, texelStart(index, at.playback), texelStart(index, at.playback) + 4);
 }
 function readPack(data, index) {
   const clip = texelStart(index, PACK_TEXELS.clip);
@@ -163,35 +196,17 @@ function readPack(data, index) {
 }
 function assertInstance(playback, index) {
   if (!Number.isInteger(index) || index < 0 || index >= playback.count) {
-    throw new Error(`three-vat: instance ${index} is outside this crowd of ${playback.count}`);
+    throw new Error(`three-vat: instance ${index} is outside this crowd's ${playback.count} rows`);
   }
 }
 function setVATInstance(playback, index, instance) {
   assertInstance(playback, index);
   const data = playback.texture.image.data;
-  const fading = instance.from === void 0 && (instance.fadeDuration ?? 0) > 0 ? { ...instance, from: freezeOf(data, index, instance.startTime) } : instance;
-  writePack(data, index, fading);
+  const transitioning = instance.from === void 0 && asksToBlend(instance) ? { ...instance, from: readPack(data, index) } : instance;
+  writePack(data, index, transitioning);
   playback.texture.addUpdateRange(rowStart(index), PACK_STRIDE);
   playback.texture.needsUpdate = true;
 }
-function freezeOf(data, index, time) {
-  const outgoing = readPack(data, index);
-  const { row } = resolveVATFrame(outgoing, time);
-  return {
-    startFrame: outgoing.clip.startFrame,
-    frames: outgoing.clip.frames,
-    // The row the instance is actually displaying at that moment — so a fade
-    // out of a finished one-shot freezes the end pose it was holding, not the
-    // first row of a clip it stopped playing seconds ago.
-    //
-    // Named as the phase at the *centre* of that row rather than the playback
-    // phase itself, because {@link fadeRowOf} is what reads it back and the two
-    // do not spread a phase the same way: a bouncing ping-pong is up to a row
-    // apart between them, and rounding in a shader could cost another. Half a
-    // row of slack costs nothing and lands all three decodes on this row.
-    phase: (row - outgoing.clip.startFrame + 0.5) / outgoing.clip.frames
-  };
-}
 function endsAt(instance) {
   const { repetitions, speed } = resolvedPlaybackOf(instance);
   if (repetitions === INFINITE_REPETITIONS || speed <= 0) return null;
@@ -199,4 +214,13 @@ function endsAt(instance) {
   return instance.startTime + duration * repetitions / speed;
 }
 
-export { EndMode, FORWARD_ONLY_REASON, INFINITE_REPETITIONS, LIBRARY_PLAYBACK_DEFAULTS, LoopMode, MAX_FADE_DURATION, MAX_TEXTURE_SIZE, PACK_TEXELS, createVATPlaybackTexture, endsAt, makeVATTexture, resolveVATFrame, setVATInstance };
+// src/rig-texture.ts
+var RIG_TEXELS = {
+  /** `(qx, qy, qz, qw)` — the slot's rotation, on one hemisphere with its neighbouring rows. */
+  rotation: 0,
+  /** `(tx, ty, tz, s)` — where the slot puts the origin, and its uniform scale in the spare component. */
+  placement: 1
+};
+var RIG_TEXELS_PER_SLOT = 2;
+
+export { EndMode, FORWARD_ONLY_REASON, INFINITE_REPETITIONS, LIBRARY_PLAYBACK_DEFAULTS, LoopMode, MAX_TEXTURE_SIZE, PACK_TEXELS, RIG_TEXELS, RIG_TEXELS_PER_SLOT, createVATPlaybackTexture, endsAt, makeVATTexture, resolveVATFrame, setVATInstance };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { AnimationClip, AnimationAction, Object3D, TypedArray, TextureDataType, DataTexture } from 'three';
-import { V as VAT } from './carrier-BFCPmcQK.js';
-export { E as EndMode, I as INFINITE_REPETITIONS, L as LoopMode, M as MAX_FADE_DURATION, a as VATCarrier, b as VATClip, c as VATClipDefaults, d as VATClock, e as VATCrowd, f as VATFadeFrom, g as VATFrame, h as VATInstance, i as VATPlaybackTexture, j as createVATPlaybackTexture, k as endsAt, r as resolveVATFrame, s as setVATInstance } from './carrier-BFCPmcQK.js';
+import { D as DeltaVAT, R as RigVAT, V as VAT } from './carrier-BxRuW47G.js';
+export { E as EndMode, I as INFINITE_REPETITIONS, L as LoopMode, a as VATBase, b as VATCarrier, c as VATClip, d as VATClipDefaults, e as VATClock, f as VATCrowd, g as VATFrame, h as VATInstance, i as VATOutgoingFrame, j as VATPlaybackState, k as VATPlaybackTexture, l as VATPlaybackTextureOptions, m as createVATPlaybackTexture, n as endsAt, r as resolveVATFrame, s as setVATInstance } from './carrier-BxRuW47G.js';
 
 /**
  * What {@link bakeVAT} takes for each animation: the clip itself, or an
@@ -37,8 +37,29 @@ interface BakeOptions {
      * Anything else that shades — a smooth-shaded lit material — would light the
      * crowd by its rest-pose normals, which is visibly wrong (ADR-0002). Both
      * decode paths refuse that pairing loudly rather than render it.
+     *
+     * Accepted and ignored under the rig encoding, which has no normal texture to
+     * drop: normals come out of the skin matrix there. Refusing a no-op would
+     * punish the caller who switched encodings and left their options alone.
      */
     bakeNormals?: boolean;
+    /**
+     * What a frame row holds (ADR-0018). Default `'delta'`.
+     *
+     * - **`'delta'`** — the vertex encoding: where every vertex ended up, as a
+     *   position delta and a normal. Source-agnostic — skinning, morph targets
+     *   and node animation alike — and the default.
+     * - **`'rig'`** — the rig encoding: the posed rig, one **slot** per bone as a
+     *   rotation, a translation and a uniform scale, skinned in the vertex shader
+     *   from the rest-pose geometry. Two orders of magnitude smaller, no vertex
+     *   ceiling, and unable to store what a rig cannot express — refused at the
+     *   bake by name, before a frame is sampled: a morph target whose influence a
+     *   baked clip animates, or a bone (or rigid part) scaled unevenly. A morph
+     *   influence no clip animates is folded into the rest pose; a rigid,
+     *   node-animated part is one slot of weight one; parts reading the same
+     *   bones through the same bind matrix share slots.
+     */
+    encoding?: 'delta' | 'rig';
 }
 /**
  * Bake animations into a VAT by sampling the posed subtree frame by frame on
@@ -89,8 +110,22 @@ interface BakeOptions {
  * approximation becomes visible, so the bake warns once, naming the bone.
  * Renderer-agnostic — touches no WebGL/WebGPU context — so it runs identically
  * at runtime, in a Web Worker, and in Node.
+ *
+ * All of that is the **vertex encoding**, the default. `encoding: 'rig'`
+ * stores the posed rig instead — one slot per bone, two texels, skinned in the
+ * vertex shader from the rest-pose geometry (ADR-0018) — under the same clip
+ * table and the same playback contract, at a fraction of the memory; see
+ * {@link BakeOptions.encoding} for what it refuses. Overloaded on the option's
+ * literal, so a call that names no encoding, or the vertex encoding, still
+ * holds the narrow {@link DeltaVAT} it always did.
  */
-declare function bakeVAT(root: Object3D, animations: BakeInput[], { fps, maxTextureSize, bakeNormals }?: BakeOptions): VAT;
+declare function bakeVAT(root: Object3D, animations: BakeInput[], options?: BakeOptions & {
+    encoding?: 'delta';
+}): DeltaVAT;
+declare function bakeVAT(root: Object3D, animations: BakeInput[], options: BakeOptions & {
+    encoding: 'rig';
+}): RigVAT;
+declare function bakeVAT(root: Object3D, animations: BakeInput[], options?: BakeOptions): VAT;
 
 /**
  * The WebGL2 *spec floor for high-end desktop*, which two things lean on.
@@ -117,4 +152,4 @@ declare const MAX_TEXTURE_SIZE = 16384;
  */
 declare function makeVATTexture(data: TypedArray, width: number, height: number, type?: TextureDataType): DataTexture;
 
-export { type BakeInput, type BakeOptions, MAX_TEXTURE_SIZE, VAT, bakeVAT, makeVATTexture };
+export { type BakeInput, type BakeOptions, DeltaVAT, MAX_TEXTURE_SIZE, RigVAT, VAT, bakeVAT, makeVATTexture };