@driftengine/core 3.63.0 → 4.1.0

package/src/render/frame/virtual.ts

@@ -0,0 +1,91 @@
+/**
+ * Transient resources a frame declares, addressed by identifier rather than by bit.
+ *
+ * **`resources.ts` is not replaced and is not wrong.** It is a fixed table of fourteen
+ * attachments held in a bit mask, and it says in its own header that the transient allocator a
+ * frame graph is famous for would be machinery with no case to serve — which was true while
+ * this frame's composition was fixed. A GPU-driven frame's composition is not: hierarchical
+ * depth chains, visibility buffers, per-material bin lists and indirect argument buffers are
+ * allocated against what the frame contains. Thirty-one bits cannot hold hundreds of them and
+ * a thirty-second bit is not the fix.
+ *
+ * So there are two representations and each is used where it is right: the mask for a fixed
+ * composition, identifiers for a dynamic one. Nothing converts between them, because nothing
+ * needs to — a frame is scheduled by one or the other.
+ *
+ * Structure of arrays, growable by doubling, and nothing here holds an object per resource.
+ */
+
+/** A transient texture, sized in texels. */
+export interface VirtualTextureDesc {
+  kind: 'texture';
+  width: number;
+  height: number;
+  bytesPerTexel: number;
+}
+
+/** A transient buffer, sized in bytes. */
+export interface VirtualBufferDesc {
+  kind: 'buffer';
+  bytes: number;
+}
+
+export type VirtualDesc = VirtualTextureDesc | VirtualBufferDesc;
+
+export interface VirtualTable {
+  /** 0 for a texture, 1 for a buffer, one entry per identifier. */
+  kinds: Uint8Array;
+  /** Byte footprint per identifier, which is what the aliasing allocator packs. */
+  bytes: Uint32Array;
+  /** How many identifiers have been declared this frame. */
+  count: number;
+}
+
+export function createVirtualTable(capacity: number): VirtualTable {
+  return { kinds: new Uint8Array(capacity), bytes: new Uint32Array(capacity), count: 0 };
+}
+
+export function resetVirtualTable(table: VirtualTable): void {
+  table.count = 0;
+}
+
+export function virtualCount(table: VirtualTable): number {
+  return table.count;
+}
+
+/*
+ * Doubling rather than growing by one, because a frame that declares one more resource than
+ * last frame will declare one more again, and a table that reallocates per declaration turns a
+ * linear frame into a quadratic one.
+ */
+function grow(table: VirtualTable): void {
+  const size = table.kinds.length === 0 ? 8 : table.kinds.length * 2;
+  const kinds = new Uint8Array(size);
+  kinds.set(table.kinds);
+  const bytes = new Uint32Array(size);
+  bytes.set(table.bytes);
+  table.kinds = kinds;
+  table.bytes = bytes;
+}
+
+export function declareVirtual(table: VirtualTable, desc: VirtualDesc): number {
+  if (table.count === table.kinds.length) grow(table);
+  const id = table.count;
+  if (desc.kind === 'texture') {
+    table.kinds[id] = 0;
+    table.bytes[id] = desc.width * desc.height * desc.bytesPerTexel;
+  } else {
+    table.kinds[id] = 1;
+    table.bytes[id] = desc.bytes;
+  }
+  table.count = id + 1;
+  return id;
+}
+
+export function virtualKind(table: VirtualTable, id: number): number {
+  return table.kinds[id] ?? 0;
+}
+
+export function virtualBytes(table: VirtualTable, id: number): number {
+  return table.bytes[id] ?? 0;
+}

package/src/render/gi/chain.ts

@@ -0,0 +1,225 @@
+/** The three levels in one place, and the rule that there is never a fourth. */
+
+import { createProbeBlend } from '../probeGrid.ts';
+import { REFLECTION_EDGE_FADE, edgeFade, newScreenSpaceHit } from '../screenSpaceReflection.ts';
+import { GLOBAL_FIELD_BLEND } from './globalField.ts';
+import { sampleProbeVolume, visibleProbes } from './probeVolume.ts';
+import { FIELD_MARCH, newFieldHit, traceField } from './traceField.ts';
+import { GI_SCREEN_MARCH, traceScreen } from './traceScreen.ts';
+
+import type { ReadonlyVec3 } from 'gl-matrix';
+import type { ProbeGrid } from '../probeGrid.ts';
+import type { ScreenSpaceMarch } from '../screenSpaceReflection.ts';
+import type { GlobalField, GlobalFieldCascade } from './globalField.ts';
+import type { ProbeVisibility } from './probeVolume.ts';
+import type { FieldMarch } from './traceField.ts';
+
+/**
+ * **Three levels, and the architecture is the fallback rather than any one of them.**
+ *
+ * `ROADMAP.md` refused screen-space global illumination, and this does not reverse that refusal —
+ * it satisfies the requirement the refusal was about. Screen space is exact wherever the screen has
+ * the answer and has *no* answer where it does not, which as a terminal technique means inventing
+ * one from whatever happened to be in frame. Here it is an accelerator with something behind it:
+ * a world-space distance field whose error is bounded by its own resolution, and behind that a
+ * probe volume which is never wrong and only ever coarse.
+ *
+ * **The last level cannot fail, and that is the load-bearing sentence.** A ray with no answer
+ * leaves a shader nothing to write but what the buffer held, which is the previous frame and reads
+ * as a flicker. A probe volume is an interpolation between measurements — no ray to escape, no
+ * frame to leave — and `visibleProbes` falls back to the nearest probe even when every visibility
+ * weight has crushed to zero. So there are exactly three cases.
+ *
+ * **And the levels blend rather than switch.** Every boundary between them moves with the camera:
+ * the frame's edge does by definition, and the cascades are centred on the camera so their faces do
+ * too. A hard switch at a boundary that moves is a seam that sweeps across the picture whenever the
+ * camera turns, which is worse than either level's own error — an error that is wrong everywhere
+ * reads as a coarse solution, and one that changes abruptly along a surface reads as a crack.
+ */
+
+export const GI_SOURCE_SCREEN = 0;
+export const GI_SOURCE_FIELD = 1;
+export const GI_SOURCE_PROBES = 2;
+
+export type GiSource = 0 | 1 | 2;
+
+/** One indirect ray, as the shading path hands it over. */
+export interface IndirectRay {
+  /** Where it starts, on the surface being shaded. */
+  readonly point: ReadonlyVec3;
+  /** That surface's normal, which both traces lift off along. */
+  readonly normal: ReadonlyVec3;
+  readonly direction: ReadonlyVec3;
+  /** Cone half-angle for the world trace. Zero is a mirror; wider is a rougher surface. */
+  readonly coneAngle: number;
+}
+
+/** Everything the three levels need, gathered so a per-ray call takes one object. */
+export interface GiResources {
+  readonly eye: ReadonlyVec3;
+  readonly project: (x: number, y: number, z: number, uv: Float32Array) => boolean;
+  /** How far the eye is from whatever the frame drew, and `Infinity` where it drew nothing. */
+  readonly sceneDistance: (u: number, v: number) => number;
+  /** The radiance the frame holds at a screen position. */
+  readonly screenRadiance: (u: number, v: number, out: Float32Array) => void;
+  readonly field: GlobalField;
+  /** The radiance at a world point the field trace arrived at. */
+  readonly fieldRadiance: (x: number, y: number, z: number, out: Float32Array) => void;
+  readonly grid: ProbeGrid;
+  /** Null is the off switch, and it lands on the grid's own blend. See `probeVolume.ts`. */
+  readonly visibility: ProbeVisibility | null;
+  /** `probeChannels` floats a probe, layer-major. */
+  readonly probeValues: Float32Array;
+  readonly probeChannels: number;
+  readonly screenMarch?: ScreenSpaceMarch;
+  readonly fieldMarch?: FieldMarch;
+}
+
+export interface IndirectResult {
+  /** Always true. See the module header: there is no fourth case. */
+  hit: boolean;
+  /** Which level contributed most. The radiance is the blend, not this level alone. */
+  source: GiSource;
+  /** Three channels. */
+  readonly radiance: Float32Array;
+  /** How much of the answer came from each level, summing to one. */
+  readonly blend: Float32Array;
+}
+
+export function newIndirectResult(): IndirectResult {
+  return {
+    hit: false,
+    source: GI_SOURCE_PROBES,
+    radiance: new Float32Array(3),
+    blend: new Float32Array(3),
+  };
+}
+
+/** Scratch, because this runs once per ray per pixel and the rule about that is absolute. */
+const SCREEN_HIT = newScreenSpaceHit();
+const FIELD_HIT = newFieldHit();
+const PROBE_BLEND = createProbeBlend();
+const LEVEL = new Float32Array(3);
+const PROBE_OUT = new Float32Array(3);
+
+/**
+ * Trace one indirect ray down the chain, and always answer.
+ *
+ * The screen answers as much as its distance from the edge of the frame allows; what is left goes
+ * to the world field, as much as *its* distance from the edge of the outermost cascade allows; and
+ * whatever is left after that goes to the probes, which have nothing behind them and take it all.
+ */
+export function traceIndirect(
+  ray: IndirectRay,
+  resources: GiResources,
+  out: IndirectResult,
+): IndirectResult {
+  out.radiance.fill(0);
+  out.blend.fill(0);
+  out.hit = true;
+
+  /* Level 0. Weighted by how far the hit landed from the edge of the frame, which is the one
+     boundary a viewer is guaranteed to see move. */
+  let screen = 0;
+  if (
+    traceScreen(
+      ray.point,
+      ray.normal,
+      ray.direction,
+      resources.eye,
+      resources.screenMarch ?? GI_SCREEN_MARCH,
+      resources.project,
+      resources.sceneDistance,
+      SCREEN_HIT,
+    )
+  ) {
+    /*
+     * **The *path*'s margin, not the hit's.** Fading only the hit leaves the seam exactly where it
+     * was: a ray that grazes the border and lands is faded, and the ray one pixel over leaves the
+     * frame and answers nothing at all, so the weight still steps from one to zero across a line
+     * that sweeps as the camera turns. See `ScreenSpaceHit.margin`.
+     */
+    screen = edgeFade(SCREEN_HIT.margin, REFLECTION_EDGE_FADE);
+    if (screen > 0) {
+      resources.screenRadiance(SCREEN_HIT.u, SCREEN_HIT.v, LEVEL);
+      add(out.radiance, LEVEL, screen);
+    }
+  }
+
+  /* Level 1, for whatever the screen did not answer. Weighted the same way against the outermost
+     cascade's face, because that face is centred on the camera and therefore moves with it too. */
+  let fieldShare = 0;
+  const remaining = 1 - screen;
+  if (remaining > 0) {
+    const march = resources.fieldMarch ?? FIELD_MARCH;
+    const coned =
+      march.coneAngle === ray.coneAngle ? march : { ...march, coneAngle: ray.coneAngle };
+    if (traceField(resources.field, ray.point, ray.normal, ray.direction, coned, FIELD_HIT)) {
+      fieldShare =
+        remaining * fieldConfidence(resources.field, FIELD_HIT.x, FIELD_HIT.y, FIELD_HIT.z);
+      if (fieldShare > 0) {
+        resources.fieldRadiance(FIELD_HIT.x, FIELD_HIT.y, FIELD_HIT.z, LEVEL);
+        add(out.radiance, LEVEL, fieldShare);
+      }
+    }
+  }
+
+  /*
+   * Level 2, for everything still unanswered. **It takes whatever is left without asking**, which
+   * is what "never wrong and only ever coarse" buys: there is no case where this declines.
+   */
+  const probes = 1 - screen - fieldShare;
+  if (probes > 0) {
+    visibleProbes(
+      resources.grid,
+      resources.visibility,
+      ray.point[0] ?? 0,
+      ray.point[1] ?? 0,
+      ray.point[2] ?? 0,
+      PROBE_BLEND,
+    );
+    sampleProbeVolume(PROBE_BLEND, resources.probeValues, resources.probeChannels, PROBE_OUT);
+    add(out.radiance, PROBE_OUT, probes);
+  }
+
+  out.blend[0] = screen;
+  out.blend[1] = fieldShare;
+  out.blend[2] = probes;
+  out.source =
+    screen >= fieldShare && screen >= probes
+      ? GI_SOURCE_SCREEN
+      : fieldShare >= probes
+        ? GI_SOURCE_FIELD
+        : GI_SOURCE_PROBES;
+  return out;
+}
+
+/**
+ * How much a world-field hit is trusted, by how far inside the outermost cascade it landed.
+ *
+ * **The same band `sampleGlobalField` fades its own cascades over**, so the two do not disagree
+ * about where the field stops being the answer. A hit right on the outer face is a hit the field
+ * barely had the information for, and the probes are what carry it the rest of the way.
+ */
+function fieldConfidence(field: GlobalField, x: number, y: number, z: number): number {
+  const outer = field.cascades[field.cascades.length - 1] as GlobalFieldCascade;
+  const band = GLOBAL_FIELD_BLEND * ((outer.bounds[3] as number) - (outer.bounds[0] as number));
+  if (band <= 0) return 1;
+  const p = [x, y, z];
+  let inside = Infinity;
+  for (let axis = 0; axis < 3; axis++) {
+    inside = Math.min(
+      inside,
+      (p[axis] as number) - (outer.bounds[axis] as number),
+      (outer.bounds[axis + 3] as number) - (p[axis] as number),
+    );
+  }
+  return Math.min(1, Math.max(0, inside / band));
+}
+
+/** `target += source * weight`, three channels. */
+function add(target: Float32Array, source: Float32Array, weight: number): void {
+  for (let channel = 0; channel < 3; channel++) {
+    target[channel] = (target[channel] as number) + (source[channel] as number) * weight;
+  }
+}

package/src/render/gi/denoise.ts

@@ -0,0 +1,276 @@
+/** Filtering indirect light without smearing it across an edge or losing any of it. */
+
+import { clipToNeighbourhood } from '../temporalAa.ts';
+
+import type { Rgb } from '../temporalAa.ts';
+import type { GiSource } from './chain.ts';
+
+/**
+ * **Indirect light arrives noisy, and every way of filtering it can quietly darken the scene.**
+ *
+ * A handful of rays a pixel is what makes this affordable, and a handful of rays is an estimate
+ * with variance. The filter is not a finishing touch — without it the chain is unusable — and the
+ * three ways it goes wrong all read as the *lighting* wanting a tuning pass rather than as the
+ * filter being wrong: a spatial kernel whose weights do not sum to one darkens every edge, a
+ * temporal blend that treats a disocclusion as staleness smears whatever moved, and a blend weight
+ * that never settles either oscillates or never reaches the mean it is averaging.
+ *
+ * **The plan asked this to reuse Wave 3A's reprojection, disocclusion and clamping rather than
+ * writing a second temporal filter, and one of those three exists.** `clipToNeighbourhood` is
+ * here, tested, and mirrored in `TEMPORAL_RESOLVE_FRAG` — so it is used. The other two do not
+ * exist in the tree and Wave 3A creates them, which is why **this module takes them as inputs
+ * rather than computing them**: `temporalDenoise` is handed the history a caller reprojected and a
+ * flag saying whether it may be trusted. That is the right shape regardless of which wave lands
+ * first — a denoiser that owned its own reprojection would be the second answer the plan was
+ * warning about — and it means the whole of this is testable and shippable today, with Wave 3A
+ * plugging into the two parameters rather than into a rewrite.
+ */
+
+/** One frame's worth of what the filter needs, as flat arrays a pass would upload. */
+export interface DenoiseFrame {
+  /** Three floats a pixel. */
+  readonly radiance: Float32Array;
+  /** One a pixel, in metres from the eye. A pixel that drew nothing may be `Infinity`. */
+  readonly depth: Float32Array;
+  /** Three a pixel, unit length. */
+  readonly normal: Float32Array;
+  /** Which level of the chain answered each pixel. See `filterStepFor`. */
+  readonly source: Uint8Array;
+  readonly width: number;
+  readonly height: number;
+}
+
+export interface SpatialOptions {
+  /**
+   * Multiplier on the kernel's spacing, in pixels. See `filterStepFor` for what chooses it.
+   *
+   * **A step rather than a radius**, which is the à-trous arrangement: the same five-tap kernel is
+   * run with its taps further apart, so a wide filter costs what a narrow one costs. A radius
+   * would cost its own square.
+   */
+  readonly step: number;
+  /**
+   * How far apart in depth two pixels may be and still share light, as a fraction of their depth.
+   *
+   * **Relative rather than absolute**, because a centimetre is a discontinuity across a desk and
+   * nothing at all across a valley. A tenth is wide enough to keep a surface tilted away from the
+   * camera together and narrow enough to find the edge of the thing standing on it.
+   */
+  readonly depthTolerance?: number;
+  /** The exponent on `max(dot(n, n'), 0)`. Higher keeps the filter inside one face. */
+  readonly normalSharpness?: number;
+}
+
+const DEFAULT_DEPTH_TOLERANCE = 0.1;
+const DEFAULT_NORMAL_SHARPNESS = 32;
+
+/**
+ * The five-tap row, which is the kernel a separable à-trous pass runs twice.
+ *
+ * `[1, 4, 6, 4, 1] / 16`, a binomial — the discrete Gaussian, and the one every implementation of
+ * this uses. It is written here rather than computed so a reader can see that it is symmetric and
+ * that it sums to one *before* any of the edge-stopping weights touch it.
+ */
+const KERNEL = [1 / 16, 4 / 16, 6 / 16, 4 / 16, 1 / 16];
+
+/**
+ * How far apart the taps go, for light that came from each level of the chain.
+ *
+ * **Task 6's `source` discriminant is what this is for**, and it is the reason that field is on
+ * `IndirectResult` at all. A sample the screen answered is as sharp as the frame it came from and
+ * wants the narrowest filter there is. One the world field answered stands for a cone's worth of
+ * surface. One the probes answered is already an interpolation over metres, and filtering it
+ * narrowly buys nothing — its noise is not at pixel scale.
+ *
+ * Filtering all three at one width either smears the sharp one or leaves the coarse one noisy, and
+ * which of those a viewer notices depends on where they are standing.
+ */
+export function filterStepFor(source: GiSource): number {
+  return source === 0 ? 1 : source === 1 ? 2 : 4;
+}
+
+/** Scratch, because a filter pass is per pixel and the rule about allocating in one is absolute. */
+const TOTAL = new Float32Array(3);
+const CLIPPED: Rgb = [0, 0, 0];
+
+/**
+ * One separable, edge-stopping pass over a frame.
+ *
+ * **The weights are renormalised by their own sum, and that is the line this module exists to get
+ * right.** A tap rejected for being on the other side of an edge has to be *removed from the
+ * average*, not set to zero and left in the denominator — the second darkens every silhouette by
+ * however much of its kernel fell off the surface, which looks like contact shadowing and is the
+ * filter eating light. `energy.test.ts` makes the same argument about the probe blend one level up.
+ */
+export function spatialDenoise(
+  frame: DenoiseFrame,
+  options: SpatialOptions,
+  out: Float32Array,
+): void {
+  const depthTolerance = options.depthTolerance ?? DEFAULT_DEPTH_TOLERANCE;
+  const normalSharpness = options.normalSharpness ?? DEFAULT_NORMAL_SHARPNESS;
+
+  /* Horizontal into `out`, then vertical in place. Separable, so a five-tap kernel is ten taps
+     rather than twenty-five, and the two halves cannot disagree because they are one function. */
+  pass(frame, frame.radiance, out, options.step, depthTolerance, normalSharpness, true);
+  pass(frame, out, out, options.step, depthTolerance, normalSharpness, false);
+}
+
+function pass(
+  frame: DenoiseFrame,
+  input: Float32Array,
+  out: Float32Array,
+  step: number,
+  depthTolerance: number,
+  normalSharpness: number,
+  horizontal: boolean,
+): void {
+  const { width, height, depth, normal, source } = frame;
+  /*
+   * A second pass reading its own output would filter the taps it has already written, which is a
+   * wider and lopsided kernel rather than the one declared. Copied when the two alias.
+   */
+  const read = input === out ? new Float32Array(out) : input;
+
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      const at = y * width + x;
+      const centreDepth = depth[at] as number;
+      const nx = normal[at * 3] as number;
+      const ny = normal[at * 3 + 1] as number;
+      const nz = normal[at * 3 + 2] as number;
+      const spacing = Math.max(1, Math.round(step * filterStepFor(source[at] as GiSource)));
+
+      TOTAL.fill(0);
+      let weightSum = 0;
+      for (let tap = 0; tap < KERNEL.length; tap++) {
+        const offset = (tap - 2) * spacing;
+        const sx = horizontal ? x + offset : x;
+        const sy = horizontal ? y : y + offset;
+        if (sx < 0 || sx >= width || sy < 0 || sy >= height) continue;
+        const from = sy * width + sx;
+
+        /* A pixel that drew nothing has no surface to share light with. */
+        const tapDepth = depth[from] as number;
+        if (!Number.isFinite(tapDepth) || !Number.isFinite(centreDepth)) {
+          if (from !== at) continue;
+        }
+
+        const reference = Math.max(Math.abs(centreDepth), 1e-3);
+        const apart = Math.abs(tapDepth - centreDepth) / reference;
+        if (apart > depthTolerance) continue;
+
+        const alignment =
+          nx * (normal[from * 3] as number) +
+          ny * (normal[from * 3 + 1] as number) +
+          nz * (normal[from * 3 + 2] as number);
+        const facing = Math.max(alignment, 0) ** normalSharpness;
+        if (facing <= 1e-6) continue;
+
+        const weight = (KERNEL[tap] as number) * facing;
+        TOTAL[0] = (TOTAL[0] as number) + (read[from * 3] as number) * weight;
+        TOTAL[1] = (TOTAL[1] as number) + (read[from * 3 + 1] as number) * weight;
+        TOTAL[2] = (TOTAL[2] as number) + (read[from * 3 + 2] as number) * weight;
+        weightSum += weight;
+      }
+
+      if (weightSum > 0) {
+        out[at * 3] = (TOTAL[0] as number) / weightSum;
+        out[at * 3 + 1] = (TOTAL[1] as number) / weightSum;
+        out[at * 3 + 2] = (TOTAL[2] as number) / weightSum;
+      } else {
+        /* Every neighbour was rejected, including itself: keep what was there rather than black. */
+        out[at * 3] = read[at * 3] as number;
+        out[at * 3 + 1] = read[at * 3 + 1] as number;
+        out[at * 3 + 2] = read[at * 3 + 2] as number;
+      }
+    }
+  }
+}
+
+/**
+ * The least weight this frame may be given, however long a pixel has been accumulating.
+ *
+ * **An honest running mean converges and then stops listening.** One over the count is the
+ * unbiased average of everything seen, which is exactly what is wanted while a pixel is settling
+ * and exactly wrong once the world changes: at ten thousand frames a new value moves the answer by
+ * a ten-thousandth, so a light switched on takes minutes to arrive. A twentieth is the floor, which
+ * is about a third of a second at sixty frames and is the same order as
+ * `TEMPORAL_HISTORY_BLEND`'s own one-tenth.
+ */
+export const DENOISE_MIN_ALPHA = 0.05;
+
+/** What a pixel carries between frames. The caller owns one per pixel. */
+export interface TemporalPixel {
+  /** The accumulated answer. */
+  readonly value: Float32Array;
+  /** How many frames have contributed since the last disocclusion. */
+  samples: number;
+}
+
+export function newTemporalPixel(): TemporalPixel {
+  return { value: new Float32Array(3), samples: 0 };
+}
+
+/**
+ * Blend this frame into the history a caller reprojected, and answer how much history there is.
+ *
+ * `history` is where this pixel was last frame, already reprojected — **this module does not do
+ * that and is not the place for it.** `disoccluded` says the reprojection landed on something that
+ * is no longer there; `neighbourhood`, when supplied, is the box of colours actually around this
+ * pixel this frame, and the history is clipped into it by `temporalAa.ts`'s own function.
+ *
+ * **A disocclusion resets rather than blends.** It is not a stale history, it is a wrong one: a
+ * character stepping away from a wall uncovers pixels whose history is the character, and blending
+ * nine parts of that is a smear of them that follows them about. Resetting leaves one frame of
+ * noise, which the spatial pass has already reduced and which is gone by the next frame.
+ */
+export function temporalDenoise(
+  current: readonly [number, number, number] | Float32Array,
+  history: readonly [number, number, number] | Float32Array,
+  neighbourhood: {
+    readonly min: readonly [number, number, number];
+    readonly max: readonly [number, number, number];
+  } | null,
+  disoccluded: boolean,
+  pixel: TemporalPixel,
+  out: Float32Array,
+): TemporalPixel {
+  if (disoccluded) {
+    pixel.samples = 1;
+    for (let c = 0; c < 3; c++) {
+      pixel.value[c] = current[c] as number;
+      out[c] = current[c] as number;
+    }
+    return pixel;
+  }
+
+  let hx = history[0] as number;
+  let hy = history[1] as number;
+  let hz = history[2] as number;
+  if (neighbourhood !== null) {
+    clipToNeighbourhood(CLIPPED, [hx, hy, hz], neighbourhood.min, neighbourhood.max);
+    hx = CLIPPED[0];
+    hy = CLIPPED[1];
+    hz = CLIPPED[2];
+  }
+
+  /*
+   * One over the count while a pixel is settling, so what comes out is the unbiased mean of
+   * everything it has seen rather than a blend biased toward whatever it started at — which is the
+   * difference between converging *to* the noisy mean and converging near it. The floor is what
+   * keeps a settled pixel able to notice the world changing; see `DENOISE_MIN_ALPHA`.
+   */
+  const samples = pixel.samples + 1;
+  const alpha = Math.max(1 / samples, DENOISE_MIN_ALPHA);
+  pixel.samples = samples;
+
+  const blended = [hx, hy, hz];
+  for (let c = 0; c < 3; c++) {
+    const value =
+      (blended[c] as number) + ((current[c] as number) - (blended[c] as number)) * alpha;
+    pixel.value[c] = value;
+    out[c] = value;
+  }
+  return pixel;
+}