@displayxr/inline3d 1.14.0 → 1.16.0

package/js/inline3d-splat.js

@@ -373,6 +373,13 @@ export function addSplat(wall, canvas, src, opts = {}) {
     prepareSource() {
       throw new Error("@displayxr/inline3d/splat: prepareSource() is implemented on the PlayCanvas backend only.");
     },
+    /** Not on this backend: the live rig switch is a PlayCanvas-backend feature. */
+    setRig() {
+      throw new Error(
+        "@displayxr/inline3d/splat: setRig() is implemented on the PlayCanvas backend only " +
+          "(addSplat(…, { engine:'playcanvas' })).",
+      );
+    },
     /** Not on this backend (splat effects are PlayCanvas-only in this version). */
     playEffect() {
       throw effectsNotOnSpark('playEffect()');
@@ -657,6 +664,16 @@ export function addSplat(wall, canvas, src, opts = {}) {
  * Fields (`viewer`, `mesh`, `rig`, …) are null until then; `viewer` in particular appears one
  * module-load later than on Spark.
  */
+/** setRig's type/options shape, checked at the call before the adapter has loaded (it re-checks all of it). */
+function validateSetRigArgs(type, o) {
+  if (!['display', 'camera', 'auto'].includes(type)) {
+    throw new Error(`@displayxr/inline3d/splat: setRig("${type}") — expected 'display', 'camera' or 'auto'.`);
+  }
+  if (o !== undefined && (o === null || typeof o !== 'object')) {
+    throw new TypeError('@displayxr/inline3d/splat: setRig options must be an object.');
+  }
+}
+
 function addSplatDeferred(wall, canvas, src, opts) {
   const pending = [];
   const queue = (name) => (...args) => {
@@ -711,6 +728,14 @@ function addSplatDeferred(wall, canvas, src, opts) {
     // setSource replaces this stub on the same object by then).
     setSource: (...args) => out.ready.then(() => out.setSource(...args)),
     prepareSource: (...args) => out.ready.then(() => out.prepareSource(...args)),
+    // A rig switch before the first asset has landed: validated now (controls:'page' and a bad
+    // type throw at the call's own line), applied once it has.
+    setRig: page
+      ? pageOnly('setRig')
+      : (type, o) => {
+          validateSetRigArgs(type, o);
+          return out.ready.then(() => out.setRig(type, o));
+        },
     // Effects before the adapter has loaded: validated NOW (a bad call throws at its own line),
     // then run once the first asset is on screen.
     playEffect: (name, o) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@displayxr/inline3d",
-  "version": "1.14.0",
+  "version": "1.16.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",

package/splat.d.ts

@@ -131,7 +131,8 @@ export interface SogCamera {
  */
 export interface ResolvedRig {
   type: 'camera' | 'display';
-  typeSource: 'caller' | 'block' | 'block-present' | 'default';
+  /** `'setRig'` after `handle.setRig('display' | 'camera')`; the waterfall's step otherwise. */
+  typeSource: 'caller' | 'block' | 'block-present' | 'default' | 'setRig';
   rest: { position: number[]; rotation: number[] };
   intrinsics: SogIntrinsics;
   intrinsicsSource: 'block' | 'caller' | 'estimated' | 'fallback-28mm';
@@ -154,7 +155,14 @@ export interface ResolvedRig {
     | 'median-disparity'
     | 'default'
     | 'picked'
-    | 'set';
+    | 'set'
+    | 'frame';
+  /**
+   * On a display rig set by `handle.setRig('display')`: what it framed, in `handle.engine.root`'s
+   * space, and where that came from (the page's meshes, meshes + the shown splat, the splat alone,
+   * or the caller's `frame`). Absent otherwise.
+   */
+  frame?: { center: number[]; extent: number[]; source: 'root' | 'root+splat' | 'splat' | 'caller' } | null;
   /** 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). */
@@ -187,6 +195,13 @@ export interface SplatOptions {
    * the knob for the weave's zero-copy read race on large canvases.
    */
   preserveDrawingBuffer?: boolean;
+  /**
+   * `engine: 'playcanvas'` only: create the tile's WebGL context with MSAA (default false — it buys
+   * nothing on alpha-blended splats). Turn it on when the page draws meshes under
+   * `handle.engine.root` and wants addModel's silhouettes (addModel's context has MSAA on);
+   * `setRig('display')` is then pixel-identical to an addModel tile. Fixed at context creation.
+   */
+  antialias?: boolean;
   /**
    * `engine: 'playcanvas'` only: the `playcanvas` module namespace to use instead of
    * `import('playcanvas')` — for a page that already bundles its own copy.
@@ -374,6 +389,10 @@ export interface SplatParticleOptions {
    * home; max 0.05). In 2D a nominal 64 mm-at-1.7 m separation is assumed.
    */
   maxDisparity?: number;
+  /** Fade a particle over the first `vanish` of its flight (0 = off, the reveals' default; the particle transitions use ~0.3–0.45). */
+  vanish?: number;
+  /** Share of the gaussians drawn while in flight, 0..1 (1 = all, the reveals' default; the swarm uses 0.2). */
+  density?: number;
   /** `order: 'layers'`: gaussians per layer (default 768² = 589 824, SHARP). */
   layerSize?: number;
   /** `assemble`: how far out the swarm starts (half-view-widths), its spiral (rad), its curl turbulence, how coherent its start field is (0..1), and how much of it reaches back in depth (0..1). */
@@ -486,6 +505,46 @@ export interface SplatEffectState {
   progress: number;
 }
 
+/**
+ * `handle.setRig('display', opts)`'s options. Every default is addModel's, so a mesh framed this
+ * way renders exactly as `addModel(url, { engine: 'playcanvas' })` renders it.
+ * docs/playcanvas-adapter.md §setRig.
+ */
+export interface SplatSetRigDisplayOptions {
+  /** Default 0.24. */
+  virtualDisplayHeight?: number;
+  /** Default `'contain'`. */
+  fit?: 'contain' | 'cover' | 'height' | 'none';
+  /** Default 0.8. */
+  margin?: number;
+  /** Default 4. */
+  depthLimit?: number;
+  /** Default true. */
+  fitSweep?: boolean;
+  /** Idle turntable, °/s after 2.5 s without input. Default 8 (addModel's); 0 for a still product. */
+  idleSpin?: number;
+  /** On the declared display rig. Default 1 each. */
+  ipdFactor?: number;
+  parallaxFactor?: number;
+  perspectiveFactor?: number;
+  /**
+   * The eye camera's tone mapping WHILE THE SPLAT IS HIDDEN (the splat's display-referred colours
+   * keep `'none'` whenever it is shown). Default `'neutral'` — addModel's (Khronos PBR Neutral).
+   */
+  toneMapping?: 'none' | 'linear' | 'neutral' | 'aces' | 'aces2' | 'filmic' | 'hejl';
+  /**
+   * `'room'` (default; `'neutral'` is the same): install addModel's generated neutral-studio IBL
+   * when the scene has no `envAtlas` of its own, removed again when the rig switches away. A page
+   * that lights its own meshes is never touched. `'none'`: never install it.
+   */
+  environment?: 'room' | 'neutral' | 'none';
+  /**
+   * Frame THIS box (in `handle.engine.root`'s space) instead of measuring. Default: the enabled
+   * meshes under root (+ the splat's box when it is shown); with no meshes, the splat itself.
+   */
+  frame?: { center: number[] | { x: number; y: number; z: number }; extent: number[] | { x: number; y: number; z: number } };
+}
+
 /** `setSource`'s options. */
 export interface SplatSourceOptions {
   /** > 0 = a crossfade of this length (the 1.10 option; same as `transition: 'crossfade'`). */
@@ -497,8 +556,15 @@ export interface SplatSourceOptions {
    * inflates out of its own; default 2200 ms), `'wavefront'` (a soft front crosses left → right
    * with a thin depth ridge riding it; default 2000 ms, ease-in-out; falls back to the crossfade
    * in a hidden tab). For photo slideshows: `crossfade` or `wavefront`.
-   */
-  transition?: 'cut' | 'crossfade' | 'flip' | 'wavefront';
+   *
+   * The particle transitions (docs/splat-effects.md §Particle transitions): `'swarm'` (the old
+   * photo disperses into a curl-noise swarm while the new one assembles out of one), `'burst'`
+   * (the old one collapses into its focus, the new one bursts out of its own), `'shimmer-cross'`
+   * (nothing moves: twinkling points out, twinkling points in) and `'dust'` (drifting dust out,
+   * gathering dust in). 2.6–2.8 s, linear shared clock (each particle eases itself). The old
+   * photo is live, in 2D too; a hidden tab gets the crossfade.
+   */
+  transition?: 'cut' | 'crossfade' | 'flip' | 'wavefront' | SplatParticleTransitionName;
   durationMs?: number;
   easing?: SplatEasing;
   /** `cut`/`crossfade` only: reveal the INCOMING asset (entity scope) while the old one fades. */
@@ -519,8 +585,34 @@ export interface SplatSourceOptions {
    * the single-camera RenderView path always use `'frozen'`.
    */
   outgoing?: 'live' | 'frozen';
+  /** Particle transitions: particle options for BOTH photos (the shared ones of the particle reveals). */
+  order?: SplatParticleOptions['order'];
+  stagger?: number;
+  jitter?: number;
+  maxDisparity?: number;
+  dotSize?: number;
+  noiseScale?: number;
+  layerSize?: number;
+  origin?: SplatEffectOrigin;
+  /** Particle transitions: how much of the clock the two photos' spans share, 0..1 (0 = one after the other). */
+  overlap?: number;
+  /** Particle transitions: option overrides for the OUTGOING photo's effect. */
+  outgoingFx?: SplatParticleOptions & Record<string, unknown>;
+  /** Particle transitions: option overrides for the INCOMING photo's effect. */
+  incomingFx?: SplatParticleOptions & Record<string, unknown>;
 }
 
+/**
+ * `prepareSource`'s options: the `setSource` options the prepared asset will be swapped in with.
+ * For a particle transition, its shaders are compiled and linked NOW, in the dwell — otherwise the
+ * first transition of each kind in a page blocks its first frame on the link (tens of ms, hundreds
+ * the first time a machine sees the variant). Validated like setSource's.
+ */
+export type SplatPrepareOptions = SplatSourceOptions;
+
+/** setSource's particle transitions (docs/splat-effects.md §Particle transitions). */
+export type SplatParticleTransitionName = 'swarm' | 'burst' | 'shimmer-cross' | 'dust';
+
 /**
  * What `prepareSource()` resolves to: an opaque, single-use handle for `setSource`. The asset is
  * fully resident (GPU textures + the engine's centre array) until used or disposed.
@@ -689,7 +781,20 @@ export interface SplatHandle {
    * Memory: two full assets resident until the swap (≈ +70 MB of GPU textures per 1.18M-gaussian
    * SOG). `remove()` disposes any still unused.
    */
-  prepareSource(src: string | Blob | ArrayBuffer | Uint8Array): Promise<SplatPreparedSource>;
+  prepareSource(src: string | Blob | ArrayBuffer | Uint8Array, opts?: SplatPrepareOptions): Promise<SplatPreparedSource>;
+  /**
+   * PlayCanvas backend only — throws on Spark, and with `controls:'page'` (the page's camera IS
+   * the rig). Switch the rig live, on the next frame: no remount, no reload, no new session.
+   *
+   * `'display'` frames the page's meshes under `handle.engine.root` (+ the splat when shown) on
+   * addModel's defaults and declares a display rig; `'camera'` returns to the asset's capture rig,
+   * re-resolved from the waterfall's own inputs (lens, captureFit, focus rung); `'auto'` is what
+   * the load resolved. The pose resets to the new rig's rest; the declared view rig switches with
+   * it; the choice is sticky across `setSource` until `'auto'`. A clean cut (no eased transition).
+   * `handle.rig.typeSource` reads `'setRig'`. Resolves once applied. docs/playcanvas-adapter.md §setRig.
+   */
+  setRig(type: 'display', opts?: SplatSetRigDisplayOptions): Promise<SplatHandle>;
+  setRig(type: 'camera' | 'auto'): Promise<SplatHandle>;
   /**
    * `engine: 'playcanvas'` only (throws on Spark). Play a transition/pulse/custom effect;
    * validated at the call, run once the first asset is on screen. Resolves `{ finished }` —