@driftengine/core 3.63.0 → 4.0.0

package/dist/render/readback.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Getting a number back from the GPU without waiting for it.
+ *
+ * The answer to a request made this frame arrives two or three frames later, and a caller that
+ * waits has stalled the pipeline to learn something it could have learned late for free. So this
+ * is a ring of slots: a request takes one, the completion fills it, and the caller collects
+ * whatever has arrived whenever it asks.
+ *
+ * **A full ring refuses rather than overwrites.** Silently dropping the oldest result produces a
+ * statistic that is wrong in a way nothing detects — a frame time that is quietly somebody
+ * else's, which is worse than a frame time that is missing.
+ *
+ * **Deliberately not what texture residency uses.** Reactive streaming is exactly the
+ * arrangement where this latency becomes visible as pop-in; the answer there is to predict
+ * rather than to read back. This ring is for timings and statistics, where being three frames
+ * late costs nothing.
+ */
+export interface ReadbackRing {
+    /** 0 free, 1 outstanding, 2 arrived, one per slot. */
+    state: Uint8Array;
+    /** The arrived buffer per slot, or null. */
+    data: (ArrayBuffer | null)[];
+    /** Where to start looking for a free slot, so requests spread rather than reusing one. */
+    next: number;
+}
+export declare function createReadbackRing(slots: number): ReadbackRing;
+export declare function beginReadback(ring: ReadbackRing): number;
+export declare function completeReadback(ring: ReadbackRing, slot: number, data: ArrayBuffer): void;
+export declare function takeReadback(ring: ReadbackRing): ArrayBuffer | null;
+export declare function readbackPending(ring: ReadbackRing): number;

package/dist/render/readback.js

@@ -0,0 +1,47 @@
+export function createReadbackRing(slots) {
+    return {
+        state: new Uint8Array(slots),
+        data: Array.from({ length: slots }, () => null),
+        next: 0,
+    };
+}
+export function beginReadback(ring) {
+    const slots = ring.state.length;
+    for (let i = 0; i < slots; i += 1) {
+        const slot = (ring.next + i) % slots;
+        if (ring.state[slot] === 0) {
+            ring.state[slot] = 1;
+            ring.next = (slot + 1) % slots;
+            return slot;
+        }
+    }
+    return -1;
+}
+export function completeReadback(ring, slot, data) {
+    if (slot < 0 || slot >= ring.state.length)
+        return;
+    /* Only an outstanding slot may be completed: one that was evicted or never requested is not
+     * ours to fill, and filling it would hand the caller a result for a request it has forgotten. */
+    if (ring.state[slot] !== 1)
+        return;
+    ring.state[slot] = 2;
+    ring.data[slot] = data;
+}
+export function takeReadback(ring) {
+    for (let slot = 0; slot < ring.state.length; slot += 1) {
+        if (ring.state[slot] === 2) {
+            const data = ring.data[slot] ?? null;
+            ring.state[slot] = 0;
+            ring.data[slot] = null;
+            return data;
+        }
+    }
+    return null;
+}
+export function readbackPending(ring) {
+    let pending = 0;
+    for (let slot = 0; slot < ring.state.length; slot += 1)
+        if (ring.state[slot] === 1)
+            pending += 1;
+    return pending;
+}

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

@@ -0,0 +1,36 @@
+/**
+ * History that disagrees with its neighbourhood, pulled in without changing its hue.
+ *
+ * **Why a luminance-chrominance space, and why a variance box.** The temporal resolve bounds its
+ * history by the minimum and maximum of nine red-green-blue samples, which is as wide as the most
+ * extreme of them: one bright pixel beside a moving edge lets the whole ghost through. A box of the
+ * mean plus or minus `gamma` standard deviations is as wide as the neighbourhood actually varies, and
+ * YCoCg separates the luminance the eye is sensitive to from the chrominance it is not.
+ *
+ * **Why clipping rather than clamping**, the resolve's own reason: a clamp moves each channel on its
+ * own, so a history merely brighter than its surroundings lands on a corner of the box and comes back
+ * a different hue — coloured fringing on every moving edge. Shortening the whole offset from the
+ * box's centre by one ratio keeps its direction and changes only its length. `clipToBox` is
+ * `clipToNeighbourhood` over plain arrays, and the test holds the two to one rule.
+ */
+/** YCoCg from linear red, green and blue, into `out`. Dyadic, so it round-trips exactly. */
+export declare function rgbToYCoCg(out: Float32Array | Float64Array, r: number, g: number, b: number): void;
+/** Linear red, green and blue from YCoCg, into `out`. */
+export declare function yCoCgToRgb(out: Float32Array | Float64Array, y: number, co: number, cg: number): void;
+/**
+ * The box of `count` three-channel samples: each channel's mean plus or minus `gamma` of its
+ * standard deviation, into `outMin` and `outMax`.
+ *
+ * **A channel whose samples all agree has that value as its box, exactly.** A mean of nine equal
+ * numbers is not always that number in floating point, and a box a rounding wide around the current
+ * colour would let a history through by a rounding instead of collapsing it onto the colour.
+ */
+export declare function varianceBox(samples: ArrayLike<number>, count: number, gamma: number, outMin: Float32Array | Float64Array, outMax: Float32Array | Float64Array): void;
+/**
+ * `history` pulled into the box `min`..`max`, along the line towards the box's centre, into `out`.
+ *
+ * Unchanged inside the box; on its boundary from outside it. A channel with no extent bounds any
+ * history that differs from it infinitely, so such a history collapses to the centre — the honest
+ * answer for a flat neighbourhood, and the alternative is a division by zero.
+ */
+export declare function clipToBox(out: Float32Array | Float64Array, history: ArrayLike<number>, min: ArrayLike<number>, max: ArrayLike<number>): void;

package/dist/render/recon/clamp.js

@@ -0,0 +1,92 @@
+/**
+ * History that disagrees with its neighbourhood, pulled in without changing its hue.
+ *
+ * **Why a luminance-chrominance space, and why a variance box.** The temporal resolve bounds its
+ * history by the minimum and maximum of nine red-green-blue samples, which is as wide as the most
+ * extreme of them: one bright pixel beside a moving edge lets the whole ghost through. A box of the
+ * mean plus or minus `gamma` standard deviations is as wide as the neighbourhood actually varies, and
+ * YCoCg separates the luminance the eye is sensitive to from the chrominance it is not.
+ *
+ * **Why clipping rather than clamping**, the resolve's own reason: a clamp moves each channel on its
+ * own, so a history merely brighter than its surroundings lands on a corner of the box and comes back
+ * a different hue — coloured fringing on every moving edge. Shortening the whole offset from the
+ * box's centre by one ratio keeps its direction and changes only its length. `clipToBox` is
+ * `clipToNeighbourhood` over plain arrays, and the test holds the two to one rule.
+ */
+/** YCoCg from linear red, green and blue, into `out`. Dyadic, so it round-trips exactly. */
+export function rgbToYCoCg(out, r, g, b) {
+    out[0] = r * 0.25 + g * 0.5 + b * 0.25;
+    out[1] = r * 0.5 - b * 0.5;
+    out[2] = -r * 0.25 + g * 0.5 - b * 0.25;
+}
+/** Linear red, green and blue from YCoCg, into `out`. */
+export function yCoCgToRgb(out, y, co, cg) {
+    const base = y - cg;
+    out[0] = base + co;
+    out[1] = y + cg;
+    out[2] = base - co;
+}
+/**
+ * The box of `count` three-channel samples: each channel's mean plus or minus `gamma` of its
+ * standard deviation, into `outMin` and `outMax`.
+ *
+ * **A channel whose samples all agree has that value as its box, exactly.** A mean of nine equal
+ * numbers is not always that number in floating point, and a box a rounding wide around the current
+ * colour would let a history through by a rounding instead of collapsing it onto the colour.
+ */
+export function varianceBox(samples, count, gamma, outMin, outMax) {
+    for (let c = 0; c < 3; c += 1) {
+        const first = samples[c];
+        let same = true;
+        let sum = 0;
+        for (let i = 0; i < count; i += 1) {
+            const value = samples[i * 3 + c];
+            sum += value;
+            if (value !== first)
+                same = false;
+        }
+        if (same) {
+            outMin[c] = first;
+            outMax[c] = first;
+            continue;
+        }
+        const mean = sum / count;
+        let spread = 0;
+        for (let i = 0; i < count; i += 1) {
+            const d = samples[i * 3 + c] - mean;
+            spread += d * d;
+        }
+        const deviation = Math.sqrt(spread / count);
+        outMin[c] = mean - gamma * deviation;
+        outMax[c] = mean + gamma * deviation;
+    }
+}
+/**
+ * `history` pulled into the box `min`..`max`, along the line towards the box's centre, into `out`.
+ *
+ * Unchanged inside the box; on its boundary from outside it. A channel with no extent bounds any
+ * history that differs from it infinitely, so such a history collapses to the centre — the honest
+ * answer for a flat neighbourhood, and the alternative is a division by zero.
+ */
+export function clipToBox(out, history, min, max) {
+    let ratio = 0;
+    for (let c = 0; c < 3; c += 1) {
+        const centre = (min[c] + max[c]) * 0.5;
+        const offset = history[c] - centre;
+        const extent = (max[c] - min[c]) * 0.5;
+        if (extent > 1e-7)
+            ratio = Math.max(ratio, Math.abs(offset) / extent);
+        else if (Math.abs(offset) > 1e-7)
+            ratio = Number.POSITIVE_INFINITY;
+    }
+    if (!(ratio > 1)) {
+        for (let c = 0; c < 3; c += 1)
+            out[c] = history[c];
+        return;
+    }
+    const scale = Number.isFinite(ratio) ? 1 / ratio : 0;
+    for (let c = 0; c < 3; c += 1) {
+        const centre = (min[c] + max[c]) * 0.5;
+        out[c] = centre + (history[c] - centre) * scale;
+    }
+}

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

@@ -0,0 +1,60 @@
+/**
+ * Whether a pixel's history is the same surface, as a weight from one to zero.
+ *
+ * **What is compared.** The camera moved, so this frame's depth and last frame's are depths from two
+ * eyes. The resolve compares the depth this surface *should* have had last frame — the w of its
+ * reprojected position, which is a view depth — with the view depth last frame actually held where it
+ * lands. Equal, and it is the same surface; different, and something else was there: a pixel that was
+ * hidden last frame would otherwise take its colour from whatever was in front of it.
+ *
+ * **Relative, and forgiving in proportion to the motion.** A tenth of a unit is nothing at a hundred
+ * units and everything at one. And a depth read at a reprojected position under fast motion comes from
+ * a different part of a texel than the one it stands for, which at a grazing angle is a different
+ * depth; the tolerance grows with the motion's length.
+ *
+ * **Normals, for the case depth cannot see.** A leaf's two sides are at one depth, and the history of
+ * the front is not the back. The forward frame has no normal buffer, so both normals come from their
+ * frame's depth — `worldPositionFromDepth` and `normalFromPositions` — in world space, where the two
+ * frames agree.
+ *
+ * **Continuous in every input**, because a step is a line on screen along which the history is kept on
+ * one frame and dropped on the next: every threshold is a smoothstep, never a comparison.
+ *
+ * Anything that is not a number, a depth that is not positive — which is what the resolve passes
+ * where the reprojection left the screen — and a negative motion length all trust nothing.
+ */
+export interface DisocclusionParams {
+    /** The relative depth disagreement trusted fully; trust falls to zero at twice it. */
+    readonly depthTolerance: number;
+    /** How much the tolerance grows per unit of motion, in uv. */
+    readonly motionScale: number;
+    /** The cosine between the two normals at and below which nothing is trusted. */
+    readonly normalFloor: number;
+    /** The cosine at and above which the normals are trusted fully. */
+    readonly normalCeiling: number;
+}
+/**
+ * A percent of depth, growing by half a percent for every hundredth of the screen the surface moved;
+ * normals trusted fully within sixty degrees and not at all past ninety.
+ */
+export declare const DEFAULT_DISOCCLUSION: DisocclusionParams;
+/**
+ * One where the history is trustworthy, zero where it is not, and continuous between.
+ *
+ * `currDepth` is the view depth this surface should have had last frame; `histDepth` the view depth
+ * last frame held where it lands, or zero where it landed off the screen; `motionLength` the motion's
+ * length in uv; `normalDot` the cosine between the two frames' world normals there.
+ */
+export declare function disocclusionWeight(currDepth: number, histDepth: number, motionLength: number, normalDot: number, params: DisocclusionParams): number;
+/**
+ * The world position a depth stands for: `(u, v, clipDepth)` through the inverse view-projection,
+ * in whatever depth convention that matrix was built for. Returns false where the matrix has no
+ * answer there — singular, or the point at infinity.
+ */
+export declare function worldPositionFromDepth(inverseViewProj: ArrayLike<number>, u: number, v: number, clipDepth: number, out: Float64Array): boolean;
+/**
+ * The unit normal of the surface through `centre` and its two screen neighbours, turned to face
+ * `eye` — so the answer is the same whichever way the target's rows run. Returns false where the
+ * three are in a line: there is no surface to have a normal.
+ */
+export declare function normalFromPositions(centre: ArrayLike<number>, right: ArrayLike<number>, up: ArrayLike<number>, eye: ArrayLike<number>, out: Float64Array): boolean;

package/dist/render/recon/disocclusion.js

@@ -0,0 +1,109 @@
+/**
+ * Whether a pixel's history is the same surface, as a weight from one to zero.
+ *
+ * **What is compared.** The camera moved, so this frame's depth and last frame's are depths from two
+ * eyes. The resolve compares the depth this surface *should* have had last frame — the w of its
+ * reprojected position, which is a view depth — with the view depth last frame actually held where it
+ * lands. Equal, and it is the same surface; different, and something else was there: a pixel that was
+ * hidden last frame would otherwise take its colour from whatever was in front of it.
+ *
+ * **Relative, and forgiving in proportion to the motion.** A tenth of a unit is nothing at a hundred
+ * units and everything at one. And a depth read at a reprojected position under fast motion comes from
+ * a different part of a texel than the one it stands for, which at a grazing angle is a different
+ * depth; the tolerance grows with the motion's length.
+ *
+ * **Normals, for the case depth cannot see.** A leaf's two sides are at one depth, and the history of
+ * the front is not the back. The forward frame has no normal buffer, so both normals come from their
+ * frame's depth — `worldPositionFromDepth` and `normalFromPositions` — in world space, where the two
+ * frames agree.
+ *
+ * **Continuous in every input**, because a step is a line on screen along which the history is kept on
+ * one frame and dropped on the next: every threshold is a smoothstep, never a comparison.
+ *
+ * Anything that is not a number, a depth that is not positive — which is what the resolve passes
+ * where the reprojection left the screen — and a negative motion length all trust nothing.
+ */
+/**
+ * A percent of depth, growing by half a percent for every hundredth of the screen the surface moved;
+ * normals trusted fully within sixty degrees and not at all past ninety.
+ */
+export const DEFAULT_DISOCCLUSION = {
+    depthTolerance: 0.01,
+    motionScale: 0.5,
+    normalFloor: 0,
+    normalCeiling: 0.5,
+};
+function smoothstep(edge0, edge1, x) {
+    const t = Math.min(1, Math.max(0, (x - edge0) / (edge1 - edge0)));
+    return t * t * (3 - 2 * t);
+}
+/**
+ * One where the history is trustworthy, zero where it is not, and continuous between.
+ *
+ * `currDepth` is the view depth this surface should have had last frame; `histDepth` the view depth
+ * last frame held where it lands, or zero where it landed off the screen; `motionLength` the motion's
+ * length in uv; `normalDot` the cosine between the two frames' world normals there.
+ */
+export function disocclusionWeight(currDepth, histDepth, motionLength, normalDot, params) {
+    if (!(currDepth > 0) || !(histDepth > 0) || !(motionLength >= 0) || Number.isNaN(normalDot)) {
+        return 0;
+    }
+    const disagreement = Math.abs(currDepth - histDepth) / currDepth;
+    const tolerance = params.depthTolerance + params.motionScale * motionLength;
+    const depth = 1 - smoothstep(tolerance, 2 * tolerance, disagreement);
+    const normal = smoothstep(params.normalFloor, params.normalCeiling, normalDot);
+    return depth * normal;
+}
+/**
+ * The world position a depth stands for: `(u, v, clipDepth)` through the inverse view-projection,
+ * in whatever depth convention that matrix was built for. Returns false where the matrix has no
+ * answer there — singular, or the point at infinity.
+ */
+export function worldPositionFromDepth(inverseViewProj, u, v, clipDepth, out) {
+    const x = u * 2 - 1;
+    const y = v * 2 - 1;
+    const m = inverseViewProj;
+    const w = m[3] * x + m[7] * y + m[11] * clipDepth + m[15];
+    if (!(Math.abs(w) > 1e-12))
+        return false;
+    for (let r = 0; r < 3; r += 1) {
+        out[r] =
+            (m[r] * x +
+                m[4 + r] * y +
+                m[8 + r] * clipDepth +
+                m[12 + r]) /
+                w;
+    }
+    return Number.isFinite(out[0]) && Number.isFinite(out[1]) && Number.isFinite(out[2]);
+}
+/**
+ * The unit normal of the surface through `centre` and its two screen neighbours, turned to face
+ * `eye` — so the answer is the same whichever way the target's rows run. Returns false where the
+ * three are in a line: there is no surface to have a normal.
+ */
+export function normalFromPositions(centre, right, up, eye, out) {
+    const ax = right[0] - centre[0];
+    const ay = right[1] - centre[1];
+    const az = right[2] - centre[2];
+    const bx = up[0] - centre[0];
+    const by = up[1] - centre[1];
+    const bz = up[2] - centre[2];
+    let nx = ay * bz - az * by;
+    let ny = az * bx - ax * bz;
+    let nz = ax * by - ay * bx;
+    const length2 = nx * nx + ny * ny + nz * nz;
+    const scale2 = (ax * ax + ay * ay + az * az) * (bx * bx + by * by + bz * bz);
+    if (!(length2 > 1e-12 * scale2))
+        return false;
+    const toEye = nx * (eye[0] - centre[0]) +
+        ny * (eye[1] - centre[1]) +
+        nz * (eye[2] - centre[2]);
+    const inverse = (toEye < 0 ? -1 : 1) / Math.sqrt(length2);
+    nx *= inverse;
+    ny *= inverse;
+    nz *= inverse;
+    out[0] = nx;
+    out[1] = ny;
+    out[2] = nz;
+    return true;
+}

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

@@ -0,0 +1,81 @@
+/**
+ * DriftFG's reference: a frame generated between two rendered ones, from their motion and depth.
+ *
+ * **One scatter, of the later frame.** Its motion points each pixel to where its surface was in the
+ * earlier frame, so a surface visible in the later frame stands at time `t` a fraction `1 − t` of
+ * that motion back from where it is now (`projectForward`), the nearest surface winning a pixel two
+ * land on. That one scatter places every surface the later frame shows, and carries both frames'
+ * colours for it: the later frame's at the pixel it came from, and the earlier frame's at the pixel
+ * its motion points to — when the earlier frame shows the same surface there, which its depth says.
+ * The colour is taken from whichever frame is nearer in time (`resolveGenerated`).
+ *
+ * **A pixel nothing lands on is a hole, filled and marked** (`fillHoles`): the later frame never
+ * saw what stands there, so it is a surface a moving object uncovered — and what a moving object
+ * uncovers is behind it, so the hole takes the farther of the two frames' surfaces at that pixel.
+ * The mark is kept for the device pass that follows this reference, which may treat a hole's pixels
+ * more carefully than a projected one's.
+ *
+ * **The interface is not in the frames generated from**: a menu drawn into them would be projected
+ * with whatever moved beneath it and warp. It is composited over the generated frame afterwards,
+ * from its own layer, at the display's rate (`composeInterface`).
+ *
+ * **Linear motion, and what that gives up.** A surface is placed along the straight line between
+ * its two positions, which is exact for a camera or an object moving at constant velocity across one
+ * render interval and wrong for anything turning within it; a turn fast enough to matter shows as a
+ * surface slightly off its arc for one generated frame. And a surface the later frame does not show
+ * — hidden in it, visible in the earlier one — is not projected at all: at small `t` it is a hole
+ * filled from the earlier frame, which is right, and at large `t` it is the same, which is late.
+ *
+ * Images are row-major; colour is four floats a pixel, premultiplied; depth is view distance, larger
+ * further; motion is two floats a pixel in pixels of this image. The engine's motion target stores
+ * uv with rows running upward, and converting it is the device pass's business rather than this.
+ */
+export interface FrameImage {
+    readonly width: number;
+    readonly height: number;
+    readonly colour: Float32Array;
+    readonly depth: Float32Array;
+    /** Where each pixel's surface was in the frame before, as an offset in pixels. */
+    readonly motion: Float32Array;
+}
+/** Which pixel of the later frame lands on each pixel at time `t`, and at what depth. */
+export interface Projection {
+    readonly width: number;
+    readonly height: number;
+    /** The later frame's pixel landing here, or -1 where none does. */
+    readonly source: Int32Array;
+    readonly depth: Float32Array;
+}
+export declare function createProjection(width: number, height: number): Projection;
+/**
+ * Scatter the later frame's pixels to where they stand at time `t`: 0 is the earlier frame and 1
+ * the later. The nearest surface wins a pixel two land on.
+ */
+export declare function projectForward(motion: Float32Array, depth: Float32Array, t: number, out: Projection): void;
+/**
+ * Colour every projected pixel from the frame nearer in time, and mark every pixel nothing landed on
+ * — whose colour is left for `fillHoles`.
+ *
+ * The earlier frame is used only where it shows the same surface where the motion says it was: its
+ * depth there within `SAME_SURFACE` of the later frame's. Where it does not, the surface was hidden
+ * in it, and the later frame is the only one that saw it.
+ */
+export declare function resolveGenerated(projection: Projection, before: FrameImage, after: FrameImage, t: number, out: Float32Array, mask: Uint8Array): void;
+/** Fill every marked pixel from the farther of the two frames' surfaces there. The mark stays. */
+export declare function fillHoles(out: Float32Array, before: FrameImage, after: FrameImage, mask: Uint8Array): void;
+/** The interface over the generated frame, premultiplied, from its own layer and never projected. */
+export declare function composeInterface(out: Float32Array, overlay: Float32Array): void;
+/**
+ * The milliseconds frame generation adds to every rendered frame, stated rather than hidden.
+ *
+ * **A generated frame sits between two rendered ones, so it cannot be shown until the later one
+ * exists**, and the later one is then held back while the frames generated before it are shown:
+ * `displayHz / renderHz − 1` display intervals, and the generation before the first of them. At
+ * the render rate nothing is generated and nothing is added. The rates must be a whole multiple
+ * apart, or the generated frames would fall unevenly between rendered ones and the motion judder.
+ *
+ * What would make it wrong: extrapolation — generating from the earlier frame alone, ahead of the
+ * later — adds no hold-back and fills no hole from a frame it has not got. That is a different
+ * trade, and this reference does not make it.
+ */
+export declare function frameGenLatency(displayHz: number, renderHz: number, generationMs: number): number;

package/dist/render/recon/frameGen.js

@@ -0,0 +1,150 @@
+/**
+ * DriftFG's reference: a frame generated between two rendered ones, from their motion and depth.
+ *
+ * **One scatter, of the later frame.** Its motion points each pixel to where its surface was in the
+ * earlier frame, so a surface visible in the later frame stands at time `t` a fraction `1 − t` of
+ * that motion back from where it is now (`projectForward`), the nearest surface winning a pixel two
+ * land on. That one scatter places every surface the later frame shows, and carries both frames'
+ * colours for it: the later frame's at the pixel it came from, and the earlier frame's at the pixel
+ * its motion points to — when the earlier frame shows the same surface there, which its depth says.
+ * The colour is taken from whichever frame is nearer in time (`resolveGenerated`).
+ *
+ * **A pixel nothing lands on is a hole, filled and marked** (`fillHoles`): the later frame never
+ * saw what stands there, so it is a surface a moving object uncovered — and what a moving object
+ * uncovers is behind it, so the hole takes the farther of the two frames' surfaces at that pixel.
+ * The mark is kept for the device pass that follows this reference, which may treat a hole's pixels
+ * more carefully than a projected one's.
+ *
+ * **The interface is not in the frames generated from**: a menu drawn into them would be projected
+ * with whatever moved beneath it and warp. It is composited over the generated frame afterwards,
+ * from its own layer, at the display's rate (`composeInterface`).
+ *
+ * **Linear motion, and what that gives up.** A surface is placed along the straight line between
+ * its two positions, which is exact for a camera or an object moving at constant velocity across one
+ * render interval and wrong for anything turning within it; a turn fast enough to matter shows as a
+ * surface slightly off its arc for one generated frame. And a surface the later frame does not show
+ * — hidden in it, visible in the earlier one — is not projected at all: at small `t` it is a hole
+ * filled from the earlier frame, which is right, and at large `t` it is the same, which is late.
+ *
+ * Images are row-major; colour is four floats a pixel, premultiplied; depth is view distance, larger
+ * further; motion is two floats a pixel in pixels of this image. The engine's motion target stores
+ * uv with rows running upward, and converting it is the device pass's business rather than this.
+ */
+/**
+ * How far two depths may differ, as a fraction of the nearer, and still be one surface.
+ *
+ * What it gives up: a surface moving toward or away from the camera changes its own depth between
+ * frames, and one moving five per cent of its distance in a render interval reads as a different
+ * surface, so it takes the later frame's colour at small `t` too — its colour a render interval
+ * late, not wrong.
+ */
+const SAME_SURFACE = 0.05;
+export function createProjection(width, height) {
+    const pixels = width * height;
+    return { width, height, source: new Int32Array(pixels), depth: new Float32Array(pixels) };
+}
+/**
+ * Scatter the later frame's pixels to where they stand at time `t`: 0 is the earlier frame and 1
+ * the later. The nearest surface wins a pixel two land on.
+ */
+export function projectForward(motion, depth, t, out) {
+    const { width, height, source } = out;
+    source.fill(-1);
+    out.depth.fill(Infinity);
+    const back = 1 - t;
+    for (let y = 0; y < height; y += 1) {
+        for (let x = 0; x < width; x += 1) {
+            const from = y * width + x;
+            const tx = Math.round(x + back * motion[from * 2]);
+            const ty = Math.round(y + back * motion[from * 2 + 1]);
+            if (tx < 0 || tx >= width || ty < 0 || ty >= height)
+                continue;
+            const at = ty * width + tx;
+            const z = depth[from];
+            if (z < out.depth[at]) {
+                out.depth[at] = z;
+                source[at] = from;
+            }
+        }
+    }
+}
+function copyColour(out, at, from, index) {
+    for (let c = 0; c < 4; c += 1)
+        out[at * 4 + c] = from[index * 4 + c];
+}
+/**
+ * Colour every projected pixel from the frame nearer in time, and mark every pixel nothing landed on
+ * — whose colour is left for `fillHoles`.
+ *
+ * The earlier frame is used only where it shows the same surface where the motion says it was: its
+ * depth there within `SAME_SURFACE` of the later frame's. Where it does not, the surface was hidden
+ * in it, and the later frame is the only one that saw it.
+ */
+export function resolveGenerated(projection, before, after, t, out, mask) {
+    const { width, height, source } = projection;
+    const early = t < 0.5;
+    for (let at = 0; at < source.length; at += 1) {
+        const from = source[at];
+        if (from < 0) {
+            mask[at] = 1;
+            continue;
+        }
+        mask[at] = 0;
+        if (early) {
+            const x = Math.round((from % width) + after.motion[from * 2]);
+            const y = Math.round(Math.floor(from / width) + after.motion[from * 2 + 1]);
+            if (x >= 0 && x < width && y >= 0 && y < height) {
+                const was = y * width + x;
+                const then = before.depth[was];
+                const now = after.depth[from];
+                if (Math.abs(then - now) <= SAME_SURFACE * Math.min(then, now)) {
+                    copyColour(out, at, before.colour, was);
+                    continue;
+                }
+            }
+        }
+        copyColour(out, at, after.colour, from);
+    }
+}
+/** Fill every marked pixel from the farther of the two frames' surfaces there. The mark stays. */
+export function fillHoles(out, before, after, mask) {
+    for (let at = 0; at < mask.length; at += 1) {
+        if (mask[at] !== 1)
+            continue;
+        const behind = before.depth[at] > after.depth[at] ? before : after;
+        copyColour(out, at, behind.colour, at);
+    }
+}
+/** The interface over the generated frame, premultiplied, from its own layer and never projected. */
+export function composeInterface(out, overlay) {
+    for (let i = 0; i < out.length; i += 4) {
+        const keep = 1 - overlay[i + 3];
+        for (let c = 0; c < 4; c += 1) {
+            out[i + c] = overlay[i + c] + out[i + c] * keep;
+        }
+    }
+}
+/**
+ * The milliseconds frame generation adds to every rendered frame, stated rather than hidden.
+ *
+ * **A generated frame sits between two rendered ones, so it cannot be shown until the later one
+ * exists**, and the later one is then held back while the frames generated before it are shown:
+ * `displayHz / renderHz − 1` display intervals, and the generation before the first of them. At
+ * the render rate nothing is generated and nothing is added. The rates must be a whole multiple
+ * apart, or the generated frames would fall unevenly between rendered ones and the motion judder.
+ *
+ * What would make it wrong: extrapolation — generating from the earlier frame alone, ahead of the
+ * later — adds no hold-back and fills no hole from a frame it has not got. That is a different
+ * trade, and this reference does not make it.
+ */
+export function frameGenLatency(displayHz, renderHz, generationMs) {
+    const ratio = displayHz / renderHz;
+    const whole = Math.round(ratio);
+    if (!(whole >= 1) || Math.abs(ratio - whole) > 1e-9) {
+        throw new RangeError(`frame generation: a display at ${displayHz} Hz over a render at ${renderHz} Hz is not a ` +
+            'whole multiple, so generated frames would fall unevenly between rendered ones');
+    }
+    if (whole === 1)
+        return 0;
+    return ((whole - 1) * 1000) / displayHz + generationMs;
+}

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

@@ -0,0 +1,34 @@
+/**
+ * The two sizes a reconstructed frame has.
+ *
+ * **A frame with a reconstruction has a render size and an output size, and every texel size is
+ * taken from the target it belongs to.** The scene, its depth, the multisampled pair, decals,
+ * reflections, the translucent set, the medium and the motion target are the render size; the
+ * resolve, the history, bloom and the composite are the output size. The two are one number apart
+ * and confusing them does not fail — it draws a picture that is subtly the wrong shape.
+ *
+ * **The projection is built from the output's aspect and never from the render's.** Each axis is
+ * rounded up on its own, so a render size's aspect differs from its output's by up to a texel's
+ * worth: at 1280 by 720 and a ratio of 1.7 that is 753 by 424, an aspect of 1.7759 against 1.7778.
+ * A projection built from the render size stretches the picture by that much — a fraction of a per
+ * cent, invisible in a screenshot and visible as a wobble every time the drawing buffer resizes.
+ */
+/**
+ * Why a multisampled frame is not reconstructed, in words, so both backends read the same sentence.
+ *
+ * **The motion pass is what forbids it.** That pass draws the frame's movers again with the depth
+ * the scene left, testing for equality so only the pixels the scene kept are written — and an
+ * attachment's sample count has to agree with every other attachment in its pass, so a
+ * multisampled depth wants a multisampled motion target, a resolve of it, and a second set of
+ * everything downstream.
+ *
+ * It is also a choice nobody should want. A reconstruction's own accumulation is what antialiases
+ * the picture; paying for a second antialiasing at four times the fragment work, and then throwing
+ * three quarters of it away in a resolve, is the cost this feature exists to avoid.
+ */
+export declare const RECONSTRUCTION_MULTISAMPLE_REFUSAL: string;
+/** The render size for an output size and a `quality.reconstruction` ratio; 0 is off. */
+export declare function reconRenderSize(outputWidth: number, outputHeight: number, ratio: number): {
+    width: number;
+    height: number;
+};