three-cad-viewer 4.1.2 → 4.3.0

package/src/rendering/texture-cache.ts

@@ -0,0 +1,319 @@
+import * as THREE from "three";
+import { gpuTracker } from "../utils/gpu-tracker.js";
+import { logger } from "../utils/logger.js";
+
+// =============================================================================
+// Constants
+// =============================================================================
+
+/**
+ * Texture fields that carry sRGB color data.
+ *
+ * When a texture is used for one of these roles, its `colorSpace` must be set
+ * to `SRGBColorSpace` so Three.js applies the sRGB-to-linear decode on
+ * sampling. All other texture roles (normal, metallic-roughness, occlusion,
+ * thickness, transmission, roughness maps) remain `LinearSRGBColorSpace`.
+ */
+const SRGB_TEXTURE_ROLES = new Set([
+  "baseColorTexture",
+  "emissiveTexture",
+  "sheenColorTexture",
+  "specularColorTexture",
+]);
+
+/**
+ * Three.js MeshPhysicalMaterial map property names that carry sRGB color data.
+ *
+ * Used by threejs-materials integration where texture params use Three.js property
+ * names directly (e.g., "map", "emissiveMap") instead of MaterialAppearance
+ * role names (e.g., "baseColorTexture", "emissiveTexture").
+ */
+const THREEJS_SRGB_MAPS = new Set([
+  "map",
+  "emissiveMap",
+  "sheenColorMap",
+  "specularColorMap",
+]);
+
+// =============================================================================
+// TextureCache
+// =============================================================================
+
+/**
+ * Manages loading, caching, and lifecycle of all Studio mode textures.
+ *
+ * The TextureCache is the **sole owner** of all THREE.Texture objects used by
+ * Studio mode. Materials reference textures but never dispose them directly.
+ * Only TextureCache.dispose() / disposeFull() disposes GPU texture resources.
+ *
+ * Resolution order for texture reference strings:
+ * 1. `data:` prefix -- treat as data URI, load directly
+ * 2. Otherwise -- treat as URL, resolve relative to HTML page
+ *
+ * Features:
+ * - In-flight promise deduplication (no duplicate loads for the same key)
+ * - Correct colorSpace assignment per texture semantic role
+ * - GPU resource tracking via gpuTracker
+ */
+class TextureCache {
+  /** Textures cache (disposed on clear/dispose, rebuilt per shape data) */
+  private _cache: Map<string, THREE.Texture> = new Map();
+
+  /** In-flight load promises keyed by cache key */
+  private _inflight: Map<string, Promise<THREE.Texture>> = new Map();
+
+  /** THREE.TextureLoader instance (created lazily) */
+  private _textureLoader: THREE.TextureLoader | null = null;
+
+  /** Whether this cache has been fully disposed */
+  private _disposed = false;
+
+  // ---------------------------------------------------------------------------
+  // Public API
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Resolve a texture reference string and return a cached or newly loaded
+   * THREE.Texture with the correct colorSpace set.
+   *
+   * @param ref - Texture reference string (table key, data URI, or URL)
+   * @param textureRole - The texture role name (MaterialAppearance field name or proxy role)
+   *   (e.g. "baseColorTexture", "normalTexture"). Used to determine colorSpace.
+   * @returns The resolved THREE.Texture, or null if the reference is invalid
+   *   or loading fails
+   */
+  async get(
+    ref: string,
+    textureRole: string,
+  ): Promise<THREE.Texture | null> {
+    if (this._disposed) {
+      logger.warn("TextureCache.get() called after dispose");
+      return null;
+    }
+
+    if (!ref) {
+      return null;
+    }
+
+    // Determine the target color space based on the texture role
+    const colorSpace = SRGB_TEXTURE_ROLES.has(textureRole)
+      ? THREE.SRGBColorSpace
+      : THREE.LinearSRGBColorSpace;
+
+    // 1. data: prefix (data URI)
+    if (ref.startsWith("data:")) {
+      return this._getFromDataUri(ref, colorSpace);
+    }
+
+    // 2. URL (relative to HTML page)
+    return this._getFromUrl(ref, colorSpace);
+  }
+
+  /**
+   * Dispose textures (called on viewer.clear() when shape data is replaced).
+   *
+   * Disposes all textures in the cache and clears in-flight promises.
+   */
+  dispose(): void {
+    for (const [key, texture] of this._cache) {
+      gpuTracker.untrack("texture", texture);
+      texture.dispose();
+      logger.debug(`Disposed texture: ${key}`);
+    }
+    this._cache.clear();
+
+    // Clear in-flight promises (they may resolve but won't be used)
+    this._inflight.clear();
+  }
+
+  /**
+   * Dispose all textures.
+   *
+   * Called on viewer.dispose() when the viewer is fully torn down.
+   * After this call, the TextureCache cannot be used again.
+   */
+  disposeFull(): void {
+    this._disposed = true;
+    this.dispose();
+    this._textureLoader = null;
+    logger.debug("TextureCache fully disposed");
+  }
+
+  // ---------------------------------------------------------------------------
+  // Private: Data URI loading
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Load a texture from a data URI string.
+   */
+  private async _getFromDataUri(
+    dataUri: string,
+    colorSpace: THREE.ColorSpace,
+  ): Promise<THREE.Texture | null> {
+    // Use the data URI itself as the cache key
+    const cacheKey = dataUri;
+
+    const cached = this._cache.get(cacheKey);
+    if (cached) {
+      cached.colorSpace = colorSpace;
+      return cached;
+    }
+
+    const inflight = this._inflight.get(cacheKey);
+    if (inflight) {
+      const texture = await inflight;
+      texture.colorSpace = colorSpace;
+      return texture;
+    }
+
+    return this._loadAndCache(cacheKey, dataUri, colorSpace);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Private: URL loading
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Load a texture from a URL (resolved relative to the HTML page).
+   */
+  private async _getFromUrl(
+    url: string,
+    colorSpace: THREE.ColorSpace,
+  ): Promise<THREE.Texture | null> {
+    const cached = this._cache.get(url);
+    if (cached) {
+      cached.colorSpace = colorSpace;
+      return cached;
+    }
+
+    const inflight = this._inflight.get(url);
+    if (inflight) {
+      const texture = await inflight;
+      texture.colorSpace = colorSpace;
+      return texture;
+    }
+
+    return this._loadAndCache(url, url, colorSpace);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Private: Core loading
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Load a texture from a source (URL or data URI), cache it, and return it.
+   *
+   * Deduplicates in-flight loads for the same cache key.
+   *
+   * @param cacheKey - Key for the user cache
+   * @param source - URL or data URI to load from
+   * @param colorSpace - Color space to assign to the loaded texture
+   * @returns The loaded texture, or null on failure
+   */
+  private async _loadAndCache(
+    cacheKey: string,
+    source: string,
+    colorSpace: THREE.ColorSpace,
+  ): Promise<THREE.Texture | null> {
+    const promise = this._doLoad(source, colorSpace);
+    this._inflight.set(cacheKey, promise);
+
+    try {
+      const texture = await promise;
+
+      // Check if disposed while loading:
+      // - disposeFull() sets _disposed
+      // - dispose() clears _inflight (so our entry is gone)
+      if (this._disposed || !this._inflight.has(cacheKey)) {
+        texture.dispose();
+        return null;
+      }
+
+      // Cache and track
+      this._cache.set(cacheKey, texture);
+      const label = cacheKey.startsWith("data:")
+        ? `Texture (data URI, ${cacheKey.length} chars)`
+        : `Texture: ${cacheKey}`;
+      gpuTracker.trackTexture(texture, label);
+      logger.debug(`Loaded and cached texture: ${label}`);
+
+      return texture;
+    } catch (error) {
+      if (this._disposed) return null;
+
+      const displayKey = cacheKey.startsWith("data:")
+        ? `data URI (${cacheKey.length} chars)`
+        : cacheKey;
+      logger.warn(
+        `Failed to load texture "${displayKey}":`,
+        error instanceof Error ? error.message : error,
+      );
+      return null;
+    } finally {
+      this._inflight.delete(cacheKey);
+    }
+  }
+
+  /**
+   * Perform the actual texture load via THREE.TextureLoader.
+   *
+   * THREE.TextureLoader handles both URLs and data URIs.
+   */
+  private _doLoad(
+    source: string,
+    colorSpace: THREE.ColorSpace,
+  ): Promise<THREE.Texture> {
+    const loader = this._ensureTextureLoader();
+
+    return new Promise<THREE.Texture>((resolve, reject) => {
+      loader.load(
+        source,
+        (texture) => {
+          texture.colorSpace = colorSpace;
+          texture.wrapS = THREE.RepeatWrapping;
+          texture.wrapT = THREE.RepeatWrapping;
+          resolve(texture);
+        },
+        undefined, // onProgress (not used)
+        (error) => {
+          reject(
+            error instanceof Error
+              ? error
+              : new Error(`Texture load failed: ${source.substring(0, 100)}`),
+          );
+        },
+      );
+    });
+  }
+
+  // ---------------------------------------------------------------------------
+  // Private: Utilities
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Get or create the THREE.TextureLoader (lazy initialization).
+   */
+  private _ensureTextureLoader(): THREE.TextureLoader {
+    if (!this._textureLoader) {
+      this._textureLoader = new THREE.TextureLoader();
+      logger.debug("Created TextureLoader");
+    }
+    return this._textureLoader;
+  }
+
+}
+
+/**
+ * Get the correct color space for a Three.js material map property name.
+ *
+ * sRGB maps (color data): map, emissiveMap, sheenColorMap, specularColorMap
+ * Linear maps (non-color data): everything else (normalMap, roughnessMap, etc.)
+ *
+ * @param mapName - Three.js material property name (e.g., "map", "normalMap")
+ * @returns THREE.SRGBColorSpace or THREE.LinearSRGBColorSpace
+ */
+function getColorSpaceForMap(mapName: string): THREE.ColorSpace {
+  return THREEJS_SRGB_MAPS.has(mapName) ? THREE.SRGBColorSpace : THREE.LinearSRGBColorSpace;
+}
+
+export { TextureCache, SRGB_TEXTURE_ROLES, getColorSpaceForMap };

package/src/rendering/triplanar.ts

@@ -0,0 +1,329 @@
+/**
+ * Triplanar texture mapping for MeshPhysicalMaterial.
+ *
+ * Replaces standard UV-based texture sampling with model-space triplanar
+ * projection via `material.onBeforeCompile`. Eliminates seams on curved
+ * surfaces (cylinders, cones, etc.) and maintains uniform texture scale
+ * regardless of object proportions.
+ *
+ * All coordinates are in **model space** to match the geometry's bounding box.
+ * `transformed` (model-space position) and `objectNormal` (model-space normal)
+ * are used — NOT the view-space `transformedNormal`.
+ *
+ * NOTE: `onBeforeCompile` receives shaders BEFORE `#include` resolution.
+ * Therefore we replace `#include <chunk_name>` directives with inline GLSL
+ * that uses triplanar sampling, rather than replacing expanded texture2D calls.
+ *
+ * Handles: map, normalMap, roughnessMap, metalnessMap, emissiveMap, aoMap,
+ *          clearcoatNormalMap, alphaMap.
+ */
+
+import * as THREE from "three";
+
+// ---------------------------------------------------------------------------
+// GLSL: Varyings (shared between vertex & fragment)
+// ---------------------------------------------------------------------------
+
+const TRIPLANAR_VARYINGS = /* glsl */ `
+varying vec3 vTriplanarPos;
+varying vec3 vTriplanarNormal;
+`;
+
+// ---------------------------------------------------------------------------
+// GLSL: Fragment header (uniforms + helper functions)
+// ---------------------------------------------------------------------------
+
+const TRIPLANAR_FRAGMENT_HEADER = /* glsl */ `
+varying vec3 vTriplanarPos;
+varying vec3 vTriplanarNormal;
+uniform vec3 triplanarOffset;
+uniform float triplanarScale;
+uniform vec2 triplanarRepeat;
+
+// normalMatrix is only declared in the fragment shader for object-space
+// normal maps. We need it for triplanar tangent-space normal mapping too.
+#ifndef USE_NORMALMAP_OBJECTSPACE
+uniform mat3 normalMatrix;
+#endif
+
+// --- Global triplanar state (computed once, reused by all samples) ---
+vec2 tri_uvX, tri_uvY, tri_uvZ;
+vec3 tri_blend;
+
+// Initialize global triplanar UVs and blend weights from varyings.
+// Must be called before any texture sampling.
+void initTriplanarUVs() {
+  tri_blend = abs(vTriplanarNormal);
+  tri_blend = pow(tri_blend, vec3(3.0));
+  tri_blend /= (tri_blend.x + tri_blend.y + tri_blend.z);
+  vec3 p = (vTriplanarPos - triplanarOffset) * triplanarScale;
+  vec2 r = triplanarRepeat;
+  tri_uvX = p.yz * r;
+  tri_uvY = p.xz * r;
+  tri_uvZ = p.xy * r;
+}
+
+// Sample a texture using the global triplanar UVs and blend weights.
+vec4 triplanarSample(sampler2D tex) {
+  return texture2D(tex, tri_uvX) * tri_blend.x
+       + texture2D(tex, tri_uvY) * tri_blend.y
+       + texture2D(tex, tri_uvZ) * tri_blend.z;
+}
+
+// Surface-gradient triplanar normal mapping.
+// Instead of constructing full 3D normals per axis (which creates faceted
+// shading at axis boundaries), we extract the tangent-space perturbation (xy)
+// from each axis sample, project it into model space as a gradient, blend
+// the gradients, and add to the geometric normal. Gradients blend smoothly.
+// Ref: Morten Mikkelsen, "Surface Gradient Based Bump Mapping Framework"
+//
+// normalScale is declared in normalmap_pars_fragment (after this header),
+// so we accept it as a parameter to avoid forward-reference errors.
+vec3 triplanarNormal(sampler2D normalTex, vec2 nScale) {
+  vec3 N = vTriplanarNormal;
+
+  // Sample tangent-space normals for each projection axis
+  vec3 tnX = texture2D(normalTex, tri_uvX).xyz * 2.0 - 1.0;
+  vec3 tnY = texture2D(normalTex, tri_uvY).xyz * 2.0 - 1.0;
+  vec3 tnZ = texture2D(normalTex, tri_uvZ).xyz * 2.0 - 1.0;
+
+  // Apply normal scale to perturbation components
+  tnX.xy *= nScale;
+  tnY.xy *= nScale;
+  tnZ.xy *= nScale;
+
+  // Project each tangent-space perturbation (xy) into model space.
+  // X proj: UV=(y,z) -> tangent=(0,1,0), bitangent=(0,0,1) -> grad=(0, tx, ty)
+  // Y proj: UV=(x,z) -> tangent=(1,0,0), bitangent=(0,0,1) -> grad=(tx, 0, ty)
+  // Z proj: UV=(x,y) -> tangent=(1,0,0), bitangent=(0,1,0) -> grad=(tx, ty, 0)
+  vec3 surfGrad =
+      vec3(0.0, tnX.x, tnX.y) * tri_blend.x +
+      vec3(tnY.x, 0.0, tnY.y) * tri_blend.y +
+      vec3(tnZ.x, tnZ.y, 0.0) * tri_blend.z;
+
+  return normalize(N + surfGrad);
+}
+`;
+
+// ---------------------------------------------------------------------------
+// GLSL: UV initialization injection
+// ---------------------------------------------------------------------------
+
+/**
+ * Injected after #include <logdepthbuf_fragment>.
+ * This is the earliest reliable point in the fragment shader before any
+ * texture sampling. Initializes global triplanar UVs.
+ */
+const UV_INIT = /* glsl */ `
+#include <logdepthbuf_fragment>
+initTriplanarUVs();
+`;
+
+// ---------------------------------------------------------------------------
+// GLSL: Replacement chunks (inline GLSL replacing #include directives)
+// ---------------------------------------------------------------------------
+
+/** Replaces #include <map_fragment> */
+const MAP_FRAGMENT = /* glsl */ `
+#ifdef USE_MAP
+  vec4 sampledDiffuseColor = triplanarSample( map );
+  #ifdef DECODE_VIDEO_TEXTURE
+    sampledDiffuseColor = sRGBTransferEOTF( sampledDiffuseColor );
+  #endif
+  diffuseColor *= sampledDiffuseColor;
+#endif
+`;
+
+/** Replaces #include <roughnessmap_fragment> */
+const ROUGHNESSMAP_FRAGMENT = /* glsl */ `
+float roughnessFactor = roughness;
+#ifdef USE_ROUGHNESSMAP
+  vec4 texelRoughness = triplanarSample( roughnessMap );
+  roughnessFactor *= texelRoughness.g;
+#endif
+`;
+
+/** Replaces #include <metalnessmap_fragment> */
+const METALNESSMAP_FRAGMENT = /* glsl */ `
+float metalnessFactor = metalness;
+#ifdef USE_METALNESSMAP
+  vec4 texelMetalness = triplanarSample( metalnessMap );
+  metalnessFactor *= texelMetalness.b;
+#endif
+`;
+
+/** Replaces #include <emissivemap_fragment> */
+const EMISSIVEMAP_FRAGMENT = /* glsl */ `
+#ifdef USE_EMISSIVEMAP
+  vec4 emissiveColor = triplanarSample( emissiveMap );
+  #ifdef DECODE_VIDEO_TEXTURE_EMISSIVE
+    emissiveColor = sRGBTransferEOTF( emissiveColor );
+  #endif
+  totalEmissiveRadiance *= emissiveColor.rgb;
+#endif
+`;
+
+/** Replaces #include <aomap_fragment> */
+const AOMAP_FRAGMENT = /* glsl */ `
+#ifdef USE_AOMAP
+  float ambientOcclusion = ( triplanarSample( aoMap ).r - 1.0 ) * aoMapIntensity + 1.0;
+  reflectedLight.indirectDiffuse *= ambientOcclusion;
+  #if defined( USE_CLEARCOAT )
+    clearcoatSpecularIndirect *= ambientOcclusion;
+  #endif
+  #if defined( USE_SHEEN )
+    sheenSpecularIndirect *= ambientOcclusion;
+  #endif
+  #if defined( USE_ENVMAP ) && defined( STANDARD )
+    float dotNV = saturate( dot( geometryNormal, geometryViewDir ) );
+    reflectedLight.indirectSpecular *= computeSpecularOcclusion( dotNV, ambientOcclusion, material.roughness );
+  #endif
+#endif
+`;
+
+/**
+ * Replaces #include <normal_fragment_maps>.
+ * Object-space and bumpmap paths kept as-is.
+ * Tangent-space path: triplanar normal mapping samples the normal map 3x
+ * (one per projection axis), swizzles each to model space, blends, and
+ * transforms to view space via normalMatrix.
+ */
+const NORMAL_FRAGMENT_MAPS = /* glsl */ `
+#ifdef USE_NORMALMAP_OBJECTSPACE
+  normal = texture2D( normalMap, vNormalMapUv ).xyz * 2.0 - 1.0;
+  #ifdef FLIP_SIDED
+    normal = - normal;
+  #endif
+  #ifdef DOUBLE_SIDED
+    normal = normal * faceDirection;
+  #endif
+  normal = normalize( normalMatrix * normal );
+
+#elif defined( USE_NORMALMAP_TANGENTSPACE )
+  // Triplanar normal mapping: sample normal map 3x (one per projection axis),
+  // swizzle each to model space, blend, and transform to view space.
+  normal = normalize(normalMatrix * triplanarNormal(normalMap, normalScale));
+
+#elif defined( USE_BUMPMAP )
+  normal = perturbNormalArb( - vViewPosition, normal, dHdxy_fwd(), faceDirection );
+
+#endif
+`;
+
+/**
+ * Replaces #include <clearcoat_normal_fragment_maps>.
+ * Triplanar clearcoat normal mapping using surface gradient blending.
+ */
+const CLEARCOAT_NORMAL_FRAGMENT_MAPS = /* glsl */ `
+#ifdef USE_CLEARCOAT_NORMALMAP
+  // Reuse triplanarNormal with clearcoat normal map and scale
+  vec3 clearcoatModelNormal = triplanarNormal(clearcoatNormalMap, clearcoatNormalScale);
+  clearcoatNormal = normalize(normalMatrix * clearcoatModelNormal);
+#endif
+`;
+
+/** Replaces #include <alphamap_fragment> */
+const ALPHAMAP_FRAGMENT = /* glsl */ `
+#ifdef USE_ALPHAMAP
+  diffuseColor.a *= triplanarSample( alphaMap ).g;
+#endif
+`;
+
+// ---------------------------------------------------------------------------
+// Chunk replacement table
+// ---------------------------------------------------------------------------
+
+/** Fragment shader chunk replacements */
+const FRAGMENT_CHUNK_REPLACEMENTS: [string, string][] = [
+  ["#include <logdepthbuf_fragment>", UV_INIT],
+  ["#include <map_fragment>", MAP_FRAGMENT],
+  ["#include <roughnessmap_fragment>", ROUGHNESSMAP_FRAGMENT],
+  ["#include <metalnessmap_fragment>", METALNESSMAP_FRAGMENT],
+  ["#include <emissivemap_fragment>", EMISSIVEMAP_FRAGMENT],
+  ["#include <aomap_fragment>", AOMAP_FRAGMENT],
+  ["#include <normal_fragment_maps>", NORMAL_FRAGMENT_MAPS],
+  ["#include <clearcoat_normal_fragment_maps>", CLEARCOAT_NORMAL_FRAGMENT_MAPS],
+  ["#include <alphamap_fragment>", ALPHAMAP_FRAGMENT],
+];
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Apply triplanar texture mapping to a MeshPhysicalMaterial.
+ *
+ * Modifies the material's shader via `onBeforeCompile` so that all texture
+ * lookups use model-space triplanar projection instead of UV coordinates.
+ * The material should be a **clone** (not shared) because `onBeforeCompile`
+ * and `customProgramCacheKey` are set on it.
+ *
+ * Bounding box of the geometry determines coordinate normalization: the
+ * texture tiles once across the largest dimension with uniform scale,
+ * preserving aspect ratio. `textureRepeat` on the material's textures
+ * (if set) is respected via the triplanarRepeat uniform.
+ *
+ * @param material - Material clone to modify
+ * @param geometry - Geometry for bounding box computation
+ */
+export function applyTriplanarMapping(
+  material: THREE.MeshPhysicalMaterial,
+  geometry: THREE.BufferGeometry,
+): void {
+  // Compute bounding box for coordinate normalization (model space)
+  geometry.computeBoundingBox();
+  const bb = geometry.boundingBox!;
+  const size = new THREE.Vector3();
+  bb.getSize(size);
+  const maxDim = Math.max(size.x, size.y, size.z, 1e-6);
+
+  // Uniform values (captured by closure, per-object)
+  const offset = bb.min.clone();
+  const scale = 1.0 / maxDim;
+
+  // Read texture repeat from the material's map (all textures share same repeat)
+  const repeat = material.map?.repeat?.clone() ?? new THREE.Vector2(1, 1);
+
+  material.onBeforeCompile = (shader) => {
+    // Custom uniforms
+    shader.uniforms.triplanarOffset = { value: offset };
+    shader.uniforms.triplanarScale = { value: scale };
+    shader.uniforms.triplanarRepeat = { value: repeat };
+
+    // --- Vertex shader ---
+    // Declare varyings
+    shader.vertexShader = shader.vertexShader.replace(
+      "#include <common>",
+      `#include <common>\n${TRIPLANAR_VARYINGS}`,
+    );
+
+    // Pass model-space position and normal to fragment shader.
+    // `transformed` = model-space position (after morphing, before view transform)
+    // `objectNormal` = model-space normal (before normalMatrix)
+    // Both match the geometry's bounding box coordinate space.
+    shader.vertexShader = shader.vertexShader.replace(
+      "#include <worldpos_vertex>",
+      `#include <worldpos_vertex>
+      vTriplanarPos = transformed;
+      vTriplanarNormal = normalize(objectNormal);`,
+    );
+
+    // --- Fragment shader ---
+    // Inject varyings, uniforms, and the triplanarSample helper
+    shader.fragmentShader = shader.fragmentShader.replace(
+      "#include <common>",
+      `#include <common>\n${TRIPLANAR_FRAGMENT_HEADER}`,
+    );
+
+    // Replace texture-sampling #include chunks with triplanar versions
+    for (const [from, to] of FRAGMENT_CHUNK_REPLACEMENTS) {
+      shader.fragmentShader = shader.fragmentShader.replace(from, to);
+    }
+  };
+
+  // All triplanar materials share the same compiled WebGL program
+  // (uniform values differ per instance). Appended to Three.js's standard
+  // program cache key, so materials with different maps/flags still get
+  // separate programs.
+  material.customProgramCacheKey = () => "triplanar";
+}

package/src/scene/animation.ts

@@ -30,7 +30,7 @@ class Animation {
   mixer: THREE.AnimationMixer | null;
   clip: THREE.AnimationClip | null;
   clipAction: THREE.AnimationAction | null;
-  clock: THREE.Clock;
+  clock: THREE.Timer;
   duration: number | null;
   speed: number | null;
   repeat: boolean | null;
@@ -47,7 +47,7 @@ class Animation {
     this.mixer = null;
     this.clip = null;
     this.clipAction = null;
-    this.clock = new THREE.Clock();
+    this.clock = new THREE.Timer();
     this.duration = null;
     this._backup = null;
     this.root = null;
@@ -334,6 +334,7 @@ class Animation {
    */
   update(): void {
     if (this.mixer) {
+      this.clock.update();
       this.mixer.update(this.clock.getDelta());
     }
   }