three-vat 1.0.1 → 2.1.0

package/dist/chunk-3PWAY6MD.js

@@ -0,0 +1,211 @@
+import { FloatType, DataTexture, RGBAFormat, NearestFilter } from 'three';
+
+// src/vat-texture.ts
+var MAX_TEXTURE_SIZE = 16384;
+function makeVATTexture(data, width, height, type = FloatType) {
+  const tex = new DataTexture(data, width, height, RGBAFormat, type);
+  tex.minFilter = NearestFilter;
+  tex.magFilter = NearestFilter;
+  tex.generateMipmaps = false;
+  tex.needsUpdate = true;
+  return tex;
+}
+
+// src/instance-playback.ts
+var PACK_TEXELS = {
+  clip: 0,
+  playback: 1,
+  fade: 2
+};
+var PACK_WIDTH = 3;
+var PACK_STRIDE = PACK_WIDTH * 4;
+var LoopMode = {
+  /** Play the clip end to end, forever (or `repetitions` times). */
+  Repeat: 0,
+  /** Play the clip through once. */
+  Once: 1,
+  /** Play forward, then backward, without baking the reversed frames. */
+  PingPong: 2
+};
+var EndMode = {
+  /** Hold the last frame. */
+  Clamp: 0,
+  /** Return to the first frame. */
+  Rewind: 1
+};
+var INFINITE_REPETITIONS = -1;
+var MAX_FADE_DURATION = 0.25;
+function defaultRepetitions(loopMode) {
+  return loopMode === LoopMode.Repeat ? INFINITE_REPETITIONS : 1;
+}
+var LIBRARY_PLAYBACK_DEFAULTS = {
+  loopMode: LoopMode.Repeat,
+  repetitions: defaultRepetitions(LoopMode.Repeat),
+  endMode: EndMode.Clamp,
+  speed: 1
+};
+function resolvedPlaybackOf(instance) {
+  const { clip } = instance;
+  const clipLoopMode = clip.loopMode ?? LIBRARY_PLAYBACK_DEFAULTS.loopMode;
+  const loopMode = instance.loopMode ?? clipLoopMode;
+  const clipRepetitions = loopMode === clipLoopMode ? clip.repetitions : void 0;
+  return {
+    loopMode,
+    repetitions: instance.repetitions ?? clipRepetitions ?? defaultRepetitions(loopMode),
+    endMode: instance.endMode ?? clip.endMode ?? LIBRARY_PLAYBACK_DEFAULTS.endMode,
+    speed: instance.speed ?? clip.speed ?? LIBRARY_PLAYBACK_DEFAULTS.speed
+  };
+}
+function fadeOf(instance) {
+  const duration = Math.min(instance.fadeDuration ?? 0, MAX_FADE_DURATION);
+  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);
+}
+function resolveVATFrame(instance, time) {
+  const { clip } = instance;
+  const frames = clip.frames;
+  const last = frames - 1;
+  const duration = frames / clip.fps;
+  const { loopMode, repetitions, endMode, speed } = resolvedPlaybackOf(instance);
+  const local = (time - instance.startTime) * speed;
+  const loops = local / duration;
+  const started = local >= 0;
+  const finished = started && repetitions !== INFINITE_REPETITIONS && loops >= repetitions;
+  let phase;
+  let wraps;
+  if (!started) {
+    phase = 0;
+    wraps = false;
+  } else if (finished) {
+    phase = endMode === EndMode.Clamp ? 1 : 0;
+    wraps = false;
+  } else if (loopMode === LoopMode.PingPong) {
+    const m = loops % 2;
+    phase = m < 1 ? m : 2 - m;
+    wraps = false;
+  } else {
+    phase = loops % 1;
+    wraps = true;
+  }
+  const f = phase * (wraps ? frames : last);
+  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;
+  return {
+    row,
+    rowNext: clip.startFrame + f1,
+    mix: f - f0,
+    wraps,
+    finished,
+    phase,
+    fadeRow: fading ? fadeRowOf(fading.from) : row,
+    fadeWeight: fading ? 1 - Math.min(Math.max(elapsed, 0), 1) : 0
+  };
+}
+function createVATPlaybackTexture(instances) {
+  const count = instances.length;
+  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"
+    );
+  }
+  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.`
+    );
+  }
+  const data = new Float32Array(count * PACK_STRIDE);
+  for (let i = 0; i < count; i++) writePack(data, i, instances[i]);
+  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);
+  if (policy.speed < 0) {
+    throw new Error(`three-vat: instance ${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;
+  data[clip + 3] = policy.speed;
+  data[playback] = instance.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;
+}
+function readPack(data, index) {
+  const clip = texelStart(index, PACK_TEXELS.clip);
+  const playback = texelStart(index, PACK_TEXELS.playback);
+  return {
+    clip: { startFrame: data[clip], frames: data[clip + 1], fps: data[clip + 2] },
+    startTime: data[playback],
+    speed: data[clip + 3],
+    loopMode: data[playback + 1],
+    repetitions: data[playback + 2],
+    endMode: data[playback + 3]
+  };
+}
+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}`);
+  }
+}
+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);
+  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;
+  const duration = instance.clip.frames / instance.clip.fps;
+  return instance.startTime + duration * repetitions / speed;
+}
+
+// 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_FADE_DURATION, MAX_TEXTURE_SIZE, PACK_TEXELS, RIG_TEXELS, RIG_TEXELS_PER_SLOT, createVATPlaybackTexture, endsAt, makeVATTexture, resolveVATFrame, setVATInstance };

package/dist/chunk-I4STYOD5.js

@@ -0,0 +1,53 @@
+// src/baked-normals.ts
+var NORMAL_READING_FLAGS = [
+  "isMeshStandardMaterial",
+  "isMeshPhongMaterial",
+  "isMeshLambertMaterial",
+  "isMeshToonMaterial",
+  "isMeshNormalMaterial",
+  "isMeshMatcapMaterial"
+];
+function needsBakedNormal(material) {
+  if (material.flatShading === true) return false;
+  const flags = material;
+  return NORMAL_READING_FLAGS.some((flag) => flags[flag] === true);
+}
+function assertBakedNormal(vat, material) {
+  if (vat.encoding !== "delta" || vat.normalTexture !== null || !needsBakedNormal(material)) return;
+  throw new Error(
+    `three-vat: material "${material.name || "(unnamed)"}" (${material.type}) shades from a normal, but this VAT was baked with \`bakeNormals: false\` and carries none \u2014 the crowd would be lit by its rest pose. Set \`flatShading: true\` on the material (three then derives the normal from the deformed position, per fragment, which is the right normal for a posed mesh), or use an unlit material such as MeshBasicMaterial, or bake with \`bakeNormals: true\`.`
+  );
+}
+
+// src/carrier.ts
+function isBatchedCarrier(carrier) {
+  return carrier?.isBatchedMesh === true;
+}
+function rangeOf(batch, geometryId) {
+  try {
+    return batch.getGeometryRangeAt(geometryId);
+  } catch {
+    return null;
+  }
+}
+function assertVATCarrier(carrier, vat) {
+  if (!isBatchedCarrier(carrier)) return;
+  if (rangeOf(carrier, 1)) {
+    throw new Error(
+      "three-vat: a BatchedMesh carrier must hold exactly one geometry \u2014 the VAT\u2019s own. Both decode paths index the VAT by the vertex index, which on a batch is the geometry\u2019s vertexStart plus the vertex, so a second geometry\u2019s instances read another character\u2019s rows. One VAT, one geometry, N instances: mixing characters in one draw needs one VAT texture each, and a sampler is a uniform per draw call."
+    );
+  }
+  const range = rangeOf(carrier, 0);
+  if (!range) {
+    throw new Error(
+      "three-vat: this BatchedMesh holds no geometry \u2014 add `vat.geometry` with `addGeometry` before patching a material for it."
+    );
+  }
+  if (range.vertexStart !== 0 || range.vertexCount !== vat.vertexCount) {
+    throw new Error(
+      `three-vat: this BatchedMesh\u2019s geometry spans ${range.vertexCount} vertices from ${range.vertexStart}, and the VAT has ${vat.vertexCount} from 0. The decode reads the VAT at the batch\u2019s own vertex index, so the batch must hold \`vat.geometry\` and nothing before it.`
+    );
+  }
+}
+
+export { assertBakedNormal, assertVATCarrier, isBatchedCarrier };

package/dist/index.d.ts

@@ -1,16 +1,16 @@
-import { Object3D, AnimationClip, TypedArray, TextureDataType, DataTexture } from 'three';
-import { V as VAT } from './instance-playback-BrGBIKLe.js';
-export { a as VATClip, b as VATClock, c as VATCrowd, d as VATInstance, e as addVATInstanceAttributes } from './instance-playback-BrGBIKLe.js';
+import { AnimationClip, AnimationAction, Object3D, TypedArray, TextureDataType, DataTexture } from 'three';
+import { D as DeltaVAT, R as RigVAT, V as VAT } from './carrier-BXaLAPRO.js';
+export { E as EndMode, I as INFINITE_REPETITIONS, L as LoopMode, M as MAX_FADE_DURATION, a as VATBase, b as VATCarrier, c as VATClip, d as VATClipDefaults, e as VATClock, f as VATCrowd, g as VATFadeFrom, h as VATFrame, i as VATInstance, j as VATPlaybackTexture, k as createVATPlaybackTexture, l as endsAt, r as resolveVATFrame, s as setVATInstance } from './carrier-BXaLAPRO.js';
 
 /**
- * Conservative fallback texture-dimension cap, used when the caller does not
- * pass `maxTextureSize`. This is the WebGL2 *spec floor for high-end desktop*,
- * not a guarantee — plenty of mobile GPUs report 4096 or 8192. The baker is
- * renderer-agnostic by design (it runs in Node, and in a Web Worker), so it cannot
- * query the real limit itself: pass `getMaxTextureSize(renderer)` from
- * `three-vat/webgl` or `three-vat/tsl` whenever a renderer exists.
+ * What {@link bakeVAT} takes for each animation: the clip itself, or an
+ * `AnimationAction` already configured the way three taught you.
+ *
+ * An action costs the baker nothing — it builds an `AnimationMixer` to pose the
+ * mesh either way — and buys the caller per-clip defaults every instance of
+ * that clip inherits ({@link VATClipDefaults}).
  */
-declare const MAX_TEXTURE_SIZE = 16384;
+type BakeInput = AnimationClip | AnimationAction;
 interface BakeOptions {
     /** Sample rate in frames per second. Default `30`. */
     fps?: number;
@@ -21,10 +21,76 @@ interface BakeOptions {
      * VAT that allocates on your desktop and fails on a phone.
      */
     maxTextureSize?: number;
+    /**
+     * Bake the normal texture. Default `true`.
+     *
+     * Turning it off halves the VAT — `verts x frames x 16 B x 2` becomes `x 1` —
+     * and is correct for exactly two material setups:
+     *
+     * - **Unlit** (`MeshBasicMaterial`, and its node twin), which never reads a
+     *   normal, so the texture was pure waste.
+     * - **`flatShading: true`**, where three derives the normal from screen-space
+     *   derivatives of the *deformed* position in the fragment stage. That is the
+     *   correct normal for the posed mesh, computed for free — the baked one is
+     *   not merely unnecessary there, it is redundant work.
+     *
+     * 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 `AnimationClip`s into a VAT by sampling the posed subtree frame by frame
- * on the CPU.
+ * Bake animations into a VAT by sampling the posed subtree frame by frame on
+ * the CPU.
+ *
+ * Each entry of `animations` is an `AnimationClip`, or an `AnimationAction`
+ * already configured the way three taught you:
+ *
+ * ```ts
+ * const action = mixer.clipAction(deathClip)
+ * action.loop = THREE.LoopOnce
+ *
+ * const vat = bakeVAT(gltf.scene, [walkAction, action, idleClip])
+ * ```
+ *
+ * Every instance that plays `death` then inherits "once, clamped" without the
+ * caller saying so again, and may still override any of it. An action costs the
+ * bake nothing — it builds an `AnimationMixer` to pose the mesh either way — and
+ * a plain clip carries no configuration, so the simple case still needs no
+ * mixer at all and takes the library defaults ({@link VATClipDefaults}).
+ *
+ * `loop`, `repetitions` and `timeScale` are read. **`clampWhenFinished` is
+ * not**: it is `false` on every untouched action, so a crowd reads it as the
+ * silence it usually is and clamps either way — an instance names
+ * `endMode: EndMode.Rewind` to get three's behaviour back.
+ * **`time` and `paused` are ignored**: they say where a playhead is sitting,
+ * not how the animation is meant to play, and a VAT has no playhead of its own
+ * to seed — every instance's position is a function of the shared clock and its
+ * own `startTime`. A non-unit `weight` and an additive `blendMode` are refused
+ * outright; both describe several actions blended at once, which one baked band
+ * cannot be.
  *
  * The unit of a bake is the whole subtree under `root`, merged into one vertex
  * set and recorded in root space (ADR-0008) — so it handles a single
@@ -44,8 +110,41 @@ 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, clips: AnimationClip[], { fps, maxTextureSize }?: 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.
+ *
+ * - **The bake's fallback cap**, used when the caller does not pass
+ *   `maxTextureSize`. The baker is renderer-agnostic by design (it runs in
+ *   Node, and in a Web Worker) so it cannot query the real limit itself: pass
+ *   `getMaxTextureSize(renderer)` from `three-vat/webgl` or `three-vat/tsl`
+ *   whenever a renderer exists.
+ * - **The instance ceiling**, because the playback texture is one row per
+ *   instance (`createVATPlaybackTexture`, ADR-0016). That one takes no
+ *   override, the crowd being built long after the bake was sized.
+ *
+ * Not a guarantee either way: plenty of mobile GPUs report 4096 or 8192, and
+ * a crowd between that and this number is refused by the driver at upload
+ * rather than here. The bake is where the real limit is worth passing, because
+ * it is where the numbers get large.
+ */
+declare const MAX_TEXTURE_SIZE = 16384;
 /**
  * Build a VAT `DataTexture` with the fixed sampling flags every path relies on:
  * RGBA, nearest filtering, no mipmaps. Frame interpolation is done manually in
@@ -53,4 +152,4 @@ declare function bakeVAT(root: Object3D, clips: AnimationClip[], { fps, maxTextu
  */
 declare function makeVATTexture(data: TypedArray, width: number, height: number, type?: TextureDataType): DataTexture;
 
-export { type BakeOptions, MAX_TEXTURE_SIZE, VAT, bakeVAT, makeVATTexture };
+export { type BakeInput, type BakeOptions, DeltaVAT, MAX_TEXTURE_SIZE, RigVAT, VAT, bakeVAT, makeVATTexture };