three-realtime-rt 0.4.2 → 0.6.0

package/src/index.d.ts

@@ -161,12 +161,62 @@ export interface RealtimeRaytracerOptions {
    * matters most to each pixel. Cost is flat in light count.
    */
   restir?: boolean;
-  /** Index of refraction used for transmissive surfaces. */
+  /**
+   * EXPERIMENTAL — ReSTIR GI (v1, temporal-only): per-pixel reservoirs reuse the
+   * 1-bounce global-illumination sample across frames (at the reprojected
+   * same-surface point; no spatial reuse). When on, the lighting pass skips its
+   * inline GI trace and the reservoir's resolved GI is added at the denoise
+   * stage — so it only takes effect when `gi` and `denoise` are also on. Its
+   * mean matches the inline GI path; convergence character differs. Default
+   * `false`. Live-toggleable.
+   */
+  restirGI?: boolean;
+  /** EXPERIMENTAL — temporal M-cap for the ReSTIR GI reservoir (default 20). */
+  restirGIMCap?: number;
+  /**
+   * EXPERIMENTAL — ReSTIR GI (v2) spatial-reuse taps per frame, taken after the
+   * temporal merge from the previous frame's reservoirs (reconnection-Jacobian
+   * reweighted, with a final visibility ray to prevent leaks). Clamped to 0..4;
+   * `0` reproduces v1 temporal-only behaviour. Default 2.
+   */
+  restirGISpatialTaps?: number;
+  /**
+   * EXPERIMENTAL — ReSTIR GI reservoir-sample validation period. Every frame a
+   * rotating 1-in-N subset of pixels re-aims its single candidate ray at the
+   * reservoir's stored hit (instead of a fresh cosine bounce) and re-shades it;
+   * the reservoir is killed when the geometry moved or the re-shaded target
+   * collapsed to near-black (a light switched off), and left untouched otherwise.
+   * Reuses the existing candidate trace (no extra bounce rays); fixes stale bounce
+   * light (a switched-off light stops haunting the reservoir) without drifting a
+   * static scene. `0` disables it (byte-identical to before the feature). Default 8.
+   */
+  restirGIValidate?: number;
+  /**
+   * Global fallback index of refraction for transmissive surfaces. A
+   * `MeshPhysicalMaterial.ior` overrides this per material for fully-transmissive
+   * glass (encoded in the G-buffer, supported range [1.0, 1.98]); `material.ior`
+   * wins when present. This value applies to partial-transmission glass and as
+   * the default when no per-material ior is carried.
+   */
   ior?: number;
+  /**
+   * Chromatic dispersion strength for glass, `0..0.5` (clamped), default `0`
+   * (off). Splits refracted white light into a spectrum via stochastic spectral
+   * sampling — each frame every glass pixel estimates one colour channel through
+   * a channel-shifted ior, and temporal accumulation blends the three into a
+   * rainbow (no extra rays). Needs accumulation to converge, so it shimmers
+   * slightly in motion. Global control only (no per-material dispersion).
+   */
+  dispersion?: number;
   /** History length cap: higher = smoother but slower to react. */
   maxHistory?: number;
   /** Clamp on indirect luminance to suppress fireflies. 0 disables. */
   fireflyClamp?: number;
+  /**
+   * BVH-cost heatmap scale for the mode-7 debug view: shadow-ray node-visit
+   * count is multiplied by this before the palette (default 1/96).
+   */
+  costScale?: number;
   /** Reproject accumulated lighting through camera motion. */
   temporalReprojection?: boolean;
   /**
@@ -176,6 +226,12 @@ export interface RealtimeRaytracerOptions {
   taa?: boolean;
   /** Fresh-sample weight in the TAA blend (lower = smoother/more AA, more lag). */
   taaBlend?: number;
+  /**
+   * Scales the TAA sub-pixel jitter amplitude. Set to your canvas scale when
+   * rendering a reduced drawing buffer CSS-stretched to the screen, so jitter
+   * stays constant in screen pixels (no visible wobble at low quality). Default 1.
+   */
+  taaJitterScale?: number;
   /** Edge-aware à-trous denoise on the irradiance buffer. */
   denoise?: boolean;
   /**
@@ -235,6 +291,16 @@ export interface CompileSceneOptions {
    * 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.
+   *
+   * A **`SkinnedMesh` is auto-detected** (no flag needed) and CPU-skinned into the
+   * dynamic BVH every frame from its live skeleton pose, so an animated character
+   * casts a moving traced shadow and rasterizes in its animated pose (the G-buffer
+   * skins via three's standard skinning chunks). Pose the skeleton *before*
+   * `updateDynamic()` — `mixer.update(dt)` then `characterRoot.updateMatrixWorld(true)`
+   * — since the skinning reads each bone's `matrixWorld`. Cost is O(source verts ×
+   * 4 bones); secondary-ray normals are per-face (recomputed from the skinned
+   * triangles), while primary visibility keeps smooth skinned normals from the
+   * raster path. Budget ~10–20k skinned source verts for a sub-2 ms frame.
    */
   dynamicMeshes?: Object3D[];
 }
@@ -248,11 +314,19 @@ export class CompiledScene {
   triangleCount: number;
   /** Number of lights scanned into the compiled light tables. */
   lightCount: number;
-  /** Number of emissive triangles registered as NEE area lights. */
+  /** Number of emissive triangles registered as NEE area lights (static + dynamic). */
   emissiveTriCount: number;
   /** World-space diagonal of the static level (used to auto-scale ray epsilon). */
   sceneDiagonal: number;
-  /** Re-bake moving meshes' current world transforms and refit the dynamic BVH. */
+  /** True when any dynamic emitter contributes NEE rows refreshed each frame. */
+  hasDynamicEmissive: boolean;
+  /** CPU cost (ms) of the most recent dynamic-emissive refresh (0 if none). */
+  lastEmissiveRefreshMs: number;
+  /**
+   * Re-bake moving meshes' current world transforms and refit the dynamic BVH.
+   * Also refreshes any dynamic emitters' NEE area-light rows + power CDF from the
+   * freshly baked world positions.
+   */
   updateDynamic(): void;
   /** Release GPU resources held by this compiled scene. */
   dispose(): void;
@@ -298,8 +372,14 @@ 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, 6 specular. */
+  /** Debug view: 0 composite, 1 albedo, 2 normal, 3 irradiance, 4 worldPos, 5 emissive, 6 specular, 7 bvh cost. */
   outputMode: number;
+  /**
+   * BVH-cost heatmap scale (outputMode 7): the per-pixel shadow-ray node-visit
+   * count is multiplied by this before the palette (default 1/96 — ~96 visits
+   * saturate to white). Live-tunable.
+   */
+  costScale: number;
 
   /** Resolution scale for the ray traced lighting; assigning reallocates targets. */
   get renderScale(): number;
@@ -338,8 +418,17 @@ export class RealtimeRaytracer {
   refraction: boolean;
   /** Alpha-blended transparency: composite `transparent` meshes over the geometry behind them. */
   transparency: boolean;
-  /** Index of refraction used for transmissive surfaces. */
+  /**
+   * Global fallback index of refraction. `MeshPhysicalMaterial.ior` overrides it
+   * per material for fully-transmissive glass (range [1.0, 1.98]).
+   */
   ior: number;
+  /**
+   * Chromatic dispersion strength for glass, `0..0.5` (clamped on upload),
+   * default `0`. Stochastic spectral sampling: splits refracted white light into
+   * a rainbow via temporal accumulation, no extra rays. Global control only.
+   */
+  dispersion: number;
   /** One stochastic direct shadow ray per pixel per frame instead of one per light. */
   stochasticLights: boolean;
   /** Adaptive quality governor toggle. */
@@ -360,6 +449,17 @@ export class RealtimeRaytracer {
   taaBlend: number;
   /** ReSTIR direct lighting toggle. */
   restir: boolean;
+  /**
+   * EXPERIMENTAL — ReSTIR GI (temporal-only) toggle. Only takes effect when
+   * `gi` and `denoise` are also on (injected at the à-trous stage). Default false.
+   */
+  restirGI: boolean;
+  /** EXPERIMENTAL — temporal M-cap for the ReSTIR GI reservoir. */
+  restirGIMCap: number;
+  /** EXPERIMENTAL — ReSTIR GI (v2) spatial-reuse taps per frame (0..4, 0 = v1). */
+  restirGISpatialTaps: number;
+  /** EXPERIMENTAL — ReSTIR GI reservoir-sample validation period (0 = off, default 8). */
+  restirGIValidate: number;
   /** Procedural-sky state. */
   sky: SkyState;
   /** Distance-fog state. */