@hology/webgpu-renderer 0.1.23 → 0.1.25

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as three from 'three';
-import { Object3D, Color, Vector2, Vector3, Vector4, Matrix3, Matrix4, Material, Texture, MaterialParameters, PerspectiveCamera, OrthographicCamera, BufferGeometry, DirectionalLight, PointLight, SpotLight, Scene } from 'three';
+import { Object3D, Color, Vector2, Vector3, Vector4, Matrix3, Matrix4, Material, Texture, MaterialParameters, PerspectiveCamera, OrthographicCamera, BufferGeometry, DirectionalLight, PointLight, SpotLight, Scene, Camera } from 'three';
 export { AmbientLight, BackSide, BatchedMesh, Bone, BoxGeometry, BufferAttribute, BufferGeometry, CanvasTexture, Color, CompressedArrayTexture, CompressedCubeTexture, CompressedTexture, CompressedArrayTexture as CompressedTextureArray, CubeTexture, Data3DTexture, DataArrayTexture, DataTexture, DepthTexture, DirectionalLight, DoubleSide, FrontSide, Group, HemisphereLight, InstancedMesh, MathUtils, Matrix4, Mesh, Object3D, OrthographicCamera, PerspectiveCamera, PlaneGeometry, PointLight, RepeatWrapping, Scene, Skeleton, SkinnedMesh, SphereGeometry, SpotLight, Texture, Vector2, Vector3, Vector4 } from 'three';
 
 interface PipelineDiagnosticOrigin {
@@ -73,6 +73,8 @@ interface WGSLStorageBufferBinding {
     buffer: GPUBuffer;
     type: string;
     visibility?: WGSLStorageBufferVisibility;
+    /** Writable fragment storage is used by surface voxelization. Defaults to read. */
+    access?: "read" | "read_write";
 }
 type WGSLSceneTextureSemantic = "sceneColor" | "sceneDepth";
 type WGSLGraphTextureDimension = "2d" | "depth-2d" | "3d";
@@ -278,6 +280,8 @@ interface RendererOptions {
     invokeObjectRenderCallbacks?: boolean;
 }
 interface StaticDrawSetOptions {
+    /** Retain source instance IDs for explicit transform/visibility refreshes. Topology stays fixed. */
+    mutableTransforms?: boolean;
     /** Defaults inherited by objects without overrides. Frozen at registration. */
     detailCulling?: DetailCullingSettings;
     label?: string;
@@ -294,6 +298,8 @@ interface StaticDrawSet {
     readonly drawCount: number;
     readonly instanceCount: number;
     enabled: boolean;
+    /** Refresh resident transforms/instance visibility. Requires mutableTransforms; topology stays fixed. */
+    updateTransforms(): void;
     dispose(): void;
 }
 interface RendererGraphBuilderContext {
@@ -341,6 +347,8 @@ interface RendererTextureTargetDescriptor extends RendererColorTargetDescriptor
 }
 interface RendererMaterialPassDescriptor {
     readonly name?: string;
+    /** Compute work that must finish before this pass samples its resources. */
+    readonly dependsOn?: readonly string[];
     readonly outputs?: string | readonly string[];
     /** Selects which extracted scene draws are submitted. Defaults to all draws. */
     readonly drawStage?: "all" | "opaque" | "late";
@@ -353,10 +361,12 @@ interface RendererMaterialPassDescriptor {
     /** Draw only objects accepted by this predicate. Intended for selection/mask passes. */
     readonly objectFilter?: (object: Object3D | null) => boolean;
     /** Replace each accepted draw's material while preserving its geometry and instance data. */
-    readonly overrideMaterial?: WGSLShaderMaterial | ((source: WGSLShaderMaterial, skinned: boolean) => WGSLShaderMaterial);
+    readonly overrideMaterial?: WGSLShaderMaterial | ((source: WGSLShaderMaterial, skinned: boolean) => WGSLShaderMaterial | null);
 }
 interface RendererSceneCaptureOptions {
-    /** Exclude objects/subtrees. Static snapshots without a source object pass null. */
+    /** Replace shading while retaining geometry/instances. Receives the source of static snapshots; null skips a draw. */
+    readonly overrideMaterial?: (source: WGSLShaderMaterial, skinned: boolean) => WGSLShaderMaterial | null;
+    /** Exclude objects/subtrees. Renderer-owned draws without a source object pass null. */
     readonly objectFilter?: (object: Object3D | null) => boolean;
     readonly clearColor?: readonly [number, number, number, number];
     /** Defaults to true. Disable point and spot lights for a consistent map view. */
@@ -378,8 +388,15 @@ interface RendererSceneCapturePostProcessContext {
 }
 /** Non-temporal, unshadowed scene view sharing the renderer's GPU resources. */
 interface RendererSceneCapture {
+    /** Display-space output format, for preparing a custom postProcess pipeline. */
+    readonly format: GPUTextureFormat;
+    /** Triangles submitted by the most recent capture, before raster clipping. */
+    readonly triangleCount: number;
     /** Persistent display-space output when created without a canvas. Owned by the capture. */
     readonly textureView?: GPUTextureView;
+    /** Prepare this view's material variants without blocking on synchronous pipeline creation.
+     * Does not submit a capture or prepare a custom postProcess callback. */
+    prepareAsync(scene: three.Scene, camera: PerspectiveCamera | OrthographicCamera, options?: RendererSceneCaptureOptions): Promise<void>;
     capture(scene: three.Scene, camera: PerspectiveCamera | OrthographicCamera, options?: RendererSceneCaptureOptions): void;
     dispose(): void;
 }
@@ -685,13 +702,14 @@ interface FrameGraphNodeFullscreenPassDescriptor {
 }
 interface FrameGraphMaterialPassDescriptor {
     readonly name?: string;
+    readonly dependsOn?: readonly string[];
     readonly outputs?: FrameGraphTextureHandle | readonly FrameGraphTextureHandle[];
     readonly drawStage?: "all" | "opaque" | "late";
     readonly loadColor?: boolean;
     readonly clearColor?: readonly [number, number, number, number];
     readonly loadDepth?: boolean;
     readonly objectFilter?: (object: Object3D | null) => boolean;
-    readonly overrideMaterial?: WGSLShaderMaterial | ((source: WGSLShaderMaterial, skinned: boolean) => WGSLShaderMaterial);
+    readonly overrideMaterial?: WGSLShaderMaterial | ((source: WGSLShaderMaterial, skinned: boolean) => WGSLShaderMaterial | null);
 }
 declare class FrameGraphBuilder {
     private readonly context;
@@ -723,190 +741,177 @@ declare class FrameGraphBuilder {
     present(source?: FrameGraphTextureHandle): void;
 }
 
-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;
-    baseDensity: number;
-    heightFalloff: number;
-    heightOffset: number;
-    startDistance?: number;
-    scatteringDistribution: number;
-    albedo: Color;
-    emissive: Color;
-    ambientIntensity?: number;
-    scatteringMode: VolumetricFogScatteringMode;
+interface SDFGIVolume {
+    readonly origin: Vector3;
+    readonly extent: number;
+    readonly resolution: number;
 }
-/** Scene marker compatible with legacy objects through `isFogVolumeObject`. */
-declare class VolumetricFogVolumeObject extends Object3D {
-    readonly volume: VolumetricFogVolumeSettings;
-    readonly isFogVolumeObject = true;
-    constructor(volume: VolumetricFogVolumeSettings);
+interface SDFGISurfaceCaptureDriver {
+    capture(scene: Scene, volume: SDFGIVolume, axis: number): number;
+    dispose(): void;
 }
-interface VolumetricFogOptions {
+interface SDFGIOptions {
     readonly enabled?: boolean;
-    /** Froxel width/height in pixels. 8 is a good desktop default. */
-    readonly froxelPixelSize?: number;
-    /** Logarithmically distributed depth slices. */
-    readonly depthSlices?: number;
-    /** Deterministic integration samples within each depth slice. */
-    readonly integrationSubsteps?: 1 | 2 | 4;
-    readonly maxDistance?: number;
-    readonly targetPrefix?: string;
-    readonly maxVolumes?: number;
-    readonly maxDirectionalLights?: number;
-    readonly maxPointLights?: number;
-    readonly maxSpotLights?: number;
-    /** Used when the scene has no ambient or hemisphere light. */
-    readonly ambientColor?: Color;
-    /** Rotating shadow taps per froxel. 4 removes block patterns at modest cost. */
-    readonly shadowFilterTaps?: 1 | 4;
-    /** Temporal sub-froxel jitter accumulated by fog history and optionally TAA. */
-    readonly temporalJitter?: boolean;
-    /**
-     * Fog-local temporal reconstruction of the 3D scattering/extinction grid.
-     * This history is accumulated before front-to-back integration.
-     */
-    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. */
-    readonly fogDitherStrength?: number;
-    /** Artistic multiplier for direct in-scattering. Does not change extinction. */
-    readonly scatteringIntensity?: number;
-    /** Optional separable, depth-aware blur of the resolved fog buffer. */
-    readonly blur?: false | VolumetricFogBlurOptions;
-}
-interface VolumetricFogBlurOptions {
-    /** Resolution relative to the render target. Defaults to 0.5. */
-    readonly scale?: number;
-    /** Kernel radius per direction, from 1 to 12. Defaults to 5. */
-    readonly radius?: number;
-    /** Log-depth rejection sigma. 0.05 allows about 5% relative depth variation. */
-    readonly depthSigma?: number;
-    /** Gaussian spatial sigma in fog-buffer pixels. */
-    readonly spatialSigma?: number;
-    /** Preserve depth discontinuities during the final upsample. Costs extra depth reads. Defaults to true. */
-    readonly depthAwareUpsample?: boolean;
-}
-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[];
-    /**
-     * Fog marker objects already collected by the renderer. When supplied, this
-     * list is authoritative and avoids traversing the scene for volumes.
-     */
-    readonly volumeObjects?: readonly Object3D[];
-    /**
-     * Lights already collected by the renderer. When supplied, this list is
-     * authoritative and avoids traversing the scene for lights.
-     */
-    readonly lights?: RendererExtractedLightState;
+    /** Immutable voxel resolution. Defaults to 64. */
+    readonly resolution?: 32 | 64 | 128;
+    /** World-space side length of the camera-following volume. Defaults to 48. */
+    readonly extent?: number;
+    /** Immutable probes per axis, generated automatically. Defaults to 12. */
+    readonly probeResolution?: number;
+    readonly intensity?: number;
+    /** Directions per updated probe, 16–256. Defaults to 64. */
+    readonly raysPerProbe?: number;
+    /** Fraction of probes updated per frame, (0, 1]. Defaults to 0.25. */
+    readonly updateFraction?: number;
+    /** Previous contribution on each probe update, [0, 0.99]. Defaults to 0.85. */
+    readonly historyWeight?: number;
+    readonly maxSteps?: number;
+    /** @deprecated Surface capture now spreads three GPU raster views over three frames. */
+    readonly geometryBudgetMs?: number;
+    /** Additional environment radiance. Zero by default to avoid doubling IBL. */
+    readonly skyColor?: readonly [number, number, number];
+    /** Optional distant volumes. Omitted/false preserves the single-volume GPU path. Immutable. */
+    readonly cascades?: false | SDFGICascadeOptions;
+}
+interface SDFGICascadeOptions {
+    /** Total volume count, including the near volume. Defaults to 2. */
+    readonly count?: 2 | 3;
+    /** Extent multiplier between volumes. Defaults to 2. */
+    readonly extentScale?: number;
+    /** Distant-volume voxel resolution. Defaults to 32. */
+    readonly resolution?: 32 | 64 | 128;
+    /** Distant probes per axis. Defaults to 8. */
+    readonly probeResolution?: number;
+    /** Maximum directions per distant probe. Defaults to 32. */
+    readonly raysPerProbe?: number;
+    /** Maximum fraction of distant probes updated per scheduled frame. Defaults to 0.125. */
+    readonly updateFraction?: number;
+    /** Steady-state update interval. Defaults to 4 frames; doubles for the third volume. */
+    readonly updateInterval?: number;
+}
+interface SDFGIStats {
+    /** Total volumes, including the near volume. */
+    cascadeCount: number;
+    /** Near-volume readiness and geometry diagnostics; building includes distant volumes. */
+    ready: boolean;
+    building: boolean;
+    triangles: number;
+    occupiedCells: number;
+    /** Last frame's CPU surface-capture preparation, separate from GPU frame profiling. */
+    geometryCpuMs: number;
+    geometryBuildMs: number;
+    gpuBytes: number;
+    updatedProbes: number;
 }
-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
- * materials can sample `integratedVolume` with configureVolumetricFogMaterial.
+ * Experimental one-bounce SDF GI with optional distant cascades. Geometry is static between
+ * invalidations; directional/point/spot lights update on each volume's cadence. No surface readbacks,
+ * hardware ray tracing, screen-space history, or manually authored probes.
  */
-declare class VolumetricFogEffect {
-    private scene;
-    readonly integratedVolume: FrameGraphTextureHandle;
-    readonly columnDepthBounds: FrameGraphTextureHandle;
-    readonly scatteringHistoryA: FrameGraphTextureHandle;
-    readonly scatteringHistoryB: FrameGraphTextureHandle;
-    private readonly options;
-    private readonly resources;
-    private readonly uniformStorage;
-    private readonly uniforms;
-    private readonly uniformIntegers;
-    private readonly volumeData;
+declare class SDFGI {
+    private readonly device;
+    readonly stats: SDFGIStats;
+    private readonly resolution;
+    private readonly extent;
+    private readonly probeResolution;
+    private readonly cellSize;
+    private readonly spacing;
+    private enabled;
+    private intensity;
+    private rays;
+    private fraction;
+    private history;
+    private steps;
+    private readonly sky;
+    private readonly buffers;
+    private readonly uniformData;
+    private readonly floats;
+    private readonly integers;
+    private readonly header;
     private readonly lightData;
-    private readonly selectedPointIndices;
-    private readonly selectedPointScores;
-    private readonly selectedSpotIndices;
-    private readonly selectedSpotScores;
-    private readonly collectedVolumes;
-    private readonly collectedDirectionals;
-    private readonly collectedPoints;
-    private readonly collectedSpots;
-    private volumeCount;
-    private directionalCount;
-    private pointCount;
-    private spotCount;
-    private collectionCamera;
-    private readonly collectVolumeObject;
-    private readonly collectLightObject;
-    private readonly executeFroxelPass;
-    private readonly projectionInverse;
-    private readonly viewProjectionInverse;
-    private readonly previousTemporalViewProjection;
-    private readonly previousFroxelViewProjection;
-    private readonly previousFroxelCameraPosition;
-    private previousFroxelNear;
-    private previousFroxelFar;
-    private previousFroxelWidth;
-    private previousFroxelHeight;
-    private froxelHistoryValid;
-    private froxelHistoryWriteIndex;
-    private activeHistoryRead;
-    private activeHistoryWrite;
-    private explicitVolumes;
-    private volumeObjects;
-    private extractedLights;
+    private readonly field;
+    private readonly fieldBankBytes;
+    private readonly snapshot;
+    private readonly snapshotBinding;
+    private populatedProbes;
+    private blend;
+    private previousValid;
+    private lastUpdateSeconds;
+    private readonly params;
+    private readonly surfaces;
+    private readonly seed;
+    private readonly seedBinding;
+    private readonly jumps;
+    private readonly inject;
+    private readonly injectBinding;
+    private readonly probes;
+    private readonly probeBinding;
+    private readonly lightBuffer;
+    private readonly surfaceConfig;
+    private readonly surfaceAccum;
+    private readonly surfaceStatistics;
+    private readonly surfaceConfigData;
+    private readonly resolveSurface;
+    private readonly resolveSurfaceBinding;
+    private readonly configuredSurfaces;
+    private surfaceCapture;
+    private captureAxis;
+    private pendingTriangleCount;
+    private pendingCounts;
+    private readonly configured;
+    private readonly watched;
+    private readonly lights;
+    private readonly staticDrawRoots;
     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. */
+    private scene;
+    private grid;
+    private pending;
+    private dirty;
+    private upload;
+    private frame;
+    private probeOffset;
+    private disposed;
+    private readonly cameraPosition;
+    private readonly sourcePosition;
+    private readonly targetPosition;
+    private readonly direction;
+    private buildMs;
+    private lightCount;
+    private readonly distantVolumes;
+    private cascadeFrame;
+    constructor(device: GPUDevice, options?: SDFGIOptions);
+    /** Structural settings (extent/resolutions/cascades) require recreating the backend. */
+    setOptions(options: SDFGIOptions): void;
+    /** Call after moving/changing static geometry or editing its materials. */
+    invalidate(): void;
+    get surfaceResolution(): number;
+    setSurfaceCapture(capture: SDFGISurfaceCaptureDriver): void;
+    /** Install independent capture targets/material bindings for every enabled volume. */
+    setSurfaceCaptureFactory(factory: (volume: SDFGI) => SDFGISurfaceCaptureDriver): void;
+    configureSurfaceMaterial(material: WGSLShaderMaterial): void;
+    /** Track static draw-set registration changes that require recapturing. */
+    registerStaticDrawRoot(root: Object3D): () => void;
+    /** Cascaded shadow lights represent one sun, including lights outside the scene. */
     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;
+    configureMaterial(material: WGSLShaderMaterial): void;
+    private readonly added;
+    private readonly removed;
+    private hasStaticGeometry;
+    private watch;
+    private unwatch;
+    /** Capture one all-layer projection per frame, before main-view extraction. */
+    prepare(scene: Scene, camera: Camera): void;
+    private updateLights;
+    /** Returns whether the update pass was added, for dependent material passes. */
+    addPasses(graph: FrameGraphBuilder): boolean;
+    /** Records the same production path used by the renderer; useful to GPU checks. */
+    encode(encoder: GPUCommandEncoder, timeSeconds?: number): void;
+    private encodeVolume;
+    /** One tiny asynchronous diagnostics read per rebuild; never read surface data to the CPU. */
+    private readSurfaceCount;
+    private dispatch;
     dispose(): void;
-    private executeFroxels;
-    private collectSceneData;
-    /** Selects the nearest local lights without depending on camera rotation. */
-    private selectClosestLights;
-    private writeVolume;
-    private writeDirectional;
-    private writeExtractedDirectional;
-    private writePoint;
-    private writeExtractedPoint;
-    private writeSpot;
-    private writeExtractedSpot;
-    private getResources;
 }
-/** WGSL appended to a material that calls rendererApplyVolumetricFog(). */
-declare const VOLUMETRIC_FOG_MATERIAL_WGSL = "\nfn rendererSampleIntegratedFogRaw(uv: vec2<f32>, normalizedDepth: f32) -> vec4<f32> {\n  let sliceCount = f32(textureDimensions(volumetricFogTexture).z);\n  let slicePosition = clamp(normalizedDepth, 0.0, 1.0) * sliceCount;\n  let textureZ = clamp((slicePosition - 0.5) / sliceCount, 0.0, 1.0);\n  let integrated = textureSampleLevel(volumetricFogTexture, volumetricFogSampler, vec3<f32>(uv, textureZ), 0.0);\n  // The volume stores slice endpoints but has no texel for the near-plane\n  // identity value. Reconstruct that missing endpoint for the first slice.\n  return mix(vec4<f32>(0.0, 0.0, 0.0, 1.0), integrated, min(slicePosition, 1.0));\n}\nfn rendererSampleIntegratedFog(uv: vec2<f32>, normalizedDepth: f32) -> vec4<f32> {\n  return rendererSampleIntegratedFogRaw(uv, normalizedDepth);\n}\nfn rendererApplyVolumetricFog(color: vec4<f32>, worldPosition: vec3<f32>) -> vec4<f32> {\n  let clip = rendererCamera.viewProj * vec4<f32>(worldPosition, 1.0);\n  let uv = clip.xy / clip.w * vec2<f32>(0.5, -0.5) + vec2<f32>(0.5);\n  let distance = length(worldPosition - rendererCamera.cameraPosition.xyz);\n  let bounds = textureSampleLevel(volumetricFogBoundsTexture, volumetricFogBoundsSampler, uv, 0.0).rg;\n  let z = clamp(log(max(distance, bounds.x) / bounds.x) / max(log(bounds.y / bounds.x), 0.0001), 0.0, 1.0);\n  let fog = rendererSampleIntegratedFog(uv, z);\n  return vec4<f32>(fog.rgb + color.rgb * fog.a, color.a);\n}";
-/** Adds the froxel input; append VOLUMETRIC_FOG_MATERIAL_WGSL and call its helper in fsMain. */
-declare function configureVolumetricFogMaterial(material: WGSLShaderMaterial, resource?: string, boundsResource?: string): WGSLShaderMaterial;
 
 interface WebGpuPMREMGeneratorContext {
     device: GPUDevice;
@@ -1189,6 +1194,8 @@ declare class WebGpuRenderer {
     private opaqueSortSampleTotal;
     private sortOpaqueDraws;
     constructor(options: RendererOptions);
+    /** Re-run material adapters after enabling renderer features between extractions. */
+    invalidateMaterialResolution(): void;
     private resolveMaterial;
     private resolveLineMaterial;
     private resolveLineBasicMaterial;
@@ -1269,8 +1276,10 @@ declare class WebGpuRenderer {
      * upload buffers, but never advances gameplay motion/visibility history.
      */
     createSceneCapture(canvas: HTMLCanvasElement | null, width?: number, height?: number): RendererSceneCapture;
+    private prepareSceneCaptureAsync;
     compile(scene: Scene, camera: PerspectiveCamera | OrthographicCamera): void;
     compileAsync(scene: Scene, camera: PerspectiveCamera | OrthographicCamera): Promise<void>;
+    prepareSceneGeometryAsync(scene: Scene, camera: Camera): Promise<void>;
     /**
      * Creates a Three-compatible CubeUV PMREM generator. Its output is a
      * HalfFloat Texture and can be assigned directly to a graph material's
@@ -1291,6 +1300,8 @@ declare class WebGpuRenderer {
     private disposeStaticDrawSetResource;
     private renderFrame;
     private recordPresentationOverlay;
+    /** Present application UI without changing scene extraction, pipelines or temporal history. */
+    renderPresentationOnly(): void;
     destroy(): void;
     private createStaticPipelines;
     private ensureTransmissionSnapshot;
@@ -1497,6 +1508,203 @@ declare class WebGpuRenderer {
     private writeShadowCameraBuffer;
 }
 
+/** All-layer rasterization: depth testing and writes are disabled on the variants. */
+declare class SDFGISurfaceCapture implements SDFGISurfaceCaptureDriver {
+    private readonly camera;
+    private readonly center;
+    private readonly target;
+    private readonly options;
+    private readonly variants;
+    constructor(renderer: Pick<WebGpuRenderer, "createSceneCapture">, gi: SDFGI, resolve: (source: WGSLShaderMaterial) => WGSLShaderMaterial | null, isolateMaterials?: boolean);
+    capture(scene: Scene, volume: SDFGIVolume, axis: number): number;
+    dispose(): void;
+}
+
+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;
+    baseDensity: number;
+    heightFalloff: number;
+    heightOffset: number;
+    startDistance?: number;
+    scatteringDistribution: number;
+    albedo: Color;
+    emissive: Color;
+    ambientIntensity?: number;
+    scatteringMode: VolumetricFogScatteringMode;
+}
+/** Scene marker compatible with legacy objects through `isFogVolumeObject`. */
+declare class VolumetricFogVolumeObject extends Object3D {
+    readonly volume: VolumetricFogVolumeSettings;
+    readonly isFogVolumeObject = true;
+    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. */
+    readonly depthSlices?: number;
+    /** Deterministic integration samples within each depth slice. */
+    readonly integrationSubsteps?: 1 | 2 | 4;
+    readonly maxDistance?: number;
+    readonly targetPrefix?: string;
+    readonly maxVolumes?: number;
+    readonly maxDirectionalLights?: number;
+    readonly maxPointLights?: number;
+    readonly maxSpotLights?: number;
+    /** Used when the scene has no ambient or hemisphere light. */
+    readonly ambientColor?: Color;
+    /** Rotating shadow taps per froxel. 4 removes block patterns at modest cost. */
+    readonly shadowFilterTaps?: 1 | 4;
+    /** Temporal sub-froxel jitter accumulated by fog history and optionally TAA. */
+    readonly temporalJitter?: boolean;
+    /**
+     * Fog-local temporal reconstruction of the 3D scattering/extinction grid.
+     * This history is accumulated before front-to-back integration.
+     */
+    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. */
+    readonly fogDitherStrength?: number;
+    /** Artistic multiplier for direct in-scattering. Does not change extinction. */
+    readonly scatteringIntensity?: number;
+    /** Optional separable, depth-aware blur of the resolved fog buffer. */
+    readonly blur?: false | VolumetricFogBlurOptions;
+}
+interface VolumetricFogBlurOptions {
+    /** Resolution relative to the render target. Defaults to 0.5. */
+    readonly scale?: number;
+    /** Kernel radius per direction, from 1 to 12. Defaults to 5. */
+    readonly radius?: number;
+    /** Log-depth rejection sigma. 0.05 allows about 5% relative depth variation. */
+    readonly depthSigma?: number;
+    /** Gaussian spatial sigma in fog-buffer pixels. */
+    readonly spatialSigma?: number;
+    /** Preserve depth discontinuities during the final upsample. Costs extra depth reads. Defaults to true. */
+    readonly depthAwareUpsample?: boolean;
+}
+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[];
+    /**
+     * Fog marker objects already collected by the renderer. When supplied, this
+     * list is authoritative and avoids traversing the scene for volumes.
+     */
+    readonly volumeObjects?: readonly Object3D[];
+    /**
+     * Lights already collected by the renderer. When supplied, this list is
+     * authoritative and avoids traversing the scene for lights.
+     */
+    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
+ * materials can sample `integratedVolume` with configureVolumetricFogMaterial.
+ */
+declare class VolumetricFogEffect {
+    private scene;
+    readonly integratedVolume: FrameGraphTextureHandle;
+    readonly columnDepthBounds: FrameGraphTextureHandle;
+    readonly scatteringHistoryA: FrameGraphTextureHandle;
+    readonly scatteringHistoryB: FrameGraphTextureHandle;
+    private readonly options;
+    private readonly resources;
+    private readonly uniformStorage;
+    private readonly uniforms;
+    private readonly uniformIntegers;
+    private readonly volumeData;
+    private readonly lightData;
+    private readonly selectedPointIndices;
+    private readonly selectedPointScores;
+    private readonly selectedSpotIndices;
+    private readonly selectedSpotScores;
+    private readonly collectedVolumes;
+    private readonly collectedDirectionals;
+    private readonly collectedPoints;
+    private readonly collectedSpots;
+    private volumeCount;
+    private directionalCount;
+    private pointCount;
+    private spotCount;
+    private collectionCamera;
+    private readonly collectVolumeObject;
+    private readonly collectLightObject;
+    private readonly executeFroxelPass;
+    private readonly projectionInverse;
+    private readonly viewProjectionInverse;
+    private readonly previousTemporalViewProjection;
+    private readonly previousFroxelViewProjection;
+    private readonly previousFroxelCameraPosition;
+    private previousFroxelNear;
+    private previousFroxelFar;
+    private previousFroxelWidth;
+    private previousFroxelHeight;
+    private froxelHistoryValid;
+    private froxelHistoryWriteIndex;
+    private activeHistoryRead;
+    private activeHistoryWrite;
+    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;
+    /** Selects the nearest local lights without depending on camera rotation. */
+    private selectClosestLights;
+    private writeVolume;
+    private writeDirectional;
+    private writeExtractedDirectional;
+    private writePoint;
+    private writeExtractedPoint;
+    private writeSpot;
+    private writeExtractedSpot;
+    private getResources;
+}
+/** WGSL appended to a material that calls rendererApplyVolumetricFog(). */
+declare const VOLUMETRIC_FOG_MATERIAL_WGSL = "\nfn rendererSampleIntegratedFogRaw(uv: vec2<f32>, normalizedDepth: f32) -> vec4<f32> {\n  let sliceCount = f32(textureDimensions(volumetricFogTexture).z);\n  let slicePosition = clamp(normalizedDepth, 0.0, 1.0) * sliceCount;\n  let textureZ = clamp((slicePosition - 0.5) / sliceCount, 0.0, 1.0);\n  let integrated = textureSampleLevel(volumetricFogTexture, volumetricFogSampler, vec3<f32>(uv, textureZ), 0.0);\n  // The volume stores slice endpoints but has no texel for the near-plane\n  // identity value. Reconstruct that missing endpoint for the first slice.\n  return mix(vec4<f32>(0.0, 0.0, 0.0, 1.0), integrated, min(slicePosition, 1.0));\n}\nfn rendererSampleIntegratedFog(uv: vec2<f32>, normalizedDepth: f32) -> vec4<f32> {\n  return rendererSampleIntegratedFogRaw(uv, normalizedDepth);\n}\nfn rendererApplyVolumetricFog(color: vec4<f32>, worldPosition: vec3<f32>) -> vec4<f32> {\n  let clip = rendererCamera.viewProj * vec4<f32>(worldPosition, 1.0);\n  let uv = clip.xy / clip.w * vec2<f32>(0.5, -0.5) + vec2<f32>(0.5);\n  let distance = length(worldPosition - rendererCamera.cameraPosition.xyz);\n  let bounds = textureSampleLevel(volumetricFogBoundsTexture, volumetricFogBoundsSampler, uv, 0.0).rg;\n  let z = clamp(log(max(distance, bounds.x) / bounds.x) / max(log(bounds.y / bounds.x), 0.0001), 0.0, 1.0);\n  let fog = rendererSampleIntegratedFog(uv, z);\n  return vec4<f32>(fog.rgb + color.rgb * fog.a, color.a);\n}";
+/** Adds the froxel input; append VOLUMETRIC_FOG_MATERIAL_WGSL and call its helper in fsMain. */
+declare function configureVolumetricFogMaterial(material: WGSLShaderMaterial, resource?: string, boundsResource?: string): WGSLShaderMaterial;
+
 interface GTAODenoiseOptions {
     readonly radius?: number;
     /** Fixed bilateral tap count. Normalized to 4, 8, 12, or 16. */
@@ -1570,6 +1778,10 @@ declare class GTAOEffect {
 }
 
 interface SSROptions {
+    /** Enables fullscreen SSR. Independent of surfaceSteps. */
+    readonly enabled?: boolean;
+    /** Ray budget for late surface shaders. Zero disables surface SSR. Defaults to 0. */
+    readonly surfaceSteps?: number;
     /** Resolution relative to the main render target. Defaults to 0.5. */
     readonly resolutionScale?: number;
     /** Maximum ray length in view-space units. */
@@ -1602,6 +1814,10 @@ declare class SSREffect {
     private readonly options;
     private readonly passes;
     constructor(options?: SSROptions);
+    get enabled(): boolean;
+    /** Independent ray budget for reflections traced inside late surface shaders. */
+    get surfaceRaySteps(): number;
+    setOptions(options: SSROptions): void;
     addPasses(graph: FrameGraphBuilder, inputs: SSRInputs): FrameGraphTextureHandle;
 }
 
@@ -1943,4 +2159,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 DetailCullingSettings, type DirectionalShadowUpdateOptions, 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, type PipelineDiagnosticOrigin, 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 RendererSceneCapture, type RendererSceneCaptureOptions, type RendererSceneCapturePostProcessContext, type RendererShadowMapDebugInfo, type RendererShadowMapDebugTextureInfo, type RendererTextureTargetDescriptor, type RendererVisibilityProfile, SCENE_COLOR_FORMAT, type SMAACompositeOptions, type SMAAEdgeDetectionMode, SMAAEffect, type SMAAOptions, type SMAAQualityPreset, SSREffect, type SSRInputs, type SSROptions, type ShaderDefineValue, type ShaderDefines, type StaticDrawSet, type StaticDrawSetOptions, type StaticSpatialObject, 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, buildParticleLightingShaderHeader, configureVolumetricFogMaterial, createComputePipelineAsync, createRenderPipelineAsync, registerPipelineDiagnosticOrigin, resolveDetailCulling, setObjectDetailCulling, setPipelineDiagnosticLoading };
+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 DetailCullingSettings, type DirectionalShadowUpdateOptions, 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, type PipelineDiagnosticOrigin, 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 RendererSceneCapture, type RendererSceneCaptureOptions, type RendererSceneCapturePostProcessContext, type RendererShadowMapDebugInfo, type RendererShadowMapDebugTextureInfo, type RendererTextureTargetDescriptor, type RendererVisibilityProfile, SCENE_COLOR_FORMAT, SDFGI, type SDFGICascadeOptions, type SDFGIOptions, type SDFGIStats, SDFGISurfaceCapture, type SDFGISurfaceCaptureDriver, type SDFGIVolume, type SMAACompositeOptions, type SMAAEdgeDetectionMode, SMAAEffect, type SMAAOptions, type SMAAQualityPreset, SSREffect, type SSRInputs, type SSROptions, type ShaderDefineValue, type ShaderDefines, type StaticDrawSet, type StaticDrawSetOptions, type StaticSpatialObject, 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, buildParticleLightingShaderHeader, configureVolumetricFogMaterial, createComputePipelineAsync, createRenderPipelineAsync, registerPipelineDiagnosticOrigin, resolveDetailCulling, setObjectDetailCulling, setPipelineDiagnosticLoading };