@driftengine/core 4.8.6 → 4.9.0

package/dist/render/backend/webgpu/reflectionSurfacePass.js

@@ -0,0 +1,100 @@
+/**
+ * The surface half of a reflection traced through the frame's materials, on this backend: the
+ * frame's opaque lit draws again, against the depth they wrote, into two half-float targets — the
+ * environment as the frame shows it with the surface's roughness, and what a reflection found in the
+ * frame is multiplied by to land in its place. `shaders/flat/reflectionSurface.ts` is what the two
+ * hold and why the swap is exact; this is where they are drawn.
+ *
+ * **Why a second pass and not a second output of the frame's.** Every pipeline drawn into the
+ * frame's pass would have to declare a target it never writes — the sky, water, particles, text and
+ * every pass a consumer registers — so the frame keeps its one attachment, and the lit stage's two
+ * extra outputs land nowhere there. Here they land: the same pipelines with `REFLECTION_SURFACE` on,
+ * which leaves before the lamps, the same bind groups and ring slots, tested `equal` against the
+ * frame's depth so only what the frame kept writes.
+ *
+ * **The draws are commands, kept the way the skin's halves are** (`skinScatterPass.ts`): the frame
+ * graph's pool is spent at every flush, and these are replayed after the flush that ends the frame's
+ * pass. Each holds the ring slots its frame draw used, which stay valid until the frame's last
+ * submit, after this has run.
+ *
+ * **What it costs**: every opaque lit draw twice, the second without its lamps; two half-float
+ * targets the size of the frame. Single-sampled only, as the trace that reads them is.
+ */
+import { createCommandPool, resetPool, takeCommand } from './drawCommand.js';
+/** Both targets' format: linear light and a tint, which an eight-bit target would clip and band. */
+export const REFLECTION_SURFACE_FORMAT = 'rgba16float';
+const USAGE_TARGET = 0x10 | 0x4; // RENDER_ATTACHMENT | TEXTURE_BINDING
+export class ReflectionSurfacePass {
+    device;
+    commands = createCommandPool(256);
+    probe = null;
+    tint = null;
+    /** The environment as the frame shows it, and the roughness in alpha. */
+    probeView = null;
+    /** What a found reflection is multiplied by. */
+    tintView = null;
+    constructor(device) {
+        this.device = device;
+    }
+    /** A command for one opaque lit draw's surface half, filled by the caller. */
+    take() {
+        return this.commands.commands[takeCommand(this.commands)];
+    }
+    /** How many draws the frame kept. */
+    get kept() {
+        return this.commands.taken;
+    }
+    /** A new frame keeps nothing yet. */
+    reset() {
+        resetPool(this.commands);
+    }
+    /** The two targets at the frame's size, made again only when it changes. */
+    size(width, height) {
+        if (this.probe !== null && this.probe.width === width && this.probe.height === height)
+            return;
+        this.release();
+        const make = (label) => this.device.createTexture({
+            label,
+            size: [width, height],
+            format: REFLECTION_SURFACE_FORMAT,
+            usage: USAGE_TARGET,
+        });
+        this.probe = make('reflection.probe');
+        this.tint = make('reflection.tint');
+        this.probeView = this.probe.createView();
+        this.tintView = this.tint.createView();
+    }
+    /**
+     * Every kept draw into the two targets against the frame's depth, which it reads and does not
+     * write; both cleared first, so a pixel no lit surface reached reflects nothing. Called with no
+     * pass open on `encoder`, and drawn even with nothing kept, since the clear is what the trace
+     * reads there.
+     */
+    draw(encoder, depth, issue) {
+        const probe = this.probeView;
+        const tint = this.tintView;
+        if (probe === null || tint === null)
+            return;
+        const pass = encoder.beginRenderPass({
+            label: 'reflection.surface',
+            colorAttachments: [
+                null,
+                { view: probe, clearValue: [0, 0, 0, 1], loadOp: 'clear', storeOp: 'store' },
+                { view: tint, clearValue: [0, 0, 0, 0], loadOp: 'clear', storeOp: 'store' },
+            ],
+            depthStencilAttachment: { view: depth, depthReadOnly: true },
+        });
+        for (let i = 0; i < this.commands.taken; i += 1) {
+            issue(pass, this.commands.commands[i]);
+        }
+        pass.end();
+    }
+    release() {
+        this.probe?.destroy();
+        this.tint?.destroy();
+        this.probe = null;
+        this.tint = null;
+        this.probeView = null;
+        this.tintView = null;
+    }
+}

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,13 +31,15 @@ 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';
 import type { BoltSegments } from '../../boltPool.ts';
 import type { LineSegments } from '../../linePoints.ts';
 import { type ParticleBatchOptions } from '../../particleBatch.ts';
-import type { ParticleInstances } from '../../particlePool.ts';
+import type { DeviceParticles, ParticleInstances } from '../../particlePool.ts';
 import type { PlumeOptions, PlumePlacement } from '../../plumeRenderer.ts';
 import type { InstanceData } from '../../instancedMesh.ts';
 import { type RenderQuality } from '../../renderQuality.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;
@@ -1186,6 +1209,27 @@ export declare class WebGPURenderer implements RendererApi {
     createSurfaceTextureArray(sources: readonly SurfaceSource[], options?: SurfaceTextureOptions): GpuSurfaceTexture;
     /** A baked lightmap page, as a `lightmapModel` material's `modelMap`. See `RendererApi`. */
     createLightmap(page: LightmapPage): GpuSurfaceTexture;
+    /**
+     * A texture the scene can be drawn into, for a material to show. See `RendererApi` and
+     * `sceneCapture.ts`. At the world's own format, which under `hdrScene` is half floats.
+     */
+    createSceneCapture(width: number, height: number): GpuSurfaceTexture;
+    /** Each capture's attachments, beside the texture a material binds. */
+    private readonly captureTargets;
+    /**
+     * Whether a scene capture is being drawn: an off-screen pass as a probe bake is, so the frame's
+     * camera, jitter, motion, refraction copy, skin's spread and late routing are left alone, but
+     * lit by the probes and DriftLight as the frame is. See `captureScene`.
+     */
+    private capturePassActive;
+    /**
+     * Draw the scene into a capture from `camera`. See `RendererApi.captureScene`.
+     *
+     * **Its own encoder, as a probe bake's**: the frame's pass is set aside and restored, the rings
+     * are marked and rewound around the submit, and the frame graph is flushed at both boundaries so
+     * no recorded draw crosses one. **Radiance**: the output transform and exposure are held off.
+     */
+    captureScene(capture: GpuSurfaceTexture, camera: Camera, clearColor: Vec3, draw: (camera: Camera) => void): boolean;
     /**
      * GPU textures an `updateSurfaceTexture` replaced, destroyed when the next frame begins.
      *
@@ -1298,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`. */
@@ -1448,6 +1498,17 @@ export declare class WebGPURenderer implements RendererApi {
     private gradeCode;
     private gradeExposure;
     drawParticles(batch: GpuParticles, data: ParticleInstances, camera: Camera, env: Environment, timeSeconds: number): void;
+    /**
+     * Draw particles a caller's own compute wrote, where they lie. See `DeviceParticles`.
+     *
+     * **The pool's draw with its instance stream swapped**: the same material, blend, flipbook, soft
+     * edge and fog, reading the caller's buffer in place of the one the pool uploads into — so nothing
+     * crosses back to the CPU. Not sorted, and a count past what the buffer holds is cut to it rather
+     * than handed to a draw the device would refuse with the frame.
+     */
+    drawDeviceParticles(batch: GpuParticles, particles: DeviceParticles, camera: Camera, env: Environment, timeSeconds: number): void;
+    /** A pool's uniforms for this view, and its draw from `instances`: both entry points' tail. */
+    private drawParticleInstances;
     /**
      * A sprite's flipbook and fades into its fragment block `f`, and the bind group holding the
      * frame's depth copy its soft edge reads — built again only when that copy is replaced.
@@ -1767,6 +1828,8 @@ export declare class WebGPURenderer implements RendererApi {
     private writeWind;
     /** Refilled per frame rather than allocated; see `resolvePointLights`. */
     private readonly lights;
+    /** The fixed arm's rectangles as `uAreaLightSize` holds them. See `packAreaSizesAndDoors`. */
+    private readonly areaSizesAndDoors;
     /** Refilled per frame rather than allocated; see `resolveAtmosphere`. */
     private readonly medium;
     private readonly panelLayout;
@@ -2521,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. */
@@ -2584,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.
      *
@@ -2772,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;
     /**
@@ -2976,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
@@ -2993,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.
      *
@@ -3550,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;
@@ -3573,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;
@@ -3588,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
@@ -3633,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.
      *