@driftengine/core 4.4.1 → 4.5.0

package/dist/render/pointShadowArray.d.ts

@@ -16,7 +16,25 @@ export declare const OCTAHEDRAL_EDGE = 1024;
 export interface PointShadowTarget {
     beginFace(gl: WebGL2RenderingContext): void;
     resolveFace(gl: WebGL2RenderingContext, layer: number, face: number, far: number, near: number): void;
+    /** Whether the array has grown its glass layers: `growForGlass`. */
+    readonly hasGlass: boolean;
+    /** Whether `face` of `layer` holds glass, which a face that offers none must clear. */
+    heldGlass(layer: number, face: number): boolean;
+    /** The depth scratch again, cleared, for the face's glass. */
+    beginGlassFace(gl: WebGL2RenderingContext): void;
+    resolveGlassFace(gl: WebGL2RenderingContext, layer: number, face: number, far: number, near: number): void;
+    /** The colour scratch, cleared to white, for what the face's glass lets through. */
+    beginTintFace(gl: WebGL2RenderingContext): void;
+    resolveTintFace(gl: WebGL2RenderingContext, layer: number, face: number, drawn: boolean): void;
 }
+/**
+ * Every published layer as the array stores it: `layer × stride`, and −1 left as −1.
+ *
+ * **Applied to the resolved arrays right after each resolve**, so every consumer of an uploaded
+ * index reads the physical layer: once glass arrives, light L's depth is at 2L and its glass at
+ * 2L + 1 (`PointShadowArray.growForGlass`). In place, because the resolve rewrites these every time.
+ */
+export declare function strideLayers(layers: Int32Array, stride: number): void;
 /**
  * Every point light's shadow as one array texture, and the scratch that fills it.
  *
@@ -34,12 +52,16 @@ export interface PointShadowTarget {
  * never the same object.
  */
 export declare class PointShadowArray implements PointShadowTarget {
-    readonly texture: WebGLTexture;
     /**
-     * How many layers this array holds: the point pool, the two live transition maps, and two more
-     * for each rectangle a world said would cast. See the constructor's `extraLayers`.
+     * How many lights this array holds: the point pool, the two live transition maps, and two more
+     * for each rectangle a world said would cast. See the constructor's `extraLayers`. Counted in
+     * lights, so it does not move when glass doubles the storage under it.
      */
     readonly layers: number;
+    /** Replaced once, when glass first casts: see `growForGlass`. */
+    private current;
+    /** What the lights' glass lets through, made with the glass layers. */
+    private tint;
     private readonly framebuffer;
     private readonly scratchTexture;
     private readonly scratchFramebuffer;
@@ -62,6 +84,35 @@ export declare class PointShadowArray implements PointShadowTarget {
      * map.
      */
     extraLayers?: number);
+    /** The array texture the lit pass samples. Replaced once, when glass first casts. */
+    get texture(): WebGLTexture;
+    get hasGlass(): boolean;
+    /** Physical layers a light: 1, or 2 once glass has interleaved the array. */
+    get stride(): number;
+    /** The glass tint, one layer a light, once glass has cast; the lit pass samples it. */
+    get tintTexture(): WebGLTexture | null;
+    /**
+     * Interleave the array for glass: light L's depth moves to 2L and its glass takes 2L + 1, and
+     * the tint is made. Returns whether it grew — once, on the first face whose casters held glass.
+     *
+     * **Interleaved rather than stacked above the opaque half** because a shader cannot ask an array
+     * its layer count under naga, so it cannot find `L + N`; `layer + 1` it can. **Every map already
+     * baked is carried across** by a depth blit, so nothing goes dark, and **no map needs baking
+     * again**: this runs on the first face that saw glass, so no map baked before it saw any, and a
+     * glass layer born at the far plane with a white tint is exactly what its bake would draw. What
+     * it costs is the doubled depth (4.19 MB a light at 1024) and the tint (5.6 MB a light with its
+     * chain, 1.4 MB at `'half'`), from then on.
+     */
+    growForGlass(gl: WebGL2RenderingContext, tintEdge: number): boolean;
+    heldGlass(layer: number, face: number): boolean;
+    /** The depth scratch, cleared, for the face's glass: `beginFace` exactly. */
+    beginGlassFace(gl: WebGL2RenderingContext): void;
+    /** The face's glass depth into light `layer`'s glass layer, 2L + 1. */
+    resolveGlassFace(gl: WebGL2RenderingContext, layer: number, face: number, far: number, near: number): void;
+    beginTintFace(gl: WebGL2RenderingContext): void;
+    resolveTintFace(gl: WebGL2RenderingContext, layer: number, face: number, drawn: boolean): void;
+    /** The chain frost reads, for every light whose tint a round touched: once a round. */
+    finishTints(gl: WebGL2RenderingContext): void;
     /**
      * Bind the scratch as the render target for one face of one bake, and clear it.
      *
@@ -91,5 +142,7 @@ export declare class PointShadowArray implements PointShadowTarget {
      * from an empty vertex array.
      */
     resolveFace(gl: WebGL2RenderingContext, layer: number, face: number, far: number, near: number): void;
+    /** The scratch into physical layer `physical`'s region for `face`. */
+    private resolveInto;
     dispose(gl: WebGL2RenderingContext): void;
 }

package/dist/render/pointShadowArray.js

@@ -1,6 +1,7 @@
 import { mat3 } from 'gl-matrix';
 import { createEmptyTexture2D } from './emptyTexture.js';
 import { LIVE_POINT_SHADOW_MAPS, POINT_SHADOW_POOL } from './lightBudget.js';
+import { PointGlassTint } from './pointGlassTint.js';
 import { pointShadowFaceRotation } from './pointShadowImage.js';
 import { compileProgram, uniformLocations } from './shader.js';
 import { OCTAHEDRAL_RESOLVE_FRAG, OCTAHEDRAL_RESOLVE_VERT } from './shaders/octahedralResolve.js';
@@ -15,6 +16,22 @@ import { OCTAHEDRAL_RESOLVE_FRAG, OCTAHEDRAL_RESOLVE_VERT } from './shaders/octa
 export const OCTAHEDRAL_EDGE = 1024;
 /** Filled per resolved face, at module scope, because a bake runs inside the frame's budget. */
 const faceRotation = mat3.create();
+/**
+ * Every published layer as the array stores it: `layer × stride`, and −1 left as −1.
+ *
+ * **Applied to the resolved arrays right after each resolve**, so every consumer of an uploaded
+ * index reads the physical layer: once glass arrives, light L's depth is at 2L and its glass at
+ * 2L + 1 (`PointShadowArray.growForGlass`). In place, because the resolve rewrites these every time.
+ */
+export function strideLayers(layers, stride) {
+    if (stride === 1)
+        return;
+    for (let i = 0; i < layers.length; i++) {
+        const layer = layers[i];
+        if (layer >= 0)
+            layers[i] = layer * stride;
+    }
+}
 /**
  * Every point light's shadow as one array texture, and the scratch that fills it.
  *
@@ -32,12 +49,16 @@ const faceRotation = mat3.create();
  * never the same object.
  */
 export class PointShadowArray {
-    texture;
     /**
-     * How many layers this array holds: the point pool, the two live transition maps, and two more
-     * for each rectangle a world said would cast. See the constructor's `extraLayers`.
+     * How many lights this array holds: the point pool, the two live transition maps, and two more
+     * for each rectangle a world said would cast. See the constructor's `extraLayers`. Counted in
+     * lights, so it does not move when glass doubles the storage under it.
      */
     layers;
+    /** Replaced once, when glass first casts: see `growForGlass`. */
+    current;
+    /** What the lights' glass lets through, made with the glass layers. */
+    tint = null;
     framebuffer;
     scratchTexture;
     scratchFramebuffer;
@@ -68,17 +89,8 @@ export class PointShadowArray {
          */
         this.layers =
             Math.min(lightCount, POINT_SHADOW_POOL) + LIVE_POINT_SHADOW_MAPS + Math.max(0, extraLayers);
-        const texture = gl.createTexture();
-        if (texture === null)
-            throw new Error('PointShadowArray: createTexture failed');
-        this.texture = texture;
-        gl.bindTexture(gl.TEXTURE_2D_ARRAY, texture);
-        gl.texStorage3D(gl.TEXTURE_2D_ARRAY, 1, gl.DEPTH_COMPONENT24, OCTAHEDRAL_EDGE, OCTAHEDRAL_EDGE, this.layers);
-        /* One storage level and no filtering, so textureLod(..., 0.0) is the only fetch there is. */
-        gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
-        gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
-        gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
-        gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+        const texture = depthArray(gl, this.layers);
+        this.current = texture;
         const scratchTexture = gl.createTexture();
         if (scratchTexture === null)
             throw new Error('PointShadowArray: createTexture failed');
@@ -141,6 +153,86 @@ export class PointShadowArray {
         gl.bindTexture(gl.TEXTURE_2D, null);
         gl.bindTexture(gl.TEXTURE_2D_ARRAY, null);
     }
+    /** The array texture the lit pass samples. Replaced once, when glass first casts. */
+    get texture() {
+        return this.current;
+    }
+    get hasGlass() {
+        return this.tint !== null;
+    }
+    /** Physical layers a light: 1, or 2 once glass has interleaved the array. */
+    get stride() {
+        return this.tint === null ? 1 : 2;
+    }
+    /** The glass tint, one layer a light, once glass has cast; the lit pass samples it. */
+    get tintTexture() {
+        return this.tint?.texture ?? null;
+    }
+    /**
+     * Interleave the array for glass: light L's depth moves to 2L and its glass takes 2L + 1, and
+     * the tint is made. Returns whether it grew — once, on the first face whose casters held glass.
+     *
+     * **Interleaved rather than stacked above the opaque half** because a shader cannot ask an array
+     * its layer count under naga, so it cannot find `L + N`; `layer + 1` it can. **Every map already
+     * baked is carried across** by a depth blit, so nothing goes dark, and **no map needs baking
+     * again**: this runs on the first face that saw glass, so no map baked before it saw any, and a
+     * glass layer born at the far plane with a white tint is exactly what its bake would draw. What
+     * it costs is the doubled depth (4.19 MB a light at 1024) and the tint (5.6 MB a light with its
+     * chain, 1.4 MB at `'half'`), from then on.
+     */
+    growForGlass(gl, tintEdge) {
+        if (this.tint !== null)
+            return false;
+        const old = this.current;
+        const texture = depthArray(gl, this.layers * 2);
+        /* Off the unit it was made on, as the constructor leaves its own: see `beginFace`. */
+        gl.bindTexture(gl.TEXTURE_2D_ARRAY, null);
+        const read = gl.createFramebuffer();
+        if (read === null)
+            throw new Error('PointShadowArray: createFramebuffer failed');
+        gl.bindFramebuffer(gl.READ_FRAMEBUFFER, read);
+        gl.bindFramebuffer(gl.DRAW_FRAMEBUFFER, this.framebuffer);
+        for (let layer = 0; layer < this.layers; layer++) {
+            gl.framebufferTextureLayer(gl.READ_FRAMEBUFFER, gl.DEPTH_ATTACHMENT, old, 0, layer);
+            gl.framebufferTextureLayer(gl.DRAW_FRAMEBUFFER, gl.DEPTH_ATTACHMENT, texture, 0, 2 * layer);
+            gl.blitFramebuffer(0, 0, OCTAHEDRAL_EDGE, OCTAHEDRAL_EDGE, 0, 0, OCTAHEDRAL_EDGE, OCTAHEDRAL_EDGE, gl.DEPTH_BUFFER_BIT, gl.NEAREST);
+        }
+        /* Nothing is nearer a lamp than a pane that has not been drawn. */
+        for (let layer = 0; layer < this.layers; layer++) {
+            gl.framebufferTextureLayer(gl.DRAW_FRAMEBUFFER, gl.DEPTH_ATTACHMENT, texture, 0, 2 * layer + 1);
+            gl.clearBufferfv(gl.DEPTH, 0, FAR_PLANE);
+        }
+        gl.bindFramebuffer(gl.READ_FRAMEBUFFER, null);
+        gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+        gl.deleteFramebuffer(read);
+        gl.deleteTexture(old);
+        this.current = texture;
+        this.tint = new PointGlassTint(gl, this.faceSize, tintEdge, this.layers);
+        return true;
+    }
+    heldGlass(layer, face) {
+        return this.tint?.held(layer, face) ?? false;
+    }
+    /** The depth scratch, cleared, for the face's glass: `beginFace` exactly. */
+    beginGlassFace(gl) {
+        this.beginFace(gl);
+    }
+    /** The face's glass depth into light `layer`'s glass layer, 2L + 1. */
+    resolveGlassFace(gl, layer, face, far, near) {
+        if (this.tint === null)
+            return;
+        this.resolveInto(gl, 2 * layer + 1, face, far, near);
+    }
+    beginTintFace(gl) {
+        this.tint?.beginFace(gl);
+    }
+    resolveTintFace(gl, layer, face, drawn) {
+        this.tint?.resolveFace(gl, layer, face, drawn);
+    }
+    /** The chain frost reads, for every light whose tint a round touched: once a round. */
+    finishTints(gl) {
+        this.tint?.fillMips(gl);
+    }
     /**
      * Bind the scratch as the render target for one face of one bake, and clear it.
      *
@@ -176,8 +268,12 @@ export class PointShadowArray {
      * from an empty vertex array.
      */
     resolveFace(gl, layer, face, far, near) {
+        this.resolveInto(gl, layer * this.stride, face, far, near);
+    }
+    /** The scratch into physical layer `physical`'s region for `face`. */
+    resolveInto(gl, physical, face, far, near) {
         gl.bindFramebuffer(gl.FRAMEBUFFER, this.framebuffer);
-        gl.framebufferTextureLayer(gl.FRAMEBUFFER, gl.DEPTH_ATTACHMENT, this.texture, 0, layer);
+        gl.framebufferTextureLayer(gl.FRAMEBUFFER, gl.DEPTH_ATTACHMENT, this.current, 0, physical);
         gl.viewport(0, 0, OCTAHEDRAL_EDGE, OCTAHEDRAL_EDGE);
         gl.useProgram(this.program);
         gl.bindVertexArray(this.vao);
@@ -210,10 +306,25 @@ export class PointShadowArray {
     dispose(gl) {
         gl.deleteFramebuffer(this.framebuffer);
         gl.deleteFramebuffer(this.scratchFramebuffer);
-        gl.deleteTexture(this.texture);
+        gl.deleteTexture(this.current);
         gl.deleteTexture(this.scratchTexture);
+        this.tint?.dispose(gl);
         gl.deleteTexture(this.parked);
         gl.deleteProgram(this.program);
         gl.deleteVertexArray(this.vao);
     }
 }
+const FAR_PLANE = new Float32Array([1]);
+/** The depth array: one storage level and no filtering, so textureLod(..., 0.0) is the only fetch. */
+function depthArray(gl, layers) {
+    const texture = gl.createTexture();
+    if (texture === null)
+        throw new Error('PointShadowArray: createTexture failed');
+    gl.bindTexture(gl.TEXTURE_2D_ARRAY, texture);
+    gl.texStorage3D(gl.TEXTURE_2D_ARRAY, 1, gl.DEPTH_COMPONENT24, OCTAHEDRAL_EDGE, OCTAHEDRAL_EDGE, layers);
+    gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
+    gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
+    gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+    gl.texParameteri(gl.TEXTURE_2D_ARRAY, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+    return texture;
+}

package/dist/render/pointShadowBudget.js

@@ -177,15 +177,15 @@ export function runPointShadowBakes(pool, lights, facesPerFrame, liveFacesPerFra
          * **The run decays rather than resetting, and it climbs past the threshold before it stops.**
          *
          * A light that wanders on a curve is not stale on *every* frame — near the turning points of
-         * its travel it moves less in a frame than the rebake tolerance, so a run that reset to zero
-         * lost the tracking allowance there and the map dropped back to two faces a frame. The shadow
-         * then travelled smoothly through the fast part of the wander and stepped through the slow
-         * part, which is not motion and not stillness: it reads as a vibration. Reported that way,
-         * against a brazier, once the tracking allowance was in.
+         * its travel it moves less in a frame than the rebake tolerance. When the run decided whether a
+         * wanderer got its whole cube, a run that reset to zero dropped it back to two faces a frame
+         * there, and the shadow stepped through the slow part of the wander: reported as a vibration
+         * against a brazier. Every image-holding map is re-baked whole now, so the run only orders the
+         * queue, and the hysteresis keeps a wanderer behind the lights that settle instead of letting
+         * it jump ahead at every turning point.
          *
-         * So the run is hysteresis. It climbs to twice the threshold, which buys a light that has
-         * earned the allowance three quiet frames before it loses it, and decays one frame at a time
-         * so a light that genuinely settles stops re-baking rather than holding a budget for ever.
+         * It climbs to twice the threshold, which keeps a light chronic for three quiet frames, and
+         * decays one frame at a time so a light that genuinely settles rejoins the ordinary order.
          */
         const previous = scratch.staleRun[slot] ?? 0;
         const run = stale
@@ -198,37 +198,40 @@ export function runPointShadowBakes(pool, lights, facesPerFrame, liveFacesPerFra
     let faces = facesPerFrame;
     let urgentSpent = false;
     /*
-     * **One wandering light finishes its cube in the frame it started it**, the same allowance a
-     * light with no image at all gets, and for a reason that turns out to be the same one: a map
-     * dribbled out at two faces a frame is a map nobody can sample correctly until it lands.
+     * **A map that holds an image is re-baked whole or not at all**, and one being shaded may take a
+     * whole cube a frame outside the budget to make that possible.
      *
-     * A cold light cannot be sampled *at all* until its six faces are in, so it takes the whole
-     * cube at once. A chronically stale one can be sampled throughout and is wrong in a quieter
-     * way: `planBake` pins the origin for the whole of a resumed bake, so six faces spread over
-     * three frames means the published origin steps once every third frame. The shader shoots from
-     * that origin, so the shadow it draws steps with it — reported on a brazier as motion that was
-     * "really fast, not smooth, snappy, and unrealistic", which is a 20 Hz sample of a flame that
-     * wanders about once a second.
+     * Faces land in the layer the shader samples as they are drawn, and `planBake` publishes the
+     * origin they were drawn from only with the last one. So a re-bake spread over frames is a cube
+     * the shader reads from the old origin with part of it drawn from the new one — and a face is a
+     * 90 degree frustum, so the part drawn from somewhere else is a straight-edged quadrilateral of
+     * wrong shadow on the ground under the lamp. With the budget spent elsewhere it could hold for a
+     * second and more. Reported under a brazier as a dark shape that came and went.
      *
-     * Given the cube in one frame the origin moves every frame and the shadow travels instead.
+     * A map with no image yet is not sampled until its sixth face lands (see
+     * `PointShadowSystem.bind`), so it still fills a few faces a frame, and a cold one being shaded
+     * still jumps the queue with all six.
      *
-     * **Bounded to one light, and it has to be.** Eight braziers each taking six passes is the 48
-     * passes and 89 ms `pointShadowFacesPerFrame` exists to prevent. One is the light being shaded
-     * that most recently went stale, which is the one somebody is standing next to; the rest keep
-     * dribbling under the ordinary budget, and their shadows step rather than travel. That is the
-     * right way round: a shadow you are looking at moves, and a shadow across the square does not
-     * cost the frame.
+     * The allowance used to be for a *chronically* stale light only — a wandering flame — whose
+     * dribbled cube published a new origin once every third frame, so its shadow stepped at 20 Hz
+     * where the flame wanders about once a second: reported as motion that was "really fast, not
+     * smooth, snappy, and unrealistic". Any shaded light is owed the same now, because a cube read
+     * part-way is wrong in the same place for the same reason whether or not it will be stale again.
      *
-     * It is spent *after* the cold and settling groups, because `planPointShadowBakes` orders the
-     * chronic ones last — so a light arriving in range still gets its first image ahead of a flame
-     * refining one it already has.
+     * **Bounded to one light, and it has to be.** Eight braziers each taking six passes is the 48
+     * passes and 89 ms `pointShadowFacesPerFrame` exists to prevent. The first in the plan's order
+     * takes it, and `planPointShadowBakes` puts the lights that settled ahead of the ones that never
+     * do, so a flame refining its image cannot hold a correction hostage. The rest keep sampling a
+     * complete image from a few centimetres away until their turn, which is the trade
+     * `pointShadowRebakeDistance` already makes. A warm map, held but not shaded, is re-baked when a
+     * whole cube fits the budget or once it is shaded, and not before.
      *
-     * **What would make it wrong** is a caster set heavy enough that six passes over it does not
-     * fit the frame. Measured against a game whose whole static world is about 8,500 triangles in
-     * a handful of draws; a world an order of magnitude heavier wants `pointShadowFacesPerFrame`
+     * **What would make it wrong** is a caster set heavy enough that six passes over it does not fit
+     * the frame. Measured against a game whose whole static world is about 8,500 triangles in a
+     * handful of draws; a world an order of magnitude heavier wants `pointShadowFacesPerFrame`
      * raised or this given up, and `gpuTiming` is how to tell which.
      */
-    let trackingSpent = false;
+    let refreshSpent = false;
     for (let i = 0; i < planned && faces > 0; i++) {
         const slot = scratch.order[i] ?? -1;
         /*
@@ -241,15 +244,22 @@ export function runPointShadowBakes(pool, lights, facesPerFrame, liveFacesPerFra
         if (light === undefined || map === undefined)
             continue;
         const sampled = slot < pool.sampledCount;
-        const cold = sampled && scratch.ready[slot] === 0;
-        const urgent = cold && !urgentSpent;
-        /* A light being shaded whose map will be stale again next frame however it is served. */
-        const tracking = !cold && sampled && scratch.chronic[slot] === 1 && !trackingSpent;
-        if (urgent)
-            urgentSpent = true;
-        if (tracking)
-            trackingSpent = true;
-        faces -= bake(map, light, staticCasters, urgent || tracking ? faceCount : faces);
+        if (scratch.ready[slot] !== 1) {
+            /* No image to spoil: a few faces a frame, or all six at once for one being shaded. */
+            const urgent = sampled && !urgentSpent;
+            if (urgent)
+                urgentSpent = true;
+            faces -= bake(map, light, staticCasters, urgent ? faceCount : faces);
+            continue;
+        }
+        if (faces >= faceCount) {
+            faces -= bake(map, light, staticCasters, faceCount);
+            continue;
+        }
+        if (!sampled || refreshSpent)
+            continue;
+        refreshSpent = true;
+        faces -= bake(map, light, staticCasters, faceCount);
     }
     /*
      * Live maps contain movers only and are composed with the static maps in the shader. A second

package/dist/render/pointShadowMap.d.ts

@@ -21,6 +21,18 @@ import { FACE_COUNT, POINT_SHADOW_NEAR } from './pointShadowImage.ts';
  * projection the shader reads. Nothing about the bake's cost, order or resumption moved.
  */
 export { FACE_COUNT, POINT_SHADOW_NEAR };
+/**
+ * What a bake asks of the renderer about glass, after each face's opaque depth.
+ *
+ * **Asked before it is drawn** because the answer decides whether the face binds a glass target at
+ * all: a face that offers no glass and holds none from a previous owner does no glass work.
+ */
+export interface PointGlassDraw {
+    /** Whether the face just drawn offered any glass. */
+    offered(): boolean;
+    /** Draw that glass: its depth, or what it lets through lit from the bake origin. */
+    draw(pass: 'depth' | 'tint', x: number, y: number, z: number): void;
+}
 export declare class PointShadowMap {
     readonly size: number;
     /**
@@ -85,7 +97,9 @@ export declare class PointShadowMap {
      * bake is not sampled at all until it completes, so this only matters for a re-bake,
      * where holding the old values keeps them matched to the old faces.
      */
-    bake(gl: WebGL2RenderingContext, x: number, y: number, z: number, range: number, drawCasters: (viewProj: mat4) => void, near?: number, sourceRadius?: number, maxFaces?: number): number;
+    bake(gl: WebGL2RenderingContext, x: number, y: number, z: number, range: number, drawCasters: (viewProj: mat4) => void, near?: number, sourceRadius?: number, maxFaces?: number, 
+    /** The face's glass, when glass shadows are on: `PointGlassDraw`. */
+    glass?: PointGlassDraw | null): number;
     /**
      * Nothing to free: every GPU object this map used to own belongs to `PointShadowArray` now.
      *
@@ -93,5 +107,13 @@ export declare class PointShadowMap {
      * needing disposal is exactly the shape of a leak nobody notices. The array is disposed by the
      * renderer that built it.
      */
+    /**
+     * The face's glass, twice: where the nearest pane is, then what the panes let through.
+     *
+     * A face that offers no glass still clears a region a previous owner's glass is in — the depth to
+     * the far plane and the tint to white, from scratches cleared and not drawn into — because a pool
+     * slot changes hands with its layer.
+     */
+    private bakeGlassFace;
     dispose(_gl: WebGL2RenderingContext): void;
 }

package/dist/render/pointShadowMap.js

@@ -113,7 +113,9 @@ export class PointShadowMap {
      * bake is not sampled at all until it completes, so this only matters for a re-bake,
      * where holding the old values keeps them matched to the old faces.
      */
-    bake(gl, x, y, z, range, drawCasters, near = POINT_SHADOW_NEAR, sourceRadius = DEFAULT_SOURCE_RADIUS, maxFaces = FACE_COUNT) {
+    bake(gl, x, y, z, range, drawCasters, near = POINT_SHADOW_NEAR, sourceRadius = DEFAULT_SOURCE_RADIUS, maxFaces = FACE_COUNT, 
+    /** The face's glass, when glass shadows are on: `PointGlassDraw`. */
+    glass = null) {
         /*
          * What to render now, **and what to render it for**. A bake in flight owns the parameters
          * it started with, so the arguments here are only a proposal for a bake that is not already
@@ -159,6 +161,8 @@ export class PointShadowMap {
              * next face's pass does care about.
              */
             array.resolveFace(gl, this.layer, face, plan.range, plan.near);
+            if (glass !== null)
+                this.bakeGlassFace(gl, array, glass, face, plan);
         }
         gl.enable(gl.CULL_FACE);
         gl.cullFace(gl.BACK);
@@ -173,5 +177,27 @@ export class PointShadowMap {
      * needing disposal is exactly the shape of a leak nobody notices. The array is disposed by the
      * renderer that built it.
      */
+    /**
+     * The face's glass, twice: where the nearest pane is, then what the panes let through.
+     *
+     * A face that offers no glass still clears a region a previous owner's glass is in — the depth to
+     * the far plane and the tint to white, from scratches cleared and not drawn into — because a pool
+     * slot changes hands with its layer.
+     */
+    bakeGlassFace(gl, array, glass, face, plan) {
+        if (!array.hasGlass)
+            return;
+        const offered = glass.offered();
+        if (!offered && !array.heldGlass(this.layer, face))
+            return;
+        array.beginGlassFace(gl);
+        if (offered)
+            glass.draw('depth', plan.x, plan.y, plan.z);
+        array.resolveGlassFace(gl, this.layer, face, plan.range, plan.near);
+        array.beginTintFace(gl);
+        if (offered)
+            glass.draw('tint', plan.x, plan.y, plan.z);
+        array.resolveTintFace(gl, this.layer, face, offered);
+    }
     dispose(_gl) { }
 }

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

@@ -0,0 +1,15 @@
+/**
+ * Which frame a change to a dynamic mesh or an instanced batch belongs to.
+ *
+ * **A consumer may change geometry in its simulation step, before `beginFrame`.** That change is
+ * what the *next* frame draws, so it is that frame's — counting it against the frame last begun
+ * would say the geometry changed a frame early and then did not change at all, which is a motion
+ * vector on the wrong frame and none on the right one.
+ *
+ * Only the **first** change in a frame keeps the state before it: a second rewrite in the same
+ * frame must not replace "where it was last frame" with "where it was a moment ago".
+ */
+export declare function frameOfChange(serial: number, inFrame: boolean): number;
+export declare function keepsPrevious(lastChange: number, frame: number): boolean;
+/** Slots `0 … n-1` pair with last frame's; a slot past last frame's count is new and has no past. */
+export declare function pairedInstances(previousCount: number, count: number): number;

package/dist/render/recon/changeFrames.js

@@ -0,0 +1,21 @@
+/**
+ * Which frame a change to a dynamic mesh or an instanced batch belongs to.
+ *
+ * **A consumer may change geometry in its simulation step, before `beginFrame`.** That change is
+ * what the *next* frame draws, so it is that frame's — counting it against the frame last begun
+ * would say the geometry changed a frame early and then did not change at all, which is a motion
+ * vector on the wrong frame and none on the right one.
+ *
+ * Only the **first** change in a frame keeps the state before it: a second rewrite in the same
+ * frame must not replace "where it was last frame" with "where it was a moment ago".
+ */
+export function frameOfChange(serial, inFrame) {
+    return inFrame ? serial : serial + 1;
+}
+export function keepsPrevious(lastChange, frame) {
+    return lastChange !== frame;
+}
+/** Slots `0 … n-1` pair with last frame's; a slot past last frame's count is new and has no past. */
+export function pairedInstances(previousCount, count) {
+    return Math.min(previousCount, count);
+}

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

@@ -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.
@@ -38,14 +43,42 @@ export interface DisocclusionParams {
  * normals trusted fully within sixty degrees and not at all past ninety.
  */
 export declare const DEFAULT_DISOCCLUSION: DisocclusionParams;
+/**
+ * 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 declare const PLANAR_FROM = 0.25;
+export declare 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 declare function planarity(before: number, centre: number, after: number): number;
+/**
+ * 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 declare function surfaceSlope(before: number, centre: number, after: number): number;
 /**
  * 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 declare function disocclusionWeight(currDepth: number, histDepth: number, motionLength: number, normalDot: number, params: DisocclusionParams): number;
+export declare function disocclusionWeight(currDepth: number, histDepth: number, motionLength: number, normalDot: number, params: DisocclusionParams, slope?: number): number;
 /**
  * The world position a depth stands for: `(u, v, clipDepth)` through the inverse view-projection,
  * in whatever depth convention that matrix was built for. Returns false where the matrix has no