@displayxr/inline3d 1.22.0 → 1.23.0

package/CHANGELOG.md

@@ -5,6 +5,22 @@ 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.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,8 @@
 //   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).
 //
 // 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 +44,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']);
 const ON_TOKENS = new Set(['1', 'on', 'true', 'yes']);
 
 /**

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

@@ -0,0 +1,423 @@
+// 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.
+
+/** 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(invertRigid(P), o.M, o.view);
+  }
+  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].pose;
+      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-playcanvas.js

@@ -67,7 +67,8 @@ import {
   sequenceSpans,
 } from './inline3d-splat-effects.js';
 import { LiveOutgoing, resolveOutgoingOption, defaultOutgoing, yieldIdle } from './inline3d-splat-live.js';
-import { VideoPlane, validateSetVideo, PAGE_VIDEO_ERROR } from './inline3d-splat-video.js';
+import { VideoPlane, validateSetVideo, PAGE_VIDEO_ERROR, eyeSplit, EYE_SPLIT_UNIFORM, makeSbsMaterial } from './inline3d-splat-video.js';
+import { LayerRigCameras, validateLayerRig } from './inline3d-splat-layer-rig.js';
 import { resolveDiag, DiagRecorder, startDiagLoop, registerDiag, DIAG_SWITCHES } from './inline3d-splat-diag.js';
 import {
   clamp,
@@ -816,6 +817,13 @@ export class PlayCanvasSplatViewer {
     this.inputLocked = false;
     /** handle.setVideo's plane (./inline3d-splat-video.js) while a video is on, else null. */
     this._videoPlane = null;
+    /** handle.setLayerRig's per-rig cameras (./inline3d-splat-layer-rig.js), made on first use. */
+    this.layerRigs = null;
+    /** () => the view-rig descriptor currently declared to the runtime (or null). */
+    this.layerRigSource = null;
+    /** That descriptor as it stood when THIS frame's views were pulled (snapshotted in onFrame). */
+    this._rigSnap = null;
+    this._eyeSplit = NaN;
     this.boxAspect = 1;
     this.featherPx = feather > 0 ? feather : 0;
     this.captureFit = captureFit;
@@ -1125,6 +1133,9 @@ export class PlayCanvasSplatViewer {
   onFrame(views, layer) {
     if (this._disposed) return;
     if (this._mode !== '3d') this.stopMono();
+    // The rig these views were located with: Blink chained the rig declared BEFORE this callback,
+    // 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);
     // BEFORE the tick: a pose the page sets in here is the one this very frame renders.
     this._beforeFrame?.(views || null);
     this._tick();
@@ -1185,6 +1196,7 @@ export class PlayCanvasSplatViewer {
     this._live = null;
     this._videoPlane?.destroy();
     this._videoPlane = null;
+    this.layerRigs = null; // its cameras go with the app
     try {
       this.app?.destroy();
     } catch (err) {
@@ -1866,6 +1878,8 @@ export class PlayCanvasSplatViewer {
       if (this._live?.active || this._live?.warming) this._live.sync(entries, rect, f);
       // setSource's wavefront: this frame's eye views, as the engine is about to compose them.
       this.onBeforeRender?.(entries, rect);
+      // handle.setLayerRig: the display / post run cameras, on the same views (display: rounded).
+      if (this.layerRigs && this.layerRigs.sync()) this.layerRigs.frame(entries, rect, f, cache ? cache.rig : null);
     } else {
       // Fallback: one camera per view, `rect` + `calculateProjection`.
       const cams = this._views;
@@ -1899,6 +1913,12 @@ export class PlayCanvasSplatViewer {
       }
     }
     this._updateFeather(entries[0].width * sx, entries[0].height * sy);
+    // handle.makeSbsMaterial: the eye split, scene-wide (a material only declares the uniform).
+    const split = eyeSplit(entries, rect);
+    if (split !== this._eyeSplit) {
+      this._eyeSplit = split;
+      app.graphicsDevice?.scope?.resolve?.(EYE_SPLIT_UNIFORM)?.setValue(split);
+    }
     // handle.setVideo's plane: size, eye split, and a new frame's upload (./inline3d-splat-video.js).
     this._videoPlane?.beforeDraw(entries, rect);
     app.tick(now());
@@ -1917,6 +1937,7 @@ export class PlayCanvasSplatViewer {
     }
     g.bufW = el.width || 0;
     g.bufH = el.height || 0;
+    g.rig = this._rigSnap ? { ...this._rigSnap } : null; // a replay re-uses the rig of its views
     for (let i = 0; i < views.length; i++) {
       const e = g.entries[i];
       const vp = vps[i];
@@ -2259,6 +2280,23 @@ export class PlayCanvasSplatViewer {
   }
 }
 
+/**
+ * A copy of the declared rig's frame fields (the SDK rewrites its camera-rig descriptor in place),
+ * or null. Only what the layer rig reads: kind, pose, convergence, metres-to-virtual.
+ */
+export function snapshotRig(rig, into = null) {
+  if (!rig || typeof rig !== 'object') return null;
+  const o = into || { position: {}, orientation: {} };
+  o.type = rig.type;
+  const p = rig.position || {};
+  const q = rig.orientation || {};
+  o.position = { x: p.x || 0, y: p.y || 0, z: p.z || 0 };
+  o.orientation = { x: q.x || 0, y: q.y || 0, z: q.z || 0, w: q.w === undefined ? 1 : q.w };
+  o.convergenceDiopters = rig.convergenceDiopters;
+  o.metersToVirtual = rig.metersToVirtual;
+  return o;
+}
+
 /** Put an engine node at a rigid display-space pose (position + rotation; no scale). */
 function placeNode(node, m) {
   node.setLocalPosition(m[12], m[13], m[14]);
@@ -2836,6 +2874,17 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     diag.log(`on — switches [${[...diag.switches].join(', ') || 'none'}]; dump: copy(__dxrDiag.dump())`);
   }
   let removed = false;
+  // handle.setLayerRig: the per-rig cameras and where they read the declared rig from.
+  // Kill switch `nolayerrig`: requests are recorded but every layer stays on the eye camera.
+  let warnedLayerRigPath = false;
+  function layerRigs() {
+    if (!viewer.layerRigs) {
+      viewer.layerRigs = new LayerRigCameras(viewer);
+      viewer.layerRigs.disabled = !!diag?.has('nolayerrig');
+      viewer.layerRigSource = () => out.viewRig || null;
+    }
+    return viewer.layerRigs;
+  }
   /** prepareSource: prepared handle → { loaded, state: 'ready' | 'used' | 'disposed', dispose }. */
   const preparedAssets = new WeakMap();
   const livePrepared = new Set();
@@ -2916,6 +2965,42 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     prepareSource,
     setRig,
     setVideo,
+    /**
+     * Draw a layer of this tile's engine through the DISPLAY rig (round, physical-depth stage
+     * objects) while the splat and the declared view rig stay on the photo's camera rig — or back
+     * on the camera rig ('camera'). No second full pass: one extra camera over the named layers,
+     * into the same target, in composition order. docs/playcanvas-adapter.md §setLayerRig and
+     * docs/proposals/layer-display-rig.md (the exact mapping, and why it is not Kooima).
+     * `viewerDistance` (m) / `gain` set the rounding for the whole tile (last call wins).
+     */
+    setLayerRig(layer, rig, o = {}) {
+      const r = validateLayerRig(layer, rig, o);
+      if (viewer._viewPath === 'cameras' && !warnedLayerRigPath) {
+        warnedLayerRigPath = true;
+        console.warn('[inline3d/splat] setLayerRig needs the engine RenderView path; on the N-camera fallback the layer stays on the photo rig.');
+      }
+      layerRigs().set(layer, r.rig, { viewerDistance: r.viewerDistance, gain: r.gain });
+      return out;
+    },
+    /** The layers on the display rig (as the page named them), and what the last frame did. */
+    layerRigState() {
+      const lr = viewer.layerRigs;
+      return {
+        display: lr ? [...lr.requests.keys()] : [],
+        disabled: !!lr?.disabled,
+        rounded: !!lr?.last.rounded,
+        gain: lr?.last.gain ?? null,
+      };
+    },
+    /**
+     * An unlit material showing the left half of `texture` to left-eye views and the right half to
+     * right-eye views (format 'sbs' | 'tb' | 'mono'), on any mesh — mono / 2D: the left half. Needs
+     * the engine (after `ready`). docs/playcanvas-adapter.md §makeSbsMaterial.
+     */
+    makeSbsMaterial(texture, o = {}) {
+      if (!viewer.app || !viewer.pc) throw new Error('@displayxr/inline3d/splat: makeSbsMaterial() needs the engine — call it after `await handle.ready`.');
+      return makeSbsMaterial(viewer.pc, texture, o);
+    },
     /**
      * Play a transition effect (inflate, deflate, sweep, dissolve, fade, pulse, custom) — see
      * docs/splat-effects.md. Validated now; runs once the first asset is on screen. Resolves
@@ -3071,6 +3156,14 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     delete out._resolveFirstWoven;
   }
 
+  // addSplat's `displayRigLayers` sugar: [layer, …] or { layers: [...], viewerDistance, gain }.
+  if (opts.displayRigLayers !== undefined) {
+    const d = opts.displayRigLayers;
+    const list = Array.isArray(d) ? d : d && Array.isArray(d.layers) ? d.layers : null;
+    if (!list) throw new TypeError('@displayxr/inline3d/splat: displayRigLayers — expected an array of layers, or { layers, viewerDistance?, gain? }.');
+    const o = Array.isArray(d) ? {} : { ...(d.viewerDistance !== undefined ? { viewerDistance: d.viewerDistance } : {}), ...(d.gain !== undefined ? { gain: d.gain } : {}) };
+    for (const l of list) out.setLayerRig(l, 'display', o);
+  }
   // Replay what the page did before this module arrived — exclude() above all, which a product
   // page calls on the very next line after addSplat.
   for (const [name, args] of pending) {

package/js/inline3d-splat-video.js

@@ -303,3 +303,100 @@ export class VideoPlane {
     this.mesh.destroy?.();
   }
 }
+
+// ── handle.makeSbsMaterial(): per-eye stereo on ANY quad (docs/proposals/layer-display-rig.md) ──
+//
+// setVideo's eye pick, lifted out of the full-screen plane: the eye viewports sit side by side in
+// the buffer, so `gl_FragCoord.x >= split` is the right eye. The viewer publishes that split every
+// draw as a SCENE-WIDE uniform (EYE_SPLIT_UNIFORM, 1e9 in mono / the 2D tier / a 1-view mode), so a
+// material only has to declare it — the SDK never has to know which materials are stereo.
+// PlayCanvas's own `view_index` is set per RenderView on the single-camera path too, but it is 0
+// for every camera on the N-camera fallback path; the split is right on both.
+
+/** The scene-wide uniform the viewer sets every draw: first right-eye pixel column (1e9 = mono). */
+export const EYE_SPLIT_UNIFORM = 'dxr_eye_split';
+
+/**
+ * GLSL for a custom shader that wants the same pick: declare the uniform, call dxrEyeRegion() with
+ * the left and right regions ([s0, t0, ds, dt], t = image rows from the top).
+ */
+export const SBS_EYE_GLSL = `
+uniform float ${EYE_SPLIT_UNIFORM};
+vec4 dxrEyeRegion(vec4 left, vec4 right) { return gl_FragCoord.x >= ${EYE_SPLIT_UNIFORM} ? right : left; }`;
+
+const SBS_OPTION_KEYS = new Set(['format', 'opacity', 'flipY', 'depthTest', 'depthWrite', 'cull', 'name']);
+
+/** makeSbsMaterial's options, validated. */
+export function validateSbsOptions(texture, o = {}) {
+  if (!texture || typeof texture !== 'object') throw new TypeError('@displayxr/inline3d/splat: makeSbsMaterial(texture) — expected a pc.Texture.');
+  if (o === null || typeof o !== 'object') throw new TypeError('@displayxr/inline3d/splat: makeSbsMaterial options must be an object.');
+  const unknown = Object.keys(o).filter((k) => !SBS_OPTION_KEYS.has(k));
+  if (unknown.length) throw new Error(`@displayxr/inline3d/splat: makeSbsMaterial — unknown option(s) ${unknown.join(', ')}.`);
+  const format = o.format === undefined ? 'sbs' : o.format;
+  if (!VIDEO_FORMATS.includes(format)) throw new Error(`@displayxr/inline3d/splat: makeSbsMaterial — format "${format}", expected ${VIDEO_FORMATS.join(' | ')}.`);
+  const opacity = o.opacity === undefined ? 1 : o.opacity;
+  if (!Number.isFinite(opacity) || opacity < 0 || opacity > 1) throw new Error(`@displayxr/inline3d/splat: makeSbsMaterial — bad opacity: ${o.opacity}.`);
+  return { format, opacity, flipY: o.flipY === true, depthTest: o.depthTest !== false, depthWrite: o.depthWrite !== false, cull: o.cull === true, name: o.name };
+}
+
+const SBS_VERT = `
+attribute vec3 vertex_position;
+attribute vec2 vertex_texCoord0;
+uniform mat4 matrix_model;
+uniform mat4 matrix_viewProjection;
+varying vec2 vUv;
+void main() {
+  vUv = vertex_texCoord0;
+  gl_Position = matrix_viewProjection * matrix_model * vec4(vertex_position, 1.0);
+}`;
+const SBS_FRAG = `
+varying vec2 vUv;
+uniform sampler2D dxrSbsTex;
+uniform vec4 dxrSbsL;       // left eye's region: s0, t0, ds, dt (t = image rows, top = 0)
+uniform vec4 dxrSbsR;       // right eye's
+uniform vec2 dxrSbsTexel;   // half a texel, per axis
+uniform float dxrSbsOpacity;
+uniform float dxrSbsFlipY;  // 1: the texture's row 0 is the image's BOTTOM
+${SBS_EYE_GLSL}
+void main() {
+  vec4 r = dxrEyeRegion(dxrSbsL, dxrSbsR);
+  vec2 st = r.xy + vec2(vUv.x, 1.0 - vUv.y) * r.zw;
+  st = clamp(st, r.xy + dxrSbsTexel, r.xy + r.zw - dxrSbsTexel);
+  if (dxrSbsFlipY > 0.5) st.y = 1.0 - st.y;
+  gl_FragColor = vec4(texture2D(dxrSbsTex, st).rgb, dxrSbsOpacity);
+}`;
+
+/**
+ * An unlit material that shows the LEFT half of `texture` to left-eye views and the RIGHT half to
+ * right-eye views (or top/bottom, or the same picture: `format`), on whatever mesh it is put on.
+ * The mesh's geometry is untouched — put the quad at the screen plane and the clip's own disparity
+ * is the only depth. Mono: every fragment samples the left region at full resolution. The texture
+ * is the page's (a `<video>`'s frames uploaded by the page, an image); nothing is decoded here.
+ */
+export function makeSbsMaterial(pc, texture, o = {}) {
+  const opt = validateSbsOptions(texture, o);
+  const mat = new pc.ShaderMaterial({
+    uniqueName: 'inline3dSbsQuad',
+    attributes: { vertex_position: pc.SEMANTIC_POSITION, vertex_texCoord0: pc.SEMANTIC_TEXCOORD0 },
+    vertexGLSL: SBS_VERT,
+    fragmentGLSL: SBS_FRAG,
+  });
+  if (opt.name) mat.name = opt.name;
+  mat.cull = opt.cull ? pc.CULLFACE_BACK : pc.CULLFACE_NONE;
+  mat.depthTest = opt.depthTest;
+  mat.depthWrite = opt.depthWrite;
+  if (opt.opacity < 1 && pc.BlendState && pc.BLENDMODE_SRC_ALPHA !== undefined) {
+    mat.blendState = new pc.BlendState(true, pc.BLENDEQUATION_ADD, pc.BLENDMODE_SRC_ALPHA, pc.BLENDMODE_ONE_MINUS_SRC_ALPHA);
+  }
+  const r = eyeRegions(opt.format);
+  mat.setParameter('dxrSbsL', r.L);
+  mat.setParameter('dxrSbsR', r.R);
+  mat.setParameter('dxrSbsOpacity', opt.opacity);
+  mat.setParameter('dxrSbsFlipY', opt.flipY ? 1 : 0);
+  mat.setParameter('dxrSbsTex', texture);
+  const w = Math.max(1, texture.width || 1);
+  const h = Math.max(1, texture.height || 1);
+  mat.setParameter('dxrSbsTexel', [0.5 / w, 0.5 / h]);
+  mat.update();
+  return mat;
+}

package/js/inline3d-splat.js

@@ -381,6 +381,14 @@ export function addSplat(wall, canvas, src, opts = {}) {
           "(addSplat(…, { engine:'playcanvas' })); with Spark, use wall.addVideo on its own canvas.",
       );
     },
+    /** Not on this backend: per-layer rigs are a PlayCanvas-backend feature. */
+    setLayerRig() {
+      throw new Error("@displayxr/inline3d/splat: setLayerRig() is implemented on the PlayCanvas backend only (addSplat(…, { engine:'playcanvas' })).");
+    },
+    /** Not on this backend: per-eye SBS materials are a PlayCanvas-backend feature. */
+    makeSbsMaterial() {
+      throw new Error("@displayxr/inline3d/splat: makeSbsMaterial() is implemented on the PlayCanvas backend only (addSplat(…, { engine:'playcanvas' })).");
+    },
     /** Not on this backend: the live rig switch is a PlayCanvas-backend feature. */
     setRig() {
       throw new Error(
@@ -759,6 +767,16 @@ function addSplatDeferred(wall, canvas, src, opts) {
       return out;
     },
     stopEffect: queue('stopEffect'),
+    // A layer-rig request before the adapter has loaded: queued, replayed in order once it has
+    // (it needs no asset, only the engine's layers — which the adapter resolves lazily).
+    setLayerRig: (...args) => {
+      pending.push(['setLayerRig', args]);
+      return out;
+    },
+    layerRigState: () => ({ display: [], disabled: false, rounded: false, gain: null }),
+    makeSbsMaterial: () => {
+      throw new Error('@displayxr/inline3d/splat: makeSbsMaterial() needs the engine — call it after `await handle.ready`.');
+    },
     effects: () => [],
     getFocus: () => null,
     // A plain data slot the adapter reads at call time, so a callback assigned on the very next

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@displayxr/inline3d",
-  "version": "1.22.0",
+  "version": "1.23.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",
@@ -54,6 +54,7 @@
     "js/inline3d-splat-live.js",
     "js/inline3d-splat-diag.js",
     "js/inline3d-splat-video.js",
+    "js/inline3d-splat-layer-rig.js",
     "js/inline3d-model.js",
     "js/inline3d-model-entry.js",
     "js/inline3d-model-playcanvas.js",

package/splat.d.ts

@@ -178,6 +178,47 @@ export interface ResolvedRig {
   parallaxFactor: number;
 }
 
+/**
+ * `handle.setLayerRig` options — how ROUND the display-rig layers are, for the whole tile (last
+ * call wins). The rounding gain is k = D / (metersToVirtual · viewerDistance): the photo rig's
+ * convergence distance over the viewer's. docs/proposals/layer-display-rig.md.
+ */
+export interface SplatLayerRigOptions {
+  /** Nominal viewer distance in metres (default 0.6, the browser's own nominal). */
+  viewerDistance?: number;
+  /** An explicit gain k instead (1 = exactly the photo rig; larger = rounder). */
+  gain?: number;
+}
+
+/** `handle.layerRigState()`. */
+export interface SplatLayerRigState {
+  /** The layers on the display rig, as the page named them. */
+  display: Array<string | number>;
+  /** The `nolayerrig` kill switch is on (requests recorded, never applied). */
+  disabled: boolean;
+  /** The last drawn frame drew the display layers through rounded views (false in mono). */
+  rounded: boolean;
+  /** The gain the last frame used (null off a camera rig). */
+  gain: number | null;
+}
+
+/** `handle.makeSbsMaterial` options. */
+export interface SplatSbsMaterialOptions {
+  /** How the texture holds the two eyes. Default `'sbs'` (left half = left eye). */
+  format?: 'sbs' | 'tb' | 'mono';
+  /** 0–1; below 1 the material alpha-blends. Default 1. */
+  opacity?: number;
+  /** The texture's row 0 is the image's BOTTOM (flip the sampling). Default false. */
+  flipY?: boolean;
+  /** Default true. */
+  depthTest?: boolean;
+  /** Default true. */
+  depthWrite?: boolean;
+  /** Back-face culling. Default false (both faces). */
+  cull?: boolean;
+  name?: string;
+}
+
 /** `handle.setVideo` options. */
 export interface SplatVideoOptions {
   /** Stereo layout of the frame: `'sbs'` (default, left eye = left half), `'tb'` (left = top), `'mono'` (both eyes the whole frame). */
@@ -219,6 +260,11 @@ export interface SplatOptions {
    * URL with `engine: 'spark'`.
    */
   engine?: 'spark' | 'playcanvas';
+  /**
+   * `engine: 'playcanvas'` only. Sugar for `handle.setLayerRig(layer, 'display', opts)` on each
+   * layer (a name, an id or a `pc.Layer`), applied as soon as the engine boots.
+   */
+  displayRigLayers?: Array<string | number | { id: number }> | ({ layers: Array<string | number | { id: number }> } & SplatLayerRigOptions);
   /**
    * `engine: 'playcanvas'` only: TRANSITION DIAGNOSTICS (#36). Off by default; `true` (or the page
    * URL's `?dxrdiag=1`) records every woven frame — its interval, whether its eye poses are
@@ -910,6 +956,27 @@ export interface SplatHandle {
    */
   setVideo(src: string | HTMLVideoElement, opts?: SplatVideoOptions): Promise<SplatVideo>;
   setVideo(src: null): Promise<null>;
+  /**
+   * `engine: 'playcanvas'` only (throws on Spark). Draw `layer` (a name, an id or a `pc.Layer` of
+   * `handle.engine.app`) through the DISPLAY rig — round, physical-depth stage objects — while the
+   * splat and the view rig declared to the runtime stay on the photo's camera rig; `'camera'` puts
+   * it back. One extra camera over the named layers, into the same target, in composition order;
+   * the photo's projection matrices are used verbatim and the views are right-multiplied by the
+   * shear that fixes the photo's convergence plane (so a z = 0 contact point never moves).
+   * Identity in mono / the 2D tier, on a display rig (`setRig('display')`, `setVideo`), and under
+   * `?dxrdiag=nolayerrig`. Callable before `ready`. docs/proposals/layer-display-rig.md.
+   */
+  setLayerRig(layer: string | number | { id: number }, rig: 'display' | 'camera', opts?: SplatLayerRigOptions): SplatHandle;
+  /** `engine: 'playcanvas'` only. What `setLayerRig` is doing. */
+  layerRigState(): SplatLayerRigState;
+  /**
+   * `engine: 'playcanvas'` only, after `ready`. An unlit `pc.ShaderMaterial` that shows the left
+   * half of `texture` to left-eye views and the right half to right-eye views (`format`), on any
+   * mesh — mono / the 2D tier / a 1-view mode: the left half. The eye is picked from the scene-wide
+   * uniform `dxr_eye_split` the SDK sets every draw (declare it in your own shader to do the same).
+   * Nothing is decoded: the page uploads its one `<video>` into `texture`.
+   */
+  makeSbsMaterial(texture: unknown, opts?: SplatSbsMaterialOptions): unknown;
   /**
    * `engine: 'playcanvas'` only (throws on Spark). Play a transition/pulse/custom effect;
    * validated at the call, run once the first asset is on screen. Resolves `{ finished }` —