three-realtime-rt 0.5.0 → 0.6.0

package/README.md

@@ -364,7 +364,7 @@ material of a group* row).
 | `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. |
@@ -383,7 +383,7 @@ material of a group* row).
 |-------|-----------|-------|
 | `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. |
@@ -397,8 +397,9 @@ material of a group* row).
   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
 
@@ -412,7 +413,7 @@ material of a group* row).
 
 - **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). 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. 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).
 
@@ -440,8 +441,9 @@ material of a group* row).
 | `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. |
-| `restirGI` | `false` | **Experimental.** ReSTIR GI (v1, temporal-only): per-pixel reservoirs reuse the 1-bounce indirect sample across frames at the reprojected same-surface point (no spatial reuse). 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; convergence character differs. `restirGIMCap` (default `20`) tunes the temporal M-cap. |
+| `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. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "three-realtime-rt",
-  "version": "0.5.0",
+  "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",

package/src/DenoisePass.js

@@ -40,9 +40,28 @@ float luminance(vec3 c) {
 }
 
 // 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) c.rgb += texture(uAddTex, uv).rgb;
+  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;
 }
 
@@ -90,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++) {