@displayxr/inline3d 1.19.3 → 1.21.0

package/js/inline3d-splat-effects.js

@@ -1164,6 +1164,58 @@ export function particleSpan(t, overlap, side) {
 /** Options a page may pass through setSource to both sides of a particle transition. */
 export const PARTICLE_TRANSITION_OPTIONS = Object.freeze(['order', 'stagger', 'jitter', 'maxDisparity', 'dotSize', 'noiseScale', 'layerSize', 'origin']);
 
+// ── setSource's SEQUENCE transitions ('reassemble', { type: 'sequence', out, in }) ────────────
+//
+// One photo at a time: the current photo plays a reveal BACKWARDS until nothing of it is drawn,
+// it is released, the next one is loaded and placed hidden, and it plays a reveal FORWARDS. No
+// second camera, no live-outgoing layer, no overlay target, no frozen capture: the eye camera
+// renders every frame, with one asset in the scene.
+//
+// A reveal can take part only if it draws NOTHING at amount 0 — otherwise the swap would pop from
+// a visible end state to an empty start (inflate's end state is a flat photo: that swap is
+// 'flip'). `dissolve` is left out for the reason it is not a setSource transition: its sway has a
+// depth component (docs/splat-effects.md §Comfort).
+
+/**
+ * The reveals a sequence can run, with the option overrides each side gets by default. The
+ * particle ones reuse the tuned sides of the particle transitions (a sparse `density`, and a
+ * `vanish` so the swarm thins out to nothing and gathers out of nothing).
+ */
+export const SEQUENCE_REVEALS = Object.freeze({
+  assemble: { out: PARTICLE_TRANSITIONS.swarm.out.opts, in: PARTICLE_TRANSITIONS.swarm.in.opts },
+  'dissolve-in': { out: PARTICLE_TRANSITIONS.dust.out.opts, in: PARTICLE_TRANSITIONS.dust.in.opts },
+  converge: { out: PARTICLE_TRANSITIONS.burst.out.opts, in: PARTICLE_TRANSITIONS.burst.in.opts },
+  shimmer: { out: PARTICLE_TRANSITIONS['shimmer-cross'].out.opts, in: PARTICLE_TRANSITIONS['shimmer-cross'].in.opts },
+  sweep: { out: {}, in: {} },
+  fade: { out: {}, in: {} },
+});
+
+/** Named sequences: `transition: 'reassemble'` = assemble backwards, then forwards. */
+export const SEQUENCE_TRANSITIONS = Object.freeze({
+  reassemble: { out: 'assemble', in: 'assemble', durationMs: 3000, easing: 'linear', beat: 0.1 },
+});
+
+/**
+ * Does `effect` with resolved options `o` draw nothing at amount 0? sweep's front starts one band
+ * before its origin and fade's coverage is 0; a particle reveal needs `hiddenAtZero` (converge,
+ * shimmer: not yet launched; assemble, dissolve-in: `vanish` > 0).
+ */
+export function emptyAtZero(effect, o) {
+  if (effect === 'sweep' || effect === 'fade') return true;
+  const def = EFFECTS[effect];
+  return !!(def?.particle && def.hiddenAtZero?.(o));
+}
+
+/**
+ * The three spans of a sequence over its clock, as fractions: out over [0, a], the empty beat
+ * over [a, 1 − a], in over [1 − a, 1], with a = (1 − beat) / 2.
+ */
+export function sequenceSpans(beat) {
+  const b = Math.min(0.9, Math.max(0, beat));
+  const a = (1 - b) / 2;
+  return { out: a, beat: b, in: a };
+}
+
 
 /**
  * The wavefront's per-column commit, lt ∈ [0, 1], for eased progress `t` at normalised u — the
@@ -1522,6 +1574,55 @@ export class SplatEffects {
     };
   }
 
+  /**
+   * A TILE-scope effect driven by the adapter's clock (setSource's sequence transitions: one photo
+   * in the scene, so the tile material carries its values and every manager of the tile reads
+   * them — a fresh one included, so a just-placed photo draws its hidden start state on its very
+   * first frame). Render time: no work-buffer rewrite, no re-sort. Named `name` (the chunk's
+   * prefix), so a sequence installs the same program as a particle transition of the same effect
+   * and order. Hidden from effects() and from a page's stopEffect(). Returns
+   * { set(amount, timeS), restart(), remove(), amount }.
+   */
+  driveTile(name, effect, opts) {
+    const o = resolveEffectOptions(effect, { ...opts, scope: 'tile', direction: 'in', progress: 0 }, 'set', { internal: true });
+    const inst = this._makeInstance(name, o, 'set');
+    inst.def = EFFECTS[effect];
+    inst.hidden = true;
+    inst.timeS = 0;
+    this._replace('tile', name, inst);
+    this._setupInstance(inst);
+    this._apply('tile', inst, this.ctx.now());
+    this._install('tile');
+    const alive = () => !this._disposed && this.scopes.get('tile')?.get(name) === inst;
+    return {
+      set: (amount, timeS = inst.timeS) => {
+        if (!alive()) return false;
+        inst.opts.progress = Math.min(1, Math.max(0, amount));
+        inst.timeS = timeS;
+        this._apply('tile', inst, this.ctx.now());
+        return true;
+      },
+      restart: () => {
+        if (!alive()) return;
+        inst.state = {};
+        this._setupInstance(inst);
+        this._apply('tile', inst, this.ctx.now());
+      },
+      remove: () => {
+        if (!alive()) return;
+        this.scopes.get('tile').delete(name);
+        inst.resolve({ finished: true });
+        this._install('tile');
+      },
+      get amount() {
+        return inst.opts.progress;
+      },
+      get alive() {
+        return alive();
+      },
+    };
+  }
+
   /**
    * ONE tile-scope body for the two photos of a setSource particle transition, with each photo's
    * values on its OWN mesh instance (the engine draws each photo through its own gsplat manager and

package/js/inline3d-splat-live.js

@@ -148,6 +148,9 @@ export class LiveOutgoing {
     this.frames = 0;
     this.views = [];
     this._frustumKey = '';
+    /** PRE-SORT (warm): the current asset is ALSO on the live layer, before the swap. */
+    this.warming = false;
+    this._warmLayers = null;
   }
 
   /** Engine support for this path: RenderViews on one camera, render targets, layers. */
@@ -212,21 +215,94 @@ export class LiveOutgoing {
     this.w = this.h = 0;
   }
 
+  /**
+   * PRE-SORT the live camera BEFORE the swap (the fix for the frozen bridge, #36). The current
+   * asset goes on the live layer IN ADDITION to its own (the eye keeps drawing it, untouched: its
+   * World placement set is unchanged, so its manager neither rebuilds nor re-sorts), and the live
+   * camera starts rendering it, through the same views, into its target. Its manager builds its
+   * work buffer and runs its first sort NOW, while the photo is still on screen and live. At the
+   * swap, start() takes the asset OFF World only: the live layer's placement set does not change,
+   * so its manager keeps its sorted state and the overlay can sample it on the very first frame.
+   *
+   * Without it, start() moved the asset onto a FRESH manager at the swap, and the overlay showed
+   * the frozen capture until that manager's first sort came back from the sort worker — a still
+   * image under a moving head for as long as that takes (the "tracking stops for a moment at
+   * every transition" report). Returns false if this engine build cannot (nothing changed).
+   */
+  warm(entity) {
+    const v = this.viewer;
+    if (this.active || !LiveOutgoing.supported(v) || !entity?.gsplat) return false;
+    if (this.warming) {
+      if (this.entity === entity) return true;
+      this.cancelWarm();
+    }
+    try {
+      this._ensureEngineObjects();
+      this._ensureTarget(v.canvas.width, v.canvas.height);
+      const own = Array.isArray(entity.gsplat.layers) ? entity.gsplat.layers.slice() : [];
+      this._warmLayers = own;
+      entity.gsplat.layers = [...own.filter((id) => id !== this.layer.id), this.layer.id];
+      this.entity = entity;
+      this.oldFrame = null; // same asset, same rig: the chain is the rig node itself
+      this.frames = 0;
+      this.cam.enabled = true;
+      this.warming = true;
+      return true;
+    } catch (err) {
+      console.warn('[inline3d/splat] live outgoing pre-sort unavailable; the transition keeps the frozen bridge', err);
+      this.cancelWarm();
+      return false;
+    }
+  }
+
+  /** The pre-sorted manager has drawn a sorted frame (what start() will then need no bridge for). */
+  get warmReady() {
+    if (!this.warming) return false;
+    const mgr = this.manager;
+    if (mgr === undefined) return this.frames >= 3;
+    const w = mgr?.world;
+    const st = w?.getState?.(w.lastWorldStateVersion);
+    return !!st?.sortedBefore && this.frames >= 1;
+  }
+
+  /** Drop a pre-sort that did not become a live window: the asset back on only its own layers. */
+  cancelWarm() {
+    if (!this.warming) return;
+    const e = this.entity;
+    const own = this._warmLayers;
+    this.warming = false;
+    this._warmLayers = null;
+    this.entity = null;
+    if (this.cam) this.cam.enabled = false;
+    this._destroyTarget();
+    try {
+      if (e?.gsplat && own) e.gsplat.layers = own;
+    } catch {
+      /* entity already gone */
+    }
+  }
+
   /**
    * Take `entity` (the outgoing splat, still enabled) onto the live layer. `oldFrame` is
    * viewer.lensFrame() read BEFORE the incoming asset's rig was adopted. Returns false if this
-   * engine build cannot (the caller keeps the frozen frame).
+   * engine build cannot (the caller keeps the frozen frame). After warm(entity) the live
+   * manager is kept (only the World placement goes), so `ready` holds from the first frame.
    */
   start(entity, oldFrame) {
     const v = this.viewer;
     if (!LiveOutgoing.supported(v) || !entity?.gsplat) return false;
+    const warmed = this.warming && this.entity === entity;
+    if (this.warming && !warmed) this.cancelWarm();
     try {
       this._ensureEngineObjects();
       this._ensureTarget(v.canvas.width, v.canvas.height);
       entity.gsplat.layers = [this.layer.id];
       this.entity = entity;
       this.oldFrame = oldFrame;
-      this.frames = 0;
+      if (!warmed) this.frames = 0;
+      this.warming = false;
+      this._warmLayers = null;
+      this.warmed = warmed;
       this.cam.enabled = true;
       this.active = true;
       return true;
@@ -275,7 +351,7 @@ export class LiveOutgoing {
    * viewport), the eye's node pose, and the rig chain.
    */
   sync(entries, rect, frustum) {
-    if (!this.active) return;
+    if (!this.active && !this.warming) return;
     const v = this.viewer;
     const pc = v.pc;
     const rvs = this.views;
@@ -322,9 +398,11 @@ export class LiveOutgoing {
   stop() {
     // The outgoing entity is NOT put back on its old layer: the caller releases it right after,
     // and a round trip through World would dirty the eye's manager (a work-buffer rebuild).
+    if (this.warming) return this.cancelWarm();
     this.entity = null;
     this.oldFrame = null;
     this.active = false;
+    this.warmed = false;
     if (this.cam) this.cam.enabled = false;
     this._destroyTarget();
   }