@driftengine/core 3.63.0 → 4.0.0

package/dist/render/gpudriven/shadeBins.d.ts

@@ -0,0 +1,92 @@
+/**
+ * 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 declare 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 declare function screenVertex(clipX: number, clipY: number, clipW: number, width: number, height: number, out: Float32Array, at: number): boolean;
+/** Twice the signed area of the screen triangle. Zero where it is degenerate. */
+export declare function screenArea(screen: Float32Array): number;
+/**
+ * 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 declare function screenBarycentrics(screen: Float32Array, x: number, y: number, out: Float32Array): boolean;
+/**
+ * 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 declare function perspectiveBarycentrics(screen: Float32Array, lambda: Float32Array, out: Float32Array): boolean;
+/**
+ * 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 declare function barycentricGradients(screen: Float32Array, lambda: Float32Array, out: Float32Array): boolean;
+/** One attribute interpolated by the weights already computed. */
+export declare function interpolate(a0: number, a1: number, a2: number, weights: Float32Array): 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 declare function attributeGradients(a0: number, a1: number, a2: number, gradients: Float32Array): {
+    dx: number;
+    dy: 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 declare function binPixel(pixels: Uint32Array, offset: number, count: number, invocation: number): number;

package/dist/render/gpudriven/shadeBins.js

@@ -0,0 +1,182 @@
+/**
+ * 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, clipY, clipW, width, height, out, at) {
+    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) {
+    const x0 = screen[0];
+    const y0 = screen[1];
+    const x1 = screen[3];
+    const y1 = screen[4];
+    const x2 = screen[6];
+    const y2 = screen[7];
+    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, x, y, out) {
+    const area = screenArea(screen);
+    if (Math.abs(area) < 1e-12)
+        return false;
+    const x0 = screen[0];
+    const y0 = screen[1];
+    const x1 = screen[3];
+    const y1 = screen[4];
+    const x2 = screen[6];
+    const y2 = screen[7];
+    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, lambda, out) {
+    const w0 = lambda[0] * screen[2];
+    const w1 = lambda[1] * screen[5];
+    const w2 = lambda[2] * screen[8];
+    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, lambda, out) {
+    const area = screenArea(screen);
+    if (Math.abs(area) < 1e-12)
+        return false;
+    const inverse = 1 / area;
+    const x0 = screen[0];
+    const y0 = screen[1];
+    const x1 = screen[3];
+    const y1 = screen[4];
+    const x2 = screen[6];
+    const y2 = screen[7];
+    /* 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];
+    const iw1 = screen[5];
+    const iw2 = screen[8];
+    const n0 = lambda[0] * iw0;
+    const n1 = lambda[1] * iw1;
+    const n2 = lambda[2] * 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, a1, a2, weights) {
+    return a0 * weights[0] + a1 * weights[1] + a2 * weights[2];
+}
+/**
+ * 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, a1, a2, gradients) {
+    return {
+        dx: a0 * gradients[0] + a1 * gradients[1] + a2 * gradients[2],
+        dy: a0 * gradients[3] + a1 * gradients[4] + a2 * gradients[5],
+    };
+}
+/**
+ * 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, offset, count, invocation) {
+    if (invocation < 0 || invocation >= count)
+        return -1;
+    return pixels[offset + invocation] ?? -1;
+}

package/dist/render/gpudriven/shadow.d.ts

@@ -0,0 +1,136 @@
+/** The directional shadow lookup, in TypeScript, so the second pipeline's copy has a reference. */
+/**
+ * **`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 declare 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 declare const SHADOW_SLOPE_TEXELS = 9.1;
+/** Subtracted from every comparison, in depth-span units. The contact bias. */
+export declare const SHADOW_DEPTH_BIAS = 0.14;
+/** The band of `n · l` over which the shadow modulation is given up. See `shadowFactor`. */
+export declare const SHADOW_TERMINATOR_BAND: readonly [number, number];
+/**
+ * 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 declare const SHADOW_DEPTH_FADE: readonly [number, number];
+/**
+ * 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 declare const SHADOW_PCF_OFFSETS: readonly (readonly [number, number])[];
+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 declare function receiverPlaneDepthGradient(dx: readonly [number, number, number], dy: readonly [number, number, number], out: Float32Array): Float32Array;
+/**
+ * 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 declare 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;
+/** How much of a shadow survives having been cast this far along the ground. */
+export declare function shadowReach(distance: number, maxDistance: number): number;
+/**
+ * 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 declare function directionalVisibility(receiverDepth: number, compareDepth: number, storedDepth: number, settings: ShadowSettings): number;
+/**
+ * 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 declare function shadowFactor(lightPos: readonly [number, number, number, number], depthGradient: readonly [number, number], ndl: number, settings: ShadowSettings, depthAt: (u: number, v: number) => number): number;

package/dist/render/gpudriven/shadow.js

@@ -0,0 +1,224 @@
+/** 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.js';
+/**
+ * **`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 = [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 = [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 = [
+    [-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],
+];
+/**
+ * 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, dy, out) {
+    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, l1, l2, gx, gy, out) {
+    const along = (g, axis) => g[0] * l0[axis] +
+        g[1] * l1[axis] +
+        g[2] * l2[axis];
+    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, edge1, x) {
+    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, maxDistance) {
+    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, compareDepth, storedDepth, settings) {
+    if (compareDepth <= storedDepth)
+        return 1;
+    const rayDistance = Math.max(receiverDepth - storedDepth, 0) * settings.depthSpan;
+    const ground = rayDistance * Math.hypot(settings.lightDir[0], settings.lightDir[2]);
+    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, depthGradient, ndl, settings, depthAt) {
+    /*
+     * **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], settings.lightDir[2]) /
+        Math.max(settings.lightDir[1], 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];
+        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] * (centreU - px) + depthGradient[1] * (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;
+}