@displayxr/inline3d 1.45.1 → 1.47.0

package/js/inline3d-model-playcanvas.js

@@ -38,7 +38,8 @@
 //       └── eye camera, N RenderViews, TONEMAP_NEUTRAL, no sky layer
 
 import { PlayCanvasSplatViewer, pageRigTRS, pageViewAxis, pageViewRig } from './inline3d-splat-playcanvas.js';
-import { resolveControls, normalizeCameraPose, now, MAX_DT_S, declareViewRig } from './inline3d-splat-shared.js';
+import { resolveControls, normalizeCameraPose, now, MAX_DT_S, declareViewRig, attachModelStereo, attachComfortDepth, resolveDepthOption, framedSubjectBounds } from './inline3d-splat-shared.js';
+import { displayRig } from './inline3d-three.js';
 import {
   NEUTRAL_STUDIO,
   neutralStudioRadiance,
@@ -440,6 +441,7 @@ export function attachPlayCanvasModel(out, wall, canvas, src, opts, pending = []
   } = opts;
   const ctl = validatePlayCanvasModelOptions(opts);
   const pageMode = ctl.page;
+  const depthOption = resolveDepthOption(opts.depth, '@displayxr/inline3d/model');
   if (pageMode && ctl.ignored.length) {
     console.info(`${TAG} controls:'page' — the page owns the camera, so ${ctl.ignored.join(', ')} ${ctl.ignored.length === 1 ? 'is' : 'are'} ignored.`);
   }
@@ -468,6 +470,8 @@ export function attachPlayCanvasModel(out, wall, canvas, src, opts, pending = []
     sky: false,
     viewerEase: opts.viewerEase,
     cursor: opts.cursor,
+    // Opt-in; undefined = the viewer's own default (a transparent clear).
+    clearColor: opts.clearColor,
     // Each environment's own look: 'room' is three's (untonemapped), the rest the Sample Viewer's.
     toneMapping: envMap ? 'neutral' : ENVIRONMENT_TONE_MAPPING[environment] || 'neutral',
   });
@@ -510,6 +514,7 @@ export function attachPlayCanvasModel(out, wall, canvas, src, opts, pending = []
     },
     remove() {
       removed = true;
+      depth.dispose();
       handle?.remove();
       viewer.dispose(); // app.destroy(): the model, its textures and any page entities go with it
     },
@@ -530,6 +535,21 @@ export function attachPlayCanvasModel(out, wall, canvas, src, opts, pending = []
   Object.defineProperty(out, 'renderScale', { get: () => viewer.effectiveRenderScale, enumerable: true, configurable: true });
   Object.defineProperty(out, 'renderScaleRequested', { get: () => viewer.renderScale, enumerable: true, configurable: true });
 
+  // handle.setStereo / handle.rig (a depth slider; nothing is declared until it is called).
+  const stereo = attachModelStereo(out, { getTile: () => handle, vH: virtualDisplayHeight, makeDisplayRig: displayRig, page: pageMode });
+  // `depth: 'auto'` (opt-in): the comfort factor under setStereo's, on the same display rig.
+  // Without it, inert: `depthFactor` reads 1 and nothing is measured or declared.
+  const depth = attachComfortDepth(out, {
+    option: depthOption,
+    canvas,
+    getTile: () => handle,
+    getBounds: () => (out.frame ? framedSubjectBounds(viewer) : null),
+    getVH: () => virtualDisplayHeight,
+    apply: (k) => stereo.setBase(k),
+    tag: TAG,
+  });
+  if (pageMode) depth.ignore("controls:'page' (the page's camera rig)");
+
   if (wall && wall.supported) {
     handle = wall.addScene(canvas, viewer.onFrame, {
       ...(pageMode
@@ -574,7 +594,11 @@ export function attachPlayCanvasModel(out, wall, canvas, src, opts, pending = []
         const dm = (c[0] - ax.origin[0]) * ax.forward[0] + (c[1] - ax.origin[1]) * ax.forward[1] + (c[2] - ax.origin[2]) * ax.forward[2];
         if (dm > 0) d = dm / (ax.scale || 1);
       }
-      out.viewRig = pageViewRig({ verticalFovDeg: viewer.page.fov, convergence: d ?? 2, comfortDepth: ctl.comfortDepth }, out.viewRig || {});
+      // setStereo's values, ABSOLUTE on this camera rig (1 and 1 until it is called: as before).
+      out.viewRig = pageViewRig(
+        { verticalFovDeg: viewer.page.fov, convergence: d ?? 2, comfortDepth: ctl.comfortDepth, ipdFactor: out.rig.ipdFactor, parallaxFactor: out.rig.parallaxFactor },
+        out.viewRig || {},
+      );
       declareViewRig(handle, out.viewRig);
     };
     if (typeof opts.onBeforeFrame === 'function') {
@@ -666,6 +690,7 @@ export function attachPlayCanvasModel(out, wall, canvas, src, opts, pending = []
     if (bounds) {
       out.frame = bounds;
       viewer.fitTo(bounds.center, bounds.extent);
+      depth.refresh();
     }
     return out;
   })();

package/js/inline3d-model.js

@@ -38,9 +38,9 @@
 // your own origin (`/draco/`, `/basis/`) and `opts.decoderPath` moves that. See
 // docs/authoring-inline-3d.md#compressed-gltf.
 
-import { guardedAttach } from './inline3d-splat-shared.js';
+import { guardedAttach, attachModelStereo, attachComfortDepth, resolveDepthOption, framedSubjectBounds } from './inline3d-splat-shared.js';
 import * as THREE from 'three';
-import { EyeCamera, EdgeFeather, DepthCursor, raycastHitTest } from './inline3d-three.js';
+import { EyeCamera, EdgeFeather, DepthCursor, raycastHitTest, displayRig } from './inline3d-three.js';
 import { resolveCursorOption } from './inline3d-cursor-depth.js';
 import { CURSOR_MODEL_RAYS_PER_FRAME } from './inline3d-cursor-perf.js';
 import { SceneViewer } from './inline3d-viewer.js';
@@ -403,6 +403,8 @@ function addModelUnguarded(wall, canvas, src, opts = {}) {
 
   const paths = normalizeDecoderPath(decoderPath);
   const injected = { draco: injectedDraco, ktx2: injectedKtx2, meshopt: injectedMeshopt };
+  // Opt-in comfort depth; a bad value throws here, at the call.
+  const depthOption = resolveDepthOption(opts.depth, '@displayxr/inline3d/model');
 
   const viewer = new SceneViewer(THREE, canvas, {
     virtualDisplayHeight,
@@ -416,6 +418,8 @@ function addModelUnguarded(wall, canvas, src, opts = {}) {
     feather,
     logTag: '[inline3d/model]',
     viewerEase: opts.viewerEase,
+    // Opt-in; undefined = the viewer's own default (a transparent clear).
+    clearColor: opts.clearColor,
   }).useEyeCamera(EyeCamera, EdgeFeather);
   const cursorOpts = resolveCursorOption(opts.cursor, '@displayxr/inline3d/model');
   // Amortised pick (a few rays a frame): the sprite follows the newest pointer position every
@@ -436,6 +440,7 @@ function addModelUnguarded(wall, canvas, src, opts = {}) {
     setPose: (p) => viewer.setPose(p),
     resetPose: () => viewer.resetPose(),
     remove() {
+      depth.dispose();
       handle?.remove();
       viewer.dispose();
       if (out.model) disposeTree(out.model);
@@ -450,6 +455,20 @@ function addModelUnguarded(wall, canvas, src, opts = {}) {
   Object.defineProperty(out, 'renderScale', { get: () => viewer.effectiveRenderScale, enumerable: true, configurable: true });
   Object.defineProperty(out, 'renderScaleRequested', { get: () => viewer.renderScale, enumerable: true, configurable: true });
 
+  // handle.setStereo / handle.rig (a depth slider; nothing is declared until it is called).
+  const stereo = attachModelStereo(out, { getTile: () => handle, vH: virtualDisplayHeight, makeDisplayRig: displayRig });
+  // `depth: 'auto'` (opt-in): the comfort factor under setStereo's, on the same display rig.
+  // Without it, inert: `depthFactor` reads 1 and nothing is measured or declared.
+  const depth = attachComfortDepth(out, {
+    option: depthOption,
+    canvas,
+    getTile: () => handle,
+    getBounds: () => (out.frame ? framedSubjectBounds(viewer) : null),
+    getVH: () => virtualDisplayHeight,
+    apply: (k) => stereo.setBase(k),
+    tag: '[inline3d/model]',
+  });
+
   // Window first, content when it lands — same reasoning as ./splat: a grid should not appear
   // one tile at a time in download order.
   let handle = null;
@@ -528,6 +547,7 @@ function addModelUnguarded(wall, canvas, src, opts = {}) {
     if (bounds) {
       out.frame = bounds;
       viewer.fitTo(bounds.center, bounds.extent);
+      depth.refresh();
     }
     return out;
   })().catch((err) => {

package/js/inline3d-splat-deferred.js

@@ -53,6 +53,8 @@ export function addSplatDeferred(wall, canvas, src, opts) {
     frame: null,
     camera: null,
     rig: null,
+    // The `depth` option's comfort factor in force (1 until measured, and always without it).
+    depthFactor: 1,
     perf: null,
     setPose: page ? pageOnly('setPose') : queue('setPose'),
     resetPose: page ? pageOnly('resetPose') : queue('resetPose'),

package/js/inline3d-splat-pc-entry.js

@@ -16,7 +16,7 @@
 // Not here: measureSplatBounds (it measures a Spark mesh — import it from ./splat).
 
 import { resolveRevealOption } from './inline3d-splat-effects.js';
-import { CAPTURE_FITS, guardedAttach, playcanvasCannotRead, resolveControls } from './inline3d-splat-shared.js';
+import { CAPTURE_FITS, guardedAttach, playcanvasCannotRead, resolveControls, resolveDepthOption } from './inline3d-splat-shared.js';
 import { addSplatDeferred } from './inline3d-splat-deferred.js';
 
 export { applySplatPerf, SPLAT_PERF_PRESETS } from './inline3d-splat-perf.js';
@@ -44,6 +44,7 @@ function addSplatUnguarded(wall, canvas, src, opts = {}) {
     );
   }
   resolveControls(opts);
+  resolveDepthOption(opts.depth);
   resolveRevealOption(opts.reveal);
   const why = playcanvasCannotRead(src, opts);
   if (why) throw new Error(`@displayxr/inline3d/splat: ${why}`);

package/js/inline3d-splat-playcanvas.js

@@ -119,6 +119,12 @@ import {
   normalizeCameraPose,
   coverageExponent,
   declareViewRig,
+  parseClearColor,
+  validateSetStereo,
+  stereoScalarOf,
+  attachComfortDepth,
+  resolveDepthOption,
+  framedSubjectBounds,
 } from './inline3d-splat-shared.js';
 import { resolveCursorOption } from './inline3d-cursor-option.js';
 
@@ -827,6 +833,10 @@ export class PlayCanvasSplatViewer {
       cursor = null,
     } = opts;
     this.canvas = canvas;
+    // `clearColor` (opt-in): the eye cameras' clear, [r,g,b,a] in 0..1, or null = the transparent
+    // clear every tile had before it existed. An OPAQUE clear avoids stale / black pixels where the
+    // weave reads an alpha-0 hole (web#198).
+    this.clearColor = parseClearColor(opts.clearColor, opts.logTag || '[inline3d/splat]');
     // `cursor: 'depth'` (ADR-046): the depth-aware cursor. OPT-IN AND FREE OTHERWISE — its module
     // is imported only when asked for (attachEngine), and every per-frame hook is an optional call
     // on `cursorDepth`, which stays null without it.
@@ -1306,6 +1316,8 @@ export class PlayCanvasSplatViewer {
   onFrame(views, layer, frame) {
     if (this._disposed) return;
     if (this._mode !== '3d') this.stopMono();
+    // cursor: 'depth' hands its depth to this layer where the runtime draws the web cursor (ADR-046 Amendment 4).
+    this._frameLayer = layer || null;
     // 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) {
@@ -1348,6 +1360,7 @@ export class PlayCanvasSplatViewer {
       this._monoRaf = requestAnimationFrame(loop);
       this._beforeFrame?.(null);
       if (this._disposed || this._mode !== 'mono') return; // the callback removed or re-wove us
+      this._frameLayer = null;
       this.cursorDepth?.inactive(); // 2D: the normal cursor
       this._tick();
       this._drawMono();
@@ -1981,7 +1994,7 @@ export class PlayCanvasSplatViewer {
     const pc = this.pc;
     const e = new pc.Entity(name, this.app);
     e.addComponent('camera', {
-      clearColor: new pc.Color(0, 0, 0, 0),
+      clearColor: this.clearColor ? new pc.Color(this.clearColor[0], this.clearColor[1], this.clearColor[2], this.clearColor[3]) : new pc.Color(0, 0, 0, 0),
       nearClip: MONO_NEAR,
       farClip: MONO_FAR,
       fov: MONO_FOV,
@@ -2221,7 +2234,7 @@ export class PlayCanvasSplatViewer {
     // handle.setVideo's plane: size, eye split, and a new frame's upload (./inline3d-splat-video.js).
     this._videoPlane?.beforeDraw(entries, rect);
     // cursor: 'depth' — place the sprite and queue its lines for the tick below (no-op unless opted in).
-    this.cursorDepth?.frame(entries);
+    this.cursorDepth?.frame(entries, this._frameLayer);
     app.tick(now());
     this._afterTick();
     return true;
@@ -3122,41 +3135,9 @@ export function validateWarmEffects(list) {
   });
 }
 
-/**
- * handle.setStereo's argument, validated and merged onto the current override (throws at the
- * call). Returns the new override, or null when nothing is overridden.
- */
-export function validateSetStereo(o, prev) {
-  if (o === null) return null;
-  if (typeof o !== 'object') throw new TypeError('@displayxr/inline3d/splat: setStereo takes an object or null.');
-  // Absolute (…Factor) or RELATIVE to the asset's own (…Scale); per scalar, the last one given wins.
-  const pairs = [
-    ['ipdFactor', 'ipdScale'],
-    ['parallaxFactor', 'parallaxScale'],
-  ];
-  const keys = pairs.flat();
-  const unknown = Object.keys(o).filter((k) => !keys.includes(k));
-  if (unknown.length) throw new Error(`@displayxr/inline3d/splat: setStereo — unknown option(s) ${unknown.join(', ')}.`);
-  for (const [a, b] of pairs) {
-    if (o[a] != null && o[b] != null) throw new Error(`@displayxr/inline3d/splat: setStereo — ${a} and ${b} are exclusive.`);
-  }
-  const next = { ...(prev || {}) };
-  for (const [a, b] of pairs) {
-    for (const k of [a, b]) {
-      if (!(k in o) || o[k] === undefined) continue;
-      if (o[k] === null) {
-        delete next[k];
-        continue;
-      }
-      if (typeof o[k] !== 'number' || !Number.isFinite(o[k]) || o[k] < 0) {
-        throw new RangeError(`@displayxr/inline3d/splat: setStereo — ${k} must be a finite number >= 0 (got ${o[k]}).`);
-      }
-      next[k] = o[k];
-      delete next[k === a ? b : a];
-    }
-  }
-  return Object.keys(next).length ? next : null;
-}
+// validateSetStereo lives in ./inline3d-splat-shared.js now (./model's setStereo shares it); it is
+// re-exported from here so every name this module exported before still resolves.
+export { validateSetStereo };
 
 /**
  * handle.setRig's arguments, validated and resolved (throws at the call, before anything runs).
@@ -3400,6 +3381,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
   // an advanced caller may reach this function directly.
   const ctl = resolveControls(opts);
   const pageMode = ctl.page;
+  const depthOption = resolveDepthOption(opts.depth);
   if (pageMode && ctl.ignored.length) {
     console.info(
       `[inline3d/splat] controls:'page' — the page owns the camera, so ${ctl.ignored.join(', ')} ` +
@@ -3431,10 +3413,27 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     sky: opts.sky,
     viewerEase: opts.viewerEase,
     cursor: opts.cursor,
+    // Opt-in; undefined = the viewer's own default (a transparent clear).
+    clearColor: opts.clearColor,
   });
 
   let handle = null;
   let unbindFocusInput = null;
+  // `depth: 'auto'` (opt-in): the comfort factor, multiplied under setStereo's on the DISPLAY rig
+  // declareDisplay sends (camera rigs and setVideo's own rig never carry it). Without the option:
+  // inert, `depthFactor` 1, nothing measured, nothing declared.
+  const depth = attachComfortDepth(out, {
+    option: depthOption,
+    canvas,
+    getTile: () => handle,
+    getBounds: () => (out.rig && out.rig.type !== 'camera' && !vid?.on ? framedSubjectBounds(viewer) : null),
+    getVH: () => viewer.vH,
+    apply: () => {
+      if (!pageMode && !vid?.on && out.rig?.type !== 'camera' && lastDisplayBase) declareDisplay(lastDisplayBase);
+    },
+    tag: '[inline3d/splat]',
+  });
+  if (pageMode) depth.ignore("controls:'page' (the page's camera rig)");
 
   // ── diagnostics (diag / ?dxrdiag — ./inline3d-splat-diag.js) ──
   const diagCfg = resolveDiag(opts.diag);
@@ -3702,6 +3701,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     effects: () => (fx ? fx.list() : []),
     remove() {
       removed = true;
+      depth.dispose();
       dropVideo(); // before the app goes: the plane's rVFC, and a <video> this handle made
       current = null;
       for (const p of [...livePrepared]) p.dispose();
@@ -4366,9 +4366,11 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     // raw: setVideo's own display rig — not the page's rig, so neither setStereo's factors nor
     // the base setStereo re-declares from.
     if (!raw) lastDisplayBase = base;
+    // The `depth` option's comfort factor (1 without it), × setStereo's: never on setVideo's rig.
+    const kd = raw ? 1 : depth.factor;
     const f =
-      stereoOverride && !raw
-        ? { ...base, ipdFactor: stereoScalar(base.ipdFactor ?? 1, 'ipd'), parallaxFactor: stereoScalar(base.parallaxFactor ?? 1, 'parallax') }
+      (stereoOverride || kd !== 1) && !raw
+        ? { ...base, ipdFactor: stereoScalar(base.ipdFactor ?? 1, 'ipd') * kd, parallaxFactor: stereoScalar(base.parallaxFactor ?? 1, 'parallax') * kd }
         : base;
     const key = `${f.vH}|${f.ipdFactor ?? 1}|${f.parallaxFactor ?? 1}|${f.perspectiveFactor ?? 1}`;
     if (declaredDisplay === key) return;
@@ -4404,6 +4406,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
       viewer.setFocus(modelToContent(resolved.focus), { snap: true, recentre: false });
       lastConvergence = Number.NaN;
       pushViewRig(true);
+      depth.ignore('a camera rig');
       return;
     }
     if (viewer.mono.capture) viewer.useDisplayCamera();
@@ -4422,6 +4425,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
       resolved.focusDefaultSource = 'frame';
       resolved.frame = target;
       declareDisplay(disp);
+      depth.resume();
       return;
     }
     // The splat itself, as a display-rig addSplat frames it (the load-time path).
@@ -4434,6 +4438,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     }
     if (disp) resolved.frame = bounds ? { center: bounds.center.slice(), extent: bounds.extent.slice(), source: 'splat' } : null;
     declareDisplay(disp || { vH: bootFraming.vH });
+    if (bounds) depth.resume();
   }
 
   // ── handle.setStereo: live stereo strength on whatever rig is declared ──
@@ -4449,10 +4454,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
   }
   /** One scalar under setStereo: its absolute value, else `base` × its scale, else `base`. */
   function stereoScalar(base, k) {
-    const o = stereoOverride;
-    if (o?.[`${k}Factor`] != null) return o[`${k}Factor`];
-    if (o?.[`${k}Scale`] != null) return base * o[`${k}Scale`];
-    return base;
+    return stereoScalarOf(stereoOverride, base, k);
   }
 
   /**
@@ -4940,6 +4942,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     lastConvergence = s.lastConvergence;
     state.on = false;
     if (stereoOverride !== state.stereoAtEnter) redeclareStereo(); // a setStereo made while the video held the rig
+    depth.refresh(); // the `depth` option holds still under a video; measure again (no-op without it)
 
   }