@displayxr/inline3d 1.30.0 → 1.32.0

package/js/inline3d-viewer-ease.js

@@ -0,0 +1,360 @@
+// inline3d-viewer-ease.js — ease the eye views across a tracking acquisition or loss.
+//
+// THE SNAP THIS REMOVES. While nobody is tracked the session's views come from the runtime's
+// NOMINAL viewer (two eyes straight in front of the window at the nominal distance). The frame a
+// viewer is acquired, the views jump to the tracked eyes — tens to hundreds of millimetres in one
+// frame — and so does everything drawn from them: the per-eye cameras, head parallax, display-rig
+// layers. The reverse happens on a loss wherever the vendor does not animate it. The browser
+// passes the views through and the core SDK deliberately does too (inline3d.js `_frame`), so the
+// ease lives in the SDK's RENDERERS (SceneViewer, the PlayCanvas splat and model viewers), on the
+// matrices they already copy out of every view, and every page that renders through them gets it.
+//
+// WHAT IT DOES. On a trigger, the difference between what was DRAWN last frame and what the
+// session reports now is frozen as an offset, and the offset decays to zero over `durationMs`
+// (smoothstep by default) while the live views keep moving underneath — so the eyes leave from
+// where they were and arrive on the tracked viewer without lagging behind it once the window ends.
+//
+//   pose_out = pose_now + w · A_now · d_local      d_local = A_then⁻¹ · (eye_drawn − eye_now)
+//   proj_out = proj_now + w · (proj_drawn − proj_now)        w = 1 − ease(t / duration)
+//
+// The position offset is held in the VIEW's own frame (A = the pose's 3×3), so a rig the page
+// moves during the ease (orbit, zoom) carries the offset with it. The projection is offset
+// element-wise, and that is exact, not an approximation: every DisplayXR frustum (the display
+// rig's window-relative Kooima and the camera rig's portal, displayxr-common dxr_view_math.c) has
+// its off-axis terms and its focal terms AFFINE in the eye position, with fixed near/far — so the
+// eased (pose, proj) pair is the view the runtime itself would report for the eased eye. A view's
+// frustum still crosses its rig's window exactly, which is what ./inline3d-splat-rig-map.js
+// reads the located rig off.
+//
+// TRIGGERS, in order of trust:
+//   1. `trackingState` edge ('searching' <-> 'tracking', DisplayXR Browser patch 0195+). For
+//      `armMs` after it (the edge frame included) any frame whose eyes move more than `armedJump`
+//      (in eye separations) starts — or restarts — the ease from what was drawn, because the edge
+//      and the jump need not land on the same frame. An edge without a jump changes nothing.
+//   2. Where the browser reports no state ('unknown'), a jump of more than `jump` eye separations
+//      in one frame. A seated viewer's head moves well under that per frame; a nominal ↔ tracked
+//      switch is a multiple of it.
+// Eye positions for the jump test are read off the PROJECTIONS (focal and off-axis terms), in
+// eye-separation units, so the test is blind to rig changes, scene scale and canvas size.
+//
+// WHAT IT LEAVES ALONE. A view-count change (a 2D <-> 3D rendering-mode switch: the eased mode
+// switch, ./inline3d-mode-switch.js, owns that) and a buffer reallocation reset it. One view
+// (mono) is passed through. Replayed (last-good) frames are not re-eased. The panel's own optical
+// switch (lens/backlight state on acquisition) is hardware and is not touched by anything here.
+//
+// Pure arithmetic on Float32Array(16) pairs; no WebXR, no DOM. test/viewer-ease.test.mjs.
+
+/** Default ease window (ms). Long enough to read as a glide, short enough not to feel laggy. */
+export const VIEWER_EASE_DEFAULT_MS = 300;
+/** Default curve: smoothstep (the mode switch's own default; zero velocity at both ends). */
+export const VIEWER_EASE_DEFAULT_EASING = 'smoothstep';
+/** Untracked-state jump detector: eye movement in one frame, in eye separations. */
+export const VIEWER_EASE_JUMP = 0.5;
+/** After a tracking edge: the (lower) per-frame movement that restarts the ease, in separations. */
+export const VIEWER_EASE_ARMED_JUMP = 0.15;
+/** How long after a tracking edge the lower threshold applies (ms). */
+export const VIEWER_EASE_ARM_MS = 600;
+
+const EASINGS = {
+  linear: (t) => t,
+  smoothstep: (t) => t * t * (3 - 2 * t),
+  easeoutcubic: (t) => 1 - (1 - t) ** 3,
+};
+
+const now = () => (typeof performance !== 'undefined' && performance.now ? performance.now() : Date.now());
+
+/**
+ * Resolve a page's `viewerEase` option. `false` / `{ enabled:false }` / `{ durationMs:0 }`
+ * disables; `true` / undefined is the default; an object overrides fields.
+ *
+ * @param {boolean|{enabled?:boolean,durationMs?:number,easing?:string}} [opt]
+ * @returns {{enabled:boolean,durationMs:number,easing:string}}
+ */
+export function resolveViewerEaseOption(opt) {
+  const out = { enabled: true, durationMs: VIEWER_EASE_DEFAULT_MS, easing: VIEWER_EASE_DEFAULT_EASING };
+  if (opt === false) out.enabled = false;
+  else if (opt && typeof opt === 'object') {
+    if (opt.enabled === false) out.enabled = false;
+    if (Number.isFinite(opt.durationMs) && opt.durationMs >= 0) out.durationMs = opt.durationMs;
+    if (typeof opt.easing === 'string') {
+      const k = opt.easing.toLowerCase().replace(/[-_\s]/g, '');
+      if (EASINGS[k]) out.easing = k;
+    }
+  }
+  if (!(out.durationMs > 0)) out.enabled = false;
+  return out;
+}
+
+/** Eye position in window-width units, read off a projection's focal and off-axis terms. */
+function eyeFromProj(P, out) {
+  const p0 = P[0];
+  const p5 = P[5];
+  const aspect = p5 !== 0 ? p0 / p5 : 1; // = H / W for a window-relative frustum
+  out[0] = -P[8] / 2;
+  out[1] = (-P[9] / 2) * aspect;
+  out[2] = p0 / 2;
+  return out;
+}
+
+const dist3 = (a, b) => Math.hypot(a[0] - b[0], a[1] - b[1], a[2] - b[2]);
+
+/** Inverse of the upper-left 3×3 of a column-major 4×4, into a 9-array (column-major). False if singular. */
+function inv3(M, out) {
+  const a = M[0], b = M[4], c = M[8];
+  const d = M[1], e = M[5], f = M[9];
+  const g = M[2], h = M[6], i = M[10];
+  const A = e * i - f * h;
+  const B = -(d * i - f * g);
+  const C = d * h - e * g;
+  const det = a * A + b * B + c * C;
+  if (!(Math.abs(det) > 1e-12)) return false;
+  const k = 1 / det;
+  // row-major inverse entries
+  const r00 = A * k, r01 = -(b * i - c * h) * k, r02 = (b * f - c * e) * k;
+  const r10 = B * k, r11 = (a * i - c * g) * k, r12 = -(a * f - c * d) * k;
+  const r20 = C * k, r21 = -(a * h - b * g) * k, r22 = (a * e - b * d) * k;
+  out[0] = r00; out[3] = r01; out[6] = r02;
+  out[1] = r10; out[4] = r11; out[7] = r12;
+  out[2] = r20; out[5] = r21; out[8] = r22;
+  return true;
+}
+
+/**
+ * One renderer's ease state. Feed it the matrices it is about to draw, once per LIVE frame,
+ * in place; it rewrites them while an ease is running and leaves them untouched otherwise.
+ */
+export class ViewerEase {
+  /**
+   * @param {object} [o]  resolveViewerEaseOption() fields, plus test knobs (`clock`, `jump`,
+   *        `armedJump`, `armMs`).
+   */
+  constructor(o = {}) {
+    const r = resolveViewerEaseOption(o);
+    this.enabled = r.enabled;
+    this.durationMs = r.durationMs;
+    this.easing = r.easing;
+    this.jump = Number.isFinite(o.jump) ? o.jump : VIEWER_EASE_JUMP;
+    this.armedJump = Number.isFinite(o.armedJump) ? o.armedJump : VIEWER_EASE_ARMED_JUMP;
+    this.armMs = Number.isFinite(o.armMs) ? o.armMs : VIEWER_EASE_ARM_MS;
+    this.clock = typeof o.clock === 'function' ? o.clock : now;
+    this.reset();
+    /** What the last apply() did, for diagnostics: { weight, reason: null|'armed-jump'|'jump'|'easing', jump }. */
+    this.last = { weight: 0, reason: null, jump: 0 };
+  }
+
+  /** Change the tuning at run time (the same shapes the option takes). */
+  configure(opt) {
+    const r = resolveViewerEaseOption(opt);
+    this.enabled = r.enabled;
+    this.durationMs = r.durationMs;
+    this.easing = r.easing;
+    if (!this.enabled) this._active = false;
+  }
+
+  /** Forget everything (a view-count change, a buffer reallocation, a mono stretch). */
+  reset() {
+    this._n = 0;
+    this._drawn = []; // per view: { proj, pose } as DRAWN last frame
+    this._seen = []; // per view: eye (window units) as REPORTED last frame
+    this._off = []; // per view: { d: [3] local, dp: Float64Array(16) }
+    this._active = false;
+    this._t0 = 0;
+    this._state = null; // last tracking state seen
+    this._armedUntil = -Infinity;
+    this._eye = [0, 0, 0];
+    this._inv = new Float64Array(9);
+  }
+
+  /** Is an ease running right now? */
+  get active() {
+    return this._active;
+  }
+
+  /**
+   * Ease these entries in place. `entries[i].proj` / `.pose` are column-major Float32Array(16)
+   * (or any 16-array), already holding THIS frame's reported matrices.
+   *
+   * @param {Array<{proj:ArrayLike<number>,pose:ArrayLike<number>}>} entries
+   * @param {'tracking'|'searching'|'unknown'|string|null} [trackingState]
+   * @param {number} [t]  ms; defaults to the clock.
+   * @returns {number} the weight applied this frame (0 = passed through, 1 = fully the old views).
+   */
+  apply(entries, trackingState, t = this.clock()) {
+    const L = this.last;
+    L.weight = 0;
+    L.reason = null;
+    L.jump = 0;
+    const n = entries ? entries.length : 0;
+    if (!this.enabled || n < 2) {
+      if (n !== this._n) this.reset();
+      this._remember(entries, n);
+      return 0;
+    }
+    if (n !== this._n) {
+      // A view-count change is a rendering-mode switch: the mode switch's ramp owns it.
+      this.reset();
+      this._remember(entries, n);
+      this._state = trackingState || null;
+      return 0;
+    }
+
+    // ── triggers ──
+    const state = trackingState === 'tracking' || trackingState === 'searching' ? trackingState : null;
+    const edge = state !== null && this._state !== null && state !== this._state;
+    if (state !== null) this._state = state;
+    if (edge) this._armedUntil = t + this.armMs;
+
+    const jump = this._jump(entries, n);
+    L.jump = jump;
+    // An edge only ARMS: it is the jump that is eased, on whichever frame it lands (the state can
+    // lead the views by a frame). An edge with no jump — a vendor that already animates the eyes —
+    // changes nothing.
+    let trigger = null;
+    if (t <= this._armedUntil && jump > this.armedJump) trigger = 'armed-jump';
+    else if (state === null && jump > this.jump) trigger = 'jump';
+
+    if (trigger) {
+      this._start(entries, n, t);
+      L.reason = trigger;
+    }
+
+    // ── apply ──
+    let w = 0;
+    if (this._active) {
+      const u = this.durationMs > 0 ? (t - this._t0) / this.durationMs : 1;
+      if (u >= 1) this._active = false;
+      else {
+        w = 1 - EASINGS[this.easing](Math.max(0, u));
+        for (let i = 0; i < n; i++) {
+          const e = entries[i];
+          const o = this._off[i];
+          const P = e.pose;
+          const d = o.d;
+          // A_now · d_local, added to the live position.
+          P[12] += w * (P[0] * d[0] + P[4] * d[1] + P[8] * d[2]);
+          P[13] += w * (P[1] * d[0] + P[5] * d[1] + P[9] * d[2]);
+          P[14] += w * (P[2] * d[0] + P[6] * d[1] + P[10] * d[2]);
+          const Q = e.proj;
+          for (let k = 0; k < 16; k++) Q[k] += w * o.dp[k];
+        }
+        if (!L.reason) L.reason = 'easing';
+      }
+    }
+    L.weight = w;
+    this._remember(entries, n);
+    return w;
+  }
+
+  /** Largest per-view eye move since the last frame, in eye separations (0 when unknown). */
+  _jump(entries, n) {
+    if (this._seen.length !== n) return 0;
+    const eye = this._eye;
+    let sep = 0;
+    const a = eyeFromProj(entries[0].proj, [0, 0, 0]);
+    const b = eyeFromProj(entries[n - 1].proj, [0, 0, 0]);
+    sep = dist3(a, b);
+    const prevSep = dist3(this._seen[0], this._seen[n - 1]);
+    // Floor: a typical IPD at this distance (~0.1 of the eye depth), so a vendor pair collapsed
+    // onto one point (separation ~0) does not turn every millimetre into a "jump".
+    const s = Math.max(sep, prevSep, 0.1 * Math.abs((a[2] + b[2]) / 2));
+    if (!(s > 1e-6)) return 0;
+    let m = 0;
+    for (let i = 0; i < n; i++) {
+      eyeFromProj(entries[i].proj, eye);
+      m = Math.max(m, dist3(eye, this._seen[i]));
+    }
+    return m / s;
+  }
+
+  /** Freeze the offset between what was drawn last frame and what is reported now. */
+  _start(entries, n, t) {
+    if (this._drawn.length !== n) return;
+    for (let i = 0; i < n; i++) {
+      const e = entries[i];
+      const D = this._drawn[i];
+      const o = (this._off[i] ||= { d: [0, 0, 0], dp: new Float64Array(16) });
+      const dx = D.pose[12] - e.pose[12];
+      const dy = D.pose[13] - e.pose[13];
+      const dz = D.pose[14] - e.pose[14];
+      if (inv3(e.pose, this._inv)) {
+        const I = this._inv;
+        o.d[0] = I[0] * dx + I[3] * dy + I[6] * dz;
+        o.d[1] = I[1] * dx + I[4] * dy + I[7] * dz;
+        o.d[2] = I[2] * dx + I[5] * dy + I[8] * dz;
+      } else {
+        o.d[0] = dx;
+        o.d[1] = dy;
+        o.d[2] = dz;
+      }
+      for (let k = 0; k < 16; k++) o.dp[k] = D.proj[k] - e.proj[k];
+    }
+    this._active = true;
+    this._t0 = t;
+  }
+
+  /** Keep this frame's drawn matrices and reported eyes for the next one. */
+  _remember(entries, n) {
+    this._n = n;
+    if (!this.enabled || n < 2) {
+      this._drawn.length = 0;
+      this._seen.length = 0;
+      return;
+    }
+    for (let i = 0; i < n; i++) {
+      const e = entries[i];
+      const D = (this._drawn[i] ||= { proj: new Float64Array(16), pose: new Float64Array(16) });
+      for (let k = 0; k < 16; k++) {
+        D.proj[k] = e.proj[k];
+        D.pose[k] = e.pose[k];
+      }
+    }
+    this._drawn.length = n;
+    this._seen.length = n;
+    // The REPORTED eyes: undo this frame's offset from the projection before keeping it.
+    const w = this.last.weight;
+    const raw = (this._raw ||= new Float64Array(16));
+    for (let i = 0; i < n; i++) {
+      const Q = entries[i].proj;
+      const o = this._off[i];
+      if (w > 0 && o) for (let k = 0; k < 16; k++) raw[k] = Q[k] - w * o.dp[k];
+      this._seen[i] = eyeFromProj(w > 0 && o ? raw : Q, this._seen[i] || [0, 0, 0]);
+    }
+  }
+}
+
+/** The session's tracking state as the frame sees it, or null (no frame / old browser). */
+export function frameTrackingState(frame) {
+  try {
+    const s = frame && frame.session ? frame.session.trackingState : undefined;
+    return s === 'tracking' || s === 'searching' || s === 'unknown' ? s : null;
+  } catch {
+    return null;
+  }
+}
+
+// ── session-wide default ──
+// `createInline3D({ viewerEase })` sets the default for every renderer drawing through that
+// session; a renderer's own `viewerEase` option overrides it. Keyed by the XRSession object, so
+// renderers find it from the XRFrame they are handed and need no reference to the manager.
+const SESSION_OPTS = new WeakMap();
+
+/** Record a session's `viewerEase` option (createInline3D does this). */
+export function setSessionViewerEase(session, opt) {
+  if (session && (typeof session === 'object' || typeof session === 'function')) SESSION_OPTS.set(session, opt);
+}
+
+/**
+ * The ViewerEase a renderer should use for frames of this session: its own option when it has
+ * one (anything but undefined), else the session's, else the default (on).
+ */
+export function viewerEaseFor(frame, windowOpt) {
+  let opt = windowOpt;
+  if (opt === undefined) {
+    try {
+      opt = frame && frame.session ? SESSION_OPTS.get(frame.session) : undefined;
+    } catch {
+      opt = undefined;
+    }
+  }
+  return new ViewerEase(opt === true ? undefined : opt);
+}

package/js/inline3d-viewer.js

@@ -72,6 +72,7 @@ import {
   scaleViewport,
   mismatchWarning,
 } from './inline3d-buffer-limit.js';
+import { viewerEaseFor, frameTrackingState } from './inline3d-viewer-ease.js';
 
 const clamp = (v, lo, hi) => (v < lo ? lo : v > hi ? hi : v);
 // NaN/Infinity into a transform silently blanks the tile — three propagates it into the
@@ -281,9 +282,14 @@ export class SceneViewer {
       renderScale = 1,
       feather = 0,
       pitchLimit = PITCH_LIMIT,
+      viewerEase,
     } = opts;
 
     this._THREE = THREE;
+    // 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;
     this.canvas = canvas;
     this.vH = virtualDisplayHeight;
     this.fit = fit;
@@ -681,7 +687,7 @@ export class SceneViewer {
    * stale sub-rect, which smears). A one-frame-stale eye pose is imperceptible; a smear and a
    * black frame are not.
    */
-  onFrame(views, layer) {
+  onFrame(views, layer, frame) {
     if (this._disposed) return;
     // A lazily-activated tile can start weaving after the page already fell back to mono (or
     // after a scroll-away/scroll-back). Take the buffer back to the SBS shape when that happens
@@ -725,7 +731,12 @@ export class SceneViewer {
       vps.push(vp);
     }
 
-    // Validated: this frame WILL draw over everything it clears.
+    // Validated: this frame WILL draw over everything it clears. Copy the matrices first (the
+    // last-good cache), ease a tracking acquisition/loss on the copies, and draw from them, so
+    // the live draw and a later replay are the same numbers.
+    this._cacheGood(views, vps, !eye);
+    const g = this._lastGood;
+    if (eye) (this.viewerEase ||= viewerEaseFor(frame, this._viewerEaseOpt)).apply(g.entries, frameTrackingState(frame));
     const r = this.renderer;
     // getViewport() splits canvas.width; a drawing buffer the browser clamped behind our back
     // (bufferScale().mismatch) gets the same split mapped onto its real size, never canvas.width/2.
@@ -737,7 +748,7 @@ export class SceneViewer {
       r.setViewport(vp.x, vp.y, vp.width, vp.height);
       r.setScissor(vp.x, vp.y, vp.width, vp.height);
       if (eye) {
-        eye.setFromView(views[i]);
+        eye.setFromMatrices(g.entries[i].proj, g.entries[i].pose);
         r.render(this.scene, eye.camera);
       } else {
         r.render(this.scene, this.monoCamera);
@@ -745,7 +756,6 @@ export class SceneViewer {
       if (this._feather) this._feather.render(r, vp);
     }
     r.setScissorTest(false);
-    this._cacheGood(views, vps, !eye);
   }
 
   /**
@@ -977,6 +987,7 @@ export class SceneViewer {
     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(window.devicePixelRatio || 1, 2) * this.renderScale;
     // Clamp to the device's GL limits BEFORE sizing (./inline3d-buffer-limit.js): a store past
     // MAX_TEXTURE_SIZE is silently clamped by the browser while getViewport() keeps splitting

package/js/inline3d.js

@@ -31,6 +31,11 @@
 // three entry points are re-exported below so a page has a single import site.
 import { undock, undockAvailable, undockUrl, tileScreenRect, setUndockLayerResolver } from './inline3d-undock.js';
 export { undock, undockAvailable, undockUrl, tileScreenRect };
+import { setSessionViewerEase } from './inline3d-viewer-ease.js';
+// The tracking-acquisition ease, for pages that render their own addScene from the views.
+export { ViewerEase, resolveViewerEaseOption, frameTrackingState, VIEWER_EASE_DEFAULT_MS } from './inline3d-viewer-ease.js';
+export { DISPLAY_METRICS_DEFAULTS, displayMetricsFrom } from './inline3d-display-metrics.js';
+import { displayMetricsFrom } from './inline3d-display-metrics.js';
 
 // The eased 2D<->3D transition. A pure state machine (no DOM, no WebXR) ported from the native
 // `dxr::ModeSwitch`, so the browser eases the disparity around a mode switch the same way — and in
@@ -130,6 +135,7 @@ const hasViewRig = () => {
 // required — a browser with a partial set is a browser mid-implementation, and treating it as
 // supported would hand a page a `requestRenderingMode is not a function` at the worst moment.
 const DISPLAY_MODE_METHODS = ['getDisplayInfo', 'getRenderingModes', 'requestRenderingMode'];
+
 // The two display events, fired on the XRSession rather than the layer — so a page hears about a
 // mode or hardware-state change even while its tile's layer is closed (lazy mode), and one
 // subscription covers every window in the document.
@@ -558,6 +564,14 @@ function noteRigWinsOverHeight() {
  *        layer; no buffer reallocation) and back on 'tracking', over the mode switch's duration;
  *        'unknown' leaves it where it is. Scene windows are never touched: the page owns those
  *        pixels — listen for `trackingstatechange` and do the same for a scene.
+ * @param {boolean|{enabled?:boolean,durationMs?:number,easing?:string}} [opts.viewerEase]  The
+ *        default, for every SDK renderer drawing through this session (`./viewer`'s SceneViewer,
+ *        `./splat`, `./model`, both engines), of the TRACKING EASE: when a viewer is acquired
+ *        (the views jump from the runtime's nominal viewer to the tracked eyes) or lost, the eye
+ *        views glide from where they were drawn to the new ones over `durationMs` (300) on
+ *        `easing` ('smoothstep' | 'linear' | 'easeOutCubic') instead of snapping in one frame.
+ *        On by default; `false` restores the snap. A renderer's own `viewerEase` option
+ *        overrides this. A page rendering its own addScene uses the exported `ViewerEase`.
  * @returns {Promise<Inline3D | {supported:false, trackingState:'unknown', error?:Error}>} the
  *        manager, which also carries
  *        the display API (`getDisplayInfo` / `getRenderingModes` / `requestRenderingMode` /
@@ -572,6 +586,7 @@ export async function createInline3D(opts = {}) {
     autoChrome = true,
     modeSwitch = null,
     untrackedFallback = 'none',
+    viewerEase,
   } = opts;
   // The unsupported shapes carry `trackingState` too, so a page can read it without branching on
   // `supported` first. There is no on() here to pair with it: nothing would ever fire.
@@ -584,6 +599,7 @@ export async function createInline3D(opts = {}) {
   } catch (e) {
     return { supported: false, trackingState: 'unknown', error: e };
   }
+  if (viewerEase !== undefined) setSessionViewerEase(session, viewerEase);
   let refSpace = null;
   try {
     refSpace = await session.requestReferenceSpace(referenceSpace);
@@ -1075,6 +1091,24 @@ class Inline3D {
        * @returns {Promise<object|null>}
        */
       getDisplayInfo: () => this._layerCall(win, 'getDisplayInfo', 'getDisplayInfo()'),
+      /**
+       * This window in PHYSICAL units: the canvas's size in metres, metres per CSS px, the panel,
+       * the nominal viewer distance and the eye separation — from getDisplayInfo(), with every
+       * value that could not be measured filled from a stated default (see `source`). Never
+       * rejects: no display API, no live layer, no glasses-free display all resolve the defaults.
+       * The canvas size is re-read at each call (call it again after a resize).
+       *
+       * @returns {Promise<object>}
+       */
+      displayMetrics: async () => {
+        let info = null;
+        try {
+          info = await this._layerCall(win, 'getDisplayInfo', 'getDisplayInfo()');
+        } catch {
+          /* no display API / no live layer: the defaults */
+        }
+        return displayMetricsFrom(info, canvas.getBoundingClientRect(), globalThis.devicePixelRatio || 1);
+      },
       /**
        * Every rendering mode the runtime can put this display in, as reported by the runtime:
        * `{modeIndex, modeName, viewCount, viewScaleX, viewScaleY, tileColumns, tileRows,

package/model.d.ts

@@ -2,7 +2,7 @@
 // EXPERIMENTAL — not covered by the 1.x semver promise. See docs/sdk-stability.md.
 
 import type { SceneViewer, SubjectBounds, OrbitPose } from './viewer.js';
-import type { FirstWovenResult } from './index.js';
+import type { FirstWovenResult, ViewerEaseOption } from './index.js';
 import type { PlayCanvasSplatViewer, SplatCameraPose, SplatFrameInfo } from './splat.js';
 
 export interface ModelOptions {
@@ -41,6 +41,13 @@ export interface ModelOptions {
    */
   renderScale?: number;
   feather?: number;
+  /**
+   * The tracking ease (default on): when a viewer is acquired or lost and the views jump (the
+   * runtime's nominal viewer <-> the tracked eyes) the eye cameras glide from where they were
+   * drawn to the new views instead of snapping in one frame. Unset: the session's
+   * `createInline3D({ viewerEase })`, else on. `false` restores the snap.
+   */
+  viewerEase?: ViewerEaseOption;
   /**
    * How the mesh is lit.
    *

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@displayxr/inline3d",
-  "version": "1.30.0",
-  "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).",
+  "version": "1.32.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",
   "main": "./js/inline3d.js",
@@ -65,8 +65,10 @@
   "files": [
     "js/inline3d.js",
     "js/inline3d-undock.js",
+    "js/inline3d-display-metrics.js",
     "js/inline3d-mode-switch.js",
     "js/inline3d-buffer-limit.js",
+    "js/inline3d-viewer-ease.js",
     "js/inline3d-three.js",
     "js/inline3d-viewer.js",
     "js/inline3d-splat.js",
@@ -116,6 +118,7 @@
     "webxr",
     "inline-3d",
     "glasses-free-3d",
+    "spatial-display",
     "stereo",
     "3d-display",
     "lightfield",

package/splat.d.ts

@@ -2,7 +2,7 @@
 // EXPERIMENTAL — not covered by the 1.x semver promise. See docs/sdk-stability.md.
 
 import type { SceneViewer, SubjectBounds, OrbitPose } from './viewer.js';
-import type { FirstWovenResult } from './index.js';
+import type { FirstWovenResult, ViewerEaseOption, DisplayMetrics } from './index.js';
 
 /**
  * The knobs behind `SplatOptions.perf`. Every one is a Spark 2.1.0 setting except `alphaRadius`,
@@ -174,8 +174,11 @@ export interface ResolvedRig {
   focusDistances: { subject_m: number | null; near_m: number | null; far_m: number | null } | null;
   /** Focus distance along the rest camera's view axis — the zero-disparity PLANE. */
   convergence: number;
+  /** In force — `setStereo`'s values when set, else `stereoDefault`'s. */
   ipdFactor: number;
   parallaxFactor: number;
+  /** The asset's own scalars (block `dxr`, else addSplat's options, else 1) — what `setStereo(null)` restores. PlayCanvas backend. */
+  stereoDefault?: { ipdFactor: number; parallaxFactor: number };
 }
 
 /**
@@ -462,6 +465,13 @@ export interface SplatOptions {
   sky?: boolean;
   /** PlayCanvas: a CAP on the projection's far plane (only ever lowers it). Unset: untouched. */
   farClip?: number;
+  /**
+   * The tracking ease (default on): when a viewer is acquired or lost and the views jump (the
+   * runtime's nominal viewer <-> the tracked eyes) the eye cameras glide from where they were
+   * drawn to the new views instead of snapping in one frame. Unset: the session's
+   * `createInline3D({ viewerEase })`, else on. `false` restores the snap.
+   */
+  viewerEase?: ViewerEaseOption;
   /** Camera rig only: the distance in world metres that sits ON the glass. */
   convergence?: number;
   /**
@@ -724,6 +734,41 @@ export interface SplatSetRigDisplayOptions {
   frame?: { center: number[] | { x: number; y: number; z: number }; extent: number[] | { x: number; y: number; z: number } };
 }
 
+/** A rectangle in canvas fractions: origin top-left, y DOWN (a DOM rect / canvas size). */
+export interface SplatCanvasRect {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+/** `handle.setDepthEnvelope`'s options. Metres are on the panel. */
+export interface SplatDepthEnvelopeOptions {
+  /** The out-of-glass cap well inside the frame. Default 0.02. */
+  maxFrontM?: number;
+  /** The cap AT a stage edge / rect edge. Default 0.001 (clamped to `maxFrontM`). */
+  edgeM?: number;
+  /** Ramp width from `edgeM` to `maxFrontM`. Default 0.016. */
+  bandM?: number;
+  /** The window content may come out in. Default (or `null`): the whole canvas. */
+  stage?: SplatCanvasRect | null;
+  /** 2D elements over the canvas to keep flat around; `weight` 0..1 (default 1) fades one in/out. The 8 heaviest are kept. */
+  rects?: Array<SplatCanvasRect & { weight?: number }> | null;
+  /** Viewer distance override; default `nominalViewerPosition.z`, else 0.65. */
+  viewerM?: number | null;
+  /** Canvas physical size override, [w, h]; default the CSS box × the panel's metres per CSS px. */
+  canvasSizeM?: [number, number] | null;
+}
+
+/** `handle.setStereo`'s options. Each a finite number >= 0; `null` = back to the asset's own. */
+export interface SplatStereoOptions {
+  ipdFactor?: number | null;
+  parallaxFactor?: number | null;
+  /** RELATIVE to the asset's own (`rig.stereoDefault`): re-applied to each asset `setSource` brings in. Exclusive with `ipdFactor`; the last one given wins. */
+  ipdScale?: number | null;
+  parallaxScale?: number | null;
+}
+
 /** `setSource`'s options. */
 export interface SplatSourceOptions {
   /** > 0 = a crossfade of this length (the 1.10 option; same as `transition: 'crossfade'`). */
@@ -1010,6 +1055,36 @@ export interface SplatHandle {
    */
   setRig(type: 'display', opts?: SplatSetRigDisplayOptions): Promise<SplatHandle>;
   setRig(type: 'camera' | 'auto'): Promise<SplatHandle>;
+  /**
+   * PlayCanvas backend only — throws on Spark. Live stereo strength: re-declares the rig in force
+   * with these scalars on the next frame, with NO cut (pose, focus and framing stay) — a depth
+   * slider. A key given replaces; a key set to `null` returns to the asset's own value (the SOG
+   * camera block's `dxr`, else addSplat's options, else 1); `setStereo(null)` clears both. Sticky
+   * across `setSource` and `setRig`. On a camera rig the values are ABSOLUTE, exactly like
+   * addSplat's `ipdFactor`/`parallaxFactor`; on a display rig they replace the declared display
+   * rig's factors. `controls:'page'` applies them from the next tick. A stereo video holds its own
+   * 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.
+   */
+  setStereo(opts: SplatStereoOptions | null): SplatHandle;
+  /** This tile in physical units — the core `TileHandle.displayMetrics()`, on the splat handle. Never rejects. */
+  displayMetrics(): Promise<DisplayMetrics>;
+  /**
+   * PlayCanvas backend only — throws on Spark. THE FRAME ENVELOPE: content may come OUT of the
+   * glass only well inside the frame. At each screen spot the out-of-glass cap is
+   * `edgeM + (maxFrontM − edgeM) · smoothstep(0, bandM, distance)`, where `distance` (metres on the
+   * panel) is to the nearest `stage` edge or to any `rects` entry (weighted). A gaussian beyond the
+   * cap slides back along its own ray from the declared camera rig (centre and scale together), so
+   * the 2D picture is unchanged, the sort stays valid and both eyes agree; behind the glass is never
+   * touched. Tile-wide and LIVE: every asset — an incoming one from its first frame, both sides of
+   * a crossfade — is judged through the rig declared now (its convergence, lens, `ipdFactor` ×
+   * `metersToVirtual`, so `setStereo` is accounted for). Camera rigs only (incl. `controls:'page'`);
+   * inert on a display rig and while a stereo video holds the rig. Physical size comes from
+   * `getDisplayInfo()` (see `displayMetrics()`), overridable with `canvasSizeM` / `viewerM`.
+   * A key given replaces; `null` turns it off. Cheap to call per layout change: uniforms only.
+   * docs/splat-effects.md §Depth envelope.
+   */
+  setDepthEnvelope(opts: SplatDepthEnvelopeOptions | null): SplatHandle;
   /**
    * PlayCanvas backend only — throws on Spark, and with `controls:'page'`. Play a stereo video ON
    * this handle: no new canvas, layer or session (docs/playcanvas-adapter.md §setVideo). The splat