@displayxr/inline3d 1.13.1 → 1.15.0

package/js/inline3d-splat.js

@@ -369,6 +369,10 @@ export function addSplat(wall, canvas, src, opts = {}) {
           "only; with the Spark backend, remove() this handle and addSplat() the new asset.",
       );
     },
+    /** Not on this backend: prepareSource() feeds setSource(), a PlayCanvas-backend feature. */
+    prepareSource() {
+      throw new Error("@displayxr/inline3d/splat: prepareSource() is implemented on the PlayCanvas backend only.");
+    },
     /** Not on this backend (splat effects are PlayCanvas-only in this version). */
     playEffect() {
       throw effectsNotOnSpark('playEffect()');
@@ -706,6 +710,7 @@ function addSplatDeferred(wall, canvas, src, opts) {
     // A swap requested before the first asset has landed runs once it has (the adapter's own
     // 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)),
     // 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/js/inline3d-viewer.js

@@ -152,7 +152,30 @@ function swap(a, i, j) {
  *        Set 0 to get the old percentile-only box back.
  * @returns {{center:number[], extent:number[]}|null} null if there is nothing to measure.
  */
-export function boundsFromPositions(xyz, { lo = 0.05, hi = 0.95, expand = 2.5 } = {}) {
+export function boundsFromPositions(xyz, opts) {
+  const it = boundsSteps(xyz, opts);
+  let r = it.next();
+  while (!r.done) r = it.next();
+  return r.value;
+}
+
+/**
+ * boundsFromPositions, in steps: the same code, the same numbers bit for bit, but a caller can
+ * give the main thread back between the per-axis selections and the window pass. On a 1.18M
+ * gaussian cloud under 4× CPU throttling the one-shot version was a single 60-80 ms task.
+ * `await boundsFromPositionsAsync(xyz, opts, yielder)` runs it with `yielder()` between steps.
+ */
+export async function boundsFromPositionsAsync(xyz, opts, yielder) {
+  const it = boundsSteps(xyz, opts);
+  let r = it.next();
+  while (!r.done) {
+    await yielder();
+    r = it.next();
+  }
+  return r.value;
+}
+
+function* boundsSteps(xyz, { lo = 0.05, hi = 0.95, expand = 2.5 } = {}) {
   const n = Math.floor(xyz.length / 3);
   if (n < 1) return null;
   // Below a few hundred points the percentiles are noise — just use the true box.
@@ -171,6 +194,7 @@ export function boundsFromPositions(xyz, { lo = 0.05, hi = 0.95, expand = 2.5 }
     const hiV = selectKth(axisVals, n, kHi);
     center[axis] = 0.5 * (loV + hiV);
     extent[axis] = Math.max(hiV - loV, 1e-6);
+    yield;
   }
   // Untrimmed already IS the true box, and expand 0 asks for the old behaviour.
   if (!trim || expand <= 0) return { center, extent };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@displayxr/inline3d",
-  "version": "1.13.1",
+  "version": "1.15.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",
@@ -51,6 +51,7 @@
     "js/inline3d-splat-playcanvas.js",
     "js/inline3d-splat-shared.js",
     "js/inline3d-splat-effects.js",
+    "js/inline3d-splat-live.js",
     "js/inline3d-model.js",
     "js/inline3d-model-entry.js",
     "js/inline3d-model-playcanvas.js",

package/splat.d.ts

@@ -336,7 +336,66 @@ export interface SplatOptions {
 }
 
 /** The transition effects `reveal` accepts. */
-export type SplatRevealName = 'inflate' | 'sweep' | 'dissolve' | 'fade';
+export type SplatRevealName = 'inflate' | 'sweep' | 'dissolve' | 'fade' | SplatParticleRevealName;
+
+/** The particle reveals: every gaussian is a particle with its own start time (docs/splat-effects.md §Particle reveals). */
+export type SplatParticleRevealName = 'assemble' | 'dissolve-in' | 'converge' | 'shimmer';
+
+/**
+ * Options every particle reveal takes (plus its timing). All sizes are in PICTURE units, so the
+ * look is the same on a 2 cm object and a 40 m street.
+ */
+export interface SplatParticleOptions {
+  /**
+   * What staggers the particles: `'radial'` (distance in the picture from the origin), `'depth'`
+   * (near first), `'noise'` (fbm patches), `'random'`, or `'layers'` (a SHARP photo's grid order:
+   * layer 0, the visible surface, then layer 1, the disocclusion fill, each outward from the
+   * origin — reads `splat.index`, so it forces `scope: 'entity'`).
+   */
+  order?: 'radial' | 'depth' | 'noise' | 'random' | 'layers';
+  /** Fraction of the duration spent launching particles, 0..0.95. */
+  stagger?: number;
+  /** How much of each particle's key is random, 0..1. */
+  jitter?: number;
+  /** A particle in flight is a dot this size (a fraction of the view width). */
+  dotSize?: number;
+  /** A particle grows back to its own splat over the last (1 − grow) of its flight. */
+  grow?: number;
+  /** In-flight alpha multiplier, 0..1. */
+  flightAlpha?: number;
+  /** In-flight tint, added as `color · glow`. */
+  color?: [number, number, number];
+  glow?: number;
+  /** Size of the noise patches, per half-view-width. */
+  noiseScale?: number;
+  /**
+   * Comfort cap: no particle is ever nearer the eyes than its home depth by more than this much
+   * extra disparity, a fraction of the eye view's width (default 0.004; 0 = never nearer than
+   * 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). */
+  spread?: number;
+  swirl?: number;
+  turbulence?: number;
+  coherence?: number;
+  depth?: number;
+  /** `dissolve-in`: the wind's lift and the random drift (half-view-widths). */
+  lift?: number;
+  drift?: number;
+  /** `converge`: the spiral (rad) and the launch ball's radius (half-view-widths). */
+  spin?: number;
+  burst?: number;
+  /** `shimmer`: twinkle rate (rad/s) and sparkle strength. */
+  twinkle?: number;
+  sparkle?: number;
+}
 
 /** Named easings; a function `(x) => y` on [0, 1] also works. */
 export type SplatEasing =
@@ -397,7 +456,7 @@ export interface SplatCustomEffect extends SplatEffectTiming {
   hold?: boolean;
 }
 
-export type SplatEffectName = 'inflate' | 'deflate' | 'sweep' | 'dissolve' | 'fade' | 'pulse' | 'grade' | 'clip' | 'custom' | `custom:${string}`;
+export type SplatEffectName = 'inflate' | 'deflate' | 'sweep' | 'dissolve' | 'fade' | SplatParticleRevealName | 'pulse' | 'grade' | 'clip' | 'custom' | `custom:${string}`;
 
 /** `setEffect('grade', …)`. */
 export interface SplatGradeParams {
@@ -442,8 +501,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. */
@@ -454,6 +520,55 @@ export interface SplatSourceOptions {
   ridge?: number;
   /** `wavefront`: the ridge's disparity cap, a fraction of the eye view's width (default 0.004, max 0.05). */
   ridgeMaxDisparity?: number;
+  /**
+   * `crossfade` / `wavefront`: how the OUTGOING photo is shown during the window.
+   * `'live'` (the default in a woven 3D session): it stays resident and keeps rendering every frame
+   * through the same eye views (head motion included) into its own target, blended per eye with
+   * the live incoming one — about 2× draw for the window, both assets resident. `'frozen'` (the
+   * default in 2D): its last frame, frozen into a texture (1.12.1); one draw, but no head parallax
+   * on the outgoing photo — on a tracked panel it reads as tracking pausing. Engine builds without
+   * 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.
+ */
+export interface SplatPreparedSource {
+  /** The asset's own count (every splat of a flat source). */
+  readonly numSplats: number;
+  /** `'ready'` until `setSource` uses it (`'used'`) or `dispose()` drops it (`'disposed'`). */
+  readonly state: 'ready' | 'used' | 'disposed';
+  /** Release the prepared asset (no-op once used or disposed). */
+  dispose(): void;
 }
 
 /** What `onBeforeFrame` receives. */
@@ -592,20 +707,32 @@ export interface SplatHandle {
   /**
    * 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 crossfade blends the two IMAGES linearly: the last frame of
-   * the old asset is frozen (both eyes) and lerped with the live new one, so the mix is exactly
-   * `t` whatever the two photos' depth order (the old asset's own motion stops during the fade). The rig waterfall re-runs for the new file (rig, lens, focus and
+   * The new file loads BEHIND the current one (or pass a `prepareSource()` result: no load at all
+   * on this path); then the two crossfade over `fadeMs` (0 = a cut) and the old one is released.
+   * The crossfade blends the two IMAGES linearly, per eye, so the mix is exactly `t` whatever the
+   * two photos' depth order. The old image is LIVE in a woven 3D session (it keeps rendering with
+   * head motion; `outgoing: 'frozen'` restores the 1.12.1 frozen last frame, the 2D default). The
+   * end state is exactly a plain swap. 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?: SplatSourceOptions): Promise<SplatHandle>;
+  setSource(src: string | Blob | ArrayBuffer | Uint8Array | SplatPreparedSource, opts?: SplatSourceOptions): Promise<SplatHandle>;
+  /**
+   * PlayCanvas backend only — throws on Spark. Fetch, decode and upload `src` now, in the
+   * background (the SDK's own passes in idle periods; the engine's end-of-load unpack runs when
+   * it must), without rendering it. `setSource(prepared, opts)` then starts on the next frame with
+   * no load on the transition path. Single use; `dispose()` it if the page changes its mind.
+   * 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, opts?: SplatPrepareOptions): Promise<SplatPreparedSource>;
   /**
    * `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 }` —
    * false when stopped or replaced. docs/splat-effects.md.
    */
+  playEffect(name: SplatParticleRevealName, opts?: Omit<SplatEffectTiming, 'direction'> & SplatParticleOptions): Promise<{ finished: boolean }>;
   playEffect(
     name: Exclude<SplatEffectName, 'grade' | 'clip'>,
     opts?: SplatEffectTiming & Record<string, unknown>,