@driftengine/core 3.62.0 → 4.0.0

package/dist/render/frame/graphSchedule.js

@@ -0,0 +1,120 @@
+import { readsOf, writesOf } from './deps.js';
+export function createGraphPasses(capacity) {
+    return Array.from({ length: capacity }, () => ({ first: 0, count: 0, ordered: true }));
+}
+export function createGraphScratch(nodes, identifiers) {
+    return {
+        keep: new Uint8Array(Math.max(1, nodes)),
+        wanted: new Uint8Array(Math.max(1, identifiers)),
+    };
+}
+/*
+ * Make the scratch big enough for this frame, which is the one place it may allocate.
+ *
+ * A frame that outgrows it has to be scheduled somehow, and growing here once is what the arena
+ * does too; the scratch the caller keeps is then large enough for every frame like it. Doubled, so
+ * a frame that grows by one node at a time does not reallocate every frame.
+ */
+function fitScratch(scratch, deps, count) {
+    if (scratch.keep.length < count) {
+        scratch.keep = new Uint8Array(Math.max(count, scratch.keep.length * 2));
+    }
+    let ceiling = 0;
+    for (let i = 0; i < deps.used; i += 1)
+        ceiling = Math.max(ceiling, (deps.edges[i] ?? 0) + 1);
+    if (scratch.wanted.length < ceiling) {
+        scratch.wanted = new Uint8Array(Math.max(ceiling, scratch.wanted.length * 2));
+    }
+}
+/*
+ * Mark every node that contributes to something in `live`, to a fixed point.
+ *
+ * Backwards, because a node is needed exactly when something after it reads what it writes. One
+ * backward sweep suffices for a chain; the outer repeat covers a node that writes a resource
+ * read by an earlier-indexed node, which cannot happen in a well-formed frame but costs one
+ * comparison to be safe about rather than one silently wrong picture to discover.
+ *
+ * `fitScratch` sized both flags for everything recorded, and this relies on it: a keep flag past
+ * the end of `keep` would read 0 after being set, and the sweep would never settle.
+ */
+function markLive(deps, count, live, liveCount, scratch) {
+    const { keep, wanted } = scratch;
+    keep.fill(0, 0, count);
+    wanted.fill(0);
+    /* A live identifier past the end is one no node writes, and a typed array ignores the write. */
+    for (let i = 0; i < liveCount; i += 1)
+        wanted[live[i] ?? -1] = 1;
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (let node = count - 1; node >= 0; node -= 1) {
+            if (keep[node] === 1)
+                continue;
+            const writes = writesOf(deps, node);
+            let needed = false;
+            for (let i = 0; i < writes.length; i += 1) {
+                if (wanted[writes[i] ?? 0] === 1) {
+                    needed = true;
+                    break;
+                }
+            }
+            if (!needed)
+                continue;
+            keep[node] = 1;
+            changed = true;
+            const reads = readsOf(deps, node);
+            for (let i = 0; i < reads.length; i += 1)
+                wanted[reads[i] ?? 0] = 1;
+        }
+    }
+}
+function sameWrites(deps, a, b) {
+    const left = writesOf(deps, a);
+    const right = writesOf(deps, b);
+    if (left.length !== right.length)
+        return false;
+    for (let i = 0; i < left.length; i += 1)
+        if (left[i] !== right[i])
+            return false;
+    return true;
+}
+/**
+ * Group the live nodes of a frame into passes, and answer how many of `out` were filled.
+ *
+ * `live` is what must survive the frame, and only its first `liveCount` entries are read — so a
+ * caller can keep one typed array and a count rather than build a list. `scratch` is the working
+ * set; a caller that passes none gets one made for the call, which is what a test wants and what a
+ * frame must not do.
+ */
+export function scheduleGraph(deps, count, live, ordered, out, scratch = createGraphScratch(count, 1), liveCount = live.length) {
+    fitScratch(scratch, deps, count);
+    markLive(deps, count, live, liveCount, scratch);
+    const keep = scratch.keep;
+    let passes = 0;
+    let at = 0;
+    while (at < count) {
+        if (keep[at] === 0) {
+            at += 1;
+            continue;
+        }
+        const isOrdered = ordered[at] === 1;
+        let end = at + 1;
+        while (end < count && keep[end] === 1) {
+            const nextOrdered = ordered[end] === 1;
+            if (isOrdered !== nextOrdered)
+                break;
+            if (isOrdered && !sameWrites(deps, at, end))
+                break;
+            end += 1;
+        }
+        const pass = out[passes];
+        if (pass === undefined)
+            return passes;
+        pass.first = at;
+        pass.count = end - at;
+        pass.ordered = isOrdered;
+        passes += 1;
+        at = end;
+    }
+    return passes;
+}

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

@@ -16,3 +16,18 @@ export { NODE_STRIDE, createArena, nodeCount, nodeMatrix, nodeReads, nodeState,
 export type { ScheduledPass } from './schedule.ts';
 export { schedule } from './schedule.ts';
 export { keptNodes, scratchFor } from './replay.ts';
+export type { VirtualBufferDesc, VirtualDesc, VirtualTable, VirtualTextureDesc, } from './virtual.ts';
+export { createVirtualTable, declareVirtual, resetVirtualTable, virtualBytes, virtualCount, virtualKind, } from './virtual.ts';
+export type { Deps } from './deps.ts';
+export { createDeps, depsNodeCount, readsOf, recordDeps, recordMaskDeps, resetDeps, writesOf, } from './deps.ts';
+export type { Lifetimes } from './lifetime.ts';
+export { computeLifetimes, createLifetimes, firstWrite, lastRead } from './lifetime.ts';
+export type { AliasPlan } from './alias.ts';
+export { createAliasPlan, offsetOf, planAliases } from './alias.ts';
+export type { GraphPass, GraphScratch } from './graphSchedule.ts';
+export { createGraphPasses, createGraphScratch, scheduleGraph } from './graphSchedule.ts';
+export type { FlushSchedule } from './flushGraph.ts';
+export { createFlushSchedule, scheduleFlush } from './flushGraph.ts';
+export { validateGraph } from './validate.ts';
+export type { PassTimings } from './passTimings.ts';
+export { createPassTimings, passLabel, passMs, recordPassLabel, recordPassSample, resetPassTimings, } from './passTimings.ts';

package/dist/render/frame/index.js

@@ -2,3 +2,11 @@ export { FRAME_RESOURCES, RESOURCE_COUNT, maskOf, namesIn, resourceBit } from '.
 export { NODE_STRIDE, createArena, nodeCount, nodeMatrix, nodeReads, nodeState, nodeVerb, nodeWrites, recordNode, resetArena, } from './arena.js';
 export { schedule } from './schedule.js';
 export { keptNodes, scratchFor } from './replay.js';
+export { createVirtualTable, declareVirtual, resetVirtualTable, virtualBytes, virtualCount, virtualKind, } from './virtual.js';
+export { createDeps, depsNodeCount, readsOf, recordDeps, recordMaskDeps, resetDeps, writesOf, } from './deps.js';
+export { computeLifetimes, createLifetimes, firstWrite, lastRead } from './lifetime.js';
+export { createAliasPlan, offsetOf, planAliases } from './alias.js';
+export { createGraphPasses, createGraphScratch, scheduleGraph } from './graphSchedule.js';
+export { createFlushSchedule, scheduleFlush } from './flushGraph.js';
+export { validateGraph } from './validate.js';
+export { createPassTimings, passLabel, passMs, recordPassLabel, recordPassSample, resetPassTimings, } from './passTimings.js';

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

@@ -0,0 +1,24 @@
+/**
+ * When each transient resource is first written and last read.
+ *
+ * Two numbers per identifier and one pass over the nodes, which is all the aliasing allocator
+ * needs and is deliberately less than a general dependency graph would compute. There is no
+ * topological sort here because there is no reordering here: the node order is the caller's,
+ * exactly as `schedule.ts` requires for the fixed path and for the same reason — blending and
+ * depth make *after* different from *before*.
+ *
+ * **A resource written and never read still has a lifetime**, ending at the node that writes
+ * it. It has to: memory it is being written into cannot be handed to something else at the same
+ * moment. Reporting an empty lifetime there is the bug this module's third test exists to catch.
+ */
+import type { Deps } from './deps.ts';
+export interface Lifetimes {
+    /** Node index of the first write per identifier, or -1. */
+    first: Int32Array;
+    /** Node index of the last read per identifier, or the first write when nothing reads it. */
+    last: Int32Array;
+}
+export declare function createLifetimes(capacity: number): Lifetimes;
+export declare function computeLifetimes(deps: Deps, count: number, out: Lifetimes): void;
+export declare function firstWrite(out: Lifetimes, id: number): number;
+export declare function lastRead(out: Lifetimes, id: number): number;

package/dist/render/frame/lifetime.js

@@ -0,0 +1,36 @@
+import { readsOf, writesOf } from './deps.js';
+export function createLifetimes(capacity) {
+    return { first: new Int32Array(capacity), last: new Int32Array(capacity) };
+}
+export function computeLifetimes(deps, count, out) {
+    out.first.fill(-1);
+    out.last.fill(-1);
+    for (let node = 0; node < count; node += 1) {
+        const writes = writesOf(deps, node);
+        for (let i = 0; i < writes.length; i += 1) {
+            const id = writes[i] ?? 0;
+            if (out.first[id] === -1) {
+                out.first[id] = node;
+                out.last[id] = node;
+            }
+        }
+        /*
+         * Reads are folded in after this node's writes, so a node that reads and writes the same
+         * identifier extends the lifetime rather than starting a second one. A read of something
+         * nothing has written is ignored here and refused by `validate.ts`, which is where a
+         * malformed frame belongs.
+         */
+        const reads = readsOf(deps, node);
+        for (let i = 0; i < reads.length; i += 1) {
+            const id = reads[i] ?? 0;
+            if (out.first[id] !== -1)
+                out.last[id] = node;
+        }
+    }
+}
+export function firstWrite(out, id) {
+    return out.first[id] ?? -1;
+}
+export function lastRead(out, id) {
+    return out.last[id] ?? -1;
+}

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

@@ -0,0 +1,42 @@
+/**
+ * Where a frame's milliseconds went, one row per graph pass.
+ *
+ * **Not a widening of `gpuTimer.ts`, and that is deliberate.** That class is a WebGL2 query pool
+ * over `TIME_ELAPSED_EXT`, partitioning a frame into three fixed brackets — shadows, reflection,
+ * rest — and it is right for what it measures. A graph pass is not one of three brackets: there
+ * are as many as the frame composes, they are named at record time, and on WebGPU the sample
+ * comes from a timestamp query rather than an elapsed-time extension. Two different measurements
+ * with two different shapes; widening one into the other would leave a class that does neither
+ * well.
+ *
+ * **What it does inherit from that class is its best rule: unmeasured is not zero.** A device
+ * without timestamp queries, or a pass that ran no work, must not read as "took no time" — a
+ * profiler that cannot distinguish those two is a profiler that sends somebody optimising a pass
+ * that never ran. `passMs` returns null for unmeasured and a number for measured, including zero.
+ *
+ * **Labels persist and timings reset.** A pass that did nothing this frame keeps its name and
+ * reports unmeasured, so the profiler's rows stop jumping about as quality settings toggle
+ * passes on and off — which is exactly when somebody is reading it.
+ */
+export interface PassTimings {
+    /** Accumulated milliseconds per pass for the current frame. */
+    ms: Float64Array;
+    /** Whether each pass received a sample this frame. */
+    measured: Uint8Array;
+    /** Name per pass, kept across frames. */
+    labels: string[];
+}
+export declare function createPassTimings(capacity: number): PassTimings;
+/** Start a frame: timings go, labels stay. See the header for why they are treated differently. */
+export declare function resetPassTimings(timings: PassTimings): void;
+/**
+ * Add one sample to a pass.
+ *
+ * Accumulates rather than replaces, because a pass may be sampled more than once in a frame — a
+ * shadow pass runs per cascade — and the row a reader wants is what that pass cost altogether.
+ */
+export declare function recordPassSample(timings: PassTimings, pass: number, ms: number): void;
+export declare function recordPassLabel(timings: PassTimings, pass: number, label: string): void;
+/** Milliseconds this pass cost, or null where nothing measured it. Null is not zero. */
+export declare function passMs(timings: PassTimings, pass: number): number | null;
+export declare function passLabel(timings: PassTimings, pass: number): string;

package/dist/render/frame/passTimings.js

@@ -0,0 +1,38 @@
+export function createPassTimings(capacity) {
+    return {
+        ms: new Float64Array(capacity),
+        measured: new Uint8Array(capacity),
+        labels: Array.from({ length: capacity }, () => ''),
+    };
+}
+/** Start a frame: timings go, labels stay. See the header for why they are treated differently. */
+export function resetPassTimings(timings) {
+    timings.ms.fill(0);
+    timings.measured.fill(0);
+}
+/**
+ * Add one sample to a pass.
+ *
+ * Accumulates rather than replaces, because a pass may be sampled more than once in a frame — a
+ * shadow pass runs per cascade — and the row a reader wants is what that pass cost altogether.
+ */
+export function recordPassSample(timings, pass, ms) {
+    if (pass < 0 || pass >= timings.ms.length)
+        return;
+    timings.ms[pass] = (timings.ms[pass] ?? 0) + ms;
+    timings.measured[pass] = 1;
+}
+export function recordPassLabel(timings, pass, label) {
+    if (pass < 0 || pass >= timings.labels.length)
+        return;
+    timings.labels[pass] = label;
+}
+/** Milliseconds this pass cost, or null where nothing measured it. Null is not zero. */
+export function passMs(timings, pass) {
+    if (pass < 0 || pass >= timings.ms.length)
+        return null;
+    return timings.measured[pass] === 1 ? (timings.ms[pass] ?? 0) : null;
+}
+export function passLabel(timings, pass) {
+    return timings.labels[pass] ?? '';
+}

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

@@ -0,0 +1,15 @@
+/**
+ * Whether a recorded frame is one that can be executed.
+ *
+ * One rule: a node may read an identifier only if something wrote it earlier in this frame, or
+ * it was imported into the frame from outside. That catches the whole family of defects a fixed
+ * resource table caught by construction — a pass sampling an attachment the quality settings
+ * disabled, a pass reading a mip chain built only when a different feature is on — and which
+ * identifiers do not catch by construction, because any integer is a plausible identifier.
+ *
+ * Returns a message rather than throwing. The renderer decides whether a malformed frame is a
+ * developer-time assertion or a dropped frame, and a validator that throws has made that
+ * decision for it.
+ */
+import type { Deps } from './deps.ts';
+export declare function validateGraph(deps: Deps, count: number, imported: readonly number[]): string | null;

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