@displayxr/inline3d 1.7.0 → 1.8.0

package/splat.d.ts

@@ -34,6 +34,36 @@ 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 global splat count per tile.
+   */
+  splatBudget?: 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 +122,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 +154,22 @@ 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.
+   */
+  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 +182,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 +206,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 +222,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 +230,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;
   /**
@@ -191,11 +271,38 @@ export interface SplatOptions {
 
 /** 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,7 +329,30 @@ 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;
 
   /** Close this window and release its GPU resources. */

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