@driftengine/core 3.63.0 → 4.0.0

package/src/render/gpudriven/sceneUpload.ts

@@ -0,0 +1,173 @@
+/**
+ * A scene's meshes packed into the one set of buffers a GPU-driven frame reads.
+ *
+ * **`clusterUpload.ts` packs the clusters and this packs everything they point at.** That split is
+ * not arbitrary: the cluster packing is about identifiers and spans and has no idea a vertex
+ * exists, and it rebases each mesh's index *offsets* by the indices already written while leaving
+ * the index *values* alone. Which is right — a mesh's indices address that mesh's vertices — and
+ * is exactly wrong the moment two meshes share one buffer, which is the whole point of the
+ * pipeline. Every mesh after the first would address vertex zero of the *scene*, a real vertex
+ * belonging to the first mesh, drawn in the wrong place with nothing reporting anything.
+ *
+ * So the rebasing happens here, where the vertex base is known, and the packer is handed sources
+ * whose indices are already scene-global.
+ *
+ * **Three parallel arrays rather than one interleaved vertex.** The raster shader reads
+ * `positions[index * 3]` and the shading pass reads normals and colours the same way; an
+ * interleaved stride would put the layout in three shaders instead of one place, and the memory
+ * this saves is not the memory the pipeline is short of.
+ *
+ * **Colour is a vertex attribute, because that is what this engine's geometry carries.**
+ * `MeshData` has `colors` and most of it is untextured, so the shading pass interpolates them the
+ * way the forward path does rather than inventing a material system to sit beside the one that
+ * exists. What a *material* then selects is the shading each bin gets — see `materialBin.ts` — and
+ * a mesh names one.
+ */
+
+import { packClusters, type ClusterBuffers, type ClusterSource } from './clusterUpload.ts';
+
+/**
+ * Floats a vertex in the buffer the GPU-driven pass uploads: position, normal, colour, uv, glow.
+ *
+ * **One number read by four consumers** — the upload, the raster, the blended raster and the
+ * shading pass — and `vertexLayout.test.ts` holds all four to it. It was nine until UVs arrived on
+ * 2026-09-17, and eleven until the voxel sandbox's block light needed a glow a vertex on 2026-09-18.
+ */
+export const GPU_DRIVEN_VERTEX_FLOATS = 12;
+
+/** One mesh of a GPU-driven scene: its vertices, its clusters, and which material shades it. */
+export interface GpuDrivenMesh {
+  /** Three floats a vertex. */
+  readonly positions: Float32Array;
+  /** Three floats a vertex. */
+  readonly normals: Float32Array;
+  /** Three floats a vertex. */
+  readonly colours: Float32Array;
+  /**
+   * Two floats a vertex. Optional: a mesh without them uploads zeros, and a textured material on
+   * it reads one texel everywhere and turns no normal — a statement about the mesh, and what the
+   * forward path does with an absent attribute.
+   */
+  readonly uvs?: Float32Array;
+  /**
+   * One float a vertex, added to the material's own emissive. Optional: a mesh without it glows as
+   * its material says and nothing more, which is every mesh before 2026-09-18.
+   *
+   * **For light a colour cannot carry.** The voxel sandbox folds occlusion and sky light into the
+   * vertex colour and keeps block light here, because it has to survive the sun going down and a
+   * colour is multiplied by the sun. The forward path reads the same attribute from `MeshData`.
+   */
+  readonly emissive?: Float32Array;
+  /** This mesh's clusters, with indices addressing *this mesh's* vertices. */
+  readonly clusters: ClusterSource;
+  /** Which material bin every cluster of this mesh shades in. */
+  readonly material: number;
+}
+
+export interface GpuDrivenScene {
+  /** Every mesh's positions, concatenated in the order they were given. */
+  readonly positions: Float32Array;
+  readonly normals: Float32Array;
+  readonly colours: Float32Array;
+  /** Two floats a vertex, zeros where a mesh carried none. */
+  readonly uvs: Float32Array;
+  /** One float a vertex, zeros where a mesh carried none. */
+  readonly emissive: Float32Array;
+  /** The clusters, with indices addressing `positions` rather than any one mesh. */
+  readonly clusters: ClusterBuffers;
+  /** One material a cluster, from the mesh it came from. */
+  readonly materialOf: Uint32Array;
+  /** Where each mesh's vertices begin. One entry a mesh, including meshes with no clusters. */
+  readonly vertexBase: Uint32Array;
+  readonly vertexCount: number;
+}
+
+/**
+ * A mesh's per-vertex glow, refused by name when it is not one float a vertex.
+ *
+ * Shared by both packers, because a glow of the wrong length read one float a vertex is somebody
+ * else's torchlight on the next mesh along — or `NaN` past the end, which lights nothing and says
+ * nothing about why.
+ */
+export function glowOf(mesh: GpuDrivenMesh, at: number | string): Float32Array | undefined {
+  const glow = mesh.emissive;
+  if (glow === undefined) return undefined;
+  const count = mesh.positions.length / 3;
+  if (glow.length !== count) {
+    throw new Error(
+      `[driftengine] mesh ${at} carries ${glow.length} emissive values for ${count} vertices`,
+    );
+  }
+  return glow;
+}
+
+/**
+ * Pack a scene.
+ *
+ * **A mesh with no clusters still takes its slot**, in `vertexBase` and in the mesh numbering the
+ * clusters carry. `meshOf` indexes the caller's transform array, so dropping an empty mesh shifts
+ * every mesh after it and each of their clusters draws with somebody else's matrix — the same
+ * reasoning `packClusters` already gives, one level up.
+ */
+export function buildGpuDrivenScene(meshes: readonly GpuDrivenMesh[]): GpuDrivenScene {
+  let vertices = 0;
+  let clusters = 0;
+  const vertexBase = new Uint32Array(meshes.length);
+  for (let at = 0; at < meshes.length; at += 1) {
+    const mesh = meshes[at] as GpuDrivenMesh;
+    vertexBase[at] = vertices;
+    vertices += mesh.positions.length / 3;
+    clusters += mesh.clusters.count;
+  }
+
+  const positions = new Float32Array(vertices * 3);
+  const normals = new Float32Array(vertices * 3);
+  const colours = new Float32Array(vertices * 3);
+  const uvs = new Float32Array(vertices * 2);
+  const emissive = new Float32Array(vertices);
+  const rebased: ClusterSource[] = [];
+  const materialOf = new Uint32Array(clusters);
+
+  let cluster = 0;
+  for (let at = 0; at < meshes.length; at += 1) {
+    const mesh = meshes[at] as GpuDrivenMesh;
+    const base = vertexBase[at] as number;
+    positions.set(mesh.positions, base * 3);
+    normals.set(mesh.normals, base * 3);
+    colours.set(mesh.colours, base * 3);
+    if (mesh.uvs !== undefined) {
+      const count = mesh.positions.length / 3;
+      if (mesh.uvs.length !== count * 2) {
+        throw new Error(
+          `[driftengine] mesh ${at} carries ${mesh.uvs.length} uv values for ${count} vertices`,
+        );
+      }
+      uvs.set(mesh.uvs, base * 2);
+    }
+    const glow = glowOf(mesh, at);
+    if (glow !== undefined) emissive.set(glow, base);
+
+    const indices = new Uint32Array(mesh.clusters.indices.length);
+    for (let i = 0; i < indices.length; i += 1) {
+      indices[i] = (mesh.clusters.indices[i] as number) + base;
+    }
+    rebased.push({ ...mesh.clusters, indices });
+
+    for (let c = 0; c < mesh.clusters.count; c += 1) {
+      materialOf[cluster] = mesh.material;
+      cluster += 1;
+    }
+  }
+
+  return {
+    positions,
+    normals,
+    colours,
+    uvs,
+    emissive,
+    clusters: packClusters(rebased),
+    materialOf,
+    vertexBase,
+    vertexCount: vertices,
+  };
+}

package/src/render/gpudriven/shadeBins.ts

@@ -0,0 +1,222 @@
+/**
+ * Rebuilding a pixel's surface from the triangle it recorded.
+ *
+ * **This is the only part of the shading that differs between the two pipelines.** The forward
+ * path gets its surface attributes from the rasteriser's varyings; a visibility buffer has none,
+ * so every attribute has to be interpolated here from the three vertices of the triangle the pixel
+ * wrote down. The lighting itself is not this module's business and must not become a second copy
+ * of the forward path's — a pair of lighting expressions drifts, and the parity gate is then the
+ * only thing that notices.
+ *
+ * **Perspective correction is not optional and screen-space barycentrics are not enough.** A
+ * triangle seen at an angle covers pixels whose interpolated attributes are *not* linear in screen
+ * position: the correct weights are the screen-space ones divided by each vertex's clip `w` and
+ * renormalised. Skipping it is the classic affine-texturing look, and on a floor it is unmistakable.
+ *
+ * **The gradients are derived analytically, and this is the subtle one.** A fragment shader gets
+ * `dFdx` and `dFdy` for free because it runs in quads of four pixels; a compute invocation has no
+ * neighbours and no derivative at all. A texture read without one either picks a fixed level —
+ * which is a blurry picture everywhere, or an aliased one — or picks level zero, which sparkles.
+ * So the rate of change of every barycentric with respect to screen x and y is computed from the
+ * triangle's own edge functions, and an attribute's gradient is the same weighted sum its value
+ * is. `attributeGradients` is that, and `barycentricGradients` is what it rests on.
+ *
+ * Everything here takes plain numbers and fills arrays the caller owns, because the shader does the
+ * same arithmetic per pixel and the two have to be comparable term by term.
+ */
+
+/** Screen position and reciprocal clip w of one vertex: x, y, 1/w. */
+export const SCREEN_VERTEX_FLOATS = 3;
+
+/**
+ * Project one clip-space vertex into pixel coordinates.
+ *
+ * Fills `x, y, 1/w`. Answers **false behind the eye**, where the division has no meaning: a
+ * visibility buffer cannot record such a pixel in the first place — the rasteriser clipped the
+ * triangle before it was drawn — so reaching this with `w <= 0` means the identifier and the
+ * geometry have gone out of step, and a silent NaN would shade a plausible-looking wrong surface.
+ */
+export function screenVertex(
+  clipX: number,
+  clipY: number,
+  clipW: number,
+  width: number,
+  height: number,
+  out: Float32Array,
+  at: number,
+): boolean {
+  if (!(clipW > 1e-9)) return false;
+  const inverse = 1 / clipW;
+  out[at] = (clipX * inverse * 0.5 + 0.5) * width;
+  out[at + 1] = (clipY * inverse * 0.5 + 0.5) * height;
+  out[at + 2] = inverse;
+  return true;
+}
+
+/** Twice the signed area of the screen triangle. Zero where it is degenerate. */
+export function screenArea(screen: Float32Array): number {
+  const x0 = screen[0] as number;
+  const y0 = screen[1] as number;
+  const x1 = screen[3] as number;
+  const y1 = screen[4] as number;
+  const x2 = screen[6] as number;
+  const y2 = screen[7] as number;
+  return (x1 - x0) * (y2 - y0) - (x2 - x0) * (y1 - y0);
+}
+
+/**
+ * The screen-space barycentric weights of a point, before perspective correction.
+ *
+ * Answers false for a degenerate triangle — one whose three screen positions are collinear, which
+ * covers no pixel and whose weights are a division by zero. A caller that reaches this has a
+ * visibility identifier for a triangle the rasteriser never drew.
+ *
+ * **A point outside the triangle gets a negative weight rather than a clamp.** Clamping is how a
+ * pixel on the far side of an edge ends up shaded as though it were on the triangle, which along a
+ * silhouette is a fringe of the wrong material.
+ */
+export function screenBarycentrics(
+  screen: Float32Array,
+  x: number,
+  y: number,
+  out: Float32Array,
+): boolean {
+  const area = screenArea(screen);
+  if (Math.abs(area) < 1e-12) return false;
+  const x0 = screen[0] as number;
+  const y0 = screen[1] as number;
+  const x1 = screen[3] as number;
+  const y1 = screen[4] as number;
+  const x2 = screen[6] as number;
+  const y2 = screen[7] as number;
+  const inverse = 1 / area;
+  out[1] = ((x - x0) * (y2 - y0) - (x2 - x0) * (y - y0)) * inverse;
+  out[2] = ((x1 - x0) * (y - y0) - (x - x0) * (y1 - y0)) * inverse;
+  out[0] = 1 - out[1] - out[2];
+  return true;
+}
+
+/**
+ * The perspective-correct weights, from the screen-space ones and the vertices' reciprocal `w`.
+ *
+ * Each screen weight is scaled by its vertex's `1/w` and the three renormalised. At an orthographic
+ * projection every `1/w` is equal and this is the identity, which is why the affine version looks
+ * right on a test quad facing the camera and wrong on the floor beneath it.
+ */
+export function perspectiveBarycentrics(
+  screen: Float32Array,
+  lambda: Float32Array,
+  out: Float32Array,
+): boolean {
+  const w0 = (lambda[0] as number) * (screen[2] as number);
+  const w1 = (lambda[1] as number) * (screen[5] as number);
+  const w2 = (lambda[2] as number) * (screen[8] as number);
+  const sum = w0 + w1 + w2;
+  if (Math.abs(sum) < 1e-20) return false;
+  const inverse = 1 / sum;
+  out[0] = w0 * inverse;
+  out[1] = w1 * inverse;
+  out[2] = w2 * inverse;
+  return true;
+}
+
+/**
+ * How each perspective-correct weight changes with screen x and y, at one pixel.
+ *
+ * Fills six numbers: `d0/dx, d1/dx, d2/dx, d0/dy, d1/dy, d2/dy`.
+ *
+ * **Derived rather than differenced.** The screen weights are linear in `x` and `y`, so their
+ * gradients are constants of the triangle; the perspective-correct ones are a ratio of two linear
+ * functions, and the quotient rule gives the rest. What this buys over a finite difference is that
+ * it is exact at the pixel rather than an average over one, and that it costs no neighbours — a
+ * compute invocation has none.
+ */
+export function barycentricGradients(
+  screen: Float32Array,
+  lambda: Float32Array,
+  out: Float32Array,
+): boolean {
+  const area = screenArea(screen);
+  if (Math.abs(area) < 1e-12) return false;
+  const inverse = 1 / area;
+  const x0 = screen[0] as number;
+  const y0 = screen[1] as number;
+  const x1 = screen[3] as number;
+  const y1 = screen[4] as number;
+  const x2 = screen[6] as number;
+  const y2 = screen[7] as number;
+
+  /* The screen weights' own gradients, which are constant over the triangle. */
+  const d1dx = (y2 - y0) * inverse;
+  const d1dy = (x0 - x2) * inverse;
+  const d2dx = (y0 - y1) * inverse;
+  const d2dy = (x1 - x0) * inverse;
+  const d0dx = -d1dx - d2dx;
+  const d0dy = -d1dy - d2dy;
+
+  const iw0 = screen[2] as number;
+  const iw1 = screen[5] as number;
+  const iw2 = screen[8] as number;
+  const n0 = (lambda[0] as number) * iw0;
+  const n1 = (lambda[1] as number) * iw1;
+  const n2 = (lambda[2] as number) * iw2;
+  const sum = n0 + n1 + n2;
+  if (Math.abs(sum) < 1e-20) return false;
+  const inverseSum = 1 / sum;
+
+  /* The denominator's own gradient: the same weighted sum of the reciprocal w values. */
+  const dSumDx = d0dx * iw0 + d1dx * iw1 + d2dx * iw2;
+  const dSumDy = d0dy * iw0 + d1dy * iw1 + d2dy * iw2;
+
+  /* Quotient rule, per weight, with the shared denominator factored out. */
+  out[0] = (d0dx * iw0 - n0 * inverseSum * dSumDx) * inverseSum;
+  out[1] = (d1dx * iw1 - n1 * inverseSum * dSumDx) * inverseSum;
+  out[2] = (d2dx * iw2 - n2 * inverseSum * dSumDx) * inverseSum;
+  out[3] = (d0dy * iw0 - n0 * inverseSum * dSumDy) * inverseSum;
+  out[4] = (d1dy * iw1 - n1 * inverseSum * dSumDy) * inverseSum;
+  out[5] = (d2dy * iw2 - n2 * inverseSum * dSumDy) * inverseSum;
+  return true;
+}
+
+/** One attribute interpolated by the weights already computed. */
+export function interpolate(a0: number, a1: number, a2: number, weights: Float32Array): number {
+  return a0 * (weights[0] as number) + a1 * (weights[1] as number) + a2 * (weights[2] as number);
+}
+
+/**
+ * One attribute's rate of change with screen x and y, from the weight gradients.
+ *
+ * An attribute is a weighted sum of three constants, so its gradient is the same sum of the
+ * weights' gradients. This is what a texture fetch's level of detail is computed from.
+ */
+export function attributeGradients(
+  a0: number,
+  a1: number,
+  a2: number,
+  gradients: Float32Array,
+): { dx: number; dy: number } {
+  return {
+    dx:
+      a0 * (gradients[0] as number) + a1 * (gradients[1] as number) + a2 * (gradients[2] as number),
+    dy:
+      a0 * (gradients[3] as number) + a1 * (gradients[4] as number) + a2 * (gradients[5] as number),
+  };
+}
+
+/**
+ * Which pixel a shading invocation is responsible for.
+ *
+ * A group covers `BIN_GROUP_SIZE` entries of one material's slice; an invocation past the end of
+ * the slice has no pixel, which is the ordinary case because the slice is not a multiple of the
+ * group size. Answers -1 there rather than the last pixel of the bin, which would shade it once
+ * per spare lane.
+ */
+export function binPixel(
+  pixels: Uint32Array,
+  offset: number,
+  count: number,
+  invocation: number,
+): number {
+  if (invocation < 0 || invocation >= count) return -1;
+  return (pixels[offset + invocation] as number) ?? -1;
+}

package/src/render/gpudriven/shadow.ts

@@ -0,0 +1,285 @@
+/** The directional shadow lookup, in TypeScript, so the second pipeline's copy has a reference. */
+
+import { DIRECTIONAL_SHADOW_FADE_START, POINT_SHADOW_FADE_START } from '../renderQuality.ts';
+
+/**
+ * **`flat/directionalShadow.ts` in TypeScript, for one depth layer.**
+ *
+ * The lesson of the lit expression was a week old when this was written: a term that exists only
+ * as a shader is a term nothing can disagree with. So the lookup was written here first, tested
+ * here, and `SHADE_SHADOW_WGSL` beside it is the same arithmetic for the device with
+ * `gpu-parity.mjs` running both — which is the order the map itself then followed.
+ *
+ * **One layer, where the forward path has three.** That path keeps a static map, a peeled one
+ * holding the second static occluder, and a dynamic one for movers, and multiplies their
+ * transmissions — an arrangement its own comments argue for at length and which exists because its
+ * shadow *pool* is shared between lights and rationed across frames. The second pipeline has no
+ * such pool: it owns its geometry, and a pass owns whatever target it renders in `prepare`. When
+ * there is one caster set there is one map, and stating that is better than pretending the shape
+ * is the same.
+ *
+ * **Everything else is term for term**, because the two pipelines drawing one scene must not
+ * disagree about where a shadow ends. Each fade below returns *fully lit*, which is the thing that
+ * makes them dangerous: a guard that fires when it should not removes a shadow, and a missing
+ * shadow reads as a scene that never had one.
+ */
+
+/** How much of a texel the filter reaches, which sets the softness of an edge. */
+export const SHADOW_TEXEL_SCALE = 1.35;
+
+/**
+ * The most depth the receiver-plane compensation may carry a tap, in texels.
+ *
+ * **A product of an unbounded gradient and a bounded offset**, and `directionalShadow.ts` records
+ * paying for the version where only the offset was bounded: a gradient that has blown up turns a
+ * fraction of a texel into a depth swing of whole map units, the comparison flips on alternate
+ * shadow texels, and what draws is hard straight stripes along the map's texel grid — oblique on
+ * screen, because that grid is turned by the sun rather than by the camera.
+ */
+export const SHADOW_SLOPE_TEXELS = 9.1;
+
+/** Subtracted from every comparison, in depth-span units. The contact bias. */
+export const SHADOW_DEPTH_BIAS = 0.14;
+
+/** The band of `n · l` over which the shadow modulation is given up. See `shadowFactor`. */
+export const SHADOW_TERMINATOR_BAND: readonly [number, number] = [0.08, 0.2];
+
+/**
+ * The stretch of stored depth, 0 to 1, over which a shadow is given up at the map's far end.
+ *
+ * **A fit has to keep its receivers short of it**, and that is why it is a name rather than two
+ * literals: in the scene fit the far end is the scene's own rim, where nothing lies beyond, and a
+ * fit that followed the eye first put the whole of the eye's sphere inside it — `fitShadow` derives
+ * its least depth reach from the first of these two numbers.
+ */
+export const SHADOW_DEPTH_FADE: readonly [number, number] = [0.9, 1];
+
+/**
+ * The twelve taps, transcribed from `flat/pointShadow.ts`.
+ *
+ * A Poisson set rather than a grid: a grid filters along its own axes and bands across them, and
+ * the sun turns the map's grid relative to the screen, so the banding arrives at an angle nobody
+ * can attribute to anything.
+ */
+export const SHADOW_PCF_OFFSETS: readonly (readonly [number, number])[] = [
+  [-0.326, -0.406],
+  [0.519, 0.767],
+  [0.962, -0.195],
+  [-0.696, 0.457],
+  [-0.84, -0.074],
+  [0.185, -0.893],
+  [0.896, 0.412],
+  [-0.203, 0.621],
+  [0.473, -0.48],
+  [0.507, 0.064],
+  [-0.322, -0.933],
+  [-0.792, -0.598],
+];
+
+export interface ShadowSettings {
+  /** 0 turns the whole lookup off, and off is exact rather than nearly. */
+  readonly strength: number;
+  readonly mapSize: number;
+  /** Metres the map's depth range spans, which turns a stored depth into a distance. */
+  readonly depthSpan: number;
+  /** Metres a shadow may travel along the ground before it has faded out. */
+  readonly maxDistance: number;
+  /** The steepest `|light.xz| / light.y` that still casts. */
+  readonly maxSlope: number;
+  readonly taps: number;
+  /** Toward the light, unit length, as `Environment.directionalDir` is. */
+  readonly lightDir: readonly [number, number, number];
+}
+
+/**
+ * The receiver plane: how the light-space depth changes per unit of the light's own `u` and `v`.
+ *
+ * **A fragment shader gets `dFdx`/`dFdy` and a compute invocation has none**, having no neighbours
+ * to difference against — the same fact `SHADE_SURFACE_WGSL` exists for. So this takes the two
+ * derivatives rather than computing them: the forward path passes what the hardware gave it, and
+ * the second pipeline passes what it derives from the barycentric gradients it already has. The
+ * arithmetic between them is one function, which is the whole point.
+ *
+ * **It is a two-by-two solve and it is refused where the system is ill-conditioned.** A triangle
+ * seen almost edge-on in the light's projection has a determinant near zero, and dividing by it
+ * turns a fraction of a texel into a depth swing of whole map units — which the clamp downstream
+ * then has to catch. Refusing here is cheaper and says what happened: a plane whose slope cannot be
+ * measured gets no compensation rather than a wrong one.
+ *
+ * **Exact only where the light's projection is orthographic**, which a directional light's is: `w`
+ * is one, so the light-space position is linear in the world position and a barycentric
+ * interpolation of the three corners is the real thing rather than an approximation of it.
+ */
+export function receiverPlaneDepthGradient(
+  dx: readonly [number, number, number],
+  dy: readonly [number, number, number],
+  out: Float32Array,
+): Float32Array {
+  const determinant = dx[0] * dy[1] - dx[1] * dy[0];
+  const conditioning = Math.hypot(dx[0], dx[1]) * Math.hypot(dy[0], dy[1]);
+  if (Math.abs(determinant) < 1e-4 * conditioning) {
+    out[0] = 0;
+    out[1] = 0;
+    return out;
+  }
+  out[0] = (dx[2] * dy[1] - dx[1] * dy[2]) / determinant;
+  out[1] = (dx[0] * dy[2] - dx[2] * dy[0]) / determinant;
+  return out;
+}
+
+/**
+ * The receiver plane a shading invocation can actually get, from the two things it already has.
+ *
+ * **A compute invocation has no neighbours, so the derivative has to be built rather than taken.**
+ * `SHADE_SURFACE_WGSL` already computes how each barycentric weight changes per pixel of screen —
+ * that is what a visibility buffer's shading needs for texture gradients — and a light-space
+ * position is a linear combination of the three corners with exactly those weights. So the
+ * derivative of the light-space position is the same combination of the corners with the *weight
+ * gradients*, which is what this assembles before handing it to the solve above.
+ *
+ * **Exact rather than approximate, because a directional light's projection is orthographic.** `w`
+ * is one everywhere, so the light-space position is linear in the world position and no perspective
+ * divide stands between the weights and the answer. A spot light would need the quotient rule here
+ * and this function would be wrong for it, which is worth knowing before one arrives.
+ *
+ * **The halving is the remap.** The lookup addresses the map in 0-to-1 coordinates and clip `x` and
+ * `y` run -1 to 1, so a slope stated per clip unit is twice the slope per map unit. Depth is not
+ * halved: this pipeline's light matrix already emits `z` in 0..1, which is the same asymmetry
+ * `shadowFactor` carries and for the same reason.
+ *
+ * Each corner is a light-space clip position, `x`, `y` and `z`, with `w` taken as one.
+ */
+export function receiverPlaneFromWeights(
+  l0: readonly [number, number, number],
+  l1: readonly [number, number, number],
+  l2: readonly [number, number, number],
+  gx: readonly [number, number, number],
+  gy: readonly [number, number, number],
+  out: Float32Array,
+): Float32Array {
+  const along = (g: readonly [number, number, number], axis: 0 | 1 | 2): number =>
+    (g[0] as number) * (l0[axis] as number) +
+    (g[1] as number) * (l1[axis] as number) +
+    (g[2] as number) * (l2[axis] as number);
+  return receiverPlaneDepthGradient(
+    [along(gx, 0) * 0.5, along(gx, 1) * 0.5, along(gx, 2)],
+    [along(gy, 0) * 0.5, along(gy, 1) * 0.5, along(gy, 2)],
+    out,
+  );
+}
+
+/** GLSL's `smoothstep`, which is not `Math`'s anything. */
+function smoothstep(edge0: number, edge1: number, x: number): number {
+  const t = Math.min(Math.max((x - edge0) / (edge1 - edge0), 0), 1);
+  return t * t * (3 - 2 * t);
+}
+
+/** How much of a shadow survives having been cast this far along the ground. */
+export function shadowReach(distance: number, maxDistance: number): number {
+  return 1 - smoothstep(maxDistance * POINT_SHADOW_FADE_START, maxDistance, distance);
+}
+
+/**
+ * Whether one tap is lit, and by how much.
+ *
+ * **A tap behind an occluder is not simply dark**: how far the shadow has travelled along the
+ * ground decides how much of it is left, which is what keeps one map's worth of geometry from
+ * shadowing the whole world.
+ */
+export function directionalVisibility(
+  receiverDepth: number,
+  compareDepth: number,
+  storedDepth: number,
+  settings: ShadowSettings,
+): number {
+  if (compareDepth <= storedDepth) return 1;
+  const rayDistance = Math.max(receiverDepth - storedDepth, 0) * settings.depthSpan;
+  const ground =
+    rayDistance * Math.hypot(settings.lightDir[0] as number, settings.lightDir[2] as number);
+  return 1 - shadowReach(ground, settings.maxDistance);
+}
+
+/**
+ * How much light reaches a receiver, from 0 in full shadow to 1 in full light.
+ *
+ * `lightPos` is the receiver in the light's clip space, before the divide. `depthGradient` is how
+ * the light-space depth changes across a pixel of the map — the receiver plane — which a fragment
+ * shader gets from `dFdx`/`dFdy` and a **compute invocation cannot**, having no neighbours. The
+ * second pipeline derives it from the barycentric gradients `SHADE_SURFACE_WGSL` already computes,
+ * which is the same reason that file computes them: a derivative has to come from somewhere.
+ *
+ * `depthAt` reads the map with nearest filtering, which is what the comparison assumes: the fetched
+ * depth belongs to the centre of the containing texel, and following the continuous coordinate
+ * instead leaves half a texel of uncompensated slope — the repeating ribs a grazing face shows.
+ */
+export function shadowFactor(
+  lightPos: readonly [number, number, number, number],
+  depthGradient: readonly [number, number],
+  ndl: number,
+  settings: ShadowSettings,
+  depthAt: (u: number, v: number) => number,
+): number {
+  /*
+   * **Four early-outs below, and every one of them is a cost rather than a correctness guard.**
+   * The result is `1 + (lit - 1) * amount` and `amount` is the product of all four fades, so a fade
+   * at zero returns exactly one whether or not the return fires — perturbing any of them changes
+   * no answer, which is recorded here rather than papered over. They stay because each one skips a
+   * loop of twelve texture reads, which on a full screen is the difference between a lookup and a
+   * pass. The bounds check is the one with a second job: without it the taps read outside the map.
+   */
+  if (settings.strength <= 0) return 1;
+
+  const w = lightPos[3];
+  if (w === 0) return 1;
+  /*
+   * **`x` and `y` are remapped and `z` is not, and that is a convention rather than an asymmetry.**
+   * WebGPU clips `z` to 0..1 already; OpenGL clips it to -1..1, which is why the GLSL this is
+   * transcribed from remaps all three. This module is the second pipeline's and the second pipeline
+   * is WebGPU only, so it takes WebGPU's convention — and a caller handing it a GL-style depth gets
+   * a shadow that is half as deep as it should be and biased by half the map, which reads as
+   * everything being lit. `CLIP_CORRECTION` records the same family of mistake one level up.
+   */
+  const px = (lightPos[0] / w) * 0.5 + 0.5;
+  const py = (lightPos[1] / w) * 0.5 + 0.5;
+  const pz = lightPos[2] / w;
+
+  const receiverFade = smoothstep(SHADOW_TERMINATOR_BAND[0], SHADOW_TERMINATOR_BAND[1], ndl);
+  if (receiverFade <= 0) return 1;
+  if (pz > 1 || px < 0 || px > 1 || py < 0 || py > 1) return 1;
+
+  const fromCentre = Math.max(Math.abs(px - 0.5) * 2, Math.abs(py - 0.5) * 2);
+  const edgeFade =
+    (1 - smoothstep(0.72, 0.98, fromCentre)) *
+    (1 - smoothstep(SHADOW_DEPTH_FADE[0], SHADOW_DEPTH_FADE[1], pz));
+  if (edgeFade <= 0) return 1;
+
+  const slope =
+    Math.hypot(settings.lightDir[0] as number, settings.lightDir[2] as number) /
+    Math.max(settings.lightDir[1] as number, 0.001);
+  const lowElevationFade =
+    1 - smoothstep(settings.maxSlope * DIRECTIONAL_SHADOW_FADE_START, settings.maxSlope, slope);
+  if (lowElevationFade <= 0) return 1;
+
+  const texel = SHADOW_TEXEL_SCALE / settings.mapSize;
+  const slopeLimit = SHADOW_SLOPE_TEXELS / settings.mapSize;
+  const taps = Math.max(1, Math.min(Math.trunc(settings.taps), SHADOW_PCF_OFFSETS.length));
+
+  let lit = 0;
+  for (let tap = 0; tap < taps; tap += 1) {
+    const offset = SHADOW_PCF_OFFSETS[tap] as readonly [number, number];
+    const u = px + offset[0] * texel;
+    const v = py + offset[1] * texel;
+    const centreU = (Math.floor(u * settings.mapSize) + 0.5) / settings.mapSize;
+    const centreV = (Math.floor(v * settings.mapSize) + 0.5) / settings.mapSize;
+    const raw =
+      (depthGradient[0] as number) * (centreU - px) + (depthGradient[1] as number) * (centreV - py);
+    const slopeOffset = Math.min(Math.max(raw, -slopeLimit), slopeLimit);
+    const receiverDepth = pz + slopeOffset;
+    const compare = receiverDepth - SHADOW_DEPTH_BIAS / settings.depthSpan;
+    lit += directionalVisibility(receiverDepth, compare, depthAt(u, v), settings);
+  }
+  lit /= taps;
+
+  const amount = settings.strength * edgeFade * lowElevationFade * receiverFade;
+  return 1 + (lit - 1) * amount;
+}