three-realtime-rt 0.4.0 → 0.5.0

package/src/index.d.ts

@@ -161,12 +161,35 @@ 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;
+  /**
+   * 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;
   /** 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 +199,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 +264,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[];
 }
@@ -288,12 +327,24 @@ 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. */
   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;
@@ -332,7 +383,10 @@ 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;
   /** One stochastic direct shadow ray per pixel per frame instead of one per light. */
   stochasticLights: boolean;
@@ -354,6 +408,13 @@ 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;
   /** Procedural-sky state. */
   sky: SkyState;
   /** Distance-fog state. */