@driftengine/core 3.62.0 → 4.0.0

package/dist/render/gi/denoise.d.ts

@@ -0,0 +1,114 @@
+/** Filtering indirect light without smearing it across an edge or losing any of it. */
+import type { GiSource } from './chain.ts';
+/**
+ * **Indirect light arrives noisy, and every way of filtering it can quietly darken the scene.**
+ *
+ * A handful of rays a pixel is what makes this affordable, and a handful of rays is an estimate
+ * with variance. The filter is not a finishing touch — without it the chain is unusable — and the
+ * three ways it goes wrong all read as the *lighting* wanting a tuning pass rather than as the
+ * filter being wrong: a spatial kernel whose weights do not sum to one darkens every edge, a
+ * temporal blend that treats a disocclusion as staleness smears whatever moved, and a blend weight
+ * that never settles either oscillates or never reaches the mean it is averaging.
+ *
+ * **The plan asked this to reuse Wave 3A's reprojection, disocclusion and clamping rather than
+ * writing a second temporal filter, and one of those three exists.** `clipToNeighbourhood` is
+ * here, tested, and mirrored in `TEMPORAL_RESOLVE_FRAG` — so it is used. The other two do not
+ * exist in the tree and Wave 3A creates them, which is why **this module takes them as inputs
+ * rather than computing them**: `temporalDenoise` is handed the history a caller reprojected and a
+ * flag saying whether it may be trusted. That is the right shape regardless of which wave lands
+ * first — a denoiser that owned its own reprojection would be the second answer the plan was
+ * warning about — and it means the whole of this is testable and shippable today, with Wave 3A
+ * plugging into the two parameters rather than into a rewrite.
+ */
+/** One frame's worth of what the filter needs, as flat arrays a pass would upload. */
+export interface DenoiseFrame {
+    /** Three floats a pixel. */
+    readonly radiance: Float32Array;
+    /** One a pixel, in metres from the eye. A pixel that drew nothing may be `Infinity`. */
+    readonly depth: Float32Array;
+    /** Three a pixel, unit length. */
+    readonly normal: Float32Array;
+    /** Which level of the chain answered each pixel. See `filterStepFor`. */
+    readonly source: Uint8Array;
+    readonly width: number;
+    readonly height: number;
+}
+export interface SpatialOptions {
+    /**
+     * Multiplier on the kernel's spacing, in pixels. See `filterStepFor` for what chooses it.
+     *
+     * **A step rather than a radius**, which is the à-trous arrangement: the same five-tap kernel is
+     * run with its taps further apart, so a wide filter costs what a narrow one costs. A radius
+     * would cost its own square.
+     */
+    readonly step: number;
+    /**
+     * How far apart in depth two pixels may be and still share light, as a fraction of their depth.
+     *
+     * **Relative rather than absolute**, because a centimetre is a discontinuity across a desk and
+     * nothing at all across a valley. A tenth is wide enough to keep a surface tilted away from the
+     * camera together and narrow enough to find the edge of the thing standing on it.
+     */
+    readonly depthTolerance?: number;
+    /** The exponent on `max(dot(n, n'), 0)`. Higher keeps the filter inside one face. */
+    readonly normalSharpness?: number;
+}
+/**
+ * How far apart the taps go, for light that came from each level of the chain.
+ *
+ * **Task 6's `source` discriminant is what this is for**, and it is the reason that field is on
+ * `IndirectResult` at all. A sample the screen answered is as sharp as the frame it came from and
+ * wants the narrowest filter there is. One the world field answered stands for a cone's worth of
+ * surface. One the probes answered is already an interpolation over metres, and filtering it
+ * narrowly buys nothing — its noise is not at pixel scale.
+ *
+ * Filtering all three at one width either smears the sharp one or leaves the coarse one noisy, and
+ * which of those a viewer notices depends on where they are standing.
+ */
+export declare function filterStepFor(source: GiSource): number;
+/**
+ * One separable, edge-stopping pass over a frame.
+ *
+ * **The weights are renormalised by their own sum, and that is the line this module exists to get
+ * right.** A tap rejected for being on the other side of an edge has to be *removed from the
+ * average*, not set to zero and left in the denominator — the second darkens every silhouette by
+ * however much of its kernel fell off the surface, which looks like contact shadowing and is the
+ * filter eating light. `energy.test.ts` makes the same argument about the probe blend one level up.
+ */
+export declare function spatialDenoise(frame: DenoiseFrame, options: SpatialOptions, out: Float32Array): void;
+/**
+ * The least weight this frame may be given, however long a pixel has been accumulating.
+ *
+ * **An honest running mean converges and then stops listening.** One over the count is the
+ * unbiased average of everything seen, which is exactly what is wanted while a pixel is settling
+ * and exactly wrong once the world changes: at ten thousand frames a new value moves the answer by
+ * a ten-thousandth, so a light switched on takes minutes to arrive. A twentieth is the floor, which
+ * is about a third of a second at sixty frames and is the same order as
+ * `TEMPORAL_HISTORY_BLEND`'s own one-tenth.
+ */
+export declare const DENOISE_MIN_ALPHA = 0.05;
+/** What a pixel carries between frames. The caller owns one per pixel. */
+export interface TemporalPixel {
+    /** The accumulated answer. */
+    readonly value: Float32Array;
+    /** How many frames have contributed since the last disocclusion. */
+    samples: number;
+}
+export declare function newTemporalPixel(): TemporalPixel;
+/**
+ * Blend this frame into the history a caller reprojected, and answer how much history there is.
+ *
+ * `history` is where this pixel was last frame, already reprojected — **this module does not do
+ * that and is not the place for it.** `disoccluded` says the reprojection landed on something that
+ * is no longer there; `neighbourhood`, when supplied, is the box of colours actually around this
+ * pixel this frame, and the history is clipped into it by `temporalAa.ts`'s own function.
+ *
+ * **A disocclusion resets rather than blends.** It is not a stale history, it is a wrong one: a
+ * character stepping away from a wall uncovers pixels whose history is the character, and blending
+ * nine parts of that is a smear of them that follows them about. Resetting leaves one frame of
+ * noise, which the spatial pass has already reduced and which is gone by the next frame.
+ */
+export declare function temporalDenoise(current: readonly [number, number, number] | Float32Array, history: readonly [number, number, number] | Float32Array, neighbourhood: {
+    readonly min: readonly [number, number, number];
+    readonly max: readonly [number, number, number];
+} | null, disoccluded: boolean, pixel: TemporalPixel, out: Float32Array): TemporalPixel;

package/dist/render/gi/denoise.js

@@ -0,0 +1,169 @@
+/** Filtering indirect light without smearing it across an edge or losing any of it. */
+import { clipToNeighbourhood } from '../temporalAa.js';
+const DEFAULT_DEPTH_TOLERANCE = 0.1;
+const DEFAULT_NORMAL_SHARPNESS = 32;
+/**
+ * The five-tap row, which is the kernel a separable à-trous pass runs twice.
+ *
+ * `[1, 4, 6, 4, 1] / 16`, a binomial — the discrete Gaussian, and the one every implementation of
+ * this uses. It is written here rather than computed so a reader can see that it is symmetric and
+ * that it sums to one *before* any of the edge-stopping weights touch it.
+ */
+const KERNEL = [1 / 16, 4 / 16, 6 / 16, 4 / 16, 1 / 16];
+/**
+ * How far apart the taps go, for light that came from each level of the chain.
+ *
+ * **Task 6's `source` discriminant is what this is for**, and it is the reason that field is on
+ * `IndirectResult` at all. A sample the screen answered is as sharp as the frame it came from and
+ * wants the narrowest filter there is. One the world field answered stands for a cone's worth of
+ * surface. One the probes answered is already an interpolation over metres, and filtering it
+ * narrowly buys nothing — its noise is not at pixel scale.
+ *
+ * Filtering all three at one width either smears the sharp one or leaves the coarse one noisy, and
+ * which of those a viewer notices depends on where they are standing.
+ */
+export function filterStepFor(source) {
+    return source === 0 ? 1 : source === 1 ? 2 : 4;
+}
+/** Scratch, because a filter pass is per pixel and the rule about allocating in one is absolute. */
+const TOTAL = new Float32Array(3);
+const CLIPPED = [0, 0, 0];
+/**
+ * One separable, edge-stopping pass over a frame.
+ *
+ * **The weights are renormalised by their own sum, and that is the line this module exists to get
+ * right.** A tap rejected for being on the other side of an edge has to be *removed from the
+ * average*, not set to zero and left in the denominator — the second darkens every silhouette by
+ * however much of its kernel fell off the surface, which looks like contact shadowing and is the
+ * filter eating light. `energy.test.ts` makes the same argument about the probe blend one level up.
+ */
+export function spatialDenoise(frame, options, out) {
+    const depthTolerance = options.depthTolerance ?? DEFAULT_DEPTH_TOLERANCE;
+    const normalSharpness = options.normalSharpness ?? DEFAULT_NORMAL_SHARPNESS;
+    /* Horizontal into `out`, then vertical in place. Separable, so a five-tap kernel is ten taps
+       rather than twenty-five, and the two halves cannot disagree because they are one function. */
+    pass(frame, frame.radiance, out, options.step, depthTolerance, normalSharpness, true);
+    pass(frame, out, out, options.step, depthTolerance, normalSharpness, false);
+}
+function pass(frame, input, out, step, depthTolerance, normalSharpness, horizontal) {
+    const { width, height, depth, normal, source } = frame;
+    /*
+     * A second pass reading its own output would filter the taps it has already written, which is a
+     * wider and lopsided kernel rather than the one declared. Copied when the two alias.
+     */
+    const read = input === out ? new Float32Array(out) : input;
+    for (let y = 0; y < height; y++) {
+        for (let x = 0; x < width; x++) {
+            const at = y * width + x;
+            const centreDepth = depth[at];
+            const nx = normal[at * 3];
+            const ny = normal[at * 3 + 1];
+            const nz = normal[at * 3 + 2];
+            const spacing = Math.max(1, Math.round(step * filterStepFor(source[at])));
+            TOTAL.fill(0);
+            let weightSum = 0;
+            for (let tap = 0; tap < KERNEL.length; tap++) {
+                const offset = (tap - 2) * spacing;
+                const sx = horizontal ? x + offset : x;
+                const sy = horizontal ? y : y + offset;
+                if (sx < 0 || sx >= width || sy < 0 || sy >= height)
+                    continue;
+                const from = sy * width + sx;
+                /* A pixel that drew nothing has no surface to share light with. */
+                const tapDepth = depth[from];
+                if (!Number.isFinite(tapDepth) || !Number.isFinite(centreDepth)) {
+                    if (from !== at)
+                        continue;
+                }
+                const reference = Math.max(Math.abs(centreDepth), 1e-3);
+                const apart = Math.abs(tapDepth - centreDepth) / reference;
+                if (apart > depthTolerance)
+                    continue;
+                const alignment = nx * normal[from * 3] +
+                    ny * normal[from * 3 + 1] +
+                    nz * normal[from * 3 + 2];
+                const facing = Math.max(alignment, 0) ** normalSharpness;
+                if (facing <= 1e-6)
+                    continue;
+                const weight = KERNEL[tap] * facing;
+                TOTAL[0] = TOTAL[0] + read[from * 3] * weight;
+                TOTAL[1] = TOTAL[1] + read[from * 3 + 1] * weight;
+                TOTAL[2] = TOTAL[2] + read[from * 3 + 2] * weight;
+                weightSum += weight;
+            }
+            if (weightSum > 0) {
+                out[at * 3] = TOTAL[0] / weightSum;
+                out[at * 3 + 1] = TOTAL[1] / weightSum;
+                out[at * 3 + 2] = TOTAL[2] / weightSum;
+            }
+            else {
+                /* Every neighbour was rejected, including itself: keep what was there rather than black. */
+                out[at * 3] = read[at * 3];
+                out[at * 3 + 1] = read[at * 3 + 1];
+                out[at * 3 + 2] = read[at * 3 + 2];
+            }
+        }
+    }
+}
+/**
+ * The least weight this frame may be given, however long a pixel has been accumulating.
+ *
+ * **An honest running mean converges and then stops listening.** One over the count is the
+ * unbiased average of everything seen, which is exactly what is wanted while a pixel is settling
+ * and exactly wrong once the world changes: at ten thousand frames a new value moves the answer by
+ * a ten-thousandth, so a light switched on takes minutes to arrive. A twentieth is the floor, which
+ * is about a third of a second at sixty frames and is the same order as
+ * `TEMPORAL_HISTORY_BLEND`'s own one-tenth.
+ */
+export const DENOISE_MIN_ALPHA = 0.05;
+export function newTemporalPixel() {
+    return { value: new Float32Array(3), samples: 0 };
+}
+/**
+ * Blend this frame into the history a caller reprojected, and answer how much history there is.
+ *
+ * `history` is where this pixel was last frame, already reprojected — **this module does not do
+ * that and is not the place for it.** `disoccluded` says the reprojection landed on something that
+ * is no longer there; `neighbourhood`, when supplied, is the box of colours actually around this
+ * pixel this frame, and the history is clipped into it by `temporalAa.ts`'s own function.
+ *
+ * **A disocclusion resets rather than blends.** It is not a stale history, it is a wrong one: a
+ * character stepping away from a wall uncovers pixels whose history is the character, and blending
+ * nine parts of that is a smear of them that follows them about. Resetting leaves one frame of
+ * noise, which the spatial pass has already reduced and which is gone by the next frame.
+ */
+export function temporalDenoise(current, history, neighbourhood, disoccluded, pixel, out) {
+    if (disoccluded) {
+        pixel.samples = 1;
+        for (let c = 0; c < 3; c++) {
+            pixel.value[c] = current[c];
+            out[c] = current[c];
+        }
+        return pixel;
+    }
+    let hx = history[0];
+    let hy = history[1];
+    let hz = history[2];
+    if (neighbourhood !== null) {
+        clipToNeighbourhood(CLIPPED, [hx, hy, hz], neighbourhood.min, neighbourhood.max);
+        hx = CLIPPED[0];
+        hy = CLIPPED[1];
+        hz = CLIPPED[2];
+    }
+    /*
+     * One over the count while a pixel is settling, so what comes out is the unbiased mean of
+     * everything it has seen rather than a blend biased toward whatever it started at — which is the
+     * difference between converging *to* the noisy mean and converging near it. The floor is what
+     * keeps a settled pixel able to notice the world changing; see `DENOISE_MIN_ALPHA`.
+     */
+    const samples = pixel.samples + 1;
+    const alpha = Math.max(1 / samples, DENOISE_MIN_ALPHA);
+    pixel.samples = samples;
+    const blended = [hx, hy, hz];
+    for (let c = 0; c < 3; c++) {
+        const value = blended[c] + (current[c] - blended[c]) * alpha;
+        pixel.value[c] = value;
+        out[c] = value;
+    }
+    return pixel;
+}

package/dist/render/gi/fieldScene.d.ts

@@ -0,0 +1,125 @@
+/**
+ * The frame's declared distance fields — what the renderer's indirect light may be traced against.
+ *
+ * **A consumer declares this, and the seam is `addOccluder`'s for `addOccluder`'s reason.** A
+ * distance field is the shape of a thing it is *safe* to be traced against, and only the consumer
+ * knows which of its objects that is true of: the terrain and the walls, not the leaves, not the
+ * water, not the thing that is about to be deleted. `quality.occlusionCulling` already makes that
+ * sentence about occluders and culls nothing until somebody declares one. This makes it about
+ * light, and lights nothing until somebody declares a field.
+ *
+ * **A field and its placement are separate arguments on purpose.** Forty identical pillars are one
+ * baked field and forty matrices: the samples are megabytes and the matrices are bytes. So a source
+ * declared twice in a frame is two instances sharing one packed copy of its samples, and the queue
+ * is what knows the difference.
+ *
+ * **The transform is copied and the samples are not.** A consumer holds a matrix and moves it —
+ * that is what a matrix is for — so a queue that kept the reference would replay every field
+ * wearing the last pose written, which is `DecalQueue`'s recorded mistake and is the dangerous
+ * kind: a plausible picture rather than a broken one. A `FieldSource`, by contrast, is baked and
+ * does not move, and copying its samples once a frame would move the whole field across the bus to
+ * say the same thing.
+ *
+ * **Records are pooled and never released**, per `AGENTS.md`: `reset` returns the count to zero
+ * and keeps the storage, so a steady scene allocates on its first frame and never again.
+ */
+import type { ReadonlyMat4 } from 'gl-matrix';
+import type { FieldSource } from './globalField.ts';
+/**
+ * How many placed fields one frame may declare.
+ *
+ * **Thirty-two, which is what `composeGlobalField` was measured against** — 707 ms on the CPU for
+ * thirty-two instances over four cascades, and the number the device composition has carried since.
+ * The cost is not in the count itself but in the instance buffer being sized once and bound for
+ * every cascade's dispatch, so it is a cap rather than a growth.
+ */
+export declare const MAX_DISTANCE_FIELDS = 32;
+/**
+ * How many samples the frame's distinct sources may add up to, across all of them.
+ *
+ * Four million floats is sixteen megabytes on the device, which is a 160-cubed field or two
+ * hundred 27-cubed ones. **The budget is over the distinct sources rather than the instances**,
+ * because that is what is actually uploaded.
+ */
+export declare const MAX_DISTANCE_FIELD_SAMPLES: number;
+/** One placed field. `transform` is this queue's own copy; `source` is the consumer's object. */
+export interface DistanceFieldInstance {
+    /** The baked field. Shared by reference: it does not move and it is the large thing. */
+    source: FieldSource;
+    /** World from object, copied at the moment it was declared. Uniform scale only. */
+    readonly transform: Float32Array;
+    /**
+     * What colour this placement's surface is, copied like the transform. White where none was given.
+     *
+     * **A ray that lands on a wall needs to know what colour it is**, because what leaves a surface
+     * is the light arriving times its albedo — and a composed distance field is a union that has
+     * already forgotten which instance won. `demo/dev/bounce.html` is what made it necessary: a
+     * trace without it returned the same answer for a red wall and a white one.
+     *
+     * On the placement rather than the field, because the same baked shape is placed many times and
+     * two pillars cut from one mould may be painted differently.
+     */
+    readonly albedo: Float32Array;
+}
+export declare class DistanceFieldScene {
+    private readonly pool;
+    private count;
+    /** The distinct sources of this frame, in the order they were first declared. */
+    private readonly distinct;
+    /** Where each distinct source's samples start in the packed upload, in floats. */
+    private readonly offsets;
+    private samples;
+    /** The distinct sources of the frame that `reset` last ended, for `packingChanged`. */
+    private packed;
+    /** Set once when a budget is first reached, so a scene over it says so and then draws. */
+    private warnedInstances;
+    private warnedSamples;
+    /** How many placed fields this frame has recorded. */
+    get length(): number;
+    /** How many records are pooled, which a test uses to assert a steady scene stops allocating. */
+    get capacity(): number;
+    /** This frame's distinct sources, in the order their samples are packed. */
+    get sources(): readonly FieldSource[];
+    /** Floats the packed upload holds — the sum of the distinct sources' fields. */
+    get sampleCount(): number;
+    /**
+     * Whether the samples have to be uploaded again, or the placements alone will do.
+     *
+     * True when this frame's distinct sources are not the last frame's in the same order, since the
+     * offsets are positional. A scene whose fields never change answers false from its second frame
+     * on, which is what keeps a sixteen-megabyte upload out of the frame loop.
+     */
+    get packingChanged(): boolean;
+    /** Where a source's samples start in the packed upload, or -1 if it is not in this frame. */
+    offsetOf(source: FieldSource): number;
+    /**
+     * Declare a field, placed.
+     *
+     * **A source whose samples do not fit is refused whole rather than clipped.** Half a field on the
+     * device is not a coarser field; it is a field whose far half reads whatever the buffer held, and
+     * that composes as surfaces that are not there — the failure Wave 4A already paid for once, where
+     * a phantom surface passed 111,907 parity samples and was found by looking at a picture.
+     */
+    record(source: FieldSource, model: ReadonlyMat4, albedo?: ArrayLike<number>): void;
+    replay(each: (instance: DistanceFieldInstance) => void): void;
+    /** Empty it for the next frame, keeping the storage and remembering what was packed. */
+    reset(): void;
+}
+/**
+ * The world extent of everything a frame declared, into vectors the caller owns.
+ *
+ * **This is what a probe grid is fitted to when a scene declared none.** A renderer asked for
+ * indirect light has to put its probes somewhere, and the only description of the world it holds is
+ * the set of fields a consumer said its light may be traced against. That is also the *right*
+ * description: a grid sized to include everything drawn would spend its probes on the inside of the
+ * sky sphere, while a grid sized to the traceable geometry is a grid around the room.
+ *
+ * **Every corner is transformed, not the box.** A rotated box's axis-aligned extent is decided by
+ * where its corners went; transforming the two extremes and taking their min and max gives a box
+ * that is too small wherever a rotation is not a multiple of a quarter turn, and too small is a
+ * probe grid that stops short of the wall it is meant to surround.
+ *
+ * False when the frame declared nothing, rather than an empty box at the origin — which
+ * `fitProbeGrid` would answer with a plausible grid of one standing in a place no scene chose.
+ */
+export declare function distanceFieldBounds(scene: DistanceFieldScene, min: Float32Array, max: Float32Array): boolean;

package/dist/render/gi/fieldScene.js

@@ -0,0 +1,219 @@
+/**
+ * The frame's declared distance fields — what the renderer's indirect light may be traced against.
+ *
+ * **A consumer declares this, and the seam is `addOccluder`'s for `addOccluder`'s reason.** A
+ * distance field is the shape of a thing it is *safe* to be traced against, and only the consumer
+ * knows which of its objects that is true of: the terrain and the walls, not the leaves, not the
+ * water, not the thing that is about to be deleted. `quality.occlusionCulling` already makes that
+ * sentence about occluders and culls nothing until somebody declares one. This makes it about
+ * light, and lights nothing until somebody declares a field.
+ *
+ * **A field and its placement are separate arguments on purpose.** Forty identical pillars are one
+ * baked field and forty matrices: the samples are megabytes and the matrices are bytes. So a source
+ * declared twice in a frame is two instances sharing one packed copy of its samples, and the queue
+ * is what knows the difference.
+ *
+ * **The transform is copied and the samples are not.** A consumer holds a matrix and moves it —
+ * that is what a matrix is for — so a queue that kept the reference would replay every field
+ * wearing the last pose written, which is `DecalQueue`'s recorded mistake and is the dangerous
+ * kind: a plausible picture rather than a broken one. A `FieldSource`, by contrast, is baked and
+ * does not move, and copying its samples once a frame would move the whole field across the bus to
+ * say the same thing.
+ *
+ * **Records are pooled and never released**, per `AGENTS.md`: `reset` returns the count to zero
+ * and keeps the storage, so a steady scene allocates on its first frame and never again.
+ */
+import { assertCubicVoxels } from './globalField.js';
+/**
+ * How many placed fields one frame may declare.
+ *
+ * **Thirty-two, which is what `composeGlobalField` was measured against** — 707 ms on the CPU for
+ * thirty-two instances over four cascades, and the number the device composition has carried since.
+ * The cost is not in the count itself but in the instance buffer being sized once and bound for
+ * every cascade's dispatch, so it is a cap rather than a growth.
+ */
+export const MAX_DISTANCE_FIELDS = 32;
+/**
+ * How many samples the frame's distinct sources may add up to, across all of them.
+ *
+ * Four million floats is sixteen megabytes on the device, which is a 160-cubed field or two
+ * hundred 27-cubed ones. **The budget is over the distinct sources rather than the instances**,
+ * because that is what is actually uploaded.
+ */
+export const MAX_DISTANCE_FIELD_SAMPLES = 1 << 22;
+function newRecord() {
+    return {
+        source: EMPTY_SOURCE,
+        transform: new Float32Array(16),
+        albedo: Float32Array.from([1, 1, 1]),
+    };
+}
+/** A placeholder a pooled record holds before its first use, so `source` is never null. */
+const EMPTY_SOURCE = {
+    field: new Float32Array(0),
+    dims: [0, 0, 0],
+    bounds: new Float32Array(6),
+};
+export class DistanceFieldScene {
+    pool = [];
+    count = 0;
+    /** The distinct sources of this frame, in the order they were first declared. */
+    distinct = [];
+    /** Where each distinct source's samples start in the packed upload, in floats. */
+    offsets = new Map();
+    samples = 0;
+    /** The distinct sources of the frame that `reset` last ended, for `packingChanged`. */
+    packed = [];
+    /** Set once when a budget is first reached, so a scene over it says so and then draws. */
+    warnedInstances = false;
+    warnedSamples = false;
+    /** How many placed fields this frame has recorded. */
+    get length() {
+        return this.count;
+    }
+    /** How many records are pooled, which a test uses to assert a steady scene stops allocating. */
+    get capacity() {
+        return this.pool.length;
+    }
+    /** This frame's distinct sources, in the order their samples are packed. */
+    get sources() {
+        return this.distinct;
+    }
+    /** Floats the packed upload holds — the sum of the distinct sources' fields. */
+    get sampleCount() {
+        return this.samples;
+    }
+    /**
+     * Whether the samples have to be uploaded again, or the placements alone will do.
+     *
+     * True when this frame's distinct sources are not the last frame's in the same order, since the
+     * offsets are positional. A scene whose fields never change answers false from its second frame
+     * on, which is what keeps a sixteen-megabyte upload out of the frame loop.
+     */
+    get packingChanged() {
+        if (this.distinct.length !== this.packed.length)
+            return true;
+        for (let i = 0; i < this.distinct.length; i += 1) {
+            if (this.distinct[i] !== this.packed[i])
+                return true;
+        }
+        return false;
+    }
+    /** Where a source's samples start in the packed upload, or -1 if it is not in this frame. */
+    offsetOf(source) {
+        return this.offsets.get(source) ?? -1;
+    }
+    /**
+     * Declare a field, placed.
+     *
+     * **A source whose samples do not fit is refused whole rather than clipped.** Half a field on the
+     * device is not a coarser field; it is a field whose far half reads whatever the buffer held, and
+     * that composes as surfaces that are not there — the failure Wave 4A already paid for once, where
+     * a phantom surface passed 111,907 parity samples and was found by looking at a picture.
+     */
+    record(source, model, albedo) {
+        /*
+         * **Before anything else, because a malformed source is not a budget.** The two warnings below
+         * are a frame asking for more than it can carry and dropping the surplus is the honest answer;
+         * there is none to a source the composer cannot read. The renderer composes on the device and
+         * never reaches `composeGlobalField`, so its own check protects only the reference path.
+         */
+        assertCubicVoxels(source);
+        if (this.count >= MAX_DISTANCE_FIELDS) {
+            if (!this.warnedInstances) {
+                this.warnedInstances = true;
+                console.warn(`driftengine: more than ${MAX_DISTANCE_FIELDS} distance fields were declared in one ` +
+                    'frame, so the rest are not traced against. Fields that never move are cheaper baked ' +
+                    'into one source, which is composed as a single instance.');
+            }
+            return;
+        }
+        const known = this.offsets.get(source);
+        if (known === undefined) {
+            if (this.samples + source.field.length > MAX_DISTANCE_FIELD_SAMPLES) {
+                if (!this.warnedSamples) {
+                    this.warnedSamples = true;
+                    console.warn(`driftengine: the frame's distance fields exceed ${MAX_DISTANCE_FIELD_SAMPLES} ` +
+                        'samples, so this one is not traced against at all. A field composed in part reads ' +
+                        'whatever the buffer held beyond it, which is surfaces that are not there.');
+                }
+                return;
+            }
+            this.offsets.set(source, this.samples);
+            this.distinct.push(source);
+            this.samples += source.field.length;
+        }
+        let record = this.pool[this.count];
+        if (record === undefined) {
+            record = newRecord();
+            this.pool.push(record);
+        }
+        record.source = source;
+        for (let at = 0; at < 16; at += 1)
+            record.transform[at] = model[at] ?? 0;
+        /* Copied like the transform, and white where none was declared. */
+        for (let at = 0; at < 3; at += 1)
+            record.albedo[at] = albedo?.[at] ?? 1;
+        this.count += 1;
+    }
+    replay(each) {
+        for (let i = 0; i < this.count; i += 1) {
+            const record = this.pool[i];
+            if (record !== undefined)
+                each(record);
+        }
+    }
+    /** Empty it for the next frame, keeping the storage and remembering what was packed. */
+    reset() {
+        this.packed = this.distinct.slice();
+        this.count = 0;
+        this.distinct.length = 0;
+        this.offsets.clear();
+        this.samples = 0;
+    }
+}
+/**
+ * The world extent of everything a frame declared, into vectors the caller owns.
+ *
+ * **This is what a probe grid is fitted to when a scene declared none.** A renderer asked for
+ * indirect light has to put its probes somewhere, and the only description of the world it holds is
+ * the set of fields a consumer said its light may be traced against. That is also the *right*
+ * description: a grid sized to include everything drawn would spend its probes on the inside of the
+ * sky sphere, while a grid sized to the traceable geometry is a grid around the room.
+ *
+ * **Every corner is transformed, not the box.** A rotated box's axis-aligned extent is decided by
+ * where its corners went; transforming the two extremes and taking their min and max gives a box
+ * that is too small wherever a rotation is not a multiple of a quarter turn, and too small is a
+ * probe grid that stops short of the wall it is meant to surround.
+ *
+ * False when the frame declared nothing, rather than an empty box at the origin — which
+ * `fitProbeGrid` would answer with a plausible grid of one standing in a place no scene chose.
+ */
+export function distanceFieldBounds(scene, min, max) {
+    if (scene.length === 0)
+        return false;
+    for (let axis = 0; axis < 3; axis += 1) {
+        min[axis] = Infinity;
+        max[axis] = -Infinity;
+    }
+    scene.replay((instance) => {
+        const box = instance.source.bounds;
+        const m = instance.transform;
+        for (let corner = 0; corner < 8; corner += 1) {
+            const x = box[(corner & 1) === 0 ? 0 : 3];
+            const y = box[(corner & 2) === 0 ? 1 : 4];
+            const z = box[(corner & 4) === 0 ? 2 : 5];
+            for (let axis = 0; axis < 3; axis += 1) {
+                const value = m[axis] * x +
+                    m[4 + axis] * y +
+                    m[8 + axis] * z +
+                    m[12 + axis];
+                if (value < min[axis])
+                    min[axis] = value;
+                if (value > max[axis])
+                    max[axis] = value;
+            }
+        }
+    });
+    return true;
+}