@driftengine/core 4.8.7 → 4.9.0

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

@@ -6,6 +6,11 @@
  * split matters because these two fail for unrelated reasons: a device is lost by a driver
  * reset the page did not cause, and a frame is wrong because of something the frame did.
  */
+/** A canvas nobody asked to extend. */
+const STANDARD_RANGE = {
+    range: 'standard',
+    reason: 'highDynamicRange was not asked for',
+};
 /**
  * Take a canvas and a device, and hand back the surface the renderer draws into.
  *
@@ -25,12 +30,23 @@
  * consumer its GPU had failed every time it unmounted a canvas on purpose, so a disposed
  * surface stays silent.
  */
-export function createGpuSurface(canvas, device) {
+export function createGpuSurface(canvas, device, 
+/** The range the profile and the display allow (`chooseDisplayRange`); standard unless given. */
+wanted = STANDARD_RANGE) {
     const context = canvas.getContext('webgpu');
     if (context === null) {
         throw new Error('createGpuSurface: the canvas would not give a webgpu context');
     }
-    const format = navigator.gpu.getPreferredCanvasFormat();
+    /*
+     * **A high range is half floats with extended tone mapping**: a value of 1 is the display's
+     * paper white, and what lies above it is shown up to the display's peak instead of clipped. The
+     * colour space stays sRGB, so the composite's encoding is the one it always wrote, carried past 1.
+     */
+    const extended = wanted.range === 'high';
+    const format = extended
+        ? 'rgba16float'
+        : navigator.gpu.getPreferredCanvasFormat();
+    let range = wanted;
     const listeners = [];
     let lost = false;
     let disposed = false;
@@ -89,14 +105,26 @@ export function createGpuSurface(canvas, device) {
          * has no use for a transparent canvas, and the opaque path is the one a compositor can
          * take without a blend.
          */
-        context.configure({ device, format, alphaMode: 'opaque' });
+        context.configure(extended
+            ? { device, format, alphaMode: 'opaque', toneMapping: { mode: 'extended' } }
+            : { device, format, alphaMode: 'opaque' });
     };
     configure(canvas.width, canvas.height);
+    /*
+     * **Read back, because a browser that does not know the option ignores it** and draws the
+     * standard range from an extended-range frame, clipped at paper white, which is the frame a game
+     * would grade for the standard range if it knew. So it is told.
+     */
+    if (extended && context.getConfiguration?.()?.toneMapping?.mode !== 'extended') {
+        range = { range: 'standard', reason: 'this browser has no extended-range canvas' };
+    }
     return {
         device,
         context,
         canvas,
         format,
+        displayRange: range.range,
+        displayRangeReason: range.reason,
         get lost() {
             return lost;
         },

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

@@ -147,6 +147,16 @@ export declare const FLAT_VERT_FIELDS: {
  * 144 bytes a slot and is what a single ring costs.
  */
 export declare const FLAT_VERT_SIZE: number;
+/**
+ * The most sampled textures and distinct samplers any lit variant carrying the environment probe
+ * binds in its fragment stage, counted from the generated bindings: what a device must allow per
+ * stage before the probe's permutation can be built. A sampler several textures share counts once,
+ * which is what `// wgsl:share` buys.
+ */
+export declare function probeStageCeilings(): {
+    readonly textures: number;
+    readonly samplers: number;
+};
 /** Everything the generator recorded about one permutation of the fragment stage. */
 export declare function flatFragmentBindings(variant: FlatVariant): StageBindings;
 /** The depth format both backends compare with. */
@@ -236,7 +246,12 @@ cloth?: boolean,
 /** Which shading model its fragment stage shades by, null the standard. The key must carry it. */
 model?: SurfaceModelKind | null, 
 /** Which half of a skin it draws. The key must carry it: `|ss`, `|sd` or `|sa`. See `SkinHalf`. */
-skinPass?: SkinHalf): GPURenderPipeline;
+skinPass?: SkinHalf, 
+/**
+ * The reflection pass's surface half: the draw again, against its own depth, into the two
+ * targets `reflectionSurfacePass.ts` holds. The key must carry it: `|rs`.
+ */
+reflectionSurface?: boolean): GPURenderPipeline;
 /**
  * The same pipeline, compiled off the main thread.
  *

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

@@ -5,6 +5,7 @@ import { FLAT_BINDINGS, FLAT_FRAG_WGSL, FLAT_VERT_WGSL, } from '../../shaders/ge
 import { vertexBufferLayouts } from './buffers.js';
 import { shaderModule } from './shaderModules.js';
 import { SCENE_ALPHA_COVERS } from '../../sceneCoverage.js';
+import { REFLECTION_SURFACE_FORMAT } from './reflectionSurfacePass.js';
 /** The material maps the flat pass reads: `2d-array` colour, filtered, not shadow maps. */
 const SURFACE_MAPS = new Set([
     'uAlbedo',
@@ -144,6 +145,24 @@ export const FLAT_VERT_FIELDS = FLAT_BINDINGS.flatVert.none.fields;
  */
 export const FLAT_VERT_SIZE = Math.max(...Object.values(VERTEX_BINDINGS).map((bindings) => bindings.uniformSize));
 const FLAT_VERT_BINDING = PLAIN_VERTEX.uniforms;
+/**
+ * The most sampled textures and distinct samplers any lit variant carrying the environment probe
+ * binds in its fragment stage, counted from the generated bindings: what a device must allow per
+ * stage before the probe's permutation can be built. A sampler several textures share counts once,
+ * which is what `// wgsl:share` buys.
+ */
+export function probeStageCeilings() {
+    let textures = 0;
+    let samplers = 0;
+    for (const [variant, bindings] of Object.entries(FLAT_BINDINGS.flatFrag)) {
+        if (!variant.includes('environmentProbe'))
+            continue;
+        const listed = Object.values(bindings.textures ?? {});
+        textures = Math.max(textures, listed.length);
+        samplers = Math.max(samplers, new Set(listed.map((entry) => entry.sampler)).size);
+    }
+    return { textures, samplers };
+}
 /** Everything the generator recorded about one permutation of the fragment stage. */
 export function flatFragmentBindings(variant) {
     const found = FRAGMENT_BINDINGS[variant];
@@ -160,7 +179,7 @@ export function flatFragmentBindings(variant) {
  * "GLASS_SHADOWS" not found*, and the frame drew nothing. Every override the variant declares is
  * set, so a switch added to the shader and not to the cache is refused here rather than defaulted.
  */
-function flatFragmentConstants(variant, cache, model, skinPass = 'whole') {
+function flatFragmentConstants(variant, cache, model, skinPass = 'whole', reflectionSurface = false) {
     const overrides = flatFragmentBindings(variant).overrides;
     if (overrides?.['GLASS_SHADOWS'] === undefined) {
         throw new Error(`flatPass: variant "${variant}" has no glass switch`);
@@ -178,6 +197,11 @@ function flatFragmentConstants(variant, cache, model, skinPass = 'whole') {
             constants[String(id)] = skinPass !== 'whole' && name === SKIN_HALF_SWITCH[skinPass] ? 1 : 0;
             continue;
         }
+        /* The reflection pass's surface half, set from the key too. See `reflectionSurface.ts`. */
+        if (name === 'REFLECTION_SURFACE') {
+            constants[String(id)] = reflectionSurface ? 1 : 0;
+            continue;
+        }
         if (!(name in cache.litSwitches)) {
             throw new Error(`flatPass: variant "${variant}" declares a switch "${name}" no cache sets`);
         }
@@ -481,8 +505,13 @@ cloth = false,
 /** Which shading model its fragment stage shades by, null the standard. The key must carry it. */
 model = null, 
 /** Which half of a skin it draws. The key must carry it: `|ss`, `|sd` or `|sa`. See `SkinHalf`. */
-skinPass = 'whole') {
-    return cache.get(key, () => flatDescriptor(cache, device, layout, variant, key, present, translucent, skinned, morphed, depthWrite, depthLayer, instanced, oit, doubleSided, alphaToCoverage, skinEight, cloth, model, skinPass), true);
+skinPass = 'whole', 
+/**
+ * The reflection pass's surface half: the draw again, against its own depth, into the two
+ * targets `reflectionSurfacePass.ts` holds. The key must carry it: `|rs`.
+ */
+reflectionSurface = false) {
+    return cache.get(key, () => flatDescriptor(cache, device, layout, variant, key, present, translucent, skinned, morphed, depthWrite, depthLayer, instanced, oit, doubleSided, alphaToCoverage, skinEight, cloth, model, skinPass, reflectionSurface), true);
 }
 /**
  * The same pipeline, compiled off the main thread.
@@ -562,10 +591,11 @@ oit = 'none',
 /** Culls nothing: a surface seen from both faces. */
 doubleSided = false, alphaToCoverage = false, skinEight = false, 
 /** Whether its vertex stage places vertices by a cloth binding. See `clothBinding.ts`. */
-cloth = false, model = null, skinPass = 'whole') {
+cloth = false, model = null, skinPass = 'whole', reflectionSurface = false) {
     const offset = depthOffsetForLayer(depthLayer);
-    /* The diffuse and colour halves are the same surface again, into the blur's targets. */
-    const diffuseAlone = skinPass === 'diffuse' || skinPass === 'albedo';
+    /* The diffuse and colour halves are the same surface again, into the blur's targets; and so is
+       the reflection pass's surface half, into its two. */
+    const diffuseAlone = skinPass === 'diffuse' || skinPass === 'albedo' || reflectionSurface;
     return {
         label: key,
         layout: device.createPipelineLayout({ bindGroupLayouts: [layout] }),
@@ -590,31 +620,33 @@ cloth = false, model = null, skinPass = 'whole') {
             }),
             entryPoint: 'main',
             /* Every variant declares it, so every lit pipeline may set it: see `PipelineCache`. */
-            constants: flatFragmentConstants(variant, cache, model, skinPass),
-            targets: [
-                oitTarget(oit) ??
-                    (translucent === 'additive'
-                        ? {
-                            format: cache.format,
-                            blend: {
-                                color: { srcFactor: 'src-alpha', dstFactor: 'one', operation: 'add' },
-                                alpha: { srcFactor: 'zero', dstFactor: 'one', operation: 'add' },
-                            },
-                        }
-                        : translucent
+            constants: flatFragmentConstants(variant, cache, model, skinPass, reflectionSurface),
+            targets: reflectionSurface
+                ? [null, { format: REFLECTION_SURFACE_FORMAT }, { format: REFLECTION_SURFACE_FORMAT }]
+                : [
+                    oitTarget(oit) ??
+                        (translucent === 'additive'
                             ? {
                                 format: cache.format,
                                 blend: {
-                                    color: {
-                                        srcFactor: 'src-alpha',
-                                        dstFactor: 'one-minus-src-alpha',
-                                        operation: 'add',
-                                    },
-                                    alpha: SCENE_ALPHA_COVERS,
+                                    color: { srcFactor: 'src-alpha', dstFactor: 'one', operation: 'add' },
+                                    alpha: { srcFactor: 'zero', dstFactor: 'one', operation: 'add' },
                                 },
                             }
-                            : { format: cache.format }),
-            ],
+                            : translucent
+                                ? {
+                                    format: cache.format,
+                                    blend: {
+                                        color: {
+                                            srcFactor: 'src-alpha',
+                                            dstFactor: 'one-minus-src-alpha',
+                                            operation: 'add',
+                                        },
+                                        alpha: SCENE_ALPHA_COVERS,
+                                    },
+                                }
+                                : { format: cache.format }),
+                ],
         },
         primitive: { topology: 'triangle-list', cullMode: doubleSided ? 'none' : 'back' },
         /* Coverage only where a sample count can carry it: WebGPU refuses it at one sample. */

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