@displayxr/inline3d 1.11.0 → 1.12.1

package/model.d.ts

@@ -1,13 +1,25 @@
-// Type definitions for @displayxr/inline3d/model.
+// Type definitions for @displayxr/inline3d/model (and ./model/three).
 // EXPERIMENTAL — not covered by the 1.x semver promise. See docs/sdk-stability.md.
 
 import type { SceneViewer, SubjectBounds, OrbitPose } from './viewer.js';
 import type { FirstWovenResult } from './index.js';
+import type { PlayCanvasSplatViewer, SplatCameraPose, SplatFrameInfo } from './splat.js';
 
 export interface ModelOptions {
+  /**
+   * Which engine renders the model (1.12). `'playcanvas'` is the DEFAULT (optional peer
+   * `playcanvas >=2.22.3 <3`); `'three'` is the 1.11 renderer, byte for byte (optional peer
+   * `three`). Both are imported dynamically, so a page loads only the engine it renders with.
+   *
+   * With no `engine`: a three.js object in `GLTFLoader` / `DRACOLoader` / `KTX2Loader` / `envMap`
+   * selects three; otherwise PlayCanvas, falling back to three (one console warning) when
+   * `playcanvas` cannot be imported, and rejecting `ready` naming both when neither can. An
+   * explicit `engine` never falls back. Anything else throws at call time.
+   */
+  engine?: 'playcanvas' | 'three';
   /** Metres of world the tile's height spans (default 0.24). */
   virtualDisplayHeight?: number;
-  /** Precomputed subject bounds. Rarely needed for a mesh — Box3 is exact. */
+  /** Precomputed subject bounds. Rarely needed for a mesh — its bounds are exact. */
   frame?: SubjectBounds;
   /** Degrees/second of turntable once idle (default 8). */
   idleSpin?: number;
@@ -25,26 +37,42 @@ export interface ModelOptions {
   /** Per-eye buffer scale; 0.5–0.7 is usually free (default 1). */
   renderScale?: number;
   feather?: number;
-  /** Built-in three-point lighting. Meshes arrive unlit; splats do not need this. */
   /**
-   * How the mesh is lit. `room` (default) bakes IBL from three's procedural RoomEnvironment —
-   * metal and glass need it, because a punctual rig leaves a `metalness: 1` surface with nothing
-   * to reflect and it renders black. `studio` is the older three-point punctual rig.
+   * How the mesh is lit.
+   *
+   * PlayCanvas (default engine): `room` (default; `neutral` is an alias) is image-based lighting
+   * from an in-memory neutral photo studio fitted to the Khronos glTF Sample Viewer's "Studio
+   * Neutral", with Khronos PBR Neutral tone mapping and exposure 1 — the Sample Viewer's look.
+   * three: `room` bakes three's procedural RoomEnvironment, untonemapped (unchanged since 1.11).
+   *
+   * Both: `studio` is the three-point punctual rig (metal renders dark under it — nothing to
+   * reflect); `none` adds no light at all. Anything else throws on PlayCanvas.
    */
-  environment?: 'room' | 'studio' | 'none';
-  /** A PMREM-processed environment texture. Better than `environment` for metal; overrides it. */
-  envMap?: object;
-  /** Hand in the GLTFLoader class instead of resolving it from `three/addons/`. */
+  environment?: 'room' | 'neutral' | 'studio' | 'none';
+  /**
+   * PlayCanvas only: yaw of the environment about +Y, degrees (default 0 = the Sample Viewer's
+   * default orientation).
+   */
+  environmentRotation?: number;
+  /**
+   * Your own environment; overrides `environment`.
+   * three: a PMREM-processed texture. PlayCanvas: a URL of an equirect image (.hdr/.png/.jpg) or
+   * a `pc.Texture` (equirect or cubemap), prefiltered for you. A three texture on
+   * `engine: 'playcanvas'` throws; with no `engine` it selects three.
+   */
+  envMap?: object | string;
+  /** three only: hand in the GLTFLoader class instead of resolving it from `three/addons/`. */
   GLTFLoader?: unknown;
 
   /**
-   * Where **your page** serves three's Draco decoder and Basis (KTX2) transcoder.
+   * Where **your page** serves the Draco decoder and Basis (KTX2) transcoder — the SAME files on
+   * both engines: three's `libs/draco/` (`draco_wasm_wrapper.js` + `draco_decoder.wasm`) and
+   * `libs/basis/` (`basis_transcoder.js` + `.wasm`). The PlayCanvas engine's own Draco and Basis
+   * workers load them.
    *
-   * `addModel` reads the asset's `extensionsUsed` before parsing and attaches only the decoders it
-   * declares, so an uncompressed model never touches any of this. But a decoder that IS needed has
-   * to come from somewhere, and the default is deliberately **not a CDN** — a page shipping an
-   * offline build must not acquire a network dependency by loading a compressed file. Copy the
-   * files out of `three` and serve them yourself:
+   * The asset's `extensionsUsed` decides which decoders are wired, so an uncompressed model never
+   * touches any of this. The default is deliberately **not a CDN** — a page shipping an offline
+   * build must not acquire a network dependency by loading a compressed file:
    *
    * ```sh
    * cp -r node_modules/three/examples/jsm/libs/draco/ public/draco/
@@ -52,25 +80,48 @@ export interface ModelOptions {
    * ```
    *
    * A string is a parent directory holding `draco/` and `basis/`; an object overrides either key.
-   * `EXT_meshopt_compression` needs nothing served — its decoder is pure JS.
+   * On PlayCanvas the engine keeps ONE Draco and ONE Basis worker pool per page: the first tile
+   * that needs one sets its path, and a later tile asking for another path is warned.
    *
    * @default {draco:'/draco/', basis:'/basis/'}
    */
   decoderPath?: string | { draco?: string; basis?: string };
-  /**
-   * DRACOLoader class **or** a ready instance, instead of resolving `three/addons/`. A class is
-   * constructed and pointed at `decoderPath`; an instance is used exactly as you configured it.
-   */
+  /** three only: DRACOLoader class **or** a ready instance, instead of resolving `three/addons/`. */
   DRACOLoader?: unknown;
+  /** three only: KTX2Loader class or instance. */
+  KTX2Loader?: unknown;
   /**
-   * KTX2Loader class or instance. `detectSupport()` is called for you with this tile's renderer,
-   * and the transcoder is loaded eagerly so a mis-served path throws instead of silently
-   * resolving a model with no textures.
+   * The `MeshoptDecoder` for `EXT_meshopt_compression`. Nothing to serve (pure JS). Default: three
+   * resolves `three/addons/libs/meshopt_decoder.module.js`; PlayCanvas resolves
+   * `meshoptimizer/decoder` (optional peer `meshoptimizer >=1`), only for an asset that declares it.
    */
-  KTX2Loader?: unknown;
-  /** The `MeshoptDecoder` namespace, instead of resolving `three/addons/`. Nothing to serve. */
   meshoptDecoder?: unknown;
 
+  /** PlayCanvas only: the `playcanvas` module (or a namespace with the same members) to use. */
+  playcanvas?: object;
+  /** PlayCanvas only: MSAA on the tile's WebGL context (default true, as three's renderer). */
+  antialias?: boolean;
+  /** PlayCanvas only: the context's `preserveDrawingBuffer` (default false). */
+  preserveDrawingBuffer?: boolean;
+  /** PlayCanvas only: raise every projection's near plane to at least this (depth mapping only). */
+  nearClip?: number;
+  /** PlayCanvas only: lower every projection's far plane to at most this. */
+  farClip?: number;
+  /** PlayCanvas only: the drag's tilt cap in degrees (default 15, tilt-and-relax). */
+  orbitMaxDeg?: number;
+  /** PlayCanvas only: the orbit's easing time constants, seconds. */
+  orbitEase?: { drag?: number; rest?: number };
+  /**
+   * PlayCanvas only: who owns the camera — the SDK's viewer (default) or the page, through
+   * {@link ModelHandle.setCameraPose} every frame (the attach rig; converges on the model's bounds
+   * centre unless the pose gives a `convergence`).
+   */
+  controls?: 'viewer' | 'page';
+  /** `controls: 'page'`: the comfort depth of the declared rig, in (0, 1] (default 0.3). */
+  comfortDepth?: number;
+  /** `controls: 'page'` only: runs inside the adapter's frame, before the draw. */
+  onBeforeFrame?: (frame: SplatFrameInfo) => void;
+
   /** Element whose visibility gates the lazy create/close lifecycle. */
   observe?: Element;
   /** Forwarded to the core window: see `TileOptions.firstWovenHoldMs`. */
@@ -79,16 +130,43 @@ export interface ModelOptions {
 
 /** What {@link addModel} returns — the same shape as addSplat's handle. */
 export interface ModelHandle {
-  readonly viewer: SceneViewer;
-  /** The loaded glTF scene root; null until `ready` resolves. */
+  /** Which engine renders this tile. Can change from `'playcanvas'` to `'three'` on the fallback. */
+  readonly backend: 'playcanvas' | 'three';
+  /**
+   * three: the SceneViewer. PlayCanvas: the backend's viewer (the SceneViewer pose surface
+   * without three). Null until the backend module has loaded — one module fetch after addModel
+   * returns (1.11 returned it synchronously; `@displayxr/inline3d/model/three` still does).
+   */
+  readonly viewer: SceneViewer | PlayCanvasSplatViewer | null;
+  /**
+   * The loaded glTF root — a three `Object3D`, or on PlayCanvas the render `pc.Entity`
+   * (`instantiateRenderEntity()`). Null until `ready` resolves.
+   */
   model: object | null;
+  /** PlayCanvas only: the container resource (animations, materials, textures). */
+  readonly container?: unknown;
+  /**
+   * PlayCanvas only (ADVANCED, not covered by the semver promise): `app` is the tile's AppBase,
+   * `root` the content root (the model's parent — add entities, lights or an `anim` component
+   * under it), `camera` the eye camera. Null on three and until the engine has booted.
+   */
+  readonly engine: { readonly app: unknown; readonly root: unknown; readonly camera: unknown } | null;
   /** Bounds used for framing; null until `ready` resolves. */
   frame: SubjectBounds | null;
   /** Resolves once the model has loaded and been framed; rejects if the load failed. */
   readonly ready: Promise<ModelHandle>;
 
+  /** Throws on `controls: 'page'`. */
   setPose(pose?: OrbitPose): void;
+  /** Throws on `controls: 'page'`. */
   resetPose(): void;
+  /** `controls: 'page'` only (throws otherwise): the camera for the next frame, model space. */
+  setCameraPose(
+    matrixWorld: ArrayLike<number>,
+    opts: { verticalFovDeg: number; near?: number; far?: number; convergence?: number | null },
+  ): ModelHandle;
+  /** The last pose the page set (a copy), or null. */
+  getCameraPose(): SplatCameraPose | null;
 
   remove(): void;
   exclude(el: Element): void;
@@ -102,10 +180,11 @@ export interface ModelHandle {
 
 /**
  * Load a glTF/GLB into an inline-3D window. Safe to call with an unsupported wall — it renders a
- * flat, orbitable view instead, so pages need no branch.
+ * flat, orbitable view instead, so pages need no branch. Renders with PlayCanvas by default
+ * (1.12); pass `engine: 'three'` for the 1.11 renderer.
  *
  * Compressed assets (Draco, meshopt, KTX2/Basis) load too: the asset's declared extensions decide
- * which decoders are imported, and nothing is imported for an asset that declares none. Draco and
+ * which decoders are wired, and nothing is wired for an asset that declares none. Draco and
  * KTX2 additionally need their runtime files served by your page — see {@link ModelOptions.decoderPath}.
  * When a decoder is needed and unavailable, `ready` rejects with an Error naming the glTF
  * extension, the option that fixes it and the path it looked in; the extension is also on the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@displayxr/inline3d",
-  "version": "1.11.0",
+  "version": "1.12.1",
   "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",
@@ -24,6 +24,10 @@
       "import": "./js/inline3d-splat.js"
     },
     "./model": {
+      "types": "./model.d.ts",
+      "import": "./js/inline3d-model-entry.js"
+    },
+    "./model/three": {
       "types": "./model.d.ts",
       "import": "./js/inline3d-model.js"
     },
@@ -47,6 +51,9 @@
     "js/inline3d-splat-playcanvas.js",
     "js/inline3d-splat-shared.js",
     "js/inline3d-model.js",
+    "js/inline3d-model-entry.js",
+    "js/inline3d-model-playcanvas.js",
+    "js/inline3d-playcanvas-engine.js",
     "index.d.ts",
     "three.d.ts",
     "viewer.d.ts",
@@ -64,7 +71,8 @@
     "stereo",
     "3d-display",
     "lightfield",
-    "three"
+    "three",
+    "playcanvas"
   ],
   "homepage": "https://displayxr.github.io/displayxr-web/",
   "repository": {
@@ -78,7 +86,8 @@
   "peerDependencies": {
     "three": ">=0.150.0",
     "@sparkjsdev/spark": ">=2.0.0",
-    "playcanvas": ">=2.22.3 <3"
+    "playcanvas": ">=2.22.3 <3",
+    "meshoptimizer": ">=1.0.0"
   },
   "peerDependenciesMeta": {
     "three": {
@@ -89,6 +98,9 @@
     },
     "playcanvas": {
       "optional": true
+    },
+    "meshoptimizer": {
+      "optional": true
     }
   },
   "publishConfig": {

package/splat.d.ts

@@ -466,7 +466,9 @@ 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).