@driftengine/core 4.8.7 → 4.9.0

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

@@ -23,6 +23,7 @@ import type { TextStyle } from '../../textLayout.ts';
 import { GpuSurfaceTexture } from './surfaceTexturePass.ts';
 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 { GpuSdfText } from './sdfTextPass.ts';
@@ -30,6 +31,8 @@ import type { SdfFont } from '../../sdfFont.ts';
 import type { SdfTextStyle } from '../../sdfTextLayout.ts';
 import type { SurfaceMaterial, SurfaceTextureOptions } from '../../surfaceTexture.ts';
 import type { RenderBackend } from '../api.ts';
+import { type DisplayRange } from '../../displayRange.ts';
+import { type FilmicCurve } from '../../filmicCurve.ts';
 import { type ColourGradeLut } from '../../colourGrade.ts';
 import type { CausticSheet } from '../../causticsRenderer.ts';
 import { type GpuCaustics } from './causticsPass.ts';
@@ -508,6 +511,17 @@ export declare class WebGPURenderer implements RendererApi {
      */
     private refractSnapshot;
     private refractSnapshotView;
+    /**
+     * The frame's colour as a registered pass reads it (`reads: ['colorSnapshot']`): the scene's own
+     * size and format, refilled at each such pass's draw. Allocated only once a pass declares the
+     * read, beside the frame's targets, and never in the frame loop. See `takePassColour`.
+     */
+    private passColour;
+    private passColourView;
+    /** Registered passes that read the colour, queued this frame for after the upscale. */
+    private readonly latePasses;
+    /** A late pass draws unjittered, as every late draw does. */
+    private readonly latePassJitter;
     /** Whether this frame has taken it. One snapshot serves every refracting draw. */
     private refractSnapshotTaken;
     /**
@@ -992,6 +1006,15 @@ export declare class WebGPURenderer implements RendererApi {
     private readonly reflectionQueue;
     private ssrLayout;
     private ssrResolveLayout;
+    /** The frame's materials' reflections, resolved; null where off. See `frameReflections.ts`. */
+    private readonly frameReflections;
+    /** Their surface half, null where they are off or cannot be drawn: `reflectionSurfacePass.ts`. */
+    private readonly reflectionSurface;
+    /** The material resolve: its layout, its one block (the blur) and its group over the three maps. */
+    private ssrMaterialLayout;
+    private ssrMaterialUniforms;
+    private readonly ssrMaterialFloats;
+    private ssrMaterialGroup;
     private ssrUniforms;
     private readonly ssrStaging;
     private readonly ssrFloats;
@@ -1319,6 +1342,12 @@ export declare class WebGPURenderer implements RendererApi {
      * frame's. See `Renderer.setAmbientSH`: material state, so the next draw takes a slot of its own.
      */
     setAmbientSH(coefficients: ArrayLike<number> | null): void;
+    /**
+     * The overlay the following draws wear, or null for none: pass state, put back to none by
+     * `bindMeshPass`. See `renderer.ts` and `surfaceOverlay.ts`. The numbers go in the material block,
+     * which every variant declares; the atlas goes in a twin of each flat group (`overlayGroup`).
+     */
+    setSurfaceOverlay(overlay: SurfaceOverlay | null): void;
     /** How reflective the surfaces drawn next are. Clamped, as `renderer.ts` clamps it. */
     setSurfaceReflectivity(amount: number): void;
     /** How bright the environment the surfaces drawn next reflect is. See `renderer.ts`. */
@@ -2555,6 +2584,20 @@ export declare class WebGPURenderer implements RendererApi {
     private warnedNoPointShadowArray;
     /** Said once, for the retired ambient dial. */
     private warnedEnvironmentAmbient;
+    /** The overlay the draws wear, `uOverlay`: see `setSurfaceOverlay`. */
+    private readonly overlayFloats;
+    /** Its atlas, bound where the refraction copy goes in a twin of each flat group. */
+    private overlayMaps;
+    /**
+     * Each flat group's twin with the atlas in the refraction slot, by the group and the atlas, built
+     * on the first draw that wears it and dropped wherever `flatBindGroups` is.
+     */
+    private readonly overlayGroups;
+    /** True while a twin is built: what `flatTextures` hands the refraction slot then. */
+    private overlayBinding;
+    /** True between `bindSeeThrough` and `releaseSeeThrough`: that draw reads the copy, not the atlas. */
+    private seeThroughBound;
+    private warnedOverlayRefraction;
     private readonly castingWorldIndices;
     private readonly resolvedPointShadows;
     /** One face's view-projection, rebuilt per face rather than allocated. */
@@ -2618,6 +2661,15 @@ export declare class WebGPURenderer implements RendererApi {
      */
     private resolveFace;
     private buildFlatBindGroup;
+    /**
+     * The open material's flat group, or its twin with the surface overlay's atlas in the refraction
+     * slot where the draw wears one and does not refract. A twin is built from the live material,
+     * which `bindGroup` always is, and kept by the group and the atlas.
+     *
+     * **A draw that refracts, or is glass, keeps the frame's copy** and its overlay reads no image —
+     * the shader asks the same of `uSeeThrough` (`overlayImagesBound`) — said once.
+     */
+    private overlayGroup;
     /**
      * The bind group a draw uses, skinned or not.
      *
@@ -2806,6 +2858,13 @@ export declare class WebGPURenderer implements RendererApi {
      * the grade, so they are graded exactly as they were when they were drawn into the scene.
      */
     private runLate;
+    /**
+     * The registered passes `drawPass` queued for after the upscale: each handed a fresh copy of the
+     * reconstructed picture with every late draw in it, in the output-size texture the late
+     * refraction keeps (its own reads are done by now: they were recorded before this copy), then
+     * drawn over the picture in a pass of its own.
+     */
+    private runLatePasses;
     /** Whether this draw lands in the reconstructed picture. See `lateRouting.ts`. */
     private tracksMotionNow;
     /**
@@ -3010,6 +3069,16 @@ export declare class WebGPURenderer implements RendererApi {
      * the frame, or an order-independent set, none of which the spread reads.
      */
     private skinSplits;
+    /** Whether a draw now is the frame's own, and so has a surface half to keep. */
+    private reflectionSurfaceKeeps;
+    /**
+     * An opaque lit draw's surface half, kept for the frame's materials' reflections: the draw again,
+     * with the same slots, buffers and bind group, through the pipeline with `REFLECTION_SURFACE` on —
+     * which writes what the pixel reflects of its environment into the two targets
+     * `reflectionSurfacePass.ts` holds and tests for the depth its frame draw wrote. Replayed when the
+     * frame's pass has ended, before the trace reads them. See `shaders/flat/reflectionSurface.ts`.
+     */
+    private keepReflectionSurface;
     /**
      * A skin draw's diffuse and colour halves, kept for the spread: the frame's draw again, twice,
      * with the same slots, buffers and bind group, through the pipelines that write the diffuse's
@@ -3027,6 +3096,21 @@ export declare class WebGPURenderer implements RendererApi {
      */
     private runSkinScatter;
     private takeVolumeDepth;
+    /** The colour copy a registered pass reads, at the scene's size and format. See `passColour`. */
+    private allocatePassColour;
+    /**
+     * The frame's colour so far, into `passColour`, for a registered pass that reads it: the
+     * boundary `takeRefractSnapshot` describes — flush, end the pass, copy what its end resolved,
+     * reopen with `load` — and refused where that one is, in a mirror, a probe bake or a capture,
+     * whose pictures are not the frame's. **Not latched**, unlike refraction's: each reading pass
+     * sees the passes drawn before it, at a full-frame copy each.
+     */
+    private takePassColour;
+    /**
+     * The frame's pass again after a copy between passes, loading everything already drawn: the same
+     * attachments the copy's caller ended, with nothing cleared.
+     */
+    private reopenFramePass;
     /**
      * The pass to record into, reopening one on the canvas if the frame has already gone.
      *
@@ -3584,6 +3668,30 @@ export declare class WebGPURenderer implements RendererApi {
     setOutputExposure(exposure: number): void;
     /** This frame's exposure into the tone curve. Starts at the profile's own. */
     private exposure;
+    /**
+     * The `filmic` curve every later frame is graded through, until it is set again. See
+     * `RendererApi.setFilmicCurve`; the constants are solved here once, not per frame or per pixel.
+     */
+    setFilmicCurve(curve: FilmicCurve): void;
+    private warnedFilmClamped;
+    /** The curve last set, so a new headroom can solve it again. */
+    private filmCurve;
+    /** The display's peak over paper white; 1 on a standard range. See `setDisplayLuminance`. */
+    private headroom;
+    /** The range the frame goes out in. See `RendererApi.displayRange`. */
+    get displayRange(): DisplayRange;
+    /** Why it is that range, in words. */
+    get displayRangeReason(): string;
+    /**
+     * How bright paper white and the display's peak are, in any one unit (nits, usually), held until
+     * changed: their ratio is how far above white the highlights may run on a high range display,
+     * and nothing changes on a standard one. See `RendererApi.setDisplayLuminance`.
+     */
+    setDisplayLuminance(paperWhite: number, peak: number): void;
+    /** The curve's eight constants, and the two views the composite uploads them through. */
+    private readonly filmConstants;
+    private readonly filmA;
+    private readonly filmB;
     private bloomScale;
     /** The draw's own ambient, as `packAmbientSH` writes it; zeros are the frame's. */
     private readonly ambientSH;
@@ -3607,6 +3715,8 @@ export declare class WebGPURenderer implements RendererApi {
     private readonly veilColor;
     private veilAlpha;
     private vignette;
+    /** The lens's colour fringe: red's and green's pull and where it begins. See `fringe.ts`. */
+    private readonly fringe;
     private grain;
     private grainSeed;
     private warnedLookWithoutComposite;
@@ -3622,6 +3732,14 @@ export declare class WebGPURenderer implements RendererApi {
      * see `filmLook.ts`. Needs `screenEffects`, and says so once rather than doing nothing.
      */
     setVignette(strength: number): void;
+    /**
+     * The lens's colour fringe, held until changed: `intensity` is a percentage, 0 is none, and red
+     * and green are pulled toward the centre by their wavelength's distance from blue, growing from
+     * `start` — a share of the half-frame, 0 the centre — to the whole of it at the edge. Applied to
+     * scene light at the composite's first read. Needs `screenEffects`, and says so once rather than
+     * doing nothing. See `shaders/fringe.ts`.
+     */
+    setChromaticAberration(intensity: number, start?: number): void;
     /**
      * Film grain, held until changed: an amplitude in display values (0 is none, 0.03 is a fine
      * grain) and this frame's seed. **The seed is the caller's**, because the engine takes time from
@@ -3667,8 +3785,19 @@ export declare class WebGPURenderer implements RendererApi {
     setGlobalMedium(density: number, albedo?: number, anisotropy?: number, maxDistance?: number): void;
     /** How much speed blur the frame should resolve with, 0 to 1. */
     setSpeedRush(strength: number): void;
-    /** How much of the frame's camera motion blur to apply, 0 to 1. */
-    setCameraMotionBlur(scale: number): void;
+    /**
+     * How much of the frame's motion blur to apply, 0 to 1, and the longest smear as a share of the
+     * frame, both held until changed. See `RendererApi.setCameraMotionBlur`.
+     */
+    setCameraMotionBlur(scale: number, maxShare?: number): void;
+    /** The longest smear, as a share of the frame. See `setCameraMotionBlur`. */
+    private motionBlurMax;
+    private warnedObjectBlur;
+    /**
+     * Said once: a draw named where it was last frame while the frame blurs, and this frame keeps no
+     * motion target to blur it by — the camera's motion alone smears it. See `OBJECT_BLUR_UNKEPT`.
+     */
+    private warnObjectBlur;
     /**
      * The camera has cut: this frame is a new shot, not the next moment of the last one.
      *