@displayxr/inline3d 1.13.1 → 1.15.0

package/CHANGELOG.md

@@ -5,6 +5,99 @@ entry points (`.`, `./three`) are frozen for 1.x, while the **scene subpaths** (
 `./splat`, `./model`) are a preview tier whose options may change in any release. Entries below say
 which tier they touch, because that is what tells you whether an upgrade can move your pixels.
 
+## 1.15.0 — 2026-09-24
+
+Touches the **preview tier** (`./splat`, `engine: 'playcanvas'` only). Additive; the existing transitions
+and reveals render the same pixels.
+
+### Added
+
+- **Particle transitions for `setSource`** (#36): `transition: 'swarm' | 'burst' | 'shimmer-cross' | 'dust'`.
+  They play the particle reveals across a slide change, with both photos live, in 3D and in 2D.
+  The old photo plays its effect backwards while the new one plays it forwards, on overlapping
+  spans of one clock (`overlap`).
+  - `swarm`: the old photo disperses into a curl-noise swarm and the new one assembles out of one.
+  - `burst`: the old photo collapses into its focus and the new one bursts out of its own.
+  - `shimmer-cross`: twinkling points out and twinkling points in; nothing moves.
+  - `dust`: drifting dust out, gathering dust in.
+
+  Defaults are 2.6–2.8 s on a linear shared clock; each particle eases on its own path. The end
+  state is a `cut`, MAE 0.000 in colour and alpha in both eyes, and VRAM goes back to baseline.
+  A hidden tab gets the crossfade.
+  See [`docs/splat-effects.md` § Particle transitions](docs/splat-effects.md#particle-transitions).
+- They render at RENDER TIME. One tile-scope chunk serves both photos, and each photo's values
+  sit on the mesh instance of the gsplat manager that draws it. A first cut used entity-scope
+  work-buffer modifiers, which rewrote both 1.18M work buffers and re-sorted both every frame.
+  Measured in a visible Chrome, that cost 2D pacing its 120 Hz: p95 went from 16.7 ms to 9.8–10.1.
+  A photo with nothing to draw skips its draw.
+- **`prepareSource(src, { transition, … })`**: with a particle transition, this also compiles and
+  links its shaders in the dwell. Otherwise the first transition of each kind blocks its first
+  frame on the link: 35–50 ms, and 190 + 260 ms on a variant the machine has never compiled.
+- Particle options `vanish` (fade over the first part of the flight) and `density` (the share
+  drawn in flight). Both are off for the reveals.
+
+### Not changed
+
+- The live `crossfade` / `wavefront` still run at about 40 Hz in stereo on an M1 (median 25.6 ms).
+  They draw both photos in full for the whole window. The same skip-what-is-not-visible idea may
+  apply there; that is a follow-up.
+
+## 1.14.0 — 2026-09-24
+
+Touches the **preview tier** (`./splat`, `engine: 'playcanvas'` only). New particle reveals are additive. One default changes pixels
+DURING a transition in a woven 3D session (the old photo is now live); end states and 2D are
+unchanged.
+
+### Changed
+
+- **`crossfade` / `wavefront`: the outgoing photo is LIVE in a woven 3D session** (#36). Before, it
+  was a frozen frame for the whole window, and on a tracked panel a still image under a moving head
+  reads as "eye tracking hung, then resumed". The old asset now stays resident. A second camera
+  with its own layer, RenderViews and render target keeps rendering it through the same eye views,
+  and the overlay lerps or wipes the two live images per eye with the same maths as before. Measured
+  on the GPU with a fake 2-view wall, the old photo at four head poses matches its own plain render
+  with MAE 0.000 in both eyes, across the rig switch; 1.13.0 showed one image at every pose. End
+  state == `cut`, MAE 0.000, colour and alpha, both eyes. Cost: about 2× splat draw for the
+  window, and both assets resident (+73 MB of GPU textures at 1.18M gaussians).
+  `outgoing: 'frozen'` restores 1.13.0; it stays the default in 2D. See
+  [`docs/splat-effects.md` § Live or frozen outgoing](docs/splat-effects.md#live-or-frozen-outgoing).
+- The frozen-frame texture is freed when a transition ends; it used to stay allocated (7 MB at
+  2560×720).
+- The framing pass (the percentile core per axis, then the window pass) runs in steps with yields
+  between them, with bit-identical results. It was a single 60–80 ms main-thread task per 1.18M
+  gaussians at 4× CPU. It now runs under 50 ms per step, so the longest task left in a load is the
+  engine's own centre readback (≈60 ms at 4×).
+
+### Added
+
+- **`handle.prepareSource(src) → Promise<SplatPreparedSource>`**: fetch, decode and upload the next
+  asset in the background, without rendering it. The SDK's own passes run in idle periods. Then
+  `setSource(prepared, opts)` starts on the next frame, with no load on the transition path.
+  `prepared.dispose()`, single use; `remove()` disposes what is left.
+  Measured with 4× / 6× CPU throttling on an M1 (1,179,648 gaussians): from the `setSource` call to
+  the first transition frame, the longest main-thread task goes from 104 / 159 ms to none over 50 ms, and the
+  longest rAF gap from 138 / 196 ms to 18 / 17 ms. Memory: +22.5 MB of GPU textures plus the
+  engine's centre array (≈14 MB) per prepared 1.18M SOG, until used.
+- `setSource`'s `outgoing: 'live' | 'frozen'` option; `SplatPreparedSource` in `splat.d.ts`.
+- **Particle reveals** ([`docs/splat-effects.md` §Particle reveals](docs/splat-effects.md#particle-reveals)),
+  usable as `reveal: '<name>'`, `playEffect(name)` and `setSource(…, { reveal })`. Every gaussian is
+  a particle with its own start time:
+  - `assemble`: a swarm that flies home along spiralling curl-noise paths.
+  - `dissolve-in`: a dissolve played backwards; dust drifts in and gathers patch by patch.
+  - `converge`: a burst from the focus that flies out and settles.
+  - `shimmer`: twinkling points that grow into the picture.
+  - Options: `order` (`'radial'`, `'depth'`, `'noise'`, `'random'`, or `'layers'` for SHARP grid
+    order via `splat.index`, which is entity scope only), `stagger`, `jitter`, `dotSize`, `grow`,
+    `flightAlpha`, `color`/`glow`, `noiseScale`, plus per-effect shape options.
+  - Comfort cap `maxDisparity` (default 0.004 of the view width, exact at every depth; nominal
+    separation in 2D). The swarm never comes nearer the viewer than that.
+  - Every effect ends bit-identical to the plain render. Measured on the real GPU: MAE 0.000,
+    colour and alpha, mono and fake stereo, tile and entity scope; removal is exact too.
+  - In-flight particles are ~1 px dots until nearly home, which hides the engine's
+    original-centre sort order.
+- The eye frame that effects receive now carries `tanHalfFovY` (internal; the `'radial'` key spans the
+  view actually seen).
+
 ## 1.13.1 — 2026-09-24
 
 Touches the **preview tier** (`./splat`, `engine: 'playcanvas'` only). No pixel change.
@@ -22,7 +115,6 @@ Touches the **preview tier** (`./splat`, `engine: 'playcanvas'` only). No pixel
   frame time at 4× CPU throttling went from 1.9–2.1 ms to 0.2–0.7 ms. GPU-synced frame time at 1×
   went from 16.0 ms to 14.4–14.6 ms, the same as after a `crossfade` (14.3–14.7 ms), which never
   had the bug.
-
 ## 1.13.0 — 2026-09-24
 
 Touches the **preview tier** (`./splat`, `engine: 'playcanvas'` only), additively. A page that

package/README.md

@@ -55,9 +55,9 @@ so the unused ~40% of the engine tree-shakes away); its sort workers are Blob UR
 
 **Splat effects (preview, `engine: 'playcanvas'`).** Shader effects on the splats themselves,
 keyed on world position and time so both eyes agree: `addSplat(…, { reveal: 'inflate' | 'sweep' |
-'dissolve' | 'fade' })` (plays once the tile is woven), `handle.playEffect` / `setEffect` /
-`stopEffect` / `effects()` (inflate, deflate, sweep, dissolve, fade, pulse, grade, clip, custom
-GLSL), and `setSource(src, { transition: 'crossfade' | 'flip' | 'wavefront', reveal })`. Spark
+'dissolve' | 'fade' | 'assemble' | 'dissolve-in' | 'converge' | 'shimmer' })` (plays once the tile
+is woven; the last four are particle reveals), `handle.playEffect` / `setEffect` / `stopEffect` /
+`effects()` (the reveals, deflate, pulse, grade, clip, custom GLSL), and `setSource(src, { transition: 'crossfade' | 'flip' | 'wavefront', reveal })`. Spark
 throws on all of them for now. [`docs/splat-effects.md`](docs/splat-effects.md).
 
 Splat and model rendering on the PlayCanvas backend uses the PlayCanvas engine (MIT); see
@@ -173,6 +173,7 @@ js/
   inline3d-model.js             the three.js model backend (engine:'three'; ./model/three)
   inline3d-playcanvas-engine.js named playcanvas imports for both PlayCanvas adapters (tree-shaking)
   inline3d-splat-effects.js     splat shader effects: the runner, the effect registry (PlayCanvas)
+  inline3d-splat-live.js        setSource's live outgoing photo: its own camera, layer and target (PlayCanvas)
                       from what the asset declares (you serve the decoder files — see the guide)
 docs/
   authoring-inline-3d.md   the authoring guide

package/js/inline3d-playcanvas-engine.js

@@ -56,6 +56,8 @@ export {
   // setSource's frame snapshot
   RenderTarget,
   FILTER_NEAREST,
+  // setSource's live outgoing asset (./inline3d-splat-live.js)
+  Layer,
   // splats
   WORKBUFFER_UPDATE_AUTO,
   WORKBUFFER_UPDATE_ALWAYS,