@hology/webgpu-renderer 0.1.25 → 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 {
@@ -439,6 +439,8 @@ interface RendererCustomPassContext {
439
439
  getGeometryVertexBuffer(geometry: BufferGeometry, attribute: "position" | "normal"): GPUBuffer;
440
440
  /** Shared current bone-world * inverse-bind palette; renderer owns its lifetime. */
441
441
  getSkeletonBoneBuffer(skeleton: three.Skeleton): GPUBuffer;
442
+ /** Shared page subrange; prefer this over the offset-zero compatibility buffer. */
443
+ getSkeletonBoneBinding?(skeleton: three.Skeleton): GPUBufferBinding;
442
444
  getColorFormat(name: string): GPUTextureFormat;
443
445
  getShadowMapDebugInfo(): RendererShadowMapDebugInfo;
444
446
  /** Shared light uniforms and shadow arrays used by the forward renderer. */
@@ -859,6 +861,7 @@ declare class SDFGI {
859
861
  private pendingTriangleCount;
860
862
  private pendingCounts;
861
863
  private readonly configured;
864
+ private readonly materialCapabilities;
862
865
  private readonly watched;
863
866
  private readonly lights;
864
867
  private readonly staticDrawRoots;
@@ -992,6 +995,7 @@ declare class WebGpuRenderer {
992
995
  private readonly repeatedInstanceResources;
993
996
  private readonly instancedMeshExtractionCache;
994
997
  private readonly batchedMeshExtractionCache;
998
+ private readonly materialUniformData;
995
999
  private readonly materialCache;
996
1000
  private readonly skinnedMaterialCache;
997
1001
  private readonly materialCacheVisible;
@@ -1184,9 +1188,14 @@ declare class WebGpuRenderer {
1184
1188
  private createExtractedPointLightScratch;
1185
1189
  private createExtractedSpotLightScratch;
1186
1190
  private readonly skinnedDrawKeys;
1191
+ private readonly skinnedInstanceSlots;
1192
+ private readonly skinnedRenderRecords;
1193
+ private skinningPaletteArena;
1187
1194
  private readonly skeletonPalettes;
1188
1195
  private readonly getSkeletonBoneBufferForPass;
1196
+ private readonly getSkeletonBoneBindingForPass;
1189
1197
  private readonly outlineResolvedFrameCache;
1198
+ private readonly preparedOutlineFrameCache;
1190
1199
  private opaqueSortMs;
1191
1200
  private readonly opaqueSortSamples;
1192
1201
  private opaqueSortSampleIndex;
@@ -1331,6 +1340,7 @@ declare class WebGpuRenderer {
1331
1340
  private pushDraw;
1332
1341
  private getToonOutlineParameters;
1333
1342
  private getToonOutlineMaterial;
1343
+ private prepareToonOutlineMaterial;
1334
1344
  private pushToonOutlineDraw;
1335
1345
  private updateTransparentDrawSortDepths;
1336
1346
  /** Bounded importance selection; stable light IDs break exact ties. */
@@ -1352,6 +1362,9 @@ declare class WebGpuRenderer {
1352
1362
  private collectMesh;
1353
1363
  private prepareSceneForCompilation;
1354
1364
  private collectInstancedMesh;
1365
+ private getSkinnedRenderRecord;
1366
+ private releaseSkinnedRenderRecord;
1367
+ private releaseSkinnedMeshResources;
1355
1368
  private collectSkinnedMesh;
1356
1369
  private collectBatchedMesh;
1357
1370
  private uploadInstanceData;
@@ -1414,6 +1427,7 @@ declare class WebGpuRenderer {
1414
1427
  private updateDynamicGeometryAttributes;
1415
1428
  private getSkinnedGeometryResource;
1416
1429
  private getSkinningPalette;
1430
+ private releaseSkinningPalette;
1417
1431
  private refreshSkinningPalette;
1418
1432
  private refreshSkinningBindMatrices;
1419
1433
  private uploadSkinningPalette;
@@ -2159,4 +2173,18 @@ declare class OutlineEffect {
2159
2173
  dispose(): void;
2160
2174
  }
2161
2175
 
2162
- 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 };