three-realtime-rt 0.5.0 → 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
@@ -476,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)) {
@@ -493,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);
 }
 
@@ -553,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).
+//
+// 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 / ior;
+  // 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;
@@ -575,7 +627,7 @@ vec3 glassRadiance(vec3 P, vec3 N, vec3 V, float rough, float ior) {
     vec3 xN = normalize(attr.xyz);
     if (dot(xN, rd) > 0.0) xN = -xN;
     vec3 xP = ro + rd * dist;
-    vec3 rd2 = refract(rd, xN, ior);
+    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 {
@@ -583,7 +635,9 @@ vec3 glassRadiance(vec3 P, vec3 N, vec3 V, float rough, float ior) {
       ? 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
@@ -978,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) },

package/src/RealtimeRaytracer.js

@@ -492,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
@@ -610,6 +621,29 @@ uniform sampler2D uTex; void main(){ outColor = texture(uTex, vUv); }`,
     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;
 
@@ -1084,6 +1118,7 @@ uniform sampler2D uTex; void main(){ outColor = texture(uTex, vUv); }`,
     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);
@@ -1128,6 +1163,8 @@ uniform sampler2D uTex; void main(){ outColor = texture(uTex, vUv); }`,
         {
           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,

package/src/SceneCompiler.js

@@ -58,6 +58,15 @@ export class CompiledScene {
     this.emissiveTriCount = 0;
     this.triangleCount = 0;
 
+    // Dynamic emissive area lights: the final (post-cap) emissive triangle list
+    // and the subset that belongs to dynamic emitters (row + merged-position
+    // offset), refreshed in place each updateDynamic(). lastEmissiveRefreshMs is
+    // the CPU cost of the most recent refresh (0 when there are none).
+    this.emissiveTris = [];
+    this._dynamicEmissive = [];
+    this.hasDynamicEmissive = false;
+    this.lastEmissiveRefreshMs = 0;
+
     this._m3 = new THREE.Matrix3();
     this._normalFrame = 0;
     this._dynBuildVolume = null; // world-volume of the dynamic set at build time
@@ -251,6 +260,64 @@ export class CompiledScene {
     if (this.hasDeforming || this.hasSkinned || this._normalFrame++ % 8 === 0) {
       this.dynamicAttrTex.updateFrom(this.dynamicPackedAttr);
     }
+
+    // Refresh dynamic emissive area lights from the freshly baked world-space
+    // merged positions (rows in the scene-data texture + the power CDF).
+    if (this.hasDynamicEmissive) this._refreshDynamicEmissive();
+  }
+
+  /**
+   * Re-derive dynamic emitters' world-space NEE triangles from the merged
+   * dynamic positions this frame, rewrite their rows in the scene-data texture
+   * (row 1) and rebuild the power CDF (row 66), then flag the texture for
+   * re-upload. The whole (small) texture goes back up — measured in
+   * lastEmissiveRefreshMs. Called from updateDynamic (i.e. only when the dynamic
+   * set actually updated); an emissive change on an emitter that did NOT move —
+   * e.g. recolouring material.emissive — is frozen at compile time and needs a
+   * compileScene() (updateLights only rescans analytic THREE lights).
+   */
+  _refreshDynamicEmissive() {
+    const list = this._dynamicEmissive;
+    if (list.length === 0) return;
+    const now = typeof performance !== "undefined" ? performance : Date;
+    const t0 = now.now();
+    const tex = this.materialsTex;
+    const data = tex.image.data;
+    const row = tex.image.width * 4; // texture width in floats
+    const pos = this.dynamicMerged.getAttribute("position").array;
+    const tris = this.emissiveTris;
+    for (let k = 0; k < list.length; k++) {
+      const de = list[k];
+      const off = de.off;
+      const ax = pos[off], ay = pos[off + 1], az = pos[off + 2];
+      const e1x = pos[off + 3] - ax, e1y = pos[off + 4] - ay, e1z = pos[off + 5] - az;
+      const e2x = pos[off + 6] - ax, e2y = pos[off + 7] - ay, e2z = pos[off + 8] - az;
+      let nx = e1y * e2z - e1z * e2y;
+      let ny = e1z * e2x - e1x * e2z;
+      let nz = e1x * e2y - e1y * e2x;
+      const len = Math.hypot(nx, ny, nz);
+      const area = len * 0.5;
+      const il = len > 1e-10 ? 1 / len : 0; // keep a degenerate frame from NaN-ing
+      nx *= il; ny *= il; nz *= il;
+      const emit = de.emit;
+      // Keep the JS-side tri object current so writeEmissiveCdf sees fresh areas.
+      const t = tris[de.row];
+      t.v0[0] = ax; t.v0[1] = ay; t.v0[2] = az;
+      t.e1[0] = e1x; t.e1[1] = e1y; t.e1[2] = e1z;
+      t.e2[0] = e2x; t.e2[1] = e2y; t.e2[2] = e2z;
+      t.n[0] = nx; t.n[1] = ny; t.n[2] = nz;
+      t.area = area;
+      // Row 1 texel (16 floats) — layout must match buildSceneDataTexture.
+      const o = row + de.row * 16;
+      data[o + 0] = ax; data[o + 1] = ay; data[o + 2] = az; data[o + 3] = area;
+      data[o + 4] = e1x; data[o + 5] = e1y; data[o + 6] = e1z; data[o + 7] = emit[0];
+      data[o + 8] = e2x; data[o + 9] = e2y; data[o + 10] = e2z; data[o + 11] = emit[1];
+      data[o + 12] = nx; data[o + 13] = ny; data[o + 14] = nz; data[o + 15] = emit[2];
+    }
+    // Areas (and therefore pick probabilities) may have changed — rebuild the CDF.
+    writeEmissiveCdf(data, row, tris);
+    tex.needsUpdate = true;
+    this.lastEmissiveRefreshMs = now.now() - t0;
   }
 
   dispose() {
@@ -333,12 +400,91 @@ function resolveMeshMaterials(mesh, count, registerMaterial) {
   return { matIdx, ranges };
 }
 
+// Average-colour cache for emissive maps: texture -> [r,g,b] linear, or null when
+// the image is unreadable (CORS-tainted / not yet decoded). Keyed by the THREE
+// texture so the two collect sites (material row + NEE tris) share one solve.
+const _emissiveMapAvgCache = new Map();
+let _emissiveMapWarned = false;
+
+// sRGB -> linear for one 0..1 channel (three decodes SRGBColorSpace maps this way
+// before lighting; average in linear so the cast colour matches the lit look).
+function srgbToLinear(c) {
+  return c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
+}
+
+// CPU average of an emissiveMap: draw the texture image into a small (16x16)
+// offscreen canvas and mean the texels. Returns linear [r,g,b] in 0..1, or null
+// if the image can't be read (CORS-tainted, or no decoded image yet) — the
+// caller then falls back to the map-zeroes-the-light behaviour, once, with a
+// console.info explaining why. Result is cached per texture.
+function averageEmissiveMap(map) {
+  if (_emissiveMapAvgCache.has(map)) return _emissiveMapAvgCache.get(map);
+  let result = null;
+  try {
+    const img = map.image;
+    const w = img && (img.width || img.videoWidth || 0);
+    const h = img && (img.height || img.videoHeight || 0);
+    if (img && w > 0 && h > 0 && typeof document !== "undefined") {
+      const N = 16;
+      const canvas = document.createElement("canvas");
+      canvas.width = N;
+      canvas.height = N;
+      const ctx = canvas.getContext("2d", { willReadFrequently: true });
+      ctx.drawImage(img, 0, 0, N, N); // downsample
+      const d = ctx.getImageData(0, 0, N, N).data; // throws if the image is tainted
+      const toLinear = map.colorSpace !== THREE.NoColorSpace && map.colorSpace !== THREE.LinearSRGBColorSpace;
+      let r = 0, g = 0, b = 0;
+      const n = d.length / 4;
+      for (let i = 0; i < d.length; i += 4) {
+        if (toLinear) {
+          r += srgbToLinear(d[i] / 255);
+          g += srgbToLinear(d[i + 1] / 255);
+          b += srgbToLinear(d[i + 2] / 255);
+        } else {
+          r += d[i] / 255; g += d[i + 1] / 255; b += d[i + 2] / 255;
+        }
+      }
+      result = [r / n, g / n, b / n];
+    }
+  } catch (e) {
+    result = null; // CORS-tainted (SecurityError) or unreadable
+  }
+  if (result === null && !_emissiveMapWarned) {
+    _emissiveMapWarned = true;
+    console.info(
+      "three-realtime-rt: an emissiveMap could not be read on the CPU (CORS-tainted " +
+      "or not yet decoded), so its mesh casts no area light — it is still drawn " +
+      "per-pixel in the G-buffer. Serve the texture same-origin (or set " +
+      "image.crossOrigin) to enable the average-colour approximation."
+    );
+  }
+  _emissiveMapAvgCache.set(map, result);
+  return result;
+}
+
 // Effective emissive colour (already scaled by intensity), or null if the
-// material doesn't emit. Matches the shading table's emissiveMap exclusion.
+// material doesn't emit. A plain emissive colour is used directly; an
+// emissiveMap is approximated by its AVERAGE colour (avg(map) x emissive x
+// emissiveIntensity) so a textured emitter casts (approximately) correct light —
+// the G-buffer still renders it per-pixel, so it LOOKS patterned. An unreadable
+// map falls back to null (visible only), matching the old exclusion.
 function emissiveColor(mat) {
-  if (mat.emissiveMap != null || !mat.emissive) return null;
+  if (!mat.emissive) return null;
   const i = mat.emissiveIntensity ?? 1;
   if (i <= 0 || mat.emissive.r + mat.emissive.g + mat.emissive.b <= 0) return null;
+  if (mat.emissiveMap != null) {
+    const avg = averageEmissiveMap(mat.emissiveMap);
+    if (avg == null) return null; // unreadable -> current behaviour (visible only)
+    const emit = [mat.emissive.r * i * avg[0], mat.emissive.g * i * avg[1], mat.emissive.b * i * avg[2]];
+    // A map that averages to (near) black casts no meaningful light — treat it
+    // as visible-only, like a black emissive colour. This keeps an incidental
+    // textured emissive (a high-poly model whose emissiveMap is mostly dark with
+    // a few tiny glowing texels — e.g. DamagedHelmet) out of the NEE list rather
+    // than flooding it with the whole mesh; a real neon sign clears this easily.
+    const lum = 0.2126 * emit[0] + 0.7152 * emit[1] + 0.0722 * emit[2];
+    if (lum < 1e-3) return null;
+    return emit;
+  }
   return [mat.emissive.r * i, mat.emissive.g * i, mat.emissive.b * i];
 }
 
@@ -387,22 +533,9 @@ function buildSceneDataTexture(materials, emissiveTris) {
       data[o + i] = (bn[src + i] + 0.5) / 256.0;
     }
   }
-  // Emissive power CDF (see the layout comment above). Weight = area x
-  // emitted luminance; degenerate totals fall back to the uniform pick.
-  if (emissiveTris.length > 0) {
-    const w = emissiveTris.map(
-      (t) => t.area * (0.2126 * t.emit[0] + 0.7152 * t.emit[1] + 0.0722 * t.emit[2])
-    );
-    const total = w.reduce((a, b) => a + b, 0);
-    const cdfRow = (2 + BLUE_NOISE_SIZE) * row;
-    let cum = 0;
-    for (let i = 0; i < emissiveTris.length; i++) {
-      const p = total > 0 ? w[i] / total : 1 / emissiveTris.length;
-      cum += p;
-      data[cdfRow + i * 4 + 0] = i === emissiveTris.length - 1 ? 1.0 : cum;
-      data[cdfRow + i * 4 + 1] = p;
-    }
-  }
+  // Emissive power CDF (row 66). Factored out so updateDynamic can rebuild it
+  // in place when a dynamic emitter's area/position changed this frame.
+  writeEmissiveCdf(data, row, emissiveTris);
   const tex = new THREE.DataTexture(data, width, height, THREE.RGBAFormat, THREE.FloatType);
   tex.minFilter = THREE.NearestFilter;
   tex.magFilter = THREE.NearestFilter;
@@ -410,11 +543,40 @@ function buildSceneDataTexture(materials, emissiveTris) {
   return tex;
 }
 
+// Write the emissive power CDF (row 66 of the scene-data texture). Weight =
+// area x emitted luminance; degenerate totals fall back to the uniform pick.
+// The layout matches the row-66 comment in buildSceneDataTexture. `row` is the
+// texture width in floats (width * 4). Reused by updateDynamic's in-place refresh.
+function writeEmissiveCdf(data, row, emissiveTris) {
+  if (emissiveTris.length === 0) return;
+  const cdfRow = (2 + BLUE_NOISE_SIZE) * row;
+  let total = 0;
+  const w = new Array(emissiveTris.length);
+  for (let i = 0; i < emissiveTris.length; i++) {
+    const t = emissiveTris[i];
+    w[i] = t.area * (0.2126 * t.emit[0] + 0.7152 * t.emit[1] + 0.0722 * t.emit[2]);
+    total += w[i];
+  }
+  let cum = 0;
+  for (let i = 0; i < emissiveTris.length; i++) {
+    const p = total > 0 ? w[i] / total : 1 / emissiveTris.length;
+    cum += p;
+    data[cdfRow + i * 4 + 0] = i === emissiveTris.length - 1 ? 1.0 : cum;
+    data[cdfRow + i * 4 + 1] = p;
+  }
+}
+
 // Collect world-space triangles of an emissive mesh for the NEE light list.
 // `geo` is already non-indexed and world-baked by extractMeshGeometry. An
 // optional [vStart, vCount) vertex range restricts collection to one material
 // group (ranges are triangle-aligned, so this stays whole-triangle).
-function collectEmissiveTriangles(geo, emit, out, vStart = 0, vCount = -1) {
+//
+// `dynBase` >= 0 tags each triangle as belonging to a DYNAMIC emitter: dynBase is
+// the float offset of this mesh's segment in the merged dynamic position array
+// (segStart * 3), so `dynOff` records where the triangle's v0/e1/e2 live there.
+// updateDynamic re-derives the world-space triangle from those merged positions
+// each frame (the merged array already holds the freshly transformed vertices).
+function collectEmissiveTriangles(geo, emit, out, vStart = 0, vCount = -1, dynBase = -1) {
   const pos = geo.getAttribute("position").array;
   const begin = vStart * 3;
   const end = vCount < 0 ? pos.length : Math.min(pos.length, (vStart + vCount) * 3);
@@ -426,14 +588,19 @@ function collectEmissiveTriangles(geo, emit, out, vStart = 0, vCount = -1) {
     const cz = e1[0] * e2[1] - e1[1] * e2[0];
     const len = Math.hypot(cx, cy, cz);
     if (len < 1e-10) continue; // degenerate
-    out.push({
+    const tri = {
       v0: [pos[i], pos[i + 1], pos[i + 2]],
       e1,
       e2,
       n: [cx / len, cy / len, cz / len],
       area: len * 0.5,
       emit,
-    });
+    };
+    if (dynBase >= 0) {
+      tri.dyn = true;
+      tri.dynOff = dynBase + i; // float offset of v0 in the merged dynamic positions
+    }
+    out.push(tri);
   }
 }
 
@@ -523,19 +690,20 @@ export function compileScene(scene, options = {}) {
     // the shared table) and get the ranges for per-group emissive collection.
     const { matIdx, ranges } = resolveMeshMaterials(obj, extracted.count, registerMaterial);
     extracted.geo.setAttribute("materialIndex", new THREE.BufferAttribute(matIdx, 1));
-    // Static emissive meshes become NEE area lights (sampled directly with
-    // shadow rays instead of waiting for a GI ray to stumble into them).
-    // Dynamic emitters are left out — their world-space triangles would go
-    // stale — so they keep lighting the old way, via GI-ray hits. Each emissive
-    // GROUP contributes its own range.
-    if (!isDynamic) {
+    // Emissive meshes become NEE area lights (sampled directly with shadow rays
+    // instead of waiting for a GI ray to stumble into them). Each emissive GROUP
+    // contributes its own range. STATIC emitters are collected in world space
+    // once; DYNAMIC emitters are ALSO collected now but tagged with their merged
+    // segment offset (segStart * 3) so updateDynamic() can re-derive their
+    // world-space triangles each frame from the freshly baked merged positions.
+    if (isDynamic) {
+      const segStart = dynVertexOffset; // this segment's vertex base in the merged array
+      dynamicGeoms.push(extracted.geo);
       for (const r of ranges) {
         const emit = emissiveColor(r.material);
-        if (emit) collectEmissiveTriangles(extracted.geo, emit, emissiveTris, r.start, r.vcount);
+        if (emit)
+          collectEmissiveTriangles(extracted.geo, emit, emissiveTris, r.start, r.vcount, segStart * 3);
       }
-    }
-    if (isDynamic) {
-      dynamicGeoms.push(extracted.geo);
       // A SkinnedMesh is auto-detected (no userData flag): it is CPU-skinned from
       // its live skeleton pose every frame. Opt-in CPU deformation (water/cloth)
       // instead requires userData.rtDeforming and reads live geometry. The two are
@@ -564,6 +732,10 @@ export function compileScene(scene, options = {}) {
       dynVertexOffset += extracted.count;
     } else {
       staticGeoms.push(extracted.geo);
+      for (const r of ranges) {
+        const emit = emissiveColor(r.material);
+        if (emit) collectEmissiveTriangles(extracted.geo, emit, emissiveTris, r.start, r.vcount);
+      }
     }
   });
 
@@ -602,13 +774,27 @@ export function compileScene(scene, options = {}) {
   if (emissiveTris.length > MAX_EMISSIVE_TRIS) {
     console.warn(
       `three-realtime-rt: ${emissiveTris.length} emissive triangles exceed the ` +
-      `NEE cap of ${MAX_EMISSIVE_TRIS}; keeping the largest by area. Dropped ` +
-      `triangles no longer act as lights — prefer low-poly emitter meshes.`
+      `NEE cap of ${MAX_EMISSIVE_TRIS} (shared across static + dynamic emitters); ` +
+      `keeping the largest by area (measured at compile time). Dropped triangles ` +
+      `no longer act as lights — prefer low-poly emitter meshes, especially for ` +
+      `dynamic ones (their tris are refreshed every frame).`
     );
     emissiveTris.sort((a, b) => b.area - a.area);
     emissiveTris.length = MAX_EMISSIVE_TRIS;
   }
   compiled.emissiveTriCount = emissiveTris.length;
+  // Keep the final (post-cap) emissive list so updateDynamic can rebuild the
+  // power CDF, and record which surviving rows belong to dynamic emitters (with
+  // their merged-position offset) so their world-space triangles can be
+  // refreshed per frame. Rows stay index-stable after this point, so the
+  // reservoir passes' triangle ids remain valid across refreshes.
+  compiled.emissiveTris = emissiveTris;
+  compiled._dynamicEmissive = [];
+  for (let r = 0; r < emissiveTris.length; r++) {
+    const t = emissiveTris[r];
+    if (t.dyn) compiled._dynamicEmissive.push({ row: r, off: t.dynOff, emit: t.emit });
+  }
+  compiled.hasDynamicEmissive = compiled._dynamicEmissive.length > 0;
   compiled.materialsTex = buildSceneDataTexture(materials, emissiveTris);
   syncLights(scene, compiled);
 

package/src/index.d.ts

@@ -173,6 +173,24 @@ export interface RealtimeRaytracerOptions {
   restirGI?: boolean;
   /** EXPERIMENTAL — temporal M-cap for the ReSTIR GI reservoir (default 20). */
   restirGIMCap?: number;
+  /**
+   * EXPERIMENTAL — 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 to prevent leaks). Clamped to 0..4;
+   * `0` reproduces v1 temporal-only behaviour. Default 2.
+   */
+  restirGISpatialTaps?: number;
+  /**
+   * EXPERIMENTAL — ReSTIR GI reservoir-sample validation period. Every frame a
+   * rotating 1-in-N subset of pixels re-aims its single candidate ray at the
+   * reservoir's stored hit (instead of a fresh cosine bounce) and re-shades it;
+   * the reservoir is killed when the geometry moved or the re-shaded target
+   * collapsed to near-black (a light switched off), and left untouched otherwise.
+   * Reuses the existing candidate trace (no extra bounce rays); fixes stale bounce
+   * light (a switched-off light stops haunting the reservoir) without drifting a
+   * static scene. `0` disables it (byte-identical to before the feature). Default 8.
+   */
+  restirGIValidate?: number;
   /**
    * Global fallback index of refraction for transmissive surfaces. A
    * `MeshPhysicalMaterial.ior` overrides this per material for fully-transmissive
@@ -181,6 +199,15 @@ export interface RealtimeRaytracerOptions {
    * the default when no per-material ior is carried.
    */
   ior?: number;
+  /**
+   * Chromatic dispersion strength for glass, `0..0.5` (clamped), default `0`
+   * (off). Splits refracted white light into a spectrum via stochastic spectral
+   * sampling — each frame every glass pixel estimates one colour channel through
+   * a channel-shifted ior, and temporal accumulation blends the three into a
+   * rainbow (no extra rays). Needs accumulation to converge, so it shimmers
+   * slightly in motion. Global control only (no per-material dispersion).
+   */
+  dispersion?: number;
   /** History length cap: higher = smoother but slower to react. */
   maxHistory?: number;
   /** Clamp on indirect luminance to suppress fireflies. 0 disables. */
@@ -287,11 +314,19 @@ export class CompiledScene {
   triangleCount: number;
   /** Number of lights scanned into the compiled light tables. */
   lightCount: number;
-  /** Number of emissive triangles registered as NEE area lights. */
+  /** Number of emissive triangles registered as NEE area lights (static + dynamic). */
   emissiveTriCount: number;
   /** World-space diagonal of the static level (used to auto-scale ray epsilon). */
   sceneDiagonal: number;
-  /** Re-bake moving meshes' current world transforms and refit the dynamic BVH. */
+  /** True when any dynamic emitter contributes NEE rows refreshed each frame. */
+  hasDynamicEmissive: boolean;
+  /** CPU cost (ms) of the most recent dynamic-emissive refresh (0 if none). */
+  lastEmissiveRefreshMs: number;
+  /**
+   * Re-bake moving meshes' current world transforms and refit the dynamic BVH.
+   * Also refreshes any dynamic emitters' NEE area-light rows + power CDF from the
+   * freshly baked world positions.
+   */
   updateDynamic(): void;
   /** Release GPU resources held by this compiled scene. */
   dispose(): void;
@@ -388,6 +423,12 @@ export class RealtimeRaytracer {
    * per material for fully-transmissive glass (range [1.0, 1.98]).
    */
   ior: number;
+  /**
+   * Chromatic dispersion strength for glass, `0..0.5` (clamped on upload),
+   * default `0`. Stochastic spectral sampling: splits refracted white light into
+   * a rainbow via temporal accumulation, no extra rays. Global control only.
+   */
+  dispersion: number;
   /** One stochastic direct shadow ray per pixel per frame instead of one per light. */
   stochasticLights: boolean;
   /** Adaptive quality governor toggle. */
@@ -415,6 +456,10 @@ export class RealtimeRaytracer {
   restirGI: boolean;
   /** EXPERIMENTAL — temporal M-cap for the ReSTIR GI reservoir. */
   restirGIMCap: number;
+  /** EXPERIMENTAL — ReSTIR GI (v2) spatial-reuse taps per frame (0..4, 0 = v1). */
+  restirGISpatialTaps: number;
+  /** EXPERIMENTAL — ReSTIR GI reservoir-sample validation period (0 = off, default 8). */
+  restirGIValidate: number;
   /** Procedural-sky state. */
   sky: SkyState;
   /** Distance-fog state. */