@driftengine/core 4.4.1 → 4.5.0

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

@@ -1,5 +1,6 @@
 import type { ProbeBakeOptions } from '../../reflectionProbe.ts';
 import type { ReadonlyMat4 } from 'gl-matrix';
+import type { Mover } from '../../recon/mover.ts';
 import type { Vec3 } from '../../../math/color.ts';
 import { Camera } from '../../camera.ts';
 import type { PickHit, PickableSource } from '../../pickable.ts';
@@ -156,6 +157,8 @@ export declare class WebGPURenderer implements RendererApi {
      * caller who passed null gets — rather than reading a slot this frame has already re-let.
      */
     private skinPaletteSlot;
+    /** The palette `skinPaletteSlot` was uploaded from, for a skinned mover to copy. See `Mover`. */
+    private skinPaletteData;
     private readonly surface;
     /** The encoder for the frame in flight, or null between frames. */
     private encoder;
@@ -163,6 +166,27 @@ export declare class WebGPURenderer implements RendererApi {
     private readonly meshPresent;
     private pass;
     private readonly pipelines;
+    /**
+     * The pipelines a reconstructing frame's blended draws are built for: the reconstructed picture's
+     * format at one sample, which is where `LatePass` draws them. Aliased to `pipelines` when the
+     * world already lands on exactly that, as `overlayPipelines` is.
+     */
+    private readonly latePipelines;
+    /** The blended draws of a reconstructing frame, drawn after the upscale. See `LatePass`. */
+    private latePass;
+    /** A late draw asked to refract: `runLate` copies the reconstructed picture before replaying. */
+    private lateRefractWanted;
+    /** The refraction copy's mip chain, recorded after each copy: what frosted glass reads. */
+    private refractMips;
+    /**
+     * The refraction copy's sampler: filtering, and **between levels as well**, so a frosted pane's
+     * level falls smoothly between two blurs rather than stepping from one to the next.
+     */
+    private refractSampler;
+    /** One glass resolution reused by every draw, so a pane allocates nothing. See `glass.ts`. */
+    private readonly glassScratch;
+    /** `issueCommand` bound once, so the late replay allocates no closure per frame. */
+    private readonly issueBound;
     /**
      * The same pipelines again, built for the canvas, for anything drawn after `endFrame`.
      *
@@ -596,6 +620,16 @@ export declare class WebGPURenderer implements RendererApi {
     private taaUniforms;
     private taaTextures;
     private taaViews;
+    /** Each pixel's flicker record, paired with the history and swapped with it: see `temporalAa.ts`. */
+    private taaRecords;
+    private taaRecordViews;
+    /** The rest of each pixel's record — depth, pull and recent swing — beside the first. */
+    private taaMotions;
+    private taaMotionViews;
+    /** The resolve's depth-to-metres row, from the inverse of `frameProjection`. */
+    private readonly taaInvProjection;
+    /** The resolve's two targets, the picture and the record, held for the pipeline cache's sake. */
+    private taaTargets;
     /** Group `i` reads history `i` and the pass writes into the other one. */
     private taaBindGroups;
     private taaWrite;
@@ -630,10 +664,10 @@ export declare class WebGPURenderer implements RendererApi {
      * the *unsharpened* result — sharpening into the history would sharpen a sharpened picture every
      * frame, which is the halo the reference's own clamp exists to prevent, compounded.
      *
-     * The motion target is render size and carries a drawn object's own motion where something wrote
-     * one. **Nothing writes it yet**, so it is cleared every frame and every pixel takes the camera's
-     * motion, which the resolve derives from the depth and the reprojection. Static geometry is
-     * exact that way and a moving object ghosts until the motion pass lands.
+     * The motion target is render size and carries a drawn object's own motion where the motion pass
+     * wrote one — a draw that named its mover, or passed last frame's matrix. Every other texel is
+     * cleared, and the resolve takes the camera's motion there, derived from the depth and the
+     * reprojection: exact for anything that did not move. See `MotionPass`.
      */
     private reconHistories;
     private reconHistoryViews;
@@ -655,34 +689,15 @@ export declare class WebGPURenderer implements RendererApi {
     private reconGroups;
     private reconSharpenGroups;
     private reconRushGroup;
-    /**
-     * What the motion pass will draw, recorded by `drawMesh` and spent once a frame.
-     *
-     * A parallel array of meshes and one flat matrix buffer rather than an array of objects, because
-     * this is written on the frame's hot path and the house rule about allocating there binds it: the
-     * matrices are copied into a buffer that only ever grows, and the count is what resets.
-     */
-    private readonly motionMeshes;
-    private motionMatrices;
-    private motionCount;
-    private motionLayout;
-    /**
-     * One pipeline per vertex stride, because a stride is a property of the *mesh*.
-     *
-     * Which optional attributes a mesh supplied decides how far apart its positions are, and this
-     * pass reads nothing but positions — so two meshes drawn by the same shader still need two
-     * vertex layouts. A map rather than a cache key on the pipeline cache: there is one shader here
-     * and a handful of strides in any scene.
-     */
-    private readonly motionPipelines;
-    private motionModule;
-    private motionPipelineLayout;
-    private motionFrameBuffer;
-    private motionDrawBuffer;
-    private motionDrawCapacity;
-    private motionGroup;
-    private readonly motionFrameStaging;
-    private motionDrawStaging;
+    /** The motion pass, made with the reconstruction's targets. See `MotionPass`. */
+    private motionPass;
+    /** This renderer's identity to a `Mover`. See `claimRendererId`. */
+    private readonly moverRenderer;
+    /** Frames begun, so a mover can tell last frame from any other. Advanced in `beginFrame`. */
+    private moverFrame;
+    /** Between `beginFrame` and `endFrame`. A change outside it is the next frame's. */
+    private inFrame;
+    private warnedMoverTwice;
     /** The scene's own clip transform with the generated shaders' y negation folded in. */
     private readonly motionRaster;
     private reconSizeKey;
@@ -1587,8 +1602,39 @@ export declare class WebGPURenderer implements RendererApi {
     private readonly sdfTextVerts;
     private readonly sdfTextFrags;
     private readonly sdfTextBindGroups;
-    private readonly shadowMap;
-    private readonly shadowView;
+    /**
+     * The sun's static, moving and peeled maps, as layers of one texture (`shadowMap.ts`). The three
+     * views below are single layers, what each pass attaches; the two here are what is sampled.
+     */
+    private sunShadowTexture;
+    /** Every layer, for the lit pass, the light volumes and the medium. */
+    private sunArrayView;
+    /**
+     * The static layer alone, as an array, for the peel: it draws into another layer of the same
+     * texture, and a view covering that layer too would put it in two usages in one pass.
+     */
+    private sunStaticArrayView;
+    /** How many layers the sun's texture holds: its maps, and the two glass layers once glass casts. */
+    private sunLayerCount;
+    /** The glass depth layers, static then moving, once glass has cast. See `growSunForGlass`. */
+    private sunGlassViews;
+    /** The texture a growth replaced, destroyed once the encoder that copied out of it is submitted. */
+    private retiredSunTexture;
+    /** What the sun's light keeps through glass: two `rgba8unorm` layers, made when glass first casts. */
+    private sunTint;
+    /** The tint pass's layouts, per-draw block, groups and pipelines, made when glass first casts. */
+    private glassTint;
+    /** The tint pass open while the glass list is replayed into it. */
+    private tintPass;
+    /** True while the glass list is replayed into a glass depth layer through `casterSink`. */
+    private drawingGlassDepth;
+    /** Whether the open sun pass is the movers' layer, whose glass goes to the moving glass layer. */
+    private shadowLayerIsDynamic;
+    /** The glass tints' sampler: filtering, and between levels, for frost's coarser reads. */
+    private readonly tintSampler;
+    /** The light a tint pass is drawn for: xyz a direction (w 0) or a position (w 1). */
+    private readonly glassLight;
+    private shadowView;
     private readonly shadowLayout;
     /** The same layout plus the joint palette. See `createDepthBindGroupLayout`. */
     private readonly shadowSkinnedLayout;
@@ -1614,8 +1660,7 @@ export declare class WebGPURenderer implements RendererApi {
      * read twice — so a profile that switches peeling off gets no map and no pass on either
      * backend rather than a map nothing writes.
      */
-    private readonly peelMap;
-    private readonly peelView;
+    private peelView;
     /**
      * The movers' own layer: the character, the rope it swings on, and anything else that walks.
      *
@@ -1636,10 +1681,9 @@ export declare class WebGPURenderer implements RendererApi {
      * and therefore as lit — so nothing looked broken, only empty, which is why it survived the
      * port and every gate in it.
      */
-    private readonly dynamicMap;
-    private readonly dynamicView;
+    private dynamicView;
     /** The peel's own bind groups: `uPeelShadowLayer` at 1, and the static map to peel against. */
-    private readonly shadowPeelBindGroup;
+    private shadowPeelBindGroup;
     /**
      * The cutout casters' layout, and a bind group per cutout map for each layer, built the first
      * time a map casts and kept: a `createBindGroup` per draw is the allocation the house rules forbid.
@@ -1651,7 +1695,7 @@ export declare class WebGPURenderer implements RendererApi {
     private readonly cutoutPeelGroups;
     private shadowPeelPassUniforms;
     private shadowPeelSampler;
-    private readonly scatterDepthPeelBindGroup;
+    private scatterDepthPeelBindGroup;
     /** Which layer the open pass is writing, so the sink picks the bindings that match it. */
     private shadowLayerIsPeel;
     /**
@@ -1722,6 +1766,10 @@ export declare class WebGPURenderer implements RendererApi {
      * Built once and held, rather than made per call: it closes over `this` and a fresh one
      * every frame would be an allocation in a per-frame path.
      */
+    /** The glass the open shadow pass was offered, kept for its own passes: `glassCasters.ts`. */
+    private readonly glassCasters;
+    /** One resolution every glass caster is read through, so recording one allocates nothing. */
+    private readonly glassCasterScratch;
     private readonly casterSink;
     /** Said once rather than every frame, because a full ring is a flood otherwise. */
     private warnedFull;
@@ -2006,7 +2054,7 @@ export declare class WebGPURenderer implements RendererApi {
      */
     drawMesh(mesh: GpuMesh, model: ArrayLike<number>, depthLayer?: number, tint?: Vec3 | null, 
     /** Where it was last frame. See `RendererApi.drawMesh`, and `runMotion` for what reads it. */
-    previousModel?: ArrayLike<number> | null): void;
+    previousModel?: ArrayLike<number> | Mover | null): void;
     /**
      * Draw a mesh that lets the world through, at `opacity`.
      *
@@ -2105,6 +2153,18 @@ export declare class WebGPURenderer implements RendererApi {
     drawTranslucentInstanced(batch: GpuInstancedBatch, data: MeshInstances, opacity: number, options?: TranslucentMeshOptions): void;
     /** Release the placement. The mesh is the caller's and is not released. */
     disposeInstanced(batch: GpuInstancedBatch): void;
+    /**
+     * Write what a translucent draw shows through it into the material scratch: refraction's bend and
+     * absorption, and glass. Returns whether the frame's copy is there to read, and so whether
+     * `releaseSeeThrough` owes the scratch back.
+     *
+     * **A glass draw takes the copy even when it does not bend**, since a pane shows what is behind it
+     * either way. A copy that cannot be taken — a mirror, a probe bake — leaves both off, so the pane
+     * shades as ordinary translucency rather than sampling a stand-in. See `glass.ts`.
+     */
+    private bindSeeThrough;
+    /** Put the scratch back after `bindSeeThrough`: refraction and glass off. */
+    private releaseSeeThrough;
     /**
      * One draw, one material slot, one uniform slot, however many instances.
      *
@@ -2197,6 +2257,34 @@ export declare class WebGPURenderer implements RendererApi {
     drawSceneCasters(casters: ShadowCasters): void;
     drawShadowCasters(casters: ShadowCasters): void;
     /** Close the shadow pass and submit it, so the frame can sample what it wrote. */
+    /**
+     * Add the sun's two glass layers, once, carrying every layer it holds across on `encoder`.
+     *
+     * **Copied rather than re-baked**, for the reason `SunShadowArray.growForGlass` gives: the static
+     * map is the consumer's to bake and may be baked once, and the glass that grows the texture
+     * arrives in the very pass that drew it. Every view of the old texture is stale afterwards, so
+     * every group holding one is rebuilt here — the lit pass's, the volumes', the medium's and the
+     * peel's — and the old texture is destroyed only once this encoder is submitted.
+     */
+    private growSunForGlass;
+    /** Every group that holds a view of the sun's texture, rebuilt after it has been replaced. */
+    private rebuildSunGroups;
+    /** The sun's tint target, made the first time glass casts and born clear on `encoder`. */
+    private ensureSunTint;
+    /**
+     * Draw the pass's glass twice: where the nearest pane is, and what the panes let through.
+     *
+     * After the opaque casters, on the pass's own encoder. A layer that has held glass is redrawn
+     * even when this pass offered none, so glass that has gone takes its colour with it.
+     */
+    private flushSunGlass;
+    /** The glass list into a glass depth layer: `casterSink` itself, with glass let through. */
+    private readonly glassDepthSink;
+    /**
+     * The glass list into a tint layer, through the tint pipelines, **culling nothing**: every pane on
+     * a ray counts, whichever way it faces. See the other backend's `glassTintSink`.
+     */
+    private readonly glassTintSink;
     endShadowPass(): void;
     /**
      * The pool, or null where the profile switched cube shadows off.
@@ -2217,6 +2305,8 @@ export declare class WebGPURenderer implements RendererApi {
     private preparedPointLightCount;
     /** See `renderer.ts`: built when a world reports its lights, and rebuilt only to grow. */
     private pointShadowArray;
+    /** The array glass replaced, destroyed once the round that copied out of it is submitted. */
+    private retiredPointTexture;
     private readonly bakeScratch;
     /** Said once per renderer; see `updatePointShadows`. */
     private warnedNoPointShadowArray;
@@ -2452,27 +2542,48 @@ export declare class WebGPURenderer implements RendererApi {
      */
     private rebuildReconGroups;
     /**
-     * Remember that this mesh moved, so the motion pass can draw where it was.
+     * Whether a blended draw recorded now lands after the upscale. See `lateRouting.ts`.
      *
-     * Silent unless a reconstruction is running: a scene that always states its previous transforms
-     * — which is the right thing for a scene to do, the alternative being to know what the renderer
-     * is configured as — must cost nothing at all when nobody is going to read them.
+     * Not during the order-independent replay, which owns its pass and issues into it directly.
+     */
+    private drawsLate;
+    /**
+     * The command a blended draw records into: the late pool while reconstructing, the frame graph
+     * otherwise. **Late draws record whatever `quality.frameGraph` says**, since the late replay is
+     * the only moment they can land; everything else keeps the path it has.
+     */
+    private recordBlended;
+    /** The pipelines a blended draw is built for: the reconstructed picture's while late. */
+    private blendedPipelines;
+    /**
+     * The blended draws of a reconstructing frame, over the reconstructed picture at the output size
+     * and unjittered, against the render's depth taken up to that size. Before occlusion, bloom and
+     * the grade, so they are graded exactly as they were when they were drawn into the scene.
      */
-    private recordMotion;
+    private runLate;
+    /** Whether this draw lands in the reconstructed picture. See `lateRouting.ts`. */
+    private tracksMotionNow;
     /**
-     * The pipeline the motion pass draws with, built once.
+     * What this draw's motion is, recorded for the motion pass.
      *
-     * **The position buffer alone**, because that is all the shader reads and a mesh keeps one buffer
-     * an attribute — so this binds buffer zero and nothing else, whatever else the mesh carries.
+     * A mesh rewritten this frame carries its vertex motion whatever else the draw says — under last
+     * frame's model where a mover or a matrix knows it, under this frame's where nothing does. A
+     * mover otherwise carries a rigid draw's last model or a skinned draw's last pose; a matrix
+     * carries a rigid draw's. A draw that says nothing and moved no vertex takes the camera's motion.
      */
-    private buildMotionPipeline;
-    /** The pipeline for one vertex stride, built on first sight of it. */
-    private motionPipelineFor;
+    private recordDrawMotion;
     /**
-     * Where every mover was last frame, into the motion target.
+     * A skinned mover's motion: this frame's palette is the draw's own slot, and last frame's takes a
+     * slot of its own, like any palette a draw binds — so it is uploaded once and nothing overwrites
+     * it before the motion pass reads it. See `SkinPaletteRing`.
+     */
+    private recordSkinnedMotion;
+    private warnMoverTwice;
+    /**
+     * Where every mover was last frame, into the motion target. See `MotionPass`.
      *
      * **After everything that draws and before the resolve reads it.** The frame's depth has to be
-     * finished for the equality test to mean anything, and the resolve is what consumes the result.
+     * finished for the pass's equality test to mean anything, and the resolve is what consumes it.
      */
     private runMotion;
     /**
@@ -2732,6 +2843,8 @@ export declare class WebGPURenderer implements RendererApi {
     private recordDraw;
     /** Replay one recorded draw into an open pass. */
     private replayNode;
+    /** One recorded draw, issued into an open pass. Shared by the graph's replay and `runLate`. */
+    private issueCommand;
     private ensurePass;
     /**
      * The pass a verb will draw into, without flushing what is already recorded.
@@ -3233,6 +3346,10 @@ export declare class WebGPURenderer implements RendererApi {
      *
      * What it gives up is one frame of history: the frame after a cut has no blur and no temporal
      * blend, as the first frame of a session has none. Nothing else is reset.
+     *
+     * **A reconstructing renderer depends on it**: its history is the last shot's, and without this
+     * call a cut blends that shot into the first frames of the next. Nothing detects a cut on the
+     * caller's behalf, deliberately — a fast pan and a cut look alike from here.
      */
     cameraCut(): void;
     /**
@@ -3566,6 +3683,16 @@ export declare class WebGPURenderer implements RendererApi {
      * The occlusion and bloom targets are half size. Both are blurs read back at full size, so a
      * full-resolution intermediate buys nothing a bilinear fetch does not already give.
      */
+    /**
+     * The medium's march group, holding the shadow views it reads — built with the composite, and
+     * again when the sun's texture grows its glass layers and every view of the old one is stale.
+     *
+     * **The stand-in has to read as unoccluded and not as absent**, which is `emptyTexture.ts`'s
+     * point and `createLightVolumeBindGroup`'s: `occlusion()` calls any stored depth below the
+     * receiver's a blocker — so a black stand-in would put the whole medium in shadow, which is a
+     * picture rather than an error. `volumeBlank` is the white one-texel texture built for this.
+     */
+    private buildMediumBindGroup;
     private ensureComposite;
     /**
      * Every bloom stage's uniform block, written once per size rather than once per frame.