@driftengine/core 3.63.0 → 4.0.0

package/dist/render/recon/resolve.js

@@ -0,0 +1,313 @@
+/**
+ * DriftTR's resolve: a jittered frame at the render size into a picture at the output size.
+ *
+ * **This is the reference the compute shader is held to**, operation for operation, and it is built
+ * from the pieces before it: the jitter taken out of where the current frame was observed
+ * (`motionVectors.ts`), the history read bicubically where the surface was (`reproject.ts`), clipped
+ * to the render neighbourhood's variance box in YCoCg (`clamp.ts`), weighted by whether it is the
+ * same surface (`disocclusion.ts`), accumulated, and then sharpened into the picture that is shown.
+ *
+ * **Per output pixel, in this order:**
+ *
+ * 1. The render texels around where this frame observed the output pixel each land, unjittered, some
+ *    distance from its centre. **Each contributes by that distance** — a Gaussian over output pixels —
+ *    and the sum of their weights is how much this frame knows about the pixel. This is what makes the
+ *    accumulation converge on the output-size picture rather than on the render's own, blurred to its
+ *    texel size: an interpolated read of the render, averaged over every jitter, is exactly that blur.
+ * 2. The same texels bound the history, and give the **nearest depth**, whose texel's motion is the one
+ *    taken — the dilation every temporal upscaler uses, because an edge's own motion belongs to the
+ *    nearer of the two surfaces meeting there. The centre texel wins a tie.
+ * 3. That texel's motion is a drawn object's where the motion target flags one, carrying the object's
+ *    previous view depth in its third channel; otherwise it is the camera's, through the surface's
+ *    world position.
+ * 4. Where the surface was is read from the history — its colour and the weight it had gathered — and
+ *    last frame's depth there says whether it is the same surface; the two frames' normals, from their
+ *    depths, catch thin geometry. The disocclusion scales the history's weight.
+ * 5. The history is clipped to the box, its weight capped so a tenth of each frame is always new, and
+ *    the two are mixed by their weights. Where the pixel has gathered less than one sample's worth,
+ *    the render read bicubically fills the gap. The history keeps colour and weight; the picture shown
+ *    is it sharpened.
+ *
+ * **Conventions.** Images are rows from `v = 0` upward. Depths are clip depths in the matrices'
+ * convention, OpenGL's here — the nearest is the smallest — and the renderer converts its reversed
+ * buffer before a sample reaches this arithmetic, as the temporal resolve already does.
+ */
+import { clipToBox, rgbToYCoCg, varianceBox, yCoCgToRgb } from './clamp.js';
+import { disocclusionWeight, normalFromPositions, worldPositionFromDepth } from './disocclusion.js';
+import { sampleBilinear, sampleHistoryBicubic5 } from './reproject.js';
+/**
+ * A tenth of each frame kept, as the temporal resolve keeps; a box of a standard deviation and a
+ * quarter; a light sharpen. At two thirds of the output a side.
+ */
+export const DEFAULT_RECON_QUALITY = {
+    ratio: 1.5,
+    alpha: 0.1,
+    sharpen: 0.25,
+    clampGamma: 1.25,
+};
+/**
+ * The current colour and the clipped history mixed: the history's share is `weight × (1 − alpha)`.
+ *
+ * A weight of zero is the current colour exactly — no history — and a weight of one with an alpha of
+ * zero is the history exactly. A convex mixture, so repeated accumulation of one colour converges to
+ * it and never overshoots.
+ */
+export function accumulate(out, current, history, weight, alpha) {
+    const kept = Math.min(1, Math.max(0, weight)) * (1 - Math.min(1, Math.max(0, alpha)));
+    for (let c = 0; c < 3; c += 1) {
+        out[c] = current[c] * (1 - kept) + history[c] * kept;
+    }
+}
+/**
+ * The centre pushed away from its four neighbours' mean by `amount`, and **held inside the range of
+ * the five** — the halo a plain unsharp mask draws beside every edge is a value outside that range.
+ * A flat region has no difference to push, so it is unchanged.
+ */
+export function sharpen(out, centre, neighbours, amount) {
+    for (let c = 0; c < 3; c += 1) {
+        const middle = centre[c];
+        let low = middle;
+        let high = middle;
+        let sum = 0;
+        for (let n = 0; n < 4; n += 1) {
+            const value = neighbours[n * 3 + c];
+            sum += value;
+            low = Math.min(low, value);
+            high = Math.max(high, value);
+        }
+        const pushed = middle + amount * (middle - sum / 4);
+        out[c] = Math.min(high, Math.max(low, pushed));
+    }
+}
+/**
+ * How far a render sample's contribution reaches, in output pixels: a Gaussian's standard deviation.
+ *
+ * Just under half a pixel, so a sample on a pixel's centre counts fully and one a pixel away counts a
+ * tenth — the width a reconstruction filter needs to avoid both aliasing and a soft picture.
+ */
+export const SAMPLE_SPREAD = 0.47;
+/** A render sample's weight at `(dx, dy)` output pixels from an output pixel's centre. */
+export function reconstructionWeight(dx, dy) {
+    return Math.exp(-(dx * dx + dy * dy) / (2 * SAMPLE_SPREAD * SAMPLE_SPREAD));
+}
+/**
+ * How much gathered weight counts as knowing a pixel. Below it, the render's bicubic read fills in —
+ * which is every pixel on the first frame at a large ratio, where the nearest sample can be most of a
+ * pixel away.
+ */
+export const CONFIDENT_WEIGHT = 1;
+const SAMPLE = new Float32Array(3);
+const GATHERED = new Float64Array(3);
+const HISTORY = new Float32Array(4);
+const NEIGHBOURS = new Float64Array(27);
+const LOW = new Float64Array(3);
+const HIGH = new Float64Array(3);
+const YCOCG = new Float64Array(3);
+const CLIPPED = new Float64Array(3);
+const MIXED = new Float64Array(3);
+const WORLD = new Float64Array(3);
+const RIGHT = new Float64Array(3);
+const UP = new Float64Array(3);
+const NORMAL = new Float64Array(3);
+const PREVIOUS_NORMAL = new Float64Array(3);
+const CLIP = new Float64Array(4);
+function clampTexel(value, size) {
+    return value < 0 ? 0 : value >= size ? size - 1 : value;
+}
+/** A texel's world position from a depth image, at its unjittered uv. Returns the view depth, or 0. */
+function worldAt(depths, inverse, jitter, width, height, x, y, out) {
+    const tx = clampTexel(x, width);
+    const ty = clampTexel(y, height);
+    const u = (tx + 0.5 - jitter[0]) / width;
+    const v = (ty + 0.5 - jitter[1]) / height;
+    const z = depths[ty * width + tx];
+    if (!worldPositionFromDepth(inverse, u, v, z, out))
+        return 0;
+    /* The view depth is the clip w, which the inverse's w is the reciprocal of. */
+    const m = inverse;
+    const w = m[3] * (u * 2 - 1) +
+        m[7] * (v * 2 - 1) +
+        m[11] * z +
+        m[15];
+    return 1 / w;
+}
+/** The world normal at a texel, from its depth and its right and upper neighbours'. */
+function normalAt(depths, inverse, jitter, eye, width, height, x, y, out) {
+    if (worldAt(depths, inverse, jitter, width, height, x, y, WORLD) <= 0)
+        return false;
+    /* The neighbour on the inside of the border, so the edge texels have a normal too. */
+    const dx = x + 1 < width ? 1 : -1;
+    const dy = y + 1 < height ? 1 : -1;
+    if (worldAt(depths, inverse, jitter, width, height, x + dx, y, RIGHT) <= 0)
+        return false;
+    if (worldAt(depths, inverse, jitter, width, height, x, y + dy, UP) <= 0)
+        return false;
+    return normalFromPositions(WORLD, RIGHT, UP, eye, out);
+}
+/**
+ * The weight a pixel's history still deserves this frame: none on the first frame, where the surface
+ * was behind last frame's eye or off its picture, and otherwise what it gathered, scaled by whether it
+ * is the same surface. Reads `HISTORY`; writes the history's colour there.
+ */
+function historyWeight(frame, u, v, dx, dy) {
+    if (!frame.hasHistory)
+        return 0;
+    const rw = frame.renderWidth;
+    const rh = frame.renderHeight;
+    const flagAt = (dy * rw + dx) * 4;
+    let mu;
+    let mv;
+    let expected;
+    if (frame.motion[flagAt + 3] > 0.5) {
+        mu = frame.motion[flagAt];
+        mv = frame.motion[flagAt + 1];
+        expected = frame.motion[flagAt + 2];
+    }
+    else {
+        if (worldAt(frame.depth, frame.inverseViewProj, frame.jitter, rw, rh, dx, dy, WORLD) <= 0) {
+            return 0;
+        }
+        const m = frame.previousViewProj;
+        for (let r = 0; r < 4; r += 1) {
+            CLIP[r] =
+                m[r] * WORLD[0] +
+                    m[4 + r] * WORLD[1] +
+                    m[8 + r] * WORLD[2] +
+                    m[12 + r];
+        }
+        /*
+         * A surface behind last frame's eye has a w that is not positive: the disocclusion trusts no
+         * such depth, so it needs no refusal of its own here.
+         */
+        expected = CLIP[3];
+        const du = (dx + 0.5 - frame.jitter[0]) / rw;
+        const dv = (dy + 0.5 - frame.jitter[1]) / rh;
+        mu = (CLIP[0] / expected) * 0.5 + 0.5 - du;
+        mv = (CLIP[1] / expected) * 0.5 + 0.5 - dv;
+    }
+    const pu = u + mu;
+    const pv = v + mv;
+    if (!(pu >= 0 && pu <= 1 && pv >= 0 && pv <= 1))
+        return 0;
+    sampleHistoryBicubic5(frame.history, pu * frame.outputWidth - 0.5, pv * frame.outputHeight - 0.5, frame.outputWidth, frame.outputHeight, 4, HISTORY);
+    const px = clampTexel(Math.round(pu * rw + frame.previousJitter[0] - 0.5), rw);
+    const py = clampTexel(Math.round(pv * rh + frame.previousJitter[1] - 0.5), rh);
+    const held = worldAt(frame.previousDepth, frame.previousInverseViewProj, frame.previousJitter, rw, rh, px, py, RIGHT);
+    let normalDot = 1;
+    if (normalAt(frame.depth, frame.inverseViewProj, frame.jitter, frame.eye, rw, rh, dx, dy, NORMAL) &&
+        normalAt(frame.previousDepth, frame.previousInverseViewProj, frame.previousJitter, frame.previousEye, rw, rh, px, py, PREVIOUS_NORMAL)) {
+        normalDot =
+            NORMAL[0] * PREVIOUS_NORMAL[0] +
+                NORMAL[1] * PREVIOUS_NORMAL[1] +
+                NORMAL[2] * PREVIOUS_NORMAL[2];
+    }
+    const trust = disocclusionWeight(expected, held, Math.hypot(mu, mv), normalDot, frame.disocclusion);
+    return HISTORY[3] * trust;
+}
+/**
+ * One output pixel: the history's next colour, before sharpening, and the weight it has gathered —
+ * four values into `out`.
+ */
+export function resolvePixel(frame, ox, oy, out) {
+    const rw = frame.renderWidth;
+    const rh = frame.renderHeight;
+    const ow = frame.outputWidth;
+    const oh = frame.outputHeight;
+    const u = (ox + 0.5) / ow;
+    const v = (oy + 0.5) / oh;
+    const jx = frame.jitter[0];
+    const jy = frame.jitter[1];
+    /* Where this frame observed the pixel, and the render read there for the gaps. */
+    const rx = u * rw + jx - 0.5;
+    const ry = v * rh + jy - 0.5;
+    sampleHistoryBicubic5(frame.scene, rx, ry, rw, rh, 3, SAMPLE);
+    const nx = clampTexel(Math.round(rx), rw);
+    const ny = clampTexel(Math.round(ry), rh);
+    /* 1 and 2. Each texel around: its weight, its colour in the box, and its depth. */
+    let nearest = frame.depth[ny * rw + nx];
+    let dx = nx;
+    let dy = ny;
+    let gathered = 0;
+    GATHERED.fill(0);
+    for (let j = -1; j <= 1; j += 1) {
+        for (let i = -1; i <= 1; i += 1) {
+            const tx = clampTexel(nx + i, rw);
+            const ty = clampTexel(ny + j, rh);
+            const at = (ty * rw + tx) * 3;
+            const r = frame.scene[at];
+            const g = frame.scene[at + 1];
+            const b = frame.scene[at + 2];
+            const weight = reconstructionWeight(((tx + 0.5 - jx) / rw) * ow - (ox + 0.5), ((ty + 0.5 - jy) / rh) * oh - (oy + 0.5));
+            gathered += weight;
+            GATHERED[0] = GATHERED[0] + r * weight;
+            GATHERED[1] = GATHERED[1] + g * weight;
+            GATHERED[2] = GATHERED[2] + b * weight;
+            rgbToYCoCg(YCOCG, r, g, b);
+            NEIGHBOURS.set(YCOCG, ((j + 1) * 3 + (i + 1)) * 3);
+            const z = frame.depth[ty * rw + tx];
+            if (z < nearest) {
+                nearest = z;
+                dx = tx;
+                dy = ty;
+            }
+        }
+    }
+    varianceBox(NEIGHBOURS, 9, frame.quality.clampGamma, LOW, HIGH);
+    for (let c = 0; c < 3; c += 1)
+        GATHERED[c] = GATHERED[c] / gathered;
+    /* 3 and 4. The history, and the weight it still deserves. */
+    const cap = (1 - frame.quality.alpha) / frame.quality.alpha;
+    const kept = Math.min(cap, historyWeight(frame, u, v, dx, dy));
+    /* 5. Clipped, mixed by weight, and the gaps filled from the render. */
+    const total = kept + gathered;
+    if (kept > 0) {
+        rgbToYCoCg(YCOCG, HISTORY[0], HISTORY[1], HISTORY[2]);
+        clipToBox(CLIPPED, YCOCG, LOW, HIGH);
+        yCoCgToRgb(YCOCG, CLIPPED[0], CLIPPED[1], CLIPPED[2]);
+        accumulate(MIXED, GATHERED, YCOCG, 1, gathered / total);
+    }
+    else {
+        MIXED.set(GATHERED);
+    }
+    const known = Math.min(1, total / CONFIDENT_WEIGHT);
+    for (let c = 0; c < 3; c += 1) {
+        out[c] = SAMPLE[c] * (1 - known) + MIXED[c] * known;
+    }
+    out[3] = total;
+}
+const TAP = new Float32Array(4);
+const CENTRE = new Float32Array(4);
+const AROUND = new Float32Array(12);
+const SHOWN = new Float32Array(3);
+const OFFSETS = [
+    [-1, 0],
+    [1, 0],
+    [0, -1],
+    [0, 1],
+];
+/**
+ * The whole frame: the next history into `history`, four floats a pixel, and the picture shown into
+ * `shown`, three — the history sharpened against the four direct neighbours it has just been given.
+ */
+export function resolveFrame(frame, history, shown) {
+    const ow = frame.outputWidth;
+    const oh = frame.outputHeight;
+    for (let y = 0; y < oh; y += 1) {
+        for (let x = 0; x < ow; x += 1) {
+            resolvePixel(frame, x, y, TAP);
+            history.set(TAP, (y * ow + x) * 4);
+        }
+    }
+    for (let y = 0; y < oh; y += 1) {
+        for (let x = 0; x < ow; x += 1) {
+            sampleBilinear(history, x, y, ow, oh, 4, CENTRE);
+            for (let n = 0; n < 4; n += 1) {
+                const offset = OFFSETS[n];
+                sampleBilinear(history, x + offset[0], y + offset[1], ow, oh, 4, TAP);
+                AROUND.set(TAP.subarray(0, 3), n * 3);
+            }
+            sharpen(SHOWN, CENTRE, AROUND, frame.quality.sharpen);
+            shown.set(SHOWN, (y * ow + x) * 3);
+        }
+    }
+}

package/dist/render/recon/tier.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Which reconstruction tier a request gets.
+ *
+ * **Tier 0, DriftTR, is analytic** and runs wherever compute does. **Tier 2, DriftFG**, generates
+ * frames between rendered ones, over tier 0.
+ *
+ * **Tier 1, DriftNeural, was withdrawn before 4.0.0 by the spec's own stop condition**, and a request
+ * for it is tier 0 on every device. Measured (the plan's Tasks 8 and 9): a network refining the
+ * finished frame averaged +0.01 dB on scenes it had not seen, and lost the one clear difference in a
+ * blind comparison. The analytic tier was designed to stand without it, so this is the degradation
+ * the design was built around rather than a gap in it.
+ *
+ * **Tier 2 used to fall to tier 0 wherever tier 1 could not run**, so that a device lacking half
+ * precision could not choose frame generation over the analytic tier for a consumer who had asked
+ * for the learned base. With no learned base there is nothing to choose between, and a request for
+ * tier 2 is a request for exactly that. **What would make this wrong** is a learned tier that
+ * measures better — a network inside the resolve rather than after it — which brings the rule back.
+ */
+import type { GpuCapabilities } from '../deviceFeatures.ts';
+export type ReconTier = 0 | 1 | 2;
+/** Whether this device can reconstruct at all: the tiers are compute dispatches. */
+export declare function reconstructionSupported(caps: GpuCapabilities): boolean;
+/** The tier a request gets, wherever `reconstructionSupported` says reconstruction runs at all. */
+export declare function selectTier(requested: ReconTier): ReconTier;

package/dist/render/recon/tier.js

@@ -0,0 +1,8 @@
+/** Whether this device can reconstruct at all: the tiers are compute dispatches. */
+export function reconstructionSupported(caps) {
+    return caps.indirect;
+}
+/** The tier a request gets, wherever `reconstructionSupported` says reconstruction runs at all. */
+export function selectTier(requested) {
+    return requested === 1 ? 0 : requested;
+}

package/dist/render/reflectionProbe.d.ts

@@ -1,6 +1,32 @@
 /** A cubemap of the scene from one point, for surfaces that mirror the room they stand in. */
 import type { Vec3 } from '../math/color.ts';
 import { Camera } from './camera.ts';
+/**
+ * The same view-projection with clip y negated, which is what rendering into a cube face wants.
+ *
+ * **A cubemap face's rows run downward and a GL framebuffer's run upward.** `framebufferTexture2D`
+ * on `TEXTURE_CUBE_MAP_POSITIVE_X + face` makes framebuffer row 0 the face's texel row 0, and the
+ * face's own direction mapping — the specification's `sc`, `tc`, `ma` table — says texel row 0 is
+ * the +Y end. A camera aimed along the face with its up at +Y puts +Y at the top of the render
+ * area, which in GL is the *last* row, so the face is stored upside down and every reflection and
+ * every irradiance sample taken from it has up and down the wrong way round.
+ *
+ * **Almost nothing can see it**, which is why it stood until 2026-09-16. A face that is flat, or
+ * chequered, or bright across its whole width is symmetric under a vertical flip, and so was every
+ * room this repository could bake into a probe. `showroom` is not: its walls are a lit cove and
+ * ceiling above and a dark floor below, and its ceiling came out 22 levels of 255 from what the
+ * other backend drew, with its floor 7 the other way and its walls exactly equal — a difference
+ * that reverses between a surface facing up and one facing down and leaves a horizontal one alone
+ * is a probe with its rows the wrong way up. `demo/dev/ibl.html?band=1` is the room that shows it
+ * directly: four side walls bright above and dark below, and without this correction the spheres
+ * in it are lit from underneath.
+ *
+ * **The winding goes with it.** Negating one clip axis mirrors every triangle, so a caller has to
+ * flip the front face for the duration or the room turns inside out — `bakeProbe` does.
+ *
+ * Writing into the source is allowed: each output element reads only the element at its own index.
+ */
+export declare function cubeFaceProjection(out: Float32Array, viewProj: ArrayLike<number>): Float32Array;
 /**
  * What a bake is for, and specifically whether it also replaces the scene's diffuse ambient.
  *

package/dist/render/reflectionProbe.js

@@ -1,6 +1,39 @@
 /** A cubemap of the scene from one point, for surfaces that mirror the room they stand in. */
 import { Camera } from './camera.js';
 import { roughnessForLevel } from './prefilterEnvMap.js';
+/**
+ * The same view-projection with clip y negated, which is what rendering into a cube face wants.
+ *
+ * **A cubemap face's rows run downward and a GL framebuffer's run upward.** `framebufferTexture2D`
+ * on `TEXTURE_CUBE_MAP_POSITIVE_X + face` makes framebuffer row 0 the face's texel row 0, and the
+ * face's own direction mapping — the specification's `sc`, `tc`, `ma` table — says texel row 0 is
+ * the +Y end. A camera aimed along the face with its up at +Y puts +Y at the top of the render
+ * area, which in GL is the *last* row, so the face is stored upside down and every reflection and
+ * every irradiance sample taken from it has up and down the wrong way round.
+ *
+ * **Almost nothing can see it**, which is why it stood until 2026-09-16. A face that is flat, or
+ * chequered, or bright across its whole width is symmetric under a vertical flip, and so was every
+ * room this repository could bake into a probe. `showroom` is not: its walls are a lit cove and
+ * ceiling above and a dark floor below, and its ceiling came out 22 levels of 255 from what the
+ * other backend drew, with its floor 7 the other way and its walls exactly equal — a difference
+ * that reverses between a surface facing up and one facing down and leaves a horizontal one alone
+ * is a probe with its rows the wrong way up. `demo/dev/ibl.html?band=1` is the room that shows it
+ * directly: four side walls bright above and dark below, and without this correction the spheres
+ * in it are lit from underneath.
+ *
+ * **The winding goes with it.** Negating one clip axis mirrors every triangle, so a caller has to
+ * flip the front face for the duration or the room turns inside out — `bakeProbe` does.
+ *
+ * Writing into the source is allowed: each output element reads only the element at its own index.
+ */
+export function cubeFaceProjection(out, viewProj) {
+    for (let i = 0; i < 16; i++) {
+        const value = viewProj[i];
+        /* Row one of a column-major 4x4 is indices 1, 5, 9, 13 — the row that produces clip y. */
+        out[i] = i % 4 === 1 ? -value : value;
+    }
+    return out;
+}
 /**
  * The six directions of a cubemap, as the yaw and pitch a `Camera` aims with.
  *

package/dist/render/renderQuality.d.ts

@@ -319,6 +319,23 @@ export interface RenderQuality {
      * rather than to a release. `?graph=0` turns it off in one reload.
      */
     readonly frameGraph: boolean;
+    /**
+     * Schedule each flush through the identifier graph rather than through masks. WebGPU only.
+     *
+     * **Off, and nothing a consumer can see changes with it on.** The graph `frameGraph` records is
+     * the same either way; this chooses which scheduler groups it into passes and derives what each
+     * attachment loads and stores. The mask scheduler is exactly right for a frame whose composition
+     * is fixed, and the identifier graph is what can also express a frame whose composition is not —
+     * the second pipeline's — so this is the switch that says the second is a generalisation of the
+     * first: the eighteen scenes the harness walks are pixel-identical with it on, measured
+     * 2026-09-17 — `showroom` in six captures a side, because it varies between runs of one build
+     * whatever this says. `frame/flushGraph.ts` says where the two can part, and why no flush the
+     * renderer makes reaches it.
+     *
+     * Ignored where `frameGraph` is off, which records nothing to schedule, and on WebGL2, which has no
+     * verb-level graph. `?idgraph=1` turns it on in one reload.
+     */
+    readonly identifierGraph: boolean;
     /**
      * Light the world from a froxel table rather than from a fixed set of uniform-array slots.
      *
@@ -485,6 +502,53 @@ export interface RenderQuality {
      * it be identical on both backends and asserted without one.
      */
     readonly occlusionCulling: number;
+    /**
+     * Reconstruction: how many output pixels the renderer draws for each render pixel, each axis.
+     * **0 is off and is the default.**
+     *
+     * On, the scene and everything that reads it before the resolve are drawn at
+     * `ceil(output / ratio)` and a compute dispatch reconstructs the output-size picture from this
+     * frame and the accumulated history — DriftTR, `render/recon/`. What it saves is `1 - 1/r²` of
+     * the scene's fragment work, which at 1.5 is 56%; what it costs is one motion target and one
+     * previous depth at render size, two output-size histories and one dispatch.
+     *
+     * **Off is byte-for-byte what the renderer does today**, which is what the published scenes are
+     * gated at. WebGPU only: WebGL2 has no compute stage, and it keeps the temporal resolve at native
+     * size, which is what it does now.
+     *
+     * **Zero is off rather than one, because one is a thing somebody might mean** — the resolve at
+     * the output size with no upscaling, which is a temporal antialiaser with a better neighbourhood
+     * rule than `temporalAa`'s. A sentinel that collided with it would make that unaskable.
+     *
+     * The range is 1.3 to 2 and a value inside it is clamped to the end it is nearest. Below 1.3 the
+     * render saves less than a third of the fragment work and the resolve's own cost eats it; above 2
+     * the render is a quarter of the output and no reconstruction holds an edge through that. A
+     * negative number is off, not a clamp to the bottom: it cannot mean "a little".
+     *
+     * `?recon=` is how it gets A/B'd in one reload.
+     */
+    readonly reconstruction: number;
+    /**
+     * Light a scene from what bounces, rather than from what was baked. **Off by default.**
+     *
+     * On, the probe grid the shading already samples is filled by tracing `render/gi/`'s three-level
+     * chain — the world distance field, and behind it the probes themselves, which is what makes the
+     * solution converge on several bounces over a few refreshes. Off, the probes hold one bounce of
+     * the rasterised scene, which is what this engine has always baked.
+     *
+     * **A switch rather than a strength.** Half an indirect bounce is not a thing to ask for: a probe
+     * either holds what the chain traced or it holds what the cube held, and mixing them is two
+     * solutions averaged rather than one at a lower quality. What is adjustable is how many probes
+     * refresh a frame, and that belongs to the grid.
+     *
+     * **WebGPU only**, and refused in words elsewhere — `INDIRECT_LIGHT_WEBGL2_REFUSAL`. A probe is a
+     * few hundred rays and that is a compute dispatch; WebGL2 has no stage for one, and the
+     * alternative — the two backends lighting one scene differently — is the disagreement the
+     * published pixel gate exists to prevent.
+     *
+     * `?indirect=1` turns it on in one reload.
+     */
+    readonly indirectLight: boolean;
     /**
      * Ambient occlusion, 0 to 1. Off by default.
      *
@@ -696,4 +760,9 @@ export declare const DIRECTIONAL_SHADOW_FADE_START = 0.65;
  */
 export declare const DEFAULT_RENDER_QUALITY: Readonly<RenderQuality>;
 /** Resolve and validate once at renderer construction, never in a hot path. */
+/** The narrowest and widest ratio a reconstruction runs at; outside them a caller means the end. */
+export declare const RECONSTRUCTION_RANGE: {
+    readonly least: 1.3;
+    readonly most: 2;
+};
 export declare function resolveRenderQuality(options?: RenderQualityOptions): Readonly<RenderQuality>;

package/dist/render/renderQuality.js

@@ -81,6 +81,8 @@ export const DEFAULT_RENDER_QUALITY = Object.freeze({
     temporalAa: false,
     orderIndependent: false,
     depthOfField: 0,
+    reconstruction: 0,
+    indirectLight: false,
     occlusionCulling: 0,
     ambientOcclusion: 0,
     nightEmissive: false,
@@ -158,6 +160,7 @@ export const DEFAULT_RENDER_QUALITY = Object.freeze({
     discardResolvedAttachments: true,
     deferFramePass: true,
     frameGraph: true,
+    identifierGraph: false,
     clusteredLights: false,
     cullDraws: false,
     /*
@@ -168,6 +171,21 @@ export const DEFAULT_RENDER_QUALITY = Object.freeze({
     gpuTiming: false,
 });
 /** Resolve and validate once at renderer construction, never in a hot path. */
+/** The narrowest and widest ratio a reconstruction runs at; outside them a caller means the end. */
+export const RECONSTRUCTION_RANGE = { least: 1.3, most: 2 };
+/**
+ * Off, or a ratio inside the range.
+ *
+ * Anything that is not a positive number is off, which covers the default, a negative, and a
+ * `NaN` arriving from a query string somebody spelled wrong — none of those can mean "a little
+ * reconstruction", and a renderer that guessed one would be drawing at a size nobody asked for.
+ */
+function resolveReconstruction(asked) {
+    const value = asked ?? DEFAULT_RENDER_QUALITY.reconstruction;
+    if (!(value > 0))
+        return 0;
+    return Math.min(RECONSTRUCTION_RANGE.most, Math.max(RECONSTRUCTION_RANGE.least, value));
+}
 export function resolveRenderQuality(options = {}) {
     const quality = {
         outputTransform: options.outputTransform ?? DEFAULT_RENDER_QUALITY.outputTransform,
@@ -200,6 +218,9 @@ export function resolveRenderQuality(options = {}) {
         cameraMotionBlur: Math.min(1, Math.max(0, options.cameraMotionBlur ?? DEFAULT_RENDER_QUALITY.cameraMotionBlur)),
         temporalAa: options.temporalAa ?? DEFAULT_RENDER_QUALITY.temporalAa,
         orderIndependent: options.orderIndependent ?? DEFAULT_RENDER_QUALITY.orderIndependent,
+        /* Off, or a ratio at least 1.3 and at most 2 — never a number between zero and the range. */
+        reconstruction: resolveReconstruction(options.reconstruction),
+        indirectLight: options.indirectLight ?? DEFAULT_RENDER_QUALITY.indirectLight,
         depthOfField: Math.min(1, Math.max(0, options.depthOfField ?? DEFAULT_RENDER_QUALITY.depthOfField)),
         occlusionCulling: Math.max(0, Math.round(options.occlusionCulling ?? DEFAULT_RENDER_QUALITY.occlusionCulling)),
         ambientOcclusion: Math.min(1, Math.max(0, options.ambientOcclusion ?? DEFAULT_RENDER_QUALITY.ambientOcclusion)),
@@ -226,6 +247,7 @@ export function resolveRenderQuality(options = {}) {
         discardResolvedAttachments: options.discardResolvedAttachments ?? DEFAULT_RENDER_QUALITY.discardResolvedAttachments,
         deferFramePass: options.deferFramePass ?? DEFAULT_RENDER_QUALITY.deferFramePass,
         frameGraph: options.frameGraph ?? DEFAULT_RENDER_QUALITY.frameGraph,
+        identifierGraph: options.identifierGraph ?? DEFAULT_RENDER_QUALITY.identifierGraph,
         clusteredLights: options.clusteredLights ?? DEFAULT_RENDER_QUALITY.clusteredLights,
         cullDraws: options.cullDraws ?? DEFAULT_RENDER_QUALITY.cullDraws,
         waterReflectionFilterTaps: options.waterReflectionFilterTaps ?? DEFAULT_RENDER_QUALITY.waterReflectionFilterTaps,

package/dist/render/screenSpaceReflection.d.ts

@@ -76,6 +76,20 @@ export interface ScreenSpaceHit {
     v: number;
     /** How far along the ray it was found, world metres. */
     distanceM: number;
+    /**
+     * The closest this ray's whole path came to the edge of the frame, 0 to 0.5. Zero if it left.
+     *
+     * **Fading the *hit* is not enough, and that is what this is for.** `screenEdgeFade` softens a
+     * hit near the border so a reflection leaves rather than being cut off along a line — but a ray
+     * that runs off the edge *before* it hits anything returns no hit at all, and that is still a
+     * line. The two cases are adjacent: one pixel's ray grazes the border and lands, the next
+     * pixel's leaves and answers nothing.
+     *
+     * So the fade has to be driven by how close the *path* came, which only the march can see. A
+     * ray that stayed in the middle of the frame reports 0.5; one that skimmed the border reports
+     * almost nothing and fades out before its neighbour disappears.
+     */
+    margin: number;
 }
 export declare function newScreenSpaceHit(): ScreenSpaceHit;
 /**
@@ -127,6 +141,15 @@ export declare function traceScreenSpaceRay(origin: ReadonlyVec3, direction: Rea
  * `band` is how much of the frame each side is fade, as a fraction.
  */
 export declare function screenEdgeFade(u: number, v: number, band: number): number;
+/** How far a screen position is from the nearest border, 0 at it and 0.5 in the middle. */
+export declare function edgeMargin(u: number, v: number): number;
+/**
+ * A margin turned into a fade, so `screenEdgeFade` and `ScreenSpaceHit.margin` cannot disagree.
+ *
+ * One expression rather than two copies of it — the rule `REFLECTION_EDGE_FADE` states about the
+ * band applied one level down, to the arithmetic the band goes into.
+ */
+export declare function edgeFade(margin: number, band: number): number;
 /**
  * How much of a reflection survives its ray pointing back toward the eye.
  *

package/dist/render/screenSpaceReflection.js

@@ -75,7 +75,7 @@ export function projectToUv(viewProjection, x, y, z, uv) {
     return true;
 }
 export function newScreenSpaceHit() {
-    return { hit: false, u: 0, v: 0, distanceM: 0 };
+    return { hit: false, u: 0, v: 0, distanceM: 0, margin: 0 };
 }
 /**
  * How many times a bracketed crossing is halved.
@@ -131,6 +131,9 @@ export function traceScreenSpaceRay(origin, direction, eye, march, project, scen
     out.u = 0;
     out.v = 0;
     out.distanceM = 0;
+    out.margin = 0;
+    /* The closest the path has come to the border so far. See `ScreenSpaceHit.margin`. */
+    let margin = 0.5;
     const steps = Math.max(1, Math.round(march.steps));
     const ox = origin[0] ?? 0;
     const oy = origin[1] ?? 0;
@@ -160,6 +163,7 @@ export function traceScreenSpaceRay(origin, direction, eye, march, project, scen
         const z = oz + dz * t;
         if (!project(x, y, z, UV))
             return false;
+        margin = Math.min(margin, edgeMargin(UV[0] ?? 0, UV[1] ?? 0));
         const scene = sceneDistance(UV[0] ?? 0, UV[1] ?? 0);
         /* Nothing was drawn here, so there is no surface to cross. Carried rather than treated as a
            miss so a ray may pass over a gap in the geometry and hit what is beyond it. */
@@ -211,6 +215,7 @@ export function traceScreenSpaceRay(origin, direction, eye, march, project, scen
             out.u = hitU;
             out.v = hitV;
             out.distanceM = far;
+            out.margin = margin;
             return true;
         }
         behind = gap;
@@ -232,8 +237,22 @@ export function traceScreenSpaceRay(origin, direction, eye, march, project, scen
 export function screenEdgeFade(u, v, band) {
     if (band <= 0)
         return u < 0 || u > 1 || v < 0 || v > 1 ? 0 : 1;
-    const nearest = Math.min(u, 1 - u, v, 1 - v);
-    return Math.min(1, Math.max(0, nearest / band));
+    return edgeFade(edgeMargin(u, v), band);
+}
+/** How far a screen position is from the nearest border, 0 at it and 0.5 in the middle. */
+export function edgeMargin(u, v) {
+    return Math.min(u, 1 - u, v, 1 - v);
+}
+/**
+ * A margin turned into a fade, so `screenEdgeFade` and `ScreenSpaceHit.margin` cannot disagree.
+ *
+ * One expression rather than two copies of it — the rule `REFLECTION_EDGE_FADE` states about the
+ * band applied one level down, to the arithmetic the band goes into.
+ */
+export function edgeFade(margin, band) {
+    if (band <= 0)
+        return margin < 0 ? 0 : 1;
+    return Math.min(1, Math.max(0, margin / band));
 }
 /**
  * How much of a reflection survives its ray pointing back toward the eye.