@driftengine/core 4.4.2 → 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/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/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/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;