@hology/webgpu-renderer 0.1.3 → 0.1.5

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as three from 'three';
-import { Color, Vector2, Vector3, Vector4, Matrix3, Matrix4, Material, Texture, MaterialParameters, Object3D, PerspectiveCamera, OrthographicCamera, Scene, DirectionalLight } from 'three';
+import { Color, Vector2, Vector3, Vector4, Matrix3, Matrix4, Material, Texture, MaterialParameters, DirectionalLight, Object3D, PerspectiveCamera, OrthographicCamera, Scene } 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 ComputeKernelDescriptor {
@@ -78,6 +78,8 @@ interface WGSLShaderMaterialParameters extends MaterialParameters {
     storageBuffers?: Record<string, WGSLStorageBufferBinding>;
     vertexAttributes?: readonly WGSLVertexAttributeBinding[];
     primitiveTopology?: GPUPrimitiveTopology;
+    /** Hash mutable uniform values on every renderer update. */
+    uniformValuesAutoUpdate?: boolean;
     /** Render triangle meshes as one-pixel triangle edges, matching Three.js wireframe materials. */
     wireframe?: boolean;
 }
@@ -108,6 +110,19 @@ declare class WGSLShaderMaterial extends Material {
     private storageBufferListCache;
     private textureLayoutKeyDeviceCache;
     private textureLayoutKeyCache;
+    /**
+     * Whether the renderer should hash mutable uniform values while rendering.
+     * Disable this for materials whose uniform changes are explicitly invalidated
+     * through `uniformValuesNeedsUpdate`.
+     */
+    uniformValuesAutoUpdate: boolean;
+    /**
+     * Incremented by setting uniformValuesNeedsUpdate to true.
+     * Each renderer resource keeps its own observed version, so one invalidation
+     * safely updates forward, depth, shadow, and other material variants.
+     */
+    uniformValuesAutoVersion: number;
+    set uniformValuesNeedsUpdate(value: boolean);
     constructor(parameters: WGSLShaderMaterialParameters);
     getUniformLayout(): UniformLayout;
     setUniform(name: string, definition: WGSLShaderMaterialUniformInput): this;
@@ -162,6 +177,97 @@ declare class RenderGraph {
     private resolveExecutionOrder;
 }
 
+interface TextureResource {
+    version: number;
+    width: number;
+    height: number;
+    depthOrArrayLayers: number;
+    format: GPUTextureFormat;
+    textureDimension: GPUTextureDimension;
+    viewDimension: GPUTextureViewDimension;
+    sampleType: GPUTextureSampleType;
+    samplerBindingType: GPUSamplerBindingType;
+    mipLevelCount: number;
+    texture: GPUTexture;
+    view: GPUTextureView;
+    sampler: GPUSampler;
+}
+interface ExtractedLightState {
+    ambient: Vector4;
+    hemisphere: ExtractedHemisphereLight | null;
+    directionals: ExtractedDirectionalLight[];
+    points: ExtractedPointLight[];
+    spots: ExtractedSpotLight[];
+    directional: ExtractedDirectionalLight | null;
+    point: ExtractedPointLight | null;
+    spot: ExtractedSpotLight | null;
+}
+interface ExtractedHemisphereLight {
+    direction: Vector3;
+    skyColor: Vector3;
+    groundColor: Vector3;
+    intensity: number;
+}
+interface ExtractedDirectionalLight {
+    sourceLight: DirectionalLight | null;
+    position: Vector3;
+    target: Vector3;
+    direction: Vector3;
+    color: Vector3;
+    intensity: number;
+    volumetricIntensity: number;
+    castShadow: boolean;
+    shadowBias: number;
+    shadowNormalBias: number;
+    shadowRadius: number;
+    shadowIntensity: number;
+    shadowMapSize: number;
+    shadowCameraLeft: number;
+    shadowCameraRight: number;
+    shadowCameraTop: number;
+    shadowCameraBottom: number;
+    shadowCameraNear: number;
+    shadowCameraFar: number;
+}
+interface ExtractedPointLight {
+    position: Vector3;
+    color: Vector3;
+    intensity: number;
+    volumetricIntensity: number;
+    range: number;
+    decay: number;
+    castShadow: boolean;
+    shadowBias: number;
+    shadowNormalBias: number;
+    shadowRadius: number;
+    shadowIntensity: number;
+    shadowMapSize: number;
+    shadowCameraNear: number;
+    shadowCameraFar: number;
+}
+interface ExtractedSpotLight {
+    position: Vector3;
+    direction: Vector3;
+    color: Vector3;
+    intensity: number;
+    volumetricIntensity: number;
+    range: number;
+    angle: number;
+    penumbra: number;
+    decay: number;
+    castShadow: boolean;
+    shadowBias: number;
+    shadowNormalBias: number;
+    shadowRadius: number;
+    shadowIntensity: number;
+    shadowMapSize: number;
+    shadowCameraNear: number;
+    shadowCameraFar: number;
+    shadowCameraFov: number;
+}
+
+/** Camera-visible lights collected during the renderer's scene extraction. */
+type RendererExtractedLightState = ExtractedLightState;
 /**
  * Resolves a scene-authored Three material to a renderer-native WGSL material
  * without mutating the scene's material slots. Return `undefined` to use the
@@ -211,6 +317,16 @@ interface StaticDrawSet {
     dispose(): void;
 }
 interface RendererGraphBuilderContext {
+    /**
+     * Visible fog-volume marker objects collected during ordinary scene
+     * extraction. Passing this list to volumetric fog avoids another scene walk.
+     */
+    readonly fogVolumeObjects: readonly Object3D[];
+    /**
+     * Camera-visible lights collected during ordinary scene extraction. The
+     * ordering matches the renderer's shadow-array layers.
+     */
+    readonly extractedLights: RendererExtractedLightState;
     addDirectionalShadowPass(): void;
     addPointShadowPass(): void;
     addSpotShadowPass(): void;
@@ -487,6 +603,16 @@ interface VolumetricFogInputs {
     readonly depth: 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;
 }
 /**
  * Compute-driven froxel fog. Add it after opaque rendering and before the late
@@ -507,6 +633,8 @@ declare class VolumetricFogEffect {
     private readonly projectionInverse;
     private readonly viewProjectionInverse;
     private explicitVolumes;
+    private volumeObjects;
+    private extractedLights;
     private cascadeDirectionalLights;
     private compositePass;
     private readonly blurPassCache;
@@ -524,8 +652,11 @@ declare class VolumetricFogEffect {
     private writeVolume;
     private lightColor;
     private writeDirectional;
+    private writeExtractedDirectional;
     private writePoint;
+    private writeExtractedPoint;
     private writeSpot;
+    private writeExtractedSpot;
     private getResources;
 }
 /** WGSL appended to a material that calls rendererApplyVolumetricFog(). */
@@ -533,22 +664,6 @@ declare const VOLUMETRIC_FOG_MATERIAL_WGSL = "\nfn rendererSampleIntegratedFog(u
 /** 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 TextureResource {
-    version: number;
-    width: number;
-    height: number;
-    depthOrArrayLayers: number;
-    format: GPUTextureFormat;
-    textureDimension: GPUTextureDimension;
-    viewDimension: GPUTextureViewDimension;
-    sampleType: GPUTextureSampleType;
-    samplerBindingType: GPUSamplerBindingType;
-    mipLevelCount: number;
-    texture: GPUTexture;
-    view: GPUTextureView;
-    sampler: GPUSampler;
-}
-
 interface WebGpuPMREMGeneratorContext {
     device: GPUDevice;
     getTextureResource(texture: Texture): TextureResource;
@@ -640,6 +755,12 @@ declare class WebGpuRenderer {
     /** Fast variants for MRT/non-default target format combinations. */
     private readonly forwardMaterialTargetFastCache;
     private readonly forwardMaterialFrameCache;
+    /**
+     * DrawCall objects are pooled and many draws share one MaterialResource.
+     * Once a resource has passed its structural/material/texture checks in an
+     * extraction, avoid repeating texture-list scans for every matching draw.
+     */
+    private readonly drawMaterialResourceFrameValidation;
     private readonly depthMaterialFastCache;
     private readonly sharedForwardPipelineCache;
     private readonly sharedForwardPipelinePromiseCache;
@@ -679,8 +800,15 @@ declare class WebGpuRenderer {
     private readonly vertexAttributeGroupCache;
     private readonly vertexAttributeGroupBufferKeyCache;
     private readonly compileDrawScratch;
-    private readonly indirectSubmissionStreamsScratch;
+    private readonly dynamicIndirectSubmissionCache;
+    private readonly indirectStreamKeyCache;
+    private nextIndirectStreamKey;
+    private indirectBundleInvalidationVersion;
+    private readonly colorFormatsIdentityCache;
+    private readonly colorFormatsValueCache;
+    private nextColorFormatsId;
     private readonly renderBundleScratch;
+    private readonly indirectMaterialResourcesScratch;
     private readonly directBundleDrawStatsScratch;
     private readonly sortedOpaqueBatchesScratch;
     private readonly opaqueBatchPool;
@@ -706,6 +834,7 @@ declare class WebGpuRenderer {
     private readonly activeDirectionalLightsScratch;
     private readonly activePointLightsScratch;
     private readonly activeSpotLightsScratch;
+    private readonly fogVolumeObjectsScratch;
     private readonly resolvedMeshMaterialsScratch;
     private readonly extractedLightsScratch;
     private readonly extractedFrameScratch;
@@ -866,8 +995,13 @@ declare class WebGpuRenderer {
     private getShadowCameraBuffer;
     private getSharedShadowBindGroupForCameraBuffer;
     private buildIndirectSubmissionStreams;
+    private getIndirectStreamKey;
     private getOrCreateStaticIndirectSubmissionStreams;
     private getOrCreateIndirectForwardBundle;
+    private submitIndirectStreamDirect;
+    private setRetainedIndirectBundleState;
+    private getIndirectBundleHash;
+    private getColorFormatsId;
     private getDirectForwardBundleKey;
     private getOrCreateDirectForwardBundle;
     private getOrCreateStaticMaterialBundle;
@@ -1145,6 +1279,49 @@ declare class FXAAEffect {
     addPass(graph: FrameGraphBuilder, source: FrameGraphTextureHandle, options?: FXAACompositeOptions): FrameGraphTextureHandle;
 }
 
+type SMAAQualityPreset = "low" | "medium" | "high" | "ultra";
+type SMAAEdgeDetectionMode = "luma" | "color";
+interface SMAAOptions {
+    /** Pattern-search budget. Defaults to `high` (16 orthogonal and 8 diagonal steps). */
+    readonly quality?: SMAAQualityPreset;
+    /** Perceptual edge threshold. Defaults to 0.08, which retains dark toon outlines. */
+    readonly threshold?: number;
+    /** Rejects edges weak relative to their neighborhood. Defaults to 0.5. */
+    readonly localContrastAdaptation?: number;
+    /** Luma is fastest; color retains isoluminant stylized edges. Defaults to `color`. */
+    readonly edgeDetection?: SMAAEdgeDetectionMode;
+    /** Corner rounding from 0 (preserve) to 1 (round). Defaults to 0.25. */
+    readonly cornerRounding?: number;
+    /** Optional contrast-adaptive sharpening, from 0 to 1. Defaults to 0. */
+    readonly sharpness?: number;
+    readonly targetPrefix?: string;
+}
+interface SMAACompositeOptions {
+    readonly output?: FrameGraphTextureHandle;
+}
+/**
+ * SMAA 1x with local contrast adaptation, accurate area classification,
+ * diagonal detection, corner preservation, and optional fused sharpening.
+ */
+declare class SMAAEffect {
+    threshold: number;
+    localContrastAdaptation: number;
+    edgeDetection: SMAAEdgeDetectionMode;
+    cornerRounding: number;
+    sharpness: number;
+    private readonly quality;
+    private readonly targetPrefix;
+    private readonly areaTexture;
+    private readonly edgePasses;
+    private readonly weightPasses;
+    private readonly blendPasses;
+    constructor(options?: SMAAOptions);
+    addPass(graph: FrameGraphBuilder, source: FrameGraphTextureHandle, options?: SMAACompositeOptions): FrameGraphTextureHandle;
+    dispose(): void;
+    get searchSteps(): number;
+    get diagonalSteps(): number;
+}
+
 interface BloomOptions {
     /** Overall bloom contribution. Defaults to 0.9. */
     readonly strength?: number;
@@ -1264,4 +1441,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, 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, 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 };