@driftengine/core 4.4.2 → 4.6.0

package/src/render/recon/resolve.ts

@@ -30,6 +30,29 @@
  *    the render read bicubically fills the gap. The history keeps colour and weight; the picture shown
  *    is it sharpened.
  *
+ * **And the temporal resolve's anti-flicker, where the caller carries its records** (`temporalAa.ts`
+ * says why it works and what it gives up). A thread finer than a render texel is caught in some
+ * phases of the jitter and missed in others, and in a phase that misses it the nine texels can all
+ * miss it: the box collapses onto what is behind, the history is clipped out, and a still picture
+ * flashes at every fine edge each period. A still camera over a still scene gathers every pixel the
+ * same way each period, so each pixel keeps a record of this frame's gathered luma over the period,
+ * and once two periods running have repeated its box widens by its own spread and it keeps more of
+ * its history. **The record stays at the pixel rather than following the reprojection**, because the
+ * proof is only ever for a pixel that has not moved; it starts over wherever the history did not
+ * survive, and is forgotten in proportion to motion.
+ *
+ * **And a still pixel whose depth has been seen to swing is not a disocclusion.** A rail finer than
+ * a texel in front of a wall is caught in some phases and missed in others, so last frame can hold
+ * the wall where this frame holds the rail with nothing moved — and the depth test threw the history
+ * away, leaving the record nothing to keep. So each pixel also keeps the largest relative miss of
+ * last frame's depth it has seen lately, kept whatever the test says, and while still its tolerance
+ * widens to `DEPTH_SWING_WIDTH` of it — the temporal resolve's answer to a crack of light round a
+ * door, as a held peak rather than its running mean: a rail caught in one phase of eighteen misses
+ * once a period, and a mean has worn that miss down to a thirtieth by the next. **What it gives up**
+ * is the depth test's word at such a pixel while still: a surface arriving there inside the swing
+ * keeps the history, and the neighbourhood clip, which the unproven sample of an arrival leaves
+ * unwidened, is what takes it out.
+ *
  * **Conventions.** Images are rows from `v = 0` upward. Depths are clip depths in the matrices'
  * convention, OpenGL's here — the nearest is the smallest — and the renderer converts its reversed
  * buffer before a sample reaches this arithmetic, as the temporal resolve already does.
@@ -44,6 +67,16 @@ import {
 } from './disocclusion.ts';
 import type { DisocclusionParams } from './disocclusion.ts';
 import { sampleBilinear, sampleHistoryBicubic5 } from './reproject.ts';
+import {
+  TEMPORAL_FLICKER,
+  flickerBlend,
+  flickerRule,
+  flickerWidening,
+  freshFlicker,
+  nextFlicker,
+  stillness,
+} from '../temporalAa.ts';
+import type { Flicker, FlickerRule } from '../temporalAa.ts';
 
 /** What a reconstruction is asked for. */
 export interface ReconQuality {
@@ -140,6 +173,12 @@ export interface ResolveFrame {
   readonly inverseViewProj: ArrayLike<number>;
   /** Last frame's view-projection and its inverse, unjittered. */
   readonly previousViewProj: ArrayLike<number>;
+  /**
+   * Last frame's view-projection times this frame's inverse: where a texel's clip position was
+   * last frame. Derived from the two when absent; a caller holding its matrices at a lower precision
+   * than it multiplies at passes its own product, as the renderer does.
+   */
+  readonly reprojection?: ArrayLike<number>;
   readonly previousInverseViewProj: ArrayLike<number>;
   readonly eye: ArrayLike<number>;
   readonly previousEye: ArrayLike<number>;
@@ -148,6 +187,22 @@ export interface ResolveFrame {
   readonly previousJitter: ArrayLike<number>;
   readonly quality: ReconQuality;
   readonly disocclusion: DisocclusionParams;
+  /**
+   * Last frame's flicker records, output size, four floats a pixel — the spread, this period's
+   * running sum, the last period's mean, and how many periods running repeated, as `Flicker` holds
+   * them — or absent for the resolve without its anti-flicker.
+   */
+  readonly flicker?: ArrayLike<number> | null;
+  /**
+   * Last frame's depth swings, output size, one float a pixel: the largest miss, relative to the
+   * depth, of last frame's depth against the one this pixel's surface should have had, seen lately
+   * — held, and halving over a period. Carried with `flicker` and read only with it.
+   */
+  readonly depthSwing?: ArrayLike<number> | null;
+  /** Whether this frame samples the first phase of the jitter's period. */
+  readonly periodStart?: boolean;
+  /** The jitter's period: the reconstruction's own phase count, not the temporal resolve's. */
+  readonly flickerPhases?: number;
 }
 
 /**
@@ -170,6 +225,13 @@ export function reconstructionWeight(dx: number, dy: number): number {
  */
 export const CONFIDENT_WEIGHT = 1;
 
+/**
+ * How many of its held depth swings a still pixel's depth test tolerates. The peak halves over a
+ * period, so the frame before the next once-a-period miss holds just over half of it: tolerating
+ * twice the peak passes that miss outright, and three leaves the same room again.
+ */
+export const DEPTH_SWING_WIDTH = 3;
+
 const SAMPLE = new Float32Array(3);
 const GATHERED = new Float64Array(3);
 const HISTORY = new Float32Array(4);
@@ -185,6 +247,36 @@ const UP = new Float64Array(3);
 const NORMAL = new Float64Array(3);
 const PREVIOUS_NORMAL = new Float64Array(3);
 const CLIP = new Float64Array(4);
+/** The last frame's reprojection, derived once a frame rather than once a pixel. */
+const REPROJECTION = new Float64Array(16);
+let reprojected: ResolveFrame | null = null;
+
+/** `frame.reprojection`, or the product of its two matrices, multiplied once per frame. */
+function reprojectionOf(frame: ResolveFrame): ArrayLike<number> {
+  if (frame.reprojection !== undefined) return frame.reprojection;
+  if (reprojected !== frame) {
+    reprojected = frame;
+    const a = frame.previousViewProj;
+    const b = frame.inverseViewProj;
+    for (let c = 0; c < 4; c += 1) {
+      for (let r = 0; r < 4; r += 1) {
+        let sum = 0;
+        for (let k = 0; k < 4; k += 1) sum += (a[k * 4 + r] as number) * (b[c * 4 + k] as number);
+        REPROJECTION[c * 4 + r] = sum;
+      }
+    }
+  }
+  return REPROJECTION;
+}
+const HELD: Flicker = { spread: 0, sum: 0, mean: 0, repeated: 0 };
+const CARRIED: Flicker = { spread: 0, sum: 0, mean: 0, repeated: 0 };
+/** How far, in output pixels, the last `historyWeight` found its surface had moved. */
+let moved = 0;
+/** How far, relative, last frame's depth missed the one expected there; -1 where nothing was held. */
+let missed = -1;
+/** The rule for the last period asked for, kept: one is made per period, not per pixel. */
+let rulePhases = 0;
+let rule: FlickerRule = TEMPORAL_FLICKER;
 
 function clampTexel(value: number, size: number): number {
   return value < 0 ? 0 : value >= size ? size - 1 : value;
@@ -296,7 +388,15 @@ function normalAt(
  * was behind last frame's eye or off its picture, and otherwise what it gathered, scaled by whether it
  * is the same surface. Reads `HISTORY`; writes the history's colour there.
  */
-function historyWeight(frame: ResolveFrame, u: number, v: number, dx: number, dy: number): number {
+function historyWeight(
+  frame: ResolveFrame,
+  u: number,
+  v: number,
+  dx: number,
+  dy: number,
+  swing: number,
+): number {
+  missed = -1;
   if (!frame.hasHistory) return 0;
   const rw = frame.renderWidth;
   const rh = frame.renderHeight;
@@ -309,28 +409,46 @@ function historyWeight(frame: ResolveFrame, u: number, v: number, dx: number, dy
     mv = frame.motion[flagAt + 1] as number;
     expected = frame.motion[flagAt + 2] as number;
   } else {
-    if (worldAt(frame.depth, frame.inverseViewProj, frame.jitter, rw, rh, dx, dy, WORLD) <= 0) {
-      return 0;
-    }
-    const m = frame.previousViewProj;
+    /*
+     * **Through one matrix, last frame's view-projection times this frame's inverse**, rather than
+     * out to a world position and back. The two are the same arithmetic in exact numbers; in single
+     * precision the round trip is not the identity — a near plane a quarter of a metre from a far one
+     * five kilometres off — and a still camera measured a few hundredths of a pixel of motion growing
+     * out from the middle of the frame, which crept every still history and kept every pixel from
+     * the anti-flicker's stillness. The product is taken where the precision is (`reprojection`),
+     * and for a still camera it is the identity.
+     */
+    const du = (dx + 0.5 - (frame.jitter[0] as number)) / rw;
+    const dv = (dy + 0.5 - (frame.jitter[1] as number)) / rh;
+    const x = du * 2 - 1;
+    const y = dv * 2 - 1;
+    const z = frame.depth[dy * rw + dx] as number;
+    const inverse = frame.inverseViewProj;
+    /* The homogeneous w of the world position: none, or behind the eye, is no surface. */
+    const hw =
+      (inverse[3] as number) * x +
+      (inverse[7] as number) * y +
+      (inverse[11] as number) * z +
+      (inverse[15] as number);
+    if (!(hw > 1e-12)) return 0;
+    const m = reprojectionOf(frame);
     for (let r = 0; r < 4; r += 1) {
       CLIP[r] =
-        (m[r] as number) * (WORLD[0] as number) +
-        (m[4 + r] as number) * (WORLD[1] as number) +
-        (m[8 + r] as number) * (WORLD[2] as number) +
+        (m[r] as number) * x +
+        (m[4 + r] as number) * y +
+        (m[8 + r] as number) * z +
         (m[12 + r] as number);
     }
     /*
      * A surface behind last frame's eye has a w that is not positive: the disocclusion trusts no
      * such depth, so it needs no refusal of its own here.
      */
-    expected = CLIP[3] as number;
-    const du = (dx + 0.5 - (frame.jitter[0] as number)) / rw;
-    const dv = (dy + 0.5 - (frame.jitter[1] as number)) / rh;
-    mu = ((CLIP[0] as number) / expected) * 0.5 + 0.5 - du;
-    mv = ((CLIP[1] as number) / expected) * 0.5 + 0.5 - dv;
+    expected = (CLIP[3] as number) / hw;
+    mu = ((CLIP[0] as number) / (CLIP[3] as number)) * 0.5 + 0.5 - du;
+    mv = ((CLIP[1] as number) / (CLIP[3] as number)) * 0.5 + 0.5 - dv;
   }
 
+  moved = Math.hypot(mu * frame.outputWidth, mv * frame.outputHeight);
   const pu = u + mu;
   const pv = v + mv;
   if (!(pu >= 0 && pu <= 1 && pv >= 0 && pv <= 1)) return 0;
@@ -440,22 +558,32 @@ function historyWeight(frame: ResolveFrame, u: number, v: number, dx: number, dy
       (NORMAL[2] as number) * (PREVIOUS_NORMAL[2] as number);
     normalDot = 1 - planar * (1 - cosine);
   }
+  if (held > 0 && expected > 0) missed = Math.abs(held - expected) / expected;
+  /* A still pixel's own depth swing, as wide as the anti-flicker's box: see the header. */
+  const swung = swing > 0 ? DEPTH_SWING_WIDTH * swing * stillness(moved) : 0;
   const trust = disocclusionWeight(
     expected,
     held,
     Math.hypot(mu, mv),
     normalDot,
     frame.disocclusion,
-    slope,
+    slope + swung,
   );
   return (HISTORY[3] as number) * trust;
 }
 
 /**
  * One output pixel: the history's next colour, before sharpening, and the weight it has gathered —
- * four values into `out`.
+ * four values into `out` — and, where the frame carries records, the pixel's next one into `record`.
  */
-export function resolvePixel(frame: ResolveFrame, ox: number, oy: number, out: Float32Array): void {
+export function resolvePixel(
+  frame: ResolveFrame,
+  ox: number,
+  oy: number,
+  out: Float32Array,
+  record?: Float32Array,
+  swingOut?: Float32Array,
+): void {
   const rw = frame.renderWidth;
   const rh = frame.renderHeight;
   const ow = frame.outputWidth;
@@ -508,8 +636,58 @@ export function resolvePixel(frame: ResolveFrame, ox: number, oy: number, out: F
   for (let c = 0; c < 3; c += 1) GATHERED[c] = (GATHERED[c] as number) / gathered;
 
   /* 3 and 4. The history, and the weight it still deserves. */
-  const cap = (1 - frame.quality.alpha) / frame.quality.alpha;
-  const kept = Math.min(cap, historyWeight(frame, u, v, dx, dy));
+  const alpha = frame.quality.alpha;
+  const records = frame.flicker;
+  const anti = records !== undefined && records !== null;
+  if (anti) {
+    const phases = frame.flickerPhases ?? 0;
+    if (phases !== rulePhases) {
+      rulePhases = phases;
+      rule = phases > 0 ? flickerRule(phases) : TEMPORAL_FLICKER;
+    }
+  }
+  const swings = frame.depthSwing;
+  const swing =
+    anti && swings !== undefined && swings !== null ? (swings[oy * ow + ox] as number) : 0;
+  const weight = historyWeight(frame, u, v, dx, dy, swing);
+  let cap = (1 - alpha) / alpha;
+  /* The anti-flicker: a proven pixel's box widened by its spread, and more of its history kept. */
+  if (anti) {
+    const sample =
+      (GATHERED[0] as number) * 0.2126 +
+      (GATHERED[1] as number) * 0.7152 +
+      (GATHERED[2] as number) * 0.0722;
+    const at = (oy * ow + ox) * 4;
+    if (weight > 0) {
+      HELD.spread = records[at] as number;
+      HELD.sum = records[at + 1] as number;
+      HELD.mean = records[at + 2] as number;
+      HELD.repeated = records[at + 3] as number;
+    } else {
+      freshFlicker(HELD, sample, rule);
+    }
+    const still = weight > 0 ? stillness(moved) : 0;
+    const widen = flickerWidening(HELD, sample, still, rule);
+    for (let c = 0; c < 3; c += 1) {
+      LOW[c] = (LOW[c] as number) - widen;
+      HIGH[c] = (HIGH[c] as number) + widen;
+    }
+    const keep = flickerBlend(1 - alpha, HELD, sample, still, rule);
+    cap = keep / (1 - keep);
+    nextFlicker(CARRIED, HELD, sample, still, frame.periodStart === true, rule);
+    if (record !== undefined) {
+      record[0] = CARRIED.spread;
+      record[1] = CARRIED.sum;
+      record[2] = CARRIED.mean;
+      record[3] = CARRIED.repeated;
+    }
+    /* The peak carried on, halving over a period, whatever the test said; none where nothing was
+       held to miss. */
+    if (swingOut !== undefined) {
+      swingOut[0] = missed >= 0 ? Math.max(missed, swing * 0.5 ** rule.memory) : 0;
+    }
+  }
+  const kept = Math.min(cap, weight);
 
   /* 5. Clipped, mixed by weight, and the gaps filled from the render. */
   const total = kept + gathered;
@@ -529,6 +707,8 @@ export function resolvePixel(frame: ResolveFrame, ox: number, oy: number, out: F
 }
 
 const TAP = new Float32Array(4);
+const RECORD = new Float32Array(4);
+const SWING = new Float32Array(1);
 const CENTRE = new Float32Array(4);
 const AROUND = new Float32Array(12);
 const SHOWN = new Float32Array(3);
@@ -541,19 +721,25 @@ const OFFSETS: readonly (readonly [number, number])[] = [
 
 /**
  * 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.
+ * `shown`, three — the history sharpened against the four direct neighbours it has just been given —
+ * and, where the frame carries records, the next ones into `records`, four floats a pixel, and the
+ * next depth swings into `swings`, one.
  */
 export function resolveFrame(
   frame: ResolveFrame,
   history: Float32Array,
   shown: Float32Array,
+  records?: Float32Array,
+  swings?: Float32Array,
 ): void {
   const ow = frame.outputWidth;
   const oh = frame.outputHeight;
   for (let y = 0; y < oh; y += 1) {
     for (let x = 0; x < ow; x += 1) {
-      resolvePixel(frame, x, y, TAP);
+      resolvePixel(frame, x, y, TAP, RECORD, SWING);
       history.set(TAP, (y * ow + x) * 4);
+      if (records !== undefined) records.set(RECORD, (y * ow + x) * 4);
+      if (swings !== undefined) swings[y * ow + x] = SWING[0] as number;
     }
   }
   for (let y = 0; y < oh; y += 1) {

package/src/render/renderQuality.ts

@@ -37,6 +37,9 @@ export type ShadowFilterTaps = 4 | 8 | 12;
 export type DirectionalShadowDepthLayers = 1 | 2;
 export type WaterReflectionFilterTaps = 1 | 5 | 9;
 
+/** How light through glass is coloured: see `RenderQuality.glassShadows`. */
+export type GlassShadows = 'full' | 'half' | 'off';
+
 export interface RenderQuality {
   /**
    * The transfer curve applied at the end of every shaded pass.
@@ -149,6 +152,25 @@ export interface RenderQuality {
   readonly lightVolumeSamples: number;
   /** Independently composited static sun depths; two preserves common overlaps. */
   readonly directionalShadowDepthLayers: DirectionalShadowDepthLayers;
+  /**
+   * Whether light through glass takes the glass's colour, and at what size.
+   *
+   * **`'full'`, the default**: every shadow a glass caster reaches gains a layer holding the depth of
+   * the nearest pane and a tint layer holding what the panes let through, at the size of the depth
+   * map beside it — 8 bytes a texel, so 32 MB for a 2048 sun map and 8 MB for a 1024 lamp layer.
+   * **`'half'`** halves the tint layers only (the glass depth must match its array): 20 MB and 5 MB,
+   * and a coloured patch softer than an opaque shadow's edge. **`'off'`** is glass before this
+   * existed: a pane casts nothing at all.
+   *
+   * Nothing is allocated until a glass caster first reaches a shadow, so a scene with no glass pays
+   * no memory and no pass whatever this says. **The lit shader is the exception**: `'full'` and
+   * `'half'` compile the glass lookup into it, and a lookup that finds no glass and returns at its
+   * first line still costs the lit pass its registers — measured on the courtyard at night, 0.27 ms
+   * at 720p on WebGPU, 0.42 ms on WebGL2 and 1.2 ms at 4K. `'off'` compiles none of it, so a world
+   * that never casts through glass is that much faster for saying so. What would make `'full'` wrong
+   * is a phone budget with a lot of glass; that is what `'half'` is for. See `glassShadow.ts`.
+   */
+  readonly glassShadows: GlassShadows;
   /** Horizontal world-space reach over which a directional shadow dissolves. */
   readonly directionalShadowMaxDistance: number;
   /** Maximum horizontal projection per vertical metre before low-angle shadows vanish. */
@@ -556,6 +578,20 @@ export interface RenderQuality {
    * the render is a quarter of the output and no reconstruction holds an edge through that. A
    * negative number is off, not a clamp to the bottom: it cannot mean "a little".
    *
+   * **What it needs from you.** A `createMover()` per moving object, passed with that object's
+   * draws where `drawMesh` takes last frame's matrix — the renderer keeps last frame's model and,
+   * for a skinned draw, last frame's pose. Instanced batches and meshes rewritten with
+   * `updateMesh` need nothing: the batch and the mesh are their own identity. And `cameraCut()` at
+   * every cut, because nothing detects one: without it a cut blends the previous shot into the
+   * next. Blended draws — translucent meshes, particles, plumes, film, bolts, lines, world text —
+   * are drawn after the upscale at the output size and need nothing either; light volumes stay in
+   * the reconstructed picture, being a march that keeps its history.
+   *
+   * **What it cannot give back** is the resolution it draws at: an edge that never moves is softer
+   * than a native frame's at any ratio, because two thirds of the pixels at 1.5 are a guess made
+   * sharp. Measured on `demo/dev/ghost.html` against a native frame at four samples, still edges
+   * err by about 8 levels where a native frame at one sample errs by 3.
+   *
    * `?recon=` is how it gets A/B'd in one reload.
    */
   readonly reconstruction: number;
@@ -838,6 +874,7 @@ export const DEFAULT_RENDER_QUALITY: Readonly<RenderQuality> = Object.freeze({
   shadowFilterTaps: MAX_SHADOW_FILTER_TAPS,
   lightVolumeSamples: 32,
   directionalShadowDepthLayers: 2,
+  glassShadows: 'full',
   directionalShadowMaxDistance: 6,
   directionalShadowMaxSlope: 3,
   pointShadowRebakeDistance: 0.001,
@@ -998,6 +1035,7 @@ export function resolveRenderQuality(options: RenderQualityOptions = {}): Readon
     lightVolumeSamples: options.lightVolumeSamples ?? DEFAULT_RENDER_QUALITY.lightVolumeSamples,
     directionalShadowDepthLayers:
       options.directionalShadowDepthLayers ?? DEFAULT_RENDER_QUALITY.directionalShadowDepthLayers,
+    glassShadows: options.glassShadows ?? DEFAULT_RENDER_QUALITY.glassShadows,
     directionalShadowMaxDistance:
       options.directionalShadowMaxDistance ?? DEFAULT_RENDER_QUALITY.directionalShadowMaxDistance,
     directionalShadowMaxSlope:
@@ -1128,6 +1166,15 @@ export function resolveRenderQuality(options: RenderQualityOptions = {}): Readon
       `RenderQuality.directionalShadowDepthLayers must be 1 or 2, got ${quality.directionalShadowDepthLayers}`,
     );
   }
+  if (
+    quality.glassShadows !== 'full' &&
+    quality.glassShadows !== 'half' &&
+    quality.glassShadows !== 'off'
+  ) {
+    throw new Error(
+      `RenderQuality.glassShadows must be 'full', 'half' or 'off', got ${String(quality.glassShadows)}`,
+    );
+  }
   if (quality.plumeNoiseOctaves > 3) {
     throw new Error(
       `RenderQuality.plumeNoiseOctaves must be <= 3, got ${quality.plumeNoiseOctaves}`,

package/src/render/rendererHarness.ts

@@ -72,6 +72,10 @@ export function recordingGl(
   const programFragments = new WeakMap<object, string>();
   const calls: { name: string; args: unknown[] }[] = [];
   const constants: Record<string, number> = {
+    /* The canvas's size, as a real context reports its drawing buffer; a function here made every
+       jitter and every per-pixel offset divided by it a NaN. */
+    drawingBufferWidth: 640,
+    drawingBufferHeight: 480,
     ACTIVE_UNIFORMS: 0x8b86,
     ACTIVE_ATTRIBUTES: 0x8b89,
     COMPILE_STATUS: 0x8b81,
@@ -129,6 +133,18 @@ export function recordingGl(
     COLOR_BUFFER_BIT: 0x00004000,
     /* Named so a test can tell a mesh that declared itself deforming from one that did not. */
     ARRAY_BUFFER: 0x8892,
+    /* Named so a blend a pass sets can be read back as numbers: glass multiplies what it lets
+       through, and a test that cannot tell DST_COLOR from a recorder cannot tell it multiplies. */
+    ZERO: 0,
+    DST_ALPHA: 0x0304,
+    DST_COLOR: 0x0306,
+    FUNC_ADD: 0x8006,
+    COLOR: 0x1800,
+    DEPTH: 0x1801,
+    /* Named so a copy can be read as from-and-to: a blit's two framebuffers are the whole claim. */
+    READ_FRAMEBUFFER: 0x8ca8,
+    DRAW_FRAMEBUFFER: 0x8ca9,
+    BLEND: 0x0be2,
     STATIC_DRAW: 0x88e4,
     DYNAMIC_DRAW: 0x88e8,
   };

package/src/render/sceneTarget.ts

@@ -82,6 +82,8 @@ export class SceneTarget {
   private colorCopyFramebuffer: WebGLFramebuffer | null = null;
   /** Whether this frame has filled it. One snapshot serves every refracting draw in a frame. */
   private colorCopyFilled = false;
+  /** Whether this frame's copy has its mip chain, which frosted glass reads. See `snapshotColor`. */
+  private colorCopyMips = false;
   /**
    * The colour grade, as a 3D texture on unit 4, and the table it was built from.
    *
@@ -275,12 +277,24 @@ export class SceneTarget {
      */
     if (this.colorCopy === null) this.colorCopy = gl.createTexture();
     gl.bindTexture(gl.TEXTURE_2D, this.colorCopy);
-    if (this.floatColor) {
-      gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA16F, width, height, 0, gl.RGBA, gl.HALF_FLOAT, null);
-    } else {
-      gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, width, height, 0, gl.RGBA, gl.UNSIGNED_BYTE, null);
+    /*
+     * **Every level, so glass can read a blurrier one.** Frosted glass reads the copy at a level its
+     * frost picks, and a texture sampled through a mipmapping filter with a level missing is
+     * incomplete and reads black — so the chain is allocated here, once per size, and filled only on
+     * a frame that draws glass (`snapshotColor`). Plain refraction reads level 0, as it always has.
+     */
+    const levels = Math.floor(Math.log2(Math.max(width, height))) + 1;
+    for (let level = 0; level < levels; level += 1) {
+      const w = Math.max(1, width >> level);
+      const h = Math.max(1, height >> level);
+      if (this.floatColor) {
+        gl.texImage2D(gl.TEXTURE_2D, level, gl.RGBA16F, w, h, 0, gl.RGBA, gl.HALF_FLOAT, null);
+      } else {
+        gl.texImage2D(gl.TEXTURE_2D, level, gl.RGBA, w, h, 0, gl.RGBA, gl.UNSIGNED_BYTE, null);
+      }
     }
-    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAX_LEVEL, levels - 1);
+    gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR_MIPMAP_LINEAR);
     gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
     gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
     gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
@@ -419,6 +433,7 @@ export class SceneTarget {
     /* Last frame's snapshot is last frame's scene. See `snapshotDepth`. */
     this.depthCopyFilled = false;
     this.colorCopyFilled = false;
+    this.colorCopyMips = false;
     this.bind();
   }
 
@@ -516,12 +531,21 @@ export class SceneTarget {
    * Null where the copy could not be made, and a caller must read that as "do not refract" rather
    * than as a black texture — refracting against black paints every pane the colour of a hole.
    */
-  snapshotColor(afresh = false): WebGLTexture | null {
+  snapshotColor(
+    afresh = false,
+    /** Fill the copy's mip chain as well, once a frame: what frosted glass reads. */
+    mips = false,
+  ): WebGLTexture | null {
     if (this.colorCopy === null || this.colorCopyFramebuffer === null) return null;
-    if (this.colorCopyFilled && !afresh) return this.colorCopy;
+    if (this.colorCopyFilled && !afresh) {
+      if (mips) this.fillColorCopyMips();
+      return this.colorCopy;
+    }
     const { gl } = this;
     const source = this.msaaFramebuffer ?? this.framebuffer;
     if (source === null) return null;
+    const drawing = gl.getParameter(gl.DRAW_FRAMEBUFFER_BINDING) as WebGLFramebuffer | null;
+    const reading = gl.getParameter(gl.READ_FRAMEBUFFER_BINDING) as WebGLFramebuffer | null;
 
     gl.bindFramebuffer(gl.READ_FRAMEBUFFER, source);
     gl.bindFramebuffer(gl.DRAW_FRAMEBUFFER, this.colorCopyFramebuffer);
@@ -546,13 +570,33 @@ export class SceneTarget {
       gl.NEAREST,
     );
     const refused = gl.getError() !== gl.NO_ERROR;
-    /* Back to what the caller was drawing into, whichever that was. */
-    gl.bindFramebuffer(gl.FRAMEBUFFER, source);
+    /*
+     * **Back to what the caller was drawing into, whichever that was** — read before the copy and
+     * handed back, never assumed. It was the scene's framebuffer, assumed, and a pane drawn into a
+     * reflection probe's face then left the scene's bound: the probe attached its next face to it,
+     * a face-sized colour beside a screen-sized depth, and every draw after refused as incomplete.
+     */
+    gl.bindFramebuffer(gl.DRAW_FRAMEBUFFER, drawing);
+    gl.bindFramebuffer(gl.READ_FRAMEBUFFER, reading);
     if (refused) return null;
     this.colorCopyFilled = true;
+    this.colorCopyMips = false;
+    if (mips) this.fillColorCopyMips();
     return this.colorCopy;
   }
 
+  /** The copy's mip chain from its level 0, once per copy. */
+  private fillColorCopyMips(): void {
+    if (this.colorCopyMips || this.colorCopy === null) return;
+    const { gl } = this;
+    /* Bound on whichever unit is active and handed back, so the caller's texture there survives. */
+    const previous = gl.getParameter(gl.TEXTURE_BINDING_2D) as WebGLTexture | null;
+    gl.bindTexture(gl.TEXTURE_2D, this.colorCopy);
+    gl.generateMipmap(gl.TEXTURE_2D);
+    gl.bindTexture(gl.TEXTURE_2D, previous);
+    this.colorCopyMips = true;
+  }
+
   snapshotDepth(
     /**
      * Take the copy again even though one has already been taken this frame.
@@ -573,6 +617,8 @@ export class SceneTarget {
     const { gl } = this;
     const source = this.msaaFramebuffer ?? this.framebuffer;
     if (source === null) return null;
+    const drawing = gl.getParameter(gl.DRAW_FRAMEBUFFER_BINDING) as WebGLFramebuffer | null;
+    const reading = gl.getParameter(gl.READ_FRAMEBUFFER_BINDING) as WebGLFramebuffer | null;
 
     gl.bindFramebuffer(gl.READ_FRAMEBUFFER, source);
     gl.bindFramebuffer(gl.DRAW_FRAMEBUFFER, this.depthCopyFramebuffer);
@@ -595,8 +641,9 @@ export class SceneTarget {
       gl.NEAREST,
     );
     const refused = gl.getError() !== gl.NO_ERROR;
-    /* Back to what the caller was drawing into, whichever that was. */
-    gl.bindFramebuffer(gl.FRAMEBUFFER, source);
+    /* Back to what the caller was drawing into, read rather than assumed: see `snapshotColor`. */
+    gl.bindFramebuffer(gl.DRAW_FRAMEBUFFER, drawing);
+    gl.bindFramebuffer(gl.READ_FRAMEBUFFER, reading);
     if (refused) return null;
     this.depthCopyFilled = true;
     return this.depthCopy;
@@ -708,6 +755,8 @@ export class SceneTarget {
       /** The projection's x and y scales, which turn a world radius into a screen one. */
       readonly projScale: Float32Array;
       readonly invProjection: Float32Array;
+      /** Where the frame's jitter put the occlusion, in uv: see the shader's `uAoOffset`. */
+      readonly offset?: Float32Array;
     },
     bloom?: {
       readonly strength: number;
@@ -976,6 +1025,8 @@ export class SceneTarget {
       this.uniforms['uAoStrength'] ?? null,
       aoTexture === null ? 0 : (ao?.strength ?? 0),
     );
+    const offset = ao?.offset;
+    gl.uniform2f(this.uniforms['uAoOffset'] ?? null, offset?.[0] ?? 0, offset?.[1] ?? 0);
 
     /* Bloom on its own unit, and the placeholder for the same reason as the one above: a
        driver may fetch a texture's descriptor before it evaluates the branch that skips the