@displayxr/inline3d 1.27.0 → 1.28.0

package/js/inline3d-model-playcanvas.js

@@ -455,6 +455,7 @@ export function attachPlayCanvasModel(out, wall, canvas, src, opts, pending = []
     orbit,
     idleSpin,
     renderScale,
+    logTag: '[inline3d/model]',
     flipY: false, // glTF is already Y-up
     orbitMaxDeg: opts.orbitMaxDeg,
     orbitEase: opts.orbitEase,
@@ -512,6 +513,11 @@ export function attachPlayCanvasModel(out, wall, canvas, src, opts, pending = []
     unexclude: (el) => handle?.unexclude(el),
   });
 
+  // The per-eye buffer scale in force (the request times the device-limit clamp,
+  // ./inline3d-buffer-limit.js) and the request as given. Accessors, so they stay live.
+  Object.defineProperty(out, 'renderScale', { get: () => viewer.effectiveRenderScale, enumerable: true, configurable: true });
+  Object.defineProperty(out, 'renderScaleRequested', { get: () => viewer.renderScale, enumerable: true, configurable: true });
+
   if (wall && wall.supported) {
     handle = wall.addScene(canvas, viewer.onFrame, {
       ...(pageMode

package/js/inline3d-model.js

@@ -379,6 +379,7 @@ export function addModel(wall, canvas, src, opts = {}) {
     idleSpin,
     renderScale,
     feather,
+    logTag: '[inline3d/model]',
   }).useEyeCamera(EyeCamera, EdgeFeather);
 
   if (envMap) viewer.scene.environment = envMap;
@@ -404,6 +405,11 @@ export function addModel(wall, canvas, src, opts = {}) {
     unexclude: (el) => handle?.unexclude(el),
   };
 
+  // The per-eye buffer scale in force (the request times the device-limit clamp,
+  // ./inline3d-buffer-limit.js) and the request as given. Accessors, so they stay live.
+  Object.defineProperty(out, 'renderScale', { get: () => viewer.effectiveRenderScale, enumerable: true, configurable: true });
+  Object.defineProperty(out, 'renderScaleRequested', { get: () => viewer.renderScale, enumerable: true, configurable: true });
+
   // 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;

package/js/inline3d-player.js

@@ -346,7 +346,8 @@ function drawFittedEye(ctx, src, srcW, srcH, layout, eye, dx, dy, dw, dh, fit, b
  * Pick the first source this browser can play, from candidates listed BEST FIRST. Each candidate
  * is a URL string, or `{ src, type }` where `type` is a full `canPlayType` string — e.g.
  * `'video/webm; codecs="vp9, opus"'`. Codec-less types answer 'maybe' for anything in the
- * container, which is why the full string matters: the DisplayXR Browser has no H.264 / AAC, and
+ * container, which is why the full string matters: only DisplayXR Browser 1.0.6+ plays H.264 /
+ * AAC (through the OS decoders, and not on a machine without hardware H.264 decode), and
  * `'video/mp4'` alone still says 'maybe'. A 'probably' wins over an earlier 'maybe'. A candidate
  * without a type is taken as-is if nothing typed was 'probably'. Warns and returns the first when
  * nothing is playable, so the `error` event (and the poster) still happens the usual way.
@@ -382,7 +383,7 @@ export function pickSource(candidates, canPlayType) {
   if (maybe) return maybe.src;
   console.warn(
     '[inline3d/player] none of the candidate sources is playable here — trying the first. The ' +
-      'DisplayXR Browser plays VP9/AV1 + Opus in WebM, not H.264/AAC.',
+      'VP9/AV1 + Opus in WebM plays everywhere; H.264/AAC MP4 needs DisplayXR Browser 1.0.6+.',
     list.map((c) => c.type || '(untyped)')
   );
   return list[0].src;

package/js/inline3d-splat-playcanvas.js

@@ -71,6 +71,14 @@ import { VideoPlane, validateSetVideo, PAGE_VIDEO_ERROR, eyeSplit, EYE_SPLIT_UNI
 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 {
+  glBufferLimits,
+  probeBufferLimits,
+  clampEyeBuffer,
+  clampWarning,
+  bufferScale,
+  mismatchWarning,
+} from './inline3d-buffer-limit.js';
 import {
   clamp,
   finite,
@@ -890,6 +898,13 @@ export class PlayCanvasSplatViewer {
     this.depthLimit = depthLimit;
     this.fitSweep = fitSweep;
     this.renderScale = renderScale;
+    // The device-limit clamp on the backing store (./inline3d-buffer-limit.js), as SceneViewer:
+    // the factor the last _resize applied on top of renderScale; warned once per viewer.
+    this._bufClamp = 1;
+    this._warnedBufClamp = false;
+    this._warnedBufMismatch = false;
+    /** Prefix for this viewer's warnings; ./model sets its own. */
+    this.logTag = opts.logTag || '[inline3d/splat]';
     this.pitchLimit = pitchLimit;
     this.idleSpin = this.pageCamera ? 0 : idleSpin;
     this.flipY = opts.flipY !== false;
@@ -1320,6 +1335,9 @@ export class PlayCanvasSplatViewer {
     // The SDK's frame drives the engine: no second rAF. `tick` is the engine's own loop body.
     app.requestAnimationFrame = () => {};
     this.app = app;
+    // The store may have been sized before the engine existed (from the probed limits, or none):
+    // re-check it against THIS context's. A no-op when nothing moves.
+    this._scheduleResize();
 
     // Footprint fix (§ patchGsplatFootprint) and the perf quad-extent cap, both as chunk
     // overrides. The gsplat chunks are registered by GSplatComponentSystem during init, so
@@ -1943,8 +1961,9 @@ export class PlayCanvasSplatViewer {
     const v = this._monoView();
     e.proj = v.proj;
     e.pose = v.pose;
-    e.width = c.width;
-    e.height = c.height;
+    const b = this._bufScale();
+    e.width = b.w || c.width;
+    e.height = b.h || c.height;
     this._drawEntries(this._monoEntry, null);
   }
 
@@ -1956,9 +1975,7 @@ export class PlayCanvasSplatViewer {
     const app = this.app;
     if (!app || !this.pc) return false;
     const pc = this.pc;
-    const el = this.canvas;
-    const sx = cache && cache.bufW > 0 && el.width ? el.width / cache.bufW : 1;
-    const sy = cache && cache.bufH > 0 && el.height ? el.height / cache.bufH : 1;
+    const { b, sx, sy } = this._entryScale(cache);
     if (this.pageCamera) {
       // The page's near/far join the caller's nearClip/farClip as a floor and a cap: only the
       // depth mapping moves, the runtime's frustum (fov, skew, principal point) stays untouched.
@@ -2033,8 +2050,8 @@ export class PlayCanvasSplatViewer {
         this._budgetViews = entries.length;
         this._applyBudget();
       }
-      const W = el.width || 1;
-      const H = el.height || 1;
+      const W = b.w || 1;
+      const H = b.h || 1;
       for (let i = 0; i < entries.length; i++) {
         const e = entries[i];
         const cam = cams[i];
@@ -2120,18 +2137,68 @@ export class PlayCanvasSplatViewer {
     const box = this.canvas.getBoundingClientRect();
     if (box.width < 1 || box.height < 1) return;
     const dpr = Math.min((typeof window !== 'undefined' && window.devicePixelRatio) || 1, 2) * this.renderScale;
-    const w = Math.max(1, Math.round(box.width * dpr));
-    const h = Math.max(1, Math.round(box.height * dpr));
-    const bufW = this._mode === 'mono' ? w : w * 2;
+    // Clamp to the device's GL limits BEFORE sizing (./inline3d-buffer-limit.js). Measured on an
+    // Adreno 740 tablet: MAX_TEXTURE_SIZE 4096, a 5120-wide request silently became a 4096-wide
+    // drawing buffer, getViewport() still split 5120, and the eye boundary sat at 62.5%.
+    const c = clampEyeBuffer(
+      Math.max(1, Math.round(box.width * dpr)),
+      Math.max(1, Math.round(box.height * dpr)),
+      glBufferLimits(this.app?.graphicsDevice?.gl) || probeBufferLimits(),
+      { cols: this._mode === 'mono' ? 1 : 2 },
+    );
+    this._noteClamp(c);
+    const bufW = c.bufW;
+    const h = c.bufH;
     this._updateMonoProjection();
     const el = this.canvas;
-    if (el.width === bufW && el.height === h) return;
+    if (el.width === bufW && el.height === h) {
+      this._bufScale(); // unchanged; still name a browser-side clamp (once)
+      return;
+    }
     el.width = bufW;
     el.height = h;
+    this._bufScale(); // warns once if the browser clamped anyway
     if (this._mode === 'mono') this._drawMono();
     else this._replayLastGood();
   }
 
+  /** The renderScale in force: the request times the device-limit clamp (SceneViewer's twin). */
+  get effectiveRenderScale() {
+    return this.renderScale * this._bufClamp;
+  }
+
+  _noteClamp(c) {
+    this._bufClamp = c.scale;
+    if (c.clamped && !this._warnedBufClamp) {
+      this._warnedBufClamp = true;
+      console.warn(clampWarning(this.logTag, c, this.renderScale));
+    }
+  }
+
+  /**
+   * How a frame's entries map into the buffer. Entries are in canvas-attribute px (getViewport()
+   * splits canvas.width), cached with that size; they are drawn into the REAL drawing buffer.
+   * Identity unless a resize happened since the cache or the browser clamped the buffer behind
+   * the SDK (the device-limit clamp in _resize normally prevents that).
+   */
+  _entryScale(cache) {
+    const b = this._bufScale();
+    const sx = cache && cache.bufW > 0 && b.w ? b.w / cache.bufW : 1;
+    const sy = cache && cache.bufH > 0 && b.h ? b.h / cache.bufH : 1;
+    return { b, sx, sy };
+  }
+
+  /** The real drawing buffer vs canvas.width/height; warns once per viewer on a mismatch. */
+  _bufScale() {
+    const el = this.canvas;
+    const b = bufferScale(el, this.app?.graphicsDevice?.gl || null);
+    if (b.mismatch && !this._warnedBufMismatch) {
+      this._warnedBufMismatch = true;
+      console.warn(mismatchWarning(this.logTag, el, b));
+    }
+    return b;
+  }
+
   _tick() {
     const t = now();
     const dt = this._lastTick ? Math.min((t - this._lastTick) / 1000, MAX_DT_S) : 0;
@@ -3051,9 +3118,13 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
   let cancelPendingVideo = null;
   let warnedAutoplayMuted = false;
 
-  // The current per-eye buffer scale (the `renderScale` option, or the last setRenderScale). A
-  // real accessor: Object.assign below would copy a getter's value once.
-  Object.defineProperty(out, 'renderScale', { get: () => viewer.renderScale, enumerable: true, configurable: true });
+  // The per-eye buffer scale IN FORCE: the request (the `renderScale` option, or the last
+  // setRenderScale) times the device-limit clamp — e.g. 0.8 for a request of 1 on a device whose
+  // MAX_TEXTURE_SIZE cannot hold the full SBS store (./inline3d-buffer-limit.js).
+  // `renderScaleRequested` is the request as given. Real accessors: Object.assign below would
+  // copy a getter's value once.
+  Object.defineProperty(out, 'renderScale', { get: () => viewer.effectiveRenderScale, enumerable: true, configurable: true });
+  Object.defineProperty(out, 'renderScaleRequested', { get: () => viewer.renderScale, enumerable: true, configurable: true });
   // The current eye offset (after the unit-disc clamp), a fresh object per read.
   Object.defineProperty(out, 'viewOffset', {
     get: () => ({ x: viewer._viewOffset[0], y: viewer._viewOffset[1] }),
@@ -3147,7 +3218,9 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     /**
      * Change the per-eye buffer scale live (the `renderScale` option): e.g. full resolution on a
      * screen that hides the splat and draws only stage quads, 0.6 elsewhere. The backing store is
-     * resized on the next animation frame (never mid-frame). Returns the handle.
+     * resized on the next animation frame (never mid-frame). 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. Returns the handle.
      */
     setRenderScale(s) {
       if (typeof s !== 'number' || !Number.isFinite(s) || s <= 0 || s > 4) {

package/js/inline3d-splat.js

@@ -245,6 +245,7 @@ export function addSplat(wall, canvas, src, opts = {}) {
     idleSpin,
     renderScale,
     feather,
+    logTag: '[inline3d/splat]',
   }).useEyeCamera(EyeCamera, EdgeFeather);
 
   // Spark renders through the ordinary three.js pipeline, so splats and meshes co-exist and
@@ -411,6 +412,10 @@ export function addSplat(wall, canvas, src, opts = {}) {
     },
     effects: () => [],
   };
+  // The per-eye buffer scale in force (the request times the device-limit clamp,
+  // ./inline3d-buffer-limit.js) and the request as given. Accessors, so they stay live.
+  Object.defineProperty(out, 'renderScale', { get: () => viewer.effectiveRenderScale, enumerable: true, configurable: true });
+  Object.defineProperty(out, 'renderScaleRequested', { get: () => viewer.renderScale, enumerable: true, configurable: true });
 
   // `src` may be a URL or the bytes themselves.
   //

package/js/inline3d-viewer.js

@@ -64,6 +64,14 @@ import {
   MONO_NEAR,
   MONO_FAR,
 } from './inline3d-splat-shared.js';
+import {
+  glBufferLimits,
+  clampEyeBuffer,
+  clampWarning,
+  bufferScale,
+  scaleViewport,
+  mismatchWarning,
+} from './inline3d-buffer-limit.js';
 
 const clamp = (v, lo, hi) => (v < lo ? lo : v > hi ? hi : v);
 // NaN/Infinity into a transform silently blanks the tile — three propagates it into the
@@ -283,6 +291,14 @@ export class SceneViewer {
     this.depthLimit = depthLimit;
     this.fitSweep = fitSweep;
     this.renderScale = renderScale;
+    // The device-limit clamp on the backing store (./inline3d-buffer-limit.js): the factor _resize
+    // last had to apply on top of renderScale, 1 when the request fit. effectiveRenderScale reports
+    // the product. Warned once per viewer (one viewer per handle).
+    this._bufClamp = 1;
+    this._warnedBufClamp = false;
+    this._warnedBufMismatch = false;
+    /** Prefix for this viewer's warnings; ./splat and ./model set their own. */
+    this.logTag = opts.logTag || '[inline3d/viewer]';
     this.pitchLimit = pitchLimit;
     this.idleSpin = idleSpin;
 
@@ -711,10 +727,13 @@ export class SceneViewer {
 
     // Validated: this frame WILL draw over everything it clears.
     const r = this.renderer;
+    // getViewport() splits canvas.width; a drawing buffer the browser clamped behind our back
+    // (bufferScale().mismatch) gets the same split mapped onto its real size, never canvas.width/2.
+    const b = this._bufScale();
     r.clear();
     r.setScissorTest(true);
     for (let i = 0; i < views.length; i++) {
-      const vp = vps[i];
+      const vp = scaleViewport(vps[i], b.sx, b.sy);
       r.setViewport(vp.x, vp.y, vp.width, vp.height);
       r.setScissor(vp.x, vp.y, vp.width, vp.height);
       if (eye) {
@@ -753,7 +772,8 @@ export class SceneViewer {
       this._tick();
       const r = this.renderer;
       r.clear();
-      r.setViewport(0, 0, this.canvas.width, this.canvas.height);
+      const b = this._bufScale();
+      r.setViewport(0, 0, b.w, b.h);
       r.render(this.scene, this.monoCamera);
     };
     this._monoRaf = requestAnimationFrame(loop);
@@ -849,9 +869,11 @@ export class SceneViewer {
     const r = this.renderer;
     const eye = g.mono ? null : this._ensureEye();
     const el = this.renderer.domElement || this.canvas;
-    // A resize between the cache and the replay changes the buffer, not the split.
-    const sx = g.bufW > 0 && el.width ? el.width / g.bufW : 1;
-    const sy = g.bufH > 0 && el.height ? el.height / g.bufH : 1;
+    // A resize between the cache and the replay changes the buffer, not the split. The cache is in
+    // canvas-attribute px (getViewport's space); the target is the REAL drawing buffer.
+    const b = this._bufScale();
+    const sx = g.bufW > 0 && b.w ? b.w / g.bufW : 1;
+    const sy = g.bufH > 0 && b.h ? b.h / g.bufH : 1;
     const scaled = sx !== 1 || sy !== 1;
     r.clear();
     r.setScissorTest(true);
@@ -903,7 +925,8 @@ export class SceneViewer {
     if (this._mode === 'mono') {
       const r = this.renderer;
       r.clear();
-      r.setViewport(0, 0, this.canvas.width, this.canvas.height);
+      const b = this._bufScale();
+      r.setViewport(0, 0, b.w, b.h);
       r.render(this.scene, this.monoCamera);
       return;
     }
@@ -955,18 +978,71 @@ export class SceneViewer {
     const box = this.canvas.getBoundingClientRect();
     if (box.width < 1 || box.height < 1) return;
     const dpr = Math.min(window.devicePixelRatio || 1, 2) * this.renderScale;
-    const w = Math.max(1, Math.round(box.width * dpr));
-    const h = Math.max(1, Math.round(box.height * dpr));
-    const bufW = this._mode === 'mono' ? w : w * 2;
+    // Clamp to the device's GL limits BEFORE sizing (./inline3d-buffer-limit.js): a store past
+    // MAX_TEXTURE_SIZE is silently clamped by the browser while getViewport() keeps splitting
+    // canvas.width, which puts the eye boundary off-centre in the woven buffer.
+    const c = clampEyeBuffer(
+      Math.max(1, Math.round(box.width * dpr)),
+      Math.max(1, Math.round(box.height * dpr)),
+      glBufferLimits(this._gl()),
+      { cols: this._mode === 'mono' ? 1 : 2 },
+    );
+    this._noteClamp(c);
+    const bufW = c.bufW;
+    const h = c.bufH;
     // Cheap and always correct to refresh, whether or not the backing store moves.
     this.monoCamera.aspect = box.width / box.height;
     this.monoCamera.updateProjectionMatrix();
     const el = this.renderer.domElement || this.canvas;
-    if (el.width === bufW && el.height === h) return; // observer fired, geometry didn't move
+    if (el.width === bufW && el.height === h) {
+      this._bufScale(); // observer fired, geometry didn't move; still name a browser-side clamp
+      return;
+    }
     this.renderer.setSize(bufW, h, false);
+    this._bufScale(); // warns once if the browser clamped anyway
     this._repaintAfterResize();
   }
 
+  /**
+   * The renderScale actually in force: the request (`renderScale`) times the device-limit clamp
+   * the last resize applied. Equal to renderScale wherever the store fits.
+   */
+  get effectiveRenderScale() {
+    return this.renderScale * this._bufClamp;
+  }
+
+  _gl() {
+    try {
+      return this.renderer?.getContext?.() || null;
+    } catch {
+      return null;
+    }
+  }
+
+  /** Record a resize's clamp; warn once per viewer the first time the device limit bites. */
+  _noteClamp(c) {
+    this._bufClamp = c.scale;
+    if (c.clamped && !this._warnedBufClamp) {
+      this._warnedBufClamp = true;
+      console.warn(clampWarning(this.logTag, c, this.renderScale));
+    }
+  }
+
+  /**
+   * The drawing buffer's real size and its ratio to canvas.width/height (the space getViewport()
+   * reports in). Identity unless the browser clamped a store the limit query did not predict;
+   * warns once per viewer when it did.
+   */
+  _bufScale() {
+    const el = this.renderer.domElement || this.canvas;
+    const b = bufferScale(el, this._gl());
+    if (b.mismatch && !this._warnedBufMismatch) {
+      this._warnedBufMismatch = true;
+      console.warn(mismatchWarning(this.logTag, el, b));
+    }
+    return b;
+  }
+
   /** Damping + idle turntable. Called once per rendered frame, 3D or mono. */
   _tick() {
     const t = now();

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.27.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",