three-vat 3.0.0 → 4.1.0

package/dist/tsl.d.ts

@@ -1,5 +1,5 @@
 import { Node } from 'three/webgpu';
-import { e as VATClock, k as VATPlaybackTexture, b as VATCarrier, V as VAT, h as VATInstance, f as VATCrowd } from './carrier-BxRuW47G.js';
+import { e as VATClock, k as VATPlaybackTexture, b as VATCarrier, V as VAT, h as VATInstance, f as VATCrowd } from './carrier-VLSJLgjX.js';
 import 'three';
 
 /**
@@ -225,6 +225,12 @@ interface CreateVATMeshOptions {
      * call make its own is identical on either path.
      */
     time?: VATTimeUniform;
+    /**
+     * The GPU's real texture ceiling — {@link getMaxTextureSize} — which the
+     * playback texture checks the crowd against, one row per instance. Defaults
+     * to `MAX_TEXTURE_SIZE`, a desktop figure (`VATPlaybackTextureOptions`).
+     */
+    maxTextureSize?: number;
 }
 /**
  * Turn a baked VAT and a list of instances into a crowd ready to render: an

package/dist/tsl.js

@@ -1,7 +1,7 @@
 import { isBatchedCarrier, assertVATCarrier, assertBakedNormal } from './chunk-I4STYOD5.js';
-import { INFINITE_REPETITIONS, LoopMode, EndMode, createVATPlaybackTexture, PACK_TEXELS, RIG_TEXELS, RIG_TEXELS_PER_SLOT } from './chunk-J5IEUGSB.js';
+import { INFINITE_REPETITIONS, LoopMode, EndMode, createVATPlaybackTexture, PACK_TEXELS, RIG_TEXELS, vertexWidthOf, RIG_TEXELS_PER_SLOT } from './chunk-OEKKEHRQ.js';
 import { InstancedMesh } from 'three';
-import { uniform, Fn, positionLocal, normalLocal, tangentLocal, positionGeometry, batch, instancedMesh, float, bool, int, vertexIndex, attribute, mat3, tangentGeometry, normalGeometry, vec4, batchIndirectIndex, instanceIndex, hash, mix, textureLoad, ivec2, dot, mat4 } from 'three/tsl';
+import { uniform, Fn, positionLocal, normalLocal, tangentLocal, positionGeometry, batch, instancedMesh, float, bool, int, vertexIndex, attribute, mat3, tangentGeometry, normalGeometry, vec4, batchIndirectIndex, instanceIndex, hash, mix, textureLoad, ivec2, dot, mat4, vec3 } from 'three/tsl';
 
 function getMaxTextureSize(renderer) {
   const backend = renderer.backend;
@@ -103,20 +103,23 @@ function resolveBand(clip, playback, time) {
   const started = local.greaterThanEqual(0);
   const finished = started.and(playback.repetitions.notEqual(INFINITE_REPETITIONS)).and(loops.greaterThanEqual(playback.repetitions));
   const isPingPong = playback.loopMode.equal(LoopMode.PingPong);
-  const bounce = loops.mod(2);
+  const bounce = loops.sub(loops.mul(0.5).floor().mul(2));
   const pingPongPhase = bounce.lessThan(1).select(bounce, float(2).sub(bounce));
   const endPhase = playback.endMode.equal(EndMode.Clamp).select(float(1), float(0));
   const phase = started.select(
     finished.select(endPhase, isPingPong.select(pingPongPhase, loops.fract())),
     float(0)
   );
-  const wraps = started.select(
+  const looping = started.select(
     finished.select(bool(false), isPingPong.select(bool(false), bool(true))),
     bool(false)
   );
-  const f = phase.mul(wraps.select(frames, last));
+  const holds = looping.and(playback.endMode.equal(EndMode.Clamp)).and(playback.repetitions.notEqual(INFINITE_REPETITIONS)).and(loops.floor().add(1).greaterThanEqual(playback.repetitions));
+  const wraps = looping.and(holds.not());
+  const f = phase.mul(looping.select(frames, last));
   const f0 = f.floor().min(last);
-  const f1 = wraps.select(f0.add(1).mod(frames), f0.add(1).min(last));
+  const next = f0.add(1);
+  const f1 = wraps.select(next.greaterThanEqual(frames).select(float(0), next), next.min(last));
   const bandRow = (offset) => int(offset).add(clip.startFrame);
   return {
     row0: bandRow(f0),
@@ -164,18 +167,50 @@ function vatDecode(vat, options = {}) {
     }
   }
 }
-function vertexDecode({ positionTexture, normalTexture }, rows) {
+function octDecode(stored) {
+  const e = stored.mul(2).sub(1);
+  const ex = e.x;
+  const ey = e.y;
+  const z = float(1).sub(ex.abs()).sub(ey.abs());
+  const overshoot = z.negate().max(0);
+  const back = (component) => component.sub(component.greaterThanEqual(0).select(overshoot, overshoot.negate()));
+  return vec3(back(ex), back(ey), z).normalize();
+}
+function texelOf(vat, vertexRow) {
+  const { rowsPerFrame } = vat;
+  if (rowsPerFrame === 1) return { column: vertexRow, rowOf: (row) => row };
+  const width = int(vertexWidthOf(vat));
+  const line = vertexRow.div(width);
+  const spanned = /* @__PURE__ */ new Map();
+  return {
+    column: vertexRow.mod(width),
+    rowOf: (row) => {
+      let at = spanned.get(row);
+      if (!at) spanned.set(row, at = row.mul(int(rowsPerFrame)).add(line));
+      return at;
+    }
+  };
+}
+function vertexDecode(vat, rows) {
+  const { positionTexture, normalTexture } = vat;
   const vertexRow = int(vertexIndex);
+  const { column, rowOf } = texelOf(vat, vertexRow);
   const band = (tex, of) => {
-    const s0 = textureLoad(tex, ivec2(vertexRow, of.row0)).xyz;
-    const s1 = textureLoad(tex, ivec2(vertexRow, of.row1)).xyz;
+    const s0 = textureLoad(tex, ivec2(column, rowOf(of.row0))).xyz;
+    const s1 = textureLoad(tex, ivec2(column, rowOf(of.row1))).xyz;
     return mix(s0, s1, of.blend);
   };
   const sample = (tex) => mix(band(tex, rows.live), band(tex, rows.outgoing), rows.weight);
+  const bandNormal = (tex, of) => {
+    const s0 = octDecode(textureLoad(tex, ivec2(column, rowOf(of.row0))).xy);
+    const s1 = octDecode(textureLoad(tex, ivec2(column, rowOf(of.row1))).xy);
+    return mix(s0, s1, of.blend);
+  };
+  const sampleNormal = (tex) => mix(bandNormal(tex, rows.live), bandNormal(tex, rows.outgoing), rows.weight);
   return {
     encoding: "delta",
     position: sample(positionTexture),
-    normal: normalTexture ? sample(normalTexture).normalize() : null
+    normal: normalTexture ? sampleNormal(normalTexture).normalize() : null
   };
 }
 function compose(q, ts) {
@@ -247,7 +282,7 @@ function rigDecode({ rigTexture, geometry }, rows) {
 }
 function createVATMesh(vat, instances, options = {}) {
   const time = options.time ?? uniform(0);
-  const playback = createVATPlaybackTexture(instances);
+  const playback = createVATPlaybackTexture(instances, { maxTextureSize: options.maxTextureSize });
   for (const source of vat.materials) assertBakedNormal(vat, source);
   const materials = vat.materials.map((source) => source.clone());
   const mesh = new InstancedMesh(vat.geometry, materials, instances.length);

package/dist/webgl.d.ts

@@ -1,5 +1,5 @@
 import { IUniform, MeshDepthMaterial, WebGLRenderer, Material } from 'three';
-import { b as VATCarrier, V as VAT, k as VATPlaybackTexture, h as VATInstance, f as VATCrowd } from './carrier-BxRuW47G.js';
+import { b as VATCarrier, V as VAT, k as VATPlaybackTexture, h as VATInstance, f as VATCrowd } from './carrier-VLSJLgjX.js';
 
 /**
  * The real maximum texture dimension this GPU accepts, for
@@ -137,6 +137,12 @@ interface CreateVATMeshOptions {
      * untwisted shadow.
      */
     hook?: VATPostDecodeHook;
+    /**
+     * The GPU's real texture ceiling — {@link getMaxTextureSize} — which the
+     * playback texture checks the crowd against, one row per instance. Defaults
+     * to `MAX_TEXTURE_SIZE`, a desktop figure (`VATPlaybackTextureOptions`).
+     */
+    maxTextureSize?: number;
 }
 /**
  * Turn a baked VAT and a list of instances into a crowd ready to render: an

package/dist/webgl.js

@@ -1,5 +1,5 @@
 import { assertBakedNormal, assertVATCarrier, isBatchedCarrier } from './chunk-I4STYOD5.js';
-import { PACK_TEXELS, EndMode, LoopMode, RIG_TEXELS_PER_SLOT, RIG_TEXELS, INFINITE_REPETITIONS, createVATPlaybackTexture } from './chunk-J5IEUGSB.js';
+import { PACK_TEXELS, EndMode, LoopMode, RIG_TEXELS_PER_SLOT, RIG_TEXELS, INFINITE_REPETITIONS, createVATPlaybackTexture, vertexWidthOf } from './chunk-OEKKEHRQ.js';
 import { MeshDepthMaterial, RGBADepthPacking, InstancedMesh, MeshDistanceMaterial, Material } from 'three';
 
 function getMaxTextureSize(renderer) {
@@ -62,26 +62,35 @@ var ROW_PRELUDE = (
     bool finished = started && repetitions != ${glslFloat(INFINITE_REPETITIONS)} && loops >= repetitions;
 
     float phase;
-    bool wraps;
+    bool looping;
     if ( !started ) {
       phase = 0.0;
-      wraps = false;
+      looping = false;
     } else if ( finished ) {
       // Held at an end pose, and in neither case sampling past it.
       phase = vatPlayback.w == ${glslFloat(EndMode.Clamp)} ? 1.0 : 0.0;
-      wraps = false;
+      looping = false;
     } else if ( vatPlayback.y == ${glslFloat(LoopMode.PingPong)} ) {
-      float m = mod( loops, 2.0 );
+      // Halved rather than divided, so the remainder cannot land below zero.
+      float m = loops - 2.0 * floor( loops * 0.5 );
       phase = m < 1.0 ? m : 2.0 - m;
-      wraps = false; // a ping-pong bounces; it does not wrap
+      looping = false; // a ping-pong bounces; it does not wrap
     } else {
       phase = fract( loops );
-      wraps = true;  // and here the interpolation crossing back is correct
+      looping = true;  // and here the interpolation crossing back is correct
     }
 
-    float f = phase * ( wraps ? frames : last );
+    // Except across the final repetition of a clip that clamps, which holds its
+    // last row rather than blending back toward its first (#88).
+    bool holds = looping && vatPlayback.w == ${glslFloat(EndMode.Clamp)} && repetitions != ${glslFloat(INFINITE_REPETITIONS)} && floor( loops ) + 1.0 >= repetitions;
+    bool wraps = looping && !holds;
+
+    float f = phase * ( looping ? frames : last );
     float f0 = min( floor( f ), last );
-    float f1 = wraps ? mod( f0 + 1.0, frames ) : min( f0 + 1.0, last );
+    // A compare, not a mod: a mod divides, and at the last row a quotient a hair
+    // under 1 leaves f1 at frames, one row past the band (#79).
+    float next = f0 + 1.0;
+    float f1 = wraps ? ( next >= frames ? 0.0 : next ) : min( next, last );
 
     VatBand band;
     band.row0 = int( vatClip.x + f0 );
@@ -112,10 +121,10 @@ var ROW_PRELUDE = (
     // normal decode. Every vertex of an instance reads the same texels of the
     // same row, whichever branch it takes, so the texture cache absorbs them;
     // the demo bench under ADR-0016's 5% bound is what said so for three of
-    // them, and ADR-0025's is what says so for a transitioning instance's five.
+    // them, and #72's idle-crowd bench is what says so for all five.
     //
-    // Three texels, always \u2014 the crossfade one sits third exactly so that an
-    // instance that is not transitioning reads what it has always read.
+    // Three texels here, the live pair and the crossfade; the other two are
+    // vatOutgoingBand's, fetched every frame by every sampler that calls it.
     vec4 vatClip      = texelFetch( uVatPlaybackTex, ivec2( ${PACK_TEXELS.clip}, vatInstance ), 0 );
     vec4 vatPlayback  = texelFetch( uVatPlaybackTex, ivec2( ${PACK_TEXELS.playback}, vatInstance ), 0 );
     vec4 vatCrossfade = texelFetch( uVatPlaybackTex, ivec2( ${PACK_TEXELS.crossfade}, vatInstance ), 0 );
@@ -166,17 +175,23 @@ var ROW_PRELUDE = (
   }
 `
 );
-var VERTEX_PRELUDE = (
+function texelOf(vat) {
+  const { rowsPerFrame } = vat;
+  if (rowsPerFrame === 1) return (row) => `ivec2( gl_VertexID, ${row} )`;
+  const width = vertexWidthOf(vat);
+  return (row) => `ivec2( gl_VertexID % ${width}, ${row} * ${rowsPerFrame} + gl_VertexID / ${width} )`;
+}
+var vertexPrelude = (texel) => (
   /* glsl */
   `
   uniform highp sampler2D uVatPosTex;
 
-  // One band of one layer: the two rows this band sits between, mixed. The
-  // same function for the live band and the outgoing one, as vatBand is the same
-  // function for both pairs.
+  // One band of the position layer: the two rows this band sits between,
+  // mixed. The same function for the live band and the outgoing one, as
+  // vatBand is the same function for both pairs.
   vec3 vatBandSample( const in sampler2D tex, const in VatBand band ) {
-    vec3 s0 = texelFetch( tex, ivec2( gl_VertexID, band.row0 ), 0 ).xyz;
-    vec3 s1 = texelFetch( tex, ivec2( gl_VertexID, band.row1 ), 0 ).xyz;
+    vec3 s0 = texelFetch( tex, ${texel("band.row0")}, 0 ).xyz;
+    vec3 s1 = texelFetch( tex, ${texel("band.row1")}, 0 ).xyz;
     return mix( s0, s1, band.blend );
   }
 
@@ -199,10 +214,37 @@ var VERTEX_PRELUDE = (
   }
 `
 );
-var NORMAL_PRELUDE = (
+var normalPrelude = (texel) => (
   /* glsl */
   `
   uniform highp sampler2D uVatNrmTex;
+
+  vec2 vatOctSign( const in vec2 v ) {
+    return vec2( v.x >= 0.0 ? 1.0 : -1.0, v.y >= 0.0 ? 1.0 : -1.0 );
+  }
+
+  vec3 vatOctDecode( const in vec2 stored ) {
+    vec2 e = stored * 2.0 - 1.0;
+    float z = 1.0 - abs( e.x ) - abs( e.y );
+    vec2 xy = e - vatOctSign( e ) * max( -z, 0.0 );
+    return normalize( vec3( xy, z ) );
+  }
+
+  // One band of the normal layer \u2014 vatBandSample, over decoded normals.
+  vec3 vatBandSampleNormal( const in VatBand band ) {
+    vec3 s0 = vatOctDecode( texelFetch( uVatNrmTex, ${texel("band.row0")}, 0 ).xy );
+    vec3 s1 = vatOctDecode( texelFetch( uVatNrmTex, ${texel("band.row1")}, 0 ).xy );
+    return mix( s0, s1, band.blend );
+  }
+
+  // vatSample, for the one layer whose texel is not what it decodes to. The
+  // outgoing band is resolved and mixed unconditionally here too, for the
+  // reason spelled out on vatSample.
+  vec3 vatSampleNormal( const in int vatInstance ) {
+    VatRows rows = vatRows( vatInstance );
+    VatBand outgoing = vatOutgoingBand( vatInstance, rows.weight > 0.0 );
+    return mix( vatBandSampleNormal( rows.live ), vatBandSampleNormal( outgoing ), rows.weight );
+  }
 `
 );
 var RIG_PRELUDE = (
@@ -320,7 +362,7 @@ var vertexPosition = (id) => (
 var vertexNormal = (id) => (
   /* glsl */
   `
-  vec3 objectNormal = normalize( vatSample( uVatNrmTex, ${INSTANCE_ID[id]} ) );
+  vec3 objectNormal = normalize( vatSampleNormal( ${INSTANCE_ID[id]} ) );
   #ifdef USE_TANGENT
     vec3 objectTangent = vec3( tangent.xyz );
   #endif
@@ -343,9 +385,12 @@ var rigNormal = (id) => (
   #endif
 `
 );
-function vertexDecode({ positionTexture, normalTexture }, id) {
+function vertexDecode(vat, id) {
+  const { positionTexture, normalTexture, rowsPerFrame } = vat;
+  const texel = texelOf(vat);
+  const span = rowsPerFrame === 1 ? "" : `:rows${rowsPerFrame}x${vertexWidthOf(vat)}`;
   return {
-    prelude: (normalTexture ? NORMAL_PRELUDE : "") + VERTEX_PRELUDE,
+    prelude: (normalTexture ? normalPrelude(texel) : "") + vertexPrelude(texel),
     bind(uniforms) {
       uniforms.uVatPosTex = { value: positionTexture };
       if (normalTexture) uniforms.uVatNrmTex = { value: normalTexture };
@@ -358,7 +403,7 @@ function vertexDecode({ positionTexture, normalTexture }, id) {
     normal: normalTexture ? vertexNormal(id) : null,
     // A normal-less VAT injects a different vertex shader off the same material
     // parameters, so the variant is in the key (see `patchVATMaterial`).
-    key: `three-vat:${id}${normalTexture ? "" : ":no-normal"}`,
+    key: `three-vat:${id}${normalTexture ? "" : ":no-normal"}${span}`,
     instanceIndex: INSTANCE_ID[id]
   };
 }
@@ -473,7 +518,7 @@ function createVATDepthMaterial(vat, uniforms, playback, options) {
 }
 function createVATMesh(vat, instances, options = {}) {
   const uniforms = options.time ? { uVatTime: options.time } : createVATUniforms();
-  const playback = createVATPlaybackTexture(instances);
+  const playback = createVATPlaybackTexture(instances, { maxTextureSize: options.maxTextureSize });
   const patch = { hook: options.hook };
   const materials = vat.materials.map((source) => patchVATMaterial(source.clone(), vat, uniforms, playback, patch));
   const mesh = new InstancedMesh(vat.geometry, materials, instances.length);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "three-vat",
-  "version": "3.0.0",
+  "version": "4.1.0",
   "description": "Bake glTF animation clips into vertex animation textures for zero-CPU instanced crowds in three.js.",
   "type": "module",
   "license": "MIT",