@displayxr/inline3d 1.23.0 → 1.25.0

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;

package/js/inline3d-splat-playcanvas.js

@@ -68,7 +68,8 @@ import {
 } from './inline3d-splat-effects.js';
 import { LiveOutgoing, resolveOutgoingOption, defaultOutgoing, yieldIdle } from './inline3d-splat-live.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 { LayerRigCameras, validateLayerRig, validateLayerRigOptions, DEFAULT_VIEWER_DISTANCE_M } from './inline3d-splat-layer-rig.js';
+import { RigTracker, remapViews, nodePose, sameRig } from './inline3d-splat-rig-map.js';
 import { resolveDiag, DiagRecorder, startDiagLoop, registerDiag, DIAG_SWITCHES } from './inline3d-splat-diag.js';
 import {
   clamp,
@@ -823,6 +824,16 @@ export class PlayCanvasSplatViewer {
     this.layerRigSource = null;
     /** That descriptor as it stood when THIS frame's views were pulled (snapshotted in onFrame). */
     this._rigSnap = null;
+    /**
+     * The rigs this tile declared and which one each frame's views were located for
+     * (./inline3d-splat-rig-map.js). Null = the kill switch (diag 'oldrig'): views drawn as
+     * located, the live outgoing on its pre-1.24 node chain.
+     */
+    this.rigTrack = null;
+    /** This frame's rig mapping: { located, eye, remapped, entries } (see _mapViews). */
+    this.rigFrame = null;
+    this._eyeMap = [];
+    this._rigAtPull = null;
     this._eyeSplit = NaN;
     this.boxAspect = 1;
     this.featherPx = feather > 0 ? feather : 0;
@@ -1136,6 +1147,8 @@ export class PlayCanvasSplatViewer {
     // 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);
+    // Same moment, for the rig map: the rig these views were most likely located for (a tie-break).
+    this._rigAtPull = this.rigTrack ? this.rigTrack.latest : null;
     // BEFORE the tick: a pose the page sets in here is the one this very frame renders.
     this._beforeFrame?.(views || null);
     this._tick();
@@ -1588,6 +1601,44 @@ export class PlayCanvasSplatViewer {
     }
   }
 
+  /**
+   * This frame's rig mapping (./inline3d-splat-rig-map.js): which declared rig the views were
+   * located for (`located`), which the current photo wants (`eye`, the last declared), and — only
+   * when those differ and both are camera rigs — the views remapped to `eye` (`entries`: proj,
+   * viewInv, view per view; `cull`: the same as { proj, pose } entries; `node`: the first eye's
+   * rigid pose). Otherwise `remapped` is false and the views are drawn exactly as located.
+   */
+  _mapViews(entries, prefer = null) {
+    const rt = this.rigTrack;
+    const rf = (this.rigFrame ||= { located: null, eye: null, remapped: false, entries: null, cull: [], node: new Float64Array(16) });
+    rf.remapped = false;
+    rf.located = rf.eye = null;
+    if (!rt || this._mode !== '3d' || entries.length < 2) return rf;
+    rf.located = rt.locate(entries, prefer);
+    rf.eye = rt.latest;
+    const L = rf.located;
+    const T = rf.eye;
+    if (!L || !T?.portal || L === T || sameRig(L.rig, T.rig)) return rf;
+    const r = remapViews(entries, L.portal, T.portal, this._eyeMap);
+    if (!r) return rf;
+    rf.remapped = true;
+    rf.entries = r;
+    rf.cull.length = r.length;
+    for (let i = 0; i < r.length; i++) {
+      const c = (rf.cull[i] ||= {});
+      c.proj = r[i].proj;
+      c.pose = r[i].viewInv;
+      c.x = r[i].x;
+      c.y = r[i].y;
+      c.width = r[i].width;
+      c.height = r[i].height;
+      c.node = null;
+    }
+    nodePose(T.portal, r[0].eye, rf.node);
+    rf.cull[0].node = rf.node; // a rigid pose for a camera NODE (the views are affine)
+    return rf;
+  }
+
   /**
    * The mono/capture camera as a lens frame, for the live outgoing's rig chain
    * (./inline3d-splat-live.js): the rig node's matrix, the camera pose in rig space, the
@@ -1612,6 +1663,8 @@ export class PlayCanvasSplatViewer {
    */
   cullViews(cam, entries, rect, into = []) {
     const parent = cam?.parent?.getWorldTransform?.()?.data ?? null;
+    // A camera drawing remapped views (./inline3d-splat-rig-map.js) publishes them as _dxrViews.
+    if (cam?._dxrViews?.length === entries.length) entries = cam._dxrViews;
     into.length = entries.length;
     for (let i = 0; i < entries.length; i++) {
       const e = entries[i];
@@ -1625,7 +1678,8 @@ export class PlayCanvasSplatViewer {
       o.W[0] = C[3]; o.W[1] = C[7]; o.W[2] = C[11]; o.W[3] = C[15];
       o.K[0] = w * e.proj[0];
       o.K[1] = 1 / w;
-      o.K[2] = V[0] * V[0] + V[1] * V[1] + V[2] * V[2];
+      // The view's largest column scale² (1 for a rigid view; a remapped view is affine).
+      o.K[2] = Math.max(V[0] * V[0] + V[1] * V[1] + V[2] * V[2], V[4] * V[4] + V[5] * V[5] + V[6] * V[6], V[8] * V[8] + V[9] * V[9] + V[10] * V[10]);
       o.K[3] = 0;
     }
     return into;
@@ -1857,12 +1911,18 @@ export class PlayCanvasSplatViewer {
         for (let i = 0; i < entries.length; i++) rvs.push(new pc.RenderView());
         this.eye.camera.camera.xrViews = rvs.slice();
       }
+      // The current photo through ITS rig (the last declared): the views are remapped only while
+      // they were located for another one (a declaration still in flight, ./inline3d-splat-rig-map.js).
+      const rf = this._mapViews(entries, cache ? cache.rigAt : null);
+      const eyeViews = rf.remapped ? rf.entries : null;
       for (let i = 0; i < entries.length; i++) {
         const e = entries[i];
-        rvs[i].setView(e.proj, e.pose);
+        if (eyeViews) rvs[i].setView(eyeViews[i].proj, eyeViews[i].viewInv, eyeViews[i].view);
+        else rvs[i].setView(e.proj, e.pose);
         const [x, y, w, h] = rect(e);
         rvs[i].setViewport(x, y, w, h);
       }
+      this.eye._dxrViews = eyeViews ? rf.cull : null;
       // LOD and FOV-compensation read camera.fov/near/far, which under xrViews come from the
       // XR properties — the frustum the views actually have, as XrManager does it.
       const f = frustumFromProjection(entries[0].proj);
@@ -1873,13 +1933,19 @@ export class PlayCanvasSplatViewer {
       }
       // The camera NODE drives the sort direction and LOD distance; the views ignore it (they
       // compose the node's PARENT with their own pose). Park it on the first eye.
-      placeNode(this.eye, entries[0].pose);
-      // setSource's live outgoing: the same views on its own camera, into its own target.
-      if (this._live?.active || this._live?.warming) this._live.sync(entries, rect, f);
+      placeNode(this.eye, eyeViews ? rf.node : entries[0].pose);
+      // setSource's live outgoing: the same views on its own camera (through ITS photo's rig),
+      // into its own target.
+      if (this._live?.active || this._live?.warming) this._live.sync(entries, rect, f, rf);
       // 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);
+      if (this.layerRigs) {
+        this.layerRigs.frame(eyeViews ? rf.cull : entries, rect, f, eyeViews ? rf.eye.rig : rf.located ? rf.located.rig : cache ? cache.rig : null, {
+          located: this.rigTrack && entries.length > 1 ? !!rf.located : null,
+          residual: this.rigTrack?.lastResidual ?? null,
+        });
+      }
     } else {
       // Fallback: one camera per view, `rect` + `calculateProjection`.
       const cams = this._views;
@@ -1911,6 +1977,15 @@ export class PlayCanvasSplatViewer {
         cam.camera.rect = new pc.Vec4(x / W, y / H, w / W, h / H);
         placeNode(cam, e.pose);
       }
+      // handle.setLayerRig on the N-camera path: N display / post cameras mirroring these, the
+      // views as located (this path draws the photo through them too — no remap here).
+      if (this.layerRigs) {
+        const rf = this._mapViews(entries, cache ? cache.rigAt : null);
+        this.layerRigs.frame(entries, rect, null, rf.located ? rf.located.rig : cache ? cache.rig : null, {
+          located: this.rigTrack && entries.length > 1 ? !!rf.located : null,
+          residual: this.rigTrack?.lastResidual ?? null,
+        });
+      }
     }
     this._updateFeather(entries[0].width * sx, entries[0].height * sy);
     // handle.makeSbsMaterial: the eye split, scene-wide (a material only declares the uniform).
@@ -1938,6 +2013,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
+    g.rigAt = this._rigAtPull ?? null;
     for (let i = 0; i < views.length; i++) {
       const e = g.entries[i];
       const vp = vps[i];
@@ -2869,6 +2945,15 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
   let rigLockArmed = false;
   if (diag) {
     diag.imageState = () => viewer.diagImageState();
+    diag.rigState = () => {
+      const rf = viewer.rigFrame;
+      if (!viewer.rigTrack || !rf) return null;
+      return {
+        at: rf.located ? rf.located.id : null,
+        in: rf.eye ? `${rf.eye.id}${rf.remapped ? '+' : ''}` : null,
+        out: viewer._live?.active ? viewer._live.path : null,
+      };
+    };
     diag.observeLongTasks();
     diag.observeLongFrames();
     diag.log(`on — switches [${[...diag.switches].join(', ') || 'none'}]; dump: copy(__dxrDiag.dump())`);
@@ -2876,7 +2961,6 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
   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);
@@ -2971,26 +3055,31 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
      * 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).
+     * Options (`viewerDistance`, `gain`, `planeOffset`, `planeDistance`) are tile-wide and MERGE
+     * (a key given replaces; `null` clears) — see setLayerRigOptions.
+     * Works on both view paths (RenderViews and the N-camera fallback); layerRigState() says
+     * whether it engaged and, if not, why.
      */
     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 });
+      layerRigs().set(layer, r.rig, r.opts);
       return out;
     },
-    /** The layers on the display rig (as the page named them), and what the last frame did. */
+    /** Change the layer rig's tile-wide options live (no layer change): merge, `null` clears. */
+    setLayerRigOptions(o = {}) {
+      layerRigs().setOptions(validateLayerRigOptions(o, 'setLayerRigOptions'));
+      return out;
+    },
+    /**
+     * What setLayerRig is doing: `path` ('renderviews' | 'ncamera' | 'mono') and `engaged` (the
+     * display-rig views were applied on the last drawn frame), `reason` when not, and the numbers
+     * (`viewerDistance`, `gain`, `planeM` — the plane that lands on the glass, as a distance from
+     * the photo's camera — `photoConvergenceM`, `planeOffset`, `located`).
+     */
     layerRigState() {
       const lr = viewer.layerRigs;
-      return {
-        display: lr ? [...lr.requests.keys()] : [],
-        disabled: !!lr?.disabled,
-        rounded: !!lr?.last.rounded,
-        gain: lr?.last.gain ?? null,
-      };
+      if (lr) return lr.state();
+      return { display: [], disabled: false, path: null, engaged: false, rounded: false, reason: 'no layer on the display rig', viewerDistance: DEFAULT_VIEWER_DISTANCE_M, gain: null, planeM: null, photoConvergenceM: null, planeOffset: 0, located: null };
     },
     /**
      * An unlit material showing the left half of `texture` to left-eye views and the right half to
@@ -3109,6 +3198,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
   // toward `target` at the viewer's FOCUS_EASE unless snapped.
   const pageFocus = { d: Number.NaN, target: Number.NaN, fired: Number.NaN, source: null };
 
+  let initialViewRig = null; // the rig addScene is created with (controls:'page'), else the shorthand
   if (wall && wall.supported) {
     const onFrame = diag
       ? (views, layer) => {
@@ -3121,7 +3211,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
       // controls:'page' starts on a camera rig (attach, provisional FOV/convergence until the page
       // and the waterfall say otherwise); the display rig's height means nothing there.
       ...(pageMode
-        ? { viewRig: pageViewRig({ verticalFovDeg: viewer.page.fov, convergence: 2, comfortDepth: ctl.comfortDepth }) }
+        ? { viewRig: (initialViewRig = pageViewRig({ verticalFovDeg: viewer.page.fov, convergence: 2, comfortDepth: ctl.comfortDepth })) }
         : { virtualDisplayHeight }),
       onLayerLost: viewer.onLayerLost,
       ...(observe ? { observe } : {}),
@@ -3130,6 +3220,20 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
   } else {
     viewer.startMono();
   }
+  // Every rig this tile declares, by VALUE (./inline3d-splat-rig-map.js): which one a frame's
+  // views were located for is read off the views, so each photo can be drawn through its own rig
+  // while a declaration is in flight or while a live outgoing photo is still on screen.
+  // `?dxrdiag=oldrig` turns it off (views drawn as located; the live outgoing's node chain).
+  if (handle && typeof handle.setViewRig === 'function' && !diag?.has('oldrig')) {
+    const rt = (viewer.rigTrack = new RigTracker());
+    rt.note(initialViewRig || { type: 'display', virtualDisplayHeight });
+    const push = handle.setViewRig;
+    handle.setViewRig = (rig) => {
+      const r = push.call(handle, rig);
+      rt.note(rig);
+      return r;
+    };
+  }
   let diagLoop = null;
   if (diag) {
     // Every rig push, logged with its values; under `norig`, every push after the first
@@ -3160,8 +3264,8 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
   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 } : {}) };
+    if (!list) throw new TypeError('@displayxr/inline3d/splat: displayRigLayers — expected an array of layers, or { layers, viewerDistance?, gain?, planeOffset?, planeDistance? }.');
+    const o = Array.isArray(d) ? {} : Object.fromEntries(Object.entries(d).filter(([k]) => k !== 'layers'));
     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