three-vat 2.1.0 → 4.0.0

package/dist/webgl.js

@@ -1,6 +1,6 @@
 import { assertBakedNormal, assertVATCarrier, isBatchedCarrier } from './chunk-I4STYOD5.js';
-import { PACK_TEXELS, EndMode, LoopMode, RIG_TEXELS_PER_SLOT, RIG_TEXELS, INFINITE_REPETITIONS, createVATPlaybackTexture } from './chunk-3PWAY6MD.js';
-import { MeshDepthMaterial, RGBADepthPacking, InstancedMesh, MeshDistanceMaterial } from 'three';
+import { PACK_TEXELS, EndMode, LoopMode, RIG_TEXELS_PER_SLOT, RIG_TEXELS, INFINITE_REPETITIONS, createVATPlaybackTexture } from './chunk-BSAJL5PG.js';
+import { MeshDepthMaterial, RGBADepthPacking, InstancedMesh, MeshDistanceMaterial, Material } from 'three';
 
 function getMaxTextureSize(renderer) {
   return renderer.capabilities.maxTextureSize;
@@ -15,40 +15,39 @@ var ROW_PRELUDE = (
   uniform highp sampler2D uVatPlaybackTex;
   uniform float uVatTime;
 
-  // Where an instance is reading: the two rows of its band it sits between and
-  // the blend toward the second; and the pose-freeze fade's frozen row and
-  // weight, a weight of zero being "not fading".
-  struct VatRows {
+  // One band resolved: the two rows an instance sits between and the blend
+  // toward the second, plus the two facts those rows cannot be read back out
+  // of \u2014 whether the sampling wrapped past the band's last row into its first,
+  // and whether the repetitions have run out.
+  struct VatBand {
     int row0;
     int row1;
     float blend;
-    int fadeRow;
-    float fadeWeight;
+    bool wraps;
+    bool finished;
   };
 
-  VatRows vatRows( const in int vatInstance ) {
-    // The pack, fetched by this instance's *logical* index rather than read
-    // off an attribute indexed by the drawn slot (ADR-0016). Three texels of
-    // one row, in the order src/instance-playback.ts lays them out; the
-    // arithmetic below is untouched by where they came from, because the pack
-    // was already three vec4s.
-    //
-    // The index arrives as a parameter rather than being read here, because
-    // where it comes from is the carrier's business and not the decode's:
-    // gl_InstanceID on an InstancedMesh, getIndirectIndex( gl_DrawID ) on a
-    // BatchedMesh \u2014 see INSTANCE_ID in src/webgl.ts. It also has to be a
-    // parameter: getIndirectIndex is declared by batching_pars_vertex, which
-    // three expands *after* this prelude, so naming it up here would not
-    // compile.
-    //
-    // Fetched inside the function, so each injection point stays
-    // self-contained (ADR-0006) \u2014 which costs a second set of fetches in the
-    // normal decode. Every vertex of an instance reads the same three texels,
-    // so the texture cache absorbs them; the 5% demo bench is what says so.
-    vec4 vatClip     = texelFetch( uVatPlaybackTex, ivec2( ${PACK_TEXELS.clip}, vatInstance ), 0 );
-    vec4 vatPlayback = texelFetch( uVatPlaybackTex, ivec2( ${PACK_TEXELS.playback}, vatInstance ), 0 );
-    vec4 vatFade     = texelFetch( uVatPlaybackTex, ivec2( ${PACK_TEXELS.fade}, vatInstance ), 0 );
+  // Where an instance is reading: the band it is playing, and how much of the
+  // band it is leaving still shows \u2014 a weight of zero being "not
+  // transitioning".
+  //
+  // The outgoing band is *not* a field here. Each sampler resolves it for
+  // itself, because what it costs to resolve is not the same on the two
+  // encodings and #72 measured the difference: see vatOutgoingBand below.
+  struct VatRows {
+    VatBand live;
+    float weight;
+  };
 
+  // resolveVATFrame for one (clip texel, playback texel) pair, branch for
+  // branch: not started, finished, ping-pong, repeat \u2014 the resolver's own
+  // order, each case falling out into the shared phase-to-row arithmetic below
+  // rather than returning early, so all of them land on the same two rows.
+  //
+  // A function of the pair rather than of the instance, because the pair is
+  // what there are two of: a crossfading instance resolves its outgoing band
+  // by calling this a second time, not by transcribing it a second time.
+  VatBand vatBand( const in vec4 vatClip, const in vec4 vatPlayback ) {
     float frames = vatClip.y;
     float last = frames - 1.0;
     float duration = frames / vatClip.z;
@@ -63,65 +62,149 @@ 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 );
+    band.row1 = int( vatClip.x + f1 );
+    band.blend = f - f0;
+    band.wraps = wraps;
+    band.finished = finished;
+    return band;
+  }
+
+  VatRows vatRows( const in int vatInstance ) {
+    // The pack, fetched by this instance's *logical* index rather than read
+    // off an attribute indexed by the drawn slot (ADR-0016). Three texels of
+    // one row, in the order src/instance-playback.ts lays them out; the
+    // arithmetic above is untouched by where they came from, because the pack
+    // was already three vec4s.
+    //
+    // The index arrives as a parameter rather than being read here, because
+    // where it comes from is the carrier's business and not the decode's:
+    // gl_InstanceID on an InstancedMesh, getIndirectIndex( gl_DrawID ) on a
+    // BatchedMesh \u2014 see INSTANCE_ID in src/webgl.ts. It also has to be a
+    // parameter: getIndirectIndex is declared by batching_pars_vertex, which
+    // three expands *after* this prelude, so naming it up here would not
+    // compile.
+    //
+    // Fetched inside the function, so each injection point stays
+    // self-contained (ADR-0006) \u2014 which costs a second set of fetches in the
+    // 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 #72's idle-crowd bench is what says so for all five.
+    //
+    // 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 );
 
     VatRows rows;
-    rows.row0 = int( vatClip.x + f0 );
-    rows.row1 = int( vatClip.x + f1 );
-    rows.blend = f - f0;
+    // The live band: the one clip this instance is playing, resolved from its
+    // own pair of texels.
+    rows.live = vatBand( vatClip, vatPlayback );
 
-    // The pose-freeze fade, transcribed from the same resolver: one frozen row
-    // of the clip this instance was playing when it changed, blended away over
-    // vatFade.w. Wall clock, not clip time \u2014 the incoming clip's speed does
-    // not stretch a fade. A duration of zero is what "not fading" is, and the
-    // pack never writes one without a band to go with it.
-    rows.fadeRow = 0;
-    rows.fadeWeight = 0.0;
-    if ( vatFade.w > 0.0 ) {
-      float weight = 1.0 - clamp( ( uVatTime - vatPlayback.x ) / vatFade.w, 0.0, 1.0 );
-      float fromRow = max( min( floor( vatFade.z * vatFade.y ), vatFade.y - 1.0 ), 0.0 );
-      rows.fadeRow = int( vatFade.x + fromRow );
-      rows.fadeWeight = weight;
+    // The crossfade's weight, transcribed from the resolver: wall clock, not
+    // clip time \u2014 the incoming clip's speed does not stretch a transition \u2014 and
+    // a duration of zero is what a cut is, which is what the pack writes when
+    // there is no band to blend away.
+    rows.weight = 0.0;
+    if ( vatCrossfade.x > 0.0 ) {
+      rows.weight = 1.0 - clamp( ( uVatTime - vatPlayback.x ) / vatCrossfade.x, 0.0, 1.0 );
     }
+
     return rows;
   }
+
+  // The band the instance is leaving: two more texels and a second call of the
+  // very same resolver, so the clip it is leaving keeps playing \u2014 keeping its
+  // own speed and its own end policy \u2014 rather than standing still (ADR-0025).
+  //
+  // While the weight is zero the pair selected *is* the live pair, so the two
+  // fetches land on texels this vertex has already read and the band resolves
+  // to the one it is playing. That is what lets a caller resolve it without a
+  // branch, and blending a pose into itself is what a weight of zero means.
+  //
+  // Selecting the live pair is also why this needs no counterpart to the TSL
+  // path's max-of-one on the outgoing frames and fps (src/tsl.ts): that path
+  // resolves a band from the zeroes "not transitioning" is written as, which is
+  // a 0/0 duration and a NaN row. The pair selected here is always real.
+  //
+  // Whether the instance is transitioning is the parameter, not the weight, so
+  // the caller is the one that says so \u2014 and the two encodings say it from
+  // different places (#72): the vertex sampler calls this unconditionally,
+  // because guarding two texel fetches cost an idle crowd 10%; the rig sampler
+  // calls it unconditionally too but guards what it *does* with the band, where
+  // what a guard skips is sixteen dependent fetches per vertex.
+  VatBand vatOutgoingBand( const in int vatInstance, const in bool transitioning ) {
+    int clipX     = transitioning ? ${PACK_TEXELS.outgoingClip} : ${PACK_TEXELS.clip};
+    int playbackX = transitioning ? ${PACK_TEXELS.outgoingPlayback} : ${PACK_TEXELS.playback};
+    vec4 vatOutClip     = texelFetch( uVatPlaybackTex, ivec2( clipX, vatInstance ), 0 );
+    vec4 vatOutPlayback = texelFetch( uVatPlaybackTex, ivec2( playbackX, vatInstance ), 0 );
+    return vatBand( vatOutClip, vatOutPlayback );
+  }
 `
 );
 var VERTEX_PRELUDE = (
   /* glsl */
   `
   uniform highp sampler2D uVatPosTex;
+
+  // 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;
+    return mix( s0, s1, band.blend );
+  }
+
   vec3 vatSample( const in sampler2D tex, const in int vatInstance ) {
     VatRows rows = vatRows( vatInstance );
-    vec3 s0 = texelFetch( tex, ivec2( gl_VertexID, rows.row0 ), 0 ).xyz;
-    vec3 s1 = texelFetch( tex, ivec2( gl_VertexID, rows.row1 ), 0 ).xyz;
-    vec3 sampled = mix( s0, s1, rows.blend );
-    // The frozen row, blended in by the weight the rows resolved.
-    float weight = rows.fadeWeight;
-    if ( weight > 0.0 ) {
-      vec3 frozen = texelFetch( tex, ivec2( gl_VertexID, rows.fadeRow ), 0 ).xyz;
-      sampled = mix( sampled, frozen, weight );
-    }
-    return sampled;
+    // The outgoing band \u2014 still playing, two rows of its own \u2014 mixed in by the
+    // weight the rows resolved, and mixed in *unconditionally*: at a weight of
+    // zero the band resolved is the live one, so this blends a pose into
+    // itself. The normal layer is renormalised by the caller after the mix, as
+    // it is for a single band.
+    //
+    // No branch, and that is measured rather than reasoned (#72): here the
+    // outgoing band is two more fetches of one layer, and guarding them cost an
+    // idle crowd 10% where paying them costs nothing measurable \u2014 0.283 ms
+    // against the 0.282 ms it cost before the crossfade existed. A branch is
+    // not free because it is not taken: the compiler still holds registers for
+    // the side it skips, and that is what an idle crowd was paying for.
+    VatBand outgoing = vatOutgoingBand( vatInstance, rows.weight > 0.0 );
+    return mix( vatBandSample( tex, rows.live ), vatBandSample( tex, outgoing ), rows.weight );
   }
 `
 );
@@ -129,6 +212,33 @@ var NORMAL_PRELUDE = (
   /* 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, ivec2( gl_VertexID, band.row0 ), 0 ).xy );
+    vec3 s1 = vatOctDecode( texelFetch( uVatNrmTex, ivec2( gl_VertexID, 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 = (
@@ -155,34 +265,58 @@ var RIG_PRELUDE = (
     );
   }
 
-  // One slot's matrix between the two rows the instance sits between \u2014 and
-  // through the fade, blended before it is composed.
-  mat4 vatSlot( const in int slot, const in VatRows rows ) {
-    int rotation = slot * ${RIG_TEXELS_PER_SLOT} + ${RIG_TEXELS.rotation};
-    int placement = slot * ${RIG_TEXELS_PER_SLOT} + ${RIG_TEXELS.placement};
-    vec4 q0 = texelFetch( uVatRigTex, ivec2( rotation, rows.row0 ), 0 );
-    vec4 ts0 = texelFetch( uVatRigTex, ivec2( placement, rows.row0 ), 0 );
-    vec4 q1 = texelFetch( uVatRigTex, ivec2( rotation, rows.row1 ), 0 );
-    vec4 ts1 = texelFetch( uVatRigTex, ivec2( placement, rows.row1 ), 0 );
+  // One slot of the posed rig, at one band: a rotation and a placement, each
+  // between the two rows that band sits between. The same function for the live
+  // band and the outgoing one, as vatBand is the same function for both pairs.
+  struct VatPose {
+    vec4 q;
+    vec4 ts;
+  };
+
+  VatPose vatSlotPose( const in int rotation, const in int placement, const in VatBand band ) {
+    vec4 q0 = texelFetch( uVatRigTex, ivec2( rotation, band.row0 ), 0 );
+    vec4 ts0 = texelFetch( uVatRigTex, ivec2( placement, band.row0 ), 0 );
+    vec4 q1 = texelFetch( uVatRigTex, ivec2( rotation, band.row1 ), 0 );
+    vec4 ts1 = texelFetch( uVatRigTex, ivec2( placement, band.row1 ), 0 );
     // The bake keeps consecutive rows on one hemisphere, but a looping clip
     // blends its band's last row into its first, and a bone that turned a full
     // circle over the clip arrives there on the far side: one dot product per
     // slot, or the blend passes through zero on the wrap frame.
     if ( dot( q0, q1 ) < 0.0 ) q1 = -q1;
+    VatPose pose;
     // A normalised lerp, not a slerp: at a bake's frame step the angular error
     // against a true slerp is far below anything visible. It is still a
     // *rotation* at every blend, which is what a componentwise matrix lerp is
     // not \u2014 that one shortens a limb as it turns (ADR-0018).
-    vec4 q = normalize( mix( q0, q1, rows.blend ) );
-    vec4 ts = mix( ts0, ts1, rows.blend );
-    if ( rows.fadeWeight > 0.0 ) {
-      vec4 qf = texelFetch( uVatRigTex, ivec2( rotation, rows.fadeRow ), 0 );
-      vec4 tsf = texelFetch( uVatRigTex, ivec2( placement, rows.fadeRow ), 0 );
-      // The frozen row is any row of the bake, not this row's neighbour, so
+    pose.q = normalize( mix( q0, q1, band.blend ) );
+    pose.ts = mix( ts0, ts1, band.blend );
+    return pose;
+  }
+
+  // One slot's matrix: its pose in the band the instance is playing and, while
+  // it is transitioning, its pose in the band it is leaving \u2014 blended per slot
+  // before the matrix is composed, so the crowd skins from one rig rather than
+  // from the average of two matrices.
+  //
+  // The guard stays here, where the vertex sampler dropped its own. What it
+  // skips is four dependent fetches of the rig texture per slot, sixteen per
+  // vertex, against the two of one layer the vertex encoding skips \u2014 and #72
+  // measured it worth keeping: this encoding did not get slower when the
+  // crossfade landed, and the vertex encoding did.
+  mat4 vatSlot( const in int slot, const in VatRows rows, const in VatBand outgoing ) {
+    int rotation = slot * ${RIG_TEXELS_PER_SLOT} + ${RIG_TEXELS.rotation};
+    int placement = slot * ${RIG_TEXELS_PER_SLOT} + ${RIG_TEXELS.placement};
+    VatPose pose = vatSlotPose( rotation, placement, rows.live );
+    vec4 q = pose.q;
+    vec4 ts = pose.ts;
+    if ( rows.weight > 0.0 ) {
+      VatPose leaving = vatSlotPose( rotation, placement, outgoing );
+      vec4 qo = leaving.q;
+      // The outgoing band is any row of the bake, not this row's neighbour, so
       // the same check.
-      if ( dot( q, qf ) < 0.0 ) qf = -qf;
-      q = normalize( mix( q, qf, rows.fadeWeight ) );
-      ts = mix( ts, tsf, rows.fadeWeight );
+      if ( dot( q, qo ) < 0.0 ) qo = -qo;
+      q = normalize( mix( q, qo, rows.weight ) );
+      ts = mix( ts, leaving.ts, rows.weight );
     }
     return vatCompose( q, ts );
   }
@@ -190,13 +324,20 @@ var RIG_PRELUDE = (
   // Linear blend skinning: the weighted sum of slot matrices, which is the
   // blend the bake did on the CPU for the bounds and three's own
   // skinning_vertex does on the GPU. A zero weight skips its four fetches.
+  //
+  // The band being left is resolved once for the vertex rather than once per
+  // slot, and unconditionally \u2014 two pack texels this encoding's old guard
+  // skipped, against the sixteen rig fetches per vertex the guard inside
+  // vatSlot still skips. At a weight of zero those two land on texels already
+  // read, and every slot below skips the pose.
   mat4 vatSkinMatrix( const in int vatInstance ) {
     VatRows rows = vatRows( vatInstance );
+    VatBand outgoing = vatOutgoingBand( vatInstance, rows.weight > 0.0 );
     mat4 skin = mat4( 0.0 );
     for ( int i = 0; i < 4; i ++ ) {
       float w = skinWeight[ i ];
       if ( w == 0.0 ) continue;
-      skin += w * vatSlot( int( skinIndex[ i ] ), rows );
+      skin += w * vatSlot( int( skinIndex[ i ] ), rows, outgoing );
     }
     return skin;
   }
@@ -215,7 +356,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
@@ -245,13 +386,16 @@ function vertexDecode({ positionTexture, normalTexture }, id) {
       uniforms.uVatPosTex = { value: positionTexture };
       if (normalTexture) uniforms.uVatNrmTex = { value: normalTexture };
     },
-    inject(vertexShader) {
-      const positioned = vertexShader.replace("#include <begin_vertex>", vertexPosition(id));
-      return normalTexture ? positioned.replace("#include <beginnormal_vertex>", vertexNormal(id)) : positioned;
-    },
+    position: vertexPosition(id),
+    // No normal texture, no normal decode, and no uniform bound for one: the
+    // material either does not read a normal or derives it from the deformed
+    // position itself (`flatShading`), so three's own `beginnormal_vertex` is
+    // left exactly where it is.
+    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"}`,
+    instanceIndex: INSTANCE_ID[id]
   };
 }
 function rigDecode({ rigTexture }, id) {
@@ -260,12 +404,44 @@ function rigDecode({ rigTexture }, id) {
     bind(uniforms) {
       uniforms.uVatRigTex = { value: rigTexture };
     },
-    inject(vertexShader) {
-      return vertexShader.replace("#include <begin_vertex>", rigPosition(id)).replace("#include <beginnormal_vertex>", rigNormal(id));
-    },
-    key: `three-vat:rig:${id}`
+    position: rigPosition(id),
+    normal: rigNormal(id),
+    key: `three-vat:rig:${id}`,
+    instanceIndex: INSTANCE_ID[id]
   };
 }
+function patchOptionsOf(fifth) {
+  if (!fifth) return {};
+  return fifth.isObject3D ? { carrier: fifth } : fifth;
+}
+function assertHook(hook) {
+  if (!hook.key.trim()) {
+    throw new Error(
+      "three-vat: a post-decode hook needs a non-empty `key`. It is folded into the library\u2019s own program cache key, and two hooks that fold in nothing share a compiled program \u2014 so one crowd renders the other\u2019s GLSL."
+    );
+  }
+  if (!hook.position && !hook.normal) {
+    throw new Error(
+      "three-vat: a post-decode hook with neither `position` nor `normal` injects nothing. Give it the chunk you meant \u2014 `position` deforms the posed vertex, `normal` repairs the normal that was taken before it, and a deformation wants both."
+    );
+  }
+}
+var hookChunk = (chunk, instanceIndex) => chunk ? (
+  /* glsl */
+  `
+  {
+    int vatInstanceIndex = ${instanceIndex};
+${chunk}
+  }
+`
+) : "";
+function injectVAT(vertexShader, decode, hook) {
+  const position = decode.position + hookChunk(hook?.position, decode.instanceIndex);
+  const normal = (decode.normal ?? "#include <beginnormal_vertex>") + hookChunk(hook?.normal, decode.instanceIndex);
+  return vertexShader.replace("#include <begin_vertex>", () => position).replace("#include <beginnormal_vertex>", () => normal);
+}
+var VAT_PATCHES = /* @__PURE__ */ new WeakSet();
+var ours = (onBeforeCompile) => onBeforeCompile === Material.prototype.onBeforeCompile || VAT_PATCHES.has(onBeforeCompile);
 function decodeFor(vat, id) {
   switch (vat.encoding) {
     case "delta":
@@ -280,18 +456,29 @@ function decodeFor(vat, id) {
     }
   }
 }
-function patchVATMaterial(material, vat, uniforms, playback, carrier) {
+function patchVATMaterial(material, vat, uniforms, playback, options) {
+  const { carrier, hook } = patchOptionsOf(options);
   assertBakedNormal(vat, material);
   if (carrier) assertVATCarrier(carrier, vat);
+  if (hook) assertHook(hook);
   const id = isBatchedCarrier(carrier) ? "batch" : "instance";
   const decode = decodeFor(vat, id);
-  material.onBeforeCompile = (shader) => {
+  const previous = ours(material.onBeforeCompile) ? null : material.onBeforeCompile.bind(material);
+  const patch = (shader, renderer) => {
+    previous?.(shader, renderer);
+    if (hook?.uniforms) Object.assign(shader.uniforms, hook.uniforms);
     shader.uniforms.uVatPlaybackTex = { value: playback.texture };
     shader.uniforms.uVatTime = uniforms.uVatTime;
     decode.bind(shader.uniforms);
-    shader.vertexShader = ROW_PRELUDE + decode.prelude + decode.inject(shader.vertexShader);
+    shader.vertexShader = ROW_PRELUDE + decode.prelude + // Ahead of three's shader, where a declaration is safe from a dead block.
+    (hook?.prelude ? `
+${hook.prelude}
+` : "") + injectVAT(shader.vertexShader, decode, hook);
   };
-  material.customProgramCacheKey = () => decode.key;
+  material.onBeforeCompile = patch;
+  VAT_PATCHES.add(patch);
+  const key = hook ? `${decode.key}+${hook.key}` : decode.key;
+  material.customProgramCacheKey = () => key;
   guardCarrierMismatch(material, id);
   return material;
 }
@@ -315,18 +502,19 @@ var CARRIER_NAME = {
   instance: "an InstancedMesh",
   batch: "a BatchedMesh"
 };
-function createVATDepthMaterial(vat, uniforms, playback, carrier) {
+function createVATDepthMaterial(vat, uniforms, playback, options) {
   const depth = new MeshDepthMaterial({ depthPacking: RGBADepthPacking });
-  patchVATMaterial(depth, vat, uniforms, playback, carrier);
+  patchVATMaterial(depth, vat, uniforms, playback, options);
   return depth;
 }
 function createVATMesh(vat, instances, options = {}) {
   const uniforms = options.time ? { uVatTime: options.time } : createVATUniforms();
-  const playback = createVATPlaybackTexture(instances);
-  const materials = vat.materials.map((source) => patchVATMaterial(source.clone(), vat, uniforms, playback));
+  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);
-  mesh.customDepthMaterial = createVATDepthMaterial(vat, uniforms, playback);
-  mesh.customDistanceMaterial = patchVATMaterial(new MeshDistanceMaterial(), vat, uniforms, playback);
+  mesh.customDepthMaterial = createVATDepthMaterial(vat, uniforms, playback, patch);
+  mesh.customDistanceMaterial = patchVATMaterial(new MeshDistanceMaterial(), vat, uniforms, playback, patch);
   return { mesh, time: uniforms.uVatTime, playback };
 }
 

package/package.json

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