@driftengine/core 4.8.6 → 4.9.0

package/src/render/backend/webgl2/sceneCaptureTarget.ts

@@ -0,0 +1,130 @@
+import { glSceneDepthFormat } from '../../depthConvention.ts';
+import type { SurfaceTexture } from '../../surfaceTexture.ts';
+
+/**
+ * A scene capture's framebuffers on WebGL2: the capture's own texture as the colour a pass resolves
+ * into, and a depth of its own, at the capture's size. See `sceneCapture.ts` for what a capture is.
+ *
+ * **At the frame's sample count, as WebGPU's is**, so a capture's edges are antialiased exactly as
+ * the frame's are: drawn into multisampled renderbuffers and blitted into the texture at the end,
+ * since a texture layer cannot be multisampled and sampled both. A count the driver refuses falls
+ * back to one, as the scene target's does, rather than drawing nothing.
+ */
+export class GlSceneCaptureTarget {
+  /** Where the capture resolves: its texture's layer, and a depth when it is drawn into directly. */
+  private readonly resolveFramebuffer: WebGLFramebuffer;
+  private readonly resolveDepth: WebGLRenderbuffer;
+  /** Where it is drawn above one sample, or null. */
+  private multisampleFramebuffer: WebGLFramebuffer | null = null;
+  private multisampleColor: WebGLRenderbuffer | null = null;
+  private multisampleDepth: WebGLRenderbuffer | null = null;
+  /** False where the driver refused the attachment, said once by the renderer. */
+  readonly usable: boolean;
+
+  constructor(
+    gl: WebGL2RenderingContext,
+    texture: SurfaceTexture,
+    readonly width: number,
+    readonly height: number,
+    samples: number,
+    float: boolean,
+  ) {
+    const depthFormat = glSceneDepthFormat(gl).internalFormat;
+    this.resolveFramebuffer = must(gl.createFramebuffer());
+    this.resolveDepth = must(gl.createRenderbuffer());
+    gl.bindRenderbuffer(gl.RENDERBUFFER, this.resolveDepth);
+    gl.renderbufferStorage(gl.RENDERBUFFER, depthFormat, width, height);
+    gl.bindFramebuffer(gl.FRAMEBUFFER, this.resolveFramebuffer);
+    texture.attachColor(gl);
+    gl.framebufferRenderbuffer(
+      gl.FRAMEBUFFER,
+      gl.DEPTH_ATTACHMENT,
+      gl.RENDERBUFFER,
+      this.resolveDepth,
+    );
+    this.usable = gl.checkFramebufferStatus(gl.FRAMEBUFFER) === gl.FRAMEBUFFER_COMPLETE;
+
+    const maximum = gl.getParameter(gl.MAX_SAMPLES) as number;
+    const count = Math.max(
+      1,
+      Math.min(Math.round(samples), Number.isFinite(maximum) ? maximum : 1),
+    );
+    if (this.usable && count > 1) {
+      const color = must(gl.createRenderbuffer());
+      const depth = must(gl.createRenderbuffer());
+      gl.bindRenderbuffer(gl.RENDERBUFFER, color);
+      gl.renderbufferStorageMultisample(
+        gl.RENDERBUFFER,
+        count,
+        float ? gl.RGBA16F : gl.RGBA8,
+        width,
+        height,
+      );
+      gl.bindRenderbuffer(gl.RENDERBUFFER, depth);
+      gl.renderbufferStorageMultisample(gl.RENDERBUFFER, count, depthFormat, width, height);
+      const framebuffer = must(gl.createFramebuffer());
+      gl.bindFramebuffer(gl.FRAMEBUFFER, framebuffer);
+      gl.framebufferRenderbuffer(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.RENDERBUFFER, color);
+      gl.framebufferRenderbuffer(gl.FRAMEBUFFER, gl.DEPTH_ATTACHMENT, gl.RENDERBUFFER, depth);
+      if (gl.checkFramebufferStatus(gl.FRAMEBUFFER) === gl.FRAMEBUFFER_COMPLETE) {
+        this.multisampleFramebuffer = framebuffer;
+        this.multisampleColor = color;
+        this.multisampleDepth = depth;
+      } else {
+        gl.deleteFramebuffer(framebuffer);
+        gl.deleteRenderbuffer(color);
+        gl.deleteRenderbuffer(depth);
+      }
+    }
+    gl.bindRenderbuffer(gl.RENDERBUFFER, null);
+    gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+  }
+
+  /** Bind where the pass draws, size the viewport and clear: colour to `clear`, depth to `depthClear`. */
+  begin(
+    gl: WebGL2RenderingContext,
+    clear: readonly [number, number, number],
+    depthClear: number,
+  ): void {
+    gl.bindFramebuffer(gl.FRAMEBUFFER, this.multisampleFramebuffer ?? this.resolveFramebuffer);
+    gl.viewport(0, 0, this.width, this.height);
+    gl.clearColor(clear[0], clear[1], clear[2], 1);
+    gl.clearDepth(depthClear);
+    gl.depthMask(true);
+    gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT);
+  }
+
+  /** Resolve the multisampled colour into the texture, where there is any. */
+  end(gl: WebGL2RenderingContext): void {
+    if (this.multisampleFramebuffer === null) return;
+    gl.bindFramebuffer(gl.READ_FRAMEBUFFER, this.multisampleFramebuffer);
+    gl.bindFramebuffer(gl.DRAW_FRAMEBUFFER, this.resolveFramebuffer);
+    gl.blitFramebuffer(
+      0,
+      0,
+      this.width,
+      this.height,
+      0,
+      0,
+      this.width,
+      this.height,
+      gl.COLOR_BUFFER_BIT,
+      gl.NEAREST,
+    );
+    gl.bindFramebuffer(gl.READ_FRAMEBUFFER, null);
+    gl.bindFramebuffer(gl.DRAW_FRAMEBUFFER, null);
+  }
+
+  dispose(gl: WebGL2RenderingContext): void {
+    gl.deleteFramebuffer(this.resolveFramebuffer);
+    gl.deleteRenderbuffer(this.resolveDepth);
+    if (this.multisampleFramebuffer !== null) gl.deleteFramebuffer(this.multisampleFramebuffer);
+    if (this.multisampleColor !== null) gl.deleteRenderbuffer(this.multisampleColor);
+    if (this.multisampleDepth !== null) gl.deleteRenderbuffer(this.multisampleDepth);
+  }
+}
+
+function must<T>(made: T | null): T {
+  if (made === null) throw new Error('GlSceneCaptureTarget: a GL object could not be created');
+  return made;
+}

package/src/render/backend/webgpu/device.ts

@@ -7,6 +7,14 @@
  * reset the page did not cause, and a frame is wrong because of something the frame did.
  */
 
+import type { DisplayRange, DisplayRangeChoice } from '../../displayRange.ts';
+
+/** A canvas nobody asked to extend. */
+const STANDARD_RANGE: DisplayRangeChoice = {
+  range: 'standard',
+  reason: 'highDynamicRange was not asked for',
+};
+
 /** What the renderer needs from the canvas it draws into, with the API's shape absorbed. */
 export interface GpuSurface {
   readonly device: GPUDevice;
@@ -22,6 +30,9 @@ export interface GpuSurface {
   readonly canvas: HTMLCanvasElement;
   /** The swap chain's format, which every render pipeline has to be built against. */
   readonly format: GPUTextureFormat;
+  /** The range the canvas was configured in, and why. See `displayRange.ts`. */
+  readonly displayRange: DisplayRange;
+  readonly displayRangeReason: string;
   /** Whether the device has gone. Read per frame; never throws. */
   readonly lost: boolean;
   /** Called when the device is lost. Fires immediately if it already has been. */
@@ -51,13 +62,27 @@ export interface GpuSurface {
  * consumer its GPU had failed every time it unmounted a canvas on purpose, so a disposed
  * surface stays silent.
  */
-export function createGpuSurface(canvas: HTMLCanvasElement, device: GPUDevice): GpuSurface {
+export function createGpuSurface(
+  canvas: HTMLCanvasElement,
+  device: GPUDevice,
+  /** The range the profile and the display allow (`chooseDisplayRange`); standard unless given. */
+  wanted: DisplayRangeChoice = STANDARD_RANGE,
+): GpuSurface {
   const context = canvas.getContext('webgpu') as GPUCanvasContext | null;
   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: GPUTextureFormat = extended
+    ? 'rgba16float'
+    : navigator.gpu.getPreferredCanvasFormat();
+  let range: DisplayRangeChoice = wanted;
   const listeners: (() => void)[] = [];
   let lost = false;
   let disposed = false;
@@ -115,16 +140,30 @@ export function createGpuSurface(canvas: HTMLCanvasElement, device: GPUDevice):
      * 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/src/render/backend/webgpu/flatPass.ts

@@ -12,6 +12,7 @@ import type { LitSwitch, PipelineCache } from './pipelineCache.ts';
 import type { ClothViews } from './clothTextures.ts';
 import { shaderModule } from './shaderModules.ts';
 import { SCENE_ALPHA_COVERS } from '../../sceneCoverage.ts';
+import { REFLECTION_SURFACE_FORMAT } from './reflectionSurfacePass.ts';
 
 /** The material maps the flat pass reads: `2d-array` colour, filtered, not shadow maps. */
 const SURFACE_MAPS: ReadonlySet<string> = new Set([
@@ -232,6 +233,26 @@ export const FLAT_VERT_SIZE = Math.max(
 );
 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(): { readonly textures: number; readonly samplers: number } {
+  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 as { textures?: Record<string, { sampler: number }> }).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: FlatVariant): StageBindings {
   const found = FRAGMENT_BINDINGS[variant];
@@ -253,6 +274,7 @@ function flatFragmentConstants(
   cache: PipelineCache,
   model: SurfaceModelKind | null,
   skinPass: SkinHalf = 'whole',
+  reflectionSurface = false,
 ): Record<string, number> {
   const overrides = flatFragmentBindings(variant).overrides;
   if (overrides?.['GLASS_SHADOWS'] === undefined) {
@@ -271,6 +293,11 @@ function flatFragmentConstants(
       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`);
     }
@@ -609,6 +636,11 @@ export function flatPipeline(
   model: SurfaceModelKind | null = null,
   /** Which half of a skin it draws. The key must carry it: `|ss`, `|sd` or `|sa`. See `SkinHalf`. */
   skinPass: SkinHalf = '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,
 ): GPURenderPipeline {
   return cache.get(
     key,
@@ -633,6 +665,7 @@ export function flatPipeline(
         cloth,
         model,
         skinPass,
+        reflectionSurface,
       ),
     true,
   );
@@ -765,10 +798,12 @@ function flatDescriptor(
   cloth = false,
   model: SurfaceModelKind | null = null,
   skinPass: SkinHalf = 'whole',
+  reflectionSurface = false,
 ): GPURenderPipelineDescriptor {
   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] }),
@@ -798,31 +833,33 @@ function flatDescriptor(
       }),
       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
-              ? {
-                  format: cache.format,
-                  blend: {
-                    color: {
-                      srcFactor: 'src-alpha',
-                      dstFactor: 'one-minus-src-alpha',
-                      operation: 'add',
+      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', operation: 'add' },
+                      alpha: { srcFactor: 'zero', dstFactor: 'one', operation: 'add' },
                     },
-                    alpha: SCENE_ALPHA_COVERS,
-                  },
-                }
-              : { 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/src/render/backend/webgpu/particlePass.ts

@@ -3,6 +3,7 @@ import { particleShaders, type ParticleMaterial } from '../../particleMaterial.t
 import { PARTICLE_BINDINGS } from '../../shaders/generated/particle.wgsl.ts';
 import { PARTICLE_BLADES, PARTICLE_INDICES, PARTICLE_VERTS } from '../../shaders/particle.ts';
 import type { ParticleInstances } from '../../particlePool.ts';
+import { DEVICE_PARTICLE_FLOATS } from '../../particlePool.ts';
 import { packSpriteStream, type ParticleBlend, type ParticleFacing } from '../../particleBatch.ts';
 import { createParticleSort, type ParticleSort } from '../../particleSort.ts';
 import { DEPTH_FORMAT } from './flatPass.ts';
@@ -58,7 +59,7 @@ const USAGE_UNIFORM_DST = 0x0040 | 0x0008;
  * Floats per instance, in the order they are packed: position 3, size 1, spin 1, colour 3,
  * alpha 1, age 1, seed 1, velocity 3, and a sprite's frame and half-height 2.
  */
-const INSTANCE_FLOATS = 16;
+const INSTANCE_FLOATS = DEVICE_PARTICLE_FLOATS;
 
 const INSTANCE_ATTRIBUTES: GPUVertexAttribute[] = [
   { shaderLocation: 2, offset: 0, format: 'float32x3' },

package/src/render/backend/webgpu/postPass.ts

@@ -29,6 +29,7 @@ import {
 } from '../../shaders/generated/ssrTrace.wgsl.ts';
 import {
   SSRRESOLVE_BINDINGS as SSR_RESOLVE_BINDINGS,
+  SSR_MATERIAL_RESOLVE_FRAG_WGSL,
   SSR_RESOLVE_FRAG_WGSL,
 } from '../../shaders/generated/ssrResolve.wgsl.ts';
 import {
@@ -331,6 +332,16 @@ export const REFLECTION_OVER_BLEND: GPUBlendState = {
   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: GPUBlendState = {
+  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
@@ -450,6 +461,12 @@ 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: UniformFields =
+  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.
@@ -513,6 +530,7 @@ export {
   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 };

package/src/render/backend/webgpu/reflectionSurfacePass.ts

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