@displayxr/inline3d 1.19.0 → 1.19.2

package/js/inline3d-splat-playcanvas.js

@@ -693,6 +693,8 @@ export class PlayCanvasSplatViewer {
     this._snap = null;
     /** setSource's live outgoing asset (./inline3d-splat-live.js), made on first use. */
     this._live = null;
+    /** (entries, rect) => void: once per drawn frame, after the views are set, before the engine renders. */
+    this.onBeforeRender = null;
     this.vH = virtualDisplayHeight;
     this.fit = fit;
     this.margin = margin;
@@ -1447,6 +1449,34 @@ export class PlayCanvasSplatViewer {
     return { rig: this.rigMatrix(), pose, c, t: Math.tan((this.mono.fov * DEG) / 2) };
   }
 
+  /**
+   * One camera's eye views as the engine composes them this frame (RenderView.updateTransforms:
+   * the camera node's PARENT world transform · each view's pose), packed for the wavefront's cull
+   * (EFFECTS.wipecull): V = the view matrix, X / W = rows 0 and 3 of proj · V, K = (the engine's
+   * focal f = viewport width · proj[0], 1 / viewport width, the view's squared scale). `into` is
+   * reused frame to frame. Null when a matrix is singular.
+   */
+  cullViews(cam, entries, rect, into = []) {
+    const parent = cam?.parent?.getWorldTransform?.()?.data ?? null;
+    into.length = entries.length;
+    for (let i = 0; i < entries.length; i++) {
+      const e = entries[i];
+      const V = mat4Invert(parent ? mat4Mul(parent, e.pose) : e.pose);
+      if (!V) return null;
+      const C = mat4Mul(e.proj, V);
+      const w = Math.max(1, rect(e)[2]);
+      const o = (into[i] ||= { V: new Float32Array(16), X: new Float32Array(4), W: new Float32Array(4), K: new Float32Array(4) });
+      o.V.set(V);
+      o.X[0] = C[0]; o.X[1] = C[4]; o.X[2] = C[8]; o.X[3] = C[12];
+      o.W[0] = C[3]; o.W[1] = C[7]; o.W[2] = C[11]; o.W[3] = C[15];
+      o.K[0] = w * e.proj[0];
+      o.K[1] = 1 / w;
+      o.K[2] = V[0] * V[0] + V[1] * V[1] + V[2] * V[2];
+      o.K[3] = 0;
+    }
+    return into;
+  }
+
   /** Can this tile render a live outgoing asset (the single-camera RenderView path)? */
   get canLiveOutgoing() {
     return LiveOutgoing.supported(this);
@@ -1643,6 +1673,8 @@ export class PlayCanvasSplatViewer {
       placeNode(this.eye, entries[0].pose);
       // setSource's live outgoing: the same views on its own camera, into its own target.
       if (this._live?.active) this._live.sync(entries, rect, f);
+      // setSource's wavefront: this frame's eye views, as the engine is about to compose them.
+      this.onBeforeRender?.(entries, rect);
     } else {
       // Fallback: one camera per view, `rect` + `calculateProjection`.
       const cams = this._views;
@@ -3223,7 +3255,8 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
   let rigSeq = 0;
   /** The IBL setRig('display') installed ({ kind, atlas, prev }), and what it replaced — or null. */
   let rigEnv = null;
-  /** ./inline3d-model-playcanvas.js once a display rig has loaded it (transmission, environments). */
+  /** ./inline3d-pc-look.js once a display rig has loaded it (transmission, environments). Never the
+   *  model module: that one holds the optional meshoptimizer import, which ./splat must not reach. */
   let rigModelModule = null;
   /** Mesh instances / materials prepareTransmission has handled, and whether it turned the grab on. */
   const rigTransmissionSeen = new WeakSet();
@@ -3322,7 +3355,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
 
   /** Install addModel's IBL (`disp.environment`) for the display rig, if the page has none of its own. */
   async function ensureRigEnvironment(disp, seq) {
-    const m = (rigModelModule ||= await import('./inline3d-model-playcanvas.js'));
+    const m = (rigModelModule ||= await import('./inline3d-pc-look.js'));
     if (removed || seq !== rigSeq || rigOverride?.type !== 'display') return;
     rigTick = 0; // transmission check on the next tick
     const kind = disp.environment;
@@ -3679,7 +3712,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     const loaded = await loadOne(pcModule, app, src, { background: true });
     perfSpan('prepareSource', t0);
     // The transition the page declared: compile its shader now, in the dwell, not on its first frame.
-    if (warm?.particles) await prewarmTransition(warm);
+    await prewarmTransition(warm); // null (no transition declared): the overlay only
     const entry = { loaded, state: 'ready', dispose: null };
     const prepared = {
       [PREPARED_TAG]: true,
@@ -3720,46 +3753,61 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
    * engine whose internals differ just compiles on the transition's first frame, as before.
    */
   async function prewarmTransition(plan) {
-    const key = `${plan.particles.in.effect}|${plan.particles.in.opts.order ?? ''}`;
-    if (!fx || prewarmed.has(key)) return;
+    // The chunk variant the transition installs (particles, wavefront), and the overlay's two quads
+    // (crossfade, wavefront and the particles all composite through them; created on the first
+    // capture otherwise, and compiled on its draw: 30–180 ms on the first frames of the window).
+    const chunkKey = plan?.particles
+      ? `${plan.particles.in.effect}|${plan.particles.in.opts.order ?? ''}`
+      : plan?.transition === 'wavefront'
+        ? 'wavefront'
+        : null;
+    const wantChunk = !!(fx && chunkKey && !prewarmed.has(chunkKey));
+    const wantOverlay = !prewarmed.has('overlay');
+    if (!wantChunk && !wantOverlay) return;
     await yieldIdle();
-    if (removed || !fx) return;
+    if (removed) return;
     try {
       const pc = pcModule;
-      const cams = [viewer.eye, viewer._live?.cam].filter(Boolean);
-      const code = fx.sharedChunkCode('transition', plan.particles.in.effect, { order: plan.particles.in.opts.order });
       const made = [];
-      let issued = 0;
-      for (const cam of cams) {
-        const cd = viewer.app?.renderer?.gsplatDirector?.camerasMap?.get?.(cam.camera?.camera);
-        let mi = null;
-        if (cd?.layersMap) for (const ld of cd.layersMap.values()) mi ||= ld?.gsplatManager?.renderer?.meshInstance ?? 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 (wantChunk && fx) {
+        const cams = [viewer.eye, viewer._live?.cam].filter(Boolean);
+        const code = plan.particles
+          ? fx.sharedChunkCode('transition', plan.particles.in.effect, { order: plan.particles.in.opts.order })
+          : fx.sharedChunkCodeFor([
+              ['transition', 'wavefront', {}],
+              ['transition-cull', 'wipecull', {}],
+            ]);
+        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);
       }
-      // the overlay's two quads (created on the first capture otherwise, and compiled on its draw)
       const cam = viewer.eye?.camera?.camera;
-      if (cam?.shaderParams) {
+      if (wantOverlay && cam?.shaderParams) {
         viewer._ensureSnapshotOverlay();
+        let issued = 0;
         for (const p of viewer._snap?.parts || []) {
-          made.push(p.mat.getShaderVariant?.({
+          const v = p.mat.getShaderVariant?.({
             device: viewer.app.graphicsDevice,
             scene: viewer.app.scene,
             objDefs: p.mi._shaderDefs,
@@ -3768,16 +3816,18 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
             sortedLights: [],
             viewUniformFormat: viewer.app.renderer?.viewUniformFormat ?? null,
             vertexFormat: p.mi.mesh?.vertexBuffer?.format,
-          }));
+          });
+          if (v) (made.push(v), issued++);
         }
+        if (issued) prewarmed.add('overlay');
       }
-      if (issued) prewarmed.add(key);
       await finalizeWhenLinked(made.filter(Boolean));
     } catch (err) {
       console.info('[inline3d/splat] transition shader pre-warm skipped', err);
     }
   }
 
+
   /**
    * 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
@@ -3844,6 +3894,9 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     await first.catch(() => null); // a failed first asset may be replaced
     if (!app || removed) return out;
     const pc = pcModule;
+    // Not prepared: compile what the transition draws with (its chunk, the overlay) while the asset
+    // loads, rather than on the window's first frames. Best effort, not awaited.
+    if (!prep && current && plan.transition !== 'cut') prewarmTransition(plan);
     const loaded = prep ? prep.loaded : await loadOne(pc, app, next);
     if (removed || gen !== sourceGen) {
       app.assets.remove(loaded.asset);
@@ -3976,15 +4029,24 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
         });
       } else release(prev); // the snapshot shows it from here on
       const band = plan.band;
+      finishers.push(() => {
+        viewer._transitionState = null;
+        viewer.setSnapshotAlpha(0);
+        viewer.releaseSnapshot();
+      });
+      if (fx && managerMi(viewer.eye, null)) {
+        playWavefrontRender({ plan, entity, live, finishers, finish, isFinished: () => finished, pumpLive });
+        await done;
+        return out;
+      }
+      // FALLBACK (an engine whose managers are not reachable): the ridge as an entity-scope
+      // modifier — correct, but it rewrites the new photo's work buffer and re-sorts it every frame.
+      viewer._transitionPath = 'entity';
       const ridge = fx.play(
         'wavefront',
         { durationMs: plan.durationMs, easing: plan.easing, band, ridge: plan.ridge, ridgeMaxDisparity: plan.ridgeMaxDisparity, scope: 'entity' },
         { entity, gate: afterTicks(2), internal: true },
       );
-      finishers.push(() => {
-        viewer.setSnapshotAlpha(0);
-        viewer.releaseSnapshot();
-      });
       viewer._hooks.push(() => {
         if (finished || removed) return false;
         if (live && !live.fits) {
@@ -4063,6 +4125,94 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     return out;
   }
 
+  /** The mesh instance of the gsplat manager that `cam` draws `layer` with (any layer: null). */
+  const managerMi = (cam, layer) => {
+    const cd = viewer.app?.renderer?.gsplatDirector?.camerasMap?.get?.(cam?.camera?.camera);
+    if (!cd?.layersMap) return null;
+    if (layer) return cd.layersMap.get(layer)?.gsplatManager?.renderer?.meshInstance ?? null;
+    for (const ld of cd.layersMap.values()) if (ld?.gsplatManager?.renderer?.meshInstance) return ld.gsplatManager.renderer.meshInstance;
+    return null;
+  };
+
+  /**
+   * setSource's wavefront, RENDER-TIME (the default): the ridge is a tile-scope body whose values
+   * sit on the eye camera's manager (the incoming photo), as the particle transitions do — no
+   * work-buffer rewrite and no re-sort per frame. Each photo is drawn only on its side of the
+   * front (EFFECTS.wipecull, the last stage): the incoming one left of where its commit starts,
+   * the outgoing one (on the live camera) right of where it ends, so the two share only the
+   * `band`. The overlay still wipes the same two live images on the same lt; the frame is the
+   * one the full draws give, bit for bit. The clock starts on the second tick (the incoming
+   * asset's first frame builds its work buffer), as the crossfade's does.
+   */
+  function playWavefrontRender({ plan, entity, live, finishers, finish, isFinished, pumpLive }) {
+    const band = plan.band;
+    const ease = typeof plan.easing === 'function' ? plan.easing : EASINGS[plan.easing] || EASINGS.linear;
+    const eyeMi = () => managerMi(viewer.eye, null);
+    const liveMi = () => (live?.active ? managerMi(live.cam, live.layer) : null);
+    const ridgeFx = fx.driveShared('transition', 'wavefront', {});
+    const cullFx = fx.driveShared('transition-cull', 'wipecull', {});
+    const ridgeIn = ridgeFx.side(eyeMi, { band, ridge: plan.ridge, ridgeMaxDisparity: plan.ridgeMaxDisparity });
+    const cull = { in: null, out: null };
+    const cullIn = cullFx.side(eyeMi, { cull: () => cull.in });
+    const cullOut = live ? cullFx.side(liveMi, { cull: () => cull.out }) : null;
+    const views = { in: [], out: [] };
+    let amount = 0;
+    ridgeIn.set(0);
+    viewer._transitionPath = 'render';
+    // Where each photo still shows, in each eye's viewport-relative NDC (setSnapshotAlpha's wipe:
+    // column u has committed lt = clamp((t − u·(1 − band)) / band, 0, 1) to the new photo).
+    const clampEdge = (x) => Math.min(3, Math.max(-3, x));
+    viewer.onBeforeRender = (entries, rect) => {
+      if (isFinished()) return;
+      const span = 1 - band;
+      // band 1: the whole picture is the band — draw both in full. `_wipeCull = false`: the
+      // diagnostics switch the exactness gate compares against (docs §Gates).
+      if (!(span > 1e-6) || viewer._wipeCull === false) {
+        cull.in = cull.out = null;
+        cullIn.set(amount);
+        cullOut?.set(amount);
+        return;
+      }
+      const vin = viewer.cullViews(viewer.eye, entries, rect, views.in);
+      cull.in = vin ? { side: -1, edge: clampEdge((2 * amount) / span - 1), views: vin } : null;
+      cullIn.set(amount);
+      if (cullOut) {
+        const vout = viewer.cullViews(live.cam, entries, rect, views.out);
+        cull.out = vout ? { side: 1, edge: clampEdge((2 * (amount - band)) / span - 1), views: vout } : null;
+        cullOut.set(amount);
+      }
+    };
+    finishers.push(() => {
+      if (viewer.onBeforeRender) viewer.onBeforeRender = null;
+      ridgeFx.remove();
+      cullFx.remove();
+    });
+    let t0 = null;
+    let ticks = 0;
+    viewer._hooks.push((t) => {
+      if (removed) return (finish(), false);
+      if (isFinished()) return false;
+      if (live && !live.fits) {
+        finish(); // a resize or a 2D/3D switch mid-window: end now
+        return false;
+      }
+      pumpLive();
+      if (++ticks >= 2 && t0 === null) {
+        t0 = t;
+        ridgeIn.restart(); // the eyes' frame, now the new rig and first frames are in
+      }
+      const raw = t0 === null ? 0 : plan.durationMs > 0 ? Math.min(1, Math.max(0, (t - t0) / plan.durationMs)) : 1;
+      amount = ease(raw);
+      viewer._transitionState = { raw, live: !!live }; // diagnostics
+      ridgeIn.set(amount);
+      if (!viewer.setSnapshotAlpha(1, { t: amount, band, views: viewer.viewsAcross }) || raw >= 1) {
+        finish();
+        return false;
+      }
+      return true;
+    });
+  }
+
   /**
    * setSource's particle transitions (swarm, burst, shimmer-cross, dust), once the frame snapshot
    * is up. The OUTGOING asset plays its effect in reverse, on the live camera, keyed on its own
@@ -4082,13 +4232,6 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     // (outgoing). No work-buffer rewrite and no re-sort per frame. An engine that does not expose
     // the managers' mesh instances gets the entity-scope modifiers instead (a full work-buffer
     // rewrite + a re-sort per asset per frame: correct, but it hitches on a 1.18M photo).
-    const managerMi = (cam, layer) => {
-      const cd = viewer.app?.renderer?.gsplatDirector?.camerasMap?.get?.(cam?.camera?.camera);
-      if (!cd?.layersMap) return null;
-      if (layer) return cd.layersMap.get(layer)?.gsplatManager?.renderer?.meshInstance ?? null;
-      for (const ld of cd.layersMap.values()) if (ld?.gsplatManager?.renderer?.meshInstance) return ld.gsplatManager.renderer.meshInstance;
-      return null;
-    };
     const eyeMi = () => managerMi(viewer.eye, null);
     const liveMi = () => (live?.active ? managerMi(live.cam, live.layer) : null);
     const shared = particle.out.effect === particle.in.effect && eyeMi() ? fx.driveShared('transition', particle.in.effect, { order: particle.in.opts.order }) : null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@displayxr/inline3d",
-  "version": "1.19.0",
+  "version": "1.19.2",
   "description": "Turn any HTML <canvas> into a glasses-free-3D window on a DisplayXR display, inside an ordinary web page. Dependency-free; progressive enhancement (falls back to plain 2D everywhere else).",
   "type": "module",
   "types": "./index.d.ts",
@@ -56,6 +56,7 @@
     "js/inline3d-model.js",
     "js/inline3d-model-entry.js",
     "js/inline3d-model-playcanvas.js",
+    "js/inline3d-pc-look.js",
     "js/inline3d-playcanvas-engine.js",
     "index.d.ts",
     "three.d.ts",