@hology/webgpu-renderer 0.1.24 → 0.1.26

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -196,6 +196,31 @@ membership, geometry, materials, and visibility are frozen; dispose and recreate
196
196
  the set after changing any of those properties. Material uniforms and textures
197
197
  remain live.
198
198
 
199
+ Skinned meshes retain renderer-owned body and outline draw records. Their transforms
200
+ and motion history occupy stable slots in shared resident instance-buffer pages
201
+ (128 slots per page), independent of traversal order, visibility, and dynamic
202
+ batching. Mesh parts and outlines use the same slot. Adding characters allocates
203
+ another page rather than resizing an existing page or moving its live slots.
204
+ Changed transforms upload a coalesced dirty range per page; unchanged slots do
205
+ not upload. Material adapters and geometry validation remain live so ordinary
206
+ Three.js edits still work. Structural draw changes refresh the retained records.
207
+
208
+ Model-instance disposal releases the slots through the external-palette lifecycle;
209
+ geometry disposal and renderer destruction also release them. Hiding or removing
210
+ a model from a scene retains its slots for reuse when it returns. Slot identity is
211
+ renderer-owned and independent of the animation worker's pose/batch indices.
212
+ This is preparation for skinned render bundles and instancing; skinned draws still
213
+ use the direct submission path. Skeleton palettes now occupy aligned ranges in
214
+ shared current/previous GPU pages, with coalesced dirty uploads per page. Fixed
215
+ pages keep live buffer bindings stable as characters spawn and despawn. Custom
216
+ compute passes can request a subrange through `getSkeletonBoneBinding`; the older
217
+ `getSkeletonBoneBuffer` API uses a lazy offset-zero compatibility copy.
218
+
219
+ Material preparation caches skinning eligibility and GI capability by shader
220
+ structure, prepares uniform-copy plans once, and resolves outline variants once
221
+ per extraction. Live texture/uniform edits remain supported; source material
222
+ version changes rebuild derived outlines.
223
+
199
224
  MSAA is currently disabled by default. You can enable it with:
200
225
 
201
226
  ```ts
@@ -451,6 +476,15 @@ Directional shadows use independent light-space sphere tests over the complete c
451
476
  Profiling now includes per-pass `triangleCount` and `drawCallCount`. Indirect submission counters remain **upper bounds**, since the CPU records registered draw capacity; they include repeated depth/color/shadow submissions. `visibility.visibleTriangles` reads actual index/instance counts from the camera's indirect arguments and represents one GPU-culled camera submission, excluding direct and transparent draws. Directional shadow run counts are exact. GPU profiling readback is diagnostic only, never needed for culling.
452
477
 
453
478
 
479
+ ### Skinned model lifetime
480
+
481
+ `ModelInstance.dispose()` releases per-mesh renderer caches for both animation
482
+ backends. Custom model owners should call `disposeSkinnedMeshResources(mesh)` for
483
+ each despawned skinned mesh. This releases resident draw records, skin uniforms
484
+ and unused palette allocations without disposing shared geometry or materials.
485
+ Removing a mesh from a scene alone retains its caches for reuse. A mesh can be
486
+ rendered again after resource release; its renderer resources are recreated.
487
+
454
488
  ### Cached directional shadow updates
455
489
 
456
490
  Temporal shadow scheduling is opt-in. Configure the renderer with `directionalShadowUpdates`, or call `setDirectionalShadowUpdateOptions`. Hology exposes the same method on `RenderingView`.
package/dist/index.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  import * as three from 'three';
2
- import { Object3D, Color, Vector2, Vector3, Vector4, Matrix3, Matrix4, Material, Texture, MaterialParameters, PerspectiveCamera, OrthographicCamera, BufferGeometry, DirectionalLight, PointLight, SpotLight, Scene, Camera } from 'three';
2
+ import { Object3D, Color, Vector2, Vector3, Vector4, Matrix3, Matrix4, Material, Texture, MaterialParameters, PerspectiveCamera, OrthographicCamera, BufferGeometry, DirectionalLight, PointLight, SpotLight, Scene, Camera, Skeleton, SkinnedMesh } from 'three';
3
3
  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';
4
4
 
5
5
  interface PipelineDiagnosticOrigin {
@@ -280,6 +280,8 @@ interface RendererOptions {
280
280
  invokeObjectRenderCallbacks?: boolean;
281
281
  }
282
282
  interface StaticDrawSetOptions {
283
+ /** Retain source instance IDs for explicit transform/visibility refreshes. Topology stays fixed. */
284
+ mutableTransforms?: boolean;
283
285
  /** Defaults inherited by objects without overrides. Frozen at registration. */
284
286
  detailCulling?: DetailCullingSettings;
285
287
  label?: string;
@@ -296,6 +298,8 @@ interface StaticDrawSet {
296
298
  readonly drawCount: number;
297
299
  readonly instanceCount: number;
298
300
  enabled: boolean;
301
+ /** Refresh resident transforms/instance visibility. Requires mutableTransforms; topology stays fixed. */
302
+ updateTransforms(): void;
299
303
  dispose(): void;
300
304
  }
301
305
  interface RendererGraphBuilderContext {
@@ -384,10 +388,15 @@ interface RendererSceneCapturePostProcessContext {
384
388
  }
385
389
  /** Non-temporal, unshadowed scene view sharing the renderer's GPU resources. */
386
390
  interface RendererSceneCapture {
391
+ /** Display-space output format, for preparing a custom postProcess pipeline. */
392
+ readonly format: GPUTextureFormat;
387
393
  /** Triangles submitted by the most recent capture, before raster clipping. */
388
394
  readonly triangleCount: number;
389
395
  /** Persistent display-space output when created without a canvas. Owned by the capture. */
390
396
  readonly textureView?: GPUTextureView;
397
+ /** Prepare this view's material variants without blocking on synchronous pipeline creation.
398
+ * Does not submit a capture or prepare a custom postProcess callback. */
399
+ prepareAsync(scene: three.Scene, camera: PerspectiveCamera | OrthographicCamera, options?: RendererSceneCaptureOptions): Promise<void>;
391
400
  capture(scene: three.Scene, camera: PerspectiveCamera | OrthographicCamera, options?: RendererSceneCaptureOptions): void;
392
401
  dispose(): void;
393
402
  }
@@ -430,6 +439,8 @@ interface RendererCustomPassContext {
430
439
  getGeometryVertexBuffer(geometry: BufferGeometry, attribute: "position" | "normal"): GPUBuffer;
431
440
  /** Shared current bone-world * inverse-bind palette; renderer owns its lifetime. */
432
441
  getSkeletonBoneBuffer(skeleton: three.Skeleton): GPUBuffer;
442
+ /** Shared page subrange; prefer this over the offset-zero compatibility buffer. */
443
+ getSkeletonBoneBinding?(skeleton: three.Skeleton): GPUBufferBinding;
433
444
  getColorFormat(name: string): GPUTextureFormat;
434
445
  getShadowMapDebugInfo(): RendererShadowMapDebugInfo;
435
446
  /** Shared light uniforms and shadow arrays used by the forward renderer. */
@@ -850,6 +861,7 @@ declare class SDFGI {
850
861
  private pendingTriangleCount;
851
862
  private pendingCounts;
852
863
  private readonly configured;
864
+ private readonly materialCapabilities;
853
865
  private readonly watched;
854
866
  private readonly lights;
855
867
  private readonly staticDrawRoots;
@@ -893,7 +905,8 @@ declare class SDFGI {
893
905
  /** Capture one all-layer projection per frame, before main-view extraction. */
894
906
  prepare(scene: Scene, camera: Camera): void;
895
907
  private updateLights;
896
- addPasses(graph: FrameGraphBuilder): void;
908
+ /** Returns whether the update pass was added, for dependent material passes. */
909
+ addPasses(graph: FrameGraphBuilder): boolean;
897
910
  /** Records the same production path used by the renderer; useful to GPU checks. */
898
911
  encode(encoder: GPUCommandEncoder, timeSeconds?: number): void;
899
912
  private encodeVolume;
@@ -982,6 +995,7 @@ declare class WebGpuRenderer {
982
995
  private readonly repeatedInstanceResources;
983
996
  private readonly instancedMeshExtractionCache;
984
997
  private readonly batchedMeshExtractionCache;
998
+ private readonly materialUniformData;
985
999
  private readonly materialCache;
986
1000
  private readonly skinnedMaterialCache;
987
1001
  private readonly materialCacheVisible;
@@ -1174,9 +1188,14 @@ declare class WebGpuRenderer {
1174
1188
  private createExtractedPointLightScratch;
1175
1189
  private createExtractedSpotLightScratch;
1176
1190
  private readonly skinnedDrawKeys;
1191
+ private readonly skinnedInstanceSlots;
1192
+ private readonly skinnedRenderRecords;
1193
+ private skinningPaletteArena;
1177
1194
  private readonly skeletonPalettes;
1178
1195
  private readonly getSkeletonBoneBufferForPass;
1196
+ private readonly getSkeletonBoneBindingForPass;
1179
1197
  private readonly outlineResolvedFrameCache;
1198
+ private readonly preparedOutlineFrameCache;
1180
1199
  private opaqueSortMs;
1181
1200
  private readonly opaqueSortSamples;
1182
1201
  private opaqueSortSampleIndex;
@@ -1266,8 +1285,10 @@ declare class WebGpuRenderer {
1266
1285
  * upload buffers, but never advances gameplay motion/visibility history.
1267
1286
  */
1268
1287
  createSceneCapture(canvas: HTMLCanvasElement | null, width?: number, height?: number): RendererSceneCapture;
1288
+ private prepareSceneCaptureAsync;
1269
1289
  compile(scene: Scene, camera: PerspectiveCamera | OrthographicCamera): void;
1270
1290
  compileAsync(scene: Scene, camera: PerspectiveCamera | OrthographicCamera): Promise<void>;
1291
+ prepareSceneGeometryAsync(scene: Scene, camera: Camera): Promise<void>;
1271
1292
  /**
1272
1293
  * Creates a Three-compatible CubeUV PMREM generator. Its output is a
1273
1294
  * HalfFloat Texture and can be assigned directly to a graph material's
@@ -1288,6 +1309,8 @@ declare class WebGpuRenderer {
1288
1309
  private disposeStaticDrawSetResource;
1289
1310
  private renderFrame;
1290
1311
  private recordPresentationOverlay;
1312
+ /** Present application UI without changing scene extraction, pipelines or temporal history. */
1313
+ renderPresentationOnly(): void;
1291
1314
  destroy(): void;
1292
1315
  private createStaticPipelines;
1293
1316
  private ensureTransmissionSnapshot;
@@ -1317,6 +1340,7 @@ declare class WebGpuRenderer {
1317
1340
  private pushDraw;
1318
1341
  private getToonOutlineParameters;
1319
1342
  private getToonOutlineMaterial;
1343
+ private prepareToonOutlineMaterial;
1320
1344
  private pushToonOutlineDraw;
1321
1345
  private updateTransparentDrawSortDepths;
1322
1346
  /** Bounded importance selection; stable light IDs break exact ties. */
@@ -1338,6 +1362,9 @@ declare class WebGpuRenderer {
1338
1362
  private collectMesh;
1339
1363
  private prepareSceneForCompilation;
1340
1364
  private collectInstancedMesh;
1365
+ private getSkinnedRenderRecord;
1366
+ private releaseSkinnedRenderRecord;
1367
+ private releaseSkinnedMeshResources;
1341
1368
  private collectSkinnedMesh;
1342
1369
  private collectBatchedMesh;
1343
1370
  private uploadInstanceData;
@@ -1400,6 +1427,7 @@ declare class WebGpuRenderer {
1400
1427
  private updateDynamicGeometryAttributes;
1401
1428
  private getSkinnedGeometryResource;
1402
1429
  private getSkinningPalette;
1430
+ private releaseSkinningPalette;
1403
1431
  private refreshSkinningPalette;
1404
1432
  private refreshSkinningBindMatrices;
1405
1433
  private uploadSkinningPalette;
@@ -2145,4 +2173,18 @@ declare class OutlineEffect {
2145
2173
  dispose(): void;
2146
2174
  }
2147
2175
 
2148
- 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 };
2176
+ /** Published on the render thread, after a complete animation frame is acquired. */
2177
+ interface ExternalSkeletonPalette {
2178
+ /** Monotonically increasing publication counter; matrices are ordinary CPU memory. */
2179
+ version: number;
2180
+ /** Palettes and attachment transforms are relative to this object. */
2181
+ root: Object3D;
2182
+ }
2183
+ declare function disposeExternalSkeletonPalette(source: ExternalSkeletonPalette): void;
2184
+ /** The producer owns skeleton.boneMatrices until unregistered. WebGPU only uploads it. */
2185
+ declare function setExternalSkeletonPalette(skeleton: Skeleton, source: ExternalSkeletonPalette | null): void;
2186
+
2187
+ /** Release renderer caches for a despawned mesh without disposing shared geometry or materials. */
2188
+ declare function disposeSkinnedMeshResources(mesh: SkinnedMesh): void;
2189
+
2190
+ 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 ExternalSkeletonPalette, 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, disposeExternalSkeletonPalette, disposeSkinnedMeshResources, registerPipelineDiagnosticOrigin, resolveDetailCulling, setExternalSkeletonPalette, setObjectDetailCulling, setPipelineDiagnosticLoading };