three-realtime-rt 0.4.0 → 0.5.0

package/src/GIReservoirPass.js

@@ -0,0 +1,572 @@
+import * as THREE from "three";
+import { shaderStructs, shaderIntersectFunction } from "three-mesh-bvh";
+import { MAX_LIGHTS } from "./SceneCompiler.js";
+import { SKY_GLSL } from "./sky.glsl.js";
+import { BVH_ANY_HIT_GLSL } from "./bvhAnyHit.glsl.js";
+
+const fullscreenVert = /* glsl */ `
+out vec2 vUv;
+void main() {
+  vUv = uv;
+  gl_Position = vec4(position.xy, 0.0, 1.0);
+}
+`;
+
+// ReSTIR GI (EXPERIMENTAL) — temporal-only reservoir reuse of the 1-bounce GI
+// path. This standalone pass owns its OWN sampler budget (the lighting pass is
+// already AT the WebGL2 16-sampler minimum and cannot take another), and shades
+// GI-bounce hits IDENTICALLY to RTLightingPass.traceRadiance so the mean equals
+// the inline path. See the estimator derivation in main() below.
+//
+// The GI-hit shading below is duplicated (not shared via include) from
+// RTLightingPass ON PURPOSE: the inline path must stay byte-identical when
+// restirGI is off, so RTLightingPass is left completely untouched. The specular
+// (gWantSpec) accumulation is dropped here — GI bounces never contribute to the
+// primary-surface highlight buffer — but every quantity that affects the
+// RETURNED radiance is copied faithfully (RNG scheme, cosine sampling, two-level
+// BVH trace, one-light NEE incl. emissive importance sampling + the near-emitter
+// firefly clamp, sky/env on a miss).
+const giFrag = /* glsl */ `
+precision highp float;
+precision highp isampler2D;
+precision highp usampler2D;
+
+${shaderStructs}
+${shaderIntersectFunction}
+${BVH_ANY_HIT_GLSL}
+${SKY_GLSL}
+
+#define MAX_LIGHTS ${MAX_LIGHTS}
+#define PI 3.14159265358979
+
+// MRT: [0] reservoir hit position + M (fp32), [1] reservoir radiance + W,
+//      [2] resolved demodulated GI irradiance (consumed by the denoise add).
+layout(location = 0) out vec4 outResPos;
+layout(location = 1) out vec4 outResRad;
+layout(location = 2) out vec4 outGI;
+
+in vec2 vUv;
+
+// Two-level BVH + per-vertex attribute textures (normal.xyz + materialIndex.w),
+// exactly as RTLightingPass binds them. 8 samplers (4 per BVH struct) + 2 attr.
+uniform BVH bvhStatic;
+uniform BVH bvhDynamic;
+uniform bool uHasDynamic;
+uniform sampler2D uAttrStatic;
+uniform sampler2D uAttrDynamic;
+uniform sampler2D uMaterialsTex;   // materials + emissive NEE tris + blue noise + power CDF
+
+uniform sampler2D uGWorldPos;
+uniform sampler2D uGNormalMetal;
+
+// Temporal reuse: reproject through last frame's G-buffer (plane-distance
+// validation, same as the lighting pass) and pull last frame's reservoir.
+uniform sampler2D uPrevGWorldPos;
+uniform sampler2D uPrevResPos;     // history attachment 0: hitPos.xyz + M
+uniform sampler2D uPrevResRad;     // history attachment 1: radiance.rgb + W
+uniform mat4 uPrevViewProj;
+
+uniform vec4 uLightPosType[MAX_LIGHTS];
+uniform vec4 uLightColorRadius[MAX_LIGHTS];
+uniform vec4 uLightDirCone[MAX_LIGHTS];
+uniform int uLightCount;
+uniform int uEmissiveCount;
+uniform bool uEmissiveCDF;
+
+uniform vec3 uCameraPos;
+uniform float uFrame;
+uniform float uEps;
+uniform float uFireflyClamp;
+uniform float uMCap;        // temporal M-cap (staleness limit)
+
+uniform vec3 uEnvColor;
+uniform float uEnvIntensity;
+uniform bool uSkyEnabled;
+uniform vec3 uSunDir;
+uniform vec3 uSunColor;
+uniform vec3 uSkyZenith;
+uniform vec3 uSkyHorizon;
+uniform float uSkyIntensity;
+
+// ---------- RNG (identical scheme to RTLightingPass) ----------
+uint gSeed;
+int gBnDim;
+vec4 gBlueNoise;
+uint pcgHash(uint s) {
+  uint state = s * 747796405u + 2891336453u;
+  uint word = ((state >> ((state >> 28u) + 4u)) ^ state) * 277803737u;
+  return (word >> 22u) ^ word;
+}
+float rand() {
+  if (gBnDim < 4) {
+    float v = gBlueNoise[gBnDim];
+    gBnDim++;
+    return v;
+  }
+  gSeed = pcgHash(gSeed);
+  return float(gSeed) * (1.0 / 4294967296.0);
+}
+vec2 rand2() { return vec2(rand(), rand()); }
+
+vec4 fetchBlueNoise() {
+  ivec2 p = ivec2(gl_FragCoord.xy) & 63;
+  vec4 bn = texelFetch(uMaterialsTex, ivec2(p.x, 2 + p.y), 0);
+  vec4 shift = fract(float(uFrame) * vec4(0.6180340, 0.7548777, 0.5698403, 0.8191725));
+  return fract(bn + shift);
+}
+
+float luminance(vec3 c) { return dot(c, vec3(0.299, 0.587, 0.114)); }
+
+void orthoBasis(vec3 n, out vec3 t, out vec3 b) {
+  float s = n.z >= 0.0 ? 1.0 : -1.0;
+  float a = -1.0 / (s + n.z);
+  float m = n.x * n.y * a;
+  t = vec3(1.0 + s * n.x * n.x * a, s * m, -s * n.x);
+  b = vec3(m, s + n.y * n.y * a, -n.y);
+}
+vec3 cosineSampleHemisphere(vec3 n, vec2 u) {
+  float a = 2.0 * PI * u.x;
+  float r = sqrt(u.y);
+  vec3 t, b;
+  orthoBasis(n, t, b);
+  return normalize(t * (r * cos(a)) + b * (r * sin(a)) + n * sqrt(max(0.0, 1.0 - u.y)));
+}
+vec3 randUnitVector() {
+  vec2 u = rand2();
+  float z = u.x * 2.0 - 1.0;
+  float a = u.y * 2.0 * PI;
+  float r = sqrt(max(0.0, 1.0 - z * z));
+  return vec3(r * cos(a), r * sin(a), z);
+}
+
+// ---------- two-level BVH helpers (copied verbatim) ----------
+bool traceBoth(vec3 ro, vec3 rd, out uvec4 fi, out vec3 bary, out float dist, out bool isDyn) {
+  uvec4 fiS; vec3 fnS; vec3 bcS; float sideS; float distS;
+  bool hitS = bvhIntersectFirstHit(bvhStatic, ro, rd, fiS, fnS, bcS, sideS, distS);
+  uvec4 fiD; vec3 fnD; vec3 bcD; float sideD; float distD;
+  bool hitD = uHasDynamic && bvhIntersectFirstHit(bvhDynamic, ro, rd, fiD, fnD, bcD, sideD, distD);
+  if (hitS && (!hitD || distS <= distD)) { fi = fiS; bary = bcS; dist = distS; isDyn = false; return true; }
+  if (hitD) { fi = fiD; bary = bcD; dist = distD; isDyn = true; return true; }
+  return false;
+}
+bool occluded(vec3 ro, vec3 rd, float maxDist) {
+  if (bvhIntersectAnyHit(bvhStatic, ro, rd, maxDist - 2.0 * uEps)) return true;
+  if (uHasDynamic && bvhIntersectAnyHit(bvhDynamic, ro, rd, maxDist - 2.0 * uEps)) return true;
+  return false;
+}
+
+void fetchMaterial(float matIndex, out vec3 albedo, out float roughness,
+                   out vec3 emissive, out float metalness) {
+  int mi = int(round(matIndex)) * 2;
+  vec4 t0 = texelFetch(uMaterialsTex, ivec2(mi, 0), 0);
+  vec4 t1 = texelFetch(uMaterialsTex, ivec2(mi + 1, 0), 0);
+  albedo = t0.rgb;
+  roughness = t0.a;
+  emissive = t1.rgb;
+  metalness = t1.a;
+}
+
+// ---------- one-light NEE at a GI-bounce hit (specular dropped) ----------
+float spotFalloff(int i, vec3 lightToP) {
+  vec4 posType = uLightPosType[i];
+  if (posType.w < 1.5) return 1.0;
+  vec4 dc = uLightDirCone[i];
+  return smoothstep(dc.w, posType.w - 2.0, dot(dc.xyz, lightToP));
+}
+
+vec3 lightContribution(int i, vec3 P, vec3 N) {
+  vec4 posType = uLightPosType[i];
+  vec4 colRad = uLightColorRadius[i];
+  vec3 L;
+  float dist2 = 1.0;
+  float maxDist = 1e7;
+  float cone = 1.0;
+  if (posType.w < 0.5 || posType.w >= 1.5) {
+    vec3 lp = posType.xyz + randUnitVector() * colRad.w;
+    vec3 d = lp - P;
+    float dl = length(d);
+    if (dl < 1e-5) return vec3(0.0);
+    L = d / dl;
+    dist2 = dl * dl;
+    maxDist = dl;
+    cone = spotFalloff(i, -L);
+    if (cone <= 0.0) return vec3(0.0);
+  } else {
+    L = normalize(-posType.xyz + randUnitVector() * colRad.w);
+    dist2 = 1.0;
+  }
+  float NdotL = dot(N, L);
+  if (NdotL <= 0.0) return vec3(0.0);
+  if (occluded(P + N * uEps, L, maxDist)) return vec3(0.0);
+  return colRad.rgb * (cone / dist2) * NdotL;
+}
+
+vec3 sampleOneLight(vec3 P, vec3 N) {
+  if (uLightCount == 0) return vec3(0.0);
+  int i = min(int(rand() * float(uLightCount)), uLightCount - 1);
+  return lightContribution(i, P, N) * float(uLightCount);
+}
+
+vec3 sampleEmissiveTri(vec3 P, vec3 N) {
+  if (uEmissiveCount == 0) return vec3(0.0);
+  int idx;
+  float invProb;
+  if (uEmissiveCDF) {
+    float u = rand();
+    int lo = 0;
+    int hi = uEmissiveCount - 1;
+    for (int s = 0; s < 8; s++) {
+      if (lo >= hi) break;
+      int mid = (lo + hi) >> 1;
+      if (u > texelFetch(uMaterialsTex, ivec2(mid, 66), 0).x) lo = mid + 1;
+      else hi = mid;
+    }
+    idx = lo;
+    invProb = 1.0 / max(texelFetch(uMaterialsTex, ivec2(idx, 66), 0).y, 1e-8);
+  } else {
+    idx = min(int(rand() * float(uEmissiveCount)), uEmissiveCount - 1);
+    invProb = float(uEmissiveCount);
+  }
+  int i = idx * 4;
+  vec4 t0 = texelFetch(uMaterialsTex, ivec2(i, 1), 0);
+  vec4 t1 = texelFetch(uMaterialsTex, ivec2(i + 1, 1), 0);
+  vec4 t2 = texelFetch(uMaterialsTex, ivec2(i + 2, 1), 0);
+  vec4 t3 = texelFetch(uMaterialsTex, ivec2(i + 3, 1), 0);
+  vec2 u = rand2();
+  if (u.x + u.y > 1.0) u = 1.0 - u;
+  vec3 lp = t0.xyz + t1.xyz * u.x + t2.xyz * u.y;
+  vec3 d = lp - P;
+  float d2 = dot(d, d);
+  float dist = sqrt(d2);
+  if (dist < 1e-4) return vec3(0.0);
+  vec3 wi = d / dist;
+  float cosS = dot(N, wi);
+  float cosL = abs(dot(t3.xyz, wi));
+  if (cosS <= 0.0 || cosL < 1e-4) return vec3(0.0);
+  if (occluded(P + N * uEps, wi, dist)) return vec3(0.0);
+  vec3 e = vec3(t1.w, t2.w, t3.w) * (cosS * cosL * invProb * t0.w / max(d2, 1e-6));
+  float eLum = dot(e, vec3(0.299, 0.587, 0.114));
+  float eCap = uFireflyClamp * 2.0;
+  if (eLum > eCap) e *= eCap / eLum;
+  return e;
+}
+
+vec3 sampleOneAny(vec3 P, vec3 N) {
+  bool hasL = uLightCount > 0;
+  bool hasE = uEmissiveCount > 0;
+  if (hasL && hasE) {
+    return rand() < 0.5
+      ? sampleOneLight(P, N) * 2.0
+      : sampleEmissiveTri(P, N) * 2.0;
+  }
+  if (hasL) return sampleOneLight(P, N);
+  if (hasE) return sampleEmissiveTri(P, N);
+  return vec3(0.0);
+}
+
+// Incoming radiance along rd for a DIFFUSE GI bounce (specular=false in the
+// inline path), plus the world-space hit position so temporal reuse can
+// recompute the geometry term at the reprojected (same) surface. On a miss the
+// "hit" is a far point along the ray, so the reused direction is recoverable.
+vec3 traceRadianceGI(vec3 ro, vec3 rd, out vec3 hitPos) {
+  uvec4 fi; vec3 bary; float dist; bool isDyn;
+  if (!traceBoth(ro, rd, fi, bary, dist, isDyn)) {
+    hitPos = ro + rd * 1.0e4;
+    return uSkyEnabled
+      ? skyColor(rd, uSunDir, uSunColor, uSkyZenith, uSkyHorizon, uSkyIntensity)
+      : uEnvColor * uEnvIntensity;
+  }
+  vec4 attr = isDyn
+    ? textureSampleBarycoord(uAttrDynamic, bary, fi.xyz)
+    : textureSampleBarycoord(uAttrStatic, bary, fi.xyz);
+  vec3 hAlbedo; float hRough; vec3 hEmissive; float hMetal;
+  fetchMaterial(attr.w, hAlbedo, hRough, hEmissive, hMetal);
+  vec3 hN = normalize(attr.xyz);
+  if (dot(hN, rd) > 0.0) hN = -hN;
+  vec3 hP = ro + rd * dist;
+  hitPos = hP;
+  vec3 Ld = sampleOneAny(hP + hN * uEps, hN);
+  // Diffuse GI drops NEE-listed (static) emitter emission so it isn't double
+  // counted (same rule as RTLightingPass.traceRadiance with specular=false).
+  vec3 hLe = (uEmissiveCount > 0 && !isDyn) ? vec3(0.0) : hEmissive;
+  return hLe + hAlbedo * Ld * (1.0 / PI);
+}
+
+void main() {
+  vec4 wp = texture(uGWorldPos, vUv);
+  if (wp.w < 0.5) {
+    outResPos = vec4(0.0);
+    outResRad = vec4(0.0);
+    outGI = vec4(0.0);
+    return;
+  }
+  vec3 P = wp.xyz;
+  vec3 N = normalize(texture(uGNormalMetal, vUv).xyz);
+
+  ivec2 px = ivec2(gl_FragCoord.xy);
+  gSeed = uint(px.x) * 1471u + uint(px.y) * 8951u + uint(uFrame) * 23833u;
+  gSeed = pcgHash(gSeed);
+  gBlueNoise = fetchBlueNoise();
+  gBnDim = 0;
+
+  // ===================== ESTIMATOR DERIVATION =====================
+  // The inline path stores, per pixel, the DEMODULATED indirect irradiance
+  //     I = (1/PI) * integral_hemisphere L_i(w) (N.w) dw
+  // as a single cosine-sampled sample: indirect = traceRadiance(cosine ray),
+  // because with the cosine pdf p(w) = cos/PI the estimate L_i(w)/p * (cos/PI)
+  // collapses to L_i(w). We reproduce the SAME quantity I via RIS.
+  //
+  //  - Candidate sample:  a hemisphere direction w (cosine-sampled), carrying
+  //    the incoming radiance L_i(w) = traceRadianceGI(w) and its hit position.
+  //  - Target function:   p_hat(w) = luminance( L_i(w) * cos(theta) ).
+  //  - Source pdf:        p(w) = cos(theta)/PI  (cosine).
+  //  - RIS candidate weight: w_i = p_hat / p = PI * luminance(L_i)  (cos cancels).
+  //  - Reservoir picks y ~ p_hat; unbiased contribution weight
+  //        W = wSum / (M * p_hat(y)).
+  //  - Final estimate of I (integrand F(w) = L_i(w) cos(theta) / PI):
+  //        <I> = F(y) * W = L_i(y) * cos(theta_y) / PI * W.
+  //
+  //  Sanity (M=1, no history):  W = w_1 / p_hat(y) = PI*lum(L)/(lum(L)*cos) =
+  //  PI/cos, so <I> = L_i * cos/PI * PI/cos = L_i(y) — EXACTLY the inline
+  //  single-sample estimate. Forcing uMCap=1 with a cleared history therefore
+  //  makes this pass statistically identical to the legacy GI path.
+  //
+  //  The reservoir is the GI temporal integrator; its output is ADDED at the
+  //  denoise stage, DOWNSTREAM of the lighting pass's own temporal accumulation,
+  //  so this GI never re-enters (and double-counts through) that history.
+  // ================================================================
+
+  // --- fresh candidate: one cosine-hemisphere GI bounce, shaded like inline ---
+  vec3 wi = cosineSampleHemisphere(N, rand2());
+  vec3 hitPos;
+  vec3 rad = traceRadianceGI(P + N * uEps, wi, hitPos);
+  // Match the inline firefly clamp, which is applied to indirect (= L_i) so
+  // the biased mean of the two paths agrees.
+  float rl = luminance(rad);
+  if (rl > uFireflyClamp) rad *= uFireflyClamp / rl;
+
+  float cosT = max(dot(N, wi), 0.0);
+  float pHatFresh = luminance(rad) * cosT;
+  // w = p_hat / p_source = p_hat / (cos/PI). cosT cancels; guard cosT==0.
+  float wFresh = cosT > 0.0 ? pHatFresh * PI / cosT : 0.0;
+
+  float wSum = wFresh;
+  float M = 1.0;
+  vec3 selRad = rad;
+  vec3 selPos = hitPos;
+
+  // --- temporal reuse: reproject P, validate the SAME surface, merge history ---
+  vec4 clip = uPrevViewProj * vec4(P, 1.0);
+  if (clip.w > 0.0) {
+    vec2 prevUv = (clip.xy / clip.w) * 0.5 + 0.5;
+    if (prevUv.x >= 0.0 && prevUv.x <= 1.0 && prevUv.y >= 0.0 && prevUv.y <= 1.0) {
+      vec4 pPos = texture(uPrevGWorldPos, prevUv);
+      float tol = 0.005 * distance(P, uCameraPos) + 20.0 * uEps;
+      if (pPos.w > 0.5 && abs(dot(P - pPos.xyz, N)) < tol) {
+        vec4 hp = texture(uPrevResPos, prevUv);  // hitPos.xyz + M
+        vec4 hr = texture(uPrevResRad, prevUv);  // radiance.rgb + W
+        float Mprev = hp.w;
+        float Wprev = hr.w;
+        if (Mprev > 0.0 && Wprev > 0.0) {
+          vec3 radPrev = hr.rgb;
+          vec3 hitPrev = hp.xyz;
+          // Re-evaluate the target at the CURRENT surface (reconnect at the
+          // stored hit point). Same world point P (validated), so no Jacobian.
+          vec3 dp = hitPrev - P;
+          float dl = length(dp);
+          float cosPrev = dl > 1e-5 ? max(dot(N, dp / dl), 0.0) : 0.0;
+          float pHatPrev = luminance(radPrev) * cosPrev;
+          float Mc = min(Mprev, uMCap);
+          // Combine reservoirs: w = p_hat_current(sample) * W_prev * M_prev.
+          float w = pHatPrev * Wprev * Mc;
+          wSum += w;
+          M += Mc;
+          if (w > 0.0 && rand() * wSum < w) {
+            selRad = radPrev;
+            selPos = hitPrev;
+          }
+        }
+      }
+    }
+  }
+
+  // --- finalize: recompute p_hat(selected) at this surface, form W, resolve ---
+  vec3 sd = selPos - P;
+  float sl = length(sd);
+  float selCos = sl > 1e-5 ? max(dot(N, sd / sl), 0.0) : 0.0;
+  float pHatSel = luminance(selRad) * selCos;
+  float W = (M > 0.0 && pHatSel > 0.0) ? wSum / (M * pHatSel) : 0.0;
+
+  vec3 gi = selRad * (selCos / PI) * W;   // demodulated indirect irradiance
+  float gil = luminance(gi);
+  if (gil > uFireflyClamp) gi *= uFireflyClamp / gil;  // matches inline safety net
+  if (any(isnan(gi)) || any(isinf(gi))) gi = vec3(0.0);
+  if (any(isnan(selRad)) || any(isinf(selRad))) { selRad = vec3(0.0); W = 0.0; }
+
+  outResPos = vec4(selPos, M);
+  outResRad = vec4(selRad, W);
+  outGI = vec4(gi, 1.0);
+}
+`;
+
+/**
+ * EXPERIMENTAL ReSTIR GI (v1, temporal-only). Per-pixel reservoirs reuse the
+ * 1-bounce GI sample across frames at the reprojected same-surface point. Runs
+ * at lighting resolution with its OWN sampler budget (16: 8 BVH + 2 attr + 1
+ * scene-data + gWorldPos + gNormalMetal + prevGWorldPos + 2 reservoir history),
+ * independent of the lighting pass. render() returns a resolved, demodulated GI
+ * irradiance texture whose mean matches the inline GI path (see main()).
+ *
+ * NO spatial reuse in v1: spatial reuse needs the solid-angle->area Jacobian and
+ * is where implementations go subtly wrong. Temporal reuse at the same surface
+ * point does not.
+ */
+export class GIReservoirPass {
+  constructor(width, height) {
+    this.targetA = this._makeTarget(width, height);
+    this.targetB = this._makeTarget(width, height);
+
+    this.material = new THREE.ShaderMaterial({
+      glslVersion: THREE.GLSL3,
+      vertexShader: fullscreenVert,
+      fragmentShader: giFrag,
+      uniforms: {
+        bvhStatic: { value: null },
+        bvhDynamic: { value: null },
+        uHasDynamic: { value: false },
+        uAttrStatic: { value: null },
+        uAttrDynamic: { value: null },
+        uMaterialsTex: { value: null },
+        uGWorldPos: { value: null },
+        uGNormalMetal: { value: null },
+        uPrevGWorldPos: { value: null },
+        uPrevResPos: { value: null },
+        uPrevResRad: { value: null },
+        uPrevViewProj: { value: new THREE.Matrix4() },
+        uLightPosType: { value: [] },
+        uLightColorRadius: { value: [] },
+        uLightDirCone: { value: [] },
+        uLightCount: { value: 0 },
+        uEmissiveCount: { value: 0 },
+        uEmissiveCDF: { value: true },
+        uCameraPos: { value: new THREE.Vector3() },
+        uFrame: { value: 0 },
+        uEps: { value: 1e-3 },
+        uFireflyClamp: { value: 4.0 },
+        uMCap: { value: 20 },
+        uEnvColor: { value: new THREE.Color(0.03, 0.04, 0.06) },
+        uEnvIntensity: { value: 1.0 },
+        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) },
+        uSkyZenith: { value: new THREE.Color(0.18, 0.34, 0.62) },
+        uSkyHorizon: { value: new THREE.Color(0.7, 0.8, 0.9) },
+        uSkyIntensity: { value: 1.0 },
+      },
+      depthTest: false,
+      depthWrite: false,
+    });
+
+    this.scene = new THREE.Scene();
+    this.camera = new THREE.OrthographicCamera(-1, 1, 1, -1, 0, 1);
+    this.quad = new THREE.Mesh(new THREE.PlaneGeometry(2, 2), this.material);
+    this.quad.frustumCulled = false;
+    this.scene.add(this.quad);
+  }
+
+  _makeTarget(width, height) {
+    // Three fp32 attachments, NearestFilter: the reservoir stores a hit POSITION
+    // (needs fp32) + M + radiance + W, which must never be interpolated. All fp32
+    // (rather than a mixed fp32/fp16 layout) sidesteps drivers that reject mixed
+    // MRT precision; the resolved GI (attachment 2) is read 1:1 by the denoise.
+    const t = new THREE.WebGLMultipleRenderTargets(width, height, 3, {
+      minFilter: THREE.NearestFilter,
+      magFilter: THREE.NearestFilter,
+      format: THREE.RGBAFormat,
+      type: THREE.FloatType,
+      depthBuffer: false,
+      stencilBuffer: false,
+    });
+    for (const tex of t.texture) tex.generateMipmaps = false;
+    return t;
+  }
+
+  setCompiledScene(compiled) {
+    const u = this.material.uniforms;
+    u.bvhStatic.value = compiled.staticBvhUniform;
+    u.bvhDynamic.value = compiled.dynamicBvhUniform;
+    u.uHasDynamic.value = compiled.hasDynamic;
+    u.uAttrStatic.value = compiled.staticAttrTex;
+    u.uAttrDynamic.value = compiled.dynamicAttrTex;
+    u.uMaterialsTex.value = compiled.materialsTex;
+    u.uLightPosType.value = compiled.lightPosType;
+    u.uLightColorRadius.value = compiled.lightColorRadius;
+    u.uLightDirCone.value = compiled.lightDirCone;
+    u.uLightCount.value = compiled.lightCount;
+    u.uEmissiveCount.value = compiled.emissiveTriCount;
+  }
+
+  /** Emissive candidates follow the emissiveNEE toggle (set per frame). */
+  setEmissiveCount(count) {
+    this.material.uniforms.uEmissiveCount.value = count;
+  }
+
+  clearHistory(renderer) {
+    const prev = renderer.getRenderTarget();
+    renderer.setClearColor(0x000000, 0);
+    for (const t of [this.targetA, this.targetB]) {
+      renderer.setRenderTarget(t);
+      renderer.clear(true, false, false);
+    }
+    renderer.setRenderTarget(prev);
+  }
+
+  setSize(width, height) {
+    this.targetA.setSize(width, height);
+    this.targetB.setSize(width, height);
+  }
+
+  /**
+   * Renders into targetA (reading targetB as reservoir history), swaps, and
+   * returns the resolved GI irradiance texture (attachment 2). `params` carries
+   * the per-frame lighting state (sky/env, firefly clamp, emissive CDF, M-cap).
+   */
+  render(renderer, gbuffer, prevViewProj, cameraPos, frame, eps, params) {
+    const u = this.material.uniforms;
+    u.uGWorldPos.value = gbuffer.worldPos;
+    u.uGNormalMetal.value = gbuffer.normalMetal;
+    u.uPrevGWorldPos.value = gbuffer.prevWorldPos;
+    u.uPrevResPos.value = this.targetB.texture[0];
+    u.uPrevResRad.value = this.targetB.texture[1];
+    u.uPrevViewProj.value.copy(prevViewProj);
+    u.uCameraPos.value.copy(cameraPos);
+    u.uFrame.value = frame;
+    u.uEps.value = eps;
+    u.uFireflyClamp.value = params.fireflyClamp;
+    u.uMCap.value = params.mCap;
+    u.uEmissiveCDF.value = params.emissiveCDF;
+    u.uEnvColor.value.copy(params.envColor);
+    u.uEnvIntensity.value = params.envIntensity;
+    u.uSkyEnabled.value = params.skyEnabled;
+    u.uSunDir.value.copy(params.sunDir);
+    u.uSunColor.value.copy(params.sunColor);
+    u.uSkyZenith.value.copy(params.skyZenith);
+    u.uSkyHorizon.value.copy(params.skyHorizon);
+    u.uSkyIntensity.value = params.skyIntensity;
+
+    renderer.setRenderTarget(this.targetA);
+    renderer.render(this.scene, this.camera);
+    renderer.setRenderTarget(null);
+
+    const out = this.targetA;
+    [this.targetA, this.targetB] = [this.targetB, this.targetA];
+    return out.texture[2];
+  }
+
+  dispose() {
+    this.targetA.dispose();
+    this.targetB.dispose();
+    this.material.dispose();
+    this.quad.geometry.dispose();
+  }
+}