@driftengine/core 4.4.1 → 4.5.0

package/dist/render/recon/disocclusion.js

@@ -12,10 +12,15 @@
  * 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.
  *
+ * **And in proportion to the surface's own slope.** A new jitter samples a surface somewhere else, so
+ * on one turned from the eye two frames' samples of it differ by up to a texel's worth of its depth
+ * with nothing moved. `surfaceSlope` measures that step on the surface's own side of any silhouette.
+ *
  * **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.
+ * frames agree. **A normal differenced across an edge is not a normal**, so the caller weighs each by
+ * `planarity`: at an edge, a sliver, or anything finer than a texel the depth test decides alone.
  *
  * **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.
@@ -37,19 +42,66 @@ function smoothstep(edge0, edge1, x) {
     const t = Math.min(1, Math.max(0, (x - edge0) / (edge1 - edge0)));
     return t * t * (3 - 2 * t);
 }
+/**
+ * The band over which three texels stop being one plane: how far their two steps in inverse depth
+ * fail to cancel, as a share of the two together. None of it is a plane at any angle; all of it is an
+ * edge — one side steps, the other does not — or a sliver, both stepping the same way.
+ *
+ * **A share and not a size**, which is the lesson of the rods in `resolve.test.ts`: a part a
+ * hundredth of the depth in front of a wall passes the depth test, and a normal differenced across it
+ * still leans by its height over a texel's width — nearly edge-on where texels are small. What would
+ * make this wrong is a curved surface judged at its apex, where both steps lean one way and the
+ * normal is sound; there it only gives the normals less say, which the depth test does not need.
+ */
+export const PLANAR_FROM = 0.25;
+export const PLANAR_TO = 0.5;
+/**
+ * How sure it is that `centre` and its neighbours either side along one axis lie on one plane, one to
+ * zero. Inverse depth is affine across a plane on screen, so a plane's two steps cancel whatever its
+ * angle. One where a neighbour is missing — zero, off the picture or undrawn — or where there is no
+ * step to compare: nothing to judge by, so a normal keeps the say it always had.
+ */
+export function planarity(before, centre, after) {
+    if (!(before > 0) || !(centre > 0) || !(after > 0))
+        return 1;
+    const a = 1 / after - 1 / centre;
+    const b = 1 / before - 1 / centre;
+    const spread = Math.abs(a) + Math.abs(b);
+    if (!(spread > 0))
+        return 1;
+    return 1 - smoothstep(PLANAR_FROM, PLANAR_TO, Math.abs(a + b) / spread);
+}
+/**
+ * How far a surface's depth moves across one texel along an axis, relative to the depth: the smaller
+ * of the steps to its two neighbours, because beside a silhouette one of them is the surface behind.
+ * Zero at a sliver — nearer or farther than both, so each step is to another surface — and one
+ * neighbour's step where only one is there.
+ */
+export function surfaceSlope(before, centre, after) {
+    const a = after > 0 ? after - centre : Number.NaN;
+    const b = before > 0 ? before - centre : Number.NaN;
+    if (Number.isNaN(a))
+        return Number.isNaN(b) ? 0 : Math.abs(b) / centre;
+    if (Number.isNaN(b))
+        return Math.abs(a) / centre;
+    if (a * b > 0)
+        return 0;
+    return Math.min(Math.abs(a), Math.abs(b)) / centre;
+}
 /**
  * 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.
+ * length in uv; `normalDot` the cosine between the two frames' world normals there; `slope` the
+ * surface's `surfaceSlope`, which widens the tolerance one for one.
  */
-export function disocclusionWeight(currDepth, histDepth, motionLength, normalDot, params) {
+export function disocclusionWeight(currDepth, histDepth, motionLength, normalDot, params, slope = 0) {
     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 tolerance = params.depthTolerance + params.motionScale * motionLength + slope;
     const depth = 1 - smoothstep(tolerance, 2 * tolerance, disagreement);
     const normal = smoothstep(params.normalFloor, params.normalCeiling, normalDot);
     return depth * normal;

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

@@ -0,0 +1,14 @@
+/**
+ * Two decisions about one draw in a reconstructing frame, and why they are the same set.
+ *
+ * A blended draw goes **late** — after the reconstruction, at output resolution, unjittered — and a
+ * mover's motion is **tracked**, only for draws that land in the picture being reconstructed. A
+ * planar mirror and a probe bake are other pictures drawn through the same verbs, and the overlay
+ * after `endFrame` is past the picture altogether; routing any of them late, or counting a mirrored
+ * draw as a mover's second draw of the frame, would be wrong in the way that reads as a ghost.
+ *
+ * Plain booleans rather than a state object, so the per-draw call allocates nothing.
+ */
+export declare function routesLate(reconstructing: boolean, mirror: boolean, probe: boolean, presented: boolean): boolean;
+/** The same set as `routesLate`, named for the other reader. */
+export declare function tracksMotion(reconstructing: boolean, mirror: boolean, probe: boolean, presented: boolean): boolean;

package/dist/render/recon/lateRouting.js

@@ -0,0 +1,18 @@
+/**
+ * Two decisions about one draw in a reconstructing frame, and why they are the same set.
+ *
+ * A blended draw goes **late** — after the reconstruction, at output resolution, unjittered — and a
+ * mover's motion is **tracked**, only for draws that land in the picture being reconstructed. A
+ * planar mirror and a probe bake are other pictures drawn through the same verbs, and the overlay
+ * after `endFrame` is past the picture altogether; routing any of them late, or counting a mirrored
+ * draw as a mover's second draw of the frame, would be wrong in the way that reads as a ghost.
+ *
+ * Plain booleans rather than a state object, so the per-draw call allocates nothing.
+ */
+export function routesLate(reconstructing, mirror, probe, presented) {
+    return reconstructing && !mirror && !probe && !presented;
+}
+/** The same set as `routesLate`, named for the other reader. */
+export function tracksMotion(reconstructing, mirror, probe, presented) {
+    return routesLate(reconstructing, mirror, probe, presented);
+}

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

@@ -0,0 +1,57 @@
+/**
+ * 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 declare const MOVER_KIND: 'drift.mover';
+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 declare const MOVER_NONE = 0;
+/** Drawn on the frame before by this renderer: `previousModel` and `previousPalette` are real. */
+export declare const MOVER_MOTION = 1;
+/** Drawn already this frame. The second draw is a different object and the caller's error. */
+export declare const MOVER_TWICE = 2;
+export type MoverVerdict = typeof MOVER_NONE | typeof MOVER_MOTION | typeof MOVER_TWICE;
+/** A number no other renderer in this page holds, so a mover can tell renderers apart. */
+export declare function claimRendererId(): number;
+export declare function createMover(): Mover;
+export declare function isMover(value: unknown): value is Mover;
+/**
+ * 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 declare function advanceMover(mover: Mover, renderer: number, frame: number, model: ArrayLike<number>, palette: Float32Array | null): MoverVerdict;

package/dist/render/recon/mover.js

@@ -0,0 +1,86 @@
+/**
+ * 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';
+/** 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;
+let nextRendererId = 1;
+/** A number no other renderer in this page holds, so a mover can tell renderers apart. */
+export function claimRendererId() {
+    const id = nextRendererId;
+    nextRendererId += 1;
+    return id;
+}
+export function createMover() {
+    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) {
+    return (typeof value === 'object' && value !== null && value.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, renderer, frame, model, palette) {
+    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/dist/render/recon/resolve.js

@@ -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,7 @@
  * buffer before a sample reaches this arithmetic, as the temporal resolve already does.
  */
 import { clipToBox, rgbToYCoCg, varianceBox, yCoCgToRgb } from './clamp.js';
-import { disocclusionWeight, normalFromPositions, worldPositionFromDepth } from './disocclusion.js';
+import { disocclusionWeight, normalFromPositions, planarity, surfaceSlope, worldPositionFromDepth, } from './disocclusion.js';
 import { sampleBilinear, sampleHistoryBicubic5 } from './reproject.js';
 /**
  * A tenth of each frame kept, as the temporal resolve keeps; a box of a standard deviation and a
@@ -131,6 +133,39 @@ function worldAt(depths, inverse, jitter, width, height, x, y, out) {
         m[15];
     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, inverse, jitter, width, height, x, y) {
+    if (x < 0 || y < 0 || x >= width || y >= height)
+        return 0;
+    const u = (x + 0.5 - jitter[0]) / width;
+    const v = (y + 0.5 - jitter[1]) / height;
+    const m = inverse;
+    const w = m[3] * (u * 2 - 1) +
+        m[7] * (v * 2 - 1) +
+        m[11] * depths[y * width + x] +
+        m[15];
+    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, inverse, jitter, width, height, x, y, centre) {
+    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, inverse, jitter, eye, width, height, x, y, out) {
     if (worldAt(depths, inverse, jitter, width, height, x, y, WORLD) <= 0)
@@ -190,18 +225,66 @@ function historyWeight(frame, u, v, dx, dy) {
     if (!(pu >= 0 && pu <= 1 && pv >= 0 && pv <= 1))
         return 0;
     sampleHistoryBicubic5(frame.history, pu * frame.outputWidth - 0.5, pv * frame.outputHeight - 0.5, frame.outputWidth, frame.outputHeight, 4, HISTORY);
-    const px = clampTexel(Math.round(pu * rw + frame.previousJitter[0] - 0.5), rw);
-    const py = clampTexel(Math.round(pv * rh + frame.previousJitter[1] - 0.5), rh);
-    const held = worldAt(frame.previousDepth, frame.previousInverseViewProj, frame.previousJitter, rw, rh, px, py, RIGHT);
+    /*
+     * **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]) / rw + mu;
+    const sv = (dy + 0.5 - frame.jitter[1]) / rh + mv;
+    const cx = clampTexel(Math.round(su * rw + frame.previousJitter[0] - 0.5), rw);
+    const cy = clampTexel(Math.round(sv * rh + frame.previousJitter[1] - 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, 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 (normalAt(frame.depth, frame.inverseViewProj, frame.jitter, frame.eye, rw, rh, dx, dy, NORMAL) &&
+    if (planar > 0 &&
+        normalAt(frame.depth, frame.inverseViewProj, frame.jitter, frame.eye, rw, rh, dx, dy, NORMAL) &&
         normalAt(frame.previousDepth, frame.previousInverseViewProj, frame.previousJitter, frame.previousEye, rw, rh, px, py, PREVIOUS_NORMAL)) {
-        normalDot =
-            NORMAL[0] * PREVIOUS_NORMAL[0] +
-                NORMAL[1] * PREVIOUS_NORMAL[1] +
-                NORMAL[2] * PREVIOUS_NORMAL[2];
+        const cosine = NORMAL[0] * PREVIOUS_NORMAL[0] +
+            NORMAL[1] * PREVIOUS_NORMAL[1] +
+            NORMAL[2] * PREVIOUS_NORMAL[2];
+        normalDot = 1 - planar * (1 - cosine);
     }
-    const trust = disocclusionWeight(expected, held, Math.hypot(mu, mv), normalDot, frame.disocclusion);
+    const trust = disocclusionWeight(expected, held, Math.hypot(mu, mv), normalDot, frame.disocclusion, slope);
     return HISTORY[3] * trust;
 }
 /**

package/dist/render/renderQuality.d.ts

@@ -29,6 +29,8 @@ export type OutputTransform = 'none' | 'srgb' | 'aces';
 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.
@@ -141,6 +143,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. */
@@ -548,6 +569,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;

package/dist/render/renderQuality.js

@@ -56,6 +56,7 @@ export const DEFAULT_RENDER_QUALITY = Object.freeze({
     shadowFilterTaps: MAX_SHADOW_FILTER_TAPS,
     lightVolumeSamples: 32,
     directionalShadowDepthLayers: 2,
+    glassShadows: 'full',
     directionalShadowMaxDistance: 6,
     directionalShadowMaxSlope: 3,
     pointShadowRebakeDistance: 0.001,
@@ -205,6 +206,7 @@ export function resolveRenderQuality(options = {}) {
         shadowFilterTaps: options.shadowFilterTaps ?? DEFAULT_RENDER_QUALITY.shadowFilterTaps,
         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: options.directionalShadowMaxSlope ?? DEFAULT_RENDER_QUALITY.directionalShadowMaxSlope,
         pointShadowRebakeDistance: options.pointShadowRebakeDistance ?? DEFAULT_RENDER_QUALITY.pointShadowRebakeDistance,
@@ -286,6 +288,11 @@ export function resolveRenderQuality(options = {}) {
     if (quality.directionalShadowDepthLayers !== 1 && quality.directionalShadowDepthLayers !== 2) {
         throw new Error(`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/dist/render/rendererHarness.js

@@ -86,6 +86,18 @@ export function recordingGl(options = {}) {
         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/dist/render/sceneTarget.d.ts

@@ -72,6 +72,8 @@ export declare class SceneTarget {
     private colorCopyFramebuffer;
     /** Whether this frame has filled it. One snapshot serves every refracting draw in a frame. */
     private colorCopyFilled;
+    /** Whether this frame's copy has its mip chain, which frosted glass reads. See `snapshotColor`. */
+    private colorCopyMips;
     /**
      * The colour grade, as a 3D texture on unit 4, and the table it was built from.
      *
@@ -221,7 +223,11 @@ export declare 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?: boolean): WebGLTexture | null;
+    snapshotColor(afresh?: boolean, 
+    /** Fill the copy's mip chain as well, once a frame: what frosted glass reads. */
+    mips?: boolean): WebGLTexture | null;
+    /** The copy's mip chain from its level 0, once per copy. */
+    private fillColorCopyMips;
     snapshotDepth(
     /**
      * Take the copy again even though one has already been taken this frame.
@@ -303,6 +309,8 @@ export declare class SceneTarget {
     }, veilColor?: Vec3, veilAlpha?: number, temporal?: {
         readonly reprojection: Float32Array;
         readonly blend: number;
+        readonly periodStart: boolean;
+        readonly depthToViewZ: Float32Array;
     }): void;
     dispose(): void;
 }