@driftengine/core 3.61.0

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

@@ -0,0 +1,174 @@
+import { DEPTH_COMPARE } from '../../depthConvention.ts';
+import {
+  CAUSTICS_BINDINGS,
+  CAUSTICS_FRAG_WGSL,
+  CAUSTICS_VERT_WGSL,
+} from '../../shaders/generated/caustics.wgsl.ts';
+import type { UniformFields } from './scatterPass.ts';
+import { DEPTH_FORMAT } from './flatPass.ts';
+import type { PipelineCache } from './pipelineCache.ts';
+import { shaderModule } from './shaderModules.ts';
+
+/**
+ * The caustics pass: a surface lit by nearby water.
+ *
+ * `causticsRenderer.ts` carries the argument for the feature and for its limits, including why
+ * the ambient term is not decoration and why either side of the water works. The geometry comes
+ * from `buildSheets`, which both backends call, so this owns three buffers and a pipeline.
+ */
+
+export const CAUSTICS_VERT_FIELDS: UniformFields = CAUSTICS_BINDINGS.CAUSTICS_VERT.fields;
+export const CAUSTICS_VERT_SIZE = CAUSTICS_BINDINGS.CAUSTICS_VERT.uniformSize;
+export const CAUSTICS_FRAG_FIELDS: UniformFields = CAUSTICS_BINDINGS.CAUSTICS_FRAG.fields;
+export const CAUSTICS_FRAG_SIZE = CAUSTICS_BINDINGS.CAUSTICS_FRAG.uniformSize;
+
+const VERT_BINDING = CAUSTICS_BINDINGS.CAUSTICS_VERT.uniforms;
+const FRAG_BINDING = CAUSTICS_BINDINGS.CAUSTICS_FRAG.uniforms;
+
+const VISIBILITY_VERTEX = 0x1;
+const VISIBILITY_FRAGMENT = 0x2;
+const USAGE_VERTEX = 0x0020 | 0x0008; // VERTEX | COPY_DST
+
+/** A lit surface on the device, behind the API's opaque handle. */
+export interface GpuCaustics {
+  readonly vertexBuffers: readonly GPUBuffer[];
+  readonly vertexCount: number;
+  dispose(): void;
+}
+
+export function createGpuCaustics(
+  device: GPUDevice,
+  positions: Float32Array,
+  locals: Float32Array,
+  params: Float32Array,
+  vertexCount: number,
+): GpuCaustics {
+  const upload = (data: Float32Array, label: string): GPUBuffer => {
+    const buffer = device.createBuffer({
+      label,
+      size: Math.max(4, data.byteLength),
+      usage: USAGE_VERTEX,
+    });
+    device.queue.writeBuffer(buffer, 0, data);
+    return buffer;
+  };
+  const buffers = [
+    upload(positions, 'caustics.rest'),
+    upload(locals, 'caustics.local'),
+    upload(params, 'caustics.params'),
+  ];
+  return {
+    vertexBuffers: buffers,
+    vertexCount,
+    dispose(): void {
+      for (const buffer of buffers) buffer.destroy();
+    },
+  };
+}
+
+/** `aRest`, `aLocal`, `aParams` — three arrays on both sides, so three buffers. */
+export function causticsVertexLayouts(): GPUVertexBufferLayout[] {
+  return [
+    {
+      arrayStride: 12,
+      attributes: [{ shaderLocation: 0, offset: 0, format: 'float32x3' as GPUVertexFormat }],
+    },
+    {
+      arrayStride: 8,
+      attributes: [{ shaderLocation: 1, offset: 0, format: 'float32x2' as GPUVertexFormat }],
+    },
+    {
+      arrayStride: 8,
+      attributes: [{ shaderLocation: 2, offset: 0, format: 'float32x2' as GPUVertexFormat }],
+    },
+  ];
+}
+
+export function createCausticsBindGroupLayout(device: GPUDevice): GPUBindGroupLayout {
+  return device.createBindGroupLayout({
+    label: 'caustics.layout',
+    entries: [
+      /*
+       * **Addressed by a dynamic offset, so a frame can draw more than one batch.**
+       *
+       * With one buffer rewritten between draws, every batch reads whatever was written last:
+       * `queue.write*` calls are ordered on the queue timeline and the encoder is submitted after
+       * every one of them. The picture is each batch wearing the last one's colour, width, time
+       * and placement. That is the hazard `UniformRing` exists for, recorded in `AGENTS.md` on
+       * 2026-08-27, and this pass was one of four still carrying it — invisible for as long as
+       * nothing drew two, which is exactly how water kept it for eight releases.
+       *
+       * WebGL2 needs none of this: it sets uniforms and draws in one stream.
+       */
+      {
+        binding: VERT_BINDING,
+        visibility: VISIBILITY_VERTEX,
+        buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: CAUSTICS_VERT_SIZE },
+      },
+      {
+        binding: FRAG_BINDING,
+        visibility: VISIBILITY_FRAGMENT,
+        buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: CAUSTICS_FRAG_SIZE },
+      },
+    ],
+  });
+}
+
+export function createCausticsBindGroup(
+  device: GPUDevice,
+  layout: GPUBindGroupLayout,
+  vertices: GPUBuffer,
+  fragments: GPUBuffer,
+): GPUBindGroup {
+  return device.createBindGroup({
+    label: 'caustics.bindGroup',
+    layout,
+    entries: [
+      { binding: VERT_BINDING, resource: { buffer: vertices, size: CAUSTICS_VERT_SIZE } },
+      { binding: FRAG_BINDING, resource: { buffer: fragments, size: CAUSTICS_FRAG_SIZE } },
+    ],
+  });
+}
+
+/**
+ * The pipeline.
+ *
+ * **Added, not blended over**, because this is light arriving at a surface rather than the
+ * surface: `gl.blendFunc(ONE, ONE)` on the other backend. Nothing culled, because a sheet is
+ * seen from either side — a pool floor from above and a soffit from below.
+ *
+ * **Depth tested and depth not written**, and the test is the part that matters:
+ * `causticsRenderer.ts` records that the sheet sits a couple of centimetres under the surface it
+ * lights, so geometry in front of it — a character, a lamp, a parapet — still occludes the light.
+ */
+export function causticsPipeline(
+  cache: PipelineCache,
+  device: GPUDevice,
+  layout: GPUBindGroupLayout,
+): GPURenderPipeline {
+  return cache.get('caustics', () => ({
+    label: 'caustics',
+    layout: device.createPipelineLayout({ bindGroupLayouts: [layout] }),
+    vertex: {
+      module: shaderModule(device, { label: 'caustics.vert', code: CAUSTICS_VERT_WGSL }),
+      entryPoint: 'main',
+      buffers: causticsVertexLayouts(),
+    },
+    fragment: {
+      module: shaderModule(device, { label: 'caustics.frag', code: CAUSTICS_FRAG_WGSL }),
+      entryPoint: 'main',
+      targets: [
+        {
+          format: cache.format,
+          blend: {
+            color: { srcFactor: 'one', dstFactor: 'one', operation: 'add' },
+            alpha: { srcFactor: 'one', dstFactor: 'one', operation: 'add' },
+          },
+        },
+      ],
+    },
+    primitive: { topology: 'triangle-list', cullMode: 'none' },
+    multisample: { count: cache.sampleCount },
+    depthStencil: { format: DEPTH_FORMAT, depthWriteEnabled: false, depthCompare: DEPTH_COMPARE },
+  }));
+}

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

@@ -0,0 +1,259 @@
+import {
+  CLUSTER_COUNT,
+  LIGHT_RECORD,
+  LIGHT_TEXELS,
+  NO_IES_PROFILE,
+  POINT_LIGHT_COS_INNER,
+  POINT_LIGHT_COS_OUTER,
+  MAX_CLUSTERED_LIGHTS,
+  TABLE_HEIGHT,
+  TABLE_WIDTH,
+  type ClusterLightSet,
+} from '../../clusteredLights.ts';
+import { MAX_POINT_LIGHTS } from '../../lightBudget.ts';
+import type { ComputeContext, ComputeDefinition, ComputeDevice } from '../../compute.ts';
+import { CLUSTER_BIN_WGSL } from './shaders/clusterBin.wgsl.ts';
+
+/**
+ * The froxel binner on the GPU: the first thing in this engine to dispatch compute.
+ *
+ * **What it replaces is not a slow thing, it is a thing on the wrong processor.** The CPU binner
+ * in `clusteredLights.ts` is measured at 0.386 ms a frame for sixteen lights and 2.0 ms for 256,
+ * and 2 ms is 12% of a 60 fps frame spent on the main thread where a consumer's own game logic
+ * lives. On WebGL2 there is nowhere else to put it. Here there is.
+ *
+ * **It writes the same table, and that is asserted rather than assumed.** `scripts/cluster-check.mjs`
+ * runs both binners over one camera and one light set and compares the tables, because the
+ * 2026-08-17 rule says two implementations of one decision drift invisibly when their constants
+ * agree — which is exactly the situation this is.
+ */
+
+/*
+ * WebGPU usage flags, named rather than read off the globals, for the reason `buffers.ts` gives:
+ * the values are normative in the specification and the globals do not exist outside a browser.
+ */
+const BUFFER_USAGE = {
+  COPY_DST: 0x0008,
+  UNIFORM: 0x0040,
+  STORAGE: 0x0080,
+} as const;
+
+const TEXTURE_USAGE = {
+  COPY_SRC: 0x01,
+  TEXTURE_BINDING: 0x04,
+  STORAGE_BINDING: 0x08,
+} as const;
+
+/** `mat4` plus a `vec4` plus four `u32`, which is 96 bytes and already 16-byte aligned. */
+const PARAMS_BYTES = 16 * 4 + 4 * 4 + 4 * 4;
+
+/** Invocations a workgroup, matching `@workgroup_size` in the shader. */
+const WORKGROUP = 64;
+
+/** What the caller sets before each dispatch. Held rather than passed, so `dispatch` allocates none. */
+export interface ClusterBinnerFrame {
+  lights: ClusterLightSet;
+  /** Column-major, as gl-matrix builds it. */
+  view: Float32Array;
+  near: number;
+  far: number;
+  tanHalfFovY: number;
+  aspect: number;
+  /** How many shadow uniform slots are live. See `LIGHT_TEXELS` in `clusteredLights.ts`. */
+  shadowSlots: number;
+}
+
+export class ClusterBinner {
+  /** The table the lit pass samples. Written by the dispatch, never by the CPU on this backend. */
+  private texture: GPUTexture | null = null;
+  private view: GPUTextureView | null = null;
+  private pipeline: GPUComputePipeline | null = null;
+  private group: GPUBindGroup | null = null;
+  private params: GPUBuffer | null = null;
+  private lightBuffer: GPUBuffer | null = null;
+  private device: GPUDevice | null = null;
+
+  /** Staging for the two uploads, allocated once: `dispatch` is a per-frame path. */
+  private readonly paramsStaging = new ArrayBuffer(PARAMS_BYTES);
+  private readonly paramsFloats = new Float32Array(this.paramsStaging);
+  private readonly paramsUints = new Uint32Array(this.paramsStaging);
+  private readonly lightStaging = new Float32Array(MAX_CLUSTERED_LIGHTS * LIGHT_TEXELS * 4);
+
+  private frame: ClusterBinnerFrame | null = null;
+
+  /** The table's view, for whoever binds it into the lit pass. Null before `init`. */
+  get tableView(): GPUTextureView | null {
+    return this.view;
+  }
+
+  /** The table itself, which a readback needs and the lit pass does not. */
+  get tableTexture(): GPUTexture | null {
+    return this.texture;
+  }
+
+  /**
+   * The device `init` was handed, for a caller that needs to encode a copy of its own.
+   *
+   * **Exposed rather than fetched from somewhere else**, because there is nowhere else: a
+   * `GPUTexture` does not name its device and `createRenderer` does not return one. The seam
+   * hands a definition the device precisely so it can do work of its own outside a dispatch, and
+   * a readback is that work.
+   */
+  get gpuDevice(): GPUDevice | null {
+    return this.device;
+  }
+
+  /** What the next dispatch bins. Set per frame; nothing is copied until `dispatch`. */
+  setFrame(frame: ClusterBinnerFrame): void {
+    this.frame = frame;
+  }
+
+  definition(): ComputeDefinition {
+    return {
+      label: 'lights.bin',
+      init: (device: ComputeDevice) => this.build(device.device),
+      dispatch: (ctx: ComputeContext) => this.run(ctx),
+      dispose: () => this.release(),
+    };
+  }
+
+  private build(device: GPUDevice): void {
+    this.device = device;
+    this.texture = device.createTexture({
+      label: 'lights.clusterTable',
+      size: [TABLE_WIDTH, TABLE_HEIGHT],
+      /*
+       * `rgba32uint` because the indices are integers and an integer is what a texture carries
+       * exactly. It is also one of core WebGPU's storage-capable formats, which is what lets the
+       * dispatch write it at all — and `texelFetch` reads the same format on WebGL2, which is the
+       * whole reason the interface between binning and shading is a texture.
+       */
+      format: 'rgba32uint',
+      usage: TEXTURE_USAGE.STORAGE_BINDING | TEXTURE_USAGE.TEXTURE_BINDING | TEXTURE_USAGE.COPY_SRC,
+    });
+    this.view = this.texture.createView({ label: 'lights.clusterTable' });
+
+    this.params = device.createBuffer({
+      label: 'lights.bin.params',
+      size: PARAMS_BYTES,
+      usage: BUFFER_USAGE.UNIFORM | BUFFER_USAGE.COPY_DST,
+    });
+    this.lightBuffer = device.createBuffer({
+      label: 'lights.bin.lights',
+      size: this.lightStaging.byteLength,
+      usage: BUFFER_USAGE.STORAGE | BUFFER_USAGE.COPY_DST,
+    });
+
+    this.pipeline = device.createComputePipeline({
+      label: 'lights.bin',
+      layout: 'auto',
+      compute: {
+        module: device.createShaderModule({ label: 'lights.bin', code: CLUSTER_BIN_WGSL }),
+        entryPoint: 'main',
+      },
+    });
+    this.group = device.createBindGroup({
+      label: 'lights.bin',
+      layout: this.pipeline.getBindGroupLayout(0),
+      entries: [
+        { binding: 0, resource: { buffer: this.params } },
+        { binding: 1, resource: { buffer: this.lightBuffer } },
+        { binding: 2, resource: this.view },
+      ],
+    });
+  }
+
+  private run(ctx: ComputeContext): void {
+    const frame = this.frame;
+    const { device, pipeline, group, params, lightBuffer } = this;
+    if (frame === null || device === null || pipeline === null || group === null) return;
+    if (params === null || lightBuffer === null) return;
+
+    const count = Math.min(frame.lights.count, MAX_CLUSTERED_LIGHTS);
+
+    /*
+     * The records, in exactly the order `buildLightClusters` writes them, because the shader
+     * copies them into the table verbatim and the lit pass reads one layout on both backends.
+     */
+    for (let light = 0; light < count; light++) {
+      const at = light * LIGHT_TEXELS * 4;
+      this.lightStaging[at] = frame.lights.positions[light * 3] ?? 0;
+      this.lightStaging[at + 1] = frame.lights.positions[light * 3 + 1] ?? 0;
+      this.lightStaging[at + 2] = frame.lights.positions[light * 3 + 2] ?? 0;
+      this.lightStaging[at + 3] = frame.lights.radii[light] ?? 0;
+      this.lightStaging[at + 4] = frame.lights.colors[light * 3] ?? 0;
+      this.lightStaging[at + 5] = frame.lights.colors[light * 3 + 1] ?? 0;
+      this.lightStaging[at + 6] = frame.lights.colors[light * 3 + 2] ?? 0;
+      this.lightStaging[at + 7] = frame.lights.sourceRadii[light] ?? 0;
+      this.lightStaging[at + LIGHT_RECORD.weight] = frame.lights.weights[light] ?? 1;
+      this.lightStaging[at + LIGHT_RECORD.shadowSlot] = light < frame.shadowSlots ? light : -1;
+      /*
+       * The cone, addressed through `LIGHT_RECORD` rather than by number. Two writers fill this
+       * record — the CPU binner in `clusteredLights.ts` and this — and the 2026-08-17 rule is that
+       * two implementations of one decision drift invisibly when the constants are identical. They
+       * now read the same table of offsets, so a field can only move in both at once.
+       *
+       * `POINT_LIGHT_COS_OUTER` and its inner twin are what make a light with no cone collapse to
+       * exactly the arithmetic a point light had. `scripts/cluster-check.mjs` compares the two
+       * tables byte for byte and is what would catch this being wrong anyway.
+       */
+      const directions = frame.lights.directions;
+      const cone = frame.lights.coneCos;
+      this.lightStaging[at + LIGHT_RECORD.directionX] = directions?.[light * 3] ?? 0;
+      this.lightStaging[at + LIGHT_RECORD.directionY] = directions?.[light * 3 + 1] ?? 0;
+      this.lightStaging[at + LIGHT_RECORD.directionZ] = directions?.[light * 3 + 2] ?? 0;
+      this.lightStaging[at + LIGHT_RECORD.cosInner] = cone?.[light * 2] ?? POINT_LIGHT_COS_INNER;
+      this.lightStaging[at + LIGHT_RECORD.cosOuter] =
+        cone?.[light * 2 + 1] ?? POINT_LIGHT_COS_OUTER;
+      this.lightStaging[at + LIGHT_RECORD.iesProfile] =
+        frame.lights.iesProfiles?.[light] ?? NO_IES_PROFILE;
+      /* The azimuth reference an asymmetric profile is oriented by; zero where a consumer gave
+         none, which the shader reads as no usable reference and leaves on the first plane. */
+      const axes = frame.lights.iesAxes;
+      this.lightStaging[at + LIGHT_RECORD.iesAxisX] = axes?.[light * 3] ?? 0;
+      this.lightStaging[at + LIGHT_RECORD.iesAxisY] = axes?.[light * 3 + 1] ?? 0;
+      this.lightStaging[at + LIGHT_RECORD.iesAxisZ] = axes?.[light * 3 + 2] ?? 0;
+      this.lightStaging[at + LIGHT_RECORD.cookie] = frame.lights.cookies?.[light] ?? NO_IES_PROFILE;
+    }
+
+    this.paramsFloats.set(frame.view, 0);
+    this.paramsFloats[16] = frame.near;
+    this.paramsFloats[17] = frame.far;
+    this.paramsFloats[18] = frame.tanHalfFovY;
+    this.paramsFloats[19] = frame.aspect;
+    this.paramsUints[20] = count;
+
+    device.queue.writeBuffer(params, 0, this.paramsStaging);
+    device.queue.writeBuffer(
+      lightBuffer,
+      0,
+      this.lightStaging.buffer,
+      0,
+      count * LIGHT_TEXELS * 16,
+    );
+
+    ctx.pass.setPipeline(pipeline);
+    ctx.pass.setBindGroup(0, group);
+    /*
+     * Enough invocations for every cluster. The first `count` of them also write a light record,
+     * which they can because there are always far more clusters than lights.
+     */
+    ctx.pass.dispatchWorkgroups(Math.ceil(CLUSTER_COUNT / WORKGROUP));
+  }
+
+  private release(): void {
+    this.texture?.destroy();
+    this.params?.destroy();
+    this.lightBuffer?.destroy();
+    this.texture = null;
+    this.view = null;
+    this.params = null;
+    this.lightBuffer = null;
+    this.pipeline = null;
+    this.group = null;
+    this.device = null;
+  }
+}
+
+/** The shadow slots a frame has, which is the fixed budget the pool is sized for. */
+export const DEFAULT_SHADOW_SLOTS = MAX_POINT_LIGHTS;

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

@@ -0,0 +1,261 @@
+import {
+  DEPTH_BINDINGS,
+  DEPTH_FRAG_WGSL,
+  DEPTH_INSTANCED_VERT_WGSL,
+  DEPTH_SKINNED_VERT_WGSL,
+  DEPTH_VERT_WGSL,
+} from '../../shaders/generated/depth.wgsl.ts';
+import { vertexBufferLayouts } from './buffers.ts';
+import type { PipelineCache } from './pipelineCache.ts';
+import { shaderModule } from './shaderModules.ts';
+
+/**
+ * The shadow pass: the world drawn from the light, into a depth map.
+ *
+ * **A pass of its own, before the frame.** `beginShadowPass` is called by a scene *before*
+ * `beginFrame`, so this owns its own encoder and its own render pass rather than sharing the
+ * frame's. That ordering is the scene's and is not this backend's to change.
+ */
+
+export const DEPTH_VERT_FIELDS = DEPTH_BINDINGS.DEPTH_VERT.fields;
+export const DEPTH_VERT_SIZE = DEPTH_BINDINGS.DEPTH_VERT.uniformSize;
+export const DEPTH_FRAG_SIZE = DEPTH_BINDINGS.DEPTH_FRAG.uniformSize;
+/** Re-exported so the scatter depth pass can pair with the same fragment stage. */
+export { DEPTH_FRAG_WGSL };
+export const DEPTH_FRAG_BINDING = DEPTH_BINDINGS.DEPTH_FRAG.uniforms;
+export const DEPTH_PREVIOUS_BINDING = DEPTH_BINDINGS.DEPTH_FRAG.textures.uPreviousShadowMap;
+
+const VERT_BINDING = DEPTH_BINDINGS.DEPTH_VERT.uniforms;
+const FRAG_BINDING = DEPTH_BINDINGS.DEPTH_FRAG.uniforms;
+const PREVIOUS = DEPTH_BINDINGS.DEPTH_FRAG.textures.uPreviousShadowMap;
+/** Where the skinned vertex stage reads the joint palette. Generated, not chosen here. */
+export const DEPTH_PALETTE_BINDING = DEPTH_BINDINGS.DEPTH_SKINNED_VERT.textures.uJointPalette;
+
+const VISIBILITY_VERTEX = 0x1;
+const VISIBILITY_FRAGMENT = 0x2;
+
+/**
+ * The format the shadow map is stored in.
+ *
+ * `depth32float` rather than the frame's `depth24plus`, because this one is *sampled* as
+ * well as written and a comparison against a quantised depth is where shadow acne comes
+ * from. It is also the format `shadowMap.ts` asks WebGL2 for, so the two backends compare
+ * the same numbers.
+ */
+export const SHADOW_FORMAT: GPUTextureFormat = 'depth32float';
+
+export function createDepthBindGroupLayout(
+  device: GPUDevice,
+  /**
+   * Whether this layout carries the joint palette.
+   *
+   * A **separate layout** rather than the palette added to the one layout with a stand-in bound
+   * when nothing is skinned, which is the shape `flatLayoutFor` already uses. What it buys is that
+   * the rigid path is untouched: no extra binding, no one-pixel texture to keep alive, and a
+   * frame that skins nothing pays nothing at all.
+   */
+  skinned = false,
+): GPUBindGroupLayout {
+  return device.createBindGroupLayout({
+    label: skinned ? 'depth.layout.skinned' : 'depth.layout',
+    entries: [
+      /* The texture and no sampler: the shader reads the palette with `textureLoad`, an integer
+         coordinate with nothing to filter, which is what `flatPass.ts` binds for the same
+         palette. naga declares a sampler for it and nothing ever reads one. */
+      ...(skinned
+        ? [
+            {
+              binding: DEPTH_PALETTE_BINDING.texture,
+              visibility: VISIBILITY_VERTEX,
+              texture: { sampleType: 'unfilterable-float' as GPUTextureSampleType },
+            },
+          ]
+        : []),
+      {
+        binding: VERT_BINDING,
+        visibility: VISIBILITY_VERTEX,
+        buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: DEPTH_VERT_SIZE },
+      },
+      {
+        binding: FRAG_BINDING,
+        visibility: VISIBILITY_FRAGMENT,
+        buffer: { type: 'uniform', minBindingSize: DEPTH_FRAG_SIZE },
+      },
+      /*
+       * **`unfilterable-float`, because the peel binds `SHADOW_FORMAT` here.**
+       *
+       * The defaults are `sampleType: 'float'` and `type: 'filtering'`, and a `depth32float`
+       * view satisfies neither. The device rejects the pair in as many words — *"None of the
+       * supported sample types (UnfilterableFloat|Depth) of [Texture "shadow.static"] match
+       * the expected sample types (Float)"* — and it rejects it by returning an **invalid
+       * bind group rather than throwing**. A peel pass built on one records nothing, so the
+       * peel map keeps the undefined contents it was created with and the frame still
+       * presents. Three ports of the peel were measured and reverted against that silence.
+       *
+       * The one-pixel `rgba8unorm` stand-in every non-peel frame binds here satisfies this
+       * too — measured, both ways — and the sampler beside it is all-`nearest` already, which
+       * is what `non-filtering` requires. `flatPass.ts` reaches the same declaration from the
+       * name, and `uPreviousShadowMap` is one of the names it would match.
+       */
+      {
+        binding: PREVIOUS.texture,
+        visibility: VISIBILITY_FRAGMENT,
+        texture: { sampleType: 'unfilterable-float' },
+      },
+      {
+        binding: PREVIOUS.sampler,
+        visibility: VISIBILITY_FRAGMENT,
+        sampler: { type: 'non-filtering' },
+      },
+    ],
+  });
+}
+
+export function createDepthBindGroup(
+  device: GPUDevice,
+  layout: GPUBindGroupLayout,
+  perDraw: GPUBuffer,
+  perPass: GPUBuffer,
+  previous: GPUTextureView,
+  sampler: GPUSampler,
+  /** The joint palette, for a layout built with `skinned`. Omit for the rigid layout. */
+  palette: GPUTextureView | null = null,
+): GPUBindGroup {
+  return device.createBindGroup({
+    label: palette === null ? 'depth.bindGroup' : 'depth.bindGroup.skinned',
+    layout,
+    entries: [
+      { binding: VERT_BINDING, resource: { buffer: perDraw, size: DEPTH_VERT_SIZE } },
+      { binding: FRAG_BINDING, resource: { buffer: perPass, size: DEPTH_FRAG_SIZE } },
+      { binding: PREVIOUS.texture, resource: previous },
+      { binding: PREVIOUS.sampler, resource: sampler },
+      ...(palette !== null ? [{ binding: DEPTH_PALETTE_BINDING.texture, resource: palette }] : []),
+    ],
+  });
+}
+
+/**
+ * The depth pipeline.
+ *
+ * **No colour target at all.** The pass writes depth and nothing else, which is what makes
+ * it cheap; a colour attachment here would be a buffer written and never read.
+ *
+ * The vertex layout is the mesh's own, because the depth shader takes position from
+ * location 0 and the pipeline still has to describe every attribute the module declares.
+ */
+export function depthPipeline(
+  cache: PipelineCache,
+  device: GPUDevice,
+  layout: GPUBindGroupLayout,
+  key: string,
+  present: Readonly<Record<string, boolean>>,
+  /**
+   * **`none` for a cubemap face, and the directional pass's own comment says why not here.**
+   *
+   * That comment argues against culling front faces to cure acne, and it is about the
+   * *directional* map, which is rendered from far away over a whole world. A point light's
+   * cube is rendered from inside a room, and `pointShadowMap.ts` disables culling outright for
+   * a reason that is not about acne at all: rendering back faces only stores the far side of
+   * every caster, and for a character's limbs the near and far sides are centimetres apart, so
+   * the caster effectively vanishes from the map. Two passes, two answers, one parameter.
+   */
+  cullMode: GPUCullMode = 'back',
+  /** Whether this pipeline's vertex stage reads a joint palette. See `DEPTH_SKINNED_VERT`. */
+  skinned = false,
+  /**
+   * Whether placement arrives per instance. See `DEPTH_INSTANCED_VERT`.
+   *
+   * Excludes `skinned`, and the layout is why rather than the shader: an instanced pipeline
+   * reclaims the two attribute locations the joint indices and weights occupy.
+   */
+  instanced = false,
+): GPURenderPipeline {
+  return cache.get(key, () => ({
+    label: key,
+    layout: device.createPipelineLayout({ bindGroupLayouts: [layout] }),
+    vertex: {
+      module: shaderModule(
+        device,
+        instanced
+          ? { label: 'depth.instanced.vert', code: DEPTH_INSTANCED_VERT_WGSL }
+          : skinned
+            ? { label: 'depth.skinned.vert', code: DEPTH_SKINNED_VERT_WGSL }
+            : { label: 'depth.vert', code: DEPTH_VERT_WGSL },
+      ),
+      entryPoint: 'main',
+      buffers: vertexBufferLayouts(present, instanced),
+    },
+    fragment: {
+      module: shaderModule(device, { label: 'depth.frag', code: DEPTH_FRAG_WGSL }),
+      entryPoint: 'main',
+      targets: [],
+    },
+    /*
+     * **Back faces culled, matching the frame.** Culling front faces instead is the textbook
+     * answer to shadow acne, and it is the wrong answer here: `renderer.ts` keeps the
+     * frame's own back-face culling through the directional pass and handles acne with
+     * receiver-plane compensation instead, so a depth map built from the far side of every
+     * surface disagrees with what the shader expects to compare against.
+     *
+     * The symptom was unmistakable and worth recording: the whole scene came out uniformly
+     * in shadow — paving, pillars and all — because every fragment compared itself against a
+     * depth recorded behind it.
+     *
+     * **`frontFace: 'cw'`, and it is this pass's projection that asks for it rather than a
+     * preference.** Facing is decided in framebuffer coordinates, whose Y points down while
+     * clip space's points up, so a triangle wound counter-clockwise in clip space reaches the
+     * rasteriser clockwise. Every presented pass is projected through `CLIP_CORRECTION`, which
+     * negates Y and turns that back over, so the default `ccw` is right for all of them. This
+     * map is sampled rather than presented, so `SHADOW_CLIP_CORRECTION` leaves Y alone — and
+     * the default then culls precisely the faces this pass exists to record.
+     *
+     * That shipped and was invisible for a fortnight, because it takes geometry the light can
+     * see through to show: on a world of a vault over an arcade, the vault was missing from the
+     * map, so the arcade under it was lit here and in shadow on WebGL2. Read back texel for
+     * texel against that backend, 2,000,709 texels of 2,095,575 differed by more than 0.2 m and
+     * 805,117 by more than 2 m, this map holding surfaces 8.4 m further from the light on
+     * average; declaring the winding takes those to 6,972 and 0.
+     *
+     * **What would make it wrong** is giving this pass the Y flip after all — the winding has to
+     * move back with it, and neither half is inert on its own.
+     * `webgpu/renderer.test.ts` asserts the pair against the matrix rather than against the
+     * literal for that reason.
+     */
+    primitive: { topology: 'triangle-list', cullMode, frontFace: 'cw' },
+    /*
+     * **The raster offset the other backend has always had, and this one never did.**
+     *
+     * `shadowMap.ts` sets `gl.polygonOffset(1.1, 4)` for its directional pass and calls it
+     * load-bearing in its own comment: *"a small slope-aware raster offset separates the stored
+     * caster from its receiver"*. This pipeline declared a format, a write and a compare, and
+     * nothing else — so every WebGPU shadow was compared against a depth with no separation at
+     * all.
+     *
+     * **It was measured as minor and it was not.** Adding it moved 2,178 pixels when it was first
+     * tried, which read as a small thing worth taking on its own terms. What that measurement
+     * could not see is that the pass was, at the time, storing the *far* side of every caster
+     * because its winding was inverted — and a caster's own thickness is an enormous accidental
+     * bias. Correcting the winding removed the masking, and what it exposed is what a shadow pass
+     * with no offset does: acne on ground in shadow, and self-shadowing near geometry that reads
+     * as a shadow with nothing casting it.
+     *
+     * **`depthBias` is not the same quantity on the two backends and that is stated rather than
+     * hidden.** WebGL2's `units` are multiples of the smallest resolvable difference of a
+     * `DEPTH_COMPONENT24` map; WebGPU applies the constant against a `depth32float`, where the
+     * specification scales it by the exponent of the primitive's maximum depth. The slope term is
+     * the same quantity in both. So these are the other backend's numbers as a starting point and
+     * the constant is the half to distrust — which is why `shadows.html` exists.
+     *
+     * **What would make it wrong** is over-biasing, which detaches a shadow from its caster: the
+     * failure `shadowMap.ts` names as the reason it culls back faces rather than front. Too small
+     * shows as acne, too large as a floating shadow, and only one of them looks like a bug.
+     */
+    depthStencil: {
+      format: SHADOW_FORMAT,
+      depthWriteEnabled: true,
+      depthCompare: 'less',
+      depthBias: 4,
+      depthBiasSlopeScale: 1.1,
+    },
+  }));
+}