three-realtime-rt 0.3.0 → 0.4.0

package/src/CopyPass.js

@@ -0,0 +1,75 @@
+import * as THREE from "three";
+
+const fullscreenVert = /* glsl */ `
+out vec2 vUv;
+void main() {
+  vUv = uv;
+  gl_Position = vec4(position.xy, 0.0, 1.0);
+}
+`;
+
+// Copies a texture into the bound target, bilinearly resampling when the sizes
+// differ (history targets use LinearFilter, so a resolution change is handled
+// for free). uCountClamp < 0 copies verbatim; >= 0 caps the alpha channel —
+// used to carry accumulation history across a reallocation while REDUCING (not
+// zeroing) the per-pixel sample count, so the temporal EMA reconverges smoothly
+// instead of strobing back to raw 1-spp noise.
+const copyFrag = /* glsl */ `
+precision highp float;
+layout(location = 0) out vec4 outColor;
+in vec2 vUv;
+uniform sampler2D uTex;
+uniform float uCountClamp;
+void main() {
+  vec4 c = texture(uTex, vUv);
+  if (uCountClamp >= 0.0) c.a = min(c.a, uCountClamp);
+  outColor = c;
+}
+`;
+
+/**
+ * Minimal fullscreen texture copy on its own program (one sampler — safely
+ * separate from the 16-sampler lighting pass). Used to blit history buffers
+ * into freshly reallocated targets during a resolution change: the linear
+ * resample absorbs the size difference, and the optional alpha clamp turns a
+ * hard accumulation reset into a soft "keep a few frames of confidence" carry.
+ */
+export class CopyPass {
+  constructor() {
+    this.material = new THREE.ShaderMaterial({
+      glslVersion: THREE.GLSL3,
+      vertexShader: fullscreenVert,
+      fragmentShader: copyFrag,
+      uniforms: {
+        uTex: { value: null },
+        uCountClamp: { value: -1 },
+      },
+      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);
+  }
+
+  /**
+   * Blit srcTexture into dstTarget. countClamp < 0 copies rgba verbatim; >= 0
+   * caps the alpha (accumulation-count) channel to that value.
+   */
+  blit(renderer, srcTexture, dstTarget, countClamp = -1) {
+    this.material.uniforms.uTex.value = srcTexture;
+    this.material.uniforms.uCountClamp.value = countClamp;
+    const prev = renderer.getRenderTarget();
+    renderer.setRenderTarget(dstTarget);
+    renderer.render(this.scene, this.camera);
+    renderer.setRenderTarget(prev);
+  }
+
+  dispose() {
+    this.material.dispose();
+    this.quad.geometry.dispose();
+  }
+}

package/src/DenoisePass.js

@@ -1,202 +1,221 @@
-import * as THREE from "three";
-
-const fullscreenVert = /* glsl */ `
-out vec2 vUv;
-void main() {
-  vUv = uv;
-  gl_Position = vec4(position.xy, 0.0, 1.0);
-}
-`;
-
-const atrousFrag = /* glsl */ `
-precision highp float;
-
-layout(location = 0) out vec4 outColor;
-
-in vec2 vUv;
-
-uniform sampler2D uIrradiance;   // rgb = irradiance, a = history count
-uniform sampler2D uGWorldPos;    // full-res guides
-uniform sampler2D uGNormalMetal;
-uniform vec2 uTexelSize;         // of the irradiance target
-uniform float uStep;             // à-trous step: 1, 2, 4, ...
-uniform vec3 uCameraPos;
-uniform float uEps;
-uniform float uLumSigma;
-
-float luminance(vec3 c) {
-  return dot(c, vec3(0.299, 0.587, 0.114));
-}
-
-void main() {
-  vec4 center = texture(uIrradiance, vUv);
-  vec4 wp = texture(uGWorldPos, vUv);
-  if (wp.w < 0.5) {
-    outColor = center;
-    return;
-  }
-  vec3 P = wp.xyz;
-  vec4 nm = texture(uGNormalMetal, vUv);
-  vec3 N = normalize(nm.xyz);
-  // Specular surfaces (mirror metals, glass) carry traced reflections whose
-  // detail is NOT in the G-buffer guides — filtering would smear them, and
-  // their signal is nearly deterministic anyway. Scale the filter down as the
-  // surface gets more mirror-like.
-  float matW = nm.w;
-  float specAmount = matW >= 2.0 ? clamp(matW - 2.0, 0.0, 1.0) : matW;
-  float specKeep = specAmount * (1.0 - clamp(wp.w - 1.0, 0.0, 1.0));
-
-  // Fewer accumulated samples -> noisier pixel -> wider luminance tolerance.
-  // A converged pixel (high count) is barely touched, preserving detail.
-  float count = max(center.a, 1.0);
-  float sigmaL = uLumSigma * clamp(8.0 / sqrt(count), 0.75, 8.0);
-
-  float distToCam = distance(P, uCameraPos);
-  float planeTol = 0.01 * distToCam + 20.0 * uEps;
-
-  // Despeckle (first iteration, short history only): a freshly disoccluded
-  // pixel can carry one huge sample that the center-weighted filter would
-  // preserve as a bright "rain drop" at silhouettes. Such a pixel has no
-  // business being brighter than its entire neighbourhood — clamp its
-  // luminance to the brightest neighbour. Converged pixels are exempt, so
-  // real small highlights survive.
-  if (uStep < 1.5 && count < 8.0) {
-    float maxL = 0.0;
-    float found = 0.0;
-    for (int dy = -1; dy <= 1; dy++) {
-      for (int dx = -1; dx <= 1; dx++) {
-        if (dx == 0 && dy == 0) continue;
-        vec2 tuv = vUv + vec2(float(dx), float(dy)) * uTexelSize;
-        if (tuv.x < 0.0 || tuv.x > 1.0 || tuv.y < 0.0 || tuv.y > 1.0) continue;
-        if (texture(uGWorldPos, tuv).w < 0.5) continue;
-        maxL = max(maxL, luminance(texture(uIrradiance, tuv).rgb));
-        found = 1.0;
-      }
-    }
-    float cap = maxL * 1.25 + 1e-4;
-    float l = luminance(center.rgb);
-    if (found > 0.5 && l > cap) center.rgb *= cap / l;
-  }
-
-  float lumC = luminance(center.rgb);
-
-  // 3x3 B-spline-ish kernel, edge-avoiding weights.
-  vec3 sum = center.rgb * 4.0;
-  float wsum = 4.0;
-  for (int dy = -1; dy <= 1; dy++) {
-    for (int dx = -1; dx <= 1; dx++) {
-      if (dx == 0 && dy == 0) continue;
-      vec2 tuv = vUv + vec2(float(dx), float(dy)) * uStep * uTexelSize;
-      if (tuv.x < 0.0 || tuv.x > 1.0 || tuv.y < 0.0 || tuv.y > 1.0) continue;
-
-      vec4 g = texture(uGWorldPos, tuv);
-      if (g.w < 0.5) continue;
-      vec4 s = texture(uIrradiance, tuv);
-      vec3 Nt = normalize(texture(uGNormalMetal, tuv).xyz);
-
-      float k = (dx == 0 || dy == 0) ? 2.0 : 1.0;
-      float wN = pow(max(dot(N, Nt), 0.0), 32.0);
-      float wZ = exp(-abs(dot(g.xyz - P, N)) / planeTol);
-      // Tighten the luminance gate as the à-trous step widens: a shadow on a
-      // flat floor has no geometric edge to protect it, so at high iteration
-      // counts the wide passes would average it away ("floating" objects with
-      // no contact shadow). Wide steps only get to blend near-equal luminance.
-      float wL = exp(-abs(luminance(s.rgb) - lumC) / (sigmaL * inversesqrt(uStep)));
-      float w = k * wN * wZ * wL * (1.0 - specKeep);
-      sum += s.rgb * w;
-      wsum += w;
-    }
-  }
-  outColor = vec4(sum / wsum, center.a);
-}
-`;
-
-/**
- * Edge-avoiding à-trous wavelet filter (SVGF-lite) on the demodulated
- * irradiance buffer, guided by the full-res G-buffer (plane distance +
- * normals) and modulated by per-pixel history count: freshly disoccluded
- * pixels get blurred hard, converged pixels stay crisp.
- */
-export class DenoisePass {
-  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: atrousFrag,
-      uniforms: {
-        uIrradiance: { value: null },
-        uGWorldPos: { value: null },
-        uGNormalMetal: { value: null },
-        uTexelSize: { value: new THREE.Vector2() },
-        uStep: { value: 1 },
-        uCameraPos: { value: new THREE.Vector3() },
-        uEps: { value: 1e-3 },
-        uLumSigma: { value: 0.25 },
-      },
-      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);
-
-    this._width = width;
-    this._height = height;
-  }
-
-  _makeTarget(width, height) {
-    const t = new THREE.WebGLRenderTarget(width, height, {
-      minFilter: THREE.LinearFilter,
-      magFilter: THREE.LinearFilter,
-      format: THREE.RGBAFormat,
-      type: THREE.HalfFloatType,
-      depthBuffer: false,
-      stencilBuffer: false,
-    });
-    t.texture.generateMipmaps = false;
-    return t;
-  }
-
-  setSize(width, height) {
-    this._width = width;
-    this._height = height;
-    this.targetA.setSize(width, height);
-    this.targetB.setSize(width, height);
-  }
-
-  /** Runs `iterations` à-trous passes; returns the final filtered texture. */
-  render(renderer, inputTexture, gbuffer, cameraPos, eps, iterations = 3) {
-    const u = this.material.uniforms;
-    u.uGWorldPos.value = gbuffer.worldPos;
-    u.uGNormalMetal.value = gbuffer.normalMetal;
-    u.uTexelSize.value.set(1 / this._width, 1 / this._height);
-    u.uCameraPos.value.copy(cameraPos);
-    u.uEps.value = eps;
-
-    let read = inputTexture;
-    let write = this.targetA;
-    for (let i = 0; i < iterations; i++) {
-      u.uIrradiance.value = read;
-      u.uStep.value = 1 << i;
-      renderer.setRenderTarget(write);
-      renderer.render(this.scene, this.camera);
-      read = write.texture;
-      write = write === this.targetA ? this.targetB : this.targetA;
-    }
-    renderer.setRenderTarget(null);
-    return read;
-  }
-
-  dispose() {
-    this.targetA.dispose();
-    this.targetB.dispose();
-    this.material.dispose();
-    this.quad.geometry.dispose();
-  }
-}
+import * as THREE from "three";
+
+const fullscreenVert = /* glsl */ `
+out vec2 vUv;
+void main() {
+  vUv = uv;
+  gl_Position = vec4(position.xy, 0.0, 1.0);
+}
+`;
+
+const atrousFrag = /* glsl */ `
+precision highp float;
+
+layout(location = 0) out vec4 outColor;
+
+in vec2 vUv;
+
+uniform sampler2D uIrradiance;   // rgb = irradiance, a = history count
+uniform sampler2D uGWorldPos;    // full-res guides
+uniform sampler2D uGNormalMetal;
+uniform vec2 uTexelSize;         // of the irradiance target
+uniform float uStep;             // à-trous step: 1, 2, 4, ...
+uniform vec3 uCameraPos;
+uniform float uEps;
+uniform float uLumSigma;
+uniform bool uBlendIsSpec;       // this instance filters the specular buffer
+
+float luminance(vec3 c) {
+  return dot(c, vec3(0.299, 0.587, 0.114));
+}
+
+void main() {
+  vec4 center = texture(uIrradiance, vUv);
+  vec4 wp = texture(uGWorldPos, vUv);
+  if (wp.w < 0.5) {
+    outColor = center;
+    return;
+  }
+  vec3 P = wp.xyz;
+  vec4 nm = texture(uGNormalMetal, vUv);
+  vec3 N = normalize(nm.xyz);
+  // Specular surfaces (mirror metals, glass) carry traced reflections whose
+  // detail is NOT in the G-buffer guides — filtering would smear them, and
+  // their signal is nearly deterministic anyway. Scale the filter down as the
+  // surface gets more mirror-like.
+  // Packed word ranges (see GBufferPass): [4,5] alpha blend, [2,4) glass,
+  // [0,1] metal. In the IRRADIANCE buffer a blend surface carries diffuse-lit
+  // direct + GI that DOES need filtering (specAmount 0); in the SPECULAR buffer
+  // (uBlendIsSpec) it carries the traced behind-the-pane image, which must be
+  // spared like a mirror — the pane is flat, so the G-buffer guides would let
+  // the filter smear the see-through content into mush.
+  float matW = nm.w;
+  float specAmount = matW >= 4.0 ? (uBlendIsSpec ? 1.0 : 0.0)
+    : (matW >= 2.0 ? clamp(matW - 2.0, 0.0, 1.0) : matW);
+  float specKeep = specAmount * (1.0 - clamp(wp.w - 1.0, 0.0, 1.0));
+
+  // Fewer accumulated samples -> noisier pixel -> wider luminance tolerance.
+  // A converged pixel (high count) is barely touched, preserving detail.
+  // The widening is CAPPED at 3x: during camera motion every pixel is fresh,
+  // and an 8x-wide gate across five à-trous passes erased small contact
+  // shadows entirely — objects visibly floated while orbiting ("ghostly
+  // apparitions") and only grounded once the camera stopped. Blue-noise
+  // sampling + ReSTIR keep fresh pixels clean enough for the tighter gate.
+  float count = max(center.a, 1.0);
+  float sigmaL = uLumSigma * clamp(8.0 / sqrt(count), 0.75, 3.0);
+
+  float distToCam = distance(P, uCameraPos);
+  float planeTol = 0.01 * distToCam + 20.0 * uEps;
+
+  // Despeckle (first iteration, short history only): a freshly disoccluded
+  // pixel can carry one huge sample that the center-weighted filter would
+  // preserve as a bright "rain drop" at silhouettes. Such a pixel has no
+  // business being brighter than its entire neighbourhood — clamp its
+  // luminance to the brightest neighbour. Converged pixels are exempt, so
+  // real small highlights survive.
+  if (uStep < 1.5 && count < 8.0) {
+    float maxL = 0.0;
+    float found = 0.0;
+    for (int dy = -1; dy <= 1; dy++) {
+      for (int dx = -1; dx <= 1; dx++) {
+        if (dx == 0 && dy == 0) continue;
+        vec2 tuv = vUv + vec2(float(dx), float(dy)) * uTexelSize;
+        if (tuv.x < 0.0 || tuv.x > 1.0 || tuv.y < 0.0 || tuv.y > 1.0) continue;
+        if (texture(uGWorldPos, tuv).w < 0.5) continue;
+        maxL = max(maxL, luminance(texture(uIrradiance, tuv).rgb));
+        found = 1.0;
+      }
+    }
+    float cap = maxL * 1.25 + 1e-4;
+    float l = luminance(center.rgb);
+    if (found > 0.5 && l > cap) center.rgb *= cap / l;
+  }
+
+  float lumC = luminance(center.rgb);
+
+  // 3x3 B-spline-ish kernel, edge-avoiding weights.
+  vec3 sum = center.rgb * 4.0;
+  float wsum = 4.0;
+  for (int dy = -1; dy <= 1; dy++) {
+    for (int dx = -1; dx <= 1; dx++) {
+      if (dx == 0 && dy == 0) continue;
+      vec2 tuv = vUv + vec2(float(dx), float(dy)) * uStep * uTexelSize;
+      if (tuv.x < 0.0 || tuv.x > 1.0 || tuv.y < 0.0 || tuv.y > 1.0) continue;
+
+      vec4 g = texture(uGWorldPos, tuv);
+      if (g.w < 0.5) continue;
+      vec4 s = texture(uIrradiance, tuv);
+      vec3 Nt = normalize(texture(uGNormalMetal, tuv).xyz);
+
+      float k = (dx == 0 || dy == 0) ? 2.0 : 1.0;
+      float wN = pow(max(dot(N, Nt), 0.0), 32.0);
+      float wZ = exp(-abs(dot(g.xyz - P, N)) / planeTol);
+      // Tighten the luminance gate as the à-trous step widens: a shadow on a
+      // flat floor has no geometric edge to protect it, so at high iteration
+      // counts the wide passes would average it away ("floating" objects with
+      // no contact shadow). Wide steps only get to blend near-equal luminance.
+      float wL = exp(-abs(luminance(s.rgb) - lumC) / (sigmaL * inversesqrt(uStep)));
+      float w = k * wN * wZ * wL * (1.0 - specKeep);
+      sum += s.rgb * w;
+      wsum += w;
+    }
+  }
+  outColor = vec4(sum / wsum, center.a);
+}
+`;
+
+/**
+ * Edge-avoiding à-trous wavelet filter (SVGF-lite) on the demodulated
+ * irradiance buffer, guided by the full-res G-buffer (plane distance +
+ * normals) and modulated by per-pixel history count: freshly disoccluded
+ * pixels get blurred hard, converged pixels stay crisp.
+ */
+export class DenoisePass {
+  // `blendIsSpec`: the SPECULAR-buffer instance passes true — for blend pixels
+  // that buffer holds the traced behind-the-pane image, whose detail is not in
+  // the G-buffer guides (the pane itself is flat), so filtering would smear it
+  // into mush. The irradiance instance keeps false: there a blend pixel holds
+  // the pane's own diffuse-lit surface, which does want filtering.
+  constructor(width, height, { blendIsSpec = false } = {}) {
+    this.targetA = this._makeTarget(width, height);
+    this.targetB = this._makeTarget(width, height);
+
+    this.material = new THREE.ShaderMaterial({
+      glslVersion: THREE.GLSL3,
+      vertexShader: fullscreenVert,
+      fragmentShader: atrousFrag,
+      uniforms: {
+        uIrradiance: { value: null },
+        uGWorldPos: { value: null },
+        uGNormalMetal: { value: null },
+        uTexelSize: { value: new THREE.Vector2() },
+        uStep: { value: 1 },
+        uCameraPos: { value: new THREE.Vector3() },
+        uEps: { value: 1e-3 },
+        uLumSigma: { value: 0.25 },
+        uBlendIsSpec: { value: blendIsSpec },
+      },
+      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);
+
+    this._width = width;
+    this._height = height;
+  }
+
+  _makeTarget(width, height) {
+    const t = new THREE.WebGLRenderTarget(width, height, {
+      minFilter: THREE.LinearFilter,
+      magFilter: THREE.LinearFilter,
+      format: THREE.RGBAFormat,
+      type: THREE.HalfFloatType,
+      depthBuffer: false,
+      stencilBuffer: false,
+    });
+    t.texture.generateMipmaps = false;
+    return t;
+  }
+
+  setSize(width, height) {
+    this._width = width;
+    this._height = height;
+    this.targetA.setSize(width, height);
+    this.targetB.setSize(width, height);
+  }
+
+  /** Runs `iterations` à-trous passes; returns the final filtered texture. */
+  render(renderer, inputTexture, gbuffer, cameraPos, eps, iterations = 3) {
+    const u = this.material.uniforms;
+    u.uGWorldPos.value = gbuffer.worldPos;
+    u.uGNormalMetal.value = gbuffer.normalMetal;
+    u.uTexelSize.value.set(1 / this._width, 1 / this._height);
+    u.uCameraPos.value.copy(cameraPos);
+    u.uEps.value = eps;
+
+    let read = inputTexture;
+    let write = this.targetA;
+    for (let i = 0; i < iterations; i++) {
+      u.uIrradiance.value = read;
+      u.uStep.value = 1 << i;
+      renderer.setRenderTarget(write);
+      renderer.render(this.scene, this.camera);
+      read = write.texture;
+      write = write === this.targetA ? this.targetB : this.targetA;
+    }
+    renderer.setRenderTarget(null);
+    return read;
+  }
+
+  dispose() {
+    this.targetA.dispose();
+    this.targetB.dispose();
+    this.material.dispose();
+    this.quad.geometry.dispose();
+  }
+}