@displayxr/inline3d 1.7.1 → 1.9.0

package/CHANGELOG.md

@@ -5,6 +5,92 @@ 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.9.0 — 2026-09-23
+
+Touches the **preview tier** (`./splat`, `engine: 'playcanvas'` only). Additive: nothing changes for
+Spark callers or for flat `.sog` files.
+
+### Added
+
+- **Streamed SOG on the PlayCanvas backend** (epic #36 P2).
+  - Pass the URL of the `lod-meta.json`, or of the directory holding it. Bytes of a
+    `lod-meta.json`, or a streamed URL with `engine: 'spark'`, throw at call time with a message
+    saying what to pass instead.
+  - `splatBudget` is **per tile, all views included**: one engine camera renders every view, so
+    both eyes share one budget. It defaults to **600k** on a Streamed SOG when unset, and
+    `perf: false` keeps the engine's 1M.
+  - New `perf` keys pass through: `lodMode`, `lodUpdateDistance`, `lodUpdateAngle`,
+    `lodUnderfillLimit` (unset = engine default).
+  - New **`handle.stats()`**: `resident`, `peakResident`, `budget`, `numSplats`, `views`,
+    `lodLevels`, `files`, `filesLoaded`, `firstFrameMs`.
+  - Framed from its octree leaf boxes, not the root bound. The `camera` block is read from the
+    top level of `lod-meta.json`.
+  - Measured on a 5.88M-gaussian captured scene (M1 Pro): first frame 2.9 s against 20.8 s flat
+    at 100 Mbit/s, and 9.6 ms against 117 ms for two 1080p views. It is not a byte saving at a
+    close framing. Recipe and tables: [`docs/playcanvas-adapter.md`](docs/playcanvas-adapter.md)
+    §Streamed SOG.
+
+## 1.8.0 — 2026-09-22
+
+Touches the **preview tier** (`./splat`, plus one additive `./three` export). **Existing callers get
+the same engine and the same code path**: with no `engine` option, or `engine: 'spark'`, `addSplat`
+renders with three.js + Spark as in 1.7.1. The PlayCanvas engine is **opt-in** with
+`engine: 'playcanvas'`.
+
+**One behaviour change, for one class of file.** The camera-rig focus waterfall gains a rung (see
+*Changed*). A `.sog` whose `camera` block has **no `focus`**, or a `focus` its converter computed
+as the whole-cloud median (`focus.source: "cloud-median"`), now converges on the **nearest
+substantial clump** in the middle of the frame instead of the whole-scene median. On an open
+landscape that is 2.4 m (the tree trunk), not 46.9 m, so that file's 3D will look different, as
+intended. Blocks with a considered focus (`convergence`, `manual`, …, or no `source`), assets with
+no block, and a caller's `focus` / `convergence` are unaffected. Both engines.
+
+### Added
+
+- **`addSplat(…, { engine: 'playcanvas' })`: the PlayCanvas engine as a second splat backend**
+  (epic #36).
+  - Same handle and the same rig/lens/focus waterfall as Spark. One camera renders every view
+    through the engine's `RenderView` list, so one sort serves all eyes.
+  - A shader-chunk fix for the engine's square-pixel footprint assumption, which a side-by-side
+    buffer breaks.
+  - `perf` presets map onto engine knobs, and `perf: false` leaves the engine alone.
+  - A **URL** `.sog` yields its `camera` block too.
+  - Needs the new **optional** peer `playcanvas >=2.22.3 <3`, loaded by a dynamic `import()` only
+    when asked for.
+  - Reads `.sog`, `.ply` and a Streamed-SOG `lod-meta.json`. With `engine: 'playcanvas'`, a
+    `.spz` / `.splat` / `.ksplat` source (or a Spark-only `fileType`) **throws at call time**.
+    Those stay Spark formats.
+  - Differences from the Spark path: [`docs/playcanvas-adapter.md`](docs/playcanvas-adapter.md).
+- On the PlayCanvas backend:
+  - **`handle.setSource(src, { fadeMs, resetPose })`**: a crossfading in-place asset swap that
+    re-runs the rig waterfall for the new file. The pose is kept unless `resetPose`. It throws on
+    Spark.
+  - **`feather`**: the per-eye edge fade, matching `EdgeFeather`.
+  - **Tilt-and-relax `orbit`**: the drag is a fraction of the tile, capped at `orbitMaxDeg` (15°),
+    and relaxes back on release (`orbitEase` `{ drag: 0.2, rest: 0.6 }` s). Spark keeps its
+    turntable drag.
+  - **Exact `pick`**: the nearest gaussian centre over the full centre set, with haze skipped.
+- **`captureFit: 'height' | 'cover'`** on the camera rig, both backends. `'height'` (default) is
+  the 1.7 window. `'cover'` fills the tile with photograph (a 4:3 capture in a 16:9 tile crops
+  top/bottom).
+- **`handle.engine`** (advanced, not semver-covered): `{ app, root, camera }` on PlayCanvas, and
+  `{ renderer, scene, camera }` on Spark. **`handle.backend`**: `'playcanvas'` or `'spark'`.
+- **`handle.getFocus()`** and **`handle.onFocusChange(point, { focusSource })`**, in the splat's
+  own space, on both backends. `handle.rig` gains `blockFocusSource` and `clumpMassFrac`.
+- **`cameraRigFromPose(pose, opts)`** in `./three`. It builds the camera-rig descriptor from a
+  plain `{position, orientation, fov}`, bit-identical to `cameraRigFromCamera`, which is unchanged.
+
+### Changed
+
+- **Focus waterfall: `nearest-clump`** (the behaviour change above). The order is now: caller ›
+  caller convergence › block focus (any source except `cloud-median` / `median-disparity`) ›
+  **nearest-clump** (needs the block's or caller's lens) › `block-cloud-median` ›
+  `median-disparity` › 2 m.
+- **Viewer tuning constants are shared** (`inline3d-splat-shared.js`). SceneViewer reads the same
+  damping, idle, focus-ease, wheel and zoom numbers as before, now from one module the PlayCanvas
+  viewer also reads. The values are unchanged, and a side-by-side trace test pins the two viewers
+  bit-identical.
+
 ## 1.7.1 — 2026-09-20
 
 Touches the **preview tier** (`./model`) only, and fixes exactly one thing: under a bundler, a

package/README.md

@@ -40,6 +40,26 @@ and only the `/three`, `/viewer` and `/splat` subpaths need them. The two viewer
 call (auto-framing on the zero-disparity plane, orbit, idle turntable, mono fallback), but their
 API is not yet covered by the semver promise below.
 
+**A second splat engine (preview).** `addSplat(wall, canvas, src, { engine: 'playcanvas' })`
+renders the same splat window with the [PlayCanvas](https://playcanvas.com/) engine instead of
+Spark — same handle, same rig/focus/camera-block behaviour, same `perf` presets (mapped onto the
+engine's knobs) — and adds `setSource(src, { fadeMs })` (crossfading asset swaps), `feather`, a
+tilt-and-relax orbit and `handle.engine` (the engine objects, for advanced pages). It needs the
+optional peer `playcanvas` (`>=2.22.3 <3`) and reads `.sog`, `.ply` and a Streamed-SOG
+`lod-meta.json`. **Spark stays the default**; a page that never passes `engine` never loads
+`playcanvas`. What differs, and why: [`docs/playcanvas-adapter.md`](docs/playcanvas-adapter.md).
+Bundlers: the engine is a literal `import('playcanvas')`; its sort workers are Blob URLs (CSP
+`worker-src blob:`), and esbuild needs `node:worker_threads` marked external.
+
+**Large scenes stream (preview).** On `engine: 'playcanvas'`, a Streamed SOG streams: pass the URL
+of its `lod-meta.json` (or of its directory), not its bytes. The engine fetches only the chunks
+the view needs and draws at most `perf.splatBudget` of them. That budget is per tile and shared
+by every view of the tile; it defaults to 600k on a Streamed SOG. `handle.stats()` reports what
+is resident. This is for big captured scenes, several million gaussians and up. A photo lift is
+one dense sheet that is fully on screen, so it gains nothing from streaming. How to produce, serve
+and budget one, with measurements:
+[`docs/playcanvas-adapter.md` §Streamed SOG](docs/playcanvas-adapter.md#streamed-sog-p2).
+
 Stability & what's covered by semver (and the deferred N-view / web-components / CSS-native roadmap
 that is intentionally **not** in 1.0): [`docs/sdk-stability.md`](docs/sdk-stability.md).
 
@@ -114,6 +134,8 @@ js/
                       and the placement readback (getSubjectBounds / getPose / depthOffset)
   inline3d-splat.js   experimental: addSplat() — a Gaussian splat window via Spark
                       (`perf` cuts overdraw; a `.sog`'s `camera` block picks the view rig)
+  inline3d-splat-playcanvas.js
+                      preview: the `engine: 'playcanvas'` backend of addSplat(), loaded on demand
   inline3d-model.js   experimental: addModel() — a glTF/GLB window; wires Draco / meshopt / KTX2
                       from what the asset declares (you serve the decoder files — see the guide)
 docs/

package/js/inline3d-splat-perf.js

@@ -253,3 +253,234 @@ export function splatPerfMeshOptions(perf) {
   if (!profile || !profile.lod) return {};
   return { lod: profile.lod === 'quality' ? 'quality' : true };
 }
+
+// ── the same presets on the PlayCanvas engine (`addSplat(…, { engine: 'playcanvas' })`) ──────
+//
+// Same contract as the Spark half above: nothing moves unless asked, and every knob can be
+// switched off. The presets are Spark-shaped (they were measured on Spark), so this maps each
+// knob onto the engine's nearest equivalent rather than inventing engine presets:
+//
+// | Spark knob | engine (2.22.3) | note |
+// |---|---|---|
+// | `alphaRadius` | always on | the engine ALREADY shrinks every quad to its own alpha radius (`clipCorner` in `gsplatCommonVS`: `min(1, sqrt(ln(a / alphaClip)) / 2)` of the √8σ quad — the same cut `patchAlphaRadius` puts into Spark). It cannot be turned off, so `alphaRadius: false` is reported as `'native'`. |
+// | `minAlpha` | `scene.gsplat.alphaClipForward` | engine default is already 1/255 |
+// | `maxStdDev` | chunk override of `gsplatCommonVS` | the engine's quad is a fixed √8σ; the override caps `clipCorner`'s scale at `maxStdDev/√8`, which truncates both the quad AND the gaussian's uv, i.e. Spark's semantics. Only ever SHRINKS (≤ √8σ). |
+// | `minPixelRadius` | `scene.gsplat.minPixelSize` = 2 × radius | the engine compares a quad DIAMETER in px (`max(l1,l2)`) |
+// | `lod`, `lodSplat*`, `maxPixelRadius`, `falloff`, `alphaFloor` | none | Spark-only; ignored with one warning. The engine's splat-count lever is `splatBudget` (below) |
+//
+// Engine-native keys may be passed in an options object as well and win over the mapping:
+// `alphaClipForward`, `minPixelSize`, `splatBudget` (a splat count per tile, all views included —
+// SPLAT_BUDGET_MODEL), `antiAlias` (only for AA-trained assets), and the Streamed-SOG knobs
+// `lodMode`, `lodUpdateDistance`, `lodUpdateAngle`, `lodUnderfillLimit` (PC_LOD_NUMERIC below).
+//
+// `minPixelSize` IS THE ONE DEFAULT CHANGED. The engine drops every splat whose quad is under
+// 2 px by default; Spark keeps them (its `minPixelRadius` default is 0). On a lifted photograph
+// the sub-2px grain is real texture, so every `perf` value except `false` starts from 0 — the
+// Spark-parity baseline — and only a preset or option that states a size moves it. `perf: false`
+// is the kill switch: the engine's own defaults, untouched, 2 px included.
+
+/** The engine's quad half-extent, in σ: `l = 2·sqrt(2λ)` over cornerUV ∈ [-1,1] (gsplatCorner). */
+export const PLAYCANVAS_QUAD_SIGMA = Math.sqrt(8);
+
+/** Knobs that are engine-native and pass straight through to `app.scene.gsplat`. */
+const PC_NATIVE = ['alphaClipForward', 'minPixelSize', 'splatBudget'];
+
+/**
+ * The Streamed-SOG (`lod-meta.json`) knobs, engine-native, passed straight through. Each one is
+ * its own kill switch: UNSET means the engine's default, never a value of ours. Numbers only,
+ * except `lodMode`, which the engine accepts as `'distance'` or `'error'` and silently ignores
+ * otherwise (so it is validated here, loudly).
+ *
+ * | key | engine default (2.22.3) | what it does |
+ * |---|---|---|
+ * | `lodMode` | `'distance'` | how a node's LOD is chosen: camera distance, or the per-chunk error table |
+ * | `lodUpdateDistance` | `1` (world units = the file's own units) | camera travel before LOD is re-evaluated |
+ * | `lodUpdateAngle` | `0` (off) | camera rotation, in degrees, before LOD is re-evaluated |
+ * | `lodUnderfillLimit` | `0` (off) | how many coarser levels may stand in while a finer one streams |
+ *
+ * None of them does anything on a flat `.sog`/`.ply` — there is no octree to choose in.
+ */
+const PC_LOD_NUMERIC = ['lodUpdateDistance', 'lodUpdateAngle', 'lodUnderfillLimit'];
+const PC_LOD_MODES = ['distance', 'error'];
+
+/**
+ * The splat budget a Streamed SOG gets when the caller did not name one: 600k splats **per tile,
+ * all views included** (see SPLAT_BUDGET_MODEL). The engine's own default is 1M.
+ *
+ * Why 600k and not the engine's 1M: the budget is ONE count for every view of a tile, and a 3D
+ * tile draws that set TWICE (two eyes, two passes over the same work buffer). Measured on an M1
+ * Pro with no other GPU client, two views at 3840×1080 (docs/playcanvas-adapter.md §Streamed
+ * SOG): a 5.88M-gaussian captured castle ran 9.6 ms median / 12.9 ms p90 at 600k and
+ * 10.9 / 13.3 at 1M; Trogir (45.7M) 8.3 / 11.1 and 10.3 / 11.9. So on that GPU 1M fits a 60 Hz
+ * stereo frame too. 600k is chosen for HEADROOM, not because 1M failed: it keeps the M1 at ~60 %
+ * of a 16.7 ms frame for the weaker GPUs a 3D display ships with (Windows iGPUs, Android
+ * tablets — not measured yet). Only 600k and 1M were measured, so it is a safe default, not a
+ * tuned optimum. A caller-set `splatBudget` always wins, and `perf: false` leaves the engine's
+ * 1M untouched.
+ *
+ * The budget has a FLOOR the engine cannot go under: a chunk is never drawn coarser than its
+ * coarsest level, so the resident count bottoms out at the sum of every visible chunk's coarsest
+ * level (367k on the castle's 5-level pyramid, above a 300k budget).
+ */
+export const STREAMED_SPLAT_BUDGET = 600000;
+
+/**
+ * THE BUDGET MODEL, pinned (a test holds these values):
+ *
+ * - `scope: 'tile'` — every tile is its own `AppBase`, so its own scene, its own
+ *   `scene.gsplat.splatBudget`, its own gsplat manager. Two tiles on a page = two budgets.
+ * - `views: 'shared'` — the engine keys its gsplat managers by CAMERA (`GSplatDirector.camerasMap`
+ *   → one `GSplatManager` per camera × layer), and this adapter renders every view of a tile
+ *   through ONE camera with N `RenderView`s. So one manager, one LOD pass, one budget, one work
+ *   buffer for all N views — a 600k budget is 600k splats per tile whether the tile is mono or
+ *   two-view. (Measured on the castle at 600k: 1 camera, 1 manager, 588,879 resident in mono
+ *   and 590,331 with two views; docs/playcanvas-adapter.md §Streamed SOG.)
+ * - `fallbackDivides: true` — the N-camera fallback path (`playcanvasViewPath: 'cameras'`) makes
+ *   N managers, each reading the SAME scene budget, which would be N× the budget per tile. The
+ *   adapter divides the budget by N on that path to keep the per-tile contract — subject to the
+ *   per-manager coarsest-level floor above (measured: 2 managers × 300k on the castle resident
+ *   734,764 = 2 × its 367,382 coarsest level).
+ * - LOD distance is measured from the camera NODE, which sits on the first view's eye; every
+ *   view uses the LOD it picked (one pass). The eyes are ~63 mm apart, so the difference is
+ *   below `lodUpdateDistance` by construction.
+ */
+export const SPLAT_BUDGET_MODEL = Object.freeze({
+  scope: 'tile',
+  views: 'shared',
+  fallbackDivides: true,
+  lodCamera: 'first-view',
+});
+
+/**
+ * The scene-level budget one engine manager must be given so that a TILE spends `tileBudget`.
+ * RenderView path: one manager for all views, so the tile budget as is. N-camera fallback: one
+ * manager per view, so the tile budget split N ways (floored, never below 1).
+ */
+export function budgetPerManager(tileBudget, viewPath, views) {
+  if (!(tileBudget > 0)) return tileBudget;
+  if (viewPath !== 'cameras') return tileBudget;
+  const n = Math.max(1, Math.floor(views) || 1);
+  return Math.max(1, Math.floor(tileBudget / n));
+}
+
+/**
+ * The tile's budget for a resolved perf profile on a source of this kind: the caller's
+ * `splatBudget` if set, else STREAMED_SPLAT_BUDGET on a Streamed SOG, else unset (engine default).
+ * `perf: false` resolves to `settings: {}`, which is why it never gets the streamed default.
+ *
+ * @param {{settings:object, applied:object|null}} resolved  playcanvasPerfSettings()'s result.
+ * @param {'flat'|'streamed'|null} kind
+ * @returns {number|undefined}
+ */
+export function tileSplatBudget(resolved, kind) {
+  const s = resolved?.settings || {};
+  if (isNum(s.splatBudget)) return s.splatBudget;
+  if (kind === 'streamed' && resolved?.applied) return STREAMED_SPLAT_BUDGET;
+  return undefined;
+}
+
+/** Spark knobs with no engine equivalent — named once in a warning, then ignored. */
+const PC_UNMAPPED = ['lod', 'lodSplatCount', 'lodSplatScale', 'lodRenderScale', 'maxPixelRadius', 'falloff', 'alphaFloor'];
+
+/**
+ * Resolve `perf` into engine settings. Pure: no engine, no GPU — the adapter applies the result.
+ *
+ * @param {undefined|null|false|true|string|object} perf  the `addSplat` option, as given.
+ * @returns {{settings:object, quadExtent:number|null, applied:object|null, ignored:string[]}}
+ *          `settings` go onto `app.scene.gsplat`; `quadExtent` (a fraction of the √8σ quad, or
+ *          null for untouched) goes into the `gsplatCommonVS` override; `applied` is what the
+ *          handle reports (null for `perf: false`).
+ */
+export function playcanvasPerfSettings(perf) {
+  const out = { settings: {}, quadExtent: null, applied: null, ignored: [] };
+  if (perf === false) return out; // kill switch: engine defaults, untouched
+
+  let profile = null;
+  let name = null;
+  if (perf === undefined || perf === null) name = 'default';
+  else if (perf === true) {
+    profile = SPLAT_PERF_PRESETS.balanced;
+    name = 'balanced';
+  } else if (typeof perf === 'string') {
+    profile = SPLAT_PERF_PRESETS[perf] || null;
+    name = profile ? perf : 'default';
+    if (!profile) {
+      console.warn(
+        `[inline3d/splat] unknown perf preset "${perf}" — ignored. ` +
+          `Known: ${Object.keys(SPLAT_PERF_PRESETS).join(', ')}, or an options object.`,
+      );
+    }
+  } else if (typeof perf === 'object') {
+    profile = perf;
+    name = 'custom';
+  }
+
+  const s = out.settings;
+  const applied = { preset: name };
+  // The Spark-parity baseline. See the block comment above.
+  s.minPixelSize = 0;
+  if (profile) {
+    if (isNum(profile.minAlpha)) s.alphaClipForward = profile.minAlpha;
+    if (isNum(profile.minPixelRadius)) s.minPixelSize = 2 * Math.max(0, profile.minPixelRadius);
+    if (isNum(profile.maxStdDev) && profile.maxStdDev > 0) {
+      const k = Math.min(1, profile.maxStdDev / PLAYCANVAS_QUAD_SIGMA);
+      if (k < 1) out.quadExtent = k;
+    }
+    if (profile.alphaRadius !== undefined) applied.alphaRadius = 'native';
+    for (const key of PC_NATIVE) if (isNum(profile[key])) s[key] = profile[key];
+    for (const key of PC_LOD_NUMERIC) if (isNum(profile[key]) && profile[key] >= 0) s[key] = profile[key];
+    if (profile.lodMode !== undefined) {
+      if (PC_LOD_MODES.includes(profile.lodMode)) s.lodMode = profile.lodMode;
+      else {
+        console.warn(
+          `[inline3d/splat] perf.lodMode "${profile.lodMode}" is not one of ${PC_LOD_MODES.join(', ')} — ` +
+            "ignored (the engine's default, 'distance', stays).",
+        );
+      }
+    }
+    if (typeof profile.antiAlias === 'boolean') s.antiAlias = profile.antiAlias;
+    for (const key of PC_UNMAPPED) if (profile[key] !== undefined) out.ignored.push(key);
+    if (out.ignored.length) {
+      console.warn(
+        `[inline3d/splat] perf: ${out.ignored.join(', ')} ${out.ignored.length > 1 ? 'have' : 'has'} ` +
+          'no PlayCanvas equivalent and ' +
+          `${out.ignored.length > 1 ? 'are' : 'is'} ignored on engine:'playcanvas' — the engine's ` +
+          'splat-count lever is `splatBudget` (see js/inline3d-splat-perf.js).',
+      );
+    }
+  }
+  Object.assign(applied, s);
+  if (out.quadExtent !== null) applied.maxStdDev = out.quadExtent * PLAYCANVAS_QUAD_SIGMA;
+  out.applied = applied;
+  return out;
+}
+
+const isNum = (v) => typeof v === 'number' && Number.isFinite(v);
+
+// The anchor the quad-extent override rewrites, from the engine's `gsplatCommonVS` (2.22.3). The
+// npm build re-indents chunks with tabs and a later release may re-space them, so it is a
+// whitespace-agnostic regex, not a string.
+const PC_CLIP_ANCHOR = /float\s+clip\s*=\s*min\(\s*1\.0\s*,/;
+
+/**
+ * Cap the engine's per-splat quad at `k` of its √8σ extent — Spark's `maxStdDev`, on PlayCanvas.
+ *
+ * Rewrites `clipCorner`'s `min(1.0, …)` to `min(k, …)`, which scales the corner offset AND the uv
+ * the fragment shader evaluates the gaussian at, so the tail is truncated rather than the
+ * profile squashed. Returns the source unchanged (and `ok:false`) when the anchor is missing;
+ * the caller warns once and renders at the engine's own extent.
+ *
+ * @param {string} src  the current `gsplatCommonVS` chunk.
+ * @param {number} k  in (0, 1).
+ * @returns {{src:string, ok:boolean}}
+ */
+export function patchPlayCanvasQuadExtent(src, k) {
+  if (typeof src !== 'string' || !(k > 0 && k < 1)) return { src, ok: false };
+  if (src.includes('dxrQuadExtent')) return { src, ok: true }; // idempotent
+  if (!PC_CLIP_ANCHOR.test(src)) return { src, ok: false };
+  const lit = k.toFixed(7);
+  return {
+    src: src.replace(PC_CLIP_ANCHOR, `float clip = min(${lit} /* dxrQuadExtent */,`),
+    ok: true,
+  };
+}