@driftengine/core 4.4.1 → 4.5.0

package/src/render/recon/mover.ts

@@ -0,0 +1,118 @@
+/**
+ * Which object a draw is, so a reconstruction can find where that object was last frame.
+ *
+ * **The engine cannot infer this and does not try.** `drawMesh` is immediate: a mesh drawn three
+ * times is three objects, and nothing in the call says which of last frame's three each one is. A
+ * consumer that makes one `Mover` per moving object and passes it with every draw of that object
+ * says exactly that, and the renderer keeps the rest — last frame's model and, for a skinned
+ * draw, last frame's palette.
+ *
+ * **Plain data, advanced by the renderer.** No renderer is needed to make one, so a consumer holds
+ * it beside the object it belongs to. Only a reconstructing WebGPU renderer reads or writes it; it
+ * costs nothing anywhere else. The fields past `kind` are the renderer's and a caller leaves them
+ * alone.
+ *
+ * **What would make this wrong** is a consumer whose objects are rebuilt every frame with no state
+ * of their own to hold a mover in; the identity then has to live in whatever *does* persist.
+ */
+
+export const MOVER_KIND = 'drift.mover' as const;
+
+export interface Mover {
+  readonly kind: typeof MOVER_KIND;
+  /** The renderer that last drew it, from `claimRendererId`; -1 before its first draw. */
+  renderer: number;
+  /** That renderer's frame serial at the last draw. */
+  frame: number;
+  readonly model: Float32Array;
+  readonly previousModel: Float32Array;
+  /**
+   * This frame's palette, exactly `paletteLength` floats long once a skinned draw has set it.
+   * Swapped with the previous one each frame and reallocated only when the rig changes.
+   */
+  palette: Float32Array;
+  previousPalette: Float32Array;
+  paletteLength: number;
+  previousPaletteLength: number;
+}
+
+/** Nothing to reproject from: first draw, a missed frame, another renderer, or a changed rig. */
+export const MOVER_NONE = 0;
+/** Drawn on the frame before by this renderer: `previousModel` and `previousPalette` are real. */
+export const MOVER_MOTION = 1;
+/** Drawn already this frame. The second draw is a different object and the caller's error. */
+export const MOVER_TWICE = 2;
+export type MoverVerdict = typeof MOVER_NONE | typeof MOVER_MOTION | typeof MOVER_TWICE;
+
+let nextRendererId = 1;
+
+/** A number no other renderer in this page holds, so a mover can tell renderers apart. */
+export function claimRendererId(): number {
+  const id = nextRendererId;
+  nextRendererId += 1;
+  return id;
+}
+
+export function createMover(): Mover {
+  return {
+    kind: MOVER_KIND,
+    renderer: -1,
+    frame: -2,
+    model: new Float32Array(16),
+    previousModel: new Float32Array(16),
+    palette: new Float32Array(0),
+    previousPalette: new Float32Array(0),
+    paletteLength: 0,
+    previousPaletteLength: 0,
+  };
+}
+
+export function isMover(value: unknown): value is Mover {
+  return (
+    typeof value === 'object' && value !== null && (value as { kind?: unknown }).kind === MOVER_KIND
+  );
+}
+
+/**
+ * Advance a mover to this draw, and say whether last frame's state is usable.
+ *
+ * **A second draw in one frame changes nothing**, so the first draw's motion stands; the caller
+ * warns. Otherwise what the mover held becomes its previous and this draw becomes its current —
+ * the palettes by swapping two arrays, so a steady rig allocates nothing after its first frame.
+ *
+ * **A changed joint count is no motion**: skinning a vertex with a palette of a different rig is
+ * not an old pose of this one.
+ */
+export function advanceMover(
+  mover: Mover,
+  renderer: number,
+  frame: number,
+  model: ArrayLike<number>,
+  palette: Float32Array | null,
+): MoverVerdict {
+  if (mover.renderer === renderer && mover.frame === frame) return MOVER_TWICE;
+  const drawnLast = mover.renderer === renderer && mover.frame === frame - 1;
+
+  mover.previousModel.set(mover.model);
+  const spare = mover.previousPalette;
+  mover.previousPalette = mover.palette;
+  mover.palette = spare;
+  mover.previousPaletteLength = mover.paletteLength;
+
+  mover.model.set(model);
+  if (palette === null) {
+    mover.paletteLength = 0;
+  } else {
+    /* Exactly the rig's length, because the array is uploaded as it stands; reallocated only when
+       the rig changes, which a steady character never does. */
+    if (mover.palette.length !== palette.length) mover.palette = new Float32Array(palette.length);
+    mover.palette.set(palette);
+    mover.paletteLength = palette.length;
+  }
+  mover.renderer = renderer;
+  mover.frame = frame;
+
+  if (!drawnLast) return MOVER_NONE;
+  if (mover.paletteLength !== mover.previousPaletteLength) return MOVER_NONE;
+  return MOVER_MOTION;
+}

package/src/render/recon/resolve.ts

@@ -21,8 +21,10 @@
  *    previous view depth in its third channel; otherwise it is the camera's, through the surface's
  *    world position.
  * 4. Where the surface was is read from the history — its colour and the weight it had gathered — and
- *    last frame's depth there says whether it is the same surface; the two frames' normals, from their
- *    depths, catch thin geometry. The disocclusion scales the history's weight.
+ *    last frame's depth says whether it is the same surface: the nearest of the nine texels around
+ *    where the dilated texel was, forgiven its own slope across a texel. The two frames' normals, from
+ *    their depths, catch thin geometry, each with the say its planarity gives it. The disocclusion
+ *    scales the history's weight.
  * 5. The history is clipped to the box, its weight capped so a tenth of each frame is always new, and
  *    the two are mixed by their weights. Where the pixel has gathered less than one sample's worth,
  *    the render read bicubically fills the gap. The history keeps colour and weight; the picture shown
@@ -33,7 +35,13 @@
  * buffer before a sample reaches this arithmetic, as the temporal resolve already does.
  */
 import { clipToBox, rgbToYCoCg, varianceBox, yCoCgToRgb } from './clamp.ts';
-import { disocclusionWeight, normalFromPositions, worldPositionFromDepth } from './disocclusion.ts';
+import {
+  disocclusionWeight,
+  normalFromPositions,
+  planarity,
+  surfaceSlope,
+  worldPositionFromDepth,
+} from './disocclusion.ts';
 import type { DisocclusionParams } from './disocclusion.ts';
 import { sampleBilinear, sampleHistoryBicubic5 } from './reproject.ts';
 
@@ -209,6 +217,59 @@ function worldAt(
   return 1 / w;
 }
 
+/**
+ * A texel's view depth at its unjittered uv, or 0 — `worldAt` without the position, which is all a
+ * search over depths needs: one row of the inverse rather than four. Zero off the picture, where
+ * `worldAt` would clamp, because a neighbour that is not there is not a step.
+ */
+function viewDepthAt(
+  depths: ArrayLike<number>,
+  inverse: ArrayLike<number>,
+  jitter: ArrayLike<number>,
+  width: number,
+  height: number,
+  x: number,
+  y: number,
+): number {
+  if (x < 0 || y < 0 || x >= width || y >= height) return 0;
+  const u = (x + 0.5 - (jitter[0] as number)) / width;
+  const v = (y + 0.5 - (jitter[1] as number)) / height;
+  const m = inverse;
+  const w =
+    (m[3] as number) * (u * 2 - 1) +
+    (m[7] as number) * (v * 2 - 1) +
+    (m[11] as number) * (depths[y * width + x] as number) +
+    (m[15] as number);
+  return Math.abs(w) > 1e-12 ? 1 / w : 0;
+}
+
+/** What a texel's four neighbours say about its surface: see `planarity` and `surfaceSlope`. */
+const SURFACE = { planar: 1, slope: 0 };
+
+function surfaceAt(
+  depths: ArrayLike<number>,
+  inverse: ArrayLike<number>,
+  jitter: ArrayLike<number>,
+  width: number,
+  height: number,
+  x: number,
+  y: number,
+  centre: number,
+): void {
+  let planar = 1;
+  let slope = 0;
+  for (let axis = 0; axis < 2; axis += 1) {
+    const ax = 1 - axis;
+    const ay = axis;
+    const after = viewDepthAt(depths, inverse, jitter, width, height, x + ax, y + ay);
+    const before = viewDepthAt(depths, inverse, jitter, width, height, x - ax, y - ay);
+    planar *= planarity(before, centre, after);
+    slope = Math.max(slope, surfaceSlope(before, centre, after));
+  }
+  SURFACE.planar = planar;
+  SURFACE.slope = slope;
+}
+
 /** The world normal at a texel, from its depth and its right and upper neighbours'. */
 function normalAt(
   depths: ArrayLike<number>,
@@ -282,20 +343,84 @@ function historyWeight(frame: ResolveFrame, u: number, v: number, dx: number, dy
     4,
     HISTORY,
   );
-  const px = clampTexel(Math.round(pu * rw + (frame.previousJitter[0] as number) - 0.5), rw);
-  const py = clampTexel(Math.round(pv * rh + (frame.previousJitter[1] as number) - 0.5), rh);
-  const held = worldAt(
+  /*
+   * **Last frame's depth is searched for this surface, around where the dilated texel was.** The
+   * surface being judged is the dilated texel's, which beside an edge is a neighbour's, so judging
+   * it by the texel under the pixel compares two surfaces: the side of every silhouette away from the
+   * eye dropped its history on every frame of a still picture. And a new jitter samples a surface
+   * somewhere else, so the nearest of last frame's nine is taken rather than the one the rounding
+   * picks. What it gives up is a disocclusion narrower than a texel, which keeps a history that the
+   * neighbourhood clip then bounds.
+   */
+  const su = (dx + 0.5 - (frame.jitter[0] as number)) / rw + mu;
+  const sv = (dy + 0.5 - (frame.jitter[1] as number)) / rh + mv;
+  const cx = clampTexel(Math.round(su * rw + (frame.previousJitter[0] as number) - 0.5), rw);
+  const cy = clampTexel(Math.round(sv * rh + (frame.previousJitter[1] as number) - 0.5), rh);
+  /*
+   * The first texel looked at answers alone when it agrees within the tolerance, which it does
+   * everywhere but at an edge: the depth test trusts it fully whichever texel would have won, so
+   * only an edge pays for the other eight.
+   */
+  let held = viewDepthAt(
     frame.previousDepth,
     frame.previousInverseViewProj,
     frame.previousJitter,
     rw,
     rh,
-    px,
-    py,
-    RIGHT,
+    cx,
+    cy,
   );
+  let px = cx;
+  let py = cy;
+  if (!(held > 0 && Math.abs(held - expected) <= frame.disocclusion.depthTolerance * expected)) {
+    held = 0;
+    let nearest = Number.POSITIVE_INFINITY;
+    for (let j = -1; j <= 1; j += 1) {
+      for (let i = -1; i <= 1; i += 1) {
+        const tx = clampTexel(cx + i, rw);
+        const ty = clampTexel(cy + j, rh);
+        const depth = viewDepthAt(
+          frame.previousDepth,
+          frame.previousInverseViewProj,
+          frame.previousJitter,
+          rw,
+          rh,
+          tx,
+          ty,
+        );
+        if (!(depth > 0)) continue;
+        const off = Math.abs(depth - expected);
+        if (off < nearest) {
+          nearest = off;
+          held = depth;
+          px = tx;
+          py = ty;
+        }
+      }
+    }
+  }
+
+  const here = viewDepthAt(frame.depth, frame.inverseViewProj, frame.jitter, rw, rh, dx, dy);
+  surfaceAt(frame.depth, frame.inverseViewProj, frame.jitter, rw, rh, dx, dy, here);
+  const slope = SURFACE.slope;
+  let planar = SURFACE.planar;
+  if (planar > 0) {
+    surfaceAt(
+      frame.previousDepth,
+      frame.previousInverseViewProj,
+      frame.previousJitter,
+      rw,
+      rh,
+      px,
+      py,
+      held,
+    );
+    planar *= SURFACE.planar;
+  }
+  /* A normal has the say its planarity gives it; at an edge or a sliver, none, and none is computed. */
   let normalDot = 1;
   if (
+    planar > 0 &&
     normalAt(frame.depth, frame.inverseViewProj, frame.jitter, frame.eye, rw, rh, dx, dy, NORMAL) &&
     normalAt(
       frame.previousDepth,
@@ -309,10 +434,11 @@ function historyWeight(frame: ResolveFrame, u: number, v: number, dx: number, dy
       PREVIOUS_NORMAL,
     )
   ) {
-    normalDot =
+    const cosine =
       (NORMAL[0] as number) * (PREVIOUS_NORMAL[0] as number) +
       (NORMAL[1] as number) * (PREVIOUS_NORMAL[1] as number) +
       (NORMAL[2] as number) * (PREVIOUS_NORMAL[2] as number);
+    normalDot = 1 - planar * (1 - cosine);
   }
   const trust = disocclusionWeight(
     expected,
@@ -320,6 +446,7 @@ function historyWeight(frame: ResolveFrame, u: number, v: number, dx: number, dy
     Math.hypot(mu, mv),
     normalDot,
     frame.disocclusion,
+    slope,
   );
   return (HISTORY[3] as number) * trust;
 }

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

@@ -129,6 +129,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;
@@ -743,7 +790,12 @@ export class SceneTarget {
      * `veilColor` and `veilAlpha` are positional defaults and every existing caller passes them
      * by position.
      */
-    temporal?: { readonly reprojection: Float32Array; readonly blend: number },
+    temporal?: {
+      readonly reprojection: Float32Array;
+      readonly blend: number;
+      readonly periodStart: boolean;
+      readonly depthToViewZ: Float32Array;
+    },
   ): void {
     const { gl } = this;
     this.depthWanted =
@@ -883,6 +935,8 @@ export class SceneTarget {
         this.width,
         this.height,
         temporal.blend,
+        temporal.periodStart,
+        temporal.depthToViewZ,
       );
     }