@driftengine/core 4.5.0 → 4.6.0

package/dist/render/mesh.js

@@ -49,14 +49,6 @@ const ATTR_JOINTS = 11;
  * setting sway, watching nothing move, and having nothing to read about why.
  */
 const ATTR_CHANNEL = 13;
-/**
- * The locations `attachInstances` claims, which a plain draw through the same array must not read.
- *
- * Eleven to fourteen are the model matrix's columns and fifteen is the tint. **Thirteen is also
- * the channel**, and eleven and twelve are the skinning pair — which cannot collide, because
- * `flatVert` refuses skinning with instancing. See `draw`.
- */
-const INSTANCE_COLUMNS = [11, 12, 13, 14, 15];
 const ATTR_WEIGHTS = 12;
 /**
  * One absent attribute's constant, at the width the table gave it.
@@ -84,6 +76,9 @@ function applyConstant(gl, location, value) {
 export class Mesh {
     vao;
     buffers = [];
+    /** Every attribute bound from a buffer, so a batch can build a vertex array of its own. */
+    layout = [];
+    indexBuffer = null;
     /**
      * The position and normal buffers, kept so `update` can rewrite them.
      *
@@ -93,6 +88,7 @@ export class Mesh {
     deformable = null;
     /** How many floats the position buffer holds, so an update of the wrong size is refused. */
     positionFloats;
+    /** Indices one draw of it issues; the batch-size rule reads it (`cullsInstances`). */
     indexCount;
     /**
      * The constant values this mesh's *absent* attributes are shaded with, re-applied on
@@ -211,7 +207,14 @@ export class Mesh {
             gl.disableVertexAttribArray(ATTR_UV);
             this.constants.push({ location: ATTR_UV, value: ABSENT_ATTRIBUTE['uvs'] });
         }
+        else if (data.layers !== undefined) {
+            /* The texture-array layer rides as the third coordinate — every vertex location is spent —
+               so a layered mesh uploads (u, v, layer) packed. See `MeshData.layers`. */
+            this.attachAttribute(gl, ATTR_UV, packUvLayers(data.uvs, data.layers), 3);
+        }
         else {
+            /* Two components; the shader's vec3 reads z as 0 by the GL rule for a missing component,
+               which is layer 0 — the only layer a plain texture has. */
             this.attachAttribute(gl, ATTR_UV, data.uvs, 2);
         }
         /* Absent means "inherit albedo", supplied as the constant the shader tests for. */
@@ -297,6 +300,7 @@ export class Mesh {
             throw new Error('createBuffer failed');
         this.buffers.push(indexBuffer);
         gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, indexBuffer);
+        this.indexBuffer = indexBuffer;
         this.allocate(gl, gl.ELEMENT_ARRAY_BUFFER, indexBuffer, data.indices, gl.STATIC_DRAW);
         gl.bindVertexArray(null);
     }
@@ -304,29 +308,11 @@ export class Mesh {
     draw(gl) {
         gl.bindVertexArray(this.vao);
         /*
-         * **A mesh with a batch has the instance columns enabled on this very array, and location 13
-         * is the channel.** `attachInstances` claims 11 to 14 for the model matrix and 15 for the
-         * tint; a `Mesh` owns one vertex array, so those bindings are still live for a *plain* draw
-         * through it — and `aChannel` then reads the third column of instance zero's matrix instead
-         * of the absent-attribute constant. For a placement with no rotation that column is
-         * `(0, 0, 1, 0)`, so `aChannel.y` is zero, `vSkyDirect = aChannel.y` scales the directional
-         * term to nothing, and the mesh renders lit by the hemispheric ambient alone — correct
-         * normals, correct albedo, no error, no warning.
-         *
-         * Found on `demo/instancing.ts`, which exists to draw two ranks of one box the two ways and
-         * compare them: the `drawMesh` rank's top face read (51, 30, 21) against the `drawInstanced`
-         * rank's (218, 110, 59), and 51 is exactly the ambient. WebGPU has no array to share and drew
-         * them alike, which is what made it visible at all.
-         *
-         * Disabled here and put back by `drawInstances`, rather than given the batch an array of its
-         * own: that is the larger change this class's own note about two batches already contemplates,
-         * and it wants one for a different reason. Three calls on a mesh that has a batch and none on
-         * a mesh that does not.
+         * No instance columns to disable: a batch draws through a vertex array of its own
+         * (`createInstanceArray`), so this array never carries them. It used to, and location 13 — the
+         * channel — then read the third column of instance zero's matrix on a plain draw, which lit a
+         * mesh by ambient alone on this backend and not the other.
          */
-        if (this.instanced) {
-            for (const location of INSTANCE_COLUMNS)
-                gl.disableVertexAttribArray(location);
-        }
         // The VAO restores the arrays; these it cannot. See `constants`.
         for (const constant of this.constants) {
             const value = constant.value;
@@ -335,32 +321,27 @@ export class Mesh {
         gl.drawElements(gl.TRIANGLES, this.indexCount, gl.UNSIGNED_INT, 0);
     }
     /**
-     * Bind one buffer's per-instance attributes to this mesh's vertex array.
-     *
-     * **One batch per mesh, and the vertex array is why.** A `Mesh` owns exactly one, so a second
-     * batch would rebind locations 11 to 15 on the array the first still draws through — and what
-     * comes out is one batch's instances placed by the other's matrices, which reads as a transform
-     * bug in the consumer's own code rather than as a misuse of this.
+     * A vertex array for one instanced batch: every attribute this mesh binds from a buffer, its index
+     * buffer, and the batch's instance columns — the model matrix at 11 to 14, the tint at 15.
      *
-     * **What would make it wrong** is a consumer legitimately wanting two batches of one mesh,
-     * which wants a vertex array per batch rather than a flag here.
+     * **A batch owns its own array**, which is what lets a mesh have more than one batch: a prop drawn
+     * once per region is one mesh and a batch per region. With one array a mesh had one batch, since a
+     * second would rebind the columns the first draws through and place one batch's instances by the
+     * other's matrices. The arrays share every buffer, so a batch costs its instances and nothing of
+     * the geometry. The caller deletes what this returns.
      */
-    attachInstances(gl, buffer, stride) {
-        if (this.instanced) {
-            throw new Error('Mesh: this mesh already has an instanced batch — a Mesh owns one vertex array, so a ' +
-                'second batch would rebind the attributes the first draws through.');
+    createInstanceArray(gl, instances, stride) {
+        const vao = gl.createVertexArray();
+        if (vao === null)
+            throw new Error('createVertexArray failed');
+        gl.bindVertexArray(vao);
+        for (const attribute of this.layout) {
+            gl.bindBuffer(gl.ARRAY_BUFFER, attribute.buffer);
+            gl.enableVertexAttribArray(attribute.location);
+            gl.vertexAttribPointer(attribute.location, attribute.size, gl.FLOAT, false, 0, 0);
         }
-        this.instanced = true;
-        this.instanceBuffer = buffer;
-        this.instanceStride = stride;
-        gl.bindVertexArray(this.vao);
-        this.bindInstanceColumns(gl, buffer);
-        gl.bindVertexArray(null);
-    }
-    /** The instance columns, bound. Called at attach and again after a plain draw disabled them. */
-    bindInstanceColumns(gl, buffer) {
-        const stride = this.instanceStride;
-        gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
+        gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, this.indexBuffer);
+        gl.bindBuffer(gl.ARRAY_BUFFER, instances);
         /* Four vec4 columns then a vec3 tint: a mat4 is not a vertex attribute in GLSL ES 300. */
         for (let column = 0; column < 4; column += 1) {
             const location = 11 + column;
@@ -371,22 +352,12 @@ export class Mesh {
         gl.enableVertexAttribArray(15);
         gl.vertexAttribPointer(15, 3, gl.FLOAT, false, stride, 64);
         gl.vertexAttribDivisor(15, 1);
+        gl.bindVertexArray(null);
+        return vao;
     }
-    instanceBuffer = null;
-    instanceStride = 0;
-    /** Whether `attachInstances` has already claimed locations 11 to 15 on this mesh's array. */
-    instanced = false;
-    /**
-     * Draw `count` instances through the attributes `attachInstances` bound.
-     *
-     * The constants are re-applied exactly as `draw` does — a vertex array restores the arrays and
-     * not the constant attributes, and an absent optional attribute is a constant here.
-     */
-    drawInstances(gl, count) {
-        gl.bindVertexArray(this.vao);
-        /* Put back what `draw` disabled, if a plain draw of this mesh came first. See its note. */
-        if (this.instanceBuffer !== null)
-            this.bindInstanceColumns(gl, this.instanceBuffer);
+    /** Draw `count` instances through a batch's own vertex array. See `createInstanceArray`. */
+    drawInstancesThrough(gl, vao, count) {
+        gl.bindVertexArray(vao);
         for (const constant of this.constants) {
             const value = constant.value;
             applyConstant(gl, constant.location, value);
@@ -438,6 +409,7 @@ export class Mesh {
         this.allocate(gl, gl.ARRAY_BUFFER, buffer, data, usage);
         gl.enableVertexAttribArray(location);
         gl.vertexAttribPointer(location, size, gl.FLOAT, false, 0, 0);
+        this.layout.push({ location, buffer, size });
         return buffer;
     }
     /**
@@ -508,3 +480,14 @@ export function createMeshIncremental(gl, data, dynamic = false) {
     const mesh = new Mesh(gl, data, dynamic, true);
     return { mesh, upload: mesh.uploads(gl) };
 }
+/** Texture coordinates and layers interleaved as (u, v, layer), one row a vertex. */
+export function packUvLayers(uvs, layers) {
+    const count = layers.length;
+    const packed = new Float32Array(count * 3);
+    for (let v = 0; v < count; v++) {
+        packed[v * 3] = uvs[v * 2];
+        packed[v * 3 + 1] = uvs[v * 2 + 1];
+        packed[v * 3 + 2] = layers[v];
+    }
+    return packed;
+}

package/dist/render/occlusion.d.ts

@@ -51,6 +51,16 @@ export declare class OcclusionBuffer {
      * something hidden costs a draw call; culling something visible is a hole.
      */
     occluded(bounds: Bounds, model: ReadonlyMat4): boolean;
+    /**
+     * Whether a world-space box is entirely behind the declared occluders — the tighter question for
+     * something that is a box, where the cube around its sphere reaches far past it. **A flat region
+     * is the case it exists for**: a city block's sphere is half as deep underground as it is wide,
+     * nothing there occludes it, and the sphere test abstains for every block in the city. False
+     * whenever anything is uncertain, exactly as `occluded`.
+     */
+    occludedBox(min: ArrayLike<number>, max: ArrayLike<number>): boolean;
+    /** The shared test: a world box's corners projected, its rectangle tested against the pyramid. */
+    private boxBehind;
     /**
      * A world point into buffer coordinates and depth, written into `CORNERS` at `slot`.
      *

package/dist/render/occlusion.js

@@ -33,6 +33,8 @@
  */
 /** What an unwritten texel holds: the far plane, which occludes nothing. */
 const FAR = 1;
+/** Texels a tested rectangle may span at the level it is read from. See `boxBehind`. */
+const TEXELS_ACROSS = 8;
 export class OcclusionBuffer {
     /**
      * The pyramid, level 0 first, each level a quarter of the one before.
@@ -169,15 +171,33 @@ export class OcclusionBuffer {
         const sz = Math.sqrt(m8 * m8 + m9 * m9 + m10 * m10);
         const radius = bounds.radius * Math.max(sx, sy, sz);
         /* The cube that contains the sphere, which contains the object. Conservative twice over. */
+        return this.boxBehind(x - radius, y - radius, z - radius, x + radius, y + radius, z + radius);
+    }
+    /**
+     * Whether a world-space box is entirely behind the declared occluders — the tighter question for
+     * something that is a box, where the cube around its sphere reaches far past it. **A flat region
+     * is the case it exists for**: a city block's sphere is half as deep underground as it is wide,
+     * nothing there occludes it, and the sphere test abstains for every block in the city. False
+     * whenever anything is uncertain, exactly as `occluded`.
+     */
+    occludedBox(min, max) {
+        if (this.occluders === 0)
+            return false;
+        if (!this.built)
+            this.buildPyramid();
+        return this.boxBehind(min[0] ?? 0, min[1] ?? 0, min[2] ?? 0, max[0] ?? 0, max[1] ?? 0, max[2] ?? 0);
+    }
+    /** The shared test: a world box's corners projected, its rectangle tested against the pyramid. */
+    boxBehind(loX, loY, loZ, hiX, hiY, hiZ) {
         let minX = Infinity;
         let minY = Infinity;
         let minZ = Infinity;
         let maxX = -Infinity;
         let maxY = -Infinity;
         for (let corner = 0; corner < 8; corner++) {
-            const px = corner & 1 ? x + radius : x - radius;
-            const py = corner & 2 ? y + radius : y - radius;
-            const pz = corner & 4 ? z + radius : z - radius;
+            const px = corner & 1 ? hiX : loX;
+            const py = corner & 2 ? hiY : loY;
+            const pz = corner & 4 ? hiZ : loZ;
             if (!this.project(px, py, pz, 0))
                 return false;
             minX = Math.min(minX, CORNERS[0] ?? 0);
@@ -192,13 +212,22 @@ export class OcclusionBuffer {
         if (minX < 0 || minY < 0 || maxX > width || maxY > height)
             return false;
         /*
-         * The coarsest level whose texel is at least as wide as the rectangle, so the test reads at
-         * most two texels each way. `Math.log2` would say the same thing and is one of the calls this
-         * repository's determinism gate refuses elsewhere; a shift loop says it in integers.
+         * The coarsest level at which the rectangle spans at most `TEXELS_ACROSS` texels, so the test
+         * reads at most that many plus one each way. `Math.log2` would say the same thing and is one of
+         * the calls this repository's determinism gate refuses elsewhere; a shift loop says it in integers.
+         *
+         * **Eight, not one, since 2026-09-30.** At one the level's texel was as wide as the rectangle, and
+         * two such texels aligned to the grid span up to twice it — so anything whose rectangle came near
+         * an occluder's edge, or the buffer's own unwritten border row, read unwritten texels and
+         * abstained. That was every city region behind a row of buildings, whose rectangle sits just
+         * under the skyline; measured on a box seven metres wide behind a wall filling the view, which
+         * one abstained at and eight culls. Reading up to 81 texels instead of 4 costs a few dozen
+         * compares and keeps the answer exactly as conservative: the maximum over every texel the
+         * rectangle touches.
          */
         let level = 0;
         let span = Math.max(maxX - minX, maxY - minY);
-        while (span > 1 && level + 1 < this.levels.length) {
+        while (span > TEXELS_ACROSS && level + 1 < this.levels.length) {
             span *= 0.5;
             level++;
         }

package/dist/render/pointLightSelection.d.ts

@@ -1,4 +1,5 @@
 /** Allocation-free selection and packing of point lights for a fixed shader budget. */
+import type { LightGrid } from './lightGrid.ts';
 export declare const DEFAULT_POINT_LIGHT_VIEW_RANGE = 180;
 export interface PointLightSource {
     x: number;
@@ -189,3 +190,9 @@ export declare function createPointLightBuffer(capacity?: number): PointLightBuf
  * makes the distance the *same arithmetic on the same operands*, not merely a close number.
  */
 export declare function selectPointLights(sources: readonly PointLightSource[], x: number, y: number, z: number, out: PointLightBuffer, timeSeconds?: number, viewRange?: number, castX?: number, castY?: number, castZ?: number): void;
+/**
+ * `selectPointLights` over a grid's sources, looking only at the lights near the eye: the same
+ * choice, tie for tie, for a world of thousands of fixed lights that the plain scan would visit
+ * every frame. See `lightGrid.ts` for why the result is the scan's exactly.
+ */
+export declare function selectGridLights(grid: LightGrid, x: number, y: number, z: number, out: PointLightBuffer, timeSeconds?: number, viewRange?: number, castX?: number, castY?: number, castZ?: number): void;

package/dist/render/pointLightSelection.js

@@ -1,6 +1,7 @@
 /** Allocation-free selection and packing of point lights for a fixed shader budget. */
 import { POINT_LIGHT_COS_INNER, POINT_LIGHT_COS_OUTER } from './clusteredLights.js';
 import { MAX_POINT_LIGHTS, POINT_SHADOW_POOL } from './lightBudget.js';
+import { gatherLights } from './lightGrid.js';
 export const DEFAULT_POINT_LIGHT_VIEW_RANGE = 180;
 /**
  * How far out a light fades to nothing, in metres before its cull distance.
@@ -38,8 +39,15 @@ const FADE_BAND_M = 40;
  * while it is still too dim to show one.
  */
 const CONTENTION_BAND_M = 3;
-/** Sort keys for the shadow list, which is ordered independently of the shaded one. */
-const shadowRank = new Float32Array(POINT_SHADOW_POOL);
+/**
+ * Sort keys for the shadow list, which is ordered independently of the shaded one.
+ *
+ * **Float64, and ties broken by source index**, the shaded list's rule. These were single precision
+ * compared against a double, so which of two lamps exactly as far away came first depended on
+ * which way the distance happened to round — and on the order the lamps were met, which is what a
+ * grid changes. Now the list is the same whatever order its candidates arrive in.
+ */
+const shadowRank = new Float64Array(POINT_SHADOW_POOL);
 /**
  * Every light in range this frame, by source index and squared distance, before the nearest are
  * chosen. Grown when a world offers more than it has held, and never shrunk, so a frame allocates
@@ -177,6 +185,19 @@ export function createPointLightBuffer(capacity = MAX_POINT_LIGHTS) {
  * makes the distance the *same arithmetic on the same operands*, not merely a close number.
  */
 export function selectPointLights(sources, x, y, z, out, timeSeconds = 0, viewRange = DEFAULT_POINT_LIGHT_VIEW_RANGE, castX = x, castY = y, castZ = z) {
+    choose(sources, null, sources.length, x, y, z, out, timeSeconds, viewRange, castX, castY, castZ);
+}
+/**
+ * `selectPointLights` over a grid's sources, looking only at the lights near the eye: the same
+ * choice, tie for tie, for a world of thousands of fixed lights that the plain scan would visit
+ * every frame. See `lightGrid.ts` for why the result is the scan's exactly.
+ */
+export function selectGridLights(grid, x, y, z, out, timeSeconds = 0, viewRange = DEFAULT_POINT_LIGHT_VIEW_RANGE, castX = x, castY = y, castZ = z) {
+    const count = gatherLights(grid, x, y, z, viewRange + grid.maxRadius);
+    choose(grid.sources, grid.gathered, count, x, y, z, out, timeSeconds, viewRange, castX, castY, castZ);
+}
+/** The choice itself, over every source or over the ones `visit` names, in source order. */
+function choose(sources, visit, visitCount, x, y, z, out, timeSeconds, viewRange, castX, castY, castZ) {
     out.count = 0;
     out.shadowCount = 0;
     /*
@@ -193,7 +214,8 @@ export function selectPointLights(sources, x, y, z, out, timeSeconds = 0, viewRa
      */
     let cutSq = Infinity;
     let candidateCount = 0;
-    for (let sourceIndex = 0; sourceIndex < sources.length; sourceIndex++) {
+    for (let visited = 0; visited < visitCount; visited++) {
+        const sourceIndex = visit === null ? visited : visit[visited];
         const light = sources[sourceIndex];
         if (light === undefined)
             continue;
@@ -265,7 +287,10 @@ export function selectPointLights(sources, x, y, z, out, timeSeconds = 0, viewRa
         if (castDistanceSq >= light.radius * light.radius)
             continue;
         let shadowSlot = out.shadowCount;
-        while (shadowSlot > 0 && (shadowRank[shadowSlot - 1] ?? 0) > castDistanceSq)
+        while (shadowSlot > 0 &&
+            ((shadowRank[shadowSlot - 1] ?? 0) > castDistanceSq ||
+                ((shadowRank[shadowSlot - 1] ?? 0) === castDistanceSq &&
+                    (out.shadowIndex[shadowSlot - 1] ?? -1) > sourceIndex)))
             shadowSlot--;
         if (shadowSlot >= POINT_SHADOW_POOL)
             continue;

package/dist/render/rainField.d.ts

@@ -49,6 +49,17 @@ export interface RainFieldOptions {
     streakSec?: number;
     /** The ground drops land on, and the roofs they do not fall through. */
     ground?: GroundSurface;
+    /**
+     * How near the viewer a streak may pass and still be drawn, metres. Default 1.
+     *
+     * **A drop that close is out of any focus a camera holds**, and drawn sharp it was a bar across
+     * the frame: a streak is a world-space width, so a 6 mm drop 30 cm from the eye drew fourteen
+     * pixels thick and as long as the frame, from a city seen from the air in the rain. A streak
+     * whose nearest point is inside this distance is not drawn; the drop keeps falling, as a
+     * sheltered one does. What it gives up is rain on a lens or a visor, which this field never
+     * drew as such anyway. What would make it wrong is a view that wants drops in macro: pass 0.
+     */
+    clearM?: number;
 }
 export declare class RainField {
     readonly segments: LineSegments;
@@ -71,6 +82,8 @@ export declare class RainField {
      */
     streakSec: number;
     private readonly ground;
+    /** How near the viewer a streak may pass and still be drawn, squared. */
+    private readonly clear2;
     /** Drops not drawn this update because something was over them. */
     private sheltered;
     /**

package/dist/render/rainField.js

@@ -41,6 +41,8 @@ export class RainField {
      */
     streakSec;
     ground;
+    /** How near the viewer a streak may pass and still be drawn, squared. */
+    clear2;
     /** Drops not drawn this update because something was over them. */
     sheltered = 0;
     /**
@@ -68,6 +70,8 @@ export class RainField {
         this.speedMps = options.speedMps ?? 9;
         this.streakSec = options.streakSec ?? 0.04;
         this.ground = options.ground ?? null;
+        const clear = options.clearM ?? 1;
+        this.clear2 = clear * clear;
         this.segments = createLineSegments(options.count);
         this.x = new Float32Array(options.count);
         this.y = new Float32Array(options.count);
@@ -141,15 +145,33 @@ export class RainField {
                 this.sheltered++;
                 continue;
             }
+            /* Where it was a shutter-time ago, which is the streak: down by its fall and back along the
+               wind, so a gust leans every drop at the same angle without anything trigonometric. */
+            const backX = -windX * this.streakSec;
+            const backY = this.speedMps * this.streakSec;
+            const backZ = -windZ * this.streakSec;
+            /* Too near the eye to be drawn (`clearM`): the streak's nearest point to the viewer. */
+            if (this.clear2 > 0) {
+                const ox = dropX - viewerX;
+                const oy = dropY - viewerY;
+                const oz = dropZ - viewerZ;
+                const length2 = backX * backX + backY * backY + backZ * backZ;
+                const along = length2 > 0
+                    ? Math.min(Math.max(-(ox * backX + oy * backY + oz * backZ) / length2, 0), 1)
+                    : 0;
+                const nx = ox + backX * along;
+                const ny = oy + backY * along;
+                const nz = oz + backZ * along;
+                if (nx * nx + ny * ny + nz * nz < this.clear2)
+                    continue;
+            }
             const at = this.segments.count;
             this.segments.from[at * 3] = dropX;
             this.segments.from[at * 3 + 1] = dropY;
             this.segments.from[at * 3 + 2] = dropZ;
-            /* Where it was a shutter-time ago, which is the streak: down by its fall and back along the
-               wind, so a gust leans every drop at the same angle without anything trigonometric. */
-            this.segments.to[at * 3] = dropX - windX * this.streakSec;
-            this.segments.to[at * 3 + 1] = dropY + this.speedMps * this.streakSec;
-            this.segments.to[at * 3 + 2] = dropZ - windZ * this.streakSec;
+            this.segments.to[at * 3] = dropX + backX;
+            this.segments.to[at * 3 + 1] = dropY + backY;
+            this.segments.to[at * 3 + 2] = dropZ + backZ;
             this.segments.count = at + 1;
         }
         this.primed = true;

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

@@ -0,0 +1,11 @@
+/**
+ * Where output pixel (`outX`, `outY`) — its centre, in pixels — falls among the render texels
+ * jittered by (`jitterX`, `jitterY`) render texels: into `out`, the cell's first texel and the
+ * fraction across it, `[x, y, fx, fy]`.
+ */
+export declare function lateDepthCell(outX: number, outY: number, renderWidth: number, renderHeight: number, outputWidth: number, outputHeight: number, jitterX: number, jitterY: number, out: Float64Array | Float32Array): void;
+/**
+ * The depth to test against, from `taps` — a 4x4 block of render texels, row-major, starting one
+ * texel up and left of the cell's first — at (`fx`, `fy`) across the cell.
+ */
+export declare function lateDepthAt(taps: ArrayLike<number>, fx: number, fy: number): number;

package/dist/render/recon/lateDepth.js

@@ -0,0 +1,70 @@
+/**
+ * The depth a reconstructing frame's late draws are tested against at an output pixel, taken from
+ * the render's jittered depth. `shaders/recon/lateDepth.wgsl.ts` is the same arithmetic on the device.
+ *
+ * **Each surface taken to the pixel, and the nearest of them.** A late draw — a glow, a pane, a
+ * caption — is drawn unjittered at the output size, and it has to meet the depth of what it lies on
+ * where *it* is. Each of the four render texels about the pixel, placed where the jitter put it,
+ * carries its surface on to the pixel's unjittered centre along that surface's own slope; the
+ * nearest of the four so carried stands, and a quarter of its slope is given back toward the far
+ * side so that a draw lying exactly on the surface is not decided by rounding. On a plane all four
+ * arrive at the plane's own depth at the pixel: exact, and the same whatever the jitter was.
+ *
+ * **A texel's slope is the smaller of its two differences along each axis, and none where they
+ * disagree in sign** — the minmod limiter. Beside an edge one difference is the jump, so it is the
+ * other, the surface's own, that is taken; a sliver one texel wide disagrees both ways and keeps its
+ * own depth, the nearest of the four as before. So a translucent draw still never comes through an
+ * opaque edge the render covered by more than the render's own texel.
+ *
+ * **Why this replaced the nearest of the four.** On a wall seen aslant the nearest of four neighbours
+ * stands up to a texel's step in front of the wall at the pixel, so a glow lying a few centimetres
+ * proud of it was judged behind the wall; and which neighbour was nearest moved with the jitter, so
+ * the glow was drawn one frame and not the next. Measured on a street of lit facades: every strip of
+ * glow on every tower flickered frame by frame, 12,415 pixels of one tower between two frames.
+ *
+ * What it gives up: a surface curving within a texel is carried on as a plane, which a quarter-step
+ * tolerance covers. What would make it wrong is depth that is not affine on a plane — a depth written
+ * from the fragment stage — which nothing drawn before the late pass writes.
+ */
+import { REVERSED_DEPTH } from '../depthConvention.js';
+/** The share of a surface's slope given back toward the far side, for a draw lying on it. */
+const TOLERANCE_SHARE = 0.25;
+/** The smaller of two differences, or none where they disagree in sign. */
+function minmod(a, b) {
+    if (a * b <= 0)
+        return 0;
+    return Math.abs(a) < Math.abs(b) ? a : b;
+}
+/**
+ * Where output pixel (`outX`, `outY`) — its centre, in pixels — falls among the render texels
+ * jittered by (`jitterX`, `jitterY`) render texels: into `out`, the cell's first texel and the
+ * fraction across it, `[x, y, fx, fy]`.
+ */
+export function lateDepthCell(outX, outY, renderWidth, renderHeight, outputWidth, outputHeight, jitterX, jitterY, out) {
+    /* A texel stands at its index plus a half less the jitter, as the resolve places it. */
+    const x = (outX * renderWidth) / outputWidth - 0.5 + jitterX;
+    const y = (outY * renderHeight) / outputHeight - 0.5 + jitterY;
+    out[0] = Math.floor(x);
+    out[1] = Math.floor(y);
+    out[2] = x - Math.floor(x);
+    out[3] = y - Math.floor(y);
+}
+/**
+ * The depth to test against, from `taps` — a 4x4 block of render texels, row-major, starting one
+ * texel up and left of the cell's first — at (`fx`, `fy`) across the cell.
+ */
+export function lateDepthAt(taps, fx, fy) {
+    const t = (x, y) => taps[(y + 1) * 4 + x + 1];
+    let depth = REVERSED_DEPTH ? -Infinity : Infinity;
+    for (let oy = 0; oy < 2; oy += 1) {
+        for (let ox = 0; ox < 2; ox += 1) {
+            const d = t(ox, oy);
+            const gx = minmod(t(ox + 1, oy) - d, d - t(ox - 1, oy));
+            const gy = minmod(t(ox, oy + 1) - d, d - t(ox, oy - 1));
+            const carried = d + gx * (fx - ox) + gy * (fy - oy);
+            const give = TOLERANCE_SHARE * Math.max(Math.abs(gx), Math.abs(gy));
+            depth = REVERSED_DEPTH ? Math.max(depth, carried - give) : Math.min(depth, carried + give);
+        }
+    }
+    return depth;
+}

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

@@ -54,6 +54,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>;
@@ -62,6 +68,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;
 }
 /**
  * How far a render sample's contribution reaches, in output pixels: a Gaussian's standard deviation.
@@ -78,13 +100,21 @@ export declare function reconstructionWeight(dx: number, dy: number): number;
  * pixel away.
  */
 export declare 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 declare const DEPTH_SWING_WIDTH = 3;
 /**
  * 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 declare function resolvePixel(frame: ResolveFrame, ox: number, oy: number, out: Float32Array): void;
+export declare function resolvePixel(frame: ResolveFrame, ox: number, oy: number, out: Float32Array, record?: Float32Array, swingOut?: Float32Array): void;
 /**
  * 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 declare function resolveFrame(frame: ResolveFrame, history: Float32Array, shown: Float32Array): void;
+export declare function resolveFrame(frame: ResolveFrame, history: Float32Array, shown: Float32Array, records?: Float32Array, swings?: Float32Array): void;