@displayxr/inline3d 1.42.0 → 1.43.0

package/js/camera/converge.js

@@ -7,8 +7,12 @@
 /** Low-pass factor for the convergence shift (RFC §3): next = prev + α·(target − prev). */
 export const CONVERGENCE_ALPHA = 0.2;
 
-/** The convergence shift never exceeds this fraction of the per-eye width, either way. */
-export const CONVERGENCE_MAX_FRACTION = 0.12;
+/**
+ * The convergence shift never exceeds this fraction of the per-eye width, either way. 0.2: a
+ * 120 mm-baseline camera (the SR laptop's) sees a face at 0.6 m at ~22% of the eye width, so it
+ * needs ~11% per eye — 0.12 left no room to lean in.
+ */
+export const CONVERGENCE_MAX_FRACTION = 0.2;
 
 /** `setDepth(v)`: v in [-1, 1] adds v times this fraction of the per-eye width to the shift. */
 export const DEPTH_RANGE_FRACTION = 0.05;

package/js/camera/disparity.js

@@ -144,7 +144,11 @@ export function matchBlock(img, W, H, x0, y0, bw, bh, { dMin, dMax, dyMax = 2, u
 export function blockDisparities(img, W, H, o = {}) {
   const E = W / 2;
   const b = o.block || Math.max(8, Math.round(E / 20));
-  const step = o.step || Math.round(b * 1.5); // sparse grid: half the blocks, same modes
+  // One block per block width. A sparser grid (1.5 b) left a dim, grayscale SR-camera frame with
+  // ~9 matched blocks, 3-4 of them on the face — too few to form a mode — so the background won
+  // and auto-convergence flipped between the two. At 1 b: ~36 blocks, the face every frame, and a
+  // steadier value (±1 px instead of ±4); ~13 ms per full search at 240 px per eye.
+  const step = o.step || b;
   const dMax = o.dMax ?? Math.round(E * 0.3);
   const dMin = o.dMin ?? -Math.round(E * 0.05);
   const x0 = Math.round(E * (o.roiX0 ?? 0.15));
@@ -165,12 +169,17 @@ export function blockDisparities(img, W, H, o = {}) {
  * The subject = the NEAREST strong disparity mode: the largest `d` whose ±`tol` bin holds at least
  * `minFrac` of the matched blocks (and `minBlocks`). Returns its members, or null.
  */
-export function nearestMode(blocks, { tol = 2, minFrac = 0.12, minBlocks = 3 } = {}) {
+export function nearestMode(blocks, { tol = 2, relTol = 0.1, minFrac = 0.12, minBlocks = 3 } = {}) {
   if (!blocks.length) return null;
   const need = Math.max(minBlocks, Math.ceil(blocks.length * minFrac));
   const ds = blocks.map((b) => b.d).sort((a, b) => b - a); // descending: nearest first
   for (const d of ds) {
-    const members = blocks.filter((b) => Math.abs(b.d - d) <= tol);
+    // The bin widens with the disparity: a near subject's own relief spreads its blocks over
+    // ~relTol of its disparity (the spread scales with baseline / distance, as d does), so a
+    // fixed +-2 px split a face from a wide-baseline (120 mm) camera into groups too small to
+    // count, and the flat background won.
+    const t = Math.max(tol, relTol * Math.abs(d));
+    const members = blocks.filter((b) => Math.abs(b.d - d) <= t);
     if (members.length >= need) {
       const md = members.map((b) => b.d).sort((a, b) => a - b);
       return { d: md[md.length >> 1], members };

package/js/camera/pair-cursor.js

@@ -72,21 +72,116 @@ export function pairFootprintDisparity(luma, geo, u, v, height, aspect) {
   const dMin = -Math.round(E * 0.05);
   const { rL, rR } = geo;
   const k = geo.outW / rL.sw; // output px per source px
-  let best = null;
-  // The tip, then a ring centred on the arrow's body: that is what content must not overlap.
+  const swp = swappedHalves(luma);
+  const found = []; // { d, x, y, eye }: a consistent match and WHERE it was taken
+  const seen = new Set();
+  const sample = (su, pv) => {
+    const y = Math.round((rL.sy + pv * rL.sh) * scale - b / 2);
+    if (y < 0 || y + b > h) return;
+    const xl = Math.round((rL.sx + su * rL.sw) * scale - b / 2);
+    const xr = Math.round((rR.sx + su * rR.sw) * scale - b / 2);
+    // The arrow is far smaller than a block (~6 vs 12 copy px at the OS arrow's size), so
+    // neighbouring footprint points land on the SAME block: match each block once.
+    if (!seen.has(`L${xl},${y}`)) {
+      seen.add(`L${xl},${y}`);
+      const dl = consistentMatch(img, swp, w, h, xl, y, b, dMin, dMax);
+      if (dl !== null) found.push({ d: dl, x: xl, y, eye: 0 });
+    }
+    if (!seen.has(`R${xr},${y}`)) {
+      seen.add(`R${xr},${y}`);
+      const dr = consistentMatch(swp, img, w, h, xr, y, b, -dMax, -dMin); // right-anchored: d' = -d
+      if (dr !== null) found.push({ d: -dr, x: xr, y, eye: 1 });
+    }
+  };
+  // The tip, then a ring centred on the arrow's body: that is what content must not overlap. Each
+  // point is sampled from BOTH eyes' images (the pointer's spot in the left eye matched into the
+  // right, and the same spot in the right eye matched into the left), so neither eye is favoured:
+  // at a foreground edge one eye's block can sit on the subject and the other's on the background.
+  // Every match must also pass the left-right consistency check (consistentMatch).
+  let cu = 0, cv = 0, n = 0;
   for (const [pu, pv] of cursorArrowFootprint(u, v, height, aspect)) {
     if (!(pu >= 0 && pu <= 1 && pv >= 0 && pv <= 1)) continue;
-    const su = geo.mirror ? 1 - pu : pu;
-    const x = Math.round((rL.sx + su * rL.sw) * scale - b / 2);
-    const y = Math.round((rL.sy + pv * rL.sh) * scale - b / 2);
-    if (x < 0 || x + b > E || y < 0 || y + b > h) continue;
-    const m = matchBlock(img, w, h, x, y, b, b, { dMin, dMax, dyMax: 2 });
-    if (!m || m.c < MIN_NCC) continue;
-    // Source disparity → displayed: each eye's crop moved its half by its own offset.
-    const d = (m.d / scale - (rL.sx - rR.sx)) * k;
-    if (best === null || d > best) best = d;
+    sample(geo.mirror ? 1 - pu : pu, pv);
+    cu += pu; cv += pv; n++;
+  }
+  if (!n) return null;
+  // ...plus four blocks half a block around the footprint's centre, so that real content under
+  // the arrow is seen by more than one distinct block (pairNearestSupported needs that).
+  const du = (b / 2 / scale) / rL.sw, dv = (b / 2 / scale) / rL.sh;
+  for (const [ou, ov] of [[-du, 0], [du, 0], [0, -dv], [0, dv]]) {
+    const pu = cu / n + ou, pv = cv / n + ov;
+    if (pu >= 0 && pu <= 1 && pv >= 0 && pv <= 1) sample(geo.mirror ? 1 - pu : pu, pv);
+  }
+  // Source disparity → displayed: each eye's crop moved its half by its own offset.
+  for (const f of found) f.d = (f.d / scale - (rL.sx - rR.sx)) * k;
+  return pairNearestSupported(found, (PAIR_SUPPORT_COPY_PX / scale) * k, b / 2);
+}
+
+/**
+ * Two consistent footprint matches must agree (within this many px of the grayscale copy) before
+ * the nearest is believed: content that comes out of the screen covers several blocks, a lone
+ * block claiming something nearer than the rest is noise.
+ */
+export const PAIR_SUPPORT_COPY_PX = 1.5;
+
+/** The SBS copy with its halves swapped (cached per copy): matching it is matching right → left. */
+const _swapped = new WeakMap();
+function swappedHalves(luma) {
+  let s = _swapped.get(luma);
+  if (s) return s;
+  const { img, w, h } = luma;
+  const E = w / 2;
+  s = new Uint8Array(w * h);
+  for (let y = 0; y < h; y++) {
+    const o = y * w;
+    for (let x = 0; x < E; x++) {
+      s[o + x] = img[o + E + x];
+      s[o + E + x] = img[o + x];
+    }
+  }
+  _swapped.set(luma, s);
+  return s;
+}
+
+/**
+ * A block of image A's left half matched into its right half, kept only if the matched block,
+ * matched BACK (in B = A with its halves swapped), lands within 1 px of where it started — the
+ * classic left-right consistency check. A block straddling a depth edge (half subject, half
+ * background, each eye seeing a different half) fails it instead of returning a random depth.
+ * @returns {number|null} disparity in A's convention (left x − right x), copy px
+ */
+export function consistentMatch(A, B, w, h, x, y, b, dMin, dMax) {
+  const E = w / 2;
+  if (x < 0 || x + b > E) return null;
+  const m = matchBlock(A, w, h, x, y, b, b, { dMin, dMax, dyMax: 2 });
+  if (!m || m.c < MIN_NCC) return null;
+  const xb = Math.round(x - m.d);
+  const yb = y + m.dy;
+  if (xb < 0 || xb + b > E || yb < 0 || yb + b > h) return null;
+  const back = matchBlock(B, w, h, xb, yb, b, b, { dMin: -Math.ceil(m.d) - 2, dMax: -Math.floor(m.d) + 2, dyMax: 1 });
+  if (!back || back.c < MIN_NCC || Math.abs(-back.d - m.d) > 1) return null;
+  return m.d;
+}
+
+/**
+ * The nearest disparity that an INDEPENDENT second sample corroborates (within `tol`), else null.
+ * Independent = taken from the other eye's image, or from a block at least `minSep` copy px away:
+ * two footprint points inside one block are one witness, not two. (A block straddling a face edge
+ * and a bright window matched at a bogus +49 px, consistently, and its twin counted as support.)
+ * @param {Array<{d:number, x?:number, y?:number, eye?:number}|number>} samples  output px, + = in front
+ * @returns {number|null}
+ */
+export function pairNearestSupported(samples, tol, minSep = 0) {
+  const S = samples.map((s) => (typeof s === 'number' ? { d: s, x: 0, y: 0, eye: -1 } : s));
+  if (S.length < 2) return null;
+  const sorted = [...S].sort((p, q) => q.d - p.d); // nearest first
+  const independent = (p, q) => p.eye === -1 || p.eye !== q.eye || Math.abs(p.x - q.x) + Math.abs(p.y - q.y) >= minSep;
+  for (const p of sorted) {
+    for (const q of sorted) {
+      if (q !== p && Math.abs(p.d - q.d) <= tol && independent(p, q)) return p.d;
+    }
   }
-  return best;
+  return null;
 }
 
 /**

package/js/inline3d-model-entry.js

@@ -141,7 +141,10 @@ function addModelUnguarded(wall, canvas, src, opts = {}) {
     remove: queue('remove'),
     exclude: queue('exclude'),
     unexclude: queue('unexclude'),
+    // Before the backend lands: once it has, the backend's own (PlayCanvas); three has none (0).
+    warmEntity: (entity, o) => out.ready.then(() => (out.warmEntity !== stubWarm && typeof out.warmEntity === 'function' ? out.warmEntity(entity, o) : 0)),
   };
+  const stubWarm = out.warmEntity;
   out.firstWoven = new Promise((resolve) => {
     out._resolveFirstWoven = resolve;
   });

package/js/inline3d-model-playcanvas.js

@@ -515,6 +515,14 @@ export function attachPlayCanvasModel(out, wall, canvas, src, opts, pending = []
     },
     exclude: (el) => handle?.exclude(el),
     unexclude: (el) => handle?.unexclude(el),
+    /**
+     * Compile `entity`'s mesh programs off the frame before it is shown (default: the model) —
+     * PlayCanvasSplatViewer.warmEntity. Resolves the number of programs warmed; 0 before `ready`.
+     */
+    async warmEntity(entity, o) {
+      await out.ready?.catch?.(() => null);
+      return removed ? 0 : viewer.warmEntity(entity ?? out.model, o);
+    },
   });
 
   // The per-eye buffer scale in force (the request times the device-limit clamp,

package/js/inline3d-playcanvas-engine.js

@@ -37,6 +37,7 @@ export {
   Vec4,
   Quat,
   LAYERID_SKYBOX,
+  LAYERID_WORLD,
   LAYERID_UI,
   LAYERID_IMMEDIATE,
   // cursor: 'depth' (./inline3d-cursor-depth-playcanvas.js, loaded only on opt-in)
@@ -57,6 +58,7 @@ export {
   SEMANTIC_COLOR,
   ShaderChunks,
   SHADERLANGUAGE_GLSL,
+  SHADER_FORWARD,
   CHUNKAPI_2_8,
   // setSource's frame snapshot
   RenderTarget,

package/js/inline3d-splat-deferred.js

@@ -117,6 +117,13 @@ export function addSplatDeferred(wall, canvas, src, opts) {
       validateEffectCall(name, o, 'play');
       return out.ready.then(() => out.playEffect(name, o));
     },
+    // Warm before the adapter has loaded: validated now, warmed once the first asset is on screen.
+    warmEffect: (name, o) => {
+      validateEffectCall(name, o, 'play');
+      return out.ready.then(() => out.warmEffect(name, o));
+    },
+    // Mesh-program warm before the adapter has loaded: runs once it has (it needs the engine).
+    warmEntity: (entity, o) => out.ready.then(() => out.warmEntity(entity, o)),
     setEffect: (name, params) => {
       validateEffectCall(name, params, 'set');
       pending.push(['setEffect', [name, params]]);

package/js/inline3d-splat-effects.js

@@ -1788,6 +1788,22 @@ export class SplatEffects {
     };
   }
 
+  /**
+   * The tile chunk play(name, opts) WOULD install right now — the tile effects already on, with
+   * this one added (or replacing its namesake, in place, as _replace does) — without installing
+   * it: what handle.warmEffect compiles ahead of the play. Null for an entity-scope effect (its
+   * program is the asset's work-buffer modifier, not the tile chunk) or a custom fragment stage.
+   */
+  playChunkCode(name, opts = {}) {
+    const o = resolveEffectOptions(name, opts, 'play');
+    if ((o.scope ?? 'tile') !== 'tile' || o.fragmentGlsl) return null;
+    const inst = { name, def: defOf(name), opts: o };
+    const m = this.scopes.get('tile');
+    const list = m ? [...m.values()].map((i) => (i.name === name ? inst : i)) : [];
+    if (!m?.has(name)) list.push(inst);
+    return composeModifier(list).code;
+  }
+
   /**
    * The tile chunk driveShared(name, effect, opts) WOULD install, without installing it — what
    * setSource's shader pre-warm compiles ahead of the transition.

package/js/inline3d-splat-playcanvas.js

@@ -1190,6 +1190,86 @@ export class PlayCanvasSplatViewer {
    * engine's `renderSceneColorMap` setter counts one request per camera. Cameras made later (a
    * view-path switch) inherit it via `_makeCamera`.
    */
+  /**
+   * Compile the forward programs `entity`'s meshes will draw with — through the RENDERER's own
+   * call (MeshInstance.getShaderInstance with the pass, layer light hash, sorted lights, view
+   * uniform format and each eye camera's live shaderParams it will pass), so the variant is the
+   * very one the first draw asks for, cached on the mesh instance — then finish each link in idle
+   * periods (KHR_parallel_shader_compile) instead of on that draw. PlayCanvas's forward renderer
+   * links synchronously on first use (asyncCompile = false): a glTF with ~13 lit materials froze
+   * 0.8–0.95 s on a panel. Calling material.getShaderVariant with hand-built params instead
+   * produces broken variants (`#include "litMainVS"` unresolved) — do not.
+   *
+   * Warm in the state you will draw in: lights, fog, the layer and the camera's render target
+   * key the variant. Needs one frame rendered (the cameras' shaderParams). Resolves the number of
+   * programs warmed (0: nothing to do, or an engine whose internals differ).
+   */
+  async warmEntity(entity, { timeoutMs = 4000 } = {}) {
+    const pc = this.pc;
+    const app = this.app;
+    if (!pc || !app || this._disposed || !entity) return 0;
+    const device = app.graphicsDevice;
+    const scene = app.scene;
+    const renderer = app.renderer;
+    if (!renderer || typeof renderer.viewUniformFormat === 'undefined') return 0;
+    // [meshInstance, the layer ids it draws in] — a render/model component's own `layers`
+    const groups = [];
+    for (const c of [...(entity.findComponents?.('render') || []), ...(entity.findComponents?.('model') || [])]) {
+      if (c.meshInstances?.length) groups.push([c.meshInstances, c.layers?.length ? c.layers : [pc.LAYERID_WORLD]]);
+    }
+    if (!groups.length) return 0;
+    const cams = [this.eye, ...(this._viewPath === 'cameras' ? this._views : [])]
+      .map((c) => c?.camera)
+      .filter((c) => c?.camera?.shaderParams);
+    const forward = pc.SHADER_FORWARD ?? 0;
+    const shaders = new Set();
+    // Issuing a program compiles its two shaders on THIS thread: 13 lit programs at once were one
+    // 65 ms frame. Time-slice — yield to idle whenever a slice passes SLICE_MS.
+    const SLICE_MS = 8;
+    let slice = now();
+    try {
+      for (const cc of cams) {
+        const shaderParams = cc.camera.shaderParams;
+        // the renderer's own pick (renderForwardLayer): the camera's shader pass, else forward
+        const pass = cc.camera.shaderPassInfo?.index ?? forward;
+        for (const [mis, layerIds] of groups) {
+          for (const layerId of layerIds) {
+            if (cc.layers && !cc.layers.includes(layerId)) continue; // this camera never draws it
+            const layer = scene.layers.getLayerById(layerId);
+            if (!layer) continue;
+            const lightHash = layer.getLightHash?.(scene.clusteredLightingEnabled) ?? 0;
+            for (const mi of mis) {
+              if (!mi?.mesh || !mi.material) continue;
+              if (((mi.shaderPassMask ?? ~0) & (1 << pass)) === 0) continue;
+              mi.ensureMaterial?.(device);
+              mi.material._scene = scene;
+              mi.material.prepareForRender?.(device, scene);
+              const si = mi.getShaderInstance(pass, lightHash, scene, shaderParams, renderer.viewUniformFormat, layer.splitLights);
+              if (si?.shader) shaders.add(si.shader);
+              if (now() - slice > SLICE_MS) {
+                await yieldIdle(50);
+                if (this._disposed) return 0;
+                slice = now();
+              }
+            }
+          }
+        }
+      }
+    } catch (err) {
+      console.info(`${this.logTag} warmEntity: could not issue the programs (engine internals differ?)`, err);
+      return 0;
+    }
+    const pending = () => [...shaders].filter((x) => !x.ready && !x.failed && x.impl?.finalize);
+    const t0 = now();
+    while (pending().length && now() - t0 < timeoutMs && !this._disposed) {
+      for (const x of pending()) if (x.impl.isLinked?.(device)) x.impl.finalize(device, x) || (x.failed = true);
+      if (pending().length) await yieldIdle(50);
+    }
+    // still linking (or no completion query): finalize now — a block here, not on the first draw
+    for (const x of pending()) x.impl.finalize(device, x) || (x.failed = true);
+    return shaders.size;
+  }
+
   useSceneColor(on = true) {
     this.sceneColor = !!on;
     const cams = [this.eye, ...(this._viewPath === 'cameras' ? this._views : [])];
@@ -3024,6 +3104,20 @@ export function validateDepthEnvelope(o, prev) {
   return next;
 }
 
+/**
+ * prepareSource's `warmEffects`: an array of effect names, or of { name, opts } (validated as a
+ * playEffect call, at prepareSource's own line). Returns [{ name, opts }].
+ */
+export function validateWarmEffects(list) {
+  if (list === undefined) return [];
+  if (!Array.isArray(list)) throw new TypeError('@displayxr/inline3d/splat: prepareSource warmEffects must be an array of effect names or { name, opts }.');
+  return list.map((w) => {
+    const e = typeof w === 'string' ? { name: w, opts: {} } : { name: w?.name, opts: w?.opts ?? {} };
+    validateEffectCall(e.name, e.opts, 'play');
+    return e;
+  });
+}
+
 /**
  * handle.setStereo's argument, validated and merged onto the current override (throws at the
  * call). Returns the new override, or null when nothing is overridden.
@@ -3477,6 +3571,15 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     },
     prepareSource,
     setRig,
+    /**
+     * Compile `entity`'s mesh programs (content under handle.engine.root) off the frame, before
+     * it is shown — viewer.warmEntity. Resolves the number of programs warmed.
+     */
+    async warmEntity(entity, o) {
+      await booted;
+      await first.catch(() => null);
+      return removed ? 0 : viewer.warmEntity(entity, o);
+    },
     setStereo,
     setDepthEnvelope,
     /**
@@ -3577,6 +3680,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
       validateEffectCall(name, o, 'play');
       return first.then(() => (fx && !removed ? fx.play(name, o) : { finished: false }));
     },
+    warmEffect,
     /** Set a persistent effect (grade, clip, custom), hold a transition at `progress`, or null to remove. */
     setEffect(name, params) {
       validateEffectCall(name, params, 'set');
@@ -4966,7 +5070,9 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
    */
   async function prepareSource(src, po = {}) {
     if (po === null || typeof po !== 'object') throw new TypeError('@displayxr/inline3d/splat: prepareSource options must be an object.');
-    const warm = po.transition !== undefined ? resolveSwap(po) : null; // the setSource options it will get; throws on a bad one
+    const warmList = validateWarmEffects(po.warmEffects);
+    const swapOpts = po.warmEffects === undefined ? po : Object.fromEntries(Object.entries(po).filter(([k]) => k !== 'warmEffects'));
+    const warm = po.transition !== undefined ? resolveSwap(swapOpts) : null; // the setSource options it will get; throws on a bad one
     const app = await booted;
     await first.catch(() => null);
     if (!app || removed) throw new Error('@displayxr/inline3d/splat: prepareSource on a removed tile.');
@@ -4995,6 +5101,8 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     diag?.mark('prepared', { ms: Math.round(performance.now() - t0), fetchOnly });
     // The transition the page declared: compile its shader now, in the dwell, not on its first frame.
     await prewarmTransition(warm); // null (no transition declared): the overlay only
+    // And the effects the page will play once this asset is in (a reveal after the swap).
+    for (const w of warmList) await warmEffect(w.name, w.opts);
     const entry = { loaded, source, state: 'ready', dispose: null };
     const prepared = {
       [PREPARED_TAG]: true,
@@ -5062,32 +5170,9 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
       const pc = pcModule;
       const made = [];
       for (const [chunkKey, codeOf] of fx ? wantChunks : []) {
-        const cams = [viewer.eye, viewer._live?.cam].filter(Boolean);
-        const code = codeOf();
-        let issued = 0;
-        for (const cam of cams) {
-          const mi = managerMi(cam, null);
-          const src = mi?.material;
-          const camera = cam.camera?.camera;
-          if (!src?.shaderDesc || !camera?.shaderParams || typeof src.getShaderVariant !== 'function') continue;
-          const m = new pc.ShaderMaterial(src.shaderDesc);
-          src.defines.forEach((v, k) => m.setDefine(k, v));
-          m.shaderChunks.copy(src.shaderChunks);
-          m.getShaderChunks(pc.SHADERLANGUAGE_GLSL).set('gsplatModifyVS', code);
-          m.blendState = src.blendState;
-          made.push(m.getShaderVariant({
-            device: viewer.app.graphicsDevice,
-            scene: viewer.app.scene,
-            objDefs: mi._shaderDefs,
-            cameraShaderParams: camera.shaderParams,
-            pass: 0, // SHADER_FORWARD
-            sortedLights: [],
-            viewUniformFormat: viewer.app.renderer?.viewUniformFormat ?? null,
-            vertexFormat: mi.mesh?.vertexBuffer?.format,
-          }));
-          issued++;
-        }
-        if (issued) prewarmed.add(chunkKey);
+        const got = issueChunkVariants(pc, codeOf());
+        made.push(...got);
+        if (got.length) prewarmed.add(chunkKey);
       }
       const cam = viewer.eye?.camera?.camera;
       if (wantOverlay && cam?.shaderParams) {
@@ -5115,6 +5200,76 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
   }
 
 
+  /**
+   * Issue (compile + link, not wait for) the gsplat render variant with `code` as its tile
+   * `gsplatModifyVS` chunk, on every eye camera's splat material: a throwaway material with the
+   * renderer's own description, defines and chunks asks the engine's program library for the
+   * variant the renderer will ask for (the library keys on the generated source + processing
+   * options, not on the material). Returns the issued shaders, for finalizeWhenLinked.
+   */
+  function issueChunkVariants(pc, code) {
+    const made = [];
+    for (const cam of [viewer.eye, viewer._live?.cam].filter(Boolean)) {
+      const mi = managerMi(cam, null);
+      const src = mi?.material;
+      const camera = cam.camera?.camera;
+      if (!src?.shaderDesc || !camera?.shaderParams || typeof src.getShaderVariant !== 'function') continue;
+      const m = new pc.ShaderMaterial(src.shaderDesc);
+      src.defines.forEach((v, k) => m.setDefine(k, v));
+      m.shaderChunks.copy(src.shaderChunks);
+      m.getShaderChunks(pc.SHADERLANGUAGE_GLSL).set('gsplatModifyVS', code);
+      m.blendState = src.blendState;
+      const v = m.getShaderVariant({
+        device: viewer.app.graphicsDevice,
+        scene: viewer.app.scene,
+        objDefs: mi._shaderDefs,
+        cameraShaderParams: camera.shaderParams,
+        pass: 0, // SHADER_FORWARD
+        sortedLights: [],
+        viewUniformFormat: viewer.app.renderer?.viewUniformFormat ?? null,
+        vertexFormat: mi.mesh?.vertexBuffer?.format,
+      });
+      if (v) made.push(v);
+    }
+    return made;
+  }
+
+  /**
+   * handle.warmEffect(name, opts) — compile the program playEffect(name, opts) will need, now,
+   * finishing the link in idle periods (KHR_parallel_shader_compile), so the effect's first frame
+   * does not block on it (a particle reveal's link: 250–300 ms on a panel). Keyed on the chunk
+   * the play would install with the tile effects on NOW — warm in the state you will play from.
+   * Resolves `true` once warm (or already warm), `false` where nothing could be warmed (an
+   * entity-scope effect, a custom fragment stage, no engine yet, an engine whose internals
+   * differ: it then compiles on its first frame, as before). Never throws after validation.
+   */
+  async function warmEffect(name, o = {}) {
+    validateEffectCall(name, o, 'play');
+    await first.catch(() => null);
+    if (removed || !fx || !pcModule || diag?.has('nowarm')) return false;
+    let code;
+    try {
+      code = fx.playChunkCode(name, o);
+    } catch {
+      return false;
+    }
+    if (!code) return false;
+    const key = `play|${code}`;
+    if (prewarmed.has(key)) return true;
+    await yieldIdle();
+    if (removed) return false;
+    try {
+      const made = issueChunkVariants(pcModule, code);
+      if (!made.length) return false;
+      await finalizeWhenLinked(made);
+      prewarmed.add(key);
+      return true;
+    } catch (err) {
+      console.info('[inline3d/splat] warmEffect skipped', err);
+      return false;
+    }
+  }
+
   /**
    * Creating a program only ISSUES its compile + link; the browser resolves the link when the
    * program is first queried — the engine's first draw, blocking (the 35–50 ms GetProgramiv the

package/js/inline3d-splat.js

@@ -434,6 +434,11 @@ function addSplatUnguarded(wall, canvas, src, opts = {}) {
     setEffect() {
       throw effectsNotOnSpark('setEffect()');
     },
+    warmEffect() {
+      throw effectsNotOnSpark('warmEffect()');
+    },
+    /** PlayCanvas-backend feature (its renderer links synchronously); nothing to warm here. */
+    warmEntity: () => Promise.resolve(0),
     stopEffect() {
       throw effectsNotOnSpark('stopEffect()');
     },

package/model.d.ts

@@ -222,6 +222,14 @@ export interface ModelHandle {
 
   remove(): void;
   exclude(el: Element): void;
+  /**
+   * PlayCanvas only (resolves 0 on three). Compile the lit programs `entity` (default: the model)
+   * will draw with, in idle time, through the renderer's own shader lookup, and finish their links
+   * off the frame (KHR_parallel_shader_compile), so its first draw does not freeze. Warm while it
+   * is hidden, in the lighting it will be shown in. Resolves the number of programs warmed.
+   * docs/playcanvas-adapter.md §warmEntity.
+   */
+  warmEntity(entity?: unknown, opts?: { timeoutMs?: number }): Promise<number>;
   unexclude(el: Element): void;
   /**
    * The core window's `TileHandle.firstWoven`: when it is safe to reveal the canvas. Resolves

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@displayxr/inline3d",
-  "version": "1.42.0",
+  "version": "1.43.0",
   "description": "Turn any HTML <canvas> into a 3D window on a spatial display, inside an ordinary web page, for the DisplayXR Browser. Dependency-free; progressive enhancement (falls back to plain 2D everywhere else).",
   "type": "module",
   "types": "./index.d.ts",

package/splat.d.ts

@@ -870,6 +870,12 @@ export type SplatPrepareOptions = SplatSourceOptions & {
    * resident during the dwell.
    */
   resident?: boolean;
+  /**
+   * Effects to compile during this prepare (after the asset and the transition), for a
+   * `playEffect` you will run once this asset is in — e.g. a reveal after the swap. Names, or
+   * `{ name, opts }` with the opts you will play with. See {@link SplatHandle.warmEffect}.
+   */
+  warmEffects?: Array<Exclude<SplatEffectName, 'grade' | 'clip'> | { name: Exclude<SplatEffectName, 'grade' | 'clip'>; opts?: SplatEffectTiming & Record<string, unknown> }>;
 };
 
 /** setSource's particle transitions (docs/splat-effects.md §Particle transitions). */
@@ -1091,6 +1097,17 @@ export interface SplatHandle {
    * display rig; a value set meanwhile applies when the video exits. `handle.rig.ipdFactor` /
    * `parallaxFactor` read what is in force. The 2D↔3D mode-switch ramp still multiplies on top.
    */
+  /**
+   * `engine: 'playcanvas'` only (resolves 0 on Spark). Compile the lit programs of `entity` — your
+   * content under `handle.engine.root`, e.g. a glTF — in idle time, through the renderer's own
+   * shader lookup (MeshInstance.getShaderInstance with its exact pass, light hash, lights, view
+   * format and the eye cameras' live shader params), and finish each link off the frame
+   * (KHR_parallel_shader_compile). PlayCanvas's forward renderer otherwise links every new program
+   * synchronously on its first draw: a 13-material car froze 0.8–0.95 s on a panel. Warm it while
+   * it is hidden (`entity.enabled = false` is fine), with the lights it will be shown under; show
+   * it after this resolves. Resolves the number of programs warmed. docs/playcanvas-adapter.md §warmEntity.
+   */
+  warmEntity(entity: unknown, opts?: { timeoutMs?: number }): Promise<number>;
   setStereo(opts: SplatStereoOptions | null): SplatHandle;
   /** This tile in physical units — the core `TileHandle.displayMetrics()`, on the splat handle. Never rejects. */
   displayMetrics(): Promise<DisplayMetrics>;
@@ -1202,6 +1219,17 @@ export interface SplatHandle {
     name: Exclude<SplatEffectName, 'grade' | 'clip'>,
     opts?: SplatEffectTiming & Record<string, unknown>,
   ): Promise<{ finished: boolean }>;
+  /**
+   * `engine: 'playcanvas'` only (throws on Spark). Compile the program `playEffect(name, opts)`
+   * will need NOW, finishing the link in idle periods (KHR_parallel_shader_compile), so the
+   * effect's first frame does not stall on it — a particle reveal (`'assemble'`) links for
+   * 250–300 ms on a panel otherwise. Keyed on the chunk the play would install with the tile
+   * effects on at the time: warm in the state you will play from. Resolves `true` once warm,
+   * `false` when nothing could be warmed (an entity-scope effect, a custom fragment stage); the
+   * effect then compiles on its first frame, as before. Validated at the call.
+   * docs/splat-effects.md §Warming an effect.
+   */
+  warmEffect(name: Exclude<SplatEffectName, 'grade' | 'clip'>, opts?: SplatEffectTiming & Record<string, unknown>): Promise<boolean>;
   /**
    * `engine: 'playcanvas'` only. Set a persistent effect (`grade`, `clip`, `custom`), hold a
    * transition at `{ progress }`, or pass `null` to remove it (the exact baseline).