@displayxr/inline3d 1.23.0 → 1.25.0

package/js/inline3d-splat-diag.js

@@ -30,6 +30,15 @@
 //              pick index. Tests "the page's picks are what blocks the main thread".
 //   nolayerrig — handle.setLayerRig is recorded but never applied: every layer stays on the eye
 //              camera and the photo's camera rig (the pre-1.23 path, byte for byte).
+//   oldrig   — no rig tracking (./inline3d-splat-rig-map.js): the views are drawn as the runtime
+//              located them, and a live outgoing photo goes back on the pre-1.24 node chain (which
+//              scales its disparity by the two rigs' window ratio at the swap). A/B for "the
+//              outgoing photo jumps when the incoming rig is declared".
+//
+// Per frame, `rigAt` / `rigIn` / `rigOut` say which declared rig the views were located for
+// (the tracker's id; null = none matched), which rig the current photo was drawn through
+// (`+` = remapped to it) and how the live outgoing photo was drawn ('own' = its rig as located,
+// 'remapped', 'eye', 'chain'; null = no live outgoing).
 //
 // WHAT RUNS ON THE MAIN THREAD, per transition phase (the fifth cause: a stall at the swap's END
 // that is not the SDK's transition at all):
@@ -44,7 +53,7 @@
 //     after it (the page's continuation of `await setSource`).
 
 /** The switches `diag` / `?dxrdiag` understand, besides the plain on values. */
-export const DIAG_SWITCHES = Object.freeze(['norig', 'frozen', 'nowarm', 'cold', 'nooverlay', 'oldpick', 'nolayerrig']);
+export const DIAG_SWITCHES = Object.freeze(['norig', 'frozen', 'nowarm', 'cold', 'nooverlay', 'oldpick', 'nolayerrig', 'oldrig']);
 const ON_TOKENS = new Set(['1', 'on', 'true', 'yes']);
 
 /**
@@ -191,6 +200,7 @@ export class DiagRecorder {
     this._frameNo = 0;
     this._open = null; // the transition being recorded
     this.imageState = null; // () => { overlay: 'none' | 'frozen' | 'live', w }
+    this.rigState = null; // () => { at, in, out } (see the header)
     this.longTasks = [];
     this._lto = null;
     this.rigLocked = null; // norig: the summary of the rig kept
@@ -373,6 +383,7 @@ export class DiagRecorder {
     this._lastFrameAt = t;
     this._frameNo++;
     const img = this.imageState ? safe(this.imageState) : null;
+    const rs = this.rigState ? safe(this.rigState) : null;
     const f = {
       n: this._frameNo,
       t: round1(t),
@@ -388,6 +399,9 @@ export class DiagRecorder {
       afterRig: this._frameNo - this._rigFrame <= 3,
       img: img ? img.overlay : 'none',
       imgW: img ? round4(img.w) : 0,
+      rigAt: rs ? rs.at : null,
+      rigIn: rs ? rs.in : null,
+      rigOut: rs ? rs.out : null,
     };
     this.frames.push(f);
     if (this.frames.length > FRAME_CAP) this.frames.splice(0, this.frames.length - FRAME_CAP);

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

@@ -19,6 +19,8 @@
 // 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.
 
+import { invertAffine } from './inline3d-splat-rig-map.js';
+
 /** handle.setLayerRig's rigs. 'camera' is the default every layer starts on. */
 export const LAYER_RIGS = Object.freeze(['display', 'camera']);
 
@@ -37,9 +39,41 @@ function rotate(q, v) {
   return [v[0] + w * tx + (y * tz - z * ty), v[1] + w * ty + (z * tx - x * tz), v[2] + w * tz + (x * ty - y * tx)];
 }
 
+/** The option keys setLayerRig / setLayerRigOptions take (the tile-wide rounding + plane). */
+export const LAYER_RIG_OPTION_KEYS = Object.freeze(['viewerDistance', 'gain', 'planeOffset', 'planeDistance']);
+
+/**
+ * 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)
+ *   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
+ *   planeDistance   > 0        the plane that lands on the glass, as a distance from the photo's
+ *                              camera in world units (wins over planeOffset)
+ */
+export function validateLayerRigOptions(o = {}, who = 'setLayerRig') {
+  if (o === null || typeof o !== 'object') throw new TypeError(`@displayxr/inline3d/splat: ${who} options must be an object.`);
+  const unknown = Object.keys(o).filter((k) => !LAYER_RIG_OPTION_KEYS.includes(k));
+  if (unknown.length) throw new Error(`@displayxr/inline3d/splat: ${who} — unknown option(s) ${unknown.join(', ')}; expected ${LAYER_RIG_OPTION_KEYS.join(', ')}.`);
+  const out = {};
+  for (const k of LAYER_RIG_OPTION_KEYS) {
+    if (o[k] === undefined) continue;
+    if (o[k] === null) {
+      out[k] = null;
+      continue;
+    }
+    const v = o[k];
+    const ok = k === 'planeOffset' ? Number.isFinite(v) : Number.isFinite(v) && v > 0;
+    if (!ok) throw new Error(`@displayxr/inline3d/splat: ${who} — bad ${k}: ${v}.`);
+    out[k] = v;
+  }
+  return out;
+}
+
 /**
  * setLayerRig's arguments, validated (throws at the call).
- * @returns {{ rig: 'display'|'camera', viewerDistance: number|null, gain: number|null }}
+ * @returns {{ rig: 'display'|'camera', opts: object }}
  */
 export function validateLayerRig(layer, rig, o = {}) {
   if (!(typeof layer === 'string' && layer.length) && !(Number.isInteger(layer) && layer >= 0) && !(layer && typeof layer === 'object' && Number.isInteger(layer.id))) {
@@ -48,13 +82,7 @@ export function validateLayerRig(layer, rig, o = {}) {
   if (!LAYER_RIGS.includes(rig)) {
     throw new Error(`@displayxr/inline3d/splat: setLayerRig — rig "${rig}", expected ${LAYER_RIGS.map((r) => `'${r}'`).join(' or ')}.`);
   }
-  if (o === null || typeof o !== 'object') throw new TypeError('@displayxr/inline3d/splat: setLayerRig options must be an object.');
-  const num = (k) => {
-    if (o[k] === undefined) return null;
-    if (!Number.isFinite(o[k]) || !(o[k] > 0)) throw new Error(`@displayxr/inline3d/splat: setLayerRig — bad ${k}: ${o[k]}.`);
-    return o[k];
-  };
-  return { rig, viewerDistance: num('viewerDistance'), gain: num('gain') };
+  return { rig, opts: validateLayerRigOptions(o) };
 }
 
 /**
@@ -75,11 +103,24 @@ export function cameraRigFrame(rig) {
 
 /** k = D / (m·n), or the caller's explicit gain. */
 export function layerRigGain(frame, { viewerDistance = null, gain = null } = {}) {
-  if (gain !== null) return gain;
-  const n = viewerDistance !== null ? viewerDistance : DEFAULT_VIEWER_DISTANCE_M;
+  if (gain !== null && gain !== undefined) return gain;
+  const n = viewerDistance !== null && viewerDistance !== undefined ? viewerDistance : DEFAULT_VIEWER_DISTANCE_M;
   return frame.D / (frame.m * n);
 }
 
+/**
+ * The plane that lands on the GLASS, as a distance from the photo's camera (world units): the
+ * convergence distance D by default; `planeDistance` if given; else D·(1 + planeOffset/n) — a
+ * stage moved toward the viewer by `planeOffset` metres on the panel (near the plane the round rig
+ * maps world depth to panel depth at n/D). Always > 0.
+ */
+export function layerRigPlane(frame, { viewerDistance = null, planeOffset = null, planeDistance = null } = {}) {
+  if (planeDistance !== null && planeDistance !== undefined) return planeDistance;
+  if (planeOffset === null || planeOffset === undefined || planeOffset === 0) return frame.D;
+  const n = viewerDistance !== null && viewerDistance !== undefined ? viewerDistance : DEFAULT_VIEWER_DISTANCE_M;
+  return Math.max(frame.D * 1e-3, frame.D * (1 + planeOffset / n));
+}
+
 /**
  * The window-fixing shear for one eye, as a column-major 4×4 (and its inverse), in the space the
  * declared rig and the views share.
@@ -173,27 +214,47 @@ export function invertRigid(m, out = new Float64Array(16)) {
 }
 
 /**
- * The round views for one frame: for each runtime view pose P_i (camera → rig space, rigid),
- * `viewInv = M_i⁻¹ · P_i` and `view = P_i⁻¹ · M_i` — what RenderView.setView takes. Null (the
- * caller keeps the photo views) when there is nothing to round: no camera rig, fewer than two
- * views, or a gain of exactly 1.
+ * The round views for one frame: for each runtime view pose P_i (camera → rig space),
+ * `viewInv = S⁻¹ · M_i⁻¹ · P_i` and `view = P_i⁻¹ · M_i · S` — what RenderView.setView takes.
+ *
+ * S is the uniform scale by σ = D / plane about the photo camera N0: it sends the plane that
+ * should land on the glass (`plane`, a distance from N0) onto the photo's window plane, and every
+ * ray from N0 onto itself — so at the nominal viewpoint the picture is unchanged and only the
+ * depth that lands on the glass moves. Exact (a portal through the window at `plane`, seen from
+ * N0 + k·D/plane·(E − N0) … mapped by S onto the photo's own portal). σ = 1 without an offset.
+ *
+ * Null (the caller keeps the photo views) when there is nothing to do: no camera rig, fewer than
+ * two views, or a gain of exactly 1 with no plane offset.
  */
-export function roundViews(entries, frame, k, into = []) {
-  if (!frame || !entries || entries.length < 2 || !(k > 0) || k === 1) return null;
+export function roundViews(entries, frame, k, into = [], plane = frame ? frame.D : 1) {
+  const sigma = frame && plane > 0 ? frame.D / plane : 1;
+  if (!frame || !entries || entries.length < 2 || !(k > 0) || (k === 1 && sigma === 1)) return null;
   into.length = entries.length;
+  const S = scaleAbout(frame.N0, sigma);
+  const Sinv = scaleAbout(frame.N0, 1 / sigma);
   for (let i = 0; i < entries.length; i++) {
     const P = entries[i].pose;
     const o = (into[i] ||= { viewInv: new Float64Array(16), view: new Float64Array(16), M: new Float64Array(16), Minv: new Float64Array(16), eye: [0, 0, 0] });
     const { Eround } = windowShear([P[12], P[13], P[14]], frame, k, o.M, o.Minv);
-    o.eye[0] = Eround[0];
-    o.eye[1] = Eround[1];
-    o.eye[2] = Eround[2];
-    mul4(o.Minv, P, o.viewInv);
-    mul4(invertRigid(P), o.M, o.view);
+    // The virtual eye in rig space: S⁻¹(E′).
+    for (let a = 0; a < 3; a++) o.eye[a] = frame.N0[a] + (Eround[a] - frame.N0[a]) / sigma;
+    mul4(Sinv, mul4(o.Minv, P), o.viewInv);
+    mul4(mul4(invertAffine(P), o.M), S, o.view); // P is rigid, or affine once remapped to the declared rig (./inline3d-splat-rig-map.js)
   }
   return into;
 }
 
+/** X ↦ C + s·(X − C), column-major. */
+function scaleAbout(C, s, out = new Float64Array(16)) {
+  out.fill(0);
+  out[0] = out[5] = out[10] = s;
+  out[12] = C[0] * (1 - s);
+  out[13] = C[1] * (1 - s);
+  out[14] = C[2] * (1 - s);
+  out[15] = 1;
+  return out;
+}
+
 /**
  * Split a layer composition into contiguous RUNS for per-rig cameras. `entries` is the
  * composition's sublayer list as layer ids, in draw order (opaque and transparent sublayers both
@@ -246,178 +307,335 @@ export function layerRuns(entries, display, eyeLayers) {
 
 // ── the engine side ──────────────────────────────────────────────────────────────────────────
 
+/** How many state lines the layer rig may WARN per tile (first 3D frame + every change). */
+const MAX_STATE_WARNS = 12;
+
+/** Name of a camera component's entity, for a reason string. */
+const camName = (c) => c?.entity?.name || c?.name || '(unnamed camera)';
+
 /**
- * The per-rig cameras of one tile. Owned by the viewer; `sync` + `frame` are called by its draw.
- * The eye camera keeps its `layers` minus what moved; `restore()` puts them back.
+ * The per-rig cameras of one tile. Owned by the viewer; `sync` + `frame` are called by its draw,
+ * on EVERY view path:
+ *   renderviews — the eye camera draws N RenderViews; each run is ONE camera with N RenderViews.
+ *   ncamera     — the fallback: one eye camera per view (rect + projection override); each run is
+ *                 N cameras the same way, the display run's projections carrying the shear.
+ * The eye camera(s) keep their `layers` minus what moved; `restore()` puts them back.
  */
 export class LayerRigCameras {
   constructor(viewer) {
     this.viewer = viewer;
-    /** What the page asked for: name or id → { viewerDistance, gain }. */
+    /** What the page asked for: name or id → true. */
     this.requests = new Map();
-    /** Those, resolved: layer id → options (the ones present in the composition right now). */
+    /** Those, resolved: layer id → the caller's key (the ones the eye camera draws right now). */
     this.layers = new Map();
-    /** The gain options in force (the last setLayerRig call's — one gain per tile). */
-    this.opts = {};
+    /** The tile's options: merged across setLayerRig / setLayerRigOptions calls. */
+    this.opts = { viewerDistance: null, gain: null, planeOffset: null, planeDistance: null };
     this.disabled = false; // the kill switch (diag 'nolayerrig')
-    this.cams = { display: null, post: null };
+    this.cams = { display: [], post: [] };
     this.moved = { display: [], post: [] };
     this._key = '';
     this._rvs = { display: [], post: [] };
     this._round = [];
-    /** Diagnostics: what the last frame did. */
-    this.last = { rounded: false, gain: null, views: 0 };
+    this._syncReason = null;
+    this._warns = 0;
+    this._warnKey = '';
+    /** What the last drawn frame did (layerRigState reads it). */
+    this.last = { path: null, engaged: false, reason: 'no frame drawn yet', gain: null, planeM: null, views: 0, located: null, rounded: false };
   }
 
   get active() {
     return !this.disabled && this.requests.size > 0;
   }
 
-  /** Resolve a name / id / pc.Layer to an id in this tile's composition (null if unknown). */
-  resolve(layer) {
+  /** Resolve a name / id / pc.Layer to a layer of this tile's composition (null if unknown). */
+  resolve(key) {
     const comp = this.viewer.app?.scene?.layers;
     if (!comp) return null;
-    if (layer && typeof layer === 'object') return layer.id;
-    if (Number.isInteger(layer)) return layer;
-    const l = comp.getLayerByName?.(layer);
-    return l ? l.id : null;
+    if (Number.isInteger(key)) return comp.getLayerById?.(key) || { id: key };
+    return comp.getLayerByName?.(key) || null;
   }
 
-  /**
-   * Record a request by the caller's key (name, id): resolved against the composition on every
-   * sync, so a layer the page adds AFTER calling setLayerRig is picked up when it appears.
-   */
-  set(key, rig, o) {
+  /** Record a request by the caller's key (name, id); resolved on every sync. */
+  set(key, rig, o = {}) {
     const k = key && typeof key === 'object' ? key.id : key;
-    if (rig === 'display') this.requests.set(k, o);
+    if (rig === 'display') this.requests.set(k, true);
     else this.requests.delete(k);
-    this.opts = o;
+    this.setOptions(o);
     this._key = ''; // re-split on the next draw
   }
 
-  _resolveAll() {
-    this.layers.clear();
-    for (const [k, o] of this.requests) {
-      const id = this.resolve(k);
-      if (id !== null && id !== undefined) this.layers.set(id, o);
-    }
+  /** Merge options (validated by the caller): a key given replaces, `null` clears. */
+  setOptions(o = {}) {
+    for (const [k, v] of Object.entries(o)) this.opts[k] = v;
+  }
+
+  /** The eye camera entities of the current view path. */
+  _eyeCams() {
+    const v = this.viewer;
+    if (v._viewPath === 'cameras') return (v._views || []).filter((c) => c?.camera);
+    return v.eye?.camera ? [v.eye] : [];
   }
 
   _makeCam(name, priority) {
     const v = this.viewer;
-    const cam = v._makeCamera(name, null);
+    const cam = v._makeCamera(name, v._viewPath === 'cameras' && v.pc?.Vec4 ? new v.pc.Vec4(0, 0, 1, 1) : null);
     cam.camera.priority = priority;
     cam.camera.clearColorBuffer = false;
     cam.camera.clearDepthBuffer = false;
     cam.camera.clearStencilBuffer = false;
     cam.camera.frustumCulling = false;
     cam.camera.layers = [];
+    cam._dxrLayerRig = true;
+    if (v._viewPath === 'cameras') {
+      cam._dxrProj = new Float64Array(16);
+      cam.camera.calculateProjection = (out) => out.set(cam._dxrProj);
+    }
     return cam;
   }
 
-  /** Re-split the composition when the display set, the eye's layers or the composition moved. */
+  /** Ensure `n` cameras for a run (1 on renderviews, one per view on ncamera). */
+  _runCams(run, n, priority) {
+    const list = this.cams[run];
+    while (list.length < n) list.push(this._makeCam(`inline3d-eye-${run}${list.length ? `-${list.length}` : ''}`, priority));
+    return list;
+  }
+
+  /**
+   * Re-split the composition when the display set, the eye's layers or the composition moved.
+   * Returns whether a display run exists; `_syncReason` says why not.
+   */
   sync() {
     const v = this.viewer;
-    const eyeCam = v.eye?.camera;
+    const eyes = this._eyeCams();
     const comp = v.app?.scene?.layers;
-    if (!eyeCam || !comp) return false;
     if (!this.active) {
       if (this.moved.display.length || this.moved.post.length) this.restore();
+      this._syncReason = this.disabled ? 'kill switch (?dxrdiag=nolayerrig)' : 'no layer on the display rig';
       return false;
     }
-    this._resolveAll();
-    const entries = (comp.layerList || []).map((l) => l.id);
-    const eyeLayers = [...(eyeCam.layers || []), ...this.moved.display, ...this.moved.post];
-    const key = `${[...this.layers.keys()].join(',')}|${entries.join(',')}|${(eyeCam.layers || []).join(',')}`;
-    if (key === this._key) return this.moved.display.length > 0;
-    const runs = layerRuns(entries, new Set(this.layers.keys()), eyeLayers);
-    if (runs.interleaved.length && !this._warnedInterleaved) {
-      this._warnedInterleaved = true;
-      console.warn(
-        `[inline3d/splat] setLayerRig: layer(s) ${runs.interleaved.join(', ')} sit BETWEEN display-rig ` +
-          'sublayers; they are drawn before them (with the eye camera). Move them before or after the display layers.',
-      );
+    if (!eyes.length || !comp) {
+      this._syncReason = 'engine not ready';
+      return false;
     }
-    this.moved.display = runs.display;
-    this.moved.post = runs.post;
-    eyeCam.layers = runs.pre;
-    if (runs.display.length) {
-      this.cams.display ||= this._makeCam('inline3d-eye-display', 1);
-      this.cams.display.camera.layers = runs.display;
+    const ref = eyes[0].camera;
+    const eyeLayers = [...(ref.layers || []), ...this.moved.display, ...this.moved.post];
+    const orphans = []; // display layers NO camera draws: ours to draw (nobody else can lose them)
+    const entries = (comp.layerList || []).map((l) => l.id);
+    // Resolve every request; a layer the eye camera does not draw cannot be moved (another camera
+    // — the page's own, a reflection pass — draws it, or none does): say so, never silently.
+    this.layers.clear();
+    const missing = [];
+    const foreign = [];
+    for (const key of this.requests.keys()) {
+      const layer = this.resolve(key);
+      if (!layer) {
+        missing.push(`"${key}" is not in the tile's layer composition`);
+        continue;
+      }
+      if (!eyeLayers.includes(layer.id)) {
+        const by = (layer.cameras || []).filter((c) => !c?.entity?._dxrLayerRig).map(camName);
+        if (by.length) {
+          // Another camera (the page's own, a reflection pass) draws it: taking it away could break
+          // that camera's output, so it is left alone — and said.
+          foreign.push(`"${key}" is drawn by ${by.join(', ')}, not by the tile's eye camera — draw it with handle.engine.camera (or pass it to setLayerRig without adding it to any camera)`);
+          continue;
+        }
+        orphans.push(layer.id);
+      }
+      this.layers.set(layer.id, key);
     }
-    if (runs.post.length) {
-      this.cams.post ||= this._makeCam('inline3d-eye-post', 2);
-      this.cams.post.camera.layers = runs.post;
+    const problems = [...missing, ...foreign];
+    const key = `${eyes.length}|${[...this.layers.keys()].join(',')}|${entries.join(',')}|${(ref.layers || []).join(',')}|${problems.length}`;
+    if (key !== this._key) {
+      const runs = layerRuns(entries, new Set(this.layers.keys()), [...eyeLayers, ...orphans]);
+      if (runs.interleaved.length && !this._warnedInterleaved) {
+        this._warnedInterleaved = true;
+        console.warn(
+          `[inline3d/splat] setLayerRig: layer(s) ${runs.interleaved.join(', ')} sit BETWEEN display-rig ` +
+            'sublayers; they are drawn before them (with the eye camera). Move them before or after the display layers.',
+        );
+      }
+      this.moved.display = runs.display;
+      this.moved.post = runs.post;
+      for (const e of eyes) e.camera.layers = runs.pre.slice();
+      this._runLayers = { display: runs.display, post: runs.post };
+      this._key = `${eyes.length}|${[...this.layers.keys()].join(',')}|${entries.join(',')}|${runs.pre.join(',')}|${problems.length}`;
     }
-    if (this.cams.display) this.cams.display.enabled = runs.display.length > 0;
-    if (this.cams.post) this.cams.post.enabled = runs.post.length > 0;
-    this._key = `${[...this.layers.keys()].join(',')}|${entries.join(',')}|${eyeCam.layers.join(',')}`;
-    return runs.display.length > 0;
+    this._problems = problems;
+    this._syncReason = this.moved.display.length ? null : problems.join('; ') || 'no display layer resolved';
+    return this.moved.display.length > 0;
   }
 
-  /** Every moved layer back on the eye camera, run cameras off (the kill switch / last layer off). */
+  /** Every moved layer back on the eye camera(s), run cameras off (the kill switch / last layer off). */
   restore() {
-    const eyeCam = this.viewer.eye?.camera;
-    if (eyeCam) {
-      const back = [...this.moved.display, ...this.moved.post];
-      eyeCam.layers = [...(eyeCam.layers || []), ...back.filter((id) => !(eyeCam.layers || []).includes(id))];
+    const back = [...this.moved.display, ...this.moved.post];
+    for (const e of this._eyeCams()) {
+      const cur = e.camera.layers || [];
+      e.camera.layers = [...cur, ...back.filter((id) => !cur.includes(id))];
     }
     this.moved = { display: [], post: [] };
-    if (this.cams.display) this.cams.display.enabled = false;
-    if (this.cams.post) this.cams.post.enabled = false;
+    for (const list of Object.values(this.cams)) for (const c of list) c.enabled = false;
     this._key = '';
   }
 
   /**
-   * Per drawn frame, after the eye camera's RenderViews are set. `rig` is the descriptor the
-   * runtime located these views with (the viewer snapshots it before the tick can declare anew).
+   * Per drawn frame, after the eye camera(s) are set up. `rig` is the descriptor the runtime
+   * located these views with; `located` whether the views were VERIFIED against it (the rig map
+   * read it off the views) — false means it is the SDK's own record, unverified. Records what
+   * happened in `last` and WARNs one line on the first 3D frame and on every change.
    */
-  frame(entries, rect, f, rig) {
-    const pc = this.viewer.pc;
-    this.last.rounded = false;
-    this.last.views = entries.length;
+  frame(entries, rect, f, rig, { located = null, residual = null } = {}) {
+    const v = this.viewer;
+    const ncam = v._viewPath === 'cameras';
+    const L = this.last;
+    L.views = entries.length;
+    L.path = entries.length < 2 ? 'mono' : ncam ? 'ncamera' : 'renderviews';
+    L.located = located;
+    L.residual = residual;
+    const hasRun = this.sync();
     const frame = cameraRigFrame(rig);
-    const k = frame ? layerRigGain(frame, this.opts || {}) : null;
-    const round = frame ? roundViews(entries, frame, k, this._round) : null;
-    this.last.gain = k;
-    for (const run of ['display', 'post']) {
-      const cam = this.cams[run];
-      if (!cam || !cam.enabled) continue;
-      const rvs = this._rvs[run];
-      if (rvs.length !== entries.length) {
-        rvs.length = 0;
-        for (let i = 0; i < entries.length; i++) rvs.push(new pc.RenderView());
-        cam.camera.camera.xrViews = rvs.slice();
-      }
-      const r = run === 'display' ? round : null;
-      for (let i = 0; i < entries.length; i++) {
-        const e = entries[i];
-        if (r) rvs[i].setView(e.proj, r[i].viewInv, r[i].view);
-        else rvs[i].setView(e.proj, e.pose);
-        const [x, y, w, h] = rect(e);
-        rvs[i].setViewport(x, y, w, h);
+    const k = frame ? layerRigGain(frame, this.opts) : null;
+    const plane = frame ? layerRigPlane(frame, this.opts) : null;
+    L.gain = k;
+    L.planeM = plane;
+    L.photoConvergenceM = frame ? frame.D : null;
+    const round = hasRun && frame ? roundViews(entries, frame, k, this._round, plane) : null;
+    let reason = null;
+    if (!hasRun) reason = this._syncReason;
+    else if (entries.length < 2) reason = 'mono (one view): nothing to round — identical to the photo rig';
+    else if (!rig) reason = 'no declared view rig for these views';
+    else if (!frame) reason = rig.type === 'camera' ? 'camera rig with no finite convergence' : `the declared rig is a ${rig.type || 'non-camera'} rig (setRig('display') / setVideo): already the display rig`;
+    else if (!round) reason = 'gain 1 and no plane offset: identical to the photo rig';
+    L.engaged = !!round;
+    L.rounded = L.engaged;
+    L.reason = reason || (this._problems?.length ? `engaged; ${this._problems.join('; ')}` : null);
+    if (hasRun) {
+      const nViews = entries.length;
+      for (const run of ['display', 'post']) {
+        const layers = this._runLayers?.[run] || [];
+        const need = layers.length ? (ncam ? nViews : 1) : 0;
+        const list = need ? this._runCams(run, need, run === 'display' ? 1 : 2) : this.cams[run];
+        for (let c = 0; c < list.length; c++) {
+          list[c].enabled = c < need;
+          if (c < need) list[c].camera.layers = layers;
+        }
+        if (!need) continue;
+        const r = run === 'display' ? round : null;
+        if (ncam) this._frameNcam(list, entries, rect, r, run);
+        else this._frameRenderViews(list[0], entries, rect, f, r, run);
+        if (run === 'display') for (let c = 0; c < need; c++) list[c].camera.clearDepthBuffer = !!r; // two spaces never share a depth test
       }
-      if (cam._frustumKey !== this.viewer._frustumKey) {
-        cam._frustumKey = this.viewer._frustumKey;
-        cam.camera.camera.setXrProperties({ ...f, horizontalFov: false });
+    }
+    this._warnState();
+  }
+
+  _frameRenderViews(cam, entries, rect, f, r, run) {
+    const pc = this.viewer.pc;
+    const rvs = this._rvs[run];
+    if (rvs.length !== entries.length) {
+      rvs.length = 0;
+      for (let i = 0; i < entries.length; i++) rvs.push(new pc.RenderView());
+      cam.camera.camera.xrViews = rvs.slice();
+    }
+    for (let i = 0; i < entries.length; i++) {
+      const e = entries[i];
+      if (r) rvs[i].setView(e.proj, r[i].viewInv, r[i].view);
+      else rvs[i].setView(e.proj, e.pose);
+      const [x, y, w, h] = rect(e);
+      rvs[i].setViewport(x, y, w, h);
+    }
+    if (cam._frustumKey !== this.viewer._frustumKey) {
+      cam._frustumKey = this.viewer._frustumKey;
+      cam.camera.camera.setXrProperties({ ...f, horizontalFov: false });
+    }
+    // The node drives transparent sorting (the views ignore it): on the (round) first eye.
+    const p = entries[0].node || entries[0].pose; // `node`: a rigid pose when the views are remapped
+    const q = quatOf(p);
+    cam.setLocalRotation(q[0], q[1], q[2], q[3]);
+    if (r) cam.setLocalPosition(r[0].eye[0], r[0].eye[1], r[0].eye[2]);
+    else cam.setLocalPosition(p[12], p[13], p[14]);
+  }
+
+  /**
+   * The N-camera path, mirroring the viewer's own fallback: camera i at view i's rect, its node on
+   * the view's rigid pose, and a projection override. The engine then draws with
+   * proj' · node⁻¹ (node under the rig node), so the display run's shear rides in the projection:
+   * proj' = proj · view_round · node  ⇒  proj' · node⁻¹ = proj · view_round. Culling is off on these
+   * cameras (the sheared frustum is not the node's).
+   */
+  _frameNcam(list, entries, rect, r, run) {
+    const v = this.viewer;
+    const pc = v.pc;
+    const el = v.canvas;
+    const W = el?.width || 1;
+    const H = el?.height || 1;
+    for (let i = 0; i < entries.length; i++) {
+      const e = entries[i];
+      const cam = list[i];
+      const node = e.node || e.pose;
+      if (r) mul4(e.proj, mul4(r[i].view, node), cam._dxrProj);
+      else if (e.node) mul4(e.proj, mul4(invertAffine(e.pose), node), cam._dxrProj);
+      else cam._dxrProj.set(e.proj);
+      const fr = v._frustumOf ? v._frustumOf(e.proj) : null;
+      if (fr) {
+        cam.camera.fov = fr.fov;
+        cam.camera.nearClip = fr.nearClip;
+        cam.camera.farClip = fr.farClip;
       }
-      // The node drives transparent sorting (the views ignore it): on the (round) first eye.
-      const p = entries[0].pose;
-      const q = quatOf(p);
+      const [x, y, w, h] = rect(e);
+      cam.camera.rect = pc?.Vec4 ? new pc.Vec4(x / W, y / H, w / W, h / H) : [x / W, y / H, w / W, h / H];
+      const q = quatOf(node);
       cam.setLocalRotation(q[0], q[1], q[2], q[3]);
-      if (r) cam.setLocalPosition(r[0].eye[0], r[0].eye[1], r[0].eye[2]);
-      else cam.setLocalPosition(p[12], p[13], p[14]);
-      if (run === 'display') {
-        // Two camera spaces never share a depth test; in mono (and at gain 1) they are one space.
-        cam.camera.clearDepthBuffer = !!r;
-        this.last.rounded = !!r;
-      }
+      cam.setLocalPosition(node[12], node[13], node[14]);
     }
   }
 
+  /** One WARN line on the first 3D frame and on every change of engaged / reason / path. */
+  _warnState() {
+    const L = this.last;
+    if (L.path === 'mono' && !this._warnedOnce3d) return; // wait for the first 3D frame
+    if (!this.requests.size) return; // nothing asked for: nothing to report
+    const key = `${L.path}|${L.engaged}|${L.reason}`;
+    if (key === this._warnKey || this._warns >= MAX_STATE_WARNS) return;
+    this._warnKey = key;
+    this._warns++;
+    if (L.path !== 'mono') this._warnedOnce3d = true;
+    console.warn(`[inline3d/splat] setLayerRig: ${layerRigLine(this.state())}`);
+  }
+
+  /** The public state (handle.layerRigState). */
+  state() {
+    const L = this.last;
+    return {
+      display: [...this.requests.keys()],
+      disabled: this.disabled,
+      path: L.path,
+      engaged: !!L.engaged,
+      rounded: !!L.engaged,
+      reason: this.disabled ? 'kill switch (?dxrdiag=nolayerrig)' : L.reason,
+      viewerDistance: this.opts.viewerDistance ?? DEFAULT_VIEWER_DISTANCE_M,
+      gain: L.gain,
+      planeM: L.planeM,
+      photoConvergenceM: L.photoConvergenceM ?? null,
+      planeOffset: this.opts.planeOffset ?? 0,
+      located: L.located,
+    };
+  }
+
   destroy() {
     this.restore();
-    for (const c of Object.values(this.cams)) c?.destroy?.();
-    this.cams = { display: null, post: null };
+    for (const list of Object.values(this.cams)) for (const c of list) c?.destroy?.();
+    this.cams = { display: [], post: [] };
   }
 }
+
+/** layerRigState() as one console line (the WARN, and what a page's HUD can print). */
+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)} ` +
+    `photoConvergenceM=${n(st.photoConvergenceM)} planeOffset=${n(st.planeOffset)}m ` +
+    `located=${st.located === null || st.located === undefined ? '-' : st.located} reason=${st.reason ?? '-'}`
+  );
+}