@displayxr/inline3d 1.26.0 → 1.28.0

package/js/inline3d.js

@@ -35,6 +35,10 @@ export { undock, undockAvailable, undockUrl, tileScreenRect };
 // The eased 2D<->3D transition. A pure state machine (no DOM, no WebXR) ported from the native
 // `dxr::ModeSwitch`, so the browser eases the disparity around a mode switch the same way — and in
 // the same ORDER — as the native apps and the demos. See _requestRenderingModeEased.
+// The device-limit clamp on a backing store (MAX_TEXTURE_SIZE & co.), shared with ./viewer,
+// ./splat and ./model. Dependency-free.
+import { probeBufferLimits, clampEyeBuffer, clampWarning, bufferScale, mismatchWarning } from './inline3d-buffer-limit.js';
+
 import {
   ModeSwitch,
   MODE_SWITCH_DEFAULT_DURATION_MS,
@@ -2340,17 +2344,108 @@ class Inline3D {
     win.autoExcluded.clear();
   }
 
-  /** The per-eye buffer size this window should have right now (explicit, or box × dpr). */
-  _eyeSize(win) {
+  /**
+   * The per-eye buffer size this window should have right now: explicit, or box × dpr — capped
+   * at the SOURCE's own per-eye resolution for image and video windows.
+   *
+   * WHY THE CAP (measured, NP02J tablet, DisplayXR Browser 1.0.6): the player sample's 90vw
+   * tile at dpr 2 asked for a 4608×1296 backing store for a 640×360-per-eye clip — 13× the
+   * source's pixels, re-drawn every frame. The page fell to 25 fps and dropped 47 of 97 video
+   * frames; the same clip in a 45vw tile (2304×648) ran at 57 fps with 0 dropped. Drawing a
+   * source into a buffer larger than itself adds no detail: the compositor scales the layer to
+   * the box either way, so upscaling here only spends GPU fill-rate. The cap keeps the BOX
+   * aspect (the eyes stay correctly shaped) and only shrinks, never grows past box × dpr.
+   * An explicit {width, height} is the page's call and is never capped by the source.
+   *
+   * THEN THE DEVICE LIMIT, on every window including an explicit size: the whole store (2 × eye
+   * wide in SBS) must fit min(MAX_TEXTURE_SIZE, MAX_RENDERBUFFER_SIZE, MAX_VIEWPORT_DIMS), or
+   * the weave cannot take it as one texture. An Android 3D tablet (Adreno 740) reports 4096 where
+   * desktops report 16384. Both axes shrink by one factor (./inline3d-buffer-limit.js), warned
+   * once per window. `win.bufScale` records the total shrink so buffer-px decoration
+   * (cornerRadius, feather) keeps its on-screen size.
+   */
+  _eyeSize(win, sbs = true) {
     const dpr = Math.min(window.devicePixelRatio || 1, 2);
-    return {
-      w: win.reqW || Math.round((win.canvas.clientWidth || 256) * dpr),
-      h: win.reqH || Math.round((win.canvas.clientHeight || 256) * dpr),
-    };
+    let w = win.reqW || Math.round((win.canvas.clientWidth || 256) * dpr);
+    let h = win.reqH || Math.round((win.canvas.clientHeight || 256) * dpr);
+    let scale = 1;
+    const eye = !win.reqW && !win.reqH && this._sourceEyeSize(win);
+    if (eye) {
+      // The smallest buffer that still holds every source pixel along the axis that fills the box.
+      const s = Math.max(eye.w / w, eye.h / h);
+      if (s < 1) {
+        scale = s;
+        w = Math.max(1, Math.round(w * s));
+        h = Math.max(1, Math.round(h * s));
+      }
+    }
+    const c = clampEyeBuffer(w, h, probeBufferLimits(), { cols: sbs ? 2 : 1 });
+    if (c.clamped) {
+      scale *= c.scale;
+      w = c.eyeW;
+      h = c.eyeH;
+      if (!win.warnedBufClamp) {
+        win.warnedBufClamp = true;
+        console.warn(clampWarning('[inline3d]', c));
+      }
+    }
+    win.bufScale = scale;
+    return { w, h };
+  }
+
+  /** One eye of an image/video window's source (an SBS pair: left eye = left half), or null. */
+  _sourceEyeSize(win) {
+    if (win.kind !== 'video' && win.kind !== 'image') return null;
+    const src = win.kind === 'video' ? win.video : win.img;
+    if (!src) return null;
+    const sw = src.videoWidth || src.naturalWidth || src.width;
+    const sh = src.videoHeight || src.naturalHeight || src.height;
+    if (!(sw > 1) || !(sh > 0)) return null;
+    return { w: sw / 2, h: sh };
+  }
+
+  /**
+   * A scene canvas is the app's to size, so the core cannot clamp it — but it can SEE the browser
+   * clamp it. Where the store exceeds the device's MAX_TEXTURE_SIZE (4096 on an Adreno 740 tablet)
+   * the drawing buffer silently comes out smaller than canvas.width, while getViewport() keeps
+   * splitting canvas.width: the eye boundary lands off-centre and the panel shows a double image.
+   * Say so once. ./viewer, ./splat and ./model clamp before sizing and never trip this.
+   *
+   * Only called after the app has drawn a stereo frame, so the canvas already HAS its context:
+   * getContext() of the same type returns it, of another type returns null — it never creates one.
+   */
+  _checkSceneBuffer(win) {
+    const c = win.canvas;
+    if (!c || typeof c.getContext !== 'function') return;
+    if (win.sceneGl === undefined) {
+      let gl = null;
+      try {
+        gl = c.getContext('webgl2') || c.getContext('webgl');
+      } catch {
+        gl = null;
+      }
+      win.sceneGl = gl && typeof gl.drawingBufferWidth === 'number' ? gl : null;
+    }
+    if (!win.sceneGl) return;
+    const b = bufferScale(c, win.sceneGl);
+    if (b.mismatch) {
+      win.warnedBufMismatch = true;
+      console.warn(
+        mismatchWarning(
+          '[inline3d]',
+          c,
+          b,
+          'getViewport() splits canvas.width, so the eyes are off-centre in the woven buffer. This ' +
+            'scene canvas is sized by the page: keep 2 × eye width and the height within ' +
+            'MAX_TEXTURE_SIZE / MAX_RENDERBUFFER_SIZE / MAX_VIEWPORT_DIMS, or map getViewport() onto ' +
+            'gl.drawingBufferWidth/Height.',
+        ),
+      );
+    }
   }
 
   _sizeBuffer(win, sbs) {
-    const { w: boxW, h: boxH } = this._eyeSize(win);
+    const { w: boxW, h: boxH } = this._eyeSize(win, sbs);
     win.eyeW = boxW;
     win.eyeH = boxH;
     win.canvas.width = sbs ? boxW * 2 : boxW; // SBS = two eye tiles wide
@@ -2473,10 +2568,25 @@ class Inline3D {
     const srcW = src.videoWidth || src.naturalWidth || src.width;
     const srcH = src.videoHeight || src.naturalHeight || src.height;
     if (!srcW || !srcH) return;
+    // The buffer is capped at the source's per-eye resolution (_eyeSize), and a source's size is
+    // only known once it has decoded — or changes on a new title. Re-derive on a change; the
+    // resize clears the buffer, and the paint right below refills it.
+    const srcKey = srcW + 'x' + srcH;
+    if (win.srcKey !== srcKey) {
+      win.srcKey = srcKey;
+      if (win.ownsBuffer && !(win.reqW && win.reqH)) {
+        const { w, h } = this._eyeSize(win, win.sbs);
+        if (w !== win.eyeW || h !== win.eyeH) this._sizeBuffer(win, win.sbs);
+      }
+    }
+    // cornerRadius / feather are buffer px at the UNCAPPED size; keep their on-screen size.
+    const k = win.bufScale || 1;
+    const radius = win.cornerRadius * k;
+    const feather = win.feather * k;
     ctx.clearRect(0, 0, c.width, c.height);
     if (!win.sbs) {
       // Flat fallback: left eye only, stretched to the square buffer.
-      drawEye(ctx, src, 0, 0, srcW / 2, srcH, 0, 0, c.width, c.height, win.cornerRadius, win.feather);
+      drawEye(ctx, src, 0, 0, srcW / 2, srcH, 0, 0, c.width, c.height, radius, feather);
       return;
     }
     const halfDst = c.width / 2;
@@ -2487,16 +2597,16 @@ class Inline3D {
     // as a squeezed pair). See _trackBakedStereo.
     const stereo = Math.min(this._stereoFactor, this._bakedStereo);
     if (stereo < 1) {
-      drawEye(ctx, src, 0, 0, srcW / 2, srcH, 0, 0, halfDst, c.height, win.cornerRadius, win.feather); // L
-      drawEyeBlend(ctx, src, srcW / 2, srcH, halfDst, c.height, stereo, win.cornerRadius, win.feather); // L+R
+      drawEye(ctx, src, 0, 0, srcW / 2, srcH, 0, 0, halfDst, c.height, radius, feather); // L
+      drawEyeBlend(ctx, src, srcW / 2, srcH, halfDst, c.height, stereo, radius, feather); // L+R
       return;
     }
     // A single stretched draw maps SBS source → SBS buffer (left→left, right→right); the
     // per-eye path is only needed to bake decoration (rounded corners / edge feather), which
     // MUST be applied to each eye separately — see drawEye/featherEye.
-    if (win.cornerRadius > 0 || win.feather > 0) {
-      drawEye(ctx, src, 0, 0, srcW / 2, srcH, 0, 0, halfDst, c.height, win.cornerRadius, win.feather); // L
-      drawEye(ctx, src, srcW / 2, 0, srcW / 2, srcH, halfDst, 0, halfDst, c.height, win.cornerRadius, win.feather); // R
+    if (radius > 0 || feather > 0) {
+      drawEye(ctx, src, 0, 0, srcW / 2, srcH, 0, 0, halfDst, c.height, radius, feather); // L
+      drawEye(ctx, src, srcW / 2, 0, srcW / 2, srcH, halfDst, 0, halfDst, c.height, radius, feather); // R
     } else {
       ctx.drawImage(src, 0, 0, srcW, srcH, 0, 0, c.width, c.height);
     }
@@ -2656,7 +2766,10 @@ class Inline3D {
             win.onFrame(views, win.layer, f);
             // A stereo frame the page drew without throwing. A short view list is the load
             // fallback (a mono frame), which is not what a poster is waiting for.
-            if (views.length >= 2) win.fwStereo = true;
+            if (views.length >= 2) {
+              win.fwStereo = true;
+              if (!win.warnedBufMismatch) this._checkSceneBuffer(win);
+            }
           } catch (err) {
             if (!win.frameThrewWarned) {
               win.frameThrewWarned = true;

package/model.d.ts

@@ -34,7 +34,11 @@ export interface ModelOptions {
    * so a long subject still fits once the turntable turns it (default true).
    */
   fitSweep?: boolean;
-  /** Per-eye buffer scale; 0.5–0.7 is usually free (default 1). */
+  /**
+   * Per-eye buffer scale; 0.5–0.7 is usually free (default 1). Clamped to the device's GL limits: the whole store (2 × eye wide in 3D) is kept within
+   * min(MAX_TEXTURE_SIZE, MAX_RENDERBUFFER_SIZE, MAX_VIEWPORT_DIMS), both axes shrunk by one factor,
+   * with a one-time console warning. The handle's `renderScale` reports the value in force.
+   */
   renderScale?: number;
   feather?: number;
   /**
@@ -176,6 +180,11 @@ export interface ModelHandle {
   /** The last pose the page set (a copy), or null. */
   getCameraPose(): SplatCameraPose | null;
 
+  /** The per-eye buffer scale in force: the `renderScale` option times the device-limit clamp. */
+  readonly renderScale: number;
+  /** The `renderScale` option as given. */
+  readonly renderScaleRequested: number;
+
   remove(): void;
   exclude(el: Element): void;
   unexclude(el: Element): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@displayxr/inline3d",
-  "version": "1.26.0",
+  "version": "1.28.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",
@@ -36,6 +36,10 @@
       "types": "./player.d.ts",
       "import": "./js/inline3d-player.js"
     },
+    "./call": {
+      "types": "./call.d.ts",
+      "import": "./js/inline3d-call.js"
+    },
     "./undock": {
       "types": "./index.d.ts",
       "import": "./js/inline3d-undock.js"
@@ -46,6 +50,7 @@
     "js/inline3d.js",
     "js/inline3d-undock.js",
     "js/inline3d-mode-switch.js",
+    "js/inline3d-buffer-limit.js",
     "js/inline3d-three.js",
     "js/inline3d-viewer.js",
     "js/inline3d-splat.js",
@@ -66,12 +71,15 @@
     "js/inline3d-pc-look.js",
     "js/inline3d-playcanvas-engine.js",
     "js/inline3d-player.js",
+    "js/inline3d-call.js",
+    "js/call/",
     "index.d.ts",
     "three.d.ts",
     "viewer.d.ts",
     "splat.d.ts",
     "model.d.ts",
     "player.d.ts",
+    "call.d.ts",
     "CHANGELOG.md",
     "README.md",
     "LICENSE",

package/player.d.ts

@@ -267,7 +267,8 @@ export type PlayerAccent = 'azure' | 'violet' | 'magenta' | 'sunset' | 'amber' |
 
 /**
  * Pick the first source this browser can play from candidates listed best first; each is a URL, or
- * `{ src, type }` with a FULL `canPlayType` string (`'video/webm; codecs="vp9, opus"'`). The
- * DisplayXR Browser has no H.264/AAC, and a codec-less `'video/mp4'` still answers 'maybe'.
+ * `{ src, type }` with a FULL `canPlayType` string (`'video/webm; codecs="vp9, opus"'`). Only
+ * DisplayXR Browser 1.0.6+ plays H.264/AAC (via the OS decoders), and a codec-less `'video/mp4'`
+ * still answers 'maybe' — so list a VP9 WebM first when you have one.
  */
 export function pickSource(candidates: PlayerSource, canPlayType?: (type: string) => string): string | Blob | undefined;

package/splat.d.ts

@@ -185,7 +185,11 @@ export interface ResolvedRig {
  * viewer's. docs/proposals/layer-display-rig.md.
  */
 export interface SplatLayerRigOptions {
-  /** Nominal viewer distance in metres (default 0.6, the browser's own nominal). */
+  /**
+   * Nominal viewer distance n in metres. Default: the browser's
+   * `XRDisplayInfo.nominalViewerPosition.z` where it reports one, else 0.6. Passing it pins n
+   * (see {@link SplatLayerRigState.viewerDistanceSource}).
+   */
   viewerDistance?: number | null;
   /** An explicit gain k instead (1 = exactly the photo rig; larger = rounder). */
   gain?: number | null;
@@ -216,7 +220,14 @@ export interface SplatLayerRigState {
   rounded: boolean;
   /** Why not engaged (or what is wrong with some layers while engaged); null when all is well. */
   reason: string | null;
+  /** The n in use (metres). */
   viewerDistance: number;
+  /**
+   * Where `viewerDistance` came from: the page's option, the browser's reported nominal viewer
+   * (`XRDisplayInfo.nominalViewerPosition.z`, asked once per tile, asynchronously — early frames
+   * may read 'default' before it lands), or the 0.6 m fallback.
+   */
+  viewerDistanceSource: 'page' | 'browser' | 'default';
   /** The gain the last frame used (null off a camera rig). */
   gain: number | null;
   /** The plane that lands on the glass, as a distance from the photo's camera (world units). */
@@ -368,7 +379,11 @@ export interface SplatOptions {
    * so a long subject still fits once the turntable turns it (default true).
    */
   fitSweep?: boolean;
-  /** Per-eye buffer scale; 0.5–0.7 is usually free (default 1). */
+  /**
+   * Per-eye buffer scale; 0.5–0.7 is usually free (default 1). Clamped to the device's GL limits: the whole store (2 × eye wide in 3D) is kept within
+   * min(MAX_TEXTURE_SIZE, MAX_RENDERBUFFER_SIZE, MAX_VIEWPORT_DIMS), both axes shrunk by one factor,
+   * with a one-time console warning. The handle's `renderScale` reports the value in force.
+   */
   renderScale?: number;
   feather?: number;
   /**
@@ -997,11 +1012,18 @@ export interface SplatHandle {
   /**
    * `engine: 'playcanvas'` only. Change the per-eye buffer scale live (the `renderScale` option),
    * in (0, 4]; the backing store is resized on the next animation frame. Throws a RangeError
-   * otherwise.
+   * otherwise. The request is kept as given (`renderScaleRequested`); the store is still clamped
+   * to the device's GL limits, and `renderScale` reports what is in force.
    */
   setRenderScale(scale: number): SplatHandle;
-  /** `engine: 'playcanvas'` only. The current per-eye buffer scale. */
+  /**
+   * The per-eye buffer scale IN FORCE: the request times the device-limit clamp. E.g. 0.8 for a
+   * request of 1 on a device whose MAX_TEXTURE_SIZE (4096) cannot hold a 5120-wide SBS store.
+   * Both engines.
+   */
   readonly renderScale: number;
+  /** The per-eye buffer scale as requested (the option, or the last `setRenderScale`). Both engines. */
+  readonly renderScaleRequested: number;
   /**
    * `engine: 'playcanvas'` only. The 2D tier's EYE offset — a head-parallax analogue for a flat
    * screen with no tracked eyes (e.g. a phone's tilt). `{x, y}` is normalised in the mono camera's

package/viewer.d.ts

@@ -29,7 +29,11 @@ export interface SceneViewerOptions {
   orbit?: boolean;
   /** Degrees/second of turntable once idle. Ignored under prefers-reduced-motion. */
   idleSpin?: number;
-  /** Per-eye buffer scale; 0.5–0.7 is usually free after the interlace (default 1). */
+  /**
+   * Per-eye buffer scale; 0.5–0.7 is usually free after the interlace (default 1). Clamped to the device's GL limits: the whole store (2 × eye wide in 3D) is kept within
+   * min(MAX_TEXTURE_SIZE, MAX_RENDERBUFFER_SIZE, MAX_VIEWPORT_DIMS), both axes shrunk by one factor,
+   * with a one-time console warning. `effectiveRenderScale` reports the value in force.
+   */
   renderScale?: number;
   /** Edge fade in buffer px (needs EdgeFeather from ./three). */
   feather?: number;
@@ -96,6 +100,13 @@ export declare class SceneViewer {
   readonly monoCamera: object;
   /** True while the side-by-side backing store is in use. */
   readonly is3D: boolean;
+  /** The requested per-eye buffer scale (the `renderScale` option). */
+  renderScale: number;
+  /**
+   * The per-eye buffer scale in force: `renderScale` times the device-limit clamp the last resize
+   * applied (1 where the store fits the device's MAX_TEXTURE_SIZE & co.).
+   */
+  readonly effectiveRenderScale: number;
 
   /** Centre the subject on the zero-disparity plane and scale it to the tile. */
   fitTo(