@displayxr/inline3d 1.22.0 → 1.24.0

package/CHANGELOG.md

@@ -5,6 +5,44 @@ 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.24.0 — 2026-09-25
+
+Touches the **preview tier** (`./splat`, `engine: 'playcanvas'` only). No API change. Pixels change
+during a live transition between two camera-rig photos (they were wrong), and for the frames in
+which a newly declared rig has not yet reached the runtime's views.
+
+- **No camera jump at the start of a live transition.** Crossfade, wavefront and the particle
+  transitions keep the outgoing photo alive next to the incoming one. Between two photos with
+  camera rigs (SOG camera blocks: each its own convergence and vertical FOV), the outgoing photo
+  was drawn from eyes scaled by the two rigs' window ratio from the swap on, a jump in its
+  disparity and head parallax. For the frame(s) before the declaration reached the views, both
+  photos were drawn through the wrong rig. Each photo is now drawn through its own rig for the whole
+  window. The SDK reads off the views which declared rig they were located for, and remaps them
+  exactly (window onto window, eye onto eye; the runtime's projection verbatim, no Kooima) where
+  they are not the photo's own. `reassemble` was never affected. Headless: 102–208 px of
+  reference-point error → < 0.005 px, and the live outgoing image equals the frame before the swap
+  (MAE 0.000). Docs: `docs/playcanvas-adapter.md` § Each photo through its own rig.
+- **Kill switch `?dxrdiag=oldrig`** (the 1.23 behaviour). The diag's per-frame record gains
+  `rigAt` / `rigIn` / `rigOut`: the rig the views were located for, the rig the current photo was
+  drawn through (`+` = remapped), and how the live outgoing photo was drawn.
+- `tools/rig-swap-capture`: the headless harness behind the numbers.
+
+## 1.23.0 — 2026-09-25
+
+Touches the **preview tier** (`./splat`, `engine: 'playcanvas'` only). New API; no pixel change for a
+page that does not call it.
+
+- **`handle.setLayerRig(layer, 'display' | 'camera', { viewerDistance?, gain? })`** (and
+  `addSplat(…, { displayRigLayers: [...] })`): draw chosen engine layers through the display rig —
+  round objects with physical pop-out — while the splat and the declared view rig stay on the
+  photo's camera rig. The display-rig views are the runtime's own views times an exact shear that
+  fixes the convergence plane (a contact point never moves); the runtime's projection matrices are
+  used verbatim — no Kooima (docs/proposals/layer-display-rig.md). Mono / 2D is byte-identical to
+  today. Kill switch `?dxrdiag=nolayerrig`. `handle.layerRigState()` reports what it did.
+- **`handle.makeSbsMaterial(texture, { format })`**: per-eye side-by-side (or top/bottom) sampling
+  on any quad — the left half to left views, the right half to right views, the left half in mono.
+  The eye split is a scene-wide uniform, `dxr_eye_split`, set every draw.
+
 ## 1.22.0 — 2026-09-25
 
 Touches the **preview tier** (`./splat`, `engine: 'playcanvas'` only). No API change; no pixel change.

package/js/inline3d-splat-diag.js

@@ -28,6 +28,17 @@
 //   nooverlay — record + console + window.__dxrDiag, but no on-screen overlay.
 //   oldpick  — handle.pick() always runs the full scan over every centre (the 1.21.1 path), no
 //              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):
@@ -42,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']);
+export const DIAG_SWITCHES = Object.freeze(['norig', 'frozen', 'nowarm', 'cold', 'nooverlay', 'oldpick', 'nolayerrig', 'oldrig']);
 const ON_TOKENS = new Set(['1', 'on', 'true', 'yes']);
 
 /**
@@ -189,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
@@ -371,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),
@@ -386,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

@@ -0,0 +1,425 @@
+// inline3d-splat-layer-rig.js — handle.setLayerRig(): draw chosen PlayCanvas layers through the
+// DISPLAY rig while the splat (and the runtime's declared rig) stay on the photo's CAMERA rig.
+// Internal to ./inline3d-splat-playcanvas.js. Design: docs/proposals/layer-display-rig.md.
+//
+// NO KOOIMA HERE. The runtime's projection matrices are used verbatim; nothing below builds a
+// frustum, a tangent or an off-axis matrix. What it does instead is an exact identity:
+//
+//   A camera rig is a portal: every view looks through ONE window rectangle on the convergence
+//   plane (centre Wc = N0 + D·fwd), from its own eye E_i. The round (display-rig) views look
+//   through the SAME window from E'_i = N0 + k·(E_i − N0) — the runtime's ipd/parallax factors
+//   are linear about the nominal viewpoint, and the photo's camera rig is the display rig with
+//   both factors at n/D (displayxr-common's rig conversion). Two portals through one window
+//   differ only by the eye, and the affine shear M_i that fixes the window plane pointwise and
+//   sends E'_i to E_i turns one picture into the other:
+//
+//       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.
+
+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']);
+
+/** Nominal viewer distance (m) when neither the page nor the platform says: the browser's own. */
+export const DEFAULT_VIEWER_DISTANCE_M = 0.6;
+
+/** 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;
+
+/** Rotate v by unit quaternion q (xyzw). */
+function rotate(q, v) {
+  const [x, y, z, w] = q;
+  const tx = 2 * (y * v[2] - z * v[1]);
+  const ty = 2 * (z * v[0] - x * v[2]);
+  const tz = 2 * (x * v[1] - y * v[0]);
+  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)];
+}
+
+/**
+ * setLayerRig's arguments, validated (throws at the call).
+ * @returns {{ rig: 'display'|'camera', viewerDistance: number|null, gain: number|null }}
+ */
+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))) {
+    throw new TypeError('@displayxr/inline3d/splat: setLayerRig(layer, …) — expected a layer name, a layer id, or a pc.Layer.');
+  }
+  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') };
+}
+
+/**
+ * The frame of a declared CAMERA-rig descriptor (XRViewRigInit shape), or null for anything else
+ * (a display rig, no rig, a convergence at infinity — no finite window to hold fixed).
+ * @returns {{ N0: number[], fwd: number[], D: number, m: number }|null}
+ */
+export function cameraRigFrame(rig) {
+  if (!rig || rig.type !== 'camera') return null;
+  const inv = rig.convergenceDiopters;
+  if (!Number.isFinite(inv) || !(inv > 0)) return null;
+  const p = rig.position || { x: 0, y: 0, z: 0 };
+  const o = rig.orientation || { x: 0, y: 0, z: 0, w: 1 };
+  const m = Number.isFinite(rig.metersToVirtual) && rig.metersToVirtual > 0 ? rig.metersToVirtual : 1;
+  const fwd = rotate([o.x || 0, o.y || 0, o.z || 0, o.w === undefined ? 1 : o.w], [0, 0, -1]);
+  return { N0: [p.x || 0, p.y || 0, p.z || 0], fwd, D: 1 / inv, m };
+}
+
+/** 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;
+  return frame.D / (frame.m * 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.
+ *
+ *   M(X) = X + v · (ẑ·X − c),   ẑ = −fwd,  c = ẑ·Wc,  v = (E − E') / h(E'),  h(X) = ẑ·X − c
+ *   M⁻¹  = the same form with v' = −v / (1 + ẑ·v)
+ *
+ * @param {number[]} E  the runtime's eye position (the view pose's translation).
+ * @returns {{ M: Float64Array, Minv: Float64Array, Eround: number[] }}
+ */
+export function windowShear(E, frame, k, M = new Float64Array(16), Minv = new Float64Array(16)) {
+  const { N0, fwd, D } = frame;
+  const z = [-fwd[0], -fwd[1], -fwd[2]];
+  const Wc = [N0[0] + D * fwd[0], N0[1] + D * fwd[1], N0[2] + D * fwd[2]];
+  const c = z[0] * Wc[0] + z[1] * Wc[1] + z[2] * Wc[2];
+  const Er = [N0[0] + k * (E[0] - N0[0]), N0[1] + k * (E[1] - N0[1]), N0[2] + k * (E[2] - N0[2])];
+  let h = z[0] * Er[0] + z[1] * Er[1] + z[2] * Er[2] - c;
+  const hMin = MIN_EYE_HEIGHT_FRAC * D;
+  if (!(h > hMin)) {
+    // Leaning into the glass with a large gain: keep the round eye in front of the window.
+    const dh = hMin - h;
+    Er[0] += dh * z[0];
+    Er[1] += dh * z[1];
+    Er[2] += dh * z[2];
+    h = hMin;
+  }
+  const v = [(E[0] - Er[0]) / h, (E[1] - Er[1]) / h, (E[2] - Er[2]) / h];
+  shearMatrix(v, z, c, M);
+  const s = 1 + z[0] * v[0] + z[1] * v[1] + z[2] * v[2];
+  shearMatrix([-v[0] / s, -v[1] / s, -v[2] / s], z, c, Minv);
+  return { M, Minv, Eround: Er };
+}
+
+/** X ↦ X + v·(z·X − c), column-major. */
+function shearMatrix(v, z, c, out) {
+  for (let col = 0; col < 3; col++) {
+    for (let row = 0; row < 3; row++) out[col * 4 + row] = (row === col ? 1 : 0) + v[row] * z[col];
+    out[col * 4 + 3] = 0;
+  }
+  out[12] = -v[0] * c;
+  out[13] = -v[1] * c;
+  out[14] = -v[2] * c;
+  out[15] = 1;
+  return out;
+}
+
+/** Unit quaternion (xyzw) of a rigid column-major 4×4's rotation. */
+function quatOf(m) {
+  const m11 = m[0], m12 = m[4], m13 = m[8], m21 = m[1], m22 = m[5], m23 = m[9], m31 = m[2], m32 = m[6], m33 = m[10];
+  const tr = m11 + m22 + m33;
+  if (tr > 0) {
+    const s = 0.5 / Math.sqrt(tr + 1);
+    return [(m32 - m23) * s, (m13 - m31) * s, (m21 - m12) * s, 0.25 / s];
+  }
+  if (m11 > m22 && m11 > m33) {
+    const s = 2 * Math.sqrt(1 + m11 - m22 - m33);
+    return [0.25 * s, (m12 + m21) / s, (m13 + m31) / s, (m32 - m23) / s];
+  }
+  if (m22 > m33) {
+    const s = 2 * Math.sqrt(1 + m22 - m11 - m33);
+    return [(m12 + m21) / s, 0.25 * s, (m23 + m32) / s, (m13 - m31) / s];
+  }
+  const s = 2 * Math.sqrt(1 + m33 - m11 - m22);
+  return [(m13 + m31) / s, (m23 + m32) / s, 0.25 * s, (m21 - m12) / s];
+}
+
+/** a × b, column-major (local, so this module stays standalone). */
+export function mul4(a, b, out = new Float64Array(16)) {
+  const r = new Float64Array(16);
+  for (let col = 0; col < 4; col++) {
+    for (let row = 0; row < 4; row++) {
+      r[col * 4 + row] = a[row] * b[col * 4] + a[4 + row] * b[col * 4 + 1] + a[8 + row] * b[col * 4 + 2] + a[12 + row] * b[col * 4 + 3];
+    }
+  }
+  out.set(r);
+  return out;
+}
+
+/** Inverse of a rigid (rotation + translation) column-major 4×4. */
+export function invertRigid(m, out = new Float64Array(16)) {
+  const r = [m[0], m[1], m[2], m[4], m[5], m[6], m[8], m[9], m[10]];
+  out[0] = r[0]; out[1] = r[3]; out[2] = r[6]; out[3] = 0;
+  out[4] = r[1]; out[5] = r[4]; out[6] = r[7]; out[7] = 0;
+  out[8] = r[2]; out[9] = r[5]; out[10] = r[8]; out[11] = 0;
+  const tx = m[12], ty = m[13], tz = m[14];
+  out[12] = -(out[0] * tx + out[4] * ty + out[8] * tz);
+  out[13] = -(out[1] * tx + out[5] * ty + out[9] * tz);
+  out[14] = -(out[2] * tx + out[6] * ty + out[10] * tz);
+  out[15] = 1;
+  return out;
+}
+
+/**
+ * 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.
+ */
+export function roundViews(entries, frame, k, into = []) {
+  if (!frame || !entries || entries.length < 2 || !(k > 0) || k === 1) return null;
+  into.length = entries.length;
+  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(invertAffine(P), o.M, o.view); // P is rigid, or affine once remapped to the declared rig (./inline3d-splat-rig-map.js)
+  }
+  return into;
+}
+
+/**
+ * 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
+ * appear); `display` the set of display-rig layer ids; `eyeLayers` the ids the eye camera draws.
+ * PlayCanvas orders render actions by CAMERA, then layer — so keeping today's order with a second
+ * rig needs one camera per run:
+ *   pre      — eye-camera layers with any sublayer before the first display sublayer (stay put);
+ *   display  — the display layers the eye camera drew;
+ *   post     — eye-camera layers whose every sublayer comes after the last display sublayer.
+ * A non-display layer INTERLEAVED between display sublayers stays in `pre` (it would otherwise
+ * split a run) and is reported in `interleaved`.
+ */
+export function layerRuns(entries, display, eyeLayers) {
+  const eye = new Set(eyeLayers);
+  let first = -1;
+  let last = -1;
+  for (let i = 0; i < entries.length; i++) {
+    if (display.has(entries[i]) && eye.has(entries[i])) {
+      if (first < 0) first = i;
+      last = i;
+    }
+  }
+  const out = { pre: [], display: [], post: [], interleaved: [] };
+  if (first < 0) {
+    out.pre = [...eye];
+    return out;
+  }
+  const seen = new Set();
+  for (const id of eyeLayers) {
+    if (seen.has(id)) continue;
+    seen.add(id);
+    if (display.has(id)) {
+      out.display.push(id);
+      continue;
+    }
+    const at = [];
+    for (let i = 0; i < entries.length; i++) if (entries[i] === id) at.push(i);
+    if (at.length && at.every((i) => i > last)) out.post.push(id);
+    else {
+      out.pre.push(id);
+      if (at.some((i) => i > first && i < last)) out.interleaved.push(id);
+    }
+  }
+  // Keep the run cameras' layer lists in draw order (the composition's, not the eye's list).
+  const order = (ids) => ids.sort((a, b) => entries.indexOf(a) - entries.indexOf(b));
+  order(out.display);
+  order(out.post);
+  return out;
+}
+
+// ── the engine side ──────────────────────────────────────────────────────────────────────────
+
+/**
+ * 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.
+ */
+export class LayerRigCameras {
+  constructor(viewer) {
+    this.viewer = viewer;
+    /** What the page asked for: name or id → { viewerDistance, gain }. */
+    this.requests = new Map();
+    /** Those, resolved: layer id → options (the ones present in the composition right now). */
+    this.layers = new Map();
+    /** The gain options in force (the last setLayerRig call's — one gain per tile). */
+    this.opts = {};
+    this.disabled = false; // the kill switch (diag 'nolayerrig')
+    this.cams = { display: null, post: null };
+    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 };
+  }
+
+  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) {
+    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;
+  }
+
+  /**
+   * 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) {
+    const k = key && typeof key === 'object' ? key.id : key;
+    if (rig === 'display') this.requests.set(k, o);
+    else this.requests.delete(k);
+    this.opts = 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);
+    }
+  }
+
+  _makeCam(name, priority) {
+    const v = this.viewer;
+    const cam = v._makeCamera(name, null);
+    cam.camera.priority = priority;
+    cam.camera.clearColorBuffer = false;
+    cam.camera.clearDepthBuffer = false;
+    cam.camera.clearStencilBuffer = false;
+    cam.camera.frustumCulling = false;
+    cam.camera.layers = [];
+    return cam;
+  }
+
+  /** Re-split the composition when the display set, the eye's layers or the composition moved. */
+  sync() {
+    const v = this.viewer;
+    const eyeCam = v.eye?.camera;
+    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();
+      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.',
+      );
+    }
+    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;
+    }
+    if (runs.post.length) {
+      this.cams.post ||= this._makeCam('inline3d-eye-post', 2);
+      this.cams.post.camera.layers = runs.post;
+    }
+    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;
+  }
+
+  /** Every moved layer back on the eye camera, 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))];
+    }
+    this.moved = { display: [], post: [] };
+    if (this.cams.display) this.cams.display.enabled = false;
+    if (this.cams.post) this.cams.post.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).
+   */
+  frame(entries, rect, f, rig) {
+    const pc = this.viewer.pc;
+    this.last.rounded = false;
+    this.last.views = entries.length;
+    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);
+      }
+      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]);
+      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;
+      }
+    }
+  }
+
+  destroy() {
+    this.restore();
+    for (const c of Object.values(this.cams)) c?.destroy?.();
+    this.cams = { display: null, post: null };
+  }
+}

package/js/inline3d-splat-live.js

@@ -25,14 +25,29 @@
 //
 // THE RIG. The incoming asset's rig (camera rig: its capture pose, lens and convergence; display
 // rig: its fit and focus) is adopted at once, as in the frozen path, so the views the runtime
-// hands us after that are the INCOMING photo's. The outgoing camera is parented under a node
-// chain that maps them back to the OUTGOING photo's framing:
+// hands us — once the declaration has reached them, a frame or more later — are the INCOMING
+// photo's. The outgoing photo must keep being drawn through ITS OWN rig for the whole window.
+//
+// Two camera rigs (a photo slideshow: every photo a SOG with a camera block): the views are
+// remapped, per frame, from the rig they were LOCATED for to the outgoing photo's rig, by the
+// exact portal map of ./inline3d-splat-rig-map.js — window onto window, eye onto eye, the
+// runtime's projection verbatim — under the outgoing photo's rig node R_o. Before the
+// declaration arrives the located rig IS the outgoing one and the views pass through untouched.
+//
+// Otherwise (a display rig on either side, views no declared rig explains, the kill switch
+// `?dxrdiag=oldrig`): the pre-1.24 node chain, which maps the incoming views back to the outgoing
+// photo's framing:
 //     N = R_o · K_o · D_o · D_n⁻¹ · K_n⁻¹
 // with R the rig node (inverse pivot), K the mono/capture pose in rig space and
 // D = diag(c·t, c·t, c) (c = convergence distance, t = tan(vfov/2)). The eye poses (head
 // motion) pass through untouched; the outgoing photo keeps its own window and zero-disparity
 // plane. Two display-rig assets cancel to N = R_o (the old fit and focus); in controls:'page' the
-// page owns the camera and N is the rig node itself.
+// page owns the camera and N is the rig node itself. For two CAMERA rigs this chain is not exact:
+// it scales the eyes with the window, by (c_o·t_o)/(c_n·t_n) — the outgoing photo's disparity and
+// head parallax jumped by that factor at the swap (the "camera change right before the
+// transition" report) — and it assumed the views were already the incoming rig's.
+
+import { remapViews, nodePose, sameRig } from './inline3d-splat-rig-map.js';
 
 /** setSource's `outgoing` option. */
 export const OUTGOING_MODES = Object.freeze(['live', 'frozen']);
@@ -151,6 +166,12 @@ export class LiveOutgoing {
     /** PRE-SORT (warm): the current asset is ALSO on the live layer, before the swap. */
     this.warming = false;
     this._warmLayers = null;
+    /** The outgoing photo's own declared rig (a RigTracker entry), taken at start(). */
+    this.ownRig = null;
+    this._map = [];
+    this._node = new Float64Array(16);
+    /** What the last sync drew through: 'eye' (the eye's views), 'own' (the photo's rig, as located), 'remapped', 'chain'. */
+    this.path = null;
   }
 
   /** Engine support for this path: RenderViews on one camera, render targets, layers. */
@@ -299,6 +320,8 @@ export class LiveOutgoing {
       entity.gsplat.layers = [this.layer.id];
       this.entity = entity;
       this.oldFrame = oldFrame;
+      // Read BEFORE the incoming asset's rig is declared: the last declared rig is the outgoing's.
+      this.ownRig = v.rigTrack?.latest ?? null;
       if (!warmed) this.frames = 0;
       this.warming = false;
       this._warmLayers = null;
@@ -347,10 +370,11 @@ export class LiveOutgoing {
   }
 
   /**
-   * Per frame, before the engine tick: the eye's views on the outgoing camera (same proj, pose,
-   * viewport), the eye's node pose, and the rig chain.
+   * Per frame, before the engine tick: the views on the outgoing camera — through the outgoing
+   * photo's own rig (see the header) — the viewports, and the node chain. `rf` is the viewer's rig
+   * mapping for this frame (viewer._mapViews), or undefined.
    */
-  sync(entries, rect, frustum) {
+  sync(entries, rect, frustum, rf) {
     if (!this.active && !this.warming) return;
     const v = this.viewer;
     const pc = v.pc;
@@ -360,11 +384,50 @@ export class LiveOutgoing {
       for (let i = 0; i < entries.length; i++) rvs.push(new pc.RenderView());
       this.cam.camera.camera.xrViews = rvs.slice();
     }
+    // Which views: the pre-sort (and controls:'page', where both photos are the page camera's)
+    // draws what the eye draws; an active window draws the outgoing photo's own rig.
+    let mapped = null; // remapped views, or null = the entries as they are
+    let exact = false; // the rig map applies: no node chain
+    let nodeRig = null; // the portal the remapped views belong to (for the camera node)
+    const own = this.ownRig;
+    if (rf && v.rigTrack && (!this.active || v.pageCamera)) {
+      exact = true;
+      mapped = rf.remapped ? rf.entries : null;
+      nodeRig = rf.eye?.portal ?? null;
+      this.path = 'eye';
+    } else if (rf?.located && own?.portal && this.active && !v.pageCamera) {
+      if (rf.located === own || sameRig(rf.located.rig, own.rig)) {
+        exact = true;
+        this.path = 'own';
+      } else {
+        mapped = remapViews(entries, rf.located.portal, own.portal, this._map);
+        exact = !!mapped;
+        nodeRig = own.portal;
+        if (mapped) this.path = 'remapped';
+      }
+    }
+    if (!exact) this.path = 'chain';
     for (let i = 0; i < entries.length; i++) {
-      rvs[i].setView(entries[i].proj, entries[i].pose);
+      if (mapped) rvs[i].setView(mapped[i].proj, mapped[i].viewInv, mapped[i].view);
+      else rvs[i].setView(entries[i].proj, entries[i].pose);
       const [x, y, w, h] = rect(entries[i]);
       rvs[i].setViewport(x, y, w, h);
     }
+    // The wavefront's cull reads the views this camera really draws (viewer.cullViews).
+    if (mapped) {
+      const cull = (this._cull ||= []);
+      cull.length = mapped.length;
+      for (let i = 0; i < mapped.length; i++) {
+        const c = (cull[i] ||= {});
+        c.proj = mapped[i].proj;
+        c.pose = mapped[i].viewInv;
+        c.x = mapped[i].x;
+        c.y = mapped[i].y;
+        c.width = mapped[i].width;
+        c.height = mapped[i].height;
+      }
+      this.cam._dxrViews = cull;
+    } else this.cam._dxrViews = null;
     if (frustum) {
       const key = `${frustum.fov.toFixed(4)}|${frustum.aspectRatio.toFixed(4)}|${frustum.nearClip}|${frustum.farClip}`;
       if (key !== this._frustumKey) {
@@ -374,6 +437,20 @@ export class LiveOutgoing {
     }
     // The node chain (see the header). controls:'page': the page's camera, for both assets.
     const { n1, n2, n3 } = this.nodes;
+    if (exact) {
+      // The views are in rig space already: only the photo's rig node above them — the one the
+      // outgoing photo had at the swap (the pre-sort and controls:'page': the current one).
+      setTRS(n1, similarityTRS(this.active && !v.pageCamera && this.oldFrame ? this.oldFrame.rig : v.rigMatrix()));
+      n2.setLocalScale(1, 1, 1);
+      setTRS(n3, { position: [0, 0, 0], rotation: [0, 0, 0, 1], scale: 1 });
+      // The camera NODE (sort direction, LOD distance) on the first eye this camera draws from.
+      const pose = mapped && nodeRig ? nodePose(nodeRig, mapped[0].eye, this._node) : entries[0].pose;
+      const q = similarityTRS(pose).rotation;
+      this.cam.setLocalPosition(pose[12], pose[13], pose[14]);
+      this.cam.setLocalRotation(q[0], q[1], q[2], q[3]);
+      this.frames++;
+      return;
+    }
     if (v.pageCamera || !this.oldFrame) {
       const r = similarityTRS(v.rigMatrix());
       setTRS(n1, r);
@@ -401,6 +478,9 @@ export class LiveOutgoing {
     if (this.warming) return this.cancelWarm();
     this.entity = null;
     this.oldFrame = null;
+    this.ownRig = null;
+    this.path = null;
+    if (this.cam) this.cam._dxrViews = null;
     this.active = false;
     this.warmed = false;
     if (this.cam) this.cam.enabled = false;