three-vat 4.0.0 → 4.2.0

package/dist/index.d.ts

@@ -1,6 +1,8 @@
-import { AnimationClip, AnimationAction, Object3D, DataTexture, FloatType, HalfFloatType } from 'three';
-import { D as DeltaVAT, R as RigVAT, V as VAT } from './carrier-D4pkftSk.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-D4pkftSk.js';
+import { AnimationClip, AnimationAction, Object3D, Material, DataTexture, FloatType, HalfFloatType } from 'three';
+import { D as DeltaVAT, R as RigVAT, b as VAT } from './types-CDPXKe0_.js';
+export { E as EndMode, I as INFINITE_REPETITIONS, L as LoopMode, e as VATBase, f as VATClip, g as VATClipDefaults, V as VATClock, d as VATCrowd, h as VATFrame, c as VATInstance, i as VATOutgoingFrame, j as VATPlaybackState, a as VATPlaybackTexture, k as VATPlaybackTextureOptions, l as createVATPlaybackTexture, m as endsAt, r as resolveVATFrame, s as setVATInstance, t as turnVATInstance } from './types-CDPXKe0_.js';
+import { GLTFLoader } from 'three/examples/jsm/loaders/GLTFLoader.js';
+export { V as VATCarrier } from './carrier-DmKhB4QL.js';
 
 /**
  * What {@link bakeVAT} takes for each animation: the clip itself, or an
@@ -15,10 +17,14 @@ interface BakeOptions {
     /** Sample rate in frames per second. Default `30`. */
     fps?: number;
     /**
-     * Largest texture dimension the target GPU accepts. Both VAT axes are checked
-     * against it: `vertexCount` (width) and `totalFrames` (height). Defaults to
+     * Largest texture dimension the target GPU accepts. Under the rig encoding
+     * both axes are checked against it: the rig's width and `totalFrames`. Under
+     * the vertex encoding a frame whose vertices outnumber it spans several rows
+     * instead of refusing (ADR-0030), so the height alone is checked: `totalFrames
+     * × rowsPerFrame`. Defaults to
      * {@link MAX_TEXTURE_SIZE}; pass the renderer's real limit to avoid baking a
-     * VAT that allocates on your desktop and fails on a phone.
+     * VAT that allocates on your desktop and fails on a phone, and so that a
+     * frame spans rows only where this GPU needs it to.
      */
     maxTextureSize?: number;
     /**
@@ -103,7 +109,8 @@ interface BakeOptions {
  * 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
+ * `loop`, `repetitions` and `timeScale` are read, a negative `timeScale` as a
+ * clip that plays backwards by default (ADR-0033). **`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.
@@ -150,6 +157,35 @@ declare function bakeVAT(root: Object3D, animations: BakeInput[], options: BakeO
 }): RigVAT;
 declare function bakeVAT(root: Object3D, animations: BakeInput[], options?: BakeOptions): VAT;
 
+interface LoadVATOptions {
+    /**
+     * The loader to read the file with: yours, configured as your page already
+     * configures it. A plain `GLTFLoader` when none is passed. The plugin that
+     * reads the baked file is registered on it once, and leaves every other
+     * file it loads alone.
+     */
+    loader?: GLTFLoader;
+    /**
+     * Your own materials, to use in place of the file's: one for each
+     * `materialIndex`, in that order, as `vat.materials` holds them. Replaces
+     * them wholesale, so a crowd is restyled without a re-bake. An array of
+     * another length is refused.
+     */
+    materials?: Material[];
+}
+/**
+ * Load a baked file, written by `npx three-vat bake <input> --out <file>`, as
+ * the VAT `bakeVAT` returned when the command baked it: every texel, the clip
+ * table with its defaults, the bounds and `fallback`. Hand it to
+ * `createVATMesh` exactly as a fresh one.
+ *
+ * Refuses, by name, a file of another format version, which is to be baked
+ * again, and a file whose geometry no longer matches the one its texels are
+ * addressed by, which an optimizer that reorders, welds or simplifies vertices
+ * is the likely cause of.
+ */
+declare function loadVAT(url: string, { loader, materials }?: LoadVATOptions): Promise<VAT>;
+
 /**
  * The WebGL2 *spec floor for high-end desktop*, which two things lean on.
  *
@@ -220,7 +256,8 @@ interface Vec3Out {
 }
 /**
  * Write a normal into two bytes of a VAT normal texture's buffer, at `offset`
- * and `offset + 1` — `(row * vertexCount + vertex) * 2` for the texel of one
+ * and `offset + 1` — `(row * vertexCount + vertex) * 2` in a one-row bake,
+ * `deltaTexel` in `src/test-utils.ts` in any, for the texel of one
  * vertex at one frame.
  *
  * Takes a direction, not a unit vector: the first step is a division by the L1
@@ -313,4 +350,4 @@ declare function bakeVATInWorker(worker: VATBakeWorker, root: Object3D, animatio
  */
 declare function serveVATBakes(scope?: VATBakeScope): () => void;
 
-export { type BakeInput, type BakeOptions, DeltaVAT, MAX_TEXTURE_SIZE, RigVAT, VAT, type VATBakeScope, type VATBakeWorker, type Vec3Out, bakeVAT, bakeVATInWorker, decodeOctahedral, encodeOctahedral, makeVATNormalTexture, makeVATTexture, serveVATBakes };
+export { type BakeInput, type BakeOptions, DeltaVAT, type LoadVATOptions, MAX_TEXTURE_SIZE, RigVAT, VAT, type VATBakeScope, type VATBakeWorker, type Vec3Out, bakeVAT, bakeVATInWorker, decodeOctahedral, encodeOctahedral, loadVAT, makeVATNormalTexture, makeVATTexture, serveVATBakes };