@hology/webgpu-renderer 0.1.6 → 0.1.8

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as three from 'three';
-import { Color, Vector2, Vector3, Vector4, Matrix3, Matrix4, Material, Texture, MaterialParameters, DirectionalLight, Object3D, PerspectiveCamera, OrthographicCamera, Scene } from 'three';
+import { Color, Vector2, Vector3, Vector4, Matrix3, Matrix4, Material, Texture, MaterialParameters, DirectionalLight, PointLight, SpotLight, Object3D, PerspectiveCamera, OrthographicCamera, BufferGeometry, 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 {
@@ -137,6 +137,8 @@ declare class WGSLShaderMaterial extends Material {
     customProgramCacheKey(): string;
     getTexturesList(): readonly Texture[];
     usesSceneTextures(): boolean;
+    usesSceneColor(): boolean;
+    usesSceneDepth(): boolean;
     getGraphTextureInputs(): Record<string, WGSLGraphTextureInput>;
     requiresLatePass(): boolean;
     getUniformValueHash(): number;
@@ -177,6 +179,9 @@ declare class RenderGraph {
     private resolveExecutionOrder;
 }
 
+/** Shared renderer lighting ABI for procedural particle geometry. */
+declare function buildParticleLightingShaderHeader(receiveShadow?: boolean, modelMatrixBody?: string): string;
+
 interface TextureResource {
     version: number;
     width: number;
@@ -230,10 +235,12 @@ interface ExtractedDirectionalLight {
     shadowCameraFar: number;
 }
 interface ExtractedPointLight {
+    sourceLight: PointLight;
     position: Vector3;
     color: Vector3;
     intensity: number;
     volumetricIntensity: number;
+    distance: number;
     range: number;
     decay: number;
     castShadow: boolean;
@@ -246,6 +253,7 @@ interface ExtractedPointLight {
     shadowCameraFar: number;
 }
 interface ExtractedSpotLight {
+    sourceLight: SpotLight;
     position: Vector3;
     direction: Vector3;
     color: Vector3;
@@ -308,6 +316,12 @@ interface RendererOptions {
 interface StaticDrawSetOptions {
     label?: string;
     onUnsupported?: "throw" | "skip";
+    /**
+     * Admit transparent and scene-texture materials and render them, in their
+     * stable recorded order, during the late pass. No camera-depth sorting is
+     * performed inside the set.
+     */
+    allowUnsortedLateDraws?: boolean;
 }
 interface StaticDrawSet {
     readonly label: string;
@@ -337,7 +351,10 @@ interface RendererGraphBuilderContext {
     defineTextureTarget(name: string, descriptor?: RendererTextureTargetDescriptor): void;
     addForwardPass(output?: string): void;
     addOpaquePass(output?: string): void;
-    addSceneTextureCopyPass(source?: string): void;
+    addSceneTextureCopyPass(source?: string, requirements?: {
+        readonly sceneColor?: boolean;
+        readonly sceneDepth?: boolean;
+    }): void;
     addLatePass(output?: string): void;
     addHiZHistoryPass(dependsOn?: string): void;
     addMaterialPass(descriptor?: RendererMaterialPassDescriptor): void;
@@ -363,6 +380,8 @@ interface RendererMaterialPassDescriptor {
     readonly drawStage?: "all" | "opaque" | "late";
     /** Preserve existing attachment contents instead of clearing them. */
     readonly loadColor?: boolean;
+    /** Color used when clearing the attachments. Defaults to the renderer clear color. */
+    readonly clearColor?: readonly [number, number, number, number];
     /** Preserve depth written by an earlier pass. Defaults to clear. */
     readonly loadDepth?: boolean;
     /** Draw only objects accepted by this predicate. Intended for selection/mask passes. */
@@ -405,13 +424,18 @@ interface RendererCustomPassContext {
         view: GPUTextureView;
         sampler: GPUSampler;
     };
+    /** Resolves the current renderer-owned vertex buffer for a geometry. */
+    getGeometryVertexBuffer(geometry: BufferGeometry, attribute: "position" | "normal"): GPUBuffer;
     getColorFormat(name: string): GPUTextureFormat;
     getShadowMapDebugInfo(): RendererShadowMapDebugInfo;
     /** Shared light uniforms and shadow arrays used by the forward renderer. */
     getSceneLightingResources(): RendererSceneLightingResources;
 }
 interface RendererSceneLightingResources {
+    readonly cameraBuffer: GPUBuffer;
     readonly lightBuffer: GPUBuffer;
+    readonly shadowSampler: GPUSampler;
+    readonly linearSampler: GPUSampler;
     readonly directionalShadowView: GPUTextureView;
     readonly pointShadowView: GPUTextureView;
     readonly spotShadowView: GPUTextureView;
@@ -507,6 +531,7 @@ interface FrameGraphMaterialPassDescriptor {
     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);
@@ -528,7 +553,10 @@ declare class FrameGraphBuilder {
     addVisibilityPass(): void;
     addForwardPass(output?: FrameGraphTextureHandle): void;
     addOpaquePass(output?: FrameGraphTextureHandle): void;
-    addSceneTextureCopyPass(source?: FrameGraphTextureHandle): void;
+    addSceneTextureCopyPass(source?: FrameGraphTextureHandle, requirements?: {
+        readonly sceneColor?: boolean;
+        readonly sceneDepth?: boolean;
+    }): void;
     addLatePass(output?: FrameGraphTextureHandle): void;
     addHiZHistoryPass(dependsOn?: string): void;
     addMaterialPass(descriptor?: FrameGraphMaterialPassDescriptor): void;
@@ -648,6 +676,22 @@ declare class VolumetricFogEffect {
     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;
@@ -679,8 +723,9 @@ declare class VolumetricFogEffect {
     dispose(): void;
     private executeFroxels;
     private collectSceneData;
+    /** Selects the nearest local lights without depending on camera rotation. */
+    private selectClosestLights;
     private writeVolume;
-    private lightColor;
     private writeDirectional;
     private writeExtractedDirectional;
     private writePoint;
@@ -828,6 +873,8 @@ declare class WebGpuRenderer {
     private readonly standardVertexAttributeCache;
     private readonly geometryVertexBufferFastCache;
     private readonly vertexAttributeGroupCache;
+    private readonly materialVertexAttributeCache;
+    private readonly vertexBufferBindingPlanCache;
     private readonly vertexAttributeGroupBufferKeyCache;
     private readonly compileDrawScratch;
     private readonly dynamicIndirectSubmissionCache;
@@ -911,6 +958,7 @@ declare class WebGpuRenderer {
     private hasRenderCallbacks;
     initialize(): Promise<void>;
     createComputeKernel(descriptor: ComputeKernelDescriptor): ComputeKernel;
+    getDevice(): GPUDevice | null;
     setRenderGraphBuilder(builder: RendererGraphBuilder): void;
     /**
      * Associates the first directional shadow layers with cascaded-shadow-map
@@ -1083,6 +1131,8 @@ declare class WebGpuRenderer {
     private clearSpotShadow;
     private drawDepthLike;
     private getGeometryResource;
+    /** Upload changed standard BufferAttributes without replacing their buffers. */
+    private updateDynamicGeometryAttributes;
     private getSkinnedGeometryResource;
     private getSkinningPalette;
     private refreshSkinningPalette;
@@ -1107,6 +1157,8 @@ declare class WebGpuRenderer {
     private getInterleavedGeometryVertexBuffer;
     private ensureWireframeIndex;
     private bindGeometryVertexBuffers;
+    private getStandardVertexAttribute;
+    private prepareDrawGeometryVertexBuffers;
     private getDefaultInstanceAttributeBuffer;
     private getMeshExtractionCacheEntry;
     private getInstancedMeshExtractionCacheEntry;
@@ -1572,6 +1624,8 @@ interface OutlineOptions {
     readonly edgeStrength?: number;
     /** Outline radius in physical render pixels. */
     readonly edgeThickness?: number;
+    /** Width of the outline's antialiased falloff in physical render pixels. */
+    readonly edgeSoftness?: number;
     readonly targetPrefix?: string;
 }
 interface OutlineInputs {
@@ -1593,6 +1647,7 @@ declare class OutlineEffect {
     visibleEdgeColor: [number, number, number];
     edgeStrength: number;
     edgeThickness: number;
+    edgeSoftness: number;
     readonly selectedObjects: Set<Object3D<three.Object3DEventMap>>;
     readonly selectedInstances: OutlineInstanceSelection[];
     private readonly targetPrefix;
@@ -1604,7 +1659,8 @@ declare class OutlineEffect {
     setSelectedObjects(objects: Iterable<Object3D>): void;
     setSelectedInstances(selections: Iterable<OutlineInstanceSelection>): void;
     addPass(graph: FrameGraphBuilder, source: FrameGraphTextureHandle): FrameGraphTextureHandle;
+    private addCachedPass;
     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, 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 };
+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, buildParticleLightingShaderHeader, configureVolumetricFogMaterial };