@displayxr/inline3d 1.29.0 → 1.31.0

package/js/inline3d-model.js

@@ -380,6 +380,7 @@ export function addModel(wall, canvas, src, opts = {}) {
     renderScale,
     feather,
     logTag: '[inline3d/model]',
+    viewerEase: opts.viewerEase,
   }).useEyeCamera(EyeCamera, EdgeFeather);
 
   if (envMap) viewer.scene.environment = envMap;

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

@@ -67,6 +67,7 @@ import {
   sequenceSpans,
 } from './inline3d-splat-effects.js';
 import { LiveOutgoing, resolveOutgoingOption, defaultOutgoing, yieldIdle } from './inline3d-splat-live.js';
+import { viewerEaseFor, frameTrackingState } from './inline3d-viewer-ease.js';
 import { VideoPlane, validateSetVideo, PAGE_VIDEO_ERROR, eyeSplit, EYE_SPLIT_UNIFORM, makeSbsMaterial } from './inline3d-splat-video.js';
 import { LayerRigCameras, validateLayerRig, validateLayerRigOptions, DEFAULT_VIEWER_DISTANCE_M } from './inline3d-splat-layer-rig.js';
 import { RigTracker, remapViews, nodePose, sameRig } from './inline3d-splat-rig-map.js';
@@ -817,8 +818,13 @@ export class PlayCanvasSplatViewer {
       sky = false,
       pageCamera = false,
       toneMapping = 'none',
+      viewerEase,
     } = opts;
     this.canvas = canvas;
+    // The tracking-acquisition ease (./inline3d-viewer-ease.js): undefined = the session's
+    // createInline3D({ viewerEase }) default. Built on the first 3D frame, which knows the session.
+    this._viewerEaseOpt = viewerEase;
+    this.viewerEase = null;
     // controls:'page': the PAGE owns the camera (setPageCamera). No orbit, no idle, no fit; the
     // rig node carries the page's matrix instead of the inverse pivot.
     this.pageCamera = pageCamera === true;
@@ -1194,7 +1200,7 @@ export class PlayCanvasSplatViewer {
   }
 
   /** wall.addScene's frame callback. Validate BEFORE drawing; replay the last good frame else. */
-  onFrame(views, layer) {
+  onFrame(views, layer, frame) {
     if (this._disposed) return;
     if (this._mode !== '3d') this.stopMono();
     // The rig these views were located with: Blink chained the rig declared BEFORE this callback,
@@ -1224,6 +1230,9 @@ export class PlayCanvasSplatViewer {
       vps.push(vp);
     }
     this._cacheGood(views, vps);
+    // Ease a tracking acquisition/loss on the copies (never the XRViews), before anything —
+    // the rig map, the layer rig, the live outgoing photo — reads them.
+    (this.viewerEase ||= viewerEaseFor(frame, this._viewerEaseOpt)).apply(this._lastGood.entries, frameTrackingState(frame));
     this._drawEntries(this._lastGood.entries, this._lastGood);
   }
 
@@ -2139,6 +2148,7 @@ export class PlayCanvasSplatViewer {
     if (this._disposed) return;
     const box = this.canvas.getBoundingClientRect();
     if (box.width < 1 || box.height < 1) return;
+    this.viewerEase?.reset(); // a new window size moves every projection: not a viewer jump
     const dpr = Math.min((typeof window !== 'undefined' && window.devicePixelRatio) || 1, 2) * this.renderScale;
     // Clamp to the device's GL limits BEFORE sizing (./inline3d-buffer-limit.js). Measured on an
     // Adreno 740 tablet: MAX_TEXTURE_SIZE 4096, a 5120-wide request silently became a 4096-wide
@@ -3072,6 +3082,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     nearClip: opts.nearClip,
     farClip: opts.farClip,
     sky: opts.sky,
+    viewerEase: opts.viewerEase,
   });
 
   let handle = null;
@@ -3394,9 +3405,9 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
   let initialViewRig = null; // the rig addScene is created with (controls:'page'), else the shorthand
   if (wall && wall.supported) {
     const onFrame = diag
-      ? (views, layer) => {
+      ? (views, layer, frame) => {
           const t = performance.now();
-          viewer.onFrame(views, layer);
+          viewer.onFrame(views, layer, frame);
           diag.frame(views, t); // after the draw: the overlay state is what this frame showed
         }
       : viewer.onFrame;

package/js/inline3d-splat.js

@@ -23,8 +23,9 @@ import { SparkRenderer, SplatMesh } from '@sparkjsdev/spark';
 import { EyeCamera, EdgeFeather, cameraRigFromCamera } from './inline3d-three.js';
 import { SceneViewer, boundsFromPositions } from './inline3d-viewer.js';
 import { readSogCamera } from './inline3d-sog.js';
-import { resolveRevealOption, effectsNotOnSpark, validateEffectCall } from './inline3d-splat-effects.js';
+import { resolveRevealOption, effectsNotOnSpark } from './inline3d-splat-effects.js';
 import { applySplatPerf, splatPerfMeshOptions } from './inline3d-splat-perf.js';
+import { addSplatDeferred } from './inline3d-splat-deferred.js';
 import {
   toArray3,
   canvasNdc,
@@ -36,7 +37,6 @@ import {
   isStreamedUrl,
   STREAMED_NEEDS_PLAYCANVAS,
   resolveControls,
-  normalizeCameraPose,
   declareViewRig,
 } from './inline3d-splat-shared.js';
 import {
@@ -246,6 +246,7 @@ export function addSplat(wall, canvas, src, opts = {}) {
     renderScale,
     feather,
     logTag: '[inline3d/splat]',
+    viewerEase: opts.viewerEase,
   }).useEyeCamera(EyeCamera, EdgeFeather);
 
   // Spark renders through the ordinary three.js pipeline, so splats and meshes co-exist and
@@ -677,149 +678,6 @@ export function addSplat(wall, canvas, src, opts = {}) {
   return out;
 }
 
-/**
- * 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.');
-  }
-}
-
-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;
-}
 
 /**
  * Percentile bounds from the loaded splats — the fallback when no sidecar was supplied.