@driftengine/core 4.8.7 → 4.10.0

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

@@ -0,0 +1,265 @@
+import { DYNAMIC_ALIGNMENT, MAX_RING_BYTES } from './uniformRing.js';
+/**
+ * The lit stage's material blocks, each kept in its slot for as long as later draws ask for the
+ * same numbers, so a material that has not changed since the last frame costs no upload at all.
+ *
+ * **Keyed by content, because nothing else names a material.** A material here is whatever the
+ * setters left in the block when a draw took it — a consumer never hands over an object that could
+ * carry an identity — so the block's own words are the key: hashed to find a bucket, compared word
+ * for word to accept a match, and bound by the slot's offset. What it gives up is a hash and a
+ * compare of a few hundred bytes per material change, against copying and uploading the whole
+ * block every frame, which a stage of four hundred materials measured at megabytes a frame.
+ *
+ * **A slot the frame has asked for is never given away within it**, for the reason `UniformRing`
+ * exists: a queue write does not interleave with recorded draws, so rewriting a slot a recorded draw
+ * reads would hand that draw the new numbers. A frame asking for more distinct blocks than there are
+ * slots is refused, counted and skipped, as the ring was. Across frames rewriting is safe, because a
+ * write issued after a submit is ordered after the commands in it.
+ *
+ * **What a new block displaces is a slot nobody asked for this frame or the last**, found by a hand
+ * that sweeps the slots in turn; only when every slot was asked for recently does it take one the
+ * last frame used. What would make that wrong is a scene whose distinct materials a frame approach
+ * the store's size: it then rewrites some of its steady materials every frame, which costs their
+ * upload and nothing else.
+ */
+export class MaterialStore {
+    device;
+    usage;
+    label;
+    budget;
+    /** Replaced by `growTo`, so every bind group over it is rebuilt when that says so. */
+    buffer;
+    /** Bytes per slot, rounded up to the alignment a dynamic offset requires. */
+    slotSize;
+    words;
+    stride;
+    capacity;
+    staging;
+    ints;
+    /** Per slot: its block's hash, the next slot in its bucket or -1, and whether it holds one. */
+    hashes;
+    next;
+    held;
+    /** Per slot: the frame that last asked for it, and whether it was written since the last flush. */
+    askedIn;
+    pending;
+    /** Per slot: how many holders pinned it. A pinned slot is never displaced. */
+    pins;
+    /**
+     * How many times the store has forgotten everything it held, which growth does: a holder of an
+     * offset compares this, because an offset from before is a slot of a buffer that is gone.
+     */
+    epoch = 0;
+    /** Per bucket: its first slot, or -1. A power of two at least twice the slots. */
+    heads;
+    mask;
+    lowPending;
+    highPending = -1;
+    hand = 0;
+    /** Starts past zero, so a slot never asked for reads as long unasked. */
+    frame = 2;
+    constructor(device, bytesPerBlock, slots, usage, label = 'materials.store', budget = null) {
+        this.device = device;
+        this.usage = usage;
+        this.label = label;
+        this.budget = budget;
+        this.words = Math.ceil(bytesPerBlock / 4);
+        this.slotSize = Math.ceil(bytesPerBlock / DYNAMIC_ALIGNMENT) * DYNAMIC_ALIGNMENT;
+        this.stride = this.slotSize / 4;
+        this.capacity = slots;
+        this.lowPending = slots;
+        this.staging = new ArrayBuffer(this.slotSize * slots);
+        this.ints = new Int32Array(this.staging);
+        this.hashes = new Int32Array(slots);
+        this.next = new Int32Array(slots);
+        this.held = new Uint8Array(slots);
+        this.askedIn = new Int32Array(slots);
+        this.pending = new Uint8Array(slots);
+        this.pins = new Int32Array(slots);
+        this.heads = new Int32Array(bucketsFor(slots)).fill(-1);
+        this.mask = this.heads.length - 1;
+        this.buffer = device.createBuffer({ label, size: this.staging.byteLength, usage });
+    }
+    /** How many distinct blocks a frame may hold. */
+    get slots() {
+        return this.capacity;
+    }
+    /** Start a frame: every slot the last one asked for may be displaced from here on, last. */
+    beginFrame() {
+        this.frame += 1;
+    }
+    /**
+     * The byte offset of a slot holding exactly `block`, written there if no slot did, or null when
+     * every slot is one this frame has asked for. `block` is the whole block, word for word.
+     */
+    place(block) {
+        this.budget?.ask();
+        const hash = hashWords(block, this.words);
+        const bucket = hash & this.mask;
+        for (let slot = this.heads[bucket]; slot >= 0; slot = this.next[slot]) {
+            if (this.hashes[slot] === hash && this.holds(slot, block)) {
+                this.askedIn[slot] = this.frame;
+                return slot * this.slotSize;
+            }
+        }
+        const slot = this.displace();
+        if (slot < 0) {
+            this.budget?.drop();
+            return null;
+        }
+        if (this.held[slot] === 1)
+            this.unlink(slot);
+        this.ints.set(block, slot * this.stride);
+        this.hashes[slot] = hash;
+        this.next[slot] = this.heads[bucket];
+        this.heads[bucket] = slot;
+        this.held[slot] = 1;
+        this.askedIn[slot] = this.frame;
+        this.pending[slot] = 1;
+        if (slot < this.lowPending)
+            this.lowPending = slot;
+        if (slot > this.highPending)
+            this.highPending = slot;
+        return slot * this.slotSize;
+    }
+    /** Upload every slot written since the last flush, one write per run of neighbouring slots. */
+    flush() {
+        let slot = this.lowPending;
+        while (slot <= this.highPending) {
+            if (this.pending[slot] !== 1) {
+                slot += 1;
+                continue;
+            }
+            const from = slot;
+            while (slot <= this.highPending && this.pending[slot] === 1) {
+                this.pending[slot] = 0;
+                slot += 1;
+            }
+            const at = from * this.slotSize;
+            this.device.queue.writeBuffer(this.buffer, at, this.staging, at, (slot - from) * this.slotSize);
+        }
+        this.lowPending = this.capacity;
+        this.highPending = -1;
+    }
+    /**
+     * Make room for at least `slots`, forgetting every block held, and say whether the buffer was
+     * replaced. Called where `UniformRing.growTo` is, at a frame's start, for the reasons it gives,
+     * and refused past the same ceiling.
+     */
+    growTo(slots) {
+        if (slots <= this.capacity)
+            return false;
+        if (this.slotSize * slots > MAX_RING_BYTES)
+            return false;
+        this.buffer.destroy();
+        this.capacity = slots;
+        this.staging = new ArrayBuffer(this.slotSize * slots);
+        this.ints = new Int32Array(this.staging);
+        this.hashes = new Int32Array(slots);
+        this.next = new Int32Array(slots);
+        this.held = new Uint8Array(slots);
+        this.askedIn = new Int32Array(slots);
+        this.pending = new Uint8Array(slots);
+        this.pins = new Int32Array(slots);
+        this.heads = new Int32Array(bucketsFor(slots)).fill(-1);
+        this.mask = this.heads.length - 1;
+        this.lowPending = slots;
+        this.epoch += 1;
+        this.highPending = -1;
+        this.hand = 0;
+        this.buffer = this.device.createBuffer({
+            label: this.label,
+            size: this.staging.byteLength,
+            usage: this.usage,
+        });
+        return true;
+    }
+    /**
+     * Keep the block at `offset` where it is until `unpin`: a holder binding it by offset frame after
+     * frame — a list recorded once — whether or not anything asks for it. Counted, so two holders of
+     * one block each let go of their own pin.
+     */
+    pin(offset) {
+        const slot = offset / this.slotSize;
+        this.pins[slot] = this.pins[slot] + 1;
+    }
+    unpin(offset) {
+        const slot = offset / this.slotSize;
+        if (this.pins[slot] > 0)
+            this.pins[slot] = this.pins[slot] - 1;
+    }
+    dispose() {
+        this.buffer.destroy();
+    }
+    holds(slot, block) {
+        const base = slot * this.stride;
+        for (let word = 0; word < this.words; word++) {
+            if (this.ints[base + word] !== block[word])
+                return false;
+        }
+        return true;
+    }
+    /**
+     * The slot a new block goes in: the first from the hand nobody asked for this frame or the last,
+     * else the first this frame has not asked for, else none. One sweep at most.
+     */
+    displace() {
+        let fallback = -1;
+        for (let step = 0; step < this.capacity; step++) {
+            const slot = this.hand;
+            this.hand = slot + 1 === this.capacity ? 0 : slot + 1;
+            if (this.pins[slot] > 0)
+                continue;
+            const asked = this.askedIn[slot];
+            if (asked < this.frame - 1)
+                return slot;
+            if (fallback < 0 && asked !== this.frame)
+                fallback = slot;
+        }
+        return fallback;
+    }
+    unlink(slot) {
+        const bucket = this.hashes[slot] & this.mask;
+        let at = this.heads[bucket];
+        if (at === slot) {
+            this.heads[bucket] = this.next[slot];
+            return;
+        }
+        while (at >= 0) {
+            const after = this.next[at];
+            if (after === slot) {
+                this.next[at] = this.next[slot];
+                return;
+            }
+            at = after;
+        }
+    }
+}
+function bucketsFor(slots) {
+    let buckets = 16;
+    while (buckets < slots * 2)
+        buckets *= 2;
+    return buckets;
+}
+/**
+ * MurmurHash3's 32-bit mix over the block's words. Not FNV, whose multiply carries a difference only
+ * upward: the bucket is the hash's low bits, and a material's words are mostly floats, whose low
+ * mantissa bits are zero for every value a person types — 0.5, 1, 2 — so blocks differing only in
+ * those would all have shared one bucket. The compare that follows a match is what decides.
+ */
+export function hashWords(block, words) {
+    let hash = 0x9747b28c;
+    for (let word = 0; word < words; word++) {
+        let k = Math.imul(block[word], 0xcc9e2d51);
+        k = (k << 15) | (k >>> 17);
+        hash ^= Math.imul(k, 0x1b873593);
+        hash = (hash << 13) | (hash >>> 19);
+        hash = (Math.imul(hash, 5) + 0xe6546b64) | 0;
+    }
+    hash ^= words * 4;
+    hash ^= hash >>> 16;
+    hash = Math.imul(hash, 0x85ebca6b);
+    hash ^= hash >>> 13;
+    hash = Math.imul(hash, 0xc2b2ae35);
+    return hash ^ (hash >>> 16);
+}

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

@@ -52,6 +52,12 @@ export declare class PipelineCache {
     readonly glassShadows: boolean;
     /** How to describe each lit pipeline again, so `enable` can rebuild every one. */
     private readonly litDescribers;
+    /**
+     * Bumped when a switch's rebuilt set lands, which replaces pipelines already handed out: a holder
+     * of one — a recorded render bundle — compares this and records again rather than drawing on
+     * with the pipelines from before the switch.
+     */
+    version: number;
     /** Bumped by every switch, so a lit build started before one is not kept after it. */
     private litGeneration;
     /** The last rebuild, which the next one waits for so they land in the order they were asked. */

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

@@ -51,6 +51,12 @@ export class PipelineCache {
     glassShadows;
     /** How to describe each lit pipeline again, so `enable` can rebuild every one. */
     litDescribers = new Map();
+    /**
+     * Bumped when a switch's rebuilt set lands, which replaces pipelines already handed out: a holder
+     * of one — a recorded render bundle — compares this and records again rather than drawing on
+     * with the pipelines from before the switch.
+     */
+    version = 0;
     /** Bumped by every switch, so a lit build started before one is not kept after it. */
     litGeneration = 0;
     /** The last rebuild, which the next one waits for so they land in the order they were asked. */
@@ -201,6 +207,7 @@ export class PipelineCache {
                 if (result.status === 'fulfilled')
                     this.pipelines.set(result.value[0], result.value[1]);
             }
+            this.version += 1;
         });
         return this.litRebuild;
     }

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

@@ -5,7 +5,7 @@ import { TEMPORAL_RESOLVE_FRAG_WGSL } from '../../shaders/generated/temporalReso
 import { OIT_RESOLVE_FRAG_WGSL } from '../../shaders/generated/oitResolve.wgsl.ts';
 import { DECAL_PROJECT_FRAG_WGSL } from '../../shaders/generated/decalProject.wgsl.ts';
 import { SSR_TRACE_FRAG_WGSL } from '../../shaders/generated/ssrTrace.wgsl.ts';
-import { SSR_RESOLVE_FRAG_WGSL } from '../../shaders/generated/ssrResolve.wgsl.ts';
+import { SSR_MATERIAL_RESOLVE_FRAG_WGSL, SSR_RESOLVE_FRAG_WGSL } from '../../shaders/generated/ssrResolve.wgsl.ts';
 import { MEDIUM_FRAG_WGSL, MEDIUM_UPSAMPLE_FRAG_WGSL } from '../../shaders/generated/globalMedium.wgsl.ts';
 import type { UniformFields } from './scatterPass.ts';
 import type { PipelineCache } from './pipelineCache.ts';
@@ -26,7 +26,7 @@ import type { PipelineCache } from './pipelineCache.ts';
  * float target the generated shaders can sample as an ordinary texture.
  */
 export declare const RUSH_FRAG_FIELDS: UniformFields;
-export declare const RUSH_FRAG_SIZE: 208;
+export declare const RUSH_FRAG_SIZE: 272;
 declare const RUSH_UNIFORMS: 1;
 declare const RUSH_TEXTURES: {
     readonly uScene: {
@@ -39,29 +39,34 @@ declare const RUSH_TEXTURES: {
         readonly sampler: 35;
         readonly type: "sampler2D";
     };
-    readonly uAo: {
+    readonly uMotion: {
         readonly texture: 36;
         readonly sampler: 37;
         readonly type: "sampler2D";
     };
-    readonly uBloom: {
+    readonly uAo: {
         readonly texture: 38;
         readonly sampler: 39;
         readonly type: "sampler2D";
     };
-    readonly uExposureHeld: {
+    readonly uBloom: {
         readonly texture: 40;
         readonly sampler: 41;
         readonly type: "sampler2D";
     };
-    readonly uExposureLocal: {
+    readonly uExposureHeld: {
         readonly texture: 42;
         readonly sampler: 43;
         readonly type: "sampler2D";
     };
-    readonly uGradeLut: {
+    readonly uExposureLocal: {
         readonly texture: 44;
         readonly sampler: 45;
+        readonly type: "sampler2D";
+    };
+    readonly uGradeLut: {
+        readonly texture: 46;
+        readonly sampler: 47;
         readonly type: "sampler3D";
     };
 };
@@ -180,6 +185,12 @@ export declare const PREMULTIPLIED_OVER_BLEND: GPUBlendState;
  * the reflection's own and its alpha is the coverage this resolve reads.
  */
 export declare const REFLECTION_OVER_BLEND: GPUBlendState;
+/**
+ * The frame's materials' reflection, added: the found colour times the tint, less the probe's share,
+ * which is negative where the probe was brighter than what replaced it. A half-float scene takes
+ * the negative addend as the subtraction it is. Its alpha kept.
+ */
+export declare const FRAME_REFLECTION_BLEND: GPUBlendState;
 /**
  * The bloom pyramid's way back up: an octave added onto a level that the blend multiplies by that
  * level's tint first — the blend constant, which white makes `one, one` exactly. Into the pyramid's
@@ -276,7 +287,7 @@ export declare const DECAL_TEXTURES: {
  * commands, so one block rewritten between two passes gives both passes the last write.
  */
 export declare const SSR_FRAG_FIELDS: UniformFields;
-export declare const SSR_FRAG_SIZE: 272;
+export declare const SSR_FRAG_SIZE: 288;
 export declare const SSR_UNIFORMS: 1;
 export declare const SSR_TEXTURES: {
     readonly uSsrDepth: {
@@ -289,6 +300,16 @@ export declare const SSR_TEXTURES: {
         readonly sampler: 35;
         readonly type: "sampler2D";
     };
+    readonly uSsrProbeMap: {
+        readonly texture: 36;
+        readonly sampler: 37;
+        readonly type: "sampler2D";
+    };
+    readonly uSsrTintMap: {
+        readonly texture: 38;
+        readonly sampler: 39;
+        readonly type: "sampler2D";
+    };
 };
 export declare const SSR_RESOLVE_TEXTURES: {
     readonly uSsrReflection: {
@@ -297,6 +318,27 @@ export declare const SSR_RESOLVE_TEXTURES: {
         readonly type: "sampler2D";
     };
 };
+/** The material resolve's block — the blur — and its three inputs. See `frameReflections.ts`. */
+export declare const SSR_MATERIAL_FIELDS: UniformFields;
+export declare const SSR_MATERIAL_SIZE: 16;
+export declare const SSR_MATERIAL_UNIFORMS: 1;
+export declare const SSR_MATERIAL_TEXTURES: {
+    readonly uSsrReflection: {
+        readonly texture: 32;
+        readonly sampler: 33;
+        readonly type: "sampler2D";
+    };
+    readonly uSsrProbeMap: {
+        readonly texture: 34;
+        readonly sampler: 35;
+        readonly type: "sampler2D";
+    };
+    readonly uSsrTintMap: {
+        readonly texture: 36;
+        readonly sampler: 37;
+        readonly type: "sampler2D";
+    };
+};
 /**
  * The resolve's layout: one texture and no uniform block.
  *
@@ -341,7 +383,7 @@ export declare const MEDIUM_UPSAMPLE_TEXTURES: {
         readonly type: "sampler2D";
     };
 };
-export { RUSH_FRAG_WGSL, AO_FRAG_WGSL, AO_BLUR_FRAG_WGSL, TEMPORAL_RESOLVE_FRAG_WGSL, OIT_RESOLVE_FRAG_WGSL, DECAL_PROJECT_FRAG_WGSL, SSR_TRACE_FRAG_WGSL, SSR_RESOLVE_FRAG_WGSL, };
+export { RUSH_FRAG_WGSL, AO_FRAG_WGSL, AO_BLUR_FRAG_WGSL, TEMPORAL_RESOLVE_FRAG_WGSL, OIT_RESOLVE_FRAG_WGSL, DECAL_PROJECT_FRAG_WGSL, SSR_TRACE_FRAG_WGSL, SSR_RESOLVE_FRAG_WGSL, SSR_MATERIAL_RESOLVE_FRAG_WGSL, };
 export { BLOOM_PREFILTER_FRAG_WGSL, BLOOM_DOWNSAMPLE_FRAG_WGSL, BLOOM_UPSAMPLE_FRAG_WGSL };
 export { RUSH_UNIFORMS, RUSH_TEXTURES };
 export declare const AO_UNIFORMS: 1;

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

@@ -6,7 +6,7 @@ import { TEMPORALRESOLVE_BINDINGS as TAA_BINDINGS, TEMPORAL_RESOLVE_FRAG_WGSL, }
 import { OITRESOLVE_BINDINGS as OIT_BINDINGS, OIT_RESOLVE_FRAG_WGSL, } from '../../shaders/generated/oitResolve.wgsl.js';
 import { DECALPROJECT_BINDINGS as DECAL_BINDINGS, DECAL_PROJECT_FRAG_WGSL, } from '../../shaders/generated/decalProject.wgsl.js';
 import { SSRTRACE_BINDINGS as SSR_BINDINGS, SSR_TRACE_FRAG_WGSL, } from '../../shaders/generated/ssrTrace.wgsl.js';
-import { SSRRESOLVE_BINDINGS as SSR_RESOLVE_BINDINGS, SSR_RESOLVE_FRAG_WGSL, } from '../../shaders/generated/ssrResolve.wgsl.js';
+import { SSRRESOLVE_BINDINGS as SSR_RESOLVE_BINDINGS, SSR_MATERIAL_RESOLVE_FRAG_WGSL, SSR_RESOLVE_FRAG_WGSL, } from '../../shaders/generated/ssrResolve.wgsl.js';
 import { GLOBALMEDIUM_BINDINGS as MEDIUM_BINDINGS, MEDIUM_FRAG_WGSL, MEDIUM_UPSAMPLE_FRAG_WGSL, } from '../../shaders/generated/globalMedium.wgsl.js';
 import { shaderModule } from './shaderModules.js';
 import { SCENE_ALPHA_KEEPS, SCENE_ALPHA_TRANSMITS } from '../../sceneCoverage.js';
@@ -252,6 +252,15 @@ export const REFLECTION_OVER_BLEND = {
     color: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
     alpha: SCENE_ALPHA_KEEPS,
 };
+/**
+ * The frame's materials' reflection, added: the found colour times the tint, less the probe's share,
+ * which is negative where the probe was brighter than what replaced it. A half-float scene takes
+ * the negative addend as the subtraction it is. Its alpha kept.
+ */
+export const FRAME_REFLECTION_BLEND = {
+    color: { srcFactor: 'one', dstFactor: 'one', operation: 'add' },
+    alpha: SCENE_ALPHA_KEEPS,
+};
 /**
  * The bloom pyramid's way back up: an octave added onto a level that the blend multiplies by that
  * level's tint first — the blend constant, which white makes `one, one` exactly. Into the pyramid's
@@ -340,6 +349,11 @@ export const SSR_FRAG_SIZE = SSR_BINDINGS.SSR_TRACE_FRAG.uniformSize;
 export const SSR_UNIFORMS = SSR_BINDINGS.SSR_TRACE_FRAG.uniforms;
 export const SSR_TEXTURES = SSR_BINDINGS.SSR_TRACE_FRAG.textures;
 export const SSR_RESOLVE_TEXTURES = SSR_RESOLVE_BINDINGS.SSR_RESOLVE_FRAG.textures;
+/** The material resolve's block — the blur — and its three inputs. See `frameReflections.ts`. */
+export const SSR_MATERIAL_FIELDS = SSR_RESOLVE_BINDINGS.SSR_MATERIAL_RESOLVE_FRAG.fields;
+export const SSR_MATERIAL_SIZE = SSR_RESOLVE_BINDINGS.SSR_MATERIAL_RESOLVE_FRAG.uniformSize;
+export const SSR_MATERIAL_UNIFORMS = SSR_RESOLVE_BINDINGS.SSR_MATERIAL_RESOLVE_FRAG.uniforms;
+export const SSR_MATERIAL_TEXTURES = SSR_RESOLVE_BINDINGS.SSR_MATERIAL_RESOLVE_FRAG.textures;
 /**
  * The resolve's layout: one texture and no uniform block.
  *
@@ -390,7 +404,7 @@ export const MEDIUM_UNIFORMS = MEDIUM_BINDINGS.MEDIUM_FRAG.uniforms;
 export const MEDIUM_TEXTURES = MEDIUM_BINDINGS.MEDIUM_FRAG.textures;
 export const MEDIUM_UPSAMPLE_UNIFORMS = MEDIUM_BINDINGS.MEDIUM_UPSAMPLE_FRAG.uniforms;
 export const MEDIUM_UPSAMPLE_TEXTURES = MEDIUM_BINDINGS.MEDIUM_UPSAMPLE_FRAG.textures;
-export { RUSH_FRAG_WGSL, AO_FRAG_WGSL, AO_BLUR_FRAG_WGSL, TEMPORAL_RESOLVE_FRAG_WGSL, OIT_RESOLVE_FRAG_WGSL, DECAL_PROJECT_FRAG_WGSL, SSR_TRACE_FRAG_WGSL, SSR_RESOLVE_FRAG_WGSL, };
+export { RUSH_FRAG_WGSL, AO_FRAG_WGSL, AO_BLUR_FRAG_WGSL, TEMPORAL_RESOLVE_FRAG_WGSL, OIT_RESOLVE_FRAG_WGSL, DECAL_PROJECT_FRAG_WGSL, SSR_TRACE_FRAG_WGSL, SSR_RESOLVE_FRAG_WGSL, SSR_MATERIAL_RESOLVE_FRAG_WGSL, };
 export { BLOOM_PREFILTER_FRAG_WGSL, BLOOM_DOWNSAMPLE_FRAG_WGSL, BLOOM_UPSAMPLE_FRAG_WGSL };
 export { RUSH_UNIFORMS, RUSH_TEXTURES };
 export const AO_UNIFORMS = AO_BINDINGS.AO_FRAG.uniforms;

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

@@ -0,0 +1,30 @@
+import type { DrawCommand } from './drawCommand.ts';
+/** Both targets' format: linear light and a tint, which an eight-bit target would clip and band. */
+export declare const REFLECTION_SURFACE_FORMAT: GPUTextureFormat;
+export declare class ReflectionSurfacePass {
+    private readonly device;
+    private readonly commands;
+    private probe;
+    private tint;
+    /** The environment as the frame shows it, and the roughness in alpha. */
+    probeView: GPUTextureView | null;
+    /** What a found reflection is multiplied by. */
+    tintView: GPUTextureView | null;
+    constructor(device: GPUDevice);
+    /** A command for one opaque lit draw's surface half, filled by the caller. */
+    take(): DrawCommand;
+    /** How many draws the frame kept. */
+    get kept(): number;
+    /** A new frame keeps nothing yet. */
+    reset(): void;
+    /** The two targets at the frame's size, made again only when it changes. */
+    size(width: number, height: number): void;
+    /**
+     * 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: GPUCommandEncoder, depth: GPUTextureView, issue: (pass: GPURenderPassEncoder, command: DrawCommand) => void): void;
+    release(): void;
+}

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;
+    }
+}