@driftengine/core 3.63.0 → 4.1.0

package/dist/render/frame/validate.js

@@ -0,0 +1,22 @@
+import { readsOf, writesOf } from './deps.js';
+export function validateGraph(deps, count, imported) {
+    const written = new Set(imported);
+    for (let node = 0; node < count; node += 1) {
+        /*
+         * Reads are checked before this node's writes join the set, which is what makes a read of
+         * something written only later a refusal and a read-modify-write legal — the latter is
+         * reading contents something earlier put there.
+         */
+        const reads = readsOf(deps, node);
+        for (let i = 0; i < reads.length; i += 1) {
+            const id = reads[i] ?? 0;
+            if (!written.has(id)) {
+                return `node ${node} reads resource ${id}, which nothing wrote and nothing imported`;
+            }
+        }
+        const writes = writesOf(deps, node);
+        for (let i = 0; i < writes.length; i += 1)
+            written.add(writes[i] ?? 0);
+    }
+    return null;
+}

package/dist/render/frame/virtual.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Transient resources a frame declares, addressed by identifier rather than by bit.
+ *
+ * **`resources.ts` is not replaced and is not wrong.** It is a fixed table of fourteen
+ * attachments held in a bit mask, and it says in its own header that the transient allocator a
+ * frame graph is famous for would be machinery with no case to serve — which was true while
+ * this frame's composition was fixed. A GPU-driven frame's composition is not: hierarchical
+ * depth chains, visibility buffers, per-material bin lists and indirect argument buffers are
+ * allocated against what the frame contains. Thirty-one bits cannot hold hundreds of them and
+ * a thirty-second bit is not the fix.
+ *
+ * So there are two representations and each is used where it is right: the mask for a fixed
+ * composition, identifiers for a dynamic one. Nothing converts between them, because nothing
+ * needs to — a frame is scheduled by one or the other.
+ *
+ * Structure of arrays, growable by doubling, and nothing here holds an object per resource.
+ */
+/** A transient texture, sized in texels. */
+export interface VirtualTextureDesc {
+    kind: 'texture';
+    width: number;
+    height: number;
+    bytesPerTexel: number;
+}
+/** A transient buffer, sized in bytes. */
+export interface VirtualBufferDesc {
+    kind: 'buffer';
+    bytes: number;
+}
+export type VirtualDesc = VirtualTextureDesc | VirtualBufferDesc;
+export interface VirtualTable {
+    /** 0 for a texture, 1 for a buffer, one entry per identifier. */
+    kinds: Uint8Array;
+    /** Byte footprint per identifier, which is what the aliasing allocator packs. */
+    bytes: Uint32Array;
+    /** How many identifiers have been declared this frame. */
+    count: number;
+}
+export declare function createVirtualTable(capacity: number): VirtualTable;
+export declare function resetVirtualTable(table: VirtualTable): void;
+export declare function virtualCount(table: VirtualTable): number;
+export declare function declareVirtual(table: VirtualTable, desc: VirtualDesc): number;
+export declare function virtualKind(table: VirtualTable, id: number): number;
+export declare function virtualBytes(table: VirtualTable, id: number): number;

package/dist/render/frame/virtual.js

@@ -0,0 +1,61 @@
+/**
+ * Transient resources a frame declares, addressed by identifier rather than by bit.
+ *
+ * **`resources.ts` is not replaced and is not wrong.** It is a fixed table of fourteen
+ * attachments held in a bit mask, and it says in its own header that the transient allocator a
+ * frame graph is famous for would be machinery with no case to serve — which was true while
+ * this frame's composition was fixed. A GPU-driven frame's composition is not: hierarchical
+ * depth chains, visibility buffers, per-material bin lists and indirect argument buffers are
+ * allocated against what the frame contains. Thirty-one bits cannot hold hundreds of them and
+ * a thirty-second bit is not the fix.
+ *
+ * So there are two representations and each is used where it is right: the mask for a fixed
+ * composition, identifiers for a dynamic one. Nothing converts between them, because nothing
+ * needs to — a frame is scheduled by one or the other.
+ *
+ * Structure of arrays, growable by doubling, and nothing here holds an object per resource.
+ */
+export function createVirtualTable(capacity) {
+    return { kinds: new Uint8Array(capacity), bytes: new Uint32Array(capacity), count: 0 };
+}
+export function resetVirtualTable(table) {
+    table.count = 0;
+}
+export function virtualCount(table) {
+    return table.count;
+}
+/*
+ * Doubling rather than growing by one, because a frame that declares one more resource than
+ * last frame will declare one more again, and a table that reallocates per declaration turns a
+ * linear frame into a quadratic one.
+ */
+function grow(table) {
+    const size = table.kinds.length === 0 ? 8 : table.kinds.length * 2;
+    const kinds = new Uint8Array(size);
+    kinds.set(table.kinds);
+    const bytes = new Uint32Array(size);
+    bytes.set(table.bytes);
+    table.kinds = kinds;
+    table.bytes = bytes;
+}
+export function declareVirtual(table, desc) {
+    if (table.count === table.kinds.length)
+        grow(table);
+    const id = table.count;
+    if (desc.kind === 'texture') {
+        table.kinds[id] = 0;
+        table.bytes[id] = desc.width * desc.height * desc.bytesPerTexel;
+    }
+    else {
+        table.kinds[id] = 1;
+        table.bytes[id] = desc.bytes;
+    }
+    table.count = id + 1;
+    return id;
+}
+export function virtualKind(table, id) {
+    return table.kinds[id] ?? 0;
+}
+export function virtualBytes(table, id) {
+    return table.bytes[id] ?? 0;
+}

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

@@ -0,0 +1,82 @@
+/** The three levels in one place, and the rule that there is never a fourth. */
+import type { ReadonlyVec3 } from 'gl-matrix';
+import type { ProbeGrid } from '../probeGrid.ts';
+import type { ScreenSpaceMarch } from '../screenSpaceReflection.ts';
+import type { GlobalField } from './globalField.ts';
+import type { ProbeVisibility } from './probeVolume.ts';
+import type { FieldMarch } from './traceField.ts';
+/**
+ * **Three levels, and the architecture is the fallback rather than any one of them.**
+ *
+ * `ROADMAP.md` refused screen-space global illumination, and this does not reverse that refusal —
+ * it satisfies the requirement the refusal was about. Screen space is exact wherever the screen has
+ * the answer and has *no* answer where it does not, which as a terminal technique means inventing
+ * one from whatever happened to be in frame. Here it is an accelerator with something behind it:
+ * a world-space distance field whose error is bounded by its own resolution, and behind that a
+ * probe volume which is never wrong and only ever coarse.
+ *
+ * **The last level cannot fail, and that is the load-bearing sentence.** A ray with no answer
+ * leaves a shader nothing to write but what the buffer held, which is the previous frame and reads
+ * as a flicker. A probe volume is an interpolation between measurements — no ray to escape, no
+ * frame to leave — and `visibleProbes` falls back to the nearest probe even when every visibility
+ * weight has crushed to zero. So there are exactly three cases.
+ *
+ * **And the levels blend rather than switch.** Every boundary between them moves with the camera:
+ * the frame's edge does by definition, and the cascades are centred on the camera so their faces do
+ * too. A hard switch at a boundary that moves is a seam that sweeps across the picture whenever the
+ * camera turns, which is worse than either level's own error — an error that is wrong everywhere
+ * reads as a coarse solution, and one that changes abruptly along a surface reads as a crack.
+ */
+export declare const GI_SOURCE_SCREEN = 0;
+export declare const GI_SOURCE_FIELD = 1;
+export declare const GI_SOURCE_PROBES = 2;
+export type GiSource = 0 | 1 | 2;
+/** One indirect ray, as the shading path hands it over. */
+export interface IndirectRay {
+    /** Where it starts, on the surface being shaded. */
+    readonly point: ReadonlyVec3;
+    /** That surface's normal, which both traces lift off along. */
+    readonly normal: ReadonlyVec3;
+    readonly direction: ReadonlyVec3;
+    /** Cone half-angle for the world trace. Zero is a mirror; wider is a rougher surface. */
+    readonly coneAngle: number;
+}
+/** Everything the three levels need, gathered so a per-ray call takes one object. */
+export interface GiResources {
+    readonly eye: ReadonlyVec3;
+    readonly project: (x: number, y: number, z: number, uv: Float32Array) => boolean;
+    /** How far the eye is from whatever the frame drew, and `Infinity` where it drew nothing. */
+    readonly sceneDistance: (u: number, v: number) => number;
+    /** The radiance the frame holds at a screen position. */
+    readonly screenRadiance: (u: number, v: number, out: Float32Array) => void;
+    readonly field: GlobalField;
+    /** The radiance at a world point the field trace arrived at. */
+    readonly fieldRadiance: (x: number, y: number, z: number, out: Float32Array) => void;
+    readonly grid: ProbeGrid;
+    /** Null is the off switch, and it lands on the grid's own blend. See `probeVolume.ts`. */
+    readonly visibility: ProbeVisibility | null;
+    /** `probeChannels` floats a probe, layer-major. */
+    readonly probeValues: Float32Array;
+    readonly probeChannels: number;
+    readonly screenMarch?: ScreenSpaceMarch;
+    readonly fieldMarch?: FieldMarch;
+}
+export interface IndirectResult {
+    /** Always true. See the module header: there is no fourth case. */
+    hit: boolean;
+    /** Which level contributed most. The radiance is the blend, not this level alone. */
+    source: GiSource;
+    /** Three channels. */
+    readonly radiance: Float32Array;
+    /** How much of the answer came from each level, summing to one. */
+    readonly blend: Float32Array;
+}
+export declare function newIndirectResult(): IndirectResult;
+/**
+ * Trace one indirect ray down the chain, and always answer.
+ *
+ * The screen answers as much as its distance from the edge of the frame allows; what is left goes
+ * to the world field, as much as *its* distance from the edge of the outermost cascade allows; and
+ * whatever is left after that goes to the probes, which have nothing behind them and take it all.
+ */
+export declare function traceIndirect(ray: IndirectRay, resources: GiResources, out: IndirectResult): IndirectResult;

package/dist/render/gi/chain.js

@@ -0,0 +1,135 @@
+/** The three levels in one place, and the rule that there is never a fourth. */
+import { createProbeBlend } from '../probeGrid.js';
+import { REFLECTION_EDGE_FADE, edgeFade, newScreenSpaceHit } from '../screenSpaceReflection.js';
+import { GLOBAL_FIELD_BLEND } from './globalField.js';
+import { sampleProbeVolume, visibleProbes } from './probeVolume.js';
+import { FIELD_MARCH, newFieldHit, traceField } from './traceField.js';
+import { GI_SCREEN_MARCH, traceScreen } from './traceScreen.js';
+/**
+ * **Three levels, and the architecture is the fallback rather than any one of them.**
+ *
+ * `ROADMAP.md` refused screen-space global illumination, and this does not reverse that refusal —
+ * it satisfies the requirement the refusal was about. Screen space is exact wherever the screen has
+ * the answer and has *no* answer where it does not, which as a terminal technique means inventing
+ * one from whatever happened to be in frame. Here it is an accelerator with something behind it:
+ * a world-space distance field whose error is bounded by its own resolution, and behind that a
+ * probe volume which is never wrong and only ever coarse.
+ *
+ * **The last level cannot fail, and that is the load-bearing sentence.** A ray with no answer
+ * leaves a shader nothing to write but what the buffer held, which is the previous frame and reads
+ * as a flicker. A probe volume is an interpolation between measurements — no ray to escape, no
+ * frame to leave — and `visibleProbes` falls back to the nearest probe even when every visibility
+ * weight has crushed to zero. So there are exactly three cases.
+ *
+ * **And the levels blend rather than switch.** Every boundary between them moves with the camera:
+ * the frame's edge does by definition, and the cascades are centred on the camera so their faces do
+ * too. A hard switch at a boundary that moves is a seam that sweeps across the picture whenever the
+ * camera turns, which is worse than either level's own error — an error that is wrong everywhere
+ * reads as a coarse solution, and one that changes abruptly along a surface reads as a crack.
+ */
+export const GI_SOURCE_SCREEN = 0;
+export const GI_SOURCE_FIELD = 1;
+export const GI_SOURCE_PROBES = 2;
+export function newIndirectResult() {
+    return {
+        hit: false,
+        source: GI_SOURCE_PROBES,
+        radiance: new Float32Array(3),
+        blend: new Float32Array(3),
+    };
+}
+/** Scratch, because this runs once per ray per pixel and the rule about that is absolute. */
+const SCREEN_HIT = newScreenSpaceHit();
+const FIELD_HIT = newFieldHit();
+const PROBE_BLEND = createProbeBlend();
+const LEVEL = new Float32Array(3);
+const PROBE_OUT = new Float32Array(3);
+/**
+ * Trace one indirect ray down the chain, and always answer.
+ *
+ * The screen answers as much as its distance from the edge of the frame allows; what is left goes
+ * to the world field, as much as *its* distance from the edge of the outermost cascade allows; and
+ * whatever is left after that goes to the probes, which have nothing behind them and take it all.
+ */
+export function traceIndirect(ray, resources, out) {
+    out.radiance.fill(0);
+    out.blend.fill(0);
+    out.hit = true;
+    /* Level 0. Weighted by how far the hit landed from the edge of the frame, which is the one
+       boundary a viewer is guaranteed to see move. */
+    let screen = 0;
+    if (traceScreen(ray.point, ray.normal, ray.direction, resources.eye, resources.screenMarch ?? GI_SCREEN_MARCH, resources.project, resources.sceneDistance, SCREEN_HIT)) {
+        /*
+         * **The *path*'s margin, not the hit's.** Fading only the hit leaves the seam exactly where it
+         * was: a ray that grazes the border and lands is faded, and the ray one pixel over leaves the
+         * frame and answers nothing at all, so the weight still steps from one to zero across a line
+         * that sweeps as the camera turns. See `ScreenSpaceHit.margin`.
+         */
+        screen = edgeFade(SCREEN_HIT.margin, REFLECTION_EDGE_FADE);
+        if (screen > 0) {
+            resources.screenRadiance(SCREEN_HIT.u, SCREEN_HIT.v, LEVEL);
+            add(out.radiance, LEVEL, screen);
+        }
+    }
+    /* Level 1, for whatever the screen did not answer. Weighted the same way against the outermost
+       cascade's face, because that face is centred on the camera and therefore moves with it too. */
+    let fieldShare = 0;
+    const remaining = 1 - screen;
+    if (remaining > 0) {
+        const march = resources.fieldMarch ?? FIELD_MARCH;
+        const coned = march.coneAngle === ray.coneAngle ? march : { ...march, coneAngle: ray.coneAngle };
+        if (traceField(resources.field, ray.point, ray.normal, ray.direction, coned, FIELD_HIT)) {
+            fieldShare =
+                remaining * fieldConfidence(resources.field, FIELD_HIT.x, FIELD_HIT.y, FIELD_HIT.z);
+            if (fieldShare > 0) {
+                resources.fieldRadiance(FIELD_HIT.x, FIELD_HIT.y, FIELD_HIT.z, LEVEL);
+                add(out.radiance, LEVEL, fieldShare);
+            }
+        }
+    }
+    /*
+     * Level 2, for everything still unanswered. **It takes whatever is left without asking**, which
+     * is what "never wrong and only ever coarse" buys: there is no case where this declines.
+     */
+    const probes = 1 - screen - fieldShare;
+    if (probes > 0) {
+        visibleProbes(resources.grid, resources.visibility, ray.point[0] ?? 0, ray.point[1] ?? 0, ray.point[2] ?? 0, PROBE_BLEND);
+        sampleProbeVolume(PROBE_BLEND, resources.probeValues, resources.probeChannels, PROBE_OUT);
+        add(out.radiance, PROBE_OUT, probes);
+    }
+    out.blend[0] = screen;
+    out.blend[1] = fieldShare;
+    out.blend[2] = probes;
+    out.source =
+        screen >= fieldShare && screen >= probes
+            ? GI_SOURCE_SCREEN
+            : fieldShare >= probes
+                ? GI_SOURCE_FIELD
+                : GI_SOURCE_PROBES;
+    return out;
+}
+/**
+ * How much a world-field hit is trusted, by how far inside the outermost cascade it landed.
+ *
+ * **The same band `sampleGlobalField` fades its own cascades over**, so the two do not disagree
+ * about where the field stops being the answer. A hit right on the outer face is a hit the field
+ * barely had the information for, and the probes are what carry it the rest of the way.
+ */
+function fieldConfidence(field, x, y, z) {
+    const outer = field.cascades[field.cascades.length - 1];
+    const band = GLOBAL_FIELD_BLEND * (outer.bounds[3] - outer.bounds[0]);
+    if (band <= 0)
+        return 1;
+    const p = [x, y, z];
+    let inside = Infinity;
+    for (let axis = 0; axis < 3; axis++) {
+        inside = Math.min(inside, p[axis] - outer.bounds[axis], outer.bounds[axis + 3] - p[axis]);
+    }
+    return Math.min(1, Math.max(0, inside / band));
+}
+/** `target += source * weight`, three channels. */
+function add(target, source, weight) {
+    for (let channel = 0; channel < 3; channel++) {
+        target[channel] = target[channel] + source[channel] * weight;
+    }
+}

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;
+}