@displayxr/inline3d 1.12.0 → 1.13.0

package/CHANGELOG.md

@@ -5,6 +5,61 @@ 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.13.0 — 2026-09-24
+
+Touches the **preview tier** (`./splat`, `engine: 'playcanvas'` only), additively. A page that
+passes none of the new options renders the same pixels (rest view MAE 0.000 vs 1.12.1).
+
+### Added
+
+- **Splat shader effects** ([`docs/splat-effects.md`](docs/splat-effects.md)). Every effect is keyed
+  on world position and time only, so both eyes of a woven tile agree (measured: coincident eyes,
+  L == R, MAE 0.000, for every effect).
+  - `addSplat(…, { reveal: 'inflate' | 'sweep' | 'dissolve' | 'fade' | { type, durationMs, holdMs,
+    easing, origin } })`: installed at its start state before the first frame, played once
+    `firstWoven` settles (at once in 2D).
+  - `handle.playEffect(name, { durationMs, holdMs, easing, origin, direction, scope }) →
+    Promise<{ finished }>`, `handle.setEffect(name, params | null)` (persistent effects, or any
+    effect held at `{ progress }`), `handle.stopEffect(name?, { finish })`, `handle.effects()`.
+  - Effects: `inflate` (the gallery's reveal, `z' = D + (z − D)·s` along rays from the eyes),
+    `deflate`, `sweep` (radial, sized from the framing box), `fade` (coverage-linear to ±8 %),
+    `dissolve` (the engine's dissolve script, as a reveal), `pulse`, `grade`, `clip`, and
+    `custom` / `custom:<name>` GLSL (engine-shaped functions, `dxrProgress`, `dxrTime`,
+    `splat.index` in entity scope; screen-space inputs refused).
+  - The SDK owns ONE generated chunk per scope (tile: the unified material's `gsplatModifyVS`;
+    entity: a work-buffer modifier), composed grade → clip → reveal → pulse → custom. Removing
+    the last effect restores the engine's own chunk: MAE 0.000, colour and alpha.
+  - `setSource(src, { transition: 'cut' | 'crossfade' | 'flip' | 'wavefront', durationMs, easing,
+    reveal, ridge, ridgeMaxDisparity })`. **`wavefront`** is the photo-frame prototype's sweep:
+    a soft left → right front, 0.18 of the travel wide, commits each column from the old photo
+    (a frozen frame, wiped at the same viewport u in both eyes) to the new one, with a 0.03 m
+    depth ridge riding it (capped at 0.4 % of the view width in disparity). It takes 2000 ms,
+    ease-in-out, and falls back to the crossfade in a hidden tab. `flip` flattens the old photo
+    onto its convergence plane, swaps at zero disparity and inflates the new one. `reveal`
+    reveals the incoming asset (entity scope) while the old one fades. `fadeMs` keeps its 1.12.1
+    meaning. For photo slideshows: `crossfade` or `wavefront`.
+  - Frame cost within noise (stereo 18.10 ms → 18.73 ms with an animating inflate; hiding effects
+    are cheaper).
+  - Spark: `reveal`, `playEffect`, `setEffect`, `stopEffect` throw "PlayCanvas-only in this
+    version".
+- **`THIRD_PARTY_NOTICES.md`** (in the package): the MIT notices of PlayCanvas engine, three.js
+  and Spark. Shader code adapted from the engine carries a provenance comment.
+
+## 1.12.1 — 2026-09-24
+
+### Fixed
+
+- **`setSource(…, { fadeMs })` is a real crossfade** (`./splat`, `engine: 'playcanvas'`). The fade
+  scaled every splat's alpha by t and drew both photos in one sorted pass, so whichever photo sat in
+  front won: an incoming photo in front covered 64 % of the picture at t = 0.2 (an 800 ms fade read
+  as a snap), one behind it only 18 % at t = 0.5 (a late pop). Now the last frame of the outgoing
+  asset is frozen into a texture (both eyes) and lerped with the live incoming one, per
+  premultiplied pixel, alpha included. Measured on three SHARP photo pairs, mono and a fake 2-view
+  stereo pair: the blend fraction is **t to ±0.001** at every tenth, identical in both eyes; the
+  frame at t = 0 equals the outgoing frame and the end state equals a `fadeMs: 0` swap (MAE 0.000,
+  colour and alpha). The outgoing photo holds still during the fade. If no frame is drawn within
+  250 ms (a hidden tab) the old one-pass fade runs, now with a coverage-linear alpha remap.
+
 ## 1.12.0 — 2026-09-24
 
 Touches the **preview tier** (`./model`, and `./splat`'s `engine: 'playcanvas'` import path). A

package/README.md

@@ -53,6 +53,16 @@ Bundlers: the engine is reached through a named-import module (`js/inline3d-play
 so the unused ~40% of the engine tree-shakes away); its sort workers are Blob URLs (CSP
 `worker-src blob:`), and esbuild needs `node:worker_threads` marked external.
 
+**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
+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
+[`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md).
+
 **Models render with PlayCanvas by default (1.12).** `addModel(wall, canvas, 'chair.glb')` loads
 the glTF with the PlayCanvas engine (optional peer `playcanvas`), lit to match the Khronos glTF
 Sample Viewer: an in-memory neutral studio environment, Khronos PBR Neutral tone mapping,
@@ -162,6 +172,7 @@ js/
   inline3d-model-playcanvas.js  the PlayCanvas model backend (Sample-Viewer lighting, engine decoders)
   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)
                       from what the asset declares (you serve the decoder files — see the guide)
 docs/
   authoring-inline-3d.md   the authoring guide

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,76 @@
+# Third-party notices — `@displayxr/inline3d`
+
+`@displayxr/inline3d` is Apache-2.0 (see `LICENSE`). It bundles no third-party code, but parts of
+it are adapted from, or run on, the MIT-licensed projects below. Their notices follow.
+
+| Project | Version | How it is used |
+|---|---|---|
+| [PlayCanvas engine](https://github.com/playcanvas/engine) | 2.22.3 | Optional peer (`playcanvas`): the default splat backend and the `./model` backend. Shader code in this package is **adapted** from it: the non-square-pixel footprint rewrite of `src/scene/shader-lib/glsl/chunks/gsplat/vert/gsplatCorner.js` (`js/inline3d-splat-playcanvas.js`), the quad-extent cap in `gsplatCommon.js` (`js/inline3d-splat-perf.js`), and the dissolve effect and its hash/noise/fbm helpers from `scripts/esm/gsplat/shader-effect-dissolve.mjs` (`js/inline3d-splat-effects.js`). Each adapted site carries a provenance comment. |
+| [three.js](https://github.com/mrdoob/three.js) | ≥ 0.150 | Optional peer (`three`): the `./three` helpers, the Spark splat path, `./model`'s `engine: 'three'`. |
+| [Spark](https://github.com/sparkjsdev/spark) | ≥ 2.0 | Optional peer (`@sparkjsdev/spark`): the Spark splat backend. |
+
+## PlayCanvas engine — MIT
+
+Copyright (c) 2011-2026 PlayCanvas Ltd.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+## three.js — MIT
+
+Copyright © 2010-2026 three.js authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+## Spark — MIT
+
+Copyright © 2025 WORLD LABS TECHNOLOGIES, INC.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/js/inline3d-playcanvas-engine.js

@@ -46,11 +46,16 @@ export {
   BLENDEQUATION_ADD,
   BLENDMODE_SRC_ALPHA,
   BLENDMODE_ZERO,
+  BLENDMODE_ONE,
+  BLENDMODE_ONE_MINUS_SRC_ALPHA,
   CULLFACE_NONE,
   SEMANTIC_POSITION,
   SEMANTIC_TEXCOORD0,
   ShaderChunks,
   SHADERLANGUAGE_GLSL,
+  // setSource's frame snapshot
+  RenderTarget,
+  FILTER_NEAREST,
   // splats
   WORKBUFFER_UPDATE_ALWAYS,
   WORKBUFFER_UPDATE_ONCE,