@displayxr/inline3d 1.27.0 → 1.29.0

package/splat.d.ts

@@ -271,6 +271,25 @@ export interface SplatVideoOptions {
   muted?: boolean;
   /** Default true for a URL (the SDK's own element), false for an element you pass. */
   autoplay?: boolean;
+  /**
+   * `'cut'` (default) or `'crossfade'`: a GPU dissolve from the video already on the plane (its
+   * last frame, frozen) to this one. From the splat, and on `setVideo(null)`, it is always a cut.
+   * The same vocabulary as `./player`'s `setSource`; `./splat`'s gaussian transitions throw here.
+   */
+  transition?: 'cut' | 'crossfade';
+  /** Crossfade length. Default 600 (the player's). 0 = a cut. */
+  durationMs?: number;
+  /** A named easing ({@link SplatEasing}) or `(x) => y` on [0, 1]. Default `'easeInOutSine'`. */
+  easing?: SplatEasing | ((x: number) => number);
+  /** Only `'frozen'`: the outgoing video dissolves from its last frame. */
+  outgoing?: 'frozen';
+  /**
+   * A letterbox slot: the picture is fitted into a centred band of this aspect inside the tile
+   * (`2.39` or `'2.39:1'` for a scope band in a 16:9 tile), the rest of the element left clear —
+   * `./player`'s `band`, on the plane. `fit: 'cover'` fills the band and crops the eye image about
+   * its centre.
+   */
+  band?: number | string | null;
 }
 
 /** What `handle.setVideo(src)` resolves to. */
@@ -279,6 +298,18 @@ export interface SplatVideo {
   readonly video: HTMLVideoElement;
   readonly format: 'sbs' | 'tb' | 'mono';
   readonly fit: 'contain' | 'cover';
+  /** The band's aspect, or null. */
+  readonly band: number | null;
+  /**
+   * Where the picture is on screen, in CSS px from the canvas's top-left, clipped to the canvas;
+   * the letterbox bars are the canvas minus this. Null before the first drawn frame and once
+   * another `setVideo` replaced this one. Place controls against the picture with it.
+   */
+  readonly rect: { readonly x: number; readonly y: number; readonly width: number; readonly height: number } | null;
+  /** `cb(rect)` whenever the rect changes (a resize, a new size, a band): a microtask right after the draw, same frame, before paint. Returns an unsubscribe. */
+  onRectChange(cb: (rect: { x: number; y: number; width: number; height: number }) => void): () => void;
+  /** What the swap did: `'crossfade'` only when it replaced a video on screen and asked to. Resolved at the swap, before the fade ends. */
+  readonly transition: 'cut' | 'crossfade';
   /** `handle.setVideo(null)`, or a no-op if another setVideo has replaced this one. */
   remove(): Promise<null>;
   /** Frames drawn with the plane up, and texture uploads (new video frames). */
@@ -379,7 +410,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;
   /**
@@ -1008,11 +1043,25 @@ 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 `<video>` `setVideo`'s plane is showing now, or null (none, or
+   * one still waiting for its first frame). Read-only; no event reports it changing.
+   */
+  readonly videoElement?: HTMLVideoElement | null;
+  /** `engine: 'playcanvas'` only. The tile's canvas (page chrome sits beside it). */
+  readonly canvas?: HTMLCanvasElement;
   /**
    * `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(