@driftengine/core 3.63.0 → 4.1.0

package/src/render/recon/clamp.ts

@@ -0,0 +1,113 @@
+/**
+ * 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: Float32Array | Float64Array,
+  r: number,
+  g: number,
+  b: number,
+): void {
+  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: Float32Array | Float64Array,
+  y: number,
+  co: number,
+  cg: number,
+): void {
+  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: ArrayLike<number>,
+  count: number,
+  gamma: number,
+  outMin: Float32Array | Float64Array,
+  outMax: Float32Array | Float64Array,
+): void {
+  for (let c = 0; c < 3; c += 1) {
+    const first = samples[c] as number;
+    let same = true;
+    let sum = 0;
+    for (let i = 0; i < count; i += 1) {
+      const value = samples[i * 3 + c] as number;
+      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] as number) - 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: Float32Array | Float64Array,
+  history: ArrayLike<number>,
+  min: ArrayLike<number>,
+  max: ArrayLike<number>,
+): void {
+  let ratio = 0;
+  for (let c = 0; c < 3; c += 1) {
+    const centre = ((min[c] as number) + (max[c] as number)) * 0.5;
+    const offset = (history[c] as number) - centre;
+    const extent = ((max[c] as number) - (min[c] as number)) * 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] as number;
+    return;
+  }
+  const scale = Number.isFinite(ratio) ? 1 / ratio : 0;
+  for (let c = 0; c < 3; c += 1) {
+    const centre = ((min[c] as number) + (max[c] as number)) * 0.5;
+    out[c] = centre + ((history[c] as number) - centre) * scale;
+  }
+}

package/src/render/recon/disocclusion.ts

@@ -0,0 +1,143 @@
+/**
+ * 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 const DEFAULT_DISOCCLUSION: DisocclusionParams = {
+  depthTolerance: 0.01,
+  motionScale: 0.5,
+  normalFloor: 0,
+  normalCeiling: 0.5,
+};
+
+function smoothstep(edge0: number, edge1: number, x: number): number {
+  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: number,
+  histDepth: number,
+  motionLength: number,
+  normalDot: number,
+  params: DisocclusionParams,
+): number {
+  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: ArrayLike<number>,
+  u: number,
+  v: number,
+  clipDepth: number,
+  out: Float64Array,
+): boolean {
+  const x = u * 2 - 1;
+  const y = v * 2 - 1;
+  const m = inverseViewProj;
+  const w =
+    (m[3] as number) * x + (m[7] as number) * y + (m[11] as number) * clipDepth + (m[15] as number);
+  if (!(Math.abs(w) > 1e-12)) return false;
+  for (let r = 0; r < 3; r += 1) {
+    out[r] =
+      ((m[r] as number) * x +
+        (m[4 + r] as number) * y +
+        (m[8 + r] as number) * clipDepth +
+        (m[12 + r] as number)) /
+      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: ArrayLike<number>,
+  right: ArrayLike<number>,
+  up: ArrayLike<number>,
+  eye: ArrayLike<number>,
+  out: Float64Array,
+): boolean {
+  const ax = (right[0] as number) - (centre[0] as number);
+  const ay = (right[1] as number) - (centre[1] as number);
+  const az = (right[2] as number) - (centre[2] as number);
+  const bx = (up[0] as number) - (centre[0] as number);
+  const by = (up[1] as number) - (centre[1] as number);
+  const bz = (up[2] as number) - (centre[2] as number);
+  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] as number) - (centre[0] as number)) +
+    ny * ((eye[1] as number) - (centre[1] as number)) +
+    nz * ((eye[2] as number) - (centre[2] as number));
+  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/src/render/recon/frameGen.ts

@@ -0,0 +1,191 @@
+/**
+ * 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;
+}
+
+/**
+ * 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: number, height: number): Projection {
+  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: Float32Array,
+  depth: Float32Array,
+  t: number,
+  out: Projection,
+): void {
+  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] as number));
+      const ty = Math.round(y + back * (motion[from * 2 + 1] as number));
+      if (tx < 0 || tx >= width || ty < 0 || ty >= height) continue;
+      const at = ty * width + tx;
+      const z = depth[from] as number;
+      if (z < (out.depth[at] as number)) {
+        out.depth[at] = z;
+        source[at] = from;
+      }
+    }
+  }
+}
+
+function copyColour(out: Float32Array, at: number, from: Float32Array, index: number): void {
+  for (let c = 0; c < 4; c += 1) out[at * 4 + c] = from[index * 4 + c] as number;
+}
+
+/**
+ * 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: Projection,
+  before: FrameImage,
+  after: FrameImage,
+  t: number,
+  out: Float32Array,
+  mask: Uint8Array,
+): void {
+  const { width, height, source } = projection;
+  const early = t < 0.5;
+  for (let at = 0; at < source.length; at += 1) {
+    const from = source[at] as number;
+    if (from < 0) {
+      mask[at] = 1;
+      continue;
+    }
+    mask[at] = 0;
+    if (early) {
+      const x = Math.round((from % width) + (after.motion[from * 2] as number));
+      const y = Math.round(Math.floor(from / width) + (after.motion[from * 2 + 1] as number));
+      if (x >= 0 && x < width && y >= 0 && y < height) {
+        const was = y * width + x;
+        const then = before.depth[was] as number;
+        const now = after.depth[from] as number;
+        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: Float32Array,
+  before: FrameImage,
+  after: FrameImage,
+  mask: Uint8Array,
+): void {
+  for (let at = 0; at < mask.length; at += 1) {
+    if (mask[at] !== 1) continue;
+    const behind = (before.depth[at] as number) > (after.depth[at] as number) ? 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: Float32Array, overlay: Float32Array): void {
+  for (let i = 0; i < out.length; i += 4) {
+    const keep = 1 - (overlay[i + 3] as number);
+    for (let c = 0; c < 4; c += 1) {
+      out[i + c] = (overlay[i + c] as number) + (out[i + c] as number) * 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: number, renderHz: number, generationMs: number): number {
+  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/src/render/recon/frameSizes.ts

@@ -0,0 +1,64 @@
+/**
+ * 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: number,
+  outputHeight: number,
+  ratio: number,
+): { width: number; height: number } {
+  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/src/render/recon/jitter.ts

@@ -0,0 +1,126 @@
+/**
+ * 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: number, base: number): number {
+  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<number, Float64Array>();
+
+/**
+ * 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: number): Float64Array {
+  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] as number;
+    meanY += table[i * 2 + 1] as number;
+  }
+  meanX /= count;
+  meanY /= count;
+  for (let i = 0; i < count; i += 1) {
+    table[i * 2] = (table[i * 2] as number) - meanX;
+    table[i * 2 + 1] = (table[i * 2 + 1] as number) - 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: number, phases: number, out: Float32Array): void {
+  const table = jitterTable(phases);
+  const count = table.length / 2;
+  const at = ((frame % count) + count) % count;
+  out[0] = table[at * 2] as number;
+  out[1] = table[at * 2 + 1] as number;
+}
+
+/** 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: number, outputWidth: number): number {
+  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: Float32Array,
+  source: ArrayLike<number>,
+  jitter: ArrayLike<number>,
+): Float32Array {
+  for (let i = 0; i < 16; i += 1) out[i] = source[i] as number;
+  const x = jitter[0] as number;
+  const y = jitter[1] as number;
+  for (let column = 0; column < 4; column += 1) {
+    const w = source[column * 4 + 3] as number;
+    out[column * 4] = (out[column * 4] as number) + x * w;
+    out[column * 4 + 1] = (out[column * 4 + 1] as number) + y * w;
+  }
+  return out;
+}