@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 +34 -0
- package/dist/index.d.ts +45 -3
- package/dist/index.js +1 -1
- package/package.json +8 -2
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
|
-
|
|
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
|
-
|
|
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 };
|