@displayxr/inline3d 1.16.0 → 1.17.0

package/CHANGELOG.md

@@ -5,6 +5,43 @@ 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.17.0 — 2026-09-24
+
+Touches the **preview tier** (`./model` and `./splat`, `engine: 'playcanvas'` only). The default look
+does not move except on glTFs that use `KHR_materials_transmission`.
+
+### Changed
+
+- **`environment: 'room'` is now three's room on the PlayCanvas backend** (#36). `addModel(…, {
+  environment: 'room' })` and `setRig('display', { environment: 'room' })` light with three.js's
+  procedural RoomEnvironment, regenerated in memory (ray cast, no asset, ~16 ms once per page), and
+  default to tone mapping `'none'`, three's. Through 1.16 `'room'` was an alias of `'neutral'` on
+  this engine, so a page that passed it to keep its three look got the Sample-Viewer studio with PBR
+  Neutral. **The default is now spelled `'neutral'` and renders exactly as before** (Khronos gate
+  re-run: 16.7 / 6.4 / 2.7 / 9.4, unchanged). On a four-item product catalogue, object MAE against three r180
+  `room` goes from 20.5 / 54.4 / 29.5 / 23.3 (the default) to **10.2 / 11.0 / 7.1 / 6.3** (storm
+  lantern / handbag / boot / compass). Tone mapping and the environment explain the gap, and what is
+  left is where three departs from the Sample Viewer (PlayCanvas `room` is closer to the Sample
+  Viewer lit by the same room than three is: handbag 4.8 vs 13.4). `setRig('display')` with
+  `'room'` renders pixel-identical to `addModel` with it. See
+  [`docs/playcanvas-model-backend.md` § Environments](docs/playcanvas-model-backend.md#environments--neutral-default-and-room-three).
+- `setRig('display')`'s `toneMapping` now defaults to the environment's (`'none'` for `'room'`,
+  `'neutral'` otherwise). A second `setRig('display')` with another environment swaps the IBL it
+  installed.
+
+### Fixed
+
+- **`KHR_materials_transmission` / `_volume` on PlayCanvas** (#36), for `addModel` and for meshes
+  under root on `setRig('display')`:
+  - The scene-colour grab pass the material samples is now requested. Without it the storm lantern's
+    burner rendered as a magenta blob inside the globe.
+  - Transmissive draws sort ahead of blended ones, the pass order of the Sample Viewer and three.
+    The lantern's opaque-alpha globe no longer shows the burner through it.
+  - The grab UV is taken per view. The engine mapped each view's NDC over the whole target, so in
+    stereo each eye sampled across both. Mono renders are identical.
+  - Lantern object MAE vs the Sample Viewer (default look): 14.4 → 12.4.
+  - See [§ Transmission](docs/playcanvas-model-backend.md#transmission-khr_materials_transmission--_volume).
+
 ## 1.16.0 — 2026-09-24
 
 Touches the **preview tier** (`./splat`, `engine: 'playcanvas'` only). Additive. A page that never

package/README.md

@@ -69,7 +69,8 @@ Splat and model rendering on the PlayCanvas backend uses the PlayCanvas engine (
 **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,
-exposure 1. `engine: 'three'` is the 1.11 three.js renderer, unchanged (also importable as
+exposure 1. `environment: 'room'` gives three's RoomEnvironment look instead (a page tuned on the
+three path). `engine: 'three'` is the 1.11 three.js renderer, unchanged (also importable as
 `@displayxr/inline3d/model/three`). Each engine is imported only when a tile asks for it. Draco
 and KTX2 use the same served decoder folders on both engines. Design, the Sample-Viewer MAE table
 and what throws: [`docs/playcanvas-model-backend.md`](docs/playcanvas-model-backend.md).

package/THIRD_PARTY_NOTICES.md

@@ -6,7 +6,7 @@ it are adapted from, or run on, the MIT-licensed projects below. Their notices f
 | 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'`. |
+| [three.js](https://github.com/mrdoob/three.js) | ≥ 0.150 | Optional peer (`three`): the `./three` helpers, the Spark splat path, `./model`'s `engine: 'three'`. The PlayCanvas backend's `environment: 'room'` is **adapted** from `examples/jsm/environments/RoomEnvironment.js` (its scene numbers, re-rendered by ray casting in `js/inline3d-model-playcanvas.js`, `ROOM_ENVIRONMENT`). |
 | [Spark](https://github.com/sparkjsdev/spark) | ≥ 2.0 | Optional peer (`@sparkjsdev/spark`): the Spark splat backend. |
 
 ## PlayCanvas engine — MIT

package/js/inline3d-model-playcanvas.js

@@ -24,6 +24,8 @@
 //     and was fitted to the Sample Viewer's "Studio Neutral". three's path keeps RoomEnvironment
 //     and no tone mapping (unchanged since 1.11); the two backends therefore do not look
 //     identical, by design — docs/playcanvas-model-backend.md §Lighting has the MAE table.
+//     `environment: 'room'` is three's room on this engine (§ the room environment), untonemapped,
+//     for a page tuned on the three path (§Environments).
 //   · Decoders are the ENGINE's: Draco and Basis through the engine's own worker readers (fed the
 //     SAME files three's `libs/draco/` and `libs/basis/` folders hold), meshopt through the
 //     container's bufferView hook with meshoptimizer's `MeshoptDecoder` (the engine has no
@@ -347,10 +349,13 @@ export const ENV_YAW_DEG = 0;
 
 /** Build the default environment on this app and set it as the scene's envAtlas. */
 export function useNeutralStudio(pc, app, yawDeg) {
-  const W = 256;
-  const H = 128;
+  return useRgbeEquirect(pc, app, 'inline3d-neutral-studio', neutralStudioRGBE(256, 128), 256, 128, yawDeg);
+}
+
+/** A grey RGBE equirect (row 0 = up) → prefiltered envAtlas on the scene. */
+function useRgbeEquirect(pc, app, name, bytes, W, H, yawDeg) {
   const tex = new pc.Texture(app.graphicsDevice, {
-    name: 'inline3d-neutral-studio',
+    name,
     width: W,
     height: H,
     format: pc.PIXELFORMAT_RGBA8,
@@ -359,7 +364,7 @@ export function useNeutralStudio(pc, app, yawDeg) {
     mipmaps: false,
     addressU: pc.ADDRESS_REPEAT,
     addressV: pc.ADDRESS_CLAMP_TO_EDGE,
-    levels: [neutralStudioRGBE(W, H)],
+    levels: [bytes],
   });
   return useLightingSource(pc, app, tex, true, yawDeg);
 }
@@ -373,7 +378,9 @@ function useLightingSource(pc, app, source, own, yawDeg = 0) {
   app.scene.envAtlas = atlas;
   app.scene.skyboxIntensity = 1;
   app.scene.exposure = 1;
-  if (pc.Quat && yawDeg) app.scene.skyboxRotation = new pc.Quat().setFromEulerAngles(0, yawDeg, 0);
+  // Always written (identity at 0): a later environment on the same scene must not inherit the
+  // previous one's yaw (setRig switches room ↔ neutral on one app).
+  if (pc.Quat) app.scene.skyboxRotation = new pc.Quat().setFromEulerAngles(0, yawDeg || 0, 0);
   return atlas;
 }
 
@@ -388,6 +395,244 @@ function loadTexture(pc, app, url) {
   });
 }
 
+// ── the room environment (environment: 'room') ─────────────────────────────────────────────
+
+/**
+ * `environment: 'room'` — three.js's procedural RoomEnvironment, regenerated here without three:
+ * the same scene (a white room lit by one point light, six grey boxes, six emissive panels), shaded
+ * the way three shades it when `PMREMGenerator.fromScene(new RoomEnvironment(), 0.04)` bakes it —
+ * which is exactly what `addModel(…, { engine: 'three', environment: 'room' })` lights with.
+ *
+ * It exists so a page that chose `'room'` on the three path gets that look on this backend. It is
+ * NOT the default: the default (`'neutral'`) is matched to the Khronos Sample Viewer, and three's
+ * room is a different, brighter room (mean radiance ~0.97 vs ~0.89, most of it from a 100-nit
+ * ceiling panel and two 50-nit wall panels).
+ *
+ * The scene's numbers (positions, rotations, scales, intensities) are three.js's
+ * examples/jsm/environments/RoomEnvironment.js (MIT, © three.js authors), itself after
+ * model-viewer's EnvironmentScene. No image is shipped: `roomRadiance` ray-casts the boxes per
+ * texel. Checked against three r180's own bake (its PMREM, read back through `textureCubeUV`):
+ * texel-to-texel ratio median 1.000 (p10 0.989, p90 1.006), solid-angle-weighted MAE 0.03 unblurred
+ * and 0.04 with the 0.04-rad blur. Solids are [cx, cy, cz, angleY, sx, sy, sz] (boxes) and
+ * [cx, cy, cz, sx, sy, sz, emissive] (panels), BoxGeometry(1) scaled — i.e. full extents.
+ */
+export const ROOM_ENVIRONMENT = Object.freeze({
+  light: [0.418, 16.199, 0.3, 900, 28, 2], // point light: position, intensity (cd), cutoff distance, decay
+  room: [-0.757, 13.219, 0.717, 31.713, 28.305, 28.591], // seen from inside
+  boxes: [
+    [-10.906, 2.009, 1.846, -0.195, 2.328, 7.905, 4.651],
+    [-5.607, -0.754, -0.758, 0.994, 1.97, 1.534, 3.955],
+    [6.167, 0.857, 7.803, 0.561, 3.927, 6.285, 3.687],
+    [-2.017, 0.018, 6.124, 0.333, 2.002, 4.566, 2.064],
+    [2.291, -0.756, -2.621, -0.286, 1.546, 1.552, 1.496],
+    [-2.193, -0.369, -5.547, 0.516, 3.875, 3.487, 2.986],
+  ],
+  panels: [
+    [-16.116, 14.37, 8.208, 0.1, 2.428, 2.739, 50],
+    [-16.109, 18.021, -8.207, 0.1, 2.425, 2.751, 50],
+    [14.904, 12.198, -1.832, 0.15, 4.265, 6.331, 17],
+    [-0.462, 8.89, 14.52, 4.38, 5.441, 0.088, 43],
+    [3.235, 11.486, -12.541, 2.5, 2.0, 0.1, 20],
+    [0.0, 20.0, 0.0, 1.0, 0.1, 1.0, 100],
+  ],
+  blur: 0.04, // radians — the sigma addModel's three path passes to fromScene
+});
+
+/** Every solid as [cx, cy, cz, cosY, sinY, hx, hy, hz, kind (0 room, 1 lit box, 2 panel), emissive]. */
+const _roomSolids = new WeakMap();
+function roomSolids(env) {
+  let out = _roomSolids.get(env);
+  if (out) return out;
+  const [rx, ry, rz, sx, sy, sz] = env.room;
+  out = [[rx, ry, rz, 1, 0, sx / 2, sy / 2, sz / 2, 0, 0]];
+  for (const [px, py, pz, a, bx, by, bz] of env.boxes) out.push([px, py, pz, Math.cos(a), Math.sin(a), bx / 2, by / 2, bz / 2, 1, 0]);
+  for (const [px, py, pz, bx, by, bz, e] of env.panels) out.push([px, py, pz, 1, 0, bx / 2, by / 2, bz / 2, 2, e]);
+  _roomSolids.set(env, out);
+  return out;
+}
+
+/**
+ * Radiance of the room seen from the origin toward unit direction (x, y, z): the nearest solid
+ * along the ray. A panel is its emissive value; a wall or box (white, roughness 1, non-metal) is
+ * three's direct physical shading from the one point light, unshadowed as in three (the scene casts
+ * no shadows) — Lambert plus GGX at alpha 1 (D = 1/π, V = 0.5/(NL+NV), Schlick F0 0.04), with
+ * three's inverse-square falloff and its (1 − (d/cutoff)⁴)² window.
+ */
+export function roomRadiance(x, y, z, env = ROOM_ENVIRONMENT) {
+  let best = Infinity;
+  let nx = 0;
+  let ny = 0;
+  let nz = 0;
+  let emit = -1;
+  let found = false;
+  for (const b of roomSolids(env)) {
+    const c = b[3];
+    const s = b[4];
+    // The ray in the solid's frame (a rotation about Y): local = Rᵀ(p − centre).
+    const ox = -b[0];
+    const oy = -b[1];
+    const oz = -b[2];
+    const o = [c * ox - s * oz, oy, s * ox + c * oz];
+    const d = [c * x - s * z, y, s * x + c * z];
+    let t0 = -Infinity;
+    let t1 = Infinity;
+    let a0 = 0;
+    let a1 = 0;
+    let miss = false;
+    for (let i = 0; i < 3; i++) {
+      const h = b[5 + i];
+      if (Math.abs(d[i]) < 1e-12) {
+        if (o[i] < -h || o[i] > h) {
+          miss = true;
+          break;
+        }
+        continue;
+      }
+      let n = (-h - o[i]) / d[i];
+      let f = (h - o[i]) / d[i];
+      let sn = -1; // the entry face's outward normal is −axis when the ray runs +axis
+      if (n > f) {
+        const t = n;
+        n = f;
+        f = t;
+        sn = 1;
+      }
+      if (n > t0) {
+        t0 = n;
+        a0 = (i + 1) * sn;
+      }
+      if (f < t1) {
+        t1 = f;
+        a1 = -(i + 1) * sn;
+      }
+    }
+    if (miss || t0 > t1 || t1 < 0) continue;
+    const inside = b[8] === 0;
+    const t = inside ? t1 : t0;
+    if (!(t > 0) || t >= best) continue;
+    best = t;
+    found = true;
+    if (b[8] === 2) {
+      emit = b[9];
+      continue;
+    }
+    emit = -1;
+    const a = inside ? a1 : a0;
+    const sg = (inside ? -1 : 1) * Math.sign(a); // the room is seen from inside: its normals point in
+    const ax = Math.abs(a) - 1;
+    const l0 = ax === 0 ? sg : 0;
+    const l2 = ax === 2 ? sg : 0;
+    nx = c * l0 + s * l2;
+    ny = ax === 1 ? sg : 0;
+    nz = -s * l0 + c * l2;
+  }
+  if (!found) return 0;
+  if (emit >= 0) return emit;
+  const [lx, ly, lz, I, cutoff, decay] = env.light;
+  let tx = lx - x * best;
+  let ty = ly - y * best;
+  let tz = lz - z * best;
+  const dist = Math.hypot(tx, ty, tz);
+  tx /= dist;
+  ty /= dist;
+  tz /= dist;
+  const nl = nx * tx + ny * ty + nz * tz;
+  if (nl <= 0) return 0;
+  const win = Math.max(0, Math.min(1, 1 - Math.pow(dist / cutoff, 4)));
+  const E = (I / Math.max(Math.pow(dist, decay), 0.01)) * win * win * nl;
+  const nv = Math.max(1e-4, -(nx * x + ny * y + nz * z));
+  const hx = tx - x;
+  const hy = ty - y;
+  const hz = tz - z;
+  const vh = Math.max(0, (tx * hx + ty * hy + tz * hz) / Math.hypot(hx, hy, hz));
+  const F = 0.04 + 0.96 * Math.pow(1 - vh, 5);
+  return (E / Math.PI) * (1 + F * (0.5 / (nl + nv)));
+}
+
+/**
+ * The room as a float equirect (row 0 = up, the same convention as neutralStudioRGBE), blurred by a
+ * Gaussian of `sigma` radians — separable on the sphere: σ in rows, σ/sinθ in columns (wrapping).
+ */
+export function roomEquirect(W = 256, H = 128, sigma = ROOM_ENVIRONMENT.blur, env = ROOM_ENVIRONMENT) {
+  const out = new Float32Array(W * H);
+  for (let r = 0; r < H; r++) {
+    const th = ((r + 0.5) / H) * Math.PI;
+    const st = Math.sin(th);
+    const y = Math.cos(th);
+    for (let c = 0; c < W; c++) {
+      const ph = ((c + 0.5) / W) * 2 * Math.PI;
+      out[r * W + c] = roomRadiance(st * Math.cos(ph), y, st * Math.sin(ph), env);
+    }
+  }
+  if (!(sigma > 0)) return out;
+  const perRow = Math.PI / H; // radians per row, and per column at the equator
+  const tmp = new Float32Array(W * H);
+  for (let r = 0; r < H; r++) {
+    const st = Math.max(Math.sin(((r + 0.5) / H) * Math.PI), 1e-3);
+    const sg = Math.min(sigma / perRow / st, W / 4);
+    const R = Math.ceil(3 * sg);
+    const k = [];
+    let ks = 0;
+    for (let i = -R; i <= R; i++) {
+      const v = Math.exp(-(i * i) / (2 * sg * sg));
+      k.push(v);
+      ks += v;
+    }
+    for (let c = 0; c < W; c++) {
+      let a = 0;
+      for (let i = -R; i <= R; i++) a += k[i + R] * out[r * W + (((c + i) % W) + W) % W];
+      tmp[r * W + c] = a / ks;
+    }
+  }
+  const sg = sigma / perRow;
+  const R = Math.ceil(3 * sg);
+  for (let r = 0; r < H; r++) {
+    for (let c = 0; c < W; c++) {
+      let a = 0;
+      let ks = 0;
+      for (let i = -R; i <= R; i++) {
+        const rr = r + i;
+        if (rr < 0 || rr >= H) continue;
+        const v = Math.exp(-(i * i) / (2 * sg * sg));
+        a += v * tmp[rr * W + c];
+        ks += v;
+      }
+      out[r * W + c] = a / ks;
+    }
+  }
+  return out;
+}
+
+/** The room as RGBE bytes (cached per size: every tile on a page gets the same image). */
+const _roomCache = new Map();
+export function roomRGBE(W = 256, H = 128) {
+  const key = `${W}x${H}`;
+  let bytes = _roomCache.get(key);
+  if (!bytes) {
+    const f = roomEquirect(W, H);
+    bytes = new Uint8Array(W * H * 4);
+    for (let i = 0; i < f.length; i++) rgbe(f[i], bytes, i * 4);
+    _roomCache.set(key, bytes);
+  }
+  return bytes.slice();
+}
+
+/**
+ * Yaw that lines the generated room up with three's world (its +X panel on +X, the ceiling panel
+ * overhead). Calibrated headless against three r180's own `environment: 'room'` render on two
+ * catalogue meshes: a sweep over 0/90/180/270 × mirrored has a clean minimum at 90, unmirrored, on
+ * both. (The neutral studio's 0 is the Sample Viewer's orientation, a different frame.)
+ */
+export const ROOM_YAW_DEG = 90;
+
+/** Build the room environment on this app and set it as the scene's envAtlas. */
+export function useRoomEnvironment(pc, app, yawDeg = ROOM_YAW_DEG) {
+  return useRgbeEquirect(pc, app, 'inline3d-room', roomRGBE(256, 128), 256, 128, yawDeg);
+}
+
+/** Each environment's tone mapping: the look it was matched to. */
+export const ENVIRONMENT_TONE_MAPPING = Object.freeze({ neutral: 'neutral', room: 'none', studio: 'neutral', none: 'neutral' });
+
 /**
  * `environment: 'studio'` — three's three-point rig, same directions and ratios. Engine lights
  * shine along their local −Y, so each is aimed by rotation (never lookAt). three's punctual
@@ -430,6 +675,100 @@ function addStudioLights(pc, app, root) {
   app.scene.ambientLight = new pc.Color(amb, amb, amb);
 }
 
+// ── KHR_materials_transmission / volume on this engine ─────────────────────────────────────
+
+/**
+ * The engine reads KHR_materials_transmission (and _volume) into `useDynamicRefraction` +
+ * `BLEND_NORMAL`, and a dynamic-refraction material samples the camera's SCENE COLOUR MAP. Three
+ * things the engine leaves to the app, all needed for a glass or transmissive glTF to look like
+ * it does in the Khronos Sample Viewer (and three):
+ *
+ *  1. THE GRAB PASS. Nothing renders the scene colour map unless a camera asks for it; without it
+ *     the material samples an unbound texture — the storm lantern's burner rendered as a MAGENTA
+ *     blob inside its globe (measured). `viewer.useSceneColor()` asks, on every eye camera.
+ *  2. PASS ORDER. Both references draw opaque → transmissive → blended. The engine puts a
+ *     transmissive material in the ONE back-to-front transparent list with the blended ones, so a
+ *     blended globe (depthWrite off) can be drawn before the transmissive body behind it, which
+ *     then paints over it — the burner showed THROUGH the lantern's opaque-alpha globe. A sort
+ *     distance that puts transmissive draws first (back-to-front among themselves) restores the
+ *     order: object MAE 10.7 → 10.2 vs three, 11.2 → 10.8 vs the Sample Viewer.
+ *  3. STEREO. The engine turns the refracted point's clip position into a grab-texture UV by
+ *     mapping the VIEW's NDC over the WHOLE target (`getGrabScreenPos`). A stereo tile draws two
+ *     views side by side into one target, so each eye would sample across both. The patched chunk
+ *     measures the offset from THIS fragment instead (NDC delta ÷ NDC-per-pixel, from the
+ *     derivatives), which is exact for any viewport and identical in mono.
+ */
+const GRAB_UV_FN = `
+vec2 inline3dGrabUV(vec4 clipPos) {
+	vec4 p0 = matrix_viewProjection * vec4(vPositionW, 1.0);
+	vec2 n0 = p0.xy / p0.w;
+	vec2 dn = clipPos.xy / clipPos.w - n0;
+	vec2 perPx = vec2(dFdx(n0.x), dFdy(n0.y));
+	vec2 off = vec2(abs(perPx.x) > 1e-9 ? dn.x / perPx.x : 0.0, abs(perPx.y) > 1e-9 ? dn.y / perPx.y : 0.0);
+	return (gl_FragCoord.xy + off) * uScreenSize.zw;
+}
+`;
+const _grabChunk = new WeakMap();
+let _warnedGrabChunk = false;
+
+/** The engine's refractionDynamicPS with the per-view grab UV (null if its shape is not the expected one). */
+function stereoRefractionChunk(pc, device) {
+  if (_grabChunk.has(device)) return _grabChunk.get(device);
+  let out = null;
+  try {
+    const src = pc.ShaderChunks?.get?.(device, pc.SHADERLANGUAGE_GLSL)?.get?.('refractionDynamicPS');
+    const call = /getGrabScreenPos\(\s*projectionPoint\s*\)/;
+    const def = /vec3\s+evalRefractionColor\s*\(/;
+    if (typeof src === 'string' && call.test(src) && def.test(src)) {
+      out = src.replace(def, (m) => `${GRAB_UV_FN}\n${m}`).replace(call, 'inline3dGrabUV(projectionPoint)');
+    }
+  } catch {
+    out = null;
+  }
+  if (!out && !_warnedGrabChunk) {
+    _warnedGrabChunk = true;
+    console.warn(`${TAG} this engine's refraction shader has an unexpected shape; transmissive materials keep the engine's grab UV (correct in mono, not per eye in stereo).`);
+  }
+  _grabChunk.set(device, out);
+  return out;
+}
+
+/** Transmissive draws first, back-to-front among themselves (the engine's own key + an offset). */
+function transmissiveFirst(mi, camPos, camFwd) {
+  const c = mi.aabb.center;
+  return 1e6 + (c.x - camPos.x) * camFwd.x + (c.y - camPos.y) * camFwd.y + (c.z - camPos.z) * camFwd.z;
+}
+
+/**
+ * Apply 1–3 above to every dynamic-refraction mesh under `entity` not already handled (`seen`).
+ * Returns how many transmissive mesh instances there are under it (handled now or before) —
+ * the caller turns the grab pass on when that is > 0. Cheap to call again: handled ones are skipped.
+ */
+export function prepareTransmission(pc, entity, device, seen = new WeakSet()) {
+  const renders = entity?.findComponents ? entity.findComponents('render') : [];
+  let n = 0;
+  for (const r of renders) {
+    for (const mi of r.meshInstances || []) {
+      const m = mi.material;
+      if (!m?.useDynamicRefraction) continue;
+      n++;
+      if (seen.has(mi)) continue;
+      seen.add(mi);
+      mi.calculateSortDistance = transmissiveFirst;
+      if (!seen.has(m)) {
+        seen.add(m);
+        const chunk = device ? stereoRefractionChunk(pc, device) : null;
+        if (chunk && typeof m.getShaderChunks === 'function') {
+          m.getShaderChunks(pc.SHADERLANGUAGE_GLSL).set('refractionDynamicPS', chunk);
+          m.shaderChunksVersion = pc.CHUNKAPI_2_8 ?? '2.8';
+          m.update?.();
+        }
+      }
+    }
+  }
+  return n;
+}
+
 // ── framing ─────────────────────────────────────────────────────────────────────────────────
 
 /** Union of the render mesh instances' world AABBs (content space, the file's own units). */
@@ -535,7 +874,7 @@ export function attachPlayCanvasModel(out, wall, canvas, src, opts, pending = []
     fitSweep = true,
     renderScale = 1,
     feather = 0,
-    environment = 'room',
+    environment = 'neutral',
     envMap = null,
     decoderPath = null,
     meshoptDecoder = null,
@@ -568,7 +907,8 @@ export function attachPlayCanvasModel(out, wall, canvas, src, opts, pending = []
     nearClip: opts.nearClip,
     farClip: opts.farClip,
     sky: false,
-    toneMapping: 'neutral',
+    // Each environment's own look: 'room' is three's (untonemapped), the rest the Sample Viewer's.
+    toneMapping: envMap ? 'neutral' : ENVIRONMENT_TONE_MAPPING[environment] || 'neutral',
   });
 
   let handle = null;
@@ -701,7 +1041,8 @@ export function attachPlayCanvasModel(out, wall, canvas, src, opts, pending = []
     const yaw = Number.isFinite(opts.environmentRotation) ? opts.environmentRotation : 0;
     if (typeof envMap === 'string') useLightingSource(pc, app, await loadTexture(pc, app, envMap), true, yaw);
     else if (envMap && typeof envMap === 'object') useLightingSource(pc, app, envMap, false, yaw);
-    else if (environment === 'room' || environment === 'neutral') useNeutralStudio(pc, app, ENV_YAW_DEG + yaw);
+    else if (environment === 'room') useRoomEnvironment(pc, app, ROOM_YAW_DEG + yaw);
+    else if (environment === 'neutral') useNeutralStudio(pc, app, ENV_YAW_DEG + yaw);
     else if (environment === 'studio') addStudioLights(pc, app, viewer.content);
     if (removed) return out;
 
@@ -736,6 +1077,8 @@ export function attachPlayCanvasModel(out, wall, canvas, src, opts, pending = []
     if (removed) return out;
 
     const entity = asset.resource.instantiateRenderEntity();
+    // KHR_materials_transmission / volume: grab pass, pass order, per-eye grab UV (§ prepareTransmission).
+    if (prepareTransmission(pc, entity, app.graphicsDevice) > 0) viewer.useSceneColor(true);
     viewer.content.addChild(entity);
     out.model = entity;
     out.container = asset.resource; // animations, materials, textures (engine types)

package/js/inline3d-playcanvas-engine.js

@@ -53,6 +53,7 @@ export {
   SEMANTIC_TEXCOORD0,
   ShaderChunks,
   SHADERLANGUAGE_GLSL,
+  CHUNKAPI_2_8,
   // setSource's frame snapshot
   RenderTarget,
   FILTER_NEAREST,

package/js/inline3d-splat-playcanvas.js

@@ -652,6 +652,7 @@ export class PlayCanvasSplatViewer {
     // 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;
+    this.sceneColor = false;
     // 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.
@@ -927,6 +928,18 @@ export class PlayCanvasSplatViewer {
     if (this._viewPath === 'cameras') for (const c of this._views) if (c?.camera) c.camera.toneMapping = v;
   }
 
+  /**
+   * Turn the scene-colour grab pass on (true) or off on every eye camera — what a
+   * KHR_materials_transmission material samples (./model's prepareTransmission). Idempotent: the
+   * engine's `renderSceneColorMap` setter counts one request per camera. Cameras made later (a
+   * view-path switch) inherit it via `_makeCamera`.
+   */
+  useSceneColor(on = true) {
+    this.sceneColor = !!on;
+    const cams = [this.eye, ...(this._viewPath === 'cameras' ? this._views : [])];
+    for (const c of cams) if (c?.camera && c.camera.renderSceneColorMap !== undefined) c.camera.renderSceneColorMap = this.sceneColor;
+  }
+
   /** Forget the auto-fit (scale 1, no subject box) — the camera rig's framing. */
   resetFit() {
     this._fitScale = 1;
@@ -1490,6 +1503,7 @@ export class PlayCanvasSplatViewer {
     // 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 = TONE_MAPPINGS[this.toneMapping] ? pc[TONE_MAPPINGS[this.toneMapping]] ?? pc.TONEMAP_NONE : pc.TONEMAP_NONE;
+    if (this.sceneColor) e.camera.renderSceneColorMap = true;
     this.rigNode.addChild(e);
     return e;
   }
@@ -2170,8 +2184,10 @@ export function describeResource(res) {
  * handle.setRig's DISPLAY-rig defaults: addModel's, so a mesh framed through setRig('display')
  * sits exactly where `addModel(url, { engine: 'playcanvas' })` puts it (docs/playcanvas-adapter.md
  * §setRig). `toneMapping` applies to the page's meshes while the splat is hidden (the splat keeps
- * 'none' whenever it is shown); `environment: 'room'` installs addModel's neutral-studio IBL when
- * the page has no `scene.envAtlas` of its own, and removes it again when the rig changes back.
+ * 'none' whenever it is shown); `environment` installs addModel's IBL of the same name when the
+ * page has no `scene.envAtlas` of its own, and removes it again when the rig changes back —
+ * `'neutral'` (default, the Sample Viewer's studio) or `'room'` (three's RoomEnvironment; its
+ * tone mapping defaults to `'none'`, three's, unless `toneMapping` is passed).
  */
 export const SET_RIG_DISPLAY_DEFAULTS = Object.freeze({
   virtualDisplayHeight: 0.24,
@@ -2184,9 +2200,12 @@ export const SET_RIG_DISPLAY_DEFAULTS = Object.freeze({
   parallaxFactor: 1,
   perspectiveFactor: 1,
   toneMapping: 'neutral',
-  environment: 'room',
+  environment: 'neutral',
 });
 
+/** The tone mapping each setRig environment defaults to (addModel's ENVIRONMENT_TONE_MAPPING). */
+const SET_RIG_ENV_TONE_MAPPING = Object.freeze({ neutral: 'neutral', room: 'none', none: 'neutral' });
+
 export const SET_RIG_TYPES = Object.freeze(['display', 'camera', 'auto']);
 const SET_RIG_FITS = ['contain', 'cover', 'height', 'none'];
 let warnedSetRigKeys = false;
@@ -2224,14 +2243,14 @@ export function validateSetRig(type, o = {}, pageMode = false) {
   };
   const fit = o.fit === undefined ? D.fit : o.fit;
   if (!SET_RIG_FITS.includes(fit)) throw new Error(`@displayxr/inline3d/splat: setRig('display') — fit "${fit}", expected ${SET_RIG_FITS.join(' | ')}.`);
-  const toneMapping = o.toneMapping === undefined ? D.toneMapping : o.toneMapping;
-  if (!TONE_MAPPINGS[toneMapping]) {
-    throw new Error(`@displayxr/inline3d/splat: setRig('display') — toneMapping "${toneMapping}", expected ${Object.keys(TONE_MAPPINGS).join(' | ')}.`);
-  }
   const environment = o.environment === undefined ? D.environment : o.environment;
   if (!['room', 'neutral', 'none'].includes(environment)) {
     throw new Error(`@displayxr/inline3d/splat: setRig('display') — environment "${environment}", expected 'room' | 'neutral' | 'none'.`);
   }
+  const toneMapping = o.toneMapping === undefined ? SET_RIG_ENV_TONE_MAPPING[environment] : o.toneMapping;
+  if (!TONE_MAPPINGS[toneMapping]) {
+    throw new Error(`@displayxr/inline3d/splat: setRig('display') — toneMapping "${toneMapping}", expected ${Object.keys(TONE_MAPPINGS).join(' | ')}.`);
+  }
   let frame = null;
   if (o.frame != null) {
     const c = o.frame.center;
@@ -3080,8 +3099,14 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
   /** null = 'auto' (the per-asset waterfall); else { type: 'camera' } | { type: 'display', o }. */
   let rigOverride = null;
   let rigSeq = 0;
-  /** The neutral-studio IBL setRig('display') installed, and what it replaced — or null. */
+  /** The IBL setRig('display') installed ({ kind, atlas, prev }), and what it replaced — or null. */
   let rigEnv = null;
+  /** ./inline3d-model-playcanvas.js once a display rig has loaded it (transmission, environments). */
+  let rigModelModule = null;
+  /** Mesh instances / materials prepareTransmission has handled, and whether it turned the grab on. */
+  const rigTransmissionSeen = new WeakSet();
+  let rigGrab = false;
+  let rigTick = 0;
   const baseToneMapping = viewer.toneMapping;
 
   /** Is the splat on screen: its entity (and every ancestor) enabled. */
@@ -3155,21 +3180,39 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
   viewer.onTick = pageMode
     ? viewer.onTick
     : () => {
-        const want = rigOverride?.type === 'display' && !splatShown() ? rigOverride.o.toneMapping : baseToneMapping;
+        const display = rigOverride?.type === 'display';
+        const want = display && !splatShown() ? rigOverride.o.toneMapping : baseToneMapping;
         if (want !== viewer.toneMapping) viewer.setToneMapping(want);
+        // A transmissive glTF the page hangs under root on the display rig (a glass
+        // lantern): addModel's grab pass + pass order + per-eye grab UV. Re-checked every 30
+        // frames, since a page adds its meshes whenever they load — before or after setRig.
+        if (display && rigModelModule && pcModule && (rigTick++ % 30 === 0)) syncRigTransmission();
       };
 
-  /** Install addModel's default IBL for the display rig, if the page has none of its own. */
+  /** prepareTransmission over root; the grab pass on while a transmissive mesh is there. */
+  function syncRigTransmission() {
+    const n = rigModelModule.prepareTransmission(pcModule, viewer.content, viewer.app?.graphicsDevice, rigTransmissionSeen);
+    if ((n > 0) !== rigGrab) {
+      rigGrab = n > 0;
+      viewer.useSceneColor(rigGrab);
+    }
+  }
+
+  /** Install addModel's IBL (`disp.environment`) for the display rig, if the page has none of its own. */
   async function ensureRigEnvironment(disp, seq) {
-    if (disp.environment === 'none' || viewer.sky || rigEnv) return;
+    const m = (rigModelModule ||= await import('./inline3d-model-playcanvas.js'));
+    if (removed || seq !== rigSeq || rigOverride?.type !== 'display') return;
+    rigTick = 0; // transmission check on the next tick
+    const kind = disp.environment;
+    if (rigEnv && rigEnv.kind === kind) return;
+    dropRigEnvironment(); // a different environment of ours (setRig('display') called again)
+    if (kind === 'none' || viewer.sky) return;
     const app = viewer.app;
     const scene = app?.scene;
     if (!scene || scene.envAtlas) return; // the page lights its own meshes: leave it alone
-    const m = await import('./inline3d-model-playcanvas.js');
-    if (removed || seq !== rigSeq || rigOverride?.type !== 'display' || scene.envAtlas || rigEnv) return;
     const prev = { skyboxIntensity: scene.skyboxIntensity, exposure: scene.exposure, skyboxRotation: scene.skyboxRotation };
-    const atlas = m.useNeutralStudio(pcModule, app, m.ENV_YAW_DEG);
-    rigEnv = { atlas, prev };
+    const atlas = kind === 'room' ? m.useRoomEnvironment(pcModule, app, m.ROOM_YAW_DEG) : m.useNeutralStudio(pcModule, app, m.ENV_YAW_DEG);
+    rigEnv = { kind, atlas, prev };
   }
 
   /** Undo ensureRigEnvironment (only what it installed, only if the page has not replaced it). */
@@ -3200,7 +3243,13 @@ export function attachPlayCanvasSplat(out, wall, canvas, src, opts, pending = []
     return first.then(async () => {
       if (removed || seq !== rigSeq || !current) return out;
       rigOverride = req.type === 'auto' ? null : req;
-      if (req.type !== 'display') dropRigEnvironment();
+      if (req.type !== 'display') {
+        dropRigEnvironment();
+        if (rigGrab) {
+          rigGrab = false;
+          viewer.useSceneColor(false);
+        }
+      }
       const resolved = resolveFor(current.rigIn, req.type);
       out.rig = resolved;
       applyRig(resolved, current.rigIn.bounds, true);

package/model.d.ts

@@ -40,18 +40,24 @@ export interface ModelOptions {
   /**
    * 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).
+   * PlayCanvas (default engine):
+   * - `neutral` (default): 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.
+   * - `room`: three.js's procedural RoomEnvironment, regenerated in memory (no asset), untonemapped
+   *   — the look `engine: 'three'` gives `room`. Pass it when a page was tuned on the three path.
+   *   (Through 1.16 `room` was an alias of `neutral` here.)
+   *
+   * three: `room` (default) bakes three's procedural RoomEnvironment, untonemapped (unchanged since
+   * 1.11); `neutral` is not offered.
    *
    * 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' | 'neutral' | 'studio' | 'none';
   /**
-   * PlayCanvas only: yaw of the environment about +Y, degrees (default 0 = the Sample Viewer's
-   * default orientation).
+   * PlayCanvas only: yaw of the environment about +Y, degrees, on top of its own calibrated
+   * orientation (default 0 = the Sample Viewer's orientation for `neutral`, three's for `room`).
    */
   environmentRotation?: number;
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@displayxr/inline3d",
-  "version": "1.16.0",
+  "version": "1.17.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",

package/splat.d.ts

@@ -529,13 +529,18 @@ export interface SplatSetRigDisplayOptions {
   perspectiveFactor?: number;
   /**
    * The eye camera's tone mapping WHILE THE SPLAT IS HIDDEN (the splat's display-referred colours
-   * keep `'none'` whenever it is shown). Default `'neutral'` — addModel's (Khronos PBR Neutral).
+   * keep `'none'` whenever it is shown). Default: the environment's own — `'neutral'` (Khronos PBR
+   * Neutral) for `environment: 'neutral'`, `'none'` (three's) for `environment: 'room'`.
    */
   toneMapping?: 'none' | 'linear' | 'neutral' | 'aces' | 'aces2' | 'filmic' | 'hejl';
   /**
-   * `'room'` (default; `'neutral'` is the same): install addModel's generated neutral-studio IBL
-   * when the scene has no `envAtlas` of its own, removed again when the rig switches away. A page
-   * that lights its own meshes is never touched. `'none'`: never install it.
+   * addModel's IBL of the same name, installed when the scene has no `envAtlas` of its own and
+   * removed again when the rig switches away (a page that lights its own meshes is never touched):
+   * `'neutral'` (default) the Sample-Viewer-matched studio; `'room'` three's RoomEnvironment (the
+   * look `addModel(…, { engine: 'three', environment: 'room' })` gives), with tone mapping
+   * `'none'` unless `toneMapping` is passed; `'none'` installs nothing. (Through 1.16 `'room'` was
+   * the default and an alias of `'neutral'`.) A transmissive glTF under root (KHR_materials_
+   * transmission) also gets the scene-colour grab pass while the display rig is active.
    */
   environment?: 'room' | 'neutral' | 'none';
   /**