@driftengine/core 4.9.0 → 4.10.0

package/dist/render/backend/webgpu/renderer.d.ts

@@ -25,7 +25,7 @@ import { GpuClothBinding, GpuClothParticles } from './clothTextures.ts';
 import type { ComputeHost } from './computeHost.ts';
 import { type SurfaceOverlay } from '../../surfaceOverlay.ts';
 import type { ClothBindingData } from '../../clothBindingData.ts';
-import type { CompressedTextureFormat, SurfaceSource } from '../../compressedSource.ts';
+import type { CompressedTextureFormat, CompressedTextureSource, SurfaceSource } from '../../compressedSource.ts';
 import { GpuSdfText } from './sdfTextPass.ts';
 import type { SdfFont } from '../../sdfFont.ts';
 import type { SdfTextStyle } from '../../sdfTextLayout.ts';
@@ -47,6 +47,8 @@ import type { MeshData } from '../../mesh.ts';
 import type { ShadowCasters } from '../../shadowCasters.ts';
 import { type GpuMesh } from './buffers.ts';
 import type { GpuSurface } from './device.ts';
+import type { BoneAnimationClip, BoneAnimationHandle } from '../../boneAnimation.ts';
+import type { StaticDrawsHandle } from '../../staticDraws.ts';
 import { type GpuScatter } from './scatterPass.ts';
 import { type GpuWater } from './waterPass.ts';
 import { type GpuPlumes } from './plumePass.ts';
@@ -143,6 +145,8 @@ export declare class WebGPURenderer implements RendererApi {
     private readonly skinnedBindGroupLayout;
     private readonly morphedBindGroupLayout;
     private readonly bothBindGroupLayout;
+    /** The instanced layout of a batch playing a bone animation. See `animatedGroup`. */
+    private readonly animatedBindGroupLayout;
     /** The morph weights the following draws use, or null for none. */
     private morphWeights;
     /**
@@ -156,13 +160,6 @@ export declare class WebGPURenderer implements RendererApi {
      * Keyed by slot instead, the groups are built once and reused for the life of the renderer.
      */
     private readonly skinnedGroups;
-    /** The unskinned group each was built beside, for identity-based invalidation. */
-    private readonly skinnedGroupsBeside;
-    private readonly skinnedGroupsPalette;
-    private readonly skinnedGroupsDeltas;
-    /** The cloth views each skinned twin was built with, compared by identity like the palette. */
-    private readonly skinnedGroupsCloth;
-    private readonly skinnedGroupsClothBinding;
     /** The cloth the next skinned draws are placed by, or null. See `setCloth`. */
     private cloth;
     private clothStandCache;
@@ -230,22 +227,51 @@ export declare class WebGPURenderer implements RendererApi {
     /** Every distinct cache above, so a mesh's pipelines are built for each. One entry when aliased. */
     private readonly pipelineTargets;
     private readonly bindGroupLayout;
-    /** One slot per draw, uploaded once a frame. See `UniformRing`. */
-    private readonly perDraw;
-    /** The lights, fog and camera, settled once per frame by `bindMeshPass`. */
-    private readonly perFrame;
+    /** One slot per draw, uploaded once a frame. See `UniformRing`. Swapped while a static list records. */
+    private perDraw;
     /**
-     * The material block as the CPU holds it, patched by the setters and copied into a slot.
+     * The lights, fog and camera, a slot per mesh pass a frame opens: `bindMeshPass` writes them, and
+     * the first draw after it takes a slot. A ring rather than one buffer because a frame opens more
+     * than one pass — a mirror's, a capture's, a probe face's — and a queue write does not interleave
+     * with the draws recorded between them. See `UniformRing`.
+     */
+    private passRing;
+    /** Each material's block, kept across frames for as long as it does not change. */
+    private readonly materialStore;
+    /**
+     * Both blocks as the CPU holds them, the pass's then the material's, patched by name and copied
+     * into a slot by the next draw after something changed them. See `FlatFragmentScratch`.
      *
      * Authoritative between draws: a setter changes one field here and marks the block dirty, and
-     * the next `drawMesh` takes a slot and copies the whole thing in. That keeps a setter free of
-     * any knowledge of slots, which is what lets it be called anywhere a scene wants.
+     * the next `drawMesh` places it. That keeps a setter free of any knowledge of slots, which is
+     * what lets it be called anywhere a scene wants.
      */
     private readonly perFrameStaging;
     private readonly perFrameFloats;
     private readonly perFrameInts;
+    /** The two halves of the scratch, as the words a slot is written from. */
+    private readonly passInts;
+    private readonly materialInts;
     /** The slot the open material occupies, and whether the next draw must take a new one. */
     private readonly materials;
+    /** The same for the pass's block: reopened by `bindMeshPass` and by nothing a material sets. */
+    private readonly passBlock;
+    /**
+     * The vertex stage's view block — the camera, the light's matrix, the wind — a slot a pass, and a
+     * second, unjittered, for a blended draw landing after the upscale. Reopened with the pass, and by
+     * `setWind` and `beginShadowPass`, which change what it holds.
+     */
+    private viewRing;
+    private readonly viewBlock;
+    private readonly lateViewBlock;
+    /** The view slot the draw being submitted bound, read by the halves it keeps for later passes. */
+    private drawViewOffset;
+    /** Pass slots asked for and refused this frame, and materials refused: what grows the two. */
+    private passesAsked;
+    private passesRefused;
+    private viewsAsked;
+    private viewsRefused;
+    private materialsRefused;
     /**
      * What this frame asked for against the ceilings above, reported rather than only warned about.
      *
@@ -453,7 +479,7 @@ export declare class WebGPURenderer implements RendererApi {
     private readonly variant;
     /** Whether this profile compiled the point-shadow path, and so has sentinels to write. */
     private readonly pointShadowsCompiled;
-    /** What the generator recorded about that permutation: sizes, offsets and bindings. */
+    /** What the generator recorded about that permutation, as the renderer's scratch lays it out. */
     private readonly fragment;
     private depth;
     private depthView;
@@ -1181,7 +1207,7 @@ export declare class WebGPURenderer implements RendererApi {
      * ones that move something *every* group holds: the shadow cubemaps, the probe fence, the cookie
      * atlas and the IES rows. None of those is a frame path.
      */
-    private readonly flatBindGroups;
+    private flatBindGroups;
     /** The group holding the one-pixel stand-in, for every draw with no texture set. */
     private blankAlbedoBindGroup;
     /** Repeats across the mesh's own UV range. Per draw, because `uUvScale` is a vertex uniform. */
@@ -1238,7 +1264,7 @@ export declare class WebGPURenderer implements RendererApi {
      * opens is submitted by the time the next one begins.
      */
     private readonly retiredTextures;
-    updateSurfaceTexture(texture: GpuSurfaceTexture, source: TexImageSource): void;
+    updateSurfaceTexture(texture: GpuSurfaceTexture, source: TexImageSource | CompressedTextureSource): void;
     disposeSurfaceTexture(texture: GpuSurfaceTexture): void;
     /**
      * Drop every bind group that may hold `texture`'s view, and rebuild the ones bound now.
@@ -1352,6 +1378,16 @@ export declare class WebGPURenderer implements RendererApi {
     setSurfaceReflectivity(amount: number): void;
     /** How bright the environment the surfaces drawn next reflect is. See `renderer.ts`. */
     setEnvironmentGain(gain: number): void;
+    /**
+     * The reflectivity and environment gain the setters gave the pass, and the ones the material
+     * set now states, or null where it states none (`SurfaceMaterial.reflectivity`). A draw wears the
+     * material's where it has one and the pass's otherwise, the rule `renderer.ts` keeps too.
+     */
+    private passReflectivity;
+    private passEnvironmentGain;
+    private materialReflectivity;
+    private materialEnvironmentGain;
+    private writeEnvironmentDials;
     setSurfaceGrain(amount: number): void;
     /** Whether the surfaces drawn next meet the medium. See `renderer.ts`. */
     setSurfaceFog(enabled: boolean): void;
@@ -1818,14 +1854,6 @@ export declare class WebGPURenderer implements RendererApi {
      * its own two programs.
      */
     private writeShadowWind;
-    /**
-     * The five wind fields of one per-draw slot.
-     *
-     * **Never called for an instanced draw.** That variant declares none of these, and
-     * `flatPass.ts` records what writing a field a variant does not declare costs: the block is
-     * shorter, so the write lands on whatever occupies that offset instead.
-     */
-    private writeWind;
     /** Refilled per frame rather than allocated; see `resolvePointLights`. */
     private readonly lights;
     /** The fixed arm's rectangles as `uAreaLightSize` holds them. See `packAreaSizesAndDoors`. */
@@ -1945,6 +1973,9 @@ export declare class WebGPURenderer implements RendererApi {
      * at submit, and a texture's view is new when an update changes its size.
      */
     private readonly shadowCutoutLayout;
+    /** A crowd's casters: the plain and cutout layouts with a bone animation's three textures. */
+    private readonly shadowAnimatedLayout;
+    private readonly shadowAnimatedCutoutLayout;
     private readonly cutoutGroups;
     private readonly cutoutPeelGroups;
     private shadowPeelPassUniforms;
@@ -2267,6 +2298,21 @@ export declare class WebGPURenderer implements RendererApi {
      * can do nothing about. Done with `complete` still false is the signal that it was abandoned.
      */
     createMeshIncremental(given: MeshData, options?: MeshOptions): IncrementalMeshHandle;
+    /**
+     * The copies this frame's mesh rewrites owe (`StagedRewrite`), recorded since the last submit and
+     * sent at the head of the next one: one encoder however many meshes are rewritten. Null while
+     * nothing is owed.
+     */
+    private pendingRewrites;
+    /** One record handed to every staged rewrite, refilled each call, so a rewrite allocates nothing. */
+    private readonly stagedRewrite;
+    private rewriteCopies;
+    /**
+     * Submit `buffers`, led by any copies the frame's mesh rewrites owe. **Every submit of this
+     * renderer goes through here**, because any of them may draw a rewritten mesh — the frame's own,
+     * a mirror's, a shadow's, a probe's — and the copies must be ahead of the first that does.
+     */
+    private submit;
     /**
      * Rewrite a mesh's positions, and its normals where the caller has them.
      *
@@ -2285,15 +2331,34 @@ export declare class WebGPURenderer implements RendererApi {
      */
     bindMeshPass(camera: Camera, env: Environment): void;
     /**
-     * The slot the next draw's material lives in, taking a new one when something dirtied it.
+     * The slot the next draw's material lives in, placing it when something dirtied it, with the
+     * pass's slot taken first where `bindMeshPass` reopened it: `passOffset` is that one's offset.
      *
-     * **A copy per material change, not per draw.** A scene drawing a hundred meshes of one
-     * material spends one slot and one copy; a scene switching material every draw spends one
-     * each, which is what it asked for.
+     * **A placement per material change, not per draw.** A scene drawing a hundred meshes of one
+     * material places it once; a scene switching material every draw places one each, and a material
+     * the store already holds — the same numbers as a draw before it, this frame or an earlier one —
+     * is bound where it is and uploads nothing.
      */
     private materialSlotForDraw;
+    /** The pass slot `materialSlotForDraw` left open, read beside the material's by every lit draw. */
+    private get passOffset();
+    /** A new pass: its block, and both its views, are taken afresh by the next draw. */
+    private reopenPass;
+    /** What a view holds changed — the wind, the light's matrix — so the next draw takes a new one. */
+    private reopenViews;
+    /**
+     * The view slot a lit draw reads its camera from: the pass's, or its unjittered twin for a blended
+     * draw landing after the upscale. Taken by the first draw that needs it after the pass, the wind or
+     * the light's matrix changed, and shared by every draw until then. Null when the ring is full, which
+     * skips the draw and grows the ring for the next frame, as the pass ring does.
+     */
+    private viewSlotFor;
+    /** A view block: the camera, the light's matrix and the frame's wind, into `ring` at `slot`. */
+    private writeView;
+    private warnMaterialsFull;
     /** Said once rather than every frame, for the reason `warnedFull` gives. */
     private warnedMaterialsFull;
+    private warnedPassesFull;
     private warnedSkyFull;
     private warnedParticlesTwice;
     /**
@@ -2407,6 +2472,26 @@ export declare class WebGPURenderer implements RendererApi {
      * the shape this repository spent a week removing.
      */
     createInstanced(mesh: GpuMesh, capacity: number, options?: InstancedOptions): GpuInstancedBatch;
+    /** See `Renderer.setAnimationTime`. Every view taken after it reads the new clock. */
+    setAnimationTime(seconds: number): void;
+    /** The clock `setAnimationTime` set, 0 until it is. */
+    private animationTime;
+    /** See `Renderer.createBoneAnimation`. */
+    createBoneAnimation(clip: BoneAnimationClip): BoneAnimationHandle;
+    /** See `Renderer.disposeBoneAnimation`. A batch still playing it draws nothing after. */
+    disposeBoneAnimation(animation: BoneAnimationHandle): void;
+    /** An animated batch's clip and clocks, as its groups bind them. */
+    private animationViews;
+    /** An animated batch's groups, dropped wherever the renderer drops its own. */
+    private freshAnimatedGroups;
+    /**
+     * The lit group an animated batch draws with: the material's group, or its overlay twin, again
+     * with the clip's and the clocks' textures — kept on the batch by the group it was built beside,
+     * as a skinned twin is kept by its palette slot.
+     */
+    private animatedGroup;
+    /** An animated caster's shadow group, by what it cuts with and whether this is the peel. */
+    private animatedDepthGroup;
     /** The device instance culls, built on the first culling draw. See `InstanceCullPass`. */
     private instanceCulls;
     /** Counts frames, so a batch knows when its cull slots were last taken. */
@@ -2527,6 +2612,38 @@ export declare class WebGPURenderer implements RendererApi {
      * face. What it replaces is a consumer re-entering its whole draw path with a second camera.
      */
     drawSceneCasters(casters: ShadowCasters): void;
+    /** See `Renderer.createStaticDraws`. Recorded on its first draw, into each view it is drawn in. */
+    createStaticDraws(casters: ShadowCasters): StaticDrawsHandle;
+    /**
+     * See `Renderer.drawStaticDraws`. One bundle executed, after a pass block and a view block are
+     * written for this view; the list is recorded first where it has no recording that is current for
+     * this target and starting state. See `staticBundles.ts`.
+     */
+    drawStaticDraws(draws: StaticDrawsHandle): void;
+    /** A list drawn the way `drawSceneCasters` draws, a draw at a time, for where a bundle cannot be. */
+    private replayStaticImmediately;
+    /** See `Renderer.disposeStaticDraws`. Its pins let go; its meshes and materials are the caller's. */
+    disposeStaticDraws(draws: StaticDrawsHandle): void;
+    /** The recording to replay `list` from here, made now if none is current; null if it cannot be. */
+    private staticRecordingFor;
+    /** How a list's pins are let go: through the store, unless it has forgotten them since. */
+    private unpinFor;
+    /**
+     * Record `list` into `recording`: its entries through the scene-caster path, with the list's
+     * rings and group cache swapped in for the frame's and the pass and view slots held at the list's
+     * first copy, so every command the path records binds the list's buffers and offsets the bundle
+     * can rewrite per copy. Everything swapped is put back, whatever the path throws.
+     */
+    private recordStatic;
+    /** The recording under way, which `recordDraw` and the side passes take their commands into. */
+    private staticRecording;
+    /** Whether the replay about to count its material changes recorded them, and so counted them. */
+    private staticJustRecorded;
+    /** A disposed list drawn, said once: the frame loop does not throw. */
+    private warnStaticDisposed;
+    private warnedStaticDisposed;
+    /** Bumped wherever the lit groups are dropped, which a static list's own groups follow. */
+    private flatGroupEpoch;
     drawShadowCasters(casters: ShadowCasters): void;
     /** Close the shadow pass and submit it, so the frame can sample what it wrote. */
     /**
@@ -2673,11 +2790,11 @@ export declare class WebGPURenderer implements RendererApi {
     /**
      * The bind group a draw uses, skinned or not.
      *
-     * **The skinned twin is cached against the two things that can invalidate it**, rather than
-     * against a flag somebody has to remember to clear at six call sites: the unskinned group it was
-     * built beside — which is rebuilt whenever the material or a shadow slot moves — and the palette
-     * view, which changes only when the texture is reallocated. Comparing object identity means a
-     * missed invalidation is not possible rather than merely unlikely, and it is why
+     * **The skinned twin is kept by palette slot and by the unskinned group it was built beside**,
+     * which is one a material, and compared against the views it holds — the palette's, which
+     * changes only when the slot's texture grows, the morph deltas and the cloth's — rather than
+     * against a flag somebody has to remember to clear at six call sites. Comparing object identity
+     * means a missed invalidation is not possible rather than merely unlikely, and it is why
      * `SkinPaletteTexture.view()` caches: a fresh view every call never compares equal and would
      * rebuild this every draw.
      */