three-realtime-rt 0.4.2 → 0.6.0

package/README.md

@@ -182,6 +182,35 @@ Lighting is traced at half resolution by default and reconstructed by a joint
 bilateral upsample + the denoiser + TAA — the same "render few pixels, rebuild
 temporally" idea DLSS uses, done with hand-written math.
 
+### Debug views
+
+Set `rt.outputMode` (the demo's **view** dropdown) to inspect a single stage
+instead of the composited image:
+
+| Mode | View | Shows |
+|------|------|-------|
+| `0` | composite | Final tonemapped image (default). |
+| `1` | albedo | G-buffer base colour. |
+| `2` | normals | World-space normals, `×0.5 + 0.5`. |
+| `3` | irradiance | Demodulated diffuse lighting (direct + GI), pre-albedo. |
+| `4` | world pos | World position, `fract(p × 0.1)`. |
+| `5` | emissive | G-buffer emissive. |
+| `6` | specular | The dielectric specular buffer. |
+| `7` | **bvh cost** | Heatmap of how many BVH nodes this pixel's shadow rays visit. |
+
+**Reading the BVH-cost heatmap.** Mode 7 counts, per pixel, the total BVH nodes
+visited by every shadow ray the lighting pass casts that frame (the ReSTIR
+winner / stochastic / per-light rays, plus reflection and glass occlusion rays),
+and maps the count through a cold→hot palette: **blue is cheap** (few boxes),
+through green and yellow, to **red and white for the most expensive** pixels. Hot
+regions mean many box tests per shadow ray — dense or overlapping geometry, long
+thin triangles whose bounding boxes overlap wastefully, or rays skimming almost
+parallel to a surface (they thread a long corridor of the tree before they
+either hit or escape). It bypasses temporal blending and the denoiser, so it is a
+raw per-frame snapshot. `rt.costScale` sets the mapping (default `1/96`, so ~96
+visits saturate to white); the demo's **cost scale** slider drives it as
+"visits-to-saturate" so you can rescale the range to your scene.
+
 ## Moving objects (dynamic BVH)
 
 Mark meshes as dynamic and their motion casts **correct ray traced shadows** —
@@ -242,6 +271,48 @@ water plane) is O(dynamic tris) too — so **keep deforming meshes low-poly**. A
 `256×256` plane (~131k tris) will dominate the frame. The demo's mirror-water
 pool is a `48×48` plane.
 
+### Skinned meshes (animated characters)
+
+A `SkinnedMesh` is **auto-detected** — just list it in `dynamicMeshes` (no
+`userData` flag) and it is CPU-skinned into the dynamic BVH every frame, so an
+animated character casts a **traced shadow that moves with its gait** and
+rasterizes in its animated pose (not bind pose) in the G-buffer:
+
+```js
+rt.compileScene(scene, { dynamicMeshes: [...crates, foxMesh] }); // foxMesh.isSkinnedMesh
+
+// each frame:
+mixer.update(dt);                 // advance the AnimationMixer
+foxRoot.updateMatrixWorld(true);  // pose the skeleton (bones -> world matrices) NOW
+rt.updateDynamic();               // CPU-skins the live pose into the BVH
+rt.render(scene, camera);
+```
+
+- **Skin the pose before `updateDynamic()`.** The CPU skinning reads each bone's
+  `matrixWorld` (via three's `SkinnedMesh.applyBoneTransform` / `getVertexPosition`,
+  which apply the bind matrix, bone weights and bone matrices), so the skeleton
+  must be posed for this frame first. `mixer.update(dt)` then a forced
+  `updateMatrixWorld` on the character root does that — otherwise the traced
+  shadow lags the raster by a frame. (three r160's `applyBoneTransform` returns
+  the vertex in the mesh's **local/bind-relative** space; the tracer applies
+  `matrixWorld` itself, exactly like a rigid mover.)
+- **Two sampler-friendly shortcuts.** Skinning is done for the mesh's *unique*
+  source vertices once per frame (shared triangle-soup slots reuse the result),
+  and secondary-ray **normals are per-face** — recomputed from the skinned
+  triangle positions rather than CPU-skinning the normal attribute. Flat-shaded
+  secondary rays are indistinguishable for shadows/GI, and **primary visibility
+  still gets smooth normals from the raster path** (the G-buffer skins the normal
+  properly via three's own `skinnormal_vertex` chunk). If your character's
+  geometry ships without a `normal` attribute (some glTF do — e.g. the Khronos
+  Fox), call `geometry.computeVertexNormals()` once after load so the raster path
+  has bind-pose normals to skin.
+
+**Cost model.** CPU skinning is O(source verts × 4 bones) with zero per-vertex
+allocation, plus the usual O(dynamic tris) BVH refit and normal upload. Budget
+~**10–20k total skinned source vertices to stay sub-2 ms**; the demo's Fox is
+≈ 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.
+
 ## Live lighting & sky
 
 Lights can be toggled, moved, and recoloured every frame without recompiling:
@@ -281,9 +352,11 @@ the honest map of what actually feeds the traced lighting.
 
 ### Materials
 
-Lighting reads the **first material only** on a multi-material mesh, pulling the
-scalar fields of `MeshStandardMaterial` / `MeshPhysicalMaterial` (Basic / Lambert
-/ Phong contribute whatever of those fields they have).
+Lighting reads the scalar fields of `MeshStandardMaterial` / `MeshPhysicalMaterial`
+(Basic / Lambert / Phong contribute whatever of those fields they have). A
+**multi-material mesh** (`mesh.material` is an array + `geometry.groups`) now feeds
+**every group's** material into both the G-buffer and the BVH (see the *2nd+
+material of a group* row).
 
 | Property | Feeds lighting? | Notes |
 |----------|-----------------|-------|
@@ -291,7 +364,7 @@ scalar fields of `MeshStandardMaterial` / `MeshPhysicalMaterial` (Basic / Lamber
 | `roughness` | ✅ | Drives shadow / GI softness, reflection sharpness **and the GGX specular lobe width** (see *dielectric specular* below). |
 | `metalness` | ✅ | Metallic pixels trace a reflection ray whose analytic-light glints are shadowed; `F0 = mix(0.04, albedo, metalness)`. |
 | `emissive` | ✅ | A *static* emissive mesh becomes a real **area light** (NEE) — casts soft light + shadows, including a GGX highlight. |
-| `emissiveMap` | ⚠️ visible only | A map-masked emissive **glows on screen** but the map **zeroes its area-light table** — it lights nothing. Use a flat `emissive` colour (no map) for an emitter that should illuminate. |
+| `emissiveMap` | ✅ average-colour approximation | A map-masked emissive **glows on screen** with its full per-pixel pattern (G-buffer, untouched) **and now also casts light**: the CPU averages the map (`avg(map) × emissive × emissiveIntensity`) and feeds that single colour into the NEE area-light table. Needs a non-black `emissive` (white keeps the cast hue equal to the map average) and a readable image (a CORS-tainted / not-yet-decoded map falls back to visible-only, with a one-time `console.info`). A map that averages to **near-black** (e.g. a model's mostly-dark emissiveMap with a few tiny glowing texels) casts nothing — treated as visible-only so it doesn't flood the NEE list with a whole high-poly mesh. Texel-accurate (spatially-varying) emission is future work. |
 | `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. |
@@ -299,10 +372,10 @@ scalar fields of `MeshStandardMaterial` / `MeshPhysicalMaterial` (Basic / Lamber
 | `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` | ❌ | Not modelled. |
-| vertex colors | ❌ | Not read into albedo. |
-| per-material `ior` | ❌ | Refraction uses the single **global** `rt.ior` (default 1.5), never `material.ior`. |
-| 2nd+ material of a group | ❌ | Only `material[0]` of a multi-material mesh reaches the G-buffer and BVH. |
+| `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). |
+| 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). |
 
 ### Lights
 
@@ -310,7 +383,7 @@ scalar fields of `MeshStandardMaterial` / `MeshPhysicalMaterial` (Basic / Lamber
 |-------|-----------|-------|
 | `PointLight` | ✅ | `light.userData.rtRadius` (default `0.15`) sets soft-shadow size. |
 | `DirectionalLight` | ✅ | `light.userData.rtRadius` (default `0.02`) sets sun softness; keep its direction in sync with `sky.sunDir`. |
-| Emissive meshes | ✅ static | Sampled directly as area lights. **Dynamic** emitters are *not* in the NEE list — they light only via GI-ray hits. |
+| Emissive meshes | ✅ static + dynamic | Sampled directly as area lights (NEE). **Dynamic** emitters (a mesh in `dynamicMeshes`) are refreshed every `updateDynamic()`: their world-space triangles are re-derived from the freshly baked/skinned/deformed positions and their NEE rows + power CDF rewritten — a moving glowing orb sweeps real light across the floor. Keep them **low-poly** (refreshed per frame) and note the 256-tri cap is shared with static emitters. |
 | `SpotLight` | ✅ | Cone + penumbra respected; soft shadows via `rtRadius`; visible light cones in volumetric fog. |
 | `RectAreaLight` | ❌ | Use an emissive mesh instead. |
 | `HemisphereLight` / `AmbientLight` | ❌ | Ignored — the procedural `sky` (or `envColor`) provides ambient. |
@@ -324,8 +397,9 @@ scalar fields of `MeshStandardMaterial` / `MeshPhysicalMaterial` (Basic / Lamber
   bright ones, and let `fireflyClamp` do its job.
 - Up to **32** point/directional lights (`MAX_LIGHTS`); further lights are dropped.
 - Moving, toggling, recolouring or dimming a light → `rt.updateLights(scene)` (cheap, no recompile).
-- Changing a mesh's **emissive** (it's an area light baked at compile time) → `rt.compileScene(...)` again.
-- Emissive area lights are capped at **256 triangles** (largest by area kept, with a console warning) — prefer low-poly emitter meshes.
+- **Textured emitters** (`emissiveMap`) cast their **average** colour (`avg(map) × emissive × emissiveIntensity`), not per-texel — the sign still *looks* patterned in the G-buffer but lights with one averaged hue. Texel-accurate emission is future work.
+- **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.
 
 ### Geometry & occlusion
 
@@ -339,7 +413,7 @@ scalar fields of `MeshStandardMaterial` / `MeshPhysicalMaterial` (Basic / Lamber
 
 - **1-bounce GI + direct light.** No multi-bounce diffuse, no caustics, no specular-chain paths.
 - **Reflections** are a single traced bounce into a **diffuse-shaded** view of the world — no recursive mirror-in-mirror; a metal shows its surroundings, not a second full render.
-- **Refraction** is two-interface (front + back) with a single global IOR — convincing glass, not a spectral / dispersive renderer.
+- **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).
 
@@ -367,12 +441,15 @@ scalar fields of `MeshStandardMaterial` / `MeshPhysicalMaterial` (Basic / Lamber
 | `refraction` | `true` | Traced two-interface refraction for `MeshPhysicalMaterial.transmission` surfaces. |
 | `transparency` | `true` | Alpha-blended transparency: composite `transparent` meshes over the geometry behind them (single-layer, weighted by `opacity`, tinted by albedo). Needs the specular buffer (`specular: true`). Off = they render fully opaque. |
 | `restir` | `true` | ReSTIR direct lighting: per-pixel reservoirs with temporal + spatial reuse, one visibility ray regardless of light count. Flat cost in light count; cuts emissive area-light noise. |
-| `ior` | `1.5` | Index of refraction used by `refraction`. |
+| `restirGI` | `false` | **Experimental.** ReSTIR GI (v2, fused spatiotemporal): per-pixel reservoirs reuse the 1-bounce indirect sample across frames at the reprojected same-surface point, then take `restirGISpatialTaps` spatial taps (default `2`, `0` = v1 temporal-only) of the previous frame's reservoirs — each reweighted by the reconnection solid-angle→area Jacobian and validated by a final visibility ray so light does not leak through walls. Runs in a standalone pass with its own sampler budget; the lighting pass then skips its inline GI trace and the resolved GI is added at the à-trous denoise stage — so it only takes effect when `gi` **and** `denoise` are also on. Its mean matches the inline GI path; the spatial taps cut per-frame variance. `restirGIMCap` (default `20`) tunes the temporal M-cap. `restirGIValidate` (default `8`, `0` = off) sets the reservoir-sample validation period: each frame a rotating 1-in-N subset of pixels re-aims its single candidate ray at the reservoir's stored hit and re-shades it; if the geometry moved or the re-shaded target collapsed to near-black (a light switched off) the reservoir is killed so fresh candidates rebuild, otherwise it is left untouched. This reuses the existing candidate trace (no extra bounce rays) and is what makes a switched-off light stop haunting the reservoir instead of fading slowly, while a static scene stays put. |
+| `ior` | `1.5` | **Global fallback** index of refraction for `refraction`. A `MeshPhysicalMaterial.ior` overrides it per material (fully-transmissive glass, range [1.0, 1.98]); this value applies to partial-transmission glass and as the default. |
+| `dispersion` | `0` | Chromatic dispersion for glass, `0..0.5` (clamped). Splits refracted white light into a spectrum — a diamond throws a rainbow. Uses **stochastic spectral sampling**: each frame every glass pixel estimates one colour channel (R/G/B) through a channel-shifted ior and traces the *same single* refraction path, so it costs **no extra rays** and adds no traced-ray call site (it fits the Metal call-site budget). The three per-channel estimates are blended by the temporal accumulator, so the rainbow **only converges with accumulation on** and shimmers slightly in motion. **Global control** for now: three r160's `MeshPhysicalMaterial.dispersion` is not yet read per-material (no free G-buffer channel) — per-material dispersion is future work. |
 | `volumetric` | *off* | Physically-based god rays: single-scatter fog, one BVH-shadowed light sample per lighting pixel per frame, temporally accumulated. `{ enabled, density, maxDist, zones }`, where `zones` is an optional array of up to 8 AABBs `{ min:[x,y,z], max:[x,y,z], density }` that add localized fog on top of (or instead of) the global `density`. |
 | `stochasticLights` | `true` | One direct shadow ray per pixel per frame (random source) instead of one per light. The governor turns it off once it has scaled resolution up on strong hardware. |
 | `temporalReprojection` | `true` | Keep samples across camera/object motion. |
 | `maxHistory` | `128` | History cap — higher is smoother, slower to react. |
 | `fireflyClamp` | `4.0` | Clamp on indirect luminance to suppress fireflies. |
+| `costScale` | `1/96` | BVH-cost heatmap scale for the `outputMode: 7` debug view (shadow-ray node-visit count × this, mapped through a cold→hot palette). See *Debug views*. |
 | `sky` | *off* | Procedural sky as background + GI ambient (see above). |
 | `fog` | *off* | Distance fog, composited before tonemap. |
 
@@ -528,6 +605,69 @@ 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.
 
+## Render self-test
+
+The renderer can pass every compile and framebuffer check and still draw a black
+screen — that is exactly what shipped in 0.4.0 on iOS (WebKit's GLSL-to-Metal
+translation silently broke at a 4th `traceRadiance` call site; clean compile, no
+console error, black output). The only defence against that class of failure is
+to **look at the pixels**, so the demo has a headless-friendly self-test.
+
+**In the browser:** load [`/?selftest=1`](examples/selftest.js). It forces the
+full lighting stack on (GI + emissive NEE + reflections + refraction, lighting at
+50%), renders the normal gallery scene, and after **90 rendered frames** reads
+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,
+  "specMRT": true, "supported": true, "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` and `supported == true`.
+
+- `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
+  irradiance readback proves the **lighting** is alive, not just emissive geometry
+  surviving the composite (0.4.0's black image still showed emitters). A near-zero
+  reading is the black-screen class; the pass gate wants a lit mid-range value.
+- `glErrors` — count of nonzero `gl.getError()` samples (any nonzero fails).
+- `specMRT` / `supported` — the two capability fallbacks, for triage.
+
+The page keeps rendering after the verdict so a human can watch. This mode builds
+the renderer with `preserveDrawingBuffer: true` so the canvas can be read back;
+normal runs keep the cheaper default.
+
+**In CI:** `npm run test:render` ([`scripts/selftest.mjs`](scripts/selftest.mjs))
+starts vite on a free port and drives `?selftest=1` through Playwright across
+**chromium, firefox and webkit**, printing a pass/fail/skip table and exiting
+nonzero on any real failure (a documented environmental *skip* does not fail the
+suite). Playwright is loaded from a sibling checkout — see the top of the script.
+
+Machine-specific note (Windows + NVIDIA, the current dev box): the chromium leg
+runs **headed** with **`--use-angle=gl`**. ANGLE's default D3D11/FXC backend
+never finishes compiling the BVH megakernel here — headless chromium,
+headed+`--use-angle=d3d11` and system Chrome all freeze at ~3 frames with silent
+`VALIDATE_STATUS=false` storms — whereas the native NVIDIA GL backend compiles
+it in ~137ms. A visible chromium window on the desktop during the run is
+expected. On this box **firefox** and **webkit** come back `skip`: firefox
+renders through that same stalling ANGLE-D3D11 backend and exposes no native-GL
+switch, and Playwright's Windows webkit has no usable WebGL2 (context lost). Both
+would actually run on a real-GPU Linux runner with native GL; only chromium is
+required to pass here.
+
+**What this catches, and what it does not.** The matrix catches API / JavaScript
+/ GLSL-frontend divergence between engines, and any regression that blackens or
+errors the image on the engines it runs. It does **not** catch the original iOS
+bug: Playwright's `webkit` on Windows is the WPE/GTK WebKit build, **not Apple's
+Metal stack**, so it never exercises the GLSL-to-Metal code generator that
+actually failed. **Real-device iOS testing stays manual.** The field kit for that
+is on-device URL flags: `?diag=1` mirrors console errors onto the page (so a
+photo of an iPad is a usable bug report) and `?nospecmrt=1` forces the
+single-attachment WebKit fallback on any machine.
+
 ## Roadmap
 
 | Stage | Status | What |
@@ -543,7 +683,10 @@ is **feature-detected** — it appears only when the loaded build exposes an
 | 6b. Sampling | ✅ | Blue-noise sampling + ReSTIR direct lighting (temporal + spatial reuse) |
 | 6c. Any-hit shadows | ✅ | Unordered early-out BVH traversal for occlusion rays — same image, up to ~2× cheaper shadows |
 | 6d. PBR materials | ✅ | Cook-Torrance GGX dielectric specular + normal/roughness/metalness maps, alpha-blended transparency, deforming (water) meshes, overscan |
-| 7. Next | — | Skinned-mesh (animated) shadows; DDGI irradiance probes; ReSTIR GI (indirect reservoir reuse); WGSL / WebGPU backend; per-material IOR |
+| 6e. Skinned meshes | ✅ | Animated characters CPU-skinned into the dynamic BVH — moving traced shadows + animated raster pose |
+| 6f. Material completeness | ✅ | Vertex colors, per-material IOR, multi-material groups (clearcoat/sheen/iridescence documented as out of G-buffer budget) |
+| 6g. ReSTIR GI | 🧪 | **Experimental** (`restirGI`, off by default): temporal-only reservoir reuse of the 1-bounce indirect sample (v1 — no spatial reuse yet) |
+| 7. Next | — | DDGI irradiance probes; ReSTIR GI **spatial** reuse + sample validation; WGSL / WebGPU backend |
 
 ## Credits
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "three-realtime-rt",
-  "version": "0.4.2",
+  "version": "0.6.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",
@@ -17,6 +17,7 @@
     "dev": "vite",
     "build": "vite build",
     "preview": "vite preview",
+    "test:render": "node scripts/selftest.mjs",
     "deploy": "vite build && gh-pages -d dist -t"
   },
   "keywords": [

package/src/CompositePass.js

@@ -30,7 +30,9 @@ uniform vec2 uVolTexelSize;
 uniform bool uVolEnabled;
 uniform vec3 uBackgroundColor;
 // 0 composite, 1 albedo, 2 normal, 3 irradiance (direct+GI), 4 worldPos,
-// 5 emissive, 6 specular
+// 5 emissive, 6 specular, 7 bvh cost (heatmap of shadow-ray node visits — the
+// lighting pass wrote the palette into the irradiance buffer, so it shares the
+// mode-3 display path)
 uniform int uOutputMode;
 
 // joint bilateral upsample (lighting may be rendered below full resolution)
@@ -177,7 +179,9 @@ void main() {
 
   if (uOutputMode == 1) color = albedoRough.rgb;
   else if (uOutputMode == 2) color = N * 0.5 + 0.5;
-  else if (uOutputMode == 3) color = irradiance;
+  // 3 = irradiance, 7 = bvh cost heatmap: both live in the irradiance buffer
+  // (the lighting pass wrote the cost palette there when uCostView was on).
+  else if (uOutputMode == 3 || uOutputMode == 7) color = irradiance;
   else if (uOutputMode == 4) color = fract(wp.xyz * 0.1);
   else if (uOutputMode == 5) color = emissive;
   else if (uOutputMode == 6) color = specular;

package/src/DenoisePass.js

@@ -25,12 +25,48 @@ uniform float uEps;
 uniform float uLumSigma;
 uniform bool uBlendIsSpec;       // this instance filters the specular buffer
 
+// Optional additive input (EXPERIMENTAL ReSTIR GI): when uHasAdd is set, this
+// texture's rgb is ADDED to every irradiance tap so the à-trous filter smooths
+// the sum (the GI is injected here, downstream of the lighting pass's own
+// temporal history, so it never double-counts through that history). The add is
+// gated to the FIRST iteration by the caller (uStep == 1) — later iterations
+// read the already-summed result. When uHasAdd is false this is byte-identical
+// to the original filter (the alpha/history-count channel is never touched).
+uniform sampler2D uAddTex;
+uniform bool uHasAdd;
+
 float luminance(vec3 c) {
   return dot(c, vec3(0.299, 0.587, 0.114));
 }
 
+// Irradiance tap with the optional GI add folded into rgb (alpha untouched).
+// METAL DIFFUSE WEIGHT: the GI add is DIFFUSE indirect irradiance. Metals have
+// essentially no diffuse response — their indirect light rides the traced
+// REFLECTION path — so their diffuse weight is (1 - metalness). RTLightingPass
+// applies this implicitly to the inline GI: sampleIrr = mix(direct + indirect,
+// reflRad, metal), scaling inline indirect by (1 - metal) on metals. The
+// external ReSTIR GI add is injected HERE, downstream of that mix, so it never
+// picked up the weight — a metalness-0.85 surface (the gold torus knot) received
+// full-strength diffuse GI, ~6.6x too much. That excess is not just too bright:
+// it is the ReSTIR resolve's residual per-pixel variance at full amplitude,
+// which reads as bright gold speckles on the curved metal (worst on iOS/Metal,
+// where the firefly stack has the least headroom). Re-apply the same
+// (1 - metalness) diffuse weight to the add so the two GI paths are energy-
+// consistent on metals and the speckle amplitude drops with the mean. Packed
+// metal word (GBufferPass): metalness lives in [0,1]; glass [2,4) and alpha
+// blend [4,5] are non-metal (weight 1, unchanged from before).
+vec4 sampleIrr(vec2 uv) {
+  vec4 c = texture(uIrradiance, uv);
+  if (uHasAdd) {
+    float mw = texture(uGNormalMetal, uv).w;
+    float metalT = mw < 2.0 ? clamp(mw, 0.0, 1.0) : 0.0;
+    c.rgb += texture(uAddTex, uv).rgb * (1.0 - metalT);
+  }
+  return c;
+}
+
 void main() {
-  vec4 center = texture(uIrradiance, vUv);
+  vec4 center = sampleIrr(vUv);
   vec4 wp = texture(uGWorldPos, vUv);
   if (wp.w < 0.5) {
     outColor = center;
@@ -73,7 +109,12 @@ void main() {
   // business being brighter than its entire neighbourhood — clamp its
   // luminance to the brightest neighbour. Converged pixels are exempt, so
   // real small highlights survive.
-  if (uStep < 1.5 && count < 8.0) {
+  // With an additive GI input (uHasAdd) the despeckle must ALWAYS run on the
+  // first iteration: count is the LIGHTING buffer's history depth and says
+  // nothing about the GI term, which is re-resolved fresh every frame — a GI
+  // firefly at a "converged" pixel would otherwise skip this clamp entirely
+  // and survive to the screen (observed as white speckles on iOS).
+  if (uStep < 1.5 && (count < 8.0 || uHasAdd)) {
     float maxL = 0.0;
     float found = 0.0;
     for (int dy = -1; dy <= 1; dy++) {
@@ -82,7 +123,7 @@ void main() {
         vec2 tuv = vUv + vec2(float(dx), float(dy)) * uTexelSize;
         if (tuv.x < 0.0 || tuv.x > 1.0 || tuv.y < 0.0 || tuv.y > 1.0) continue;
         if (texture(uGWorldPos, tuv).w < 0.5) continue;
-        maxL = max(maxL, luminance(texture(uIrradiance, tuv).rgb));
+        maxL = max(maxL, luminance(sampleIrr(tuv).rgb));
         found = 1.0;
       }
     }
@@ -104,7 +145,7 @@ void main() {
 
       vec4 g = texture(uGWorldPos, tuv);
       if (g.w < 0.5) continue;
-      vec4 s = texture(uIrradiance, tuv);
+      vec4 s = sampleIrr(tuv);
       vec3 Nt = normalize(texture(uGNormalMetal, tuv).xyz);
 
       float k = (dx == 0 || dy == 0) ? 2.0 : 1.0;
@@ -154,6 +195,8 @@ export class DenoisePass {
         uEps: { value: 1e-3 },
         uLumSigma: { value: 0.25 },
         uBlendIsSpec: { value: blendIsSpec },
+        uAddTex: { value: null },
+        uHasAdd: { value: false },
       },
       depthTest: false,
       depthWrite: false,
@@ -189,20 +232,29 @@ export class DenoisePass {
     this.targetB.setSize(width, height);
   }
 
-  /** Runs `iterations` à-trous passes; returns the final filtered texture. */
-  render(renderer, inputTexture, gbuffer, cameraPos, eps, iterations = 3) {
+  /**
+   * Runs `iterations` à-trous passes; returns the final filtered texture.
+   * `addTexture` (EXPERIMENTAL ReSTIR GI) is added to the input on the FIRST
+   * iteration only, so the filter smooths input + GI together; pass null to
+   * leave the filter byte-identical to before.
+   */
+  render(renderer, inputTexture, gbuffer, cameraPos, eps, iterations = 3, addTexture = null) {
     const u = this.material.uniforms;
     u.uGWorldPos.value = gbuffer.worldPos;
     u.uGNormalMetal.value = gbuffer.normalMetal;
     u.uTexelSize.value.set(1 / this._width, 1 / this._height);
     u.uCameraPos.value.copy(cameraPos);
     u.uEps.value = eps;
+    u.uAddTex.value = addTexture;
 
     let read = inputTexture;
     let write = this.targetA;
     for (let i = 0; i < iterations; i++) {
       u.uIrradiance.value = read;
       u.uStep.value = 1 << i;
+      // The GI add is applied once, on iteration 0 — later iterations read the
+      // already-summed intermediate, so adding again would double it.
+      u.uHasAdd.value = addTexture !== null && i === 0;
       renderer.setRenderTarget(write);
       renderer.render(this.scene, this.camera);
       read = write.texture;