@driftengine/core 3.61.0

package/dist/render/ambientOcclusionPass.js

@@ -0,0 +1,179 @@
+import { AO_BLUR_FRAG, AO_FRAG } from './shaders/ambientOcclusion.js';
+import { FULLSCREEN_VERT } from './shaders/fullscreen.js';
+import { compileProgram, uniformLocations } from './shader.js';
+/**
+ * The screen-space ambient occlusion pass: estimate from depth, then blur.
+ *
+ * Its own module rather than more of `SceneTarget`, because it is its own responsibility —
+ * that class owns where the frame lands and how it reaches the canvas, and this owns one
+ * effect's targets and programs. The composite pass consumes the texture this returns and
+ * knows nothing else about it.
+ *
+ * **Two single-channel targets, ping-ponged.** The estimate lands in one, the horizontal
+ * blur writes the other, the vertical blur writes back into the first, and that one is
+ * returned. `R8` rather than `RGBA8`: occlusion is one number, and three channels of padding
+ * over a 4K frame is 24 MB of bandwidth per pass to carry nothing.
+ */
+export class AmbientOcclusionPass {
+    gl;
+    width = 0;
+    height = 0;
+    estimate = null;
+    scratch = null;
+    estimateFramebuffer = null;
+    scratchFramebuffer = null;
+    /**
+     * Set once if a single-channel target will not complete, after which this pass does
+     * nothing and says so once.
+     *
+     * `R8` is colour-renderable in WebGL2 by specification, so this is not expected. It is here
+     * because the alternative to an honest "off" is a frame multiplied by a texture that was
+     * never written, and the last time an effect in this renderer sampled a target nobody had
+     * filled, the failure presented as the driver being at fault. See `sceneTarget.ts`.
+     */
+    unavailable = false;
+    estimateProgram;
+    estimateUniforms;
+    blurProgram;
+    blurUniforms;
+    vao;
+    /** Scratch for the blur direction, so a per-frame pass allocates nothing. */
+    step = new Float32Array(2);
+    /** Scratch for the four inverse-projection terms the blur linearises depth with. */
+    depthToViewZ = new Float32Array(4);
+    constructor(gl) {
+        this.gl = gl;
+        this.estimateProgram = compileProgram(gl, FULLSCREEN_VERT, AO_FRAG, 'ao');
+        this.estimateUniforms = uniformLocations(gl, this.estimateProgram, 'ao');
+        this.blurProgram = compileProgram(gl, FULLSCREEN_VERT, AO_BLUR_FRAG, 'aoBlur');
+        this.blurUniforms = uniformLocations(gl, this.blurProgram, 'aoBlur');
+        const vao = gl.createVertexArray();
+        if (vao === null)
+            throw new Error('AmbientOcclusionPass: createVertexArray failed');
+        this.vao = vao;
+    }
+    ensureSize(width, height) {
+        if (this.unavailable)
+            return false;
+        if (this.width === width && this.height === height && this.estimate !== null)
+            return true;
+        const { gl } = this;
+        this.width = width;
+        this.height = height;
+        this.estimate = this.allocate(this.estimate, width, height);
+        this.scratch = this.allocate(this.scratch, width, height);
+        if (this.estimateFramebuffer === null)
+            this.estimateFramebuffer = gl.createFramebuffer();
+        gl.bindFramebuffer(gl.FRAMEBUFFER, this.estimateFramebuffer);
+        gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, this.estimate, 0);
+        const estimateReady = gl.checkFramebufferStatus(gl.FRAMEBUFFER) === gl.FRAMEBUFFER_COMPLETE;
+        if (this.scratchFramebuffer === null)
+            this.scratchFramebuffer = gl.createFramebuffer();
+        gl.bindFramebuffer(gl.FRAMEBUFFER, this.scratchFramebuffer);
+        gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, this.scratch, 0);
+        const scratchReady = gl.checkFramebufferStatus(gl.FRAMEBUFFER) === gl.FRAMEBUFFER_COMPLETE;
+        gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+        gl.bindTexture(gl.TEXTURE_2D, null);
+        if (!estimateReady || !scratchReady) {
+            this.unavailable = true;
+            console.warn('AmbientOcclusionPass: this driver will not render to a single-channel target, so ' +
+                'ambient occlusion is off. The frame itself is unaffected.');
+            return false;
+        }
+        return true;
+    }
+    allocate(existing, width, height) {
+        const { gl } = this;
+        const texture = existing ?? gl.createTexture();
+        gl.bindTexture(gl.TEXTURE_2D, texture);
+        gl.texImage2D(gl.TEXTURE_2D, 0, gl.R8, width, height, 0, gl.RED, gl.UNSIGNED_BYTE, null);
+        /* NEAREST, because every read of this is at a texel centre: the blur steps whole pixels
+           and the composite reads the pixel it is shading. Linear would only cost filtering. */
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
+        /* Clamped, so a tap past the edge repeats the edge rather than wrapping the opposite
+           side of the frame into a corner. */
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+        return texture;
+    }
+    /**
+     * Estimate occlusion from the frame's depth and blur it. Returns the texture to multiply
+     * by, or null if this pass could not run, which the caller must read as "no occlusion"
+     * rather than as black.
+     *
+     * `invProjection` is column-major, as `gl-matrix` produces it.
+     */
+    run(depth, width, height, radius, projScale, invProjection) {
+        if (!this.ensureSize(width, height))
+            return null;
+        const { gl } = this;
+        /* One triangle over a target with no depth attachment. Anything inherited from the scene
+           pass would be tested against a buffer that is not there. */
+        gl.disable(gl.DEPTH_TEST);
+        gl.disable(gl.BLEND);
+        gl.disable(gl.CULL_FACE);
+        gl.depthMask(false);
+        gl.bindVertexArray(this.vao);
+        gl.viewport(0, 0, width, height);
+        gl.bindFramebuffer(gl.FRAMEBUFFER, this.estimateFramebuffer);
+        gl.useProgram(this.estimateProgram);
+        gl.activeTexture(gl.TEXTURE0);
+        gl.bindTexture(gl.TEXTURE_2D, depth);
+        gl.uniform1i(this.estimateUniforms['uDepth'] ?? null, 0);
+        gl.uniform2fv(this.estimateUniforms['uProjScale'] ?? null, projScale);
+        gl.uniform1f(this.estimateUniforms['uRadius'] ?? null, radius);
+        gl.uniformMatrix4fv(this.estimateUniforms['uInvProjection'] ?? null, false, invProjection);
+        gl.drawArrays(gl.TRIANGLES, 0, 3);
+        /*
+         * The four terms that carry a depth back to metres, read out of the inverse projection.
+         * Column major, so `[2][2]` is element 10 and `[3][3]` is element 15.
+         */
+        this.depthToViewZ[0] = invProjection[10] ?? 0;
+        this.depthToViewZ[1] = invProjection[14] ?? 0;
+        this.depthToViewZ[2] = invProjection[11] ?? 0;
+        this.depthToViewZ[3] = invProjection[15] ?? 1;
+        gl.useProgram(this.blurProgram);
+        gl.uniform1i(this.blurUniforms['uAo'] ?? null, 0);
+        gl.uniform1i(this.blurUniforms['uDepth'] ?? null, 1);
+        gl.uniform4fv(this.blurUniforms['uDepthToViewZ'] ?? null, this.depthToViewZ);
+        gl.activeTexture(gl.TEXTURE1);
+        gl.bindTexture(gl.TEXTURE_2D, depth);
+        /* Across, into the scratch target. */
+        gl.bindFramebuffer(gl.FRAMEBUFFER, this.scratchFramebuffer);
+        gl.activeTexture(gl.TEXTURE0);
+        gl.bindTexture(gl.TEXTURE_2D, this.estimate);
+        this.step[0] = 1 / width;
+        this.step[1] = 0;
+        gl.uniform2fv(this.blurUniforms['uStep'] ?? null, this.step);
+        gl.drawArrays(gl.TRIANGLES, 0, 3);
+        /* And down, back into the estimate, which is the texture handed out. */
+        gl.bindFramebuffer(gl.FRAMEBUFFER, this.estimateFramebuffer);
+        gl.bindTexture(gl.TEXTURE_2D, this.scratch);
+        this.step[0] = 0;
+        this.step[1] = 1 / height;
+        gl.uniform2fv(this.blurUniforms['uStep'] ?? null, this.step);
+        gl.drawArrays(gl.TRIANGLES, 0, 3);
+        gl.bindVertexArray(null);
+        gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+        return this.estimate;
+    }
+    dispose() {
+        const { gl } = this;
+        if (this.estimateFramebuffer !== null)
+            gl.deleteFramebuffer(this.estimateFramebuffer);
+        if (this.scratchFramebuffer !== null)
+            gl.deleteFramebuffer(this.scratchFramebuffer);
+        if (this.estimate !== null)
+            gl.deleteTexture(this.estimate);
+        if (this.scratch !== null)
+            gl.deleteTexture(this.scratch);
+        gl.deleteProgram(this.estimateProgram);
+        gl.deleteProgram(this.blurProgram);
+        gl.deleteVertexArray(this.vao);
+        this.estimateFramebuffer = null;
+        this.scratchFramebuffer = null;
+        this.estimate = null;
+        this.scratch = null;
+    }
+}

package/dist/render/areaLights.d.ts

@@ -0,0 +1,116 @@
+/** Rectangular area lights: what a caller declares, and the arrays a shader wants. */
+/**
+ * How many rectangles the lit pass shades against at once.
+ *
+ * **Four, because a rectangle is a fixture rather than a lamp.** A window, a softbox, a lit panel:
+ * a scene with more than a handful of these is a scene that wants them baked into an environment,
+ * which is what the prefilter and the loader are for. Raising it is a uniform-array size and an
+ * iteration of the loop, exactly as `MAX_POINT_LIGHTS` is.
+ */
+export declare const MAX_AREA_LIGHTS = 4;
+/**
+ * One rectangular emitter, as a consumer describes it.
+ *
+ * Positions, colours and sizes, and nothing that means anything in one game — the rule
+ * `AGENTS.md` opens with. `right` and `up` are the rectangle's own in-plane axes, and their cross
+ * product is the direction it emits.
+ */
+export interface AreaLightSource {
+    x: number;
+    y: number;
+    z: number;
+    r: number;
+    g: number;
+    b: number;
+    /** In-plane axes. Normalised on the way in, because the form factor assumes unit length. */
+    rightX: number;
+    rightY: number;
+    rightZ: number;
+    upX: number;
+    upY: number;
+    upZ: number;
+    /** Half extents along `right` and `up`, in metres. */
+    halfWidth: number;
+    halfHeight: number;
+    /**
+     * Whether the rectangle emits from both faces. Default false.
+     *
+     * A window is one-sided and a hanging panel is two-sided, and the difference is visible rather
+     * than pedantic: a one-sided light must contribute nothing to a surface behind it, or the wall
+     * it is set into is lit by it and reads as glowing.
+     */
+    twoSided?: boolean;
+    /**
+     * Whether this rectangle is worth a shadow layer at all. **Default false**, which is the
+     * opposite of what a point light's identically named field defaults to.
+     *
+     * A point light has cast since before there was a budget to ration, so `true` is what its
+     * existing callers already rely on. An area light shipped in 3.2.0 with no occlusion at all —
+     * `AGENTS.md` calls that a bug rather than a limitation, and it is the row this field closes —
+     * so every scene that already declares one was authored against a rectangle that lights
+     * through walls. Defaulting to `true` here would hand each of them two octahedral layers,
+     * 8.39 MB, and a six-face bake over the static world, for a change in the picture nobody asked
+     * for. `RenderQuality`'s own rule is that a feature's default reproduces today's frame.
+     *
+     * **It also rides `RenderQuality.pointShadows`**, because an area light's occlusion is read out
+     * of the same array texture a point light's is. WebGL2 guarantees sixteen texture units and the
+     * lit pass binds sixteen, so a seventeenth sampler is not available to declare — see
+     * `FlatShaderOptions.environmentProbe` for the same wall reached from the other side. With that
+     * flag off there is no array to bake into, and the renderer says so once by name rather than
+     * quietly drawing an unoccluded rectangle.
+     */
+    castsShadow?: boolean;
+    /**
+     * How far from the rectangle occlusion is tracked, in metres: the shadow map's far plane.
+     *
+     * **Required when `castsShadow` is true, and deliberately not defaulted.** A point light's map
+     * gets its far plane from `radius`, the distance at which the light itself reaches zero — a
+     * rectangle has no such distance, because its falloff is the solid angle it subtends and that is
+     * never exactly zero. So the number is a statement about how much of the scene this fixture is
+     * responsible for occluding, which is a decision about the content: a panel in a corridor wants
+     * the corridor's length and a sky panel over a courtyard wants the courtyard's.
+     *
+     * Guessing it would produce one of two failures, both of which read as a renderer bug rather
+     * than a missing field: too short and the shadow stops in a straight line partway across the
+     * floor, too long and the depth precision spent on the near metres is what a fixture actually
+     * needed. A rectangle that declares it casts and names no range is refused with a warning
+     * naming the field.
+     */
+    shadowRange?: number;
+    /**
+     * Where casting begins, in metres from the rectangle's plane. Defaults to `POINT_SHADOW_NEAR`.
+     *
+     * The same knob a point light carries and for the same reason: a fixture's own housing sits
+     * within centimetres of the emitter, occludes an enormous solid angle from it, and throws that
+     * across the floor as a hard square much larger than the housing. Keep it small — it clips
+     * every caster, not just the fixture.
+     */
+    shadowNear?: number;
+}
+/** The five arrays the shader declares, filled once a frame from whatever a caller supplied. */
+export interface AreaLightBuffer {
+    count: number;
+    readonly positions: Float32Array;
+    readonly colors: Float32Array;
+    readonly right: Float32Array;
+    readonly up: Float32Array;
+    readonly sizes: Float32Array;
+    readonly twoSided: Float32Array;
+}
+export declare function createAreaLightBuffer(capacity?: number): AreaLightBuffer;
+/**
+ * Fill the buffer from a caller's list, normalising the axes and orthogonalising them.
+ *
+ * **Both corrections are here rather than trusted**, and neither is defensive tidying:
+ *
+ * - The form factor treats `right` and `up` as unit vectors, so a caller's un-normalised axis
+ *   scales the rectangle it describes. That is a light of the wrong *size*, which reads as the
+ *   half extents having been set wrong.
+ * - The two axes are made perpendicular, because a rectangle whose axes are not describes a
+ *   parallelogram — and the form factor is defined for the polygon its four corners make, so what
+ *   comes out is the irradiance of a shape the caller did not ask for and cannot see the outline
+ *   of.
+ *
+ * Allocation-free: it fills a target the caller owns, because this runs per frame.
+ */
+export declare function selectAreaLights(lights: readonly AreaLightSource[], out: AreaLightBuffer): AreaLightBuffer;

package/dist/render/areaLights.js

@@ -0,0 +1,91 @@
+/** Rectangular area lights: what a caller declares, and the arrays a shader wants. */
+/**
+ * How many rectangles the lit pass shades against at once.
+ *
+ * **Four, because a rectangle is a fixture rather than a lamp.** A window, a softbox, a lit panel:
+ * a scene with more than a handful of these is a scene that wants them baked into an environment,
+ * which is what the prefilter and the loader are for. Raising it is a uniform-array size and an
+ * iteration of the loop, exactly as `MAX_POINT_LIGHTS` is.
+ */
+export const MAX_AREA_LIGHTS = 4;
+export function createAreaLightBuffer(capacity = MAX_AREA_LIGHTS) {
+    return {
+        count: 0,
+        positions: new Float32Array(capacity * 3),
+        colors: new Float32Array(capacity * 3),
+        right: new Float32Array(capacity * 3),
+        up: new Float32Array(capacity * 3),
+        sizes: new Float32Array(capacity * 2),
+        twoSided: new Float32Array(capacity),
+    };
+}
+/**
+ * Fill the buffer from a caller's list, normalising the axes and orthogonalising them.
+ *
+ * **Both corrections are here rather than trusted**, and neither is defensive tidying:
+ *
+ * - The form factor treats `right` and `up` as unit vectors, so a caller's un-normalised axis
+ *   scales the rectangle it describes. That is a light of the wrong *size*, which reads as the
+ *   half extents having been set wrong.
+ * - The two axes are made perpendicular, because a rectangle whose axes are not describes a
+ *   parallelogram — and the form factor is defined for the polygon its four corners make, so what
+ *   comes out is the irradiance of a shape the caller did not ask for and cannot see the outline
+ *   of.
+ *
+ * Allocation-free: it fills a target the caller owns, because this runs per frame.
+ */
+export function selectAreaLights(lights, out) {
+    const capacity = Math.floor(out.sizes.length / 2);
+    const count = Math.min(lights.length, capacity);
+    out.count = count;
+    for (let slot = 0; slot < count; slot++) {
+        const light = lights[slot];
+        if (light === undefined)
+            continue;
+        out.positions[slot * 3] = light.x;
+        out.positions[slot * 3 + 1] = light.y;
+        out.positions[slot * 3 + 2] = light.z;
+        out.colors[slot * 3] = light.r;
+        out.colors[slot * 3 + 1] = light.g;
+        out.colors[slot * 3 + 2] = light.b;
+        const rx = light.rightX;
+        const ry = light.rightY;
+        const rz = light.rightZ;
+        const rLen = Math.sqrt(rx * rx + ry * ry + rz * rz) || 1;
+        const nrx = rx / rLen;
+        const nry = ry / rLen;
+        const nrz = rz / rLen;
+        /* Gram-Schmidt: up loses whatever component it shared with right, then is normalised. */
+        const ux = light.upX;
+        const uy = light.upY;
+        const uz = light.upZ;
+        const along = ux * nrx + uy * nry + uz * nrz;
+        let oux = ux - nrx * along;
+        let ouy = uy - nry * along;
+        let ouz = uz - nrz * along;
+        const uLen = Math.sqrt(oux * oux + ouy * ouy + ouz * ouz);
+        if (uLen < 1e-6) {
+            /*
+             * Parallel axes describe no rectangle at all. Any perpendicular will do rather than leaving
+             * a zero vector, which would make every corner the same point and every form factor NaN —
+             * a light that blanks whatever it touches, from two numbers a caller got wrong.
+             */
+            const fallback = Math.abs(nry) < 0.9 ? [0, 1, 0] : [1, 0, 0];
+            oux = (fallback[1] ?? 0) * nrz - (fallback[2] ?? 0) * nry;
+            ouy = (fallback[2] ?? 0) * nrx - (fallback[0] ?? 0) * nrz;
+            ouz = (fallback[0] ?? 0) * nry - (fallback[1] ?? 0) * nrx;
+        }
+        const finalLen = Math.sqrt(oux * oux + ouy * ouy + ouz * ouz) || 1;
+        out.right[slot * 3] = nrx;
+        out.right[slot * 3 + 1] = nry;
+        out.right[slot * 3 + 2] = nrz;
+        out.up[slot * 3] = oux / finalLen;
+        out.up[slot * 3 + 1] = ouy / finalLen;
+        out.up[slot * 3 + 2] = ouz / finalLen;
+        /* Never zero: a rectangle with no extent has no solid angle and no light. */
+        out.sizes[slot * 2] = Math.max(1e-4, light.halfWidth);
+        out.sizes[slot * 2 + 1] = Math.max(1e-4, light.halfHeight);
+        out.twoSided[slot] = light.twoSided === true ? 1 : 0;
+    }
+    return out;
+}

package/dist/render/areaShadowSet.d.ts

@@ -0,0 +1,184 @@
+/**
+ * Occlusion for a rectangular area light: which layers it holds, when they re-bake, and what the
+ * shader is told about them.
+ *
+ * **An area light's shadow is a point light's shadow rendered from the rectangle's centre**, and
+ * the whole of what makes it an *area* shadow is where the penumbra's width comes from. A point
+ * light hands the filter one number, `sourceRadius`, and gets a round penumbra. A rectangle hands
+ * it two half extents and the filter opens along the rectangle's own axes, so a long cable of
+ * bulbs — the case this was reported for — throws one broad shadow that is soft along the cable
+ * and tight across it, rather than nine overlapping hard ones that pile up where they cross.
+ * That part is `areaShadow()` in `shaders/flat/pointShadow.ts`; this file is the storage and the
+ * scheduling in front of it.
+ *
+ * **Rendering from the centre is an approximation and it is the one this technique is.** The
+ * correct answer integrates visibility over the rectangle, which is many shadow maps or a ray
+ * query; one map from the centre plus a filter whose width is the emitter's own extent is the
+ * standard percentage-closer soft shadow, and what it gets wrong is contact: a caster touching a
+ * surface has an umbra there whatever the source's size, and the widened filter still softens it
+ * slightly. **What would make it visibly wrong** is a rectangle much wider than its distance to
+ * the caster, where different points on the emitter see genuinely different silhouettes — a
+ * ceiling-wide panel a hand's width above a table.
+ *
+ * **Why these layers are dedicated rather than pooled**, which is the one decision here that
+ * reverses a note written before it: `POINT_SHADOW_POOL` rations layers because up to fifty lamps
+ * compete for twelve, and the eviction rule is what keeps that from costing 327 MB. At most
+ * `MAX_AREA_LIGHTS` rectangles exist and every one of them is shaded, so there is nothing to
+ * ration — and `preamble.ts` already states the rule that matters here: a shadow budget below the
+ * shading budget means some lights illuminate without occluding and *which* ones changes as the
+ * camera moves, which reads as shadows switching on and off. Matching the two budgets makes that
+ * impossible rather than rare. So the layers are sized from how many rectangles a world says will
+ * cast, exactly as `PointShadowArray` sizes itself from the world's light count rather than from
+ * the maximum.
+ *
+ * **What that costs, arithmetic rather than estimate:** an octahedral layer is
+ * `OCTAHEDRAL_EDGE` squared at four bytes, 4.19 MB, and a casting rectangle takes two — one for
+ * the static world and one for the movers. 8.39 MB each, 33.6 MB if a world declares the full
+ * four, nothing at all for a world whose rectangles do not cast. The point pool at its own
+ * maximum is 58.7 MB for comparison.
+ *
+ * **Why two layers and not one.** A single layer would have to hold the static world and the
+ * movers together, so a person walking under the rectangle would re-bake six passes over the whole
+ * static scene every frame — `pointShadowBudget.ts` measured that shape at 89 ms and 99 ms in two
+ * consecutive frames against an 8.3 ms budget, and it is the reason point lights split the two in
+ * the first place. Movers alone are a handful of meshes, so the live layer is affordable every
+ * frame and the static one is baked once for a fixture that never moves.
+ */
+import type { AreaLightSource } from './areaLights.ts';
+import { type BakeScratch } from './pointShadowBudget.ts';
+/** A static layer and a live one. See the header for why it is not one. */
+export declare const LAYERS_PER_AREA_LIGHT = 2;
+/**
+ * How many layers of the shared array a world's rectangles will take.
+ *
+ * Two per rectangle that declares it casts and names a range, and none for one that does not. A
+ * rectangle past `MAX_AREA_LIGHTS` is not shaded, so it gets no layer either — a layer for a light
+ * the loop never reaches is storage nothing can read.
+ */
+export declare function areaShadowLayerCount(lights: readonly AreaLightSource[]): number;
+/**
+ * Where the area layers begin, given how many point lights the world has.
+ *
+ * **One function rather than the same expression written in three files**, which is the mistake
+ * `pointShadowImage.ts` records at `DEFAULT_SOURCE_RADIUS`: the array sizes itself, this set hands
+ * out indices, and the two disagreeing by one would have every rectangle sampling a lamp's map.
+ * Both call this.
+ */
+export declare function firstAreaShadowLayer(pointLightCount: number): number;
+/**
+ * The range a rectangle will actually cast over, or 0 for one that will not.
+ *
+ * **A declared `castsShadow` with no `shadowRange` counts as not casting**, because there is no
+ * honest far plane to invent for it — see the field. The renderer says so once by name; this
+ * function is only the predicate, and it is shared so the layer count and the map assignment
+ * cannot answer it differently.
+ */
+export declare function castingRange(light: AreaLightSource | undefined): number;
+/** What the shader is told about each rectangle's occlusion, filled once a frame. */
+export interface ResolvedAreaShadows {
+    /** Which array layer holds this rectangle's static image, or -1 for none. */
+    readonly layer: Int32Array;
+    readonly far: Float32Array;
+    readonly near: Float32Array;
+    /** How present the image is, 0 to 1, so a fresh bake arrives rather than appears. */
+    readonly weight: Float32Array;
+    /** The same four for the layer holding movers only. */
+    readonly liveLayer: Int32Array;
+    readonly liveFar: Float32Array;
+    readonly liveNear: Float32Array;
+    readonly liveWeight: Float32Array;
+}
+export declare function createResolvedAreaShadows(slots?: number): ResolvedAreaShadows;
+/**
+ * What a map must answer for this set to schedule and publish it.
+ *
+ * Structurally exactly what `PointShadowMap` and `GpuPointShadowMap` already are, which is the
+ * point: an area light's map is a point light's map on a layer of the same array, so neither
+ * backend needs a second class and neither can drift from the other about staleness, arrival or
+ * resumption. All of that lives in `PointShadowImage`, inside both of them.
+ */
+export interface AreaShadowMap {
+    readonly layer: number;
+    readonly far: number;
+    readonly near: number;
+    readonly hasBaked: boolean;
+    readonly presence: number;
+    matchesSource(x: number, y: number, z: number, range: number, near: number, sourceRadius: number, tolerance: number): boolean;
+    advance(dt: number): void;
+    forget(): void;
+}
+/** The one thing this set cannot do itself: put faces of a world into a layer. */
+export type BakeAreaFaces<M> = (map: M, light: AreaLightSource, range: number, near: number, casters: unknown, maxFaces: number) => number;
+/**
+ * The maps a world's casting rectangles hold, and when each of them re-bakes.
+ *
+ * Constructed with a factory rather than a device, for the reason `PointShadowSystem` is: every
+ * decision in here is about scheduling and none of it is about a texture, so both backends share
+ * this file and supply one callback each.
+ */
+export declare class AreaShadowSet<M extends AreaShadowMap> {
+    private readonly createMap;
+    private readonly releaseMap;
+    /** Indexed by area-light slot. `undefined` where that slot does not cast. */
+    private readonly statics;
+    private readonly lives;
+    /** What each slot was prepared for, so a changed declaration rebuilds rather than lies. */
+    private readonly ranges;
+    private firstLayer;
+    constructor(createMap: (layer: number) => M, releaseMap: (map: M) => void);
+    /** How many slots currently hold a static map. For a renderer publishing its own state. */
+    get castingCount(): number;
+    /**
+     * Hand out layers for the rectangles that will cast. Called when the world's lights are known.
+     *
+     * **Rebuilt from scratch rather than patched**, because the layer a map owns is fixed for its
+     * life — `PointShadowMap.layer` is `readonly` and the shader is told an index — so a rectangle
+     * that starts or stops casting moves every layer after it. That happens at load, not per frame.
+     */
+    prepare(lights: readonly AreaLightSource[], firstLayer: number): void;
+    /** Throw every image away, keeping the layers. For an array that has just been rebuilt. */
+    forgetEveryImage(): void;
+    /** Give the layers back. */
+    release(): void;
+    /**
+     * Whether the layers handed out still match what these lights declare.
+     *
+     * A consumer that turns a rectangle's casting on, or moves one past `MAX_AREA_LIGHTS`, has
+     * changed the layout — and a set that carried on would publish a layer index belonging to
+     * another rectangle, which is another fixture's shadow under this one. The renderer re-prepares
+     * on a false answer, which is the same thing `prepareStaticPointShadows` does about a light
+     * count that grew.
+     */
+    matchesDeclaration(lights: readonly AreaLightSource[]): boolean;
+    /**
+     * Spend a frame's faces across the casting rectangles, static maps first.
+     *
+     * **The static half is ordered by `planPointShadowBakes`, the same function the point pool
+     * uses**, so a rectangle with no image yet jumps ahead of one that has merely drifted — a map
+     * that has never baked contributes no occlusion at all, and every frame it waits is a frame with
+     * a rectangle visibly lighting through walls. Sharing the ordering rather than writing a second
+     * one is the 2026-08-13 rule: two implementations of one decision drift, and here the drift
+     * would be shadows arriving in a different order on the two backends, which no parity capture
+     * would attribute because both frames look plausible.
+     *
+     * **The live half has no staleness test, for the reason the point pool's does not**: the caster
+     * moved, which is what makes it live. It has a ceiling instead, round-robin across the
+     * rectangles, so a scene with four of them spends a bounded number of faces rather than
+     * twenty-four.
+     */
+    update(lights: readonly AreaLightSource[], dt: number, facesPerFrame: number, liveFacesPerFrame: number, rebakeDistance: number, faceCount: number, scratch: BakeScratch, staticCasters: unknown, dynamicCasters: unknown, bake: BakeAreaFaces<M>): void;
+    /**
+     * Publish what the shader should read, per area-light slot.
+     *
+     * **The far plane and the near plane come off the map rather than off the light**, which is the
+     * trap `PointShadowImage.planBake` was written for: a bake in flight owns the parameters it
+     * started with, so a rectangle whose range changed mid-bake has a map holding faces rendered
+     * under the old one. Publishing the declaration would pair new numbers with old pixels, and what
+     * that looks like is a shadow at the wrong distance rather than an error.
+     *
+     * **A map with no image publishes -1** rather than a layer at zero weight. Zero weight would
+     * make the fetch harmless and it would still *be* a fetch, of a layer holding whatever
+     * `texStorage3D` left there.
+     */
+    resolve(lights: readonly AreaLightSource[], out: ResolvedAreaShadows): void;
+}