three-realtime-rt 0.4.0 → 0.4.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "three-realtime-rt",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Turn-on ray traced lighting for three.js: a hybrid deferred renderer with BVH-traced soft shadows, one-bounce global illumination, temporal reprojection, an a-trous denoiser and TAA.",
   "type": "module",
   "main": "src/index.js",

package/src/RTLightingPass.js

@@ -634,11 +634,29 @@ 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;
+  bool wantGI = uGIEnabled && !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;
     }
   }
@@ -685,11 +703,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.
@@ -854,18 +869,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 },
@@ -936,11 +964,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 +992,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 +1038,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 +1049,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 +1073,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 +1087,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 +1124,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 +1135,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();

package/src/RealtimeRaytracer.js

@@ -242,6 +242,72 @@ export class RealtimeRaytracer {
     }
   }
 
+  /**
+   * FUNCTIONAL probe: can this context actually DRAW into a 2-attachment
+   * half-float MRT? A checkFramebufferStatus probe is not enough — WebKit
+   * (every iOS browser) reports the framebuffer complete and then renders
+   * black, which killed the whole lighting pass on iPhone/iPad in 0.4.0.
+   * So: render one 2-output quad into a tiny fp16 MRT, resolve attachment 0
+   * into an RGBA8 target through a sampler, and read the pixel back. Only a
+   * round-trip that returns the written value counts as support.
+   */
+  static _specMrtSupported(renderer) {
+    let mrt, out, mat, copy, quad, scene2, cam;
+    const prevTarget = renderer.getRenderTarget();
+    try {
+      mrt = new THREE.WebGLMultipleRenderTargets(2, 2, 2, {
+        format: THREE.RGBAFormat,
+        type: THREE.HalfFloatType,
+        depthBuffer: false,
+        stencilBuffer: false,
+      });
+      for (const tex of mrt.texture) tex.generateMipmaps = false;
+      out = new THREE.WebGLRenderTarget(2, 2, { depthBuffer: false, stencilBuffer: false });
+      const vert = `out vec2 vUv; void main(){ vUv = uv; gl_Position = vec4(position.xy, 0.0, 1.0); }`;
+      mat = new THREE.ShaderMaterial({
+        glslVersion: THREE.GLSL3,
+        vertexShader: vert,
+        fragmentShader: `precision highp float;
+layout(location = 0) out vec4 o0; layout(location = 1) out vec4 o1;
+void main(){ o0 = vec4(0.5, 0.25, 0.75, 1.0); o1 = vec4(0.125); }`,
+        depthTest: false,
+        depthWrite: false,
+      });
+      copy = new THREE.ShaderMaterial({
+        glslVersion: THREE.GLSL3,
+        vertexShader: vert,
+        fragmentShader: `precision highp float; in vec2 vUv; out vec4 outColor;
+uniform sampler2D uTex; void main(){ outColor = texture(uTex, vUv); }`,
+        uniforms: { uTex: { value: mrt.texture[0] } },
+        depthTest: false,
+        depthWrite: false,
+      });
+      scene2 = new THREE.Scene();
+      cam = new THREE.OrthographicCamera(-1, 1, 1, -1, 0, 1);
+      quad = new THREE.Mesh(new THREE.PlaneGeometry(2, 2), mat);
+      quad.frustumCulled = false;
+      scene2.add(quad);
+      renderer.setRenderTarget(mrt);
+      renderer.render(scene2, cam);
+      quad.material = copy;
+      renderer.setRenderTarget(out);
+      renderer.render(scene2, cam);
+      const px = new Uint8Array(4);
+      renderer.readRenderTargetPixels(out, 0, 0, 1, 1, px);
+      // 0.5 -> ~128; accept a generous tolerance (fp16 + dithering).
+      return Math.abs(px[0] - 128) < 24 && Math.abs(px[1] - 64) < 24;
+    } catch {
+      return false;
+    } finally {
+      renderer.setRenderTarget(prevTarget);
+      if (quad) quad.geometry.dispose();
+      if (mat) mat.dispose();
+      if (copy) copy.dispose();
+      if (mrt) mrt.dispose();
+      if (out) out.dispose();
+    }
+  }
+
   /**
    * Companion settings for a given lighting resolution. LOW resolution wants
    * MORE denoise passes, not fewer — the filter runs at lighting res so extra
@@ -325,8 +391,22 @@ export class RealtimeRaytracer {
     if (!mixedPrecision) {
       console.info("three-realtime-rt: mixed fp16/fp32 G-buffer not supported here — using fp32 for all targets.");
     }
+    // Functional probe, not just a status check: WebKit (all iOS browsers)
+    // reports the 2-attachment fp16 MRT complete but silently renders black,
+    // which blanks the whole lighting pass. On such devices the lighting pass
+    // runs single-attachment (0.3.x layout): the specular buffer is disabled
+    // and blend surfaces degrade to opaque — everything else keeps working.
+    this.specMRTSupported = RealtimeRaytracer._specMrtSupported(renderer);
+    if (!this.specMRTSupported) {
+      console.info(
+        "three-realtime-rt: multi-attachment lighting buffer failed the draw probe here " +
+          "(WebKit/iOS) — specular buffer disabled, alpha-blend surfaces render opaque."
+      );
+    }
     this.gbuffer = new GBufferPass(this._width, this._height, { mixedPrecision });
-    this.rtPass = new RTLightingPass(this._scaledW, this._scaledH);
+    this.rtPass = new RTLightingPass(this._scaledW, this._scaledH, {
+      specMRT: this.specMRTSupported,
+    });
     this.denoisePass = new DenoisePass(this._scaledW, this._scaledH);
     // Separate à-trous instance for the specular buffer (its own ping-pong
     // targets, so the specular denoise cannot clobber the irradiance result).
@@ -343,7 +423,7 @@ export class RealtimeRaytracer {
     this.compiled = null;
     this.frame = 0;
 
-    /** Debug view: 0 composite, 1 albedo, 2 normal, 3 irradiance, 4 worldPos, 5 emissive */
+    /** Debug view: 0 composite, 1 albedo, 2 normal, 3 irradiance, 4 worldPos, 5 emissive, 6 specular */
     this.outputMode = 0;
     /** Environment (sky) color used for GI rays that miss + composite background. */
     this.envColor = options.envColor ?? new THREE.Color(0.03, 0.04, 0.06);

package/src/index.d.ts

@@ -288,6 +288,12 @@ export class RealtimeRaytracer {
   renderer: WebGLRenderer;
   /** False when the platform can't run the tracer; render() then forwards to renderer.render. */
   supported: boolean;
+  /**
+   * False when the 2-attachment lighting buffer fails the construction-time
+   * draw probe (WebKit/iOS): the specular buffer is disabled there and
+   * alpha-blend surfaces render opaque; everything else keeps working.
+   */
+  specMRTSupported: boolean;
   /** The current compiled scene, or null before the first compile / when unsupported. */
   compiled: CompiledScene | null;
   /** Accumulated frame counter. */