@driftengine/core 4.3.0 → 4.4.1

package/dist/render/driftLight/bake.d.ts

@@ -0,0 +1,34 @@
+/**
+ * One brick of DriftLight's volume: at every sample, the light that arrives from every light that
+ * reaches it, and the direction it mostly arrives from.
+ *
+ * **Two texels a sample.** The first is the summed colour, and in its fourth channel whether the
+ * sample is a sample at all: one standing inside solid geometry is not, and its zero lets the
+ * shader's filtered lookup leave it out rather than blend darkness into the wall beside it. The
+ * second is the arrival direction, weighted by each light's brightness, so it points at a lone light
+ * with a length of one and shrinks towards zero as lights surround the sample from all sides. The
+ * shader turns the pair back into the light on a surface of any facing: exactly Lambert for a single
+ * light, a quarter of the sum, the mean of a clamped cosine, for light from everywhere.
+ *
+ * **What it gives up is the specular.** Two numbers of direction cannot say where a highlight
+ * falls, which is why the exact lights near the camera are shaded exactly and this stands in only
+ * past them, where a highlight from a candle is a fraction of a pixel.
+ */
+import type { PointLightFalloff } from './falloff.ts';
+import type { LightFieldLayout, LightReach } from './layout.ts';
+import type { DistanceAt } from './visibility.ts';
+/** Samples in a brick, and so texels in each of its two blocks. */
+export declare const BRICK_TEXELS: number;
+/** What the bake reads of a light, which a `PointLightSource` already carries. */
+export interface FieldLight extends LightReach {
+    readonly r: number;
+    readonly g: number;
+    readonly b: number;
+    /** The emitter's physical radius, which widens its penumbra. */
+    readonly sourceRadius: number;
+}
+/**
+ * Fill `light` and `direction`, `BRICK_TEXELS * 4` floats each, x fastest, for brick `brick`.
+ * `distance` is the scene's distance field, or null for no occlusion.
+ */
+export declare function bakeBrick(layout: LightFieldLayout, brick: number, lights: readonly FieldLight[], falloff: PointLightFalloff, distance: DistanceAt | null, light: Float32Array, direction: Float32Array): void;

package/dist/render/driftLight/bake.js

@@ -0,0 +1,95 @@
+/**
+ * One brick of DriftLight's volume: at every sample, the light that arrives from every light that
+ * reaches it, and the direction it mostly arrives from.
+ *
+ * **Two texels a sample.** The first is the summed colour, and in its fourth channel whether the
+ * sample is a sample at all: one standing inside solid geometry is not, and its zero lets the
+ * shader's filtered lookup leave it out rather than blend darkness into the wall beside it. The
+ * second is the arrival direction, weighted by each light's brightness, so it points at a lone light
+ * with a length of one and shrinks towards zero as lights surround the sample from all sides. The
+ * shader turns the pair back into the light on a surface of any facing: exactly Lambert for a single
+ * light, a quarter of the sum, the mean of a clamped cosine, for light from everywhere.
+ *
+ * **What it gives up is the specular.** Two numbers of direction cannot say where a highlight
+ * falls, which is why the exact lights near the camera are shaded exactly and this stands in only
+ * past them, where a highlight from a candle is a fraction of a pixel.
+ */
+import { pointLightShape } from './falloff.js';
+import { BRICK_SAMPLES } from './layout.js';
+import { softVisibility } from './visibility.js';
+/** Samples in a brick, and so texels in each of its two blocks. */
+export const BRICK_TEXELS = BRICK_SAMPLES * BRICK_SAMPLES * BRICK_SAMPLES;
+/**
+ * Fill `light` and `direction`, `BRICK_TEXELS * 4` floats each, x fastest, for brick `brick`.
+ * `distance` is the scene's distance field, or null for no occlusion.
+ */
+export function bakeBrick(layout, brick, lights, falloff, distance, light, direction) {
+    const { spacing, span, origin } = layout;
+    const bx = origin[0] + layout.brickCoords[brick * 3] * span;
+    const by = origin[1] + layout.brickCoords[brick * 3 + 1] * span;
+    const bz = origin[2] + layout.brickCoords[brick * 3 + 2] * span;
+    const first = layout.lightStart[brick];
+    const last = layout.lightStart[brick + 1];
+    for (let k = 0; k < BRICK_SAMPLES; k++) {
+        for (let j = 0; j < BRICK_SAMPLES; j++) {
+            for (let i = 0; i < BRICK_SAMPLES; i++) {
+                const texel = (i + BRICK_SAMPLES * (j + BRICK_SAMPLES * k)) * 4;
+                const px = bx + i * spacing;
+                const py = by + j * spacing;
+                const pz = bz + k * spacing;
+                light.fill(0, texel, texel + 4);
+                direction.fill(0, texel, texel + 4);
+                if (distance !== null && distance(px, py, pz) < 0)
+                    continue;
+                let r = 0;
+                let g = 0;
+                let b = 0;
+                let towardX = 0;
+                let towardY = 0;
+                let towardZ = 0;
+                let weight = 0;
+                for (let listed = first; listed < last; listed++) {
+                    const source = lights[layout.lights[listed]];
+                    if (source === undefined)
+                        continue;
+                    const dx = source.x - px;
+                    const dy = source.y - py;
+                    const dz = source.z - pz;
+                    const dist = Math.hypot(dx, dy, dz);
+                    if (dist >= source.radius)
+                        continue;
+                    const shape = pointLightShape(dist, source.radius, falloff);
+                    if (shape <= 0)
+                        continue;
+                    const seen = distance === null
+                        ? 1
+                        : softVisibility(distance, px, py, pz, source.x, source.y, source.z, source.sourceRadius);
+                    if (seen <= 0)
+                        continue;
+                    const lr = source.r * shape * seen;
+                    const lg = source.g * shape * seen;
+                    const lb = source.b * shape * seen;
+                    r += lr;
+                    g += lg;
+                    b += lb;
+                    const bright = 0.2126 * lr + 0.7152 * lg + 0.0722 * lb;
+                    if (dist > 1e-6 && bright > 0) {
+                        towardX += (bright * dx) / dist;
+                        towardY += (bright * dy) / dist;
+                        towardZ += (bright * dz) / dist;
+                        weight += bright;
+                    }
+                }
+                light[texel] = r;
+                light[texel + 1] = g;
+                light[texel + 2] = b;
+                light[texel + 3] = 1;
+                if (weight > 0) {
+                    direction[texel] = towardX / weight;
+                    direction[texel + 1] = towardY / weight;
+                    direction[texel + 2] = towardZ / weight;
+                }
+            }
+        }
+    }
+}

package/dist/render/driftLight/falloff.d.ts

@@ -0,0 +1,16 @@
+/**
+ * How a point light's brightness falls with distance, as the lit shader draws it, for the light
+ * DriftLight sums into its volume.
+ *
+ * **One formula in two languages, tied by a test.** The frame shades a light in GLSL; the volume is
+ * summed in TypeScript. If they disagree the summed light and the exact light differ where they
+ * crossfade, and a seam follows the camera across every surface. `falloff.test.ts` reads the
+ * shader's lines and asserts these numbers against them.
+ *
+ * Both of the renderer's falloffs: `smooth`, the default, is a linear ramp squared, reaching zero at
+ * the radius; `inverseSquare` is physical, windowed so it still reaches zero at the radius, and
+ * floored at ten centimetres so a surface touching a light is not infinitely bright.
+ */
+export type PointLightFalloff = 'smooth' | 'inverseSquare';
+/** The shader's `shape` for an unshaped point light: no cone, no photometric profile. */
+export declare function pointLightShape(dist: number, radius: number, falloff: PointLightFalloff): number;

package/dist/render/driftLight/falloff.js

@@ -0,0 +1,23 @@
+/**
+ * How a point light's brightness falls with distance, as the lit shader draws it, for the light
+ * DriftLight sums into its volume.
+ *
+ * **One formula in two languages, tied by a test.** The frame shades a light in GLSL; the volume is
+ * summed in TypeScript. If they disagree the summed light and the exact light differ where they
+ * crossfade, and a seam follows the camera across every surface. `falloff.test.ts` reads the
+ * shader's lines and asserts these numbers against them.
+ *
+ * Both of the renderer's falloffs: `smooth`, the default, is a linear ramp squared, reaching zero at
+ * the radius; `inverseSquare` is physical, windowed so it still reaches zero at the radius, and
+ * floored at ten centimetres so a surface touching a light is not infinitely bright.
+ */
+/** The shader's `shape` for an unshaped point light: no cone, no photometric profile. */
+export function pointLightShape(dist, radius, falloff) {
+    if (falloff === 'inverseSquare') {
+        const ratio = dist / Math.max(radius, 1e-4);
+        const window = Math.min(1, Math.max(0, 1 - ratio ** 4));
+        return (window * window) / Math.max(dist * dist, 0.01);
+    }
+    const linear = Math.min(1, Math.max(0, 1 - dist / radius));
+    return linear * linear;
+}

package/dist/render/driftLight/layout.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Where DriftLight's volume exists: the bricks some light reaches, the grid that finds them, and
+ * which lights reach each one.
+ *
+ * **Sparse, because light is.** A candle reaches a metre and a courtyard is forty, so a dense grid
+ * would be almost entirely zeros: a brick is kept only where a light's reach touches it, by the
+ * exact sphere-against-box test rather than the box-against-box one, which takes the corner bricks a
+ * sphere's box reaches and the sphere does not.
+ *
+ * **A brick is four samples a side and shares its faces with its neighbours**, so it spans three
+ * spacings and two bricks that meet agree on the samples between them. That is what lets the shader
+ * filter inside one brick with the hardware's trilinear lookup and never see a seam where it crosses
+ * into the next.
+ *
+ * **Numbered in the index's own order**, x fastest, so a layout depends on where the lights are and
+ * not on the order a scene listed them in: two loads of one scene produce one atlas.
+ *
+ * What it gives up: the index is dense over the lights' bounding box, so lights spread thinly over a
+ * kilometre would make a large, mostly empty grid. It refuses one past `MAX_INDEX_AXIS` bricks on
+ * any axis and says to make one field per region instead; what would change that is a hashed
+ * index, which costs the shader a probe loop.
+ */
+/** Samples on each axis of a brick. The first and last are shared with the neighbour. */
+export declare const BRICK_SAMPLES = 4;
+/**
+ * Bricks on each axis of the index, which is a 3D texture: 256 is the least `MAX_3D_TEXTURE_SIZE`
+ * WebGL2 promises, and a limit on the cell count alone would pass a grid 300 bricks long and one
+ * wide that a device is free to refuse. At a metre a brick, a field 256 m on a side.
+ */
+export declare const MAX_INDEX_AXIS = 256;
+/** What the layout reads of a light: where it is and how far it reaches. */
+export interface LightReach {
+    readonly x: number;
+    readonly y: number;
+    readonly z: number;
+    readonly radius: number;
+}
+export interface LightFieldLayout {
+    /** Metres between two samples. */
+    readonly spacing: number;
+    /** Metres a brick spans: three spacings. */
+    readonly span: number;
+    /** The world position of brick (0, 0, 0)'s first sample. */
+    readonly origin: readonly [number, number, number];
+    /** Bricks on each axis of the index. */
+    readonly dims: readonly [number, number, number];
+    /** Per index cell, x fastest: the brick's number plus one, or 0 where there is no brick. */
+    readonly index: Uint32Array;
+    /** How many bricks there are. */
+    readonly count: number;
+    /** Each brick's cell in the index, three integers a brick. */
+    readonly brickCoords: Int32Array;
+    /** Where brick `b`'s lights start in `lights`; `lightStart[b + 1]` is where they end. */
+    readonly lightStart: Uint32Array;
+    /** The lights reaching each brick, in the order the scene listed them. */
+    readonly lights: Uint32Array;
+}
+/** The bricks `lights` reach at `spacing` metres between samples. Built once; not a frame path. */
+export declare function layoutLightField(lights: readonly LightReach[], spacing: number): LightFieldLayout;

package/dist/render/driftLight/layout.js

@@ -0,0 +1,138 @@
+/**
+ * Where DriftLight's volume exists: the bricks some light reaches, the grid that finds them, and
+ * which lights reach each one.
+ *
+ * **Sparse, because light is.** A candle reaches a metre and a courtyard is forty, so a dense grid
+ * would be almost entirely zeros: a brick is kept only where a light's reach touches it, by the
+ * exact sphere-against-box test rather than the box-against-box one, which takes the corner bricks a
+ * sphere's box reaches and the sphere does not.
+ *
+ * **A brick is four samples a side and shares its faces with its neighbours**, so it spans three
+ * spacings and two bricks that meet agree on the samples between them. That is what lets the shader
+ * filter inside one brick with the hardware's trilinear lookup and never see a seam where it crosses
+ * into the next.
+ *
+ * **Numbered in the index's own order**, x fastest, so a layout depends on where the lights are and
+ * not on the order a scene listed them in: two loads of one scene produce one atlas.
+ *
+ * What it gives up: the index is dense over the lights' bounding box, so lights spread thinly over a
+ * kilometre would make a large, mostly empty grid. It refuses one past `MAX_INDEX_AXIS` bricks on
+ * any axis and says to make one field per region instead; what would change that is a hashed
+ * index, which costs the shader a probe loop.
+ */
+/** Samples on each axis of a brick. The first and last are shared with the neighbour. */
+export const BRICK_SAMPLES = 4;
+/**
+ * Bricks on each axis of the index, which is a 3D texture: 256 is the least `MAX_3D_TEXTURE_SIZE`
+ * WebGL2 promises, and a limit on the cell count alone would pass a grid 300 bricks long and one
+ * wide that a device is free to refuse. At a metre a brick, a field 256 m on a side.
+ */
+export const MAX_INDEX_AXIS = 256;
+const EMPTY = {
+    spacing: 0,
+    span: 0,
+    origin: [0, 0, 0],
+    dims: [0, 0, 0],
+    index: new Uint32Array(0),
+    count: 0,
+    brickCoords: new Int32Array(0),
+    lightStart: new Uint32Array(1),
+    lights: new Uint32Array(0),
+};
+/** The bricks `lights` reach at `spacing` metres between samples. Built once; not a frame path. */
+export function layoutLightField(lights, spacing) {
+    if (!(spacing > 0)) {
+        throw new Error(`layoutLightField: spacing is ${String(spacing)} and must be positive.`);
+    }
+    const span = spacing * (BRICK_SAMPLES - 1);
+    const min = [Infinity, Infinity, Infinity];
+    const max = [-Infinity, -Infinity, -Infinity];
+    let reaching = 0;
+    for (const light of lights) {
+        if (!(light.radius > 0))
+            continue;
+        reaching += 1;
+        const at = [light.x, light.y, light.z];
+        for (let axis = 0; axis < 3; axis++) {
+            min[axis] = Math.min(min[axis], at[axis] - light.radius);
+            max[axis] = Math.max(max[axis], at[axis] + light.radius);
+        }
+    }
+    if (reaching === 0)
+        return EMPTY;
+    const origin = min.map((value) => Math.floor(value / span) * span);
+    const dims = max.map((value, axis) => Math.floor((value - origin[axis]) / span) + 1);
+    if (dims.some((across) => across > MAX_INDEX_AXIS)) {
+        throw new Error(`layoutLightField: these lights span ${dims.join(' x ')} bricks against a limit of ` +
+            `${MAX_INDEX_AXIS} on each axis. Give each region of the world a field of its own, or a ` +
+            'coarser spacing.');
+    }
+    const cells = dims[0] * dims[1] * dims[2];
+    /* Which cells a light reaches, visited twice: once to mark and count, once to list. */
+    const visit = (each) => {
+        lights.forEach((light, number) => {
+            if (!(light.radius > 0))
+                return;
+            const at = [light.x, light.y, light.z];
+            const low = [0, 0, 0];
+            const high = [0, 0, 0];
+            for (let axis = 0; axis < 3; axis++) {
+                const o = origin[axis];
+                const p = at[axis];
+                low[axis] = Math.max(0, Math.floor((p - light.radius - o) / span));
+                high[axis] = Math.min(dims[axis] - 1, Math.floor((p + light.radius - o) / span));
+            }
+            const reach2 = light.radius * light.radius;
+            for (let k = low[2]; k <= high[2]; k++) {
+                for (let j = low[1]; j <= high[1]; j++) {
+                    for (let i = low[0]; i <= high[0]; i++) {
+                        const cell = [i, j, k];
+                        let d2 = 0;
+                        for (let axis = 0; axis < 3; axis++) {
+                            const lo = origin[axis] + cell[axis] * span;
+                            const p = at[axis];
+                            const out = Math.max(lo - p, 0, p - (lo + span));
+                            d2 += out * out;
+                        }
+                        if (d2 <= reach2)
+                            each(number, i + dims[0] * (j + dims[1] * k));
+                    }
+                }
+            }
+        });
+    };
+    const index = new Uint32Array(cells);
+    let pairs = 0;
+    visit((_, cell) => {
+        index[cell] = 1;
+        pairs += 1;
+    });
+    let count = 0;
+    for (let cell = 0; cell < cells; cell++)
+        if (index[cell] !== 0)
+            index[cell] = ++count;
+    const brickCoords = new Int32Array(count * 3);
+    for (let cell = 0; cell < cells; cell++) {
+        const brick = index[cell] - 1;
+        if (brick < 0)
+            continue;
+        brickCoords[brick * 3] = cell % dims[0];
+        brickCoords[brick * 3 + 1] = Math.floor(cell / dims[0]) % dims[1];
+        brickCoords[brick * 3 + 2] = Math.floor(cell / (dims[0] * dims[1]));
+    }
+    const lightStart = new Uint32Array(count + 1);
+    visit((_, cell) => {
+        lightStart[index[cell]] = lightStart[index[cell]] + 1;
+    });
+    for (let brick = 0; brick < count; brick++) {
+        lightStart[brick + 1] = lightStart[brick + 1] + lightStart[brick];
+    }
+    const filled = lightStart.slice(0, count);
+    const listed = new Uint32Array(pairs);
+    visit((light, cell) => {
+        const brick = index[cell] - 1;
+        listed[filled[brick]] = light;
+        filled[brick] = filled[brick] + 1;
+    });
+    return { spacing, span, origin, dims, index, count, brickCoords, lightStart, lights: listed };
+}

package/dist/render/driftLight/lightField.d.ts

@@ -0,0 +1,108 @@
+/**
+ * DriftLight: a scene's many fixed lights summed into one volume, which stands in for them wherever
+ * they are not shaded one by one.
+ *
+ * **The problem it answers.** A frame shades a few hundred lights at most, chosen nearest the
+ * camera, and a scene of thousands of candles left every one past that choice dark: a wall with a
+ * dozen candles beside it lit nothing until the camera walked up to it. This sums every fixed light
+ * once, occluded by the scene's distance field, into sparse bricks of light and direction; the lit
+ * shader shades exactly where the frame's choice is complete (`PointLightBuffer.complete`) and reads
+ * the volume past it, crossfading across a band so nothing pops. A light is never counted twice:
+ * the split is per pixel, and the field's own lights carry a mark (`inLightField`) the selection
+ * turns into the sign of their weight.
+ *
+ * **Baked a few bricks a step, by the scene.** `bake(bricks)` does the number asked, so a scene paces
+ * it as it paces anything else it builds behind a loading screen, and the build is deterministic:
+ * the engine reads no clock. The volume is not summed into the frame until every brick has landed,
+ * then fades in over `fadeSec`, so a field completing in view does not pop; a field baked behind a
+ * loading screen asks for no fade.
+ *
+ * **The lights are summed as they stood when the field was made**, from a copy: a scene dimming its
+ * lamps at dawn rewrites the very objects it gave the field, and a bake paced into the morning
+ * would otherwise sum lamps already out. `scale` dims what was summed.
+ *
+ * What it gives up is stated where each part does it: specular from summed lights (`bake.ts`),
+ * flicker past the choice (the volume holds each light's steady colour), and occlusion by anything
+ * that moves (only the fields given at construction shadow it).
+ */
+import type { GlobalFieldInstance } from '../gi/globalField.ts';
+import type { FieldLight } from './bake.ts';
+import type { PointLightFalloff } from './falloff.ts';
+import type { LightFieldLayout } from './layout.ts';
+/** Seconds the summed light takes to fade in once the field is whole. */
+export declare const FIELD_FADE_SEC = 0.5;
+/** A light a field sums: a `PointLightSource`, whose `inLightField` the field sets. */
+export interface LightFieldSource extends FieldLight {
+    inLightField?: boolean;
+}
+export interface LightFieldOptions {
+    /** How the renderer shades a point light, which the sum has to match. */
+    readonly falloff: PointLightFalloff;
+    /** Metres between samples; a third of a metre by default, so a brick spans a metre. */
+    readonly spacing?: number;
+    /** The scene's placed distance fields, which occlude the light. None leaves it unoccluded. */
+    readonly fields?: readonly GlobalFieldInstance[];
+    /** Metres over which exact and summed light crossfade at the shading radius. Two by default. */
+    readonly band?: number;
+    /**
+     * Seconds the summed light fades in over once the field is whole, `FIELD_FADE_SEC` by default.
+     * Zero for a field baked behind a loading screen, which has nothing on screen to pop and may be
+     * stepped by a clock that has stopped.
+     */
+    readonly fadeSec?: number;
+}
+export declare class LightField {
+    readonly layout: LightFieldLayout;
+    /** Texels on each axis of the atlas. */
+    readonly atlasSize: readonly [number, number, number];
+    /** Bricks on each axis of the atlas, which the shader needs to find a brick's corner. */
+    readonly atlasBricks: readonly [number, number, number];
+    /** The atlas as half floats, four channels a texel, x fastest. */
+    readonly atlas: Uint16Array;
+    /** Metres over which exact and summed light crossfade. */
+    readonly band: number;
+    /** Whether a distance field occludes this field's light. */
+    readonly occluded: boolean;
+    /** Seconds the summed light fades in over once whole; zero is at once. */
+    readonly fadeSec: number;
+    /** The summed light's brightness, for a scene that dims all its lamps at once: dawn, a switch. */
+    scale: number;
+    /** Where the frame's choice was centred, which the shader measures the radius from. */
+    readonly centre: Float32Array<ArrayBuffer>;
+    private readonly lights;
+    private readonly falloff;
+    private readonly distance;
+    private readonly lightBlock;
+    private readonly directionBlock;
+    private baked;
+    private taken;
+    private eased;
+    private shown;
+    constructor(lights: readonly LightFieldSource[], options: LightFieldOptions);
+    /** Whether every brick has been baked. */
+    get ready(): boolean;
+    /** How much of the bake is done, 0 to 1, for a loading screen. */
+    get progress(): number;
+    /** The radius, in metres from `centre`, inside which lights are shaded exactly. */
+    get radius(): number;
+    /** How much of the summed light is in the frame, 0 until the field is whole, then up to 1. */
+    get presence(): number;
+    /** The texel at which brick `brick`'s light block starts; its direction block is 4 along x. */
+    atlasCorner(brick: number): [number, number, number];
+    /** Bake up to `bricks` more bricks into the atlas, and answer how many were baked. */
+    bake(bricks: number): number;
+    /** The bricks baked since the last call, for a backend to upload. */
+    takeBaked(): {
+        from: number;
+        to: number;
+    };
+    /**
+     * Follow the frame's choice: `complete` from the selection, centred at (x, y, z). The radius
+     * shrinks at once, because a pixel inside it that a left-out light reaches would be shaded
+     * short, and grows back slowly, because a pixel it has not reached yet takes the summed light,
+     * which is only less exact. While nothing is summed the radius simply follows.
+     */
+    follow(complete: number, x: number, y: number, z: number, dtSec: number): void;
+    /** Write the brick just baked into its place in the atlas, as half floats. */
+    private place;
+}

package/dist/render/driftLight/lightField.js

@@ -0,0 +1,179 @@
+/**
+ * DriftLight: a scene's many fixed lights summed into one volume, which stands in for them wherever
+ * they are not shaded one by one.
+ *
+ * **The problem it answers.** A frame shades a few hundred lights at most, chosen nearest the
+ * camera, and a scene of thousands of candles left every one past that choice dark: a wall with a
+ * dozen candles beside it lit nothing until the camera walked up to it. This sums every fixed light
+ * once, occluded by the scene's distance field, into sparse bricks of light and direction; the lit
+ * shader shades exactly where the frame's choice is complete (`PointLightBuffer.complete`) and reads
+ * the volume past it, crossfading across a band so nothing pops. A light is never counted twice:
+ * the split is per pixel, and the field's own lights carry a mark (`inLightField`) the selection
+ * turns into the sign of their weight.
+ *
+ * **Baked a few bricks a step, by the scene.** `bake(bricks)` does the number asked, so a scene paces
+ * it as it paces anything else it builds behind a loading screen, and the build is deterministic:
+ * the engine reads no clock. The volume is not summed into the frame until every brick has landed,
+ * then fades in over `fadeSec`, so a field completing in view does not pop; a field baked behind a
+ * loading screen asks for no fade.
+ *
+ * **The lights are summed as they stood when the field was made**, from a copy: a scene dimming its
+ * lamps at dawn rewrites the very objects it gave the field, and a bake paced into the morning
+ * would otherwise sum lamps already out. `scale` dims what was summed.
+ *
+ * What it gives up is stated where each part does it: specular from summed lights (`bake.ts`),
+ * flicker past the choice (the volume holds each light's steady colour), and occlusion by anything
+ * that moves (only the fields given at construction shadow it).
+ */
+import { distanceToInstances } from '../gi/globalField.js';
+import { halfBits } from '../halfFloat.js';
+import { BRICK_TEXELS, bakeBrick } from './bake.js';
+import { BRICK_SAMPLES, layoutLightField } from './layout.js';
+/** Seconds the summed light takes to fade in once the field is whole. */
+export const FIELD_FADE_SEC = 0.5;
+/** How fast the shading radius grows back, per second, when the choice reaches further again. */
+const RADIUS_GROWTH_PER_SEC = 2;
+/** Bricks along each axis of the atlas: 256 texels a side, the least 3D texture WebGL2 promises. */
+const ATLAS_BRICKS = [32, 64, 64];
+/** A brick's footprint in the atlas: its light block and its direction block side by side. */
+const BRICK_WIDTH = BRICK_SAMPLES * 2;
+export class LightField {
+    layout;
+    /** Texels on each axis of the atlas. */
+    atlasSize;
+    /** Bricks on each axis of the atlas, which the shader needs to find a brick's corner. */
+    atlasBricks;
+    /** The atlas as half floats, four channels a texel, x fastest. */
+    atlas;
+    /** Metres over which exact and summed light crossfade. */
+    band;
+    /** Whether a distance field occludes this field's light. */
+    occluded;
+    /** Seconds the summed light fades in over once whole; zero is at once. */
+    fadeSec;
+    /** The summed light's brightness, for a scene that dims all its lamps at once: dawn, a switch. */
+    scale = 1;
+    /** Where the frame's choice was centred, which the shader measures the radius from. */
+    centre = new Float32Array(3);
+    lights;
+    falloff;
+    distance;
+    lightBlock = new Float32Array(BRICK_TEXELS * 4);
+    directionBlock = new Float32Array(BRICK_TEXELS * 4);
+    baked = 0;
+    taken = 0;
+    eased = 0;
+    shown = 0;
+    constructor(lights, options) {
+        for (const light of lights)
+            light.inLightField = true;
+        this.lights = lights.map(({ x, y, z, radius, r, g, b, sourceRadius }) => ({
+            x,
+            y,
+            z,
+            radius,
+            r,
+            g,
+            b,
+            sourceRadius,
+        }));
+        this.falloff = options.falloff;
+        this.band = options.band ?? 2;
+        this.fadeSec = Math.max(0, options.fadeSec ?? FIELD_FADE_SEC);
+        const fields = options.fields ?? [];
+        this.occluded = fields.length > 0;
+        this.distance = this.occluded ? distanceToInstances(fields) : null;
+        this.layout = layoutLightField(lights, options.spacing ?? 1 / 3);
+        const count = this.layout.count;
+        const capacity = ATLAS_BRICKS[0] * ATLAS_BRICKS[1] * ATLAS_BRICKS[2];
+        if (count > capacity) {
+            throw new Error(`LightField: these lights reach ${count} bricks and one field holds ${capacity}. ` +
+                'Give each region of the world a field of its own, or a coarser spacing.');
+        }
+        const ax = Math.max(1, Math.min(count, ATLAS_BRICKS[0]));
+        const ay = Math.max(1, Math.min(Math.ceil(count / ax), ATLAS_BRICKS[1]));
+        const az = Math.max(1, Math.ceil(count / (ax * ay)));
+        this.atlasBricks = [ax, ay, az];
+        this.atlasSize = [ax * BRICK_WIDTH, ay * BRICK_SAMPLES, az * BRICK_SAMPLES];
+        this.atlas = new Uint16Array(this.atlasSize[0] * this.atlasSize[1] * this.atlasSize[2] * 4);
+    }
+    /** Whether every brick has been baked. */
+    get ready() {
+        return this.baked >= this.layout.count;
+    }
+    /** How much of the bake is done, 0 to 1, for a loading screen. */
+    get progress() {
+        return this.layout.count === 0 ? 1 : this.baked / this.layout.count;
+    }
+    /** The radius, in metres from `centre`, inside which lights are shaded exactly. */
+    get radius() {
+        return this.eased;
+    }
+    /** How much of the summed light is in the frame, 0 until the field is whole, then up to 1. */
+    get presence() {
+        return this.shown;
+    }
+    /** The texel at which brick `brick`'s light block starts; its direction block is 4 along x. */
+    atlasCorner(brick) {
+        const [ax, ay] = this.atlasBricks;
+        return [
+            (brick % ax) * BRICK_WIDTH,
+            (Math.floor(brick / ax) % ay) * BRICK_SAMPLES,
+            Math.floor(brick / (ax * ay)) * BRICK_SAMPLES,
+        ];
+    }
+    /** Bake up to `bricks` more bricks into the atlas, and answer how many were baked. */
+    bake(bricks) {
+        const end = Math.min(this.layout.count, this.baked + Math.max(0, Math.floor(bricks)));
+        const done = end - this.baked;
+        for (let brick = this.baked; brick < end; brick++) {
+            bakeBrick(this.layout, brick, this.lights, this.falloff, this.distance, this.lightBlock, this.directionBlock);
+            this.place(brick);
+        }
+        this.baked = end;
+        return done;
+    }
+    /** The bricks baked since the last call, for a backend to upload. */
+    takeBaked() {
+        const range = { from: this.taken, to: this.baked };
+        this.taken = this.baked;
+        return range;
+    }
+    /**
+     * Follow the frame's choice: `complete` from the selection, centred at (x, y, z). The radius
+     * shrinks at once, because a pixel inside it that a left-out light reaches would be shaded
+     * short, and grows back slowly, because a pixel it has not reached yet takes the summed light,
+     * which is only less exact. While nothing is summed the radius simply follows.
+     */
+    follow(complete, x, y, z, dtSec) {
+        this.centre[0] = x;
+        this.centre[1] = y;
+        this.centre[2] = z;
+        const showing = this.shown > 0;
+        if (!showing || complete < this.eased)
+            this.eased = complete;
+        else
+            this.eased += (complete - this.eased) * (1 - Math.exp(-RADIUS_GROWTH_PER_SEC * dtSec));
+        if (this.ready) {
+            this.shown = this.fadeSec > 0 ? Math.min(1, this.shown + dtSec / this.fadeSec) : 1;
+        }
+    }
+    /** Write the brick just baked into its place in the atlas, as half floats. */
+    place(brick) {
+        const [x0, y0, z0] = this.atlasCorner(brick);
+        const [w, h] = this.atlasSize;
+        for (let k = 0; k < BRICK_SAMPLES; k++) {
+            for (let j = 0; j < BRICK_SAMPLES; j++) {
+                for (let i = 0; i < BRICK_SAMPLES; i++) {
+                    const from = (i + BRICK_SAMPLES * (j + BRICK_SAMPLES * k)) * 4;
+                    const light = (((z0 + k) * h + (y0 + j)) * w + (x0 + i)) * 4;
+                    const direction = light + BRICK_SAMPLES * 4;
+                    for (let c = 0; c < 4; c++) {
+                        this.atlas[light + c] = halfBits(this.lightBlock[from + c]);
+                        this.atlas[direction + c] = halfBits(this.directionBlock[from + c]);
+                    }
+                }
+            }
+        }
+    }
+}