@displayxr/inline3d 1.49.1 → 1.49.3

package/js/camera/capture.js

@@ -49,6 +49,47 @@ const MONO_CONSTRAINTS = { width: { ideal: 1280 }, height: { ideal: 720 }, frame
 const PROBE_CONSTRAINTS = { width: { ideal: 3840 }, height: { ideal: 1080 }, frameRate: { ideal: 30 } };
 export const AUDIO_CONSTRAINTS = Object.freeze({ echoCancellation: true, noiseSuppression: true, autoGainControl: true });
 
+// How long `'auto'` / `'stereo'` waits, in a DisplayXR Browser with labels visible, for the
+// runtime's 3D camera to be listed before it opens any plain lens (see openCamera), and how often
+// it re-reads the list meanwhile (a `devicechange` re-reads at once).
+export const STEREO_WAIT_MS = 2500;
+const STEREO_WAIT_STEP_MS = 500;
+
+/**
+ * The default `stereoWaitMs`: STEREO_WAIT_MS in a DisplayXR Browser (the same test as
+ * inline3DAvailable(): a runtime 3D camera can be listed there), else 0. Pure apart from globals.
+ */
+export function defaultStereoWaitMs() {
+  return inDisplayXRBrowser() ? STEREO_WAIT_MS : 0;
+}
+
+/** The same test as inline3DAvailable() (navigator.xr + XRDisplayLayer), without importing the core. */
+function inDisplayXRBrowser() {
+  return typeof navigator !== 'undefined' && !!navigator.xr && typeof window !== 'undefined' && typeof window.XRDisplayLayer === 'function';
+}
+
+/** Resolves on the next `devicechange` of `md`, or after `ms`, whichever is first. */
+function nextDeviceChange(md, ms) {
+  return new Promise((resolve) => {
+    let timer = 0;
+    const done = () => {
+      clearTimeout(timer);
+      try {
+        md.removeEventListener?.('devicechange', done);
+      } catch {
+        /* no events */
+      }
+      resolve();
+    };
+    timer = setTimeout(done, ms);
+    try {
+      md.addEventListener?.('devicechange', done);
+    } catch {
+      /* no events: the timer alone */
+    }
+  });
+}
+
 /** Errors that mean "the device exists but another process holds it" (an eye tracker, say). */
 export function isBusyError(err) {
   return !!err && (err.name === 'NotReadableError' || err.name === 'TrackStartError' || /in use|busy/i.test(err.message || ''));
@@ -129,9 +170,12 @@ export function stereoLabelHint(label) {
  * @param {'auto'|'stereo'|'mono'|string|MediaStream} want  'auto' | 'stereo' | 'mono' | a
  *        deviceId | a page-supplied MediaStream
  * @param {{ format?: 'sbs'|'mono', calibration?: {baselineMm?: number, hfovDeg?: number, rectified?: boolean},
- *           mediaDevices?: MediaDevices, log?: Function, exclude?: false|Array<string|RegExp> }} [o]
+ *           mediaDevices?: MediaDevices, log?: Function, exclude?: false|Array<string|RegExp>,
+ *           stereoWaitMs?: number }} [o]
  *        `exclude`: devices no probe may open (see cameraExcluder); an explicit deviceId is the
  *        page's own choice and is opened regardless.
+ *        `stereoWaitMs`: with labels visible and no stereo-named device listed, how long to wait
+ *        for one before opening a plain lens (default defaultStereoWaitMs(); 0 = one re-read).
  * @returns {Promise<{ stream: MediaStream, format: 'sbs'|'mono', width: number, height: number,
  *           deviceId: string|null, label: string, owned: boolean, skipped: Array<{label: string, error: string}>,
  *           calibration: object }>}
@@ -320,16 +364,38 @@ export async function openCamera(want = 'auto', o = {}) {
     }
     return null;
   };
+  // Re-read the list until a stereo-named device opens or `ms` is up: on each `devicechange` and
+  // every STEREO_WAIT_STEP_MS. `ms` <= 0: one re-read. Stops early once a named pair was listed and
+  // failed to open (busy): waiting longer would not free it.
+  const waitMs = Number.isFinite(o.stereoWaitMs) ? Math.max(0, o.stereoWaitMs) : defaultStereoWaitMs();
+  const waitForNamedPair = async (ms) => {
+    if (!(ms > 0)) return tryNamedPairs(await listCameras());
+    const deadline = Date.now() + ms;
+    log('camera-wait-stereo', { ms });
+    for (;;) {
+      const left = deadline - Date.now();
+      if (left <= 0) break;
+      await nextDeviceChange(md, Math.min(STEREO_WAIT_STEP_MS, left));
+      const list = await listCameras();
+      const r = await tryNamedPairs(list);
+      if (r) return r;
+      if (list.some((d) => stereoLabelHint(d.label) && !isApp(d))) break; // listed, tried, not usable
+    }
+    log('camera-no-stereo-listed', { ms });
+    return null;
+  };
   let mono = null;
   if (want !== 'mono') {
     let listed = await listCameras();
     let pair = await tryNamedPairs(listed);
     if (pair) return result(pair, 'sbs');
     // Labels visible but no stereo-named device: a runtime 3D camera can join the list late (after
-    // a runtime restart), so read it once more before falling back.
+    // a runtime restart; on Android the runtime lists its cameras lazily). In a DisplayXR Browser
+    // wait for it BEFORE any plain lens is opened (stereoWaitMs): on some phones opening a physical
+    // lens while head tracking streams crashes the camera HAL, and the runtime's pair goes down with
+    // it. Elsewhere read the list once more.
     if (listed.some((d) => d.label) && !listed.some((d) => stereoLabelHint(d.label))) {
-      listed = await listCameras();
-      pair = await tryNamedPairs(listed);
+      pair = await waitForNamedPair(waitMs);
       if (pair) return result(pair, 'sbs');
     }
     // No labels yet (no permission). Prime it on the default camera with NO constraints (a facing
@@ -392,9 +458,14 @@ export async function openCamera(want = 'auto', o = {}) {
   }
   // A label that names a pair first; never by list position (see the header).
   devices.sort((a, b) => Number(stereoLabelHint(b.label)) - Number(stereoLabelHint(a.label)));
+  // In a DisplayXR Browser a stereo camera (a USB SBS webcam included) is the runtime's named
+  // "3D Camera", so once a plain lens is in hand no other plain lens is opened to test its shape:
+  // on some phones that extra open crashes the camera HAL.
+  const shapeProbe = !inDisplayXRBrowser();
   for (const d of devices) {
     if (!d.deviceId) continue; // no permission yet: an anonymous entry cannot be opened by id
     if (mono && d.deviceId === mono.deviceId) continue;
+    if (mono && !shapeProbe && !stereoLabelHint(d.label)) continue;
     if (tried.has(d.deviceId) || excludedIds.has(d.deviceId)) continue; // already opened (not a pair, or busy) or left out
     if (listedExcluded(d)) continue; // the last resort never opens a sensor (a hand-tracking camera)
     let r = null;
@@ -414,7 +485,7 @@ export async function openCamera(want = 'auto', o = {}) {
     // No default could be used (excluded, busy): the first plain camera found is the fallback.
     if (!mono && !isPair(r)) {
       mono = await withMode(r, MONO_CONSTRAINTS);
-      if (want === 'mono') return result(mono, 'mono');
+      if (want === 'mono' || !shapeProbe) return result(mono, 'mono');
       continue;
     }
     stop(r);

package/js/inline3d-call.js

@@ -2565,7 +2565,7 @@ class SelfTile {
 
   /** For `call.diagnostics().self`: what the self view actually shows. */
   diag() {
-    if (!this.view) return { route: null, woven: false, reason: 'no-camera', firstWoven: null, layerRetries: 0 };
+    if (!this.view) return { route: null, woven: false, reason: 'no-camera', firstWoven: null, layerRetries: 0, frameAgeMs: null };
     return this.view.weaveState();
   }
 

package/js/inline3d-camera.js

@@ -441,7 +441,11 @@ class StereoCamera {
  * are in `skipped` with `excluded: true`. An explicit `deviceId` or `label:` is the page's choice
  * and is opened regardless.
  *
- * @param {object|string|MediaStream} [opts]  `{ prefer, format, calibration, rectify, exclude, debug }` (or just `prefer`)
+ * In a DisplayXR Browser with labels visible and no 3D camera listed yet, `'auto'` / `'stereo'`
+ * waits up to `stereoWaitMs` (default 2500) for the runtime's 3D camera to be listed before it
+ * opens any plain lens (docs/camera.md, "Waiting for the 3D camera").
+ *
+ * @param {object|string|MediaStream} [opts]  `{ prefer, format, calibration, rectify, exclude, stereoWaitMs, debug }` (or just `prefer`)
  */
 export async function openCamera(opts = {}) {
   const o = typeof opts === 'string' || (opts && typeof opts.getVideoTracks === 'function') ? { prefer: opts } : opts || {};
@@ -451,7 +455,7 @@ export async function openCamera(opts = {}) {
   // `horizontalFovDeg` is the public spelling (RFC 0003 §4); the hello wire field is `hfovDeg`.
   if (cal.horizontalFovDeg > 0 && !(cal.hfovDeg > 0)) cal.hfovDeg = cal.horizontalFovDeg;
   delete cal.horizontalFovDeg;
-  const r = await openDevice(prefer, { format: o.format, calibration: cal, mediaDevices: o.mediaDevices, log: log || undefined, exclude: o.exclude });
+  const r = await openDevice(prefer, { format: o.format, calibration: cal, mediaDevices: o.mediaDevices, log: log || undefined, exclude: o.exclude, stereoWaitMs: o.stereoWaitMs });
   if (r.format === 'sbs' && typeof o.rectify === 'function') {
     // A calibrated rectification step (plug-in or runtime supplied): its output is a rectified
     // SBS stream, and the record then says so. A throwing hook keeps the raw pair.
@@ -560,6 +564,8 @@ class CameraView {
     this._scratch = null;
     this._luma = null; // the latest grayscale source copy (auto-convergence and the depth cursor read it)
     this.disparityPx = null;
+    this._lastFrameAt = 0; // performance.now() of the last NEW camera frame (0 = none yet)
+    this._lastVideoTime = -1;
     // `cursor: 'depth'` (ADR-046 on a pair): validated now, its module loaded only on opt-in.
     this._cursorOpt = resolvePairCursorOption(o.cursor, '@displayxr/inline3d/camera');
     /** The depth cursor once its module has loaded; null without `cursor: 'depth'`. */
@@ -594,9 +600,28 @@ class CameraView {
       reason: this.fallbackReason,
       firstWoven: this.route === 'woven-sbs' ? (this._fw ? { ...this._fw } : 'pending') : null,
       layerRetries: this._layerFails,
+      frameAgeMs: this.frameAgeMs,
     };
   }
 
+  /**
+   * Milliseconds since the camera last delivered a NEW frame to this view (its video's
+   * `currentTime` moved), or null before the first one. A view whose track stalls (a camera taken
+   * by another app, a suspended capture) keeps painting its last frame; this is how a page tells.
+   */
+  get frameAgeMs() {
+    return this._lastFrameAt ? Math.round(performance.now() - this._lastFrameAt) : null;
+  }
+
+  /** Note a new camera frame (the video's clock moved since the last paint). */
+  _noteFrame(v) {
+    if ((v.readyState || 0) < 2) return;
+    const t = v.currentTime;
+    if (t === this._lastVideoTime) return;
+    this._lastVideoTime = t;
+    this._lastFrameAt = performance.now();
+  }
+
   /** The per-eye convergence shift currently painted, source px. */
   get convergencePx() {
     return this.conv.current;
@@ -654,7 +679,14 @@ class CameraView {
   }
 
   _registerWoven() {
-    if (!this.buffer) this.buffer = document.createElement('canvas');
+    if (!this.buffer) {
+      // Empty until the camera's first frame is painted into it: the wall does not count an empty
+      // buffer as a stereo frame, so firstWoven cannot settle "woven" over a tile that never
+      // showed the camera (a track that delivers no frames).
+      this.buffer = document.createElement('canvas');
+      this.buffer.width = 0;
+      this.buffer.height = 0;
+    }
     this._paintWoven(); // the first frame exists before the layer does
     const handle = this.rectCover === undefined ? this.wall.addImage(this.canvas, this.buffer) : this.wall.addImage(this.canvas, this.buffer, { rectCover: this.rectCover });
     this.handle = handle;
@@ -733,6 +765,7 @@ class CameraView {
     if (this.removed) return;
     const v = this.cam.video;
     if (!v || this.cam.state === 'closed') return;
+    this._noteFrame(v);
     if (this.route === 'woven-sbs') this._paintWoven();
     else this._paintFlat(v);
   }

package/js/inline3d.js

@@ -3345,7 +3345,10 @@ class Inline3D {
         this._paint(win, views);
         // An SBS paint with a real source behind it. Before the image has loaded (or while a
         // video has never had a frame) the tile holds nothing worth revealing yet.
-        if (win.sbs && (win.kind === 'video' ? ((win.video && win.video.readyState) || 0) >= 2 : !!win.img)) {
+        // A canvas source counts once it has pixels: an empty (0x0) buffer is a page that has not
+        // drawn its first frame yet (a camera view before the camera's first frame), and settling
+        // firstWoven on it reported a tile woven that had never shown anything.
+        if (win.sbs && (win.kind === 'video' ? ((win.video && win.video.readyState) || 0) >= 2 : sourceHasPixels(win.img))) {
           win.fwStereo = true;
           win.lfStereo = true;
           if (win.rw) win.rw.stereo = true;
@@ -3867,6 +3870,18 @@ function firstWovenHold(v) {
   return typeof v === 'number' && Number.isFinite(v) && v >= 0 ? v : FIRST_WOVEN_HOLD_MS;
 }
 
+/**
+ * True when an image source has something to draw: a loaded image, a sized canvas or bitmap. A
+ * source that reports no size at all (a test double) keeps the old rule: present = drawable.
+ */
+function sourceHasPixels(src) {
+  if (!src) return false;
+  const w = src.naturalWidth ?? src.videoWidth ?? src.width;
+  const h = src.naturalHeight ?? src.videoHeight ?? src.height;
+  if (w === undefined && h === undefined) return true;
+  return w > 0 && h > 0;
+}
+
 function loadImage(source) {
   if (typeof source !== 'string') return Promise.resolve(source); // element/bitmap/canvas
   return new Promise((resolve, reject) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@displayxr/inline3d",
-  "version": "1.49.1",
+  "version": "1.49.3",
   "description": "Turn any HTML <canvas> into a 3D window on a spatial display, inside an ordinary web page, for the DisplayXR Browser. Dependency-free; progressive enhancement (falls back to plain 2D everywhere else).",
   "type": "module",
   "types": "./index.d.ts",