@displayxr/inline3d 1.12.0 → 1.13.0

package/js/inline3d-splat-shared.js

@@ -437,3 +437,36 @@ export function normalizeCameraPose(matrixWorld, o = {}) {
   }
   return { matrixWorld: m, verticalFovDeg: fov, near, far, convergence };
 }
+
+// ── coverage-linear alpha (setSource's crossfade, the `fade` effect) ────────────────────────────
+
+/**
+ * Nominal optical depth of a dense photo's splat stack, per pixel: −ln(transmittance) through the
+ * whole stack at rest. The remap below is exact for a pixel of optical depth `L`. Real pictures
+ * spread widely around any single value (measured 13–25 on SHARP photos), which is why the
+ * crossfade blends IMAGES (FRAME_SNAPSHOT in ./inline3d-splat-playcanvas.js) and uses this only
+ * to shape ramps — never as the thing that makes a fade linear.
+ */
+export const FADE_OPTICAL_DEPTH = 3;
+
+/**
+ * Smallest per-splat transmittance the remap works from. A fully opaque splat (SOG alpha 255/255
+ * decodes to exactly 1, common in photos) has transmittance 0, and 0^k is 0 for every k > 0 — so
+ * without a floor it could never fade at all. 0.02 caps one splat's optical depth at ~3.9.
+ */
+export const FADE_TRANSMITTANCE_FLOOR = 0.02;
+
+/**
+ * The per-splat alpha exponent `k` that puts a stack of nominal optical depth `L` at screen
+ * coverage `c` (0..1).
+ *
+ * Scaling every splat's alpha by `c` saturates: a pixel under n near-opaque splats is covered
+ * `1 − (1 − c·α)^n`. Raising each splat's transmittance to a power instead, `α' = 1 − (1 − α)^k`,
+ * multiplies the stack's optical depth by k: coverage is `1 − e^{−kL}`. Solving for coverage =
+ * c·(1 − e^{−L}) gives this k. Exact ends: k(0) = 0 (α' = 0, invisible) and k(1) = 1 (untouched).
+ */
+export function coverageExponent(c, L = FADE_OPTICAL_DEPTH) {
+  if (!(c > 0)) return 0;
+  if (c >= 1) return 1;
+  return -Math.log(1 - c * (1 - Math.exp(-L))) / L;
+}

package/js/inline3d-splat.js

@@ -23,6 +23,7 @@ import { SparkRenderer, SplatMesh } from '@sparkjsdev/spark';
 import { EyeCamera, EdgeFeather, cameraRigFromCamera } from './inline3d-three.js';
 import { SceneViewer, boundsFromPositions } from './inline3d-viewer.js';
 import { readSogCamera } from './inline3d-sog.js';
+import { resolveRevealOption, effectsNotOnSpark, validateEffectCall } from './inline3d-splat-effects.js';
 import { applySplatPerf, splatPerfMeshOptions } from './inline3d-splat-perf.js';
 import {
   toArray3,
@@ -172,6 +173,8 @@ export function addSplat(wall, canvas, src, opts = {}) {
   // ./inline3d-splat-playcanvas.js, imported DYNAMICALLY so a page that never asks for it never
   // resolves `playcanvas` — see addSplatDeferred.
   if (resolveSplatEngine(opts) === 'playcanvas') {
+    // A bad `reveal` is a page bug true of every call: throw at the call.
+    resolveRevealOption(opts.reveal);
     // A format that engine provably cannot read (a .spz URL, gzip bytes, a Spark-only fileType)
     // is a page bug: say so NOW rather than fail inside a loader later.
     const why = playcanvasCannotRead(src, opts);
@@ -182,6 +185,7 @@ export function addSplat(wall, canvas, src, opts = {}) {
   // controls:'page' is a PlayCanvas-backend feature (docs/playcanvas-adapter.md §controls:'page'):
   // on Spark it would need SceneViewer — which ./viewer and ./model share — to take an external
   // camera in both its mono and eye paths. Refused by name rather than half-supported.
+  if (opts.reveal !== undefined && opts.reveal !== false) throw effectsNotOnSpark('reveal');
   if (pageControls) {
     throw new Error(
       "@displayxr/inline3d/splat: controls:'page' is not supported on Spark (the default engine) — " +
@@ -365,6 +369,17 @@ export function addSplat(wall, canvas, src, opts = {}) {
           "only; with the Spark backend, remove() this handle and addSplat() the new asset.",
       );
     },
+    /** Not on this backend (splat effects are PlayCanvas-only in this version). */
+    playEffect() {
+      throw effectsNotOnSpark('playEffect()');
+    },
+    setEffect() {
+      throw effectsNotOnSpark('setEffect()');
+    },
+    stopEffect() {
+      throw effectsNotOnSpark('stopEffect()');
+    },
+    effects: () => [],
   };
 
   // `src` may be a URL or the bytes themselves.
@@ -691,6 +706,19 @@ 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)),
+    // 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) => {
+      validateEffectCall(name, o, 'play');
+      return out.ready.then(() => out.playEffect(name, o));
+    },
+    setEffect: (name, params) => {
+      validateEffectCall(name, params, 'set');
+      pending.push(['setEffect', [name, params]]);
+      return out;
+    },
+    stopEffect: queue('stopEffect'),
+    effects: () => [],
     getFocus: () => null,
     // A plain data slot the adapter reads at call time, so a callback assigned on the very next
     // line after addSplat — before the module has loaded — is the one that fires.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@displayxr/inline3d",
-  "version": "1.12.0",
+  "version": "1.13.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",
@@ -50,6 +50,7 @@
     "js/inline3d-splat-rig.js",
     "js/inline3d-splat-playcanvas.js",
     "js/inline3d-splat-shared.js",
+    "js/inline3d-splat-effects.js",
     "js/inline3d-model.js",
     "js/inline3d-model-entry.js",
     "js/inline3d-model-playcanvas.js",
@@ -61,7 +62,8 @@
     "model.d.ts",
     "CHANGELOG.md",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md"
   ],
   "keywords": [
     "displayxr",

package/splat.d.ts

@@ -327,6 +327,133 @@ export interface SplatOptions {
    * caught and warned once; frames keep rendering.
    */
   onBeforeFrame?: (frame: SplatFrameInfo) => void;
+  /**
+   * `engine: 'playcanvas'` only (throws on Spark): play a reveal on the first asset. Installed at
+   * its start state before the first frame, played once `firstWoven` settles (at once in 2D) —
+   * docs/splat-effects.md. A name uses that effect's defaults; an object overrides them.
+   */
+  reveal?: SplatRevealName | false | SplatRevealSpec;
+}
+
+/** The transition effects `reveal` accepts. */
+export type SplatRevealName = 'inflate' | 'sweep' | 'dissolve' | 'fade';
+
+/** Named easings; a function `(x) => y` on [0, 1] also works. */
+export type SplatEasing =
+  | 'linear'
+  | 'easeInQuad'
+  | 'easeOutQuad'
+  | 'easeInOutQuad'
+  | 'easeInCubic'
+  | 'easeOutCubic'
+  | 'easeInOutCubic'
+  | 'easeInOutSine'
+  | ((x: number) => number);
+
+/**
+ * Where an effect is centred: `'focus'` (the focus point), `'eyes'` (the eyes' midpoint — the
+ * inflate default), a point in the splat's OWN space `[x, y, z]`, or a canvas point
+ * `[clientX, clientY]` / `{ clientX, clientY }` resolved with `pick()` when the effect starts.
+ * All effects are keyed on world position and time only, so both eyes agree.
+ */
+export type SplatEffectOrigin = 'focus' | 'eyes' | [number, number, number] | [number, number] | { clientX: number; clientY: number };
+
+/** Options every played effect takes. */
+export interface SplatEffectTiming {
+  durationMs?: number;
+  /** Wait this long at the start state before the clock runs. */
+  holdMs?: number;
+  easing?: SplatEasing;
+  origin?: SplatEffectOrigin;
+  /** `'in'` (default): arrive, then the effect is removed. `'out'`: leave; the end state is held until `stopEffect`. */
+  direction?: 'in' | 'out';
+  /** `'tile'` (default, every splat of the tile, render time) or `'entity'` (the current asset only, work buffer). */
+  scope?: 'tile' | 'entity';
+}
+
+/** `reveal: { type, … }`. */
+export interface SplatRevealSpec extends Omit<SplatEffectTiming, 'direction' | 'scope'> {
+  type: SplatRevealName;
+  [param: string]: unknown;
+}
+
+/** A custom effect's GLSL (PlayCanvas-shaped) — docs/splat-effects.md §custom. */
+export interface SplatCustomEffect extends SplatEffectTiming {
+  /**
+   * Any of `void modifySplatCenter(inout vec3 center)`, `void modifySplatRotationScale(vec3
+   * originalCenter, vec3 modifiedCenter, inout vec4 rotation, inout vec3 scale)`, `void
+   * modifySplatColor(vec3 center, inout vec4 color)` — world-space centres. `dxrProgress` (0..1)
+   * and `dxrTime` (s) are defined; `splat.index` / `splat.uv` are the asset's own file index in
+   * `scope: 'entity'`. Screen-space inputs are refused.
+   */
+  glsl: string;
+  /** Tile scope only: `void modifySplatColor(vec2 gaussianUV, inout vec4 color)` per fragment. */
+  fragmentGlsl?: string;
+  /** Uniform values, set every frame; a function gets the frame time in ms. */
+  uniforms?: Record<string, number | number[] | ((tMs: number) => number | number[])>;
+  /** `setEffect` only: hold `dxrProgress` here (default 1). */
+  progress?: number;
+  /** `playEffect` only: keep the effect at its end instead of removing it. */
+  hold?: boolean;
+}
+
+export type SplatEffectName = 'inflate' | 'deflate' | 'sweep' | 'dissolve' | 'fade' | 'pulse' | 'grade' | 'clip' | 'custom' | `custom:${string}`;
+
+/** `setEffect('grade', …)`. */
+export interface SplatGradeParams {
+  /** Stops; default 0. */
+  exposure?: number;
+  contrast?: number;
+  saturation?: number;
+  tint?: [number, number, number];
+  scope?: 'tile' | 'entity';
+}
+
+/** `setEffect('clip', …)` — in the splat's own space, like setFocus. Exactly one shape. */
+export interface SplatClipParams {
+  box?: { min: [number, number, number]; max: [number, number, number] };
+  sphere?: { center: [number, number, number]; radius: number };
+  /** Keep the outside instead. */
+  invert?: boolean;
+  scope?: 'tile' | 'entity';
+}
+
+/** One row of `handle.effects()`. */
+export interface SplatEffectState {
+  name: string;
+  scope: 'tile' | 'entity';
+  stage: 'grade' | 'clip' | 'reveal' | 'pulse' | 'custom';
+  /** Played (has a clock) vs set (held). */
+  playing: boolean;
+  /** Held at its start state until a gate settles (a reveal waiting for `firstWoven`). */
+  waiting: boolean;
+  /** 0..1, before easing. */
+  progress: number;
+}
+
+/** `setSource`'s options. */
+export interface SplatSourceOptions {
+  /** > 0 = a crossfade of this length (the 1.10 option; same as `transition: 'crossfade'`). */
+  fadeMs?: number;
+  resetPose?: boolean;
+  /**
+   * `'cut'` (default), `'crossfade'` (images lerp, see setSource), `'flip'` (the old photo
+   * flattens to its convergence plane — zero disparity — the swap happens there, the new one
+   * 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';
+  durationMs?: number;
+  easing?: SplatEasing;
+  /** `cut`/`crossfade` only: reveal the INCOMING asset (entity scope) while the old one fades. */
+  reveal?: SplatRevealName | false | SplatRevealSpec;
+  /** `wavefront`: the soft band, a fraction of the picture width (default 0.18). */
+  band?: number;
+  /** `wavefront`: the ridge's pull toward the eyes, world units (default 0.03 — 3 cm on a metric photo). */
+  ridge?: number;
+  /** `wavefront`: the ridge's disparity cap, a fraction of the eye view's width (default 0.004, max 0.05). */
+  ridgeMaxDisparity?: number;
 }
 
 /** What `onBeforeFrame` receives. */
@@ -466,15 +593,35 @@ 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 rig waterfall re-runs for the new file (rig, lens, focus and
+   * 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
    * 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?: { fadeMs?: number; resetPose?: boolean },
-  ): Promise<SplatHandle>;
+  setSource(src: string | Blob | ArrayBuffer | Uint8Array, opts?: SplatSourceOptions): 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 }` —
+   * false when stopped or replaced. docs/splat-effects.md.
+   */
+  playEffect(
+    name: Exclude<SplatEffectName, 'grade' | 'clip'>,
+    opts?: SplatEffectTiming & Record<string, unknown>,
+  ): Promise<{ finished: boolean }>;
+  /**
+   * `engine: 'playcanvas'` only. Set a persistent effect (`grade`, `clip`, `custom`), hold a
+   * transition at `{ progress }`, or pass `null` to remove it (the exact baseline).
+   */
+  setEffect(name: 'grade', params: SplatGradeParams | null): SplatHandle;
+  setEffect(name: 'clip', params: SplatClipParams | null): SplatHandle;
+  setEffect(name: 'custom' | `custom:${string}`, params: SplatCustomEffect | null): SplatHandle;
+  setEffect(name: SplatEffectName, params: (SplatEffectTiming & { progress?: number } & Record<string, unknown>) | null): SplatHandle;
+  /** Stop one effect (all with no name): `finish: true` jumps to its end state, else removes it. */
+  stopEffect(name?: SplatEffectName, opts?: { finish?: boolean }): SplatHandle;
+  /** What is on right now. */
+  effects(): SplatEffectState[];
   /**
    * Called with the live focus (the splat's own space) whenever it moves — easing included — and
    * which waterfall step it came from. PlayCanvas backend; assign any time, even before `ready`.