@driftengine/core 3.62.0 → 4.0.0

package/dist/render/recon/frameSizes.js

@@ -0,0 +1,58 @@
+/**
+ * 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 const RECONSTRUCTION_MULTISAMPLE_REFUSAL = 'driftengine: a reconstruction draws its movers again against the depth the scene left, and ' +
+    'every attachment in a pass must agree about its sample count — so reconstruction is off ' +
+    'wherever `sceneSamples` is above one. The accumulation is the antialiasing; the two are a ' +
+    'choice of one.';
+/** The render size for an output size and a `quality.reconstruction` ratio; 0 is off. */
+export function reconRenderSize(outputWidth, outputHeight, ratio) {
+    const width = Math.max(1, Math.floor(outputWidth));
+    const height = Math.max(1, Math.floor(outputHeight));
+    /*
+     * **Anything that is not a ratio above one draws at the output size**: off, a ratio of exactly
+     * one, and — the case that matters — a ratio *below* one, which divides the other way and would
+     * ask the renderer to draw more pixels than it shows. `resolveRenderQuality` never produces one,
+     * and this is a public function that a caller reaches with whatever number they have. `NaN`
+     * lands here too, which `ratio <= 0` would have sent through the divide to a size of `NaN`.
+     */
+    if (!(ratio > 1))
+        return { width, height };
+    /*
+     * Up, never down: rounding down draws fewer pixels than the ratio says, which is a frame-rate win
+     * nobody asked for and a softer picture they did not agree to.
+     *
+     * **The floor of one is not redundant**, which taking it out and watching nothing fail suggested
+     * it was. A ceiling of a positive quotient is at least one for every finite ratio — and an
+     * infinite one divides to zero, so the size comes back zero by zero, which a device refuses.
+     */
+    return {
+        width: Math.max(1, Math.ceil(width / ratio)),
+        height: Math.max(1, Math.ceil(height / ratio)),
+    };
+}

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

@@ -0,0 +1,60 @@
+/**
+ * The sub-pixel sequence a frame is rasterised along, for the temporal resolve and for
+ * reconstruction.
+ *
+ * **One sequence, two consumers.** `temporalAa.ts` jitters a frame at its output size along eight
+ * phases; DriftTR jitters a frame rendered below its output size, and needs more phases for the
+ * same reason a smaller render needs more frames to cover the output — each render pixel stands
+ * for several output pixels, and the sequence has to visit each of their positions before it
+ * repeats. The eight-phase sequence is the numbers the temporal resolve always used, so its
+ * captures do not move.
+ *
+ * **What is reused rather than rebuilt**, from `temporalAa.ts`: Halton in bases two and three, each
+ * period centred on its own mean, and `jitterProjection`, which puts the offset into clip space
+ * rather than into the projection's third column. See that function for why the third column is
+ * wrong for the combined view-projection this engine draws with.
+ */
+/**
+ * The radical inverse of `index` in `base`: the digits of `index` mirrored about the point.
+ *
+ * Consecutive indices land as far from each other as the base allows, which is what lets eight of
+ * them cover a pixel evenly where eight random ones leave holes and pairs.
+ */
+export declare function halton(index: number, base: number): number;
+/**
+ * The period's offsets, centred so they sum to zero.
+ *
+ * **Halton's own mean is not the middle of the pixel** — eight points in base two average 57/128 —
+ * and accumulating towards an off-centre mean resolves to a picture displaced from the depth
+ * buffer it is tested against and from every pass that did not jitter. Subtracting the period's
+ * own mean costs nothing and makes the property exact.
+ */
+export declare function jitterTable(phases: number): Float64Array;
+/**
+ * Where in its pixel frame `frame` samples, in pixels and centred on zero, on a sequence of
+ * `phases` positions. Written into `out`, two floats.
+ */
+export declare function jitterOffset(frame: number, phases: number, out: Float32Array): void;
+/**
+ * How many phases a reconstruction from `renderWidth` to `outputWidth` takes: eight for every
+ * output pixel one render pixel covers, rounded up — and eight where the render is not smaller.
+ *
+ * The count the published temporal upscalers use, and the reason is coverage rather than taste: a
+ * render pixel two thirds of an output pixel wide stands for 2.25 output pixels, and eight positions
+ * an output pixel is what the temporal resolve already found enough.
+ */
+export declare function reconJitterPhases(renderWidth: number, outputWidth: number): number;
+/**
+ * `source` moved in clip space by `jitter`, which is what a contributed pass does with the frame's
+ * jitter (`PrepareContext.jitter`) to draw where the renderer's own verbs drew this frame.
+ *
+ * **In the camera's own convention, before any correction**: `jitter` is a fraction of the clip
+ * square, x rightward and y upward as `mat4.perspective` has them, so the matrix it applies to is
+ * the one the consumer built — a pass then multiplies by `clipCorrection` or `depthCorrection`
+ * exactly as it would have, and the offset arrives on screen where the renderer's did. Scaled by w,
+ * as `jitterProjection` is, so it is a constant screen offset at every depth.
+ *
+ * **A zero jitter leaves a finite matrix bit for bit** — each term gains a zero — so a frame that is
+ * not reconstructed draws exactly what it drew before this existed.
+ */
+export declare function jitterClip(out: Float32Array, source: ArrayLike<number>, jitter: ArrayLike<number>): Float32Array;

package/dist/render/recon/jitter.js

@@ -0,0 +1,118 @@
+/**
+ * The sub-pixel sequence a frame is rasterised along, for the temporal resolve and for
+ * reconstruction.
+ *
+ * **One sequence, two consumers.** `temporalAa.ts` jitters a frame at its output size along eight
+ * phases; DriftTR jitters a frame rendered below its output size, and needs more phases for the
+ * same reason a smaller render needs more frames to cover the output — each render pixel stands
+ * for several output pixels, and the sequence has to visit each of their positions before it
+ * repeats. The eight-phase sequence is the numbers the temporal resolve always used, so its
+ * captures do not move.
+ *
+ * **What is reused rather than rebuilt**, from `temporalAa.ts`: Halton in bases two and three, each
+ * period centred on its own mean, and `jitterProjection`, which puts the offset into clip space
+ * rather than into the projection's third column. See that function for why the third column is
+ * wrong for the combined view-projection this engine draws with.
+ */
+/**
+ * The radical inverse of `index` in `base`: the digits of `index` mirrored about the point.
+ *
+ * Consecutive indices land as far from each other as the base allows, which is what lets eight of
+ * them cover a pixel evenly where eight random ones leave holes and pairs.
+ */
+export function halton(index, base) {
+    let result = 0;
+    let fraction = 1;
+    let i = index;
+    while (i > 0) {
+        fraction /= base;
+        result += fraction * (i % base);
+        i = Math.floor(i / base);
+    }
+    return result;
+}
+/* One table a phase count, built once: x then y a phase. */
+const TABLES = new Map();
+/**
+ * The period's offsets, centred so they sum to zero.
+ *
+ * **Halton's own mean is not the middle of the pixel** — eight points in base two average 57/128 —
+ * and accumulating towards an off-centre mean resolves to a picture displaced from the depth
+ * buffer it is tested against and from every pass that did not jitter. Subtracting the period's
+ * own mean costs nothing and makes the property exact.
+ */
+export function jitterTable(phases) {
+    const count = Math.max(1, Math.floor(phases));
+    let table = TABLES.get(count);
+    if (table !== undefined)
+        return table;
+    table = new Float64Array(count * 2);
+    let meanX = 0;
+    let meanY = 0;
+    for (let i = 0; i < count; i += 1) {
+        table[i * 2] = halton(i + 1, 2);
+        table[i * 2 + 1] = halton(i + 1, 3);
+        meanX += table[i * 2];
+        meanY += table[i * 2 + 1];
+    }
+    meanX /= count;
+    meanY /= count;
+    for (let i = 0; i < count; i += 1) {
+        table[i * 2] = table[i * 2] - meanX;
+        table[i * 2 + 1] = table[i * 2 + 1] - meanY;
+    }
+    TABLES.set(count, table);
+    return table;
+}
+/**
+ * Where in its pixel frame `frame` samples, in pixels and centred on zero, on a sequence of
+ * `phases` positions. Written into `out`, two floats.
+ */
+export function jitterOffset(frame, phases, out) {
+    const table = jitterTable(phases);
+    const count = table.length / 2;
+    const at = ((frame % count) + count) % count;
+    out[0] = table[at * 2];
+    out[1] = table[at * 2 + 1];
+}
+/** The temporal resolve's own count, and the fewest a reconstruction takes. */
+const BASE_PHASES = 8;
+/**
+ * How many phases a reconstruction from `renderWidth` to `outputWidth` takes: eight for every
+ * output pixel one render pixel covers, rounded up — and eight where the render is not smaller.
+ *
+ * The count the published temporal upscalers use, and the reason is coverage rather than taste: a
+ * render pixel two thirds of an output pixel wide stands for 2.25 output pixels, and eight positions
+ * an output pixel is what the temporal resolve already found enough.
+ */
+export function reconJitterPhases(renderWidth, outputWidth) {
+    if (!(renderWidth > 0) || !(outputWidth > renderWidth))
+        return BASE_PHASES;
+    const ratio = outputWidth / renderWidth;
+    return Math.ceil(BASE_PHASES * ratio * ratio);
+}
+/**
+ * `source` moved in clip space by `jitter`, which is what a contributed pass does with the frame's
+ * jitter (`PrepareContext.jitter`) to draw where the renderer's own verbs drew this frame.
+ *
+ * **In the camera's own convention, before any correction**: `jitter` is a fraction of the clip
+ * square, x rightward and y upward as `mat4.perspective` has them, so the matrix it applies to is
+ * the one the consumer built — a pass then multiplies by `clipCorrection` or `depthCorrection`
+ * exactly as it would have, and the offset arrives on screen where the renderer's did. Scaled by w,
+ * as `jitterProjection` is, so it is a constant screen offset at every depth.
+ *
+ * **A zero jitter leaves a finite matrix bit for bit** — each term gains a zero — so a frame that is
+ * not reconstructed draws exactly what it drew before this existed.
+ */
+export function jitterClip(out, source, jitter) {
+    for (let i = 0; i < 16; i += 1)
+        out[i] = source[i];
+    const x = jitter[0];
+    const y = jitter[1];
+    for (let column = 0; column < 4; column += 1) {
+        const w = source[column * 4 + 3];
+        out[column * 4] = out[column * 4] + x * w;
+        out[column * 4 + 1] = out[column * 4 + 1] + y * w;
+    }
+    return out;
+}

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

@@ -0,0 +1,55 @@
+/**
+ * Where each pixel's surface was last frame.
+ *
+ * **A motion vector is the offset from this frame's pixel to where its surface was, in the
+ * coordinates of an unjittered frame**, and every step of the reconstruction after this reads it
+ * that way. The history is a picture of the unjittered scene; a vector that carried either frame's
+ * jitter would look every sample up a fraction of a pixel away, in a pattern that repeats with the
+ * jitter period — which reads as shimmer and is diagnosed as everything except its cause. So the
+ * jitter is taken out of where a pixel was *observed* (`unjitteredUv`) and never put into the
+ * matrices a vector is built from.
+ *
+ * **Two sources, one meaning.** Most of a frame did not move: its motion is the camera's, derived in
+ * the resolve from depth through the reprojection matrix both renderers already build
+ * (`cameraMotion`). A draw that states where it was last frame — a previous model matrix, a
+ * previous skin palette — is drawn again into a motion target, and there the vector is the
+ * difference of the vertex's two clip positions (`objectMotion`). A skinned vertex's previous
+ * position comes from its previous *pose*, not from its previous model matrix: a character standing
+ * still and swinging an arm has the same model both frames.
+ *
+ * **What this does not follow**: wind bending (`channelBend`) and morph targets move vertices by the
+ * clock and by weights nothing keeps a previous value of. Their surfaces take the model's motion,
+ * and the neighbourhood clip catches what is left.
+ *
+ * Coordinates are clip-up throughout: `u` and `v` run 0 to 1, with `v = 0` where clip y is -1.
+ */
+/** The motion target's format: the vector in two channels, and a flag where a draw wrote one. */
+export declare const MOTION_FORMAT: 'rgba16float';
+/**
+ * The camera's motion at a pixel: where the surface at `(u, v)` and `clipDepth` was last frame,
+ * less where it is. `reprojection` is `previousViewProj × inverse(currentViewProj)`, unjittered,
+ * in whatever depth convention `clipDepth` is given in.
+ *
+ * Returns false, and a zero vector, where the surface was behind last frame's eye: there is no
+ * position to have been at, and a vector through the eye points anywhere.
+ */
+export declare function cameraMotion(reprojection: ArrayLike<number>, u: number, v: number, clipDepth: number, out: Float32Array): boolean;
+/**
+ * A drawn vertex's motion: its previous clip position less its current one, in uv units.
+ *
+ * Both positions are unjittered — the motion pass draws with the frame's unjittered matrices and
+ * the vertex's two transforms. Returns false, and a zero vector, where either is behind its eye.
+ */
+export declare function objectMotion(currentClip: ArrayLike<number>, previousClip: ArrayLike<number>, out: Float32Array): boolean;
+/**
+ * A vertex through a skin palette: the four joints' matrices weighted and summed, then applied —
+ * `SKINNING_GLSL`'s `skinMatrix()` times the position, in model space, before the model matrix.
+ * `palette` is sixteen floats a joint, column-major. Written into `out`, four values.
+ */
+export declare function skinVertex(palette: ArrayLike<number>, joints: ArrayLike<number>, weights: ArrayLike<number>, position: ArrayLike<number>, out: Float64Array): void;
+/**
+ * Where a sample observed at `(u, v)` in a frame jittered by `jitterX`, `jitterY` pixels of a
+ * `width` by `height` target stands in the unjittered frame. `jitterProjection` moved the picture by
+ * the jitter; this moves the observation back.
+ */
+export declare function unjitteredUv(u: number, v: number, jitterX: number, jitterY: number, width: number, height: number, out: Float32Array): void;

package/dist/render/recon/motionVectors.js

@@ -0,0 +1,107 @@
+/**
+ * Where each pixel's surface was last frame.
+ *
+ * **A motion vector is the offset from this frame's pixel to where its surface was, in the
+ * coordinates of an unjittered frame**, and every step of the reconstruction after this reads it
+ * that way. The history is a picture of the unjittered scene; a vector that carried either frame's
+ * jitter would look every sample up a fraction of a pixel away, in a pattern that repeats with the
+ * jitter period — which reads as shimmer and is diagnosed as everything except its cause. So the
+ * jitter is taken out of where a pixel was *observed* (`unjitteredUv`) and never put into the
+ * matrices a vector is built from.
+ *
+ * **Two sources, one meaning.** Most of a frame did not move: its motion is the camera's, derived in
+ * the resolve from depth through the reprojection matrix both renderers already build
+ * (`cameraMotion`). A draw that states where it was last frame — a previous model matrix, a
+ * previous skin palette — is drawn again into a motion target, and there the vector is the
+ * difference of the vertex's two clip positions (`objectMotion`). A skinned vertex's previous
+ * position comes from its previous *pose*, not from its previous model matrix: a character standing
+ * still and swinging an arm has the same model both frames.
+ *
+ * **What this does not follow**: wind bending (`channelBend`) and morph targets move vertices by the
+ * clock and by weights nothing keeps a previous value of. Their surfaces take the model's motion,
+ * and the neighbourhood clip catches what is left.
+ *
+ * Coordinates are clip-up throughout: `u` and `v` run 0 to 1, with `v = 0` where clip y is -1.
+ */
+/** The motion target's format: the vector in two channels, and a flag where a draw wrote one. */
+export const MOTION_FORMAT = 'rgba16float';
+/**
+ * The camera's motion at a pixel: where the surface at `(u, v)` and `clipDepth` was last frame,
+ * less where it is. `reprojection` is `previousViewProj × inverse(currentViewProj)`, unjittered,
+ * in whatever depth convention `clipDepth` is given in.
+ *
+ * Returns false, and a zero vector, where the surface was behind last frame's eye: there is no
+ * position to have been at, and a vector through the eye points anywhere.
+ */
+export function cameraMotion(reprojection, u, v, clipDepth, out) {
+    const x = u * 2 - 1;
+    const y = v * 2 - 1;
+    const m = reprojection;
+    const w = m[3] * x + m[7] * y + m[11] * clipDepth + m[15];
+    if (!(w > 0)) {
+        out[0] = 0;
+        out[1] = 0;
+        return false;
+    }
+    const px = m[0] * x + m[4] * y + m[8] * clipDepth + m[12];
+    const py = m[1] * x + m[5] * y + m[9] * clipDepth + m[13];
+    out[0] = (px / w) * 0.5 + 0.5 - u;
+    out[1] = (py / w) * 0.5 + 0.5 - v;
+    return true;
+}
+/**
+ * A drawn vertex's motion: its previous clip position less its current one, in uv units.
+ *
+ * Both positions are unjittered — the motion pass draws with the frame's unjittered matrices and
+ * the vertex's two transforms. Returns false, and a zero vector, where either is behind its eye.
+ */
+export function objectMotion(currentClip, previousClip, out) {
+    const cw = currentClip[3];
+    const pw = previousClip[3];
+    if (!(cw > 0) || !(pw > 0)) {
+        out[0] = 0;
+        out[1] = 0;
+        return false;
+    }
+    out[0] = (previousClip[0] / pw - currentClip[0] / cw) * 0.5;
+    out[1] = (previousClip[1] / pw - currentClip[1] / cw) * 0.5;
+    return true;
+}
+/**
+ * A vertex through a skin palette: the four joints' matrices weighted and summed, then applied —
+ * `SKINNING_GLSL`'s `skinMatrix()` times the position, in model space, before the model matrix.
+ * `palette` is sixteen floats a joint, column-major. Written into `out`, four values.
+ */
+export function skinVertex(palette, joints, weights, position, out) {
+    const px = position[0];
+    const py = position[1];
+    const pz = position[2];
+    out[0] = 0;
+    out[1] = 0;
+    out[2] = 0;
+    out[3] = 0;
+    for (let influence = 0; influence < 4; influence += 1) {
+        const weight = weights[influence];
+        if (weight === 0)
+            continue;
+        const at = joints[influence] * 16;
+        for (let row = 0; row < 4; row += 1) {
+            out[row] =
+                out[row] +
+                    weight *
+                        (palette[at + row] * px +
+                            palette[at + 4 + row] * py +
+                            palette[at + 8 + row] * pz +
+                            palette[at + 12 + row]);
+        }
+    }
+}
+/**
+ * Where a sample observed at `(u, v)` in a frame jittered by `jitterX`, `jitterY` pixels of a
+ * `width` by `height` target stands in the unjittered frame. `jitterProjection` moved the picture by
+ * the jitter; this moves the observation back.
+ */
+export function unjitteredUv(u, v, jitterX, jitterY, width, height, out) {
+    out[0] = u - jitterX / width;
+    out[1] = v - jitterY / height;
+}

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

@@ -0,0 +1,41 @@
+/**
+ * Where a pixel's surface was, and the history sampled there.
+ *
+ * **Off the edge is a disocclusion, not a clamp.** A surface that was outside last frame's picture
+ * has no history; sampling the border instead drags one row of pixels inward as a smear for as long
+ * as the camera keeps turning. The temporal resolve already refuses it, and this keeps the rule.
+ *
+ * **The history is read bicubically**, because a bilinear read of an accumulated picture blurs it a
+ * little more every frame it is carried: a history reprojected by half a pixel sixty times a second
+ * is a history bilinearly filtered sixty times a second. Catmull-Rom interpolates — a texel centre
+ * returns that texel — and its weights sum to one, so the picture neither brightens nor darkens as
+ * it accumulates. Its negative lobes can undershoot beside a bright edge; a colour cannot be
+ * negative, so the sample is floored at zero, and the neighbourhood clip bounds the rest.
+ *
+ * **The shader uses five bilinear taps for the sixteen texels**: the middle pair of each axis folded
+ * into one tap, the four corners dropped, the weights renormalised. On an accumulated picture the
+ * corners carry almost nothing, and the test beside this says how little.
+ *
+ * Images are rows from `v = 0` upward, texel centres at whole texel coordinates, clamped at the
+ * border.
+ */
+/**
+ * Reproject pixel `(x, y)` of a `width` by `height` target by a motion vector in uv units, into the
+ * texel coordinate its surface had. Returns false where that is off the picture — past the outer
+ * edge of the border texels, or not a number.
+ */
+export declare function reprojectPixel(x: number, y: number, motion: ArrayLike<number>, width: number, height: number, out: Float32Array): boolean;
+/** Catmull-Rom's four weights for the texels at -1, 0, 1 and 2 about a fraction `t`. */
+export declare function catmullRomWeights(t: number, out: Float64Array): void;
+/** A bilinear read at texel coordinate `(x, y)`, clamped at the border. */
+export declare function sampleBilinear(image: ArrayLike<number>, x: number, y: number, width: number, height: number, channels: number, out: Float32Array): void;
+/** The full sixteen-texel Catmull-Rom read at texel coordinate `(x, y)`, floored at zero. */
+export declare function sampleHistoryBicubic(image: ArrayLike<number>, x: number, y: number, width: number, height: number, channels: number, out: Float32Array): void;
+/**
+ * The five-tap approximation the shader uses, at texel coordinate `(x, y)`, floored at zero.
+ *
+ * Each axis's middle two texels are one bilinear tap placed at `w2 / (w1 + w2)` between them, which
+ * is exact for those four texels; the edge taps read a row or column the same way; the corners are
+ * dropped and the five weights renormalised.
+ */
+export declare function sampleHistoryBicubic5(image: ArrayLike<number>, x: number, y: number, width: number, height: number, channels: number, out: Float32Array): void;

package/dist/render/recon/reproject.js

@@ -0,0 +1,131 @@
+/**
+ * Where a pixel's surface was, and the history sampled there.
+ *
+ * **Off the edge is a disocclusion, not a clamp.** A surface that was outside last frame's picture
+ * has no history; sampling the border instead drags one row of pixels inward as a smear for as long
+ * as the camera keeps turning. The temporal resolve already refuses it, and this keeps the rule.
+ *
+ * **The history is read bicubically**, because a bilinear read of an accumulated picture blurs it a
+ * little more every frame it is carried: a history reprojected by half a pixel sixty times a second
+ * is a history bilinearly filtered sixty times a second. Catmull-Rom interpolates — a texel centre
+ * returns that texel — and its weights sum to one, so the picture neither brightens nor darkens as
+ * it accumulates. Its negative lobes can undershoot beside a bright edge; a colour cannot be
+ * negative, so the sample is floored at zero, and the neighbourhood clip bounds the rest.
+ *
+ * **The shader uses five bilinear taps for the sixteen texels**: the middle pair of each axis folded
+ * into one tap, the four corners dropped, the weights renormalised. On an accumulated picture the
+ * corners carry almost nothing, and the test beside this says how little.
+ *
+ * Images are rows from `v = 0` upward, texel centres at whole texel coordinates, clamped at the
+ * border.
+ */
+/**
+ * Reproject pixel `(x, y)` of a `width` by `height` target by a motion vector in uv units, into the
+ * texel coordinate its surface had. Returns false where that is off the picture — past the outer
+ * edge of the border texels, or not a number.
+ */
+export function reprojectPixel(x, y, motion, width, height, out) {
+    const u = (x + 0.5) / width + motion[0];
+    const v = (y + 0.5) / height + motion[1];
+    out[0] = u * width - 0.5;
+    out[1] = v * height - 0.5;
+    return u >= 0 && u <= 1 && v >= 0 && v <= 1;
+}
+/** Catmull-Rom's four weights for the texels at -1, 0, 1 and 2 about a fraction `t`. */
+export function catmullRomWeights(t, out) {
+    const t2 = t * t;
+    const t3 = t2 * t;
+    out[0] = -0.5 * t3 + t2 - 0.5 * t;
+    out[1] = 1.5 * t3 - 2.5 * t2 + 1;
+    out[2] = -1.5 * t3 + 2 * t2 + 0.5 * t;
+    out[3] = 0.5 * t3 - 0.5 * t2;
+}
+function clampIndex(value, size) {
+    return value < 0 ? 0 : value >= size ? size - 1 : value;
+}
+/** One texel, clamped to the image. */
+function texel(image, x, y, width, height, channels, c) {
+    return image[(clampIndex(y, height) * width + clampIndex(x, width)) * channels + c];
+}
+/** A bilinear read at texel coordinate `(x, y)`, clamped at the border. */
+export function sampleBilinear(image, x, y, width, height, channels, out) {
+    const x0 = Math.floor(x);
+    const y0 = Math.floor(y);
+    const fx = x - x0;
+    const fy = y - y0;
+    for (let c = 0; c < channels; c += 1) {
+        const top = texel(image, x0, y0, width, height, channels, c) * (1 - fx) +
+            texel(image, x0 + 1, y0, width, height, channels, c) * fx;
+        const bottom = texel(image, x0, y0 + 1, width, height, channels, c) * (1 - fx) +
+            texel(image, x0 + 1, y0 + 1, width, height, channels, c) * fx;
+        out[c] = top * (1 - fy) + bottom * fy;
+    }
+}
+const WX = new Float64Array(4);
+const WY = new Float64Array(4);
+/** The full sixteen-texel Catmull-Rom read at texel coordinate `(x, y)`, floored at zero. */
+export function sampleHistoryBicubic(image, x, y, width, height, channels, out) {
+    const x1 = Math.floor(x);
+    const y1 = Math.floor(y);
+    catmullRomWeights(x - x1, WX);
+    catmullRomWeights(y - y1, WY);
+    for (let c = 0; c < channels; c += 1) {
+        let sum = 0;
+        for (let j = 0; j < 4; j += 1) {
+            let row = 0;
+            for (let i = 0; i < 4; i += 1) {
+                row += WX[i] * texel(image, x1 - 1 + i, y1 - 1 + j, width, height, channels, c);
+            }
+            sum += WY[j] * row;
+        }
+        out[c] = Math.max(0, sum);
+    }
+}
+const TAP = new Float32Array(4);
+/**
+ * The five-tap approximation the shader uses, at texel coordinate `(x, y)`, floored at zero.
+ *
+ * Each axis's middle two texels are one bilinear tap placed at `w2 / (w1 + w2)` between them, which
+ * is exact for those four texels; the edge taps read a row or column the same way; the corners are
+ * dropped and the five weights renormalised.
+ */
+export function sampleHistoryBicubic5(image, x, y, width, height, channels, out) {
+    const x1 = Math.floor(x);
+    const y1 = Math.floor(y);
+    catmullRomWeights(x - x1, WX);
+    catmullRomWeights(y - y1, WY);
+    const wx12 = WX[1] + WX[2];
+    const wy12 = WY[1] + WY[2];
+    const x12 = x1 + WX[2] / wx12;
+    const y12 = y1 + WY[2] / wy12;
+    const x0 = x1 - 1;
+    const y0 = y1 - 1;
+    const x3 = x1 + 2;
+    const y3 = y1 + 2;
+    const weights = [
+        wx12 * WY[0],
+        WX[0] * wy12,
+        wx12 * wy12,
+        WX[3] * wy12,
+        wx12 * WY[3],
+    ];
+    const at = [
+        [x12, y0],
+        [x0, y12],
+        [x12, y12],
+        [x3, y12],
+        [x12, y3],
+    ];
+    const total = weights.reduce((sum, w) => sum + w, 0);
+    for (let c = 0; c < channels; c += 1)
+        out[c] = 0;
+    for (let k = 0; k < 5; k += 1) {
+        const place = at[k];
+        sampleBilinear(image, place[0], place[1], width, height, channels, TAP);
+        for (let c = 0; c < channels; c += 1) {
+            out[c] = out[c] + weights[k] * TAP[c];
+        }
+    }
+    for (let c = 0; c < channels; c += 1)
+        out[c] = Math.max(0, out[c] / total);
+}

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

@@ -0,0 +1,90 @@
+import type { DisocclusionParams } from './disocclusion.ts';
+/** What a reconstruction is asked for. */
+export interface ReconQuality {
+    /** Output size over render size, each axis. 1.3 to 2; 0 is off. */
+    readonly ratio: number;
+    /** The current frame's share of a fully trusted accumulation. */
+    readonly alpha: number;
+    /** How far the shown picture is sharpened, 0 to 1. */
+    readonly sharpen: number;
+    /** Standard deviations the neighbourhood box extends either side of its mean. */
+    readonly clampGamma: number;
+}
+/**
+ * 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 declare const DEFAULT_RECON_QUALITY: ReconQuality;
+/**
+ * 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 declare function accumulate(out: Float32Array | Float64Array, current: ArrayLike<number>, history: ArrayLike<number>, weight: number, alpha: number): void;
+/**
+ * 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 declare function sharpen(out: Float32Array | Float64Array, centre: ArrayLike<number>, neighbours: ArrayLike<number>, amount: number): void;
+/** Everything one resolve reads. Images are rows from `v = 0` upward. */
+export interface ResolveFrame {
+    readonly renderWidth: number;
+    readonly renderHeight: number;
+    readonly outputWidth: number;
+    readonly outputHeight: number;
+    /** Render size, three floats a texel, linear. */
+    readonly scene: ArrayLike<number>;
+    /** Render size, one clip depth a texel. */
+    readonly depth: ArrayLike<number>;
+    /**
+     * Render size, four floats a texel: a drawn object's motion in uv, its previous view depth, and a
+     * flag above one half where a draw wrote them.
+     */
+    readonly motion: ArrayLike<number>;
+    /** Last frame's `depth`. */
+    readonly previousDepth: ArrayLike<number>;
+    /** Output size, four floats a texel: last frame's unsharpened colour, and the weight it gathered. */
+    readonly history: ArrayLike<number>;
+    /** False on the first frame, after a resize and after a cut. */
+    readonly hasHistory: boolean;
+    /** This frame's inverse view-projection, unjittered. */
+    readonly inverseViewProj: ArrayLike<number>;
+    /** Last frame's view-projection and its inverse, unjittered. */
+    readonly previousViewProj: ArrayLike<number>;
+    readonly previousInverseViewProj: ArrayLike<number>;
+    readonly eye: ArrayLike<number>;
+    readonly previousEye: ArrayLike<number>;
+    /** This frame's and last frame's jitter, in render pixels. */
+    readonly jitter: ArrayLike<number>;
+    readonly previousJitter: ArrayLike<number>;
+    readonly quality: ReconQuality;
+    readonly disocclusion: DisocclusionParams;
+}
+/**
+ * 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 declare const SAMPLE_SPREAD = 0.47;
+/** A render sample's weight at `(dx, dy)` output pixels from an output pixel's centre. */
+export declare function reconstructionWeight(dx: number, dy: number): number;
+/**
+ * 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 declare const CONFIDENT_WEIGHT = 1;
+/**
+ * One output pixel: the history's next colour, before sharpening, and the weight it has gathered —
+ * four values into `out`.
+ */
+export declare function resolvePixel(frame: ResolveFrame, ox: number, oy: number, out: Float32Array): void;
+/**
+ * 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 declare function resolveFrame(frame: ResolveFrame, history: Float32Array, shown: Float32Array): void;