@displayxr/inline3d 1.11.0 → 1.12.0

package/js/inline3d-playcanvas-engine.js

@@ -0,0 +1,77 @@
+// inline3d-playcanvas-engine.js — the slice of `playcanvas` the SDK's two PlayCanvas backends use,
+// as NAMED re-exports.
+//
+// Internal. ./model and ./splat import THIS module (dynamically) instead of `import('playcanvas')`.
+// A dynamic import of the package hands back its whole namespace, and a bundler cannot know which
+// members a namespace object will be asked for — so it keeps all of them: the full engine
+// (physics, UI, audio, particles, XR, the WebGPU backend …) lands in the page's bundle. Naming
+// the members here is what lets a bundler drop everything else. The page's own `import … from
+// 'playcanvas'` still resolves to the SAME module instance, so entities a page adds under
+// `handle.engine.root` are the engine's own types.
+//
+// Adding an engine member to either adapter? Add it here too; test/playcanvas-engine.test.mjs
+// fails on a `pc.X` the adapters read that this list does not export.
+export {
+  // app + device
+  AppBase,
+  AppOptions,
+  createGraphicsDevice,
+  DEVICETYPE_WEBGL2,
+  RESOLUTION_FIXED,
+  // component systems + resource handlers (PLAYCANVAS_SYSTEMS / PLAYCANVAS_HANDLERS)
+  CameraComponentSystem,
+  GSplatComponentSystem,
+  RenderComponentSystem,
+  LightComponentSystem,
+  AnimComponentSystem,
+  TextureHandler,
+  GSplatHandler,
+  ContainerHandler,
+  // scene graph + cameras
+  Entity,
+  GraphNode,
+  Camera,
+  RenderView,
+  Asset,
+  Color,
+  Vec4,
+  Quat,
+  LAYERID_SKYBOX,
+  LAYERID_UI,
+  // materials / meshes (the edge feather)
+  Mesh,
+  MeshInstance,
+  ShaderMaterial,
+  BlendState,
+  BLENDEQUATION_ADD,
+  BLENDMODE_SRC_ALPHA,
+  BLENDMODE_ZERO,
+  CULLFACE_NONE,
+  SEMANTIC_POSITION,
+  SEMANTIC_TEXCOORD0,
+  ShaderChunks,
+  SHADERLANGUAGE_GLSL,
+  // splats
+  WORKBUFFER_UPDATE_ALWAYS,
+  WORKBUFFER_UPDATE_ONCE,
+  // tone mapping (TONE_MAPPINGS)
+  TONEMAP_NONE,
+  TONEMAP_LINEAR,
+  TONEMAP_NEUTRAL,
+  TONEMAP_ACES,
+  TONEMAP_ACES2,
+  TONEMAP_FILMIC,
+  TONEMAP_HEJL,
+  // lighting (./model)
+  Texture,
+  EnvLighting,
+  PIXELFORMAT_RGBA8,
+  TEXTURETYPE_RGBE,
+  TEXTUREPROJECTION_EQUIRECT,
+  ADDRESS_REPEAT,
+  ADDRESS_CLAMP_TO_EDGE,
+  // compressed glTF (./model)
+  dracoInitialize,
+  basisInitialize,
+  version,
+} from 'playcanvas';

package/js/inline3d-splat-playcanvas.js

@@ -145,6 +145,17 @@ const PAGE_POSE_ERROR =
 
 const DEG = Math.PI / 180;
 
+/** Tone-mapping names the viewer takes → the engine's constant names. */
+export const TONE_MAPPINGS = Object.freeze({
+  none: 'TONEMAP_NONE',
+  linear: 'TONEMAP_LINEAR',
+  neutral: 'TONEMAP_NEUTRAL',
+  aces: 'TONEMAP_ACES',
+  aces2: 'TONEMAP_ACES2',
+  filmic: 'TONEMAP_FILMIC',
+  hejl: 'TONEMAP_HEJL',
+});
+
 // ── pure matrix arithmetic (column-major, the layout XRView, three and the engine all use) ──
 
 /** three's `Matrix4.makePerspective(left, right, top, bottom, near, far)`, element for element. */
@@ -606,6 +617,7 @@ export class PlayCanvasSplatViewer {
       farClip,
       sky = false,
       pageCamera = false,
+      toneMapping = 'none',
     } = opts;
     this.canvas = canvas;
     // controls:'page': the PAGE owns the camera (setPageCamera). No orbit, no idle, no fit; the
@@ -620,6 +632,10 @@ export class PlayCanvasSplatViewer {
     // hidden (mid-setSource, or a page showing only its meshes). The SDK's contract is a
     // transparent canvas the page shows through, so the sky layer is off unless asked for.
     this.sky = sky === true;
+    // The eye camera's tone mapping, by name (the engine constant is looked up once the engine has
+    // loaded). 'none' for splats — their colours are already display-referred; ./model's mesh
+    // tiles pass 'neutral' (Khronos PBR Neutral), the glTF Sample Viewer's default.
+    this.toneMapping = toneMapping;
     // Depth range for a MIXED scene (meshes under handle.engine.root depth-test against each
     // other; splats only test against them). The projections' own near/far stay the adapter's —
     // these only raise the near (floor) and lower the far (cap). Unset: untouched.
@@ -972,13 +988,15 @@ export class PlayCanvasSplatViewer {
    * @param {object} o.perf  the resolved playcanvasPerfSettings().
    * @param {string} [o.viewPath]  force 'cameras' | 'renderview' (diagnostics).
    */
-  async attachEngine(pc, { preserveDrawingBuffer = false, perf, viewPath } = {}) {
+  async attachEngine(pc, { preserveDrawingBuffer = false, perf, viewPath, antialias = false, patchSplats = true } = {}) {
     this.pc = pc;
     const device = await pc.createGraphicsDevice(this.canvas, {
       deviceTypes: [pc.DEVICETYPE_WEBGL2],
       alpha: true,
       premultipliedAlpha: true,
-      antialias: false,
+      // Off for splats (alpha-blended quads gain nothing from MSAA); ./model turns it on, as
+      // three's SceneViewer has it, because mesh silhouettes alias visibly without it.
+      antialias,
       xrCompatible: false,
       preserveDrawingBuffer,
     });
@@ -1022,10 +1040,12 @@ export class PlayCanvasSplatViewer {
     // Footprint fix (§ patchGsplatFootprint) and the perf quad-extent cap, both as chunk
     // overrides. The gsplat chunks are registered by GSplatComponentSystem during init, so
     // after it; before any gsplat material compiles.
-    const chunks = pc.ShaderChunks.get(device, pc.SHADERLANGUAGE_GLSL);
-    const corner = patchGsplatFootprint(chunks.get('gsplatCornerVS'));
+    // ./model passes patchSplats:false: its subject is a mesh, and a page adding a splat under
+    // handle.engine.root on a model tile gets the engine's stock footprint (documented).
+    const chunks = patchSplats ? pc.ShaderChunks.get(device, pc.SHADERLANGUAGE_GLSL) : null;
+    const corner = chunks ? patchGsplatFootprint(chunks.get('gsplatCornerVS')) : { ok: false, skipped: true };
     if (corner.ok) chunks.set('gsplatCornerVS', corner.src);
-    else if (!warnedFootprint) {
+    else if (!corner.skipped && !warnedFootprint) {
       warnedFootprint = true;
       console.warn(
         '[inline3d/splat] engine:playcanvas — this engine build does not have the gsplatCornerVS ' +
@@ -1035,7 +1055,7 @@ export class PlayCanvasSplatViewer {
       );
     }
     this.footprintPatched = corner.ok;
-    if (perf?.quadExtent) {
+    if (chunks && perf?.quadExtent) {
       const q = patchPlayCanvasQuadExtent(chunks.get('gsplatCommonVS'), perf.quadExtent);
       if (q.ok) chunks.set('gsplatCommonVS', q.src);
       else if (!warnedQuadExtent) {
@@ -1184,7 +1204,7 @@ export class PlayCanvasSplatViewer {
     // The engine's default camera tonemap is LINEAR, which routes every splat colour through
     // decodeGamma → toneMap → gammaCorrectOutput. Spark writes the stored colour straight out;
     // NONE is the same thing here (GAMMA_SRGB alone leaves a gamma-space colour untouched).
-    e.camera.toneMapping = pc.TONEMAP_NONE;
+    e.camera.toneMapping = TONE_MAPPINGS[this.toneMapping] ? pc[TONE_MAPPINGS[this.toneMapping]] ?? pc.TONEMAP_NONE : pc.TONEMAP_NONE;
     this.rigNode.addChild(e);
     return e;
   }
@@ -2415,7 +2435,9 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
 
   let pcModule = null;
   const booted = (async () => {
-    const pc = opts.playcanvas || (await import('playcanvas'));
+    // Named re-exports, not the package namespace: lets a bundler drop the ~40% of the engine the
+    // SDK never touches (./inline3d-playcanvas-engine.js).
+    const pc = opts.playcanvas || (await import('./inline3d-playcanvas-engine.js'));
     if (removed) return null;
     const app = await viewer.attachEngine(pc, {
       preserveDrawingBuffer,

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.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",
@@ -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": {