@driftengine/core 3.61.0

package/dist/render/instances.d.ts

@@ -0,0 +1,69 @@
+/**
+ * One base mesh's per-instance placement and colour.
+ *
+ * **Many copies of one mesh are one draw and one material.** A street of thirty cars of five
+ * models is five draws rather than thirty, and — the half that is easy to miss — five *material*
+ * changes rather than thirty, which on the WebGPU backend is the scarcer of the two.
+ *
+ * Distinct from `InstanceData`, which `createScatter` takes, and deliberately not merged with it:
+ * a scatter instance carries a uniform scale, a yaw and a wind response, because it describes a
+ * plant. This one carries a full transform, because a vehicle pitches and rolls on its suspension
+ * and a yaw cannot say so.
+ *
+ * **What it gives up** is a matrix per instance where a scatter spends five floats: 76 bytes
+ * against 44, and no wind. **What would make it wrong** is a caller wanting per-instance
+ * anything else — an opacity, a morph weight — which wants another attribute, and the sixteen
+ * WebGL2 guarantees are already spent.
+ */
+export interface MeshInstances {
+    /**
+     * Sixteen floats each, column-major: one model matrix per instance.
+     *
+     * The same layout `drawMesh` takes, so a caller that already builds a matrix per object passes
+     * what it has rather than decomposing it.
+     */
+    readonly models: Float32Array;
+    /**
+     * Three floats each, multiplied into the base mesh's colour exactly as `drawMesh`'s tint is.
+     *
+     * White is the identity. A batch whose instances share a colour still spends three floats each
+     * — the alternative is a second batch per colour, which is the thing this exists to avoid.
+     */
+    readonly tints: Float32Array;
+    /** How many instances the arrays hold. Fixed at creation; the buffers are sized from it. */
+    readonly capacity: number;
+    /** How many are live. The rest of the buffer is neither uploaded nor drawn. */
+    count: number;
+}
+/**
+ * Allocate both arrays at `capacity`, empty.
+ *
+ * Allocated once and rewritten in place, never per frame — the arrays are the caller's to fill
+ * and the count is the caller's to set, which is what keeps a frame that redraws a batch
+ * allocation-free.
+ */
+export declare function createMeshInstances(capacity: number): MeshInstances;
+/**
+ * Floats one instance occupies in the interleaved vertex buffer: sixteen of matrix, three of
+ * tint, and one of padding.
+ *
+ * **Padded to twenty so the stride is 80 bytes rather than 76.** A vertex buffer's stride must be
+ * a multiple of four on both backends, which 76 already is — the padding is for the *attribute*
+ * offsets: the tint sits at byte 64 and a three-float attribute ending at 76 leaves the next
+ * instance's first column starting there, which is legal but puts every second instance on an
+ * offset no driver aligns well. One wasted float an instance is 4 bytes against 76.
+ */
+export declare const INSTANCE_FLOATS = 20;
+/** Bytes one instance occupies. See `INSTANCE_FLOATS`. */
+export declare const INSTANCE_STRIDE: number;
+/**
+ * Interleave `count` instances into `out`, matrix then tint, at `INSTANCE_FLOATS` apart.
+ *
+ * **Interleaved rather than two buffers** so a batch's upload is one `writeBuffer` and an
+ * instance's colour sits beside the matrix that places it. Shared by both backends, because
+ * which floats go where is a decision and not a binding — the rule this repository draws around
+ * `resolveAtmosphere` and `resolvePointLights`.
+ *
+ * Writes nothing beyond `count`, and allocates nothing: `out` is the caller's staging array.
+ */
+export declare function packInstances(instances: MeshInstances, out: Float32Array): void;

package/dist/render/instances.js

@@ -0,0 +1,52 @@
+/**
+ * Allocate both arrays at `capacity`, empty.
+ *
+ * Allocated once and rewritten in place, never per frame — the arrays are the caller's to fill
+ * and the count is the caller's to set, which is what keeps a frame that redraws a batch
+ * allocation-free.
+ */
+export function createMeshInstances(capacity) {
+    return {
+        models: new Float32Array(capacity * 16),
+        tints: new Float32Array(capacity * 3),
+        capacity,
+        count: 0,
+    };
+}
+/**
+ * Floats one instance occupies in the interleaved vertex buffer: sixteen of matrix, three of
+ * tint, and one of padding.
+ *
+ * **Padded to twenty so the stride is 80 bytes rather than 76.** A vertex buffer's stride must be
+ * a multiple of four on both backends, which 76 already is — the padding is for the *attribute*
+ * offsets: the tint sits at byte 64 and a three-float attribute ending at 76 leaves the next
+ * instance's first column starting there, which is legal but puts every second instance on an
+ * offset no driver aligns well. One wasted float an instance is 4 bytes against 76.
+ */
+export const INSTANCE_FLOATS = 20;
+/** Bytes one instance occupies. See `INSTANCE_FLOATS`. */
+export const INSTANCE_STRIDE = INSTANCE_FLOATS * 4;
+/**
+ * Interleave `count` instances into `out`, matrix then tint, at `INSTANCE_FLOATS` apart.
+ *
+ * **Interleaved rather than two buffers** so a batch's upload is one `writeBuffer` and an
+ * instance's colour sits beside the matrix that places it. Shared by both backends, because
+ * which floats go where is a decision and not a binding — the rule this repository draws around
+ * `resolveAtmosphere` and `resolvePointLights`.
+ *
+ * Writes nothing beyond `count`, and allocates nothing: `out` is the caller's staging array.
+ */
+export function packInstances(instances, out) {
+    const { models, tints } = instances;
+    const count = Math.min(instances.count, instances.capacity);
+    for (let i = 0; i < count; i += 1) {
+        const at = i * INSTANCE_FLOATS;
+        const m = i * 16;
+        for (let c = 0; c < 16; c += 1)
+            out[at + c] = models[m + c];
+        const t = i * 3;
+        out[at + 16] = tints[t];
+        out[at + 17] = tints[t + 1];
+        out[at + 18] = tints[t + 2];
+    }
+}

package/dist/render/lightBudget.d.ts

@@ -0,0 +1,397 @@
+/** Fixed point-light budget shared by CPU selection and the flat shader. */
+import type { AreaLightBuffer } from './areaLights.ts';
+import type { ResolvedAreaShadows } from './areaShadowSet.ts';
+/**
+ * How many point lights the shading pass shades against at once.
+ *
+ * It was eight, and eight is what an ordinary lamp-lit courtyard broke over: six lamps
+ * and a brazier inside 8.7 m take seven of them, so a gate's two lights —
+ * equidistant by construction, both 12.52 m out — contended for the one remaining
+ * slot and only ever one of them was rendered. More slots do not make the budget
+ * unbounded, and they are not what fixes contention; `CONTENTION_BAND_M` in
+ * `pointLightSelection.ts` is, by making the trade continuous. They buy the room
+ * that stops a scene this ordinary from having to make the trade at all.
+ *
+ * **It was ten, and ten was a texture-unit limit that no longer exists.** The comment
+ * here used to say that raising it "costs a texture unit and a pool slot each" and that
+ * eleven "would spend the last guaranteed unit, so this is the end of the road". That was
+ * true while each light's shadow was its own `samplerCube`. Every point shadow is now one
+ * layer of one `TEXTURE_2D_ARRAY` — see `pointShadowArray.ts` — so a light costs a layer
+ * and a pool slot, and no bindings at all.
+ *
+ * **Sixteen because that is what costs nothing.** A cube at face 512 was 6.29 MB and the
+ * pool plus the two live maps was sixteen of them, 100.7 MB. An octahedral layer at 1024 is
+ * 4.19 MB, so sixteen lights is a pool of twenty plus two live, twenty-two layers, 92.3 MB —
+ * less than the storage it replaces, with six more shadowed lights. **Eighteen is where the
+ * memory exactly equals what the cubes cost**, which is the number to reach for if a scene
+ * ever wants more, and the arithmetic is written down here so nobody has to re-derive it.
+ *
+ * What limits it now is the shader rather than the bindings: every one of these is a slot in
+ * five uniform arrays and an iteration of the light loop in the widest permutation of the
+ * largest shader in the engine.
+ */
+export declare const MAX_POINT_LIGHTS = 16;
+/** Two live maps make changing the caster's owning light a crossfade, not a pop. */
+export declare const LIVE_POINT_SHADOW_MAPS = 2;
+/**
+ * Texture units the directional cascade binds: static, its depth peel, and dynamic.
+ *
+ * Named because the shading pass's total unit count has to be compared against what a
+ * device offers, and a budget assembled from three literals scattered across two files
+ * is a budget nobody can check. See the guard in `Renderer`'s constructor.
+ */
+export declare const DIRECTIONAL_SHADOW_UNITS = 3;
+/**
+ * Texture units every point light's shadow binds: one, for all of them.
+ *
+ * **It was twelve** — ten pooled cubemaps and two live transition maps, each its own
+ * `samplerCube`, because GLSL ES cannot index a sampler array with a non-constant expression.
+ * One `TEXTURE_2D_ARRAY` of octahedral maps makes the choice a layer index instead, so the
+ * count stops depending on `MAX_POINT_LIGHTS` at all.
+ */
+export declare const POINT_SHADOW_UNITS = 1;
+/**
+ * Where surface colour binds, directly above the shadow units.
+ *
+ * Units 0–2 are the sun's static, peeled and mover depth layers; unit 3 is the point-shadow
+ * array, every light in one binding. This is the fifth, the normal map is the sixth, and **ten of
+ * WebGL2's guaranteed sixteen are free** — where the lit pass used to fill all sixteen exactly.
+ *
+ * It lives here rather than in the renderer because this is where the unit accounting is
+ * written down. Raising `MAX_POINT_LIGHTS` no longer moves it: lights cost layers now, not
+ * units, which is the whole of what the octahedral change bought.
+ */
+export declare const SURFACE_TEXTURE_UNIT: number;
+/**
+ * Where a normal map binds, directly above surface colour.
+ *
+ * **The first of the eleven units Phase 1.4 freed to be spent**, and it is worth saying what it
+ * cost to have one at all. `uTextureRelief`'s comment records the constraint in as many words: a
+ * second image sampler "is not the free addition it would be in a smaller shader", because the
+ * widest permutation already declared one more sampler than this project's adapter offered.
+ * Twelve point-shadow cubemaps became one array binding, and this is what that was for.
+ *
+ * The ORM map is the next one, and takes the unit above this.
+ */
+export declare const NORMAL_TEXTURE_UNIT: number;
+/**
+ * Occlusion, roughness and metallic in one image, on the unit above the normal map.
+ *
+ * Derived rather than written down, for the reason `SURFACE_TEXTURE_UNIT` is: a gap wastes a unit
+ * on a device that has none to waste, and an overlap binds two textures to one unit, which is
+ * undefined at best and reads as a surface losing one of its maps depending on the driver.
+ *
+ * **One unit for three channels rather than three units for three maps.** glTF packs them this way
+ * and so does every authoring tool that emits them; a file that separates its occlusion into its
+ * own image loses it, with the reason stated in the importer rather than a second sampler spent.
+ *
+ * The emissive map is the next one, and takes the unit above this.
+ */
+export declare const ORM_TEXTURE_UNIT: number;
+/**
+ * Where a consumer's emissive map binds.
+ *
+ * **The unit `textureUnitBudget.test.ts` has named for it since the sampler unlock**, which is the
+ * point of naming units rather than counting them: the change that spends one has to read what it
+ * is spending, and this one was written down before it was taken.
+ *
+ * Directly above the ORM map so the four material maps are contiguous — surface, normal, ORM,
+ * emissive. They are the set a device's guaranteed sixteen has to hold together, and anything else
+ * sitting between two of them makes that budget harder to read than it is.
+ */
+export declare const EMISSIVE_TEXTURE_UNIT: number;
+/**
+ * Where a baked reflection probe binds, when there is a unit spare for one.
+ *
+ * **It used to be one past the guarantee, and it is not any more.** WebGL2 promises sixteen
+ * units; the lit pass used to fill 0 through 15, so the probe sat at the seventeenth and every
+ * Apple GPU — all of which report exactly sixteen — had no unit for it and stood down. The
+ * point-shadow cubes became one array binding, so this is the eighth of sixteen and the probe
+ * fits everywhere.
+ *
+ * The rule it carried is kept anyway rather than deleted, because the reasoning is still the
+ * right one if the budget ever fills again: the probe is the thing given up, not the shadows.
+ * Dropping shadows to make room would trade a feature every scene uses for one a single
+ * material asks for, and a surface that cannot mirror the room still reflects the
+ * sky-and-ground approximation it always did.
+ */
+export declare const ENVIRONMENT_TEXTURE_UNIT: number;
+/**
+ * Where the froxel table binds.
+ *
+ * **Spent unconditionally, and that is what a runtime branch costs.** The clustered arm is
+ * compiled into every profile rather than permuted in, because a fifth permutation flag doubled
+ * the generated WGSL and cost 49% of the bundle on every consumer — the measurement is at the
+ * declaration in `shaders/flat/preamble.ts`. A declared sampler needs a valid texture bound to it
+ * whether or not the branch reads it, so this unit is taken even with `clusteredLights` off, and a
+ * one-texel placeholder stands in it.
+ *
+ * The eighth of sixteen. The sampler unlock left nine free and this is the first of them.
+ */
+export declare const CLUSTER_TABLE_TEXTURE_UNIT: number;
+/**
+ * Where the photometric atlas binds: one row per IES profile, any number of them.
+ *
+ * **One unit for every profile a world holds, which is the whole reason it is an atlas.** A
+ * fixture's distribution is a curve rather than an image, so a row of 128 floats holds one and a
+ * texture holds as many as a consumer loads. Per-profile textures would have spent the remaining
+ * units on the third fixture.
+ *
+ * **Spent unconditionally, for the same reason the froxel table is**, and the argument is at that
+ * declaration: the lookup is a branch on a value rather than a permutation, so the sampler is
+ * declared in every profile and a declared sampler needs a complete texture bound whether or not
+ * the branch reads it. With no profile loaded that texture is a single row of ones, which is the
+ * multiplicative identity — a row of zeros would switch off every light that reached it.
+ *
+ * The tenth of sixteen. `CAPABILITIES.md` §3 keeps the running count.
+ */
+export declare const IES_ATLAS_TEXTURE_UNIT: number;
+/**
+ * The joint palette, read by the **vertex** stage.
+ *
+ * **It comes out of the same sixteen as everything above it, and that is the correction.** The
+ * palette was first given unit 0 on the reasoning that `MAX_VERTEX_TEXTURE_IMAGE_UNITS` is a
+ * separate guarantee of sixteen from `MAX_TEXTURE_IMAGE_UNITS`. Those two do bound the stages
+ * separately — but they bound how many units each stage may *reference*, not how the units are
+ * numbered: `activeTexture` selects from one shared pool, so unit 0 is the directional shadow map
+ * whoever binds it. The result is `GL_INVALID_OPERATION: two textures of different types use the
+ * same sampler location`, on a frame that otherwise draws.
+ *
+ * Found on hardware rather than in review, which is the whole reason a capture is part of the
+ * work. WebGPU never had it: its bindings are per bind group and carry no shared namespace.
+ *
+ * What it costs is one of the five units left after the IES atlas. What would make it wrong is
+ * the lit pass growing past sixteen, which `textureUnitBudget.test.ts` asserts against.
+ */
+export declare const SKIN_PALETTE_TEXTURE_UNIT: number;
+/**
+ * A mesh's morph deltas, also read by the vertex stage, and also out of this same sixteen.
+ *
+ * The second vertex-stage sampler this engine has, and it takes a unit for the reason the palette
+ * does: `activeTexture` selects from one pool whichever stage the sampler is declared in. Thirteen
+ * of sixteen spoken for, three free.
+ */
+export declare const MORPH_DELTA_TEXTURE_UNIT: number;
+/**
+ * Where the spot-light cookie atlas binds: one row of square tiles, one tile a cookie.
+ *
+ * **The fourteenth of sixteen, and two are left.** `CAPABILITIES.md` §3 keeps the running count —
+ * and had been three units stale for as long as the IES atlas, the skin palette and the morph
+ * deltas have existed, which is why the number is derived in `textureUnitBudget.test.ts` and only
+ * quoted in prose.
+ *
+ * **Spent unconditionally, for the reason the froxel table and the IES atlas are**: a declared
+ * sampler needs a complete texture bound whether or not the branch reads it, so a one-texel white
+ * placeholder stands in it when no consumer has loaded a cookie. White rather than black, because
+ * it multiplies a light's colour and a black stand-in would switch off every light that reached
+ * it — the identity `packIesAtlas` chooses for the same reason.
+ */
+export declare const COOKIE_ATLAS_TEXTURE_UNIT: number;
+/**
+ * The colour the frame had already drawn, for a refracting surface to sample.
+ *
+ * **The second-to-last unit WebGL2 guarantees, and derived rather than a literal** for the reason
+ * every unit above it is: a gap wastes a unit on a device that has none to waste, and an overlap
+ * binds two textures of different types to one unit, which is undefined and reads as a scene
+ * losing one of them depending on the driver.
+ *
+ * **One unit is left after this.** What that costs is that the next sampler added has to find room
+ * rather than take it — by folding into an existing binding the way the twelve point-shadow
+ * cubemaps became one array, which is what freed the units this one is spending.
+ * `textureUnitBudget.test.ts` carries the phone that budget was written for.
+ */
+export declare const REFRACT_SCENE_TEXTURE_UNIT: number;
+/**
+ * A cookie's tile, in texels a side.
+ *
+ * **128, which is what a gobo is.** A cookie is a soft mask — a window frame, a leaf canopy, a
+ * grille — and its edges are blurred by the source's own size before anything sees them, so the
+ * resolution that matters is the shape rather than the detail. Sixteen tiles at 128 is a
+ * 2048x128 atlas at 1 MB, against 16 MB for the same count at 512.
+ *
+ * Interpolated into the shader rather than repeated there, so the half-texel inset that stops one
+ * tile bleeding into the next is derived from one definition.
+ */
+export declare const COOKIE_TILE = 128;
+/**
+ * Where the SDF text atlas binds.
+ *
+ * **Not a new number past `SURFACE_TEXTURE_UNIT`.** The next untaken one by that reading is
+ * `ENVIRONMENT_TEXTURE_UNIT`, the seventeenth unit — and on the Apple GPUs this file already
+ * accounts for, which report exactly the guaranteed sixteen, a seventeenth unit does not
+ * exist. The reflection probe can decline gracefully when that happens and still leave a
+ * correct picture behind. SDF text has no such fallback: it is opt-in, but a consumer who
+ * opts in wants their labels on every device that promises WebGL2, not on every device except
+ * one vendor's phones.
+ *
+ * So the atlas reuses `SURFACE_TEXTURE_UNIT` itself, which needs no capability check because
+ * it is already the last unit WebGL2 guarantees. That is safe rather than a compromise: text
+ * draws through its own program, in its own pass, with exactly one sampler, so it never
+ * needs to coexist with whatever the shading pass bound a moment earlier — the two are never
+ * bound at once. Named separately anyway, so the SDF renderer's call site reads as "the
+ * atlas's unit" rather than as a reference to a surface colour it has nothing to do with.
+ */
+export declare const SDF_TEXT_TEXTURE_UNIT: number;
+/**
+ * Cubemaps kept for world lights, independent of how many lights a world has.
+ *
+ * This used to be one map per light, forever, and it is the single most expensive
+ * mistake the renderer has made. A `DEPTH_COMPONENT24` cube at face size 512 is
+ * six faces at four bytes a texel, about 6.3 MB; a measured world carries 50
+ * lights, so the renderer allocated roughly 327 MB of shadow storage — of which
+ * `MAX_POINT_LIGHTS` worth, eight maps, could be sampled in any given frame.
+ * Forty-two of them, some 265 MB, were unreadable by construction.
+ *
+ * Nothing about that is visible on a GPU with its own memory. On an integrated
+ * part it is fatal: system RAM *is* the VRAM, over a bus shared with the CPU, so
+ * past the budget the driver evicts and re-uploads every frame and the frame rate
+ * falls off a cliff rather than degrading. It reproduced as a game that ran at
+ * 3 fps maximised and *perfectly* in a small window, because shrinking the window
+ * shrank the other targets back under the budget.
+ *
+ * So the pool is sized to what the shader can actually read, plus headroom. The
+ * headroom is not optional: selection reorders as the camera moves, and a pool of
+ * exactly eight would evict a map that is about to be wanted again and re-bake it
+ * on the next frame, forever. Four spare slots absorb that churn.
+ *
+ * The maps are no longer permanent, which is the cost of this: a light entering
+ * the sampled set for the first time in a while pays six face passes once. They
+ * bake from static geometry, so the result is identical whenever it is taken.
+ */
+export declare const POINT_SHADOW_POOL: number;
+/**
+ * The active point lights a pass shades against.
+ *
+ * Named separately from `Environment` so a pass can ask for the lights without asking
+ * for the sky, the fog, the shadow maps and the highlight box as well — and named with
+ * `Environment`'s own field names so an environment satisfies it structurally, which
+ * keeps the call free of a per-frame adapter object in a per-frame path.
+ */
+export interface PointLightSet {
+    readonly lightCount: number;
+    readonly lightPositions: Float32Array;
+    readonly lightColors: Float32Array;
+    readonly lightRadii: Float32Array;
+    readonly lightWeights: Float32Array;
+    /**
+     * Each light's emitter radius in metres, optional per consumer.
+     *
+     * Absent means every source is a mathematical point, which is what this engine assumed until
+     * a highlight smaller than a fragment turned out to be the cause of speckle on glossy paint.
+     */
+    readonly lightSourceRadii?: Float32Array;
+    /**
+     * Three per light: where a spot points, normalised. Absent means every light is a point.
+     *
+     * Optional so that a consumer which has never heard of spot lights passes exactly what it passed
+     * before and gets exactly what it got before.
+     */
+    readonly lightDirections?: Float32Array;
+    /** Two per light: the cosine of the inner cone angle, then of the outer. */
+    readonly lightConeCos?: Float32Array;
+    /** One per light: a row of the photometric atlas, or negative for none. */
+    readonly lightIesProfiles?: Float32Array;
+    /**
+     * Three per light: where a photometric profile's azimuth zero points, in world space.
+     *
+     * **Only an asymmetric fixture reads it** — a street light, a wall washer — and every axially
+     * symmetric profile ignores it entirely, which is nearly all of them. It need not be
+     * perpendicular to the light's direction: the shader orthogonalises it against the aim, so a
+     * caller can hand the fixture's own forward and let the aim decide the rest. A zero vector, or
+     * one parallel to the aim, leaves the profile on its first plane.
+     *
+     * **It cannot be derived from the direction**, which is why it is here at all: there is no
+     * continuous field of unit vectors tangent to a sphere, so any reference built from the aim
+     * alone flips somewhere — and the obvious constructions put that flip exactly where these
+     * fixtures point, `cross(worldUp, dir)` being singular for a light aimed straight down.
+     */
+    readonly lightIesAxes?: Float32Array;
+    /**
+     * One per light: a tile of the cookie atlas, or negative for none.
+     *
+     * A cookie is a mask the fixture projects — a window frame, a grille, foliage — and it is
+     * oriented by the same `lightIesAxes` a photometric profile is, because both answer the same
+     * question about a fixture: which way is up. It fills the light's **outer cone**, so a cookie
+     * drawn for one spot works in another with a different angle.
+     */
+    readonly lightCookies?: Float32Array;
+}
+/**
+ * A cone that admits every direction, for every light.
+ *
+ * Inner −1 and outer −2 in each pair, which is the collapse `POINT_LIGHT_COS_OUTER` describes: the
+ * dot product never falls below −1, so the term is exactly 1 and a scene with no spot light shades
+ * exactly as it did before spot lights existed.
+ */
+/**
+ * A fresh cone array where every light admits every direction.
+ *
+ * Exported because `createEnvironment` needs one it owns: the module-scope `OPEN_CONES` is shared
+ * by every fallback in this file, and handing it to an environment would let one scene's edit
+ * reach another's — the aliasing `createEnvironment` already warns about for `lightPositions`.
+ */
+export declare function openCones(lights?: number): Float32Array;
+/**
+ * Bind a light set to whichever program declares the shared slot names.
+ *
+ * Three passes now shade against these — surfaces, smoke and water — and each had its
+ * own copy of the same four uploads. A fourth would have made it four, and one of the
+ * four would eventually have been the one to forget `uLightWeight` and have lights pop
+ * in and out instead of fading.
+ *
+ * `falloff` travels with them because the shape a lamp fades with is a property of the
+ * *world*, not of the material it lands on: a lamp that behaves one way on stone and
+ * another on the water beside it is the same light in two places.
+ */
+export declare function bindPointLights(gl: WebGL2RenderingContext, uniforms: Record<string, WebGLUniformLocation>, lights: PointLightSet | null, falloff: 'smooth' | 'inverseSquare'): void;
+/**
+ * Bind the rectangular emitters, on the same reasoning `bindPointLights` gives.
+ *
+ * Separate from the point lights because they are a separate loop with separate arrays, and in the
+ * same file because a fourth pass forgetting one of these is the failure that helper exists to
+ * prevent — and there is no reason a second one would be immune to it.
+ */
+export declare function bindAreaLights(gl: WebGL2RenderingContext, uniforms: Record<string, WebGLUniformLocation>, lights: AreaLightBuffer | null): void;
+/**
+ * Put a rectangle's occlusion on the program: eight arrays, no texture of its own.
+ *
+ * **No sampler here, and that is the whole reason this is a separate function rather than part of
+ * `bindPointShadows`.** An area light's layers live in the array that call already bound, so the
+ * unit and the sampler name are its business and these are only indices into it — which is also
+ * what makes an area shadow ride `RenderQuality.pointShadows`: with the flag off the program
+ * declares no array at all, none of these eight names exists, and every lookup below answers
+ * `null`.
+ *
+ * Addressed as `name[0]`, because GLSL ES exposes an array uniform under the name of its first
+ * element and `name[1]` returns nothing from the cached table — the mistake that left point-light
+ * slots 1 to 7 at zero and made their shadows vanish.
+ */
+export declare function bindAreaShadows(gl: WebGL2RenderingContext, uniforms: Record<string, WebGLUniformLocation>, shadows: ResolvedAreaShadows): void;
+/** The five arrays and two scalars a shader needs, after every fallback has been applied. */
+export interface ResolvedPointLights {
+    count: number;
+    /** 1 for `inverseSquare`, 0 for `smooth`. An `int` uniform on both backends. */
+    falloff: number;
+    positions: Float32Array;
+    colors: Float32Array;
+    radii: Float32Array;
+    sourceRadii: Float32Array;
+    weights: Float32Array;
+    directions: Float32Array;
+    coneCos: Float32Array;
+    iesProfiles: Float32Array;
+    iesAxes: Float32Array;
+    cookies: Float32Array;
+}
+/**
+ * Choose which array each slot actually gets, with every fallback applied.
+ *
+ * **Separated from the upload so a second backend reaches the same five arrays.** The whole
+ * argument for `bindPointLights` is that a fourth pass would eventually be the one to forget
+ * `uLightWeight`; a second *backend* that cannot call it, having no `WebGL2RenderingContext`,
+ * is that same fourth pass wearing a different hat. WebGPU scatters these into a uniform block
+ * at the generated stride, WebGL2 hands them to `uniform3fv`.
+ *
+ * Fills a target the caller owns, because both callers are per-frame paths.
+ */
+export declare function resolvePointLights(lights: PointLightSet | null, falloff: 'smooth' | 'inverseSquare', out: ResolvedPointLights): ResolvedPointLights;