@displayxr/inline3d 1.29.0 → 1.31.0

package/index.d.ts

@@ -555,7 +555,63 @@ export interface CreateInline3DOptions {
    * `trackingstatechange` and do the same for a scene.
    */
   untrackedFallback?: 'none' | 'mono';
+  /**
+   * The TRACKING EASE, as the default for every SDK renderer drawing through this session
+   * (`./viewer`'s SceneViewer, `./splat` and `./model` on both engines). When a viewer is
+   * acquired — the views jump from the runtime's nominal viewer to the tracked eyes — or lost,
+   * the eye cameras glide from where they were drawn to the new views over `durationMs` instead
+   * of snapping in one frame; everything parented to the views (parallax, display-rig layers)
+   * follows. Triggered by a jump in the views around a `trackingState` edge (or, where the browser
+   * reports no state, by a large one-frame jump); a no-op when the vendor already animates the eyes. On by default; `false` restores
+   * the snap; a renderer's own `viewerEase` option overrides this. A page rendering its own
+   * `addScene` can use the exported {@link ViewerEase}.
+   */
+  viewerEase?: ViewerEaseOption;
+}
+
+/** `true`/unset = on with defaults, `false` = off, or tune it. */
+export type ViewerEaseOption =
+  | boolean
+  | {
+      /** Default true. */
+      enabled?: boolean;
+      /** The glide, in ms (default 300). 0 disables. */
+      durationMs?: number;
+      /** 'smoothstep' (default) | 'linear' | 'easeOutCubic'. */
+      easing?: 'smoothstep' | 'linear' | 'easeOutCubic' | string;
+    };
+
+/** One frame's matrices as an SDK renderer copies them out of an XRView (column-major). */
+export interface ViewerEaseEntry {
+  proj: Float32Array | Float64Array | number[];
+  pose: Float32Array | Float64Array | number[];
+}
+
+/**
+ * The tracking ease on its own, for a page that renders its own `addScene`: copy each view's
+ * `projectionMatrix` and `transform.matrix` into an entry, call `apply(entries,
+ * frame.session.trackingState)` once per LIVE frame, and render from the entries (keep using the
+ * real XRView for `layer.getViewport`). It rewrites the entries only while an ease is running.
+ */
+export declare class ViewerEase {
+  constructor(opts?: ViewerEaseOption & object);
+  readonly enabled: boolean;
+  readonly durationMs: number;
+  readonly easing: string;
+  /** Is an ease running right now? */
+  readonly active: boolean;
+  /** What the last apply() did: the weight of the old views (0 = passed through), the trigger, the jump (eye separations). */
+  readonly last: { weight: number; reason: null | 'armed-jump' | 'jump' | 'easing'; jump: number };
+  apply(entries: ViewerEaseEntry[], trackingState?: XRTrackingState | string | null, timeMs?: number): number;
+  configure(opts?: ViewerEaseOption): void;
+  /** Forget the previous frame (call after a resize or a view-count change you handle yourself). */
+  reset(): void;
 }
+export function resolveViewerEaseOption(opt?: ViewerEaseOption): { enabled: boolean; durationMs: number; easing: string };
+/** `frame.session.trackingState`, or null when the browser does not report one. */
+export function frameTrackingState(frame: unknown): XRTrackingState | null;
+/** 300. */
+export const VIEWER_EASE_DEFAULT_MS: number;
 
 /**
  * The eased 2D<->3D transition — on by default, and the same sequencer (and the same defaults)

package/js/call/capture.js

@@ -1,212 +1,4 @@
-// call/capture.js — getting a camera (+ microphone) and knowing what it is (RFC §4).
-//
-// `camera: 'auto'` looks for a device that delivers a side-by-side PAIR — one device whose frame
-// is wider than 2.5:1 (a USB stereo camera enumerates as one wide device: field data has one at
-// 1280x480, i.e. 640x480 per eye, grayscale and UNRECTIFIED). Found → sent as `sbs`. Otherwise the
-// default webcam, sent as `mono`. Per-eye width is whatever the camera gives; nothing is upscaled.
-//
-// Two field facts shape the probing:
-//  - On some laptops the stereo camera is held EXCLUSIVELY by the eye tracker, so opening it
-//    fails with NotReadableError ("Device in use"). That device is skipped silently — a call must
-//    never fail because an optional camera is busy.
-//  - Labels are empty until one getUserMedia has succeeded, so the default camera is opened first
-//    (which is also the fallback), then the others are probed one at a time.
-//
-// RECTIFICATION is not done here (P2): it needs the camera's calibration (intrinsics/extrinsics
-// for the ACTIVE device), which comes from a plug-in or the runtime. P1 sends the raw pair with
-// `rectified: false`, and the `rectify` hook (addCall option) is where a calibrated step plugs in:
-// `(stream, info) => MediaStream | Promise<MediaStream>`, returning a rectified SBS stream.
-
-import { looksSbs } from './wire.js';
-
-const MONO_CONSTRAINTS = { width: { ideal: 1280 }, height: { ideal: 720 }, frameRate: { ideal: 30 } };
-// Ask a candidate stereo device for its widest mode; a 2560x720 or 3840x1080 pair comes back as
-// itself, a 1280x480 one as 1280x480. `ideal`, never `min`: a smaller real pair is still a pair.
-const PROBE_CONSTRAINTS = { width: { ideal: 3840 }, height: { ideal: 1080 }, frameRate: { ideal: 30 } };
-export const AUDIO_CONSTRAINTS = Object.freeze({ echoCancellation: true, noiseSuppression: true, autoGainControl: true });
-
-/** 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 || ''));
-}
-
-/**
- * Why no camera could be opened, from the per-device failures. `'camera-busy'` when every device
- * that exists is held by another process — on a 3D laptop/monitor whose only camera is the eye
- * tracker's, that is the normal case while tracking, and the call should go audio-only and say so
- * rather than fail or send an empty picture. Pure.
- * @param {Array<{error: string, busy?: boolean}>} skipped
- */
-export function noCameraCode(skipped) {
-  return skipped.length && skipped.every((s) => s.busy) ? 'camera-busy' : 'no-camera';
-}
-
-/** A label that names a stereo camera, tried first when probing. Pure. */
-export function stereoLabelHint(label) {
-  return /stereo|\b3d\b|\bsbs\b|dual/i.test(label || '');
-}
-
-/**
- * Open the camera. Never rejects for a busy optional device; rejects only when NO camera can be
- * opened at all (the caller then runs audio-only or reports the error).
- *
- * @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 }} [o]
- * @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 }>}
- */
-export async function openCamera(want = 'auto', o = {}) {
-  const md = o.mediaDevices || (globalThis.navigator && navigator.mediaDevices);
-  const log = o.log || (() => {});
-  const skipped = [];
-  const cal = o.calibration || {};
-
-  if (want && typeof want === 'object' && typeof want.getVideoTracks === 'function') {
-    const t = want.getVideoTracks()[0];
-    const st = t ? t.getSettings() : {};
-    // A page-supplied stream carries a DECLARED format; aspect is never used to guess 3D-ness here.
-    const format = o.format === 'sbs' ? 'sbs' : 'mono';
-    return { stream: want, format, width: st.width || 0, height: st.height || 0, deviceId: st.deviceId || null, label: t ? t.label : '', owned: false, skipped, calibration: cal };
-  }
-  if (!md || !md.getUserMedia) throw Object.assign(new Error('getUserMedia is not available (insecure context?)'), { code: 'no-camera' });
-
-  const open = async (constraints) => {
-    const s = await md.getUserMedia({ video: constraints, audio: false });
-    const t = s.getVideoTracks()[0];
-    const st = t ? t.getSettings() : {};
-    // Never hand back a 0x0 track: some engines open a device that then delivers nothing.
-    if (!t || t.readyState === 'ended' || !(st.width > 0) || !(st.height > 0)) {
-      s.getTracks().forEach((x) => x.stop());
-      throw Object.assign(new Error('the camera opened but delivers no picture (0x0)'), { name: 'NotReadableError' });
-    }
-    // The DisplayXR Browser's "3D Camera (DisplayXR)" (the runtime's stereo camera, e.g. an SR
-    // eye-tracking camera shared without stealing it) describes itself on the opened track:
-    // `displayxrStereo: {layout, rectified, baselineMm, horizontalFovDeg}`.
-    const stereo = st.displayxrStereo && st.displayxrStereo.layout === 'side-by-side' ? st.displayxrStereo : null;
-    return { stream: s, track: t, width: st.width, height: st.height, deviceId: st.deviceId || null, label: t.label || '', stereo };
-  };
-  const skip = (label, err) => {
-    skipped.push({ label, error: `${err.name}: ${err.message}`, busy: isBusyError(err) });
-    log('camera-skip', { label, error: err.name });
-  };
-  const stop = (r) => r && r.stream.getTracks().forEach((t) => t.stop());
-  const result = (r, format) => ({
-    stream: r.stream, format, width: r.width, height: r.height, deviceId: r.deviceId, label: r.label, owned: true, skipped,
-    calibration: {
-      rectified: false,
-      // A runtime stereo camera's own description, where the page gave none.
-      ...(format === 'sbs' && r.stereo
-        ? {
-            rectified: !!r.stereo.rectified,
-            ...(r.stereo.baselineMm > 0 ? { baselineMm: r.stereo.baselineMm } : {}),
-            ...(r.stereo.horizontalFovDeg > 0 ? { hfovDeg: r.stereo.horizontalFovDeg } : {}),
-          }
-        : {}),
-      ...cal,
-    },
-  });
-
-  // An explicit device id.
-  if (typeof want === 'string' && !['auto', 'stereo', 'mono'].includes(want)) {
-    let r;
-    try {
-      r = await open({ deviceId: { exact: want }, ...PROBE_CONSTRAINTS });
-    } catch (err) {
-      skip(want, err);
-      throw Object.assign(new Error(`camera unavailable: ${err.message}`), { code: noCameraCode(skipped), skipped });
-    }
-    if (looksSbs(r.width, r.height)) return result(r, 'sbs');
-    stop(r);
-    return result(await open({ deviceId: { exact: want }, ...MONO_CONSTRAINTS }), 'mono');
-  }
-
-  // Fast path: when labels are already visible (camera permission persisted), open a device that
-  // NAMES itself stereo — e.g. the DisplayXR Browser's "3D Camera (DisplayXR)" — directly. Every
-  // camera start can take seconds (a busy capture stack took 7-20 s per start on a field box), and
-  // the default-first probe below costs two or three of them before it reaches the pair.
-  const tried = new Set();
-  if (want !== 'mono') {
-    let early = [];
-    try {
-      early = (await md.enumerateDevices()).filter((d) => d.kind === 'videoinput' && d.deviceId && stereoLabelHint(d.label));
-    } catch {
-      /* no enumeration yet: the normal path below */
-    }
-    for (const d of early) {
-      tried.add(d.deviceId);
-      let r = null;
-      try {
-        r = await open({ deviceId: { exact: d.deviceId }, ...PROBE_CONSTRAINTS });
-      } catch (err) {
-        skip(d.label, err);
-        continue;
-      }
-      if (looksSbs(r.width, r.height)) {
-        log('camera-sbs', { label: r.label, width: r.width, height: r.height, direct: true });
-        return result(r, 'sbs');
-      }
-      stop(r);
-    }
-  }
-
-  // The default camera first: permission, labels, and the fallback.
-  let mono = null;
-  try {
-    mono = await open(MONO_CONSTRAINTS);
-  } catch (err) {
-    skip('default', err);
-  }
-  if (want === 'mono' && mono) return result(mono, 'mono');
-  if (mono && looksSbs(mono.width, mono.height)) return result(mono, 'sbs'); // the default IS the pair
-
-  let devices = [];
-  try {
-    devices = (await md.enumerateDevices()).filter((d) => d.kind === 'videoinput');
-  } catch {
-    /* no enumeration: keep the default */
-  }
-  devices.sort((a, b) => Number(stereoLabelHint(b.label)) - Number(stereoLabelHint(a.label)));
-  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 (tried.has(d.deviceId)) continue; // the fast path already opened it (not a pair, or busy)
-    let r = null;
-    try {
-      r = await open({ deviceId: { exact: d.deviceId }, ...PROBE_CONSTRAINTS });
-    } catch (err) {
-      // NotReadableError = held by another process (e.g. an eye tracker). Skip, never fail.
-      skip(d.label, err);
-      continue;
-    }
-    if (looksSbs(r.width, r.height)) {
-      stop(mono);
-      log('camera-sbs', { label: r.label, width: r.width, height: r.height });
-      return result(r, 'sbs');
-    }
-    stop(r);
-  }
-  if (mono) {
-    if (want === 'stereo') log('camera-no-stereo', { fallback: mono.label });
-    return result(mono, 'mono');
-  }
-  const code = noCameraCode(skipped);
-  throw Object.assign(
-    new Error(code === 'camera-busy' ? 'every camera is in use by another app (e.g. eye tracking)' : 'no camera could be opened'),
-    { code, skipped }
-  );
-}
-
-/** The microphone, with echo cancellation and noise suppression. Null if unavailable/denied. */
-export async function openMic(o = {}) {
-  const md = o.mediaDevices || (globalThis.navigator && navigator.mediaDevices);
-  try {
-    const s = await md.getUserMedia({ audio: { ...AUDIO_CONSTRAINTS }, video: false });
-    return s.getAudioTracks()[0] || null;
-  } catch (err) {
-    (o.log || (() => {}))('mic-skip', { error: err && err.name });
-    return null;
-  }
-}
+// call/capture.js — moved to js/camera/capture.js in C2 (RFC 0003 §4: device selection,
+// calibration and the busy-device skip belong to `@displayxr/inline3d/camera`). This path
+// re-exports it so test imports and any in-tree reference keep resolving.
+export * from '../camera/capture.js';