@driftengine/core 4.4.2 → 4.6.0

package/dist/render/gpudriven/sunGlass.js

@@ -0,0 +1,89 @@
+/**
+ * The second pipeline's sunlight through glass, as a reference: `glassTintAt` over the glass depth
+ * and tint maps the GPU-driven pass draws from the sun, for `shade.wgsl.ts`'s lookup to be read
+ * against.
+ *
+ * **The forward path's rule, not a second one** (`glassShadow.ts`, and `sunGlassLookup` in
+ * `flat/directionalShadow.ts`): the outline from taps at the base filter radius that count a pane
+ * only where the receiver is behind it, and the colour from spread taps read coarse, unmixed from
+ * the ground around the pane by its clarity and weighed by its share. Frost widens only the
+ * colour's taps, so the light a frosted pane passes is the light a clear one does.
+ *
+ * **What differs is where two numbers come from.** A compute invocation has no derivatives, so the
+ * map's scale in metres is the caller's (`uvPerMetre`, which an orthographic light matrix states
+ * outright); and a coarse level here is a box average over the spread's footprint, which is what a
+ * mip level approximates on the device. `scripts/gpu-parity.mjs` holds the device's per-tap
+ * arithmetic to `glassShadow.ts`; the sampling is what the glass page measures.
+ */
+import { frostRadius, spreadTint, unmixTint } from '../glassShadow.js';
+import { SHADOW_DEPTH_BIAS, SHADOW_PCF_OFFSETS, SHADOW_TEXEL_SCALE } from './shadow.js';
+const centre = { r: 1, g: 1, b: 1, clarity: 1 };
+const coarse = { r: 1, g: 1, b: 1, clarity: 1 };
+const pane = { r: 1, g: 1, b: 1, clarity: 1 };
+const found = { r: 0, g: 0, b: 0, clarity: 0 };
+function index(maps, u, v) {
+    const x = Math.min(maps.size - 1, Math.max(0, Math.floor(u * maps.size)));
+    const y = Math.min(maps.size - 1, Math.max(0, Math.floor(v * maps.size)));
+    return y * maps.size + x;
+}
+/** The average of every texel within `radius` of (u, v): a mip level's footprint, in the large. */
+function coarseAt(maps, u, v, radius, out) {
+    const reach = radius * maps.size;
+    const x0 = Math.max(0, Math.floor(u * maps.size - reach));
+    const x1 = Math.min(maps.size - 1, Math.floor(u * maps.size + reach));
+    const y0 = Math.max(0, Math.floor(v * maps.size - reach));
+    const y1 = Math.min(maps.size - 1, Math.floor(v * maps.size + reach));
+    out.r = 0;
+    out.g = 0;
+    out.b = 0;
+    out.clarity = 0;
+    let n = 0;
+    for (let y = y0; y <= y1; y++) {
+        for (let x = x0; x <= x1; x++) {
+            const at = (y * maps.size + x) * 4;
+            out.r += maps.tint[at];
+            out.g += maps.tint[at + 1];
+            out.b += maps.tint[at + 2];
+            out.clarity += maps.tint[at + 3];
+            n++;
+        }
+    }
+    out.r /= n;
+    out.g /= n;
+    out.b /= n;
+    out.clarity /= n;
+}
+/** What the sun keeps through glass at a receiver at map position (u, v) and light depth `depth`. */
+export function glassTintAt(u, v, depth, maps, settings, out) {
+    out.r = 1;
+    out.g = 1;
+    out.b = 1;
+    out.clarity = 1;
+    if (u < 0 || u > 1 || v < 0 || v > 1)
+        return out;
+    const texel = SHADOW_TEXEL_SCALE / maps.size;
+    const bias = SHADOW_DEPTH_BIAS / settings.depthSpan;
+    const taps = Math.min(settings.taps, SHADOW_PCF_OFFSETS.length);
+    const at = index(maps, u, v);
+    centre.clarity = maps.tint[at * 4 + 3];
+    const behind = Math.max(depth - maps.glassDepth[at], 0) * settings.depthSpan;
+    const radius = frostRadius(centre.clarity, behind * settings.uvPerMetre, texel);
+    let cover = 0;
+    found.r = 0;
+    found.g = 0;
+    found.b = 0;
+    let shares = 0;
+    for (let i = 0; i < taps; i++) {
+        const offset = SHADOW_PCF_OFFSETS[i];
+        const nearest = maps.glassDepth[index(maps, u + offset[0] * texel, v + offset[1] * texel)];
+        if (depth > nearest + bias)
+            cover++;
+        coarseAt(maps, u + offset[0] * radius, v + offset[1] * radius, radius, coarse);
+        const share = unmixTint(coarse, centre.clarity, pane);
+        found.r += pane.r * share;
+        found.g += pane.g * share;
+        found.b += pane.b * share;
+        shares += share;
+    }
+    return spreadTint(cover / Math.max(taps, 1), found, shares, out);
+}

package/dist/render/instanceCull.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Which instances of a batch can be seen: the decision both backends make, and the reference the
+ * WebGPU compute cull is held to.
+ *
+ * **An instance's bounds are the mesh's, placed by its matrix** — the mesh's bounding sphere with its
+ * centre through the model matrix and its radius scaled by the largest axis, exactly as
+ * `boundsVisible` treats one mesh — so a batch needs no bounds of its own and a caller supplies none.
+ * The test is `sphereInFrustum`'s: kept unless wholly beyond one plane.
+ *
+ * WebGL2 runs `cullInstances` on the CPU; WebGPU runs `CULL_INSTANCES_WGSL`, the same arithmetic, on
+ * the device. Both keep what this keeps: `gpu-parity.mjs` compares them on a device. What this gives
+ * up is shape: a long thin mesh is culled by the sphere around it, which keeps it in more views than
+ * its box would. What would make that wrong is a batch of long thin things seen end on, where a box
+ * test pays; nothing in the engine draws those instanced today.
+ *
+ * Per frame and allocation-free: everything writes into arrays the caller owns.
+ */
+import type { MeshInstances } from './instances.ts';
+import type { Bounds } from '../math/bounds.ts';
+import type { FrustumPlanes } from '../math/frustum.ts';
+/**
+ * Indices a culling batch must draw, all its instances together, before culling it instance by
+ * instance pays; below it the batch is drawn whole once its box is seen (`batchBoxVisible`).
+ *
+ * **What a per-instance cull costs is fixed a batch, and what it saves grows with the batch.** On
+ * WebGPU it is a dispatch and an indirect draw, and Chrome validates every indirect draw in its GPU
+ * process — measured at 8 µs apiece in a city frame whose six hundred small prop batches took one
+ * each, 52 fps against 70 with those draws gone. On WebGL2 it is a loop over the instances and an
+ * upload of the survivors. A few thousand indices cost a device less than either.
+ *
+ * What it gives up is the instances of a small batch that stand out of view once its box is in it,
+ * which the device transforms and clips for nothing. What would make it wrong is a device whose
+ * vertex stage limits the frame while the CPU idles — where this wants to come down.
+ */
+export declare const INSTANCE_CULL_MIN_INDICES: number;
+/**
+ * Whether a culling batch of `count` instances of a mesh of `indexCount` indices is culled instance
+ * by instance, or drawn whole once its box is seen. See `INSTANCE_CULL_MIN_INDICES`.
+ */
+export declare function cullsInstances(count: number, indexCount: number): boolean;
+/**
+ * Keep the instances of `data` whose spheres meet `frustum`, compacted in order into `out`, and
+ * return how many. `out` must hold as many as `data` does; its count is set.
+ */
+export declare function cullInstances(data: MeshInstances, local: Bounds, frustum: FrustumPlanes, out: MeshInstances): number;
+/**
+ * The world box around every instance's sphere, for testing a whole batch at once: (minX, minY,
+ * minZ, maxX, maxY, maxZ) into `out`. A batch holding nothing writes a min above its max.
+ *
+ * **A box, not a sphere, and the difference is the whole point for a flat batch.** A region of props
+ * a hundred metres square has a sphere seventy metres deep underground, where nothing occludes it,
+ * so a sphere test never finds a region hidden. The box stays as flat as the props are.
+ */
+export declare function instancesBox(data: MeshInstances, local: Bounds, out: Float32Array): void;
+/** What the batch test asks of an occlusion buffer. `OcclusionBuffer` and both renderers answer it. */
+export interface BoxOccluder {
+    occludedBox(min: ArrayLike<number>, max: ArrayLike<number>): boolean;
+}
+/**
+ * Whether a batch's box (`instancesBox`) can be seen at all: inside the frustum, and not behind the
+ * declared occluders. One test for a whole region's props, run before any instance is looked at.
+ */
+export declare function batchBoxVisible(box: Float32Array, frustum: FrustumPlanes, occluder: BoxOccluder | null): boolean;

package/dist/render/instanceCull.js

@@ -0,0 +1,160 @@
+import { boxInFrustum } from '../math/frustum.js';
+/** How many planes a frustum holds, four floats each. */
+const PLANES = 6;
+/**
+ * Indices a culling batch must draw, all its instances together, before culling it instance by
+ * instance pays; below it the batch is drawn whole once its box is seen (`batchBoxVisible`).
+ *
+ * **What a per-instance cull costs is fixed a batch, and what it saves grows with the batch.** On
+ * WebGPU it is a dispatch and an indirect draw, and Chrome validates every indirect draw in its GPU
+ * process — measured at 8 µs apiece in a city frame whose six hundred small prop batches took one
+ * each, 52 fps against 70 with those draws gone. On WebGL2 it is a loop over the instances and an
+ * upload of the survivors. A few thousand indices cost a device less than either.
+ *
+ * What it gives up is the instances of a small batch that stand out of view once its box is in it,
+ * which the device transforms and clips for nothing. What would make it wrong is a device whose
+ * vertex stage limits the frame while the CPU idles — where this wants to come down.
+ */
+export const INSTANCE_CULL_MIN_INDICES = 1 << 14;
+/**
+ * Whether a culling batch of `count` instances of a mesh of `indexCount` indices is culled instance
+ * by instance, or drawn whole once its box is seen. See `INSTANCE_CULL_MIN_INDICES`.
+ */
+export function cullsInstances(count, indexCount) {
+    return count * indexCount >= INSTANCE_CULL_MIN_INDICES;
+}
+/**
+ * Keep the instances of `data` whose spheres meet `frustum`, compacted in order into `out`, and
+ * return how many. `out` must hold as many as `data` does; its count is set.
+ */
+export function cullInstances(data, local, frustum, out) {
+    const count = Math.min(data.count, data.capacity, out.capacity);
+    const models = data.models;
+    const tints = data.tints;
+    let kept = 0;
+    for (let i = 0; i < count; i++) {
+        sphereOf(models, i, local, scratch);
+        if (!sphereMeets(frustum, scratch))
+            continue;
+        /* Copied float by float: a subarray would be a view allocated per instance, per frame. */
+        const from = i * 16;
+        const to = kept * 16;
+        for (let k = 0; k < 16; k++)
+            out.models[to + k] = models[from + k];
+        out.tints[kept * 3] = tints[i * 3];
+        out.tints[kept * 3 + 1] = tints[i * 3 + 1];
+        out.tints[kept * 3 + 2] = tints[i * 3 + 2];
+        kept++;
+    }
+    out.count = kept;
+    return kept;
+}
+/** `sphereInFrustum` over a packed (x, y, z, radius): kept unless wholly beyond one plane. */
+function sphereMeets(frustum, sphere) {
+    const x = sphere[0];
+    const y = sphere[1];
+    const z = sphere[2];
+    const radius = sphere[3];
+    for (let plane = 0; plane < PLANES; plane++) {
+        const at = plane * 4;
+        const distance = frustum[at] * x +
+            frustum[at + 1] * y +
+            frustum[at + 2] * z +
+            frustum[at + 3];
+        if (distance < -radius)
+            return false;
+    }
+    return true;
+}
+/**
+ * The world box around every instance's sphere, for testing a whole batch at once: (minX, minY,
+ * minZ, maxX, maxY, maxZ) into `out`. A batch holding nothing writes a min above its max.
+ *
+ * **A box, not a sphere, and the difference is the whole point for a flat batch.** A region of props
+ * a hundred metres square has a sphere seventy metres deep underground, where nothing occludes it,
+ * so a sphere test never finds a region hidden. The box stays as flat as the props are.
+ */
+export function instancesBox(data, local, out) {
+    const count = Math.min(data.count, data.capacity);
+    if (count === 0) {
+        out[0] = 1;
+        out[1] = 1;
+        out[2] = 1;
+        out[3] = -1;
+        out[4] = -1;
+        out[5] = -1;
+        return;
+    }
+    let minX = Infinity;
+    let minY = Infinity;
+    let minZ = Infinity;
+    let maxX = -Infinity;
+    let maxY = -Infinity;
+    let maxZ = -Infinity;
+    for (let i = 0; i < count; i++) {
+        sphereOf(data.models, i, local, scratch);
+        const r = scratch[3];
+        minX = Math.min(minX, scratch[0] - r);
+        minY = Math.min(minY, scratch[1] - r);
+        minZ = Math.min(minZ, scratch[2] - r);
+        maxX = Math.max(maxX, scratch[0] + r);
+        maxY = Math.max(maxY, scratch[1] + r);
+        maxZ = Math.max(maxZ, scratch[2] + r);
+    }
+    out[0] = minX;
+    out[1] = minY;
+    out[2] = minZ;
+    out[3] = maxX;
+    out[4] = maxY;
+    out[5] = maxZ;
+}
+const scratch = new Float32Array(4);
+/** Instance `i`'s world sphere into `out` as (x, y, z, radius). */
+function sphereOf(models, i, local, out) {
+    const m = i * 16;
+    const cx = local.centre[0] ?? 0;
+    const cy = local.centre[1] ?? 0;
+    const cz = local.centre[2] ?? 0;
+    const m0 = models[m];
+    const m1 = models[m + 1];
+    const m2 = models[m + 2];
+    const m4 = models[m + 4];
+    const m5 = models[m + 5];
+    const m6 = models[m + 6];
+    const m8 = models[m + 8];
+    const m9 = models[m + 9];
+    const m10 = models[m + 10];
+    out[0] = m0 * cx + m4 * cy + m8 * cz + models[m + 12];
+    out[1] = m1 * cx + m5 * cy + m9 * cz + models[m + 13];
+    out[2] = m2 * cx + m6 * cy + m10 * cz + models[m + 14];
+    out[3] =
+        local.radius *
+            Math.sqrt(Math.max(m0 * m0 + m1 * m1 + m2 * m2, m4 * m4 + m5 * m5 + m6 * m6, m8 * m8 + m9 * m9 + m10 * m10));
+}
+/**
+ * Whether a batch's box (`instancesBox`) can be seen at all: inside the frustum, and not behind the
+ * declared occluders. One test for a whole region's props, run before any instance is looked at.
+ */
+export function batchBoxVisible(box, frustum, occluder) {
+    const minX = box[0];
+    const minY = box[1];
+    const minZ = box[2];
+    const maxX = box[3];
+    const maxY = box[4];
+    const maxZ = box[5];
+    if (minX > maxX)
+        return false;
+    if (!boxInFrustum(frustum, minX, minY, minZ, maxX, maxY, maxZ))
+        return false;
+    if (occluder === null)
+        return true;
+    boxMin[0] = minX;
+    boxMin[1] = minY;
+    boxMin[2] = minZ;
+    boxMax[0] = maxX;
+    boxMax[1] = maxY;
+    boxMax[2] = maxZ;
+    return !occluder.occludedBox(boxMin, boxMax);
+}
+const boxMin = new Float32Array(3);
+const boxMax = new Float32Array(3);

package/dist/render/instances.d.ts

@@ -67,3 +67,18 @@ export declare const INSTANCE_STRIDE: number;
  * Writes nothing beyond `count`, and allocates nothing: `out` is the caller's staging array.
  */
 export declare function packInstances(instances: MeshInstances, out: Float32Array): void;
+/** How a batch made by `createInstanced` behaves. */
+export interface InstancedOptions {
+    /**
+     * Cull the camera draw: the whole batch skipped when its instances' sphere is out of view or behind
+     * the declared occluders, and otherwise each instance kept only where its sphere meets the view —
+     * on the CPU on WebGL2, as compute into an indirect draw on WebGPU — once the batch is large enough
+     * to repay that (`cullsInstances`); a smaller one is drawn whole. Shadow, mirror-free motion and
+     * blended draws still see every instance. Off by default, because a batch small enough to draw whole
+     * pays for nothing it would save.
+     *
+     * **For a batch spread over space** — a prop across a region, a crowd, traffic. A batch in one
+     * place gains only the whole-batch test, which it could as well do itself.
+     */
+    readonly cull?: boolean;
+}

package/dist/render/lightBudget.d.ts

@@ -34,13 +34,14 @@ 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.
+ * Texture units the sun's shadow binds: one, for its static, moving and peeled layers.
  *
- * 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.
+ * **It was three**, a `sampler2D` per map, until 4.5.0 folded them into one `sampler2DArray`
+ * (`shadowMap.ts`) the way the lamps' twelve cubemaps became one — which is where the two tints
+ * glass casts with found their units. Named because the shading pass's total has to be compared
+ * against what a device offers; see the guard in `Renderer`'s constructor.
  */
-export declare const DIRECTIONAL_SHADOW_UNITS = 3;
+export declare const DIRECTIONAL_SHADOW_UNITS = 1;
 /**
  * Texture units every point light's shadow binds: one, for all of them.
  *
@@ -130,22 +131,20 @@ export declare const ENVIRONMENT_TEXTURE_UNIT: number;
  */
 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.
+ * Where the fixture atlas binds: a fixture's spot cookies and its photometric profiles, one texture.
+ *
+ * **Two tables in one binding since 2026-09-30**, which is the fold `textureUnitBudget.test.ts` asks
+ * the next sampler for: the widest lit shader bound fifteen of the sixteen fragment samplers WebGL2
+ * guarantees, and the cookie atlas and the photometric atlas were two small float tables read with
+ * `textureLod`, both 128 texels across. See `fixtureAtlas.ts` for the layout and why cookies sit on
+ * top.
+ *
+ * **Spent unconditionally, for the reason the froxel table is**: both lookups are branches on values
+ * rather than permutations, so the sampler is declared in every profile and a declared sampler needs
+ * a complete texture. With nothing loaded that is a single row of ones — the multiplicative
+ * identity, since a row of zeros would switch off every light that reached it.
  */
-export declare const IES_ATLAS_TEXTURE_UNIT: number;
+export declare const FIXTURE_ATLAS_TEXTURE_UNIT: number;
 /**
  * The joint palette, read by the **vertex** stage.
  *
@@ -172,21 +171,6 @@ export declare const SKIN_PALETTE_TEXTURE_UNIT: number;
  * 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.
  *
@@ -212,6 +196,23 @@ export declare const REFRACT_SCENE_TEXTURE_UNIT: number;
  */
 export declare const DRIFT_LIGHT_INDEX_TEXTURE_UNIT: number;
 export declare const DRIFT_LIGHT_ATLAS_TEXTURE_UNIT: number;
+/**
+ * What the sun keeps through glass (`sunGlassTint.ts`), the lit program's fourteenth fragment
+ * sampler: the unit the sun's three maps gave back when they became one array.
+ */
+export declare const SUN_GLASS_TINT_TEXTURE_UNIT: number;
+/**
+ * What each lamp keeps through glass (`pointGlassTint.ts`), a fragment sampler of the lit program.
+ * A unit of the combined pool, which WebGL2 guarantees thirty-two of; what a stage may declare is
+ * sixteen, which `textureUnitBudget.test.ts` counts from the shader source.
+ */
+export declare const POINT_GLASS_TINT_TEXTURE_UNIT: number;
+/**
+ * Each surface layer's effects table (`surfaceEffects.ts`), bound beside the albedo array it
+ * describes. **Paid for by folding**: the cookie and photometric atlases became one fixture atlas
+ * to free the sampler this takes, so the lit stage still keeps one of its sixteen spare.
+ */
+export declare const SURFACE_EFFECTS_TEXTURE_UNIT: number;
 /**
  * A cookie's tile, in texels a side.
  *

package/dist/render/lightBudget.js

@@ -32,13 +32,14 @@ export const MAX_POINT_LIGHTS = 16;
 /** Two live maps make changing the caster's owning light a crossfade, not a pop. */
 export const LIVE_POINT_SHADOW_MAPS = 2;
 /**
- * Texture units the directional cascade binds: static, its depth peel, and dynamic.
+ * Texture units the sun's shadow binds: one, for its static, moving and peeled layers.
  *
- * 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.
+ * **It was three**, a `sampler2D` per map, until 4.5.0 folded them into one `sampler2DArray`
+ * (`shadowMap.ts`) the way the lamps' twelve cubemaps became one — which is where the two tints
+ * glass casts with found their units. Named because the shading pass's total has to be compared
+ * against what a device offers; see the guard in `Renderer`'s constructor.
  */
-export const DIRECTIONAL_SHADOW_UNITS = 3;
+export const DIRECTIONAL_SHADOW_UNITS = 1;
 /**
  * Texture units every point light's shadow binds: one, for all of them.
  *
@@ -128,22 +129,20 @@ export const ENVIRONMENT_TEXTURE_UNIT = EMISSIVE_TEXTURE_UNIT + 1;
  */
 export const CLUSTER_TABLE_TEXTURE_UNIT = ENVIRONMENT_TEXTURE_UNIT + 1;
 /**
- * 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.
+ * Where the fixture atlas binds: a fixture's spot cookies and its photometric profiles, one texture.
+ *
+ * **Two tables in one binding since 2026-09-30**, which is the fold `textureUnitBudget.test.ts` asks
+ * the next sampler for: the widest lit shader bound fifteen of the sixteen fragment samplers WebGL2
+ * guarantees, and the cookie atlas and the photometric atlas were two small float tables read with
+ * `textureLod`, both 128 texels across. See `fixtureAtlas.ts` for the layout and why cookies sit on
+ * top.
+ *
+ * **Spent unconditionally, for the reason the froxel table is**: both lookups are branches on values
+ * rather than permutations, so the sampler is declared in every profile and a declared sampler needs
+ * a complete texture. With nothing loaded that is a single row of ones — the multiplicative
+ * identity, since a row of zeros would switch off every light that reached it.
  */
-export const IES_ATLAS_TEXTURE_UNIT = CLUSTER_TABLE_TEXTURE_UNIT + 1;
+export const FIXTURE_ATLAS_TEXTURE_UNIT = CLUSTER_TABLE_TEXTURE_UNIT + 1;
 /**
  * The joint palette, read by the **vertex** stage.
  *
@@ -161,7 +160,7 @@ export const IES_ATLAS_TEXTURE_UNIT = CLUSTER_TABLE_TEXTURE_UNIT + 1;
  * 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 const SKIN_PALETTE_TEXTURE_UNIT = IES_ATLAS_TEXTURE_UNIT + 1;
+export const SKIN_PALETTE_TEXTURE_UNIT = FIXTURE_ATLAS_TEXTURE_UNIT + 1;
 /**
  * A mesh's morph deltas, also read by the vertex stage, and also out of this same sixteen.
  *
@@ -170,21 +169,6 @@ export const SKIN_PALETTE_TEXTURE_UNIT = IES_ATLAS_TEXTURE_UNIT + 1;
  * of sixteen spoken for, three free.
  */
 export const MORPH_DELTA_TEXTURE_UNIT = SKIN_PALETTE_TEXTURE_UNIT + 1;
-/**
- * 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 const COOKIE_ATLAS_TEXTURE_UNIT = MORPH_DELTA_TEXTURE_UNIT + 1;
 /**
  * The colour the frame had already drawn, for a refracting surface to sample.
  *
@@ -198,7 +182,7 @@ export const COOKIE_ATLAS_TEXTURE_UNIT = MORPH_DELTA_TEXTURE_UNIT + 1;
  * 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 const REFRACT_SCENE_TEXTURE_UNIT = COOKIE_ATLAS_TEXTURE_UNIT + 1;
+export const REFRACT_SCENE_TEXTURE_UNIT = MORPH_DELTA_TEXTURE_UNIT + 1;
 /**
  * DriftLight's brick index and atlas, the lit program's fourteenth and fifteenth fragment samplers.
  *
@@ -210,6 +194,23 @@ export const REFRACT_SCENE_TEXTURE_UNIT = COOKIE_ATLAS_TEXTURE_UNIT + 1;
  */
 export const DRIFT_LIGHT_INDEX_TEXTURE_UNIT = REFRACT_SCENE_TEXTURE_UNIT + 1;
 export const DRIFT_LIGHT_ATLAS_TEXTURE_UNIT = DRIFT_LIGHT_INDEX_TEXTURE_UNIT + 1;
+/**
+ * What the sun keeps through glass (`sunGlassTint.ts`), the lit program's fourteenth fragment
+ * sampler: the unit the sun's three maps gave back when they became one array.
+ */
+export const SUN_GLASS_TINT_TEXTURE_UNIT = DRIFT_LIGHT_ATLAS_TEXTURE_UNIT + 1;
+/**
+ * What each lamp keeps through glass (`pointGlassTint.ts`), a fragment sampler of the lit program.
+ * A unit of the combined pool, which WebGL2 guarantees thirty-two of; what a stage may declare is
+ * sixteen, which `textureUnitBudget.test.ts` counts from the shader source.
+ */
+export const POINT_GLASS_TINT_TEXTURE_UNIT = SUN_GLASS_TINT_TEXTURE_UNIT + 1;
+/**
+ * Each surface layer's effects table (`surfaceEffects.ts`), bound beside the albedo array it
+ * describes. **Paid for by folding**: the cookie and photometric atlases became one fixture atlas
+ * to free the sampler this takes, so the lit stage still keeps one of its sixteen spare.
+ */
+export const SURFACE_EFFECTS_TEXTURE_UNIT = POINT_GLASS_TINT_TEXTURE_UNIT + 1;
 /**
  * A cookie's tile, in texels a side.
  *

package/dist/render/lightGrid.d.ts

@@ -0,0 +1,42 @@
+/**
+ * A world's fixed lights bucketed once, so the frame's exact choice looks only at the lights near
+ * the eye rather than at every one of them.
+ *
+ * **The choice must be the full scan's, exactly, and needs no sort to be.** Both of the choice's
+ * lists break a tie in distance by source index, so the order the lights are met in cannot reach the
+ * result: what reaches it is the full scan's candidates minus only lights no query could keep —
+ * every light whose cell lies within `viewRange + maxRadius` of the eye is gathered, and the
+ * selection's own `viewRange + radius` test does the rest.
+ *
+ * **Cost stated**: built once, from where the lights stood. A light that moves or changes its reach
+ * must be re-bucketed by the caller — this is for the city's fixed thousands, and a scene's handful
+ * of movers stays with the plain scan.
+ *
+ * Nothing here allocates after construction; the gather writes into the grid's own scratch.
+ */
+import type { PointLightSource } from './pointLightSelection.ts';
+/** The most cells a grid may span, which keeps a stray light far away from costing a gigabyte. */
+export declare const LIGHT_GRID_MAX_CELLS: number;
+export interface LightGrid {
+    readonly sources: readonly PointLightSource[];
+    /** Metres a cell spans on each axis. */
+    readonly cell: number;
+    /** The world position of cell (0, 0, 0)'s corner. */
+    readonly origin: readonly [number, number, number];
+    readonly dims: readonly [number, number, number];
+    /** Where cell `c`'s lights start in `lights`; `start[c + 1]` is where they end. */
+    readonly start: Uint32Array;
+    /** Source indices by cell, ascending within each. */
+    readonly lights: Uint32Array;
+    /** The largest reach of any source, which widens every query. */
+    readonly maxRadius: number;
+    /** The last gather, cell by cell: `gathered[0..count)`. */
+    readonly gathered: Int32Array;
+}
+/** Bucket `sources` into cells of `cell` metres. Built once; not a frame path. */
+export declare function createLightGrid(sources: readonly PointLightSource[], cell: number): LightGrid;
+/**
+ * Gather into `grid.gathered`, cell by cell, every light whose cell lies within `reach` metres of
+ * (x, y, z) on each axis, and answer how many.
+ */
+export declare function gatherLights(grid: LightGrid, x: number, y: number, z: number, reach: number): number;