@driftengine/core 3.61.0

package/dist/render/pointShadowImage.js

@@ -0,0 +1,339 @@
+import { mat3, mat4, vec3 } from 'gl-matrix';
+/**
+ * What a point light's shadow cubemap *is*, with no device in it.
+ *
+ * **Everything here is a decision, and the six that matter are already paid for.** A cubemap
+ * that is stale by a millimetre re-bakes six passes over the world; one that is not stale
+ * enough strobes; one that publishes its parameters before its last face pairs new numbers with
+ * old pixels; one that keeps `baked` across a pool handover reports another lamp's picture as
+ * its own. Each of those was a shipped bug on the WebGL2 path and each is fixed *here*, so a
+ * second backend inherits the fixes instead of re-earning them. That is the 2026-08-13 rule
+ * applied to the largest piece of state in the renderer.
+ *
+ * The device half — the cube texture and the six passes that fill it — is per backend and is
+ * all that is left outside this file.
+ */
+/** A cubemap is six faces, and a bake may be spread across frames a few at a time. */
+export const FACE_COUNT = 6;
+/** Which way each face looks, and which way is up for it. The order is the cubemap's own. */
+const FACE_TARGETS = [
+    [
+        [1, 0, 0],
+        [0, -1, 0],
+    ],
+    [
+        [-1, 0, 0],
+        [0, -1, 0],
+    ],
+    [
+        [0, 1, 0],
+        [0, 0, 1],
+    ],
+    [
+        [0, -1, 0],
+        [0, 0, -1],
+    ],
+    [
+        [0, 0, 1],
+        [0, -1, 0],
+    ],
+    [
+        [0, 0, -1],
+        [0, -1, 0],
+    ],
+];
+/**
+ * Default distance from the source at which shadow casting begins.
+ *
+ * Raising it per light is how a fixture avoids shadowing its own lamp: a brazier sits directly
+ * under its flame, so with a near plane of a few centimetres it occludes an enormous solid
+ * angle and throws a big square across the ground. Anything nearer the source than this is
+ * simply not rendered into the map, which is what real fixtures do — the light comes from
+ * *inside* them.
+ */
+export const POINT_SHADOW_NEAR = 0.25;
+/**
+ * How long a freshly baked image takes to reach full strength, in seconds.
+ *
+ * Long enough to read as a shadow settling rather than a shadow appearing, short enough that
+ * nobody standing still waits for it. A quarter second is about thirty frames at 120 Hz, which
+ * is also comfortably longer than the six-face bake it follows, so the ramp starts from a
+ * picture that is already complete.
+ */
+const ARRIVAL_SECONDS = 0.25;
+/**
+ * The emitter radius assumed for a light that names none.
+ *
+ * One constant because it is read in three places — the field, the bake and `matchesSource` —
+ * and the whole of the bug it replaces was two of those disagreeing. The bake filled in 0.05
+ * and `matchesSource` compared against `undefined`, so a map baked by a caller that said
+ * nothing was stale on every frame it was ever checked.
+ */
+export const DEFAULT_SOURCE_RADIUS = 0.05;
+const scratchView = mat4.create();
+const scratchLook = mat4.create();
+const scratchProj = mat4.create();
+const scratchEye = vec3.create();
+const scratchCenter = vec3.create();
+/**
+ * One face's view-projection, into a matrix the caller owns.
+ *
+ * A ninety-degree square frustum per face is what makes six of them a cube, so the projection
+ * takes no aspect and no field of view: both are fixed by the shape. Module-scope scratch,
+ * because this runs once per face of every bake and `AGENTS.md` allows no allocation there.
+ */
+export function pointShadowFaceViewProj(face, x, y, z, near, range, out) {
+    const target = FACE_TARGETS[face];
+    if (target === undefined)
+        return out;
+    const dir = target[0];
+    vec3.set(scratchEye, x, y, z);
+    vec3.set(scratchCenter, x + dir[0], y + dir[1], z + dir[2]);
+    mat4.perspective(scratchProj, Math.PI / 2, 1, near, range);
+    mat4.lookAt(scratchView, scratchEye, scratchCenter, target[1]);
+    return mat4.multiply(out, scratchProj, scratchView);
+}
+/**
+ * A face's world-to-face rotation, from the same targets its frustum is built from.
+ *
+ * **The resolve needs one and the bake needs the other, and two tables would eventually
+ * disagree.** A face's octahedral region is written by projecting each texel's direction into that
+ * face's own frame and reading the depth the bake stored there; if the two differ by an up vector,
+ * every texel of that face is read from the wrong place. That reads as a lighting bug and is a
+ * transcription error, so both come off `FACE_TARGETS` and a test puts one point through each and
+ * requires the same image coordinates.
+ *
+ * `lookAt` builds a right-handed view looking down `-z`, so a direction inside this face comes
+ * back with a **negative** `z`. The resolve divides by `-v.z` for that reason and not by
+ * preference.
+ *
+ * Module-scope scratch, because this runs once per resolved face inside the bake budget and
+ * `AGENTS.md` allows no allocation there.
+ */
+export function pointShadowFaceRotation(face, out) {
+    const target = FACE_TARGETS[face];
+    if (target === undefined)
+        return out;
+    const dir = target[0];
+    vec3.set(scratchEye, 0, 0, 0);
+    vec3.set(scratchCenter, dir[0], dir[1], dir[2]);
+    mat4.lookAt(scratchLook, scratchEye, scratchCenter, target[1]);
+    return mat3.fromMat4(out, scratchLook);
+}
+/** A `FaceRange` a map can own for the life of the session, since a bake allocates nothing. */
+export function createFaceRange() {
+    return {
+        first: 0,
+        last: 0,
+        x: 0,
+        y: 0,
+        z: 0,
+        range: 1,
+        near: POINT_SHADOW_NEAR,
+        sourceRadius: DEFAULT_SOURCE_RADIUS,
+    };
+}
+/**
+ * The state of one cubemap: what it was baked for, how present it is, and how far through.
+ *
+ * Held by a backend's map rather than inherited from, so the device resource stays a device
+ * resource and this stays testable without one.
+ */
+export class PointShadowImage {
+    /** Far plane, needed by the shader to linearise the comparison. */
+    far = 1;
+    /** Near plane; the shader needs the same value to linearise. */
+    near = POINT_SHADOW_NEAR;
+    /** Emitter radius of the light this map was baked for. */
+    sourceRadius = DEFAULT_SOURCE_RADIUS;
+    baked = false;
+    arrival = 0;
+    x = 0;
+    y = 0;
+    z = 0;
+    /** Next face a resumed bake will render; 0 when none is in flight. */
+    pendingFace = 0;
+    /** What the in-flight bake was started for, so a changed light restarts it. */
+    pendingX = 0;
+    pendingY = 0;
+    pendingZ = 0;
+    pendingRange = 0;
+    pendingNear = 0;
+    pendingSourceRadius = 0;
+    /** Whether this map holds an image worth sampling. False until a bake completes. */
+    get hasBaked() {
+        return this.baked;
+    }
+    /** How present the image is, 0 to 1. The shader mixes the occlusion in by it. */
+    get presence() {
+        return this.arrival;
+    }
+    /**
+     * Whether this map still represents the source projection well enough to sample.
+     *
+     * `tolerance` is how far the source may drift from where it was baked before the map is
+     * stale. It exists because an exact comparison made a *flame* the most expensive object in
+     * the scene: a brazier wanders a few centimetres every frame to look alive, every frame that
+     * moved the light, and every move re-baked six cubemap faces of the entire static world. Up
+     * to eight sampled lights doing that is where a frame's 174 surplus draw calls came from,
+     * against an `AGENTS.md` budget of a hundred in total.
+     *
+     * A drift tolerance is the honest fix rather than a cheat. The shadow of static geometry
+     * metres away barely moves when the emitter shifts by centimetres, and a fire's shadow that
+     * re-solves every frame reads as strobing rather than as flicker. Callers that genuinely move
+     * a light pass 0 and get the old behaviour, because drift is measured against the *baked*
+     * origin and so accumulates rather than being forgiven each frame.
+     *
+     * `sourceRadius` defaults to exactly what a bake defaults it to, and the two defaults being
+     * one constant is the point rather than a convenience: they disagreed once, `0.05 !== undefined`
+     * was true every frame, every map was stale forever, and with a couple of faces of budget the
+     * only thing on screen was whichever face had most recently finished — a hard square of shadow
+     * that moved as you did. Any default would do as long as it is the same one. Two is the bug.
+     */
+    matchesSource(x, y, z, range, near, sourceRadius = DEFAULT_SOURCE_RADIUS, tolerance = 0) {
+        if (!this.baked ||
+            this.far !== range ||
+            this.near !== near ||
+            this.sourceRadius !== sourceRadius) {
+            return false;
+        }
+        const dx = this.x - x;
+        const dy = this.y - y;
+        const dz = this.z - z;
+        return dx * dx + dy * dy + dz * dz <= tolerance * tolerance;
+    }
+    /**
+     * Ramp the image in over `ARRIVAL_SECONDS`.
+     *
+     * The drastic case, and the one the light's own fade cannot reach. A light leaving takes its
+     * shadow with it, because by the time membership changes the light is already at nothing —
+     * but a light *keeping* its place can still lose its picture, when a pool slot changes hands
+     * and `forget` throws the image away. The re-bake then lands whole between two frames, under
+     * a lamp that has not moved, and a shadow switching on is exactly as wrong as one switching
+     * off.
+     *
+     * Only a first image after a `forget` ramps. A map that merely drifted past the rebake
+     * tolerance keeps `baked` true throughout and stays fully present, which is right: it is
+     * correcting a picture, not arriving with one.
+     */
+    advance(dt) {
+        if (!this.baked) {
+            this.arrival = 0;
+            return;
+        }
+        this.arrival = Math.min(1, this.arrival + dt / ARRIVAL_SECONDS);
+    }
+    /**
+     * Throw away the image, because this map is about to belong to another light.
+     *
+     * A pool slot keeps its cubemap when it changes hands. Without this, `baked` stayed true from
+     * the previous borrower, so the new light reported an image it had never rendered — the *old*
+     * lamp's, taken from somewhere else — and the shader sampled it for the three frames a
+     * re-bake takes at two faces each. That is the flicker: shadows and glare appearing and
+     * disappearing as the camera moves and the chosen eight reorder.
+     *
+     * The partial-bake cursor goes too: a resumed bake must not stitch new faces onto the
+     * previous light's old ones. Presence goes with the image — whatever arrives next is a new
+     * light's, and it arrives as one.
+     */
+    forget() {
+        this.baked = false;
+        this.pendingFace = 0;
+        this.arrival = 0;
+    }
+    /**
+     * Which faces to render now, and what to render them for.
+     *
+     * **A bake in flight owns its parameters until it finishes**, and the returned range carries
+     * them so the caller renders the remaining faces at the place the first ones were rendered
+     * for. Half a cubemap around one point and half around another is not a cubemap around
+     * anything, and this is what stops it being built.
+     *
+     * **It used to abandon a partial image whenever any argument moved, and that is the defect
+     * this replaces.** The comparison was exact — position, range, near plane and emitter radius,
+     * all of them — so a light that changes by any amount between two frames could never satisfy
+     * it. Two kinds are ordinary rather than exotic: a flame wanders a few centimetres every
+     * frame to look alive, and a light whose brightness is expressed as a radius rescales that
+     * radius every frame while it pulses. For either, `pendingFace` was reset to zero on every
+     * frame, so with a budget of two faces the bake rendered faces 0 and 1 for ever and **faces 2
+     * to 5 were never written again**.
+     *
+     * That is not a bake that is merely slow. `resolveFace` writes each face into the light's
+     * octahedral layer as it is rendered, and `hasBaked` stays true from the last bake that did
+     * complete — so the shader keeps sampling a layer holding two faces from where the light is
+     * now and four from wherever it used to be, permanently, at full presence. A cube face is a
+     * 90 degree frustum, so what that draws is a hard-edged quadrilateral of shadow standing on
+     * the ground under the lamp with nothing above it to cast one. Reported as exactly that.
+     *
+     * A light that moves during a bake is not lost: the image completes at the origin it started
+     * from, `matchesSource` finds it stale on the next frame, and a fresh bake starts. What it
+     * costs is a shadow up to `FACE_COUNT / facesPerFrame` frames behind a moving lamp, which is
+     * the trade `pointShadowRebakeDistance` already makes in a coarser form.
+     */
+    planBake(x, y, z, range, near, sourceRadius, maxFaces, out) {
+        if (this.pendingFace <= 0) {
+            this.pendingX = x;
+            this.pendingY = y;
+            this.pendingZ = z;
+            this.pendingRange = range;
+            this.pendingNear = near;
+            this.pendingSourceRadius = sourceRadius;
+        }
+        out.first = this.pendingFace;
+        out.last = Math.min(FACE_COUNT, out.first + Math.max(0, Math.trunc(maxFaces)));
+        out.x = this.pendingX;
+        out.y = this.pendingY;
+        out.z = this.pendingZ;
+        out.range = this.pendingRange;
+        out.near = this.pendingNear;
+        out.sourceRadius = this.pendingSourceRadius;
+        return out;
+    }
+    /**
+     * Record that faces up to `last` have been rendered.
+     *
+     * **`far`, `near` and `sourceRadius` move only when the last face lands**, and that is the
+     * one subtle part. They describe the image the shader is sampling, so publishing them early
+     * would pair new parameters with faces that are still mostly old. A first bake is not sampled
+     * at all until it completes, so this only matters for a re-bake, where holding the old values
+     * keeps them matched to the old faces.
+     */
+    completeBake(last, x, y, z, range, near, sourceRadius) {
+        this.pendingFace = last;
+        if (last < FACE_COUNT)
+            return;
+        this.pendingFace = 0;
+        this.x = x;
+        this.y = y;
+        this.z = z;
+        this.far = range;
+        this.near = near;
+        this.sourceRadius = sourceRadius;
+        this.baked = true;
+    }
+}
+export function createResolvedPointShadows(lights) {
+    /*
+     * **−1 from the moment it exists, because zero is a layer.**
+     *
+     * `flat.ts` reads `uPointShadowLayer[i]` and samples when it is not negative, so a zero-filled
+     * array does not mean "no point shadows" — it means every light in every scene samples layer
+     * zero, which belongs to a live transition map. `resolve` fills these every frame, but a pass
+     * bound before the pool has ever been updated would otherwise upload the zeroes, and a scene
+     * is free to draw before it updates its shadows. Caught by a unit test that failed with
+     * `expected +0 to be -1`; the same trap survives the move from slots to layers, with a worse
+     * failure than before, because layer zero always exists where slot zero often did not.
+     */
+    return {
+        layers: new Int32Array(lights).fill(-1),
+        far: new Float32Array(lights),
+        near: new Float32Array(lights),
+        sourceRadius: new Float32Array(lights),
+        presence: new Float32Array(lights),
+        liveLayers: new Int32Array(lights).fill(-1),
+        liveFar: new Float32Array(lights),
+        liveNear: new Float32Array(lights),
+        liveSourceRadius: new Float32Array(lights),
+        liveWeights: new Float32Array(lights),
+    };
+}

package/dist/render/pointShadowMap.d.ts

@@ -0,0 +1,93 @@
+import { mat4 } from 'gl-matrix';
+import type { PointShadowTarget } from './pointShadowArray.ts';
+import { FACE_COUNT, POINT_SHADOW_NEAR } from './pointShadowImage.ts';
+/**
+ * Omnidirectional shadows for a point light: one octahedral layer, rendered a face at a time.
+ *
+ * Six depth passes per light is normally what makes point-light shadows unaffordable. Static
+ * scenes can bake once; a caller may also rebuild a map for a moving source or nearby moving
+ * casters.
+ *
+ * Game-agnostic: it takes a position, a range, and a callback that draws whatever should cast.
+ *
+ * **All of the state is `PointShadowImage`'s and all of the arithmetic is too**, and now every
+ * GPU object is `PointShadowArray`'s — so what is left here is a layer index and a loop. That
+ * split is what lets a second backend inherit six paid-for decisions rather than re-derive them;
+ * see that file.
+ *
+ * **The six faces are still rasterised under six 90 degree frusta**, unchanged, because that is
+ * the only projection a triangle survives. What changed is where they land: each one goes to the
+ * array's shared scratch and is resolved from there into this map's layer, in the octahedral
+ * projection the shader reads. Nothing about the bake's cost, order or resumption moved.
+ */
+export { FACE_COUNT, POINT_SHADOW_NEAR };
+export declare class PointShadowMap {
+    readonly size: number;
+    /**
+     * Which layer of the shared array this map's image lives in.
+     *
+     * Fixed for the life of the map. The pool hands slots out and takes them back, and a slot's
+     * layer never moves — `forget` throws the *image* away, not the storage — so the shader can be
+     * told a layer index and nothing has to re-upload a texture binding when a light changes hands.
+     */
+    readonly layer: number;
+    /** Everything this map knows about itself that is not a GPU object. */
+    private readonly image;
+    private readonly range;
+    /**
+     * The array this map writes into, read late rather than held.
+     *
+     * The pool builds its live maps when the renderer is constructed, and the array cannot exist
+     * until a world says how many lights it has — and it is rebuilt if a later world says more. A
+     * getter rather than a reference means a map outlives both events without knowing about either.
+     * Called once per resolved face, which is nowhere near a per-fragment path.
+     */
+    private readonly array;
+    get far(): number;
+    get near(): number;
+    get sourceRadius(): number;
+    /** Whether this map holds an image worth sampling. False until a bake completes. */
+    get hasBaked(): boolean;
+    /** How present the image is, 0 to 1. The shader mixes the occlusion in by it. */
+    get presence(): number;
+    /** Whether this map still represents the source well enough to sample. See the image. */
+    matchesSource(x: number, y: number, z: number, range: number, near: number, sourceRadius?: number, tolerance?: number): boolean;
+    /** Ramp the image in. See the image. */
+    advance(dt: number): void;
+    /** Throw the image away, because this map is about to belong to another light. */
+    forget(): void;
+    constructor(array: () => PointShadowTarget | null, layer: number, size?: number);
+    /**
+     * Render up to `maxFaces` of the six, resuming a bake already under way.
+     * Returns how many faces were rendered.
+     *
+     * `drawCasters` receives each face's view-projection and issues its draw calls, so a
+     * face is a full pass over the caster set and six of them is the whole cost. Doing
+     * all six unconditionally is what made this the most expensive thing in the frame the
+     * moment several lights went stale together: eight lights is 48 passes, measured at
+     * 89 ms and 99 ms in two consecutive frames against an 8.3 ms budget. The caller
+     * spends a per-frame face budget across the lights that need one; see
+     * `pointShadowBudget.ts`.
+     *
+     * A resumed bake keeps the origin it started with, **whatever this call is passed**:
+     * half a cubemap around one point and half around another is not a cubemap around
+     * anything, and a light that moves every frame used to produce exactly that, for ever.
+     * See `planBake`. Different arguments are honoured by the *next* bake, which the
+     * staleness test starts as soon as this one lands.
+     *
+     * **`far`, `near` and `sourceRadius` move only when the last face lands**, and that is
+     * the one subtle part. They describe the image the shader is sampling, so publishing
+     * them early would pair new parameters with faces that are still mostly old. A first
+     * bake is not sampled at all until it completes, so this only matters for a re-bake,
+     * where holding the old values keeps them matched to the old faces.
+     */
+    bake(gl: WebGL2RenderingContext, x: number, y: number, z: number, range: number, drawCasters: (viewProj: mat4) => void, near?: number, sourceRadius?: number, maxFaces?: number): number;
+    /**
+     * Nothing to free: every GPU object this map used to own belongs to `PointShadowArray` now.
+     *
+     * Kept because the pool's `releaseMap` calls it, and because a map that silently stopped
+     * needing disposal is exactly the shape of a leak nobody notices. The array is disposed by the
+     * renderer that built it.
+     */
+    dispose(_gl: WebGL2RenderingContext): void;
+}

package/dist/render/pointShadowMap.js

@@ -0,0 +1,167 @@
+import { mat4 } from 'gl-matrix';
+import { DEFAULT_RENDER_QUALITY } from './renderQuality.js';
+import { createFaceRange, DEFAULT_SOURCE_RADIUS, FACE_COUNT, POINT_SHADOW_NEAR, PointShadowImage, pointShadowFaceViewProj, } from './pointShadowImage.js';
+/**
+ * Omnidirectional shadows for a point light: one octahedral layer, rendered a face at a time.
+ *
+ * Six depth passes per light is normally what makes point-light shadows unaffordable. Static
+ * scenes can bake once; a caller may also rebuild a map for a moving source or nearby moving
+ * casters.
+ *
+ * Game-agnostic: it takes a position, a range, and a callback that draws whatever should cast.
+ *
+ * **All of the state is `PointShadowImage`'s and all of the arithmetic is too**, and now every
+ * GPU object is `PointShadowArray`'s — so what is left here is a layer index and a loop. That
+ * split is what lets a second backend inherit six paid-for decisions rather than re-derive them;
+ * see that file.
+ *
+ * **The six faces are still rasterised under six 90 degree frusta**, unchanged, because that is
+ * the only projection a triangle survives. What changed is where they land: each one goes to the
+ * array's shared scratch and is resolved from there into this map's layer, in the octahedral
+ * projection the shader reads. Nothing about the bake's cost, order or resumption moved.
+ */
+/* Re-exported so callers that reach for these through this module keep working. */
+export { FACE_COUNT, POINT_SHADOW_NEAR };
+const scratchViewProj = mat4.create();
+export class PointShadowMap {
+    size;
+    /**
+     * Which layer of the shared array this map's image lives in.
+     *
+     * Fixed for the life of the map. The pool hands slots out and takes them back, and a slot's
+     * layer never moves — `forget` throws the *image* away, not the storage — so the shader can be
+     * told a layer index and nothing has to re-upload a texture binding when a light changes hands.
+     */
+    layer;
+    /** Everything this map knows about itself that is not a GPU object. */
+    image = new PointShadowImage();
+    range = createFaceRange();
+    /**
+     * The array this map writes into, read late rather than held.
+     *
+     * The pool builds its live maps when the renderer is constructed, and the array cannot exist
+     * until a world says how many lights it has — and it is rebuilt if a later world says more. A
+     * getter rather than a reference means a map outlives both events without knowing about either.
+     * Called once per resolved face, which is nowhere near a per-fragment path.
+     */
+    array;
+    get far() {
+        return this.image.far;
+    }
+    get near() {
+        return this.image.near;
+    }
+    get sourceRadius() {
+        return this.image.sourceRadius;
+    }
+    /** Whether this map holds an image worth sampling. False until a bake completes. */
+    get hasBaked() {
+        return this.image.hasBaked;
+    }
+    /** How present the image is, 0 to 1. The shader mixes the occlusion in by it. */
+    get presence() {
+        return this.image.presence;
+    }
+    /** Whether this map still represents the source well enough to sample. See the image. */
+    matchesSource(x, y, z, range, near, sourceRadius = DEFAULT_SOURCE_RADIUS, tolerance = 0) {
+        return this.image.matchesSource(x, y, z, range, near, sourceRadius, tolerance);
+    }
+    /** Ramp the image in. See the image. */
+    advance(dt) {
+        this.image.advance(dt);
+    }
+    /** Throw the image away, because this map is about to belong to another light. */
+    forget() {
+        this.image.forget();
+    }
+    constructor(array, layer, size = DEFAULT_RENDER_QUALITY.pointShadowFaceSize) {
+        this.array = array;
+        this.layer = layer;
+        this.size = size;
+    }
+    /**
+     * Render up to `maxFaces` of the six, resuming a bake already under way.
+     * Returns how many faces were rendered.
+     *
+     * `drawCasters` receives each face's view-projection and issues its draw calls, so a
+     * face is a full pass over the caster set and six of them is the whole cost. Doing
+     * all six unconditionally is what made this the most expensive thing in the frame the
+     * moment several lights went stale together: eight lights is 48 passes, measured at
+     * 89 ms and 99 ms in two consecutive frames against an 8.3 ms budget. The caller
+     * spends a per-frame face budget across the lights that need one; see
+     * `pointShadowBudget.ts`.
+     *
+     * A resumed bake keeps the origin it started with, **whatever this call is passed**:
+     * half a cubemap around one point and half around another is not a cubemap around
+     * anything, and a light that moves every frame used to produce exactly that, for ever.
+     * See `planBake`. Different arguments are honoured by the *next* bake, which the
+     * staleness test starts as soon as this one lands.
+     *
+     * **`far`, `near` and `sourceRadius` move only when the last face lands**, and that is
+     * the one subtle part. They describe the image the shader is sampling, so publishing
+     * them early would pair new parameters with faces that are still mostly old. A first
+     * bake is not sampled at all until it completes, so this only matters for a re-bake,
+     * where holding the old values keeps them matched to the old faces.
+     */
+    bake(gl, x, y, z, range, drawCasters, near = POINT_SHADOW_NEAR, sourceRadius = DEFAULT_SOURCE_RADIUS, maxFaces = FACE_COUNT) {
+        /*
+         * What to render now, **and what to render it for**. A bake in flight owns the parameters
+         * it started with, so the arguments here are only a proposal for a bake that is not already
+         * under way; see `planBake` for the permanent artefact that reading them unconditionally
+         * left in a moving light's map.
+         */
+        const plan = this.image.planBake(x, y, z, range, near, sourceRadius, maxFaces, this.range);
+        const { first, last } = plan;
+        if (last <= first)
+            return 0;
+        const array = this.array();
+        if (array === null)
+            return 0;
+        /*
+         * Cull nothing.
+         *
+         * Rendering back faces only is the usual acne cure, but it 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.
+         * Acne is handled properly by the slope-scaled bias in the flat shader,
+         * which is where it belongs: it is a function of the receiving angle, not
+         * of which faces were rasterised.
+         */
+        gl.disable(gl.CULL_FACE);
+        /*
+         * Render, resolve, repeat — and the *repeat* is what makes one scratch serve every light.
+         *
+         * A face's octahedral region is disjoint from the other five, so the scratch is consumed the
+         * moment `resolveFace` reads it and is free again before the next face touches it. That holds
+         * across lights too, which matters: `pointShadowBudget.ts` spends one frame's face budget
+         * across several stale maps, so a scratch that had to survive a whole six-face bake would be
+         * clobbered by whichever light baked next.
+         *
+         * Completeness is checked once, in the array's constructor. See the note there: asking here
+         * is a pipeline flush in the middle of the frame loop.
+         */
+        for (let face = first; face < last; face++) {
+            array.beginFace(gl);
+            drawCasters(pointShadowFaceViewProj(face, plan.x, plan.y, plan.z, plan.near, plan.range, scratchViewProj));
+            /*
+             * The casters left culling off and the resolve is a fullscreen triangle, so it does not
+             * care; `resolveFace` restores the depth function it borrows, which is the one thing the
+             * next face's pass does care about.
+             */
+            array.resolveFace(gl, this.layer, face, plan.range, plan.near);
+        }
+        gl.enable(gl.CULL_FACE);
+        gl.cullFace(gl.BACK);
+        gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+        this.image.completeBake(last, plan.x, plan.y, plan.z, plan.range, plan.near, plan.sourceRadius);
+        return last - first;
+    }
+    /**
+     * Nothing to free: every GPU object this map used to own belongs to `PointShadowArray` now.
+     *
+     * Kept because the pool's `releaseMap` calls it, and because a map that silently stopped
+     * needing disposal is exactly the shape of a leak nobody notices. The array is disposed by the
+     * renderer that built it.
+     */
+    dispose(_gl) { }
+}