@displayxr/inline3d 1.26.0 → 1.27.0

package/CHANGELOG.md

@@ -5,6 +5,25 @@ entry points (`.`, `./three`) are frozen for 1.x, while the **scene subpaths** (
 `./splat`, `./model`) are a preview tier whose options may change in any release. Entries below say
 which tier they touch, because that is what tells you whether an upgrade can move your pixels.
 
+## 1.27.0 — 2026-09-26
+
+Touches the **preview tier** (`./splat`, `engine: 'playcanvas'` only) and adds one optional field
+to the core `XRDisplayInfo` type. A page on a browser that does not report the new field sees no
+change.
+
+- **`setLayerRig`'s default `viewerDistance` now comes from the browser.** Where
+  `XRDisplayInfo.nominalViewerPosition` is reported (DisplayXR Browser patch 0221, Windows and
+  Android), the layer rig's n is its **z** — the runtime's nominal viewer distance for the panel,
+  the value its camera rig is calibrated to — instead of the fixed 0.6 m. The tile asks the frame's
+  `XRDisplayLayer.getDisplayInfo()` once, asynchronously; frames drawn before it answers use 0.6 m.
+  A page's `viewerDistance` still wins, and clearing it (`null`) falls back to the browser's value,
+  then 0.6 m. **Pixels move** on a panel whose nominal distance is not 0.6 m: display-rig objects'
+  pop-out scales by 0.6/n (that was the bug); the contact plane and the 2D picture do not move.
+- **`layerRigState().viewerDistanceSource`** — `'page'` | `'browser'` | `'default'` — says where
+  `viewerDistance` came from, and the WARN line prints it: `viewerDistance=0.45m(browser)`.
+- **Types:** `XRDisplayInfo.nominalViewerPosition?: DOMPointReadOnly` (metres, display space, +z
+  out of the glass; absent when unreported), `SplatLayerRigState.viewerDistanceSource`.
+
 ## 1.26.0 — 2026-09-25
 
 Touches the **preview tier** (`./splat`, `engine: 'playcanvas'` only). Additive; nothing changes

package/index.d.ts

@@ -103,6 +103,16 @@ export interface XRDisplayInfo {
   displayPixelHeight: number;
   recommendedViewScaleX: number;
   recommendedViewScaleY: number;
+  /**
+   * The runtime's NOMINAL viewer position, metres, in display space: origin at the panel
+   * centre, +x right, +y up, +z out of the glass toward the viewer (w = 1). A constant of the
+   * panel — where the runtime seats the viewer when nobody is tracked, and the distance its
+   * camera rig is calibrated to (`z` is that rig's n) — NOT the live eye position.
+   *
+   * Absent on browsers that predate it (DisplayXR Browser patch 0221) and when the runtime
+   * reports nothing usable, so read it as `info.nominalViewerPosition?.z ?? fallback`.
+   */
+  nominalViewerPosition?: DOMPointReadOnly;
 }
 
 /**

package/js/inline3d-splat-layer-rig.js

@@ -16,8 +16,10 @@
 //       view_round_i = view_photo_i · M_i,     proj_round_i = proj_photo_i
 //
 // k = D / (m·n): D the declared convergence (world units), m the declared metersToVirtual, n the
-// nominal viewer distance in metres — the one quantity the browser does not expose (see the
-// design note §5). Everything here is PLAIN ARITHMETIC on arrays, unit-testable without a GPU.
+// nominal viewer distance in metres. n comes from the page's `viewerDistance` if it passed one,
+// else from the browser (XRDisplayInfo.nominalViewerPosition.z, DisplayXR Browser 0221+), else
+// 0.6 m (design note §5, (c)1). Everything here is PLAIN ARITHMETIC on arrays, unit-testable
+// without a GPU.
 
 import { invertAffine } from './inline3d-splat-rig-map.js';
 
@@ -27,6 +29,32 @@ export const LAYER_RIGS = Object.freeze(['display', 'camera']);
 /** Nominal viewer distance (m) when neither the page nor the platform says: the browser's own. */
 export const DEFAULT_VIEWER_DISTANCE_M = 0.6;
 
+/** How many times a tile asks the layer for its display info before giving up (rejections only). */
+const MAX_DISPLAY_INFO_ASKS = 3;
+
+/**
+ * The runtime's nominal viewer DISTANCE n (m) from an XRDisplayInfo, or null when the browser does
+ * not report one. It is the position's **z** — the distance out of the glass along the display
+ * normal — not its length: the runtime's camera rig reads only `nominal_viewer->z`
+ * (displayxr-common dxr_view_math.c, `eye_local.z = m2v·(eye.z − nominal_z)`), and z is what
+ * D/n undoes. A browser without the field, a null info, or a z that is not finite and > 0 → null.
+ */
+export function nominalViewerDistanceFromInfo(info) {
+  const z = info && info.nominalViewerPosition ? info.nominalViewerPosition.z : undefined;
+  return typeof z === 'number' && Number.isFinite(z) && z > 0 ? z : null;
+}
+
+/**
+ * The n the layer rig uses, and where it came from: the page's `viewerDistance` wins ('page'),
+ * then the browser's nominal viewer ('browser'), then DEFAULT_VIEWER_DISTANCE_M ('default').
+ * @returns {{ value: number, source: 'page'|'browser'|'default' }}
+ */
+export function resolveViewerDistance(pageViewerDistance, browserViewerDistance) {
+  if (pageViewerDistance !== null && pageViewerDistance !== undefined) return { value: pageViewerDistance, source: 'page' };
+  if (browserViewerDistance !== null && browserViewerDistance !== undefined) return { value: browserViewerDistance, source: 'browser' };
+  return { value: DEFAULT_VIEWER_DISTANCE_M, source: 'default' };
+}
+
 /** A round eye may not reach the window plane: h(E') is floored at this fraction of D. */
 const MIN_EYE_HEIGHT_FRAC = 1e-3;
 
@@ -45,7 +73,8 @@ export const LAYER_RIG_OPTION_KEYS = Object.freeze(['viewerDistance', 'gain', 'p
 /**
  * setLayerRig / setLayerRigOptions options, validated (throws at the call). Only the keys given
  * are returned: they MERGE into the tile's options. `null` clears a key (back to its default).
- *   viewerDistance  m, > 0     the nominal viewer distance n (default 0.6)
+ *   viewerDistance  m, > 0     the nominal viewer distance n (default: the browser's
+ *                              XRDisplayInfo.nominalViewerPosition.z, else 0.6)
  *   gain            > 0        an explicit rounding gain k instead of D/(m·n)
  *   planeOffset     m, finite  moves the stage TOWARD the viewer by this much on the panel (display
  *                              space): the plane that lands on the glass moves back by offset·D/n
@@ -330,6 +359,11 @@ export class LayerRigCameras {
     this.layers = new Map();
     /** The tile's options: merged across setLayerRig / setLayerRigOptions calls. */
     this.opts = { viewerDistance: null, gain: null, planeOffset: null, planeDistance: null };
+    /** n as the browser reports it (XRDisplayInfo.nominalViewerPosition.z), once known; else null. */
+    this.browserViewerDistance = null;
+    this._infoAsks = 0;
+    this._infoPending = false;
+    this._infoSettled = false;
     this.disabled = false; // the kill switch (diag 'nolayerrig')
     this.cams = { display: [], post: [] };
     this.moved = { display: [], post: [] };
@@ -369,6 +403,41 @@ export class LayerRigCameras {
     for (const [k, v] of Object.entries(o)) this.opts[k] = v;
   }
 
+  /** The n this tile uses right now, and its source ('page' | 'browser' | 'default'). */
+  viewerDistance() {
+    return resolveViewerDistance(this.opts.viewerDistance, this.browserViewerDistance);
+  }
+
+  /**
+   * Called with the frame's XRDisplayLayer: ask it ONCE for the display info and keep the
+   * browser's nominal viewer distance. Asynchronous — frames drawn before it resolves use the
+   * page's value or 0.6 m, and the state's `viewerDistanceSource` says which. A browser without
+   * getDisplayInfo (or without the field) leaves the default in place; a REJECTED ask (e.g. no live
+   * layer yet) is retried on later frames, up to MAX_DISPLAY_INFO_ASKS times.
+   */
+  noteLayer(layer) {
+    if (this._infoSettled || this._infoPending || this._infoAsks >= MAX_DISPLAY_INFO_ASKS) return;
+    if (!layer || typeof layer.getDisplayInfo !== 'function') return;
+    this._infoAsks++;
+    this._infoPending = true;
+    let p;
+    try {
+      p = Promise.resolve(layer.getDisplayInfo());
+    } catch (e) {
+      p = Promise.reject(e);
+    }
+    return p.then(
+      (info) => {
+        this._infoPending = false;
+        this._infoSettled = true;
+        this.browserViewerDistance = nominalViewerDistanceFromInfo(info);
+      },
+      () => {
+        this._infoPending = false;
+      }
+    );
+  }
+
   /** The eye camera entities of the current view path. */
   _eyeCams() {
     const v = this.viewer;
@@ -494,8 +563,9 @@ export class LayerRigCameras {
     L.residual = residual;
     const hasRun = this.sync();
     const frame = cameraRigFrame(rig);
-    const k = frame ? layerRigGain(frame, this.opts) : null;
-    const plane = frame ? layerRigPlane(frame, this.opts) : null;
+    const opts = { ...this.opts, viewerDistance: this.viewerDistance().value };
+    const k = frame ? layerRigGain(frame, opts) : null;
+    const plane = frame ? layerRigPlane(frame, opts) : null;
     L.gain = k;
     L.planeM = plane;
     L.photoConvergenceM = frame ? frame.D : null;
@@ -606,6 +676,7 @@ export class LayerRigCameras {
   /** The public state (handle.layerRigState). */
   state() {
     const L = this.last;
+    const n = this.viewerDistance();
     return {
       display: [...this.requests.keys()],
       disabled: this.disabled,
@@ -613,7 +684,8 @@ export class LayerRigCameras {
       engaged: !!L.engaged,
       rounded: !!L.engaged,
       reason: this.disabled ? 'kill switch (?dxrdiag=nolayerrig)' : L.reason,
-      viewerDistance: this.opts.viewerDistance ?? DEFAULT_VIEWER_DISTANCE_M,
+      viewerDistance: n.value,
+      viewerDistanceSource: n.source,
       gain: L.gain,
       planeM: L.planeM,
       photoConvergenceM: L.photoConvergenceM ?? null,
@@ -634,7 +706,7 @@ export function layerRigLine(st) {
   const n = (x, d = 3) => (x === null || x === undefined ? '-' : Number(x).toFixed(d));
   return (
     `path=${st.path ?? '-'} engaged=${st.engaged} layers=[${st.display.join(', ')}] ` +
-    `viewerDistance=${n(st.viewerDistance, 2)}m gain=${n(st.gain)} planeM=${n(st.planeM)} ` +
+    `viewerDistance=${n(st.viewerDistance, 2)}m(${st.viewerDistanceSource ?? '-'}) gain=${n(st.gain)} planeM=${n(st.planeM)} ` +
     `photoConvergenceM=${n(st.photoConvergenceM)} planeOffset=${n(st.planeOffset)}m ` +
     `located=${st.located === null || st.located === undefined ? '-' : st.located} reason=${st.reason ?? '-'}`
   );

package/js/inline3d-splat-playcanvas.js

@@ -1184,7 +1184,11 @@ export class PlayCanvasSplatViewer {
     if (this._mode !== '3d') this.stopMono();
     // The rig these views were located with: Blink chained the rig declared BEFORE this callback,
     // and the tick below may declare a new one (a focus ease) for the NEXT locate.
-    if (this.layerRigs?.active) this._rigSnap = snapshotRig(this.layerRigSource?.(), this._rigSnap);
+    if (this.layerRigs?.active) {
+      this._rigSnap = snapshotRig(this.layerRigSource?.(), this._rigSnap);
+      // n for the layer rig: the browser's nominal viewer, asked once (async; no-op after).
+      this.layerRigs.noteLayer(layer);
+    }
     // Same moment, for the rig map: the rig these views were most likely located for (a tie-break).
     this._rigAtPull = this.rigTrack ? this.rigTrack.latest : null;
     // BEFORE the tick: a pose the page sets in here is the one this very frame renders.
@@ -3186,7 +3190,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     layerRigState() {
       const lr = viewer.layerRigs;
       if (lr) return lr.state();
-      return { display: [], disabled: false, path: null, engaged: false, rounded: false, reason: 'no layer on the display rig', viewerDistance: DEFAULT_VIEWER_DISTANCE_M, gain: null, planeM: null, photoConvergenceM: null, planeOffset: 0, located: null };
+      return { display: [], disabled: false, path: null, engaged: false, rounded: false, reason: 'no layer on the display rig', viewerDistance: DEFAULT_VIEWER_DISTANCE_M, viewerDistanceSource: 'default', gain: null, planeM: null, photoConvergenceM: null, planeOffset: 0, located: null };
     },
     /**
      * An unlit material showing the left half of `texture` to left-eye views and the right half to

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@displayxr/inline3d",
-  "version": "1.26.0",
+  "version": "1.27.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).",
   "type": "module",
   "types": "./index.d.ts",

package/splat.d.ts

@@ -185,7 +185,11 @@ export interface ResolvedRig {
  * viewer's. docs/proposals/layer-display-rig.md.
  */
 export interface SplatLayerRigOptions {
-  /** Nominal viewer distance in metres (default 0.6, the browser's own nominal). */
+  /**
+   * Nominal viewer distance n in metres. Default: the browser's
+   * `XRDisplayInfo.nominalViewerPosition.z` where it reports one, else 0.6. Passing it pins n
+   * (see {@link SplatLayerRigState.viewerDistanceSource}).
+   */
   viewerDistance?: number | null;
   /** An explicit gain k instead (1 = exactly the photo rig; larger = rounder). */
   gain?: number | null;
@@ -216,7 +220,14 @@ export interface SplatLayerRigState {
   rounded: boolean;
   /** Why not engaged (or what is wrong with some layers while engaged); null when all is well. */
   reason: string | null;
+  /** The n in use (metres). */
   viewerDistance: number;
+  /**
+   * Where `viewerDistance` came from: the page's option, the browser's reported nominal viewer
+   * (`XRDisplayInfo.nominalViewerPosition.z`, asked once per tile, asynchronously — early frames
+   * may read 'default' before it lands), or the 0.6 m fallback.
+   */
+  viewerDistanceSource: 'page' | 'browser' | 'default';
   /** The gain the last frame used (null off a camera rig). */
   gain: number | null;
   /** The plane that lands on the glass, as a distance from the photo's camera (world units). */