@hology/webgpu-renderer 0.1.21 → 0.1.23

package/dist/index.d.ts

@@ -32,6 +32,14 @@ interface ResolvedDetailCulling {
 declare function setObjectDetailCulling(object: Object3D, settings: DetailCullingSettings): void;
 declare function resolveDetailCulling(object: Object3D | null, registration?: DetailCullingSettings): ResolvedDetailCulling;
 
+interface StaticSpatialObject {
+    /** Refresh after geometry, inherited transforms, or detail policy changes. */
+    update(): void;
+    /** Edited objects temporarily return to ordinary scene traversal. */
+    setEditing(editing: boolean): void;
+    dispose(): void;
+}
+
 type ShaderDefineValue = string | number | boolean;
 type ShaderDefines = Record<string, ShaderDefineValue | null | undefined>;
 
@@ -120,6 +128,8 @@ declare class WGSLShaderMaterial extends Material {
     wireframe: boolean;
     private uniformLayoutCache;
     private programCacheKeyCache;
+    private depthProgramCacheKeyCache;
+    private pointShadowProgramCacheKeyCache;
     private textureListCache;
     private textureVersionsCache;
     private textureVersionHashCache;
@@ -152,6 +162,9 @@ declare class WGSLShaderMaterial extends Material {
     /** Three's default clone path cannot call this material's required constructor. */
     clone(): this;
     customProgramCacheKey(): string;
+    /** Depth passes can share pipelines despite differences in unused forward shading. */
+    getDepthProgramCacheKey(pointShadow?: boolean): string;
+    private createProgramCacheKey;
     getTexturesList(): readonly Texture[];
     usesSceneTextures(): boolean;
     usesSceneColor(): boolean;
@@ -342,6 +355,34 @@ interface RendererMaterialPassDescriptor {
     /** Replace each accepted draw's material while preserving its geometry and instance data. */
     readonly overrideMaterial?: WGSLShaderMaterial | ((source: WGSLShaderMaterial, skinned: boolean) => WGSLShaderMaterial);
 }
+interface RendererSceneCaptureOptions {
+    /** Exclude objects/subtrees. Static snapshots 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. */
+    readonly includeLocalLights?: boolean;
+    /** Optional final pass. Must write display-sRGB color into targetView. */
+    readonly postProcess?: (context: RendererSceneCapturePostProcessContext) => void;
+}
+interface RendererSceneCapturePostProcessContext {
+    readonly device: GPUDevice;
+    readonly encoder: GPUCommandEncoder;
+    readonly colorView: GPUTextureView;
+    readonly depthView: GPUTextureView;
+    readonly sampler: GPUSampler;
+    readonly targetView: GPUTextureView;
+    readonly targetFormat: GPUTextureFormat;
+    readonly width: number;
+    readonly height: number;
+    readonly camera: PerspectiveCamera | OrthographicCamera;
+}
+/** Non-temporal, unshadowed scene view sharing the renderer's GPU resources. */
+interface RendererSceneCapture {
+    /** Persistent display-space output when created without a canvas. Owned by the capture. */
+    readonly textureView?: GPUTextureView;
+    capture(scene: three.Scene, camera: PerspectiveCamera | OrthographicCamera, options?: RendererSceneCaptureOptions): void;
+    dispose(): void;
+}
 interface RendererShadowMapDebugTextureInfo {
     readonly view: GPUTextureView | null;
     readonly size: number;
@@ -432,6 +473,12 @@ interface RendererFrameProfile {
         gpuIndirectDraws?: number;
     };
     frameIndex: number;
+    /** Internal scene attachment dimensions in physical pixels. */
+    renderWidth?: number;
+    renderHeight?: number;
+    /** Presentation dimensions before any internal resolution scaling. */
+    presentationWidth?: number;
+    presentationHeight?: number;
     cpuTimeMs: number;
     gpuTimeMs: number | null;
     drawCallCount: number;
@@ -914,11 +961,14 @@ declare class WebGpuRenderer {
     private sampleCount;
     private renderScale;
     private hiZOcclusionCullingEnabled;
+    private frameHiZOcclusionCullingNeeded;
     private multiDrawIndirectEnabled;
     private dynamicBatchingEnabled;
     private multiDrawIndirectSupported;
     private tiledPointLights;
     private tiledLightingEnabled;
+    private readonly transientPointLightsScratch;
+    private readonly transientPointScoresScratch;
     private renderGraphProfilingEnabled;
     private indirectFirstInstanceSupported;
     private timestampQuerySupported;
@@ -983,7 +1033,7 @@ declare class WebGpuRenderer {
      * `instance_index`. Keep shared default buffers large enough for the packed
      * renderer instance range instead of binding one value at index zero.
      */
-    private readonly defaultInstanceAttributeBuffers;
+    private readonly defaultVertexAttributeBuffers;
     private readonly textureManager;
     private readonly renderGraph;
     private readonly nativePostSubmit;
@@ -1013,6 +1063,7 @@ declare class WebGpuRenderer {
     private readonly geometryVertexBufferFastCache;
     private readonly vertexAttributeGroupCache;
     private readonly materialVertexAttributeCache;
+    private readonly sharedVertexAttributeLayouts;
     private readonly vertexBufferBindingPlanCache;
     private readonly preparedVertexBufferCache;
     private readonly vertexAttributeGroupBufferKeyCache;
@@ -1089,6 +1140,23 @@ declare class WebGpuRenderer {
     private readonly objectMotionHistory;
     private readonly cameraFrustumPlanesScratch;
     private readonly objectTraversalStackScratch;
+    private readonly staticSceneSpatialIndex;
+    private readonly staticMeshDraws;
+    private readonly spatialShadowPlanes;
+    private spatialShadowCount;
+    private readonly spatialLocalShadowSpheres;
+    private spatialLocalShadowCount;
+    private readonly spatialShadowMatrix;
+    private spatialIncludeOffscreen;
+    private spatialCameraLayers;
+    private readonly testSpatialCamera;
+    private readonly testSpatialScene;
+    private readonly filterSpatialCaptureObject;
+    private readonly pushSpatialRoot;
+    private readonly collectSpatialMesh;
+    private readonly isSpatialSphereVisible;
+    private isSpatialShadowSphereVisible;
+    private readonly collectSpatialRoot;
     private readonly shadowDrawsScratch;
     private extractingCaster;
     private readonly cameraDetailHistory;
@@ -1101,6 +1169,10 @@ declare class WebGpuRenderer {
     private readonly temporalVisibilityPreviousCameraPosition;
     private readonly shadowViewProjScratch;
     private extractionVersion;
+    private motionHistoryExtractionVersion;
+    private sceneCaptureOptions;
+    private readonly sceneCaptureDisposers;
+    private readonly captureMotionHistory;
     private graphBuilder;
     private createExtractedDirectionalLightScratch;
     private createExtractedHemisphereLightScratch;
@@ -1174,6 +1246,11 @@ declare class WebGpuRenderer {
     setHiZOcclusionCullingEnabled(enabled: boolean): void;
     getHiZOcclusionCullingEnabled(): boolean;
     getHiZOcclusionCullingActive(): boolean;
+    /** Captures and shadow views must not inherit the primary camera's culling. */
+    private isStaticDrawSetCameraVisible;
+    private getCameraStaticDrawSets;
+    private queryStaticShadowResources;
+    private updateVisibilityWorkload;
     setMultiDrawIndirectEnabled(enabled: boolean): void;
     getMultiDrawIndirectEnabled(): boolean;
     /** Toggle without recompiling materials, for scene-specific GPU comparisons. */
@@ -1186,6 +1263,12 @@ declare class WebGpuRenderer {
     setClearColor(color: readonly [number, number, number, number]): void;
     render(scene: Scene, camera: PerspectiveCamera | OrthographicCamera, timeSeconds?: number): void;
     renderAsync(scene: Scene, camera: PerspectiveCamera | OrthographicCamera, timeSeconds?: number): Promise<void>;
+    /**
+     * Creates an independent canvas or sampleable texture view on the same device.
+     * Call capture between frames, before render(): it reuses extraction scratch and
+     * upload buffers, but never advances gameplay motion/visibility history.
+     */
+    createSceneCapture(canvas: HTMLCanvasElement | null, width?: number, height?: number): RendererSceneCapture;
     compile(scene: Scene, camera: PerspectiveCamera | OrthographicCamera): void;
     compileAsync(scene: Scene, camera: PerspectiveCamera | OrthographicCamera): Promise<void>;
     /**
@@ -1203,6 +1286,8 @@ declare class WebGpuRenderer {
      */
     initTexture(texture: Texture): void;
     createStaticDrawSet(root: Object3D, options?: StaticDrawSetOptions): StaticDrawSet;
+    /** Register immutable ordinary meshes without changing their authored parents. */
+    registerStaticSpatialObject(root: Object3D): StaticSpatialObject;
     private disposeStaticDrawSetResource;
     private renderFrame;
     private recordPresentationOverlay;
@@ -1227,6 +1312,7 @@ declare class WebGpuRenderer {
     private transparentDraws;
     private opaqueBatches;
     private acquireDrawCall;
+    private createDrawCall;
     private acquireOpaqueBatchBuilder;
     private populateDrawCall;
     private populateDynamicDrawCall;
@@ -1236,6 +1322,9 @@ declare class WebGpuRenderer {
     private getToonOutlineMaterial;
     private pushToonOutlineDraw;
     private updateTransparentDrawSortDepths;
+    /** Bounded importance selection; stable light IDs break exact ties. */
+    private selectTransientPointLight;
+    private extractPointLight;
     private extractScene;
     private collectLine;
     /**
@@ -1332,6 +1421,7 @@ declare class WebGpuRenderer {
     private getGeometryAttributeBufferKey;
     private getGeometryAttributeGroupBufferKey;
     private getMaterialVertexAttributes;
+    private getSharedVertexAttributeLayout;
     private getGeometryVertexBuffer;
     private cacheGeometryVertexBufferFast;
     private readonly packedVertexGroups;
@@ -1341,7 +1431,7 @@ declare class WebGpuRenderer {
     private prepareGeometryVertexBuffers;
     private getStandardVertexAttribute;
     private prepareDrawGeometryVertexBuffers;
-    private getDefaultInstanceAttributeBuffer;
+    private getDefaultVertexAttributeBuffer;
     private getMeshExtractionCacheEntry;
     private getInstancedMeshExtractionCacheEntry;
     private getBatchedMeshExtractionCacheEntry;
@@ -1837,6 +1927,8 @@ declare class OutlineEffect {
     edgeThickness: number;
     edgeSoftness: number;
     readonly selectedObjects: Set<Object3D<three.Object3DEventMap>>;
+    private readonly selectionMembers;
+    private readonly addSelectionMember;
     readonly selectedInstances: OutlineInstanceSelection[];
     private readonly targetPrefix;
     private readonly maskMaterial;
@@ -1851,4 +1943,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 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, 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, 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 };