@driftengine/core 3.63.0 → 4.1.0

package/dist/render/gpudriven/streamScene.js

@@ -0,0 +1,459 @@
+/**
+ * The frame's geometry, which arrives and leaves while the frame loop runs.
+ *
+ * **`GpuDrivenPass` uploaded its scene in a method called `buildStatic`**, and its constructor said
+ * why: this pipeline's geometry does not move. A voxel world streams chunks as a player walks and
+ * remeshes one on every block they break, so it has to.
+ *
+ * **Four `RangeAlloc`s over what the pass binds**: six arrays the scene keeps — the cluster and
+ * mesh records a frame's culling reads — and two it never keeps. The vertices and the indices go
+ * through a `GeometrySink` straight into the device's buffers when a mesh is placed, because
+ * holding them as well doubled what a world costs, and at the voxel sandbox's radius 32 the copy
+ * was an ArrayBuffer Chrome will not allocate. A mesh claims a run of each, writes its rows, and
+ * hands the runs back when it leaves.
+ *
+ * **One path, not two.** The static case is a scene filled once and never emptied — `streamingScene`
+ * is that, and it is what every caller of `buildGpuDrivenScene` plus `new GpuDrivenPass` becomes.
+ * Two paths would mean the three rigs in `DRAFT_SCENES` exercise the path no published scene uses,
+ * which is how a control stops being a control; `streamScene.test.ts` asserts this class packs a
+ * static scene byte for byte where `buildGpuDrivenScene` packed it.
+ *
+ * **`add` allocates only when a mesh larger than any before it arrives**, because it is called
+ * from a frame loop when a player walks: the scratch it interleaves into grows to the largest mesh
+ * and is reused. A scene filled before its pass mounts is the exception, and it is the static
+ * case: it holds each mesh until the pass attaches, and nothing after. `heldBytes` says which.
+ */
+import { worldClustersInto } from './clusterWorld.js';
+import { cullCutoff } from './cullClusters.js';
+import { INSTANCE_FLOATS, instanceSphereInto } from './instances.js';
+import { RangeAlloc } from './rangeAlloc.js';
+import { sceneShadowBounds } from './shadowCamera.js';
+import { GPU_DRIVEN_VERTEX_FLOATS, glowOf } from './sceneUpload.js';
+/** Eight floats a cluster in `cull`, matching `clusterWorld.ts` and the cull shader's stride. */
+const CULL_FLOATS = 8;
+/** Six floats a cluster in `lod`, matching the LOD shader's `i * 6u`. */
+const LOD_FLOATS = 6;
+/** Four words a cluster in `meta`: index offset, index count, cluster id, mesh index. */
+const META_WORDS = 4;
+/** Sixteen floats a mesh. */
+const TRANSFORM_FLOATS = 16;
+/** Four words a removed mesh while its ranges wait: vertex base and count, index base and count. */
+const WAITING_WORDS = 4;
+/** What a second pass is told. See `attach`. */
+const SPENT = "[driftengine] a streaming scene writes its geometry to one pass's device and keeps no copy, " +
+    "and this one's has already gone to a pass; build the scene again for a second pass";
+/**
+ * A list of changed runs, kept sorted and merged.
+ *
+ * **The same invariant `RangeAlloc` keeps over its holes, for the same reason**: `takeDirty` has to
+ * answer the same way however the frame's adds were ordered, or a capture depends on history.
+ */
+class DirtyList {
+    spans = [];
+    mark(from, to) {
+        if (to <= from)
+            return;
+        let index = 0;
+        while (index < this.spans.length && this.spans[index].from < from)
+            index += 1;
+        this.spans.splice(index, 0, { from, to });
+        /* Merge backwards then forwards, so three touching runs become one. */
+        const previous = index > 0 ? this.spans[index - 1] : undefined;
+        if (previous !== undefined && previous.to >= from) {
+            previous.to = Math.max(previous.to, to);
+            this.spans.splice(index, 1);
+            index -= 1;
+        }
+        let merged = this.spans[index];
+        while (index + 1 < this.spans.length) {
+            const next = this.spans[index + 1];
+            if (next.from > merged.to)
+                break;
+            merged.to = Math.max(merged.to, next.to);
+            this.spans.splice(index + 1, 1);
+            merged = this.spans[index];
+        }
+    }
+    take() {
+        const out = this.spans;
+        this.spans = [];
+        return out;
+    }
+}
+export class StreamingScene {
+    capacity;
+    /** Eight floats a cluster: world centre, radius, cone axis, cutoff. */
+    cull;
+    /** Six floats a cluster: world centre, radius, own error, parent error. */
+    lod;
+    /** Four words a cluster: index offset, index count, cluster id, mesh index. */
+    meta;
+    materialOf;
+    transforms;
+    instanceSpheres;
+    vertexAlloc;
+    indexAlloc;
+    clusterAlloc;
+    meshAlloc;
+    dirtyClusters = new DirtyList();
+    dirtyMeshes = new DirtyList();
+    /**
+     * Scratch `worldClustersInto` needs, sized once.
+     *
+     * It wants `bounds` as four floats a cluster — centre and radius together — and `cones` as four,
+     * where a `ClusterSource` keeps `boundsCentre` / `boundsRadius` and `coneAxis` / `coneCutoff` as
+     * separate arrays. Packing them is a copy a frame loop must not allocate for.
+     */
+    boundScratch;
+    coneScratch;
+    errorScratch;
+    meshScratch;
+    live = 0;
+    /**
+     * **Where the geometry is.** Held a mesh at a time until a pass attaches (`staging`), written
+     * straight to that pass's buffers (`attached`), or nowhere once the pass has gone (`spent`).
+     */
+    state = 'staging';
+    sink = null;
+    staged = new Map();
+    /* What an attached scene interleaves through: grown to the largest mesh, never shrunk. */
+    rowScratch = new Float32Array(0);
+    indexScratch = new Uint32Array(0);
+    /* Geometry ranges a removal freed while attached, given back at the next `takeDirty`. */
+    waiting;
+    waitingCount = 0;
+    constructor(capacity) {
+        const clusters = Math.max(0, Math.floor(capacity.clusters));
+        const meshes = Math.max(0, Math.floor(capacity.meshes));
+        this.capacity = {
+            vertices: Math.max(0, Math.floor(capacity.vertices)),
+            indices: Math.max(0, Math.floor(capacity.indices)),
+            clusters,
+            meshes,
+        };
+        this.cull = new Float32Array(clusters * CULL_FLOATS);
+        this.lod = new Float32Array(clusters * LOD_FLOATS);
+        this.meta = new Uint32Array(clusters * META_WORDS);
+        this.materialOf = new Uint32Array(clusters);
+        this.transforms = new Float32Array(meshes * TRANSFORM_FLOATS);
+        this.instanceSpheres = new Float32Array(meshes * INSTANCE_FLOATS);
+        this.vertexAlloc = new RangeAlloc(this.capacity.vertices);
+        this.indexAlloc = new RangeAlloc(this.capacity.indices);
+        this.clusterAlloc = new RangeAlloc(clusters);
+        this.meshAlloc = new RangeAlloc(meshes);
+        this.boundScratch = new Float32Array(clusters * 4);
+        this.coneScratch = new Float32Array(clusters * 4);
+        this.errorScratch = new Float32Array(clusters * 2);
+        this.meshScratch = new Uint32Array(clusters);
+        /* Room for every mesh the scene can hold being removed in one frame; `hold` grows it past. */
+        this.waiting = new Uint32Array(meshes * WAITING_WORDS);
+    }
+    /** How many clusters currently draw. A removed cluster's slot is still allocated until released. */
+    get liveClusters() {
+        return this.live;
+    }
+    /** Room left on each axis, which `scripts/stream-fragmentation.mjs` and its tests read. */
+    get freeVertices() {
+        return this.vertexAlloc.capacity - this.vertexAlloc.used;
+    }
+    /** The worst each axis ever reached, which is the occupancy a fragmentation run reports. */
+    get highWater() {
+        return {
+            vertices: this.vertexAlloc.highWater,
+            indices: this.indexAlloc.highWater,
+            clusters: this.clusterAlloc.highWater,
+            meshes: this.meshAlloc.highWater,
+        };
+    }
+    /**
+     * The geometry this scene holds on the CPU, in bytes: what is staged for a pass that has not
+     * attached, and the two scratch arrays an attached scene interleaves through. **Nothing past
+     * that** — which is the whole of what `GeometrySink` is for, as a number a test and a readout can
+     * read.
+     */
+    get heldBytes() {
+        let bytes = this.rowScratch.byteLength + this.indexScratch.byteLength;
+        for (const entry of this.staged.values()) {
+            bytes += entry.rows.byteLength + entry.values.byteLength;
+        }
+        return bytes;
+    }
+    /**
+     * Give the scene the one place its geometry goes, and send it everything staged so far.
+     *
+     * **Once, and a second time is refused by name.** The scene keeps no copy of what it has sent,
+     * so a second pass would bind two empty buffers and draw nothing — silently, which is the one
+     * answer this cannot give. The dirty journal already made a scene one pass's: two passes would
+     * each take its spans and each miss the other's.
+     */
+    attach(sink) {
+        if (this.state !== 'staging')
+            throw new Error(SPENT);
+        this.state = 'attached';
+        this.sink = sink;
+        for (const entry of this.staged.values()) {
+            sink.writeVertices(entry.vertexBase, entry.rows, entry.vertexCount);
+            sink.writeIndices(entry.indexBase, entry.values, entry.indexCount);
+        }
+        this.staged.clear();
+    }
+    /**
+     * The pass has gone. Adds and removes still keep the records, and the geometry goes nowhere.
+     *
+     * **Called by `GpuDrivenPass.dispose` before it destroys its buffers**, because a write to a
+     * destroyed buffer is a device error; and nothing waits after it, because nothing reads.
+     */
+    detach() {
+        this.state = 'spent';
+        this.sink = null;
+        this.staged.clear();
+        this.releaseWaiting();
+    }
+    /**
+     * Place a mesh, or refuse.
+     *
+     * **Every claim before any write, and a rollback if the last one fails.** A partial add is a mesh
+     * whose clusters point at vertices another mesh owns, which draws somebody else's geometry rather
+     * than failing — the shape of mistake `packClusters` documents one level up.
+     *
+     * **`null` rather than an exception**, because a streaming consumer calls this from a frame loop
+     * when the player walks: an exception there is a crashed demo where a refusal is a chunk that
+     * arrives a frame later.
+     */
+    add(mesh, transform, material) {
+        const vertexCount = mesh.positions.length / 3;
+        const indexCount = mesh.clusters.indices.length;
+        const clusterCount = mesh.clusters.count;
+        const vertexBase = this.vertexAlloc.claim(vertexCount);
+        const indexBase = vertexBase < 0 ? -1 : this.indexAlloc.claim(indexCount);
+        const clusterBase = indexBase < 0 ? -1 : this.clusterAlloc.claim(clusterCount);
+        const slot = clusterBase < 0 ? -1 : this.meshAlloc.claim(1);
+        if (vertexBase < 0 || indexBase < 0 || clusterBase < 0 || slot < 0) {
+            if (clusterBase >= 0)
+                this.clusterAlloc.release(clusterBase, clusterCount);
+            if (indexBase >= 0)
+                this.indexAlloc.release(indexBase, indexCount);
+            if (vertexBase >= 0)
+                this.vertexAlloc.release(vertexBase, vertexCount);
+            return null;
+        }
+        for (let i = 0; i < TRANSFORM_FLOATS; i += 1) {
+            this.transforms[slot * TRANSFORM_FLOATS + i] = transform[i] ?? 0;
+        }
+        /* The interleave the pass used to do at construction, in the order its shaders index. */
+        const uvs = mesh.uvs;
+        const glow = glowOf(mesh, 'added');
+        const rows = this.rowsFor(vertexCount);
+        for (let v = 0; v < vertexCount; v += 1) {
+            const to = v * GPU_DRIVEN_VERTEX_FLOATS;
+            for (let axis = 0; axis < 3; axis += 1) {
+                rows[to + axis] = mesh.positions[v * 3 + axis];
+                rows[to + 3 + axis] = mesh.normals[v * 3 + axis];
+                rows[to + 6 + axis] = mesh.colours[v * 3 + axis];
+            }
+            rows[to + 9] = uvs === undefined ? 0 : uvs[v * 2];
+            rows[to + 10] = uvs === undefined ? 0 : uvs[v * 2 + 1];
+            rows[to + 11] = glow === undefined ? 0 : glow[v];
+        }
+        /* **Rebased onto the scene**, because the indices arrive addressing the mesh they came from. */
+        const values = this.valuesFor(indexCount);
+        for (let i = 0; i < indexCount; i += 1) {
+            values[i] = mesh.clusters.indices[i] + vertexBase;
+        }
+        this.place(slot, vertexBase, rows, vertexCount, indexBase, values, indexCount);
+        for (let c = 0; c < clusterCount; c += 1) {
+            const record = clusterBase + c;
+            this.meta[record * META_WORDS] = indexBase + mesh.clusters.triangleOffsets[c] * 3;
+            this.meta[record * META_WORDS + 1] = mesh.clusters.triangleCounts[c] * 3;
+            /* Its own position, which is what a pixel in the visibility buffer resolves through. */
+            this.meta[record * META_WORDS + 2] = record;
+            this.meta[record * META_WORDS + 3] = slot;
+            this.materialOf[record] = material;
+            for (let axis = 0; axis < 3; axis += 1) {
+                this.boundScratch[c * 4 + axis] = mesh.clusters.boundsCentre[c * 3 + axis];
+                this.coneScratch[c * 4 + axis] = mesh.clusters.coneAxis[c * 3 + axis];
+            }
+            this.boundScratch[c * 4 + 3] = mesh.clusters.boundsRadius[c];
+            /* Carried as a cosine, read by the cull as a sine: see `cullCutoff`. */
+            this.coneScratch[c * 4 + 3] = cullCutoff(mesh.clusters.coneCutoff[c]);
+            this.errorScratch[c * 2] = mesh.clusters.ownError[c];
+            this.errorScratch[c * 2 + 1] = mesh.clusters.parentError[c];
+            this.meshScratch[c] = slot;
+        }
+        /*
+         * **The bounds are computed here, at the moment the mesh is placed.** `cull` holds them already
+         * multiplied by the transform, and the pass's own constructor records what happened when it did
+         * not: every rig stood at the origin, so nothing ever said so.
+         */
+        worldClustersInto({
+            bounds: this.boundScratch,
+            cones: this.coneScratch,
+            errors: this.errorScratch,
+            meshOf: this.meshScratch,
+            count: clusterCount,
+        }, this.transforms, this.cull, this.lod, clusterBase);
+        instanceSphereInto(this.cull, clusterBase, clusterCount, this.instanceSpheres, slot);
+        this.dirtyClusters.mark(clusterBase, clusterBase + clusterCount);
+        this.dirtyMeshes.mark(slot, slot + 1);
+        this.live += clusterCount;
+        return {
+            mesh: slot,
+            vertexBase,
+            vertexCount,
+            indexBase,
+            indexCount,
+            clusterBase,
+            clusterCount,
+        };
+    }
+    /** Take a mesh out. Its ranges go back and its clusters stop drawing. */
+    remove(handle) {
+        for (let c = 0; c < handle.clusterCount; c += 1) {
+            /*
+             * **The index count, not the offset.** Zero indices is a cluster that draws nothing and that
+             * `instanceCull` rejects before it can write an instance; a zeroed offset is a cluster that
+             * draws somebody else's first triangle.
+             */
+            this.meta[(handle.clusterBase + c) * META_WORDS + 1] = 0;
+            /*
+             * **And its world bounds, because `sceneBounds` reads them.** A released cluster whose cull
+             * record still holds where it used to stand keeps the light's box stretched over a mesh that
+             * is not there — which is a shadow map spread across empty space rather than anything that
+             * fails. A radius of zero is what `sceneShadowBounds` skips.
+             */
+            for (let f = 0; f < CULL_FLOATS; f += 1)
+                this.cull[(handle.clusterBase + c) * CULL_FLOATS + f] = 0;
+        }
+        for (let i = 0; i < INSTANCE_FLOATS; i += 1) {
+            this.instanceSpheres[handle.mesh * INSTANCE_FLOATS + i] = 0;
+        }
+        this.clusterAlloc.release(handle.clusterBase, handle.clusterCount);
+        this.meshAlloc.release(handle.mesh, 1);
+        /* Removed before a pass attached: nothing of it is ever sent. */
+        this.staged.delete(handle.mesh);
+        if (this.state === 'attached') {
+            this.hold(handle);
+        }
+        else {
+            this.indexAlloc.release(handle.indexBase, handle.indexCount);
+            this.vertexAlloc.release(handle.vertexBase, handle.vertexCount);
+        }
+        this.dirtyClusters.mark(handle.clusterBase, handle.clusterBase + handle.clusterCount);
+        this.dirtyMeshes.mark(handle.mesh, handle.mesh + 1);
+        this.live -= handle.clusterCount;
+        /*
+         * **The geometry is deliberately not cleared.** Nothing reads it once no cluster points at it,
+         * and not clearing it is what makes a removal a handful of stores rather than a device write —
+         * which matters, because a player walking away causes one every few frames.
+         */
+    }
+    /** What changed since the last call, then cleared. An unchanged frame uploads nothing. */
+    takeDirty() {
+        /* The uploads the caller is about to make are what stop anything reading a waiting range. */
+        this.releaseWaiting();
+        return {
+            clusters: this.dirtyClusters.take(),
+            meshes: this.dirtyMeshes.take(),
+        };
+    }
+    /**
+     * Where a mesh is interleaved: a fresh array while it has to be held until a pass attaches, and
+     * the one scratch otherwise, grown only when a mesh larger than any before it arrives.
+     */
+    rowsFor(vertexCount) {
+        const floats = vertexCount * GPU_DRIVEN_VERTEX_FLOATS;
+        if (this.state === 'staging')
+            return new Float32Array(floats);
+        if (this.rowScratch.length < floats)
+            this.rowScratch = new Float32Array(floats);
+        return this.rowScratch;
+    }
+    valuesFor(indexCount) {
+        if (this.state === 'staging')
+            return new Uint32Array(indexCount);
+        if (this.indexScratch.length < indexCount)
+            this.indexScratch = new Uint32Array(indexCount);
+        return this.indexScratch;
+    }
+    /** Hand a placed mesh's geometry on, or hold it for the pass that has not attached yet. */
+    place(slot, vertexBase, rows, vertexCount, indexBase, values, indexCount) {
+        if (this.state === 'staging') {
+            this.staged.set(slot, { vertexBase, rows, vertexCount, indexBase, values, indexCount });
+            return;
+        }
+        const sink = this.sink;
+        if (sink === null)
+            return;
+        sink.writeVertices(vertexBase, rows, vertexCount);
+        sink.writeIndices(indexBase, values, indexCount);
+    }
+    /**
+     * Keep a removed mesh's vertex and index ranges from the allocator until the next `takeDirty`.
+     *
+     * **Because the geometry is written when a mesh is added, not when the frame is recorded.** The
+     * pass records its frame at `beginFrame` and submits it at `endFrame`, and a queue write lands
+     * before the frame it was made during runs. A mesh added in that window into a range freed that
+     * frame would be drawn through the removed mesh's clusters, which the device holds until the
+     * next upload. `takeDirty` is that upload's first step, so from then on nothing reads the range.
+     * The cluster and mesh slots do not wait: their records travel together through the journal.
+     */
+    hold(handle) {
+        if ((this.waitingCount + 1) * WAITING_WORDS > this.waiting.length) {
+            const grown = new Uint32Array(Math.max(WAITING_WORDS, this.waiting.length * 2));
+            grown.set(this.waiting);
+            this.waiting = grown;
+        }
+        const at = this.waitingCount * WAITING_WORDS;
+        this.waiting[at] = handle.vertexBase;
+        this.waiting[at + 1] = handle.vertexCount;
+        this.waiting[at + 2] = handle.indexBase;
+        this.waiting[at + 3] = handle.indexCount;
+        this.waitingCount += 1;
+    }
+    releaseWaiting() {
+        const waiting = this.waiting;
+        for (let i = 0; i < this.waitingCount; i += 1) {
+            const at = i * WAITING_WORDS;
+            this.vertexAlloc.release(waiting[at], waiting[at + 1]);
+            this.indexAlloc.release(waiting[at + 2], waiting[at + 3]);
+        }
+        this.waitingCount = 0;
+    }
+    /**
+     * A bounding sphere over every live cluster: centre in floats 0 to 2, radius in float 3.
+     *
+     * **`sceneShadowBounds` itself rather than a second spelling of it**, and that is not tidiness —
+     * the first version of this method wrote a *box* into the same four floats the pass reads a
+     * sphere out of, so the shadow camera was fitted to a sphere centred on the box's minimum corner
+     * with `maxX` as its radius. Two GPU-driven rigs lost their shadows and the maintainer saw it on
+     * the page before the capture diff was read.
+     *
+     * The function's own header already says why there is one copy of this arithmetic: a light's box
+     * that disagrees with the cull's bounds clips casters out of a map the cull believes are in it.
+     * A second copy here was the same mistake one level up.
+     */
+    sceneBounds(out) {
+        sceneShadowBounds(this.cull, CULL_FLOATS, this.capacity.clusters, out);
+    }
+}
+/**
+ * A scene filled once from a list of meshes, which is the static case.
+ *
+ * With no capacity given it sizes itself to exactly what the meshes need, so a static scene
+ * allocates nothing spare and packs where `buildGpuDrivenScene` packed.
+ */
+export function streamingScene(meshes, transforms, capacity) {
+    let vertices = 0;
+    let indices = 0;
+    let clusters = 0;
+    for (const mesh of meshes) {
+        vertices += mesh.positions.length / 3;
+        indices += mesh.clusters.indices.length;
+        clusters += mesh.clusters.count;
+    }
+    const scene = new StreamingScene(capacity ?? { vertices, indices, clusters, meshes: meshes.length });
+    meshes.forEach((mesh, at) => {
+        scene.add(mesh, transforms.subarray(at * TRANSFORM_FLOATS, at * TRANSFORM_FLOATS + TRANSFORM_FLOATS), mesh.material);
+    });
+    return scene;
+}

package/dist/render/gpudriven/surfaceFrame.d.ts

@@ -0,0 +1,25 @@
+/** What a textured pixel needs from its triangle that a compute invocation cannot take for itself. */
+/**
+ * **Two derivatives the forward path gets from the hardware and this pipeline has to build.** A
+ * fragment shader takes `dFdx` and `dFdy`; a compute invocation has no neighbours. The shading
+ * pass already has the analytic barycentric gradients — `SHADE_SURFACE_WGSL` builds them for the
+ * shadow's receiver plane — and any attribute's screen gradient is those weights applied to its
+ * three corners. The UV's picks a mip level; the UV's and the world position's together build the
+ * tangent frame a normal map is read through.
+ */
+/**
+ * The mip level a pixel's texture footprint asks for: the log of the longer of the two screen-axis
+ * UV steps, in texels. The common isotropic form; a device choosing its own level for an
+ * implicit-derivative sample may differ in the last bits, which is stated where the two pipelines
+ * are compared rather than hidden here.
+ */
+export declare function surfaceLod(dudx: number, dvdx: number, dudy: number, dvdy: number, size: number): number;
+/**
+ * `tangentFrame.ts`'s derived branch, from analytic gradients instead of `dFdx` and `dFdy`.
+ *
+ * **Term for term, including the determinant's sign and the one scale for both axes**, because the
+ * forward path's comment records what each is worth: without the sign the frame points the other
+ * way on one backend, and two scales shear a stretched UV layout. The screen axes here are x to the
+ * right and y up, as the shading pass measures them; the fold makes the answer the same either way.
+ */
+export declare function derivedTangentFrame(n: readonly [number, number, number], dp1: readonly [number, number, number], dp2: readonly [number, number, number], duv1: readonly [number, number], duv2: readonly [number, number], out: Float32Array): Float32Array;

package/dist/render/gpudriven/surfaceFrame.js

@@ -0,0 +1,51 @@
+/** What a textured pixel needs from its triangle that a compute invocation cannot take for itself. */
+/**
+ * **Two derivatives the forward path gets from the hardware and this pipeline has to build.** A
+ * fragment shader takes `dFdx` and `dFdy`; a compute invocation has no neighbours. The shading
+ * pass already has the analytic barycentric gradients — `SHADE_SURFACE_WGSL` builds them for the
+ * shadow's receiver plane — and any attribute's screen gradient is those weights applied to its
+ * three corners. The UV's picks a mip level; the UV's and the world position's together build the
+ * tangent frame a normal map is read through.
+ */
+/**
+ * The mip level a pixel's texture footprint asks for: the log of the longer of the two screen-axis
+ * UV steps, in texels. The common isotropic form; a device choosing its own level for an
+ * implicit-derivative sample may differ in the last bits, which is stated where the two pipelines
+ * are compared rather than hidden here.
+ */
+export function surfaceLod(dudx, dvdx, dudy, dvdy, size) {
+    const footprint = Math.max(Math.hypot(dudx, dvdx), Math.hypot(dudy, dvdy)) * size;
+    return Math.max(Math.log2(Math.max(footprint, 1e-30)), 0);
+}
+/**
+ * `tangentFrame.ts`'s derived branch, from analytic gradients instead of `dFdx` and `dFdy`.
+ *
+ * **Term for term, including the determinant's sign and the one scale for both axes**, because the
+ * forward path's comment records what each is worth: without the sign the frame points the other
+ * way on one backend, and two scales shear a stretched UV layout. The screen axes here are x to the
+ * right and y up, as the shading pass measures them; the fold makes the answer the same either way.
+ */
+export function derivedTangentFrame(n, dp1, dp2, duv1, duv2, out) {
+    const p2x = dp2[1] * n[2] - dp2[2] * n[1];
+    const p2y = dp2[2] * n[0] - dp2[0] * n[2];
+    const p2z = dp2[0] * n[1] - dp2[1] * n[0];
+    const p1x = n[1] * dp1[2] - n[2] * dp1[1];
+    const p1y = n[2] * dp1[0] - n[0] * dp1[2];
+    const p1z = n[0] * dp1[1] - n[1] * dp1[0];
+    const tx = p2x * duv1[0] + p1x * duv2[0];
+    const ty = p2y * duv1[0] + p1y * duv2[0];
+    const tz = p2z * duv1[0] + p1z * duv2[0];
+    const bx = p2x * duv1[1] + p1x * duv2[1];
+    const by = p2y * duv1[1] + p1y * duv2[1];
+    const bz = p2z * duv1[1] + p1z * duv2[1];
+    const det = duv1[0] * duv2[1] - duv2[0] * duv1[1];
+    const handed = det < 0 ? -1 : 1;
+    const scale = handed / Math.sqrt(Math.max(tx * tx + ty * ty + tz * tz, bx * bx + by * by + bz * bz, 1e-12));
+    out[0] = tx * scale;
+    out[1] = ty * scale;
+    out[2] = tz * scale;
+    out[3] = bx * scale;
+    out[4] = by * scale;
+    out[5] = bz * scale;
+    return out;
+}

package/dist/render/gpudriven/twoPhase.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Occlusion tested against depth from **this** frame rather than the last one.
+ *
+ * A hierarchical depth buffer is only an occluder if something has already been drawn into it, and
+ * the cheap way to have one at the start of a frame is to keep last frame's. That is wrong exactly
+ * when the camera moved: the pyramid describes a view nobody is looking from, and geometry the old
+ * view happened to hide is culled out of the new one. What it looks like is a wall or a floor
+ * disappearing for a frame or two after a cut, a teleport, or a fast turn — and it is intermittent,
+ * so it is reported as a streaming fault.
+ *
+ * **So the frame is drawn in two halves.** Phase one draws only what was visible last frame, which
+ * on a continuous camera is nearly everything and is a good occluder for the rest. The pyramid is
+ * reduced from *that* depth. Phase two then tests everything else against it and draws whatever
+ * phase one missed. Both halves write the same colour and depth, because they are one frame.
+ *
+ * **The history decides which phase a cluster is judged in and never whether it is judged.** Every
+ * cluster is in exactly one of the two lists, whatever the history holds, so a history that is
+ * stale — which after a teleport is all of it — costs a phase-two test and never a hole. That
+ * invariant is what makes the history safe to keep across a cut, and it is the one this file's
+ * tests assert most directly.
+ *
+ * **One history per view.** A shadow pass and the main camera see different things, and sharing a
+ * bit set between them puts one view's visibility into the other's phase one — which is the same
+ * defect as a stale history, arriving every frame instead of after a cut.
+ *
+ * The pass recording here is the frame graph's data rather than device calls: `phaseOnePasses` and
+ * `phaseTwoPasses` record what each half reads and writes, and the edge from the reduction's write
+ * to phase two's read *is* the guarantee in the first paragraph. Wiring them to a real encoder is
+ * Task 14's, against a consumer, for the reason `ARCHITECTURE.md` §3 gives about rendering changes
+ * nobody has looked at.
+ */
+import type { Deps } from '../frame/deps.ts';
+/** Which clusters a view drew last frame, one bit each. */
+export interface VisibilityHistory {
+    /** Thirty-two clusters a word, cluster `n` at bit `n & 31` of word `n >> 5`. */
+    bits: Uint32Array;
+    /** How many clusters it has room for. A wider one is allocated rather than the old one read. */
+    capacity: number;
+}
+export declare function createVisibilityHistory(capacity: number): VisibilityHistory;
+/**
+ * Whether a cluster was drawn last frame.
+ *
+ * **Out of range answers false rather than throwing or wrapping.** A cluster index past the end is
+ * a scene that grew since the history was made, and the honest answer for one nobody has seen is
+ * "not last frame" — which puts it in phase two, where it is tested rather than assumed. Wrapping
+ * would put an unrelated cluster's bit in its place, which is a visibility answer for the wrong
+ * geometry and is invisible until it is wrong.
+ *
+ * **A perturbation survives this check and it is kept anyway.** `setHistory` refuses the same
+ * range, so no bit above `capacity` can ever be set, and a read past the end of the word array is
+ * `undefined` — which `&` coerces to zero and therefore answers false already. What it decides is
+ * the case where the two guards disagree, and the reason both are here rather than one is that
+ * they are read independently: the write side is the one a test can catch, and it is caught. The
+ * bits between `capacity` and the end of the last word are the ones that make the write side
+ * matter — forty clusters is two words, so twenty-four of them belong to nobody.
+ */
+export declare function historyHas(history: VisibilityHistory, cluster: number): boolean;
+export declare function setHistory(history: VisibilityHistory, cluster: number, drawn: boolean): void;
+export declare function clearHistory(history: VisibilityHistory): void;
+/** How many of the first `count` clusters the history holds. */
+export declare function historyCount(history: VisibilityHistory, count: number): number;
+/** The clusters phase one draws: exactly what was visible last frame, in index order. */
+export declare function phaseOneClusters(history: VisibilityHistory, count: number, out: Uint32Array): number;
+/** The clusters phase two tests: everything the history does not hold. */
+export declare function phaseTwoClusters(history: VisibilityHistory, count: number, out: Uint32Array): number;
+/**
+ * Replace the history with what this frame actually drew.
+ *
+ * **Replace rather than accumulate**, and that is the half that is easy to leave out: a cluster
+ * kept in phase one and then culled in phase two has to leave the set, or it is drawn every frame
+ * for ever on the strength of having once been visible. `keep` is the flag buffer
+ * `cullClusters` writes, so this is one pass over the same array the draw used.
+ */
+export declare function updateHistory(history: VisibilityHistory, keep: Uint32Array, count: number): void;
+/** Every view's history, keyed by whatever identifier the caller gives its views. */
+export interface VisibilityHistories {
+    readonly byView: Map<number, VisibilityHistory>;
+}
+export declare function createVisibilityHistories(): VisibilityHistories;
+/**
+ * This view's history, widened in place if the scene grew.
+ *
+ * **Widened rather than replaced**, because replacing it throws away a frame of visibility every
+ * time a cluster is added and puts the whole scene through phase two — which is correct and is
+ * also the slow path this feature exists to avoid.
+ */
+export declare function historyFor(store: VisibilityHistories, view: number, capacity: number): VisibilityHistory;
+/** The virtual resources a two-phase frame moves between its halves. */
+export interface TwoPhaseResources {
+    readonly colour: number;
+    readonly depth: number;
+    readonly hzb: number;
+    readonly clusters: number;
+    readonly keep: number;
+}
+/** Where phase one's two nodes landed in the dependency table. */
+export interface PhaseOneNodes {
+    readonly draw: number;
+    readonly reduce: number;
+}
+/** Where phase two's two nodes landed. */
+export interface PhaseTwoNodes {
+    readonly cull: number;
+    readonly draw: number;
+}
+/**
+ * Phase one: draw what was visible, then reduce the depth it produced into the pyramid.
+ *
+ * The reduction reads the depth the draw wrote, so nothing can reorder them and nothing can alias
+ * the depth away between them — which is exactly what `lifetime.ts` and `alias.ts` are reading
+ * these edges for.
+ */
+export declare function phaseOnePasses(deps: Deps, res: TwoPhaseResources): PhaseOneNodes;
+/**
+ * Phase two: cull everything else against that pyramid, then draw what survived.
+ *
+ * `cull` reads `hzb`, which `phaseOnePasses` wrote. That one edge is the whole claim of this
+ * module — the depth being tested against belongs to this frame — expressed where the scheduler
+ * can enforce it rather than in a comment somebody has to obey.
+ */
+export declare function phaseTwoPasses(deps: Deps, res: TwoPhaseResources): PhaseTwoNodes;