@displayxr/inline3d 1.26.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-layer-rig.js

@@ -16,8 +16,10 @@
 //       view_round_i = view_photo_i · M_i,     proj_round_i = proj_photo_i
 //
 // k = D / (m·n): D the declared convergence (world units), m the declared metersToVirtual, n the
-// nominal viewer distance in metres — the one quantity the browser does not expose (see the
-// design note §5). Everything here is PLAIN ARITHMETIC on arrays, unit-testable without a GPU.
+// nominal viewer distance in metres. n comes from the page's `viewerDistance` if it passed one,
+// else from the browser (XRDisplayInfo.nominalViewerPosition.z, DisplayXR Browser 0221+), else
+// 0.6 m (design note §5, (c)1). Everything here is PLAIN ARITHMETIC on arrays, unit-testable
+// without a GPU.
 
 import { invertAffine } from './inline3d-splat-rig-map.js';
 
@@ -27,6 +29,32 @@ export const LAYER_RIGS = Object.freeze(['display', 'camera']);
 /** Nominal viewer distance (m) when neither the page nor the platform says: the browser's own. */
 export const DEFAULT_VIEWER_DISTANCE_M = 0.6;
 
+/** How many times a tile asks the layer for its display info before giving up (rejections only). */
+const MAX_DISPLAY_INFO_ASKS = 3;
+
+/**
+ * The runtime's nominal viewer DISTANCE n (m) from an XRDisplayInfo, or null when the browser does
+ * not report one. It is the position's **z** — the distance out of the glass along the display
+ * normal — not its length: the runtime's camera rig reads only `nominal_viewer->z`
+ * (displayxr-common dxr_view_math.c, `eye_local.z = m2v·(eye.z − nominal_z)`), and z is what
+ * D/n undoes. A browser without the field, a null info, or a z that is not finite and > 0 → null.
+ */
+export function nominalViewerDistanceFromInfo(info) {
+  const z = info && info.nominalViewerPosition ? info.nominalViewerPosition.z : undefined;
+  return typeof z === 'number' && Number.isFinite(z) && z > 0 ? z : null;
+}
+
+/**
+ * The n the layer rig uses, and where it came from: the page's `viewerDistance` wins ('page'),
+ * then the browser's nominal viewer ('browser'), then DEFAULT_VIEWER_DISTANCE_M ('default').
+ * @returns {{ value: number, source: 'page'|'browser'|'default' }}
+ */
+export function resolveViewerDistance(pageViewerDistance, browserViewerDistance) {
+  if (pageViewerDistance !== null && pageViewerDistance !== undefined) return { value: pageViewerDistance, source: 'page' };
+  if (browserViewerDistance !== null && browserViewerDistance !== undefined) return { value: browserViewerDistance, source: 'browser' };
+  return { value: DEFAULT_VIEWER_DISTANCE_M, source: 'default' };
+}
+
 /** A round eye may not reach the window plane: h(E') is floored at this fraction of D. */
 const MIN_EYE_HEIGHT_FRAC = 1e-3;
 
@@ -45,7 +73,8 @@ export const LAYER_RIG_OPTION_KEYS = Object.freeze(['viewerDistance', 'gain', 'p
 /**
  * setLayerRig / setLayerRigOptions options, validated (throws at the call). Only the keys given
  * are returned: they MERGE into the tile's options. `null` clears a key (back to its default).
- *   viewerDistance  m, > 0     the nominal viewer distance n (default 0.6)
+ *   viewerDistance  m, > 0     the nominal viewer distance n (default: the browser's
+ *                              XRDisplayInfo.nominalViewerPosition.z, else 0.6)
  *   gain            > 0        an explicit rounding gain k instead of D/(m·n)
  *   planeOffset     m, finite  moves the stage TOWARD the viewer by this much on the panel (display
  *                              space): the plane that lands on the glass moves back by offset·D/n
@@ -330,6 +359,11 @@ export class LayerRigCameras {
     this.layers = new Map();
     /** The tile's options: merged across setLayerRig / setLayerRigOptions calls. */
     this.opts = { viewerDistance: null, gain: null, planeOffset: null, planeDistance: null };
+    /** n as the browser reports it (XRDisplayInfo.nominalViewerPosition.z), once known; else null. */
+    this.browserViewerDistance = null;
+    this._infoAsks = 0;
+    this._infoPending = false;
+    this._infoSettled = false;
     this.disabled = false; // the kill switch (diag 'nolayerrig')
     this.cams = { display: [], post: [] };
     this.moved = { display: [], post: [] };
@@ -369,6 +403,41 @@ export class LayerRigCameras {
     for (const [k, v] of Object.entries(o)) this.opts[k] = v;
   }
 
+  /** The n this tile uses right now, and its source ('page' | 'browser' | 'default'). */
+  viewerDistance() {
+    return resolveViewerDistance(this.opts.viewerDistance, this.browserViewerDistance);
+  }
+
+  /**
+   * Called with the frame's XRDisplayLayer: ask it ONCE for the display info and keep the
+   * browser's nominal viewer distance. Asynchronous — frames drawn before it resolves use the
+   * page's value or 0.6 m, and the state's `viewerDistanceSource` says which. A browser without
+   * getDisplayInfo (or without the field) leaves the default in place; a REJECTED ask (e.g. no live
+   * layer yet) is retried on later frames, up to MAX_DISPLAY_INFO_ASKS times.
+   */
+  noteLayer(layer) {
+    if (this._infoSettled || this._infoPending || this._infoAsks >= MAX_DISPLAY_INFO_ASKS) return;
+    if (!layer || typeof layer.getDisplayInfo !== 'function') return;
+    this._infoAsks++;
+    this._infoPending = true;
+    let p;
+    try {
+      p = Promise.resolve(layer.getDisplayInfo());
+    } catch (e) {
+      p = Promise.reject(e);
+    }
+    return p.then(
+      (info) => {
+        this._infoPending = false;
+        this._infoSettled = true;
+        this.browserViewerDistance = nominalViewerDistanceFromInfo(info);
+      },
+      () => {
+        this._infoPending = false;
+      }
+    );
+  }
+
   /** The eye camera entities of the current view path. */
   _eyeCams() {
     const v = this.viewer;
@@ -494,8 +563,9 @@ export class LayerRigCameras {
     L.residual = residual;
     const hasRun = this.sync();
     const frame = cameraRigFrame(rig);
-    const k = frame ? layerRigGain(frame, this.opts) : null;
-    const plane = frame ? layerRigPlane(frame, this.opts) : null;
+    const opts = { ...this.opts, viewerDistance: this.viewerDistance().value };
+    const k = frame ? layerRigGain(frame, opts) : null;
+    const plane = frame ? layerRigPlane(frame, opts) : null;
     L.gain = k;
     L.planeM = plane;
     L.photoConvergenceM = frame ? frame.D : null;
@@ -606,6 +676,7 @@ export class LayerRigCameras {
   /** The public state (handle.layerRigState). */
   state() {
     const L = this.last;
+    const n = this.viewerDistance();
     return {
       display: [...this.requests.keys()],
       disabled: this.disabled,
@@ -613,7 +684,8 @@ export class LayerRigCameras {
       engaged: !!L.engaged,
       rounded: !!L.engaged,
       reason: this.disabled ? 'kill switch (?dxrdiag=nolayerrig)' : L.reason,
-      viewerDistance: this.opts.viewerDistance ?? DEFAULT_VIEWER_DISTANCE_M,
+      viewerDistance: n.value,
+      viewerDistanceSource: n.source,
       gain: L.gain,
       planeM: L.planeM,
       photoConvergenceM: L.photoConvergenceM ?? null,
@@ -634,7 +706,7 @@ export function layerRigLine(st) {
   const n = (x, d = 3) => (x === null || x === undefined ? '-' : Number(x).toFixed(d));
   return (
     `path=${st.path ?? '-'} engaged=${st.engaged} layers=[${st.display.join(', ')}] ` +
-    `viewerDistance=${n(st.viewerDistance, 2)}m gain=${n(st.gain)} planeM=${n(st.planeM)} ` +
+    `viewerDistance=${n(st.viewerDistance, 2)}m(${st.viewerDistanceSource ?? '-'}) gain=${n(st.gain)} planeM=${n(st.planeM)} ` +
     `photoConvergenceM=${n(st.photoConvergenceM)} planeOffset=${n(st.planeOffset)}m ` +
     `located=${st.located === null || st.located === undefined ? '-' : st.located} reason=${st.reason ?? '-'}`
   );

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;
@@ -1184,7 +1199,11 @@ export class PlayCanvasSplatViewer {
     if (this._mode !== '3d') this.stopMono();
     // 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) this._rigSnap = snapshotRig(this.layerRigSource?.(), this._rigSnap);
+    if (this.layerRigs?.active) {
+      this._rigSnap = snapshotRig(this.layerRigSource?.(), this._rigSnap);
+      // n for the layer rig: the browser's nominal viewer, asked once (async; no-op after).
+      this.layerRigs.noteLayer(layer);
+    }
     // Same moment, for the rig map: the rig these views were most likely located for (a tie-break).
     this._rigAtPull = this.rigTrack ? this.rigTrack.latest : null;
     // BEFORE the tick: a pose the page sets in here is the one this very frame renders.
@@ -1316,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
@@ -1939,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);
   }
 
@@ -1952,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.
@@ -2029,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];
@@ -2116,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;
@@ -3047,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] }),
@@ -3143,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) {
@@ -3186,7 +3263,7 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     layerRigState() {
       const lr = viewer.layerRigs;
       if (lr) return lr.state();
-      return { display: [], disabled: false, path: null, engaged: false, rounded: false, reason: 'no layer on the display rig', viewerDistance: DEFAULT_VIEWER_DISTANCE_M, gain: null, planeM: null, photoConvergenceM: null, planeOffset: 0, located: null };
+      return { display: [], disabled: false, path: null, engaged: false, rounded: false, reason: 'no layer on the display rig', viewerDistance: DEFAULT_VIEWER_DISTANCE_M, viewerDistanceSource: 'default', gain: null, planeM: null, photoConvergenceM: null, planeOffset: 0, located: null };
     },
     /**
      * An unlit material showing the left half of `texture` to left-eye views and the right half to

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();