@hology/webgpu-renderer 0.1.5 → 0.1.6

package/dist/index.d.ts

@@ -539,6 +539,15 @@ declare class FrameGraphBuilder {
 }
 
 type VolumetricFogScatteringMode = "volumetric" | "lightShaft";
+type VolumetricFogQuality = "low" | "medium" | "high";
+interface VolumetricFogTemporalOptions {
+    /** Previous-frame contribution for stable fog. Defaults to 0.92. */
+    readonly historyWeight?: number;
+    /** Relative view-depth difference that rejects history. Defaults to 0.04. */
+    readonly depthRejection?: number;
+    /** Clamp reprojected history to the current 3x3 fog neighborhood. */
+    readonly neighborhoodClamp?: boolean;
+}
 /** Kept structurally compatible with Hology's legacy FogVolumeSettings. */
 interface VolumetricFogVolumeSettings {
     readonly object: Object3D;
@@ -559,6 +568,7 @@ declare class VolumetricFogVolumeObject extends Object3D {
     constructor(volume: VolumetricFogVolumeSettings);
 }
 interface VolumetricFogOptions {
+    readonly enabled?: boolean;
     /** Froxel width/height in pixels. 8 is a good desktop default. */
     readonly froxelPixelSize?: number;
     /** Logarithmically distributed depth slices. */
@@ -575,8 +585,13 @@ interface VolumetricFogOptions {
     readonly ambientColor?: Color;
     /** Rotating shadow taps per froxel. 4 removes block patterns at modest cost. */
     readonly shadowFilterTaps?: 1 | 4;
-    /** Temporal sub-froxel jitter, intended to be accumulated by TAA. */
+    /** Temporal sub-froxel jitter accumulated by fog history and optionally TAA. */
     readonly temporalJitter?: boolean;
+    /**
+     * Fog-local temporal reconstruction. Unlike temporalJitter, this retains a
+     * resolved fog history and permits cheaper current-frame sampling.
+     */
+    readonly temporal?: false | VolumetricFogTemporalOptions;
     /** Stable per-ray depth jitter. Breaks slice bands without animated noise. */
     readonly spatialJitter?: boolean;
     /** Final fog-gradient dithering in approximate 8-bit code values. */
@@ -601,6 +616,8 @@ interface VolumetricFogBlurOptions {
 interface VolumetricFogInputs {
     readonly sceneColor: FrameGraphTextureHandle;
     readonly depth: FrameGraphTextureHandle;
+    /** Raw unjittered previous-to-current UV velocity from the opaque MRT. */
+    readonly velocity?: FrameGraphTextureHandle;
     /** Explicit volumes can be mixed with compatible scene marker objects. */
     readonly volumes?: readonly VolumetricFogVolumeSettings[];
     /**
@@ -614,6 +631,7 @@ interface VolumetricFogInputs {
      */
     readonly lights?: RendererExtractedLightState;
 }
+declare const VOLUMETRIC_FOG_PRESETS: Readonly<Record<VolumetricFogQuality, VolumetricFogOptions>>;
 /**
  * Compute-driven froxel fog. Add it after opaque rendering and before the late
  * transparent pass. Existing content can use the composite output; transparent
@@ -632,20 +650,32 @@ declare class VolumetricFogEffect {
     private readonly lightData;
     private readonly projectionInverse;
     private readonly viewProjectionInverse;
+    private readonly previousTemporalViewProjection;
     private explicitVolumes;
     private volumeObjects;
     private extractedLights;
     private cascadeDirectionalLights;
     private compositePass;
     private readonly blurPassCache;
+    private readonly temporalPassCache;
+    private temporalWriteIndex;
+    private temporalHistoryValid;
+    private activeLastFrame;
     private frameIndex;
     constructor(scene?: Scene, options?: VolumetricFogOptions);
     /** Updates the scene traversed for compatible volumes and lights. */
     setScene(scene: Scene): void;
+    get enabled(): boolean;
+    setOptions(options: VolumetricFogOptions): void;
+    applyPreset(quality: VolumetricFogQuality): void;
+    reset(): void;
     /** Keeps CSM light data in the same near-to-far order as shadow-array layers. */
     setCascadedDirectionalLights(lights: readonly DirectionalLight[]): void;
     addPasses(graph: FrameGraphBuilder, inputs: VolumetricFogInputs): FrameGraphTextureHandle;
     private addBlurredComposite;
+    private addTemporalPass;
+    consumeTemporalHistoryValid(): boolean;
+    updateTemporalUniforms(uniforms: Float32Array, currentViewProjection: Matrix4, currentViewProjectionInverse: Matrix4, temporal: Required<VolumetricFogTemporalOptions>, context: RendererCustomPassContext): void;
     dispose(): void;
     private executeFroxels;
     private collectSceneData;
@@ -850,6 +880,14 @@ declare class WebGpuRenderer {
     private readonly projectionJitterPixels;
     private readonly temporalVisibilityCurrentViewProj;
     private readonly temporalVisibilityPreviousViewProj;
+    private readonly motionVectorProjection;
+    private readonly motionVectorCurrentViewProj;
+    private readonly motionVectorPreviousViewProj;
+    private motionVectorProjectionPending;
+    private motionVectorHistoryValid;
+    private motionVectorHistoryGeneration;
+    private lastMotionVectorTimeSeconds;
+    private readonly objectMotionHistory;
     private readonly cameraFrustumPlanesScratch;
     private readonly objectTraversalStackScratch;
     private readonly isSphereVisibleScratch;
@@ -899,6 +937,13 @@ declare class WebGpuRenderer {
      */
     setProjectionJitter(x: number, y: number): void;
     clearProjectionJitter(): void;
+    /**
+     * Supplies the unjittered projection used by motion vectors for the next
+     * render. The backend calls this before TAA temporarily jitters the camera.
+     */
+    setMotionVectorProjection(projection: Matrix4): void;
+    /** Suppresses object velocity for one frame without discarding GPU caches. */
+    invalidateObjectMotion(object: Object3D): void;
     getLastFrameProfile(): RendererFrameProfile | null;
     /**
      * Invalidates temporal data when this renderer starts presenting a
@@ -975,6 +1020,8 @@ declare class WebGpuRenderer {
      */
     private collectSprite;
     private hasExtractedDirectionalLight;
+    private getObjectMotionHistory;
+    private commitObjectMotionHistory;
     private collectMesh;
     private prepareSceneForCompilation;
     private collectInstancedMesh;
@@ -1126,11 +1173,22 @@ declare class WebGpuRenderer {
 
 interface GTAODenoiseOptions {
     readonly radius?: number;
+    /** Fixed bilateral tap count. Normalized to 4, 8, 12, or 16. */
+    readonly samples?: number;
     readonly depthPhi?: number;
     readonly normalPhi?: number;
     readonly lumaPhi?: number;
 }
+interface GTAOTemporalOptions {
+    /** Previous-frame contribution for accepted history. Defaults to 0.9. */
+    readonly historyWeight?: number;
+    /** Relative linear view-depth rejection threshold. Defaults to 0.08. */
+    readonly depthRejection?: number;
+    /** Clamp history to the current AO cross-neighborhood. Defaults to true. */
+    readonly neighborhoodClamp?: boolean;
+}
 interface GTAOOptions {
+    readonly enabled?: boolean;
     /** Resolution relative to the render target. Defaults to 1. */
     readonly resolutionScale?: number;
     readonly radius?: number;
@@ -1142,28 +1200,43 @@ interface GTAOOptions {
     /** Space used by the encoded normal input. Defaults to world. */
     readonly normalSpace?: "world" | "view";
     readonly denoise?: false | GTAODenoiseOptions;
+    /** Velocity-reprojected accumulation. Requires a velocity input. */
+    readonly temporal?: false | GTAOTemporalOptions;
     readonly targetPrefix?: string;
 }
 interface GTAOInputs {
     readonly depth: FrameGraphTextureHandle;
     readonly normal: FrameGraphTextureHandle;
+    readonly velocity?: FrameGraphTextureHandle;
 }
 interface GTAOCompositeOptions {
     readonly intensity?: number;
     readonly power?: number;
     readonly output?: FrameGraphTextureHandle;
 }
-/** Reusable GTAO pass pair. The caller controls where AO is composited. */
+type GTAOQuality = "off" | "low" | "medium" | "high";
+declare const GTAO_PRESETS: Readonly<Record<GTAOQuality, Readonly<GTAOOptions>>>;
+/** Reusable GTAO pass chain. The caller controls where AO is composited. */
 declare class GTAOEffect {
     private readonly options;
     private readonly noiseTexture;
     private readonly gtaoPasses;
+    private readonly temporalPasses;
     private readonly denoisePasses;
     private readonly compositePasses;
+    private writeIndex;
+    private frameIndex;
+    private historyValid;
     constructor(options?: GTAOOptions);
+    get enabled(): boolean;
+    get temporalEnabled(): boolean;
+    setOptions(options: GTAOOptions): void;
+    applyPreset(quality: GTAOQuality): void;
+    reset(): void;
     addPasses(graph: FrameGraphBuilder, inputs: GTAOInputs): FrameGraphTextureHandle;
     addCompositePass(graph: FrameGraphBuilder, sceneColor: FrameGraphTextureHandle, ambientOcclusion: FrameGraphTextureHandle, options?: GTAOCompositeOptions): FrameGraphTextureHandle;
     dispose(): void;
+    consumeHistoryValid(): boolean;
 }
 
 interface SSROptions {
@@ -1218,7 +1291,7 @@ interface TemporalAAOptions {
     readonly targetPrefix?: string;
 }
 declare class TemporalAAEffect {
-    readonly renderScale: number;
+    renderScale: number;
     private readonly sampleCount;
     private readonly minCurrentWeight;
     private readonly motionWeightScale;
@@ -1250,8 +1323,14 @@ declare class TemporalAAEffect {
         projectionMatrix: Matrix4;
         projectionMatrixInverse?: Matrix4;
     }): void;
-    addPass(graph: FrameGraphBuilder, currentColor: FrameGraphTextureHandle, currentDepth?: FrameGraphTextureHandle): FrameGraphTextureHandle;
+    addPass(graph: FrameGraphBuilder, currentColor: FrameGraphTextureHandle, currentDepth?: FrameGraphTextureHandle, velocity?: FrameGraphTextureHandle): FrameGraphTextureHandle;
     reset(): void;
+    /**
+     * Updates the internal scene scale used to convert the presentation-space
+     * jitter into internal-render pixels. TAA histories remain at presentation
+     * resolution and therefore act as the temporal upscaling target.
+     */
+    setRenderScale(renderScale: number): void;
     private setSize;
     updateResolveUniforms(uniforms: Float32Array, currentViewProjection: Matrix4, currentViewProjectionInverse: Matrix4, context: RendererCustomPassContext): void;
 }
@@ -1400,6 +1479,93 @@ declare class DepthOfFieldEffect {
     addPass(graph: FrameGraphBuilder, source: FrameGraphTextureHandle, depth: FrameGraphTextureHandle): FrameGraphTextureHandle;
 }
 
+declare enum MotionBlurMode {
+    Disabled = 0,
+    CameraOnly = 1,
+    ObjectAndCamera = 2,
+    ForceObjectBlur = 3
+}
+type MotionBlurQuality = "off" | "low" | "medium" | "high";
+interface MotionBlurOptions {
+    enabled?: boolean;
+    sampleCount?: number;
+    shutterScale?: number;
+    maxBlurPixels?: number;
+    cameraBlurScale?: number;
+    objectBlurScale?: number;
+    depthRejectionStrength?: number;
+    velocityThresholdPixels?: number;
+    dilation?: boolean;
+    debugVelocity?: boolean;
+    targetFrameRate?: number;
+    maxFrameTime?: number;
+    cameraCutDistance?: number;
+    cameraCutRotationThreshold?: number;
+    projectionCutThreshold?: number;
+    targetPrefix?: string;
+}
+interface MotionBlurOverride extends Partial<MotionBlurOptions> {
+    duration: number;
+}
+interface MotionBlurOverrideHandle {
+    readonly id: number;
+    cancel(): void;
+}
+declare const MOTION_BLUR_PRESETS: Readonly<Record<MotionBlurQuality, Readonly<MotionBlurOptions>>>;
+/**
+ * HDR, depth-aware motion-blur resolve.
+ *
+ * Velocity convention:
+ * - RG points from the previous position to the current position.
+ * - Units are texture UV displacement per rendered frame.
+ * - Y is texture-space down; the node compiler flips WebGPU's Y-up NDC.
+ * - Current/previous matrices are unjittered, so TAA jitter is excluded.
+ * - B stores MotionBlurMode and A stores the authored object scale.
+ */
+declare class MotionBlurEffect {
+    readonly options: Required<Omit<MotionBlurOptions, "targetPrefix">>;
+    private readonly targetPrefix;
+    private readonly currentViewProjection;
+    private readonly currentInverseViewProjection;
+    private readonly currentInverseProjection;
+    private readonly previousViewProjection;
+    private readonly pendingViewProjection;
+    private readonly previousProjection;
+    private readonly previousCameraWorld;
+    private readonly previousCameraPosition;
+    private readonly currentCameraPosition;
+    private readonly currentJitterUv;
+    private historyValid;
+    private pendingCamera;
+    private width;
+    private height;
+    private timeSeconds;
+    private frameDuration;
+    private previousTimeSeconds;
+    private nextOverrideId;
+    private readonly overrides;
+    private readonly passes;
+    constructor(options?: MotionBlurOptions);
+    applyPreset(quality: MotionBlurQuality): void;
+    prepareCamera(camera: PerspectiveCamera | OrthographicCamera, width: number, height: number, timeSeconds: number): void;
+    commitCamera(): void;
+    setJitterUv(x: number, y: number): void;
+    reset(): void;
+    requiresRendererHistoryReset(): boolean;
+    pushOverride(override: MotionBlurOverride): MotionBlurOverrideHandle;
+    addPass(graph: FrameGraphBuilder, sceneColor: FrameGraphTextureHandle, velocity: FrameGraphTextureHandle, depth?: FrameGraphTextureHandle): FrameGraphTextureHandle;
+    dispose(): void;
+    getTemporalMatrices(): {
+        readonly currentInverseViewProjection: Matrix4;
+        readonly currentInverseProjection: Matrix4;
+        readonly previousViewProjection: Matrix4;
+    };
+    getFrameDuration(): number;
+    getJitterUv(): Vector2;
+    private pruneOverrides;
+    private getResolvedSettings;
+}
+
 interface OutlineOptions {
     readonly enabled?: boolean;
     readonly visibleEdgeColor?: readonly [number, number, number];
@@ -1441,4 +1607,4 @@ declare class OutlineEffect {
     dispose(): void;
 }
 
-export { type BloomCompositeOptions, BloomEffect, type BloomOptions, ColorGradingEffect, type ColorGradingOptions, type ColorGradingRange, type ColorGradingVector, type CompiledNodeFullscreenShader, ComputeKernel, type ComputeKernelDescriptor, DEFAULT_WGSL_VERTEX_ATTRIBUTES, DepthOfFieldEffect, type DepthOfFieldOptions, type FXAACompositeOptions, FXAAEffect, type FXAAOptions, FrameGraphBuilder, type FrameGraphFullscreenPassDescriptor, type FrameGraphMaterialPassDescriptor, type FrameGraphNodeFullscreenPassDescriptor, type FrameGraphPassDescriptor, type FrameGraphTextureHandle, type GTAOCompositeOptions, type GTAODenoiseOptions, GTAOEffect, type GTAOInputs, type GTAOOptions, OutlineEffect, type OutlineInputs, type OutlineInstanceSelection, type OutlineOptions, RenderGraph, type RenderGraphContext, type RenderGraphExecutionObserver, type RenderGraphPass, type RendererColorTargetDescriptor, type RendererCustomPassContext, type RendererCustomPassDescriptor, type RendererFrameProfile, type RendererGraphBuilder, type RendererGraphBuilderContext, type RendererMaterialPassDescriptor, type RendererMaterialResolver, type RendererOptions, type RendererPassProfile, type RendererShadowMapDebugInfo, type RendererShadowMapDebugTextureInfo, type RendererTextureTargetDescriptor, type RendererVisibilityProfile, type SMAACompositeOptions, type SMAAEdgeDetectionMode, SMAAEffect, type SMAAOptions, type SMAAQualityPreset, SSREffect, type SSRInputs, type SSROptions, type ShaderDefineValue, type ShaderDefines, type StaticDrawSet, type StaticDrawSetOptions, TemporalAAEffect, type TemporalAAOptions, type ToneMappingMode, type ToonOutlineParameters, type UniformDefinition, type UniformType, type UniformValue, VOLUMETRIC_FOG_MATERIAL_WGSL, type VolumetricFogBlurOptions, VolumetricFogEffect, type VolumetricFogInputs, type VolumetricFogOptions, type VolumetricFogScatteringMode, VolumetricFogVolumeObject, type VolumetricFogVolumeSettings, type WGSLGraphTextureDimension, type WGSLGraphTextureInput, type WGSLSceneTextureSemantic, WGSLShaderMaterial, type WGSLShaderMaterialParameters, type WGSLShaderMaterialUniform, type WGSLShaderMaterialUniformInput, type WGSLStorageBufferBinding, type WGSLStorageBufferVisibility, type WGSLSupportedVertexFormat, type WGSLVertexAttributeBinding, WebGpuPMREMGenerator, WebGpuRenderer, configureVolumetricFogMaterial };
+export { type BloomCompositeOptions, BloomEffect, type BloomOptions, ColorGradingEffect, type ColorGradingOptions, type ColorGradingRange, type ColorGradingVector, type CompiledNodeFullscreenShader, ComputeKernel, type ComputeKernelDescriptor, DEFAULT_WGSL_VERTEX_ATTRIBUTES, DepthOfFieldEffect, type DepthOfFieldOptions, type FXAACompositeOptions, FXAAEffect, type FXAAOptions, FrameGraphBuilder, type FrameGraphFullscreenPassDescriptor, type FrameGraphMaterialPassDescriptor, type FrameGraphNodeFullscreenPassDescriptor, type FrameGraphPassDescriptor, type FrameGraphTextureHandle, type GTAOCompositeOptions, type GTAODenoiseOptions, GTAOEffect, type GTAOInputs, type GTAOOptions, type GTAOQuality, type GTAOTemporalOptions, GTAO_PRESETS, MOTION_BLUR_PRESETS, MotionBlurEffect, MotionBlurMode, type MotionBlurOptions, type MotionBlurOverride, type MotionBlurOverrideHandle, type MotionBlurQuality, OutlineEffect, type OutlineInputs, type OutlineInstanceSelection, type OutlineOptions, RenderGraph, type RenderGraphContext, type RenderGraphExecutionObserver, type RenderGraphPass, type RendererColorTargetDescriptor, type RendererCustomPassContext, type RendererCustomPassDescriptor, type RendererFrameProfile, type RendererGraphBuilder, type RendererGraphBuilderContext, type RendererMaterialPassDescriptor, type RendererMaterialResolver, type RendererOptions, type RendererPassProfile, type RendererShadowMapDebugInfo, type RendererShadowMapDebugTextureInfo, type RendererTextureTargetDescriptor, type RendererVisibilityProfile, type SMAACompositeOptions, type SMAAEdgeDetectionMode, SMAAEffect, type SMAAOptions, type SMAAQualityPreset, SSREffect, type SSRInputs, type SSROptions, type ShaderDefineValue, type ShaderDefines, type StaticDrawSet, type StaticDrawSetOptions, TemporalAAEffect, type TemporalAAOptions, type ToneMappingMode, type ToonOutlineParameters, type UniformDefinition, type UniformType, type UniformValue, VOLUMETRIC_FOG_MATERIAL_WGSL, VOLUMETRIC_FOG_PRESETS, type VolumetricFogBlurOptions, VolumetricFogEffect, type VolumetricFogInputs, type VolumetricFogOptions, type VolumetricFogQuality, type VolumetricFogScatteringMode, type VolumetricFogTemporalOptions, VolumetricFogVolumeObject, type VolumetricFogVolumeSettings, type WGSLGraphTextureDimension, type WGSLGraphTextureInput, type WGSLSceneTextureSemantic, WGSLShaderMaterial, type WGSLShaderMaterialParameters, type WGSLShaderMaterialUniform, type WGSLShaderMaterialUniformInput, type WGSLStorageBufferBinding, type WGSLStorageBufferVisibility, type WGSLSupportedVertexFormat, type WGSLVertexAttributeBinding, WebGpuPMREMGenerator, WebGpuRenderer, configureVolumetricFogMaterial };