@displayxr/inline3d 1.28.0 → 1.30.0

package/js/inline3d-splat-deferred.js

@@ -0,0 +1,153 @@
+// inline3d-splat-deferred.js — the engine:'playcanvas' handle, shared by both splat entries.
+//
+// Internal. ./splat (Spark by default) and ./splat/playcanvas (PlayCanvas only) both build their
+// PlayCanvas handle here. This module must never import `three` or `@sparkjsdev/spark`, directly
+// or through anything it imports: that is what lets ./splat/playcanvas keep both off the page
+// (test/splat-pc-entry.test.mjs walks the import graph to hold it to that).
+
+import { normalizeCameraPose } from './inline3d-splat-shared.js';
+import { validateEffectCall } from './inline3d-splat-effects.js';
+
+/**
+ * The `engine: 'playcanvas'` handle, returned SYNCHRONOUSLY like the Spark one.
+ *
+ * The adapter module is loaded on demand, so for a moment the handle exists before its
+ * implementation does. Rather than make every caller await something new, the handle starts as
+ * stubs that QUEUE: `exclude()` (which a product page calls on the very next line), `setPose`,
+ * `setFocus`, `remove` — and the adapter replays the queue into the real implementation, on the
+ * SAME object, the moment it arrives. `ready` resolves to this object, as it does on Spark.
+ * Fields (`viewer`, `mesh`, `rig`, …) are null until then; `viewer` in particular appears one
+ * module-load later than on Spark.
+ */
+/** setRig's type/options shape, checked at the call before the adapter has loaded (it re-checks all of it). */
+function validateSetRigArgs(type, o) {
+  if (!['display', 'camera', 'auto'].includes(type)) {
+    throw new Error(`@displayxr/inline3d/splat: setRig("${type}") — expected 'display', 'camera' or 'auto'.`);
+  }
+  if (o !== undefined && (o === null || typeof o !== 'object')) {
+    throw new TypeError('@displayxr/inline3d/splat: setRig options must be an object.');
+  }
+}
+
+export function addSplatDeferred(wall, canvas, src, opts) {
+  const pending = [];
+  const queue = (name) => (...args) => {
+    pending.push([name, args]);
+    return name === 'setFocus' ? out : undefined;
+  };
+  const page = opts.controls === 'page';
+  const pageOnly = (name) => () => {
+    throw new Error(
+      `@displayxr/inline3d/splat: ${name}() is not available with controls:'page' — the page owns the ` +
+        'camera. Drive it with handle.setCameraPose(matrixWorld, { verticalFovDeg, near, far }).',
+    );
+  };
+  // Before the adapter lands, a page calling setCameraPose every frame keeps ONE pending pose
+  // (validated now, so a bad call throws at its own line): last call wins, as it will after.
+  let pendingPose = null;
+  const out = {
+    backend: 'playcanvas',
+    engine: null,
+    viewer: null,
+    mesh: null,
+    frame: null,
+    camera: null,
+    rig: null,
+    perf: null,
+    setPose: page ? pageOnly('setPose') : queue('setPose'),
+    resetPose: page ? pageOnly('resetPose') : queue('resetPose'),
+    setCameraPose(matrixWorld, o) {
+      if (!page) {
+        throw new Error(
+          "@displayxr/inline3d/splat: setCameraPose() needs addSplat(…, { controls:'page' }) — " +
+            'with the default controls the SDK owns the camera (use setPose).',
+        );
+      }
+      const pose = normalizeCameraPose(matrixWorld, o);
+      if (pendingPose) pendingPose[1] = [pose.matrixWorld, pose];
+      else pending.push((pendingPose = ['setCameraPose', [pose.matrixWorld, pose]]));
+      return out;
+    },
+    getCameraPose: () =>
+      pendingPose
+        ? {
+            matrixWorld: Float32Array.from(pendingPose[1][1].matrixWorld),
+            verticalFovDeg: pendingPose[1][1].verticalFovDeg,
+            near: pendingPose[1][1].near,
+            far: pendingPose[1][1].far,
+            convergence: pendingPose[1][1].convergence,
+          }
+        : null,
+    setFocus: queue('setFocus'),
+    // A swap requested before the first asset has landed runs once it has (the adapter's own
+    // setSource replaces this stub on the same object by then).
+    setSource: (...args) => out.ready.then(() => out.setSource(...args)),
+    prepareSource: (...args) => out.ready.then(() => out.prepareSource(...args)),
+    // A rig switch before the first asset has landed: validated now (controls:'page' and a bad
+    // type throw at the call's own line), applied once it has.
+    setRig: page
+      ? pageOnly('setRig')
+      : (type, o) => {
+          validateSetRigArgs(type, o);
+          return out.ready.then(() => out.setRig(type, o));
+        },
+    // A video before the first asset has landed: controls:'page' throws at the call's own line,
+    // the rest is validated by the adapter's setVideo, which runs once the asset is on screen.
+    setVideo: page ? pageOnly('setVideo') : (src, o) => out.ready.then(() => out.setVideo(src, o)),
+    // Effects before the adapter has loaded: validated NOW (a bad call throws at its own line),
+    // then run once the first asset is on screen.
+    playEffect: (name, o) => {
+      validateEffectCall(name, o, 'play');
+      return out.ready.then(() => out.playEffect(name, o));
+    },
+    setEffect: (name, params) => {
+      validateEffectCall(name, params, 'set');
+      pending.push(['setEffect', [name, params]]);
+      return out;
+    },
+    stopEffect: queue('stopEffect'),
+    // A layer-rig request before the adapter has loaded: queued, replayed in order once it has
+    // (it needs no asset, only the engine's layers — which the adapter resolves lazily).
+    setLayerRig: (...args) => {
+      pending.push(['setLayerRig', args]);
+      return out;
+    },
+    setLayerRigOptions: (...args) => {
+      pending.push(['setLayerRigOptions', args]);
+      return out;
+    },
+    layerRigState: () => ({ display: [], disabled: false, path: null, engaged: false, rounded: false, reason: 'the PlayCanvas adapter has not loaded yet', viewerDistance: 0.6, gain: null, planeM: null, photoConvergenceM: null, planeOffset: 0, located: null }),
+    makeSbsMaterial: () => {
+      throw new Error('@displayxr/inline3d/splat: makeSbsMaterial() needs the engine — call it after `await handle.ready`.');
+    },
+    effects: () => [],
+    getFocus: () => null,
+    // A plain data slot the adapter reads at call time, so a callback assigned on the very next
+    // line after addSplat — before the module has loaded — is the one that fires.
+    onFocusChange: null,
+    pick: () => null,
+    // Splat accounting (resident / budget / first frame); null until the adapter has loaded.
+    stats: () => null,
+    remove: queue('remove'),
+    exclude: queue('exclude'),
+    unexclude: queue('unexclude'),
+  };
+  // `firstWoven` exists from the first line, like every other field a page reads right away; the
+  // adapter settles it with the core handle's own once the module has loaded.
+  out.firstWoven = new Promise((resolve) => {
+    out._resolveFirstWoven = resolve;
+  });
+  // The ONE owner of `ready`: the adapter returns its load promise and never touches this field.
+  out.ready = import('./inline3d-splat-playcanvas.js')
+    .then((m) => m.attachPlayCanvasSplat(out, wall, canvas, src, opts, pending))
+    .catch((err) => {
+      // The adapter warns about its own load failures; this is for the module not arriving.
+      if (!out.viewer) console.warn('[inline3d/splat] engine:playcanvas failed to start', err);
+      if (out._resolveFirstWoven) {
+        out._resolveFirstWoven(Object.freeze({ woven: false, confirmed: false, reason: 'layer-failed', ms: 0 }));
+        delete out._resolveFirstWoven;
+      }
+      throw err;
+    });
+  return out;
+}

package/js/inline3d-splat-pc-entry.js

@@ -0,0 +1,45 @@
+// inline3d-splat-pc-entry.js — `@displayxr/inline3d/splat/playcanvas`: addSplat on PlayCanvas only.
+//
+// EXPERIMENTAL, like ./splat. Same addSplat, same handle, same options, with the engine fixed to
+// 'playcanvas'. The difference is what the page downloads: ./splat statically imports `three`
+// and `@sparkjsdev/spark` because Spark is its default engine and its Spark path is synchronous,
+// so a page passing engine:'playcanvas' there still pays for both (~1.7 MB gzipped). This entry
+// imports neither, directly or transitively. `playcanvas` itself is still loaded on demand, when
+// the first splat is added.
+//
+//   import { createInline3D } from '@displayxr/inline3d';
+//   import { addSplat } from '@displayxr/inline3d/splat/playcanvas';
+//
+//   const wall = await createInline3D();
+//   const scene = addSplat(wall, canvas, 'lake.sog', { reveal: 'sweep' });
+//
+// Not here: measureSplatBounds (it measures a Spark mesh — import it from ./splat).
+
+import { resolveRevealOption } from './inline3d-splat-effects.js';
+import { CAPTURE_FITS, playcanvasCannotRead, resolveControls } from './inline3d-splat-shared.js';
+import { addSplatDeferred } from './inline3d-splat-deferred.js';
+
+export { applySplatPerf, SPLAT_PERF_PRESETS } from './inline3d-splat-perf.js';
+export { readSogCamera, readSogMeta } from './inline3d-sog.js';
+export { resolveRig } from './inline3d-splat-rig.js';
+
+/** addSplat with `engine: 'playcanvas'`; the same validation, at the call, as ./splat's. */
+export function addSplat(wall, canvas, src, opts = {}) {
+  if (opts.engine !== undefined && opts.engine !== 'playcanvas') {
+    throw new Error(
+      `@displayxr/inline3d/splat/playcanvas: engine "${opts.engine}" — this entry is PlayCanvas ` +
+        "only. Import addSplat from '@displayxr/inline3d/splat' for Spark.",
+    );
+  }
+  if (opts.captureFit !== undefined && !CAPTURE_FITS.includes(opts.captureFit)) {
+    throw new Error(
+      `@displayxr/inline3d/splat: captureFit "${opts.captureFit}" — expected ` +
+        `${CAPTURE_FITS.map((f) => `'${f}'`).join(' or ')}.`,
+    );
+  }
+  resolveControls(opts);
+  resolveRevealOption(opts.reveal);
+  const why = playcanvasCannotRead(src, opts);
+  if (why) throw new Error(`@displayxr/inline3d/splat: ${why}`);
+  return addSplatDeferred(wall, canvas, src, { ...opts, engine: 'playcanvas' });
+}

package/js/inline3d-splat-playcanvas.js

@@ -1915,6 +1915,9 @@ export class PlayCanvasSplatViewer {
     const box = this.canvas.getBoundingClientRect();
     const aspect = box.height > 0 ? box.width / box.height : 1;
     this.boxAspect = aspect; // setVideo's plane reads it per frame (no layout read in the draw)
+    // and this, for its on-screen rect: a NEW object only when the size changed (the plane's rect
+    // check compares identity, so an unchanged frame allocates nothing).
+    if (!this.boxCss || this.boxCss.w !== (box.width || 0) || this.boxCss.h !== (box.height || 0)) this.boxCss = { w: box.width || 0, h: box.height || 0 };
     if (this.mono.capture) {
       captureProjection(this.mono.capture, aspect, this.mono.near, this.mono.far, this.mono.proj, this.captureFit);
       if (this.captureFit !== 'height') {
@@ -3125,6 +3128,12 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
   // copy a getter's value once.
   Object.defineProperty(out, 'renderScale', { get: () => viewer.effectiveRenderScale, enumerable: true, configurable: true });
   Object.defineProperty(out, 'renderScaleRequested', { get: () => viewer.renderScale, enumerable: true, configurable: true });
+  // setVideo's current element: the <video> the plane is SHOWING (not one still waiting for its first
+  // frame), else null. Read-only. A player attached to this handle (./player attachPlayer) reads it
+  // to notice another setVideo taking the slot, which no event reports.
+  Object.defineProperty(out, 'videoElement', { get: () => (vid && vid.on ? vid.el : null), enumerable: true, configurable: true });
+  // The tile's canvas, for page chrome that sits beside it (attachPlayer's controls are its siblings).
+  Object.defineProperty(out, 'canvas', { value: canvas, enumerable: true, configurable: true });
   // The current eye offset (after the unit-disc clamp), a fresh object per read.
   Object.defineProperty(out, 'viewOffset', {
     get: () => ({ x: viewer._viewOffset[0], y: viewer._viewOffset[1] }),
@@ -4405,7 +4414,9 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
    * handle.setVideo(src, options) — play a stereo video on THIS handle: no new canvas, layer or
    * session. The splat is hidden and a screen-locked plane on the display rig shows the video, each
    * eye its own half (sbs: left/right, tb: top/bottom); flat (mono), the left half at full
-   * resolution. Applies on the first frame the video has. Resolves to `{ video, remove(), stats() }`;
+   * resolution. Applies on the first frame the video has; `transition: 'crossfade'` (with
+   * `durationMs`, `easing`) dissolves from a video already on the plane, on the GPU, and is a cut
+   * from the splat. Resolves to `{ video, transition, remove(), stats() }`;
    * the page drives transport through `video`. setVideo(null) exits and restores the splat, the rig
    * and its declaration exactly as they were. Throws during an in-flight setSource.
    */
@@ -4432,7 +4443,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     if (owned ? r.autoplay !== false : r.autoplay === true) autoplay(el);
     // The guard state is taken NOW (setSource / setRig refuse from this call on), the pixels change
     // on the first frame the video has.
-    const state = { seq, el, owned, format: r.format, fit: r.fit, vH: r.vH ?? bootFraming.vH, on: false, saved: null, pending: true };
+    const state = { seq, el, owned, format: r.format, fit: r.fit, band: r.band, vH: r.vH ?? bootFraming.vH, on: false, saved: null, pending: true, rectOffs: new Set() };
     if (!prev || !prev.on) vid = state; // a pending one it supersedes is cancelled above
     return first
       .catch(() => null)
@@ -4444,6 +4455,9 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
           // Another video on screen: keep ITS snapshot (the pre-video state), swap the source.
           state.saved = live.saved;
           state.on = true;
+          // S2: the plane outlives this swap; the replaced video's rect subscriptions go with it.
+          for (const off of live.rectOffs) off();
+          live.rectOffs.clear();
           if (live.owned && live.el !== el) releaseOwned(live.el);
           if (state.vH !== live.vH) {
             viewer.vH = state.vH;
@@ -4454,13 +4468,42 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
         } else enterVideo(state);
         vid = state;
         state.pending = false;
+        // A crossfade only dissolves between two videos: from the splat (entry) it is a cut.
+        const fade = live && r.transition.type === 'crossfade' && r.transition.durationMs > 0 ? r.transition : null;
         viewer._videoPlane ||= new VideoPlane(viewer);
-        viewer._videoPlane.setSource(el, { format: state.format, fit: state.fit, vH: state.vH });
+        const faded = viewer._videoPlane.setSource(el, { format: state.format, fit: state.fit, vH: state.vH, band: state.band }, fade);
         const plane = viewer._videoPlane;
         return Object.freeze({
           video: el,
           format: state.format,
           fit: state.fit,
+          /** The letterbox band's aspect, or null. */
+          band: state.band,
+          /**
+           * Where the picture is on screen, in CSS px from the canvas's top-left, clipped to the
+           * canvas: `{ x, y, width, height }`. The bars are the canvas minus this. Null once
+           * another setVideo replaced this one, or before the first drawn frame.
+           */
+          get rect() {
+            return vid === state && viewer._videoPlane === plane ? plane.rect : null;
+          },
+          /** Called with the new rect whenever it changes (resize, band, a new size). Returns an unsubscribe. */
+          onRectChange(cb) {
+            if (typeof cb !== 'function') throw new TypeError('@displayxr/inline3d/splat: onRectChange(cb) — expected a function.');
+            if (vid !== state) return () => {};
+            // S2: never outlives this video — every subscription is dropped at the swap that
+            // replaces it (and with the plane on setVideo(null)).
+            // Each subscription is its own entry on the plane, so calling this twice is harmless.
+            const off = plane.onRect(cb);
+            const unsubscribe = () => {
+              off();
+              state.rectOffs.delete(unsubscribe);
+            };
+            state.rectOffs.add(unsubscribe);
+            return unsubscribe;
+          },
+          /** What this swap did: 'crossfade' only when a fade actually started, else 'cut'. */
+          transition: faded ? 'crossfade' : 'cut',
           /** Exit (setVideo(null)) — a no-op once another setVideo replaced this one. */
           remove: () => (vid === state ? setVideo(null) : Promise.resolve(null)),
           /** Upload accounting: frames drawn with the plane up, and texture uploads (new frames). */