@displayxr/inline3d 1.7.1 → 1.9.0

package/splat.d.ts

@@ -34,6 +34,52 @@ export interface SplatPerfOptions {
   lodSplatCount?: number;
   /** Minimum on-screen splat size multiplier (needs `lod`); up to ~5 is often invisible. */
   lodRenderScale?: number;
+  /**
+   * `engine: 'playcanvas'` only — engine-native knobs, passed straight to `app.scene.gsplat`
+   * (and winning over the Spark-knob mapping).
+   *
+   * `splatBudget` is a splat count **per tile, all views included**: every view of a tile is
+   * drawn through one engine camera, so one budget covers both eyes of a 3D tile. It only acts
+   * on a Streamed SOG (a flat `.sog` draws every splat). Unset on a Streamed SOG = 600k
+   * (`STREAMED_SPLAT_BUDGET`); unset on anything else, or `perf: false` = the engine's 1M.
+   */
+  splatBudget?: number;
+  /**
+   * `engine: 'playcanvas'`, Streamed SOG only: how a chunk's LOD is chosen. Unset = the engine's
+   * `'distance'`.
+   */
+  lodMode?: 'distance' | 'error';
+  /** Streamed SOG only: camera travel (in the file's own units) before LOD re-evaluates. Engine default 1. */
+  lodUpdateDistance?: number;
+  /** Streamed SOG only: camera rotation in degrees before LOD re-evaluates. Engine default 0 (off). */
+  lodUpdateAngle?: number;
+  /** Streamed SOG only: how many coarser levels may stand in while a finer one streams. Engine default 0. */
+  lodUnderfillLimit?: number;
+  /** `engine: 'playcanvas'` only: cull splats whose quad DIAMETER is under this many px. */
+  minPixelSize?: number;
+  /** `engine: 'playcanvas'` only: the forward-pass alpha floor (engine default 1/255). */
+  alphaClipForward?: number;
+  /** `engine: 'playcanvas'` only: the engine's AA compensation, for AA-trained assets. */
+  antiAlias?: boolean;
+}
+
+/**
+ * The PlayCanvas backend's viewer (`engine: 'playcanvas'`): the SceneViewer pose surface without
+ * three. Not field-compatible with SceneViewer — see docs/playcanvas-adapter.md.
+ */
+export interface PlayCanvasSplatViewer {
+  idleSpin: number;
+  readonly is3D: boolean;
+  depthOffset: number;
+  /** The engine's `AppBase`, once booted. */
+  readonly app: unknown;
+  fitTo(center: number[], extent: number[]): void;
+  setPose(pose?: OrbitPose): void;
+  getPose(opts?: { target?: boolean }): Required<OrbitPose>;
+  resetPose(): void;
+  getSubjectBounds(): SubjectBounds & { front: number; back: number; scale: number };
+  setFocus(point: number[] | { x: number; y: number; z: number } | null, opts?: { snap?: boolean; recentre?: boolean }): PlayCanvasSplatViewer;
+  getFocus(opts?: { target?: boolean }): { x: number; y: number; z: number };
 }
 
 /** Camera intrinsics for ONE eye, in pixels, OpenCV convention. */
@@ -92,14 +138,26 @@ export interface ResolvedRig {
   focalEqMm: number;
   /** The live focus, in the splat's own space. */
   focus: number[];
+  /**
+   * Which step answered the focus. The order: `caller` › `caller-convergence` › `block` (a
+   * considered block focus) › `nearest-clump` (the nearest substantial disparity clump in the
+   * central half of the frame — needs the block's or the caller's lens) › `block-cloud-median` (a
+   * block focus a converter computed as a whole-cloud median) › `median-disparity` › `default`.
+   */
   focusSource:
     | 'caller'
     | 'caller-convergence'
     | 'block'
+    | 'nearest-clump'
+    | 'block-cloud-median'
     | 'median-disparity'
     | 'default'
     | 'picked'
     | 'set';
+  /** The block's own `focus.source` string (e.g. `'convergence'`, `'cloud-median'`), for diagnostics. */
+  blockFocusSource: string | null;
+  /** Fraction of the central crop's opacity-weighted mass the winning clump carried (`nearest-clump` only). */
+  clumpMassFrac: number | null;
   /** What Space returns to. */
   focusDefault: number[];
   focusDefaultSource: string;
@@ -112,6 +170,27 @@ export interface ResolvedRig {
 }
 
 export interface SplatOptions {
+  /**
+   * Which renderer. `'spark'` (the default) is three.js + Spark. `'playcanvas'` is the PlayCanvas
+   * engine (optional peer `playcanvas >=2.22.3 <3`, loaded by dynamic import only when asked):
+   * same handle, reads `.sog` / `.ply` / a Streamed-SOG `lod-meta.json`. Anything else throws.
+   *
+   * A Streamed SOG is loaded BY URL only — its `lod-meta.json`, or the directory holding it (a
+   * URL ending in `/`). It is a directory of chunk files named by relative path, so bytes of a
+   * `lod-meta.json` throw at call time with a message giving the URL form, and so does a streamed
+   * URL with `engine: 'spark'`.
+   */
+  engine?: 'spark' | 'playcanvas';
+  /**
+   * `engine: 'playcanvas'` only: the WebGL context's `preserveDrawingBuffer` (default false) —
+   * the knob for the weave's zero-copy read race on large canvases.
+   */
+  preserveDrawingBuffer?: boolean;
+  /**
+   * `engine: 'playcanvas'` only: the `playcanvas` module namespace to use instead of
+   * `import('playcanvas')` — for a page that already bundles its own copy.
+   */
+  playcanvas?: unknown;
   /** Metres of world the tile's height spans (default 0.24). */
   virtualDisplayHeight?: number;
   /**
@@ -124,7 +203,17 @@ export interface SplatOptions {
   flipY?: boolean;
   /** Degrees/second of turntable once idle (default 8). */
   idleSpin?: number;
+  /**
+   * Drag + wheel. On the PlayCanvas backend the drag is TILT-AND-RELAX: measured as a fraction of
+   * the canvas box from the press, it tilts up to ±`orbitMaxDeg` (a half-width swipe reaches it)
+   * and relaxes back to rest on release; `idleSpin` resumes once at rest. On Spark (SceneViewer)
+   * it is still the cumulative turntable (a full-width drag = 180°).
+   */
   orbit?: boolean;
+  /** PlayCanvas: the largest drag tilt, degrees, either axis (default 15). */
+  orbitMaxDeg?: number;
+  /** PlayCanvas: easing time constants, seconds — `drag` while held (0.2), `rest` after release (0.6). */
+  orbitEase?: { drag?: number; rest?: number };
   fit?: 'contain' | 'height' | 'cover' | 'none';
   /** Fraction of the tile the subject may occupy (default 0.8) — width AND height. */
   margin?: number;
@@ -138,7 +227,11 @@ export interface SplatOptions {
   /** Per-eye buffer scale; 0.5–0.7 is usually free (default 1). */
   renderScale?: number;
   feather?: number;
-  /** Minimum ms between splat sorts. Defaults to 16 so both eyes share one sort per frame. */
+  /**
+   * Spark: minimum ms between splat sorts (default 16, so both eyes share one sort per frame).
+   * PlayCanvas: accepted and has no effect — the engine re-sorts when the camera ROTATES, with one
+   * directional sort serving every view.
+   */
   sortIntervalMs?: number;
   /**
    * Cut overdraw. UNSET changes nothing — every Spark default stays where Spark put it, so an
@@ -150,7 +243,7 @@ export interface SplatOptions {
    * `true`, −5…−20 % measured) and `'aggressive'` (−22 %) tighten the quad extent instead, which
    * is the axis that actually pays on the web; both move pixels.
    */
-  perf?: true | 'exact' | 'balanced' | 'aggressive' | SplatPerfOptions;
+  perf?: boolean | 'exact' | 'balanced' | 'aggressive' | SplatPerfOptions;
   /**
    * Which view rig. `'auto'` (the default) reads it off the ASSET — a `.sog` carrying a `camera`
    * block was lifted from a photograph and gets a camera rig that conserves the recording
@@ -158,6 +251,14 @@ export interface SplatOptions {
    * detectable when `src` is BYTES.
    */
   rig?: 'auto' | 'display' | 'camera';
+  /**
+   * Camera rig only: what gives when the canvas is not the capture's shape. `'height'` (default,
+   * the 1.7 behaviour) keeps the capture's vertical extent and widens or narrows the horizontal to
+   * the canvas. `'cover'` always fills the tile with photograph: a canvas WIDER than the capture
+   * keeps the width and crops top/bottom (a 4:3 capture in a 16:9 tile); a narrower one is
+   * `'height'`. Both backends; the 3D rig's vertical FOV follows the crop. Anything else throws.
+   */
+  captureFit?: 'height' | 'cover';
   /** Camera rig only: the distance in world metres that sits ON the glass. */
   convergence?: number;
   /**
@@ -189,13 +290,68 @@ export interface SplatOptions {
   observe?: Element;
 }
 
+/** `handle.stats()` on `engine: 'playcanvas'`. */
+export interface SplatStats {
+  /** `'streamed'` for a `lod-meta.json`, `'flat'` for `.sog`/`.ply`, null before load. */
+  kind: 'flat' | 'streamed' | null;
+  /**
+   * Splats the engine placed in this tile's work buffer on the LAST frame: after LOD selection
+   * and the budget, before per-view frustum culling. Every view of the tile draws from this set.
+   */
+  resident: number;
+  /** The largest `resident` seen so far. */
+  peakResident: number;
+  /** The tile's splat budget (all views included), or null. */
+  budget: number | null;
+  /** The asset's own count: every splat of a flat source, the finest level of a Streamed SOG. */
+  numSplats: number;
+  /** Views drawn last frame (1 in mono, the runtime's view count in 3D). */
+  views: number;
+  /** Streamed SOG only (null otherwise): LOD levels, chunk files, chunk files currently loaded. */
+  lodLevels: number | null;
+  files: number | null;
+  filesLoaded: number | null;
+  /**
+   * `performance.now()` (ms since navigation start) of the first frame that drew a non-empty
+   * set — the page's time to first splat. Null until then.
+   */
+  firstFrameMs: number | null;
+}
+
 /** What {@link addSplat} returns: a TileHandle plus the objects behind it. */
 export interface SplatHandle {
-  readonly viewer: SceneViewer;
-  /** Spark's SplatMesh. */
+  /**
+   * SceneViewer on Spark; the PlayCanvas backend's own viewer on `engine: 'playcanvas'` (null
+   * there until the backend module has loaded — one module fetch after addSplat returns).
+   */
+  readonly viewer: SceneViewer | PlayCanvasSplatViewer;
+  /**
+   * Spark's SplatMesh; on `engine: 'playcanvas'` a `{ numSplats, entity, asset, resource }`
+   * record of the engine objects. Null until the asset is loaded.
+   */
   readonly mesh: object;
-  /** Spark's SparkRenderer. */
-  readonly spark: object;
+  /** Spark's SparkRenderer (absent on `engine: 'playcanvas'`). */
+  readonly spark?: object;
+  /** Which backend is rendering: `'playcanvas'` or `'spark'`; null until it has loaded. */
+  readonly backend: 'playcanvas' | 'spark' | null;
+  /**
+   * ADVANCED — not covered by the semver promise. The renderer objects behind this window, for a
+   * page that wants to add its own content. Null until the backend has booted.
+   *
+   * PlayCanvas: `{ app, root, camera }` — the tile's `pc.AppBase`; the content root entity (the
+   * splat's content space — add your own entities under it, e.g. a glTF through the engine's
+   * container loader, skinned and animated included); the eye-rig camera entity. `remove()`
+   * destroys the app, and everything under `root` with it.
+   *
+   * Spark: `{ renderer, scene, camera }` — the WebGLRenderer, the scene, and whichever camera draws
+   * the current frame.
+   */
+  readonly engine:
+    | { readonly app: unknown; readonly root: unknown; readonly camera: unknown }
+    | { readonly renderer: unknown; readonly scene: unknown; readonly camera: unknown }
+    | null;
+  /** `engine: 'playcanvas'` only: the live focus, in the splat's own space. */
+  getFocus?(opts?: { target?: boolean }): number[] | null;
   /** Bounds actually used for framing; null until `ready` resolves. */
   frame: SubjectBounds | null;
   /**
@@ -222,8 +378,36 @@ export interface SplatHandle {
     point: number[] | { x: number; y: number; z: number } | null,
     opts?: { snap?: boolean },
   ): SplatHandle;
-  /** What is under a point on the canvas, in the splat's own space — the double-click's raycast. */
+  /**
+   * Swap the asset (URL or bytes) in place. PlayCanvas backend only — throws on Spark.
+   *
+   * The new file loads BEHIND the current one; then the two crossfade over `fadeMs` (0 = a cut)
+   * and the old one is released. The rig waterfall re-runs for the new file (rig, lens, focus and
+   * frame update; `onFocusChange` fires). The pose (yaw/pitch/zoom/depth) is kept unless
+   * `resetPose`. A newer call supersedes an older one still loading. Resolves once the fade has
+   * finished; rejects if the new asset cannot be loaded (the current one stays on screen).
+   */
+  setSource(
+    src: string | Blob | ArrayBuffer | Uint8Array,
+    opts?: { fadeMs?: number; resetPose?: boolean },
+  ): Promise<SplatHandle>;
+  /**
+   * Called with the live focus (the splat's own space) whenever it moves — easing included — and
+   * which waterfall step it came from. PlayCanvas backend; assign any time, even before `ready`.
+   */
+  onFocusChange: ((point: number[], info: { focusSource: ResolvedRig['focusSource'] | null }) => void) | null;
+  /**
+   * What is under a point on the canvas, in the splat's own space — the double-click's pick.
+   * PlayCanvas: the nearest gaussian CENTRE to the ray over the FULL centre set (haze under 5 %
+   * opacity skipped); on a Streamed SOG, over the chunks currently resident. Spark: its surface
+   * raycast, falling back to the nearest centre.
+   */
   pick(clientX: number, clientY: number): number[] | null;
+  /**
+   * `engine: 'playcanvas'` only: splat accounting for this tile. Null until the backend module
+   * has loaded.
+   */
+  stats?(): SplatStats | null;
 
   /** Close this window and release its GPU resources. */
   remove(): void;

package/three.d.ts

@@ -100,6 +100,23 @@ export function cameraRigFromCamera(
   opts?: CameraRigOptions,
 ): XRViewRigInit;
 
+/**
+ * The same CAMERA-rig descriptor as {@link cameraRigFromCamera}, from a plain pose instead of a
+ * three.js camera — for a renderer that is not three. Agrees with cameraRigFromCamera to the bit
+ * for the same pose.
+ */
+export function cameraRigFromPose(
+  pose: {
+    /** WORLD position. */
+    position: { x: number; y: number; z: number };
+    /** WORLD orientation quaternion. */
+    orientation: { x: number; y: number; z: number; w: number };
+    /** FULL vertical angle in DEGREES (three's `camera.fov` convention). */
+    fov: number;
+  },
+  opts?: CameraRigOptions,
+): XRViewRigInit;
+
 /**
  * Build a DISPLAY-rig descriptor — the default rig, made explicit and posable: the canvas is a
  * portal onto a virtual display `virtualDisplayHeight` metres tall. Adds what the scalar