three-realtime-rt 0.4.2 → 0.6.0

package/src/RTLightingPass.js

@@ -66,6 +66,7 @@ uniform bool uReflEnabled;  // traced reflections on metallic surfaces
 uniform bool uRefrEnabled;  // traced refraction on transmissive surfaces
 uniform bool uBlendEnabled; // straight-through view continuation on blend surfaces
 uniform float uIor;         // index of refraction for transmissive materials
+uniform float uDispersion;  // chromatic dispersion strength for glass (0 = off)
 uniform bool uLightStochastic; // 1 direct shadow ray/pixel/frame instead of 1/light
 uniform bool uRestirEnabled;   // shade the reservoir winner instead of sampling
 uniform bool uGIHalfRate;      // GI ray on alternating checkerboard, doubled
@@ -75,6 +76,18 @@ uniform float uEnvIntensity;
 uniform float uFrame;
 uniform float uEps;
 uniform bool uGIEnabled;
+// EXPERIMENTAL: when an external ReSTIR GI pass supplies the 1-bounce indirect
+// (added downstream at the denoise stage), skip the inline GI trace so it isn't
+// counted twice. A uniform, NOT a sampler — the lighting pass is already at the
+// WebGL2 16-sampler minimum and cannot take another.
+uniform bool uExternalGI;
+
+// BVH traversal-cost heatmap (outputMode 7). When uCostView is on, main() writes
+// the per-pixel shadow-ray node-visit count (gBvhVisits, from bvhAnyHit.glsl.js)
+// through costPalette() into the irradiance attachment INSTEAD of the accumulated
+// lighting — bypassing temporal blending — so the debug view reads the raw cost.
+uniform bool uCostView;
+uniform float uCostScale; // multiplies the visit count before the palette (default 1/96)
 
 // Procedural sky (when enabled, replaces the flat env colour as the "miss" term
 // for GI rays — this is what gives natural outdoor bounce light).
@@ -464,7 +477,8 @@ vec3 sampleOneAny(vec3 P, vec3 N) {
 // Incoming radiance along rd: trace, shade the hit with direct + NEE lighting,
 // sky/env on a miss. Specular rays keep emitter emission on hit (NEE at the ray
 // origin cannot cover a specular path); diffuse GI rays drop it for NEE-listed
-// (static) emitters so that light isn't counted twice.
+// emitters (static AND dynamic — dynamic emitters now join the NEE table, their
+// rows refreshed each frame) so that light isn't counted twice.
 vec3 traceRadiance(vec3 ro, vec3 rd, bool specular) {
   uvec4 fi; vec3 bary; float dist; bool isDyn;
   if (!traceBoth(ro, rd, fi, bary, dist, isDyn)) {
@@ -481,7 +495,7 @@ vec3 traceRadiance(vec3 ro, vec3 rd, bool specular) {
   if (dot(hN, rd) > 0.0) hN = -hN;
   vec3 hP = ro + rd * dist;
   vec3 Ld = sampleOneAny(hP + hN * uEps, hN);
-  vec3 hLe = (!specular && uEmissiveCount > 0 && !isDyn) ? vec3(0.0) : hEmissive;
+  vec3 hLe = (!specular && uEmissiveCount > 0) ? vec3(0.0) : hEmissive;
   return hLe + hAlbedo * Ld * (1.0 / PI);
 }
 
@@ -541,16 +555,66 @@ vec3 analyticGlint(vec3 P, vec3 refl) {
 
 // Glass: Fresnel-weighted blend of a surface reflection and a two-interface
 // refraction (enter at P, march to the exit surface, refract again).
-vec3 glassRadiance(vec3 P, vec3 N, vec3 V, float rough) {
+//
+// CHROMATIC DISPERSION (stochastic spectral sampling). Real glass has a
+// wavelength-dependent ior, so white light splits into a spectrum (a diamond
+// throws a rainbow). Tracing one refraction path per colour would cost three
+// traceRadiance calls, but the Metal call-site budget (see the note at the
+// unified secondary-ray site) forbids a fourth traceRadiance anywhere in this
+// shader. Instead, when uDispersion > 0 each frame this pixel picks ONE colour
+// channel c in R,G,B uniformly and traces the SAME single refraction path with
+// a channel-shifted ior. The refracted radiance is then isolated to channel c
+// and multiplied by 3 (to compensate the 1-of-3 pick); the temporal EMA
+// averages the three per-channel estimates into a full-spectrum, dispersed
+// refraction — zero extra rays, zero new call sites, unbiased in the mean. It
+// therefore shimmers slightly while converging.
+//
+// THE MIX SPLIT. The return is mix(refrRad, reflRad, fres) = refrRad*(1-fres)
+// + reflRad*fres. Only the TRANSMITTED half (refrRad) carries the channel
+// mask; the reflection half (reflRad) is NOT dispersed and stays full colour
+// EVERY frame. To keep the reflection deterministic frame-to-frame, the
+// Fresnel weight is taken from the BASE ior (constant), not the channel-shifted
+// ior — only the refracted ray DIRECTION disperses, so the reflection term
+// reflRad*fres is identical every frame while refrRad*mask*3 is the spectral
+// estimator.
+//
+// OFF-PATH IDENTITY. uDispersion == 0 skips the channel pick entirely: it
+// consumes NO rand() (so the RNG stream does not shift), leaves iorC == ior and
+// chanMask == vec3(1), and the whole function reduces byte-for-byte to the
+// pre-dispersion path.
+vec3 glassRadiance(vec3 P, vec3 N, vec3 V, float rough, float ior) {
   vec3 refl = glossyReflect(V, N, rough);
   vec3 reflRad = dot(refl, N) > 0.0
     ? traceRadiance(P + N * uEps, refl, true) + analyticGlint(P, refl)
     : vec3(0.0);
 
-  float eta = 1.0 / uIor;
+  // Per-frame spectral channel pick for the transmitted term (guarded so the
+  // off path consumes no rand()).
+  vec3 chanMask = vec3(1.0); // full colour (un-masked) when dispersion is off
+  float iorC = ior;
+  if (uDispersion > 0.0) {
+    int c = min(int(rand() * 3.0), 2); // uniform channel: 0 = R, 1 = G, 2 = B
+    // Normal dispersion: BLUE has the higher refractive index and bends most,
+    // red least. shift = (-1.0, 0.0, +1.0) * 0.5, indexed by channel:
+    // R = -0.5, G = 0, B = +0.5. uDispersion (0..0.5) scales the ior spread.
+    // (The original spec vector had the R/B signs reversed — audit-corrected.)
+    float shift = c == 0 ? -0.5 : (c == 2 ? 0.5 : 0.0);
+    iorC = ior * (1.0 + uDispersion * shift);
+    // Isolate channel c and weight x3: vec3(3,0,0) / (0,3,0) / (0,0,3). The
+    // mean over the three equally-likely picks is (1/3)(3,0,0)+... = (1,1,1),
+    // so E[masked refrRad] == refrRad. The OTHER channels are zero this frame.
+    chanMask = c == 0 ? vec3(3.0, 0.0, 0.0)
+             : c == 1 ? vec3(0.0, 3.0, 0.0)
+                      : vec3(0.0, 0.0, 3.0);
+  }
+
+  float eta = 1.0 / iorC;                 // channel-shifted: drives the refraction bend
   vec3 rd = refract(V, N, eta);
-  if (rd == vec3(0.0)) return reflRad; // total internal reflection at entry
-  float fres = schlick(clamp(-dot(V, N), 0.0, 1.0), eta);
+  if (rd == vec3(0.0)) return reflRad;    // total internal reflection at entry
+  // Fresnel from the BASE ior so the reflection/refraction split is the same
+  // every frame (reflection stays full colour and un-dispersed). Equal to the
+  // original schlick(..., eta) when uDispersion == 0 (iorC == ior).
+  float fres = schlick(clamp(-dot(V, N), 0.0, 1.0), 1.0 / ior);
 
   vec3 ro = P - N * (2.0 * uEps);
   vec3 refrRad;
@@ -563,7 +627,7 @@ vec3 glassRadiance(vec3 P, vec3 N, vec3 V, float rough) {
     vec3 xN = normalize(attr.xyz);
     if (dot(xN, rd) > 0.0) xN = -xN;
     vec3 xP = ro + rd * dist;
-    vec3 rd2 = refract(rd, xN, uIor);
+    vec3 rd2 = refract(rd, xN, iorC);     // same channel-shifted ior on exit
     if (rd2 == vec3(0.0)) rd2 = reflect(rd, xN);
     refrRad = traceRadiance(xP - xN * uEps, rd2, true);
   } else {
@@ -571,7 +635,29 @@ vec3 glassRadiance(vec3 P, vec3 N, vec3 V, float rough) {
       ? skyColor(rd, uSunDir, uSunColor, uSkyZenith, uSkyHorizon, uSkyIntensity)
       : uEnvColor * uEnvIntensity;
   }
-  return mix(refrRad, reflRad, fres);
+  // Mask ONLY the transmitted term to the chosen channel (full colour when
+  // dispersion is off); the reflection term is never masked.
+  return mix(refrRad * chanMask, reflRad, fres);
+}
+
+// Compact cold->hot ramp for the BVH-cost heatmap. Piecewise mix of five
+// anchors (deep blue -> green -> yellow -> red -> white) over four equal
+// segments — cheap, no textures, no extra samplers. t is the normalised cost
+// (visit count * uCostScale), clamped to [0,1]; saturating at white = the most
+// expensive pixels.
+vec3 costPalette(float t) {
+  t = clamp(t, 0.0, 1.0);
+  const vec3 c0 = vec3(0.02, 0.05, 0.45); // cold: cheap (few boxes)
+  const vec3 c1 = vec3(0.05, 0.55, 0.25); // green
+  const vec3 c2 = vec3(0.95, 0.85, 0.10); // yellow
+  const vec3 c3 = vec3(0.90, 0.10, 0.05); // red
+  const vec3 c4 = vec3(1.00, 1.00, 1.00); // hot: expensive (many boxes)
+  float s = t * 4.0;
+  vec3 col = mix(c0, c1, clamp(s, 0.0, 1.0));
+  col = mix(col, c2, clamp(s - 1.0, 0.0, 1.0));
+  col = mix(col, c3, clamp(s - 2.0, 0.0, 1.0));
+  col = mix(col, c4, clamp(s - 3.0, 0.0, 1.0));
+  return col;
 }
 
 void main() {
@@ -599,6 +685,10 @@ void main() {
   float transmission = (matW >= 2.0 && matW < 4.0) ? clamp(matW - 2.0, 0.0, 1.0) : 0.0;
   float metal = matW < 2.0 ? matW : 0.0;
   float rough = clamp(wp.w - 1.0, 0.0, 1.0);
+  // Per-material IOR rides the [3,4) glass sub-band (full-transmission glass, see
+  // GBufferPass). Below 3 (partial glass) or non-glass, fall back to the global
+  // rt.ior uniform. material.ior wins whenever it was encoded. (Task 2)
+  float ior = (matW >= 3.0 && matW < 4.0) ? (1.0 + (matW - 3.0)) : uIor;
 
   // Cook-Torrance specular state for this primary surface. gWantSpec gates the
   // GGX term to PRIMARY direct lighting only (GI-bounce direct light, below,
@@ -608,6 +698,11 @@ void main() {
   gSpecRough = rough;
   gWantSpec = true;
 
+  // Reset the shadow-ray traversal-cost counter for this pixel. It accumulates
+  // across every occluded() call below (direct, GI, reflection, glass) and is
+  // read once at the end when uCostView is on (see the cost-heatmap branch).
+  gBvhVisits = 0;
+
   // --- direct lighting ---
   // ReSTIR: shade the reservoir's winner with one visibility ray (flat cost in
   // light count). Stochastic: one blind random sample. Full: one shadow ray
@@ -646,7 +741,10 @@ void main() {
   vec3 indirect = vec3(0.0);
   vec3 blendBehind = vec3(0.0);
   bool wantBehind = uBlendEnabled && blend;
-  bool wantGI = uGIEnabled && !wantBehind
+  // uExternalGI (experimental ReSTIR GI): the GIReservoirPass supplies the
+  // bounce, so the inline GI ray is skipped — but the blend continuation is
+  // NOT GI and must keep tracing regardless.
+  bool wantGI = uGIEnabled && !uExternalGI && !wantBehind
     && (!uGIHalfRate || (((px.x + px.y + int(uFrame)) & 1) == 0));
   if (wantBehind || wantGI) {
     vec3 Vv = normalize(P - uCameraPos);
@@ -685,7 +783,7 @@ void main() {
   // --- traced glass: Fresnel reflection + two-interface refraction ---
   if (uRefrEnabled && transmission > 0.001) {
     vec3 V = normalize(P - uCameraPos);
-    sampleIrr = mix(sampleIrr, glassRadiance(P, N, V, rough), transmission);
+    sampleIrr = mix(sampleIrr, glassRadiance(P, N, V, rough, ior), transmission);
   }
 
   // --- alpha blend: straight-through view continuation ---
@@ -772,6 +870,17 @@ void main() {
   // the fresh sample is used as-is.
   vec3 blended = mix(history, sampleIrr, 1.0 / count);
   outIrradiance = vec4(blended, count);
+
+  // BVH traversal-cost heatmap (outputMode 7). Overwrite the accumulated
+  // lighting with the palette-mapped shadow-ray node-visit count for this pixel.
+  // Alpha is forced to 1.0 so temporal history never builds on the cost image
+  // (each frame is a fresh snapshot), and the specular attachment is cleared so
+  // the composite's cost branch shows the palette alone. Uniform branch: when
+  // uCostView is off this is skipped and the writes above stand unchanged.
+  if (uCostView) {
+    outIrradiance = vec4(costPalette(float(gBvhVisits) * uCostScale), 1.0);
+    outSpecular = vec4(0.0);
+  }
 }
 `;
 
@@ -923,6 +1032,7 @@ export class RTLightingPass {
         uRefrEnabled: { value: true },
         uBlendEnabled: { value: true },
         uIor: { value: 1.5 },
+        uDispersion: { value: 0 },
         uLightStochastic: { value: false },
         uGIHalfRate: { value: false },
         uEnvColor: { value: new THREE.Color(0.03, 0.04, 0.06) },
@@ -930,6 +1040,9 @@ export class RTLightingPass {
         uFrame: { value: 0 },
         uEps: { value: 1e-3 },
         uGIEnabled: { value: true },
+        uExternalGI: { value: false },
+        uCostView: { value: false },
+        uCostScale: { value: 1 / 96 },
         uSkyEnabled: { value: false },
         uSunDir: { value: new THREE.Vector3(0.4, 0.8, 0.45).normalize() },
         uSunColor: { value: new THREE.Color(1.0, 0.9, 0.75) },

package/src/RealtimeRaytracer.js

@@ -7,6 +7,7 @@ import { CompositePass } from "./CompositePass.js";
 import { TAAPass } from "./TAAPass.js";
 import { VolumetricPass } from "./VolumetricPass.js";
 import { RestirPass } from "./RestirPass.js";
+import { GIReservoirPass } from "./GIReservoirPass.js";
 import { CopyPass } from "./CopyPass.js";
 
 // Van der Corput / Halton radical inverse — deterministic low-discrepancy
@@ -423,8 +424,15 @@ uniform sampler2D uTex; void main(){ outColor = texture(uTex, vUv); }`,
     this.compiled = null;
     this.frame = 0;
 
-    /** Debug view: 0 composite, 1 albedo, 2 normal, 3 irradiance, 4 worldPos, 5 emissive, 6 specular */
+    /** Debug view: 0 composite, 1 albedo, 2 normal, 3 irradiance, 4 worldPos, 5 emissive, 6 specular, 7 bvh cost */
     this.outputMode = 0;
+    /**
+     * BVH-cost heatmap scale (outputMode 7): the per-pixel shadow-ray node-visit
+     * count is multiplied by this before the palette, so 1/costScale visits map
+     * to the hot (white) end. Default 1/96 — ~96 visits saturate. Live-tunable
+     * (the demo's "cost scale" slider drives it).
+     */
+    this.costScale = options.costScale ?? 1 / 96;
     /** Environment (sky) color used for GI rays that miss + composite background. */
     this.envColor = options.envColor ?? new THREE.Color(0.03, 0.04, 0.06);
     this.envIntensity = options.envIntensity ?? 1.0;
@@ -484,6 +492,17 @@ uniform sampler2D uTex; void main(){ outColor = texture(uTex, vUv); }`,
     this.transparency = options.transparency ?? true;
     /** Index of refraction used for transmissive surfaces. */
     this.ior = options.ior ?? 1.5;
+    /**
+     * Chromatic dispersion strength for glass (0..0.5, clamped on upload,
+     * default 0 = off). Splits refracted white light into a spectrum: each
+     * frame every glass pixel estimates ONE colour channel through a
+     * channel-shifted ior and the temporal accumulator blends the three into a
+     * rainbow (stochastic spectral sampling — no extra rays). It shimmers
+     * slightly while converging, so it needs temporal accumulation to settle.
+     * Global control only for now (there is no free G-buffer channel for a
+     * per-material MeshPhysicalMaterial.dispersion).
+     */
+    this.dispersion = options.dispersion ?? 0;
     /**
      * One stochastic direct shadow ray per pixel per frame (source picked at
      * random) instead of one per light — the biggest ray-count lever for
@@ -552,6 +571,13 @@ uniform sampler2D uTex; void main(){ outColor = texture(uTex, vUv); }`,
     this.taa = options.taa ?? true;
     /** Fresh-sample weight in the TAA blend (lower = smoother/more AA, more lag). */
     this.taaBlend = options.taaBlend ?? 0.1;
+    /**
+     * Scales the TAA sub-pixel jitter amplitude. Set this to your canvas scale
+     * when you render a reduced drawing buffer CSS-stretched to the screen
+     * (canvasScaleHook), so the jitter stays constant in SCREEN pixels instead
+     * of being magnified by the stretch (visible wobble at low quality).
+     */
+    this.taaJitterScale = options.taaJitterScale ?? 1;
 
     /**
      * Volumetric lighting — real "god rays": single-scatter fog integrated
@@ -582,6 +608,45 @@ uniform sampler2D uTex; void main(){ outColor = texture(uTex, vUv); }`,
     this.restir = options.restir ?? true;
     this.restirPass = new RestirPass(this._scaledW, this._scaledH);
 
+    /**
+     * EXPERIMENTAL — ReSTIR GI (v1, temporal-only): per-pixel reservoirs reuse
+     * the 1-bounce global-illumination sample across frames (at the reprojected
+     * same-surface point, no spatial reuse / no Jacobian). Runs in a standalone
+     * pass with its own sampler budget; when on, the lighting pass skips its
+     * inline GI trace and this pass's resolved GI is added at the denoise stage.
+     * Only meaningful when `gi` is on, and injected via the à-trous denoise, so
+     * it requires `denoise` (denoiseIterations >= 1). Default OFF. Its mean
+     * matches the inline GI path — see GIReservoirPass. Live-toggleable.
+     */
+    this.restirGI = options.restirGI ?? false;
+    /** Temporal M-cap for the ReSTIR GI reservoir (staleness limit). */
+    this.restirGIMCap = options.restirGIMCap ?? 20;
+    /**
+     * ReSTIR GI (v2) spatial-reuse taps per frame, taken after the temporal
+     * merge from the previous frame's reservoirs (reconnection-Jacobian
+     * reweighted, with a final visibility ray). Clamped to 0..4; `0` reproduces
+     * the v1 temporal-only behaviour. Default 2.
+     */
+    // Default 1 (not 2): each reconnection tap adds its own estimator noise;
+    // one tap keeps most of the disocclusion win at half the artifact surface
+    // (tuned on-device — raise it for scenes with heavy camera motion).
+    this.restirGISpatialTaps = options.restirGISpatialTaps ?? 1;
+    /**
+     * EXPERIMENTAL — ReSTIR GI reservoir-sample validation period. Every frame a
+     * rotating 1-in-N subset of pixels (decorrelated by a per-pixel hash) re-aims
+     * its ONE candidate ray at the reservoir's STORED hit instead of a fresh
+     * cosine bounce and re-shades it; the reservoir is killed (so fresh candidates
+     * rebuild) when the geometry moved or the re-shaded target collapsed to
+     * near-black (a light switched off), and left untouched otherwise. This reuses
+     * the existing candidate trace (no extra bounce rays) and is the fix for stale
+     * bounce light: a switched-off light stops haunting the reservoir instead of
+     * fading slowly, while a static scene does not drift. `0` disables it
+     * (byte-identical to before the feature); default 8.
+     */
+    this.restirGIValidate = options.restirGIValidate ?? 8;
+    this.giReservoirPass = new GIReservoirPass(this._scaledW, this._scaledH);
+    this._giMissWarned = false;
+
     /** Distance fog (composited in linear space before tonemap). */
     this.fog = {
       enabled: options.fog?.enabled ?? false,
@@ -703,6 +768,7 @@ uniform sampler2D uTex; void main(){ outColor = texture(uTex, vUv); }`,
     this.rtPass.setCompiledScene(this.compiled);
     this.volumetricPass.setCompiledScene(this.compiled);
     this.restirPass.setCompiledScene(this.compiled);
+    this.giReservoirPass.setCompiledScene(this.compiled);
     this.resetAccumulation();
     return this.compiled;
   }
@@ -728,6 +794,7 @@ uniform sampler2D uTex; void main(){ outColor = texture(uTex, vUv); }`,
     this.rtPass.setCompiledScene(this.compiled);
     this.volumetricPass.setCompiledScene(this.compiled);
     this.restirPass.setCompiledScene(this.compiled);
+    this.giReservoirPass.setCompiledScene(this.compiled);
   }
 
   resetAccumulation() {
@@ -831,6 +898,11 @@ uniform sampler2D uTex; void main(){ outColor = texture(uTex, vUv); }`,
       // clear them.
       this.restirPass.setSize(sw, sh);
       this.restirPass.clearHistory(this.renderer);
+      // Reservoir GI history is packed (hit position + M + radiance + W) —
+      // invalid to linearly resample — but reconverges in a few frames, so
+      // reallocate and clear like the DI reservoirs.
+      this.giReservoirPass.setSize(sw, sh);
+      this.giReservoirPass.clearHistory(this.renderer);
     }
 
     // Full-res / canvas-res targets: only touched on a real canvas resize (a
@@ -976,8 +1048,15 @@ uniform sampler2D uTex; void main(){ outColor = texture(uTex, vUv); }`,
     // too — otherwise the raw buffers visibly shake.
     if (this.taa && this.outputMode === 0) {
       this._jitterIndex = (this._jitterIndex + 1) % 16;
-      const jx = (halton(this._jitterIndex + 1, 2) - 0.5) * 2 / this._width;
-      const jy = (halton(this._jitterIndex + 1, 3) - 0.5) * 2 / this._height;
+      // taaJitterScale: when the app renders a REDUCED drawing buffer and CSS-
+      // stretches it to the screen (the canvas-scale ladder), a half-buffer-pixel
+      // jitter is magnified by the stretch and reads as visible screen wobble.
+      // The app sets this to its canvas scale (see canvasScaleHook) so the
+      // jitter stays constant in SCREEN pixels — slightly less sub-pixel AA
+      // coverage at low canvas scales, in exchange for a steady image.
+      const js = this.taaJitterScale;
+      const jx = (halton(this._jitterIndex + 1, 2) - 0.5) * 2 * js / this._width;
+      const jy = (halton(this._jitterIndex + 1, 3) - 0.5) * 2 * js / this._height;
       proj.elements[8] += jx;
       proj.elements[9] += jy;
       // Where this jitter moves the image, in UV space: elements[8/9] multiply
@@ -999,6 +1078,7 @@ uniform sampler2D uTex; void main(){ outColor = texture(uTex, vUv); }`,
       this.rtPass.clearHistory(this.renderer);
       this.volumetricPass.clearHistory(this.renderer);
       this.restirPass.clearHistory(this.renderer);
+      this.giReservoirPass.clearHistory(this.renderer);
       this._needsClear = false;
     }
 
@@ -1010,17 +1090,35 @@ uniform sampler2D uTex; void main(){ outColor = texture(uTex, vUv); }`,
     rtU.uEnvColor.value.copy(this.envColor);
     rtU.uEnvIntensity.value = this.envIntensity;
     rtU.uEps.value = this.eps;
+    rtU.uCostView.value = this.outputMode === 7;
+    rtU.uCostScale.value = this.costScale;
     rtU.uTemporalReprojection.value = this.temporalReprojection;
     rtU.uMaxHistory.value = this.maxHistory;
     rtU.uFireflyClamp.value = this.fireflyClamp > 0 ? this.fireflyClamp : 1e6;
     rtU.uGIEnabled.value = this.gi;
     rtU.uGIHalfRate.value = this.giHalfRate;
+    // ReSTIR GI (experimental) supplies the 1-bounce indirect externally when
+    // on; the lighting pass then skips its inline GI trace so it isn't double
+    // counted. It's injected at the denoise stage, so it needs denoise on.
+    const giExternal =
+      this.restirGI && this.gi && this.denoise && this.denoiseIterations > 0;
+    rtU.uExternalGI.value = giExternal;
+    if (this.restirGI && this.gi && !giExternal && !this._giMissWarned) {
+      console.info(
+        "[three-realtime-rt] restirGI is on but denoise is off — ReSTIR GI is " +
+          "injected during the à-trous denoise, so enable denoise " +
+          "(denoiseIterations >= 1) to see its contribution."
+      );
+      this._giMissWarned = true;
+    }
+    if (giExternal) this._giMissWarned = false;
     rtU.uEmissiveCount.value = this.emissiveNEE ? this.compiled.emissiveTriCount : 0;
     rtU.uEmissiveCDF.value = this.emissiveImportance;
     rtU.uReflEnabled.value = this.reflections;
     rtU.uRefrEnabled.value = this.refraction;
     rtU.uBlendEnabled.value = this.transparency;
     rtU.uIor.value = this.ior;
+    rtU.uDispersion.value = Math.min(0.5, Math.max(0, this.dispersion));
     rtU.uLightStochastic.value = this.stochasticLights;
     rtU.uSkyEnabled.value = this.sky.enabled;
     rtU.uSunDir.value.copy(this.sky.sunDir);
@@ -1048,17 +1146,55 @@ uniform sampler2D uTex; void main(){ outColor = texture(uTex, vUv); }`,
         this.eps
       );
     }
+    // 2b. ReSTIR GI reservoirs (experimental). Runs after the lighting pass's
+    // inline GI is skipped (uExternalGI); the resolved GI is added at denoise.
+    let giTex = null;
+    if (giExternal) {
+      this.giReservoirPass.setEmissiveCount(
+        this.emissiveNEE ? this.compiled.emissiveTriCount : 0
+      );
+      giTex = this.giReservoirPass.render(
+        this.renderer,
+        this.gbuffer,
+        this._prevViewProj,
+        this._camWorldPos,
+        this.frame,
+        this.eps,
+        {
+          fireflyClamp: this.fireflyClamp > 0 ? this.fireflyClamp : 1e6,
+          mCap: this.restirGIMCap,
+          spatialTaps: Math.max(0, Math.min(4, this.restirGISpatialTaps | 0)),
+          validateInterval: Math.max(0, this.restirGIValidate | 0),
+          emissiveCDF: this.emissiveImportance,
+          envColor: this.envColor,
+          envIntensity: this.envIntensity,
+          skyEnabled: this.sky.enabled,
+          sunDir: this.sky.sunDir,
+          sunColor: this.sky.sunColor,
+          skyZenith: this.sky.zenith,
+          skyHorizon: this.sky.horizon,
+          skyIntensity: this.sky.intensity,
+        }
+      );
+    }
+
     let { irradiance, specular } = this.rtPass.render(this.renderer, this.gbuffer, this.frame, reservoirTex);
 
-    // 3. denoise (display-only: history keeps accumulating raw samples)
-    if (this.denoise && this.denoiseIterations > 0) {
+    // 3. denoise (display-only: history keeps accumulating raw samples). The
+    // experimental ReSTIR GI (giTex) is added on the first à-trous iteration —
+    // downstream of the lighting pass's temporal history, so it never
+    // double-counts through it. The bvh-cost heatmap (mode 7) is a per-pixel
+    // debug signal, not lighting — the edge-aware blur would smear its bands,
+    // so it bypasses the denoiser (which also keeps the GI add out of mode 7).
+    if (this.denoise && this.denoiseIterations > 0 && this.outputMode !== 7) {
       irradiance = this.denoisePass.render(
         this.renderer,
         irradiance,
         this.gbuffer,
         this._camWorldPos,
         this.eps,
-        this.denoiseIterations
+        this.denoiseIterations,
+        giTex
       );
     }
 
@@ -1179,6 +1315,7 @@ uniform sampler2D uTex; void main(){ outColor = texture(uTex, vUv); }`,
     this.taaPass.dispose();
     this.volumetricPass.dispose();
     this.restirPass.dispose();
+    this.giReservoirPass.dispose();
     this._sceneColor.dispose();
     this._copyPass.dispose();
     if (this.compiled) this.compiled.dispose();