@driftengine/core 4.4.2 → 4.6.0

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/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/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/lateRouting.d.ts

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

package/dist/render/recon/lateRouting.js

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

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

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

package/dist/render/recon/mover.js

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

package/dist/render/recon/resolve.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;