three-realtime-rt 0.4.0 → 0.5.0

package/src/RTLightingPass.js

@@ -75,6 +75,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).
@@ -541,13 +553,13 @@ 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) {
+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;
+  float eta = 1.0 / ior;
   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);
@@ -563,7 +575,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, ior);
     if (rd2 == vec3(0.0)) rd2 = reflect(rd, xN);
     refrRad = traceRadiance(xP - xN * uEps, rd2, true);
   } else {
@@ -574,6 +586,26 @@ vec3 glassRadiance(vec3 P, vec3 N, vec3 V, float rough) {
   return mix(refrRad, 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() {
   vec4 wp = texture(uGWorldPos, vUv);
   if (wp.w < 0.5) {
@@ -599,6 +631,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 +644,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
@@ -634,11 +675,32 @@ void main() {
   // (unbiased) while GI's ray cost halves; accumulation + denoise absorb
   // the alternation.
   gWantSpec = false; // secondary bounces contribute to diffuse GI only
+  // BLEND pixels reuse THIS call site as their straight-through view
+  // continuation instead of a GI bounce (their behind-image rides the specular
+  // attachment; the pane forgoes its own GI bounce — visually negligible, and
+  // it saves a ray). CRITICAL CALL-SITE BUDGET: traceRadiance may appear at
+  // most THREE times in this shader (glass refraction exit, this unified
+  // secondary site, the metal-reflection path). WebKit's GLSL->Metal
+  // translation silently emits a broken program at a FOURTH inlined call site
+  // (clean compile, black output on every iOS browser) — bisected live on an
+  // iPad, 2026-07-22. Never add a call site; extend this one.
   vec3 indirect = vec3(0.0);
-  if (uGIEnabled) {
-    bool trace = !uGIHalfRate || (((px.x + px.y + int(uFrame)) & 1) == 0);
-    if (trace) {
-      indirect = traceRadiance(P + N * uEps, cosineSampleHemisphere(N, rand2()), false);
+  vec3 blendBehind = vec3(0.0);
+  bool wantBehind = uBlendEnabled && blend;
+  // 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);
+    vec3 dir = wantBehind ? Vv : cosineSampleHemisphere(N, rand2());
+    vec3 org = wantBehind ? P + Vv * uEps : P + N * uEps;
+    vec3 r = traceRadiance(org, dir, wantBehind);
+    if (wantBehind) {
+      blendBehind = r;
+    } else {
+      indirect = r;
       if (uGIHalfRate) indirect *= 2.0;
     }
   }
@@ -667,7 +729,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 ---
@@ -685,11 +747,8 @@ void main() {
   // where the pane's albedo is actually available. sampleIrr keeps only the
   // pane's own surface lighting, which is static on the surface and accumulates
   // with normal full-length history.
-  vec3 blendBehind = vec3(0.0);
-  if (uBlendEnabled && blend) {
-    vec3 V = normalize(P - uCameraPos);
-    blendBehind = traceRadiance(P + V * uEps, V, true);
-  }
+  // (The straight-through trace itself happens at the unified secondary-ray
+  // call site above — see the Metal call-site-count note there.)
 
   // A single NaN/Inf sample would poison the EMA history for good (mix() with
   // NaN stays NaN until a disocclusion resets the pixel) — sanitize first.
@@ -757,6 +816,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);
+  }
 }
 `;
 
@@ -854,18 +924,31 @@ void main() {
  * into a second ping-pong pair, specA/specB).
  */
 export class RTLightingPass {
-  constructor(width, height) {
+  // `specMRT: false` is the WebKit fallback: iOS Safari (every iOS browser)
+  // silently fails the 2-attachment half-float MRT draw — the whole lighting
+  // pass renders black. RealtimeRaytracer probes this functionally at
+  // construction; in fallback mode this pass allocates a single-attachment
+  // target exactly like 0.3.x, the shader's second output collapses to a dead
+  // local variable, and render() returns { specular: null } (the caller then
+  // runs with specular off; blend surfaces degrade to opaque as documented).
+  constructor(width, height, { specMRT = true } = {}) {
+    this.specMRT = specMRT;
     this.targetA = this._makeTarget(width, height);
     this.targetB = this._makeTarget(width, height);
     // Accumulated specular history (ping-pong), fed by the fresh specular in
     // targetA/B attachment 1.
-    this.specA = this._makeSpecTarget(width, height);
-    this.specB = this._makeSpecTarget(width, height);
+    this.specA = specMRT ? this._makeSpecTarget(width, height) : null;
+    this.specB = specMRT ? this._makeSpecTarget(width, height) : null;
 
     this.material = new THREE.ShaderMaterial({
       glslVersion: THREE.GLSL3,
       vertexShader: fullscreenVert,
-      fragmentShader: rtLightingFrag,
+      fragmentShader: specMRT
+        ? rtLightingFrag
+        : rtLightingFrag.replace(
+            "layout(location = 1) out vec4 outSpecular;",
+            "vec4 outSpecular; // single-target fallback: dead store"
+          ),
       uniforms: {
         bvhStatic: { value: null },
         bvhDynamic: { value: null },
@@ -902,6 +985,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) },
@@ -936,11 +1022,18 @@ export class RTLightingPass {
       depthWrite: false,
     });
 
-    // 2-output history carry (see mrtCarryFrag) — matches the MRT's draw buffers.
+    // 2-output history carry (see mrtCarryFrag) — matches the MRT's draw
+    // buffers. In single-target fallback the second output collapses the same
+    // way as the lighting shader's.
     this.carryMaterial = new THREE.ShaderMaterial({
       glslVersion: THREE.GLSL3,
       vertexShader: fullscreenVert,
-      fragmentShader: mrtCarryFrag,
+      fragmentShader: specMRT
+        ? mrtCarryFrag
+        : mrtCarryFrag.replace(
+            "layout(location = 1) out vec4 o1;",
+            "vec4 o1; // single-target fallback: dead store"
+          ),
       uniforms: { uTex: { value: null }, uCountClamp: { value: -1 } },
       depthTest: false,
       depthWrite: false,
@@ -957,19 +1050,31 @@ export class RTLightingPass {
     // Half-float + linear: history is sampled bilinearly at reprojected UVs,
     // and fp16 halves the bandwidth (EMA blending never accumulates a raw sum,
     // so fp16 precision is sufficient). Two attachments: [0] irradiance,
-    // [1] fresh dielectric specular.
-    const t = new THREE.WebGLMultipleRenderTargets(width, height, 2, {
+    // [1] fresh dielectric specular — or a single attachment in the WebKit
+    // fallback (see the constructor note).
+    const opts = {
       minFilter: THREE.LinearFilter,
       magFilter: THREE.LinearFilter,
       format: THREE.RGBAFormat,
       type: THREE.HalfFloatType,
       depthBuffer: false,
       stencilBuffer: false,
-    });
+    };
+    if (!this.specMRT) {
+      const t = new THREE.WebGLRenderTarget(width, height, opts);
+      t.texture.generateMipmaps = false;
+      return t;
+    }
+    const t = new THREE.WebGLMultipleRenderTargets(width, height, 2, opts);
     for (const tex of t.texture) tex.generateMipmaps = false;
     return t;
   }
 
+  // The accumulated-irradiance texture of a history target, either layout.
+  _irrTex(target) {
+    return this.specMRT ? target.texture[0] : target.texture;
+  }
+
   _makeSpecTarget(width, height) {
     const t = new THREE.WebGLRenderTarget(width, height, {
       minFilter: THREE.LinearFilter,
@@ -991,6 +1096,7 @@ export class RTLightingPass {
     const prevAlpha = renderer.getClearAlpha();
     renderer.setClearColor(0x000000, 0);
     for (const t of [this.targetA, this.targetB, this.specA, this.specB]) {
+      if (!t) continue; // spec pair is absent in the single-target fallback
       renderer.setRenderTarget(t);
       renderer.clear(true, false, false);
     }
@@ -1001,8 +1107,8 @@ export class RTLightingPass {
   setSize(width, height) {
     this.targetA.setSize(width, height);
     this.targetB.setSize(width, height);
-    this.specA.setSize(width, height);
-    this.specB.setSize(width, height);
+    if (this.specA) this.specA.setSize(width, height);
+    if (this.specB) this.specB.setSize(width, height);
   }
 
   /**
@@ -1025,7 +1131,7 @@ export class RTLightingPass {
     // material so the draw matches the MRT's draw buffers (a 1-output CopyPass
     // blit here is INVALID_OPERATION on ANGLE/D3D11). Attachment 1 is fresh-
     // written every frame, so it needs no carry.
-    this.carryMaterial.uniforms.uTex.value = this.targetB.texture[0];
+    this.carryMaterial.uniforms.uTex.value = this._irrTex(this.targetB);
     this.carryMaterial.uniforms.uCountClamp.value = carryFrames;
     this.quad.material = this.carryMaterial;
     const prev = renderer.getRenderTarget();
@@ -1039,13 +1145,15 @@ export class RTLightingPass {
     this.targetB = newB;
 
     // Specular history carries the same way (freshest is specB — see render()).
-    const newSpecA = this._makeSpecTarget(width, height);
-    const newSpecB = this._makeSpecTarget(width, height);
-    copyPass.blit(renderer, this.specB.texture, newSpecB, carryFrames);
-    this.specA.dispose();
-    this.specB.dispose();
-    this.specA = newSpecA;
-    this.specB = newSpecB;
+    if (this.specMRT) {
+      const newSpecA = this._makeSpecTarget(width, height);
+      const newSpecB = this._makeSpecTarget(width, height);
+      copyPass.blit(renderer, this.specB.texture, newSpecB, carryFrames);
+      this.specA.dispose();
+      this.specB.dispose();
+      this.specA = newSpecA;
+      this.specB = newSpecB;
+    }
   }
 
   setCompiledScene(compiled) {
@@ -1074,7 +1182,7 @@ export class RTLightingPass {
     u.uGWorldPos.value = gbuffer.worldPos;
     u.uGNormalMetal.value = gbuffer.normalMetal;
     u.uPrevGWorldPos.value = gbuffer.prevWorldPos;
-    u.uPrevAccum.value = this.targetB.texture[0];
+    u.uPrevAccum.value = this._irrTex(this.targetB);
     u.uReservoir.value = reservoirTexture;
     u.uRestirEnabled.value = reservoirTexture !== null;
     u.uFrame.value = frame;
@@ -1085,37 +1193,42 @@ export class RTLightingPass {
     renderer.render(this.scene, this.camera);
 
     // 2. specular temporal accumulation: fresh (targetA[1]) + history (specB).
-    const su = this.specMaterial.uniforms;
-    su.uFreshSpec.value = this.targetA.texture[1];
-    su.uPrevSpec.value = this.specB.texture;
-    su.uGWorldPos.value = gbuffer.worldPos;
-    su.uGNormalMetal.value = gbuffer.normalMetal;
-    su.uPrevGWorldPos.value = gbuffer.prevWorldPos;
-    su.uPrevViewProj.value.copy(u.uPrevViewProj.value);
-    su.uViewProj.value.copy(u.uViewProj.value);
-    su.uCameraPos.value.copy(u.uCameraPos.value);
-    su.uEps.value = u.uEps.value;
-    su.uMaxHistory.value = u.uMaxHistory.value;
-    su.uTemporalReprojection.value = u.uTemporalReprojection.value;
-    this.quad.material = this.specMaterial;
-    renderer.setRenderTarget(this.specA);
-    renderer.render(this.scene, this.camera);
+    // Skipped entirely in the single-target fallback — there is no fresh
+    // specular attachment to accumulate.
+    let outSpec = null;
+    if (this.specMRT) {
+      const su = this.specMaterial.uniforms;
+      su.uFreshSpec.value = this.targetA.texture[1];
+      su.uPrevSpec.value = this.specB.texture;
+      su.uGWorldPos.value = gbuffer.worldPos;
+      su.uGNormalMetal.value = gbuffer.normalMetal;
+      su.uPrevGWorldPos.value = gbuffer.prevWorldPos;
+      su.uPrevViewProj.value.copy(u.uPrevViewProj.value);
+      su.uViewProj.value.copy(u.uViewProj.value);
+      su.uCameraPos.value.copy(u.uCameraPos.value);
+      su.uEps.value = u.uEps.value;
+      su.uMaxHistory.value = u.uMaxHistory.value;
+      su.uTemporalReprojection.value = u.uTemporalReprojection.value;
+      this.quad.material = this.specMaterial;
+      renderer.setRenderTarget(this.specA);
+      renderer.render(this.scene, this.camera);
+      outSpec = this.specA.texture;
+    }
 
     this.quad.material = this.material; // restore for the next caller
     renderer.setRenderTarget(null);
 
-    const outIrr = this.targetA.texture[0];
-    const outSpec = this.specA.texture;
+    const outIrr = this._irrTex(this.targetA);
     [this.targetA, this.targetB] = [this.targetB, this.targetA];
-    [this.specA, this.specB] = [this.specB, this.specA];
+    if (this.specMRT) [this.specA, this.specB] = [this.specB, this.specA];
     return { irradiance: outIrr, specular: outSpec };
   }
 
   dispose() {
     this.targetA.dispose();
     this.targetB.dispose();
-    this.specA.dispose();
-    this.specB.dispose();
+    if (this.specA) this.specA.dispose();
+    if (this.specB) this.specB.dispose();
     this.material.dispose();
     this.specMaterial.dispose();
     this.carryMaterial.dispose();