three-realtime-rt 0.3.2 → 0.4.0

package/src/SceneCompiler.js

@@ -40,8 +40,11 @@ export class CompiledScene {
     this.dynamicMerged = null;
     this.dynamicPacked = null; // Float32Array + BufferAttribute for re-baking
     this.dynamicPackedAttr = null;
-    this.dynamic = []; // [{ mesh, start, count, localPos, localNorm }]
+    this.dynamic = []; // [{ mesh, start, count, localPos, localNorm, deforming, ... }]
     this.hasDynamic = false;
+    // True when any dynamic segment is CPU-deformed (rtDeforming) — such segments
+    // read their live geometry every frame and force a per-frame normal upload.
+    this.hasDeforming = false;
 
     this.materialsTex = null;
     this.materials = [];
@@ -75,32 +78,82 @@ export class CompiledScene {
       seg.mesh.updateWorldMatrix(true, false);
       const m = seg.mesh.matrixWorld.elements;
       const nm = this._m3.getNormalMatrix(seg.mesh.matrixWorld).elements;
-      const lp = seg.localPos;
-      const ln = seg.localNorm;
       let o = seg.start * 3;
       let p = seg.start * 4;
-      for (let i = 0; i < seg.count; i++) {
-        const x = lp[i * 3], y = lp[i * 3 + 1], z = lp[i * 3 + 2];
-        const wx = m[0] * x + m[4] * y + m[8] * z + m[12];
-        const wy = m[1] * x + m[5] * y + m[9] * z + m[13];
-        const wz = m[2] * x + m[6] * y + m[10] * z + m[14];
-        pos[o] = wx;
-        pos[o + 1] = wy;
-        pos[o + 2] = wz;
-        if (wx < minX) minX = wx; if (wx > maxX) maxX = wx;
-        if (wy < minY) minY = wy; if (wy > maxY) maxY = wy;
-        if (wz < minZ) minZ = wz; if (wz > maxZ) maxZ = wz;
-        const nx = ln[i * 3], ny = ln[i * 3 + 1], nz = ln[i * 3 + 2];
-        const tx = nm[0] * nx + nm[3] * ny + nm[6] * nz;
-        const ty = nm[1] * nx + nm[4] * ny + nm[7] * nz;
-        const tz = nm[2] * nx + nm[5] * ny + nm[8] * nz;
-        const il = 1.0 / (Math.hypot(tx, ty, tz) || 1);
-        packed[p] = tx * il;
-        packed[p + 1] = ty * il;
-        packed[p + 2] = tz * il;
-        // packed[p + 3] (matIndex) never changes
-        o += 3;
-        p += 4;
+
+      if (seg.deforming) {
+        // CPU-deformed mesh (water/cloth): read the LIVE geometry every frame
+        // and expand it back to the merged de-indexed layout through the mapping
+        // snapshotted at compile time. `indexMap` (the source geometry's index
+        // buffer, or null for an already-non-indexed source) maps each merged
+        // triangle-soup vertex slot to its source-vertex index; the source
+        // attributes carry the shared, deformed values.
+        const livePosAttr = seg.liveGeometry.getAttribute("position");
+        if (livePosAttr.count !== seg.srcVertexCount) {
+          throw new Error(
+            "three-realtime-rt: deforming mesh vertex count changed since " +
+            `compile (${seg.srcVertexCount} -> ${livePosAttr.count}); the merged ` +
+            "BVH layout is fixed at compile time — call compileScene() again."
+          );
+        }
+        const sp = livePosAttr.array;
+        const snAttr = seg.liveGeometry.getAttribute("normal");
+        const sn = snAttr ? snAttr.array : null;
+        const map = seg.indexMap; // null = identity (non-indexed source)
+        const ln = seg.localNorm; // fallback if the app never recomputed normals
+        for (let i = 0; i < seg.count; i++) {
+          const sv = map ? map[i] : i;
+          const x = sp[sv * 3], y = sp[sv * 3 + 1], z = sp[sv * 3 + 2];
+          const wx = m[0] * x + m[4] * y + m[8] * z + m[12];
+          const wy = m[1] * x + m[5] * y + m[9] * z + m[13];
+          const wz = m[2] * x + m[6] * y + m[10] * z + m[14];
+          pos[o] = wx;
+          pos[o + 1] = wy;
+          pos[o + 2] = wz;
+          if (wx < minX) minX = wx; if (wx > maxX) maxX = wx;
+          if (wy < minY) minY = wy; if (wy > maxY) maxY = wy;
+          if (wz < minZ) minZ = wz; if (wz > maxZ) maxZ = wz;
+          let nx, ny, nz;
+          if (sn) { nx = sn[sv * 3]; ny = sn[sv * 3 + 1]; nz = sn[sv * 3 + 2]; }
+          else { nx = ln[i * 3]; ny = ln[i * 3 + 1]; nz = ln[i * 3 + 2]; }
+          const tx = nm[0] * nx + nm[3] * ny + nm[6] * nz;
+          const ty = nm[1] * nx + nm[4] * ny + nm[7] * nz;
+          const tz = nm[2] * nx + nm[5] * ny + nm[8] * nz;
+          const il = 1.0 / (Math.hypot(tx, ty, tz) || 1);
+          packed[p] = tx * il;
+          packed[p + 1] = ty * il;
+          packed[p + 2] = tz * il;
+          // packed[p + 3] (matIndex) never changes
+          o += 3;
+          p += 4;
+        }
+      } else {
+        // Rigid mover: transform the frozen local snapshot by the world matrix.
+        const lp = seg.localPos;
+        const ln = seg.localNorm;
+        for (let i = 0; i < seg.count; i++) {
+          const x = lp[i * 3], y = lp[i * 3 + 1], z = lp[i * 3 + 2];
+          const wx = m[0] * x + m[4] * y + m[8] * z + m[12];
+          const wy = m[1] * x + m[5] * y + m[9] * z + m[13];
+          const wz = m[2] * x + m[6] * y + m[10] * z + m[14];
+          pos[o] = wx;
+          pos[o + 1] = wy;
+          pos[o + 2] = wz;
+          if (wx < minX) minX = wx; if (wx > maxX) maxX = wx;
+          if (wy < minY) minY = wy; if (wy > maxY) maxY = wy;
+          if (wz < minZ) minZ = wz; if (wz > maxZ) maxZ = wz;
+          const nx = ln[i * 3], ny = ln[i * 3 + 1], nz = ln[i * 3 + 2];
+          const tx = nm[0] * nx + nm[3] * ny + nm[6] * nz;
+          const ty = nm[1] * nx + nm[4] * ny + nm[7] * nz;
+          const tz = nm[2] * nx + nm[5] * ny + nm[8] * nz;
+          const il = 1.0 / (Math.hypot(tx, ty, tz) || 1);
+          packed[p] = tx * il;
+          packed[p + 1] = ty * il;
+          packed[p + 2] = tz * il;
+          // packed[p + 3] (matIndex) never changes
+          o += 3;
+          p += 4;
+        }
       }
     }
     posAttr.needsUpdate = true;
@@ -124,8 +177,11 @@ export class CompiledScene {
       this.dynamicBvh.refit();
     }
     this.dynamicBvhUniform.updateFrom(this.dynamicBvh);
-    // Normals only feed GI-bounce shading off movers — amortize their upload.
-    if (this._normalFrame++ % 8 === 0) {
+    // Normals only feed GI-bounce shading off movers — amortize their upload for
+    // rigid movers. Deforming meshes change shape (not just orientation) every
+    // frame, so their normals must go up every frame or the shading lags the
+    // silhouette; one deforming segment forces the whole (shared) upload.
+    if (this.hasDeforming || this._normalFrame++ % 8 === 0) {
       this.dynamicAttrTex.updateFrom(this.dynamicPackedAttr);
     }
   }
@@ -142,9 +198,8 @@ export class CompiledScene {
 }
 
 function extractMeshGeometry(mesh, materialIndex) {
-  const src = mesh.geometry.index
-    ? mesh.geometry.toNonIndexed()
-    : mesh.geometry.clone();
+  const indexed = mesh.geometry.index;
+  const src = indexed ? mesh.geometry.toNonIndexed() : mesh.geometry.clone();
 
   if (!src.getAttribute("normal")) src.computeVertexNormals();
   const localPos = src.getAttribute("position").array.slice();
@@ -158,7 +213,17 @@ function extractMeshGeometry(mesh, materialIndex) {
   const count = geo.getAttribute("position").count;
   const mi = new Float32Array(count).fill(materialIndex);
   geo.setAttribute("materialIndex", new THREE.BufferAttribute(mi, 1));
-  return { geo, localPos, localNorm, count };
+
+  // For CPU-deformed (rtDeforming) meshes we re-read the LIVE geometry each
+  // frame. The merged BVH is de-indexed triangle soup, so record how to expand
+  // the live (source) vertices back into that layout: `indexMap[i]` is the
+  // source-vertex index feeding merged slot `i` (a snapshot of the index
+  // buffer), or null when the source was already non-indexed (identity map).
+  // `srcVertexCount` is the live position count at compile time — used to catch
+  // a topology change that would invalidate this mapping.
+  const indexMap = indexed ? mesh.geometry.index.array.slice() : null;
+  const srcVertexCount = mesh.geometry.getAttribute("position").count;
+  return { geo, localPos, localNorm, count, indexMap, srcVertexCount };
 }
 
 // Effective emissive colour (already scaled by intensity), or null if the
@@ -174,12 +239,18 @@ function emissiveColor(mat) {
 // Row 1: emissive triangles for NEE, 4 texels each:
 //   [v0.xyz | area] [e1.xyz | emit.r] [e2.xyz | emit.g] [n.xyz | emit.b]
 // Rows 2..65: a 64x64 RGBA blue-noise tile for low-discrepancy sampling.
+// Row 66 (2 + BLUE_NOISE_SIZE): the emissive power CDF, 1 texel per triangle:
+//   [cdf | prob | 0 | 0] — cumulative and individual pick probability, both
+//   proportional to area x emitted luminance. Lets NEE importance-sample WHICH
+//   triangle to shoot at instead of picking uniformly (a big/bright panel gets
+//   sampled proportionally more than a tiny dim strip), which is the main
+//   variance lever for emissive lighting outside of ReSTIR.
 // All packed into ONE texture because the lighting pass already sits at the
 // WebGL2-guaranteed 16-sampler limit — extra samplers are not available.
 function buildSceneDataTexture(materials, emissiveTris) {
   const bn = decodeBlueNoise();
   const width = Math.max(materials.length * 2, emissiveTris.length * 4, BLUE_NOISE_SIZE);
-  const height = 2 + BLUE_NOISE_SIZE;
+  const height = 2 + BLUE_NOISE_SIZE + 1;
   const data = new Float32Array(width * height * 4);
   materials.forEach((mat, i) => {
     const o = i * 8;
@@ -209,6 +280,22 @@ 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;
+    }
+  }
   const tex = new THREE.DataTexture(data, width, height, THREE.RGBAFormat, THREE.FloatType);
   tex.minFilter = THREE.NearestFilter;
   tex.magFilter = THREE.NearestFilter;
@@ -310,12 +397,20 @@ export function compileScene(scene, options = {}) {
     }
     if (isDynamic) {
       dynamicGeoms.push(extracted.geo);
+      // Opt-in CPU deformation: the mesh must be BOTH in dynamicMeshes AND carry
+      // userData.rtDeforming, and its live geometry is read every frame.
+      const deforming = obj.userData.rtDeforming === true;
+      if (deforming) compiled.hasDeforming = true;
       compiled.dynamic.push({
         mesh: obj,
         start: dynVertexOffset,
         count: extracted.count,
         localPos: extracted.localPos,
         localNorm: extracted.localNorm,
+        deforming,
+        liveGeometry: deforming ? obj.geometry : null,
+        indexMap: deforming ? extracted.indexMap : null,
+        srcVertexCount: deforming ? extracted.srcVertexCount : 0,
       });
       dynVertexOffset += extracted.count;
     } else {

package/src/TAAPass.js

@@ -101,12 +101,17 @@ void main() {
 }
 `;
 
+// Copies the resolved frame out. When overscan is active the resolve target is
+// PADDED (larger than the canvas); uCrop (scale.xy, offset.zw) samples its central
+// canvas-sized region so the padded edges — where disocclusion noise is born —
+// stay off-screen. Identity (1,1,0,0) when overscan is 0.
 const copyFrag = /* glsl */ `
 precision highp float;
 layout(location = 0) out vec4 outColor;
 in vec2 vUv;
 uniform sampler2D uTex;
-void main() { outColor = vec4(texture(uTex, vUv).rgb, 1.0); }
+uniform vec4 uCrop;
+void main() { outColor = vec4(texture(uTex, vUv * uCrop.xy + uCrop.zw).rgb, 1.0); }
 `;
 
 /**
@@ -145,7 +150,10 @@ export class TAAPass {
       glslVersion: THREE.GLSL3,
       vertexShader: fullscreenVert,
       fragmentShader: copyFrag,
-      uniforms: { uTex: { value: null } },
+      uniforms: {
+        uTex: { value: null },
+        uCrop: { value: new THREE.Vector4(1, 1, 0, 0) },
+      },
       depthTest: false,
       depthWrite: false,
     });
@@ -217,8 +225,12 @@ export class TAAPass {
    * @param prevJitterUv last frame's projection jitter in UV space
    * @param outputTarget where the resolved frame goes (null = screen); lets a
    *                     post pass (god rays) run after the resolve
+   * @param crop         overscan central-crop transform (THREE.Vector4 scale.xy /
+   *                     offset.zw) applied by the out-copy; null = identity. The
+   *                     resolve itself runs in full padded space; only the copy
+   *                     to `outputTarget` crops to the canvas.
    */
-  render(renderer, currentColor, gbuffer, prevViewProj, jitterUv, prevJitterUv, blend, outputTarget = null) {
+  render(renderer, currentColor, gbuffer, prevViewProj, jitterUv, prevJitterUv, blend, outputTarget = null, crop = null) {
     const u = this.material.uniforms;
     u.uCurrent.value = currentColor;
     u.uHistory.value = this.targetB.texture; // previous resolved
@@ -234,9 +246,13 @@ export class TAAPass {
     renderer.setRenderTarget(this.targetA);
     renderer.render(this.scene, this.camera);
 
-    // Copy the resolved frame out (screen, or a post-pass input target).
+    // Copy the resolved frame out (screen, or a post-pass input target). The
+    // overscan crop lives here — the resolve above stays in full padded space so
+    // history reprojection and the neighbourhood clamp see the whole padded image.
     this.quad.material = this.copyMaterial;
     this.copyMaterial.uniforms.uTex.value = this.targetA.texture;
+    if (crop) this.copyMaterial.uniforms.uCrop.value.copy(crop);
+    else this.copyMaterial.uniforms.uCrop.value.set(1, 1, 0, 0);
     renderer.setRenderTarget(outputTarget);
     renderer.render(this.scene, this.camera);
 

package/src/index.d.ts

@@ -10,6 +10,24 @@ import type {
 /** Capability tier used to pick sensible defaults. */
 export type Tier = "none" | "mid" | "high";
 
+/** Result of {@link RealtimeRaytracer.probeGPUTier}. */
+export interface GPUTierProbe {
+  /** Chosen capability tier. */
+  tier: Tier;
+  /**
+   * Where the tier came from: `"webgpu"` (real adapter limits inspected),
+   * `"webgl"` (WebGL `detectTier` heuristic on the supplied renderer), or
+   * `"fallback"` (pure user-agent guess — no WebGPU and no renderer given).
+   */
+  source: "webgpu" | "webgl" | "fallback";
+  /**
+   * Diagnostics behind the decision: the adapter limits read, any masked
+   * `adapter.info` fields, the computed `screenPixels` demand factor, and a
+   * human-readable `reason`. Shape varies by `source`; treat as informational.
+   */
+  details: Record<string, unknown>;
+}
+
 /** Procedural-sky configuration (background + ambient light for escaping GI rays). */
 export interface SkyOptions {
   /** Enable the procedural sky as background and ambient GI source. */
@@ -70,6 +88,14 @@ export interface RealtimeRaytracerOptions {
    * denoiser reconstruct the difference. Set 1.0 for maximum quality.
    */
   renderScale?: number;
+  /**
+   * Overscan: render internally at a padded resolution with a proportionally
+   * widened field of view, then crop the centre to the canvas on the final draw.
+   * Fraction of padding PER EDGE (clamped 0–0.25). Pushes the disocclusion
+   * convergence noise at the leading screen edge off-screen during camera
+   * motion. `0.1` renders 1.44× the pixels; 0.05–0.1 recommended. Default `0`.
+   */
+  overscan?: number;
   /** À-trous denoise iterations (steps 1, 2, 4, ...). */
   denoiseIterations?: number;
   /**
@@ -105,10 +131,31 @@ export interface RealtimeRaytracerOptions {
    * Dramatically less noise than waiting for GI rays to hit the emitter.
    */
   emissiveNEE?: boolean;
+  /**
+   * Importance-sample WHICH emissive triangle NEE shoots at, proportional to
+   * area x emitted luminance (compile-time power CDF) instead of a uniform
+   * 1-of-N pick. Same mean, far less sparkle when emitters differ in
+   * size/brightness. Default true; false restores the legacy uniform pick.
+   */
+  emissiveImportance?: boolean;
+  /**
+   * PBR direct specular: Cook-Torrance GGX highlights for every surface, kept in
+   * a separate specular buffer the composite adds WITHOUT the albedo multiply
+   * (dielectric highlights are white, F0 ~= 0.04). Metals' albedo-tinted specular
+   * rides the reflection path instead. Default true; false restores the old
+   * Lambert-only diffuse look.
+   */
+  specular?: boolean;
   /** Traced mirror/glossy reflections on metallic surfaces. */
   reflections?: boolean;
   /** Traced refraction for transmissive (MeshPhysicalMaterial.transmission) surfaces. */
   refraction?: boolean;
+  /**
+   * Alpha-blended transparency: `transparent: true` meshes are primary-visible
+   * and composited against the geometry behind them (weighted by `opacity`).
+   * Default true. Off = blend surfaces render fully opaque.
+   */
+  transparency?: boolean;
   /**
    * ReSTIR direct lighting: per-pixel reservoirs converge onto the light that
    * matters most to each pixel. Cost is flat in light count.
@@ -176,7 +223,19 @@ export interface VolumetricState {
 
 /** Options accepted by {@link RealtimeRaytracer.compileScene} and {@link compileScene}. */
 export interface CompileSceneOptions {
-  /** Meshes whose transforms change every frame; drive them with updateDynamic(). */
+  /**
+   * Meshes whose transforms change every frame; drive them with updateDynamic().
+   *
+   * By default a dynamic mesh is treated as **rigid** — its compile-time vertices
+   * are snapshotted and only re-transformed by `mesh.matrixWorld` each frame.
+   * To trace a mesh whose *vertices* move on the CPU (water, cloth, morph
+   * targets), also set `mesh.userData.rtDeforming = true`. Such a mesh has its
+   * live `position` (and `normal`) attributes re-read every frame, so the traced
+   * shadows/reflections follow the actual deformed shape. The app must keep the
+   * normal attribute current (e.g. call `geometry.computeVertexNormals()` after
+   * deforming). The live vertex count is fixed at compile time — changing it
+   * throws; call `compileScene()` again after a topology change.
+   */
   dynamicMeshes?: Object3D[];
 }
 
@@ -210,8 +269,16 @@ export class RealtimeRaytracer {
 
   /** Can this renderer run the ray tracing pipeline at all (WebGL2 + float RTs on hardware GPU)? */
   static isSupported(renderer: WebGLRenderer): boolean;
-  /** Rough capability tier for choosing defaults. */
+  /** Rough capability tier for choosing defaults (synchronous WebGL heuristic). */
   static detectTier(renderer?: WebGLRenderer): Tier;
+  /**
+   * Optional async GPU tier probe: inspects real WebGPU adapter limits when
+   * available (honest heuristic — WebGPU does NOT expose VRAM, so it uses
+   * `maxBufferSize`/texture limits as a proxy and factors screen resolution),
+   * else falls back to {@link detectTier}. The constructor stays synchronous;
+   * feed the result to {@link recommendedOptions}.
+   */
+  static probeGPUTier(renderer?: WebGLRenderer): Promise<GPUTierProbe>;
   /** Sensible constructor options for a tier (spread them, then override). */
   static recommendedOptions(tier: Tier): RealtimeRaytracerOptions;
 
@@ -225,13 +292,20 @@ export class RealtimeRaytracer {
   compiled: CompiledScene | null;
   /** Accumulated frame counter. */
   frame: number;
-  /** 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. */
   outputMode: number;
 
   /** Resolution scale for the ray traced lighting; assigning reallocates targets. */
   get renderScale(): number;
   set renderScale(v: number);
 
+  /**
+   * Overscan padding fraction per edge (0–0.25). Assigning reallocates every
+   * pass at the new padded size and hard-resets accumulation (settings-time).
+   */
+  get overscan(): number;
+  set overscan(v: number);
+
   /** Environment (sky) color for GI rays that miss + composite background. */
   envColor: Color;
   /** Environment intensity multiplier. */
@@ -248,10 +322,16 @@ export class RealtimeRaytracer {
   gi: boolean;
   /** Sample static emissive meshes as area lights (NEE). */
   emissiveNEE: boolean;
+  /** Importance-sample emissive triangles by power (see the option of the same name). */
+  emissiveImportance: boolean;
+  /** PBR direct specular (Cook-Torrance GGX) into a separate additive buffer. */
+  specular: boolean;
   /** Traced mirror/glossy reflections on metallic surfaces. */
   reflections: boolean;
   /** Traced refraction for transmissive surfaces. */
   refraction: boolean;
+  /** Alpha-blended transparency: composite `transparent` meshes over the geometry behind them. */
+  transparency: boolean;
   /** Index of refraction used for transmissive surfaces. */
   ior: number;
   /** One stochastic direct shadow ray per pixel per frame instead of one per light. */
@@ -292,7 +372,10 @@ export class RealtimeRaytracer {
   updateLights(scene: Scene): void;
   /** Discard temporal history and restart accumulation. */
   resetAccumulation(): void;
-  /** Resize all internal render targets. */
+  /**
+   * Resize all internal render targets. Pass the CANVAS (drawing-buffer) size;
+   * the internal targets are the overscan-padded size derived from it.
+   */
   setSize(width: number, height: number): void;
   /** Render one frame (call instead of renderer.render). */
   render(scene: Scene, camera: Camera): void;