@driftengine/core 4.4.2 → 4.6.0

package/src/render/pointShadowArray.ts

@@ -2,6 +2,7 @@ import { mat3 } from 'gl-matrix';
 
 import { createEmptyTexture2D } from './emptyTexture.ts';
 import { LIVE_POINT_SHADOW_MAPS, POINT_SHADOW_POOL } from './lightBudget.ts';
+import { PointGlassTint } from './pointGlassTint.ts';
 import { pointShadowFaceRotation } from './pointShadowImage.ts';
 import { compileProgram, uniformLocations } from './shader.ts';
 import { OCTAHEDRAL_RESOLVE_FRAG, OCTAHEDRAL_RESOLVE_VERT } from './shaders/octahedralResolve.ts';
@@ -34,6 +35,37 @@ export interface PointShadowTarget {
     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 function strideLayers(layers: Int32Array, stride: number): void {
+  if (stride === 1) return;
+  for (let i = 0; i < layers.length; i++) {
+    const layer = layers[i] as number;
+    if (layer >= 0) layers[i] = layer * stride;
+  }
 }
 
 /**
@@ -53,12 +85,16 @@ export interface PointShadowTarget {
  * never the same object.
  */
 export 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: WebGLTexture;
+  /** What the lights' glass lets through, made with the glass layers. */
+  private tint: PointGlassTint | null = null;
 
   private readonly framebuffer: WebGLFramebuffer;
   private readonly scratchTexture: WebGLTexture;
@@ -96,23 +132,8 @@ export class PointShadowArray implements PointShadowTarget {
     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');
@@ -183,6 +204,117 @@ export class PointShadowArray implements PointShadowTarget {
     gl.bindTexture(gl.TEXTURE_2D_ARRAY, null);
   }
 
+  /** The array texture the lit pass samples. Replaced once, when glass first casts. */
+  get texture(): WebGLTexture {
+    return this.current;
+  }
+
+  get hasGlass(): boolean {
+    return this.tint !== null;
+  }
+
+  /** Physical layers a light: 1, or 2 once glass has interleaved the array. */
+  get stride(): number {
+    return this.tint === null ? 1 : 2;
+  }
+
+  /** The glass tint, one layer a light, once glass has cast; the lit pass samples it. */
+  get tintTexture(): WebGLTexture | null {
+    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: WebGL2RenderingContext, tintEdge: number): boolean {
+    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: number, face: number): boolean {
+    return this.tint?.held(layer, face) ?? false;
+  }
+
+  /** The depth scratch, cleared, for the face's glass: `beginFace` exactly. */
+  beginGlassFace(gl: WebGL2RenderingContext): void {
+    this.beginFace(gl);
+  }
+
+  /** 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 {
+    if (this.tint === null) return;
+    this.resolveInto(gl, 2 * layer + 1, face, far, near);
+  }
+
+  beginTintFace(gl: WebGL2RenderingContext): void {
+    this.tint?.beginFace(gl);
+  }
+
+  resolveTintFace(gl: WebGL2RenderingContext, layer: number, face: number, drawn: boolean): void {
+    this.tint?.resolveFace(gl, layer, face, drawn);
+  }
+
+  /** The chain frost reads, for every light whose tint a round touched: once a round. */
+  finishTints(gl: WebGL2RenderingContext): void {
+    this.tint?.fillMips(gl);
+  }
+
   /**
    * Bind the scratch as the render target for one face of one bake, and clear it.
    *
@@ -224,9 +356,20 @@ export class PointShadowArray implements PointShadowTarget {
     face: number,
     far: number,
     near: number,
+  ): void {
+    this.resolveInto(gl, layer * this.stride, face, far, near);
+  }
+
+  /** The scratch into physical layer `physical`'s region for `face`. */
+  private resolveInto(
+    gl: WebGL2RenderingContext,
+    physical: number,
+    face: number,
+    far: number,
+    near: number,
   ): void {
     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);
@@ -267,10 +410,33 @@ export class PointShadowArray implements PointShadowTarget {
   dispose(gl: WebGL2RenderingContext): void {
     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: WebGL2RenderingContext, layers: number): WebGLTexture {
+  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/src/render/pointShadowMap.ts

@@ -36,6 +36,19 @@ export { FACE_COUNT, POINT_SHADOW_NEAR };
 
 const scratchViewProj = mat4.create();
 
+/**
+ * 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 class PointShadowMap {
   readonly size: number;
   /**
@@ -163,6 +176,8 @@ export class PointShadowMap {
     near = POINT_SHADOW_NEAR,
     sourceRadius = DEFAULT_SOURCE_RADIUS,
     maxFaces = FACE_COUNT,
+    /** The face's glass, when glass shadows are on: `PointGlassDraw`. */
+    glass: PointGlassDraw | null = null,
   ): number {
     /*
      * What to render now, **and what to render it for**. A bake in flight owns the parameters
@@ -220,6 +235,7 @@ 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);
@@ -237,5 +253,30 @@ 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.
+   */
+  private bakeGlassFace(
+    gl: WebGL2RenderingContext,
+    array: PointShadowTarget,
+    glass: PointGlassDraw,
+    face: number,
+    plan: FaceRange,
+  ): void {
+    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: WebGL2RenderingContext): void {}
 }

package/src/render/rainField.ts

@@ -53,6 +53,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 class RainField {
@@ -97,6 +108,8 @@ export class RainField {
    */
   streakSec: number;
   private readonly ground: GroundSurface | null;
+  /** How near the viewer a streak may pass and still be drawn, squared. */
+  private readonly clear2: number;
   /** Drops not drawn this update because something was over them. */
   private sheltered = 0;
   /**
@@ -125,6 +138,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);
@@ -212,15 +227,34 @@ export class RainField {
         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/src/render/recon/changeFrames.ts

@@ -0,0 +1,24 @@
+/**
+ * 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: number, inFrame: boolean): number {
+  return inFrame ? serial : serial + 1;
+}
+
+export function keepsPrevious(lastChange: number, frame: number): boolean {
+  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: number, count: number): number {
+  return Math.min(previousCount, count);
+}

package/src/render/recon/lateDepth.ts

@@ -0,0 +1,83 @@
+/**
+ * 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.ts';
+
+/** 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: number, b: number): number {
+  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: number,
+  outY: number,
+  renderWidth: number,
+  renderHeight: number,
+  outputWidth: number,
+  outputHeight: number,
+  jitterX: number,
+  jitterY: number,
+  out: Float64Array | Float32Array,
+): void {
+  /* 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: ArrayLike<number>, fx: number, fy: number): number {
+  const t = (x: number, y: number): number => taps[(y + 1) * 4 + x + 1] as number;
+  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/src/render/recon/lateRouting.ts

@@ -0,0 +1,29 @@
+/**
+ * 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: boolean,
+  mirror: boolean,
+  probe: boolean,
+  presented: boolean,
+): boolean {
+  return reconstructing && !mirror && !probe && !presented;
+}
+
+/** The same set as `routesLate`, named for the other reader. */
+export function tracksMotion(
+  reconstructing: boolean,
+  mirror: boolean,
+  probe: boolean,
+  presented: boolean,
+): boolean {
+  return routesLate(reconstructing, mirror, probe, presented);
+}

package/src/render/recon/mover.ts

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