three-realtime-rt 0.6.1 → 0.7.0

package/README.md

@@ -138,7 +138,9 @@ A checklist for dropping the tracer into a scene you already have:
    scene with **no meshes yet** is a **no-op** (it warns once and keeps any
    previously compiled scene), so "construct the tracer, then add meshes" is a
    valid order — until meshes are added and recompiled, `rt.render()` falls back
-   to plain rasterization (no crash, no black screen).
+   to plain rasterization (no crash, no black screen). Call it **explicitly**: if
+   `render()` finds no compiled scene it compiles one itself, with *no options*,
+   so everything is static (it warns once — `implicit-compile`).
 3. **Declare movers** — pass moving meshes to
    `rt.compileScene(scene, { dynamicMeshes: [...] })`, then call
    `rt.updateDynamic()` each frame after you move them (e.g. after a physics
@@ -317,6 +319,71 @@ allocation, plus the usual O(dynamic tris) BVH refit and normal upload. Budget
 ≈ 1.7k source verts and skins in ≈ 0.3 ms. As with any dynamic mesh, keep the
 skinned tris low and there is no static-world cost.
 
+## Volumetric surface albedo (world-space 3D-texture colour)
+
+Colour a surface by a **world-space 3D texture** sampled at the ray hit point,
+instead of a flat colour or a 2D UV map. This is how you paint a **volumetric data
+field** — stress, temperature, density, a distance field — onto a mesh in a path
+tracer, where a custom fragment shader can't run. Opt a material in through
+`userData`, and the tracer samples your (already colour-mapped) `Data3DTexture` for
+that surface's albedo in **both** primary visibility (the G-buffer, so the
+raster/hybrid view agrees) **and** the traced GI / reflection bounces (so the
+field's colours bleed correctly through global illumination):
+
+```js
+import * as THREE from "three";
+
+// An RGB(A) 3D texture you have ALREADY colour-mapped (the tracer samples .rgb —
+// it contains no colormap logic). RGBA8 is fine; no float-filtering required.
+const field = new THREE.Data3DTexture(rgbaBytes, N, N, N); // your data
+field.format = THREE.RGBAFormat;
+field.type = THREE.UnsignedByteType;
+field.needsUpdate = true;
+
+// Map the volume into world space: origin = world position of the texel-(0,0,0)
+// corner, size = the world extent of the whole volume. A mesh's world AABB is the
+// natural choice, so the field fills the mesh.
+mesh.updateMatrixWorld(true);
+const box = new THREE.Box3().setFromObject(mesh);
+mesh.material.userData.rtVolumeAlbedo = {
+  texture: field,
+  origin: box.min.clone(),
+  size:   box.getSize(new THREE.Vector3()),
+};
+
+rt.compileScene(scene);   // detects the opt-in; recompile after adding/changing it
+```
+
+At the hit point `p`, the tracer computes `uvw = clamp((p - origin) / size, 0, 1)`
+and samples the texture **trilinearly** (it sets `LinearFilter` + `ClampToEdge` on
+your texture at compile time). The sampled RGB **replaces the base albedo**;
+`roughness`, `metalness` and `emissive` still compose normally. Updating the
+texture **data** later (an animated field) needs only `texture.needsUpdate = true`
+— no recompile; changing which material carries the field, or its `origin` / `size`,
+needs a `compileScene()`.
+
+**Demo:** [`volumetric-albedo.html`](volumetric-albedo.html) — a torus knot coloured
+by a procedural 3D noise field (turbo colormap) under an emissive area light, with
+the field's colours bleeding onto white walls through GI.
+
+**v1 is single-volume for the traced-bounce path.** Any number of materials may
+carry distinct volumes and each renders correctly in **primary visibility**; the
+GI / reflection **bounce** samples only the first registered volume. The reason is
+the sampler budget: the lighting megakernel already binds the WebGL2-guaranteed
+minimum of **16** fragment samplers, and this feature's bounce path adds one
+`sampler3D` (the 17th). It is compiled in only when a scene uses the feature **and**
+the GPU exposes ≥ 17 fragment texture units (`MAX_TEXTURE_IMAGE_UNITS` — most
+desktop GPUs report 32). On a bare-minimum 16-unit device the bounces fall back to
+the material's flat base colour (a one-time `console.info`), while primary
+visibility still shows the full field. The whole feature is behind a compile-time
+`RT_VOLUME_ALBEDO` define that is **off unless a volume material is registered**, so
+scenes that don't use it compile byte-identical shaders. Multi-volume bounces are
+future work — the `userData` API doesn't preclude them. One more edge: the
+**experimental** `restirGI` path (off by default) resolves the indirect bounce in
+its own kernel and does **not** yet sample the volume — a volume surface's
+*indirect* contribution falls back to its flat colour while `restirGI` is on (the
+default inline-GI path carries the field correctly).
+
 ## Live lighting & sky
 
 Lights can be toggled, moved, and recoloured every frame without recompiling:
@@ -372,14 +439,16 @@ material of a group* row).
 | `transmission` (Physical) | ✅ | Glass: Fresnel reflection (with analytic-light glints) + two-interface refraction. |
 | `transparent` + `opacity` | ✅ | Alpha blend: the surface is composited over the geometry behind it (a straight-through traced ray), weighted by scalar `opacity` and **tinted by `color`/`map`**. The behind-radiance rides the **specular buffer** and the opacity blend happens at **composite** (where the pane's albedo lives), so **needs `specular: true`** — with the specular buffer off, blend surfaces degrade to opaque. Single layer — nearest transparent surface wins, overlapping panes don't inter-sort. Kept out of the BVH, so it casts no shadow. Toggle with `transparency`. |
 | `opacity` on an opaque material | ❌ | Only read when `transparent: true`; an opaque material always writes at full coverage. |
+| `alphaMap` | ❌ | There is **no per-pixel opacity route**: opacity is a **scalar per material**, packed into the material word the lighting pass reads. An `alphaMap` is ignored — a mesh carrying one blends at its uniform `opacity` (see the `transparent` + `opacity` row, the supported path), so a partly-cut-out texture reads as an evenly translucent surface. For hard cut-outs use `alphaTest` (`transparent: false`), which occludes as full triangles. |
 | **dielectric specular** | ✅ | Cook-Torrance **GGX** direct highlights for *every* surface, in a separate white (`F0 ≈ 0.04`) specular buffer the composite adds without the albedo multiply. Toggle with `specular` (default on). |
 | `roughnessMap` | ✅ | `roughness × roughnessMap.g` (three.js convention) — sampled in the G-buffer. |
 | `metalnessMap` | ✅ | `metalness × metalnessMap.b` (a packed ORM texture works — G = roughness, B = metalness). |
 | `normalMap` | ✅ | Perturbs the shading normal via a screen-space cotangent frame (no tangent attribute needed); respects `material.normalScale`. |
 | `clearcoat`, `sheen`, `iridescence` | ❌ | Per-pixel lobe parameters have **no remaining G-buffer channel** — the 4-MRT WebGL2 guarantee is fully packed (see the `GBufferPass` layout comment), so these stay unmodelled rather than risk corrupting the packing; revisit if a WebGPU backend lands. |
 | vertex colors | ✅ | Geometry `color` attribute (3- or 4-component; `.rgb` used) multiplies into G-buffer albedo, gated so meshes without one render byte-identically. **Caveat:** secondary GI/reflection rays see the flat `material.color` (same as texture maps). |
+| `userData.rtVolumeAlbedo` *(since 0.7.0)* | ✅ | **World-space 3D-texture albedo** — sample a colour-mapped `Data3DTexture` at the world hit point for the surface's albedo, in primary visibility **and** GI/reflection bounces. For volumetric data fields (stress/temperature/density) on a surface. See *[Volumetric surface albedo](#volumetric-surface-albedo-world-space-3d-texture-colour)*. Single volume in the bounce path in v1 (needs a 17th fragment sampler; primary visibility is unlimited). |
 | per-material `ior` | ✅ | `MeshPhysicalMaterial.ior` refracts per material, encoded in the packed material word for fully-transmissive glass. Supported range **[1.0, 1.98]** (values clamp; the tight ceiling keeps the packed word clear of the alpha-blend boundary). `rt.ior` is the global fallback (partial-transmission glass + the default); **`material.ior` wins when present**. |
-| 2nd+ material of a group | ✅ | Each group material of a multi-material mesh (`mesh.material` array + `geometry.groups`) is registered separately in the G-buffer **and** the BVH, with per-vertex material indices; emissive group materials also join the NEE area-light list. **Limits:** opaque groups only (a transparent group throws — split it out); not supported on CPU-deforming (`rtDeforming`) meshes (throws). |
+| 2nd+ material of a group | ✅ | Each group material of a multi-material mesh (`mesh.material` array + `geometry.groups`) is registered separately in the G-buffer **and** the BVH, with per-vertex material indices; emissive group materials also join the NEE area-light list. **Limits:** opaque groups only (a transparent group throws — split it out); not supported on a mesh that is **both** listed in `dynamicMeshes` **and** flagged `userData.rtDeforming` — that combination is what the per-frame live-geometry rebake can't express, and it throws. (`rtDeforming` *without* `dynamicMeshes` membership is inert: the flag is ignored, the mesh compiles static, and the library warns — see *[Supported object types](#supported-object-types)*.) |
 
 ### Lights
 
@@ -405,10 +474,26 @@ material of a group* row).
 - **Moving** a dynamic emitter → `rt.updateDynamic()` refreshes its area-light rows + CDF from the new geometry. But an emitter's **emission itself** (its `emissive` colour / `emissiveIntensity`, or the map's average) is frozen at compile time: **changing what it emits — static or dynamic — needs `rt.compileScene(...)` again** (`updateDynamic`/`updateLights` do not rescan emissive meshes). A dynamic emitter that never moves also needs a recompile to reflect an emission change.
 - Emissive area lights are capped at **256 triangles** (shared across static + dynamic; largest by compile-time area kept, with a console warning) — prefer low-poly emitter meshes, especially dynamic ones.
 
+### Supported object types
+
+What kind of `Object3D` the tracer can actually see. Anything it cannot trace is
+also excluded from the rasterized G-buffer, so the traced frame stays consistent
+with what the lighting was computed against — and the library **warns once**,
+naming the object (see *[Diagnostics](#diagnostics-statuswarnings)*).
+
+| Object | Supported | Notes |
+|--------|-----------|-------|
+| `Mesh` | ✅ | The normal case: merged into the static BVH, or into the per-frame dynamic BVH when listed in `dynamicMeshes`. |
+| `SkinnedMesh` | ✅ | Auto-detected (no flag). **CPU-skinned** into the dynamic BVH every frame from its live skeleton pose — list it in `dynamicMeshes`. See *[Skinned meshes](#skinned-meshes-animated-characters)*. |
+| `InstancedMesh` | ❌ | **Instancing is not supported.** The per-instance matrices are a GPU attribute the compiler never reads, so it **collapses to a single instance** in the traced output *and* in the G-buffer. Warns (`instanced-mesh`). Expand it to individual meshes, or exclude it with `userData.rtExclude`. |
+| `Sprite` / `Line` / `LineSegments` / `Points` | — | Not traceable geometry, and their materials write a single `gl_FragColor`, which cannot feed the 4-attachment G-buffer. They are **automatically hidden for the traced frame** (and restored right after), so they simply do not appear. Warns (`untraceable-object`). Draw them yourself in an **overlay pass on top of `rt.render()`**, or set `userData.rtExclude` on them to silence the warning. |
+| `userData.rtExclude` | ✅ honored | Keeps a mesh out of the BVH entirely — it still rasterizes into the G-buffer and gets lit, it just never occludes or bounces light. Also suppresses the warnings above, so it is the way to say "yes, I meant that". |
+| `Group` / `Object3D` / `Bone` | ✅ | Pure transform nodes; traversed for their mesh children. |
+
 ### Geometry & occlusion
 
 - Every non-excluded visible mesh is **merged into one static BVH at compile time**. Add / remove geometry → recompile.
-- Meshes that move must be declared via `dynamicMeshes` and driven with `updateDynamic()`. Anything not declared is treated as static — moving it on screen won't move its traced shadow.
+- Meshes that move must be declared via `dynamicMeshes` and driven with `updateDynamic()`. Anything not declared is treated as static — moving it on screen won't move its traced shadow. The library **detects this and warns** (`stale-transform` / `stale-geometry`); see *[Diagnostics](#diagnostics-statuswarnings)*.
 - **Transparent materials never occlude** (by design — a glass case shouldn't cast an opaque shadow). They still rasterize normally.
 - **`alphaTest` cut-outs** (`transparent: false`) *do* occlude — but as **full triangles**, not per-texel, so their shadows are blocky.
 - `mesh.userData.rtExclude = true` removes a mesh from the BVH entirely (it still rasterizes and gets lit) — handy for water / translucent surfaces.
@@ -420,6 +505,10 @@ material of a group* row).
 - **Refraction** is two-interface (front + back). IOR is **per material** (`MeshPhysicalMaterial.ior`, encoded in the G-buffer for fully-transmissive glass, range [1.0, 1.98]); `rt.ior` is the global fallback. Optional **chromatic dispersion** (`rt.dispersion`, off by default) splits the refracted term into a spectrum by stochastic spectral sampling (one channel per glass pixel per frame, blended by temporal accumulation — no extra rays); it is a **global** control, not yet per-material.
 - **Volumetric** is **single-scatter** god rays, not multiple-scattering fog.
 - **Transparency** is a **single-layer deferred blend**: a `transparent` surface writes as the nearest layer of the G-buffer and the lighting pass composites it over the geometry behind by tracing one straight-through ray. The behind-radiance is fully lit (direct + 1-bounce GI) and tinted by the pane's albedo. Overlapping transparent surfaces do **not** inter-sort (only the nearest is kept), and there is no per-pixel back-to-front over-blend of many layers as in raster three.js. Turn it off with `transparency: false` (blend surfaces then render fully opaque).
+  - **What's behind the glass is a genuinely traced ray**, not a re-sorted draw of the same rasterized surfaces — so it is *stronger* than sorted transparency in the one way that matters: the surface seen through the pane is shaded with real traced direct light and GI at its own hit point, including things outside the frustum and things the raster pass never drew.
+  - **Only BVH geometry shows through.** The blend ray hits the compiled scene, so anything kept out of the BVH is invisible behind glass — including *other transparent surfaces* (they are never occluders). The nearest transparent surface wins, so an **intermediate translucent layer disappears the moment another transparent surface covers it**: two panes in a row read as one.
+  - **Behind-radiance bypasses the firefly / irradiance clamps.** It is composited as radiance rather than filtered demodulated irradiance, so a bright emitter **seen through glass reads hotter than the same emitter viewed directly** (which the clamps tame). That is a known asymmetry, not a bug in your scene — dim the emitter or thicken the pane's `opacity` if it bothers you.
+- **Transparent meshes are never dynamic.** They are dropped before the dynamic registration, so listing one in `dynamicMeshes` does nothing at all (the library warns: `transparent-dynamic`).
 
 ### Platform
 
@@ -434,6 +523,9 @@ material of a group* row).
 | `renderScale` | `0.5` | Lighting resolution vs. the G-buffer. `1.0` = max quality. |
 | `overscan` | `0` | Render past the canvas edges and crop the centre back, so leading-edge disocclusion noise during camera motion is born off-screen. Padding fraction per edge (0–0.25); `0.1` costs 1.44× the pixels. See *Edge convergence and overscan*. |
 | `adaptiveQuality` | `true` | Governor that steers `renderScale` / `denoiseIterations` / `stochasticLights` toward `targetFps` — scales **up** on strong hardware, **down** on weak. Turn off for manual control. |
+| `targetFps` | `55` | Frame rate the governor steers toward. |
+| `canvasScaleHook` | `null` | Callback `(scale) => void` letting the governor drive your **canvas scale** — its deepest, most valuable lever. See *[canvasScaleHook](#canvasscalehook-the-governors-deepest-lever)*. |
+| `taaJitterScale` | `1` | Scales the sub-pixel TAA jitter. Set it to your current canvas scale when you CSS-stretch a reduced drawing buffer, so the jitter stays constant in *screen* pixels instead of wobbling. |
 | `denoiseIterations` | `2` | À-trous denoise passes; the governor raises this as it lowers resolution. |
 | `taa` | `true` | Temporal anti-aliasing (jitter + neighbourhood clamp). |
 | `denoise` | `true` | Edge-aware à-trous denoiser. |
@@ -551,6 +643,79 @@ starting point or take manual control:
   pixel per frame instead of one per light — the biggest ray-count lever for
   many-light scenes and mobile GPUs.
 
+### canvasScaleHook (the governor's deepest lever)
+
+`renderScale` only shrinks the *lighting* buffer. **Canvas scale** shrinks the
+whole drawing buffer, so every pass — the raster G-buffer, lighting, denoise,
+TAA, resolve — gets quadratically cheaper. That makes it the strongest lever the
+governor has, and the one it reaches for **first when recovering** quality and
+**last when cutting** it (once `renderScale` has bottomed out at `0.2`).
+
+The canvas belongs to your app, not the library, so the governor cannot resize it
+itself: it calls **`canvasScaleHook(scale)`** with the next value from
+`RealtimeRaytracer.CANVAS_LEVELS` (`[1, 0.85, 0.75, 0.62, 0.5]`) and leaves the
+implementation to you. The pattern is: render a **reduced drawing buffer**, then
+**CSS-stretch** the canvas back to full size.
+
+```js
+let canvasScale = 1;
+
+const applyCanvasSize = () => {
+  // CSS size stays the full layout size; the BUFFER shrinks.
+  renderer.domElement.style.width = `${innerWidth}px`;
+  renderer.domElement.style.height = `${innerHeight}px`;
+  renderer.setPixelRatio(Math.min(devicePixelRatio, 2) * canvasScale);
+  renderer.setSize(innerWidth, innerHeight, false);
+};
+
+const setCanvasScale = (s) => {
+  canvasScale = s;
+  applyCanvasSize();
+  rt.setSize(...renderer.getDrawingBufferSize(new THREE.Vector2()).toArray());
+  // Keep the TAA jitter constant in SCREEN pixels: at a reduced canvas scale the
+  // CSS stretch magnifies buffer-pixel jitter into visible wobble.
+  rt.taaJitterScale = s;
+};
+```
+
+Two rules: call `rt.setSize(...)` with **drawing-buffer pixels** after the resize,
+and set **`rt.taaJitterScale = s`**. Skipping the second is the usual cause of
+"the image shimmers once auto-quality kicks in". The hook is optional — without
+it the governor simply never uses the canvas lever. Live examples:
+[`examples/main.js`](examples/main.js) and [`examples/gallery.js`](examples/gallery.js).
+
+### Recommended integration
+
+Tier detection for the starting point, the governor for everything after, and the
+canvas hook so the governor has its deepest lever:
+
+```js
+const renderer = new THREE.WebGLRenderer({ antialias: false });
+renderer.setSize(innerWidth, innerHeight);
+
+const tier = RealtimeRaytracer.detectTier(renderer);   // "none" | "mid" | "high"
+const rt = new RealtimeRaytracer(renderer, {
+  ...RealtimeRaytracer.recommendedOptions(tier),       // sensible start for the GPU
+  adaptiveQuality: true,                               // (already the default)
+  targetFps: 55,
+  canvasScaleHook: (s) => setCanvasScale(s),           // see above
+});
+
+rt.compileScene(scene, { dynamicMeshes: movers });     // explicit — see Diagnostics
+
+function frame() {
+  requestAnimationFrame(frame);
+  rt.updateDynamic();                 // only on frames where something moved
+  rt.render(scene, camera);
+}
+frame();
+```
+
+`detectTier` picks *where you start*; `adaptiveQuality` decides *where you end up*
+on the machine that actually loaded the page; `canvasScaleHook` widens the range
+it can move through. On a device too slow to trace at all, `rt.supported` is
+`false` and `rt.render()` is a plain `renderer.render()` — no branch needed.
+
 WebGPU: not used as a backend (this is a WebGL2 library); a WGSL compute
 backend is on the roadmap.
 
@@ -609,6 +774,75 @@ JSON line to the console every 2s for automated scraping. The overscan control
 is **feature-detected** — it appears only when the loaded build exposes an
 `overscan` property.
 
+## Diagnostics (`status.warnings`)
+
+*Since 0.7.0.* Most integration mistakes in a hybrid tracer are **silent**: the
+image still renders, nothing throws, and the lighting is quietly computed against
+a scene that is not the one on screen. So the library detects the common ones at
+compile time (and on a cheap periodic scan while rendering), prints **one**
+`console.warn` naming the object and the exact fix, and records the same thing on
+`rt.status.warnings`:
+
+```js
+rt.render(scene, camera);
+for (const w of rt.status.warnings) {
+  console.log(w.code, w.message); // e.g. "stale-transform", "three-realtime-rt: ..."
+}
+```
+
+`rt.status.warnings` is `{ code, message }[]`, deduplicated, and **never affects
+`status.ok`** — these are scene-setup diagnostics, not pipeline failures (for
+those see [`compileError` / `status.coreFailure`](#render-self-test)).
+
+| Code | Fires when | Consequence |
+|------|------------|-------------|
+| `stale-geometry` | A **static** mesh's `position` buffer changed after `compileScene()`. | Traced lighting still uses the ORIGINAL shape. |
+| `stale-transform` | A **static** mesh was moved after `compileScene()`. | Traced lighting still uses the ORIGINAL transform — its shadow stays behind. |
+| `rtdeforming-not-dynamic` | `userData.rtDeforming` is set on a mesh that is **not** in `dynamicMeshes`. | The flag is ignored; the mesh compiles static. |
+| `implicit-compile` | `render()` had to compile the scene itself. | Compiled with **no options** — everything is static. |
+| `untraceable-object` | A visible `Sprite` / `Line` / `Points`. | Auto-hidden from the traced frame; render it in your own overlay pass. |
+| `instanced-mesh` | An `InstancedMesh`. | Collapses to a single instance. |
+| `transparent-dynamic` | A `transparent` mesh listed in `dynamicMeshes`. | That entry does nothing. |
+
+The stale scan runs **every 30th frame**, compares one integer and one matrix per
+static mesh, stops checking a mesh once it has reported, and caps at 8 reports —
+so it costs effectively nothing in a correct scene. Set `userData.rtExclude` on
+an object to say "this is intentional" and silence its warning.
+
+### Troubleshooting
+
+**"Black patches", "the shadow doesn't move", "rays still hit the original
+shape".** All three are the same bug: a **stale BVH**. The tracer bakes geometry
+into a BVH at `compileScene()` time. Move a mesh (or edit its vertices) after
+that without declaring it, and the rasterized image shows the new pose while the
+traced lighting still shadows, bounces and reflects off the **old** one — which
+reads as a shadow left behind, a reflection of something that isn't there, or a
+dark patch where the invisible old geometry still occludes.
+
+The fixes, in order of how much you are asking for:
+
+| Your object… | Do this |
+|--------------|---------|
+| never moves after setup | nothing — but call `compileScene(scene)` again after you add/remove/replace geometry. |
+| moves rigidly every frame | `compileScene(scene, { dynamicMeshes: [mesh] })`, then `rt.updateDynamic()` each frame. |
+| has **vertices** that move on the CPU (water, cloth, morphs) | the above **plus** `mesh.userData.rtDeforming = true`, and keep its `normal` attribute current. See *[Deforming meshes](#deforming-meshes-water-cloth)*. |
+| is an animated character | list its `SkinnedMesh` in `dynamicMeshes` — skinning is auto-detected. See *[Skinned meshes](#skinned-meshes-animated-characters)*. |
+| changed structurally (mesh added/removed, material swapped, emission changed) | `compileScene()` again. |
+
+You should not have to guess which one you hit: the `stale-geometry` /
+`stale-transform` / `rtdeforming-not-dynamic` warnings above name the mesh and
+the fix in the console. If a mesh is *deliberately* left out of the BVH, set
+`userData.rtExclude = true`.
+
+**"Nothing I do to `dynamicMeshes` has any effect."** Check for
+`implicit-compile` in the console: if the first `rt.render()` ran before any
+`compileScene()` call, the scene was compiled implicitly **with no options** and
+every mesh is static. Call `compileScene(scene, options)` yourself first.
+
+**"My HUD sprite / debug lines disappeared."** They are not traceable geometry
+and cannot write the G-buffer, so they are hidden for the traced frame
+(`untraceable-object`). Draw them in your own pass on top of `rt.render()`.
+
 ## Render self-test
 
 The renderer can pass every compile and framebuffer check and still draw a black
@@ -636,7 +870,7 @@ if (!rt.status.ok) {
 
 - **`rt.compileError`** (`string | null`) — first / most-severe failure summary
   (`"rt:<pass>: <driver log>"`), or `null` while every pass compiles clean.
-- **`rt.status`** (`{ ok, disabled, coreFailure }`) — `ok` is `true` on the healthy
+- **`rt.status`** (`{ ok, disabled, coreFailure, warnings }`) — `ok` is `true` on the healthy
   path and `false` once any `rt:*` pass fails to link. **Optional** features whose
   pass failed are **auto-disabled** so the image stays lit (`restir`, `restirGI`,
   `denoise`, `volumetric`, `taa`, `specular`), each listed in `disabled` as
@@ -645,6 +879,13 @@ if (!rt.status.ok) {
   and the image is black-but-diagnosed. This lets an integrator render an honest
   `raster (reason)` fallback instead of guessing. (When `supported` is `false` the
   RT pipeline never runs, so `status.ok` is `false` too — check `supported` first.)
+- **`rt.status.warnings`** (`{ code, message }[]`, **since 0.7.0**) — USAGE
+  diagnostics: a flag being ignored, an object type that cannot be traced, a
+  static mesh edited after `compileScene()`. Separate axis from the three fields
+  above: the pipeline is healthy, the scene setup is not what you probably meant,
+  so **warnings never change `status.ok`**. Full list in
+  *[Diagnostics](#diagnostics-statuswarnings)*. (`compileError` and the base
+  `status` surface are since 0.6.1.)
 
 **In the browser:** load [`/?selftest=1`](examples/selftest.js). It forces the
 full lighting stack on (GI + emissive NEE + reflections + refraction, lighting at
@@ -653,17 +894,22 @@ the drawing buffer back and emits one JSON line to the console (`[selftest] …`
 and into a hidden `#selftest-verdict` DOM node:
 
 ```json
-{ "pass": true, "meanLum": 139.08, "irrLum": 169.73, "glErrors": 0,
+{ "pass": true, "meanLum": 139.80, "irrLum": 170.53, "glErrors": 0,
   "specMRT": true, "supported": true, "statusOk": true, "rtPrograms": 15,
-  "compileError": null, "disabled": [], "frames": 91, "ua": "…" }
+  "compileError": null, "disabled": [], "warnings": 0, "warningCodes": [],
+  "frames": 91, "ua": "…" }
 ```
 
 The pass gate wants `meanLum` in `[12, 230]` (calibrated: a healthy composite of
 the gallery centre reads ~140 on desktop; a black screen reads ~0), `irrLum > 6`,
-`glErrors == 0`, `supported == true`, and `statusOk == true` — the last asserts
-the compile-failure surface above stayed clean (`rt.status.ok`, `compileError`
-null) *and* that the named pass programs were actually discoverable
-(`rtPrograms > 0`), so a broken diagnosis can't read as a false pass.
+`glErrors == 0`, `supported == true`, `statusOk == true`, and `warnings == 0`.
+`statusOk` asserts the compile-failure surface above stayed clean (`rt.status.ok`,
+`compileError` null) *and* that the named pass programs were actually discoverable
+(`rtPrograms > 0`), so a broken diagnosis can't read as a false pass. `warnings`
+is `rt.status.warnings.length`: the demo is the reference integration, so the
+healthy path must raise **none** — a nonzero count means either the demo really
+did something wrong, or a [diagnostic](#diagnostics-statuswarnings) has started
+firing on a correct scene.
 
 - `meanLum` / `irrLum` — mean Rec.709 luma (0–255) of the **centre 25%** of the
   composite, and of the raw irradiance buffer (`outputMode 3`) for one frame. The
@@ -691,8 +937,13 @@ tested a newer three, so **chromium runs twice**: once against the pinned three
 class of regression, and **the pass gate requires both chromium legs**. A fourth
 chromium load of `?selftest=empty` asserts the [empty-scene no-op](#empty-scene)
 (`compileScene` on a scene with no meshes is a no-op and `render()` falls back to
-plain raster instead of crashing). firefox/webkit stay single-leg against the
-default three (both are environmental skips here — see below).
+plain raster instead of crashing), and a fifth,
+[`?selftest=warnings`](#diagnostics-statuswarnings), drives a deliberately
+mis-configured scene and asserts every usage diagnostic fires **exactly once**,
+lands on `status.warnings`, leaves `status.ok` true, and that a visible
+`Sprite`/`Line` costs zero GL errors (it is hidden from the 4-attachment G-buffer
+rather than drawn into it). Both are gating. firefox/webkit stay single-leg
+against the default three (both are environmental skips here — see below).
 
 Machine-specific note (Windows + NVIDIA, the current dev box): each chromium leg
 runs **headed** with **`--use-angle=gl`**. ANGLE's default D3D11/FXC backend

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "three-realtime-rt",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "Turn-on ray traced lighting for three.js: a hybrid deferred renderer with BVH-traced soft shadows, one-bounce global illumination, temporal reprojection, an a-trous denoiser and TAA.",
   "type": "module",
   "main": "src/index.js",

package/src/GBufferPass.js

@@ -86,6 +86,20 @@ uniform bool uHasMetalnessMap;
 uniform bool uBlend;
 uniform float uOpacity;
 
+// World-space 3D-texture albedo ("volumetric surface albedo"), compiled in ONLY
+// when a scene registers a material with userData.rtVolumeAlbedo (the whole block
+// is behind the RT_VOLUME_ALBEDO define, so a scene without the feature builds a
+// byte-identical G-buffer program with no extra sampler). Primary visibility can
+// afford this sampler3D — the raster pass has ample sampler headroom, unlike the
+// lighting megakernel. The value is gated per-mesh by uHasVolume, so non-volume
+// meshes sharing this program write exactly the same albedo they did before.
+#ifdef RT_VOLUME_ALBEDO
+uniform highp sampler3D uVolumeTex;
+uniform vec3 uVolumeOrigin;
+uniform vec3 uVolumeSize;
+uniform bool uHasVolume;
+#endif
+
 // Screen-space cotangent frame (Mikkelsen 2010): reconstruct a tangent basis
 // from derivatives of world position and uv, so tangent-space normal maps work
 // without a per-vertex tangent attribute (none is uploaded to the BVH/G-buffer).
@@ -106,6 +120,17 @@ void main() {
     albedo *= texture(uMap, vUvCoord).rgb;
   }
   albedo *= vColor; // vertex colours (white when the mesh has no color attribute)
+  // Volumetric surface albedo: sample a world-space 3D texture at this fragment's
+  // world position and use it as the base colour, replacing color x map x vColor.
+  // uvw = clamp((p - origin) / size, 0, 1); the ClampToEdge sampler + this clamp
+  // keep hits just outside the volume reading the boundary colour instead of
+  // wrapping. Gated so only rtVolumeAlbedo meshes are affected.
+#ifdef RT_VOLUME_ALBEDO
+  if (uHasVolume) {
+    vec3 uvw = clamp((vWorldPos - uVolumeOrigin) / uVolumeSize, 0.0, 1.0);
+    albedo = texture(uVolumeTex, uvw).rgb;
+  }
+#endif
   vec3 emissive = uEmissive;
   if (uHasEmissiveMap) {
     emissive *= texture(uEmissiveMap, vUvCoord).rgb;
@@ -187,7 +212,44 @@ export class GBufferPass {
 
     this._materialCache = new WeakMap(); // mesh -> gbuffer ShaderMaterial
     this._swapped = []; // [mesh, originalMaterial] pairs during render
+    this._hidden = []; // objects temporarily hidden for the G-buffer draw
     this._normalMat3 = new THREE.Matrix3();
+    // World-space 3D-texture albedo: off unless a scene registers a material with
+    // userData.rtVolumeAlbedo (see setVolume). When off, the gbuffer program is
+    // compiled WITHOUT the RT_VOLUME_ALBEDO define — no sampler3D, byte-identical.
+    this._volumeEnabled = false;
+    this._dummyVolumeTex = null; // 1x1x1 fallback bound to non-volume meshes when on
+  }
+
+  // A valid 1x1x1 3D texture to bind on gbuffer materials whose mesh is NOT a
+  // volume material while the feature is compiled in — keeps every declared
+  // sampler3D pointing at a complete texture (its branch is never taken, so the
+  // value is irrelevant; it just must not be an unbound/incomplete sampler).
+  _dummyVolume() {
+    if (!this._dummyVolumeTex) {
+      const t = new THREE.Data3DTexture(new Uint8Array([255, 255, 255, 255]), 1, 1, 1);
+      t.format = THREE.RGBAFormat;
+      t.type = THREE.UnsignedByteType;
+      t.minFilter = THREE.LinearFilter;
+      t.magFilter = THREE.LinearFilter;
+      t.needsUpdate = true;
+      this._dummyVolumeTex = t;
+    }
+    return this._dummyVolumeTex;
+  }
+
+  /**
+   * Enable/disable the world-space 3D-texture albedo path for the primary
+   * (G-buffer) visibility. Compiles the RT_VOLUME_ALBEDO define into the per-mesh
+   * gbuffer program when on. Toggling clears the material cache so the programs
+   * recompile with/without the define. Called by RealtimeRaytracer after each
+   * compile with whether the scene registered any rtVolumeAlbedo material.
+   */
+  setVolume(enabled) {
+    const on = !!enabled;
+    if (on === this._volumeEnabled) return;
+    this._volumeEnabled = on;
+    this._materialCache = new WeakMap(); // force recompile with the new define
   }
 
   _makeTarget(width, height) {
@@ -246,6 +308,10 @@ export class GBufferPass {
       // cache key, so they all surface as the single core pass "rt:gbuffer".
       name: "rt:gbuffer",
       glslVersion: THREE.GLSL3,
+      // RT_VOLUME_ALBEDO is present only while a scene uses the volumetric-albedo
+      // feature (see setVolume); absent, the compiled program is identical to the
+      // pre-feature G-buffer (no sampler3D, no volume branch).
+      defines: this._volumeEnabled ? { RT_VOLUME_ALBEDO: "1" } : {},
       vertexShader: gbufferVert,
       fragmentShader: gbufferFrag,
       uniforms: {
@@ -269,6 +335,16 @@ export class GBufferPass {
         uHasMetalnessMap: { value: false },
         uBlend: { value: false },
         uOpacity: { value: 1.0 },
+        // Volume-albedo uniforms are always present in the JS uniform object
+        // (harmless when the define is off — three uploads only uniforms that
+        // exist in the compiled program, so a non-volume scene never touches
+        // these). While the define is on, _syncGbufferMaterial binds either the
+        // material's own volume texture or the shared dummy, so a non-volume mesh
+        // never leaves an incomplete sampler3D bound.
+        uVolumeTex: { value: null },
+        uVolumeOrigin: { value: new THREE.Vector3() },
+        uVolumeSize: { value: new THREE.Vector3(1, 1, 1) },
+        uHasVolume: { value: false },
       },
       side: THREE.FrontSide,
     });
@@ -314,6 +390,23 @@ export class GBufferPass {
     // lighting pass. opacity 1 renders opaque, matching the old force-opaque path.
     u.uBlend.value = !!src.transparent;
     u.uOpacity.value = src.opacity ?? 1.0;
+    // World-space 3D-texture albedo. Only meshes whose material opted in via
+    // userData.rtVolumeAlbedo get uHasVolume=true; every other mesh keeps the
+    // dummy sampler (branch never taken) so its albedo is byte-identical. This is
+    // per-mesh, so DISTINCT volumes each render correctly in primary visibility.
+    if (this._volumeEnabled) {
+      const vol = src.userData && src.userData.rtVolumeAlbedo;
+      if (vol && vol.texture) {
+        u.uHasVolume.value = true;
+        u.uVolumeTex.value = vol.texture;
+        u.uVolumeOrigin.value.copy(vol.origin ?? { x: 0, y: 0, z: 0 });
+        const s = vol.size ?? { x: 1, y: 1, z: 1 };
+        u.uVolumeSize.value.set(s.x || 1, s.y || 1, s.z || 1);
+      } else {
+        u.uHasVolume.value = false;
+        u.uVolumeTex.value = this._dummyVolume();
+      }
+    }
     u.uNormalMatrixWorld.value.getNormalMatrix(mesh.matrixWorld);
     material.side = src.side ?? THREE.FrontSide;
   }
@@ -353,11 +446,27 @@ export class GBufferPass {
     // material word + gEmissive.a, and the lighting pass blends them against the
     // geometry behind. opacity 1 writes fully opaque, so alpha-textured cases
     // (LittlestTokyo's glass) look exactly as before.
+    //
+    // Objects that are NOT meshes (Sprite / Line / Points) keep their OWN
+    // material here, and those materials write a single gl_FragColor. Rendering
+    // one into this 4-attachment MRT framebuffer is a GL_INVALID_OPERATION (an
+    // ESSL1 fragment shader cannot feed multiple draw buffers) and the object is
+    // not traceable geometry either — the BVH compiler skips it. So they are
+    // HIDDEN for the duration of the G-buffer draw and restored right after;
+    // draw them yourself in an overlay pass on top of rt.render() if you need
+    // them on screen. compileScene() warns once naming them.
     this._swapped.length = 0;
+    this._hidden.length = 0;
     scene.traverse((obj) => {
-      if (obj.isMesh && obj.geometry && obj.visible) {
+      if (!obj.visible) return;
+      if (obj.isMesh && obj.geometry) {
         this._swapped.push([obj, obj.material]);
         obj.material = this._gbufferMaterialFor(obj);
+        return;
+      }
+      if (obj.isSprite || obj.isLine || obj.isPoints) {
+        obj.visible = false;
+        this._hidden.push(obj);
       }
     });
 
@@ -373,9 +482,14 @@ export class GBufferPass {
     scene.background = prevBackground;
     for (const [mesh, mat] of this._swapped) mesh.material = mat;
     this._swapped.length = 0;
+    // Restore visibility exactly once per object (each was pushed once, and only
+    // if it was visible when we hid it).
+    for (const obj of this._hidden) obj.visible = true;
+    this._hidden.length = 0;
   }
 
   dispose() {
     for (const t of this._targets) t.dispose();
+    if (this._dummyVolumeTex) this._dummyVolumeTex.dispose();
   }
 }