@driftengine/core 3.63.0 → 4.0.0

package/dist/render/gpudriven/cullClusters.js

@@ -0,0 +1,237 @@
+/**
+ * Which clusters are worth rasterising: the three tests, in the order that makes them cheap.
+ *
+ * Frustum first, because it is six dot products and throws away most of a world. Then the normal
+ * cone, which is one more dot product and throws away roughly half of what is left on a closed
+ * surface. Then the hierarchical depth buffer, which costs a projection and four texel reads and
+ * is the only one that needs anything from this frame.
+ *
+ * **Every one of them is conservative in the same direction.** A cluster that might be visible
+ * survives; only a cluster that provably cannot be seen is dropped. Culling something visible is a
+ * hole in the picture that comes and goes with the camera and is diagnosed as almost anything
+ * else; keeping something invisible is a wasted draw. `frustum.ts` says the same in its own words
+ * and the two files have to agree about it, because a pipeline whose stages disagree about which
+ * way to round is one that drops geometry at exactly the boundaries.
+ *
+ * **The compaction is here and the flags are the device's.** A dispatch can decide every cluster
+ * in parallel and cannot append them in order without a prefix sum, so the shader writes one flag
+ * per cluster and this writes the ordered list from the flags. That split is also what
+ * `scripts/gpu-parity.mjs` compares: the flags are order-free, so they can be checked
+ * element-by-element against a reference that has not had to reproduce an atomic's arrival order.
+ */
+import { sphereOutsideFrustum } from './frustum.js';
+import { hzbOccluded } from './hzb.js';
+/** Eight floats a cluster: centre, radius, cone axis, cone cutoff. `clusterUpload.ts` packs them. */
+export const CLUSTER_CULL_FLOATS = 8;
+/** What a kept cluster's flag holds. One rather than a bit mask: there is one reason to keep. */
+export const CLUSTER_KEEP = 1;
+/**
+ * A cluster's cone as it is carried, turned into the cutoff `coneBackfacing` reads.
+ *
+ * **A cluster carries a cosine and this test is written in a sine**, and until 2026-09-18 nothing
+ * said so. `buildClusters` writes "the minimum dot product of any face normal against the axis",
+ * the `MSHL` container stores that and says so, and `ClusterSource` passed it through to the test
+ * below untouched. Every cluster before then was a single quad or a near-flat patch, whose cosine
+ * of about one reads as a sine of one — a hemisphere, never culled — so the mismatch was silent and
+ * cone culling simply did not happen. The voxel sandbox grows its clusters by position, across
+ * every direction a block faces: a cosine of zero read as a sine of zero is a flat cluster, and a
+ * canopy seen from below lost every block whose cluster pointed up.
+ *
+ * `cos(a)` at or above zero is `sin(a) = sqrt(1 - cos(a)^2)`. Below zero the cone is wider than a
+ * hemisphere and no aim of the eye sees every face from behind, so the answer is one, which the
+ * test can never satisfy. Converted where a cluster is packed, once, so neither shader nor
+ * reference changes.
+ */
+export function cullCutoff(minimumDot) {
+    if (minimumDot < 0)
+        return 1;
+    return Math.sqrt(Math.max(0, 1 - minimumDot * minimumDot));
+}
+/**
+ * Whether every triangle in a cluster faces away from the eye.
+ *
+ * **`cutoff` is `sin(a)`**, where `a` is the half-angle of the cone containing every normal. Zero
+ * is a flat cluster; one is a cluster whose normals span a hemisphere, which can never be culled
+ * because the test below cannot be satisfied. Stating it as a sine rather than a cosine is what
+ * makes the expression a single comparison with no trigonometry in the shader.
+ *
+ * The derivation, because the constant is otherwise unfalsifiable. Let `d` be the vector from the
+ * eye to the cluster's centre. Directions from the eye to points on the cluster lie within
+ * `b = asin(radius / |d|)` of `d`. A triangle is backfacing when its normal has a positive dot
+ * with the direction the eye looks along it, so *every* triangle is backfacing when
+ * `angle(axis, d) + a + b < 90 degrees`, which is `dot(axis, normalise(d)) > sin(a + b)`.
+ * Expanding `sin(a + b)` to `sin a + radius / |d|` is exact at `a = 0` and errs on the side of
+ * keeping a cluster everywhere else, which is the direction this file rounds.
+ *
+ * Multiplied through by `|d|` so there is no divide and no normalise.
+ */
+export function coneBackfacing(axisX, axisY, axisZ, cutoff, centreX, centreY, centreZ, radius, eyeX, eyeY, eyeZ) {
+    const dx = centreX - eyeX;
+    const dy = centreY - eyeY;
+    const dz = centreZ - eyeZ;
+    const distance = Math.sqrt(dx * dx + dy * dy + dz * dz);
+    return dx * axisX + dy * axisY + dz * axisZ >= cutoff * distance + radius;
+}
+/**
+ * The screen rectangle a sphere covers and the nearest clip depth it reaches.
+ *
+ * Writes `minX, minY, maxX, maxY, nearestDepth` into `out`, in the [0, 1] range a texture
+ * coordinate uses, and answers **false when the sphere has no rectangle at all** — when any part
+ * of it is at or behind the eye. That case is the reason this returns a boolean rather than
+ * clamping: a sphere straddling the near plane does not project to a rectangle, and every
+ * implementation that pretends it does culls it on the frames where the wrap happens to land
+ * outside the screen and keeps it on the frames where it does not. What that looks like is
+ * geometry flickering as the camera moves through it, which is the defect this function's shape
+ * exists to prevent.
+ *
+ * The eight corners of the sphere's bounding box rather than an analytic silhouette: the box is
+ * larger than the sphere, so the rectangle is conservative, and it is eight transforms instead of
+ * a quadratic.
+ */
+export function sphereScreenBounds(viewProj, centreX, centreY, centreZ, radius, out) {
+    let minX = Number.POSITIVE_INFINITY;
+    let minY = Number.POSITIVE_INFINITY;
+    let maxX = Number.NEGATIVE_INFINITY;
+    let maxY = Number.NEGATIVE_INFINITY;
+    let nearest = Number.NEGATIVE_INFINITY;
+    for (let corner = 0; corner < 8; corner += 1) {
+        const x = centreX + (corner & 1 ? radius : -radius);
+        const y = centreY + (corner & 2 ? radius : -radius);
+        const z = centreZ + (corner & 4 ? radius : -radius);
+        const cw = viewProj[3] * x +
+            viewProj[7] * y +
+            viewProj[11] * z +
+            viewProj[15];
+        /* At or behind the eye, so there is no rectangle. See the header. */
+        if (cw <= 1e-6)
+            return false;
+        const cx = viewProj[0] * x +
+            viewProj[4] * y +
+            viewProj[8] * z +
+            viewProj[12];
+        const cy = viewProj[1] * x +
+            viewProj[5] * y +
+            viewProj[9] * z +
+            viewProj[13];
+        const cz = viewProj[2] * x +
+            viewProj[6] * y +
+            viewProj[10] * z +
+            viewProj[14];
+        const inverse = 1 / cw;
+        const u = cx * inverse * 0.5 + 0.5;
+        const v = cy * inverse * 0.5 + 0.5;
+        minX = Math.min(minX, u);
+        maxX = Math.max(maxX, u);
+        minY = Math.min(minY, v);
+        maxY = Math.max(maxY, v);
+        /* Nearest is the *largest* clip depth here; `depthConvention.ts` puts the near plane at 1. */
+        nearest = Math.max(nearest, cz * inverse);
+    }
+    out[0] = minX;
+    out[1] = minY;
+    out[2] = maxX;
+    out[3] = maxY;
+    out[4] = nearest;
+    return true;
+}
+/**
+ * The pyramid level whose texels are wide enough that four of them cover the rectangle.
+ *
+ * `ceil(log2(longest side in texels))` minus one, floored at zero: at that level the rectangle
+ * spans at most two texels each way, which is what a four-texel gather reads. One level coarser
+ * would read a texel covering geometry outside the rectangle and cull against an occluder that is
+ * not in front of this cluster at all.
+ *
+ * Clamped to the top of the pyramid, because a rectangle larger than the screen is a cluster the
+ * camera is inside and there is no level coarse enough for it.
+ */
+export function hzbLevelFor(rectWidthTexels, rectHeightTexels, width, height) {
+    const longest = Math.max(rectWidthTexels, rectHeightTexels, 1);
+    const level = Math.max(0, Math.ceil(Math.log2(longest)) - 1);
+    const top = Math.floor(Math.log2(Math.max(1, Math.max(width, height))));
+    return Math.min(level, top);
+}
+/**
+ * Whether a rectangle's nearest depth is behind everything already drawn under it.
+ *
+ * **The weakest of the four texels decides.** Each holds the furthest depth in its own region, so
+ * a cluster is hidden only where it is behind *all* of them — and under reversed-Z the furthest of
+ * four is the smallest. Taking the nearest instead would cull a cluster visible through a gap,
+ * which is the failure mode that reads as holes appearing in geometry as the camera turns.
+ */
+export function clusterOccluded(depths, offsets, width, height, minX, minY, maxX, maxY, nearestDepth) {
+    const level = hzbLevelFor((maxX - minX) * width, (maxY - minY) * height, width, height);
+    if (level >= offsets.length)
+        return false;
+    const levelWidth = Math.max(1, width >> level);
+    const levelHeight = Math.max(1, height >> level);
+    const base = offsets[level];
+    const x0 = Math.max(0, Math.min(levelWidth - 1, Math.floor(minX * levelWidth)));
+    const x1 = Math.max(0, Math.min(levelWidth - 1, Math.floor(maxX * levelWidth)));
+    /*
+     * **The rows run the other way, and the swap is not cosmetic.** `sphereScreenBounds` reports the
+     * rectangle in clip-up coordinates — `v` of 1 is clip `y` of +1 — and the pyramid is seeded
+     * straight from the depth texture, whose row 0 is exactly there. So a `v` used as a row index
+     * reads the mirror of what the cluster covers, and the top edge of the rectangle becomes the
+     * bottom row.
+     *
+     * It shipped that way and drew holes: geometry near the top of the frame tested against whatever
+     * stood near the bottom, coming and going with the camera. `gpu-parity.mjs` agreed about it for
+     * as long, because the WGSL made the same mistake — a parity check compares two implementations
+     * and neither of them is the truth.
+     */
+    const y0 = Math.max(0, Math.min(levelHeight - 1, Math.floor((1 - maxY) * levelHeight)));
+    const y1 = Math.max(0, Math.min(levelHeight - 1, Math.floor((1 - minY) * levelHeight)));
+    let furthest = Number.POSITIVE_INFINITY;
+    for (let y = y0; y <= y1; y += 1) {
+        for (let x = x0; x <= x1; x += 1) {
+            furthest = Math.min(furthest, depths[base + y * levelWidth + x]);
+        }
+    }
+    return hzbOccluded(nearestDepth, furthest);
+}
+/**
+ * Every test, over every cluster: one flag each, and the kept indices in input order.
+ *
+ * `selected`, where given, is the cut's flag a cluster: a cluster it did not select is not tested
+ * and not kept, which is how an instance cull reaches the clusters of a mesh it hid. Absent, every
+ * cluster is judged.
+ *
+ * `hzb` is null in the first phase of a two-phase pass, where there is no depth from this frame to
+ * test against yet — and null rather than an empty pyramid, because an empty one is a pyramid full
+ * of zeroes and under reversed-Z zero is the far plane, which occludes nothing and would look like
+ * the test running when it is not.
+ *
+ * Returns how many survived, which is also what an indirect draw's instance count wants.
+ */
+export function cullClusters(clusters, planes, eyeX, eyeY, eyeZ, hzb, keep, list, selected = null, 
+/** False for the blended run, whose raster draws both sides. See `CULL_CONES`. */
+cones = true) {
+    const bounds = new Float32Array(5);
+    const count = Math.floor(clusters.length / CLUSTER_CULL_FLOATS);
+    let kept = 0;
+    for (let i = 0; i < count; i += 1) {
+        if (selected !== null && selected[i] === 0) {
+            keep[i] = 0;
+            continue;
+        }
+        const at = i * CLUSTER_CULL_FLOATS;
+        const cx = clusters[at];
+        const cy = clusters[at + 1];
+        const cz = clusters[at + 2];
+        const radius = clusters[at + 3];
+        let survives = !sphereOutsideFrustum(planes, cx, cy, cz, radius);
+        if (survives && cones) {
+            survives = !coneBackfacing(clusters[at + 4], clusters[at + 5], clusters[at + 6], clusters[at + 7], cx, cy, cz, radius, eyeX, eyeY, eyeZ);
+        }
+        if (survives && hzb !== null && sphereScreenBounds(hzb.viewProj, cx, cy, cz, radius, bounds)) {
+            survives = !clusterOccluded(hzb.depths, hzb.offsets, hzb.width, hzb.height, bounds[0], bounds[1], bounds[2], bounds[3], bounds[4]);
+        }
+        keep[i] = survives ? CLUSTER_KEEP : 0;
+        if (survives) {
+            list[kept] = i;
+            kept += 1;
+        }
+    }
+    return kept;
+}

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

@@ -0,0 +1,64 @@
+/** Every material's decode programs, flattened into what the shading pass binds. */
+/**
+ * **A program is `DecodeResources` with bytes rather than floats**, because bytes are what the
+ * device array holds. The types are structural: core does not import `@driftengine/texture`, and
+ * what `encodeMaterial` returns satisfies `programFromEncoded` as it stands.
+ *
+ * **Every slot a graph names is program-local and is rewritten here to a global one** — a layer, a
+ * network, a constant — so the interpreter needs no per-program indirection table. The graph a
+ * caller handed in is not modified; the rewritten copy lives only in the table.
+ */
+export interface GpuDrivenLatent {
+    readonly width: number;
+    readonly height: number;
+    /** One to four. The lanes past them read zero, and alpha reads one, as `decodeCpu` does. */
+    readonly components: number;
+    /** Level 0 first, each half the last, down to one texel. `components` bytes a texel. */
+    readonly levels: readonly Uint8Array[];
+}
+export interface GpuDrivenNetwork {
+    readonly shape: {
+        readonly inputs: number;
+        readonly hidden: readonly number[];
+        readonly outputs: number;
+    };
+    readonly weights: Float32Array;
+}
+export interface GpuDrivenProgram {
+    readonly graph: {
+        readonly nodes: Uint32Array;
+        readonly count: number;
+        readonly result: number;
+        readonly addressMode: number;
+    };
+    readonly latents: readonly GpuDrivenLatent[];
+    readonly blocks?: readonly GpuDrivenLatent[];
+    readonly networks: readonly GpuDrivenNetwork[];
+    /** Four floats a slot, for `CONSTANT`. */
+    readonly constants?: Float32Array;
+}
+export interface DecodeTables {
+    readonly nodes: Uint32Array;
+    readonly weights: Float32Array;
+    /** One array a mip level: every layer's RGBA bytes, layer after layer. */
+    readonly levels: readonly Uint8Array[];
+    /** At least one, because a texture array of no layers cannot be created. */
+    readonly layerCount: number;
+    /** Level 0's edge in texels. One when nothing is sampled. */
+    readonly layerSize: number;
+}
+/** What `encodeMaterial` returns, as far as this needs it. */
+export interface EncodedProgramShape {
+    readonly latentWidth: number;
+    readonly latentHeight: number;
+    readonly components: number;
+    readonly weights: Float32Array;
+    readonly shape: GpuDrivenNetwork['shape'];
+    readonly graph: GpuDrivenProgram['graph'];
+    /** Level 0 first — `encodeMaterial` puts the latent itself there. */
+    readonly mips: readonly {
+        readonly data: Uint8Array;
+    }[];
+}
+export declare function programFromEncoded(encoded: EncodedProgramShape): GpuDrivenProgram;
+export declare function packDecodeTables(programs: readonly GpuDrivenProgram[]): DecodeTables;

package/dist/render/gpudriven/decodeTables.js

@@ -0,0 +1,219 @@
+/** Every material's decode programs, flattened into what the shading pass binds. */
+import { DECODE_ADDRESS_MODES, DECODE_CONSTANT_CAPACITY, DECODE_FBM_OCTAVES, DECODE_NETWORK_CAPACITY, DECODE_NETWORK_HIDDEN_LAYERS, DECODE_NETWORK_INPUTS, DECODE_NETWORK_OUTPUTS, DECODE_NETWORK_WIDTH, DECODE_NODE_CAPACITY, DECODE_NODES_BYTES, DECODE_OPS, DECODE_PROGRAM_CAPACITY, DECODE_REGISTERS, DECODE_WEIGHT_BLOCKS, DECODE_WEIGHTS_BYTES, } from '../shaders/gpudriven/decode.wgsl.js';
+export function programFromEncoded(encoded) {
+    return {
+        graph: encoded.graph,
+        latents: [
+            {
+                width: encoded.latentWidth,
+                height: encoded.latentHeight,
+                components: encoded.components,
+                levels: encoded.mips.map((level) => level.data),
+            },
+        ],
+        networks: [{ shape: encoded.shape, weights: encoded.weights }],
+    };
+}
+const NETWORK_AT = DECODE_PROGRAM_CAPACITY * 4;
+const NODE_AT = NETWORK_AT + DECODE_NETWORK_CAPACITY * 8;
+const CONSTANT_AT = DECODE_WEIGHT_BLOCKS * 4;
+/** Whether an operation's `a` and `b` name registers. `decodeGraph.ts`'s `OP_ARGS`, again. */
+const REGISTER_ARGS = {
+    [DECODE_OPS.SAMPLE_LATENT]: [false, false],
+    [DECODE_OPS.EVAL_NETWORK]: [true, false],
+    [DECODE_OPS.SAMPLE_BLOCK]: [false, false],
+    [DECODE_OPS.PROCEDURAL_FBM]: [false, false],
+    [DECODE_OPS.FLIPBOOK_INDEX]: [false, false],
+    [DECODE_OPS.LATENT_LERP]: [true, true],
+    [DECODE_OPS.REMAP_CHANNEL]: [true, false],
+    [DECODE_OPS.COMPOSITE]: [true, true],
+    [DECODE_OPS.CONSTANT]: [false, false],
+};
+function refuse(message) {
+    throw new Error(`[driftengine] ${message}`);
+}
+/** `networkWeightCount`, again, for the same reason `REGISTER_ARGS` is. */
+function weightCount(shape) {
+    let total = 0;
+    let previous = shape.inputs;
+    for (const width of shape.hidden) {
+        total += previous * width + width;
+        previous = width;
+    }
+    return total + previous * shape.outputs + shape.outputs;
+}
+export function packDecodeTables(programs) {
+    if (programs.length > DECODE_PROGRAM_CAPACITY) {
+        refuse(`${programs.length} programs, past the ${DECODE_PROGRAM_CAPACITY} the table holds`);
+    }
+    const nodes = new Uint32Array(DECODE_NODES_BYTES / 4);
+    const weights = new Float32Array(DECODE_WEIGHTS_BYTES / 4);
+    const first = programs.flatMap((p) => [...p.latents, ...(p.blocks ?? [])])[0];
+    const layerSize = first?.width ?? 1;
+    if (!(layerSize > 0 && (layerSize & (layerSize - 1)) === 0)) {
+        refuse(`a latent is ${layerSize} texels across, and a layer's edge has to be a power of two`);
+    }
+    const levelCount = Math.log2(layerSize) + 1;
+    const chunks = Array.from({ length: levelCount }, () => []);
+    let layers = 0;
+    let networkCount = 0;
+    let nodeCount = 0;
+    let weightAt = 0;
+    let constantCount = 0;
+    const addLatent = (latent) => {
+        if (latent.width !== layerSize || latent.height !== layerSize) {
+            refuse(`a latent is ${latent.width} by ${latent.height}, and every latent in one pass is ` +
+                `${layerSize} by ${layerSize}`);
+        }
+        if (latent.components < 1 || latent.components > 4) {
+            refuse(`a latent has ${latent.components} components, not one to four`);
+        }
+        if (latent.levels.length !== levelCount) {
+            refuse(`a latent carries ${latent.levels.length} level${latent.levels.length === 1 ? '' : 's'}, ` +
+                `and a ${layerSize}-texel layer has ${levelCount}`);
+        }
+        for (let level = 0; level < levelCount; level += 1) {
+            const edge = Math.max(1, layerSize >> level);
+            const source = latent.levels[level];
+            if (source.length !== edge * edge * latent.components) {
+                refuse(`level ${level} of a latent holds ${source.length} bytes, not ${edge * edge * latent.components}`);
+            }
+            const rgba = new Uint8Array(edge * edge * 4);
+            for (let texel = 0; texel < edge * edge; texel += 1) {
+                for (let c = 0; c < 4; c += 1) {
+                    rgba[texel * 4 + c] =
+                        c < latent.components
+                            ? source[texel * latent.components + c]
+                            : c === 3
+                                ? 255
+                                : 0;
+                }
+            }
+            chunks[level].push(rgba);
+        }
+        layers += 1;
+        return layers - 1;
+    };
+    programs.forEach((program, p) => {
+        const graph = program.graph;
+        if (graph.addressMode >= DECODE_ADDRESS_MODES) {
+            refuse(`program ${p} asks for address mode ${graph.addressMode}; the interpreter knows 0 to ${DECODE_ADDRESS_MODES - 1}`);
+        }
+        if (graph.result >= DECODE_REGISTERS) {
+            refuse(`program ${p} returns register ${graph.result}, past the ${DECODE_REGISTERS} it has`);
+        }
+        const latentLayer = program.latents.map(addLatent);
+        const blockLayer = (program.blocks ?? []).map(addLatent);
+        const networkIndex = program.networks.map((network) => {
+            const { shape } = network;
+            if (shape.inputs < 1 || shape.inputs > DECODE_NETWORK_INPUTS) {
+                refuse(`a network takes ${shape.inputs} inputs; a register holds ${DECODE_NETWORK_INPUTS}`);
+            }
+            if (shape.outputs < 1 || shape.outputs > DECODE_NETWORK_OUTPUTS) {
+                refuse(`a network gives ${shape.outputs} outputs; a register holds ${DECODE_NETWORK_OUTPUTS}`);
+            }
+            if (shape.hidden.length > DECODE_NETWORK_HIDDEN_LAYERS) {
+                refuse(`a network has ${shape.hidden.length} hidden layers, past ${DECODE_NETWORK_HIDDEN_LAYERS}`);
+            }
+            for (const width of shape.hidden) {
+                if (width < 1 || width > DECODE_NETWORK_WIDTH) {
+                    refuse(`a hidden layer is ${width} wide, past ${DECODE_NETWORK_WIDTH}`);
+                }
+            }
+            if (network.weights.length !== weightCount(shape)) {
+                refuse(`a network carries ${network.weights.length} weights and its shape needs ${weightCount(shape)}`);
+            }
+            if (networkCount >= DECODE_NETWORK_CAPACITY) {
+                refuse(`more than ${DECODE_NETWORK_CAPACITY} networks`);
+            }
+            if (weightAt + network.weights.length > DECODE_WEIGHT_BLOCKS * 4) {
+                refuse(`the networks need more than the ${DECODE_WEIGHT_BLOCKS * 4} weights a ` +
+                    `${DECODE_WEIGHTS_BYTES}-byte uniform holds`);
+            }
+            const at = NETWORK_AT + networkCount * 8;
+            nodes[at] = weightAt;
+            nodes[at + 1] = shape.inputs;
+            nodes[at + 2] = shape.outputs;
+            nodes[at + 3] = shape.hidden.length;
+            shape.hidden.forEach((width, k) => {
+                nodes[at + 4 + k] = width;
+            });
+            weights.set(network.weights, weightAt);
+            weightAt += network.weights.length;
+            networkCount += 1;
+            return networkCount - 1;
+        });
+        const constants = program.constants ?? new Float32Array(0);
+        const constantIndex = [];
+        for (let k = 0; k * 4 < constants.length; k += 1) {
+            if (constantCount >= DECODE_CONSTANT_CAPACITY) {
+                refuse(`more than ${DECODE_CONSTANT_CAPACITY} constants`);
+            }
+            for (let c = 0; c < 4; c += 1) {
+                weights[CONSTANT_AT + constantCount * 4 + c] = constants[k * 4 + c] ?? 0;
+            }
+            constantIndex.push(constantCount);
+            constantCount += 1;
+        }
+        if (nodeCount + graph.count > DECODE_NODE_CAPACITY) {
+            refuse(`more than ${DECODE_NODE_CAPACITY} decode nodes`);
+        }
+        const header = p * 4;
+        nodes[header] = nodeCount;
+        nodes[header + 1] = graph.count;
+        nodes[header + 2] = graph.result;
+        nodes[header + 3] = graph.addressMode;
+        for (let i = 0; i < graph.count; i += 1) {
+            const op = graph.nodes[i * 4];
+            let a = graph.nodes[i * 4 + 1];
+            let b = graph.nodes[i * 4 + 2];
+            const dst = graph.nodes[i * 4 + 3];
+            const args = REGISTER_ARGS[op];
+            if (args === undefined) {
+                refuse(`program ${p} node ${i} has opcode ${op}, which the interpreter does not have`);
+            }
+            if (dst >= DECODE_REGISTERS ||
+                (args[0] && a >= DECODE_REGISTERS) ||
+                (args[1] && b >= DECODE_REGISTERS)) {
+                refuse(`program ${p} node ${i} names a register past ${DECODE_REGISTERS - 1}: ${a}, ${b}, ${dst}`);
+            }
+            if (op === DECODE_OPS.SAMPLE_LATENT) {
+                a =
+                    latentLayer[a] ??
+                        refuse(`program ${p} node ${i} samples latent ${a}, which it does not carry`);
+            }
+            else if (op === DECODE_OPS.SAMPLE_BLOCK) {
+                a =
+                    blockLayer[a] ??
+                        refuse(`program ${p} node ${i} samples block ${a}, which it does not carry`);
+            }
+            else if (op === DECODE_OPS.EVAL_NETWORK) {
+                b =
+                    networkIndex[b] ??
+                        refuse(`program ${p} node ${i} runs network ${b}, which it does not carry`);
+            }
+            else if (op === DECODE_OPS.CONSTANT) {
+                a =
+                    constantIndex[a] ??
+                        refuse(`program ${p} node ${i} reads constant ${a}, which it does not carry`);
+            }
+            else if (op === DECODE_OPS.PROCEDURAL_FBM && b > DECODE_FBM_OCTAVES) {
+                refuse(`program ${p} node ${i} asks for ${b} octaves, past ${DECODE_FBM_OCTAVES}`);
+            }
+            const at = NODE_AT + nodeCount * 4;
+            nodes[at] = op;
+            nodes[at + 1] = a;
+            nodes[at + 2] = b;
+            nodes[at + 3] = dst;
+            nodeCount += 1;
+        }
+    });
+    const layerCount = Math.max(1, layers);
+    const levels = chunks.map((parts, level) => {
+        const edge = Math.max(1, layerSize >> level);
+        const bytes = new Uint8Array(layerCount * edge * edge * 4);
+        parts.forEach((part, layer) => bytes.set(part, layer * edge * edge * 4));
+        return bytes;
+    });
+    return { nodes, weights, levels, layerCount, layerSize };
+}

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

@@ -0,0 +1,25 @@
+/**
+ * Frustum planes from a view-projection matrix, and the sphere test against them.
+ *
+ * **The reference implementation, and that is its job.** The culling arithmetic is written twice —
+ * here for the processor and in WGSL for the device — and a test asserts the two agree over
+ * generated input. `splats` already establishes that discipline for shaders authored once and
+ * generated to two backends; this is the same rule where the second copy cannot be generated.
+ *
+ * **Reversed-Z does not change the planes, only their names.** `depthConvention.ts` maps near to 1
+ * and far to 0, but the two depth planes are still "clip z at or above 0" and "clip z at or below
+ * w" — the mapping swaps which physical plane each one is, and a sphere satisfying both is inside
+ * either way. Nothing here has to know which way depth runs, which is why nothing here asks.
+ *
+ * Column-major throughout, matching the matrices the renderer already passes around.
+ */
+/** Six planes, four floats each: a, b, c, d with the normal pointing inward. */
+export declare const FRUSTUM_FLOATS = 24;
+export declare function frustumPlanes(viewProj: Float32Array, out: Float32Array): void;
+/**
+ * Whether a bounding sphere is entirely outside the frustum.
+ *
+ * **Conservative in one direction only.** A sphere straddling a plane survives, because culling
+ * something visible is a hole in the picture and keeping something invisible is a wasted draw.
+ */
+export declare function sphereOutsideFrustum(planes: Float32Array, cx: number, cy: number, cz: number, radius: number): boolean;

package/dist/render/gpudriven/frustum.js

@@ -0,0 +1,59 @@
+/**
+ * Frustum planes from a view-projection matrix, and the sphere test against them.
+ *
+ * **The reference implementation, and that is its job.** The culling arithmetic is written twice —
+ * here for the processor and in WGSL for the device — and a test asserts the two agree over
+ * generated input. `splats` already establishes that discipline for shaders authored once and
+ * generated to two backends; this is the same rule where the second copy cannot be generated.
+ *
+ * **Reversed-Z does not change the planes, only their names.** `depthConvention.ts` maps near to 1
+ * and far to 0, but the two depth planes are still "clip z at or above 0" and "clip z at or below
+ * w" — the mapping swaps which physical plane each one is, and a sphere satisfying both is inside
+ * either way. Nothing here has to know which way depth runs, which is why nothing here asks.
+ *
+ * Column-major throughout, matching the matrices the renderer already passes around.
+ */
+/** Six planes, four floats each: a, b, c, d with the normal pointing inward. */
+export const FRUSTUM_FLOATS = 24;
+function setPlane(out, at, a, b, c, d) {
+    /* Normalised so the plane test is a true signed distance and can be compared against a radius. */
+    const length = Math.hypot(a, b, c);
+    const k = length > 0 ? 1 / length : 0;
+    out[at] = a * k;
+    out[at + 1] = b * k;
+    out[at + 2] = c * k;
+    out[at + 3] = d * k;
+}
+export function frustumPlanes(viewProj, out) {
+    const m = viewProj;
+    /* Rows of a column-major matrix: row i is m[i], m[4+i], m[8+i], m[12+i]. */
+    const r0 = [m[0], m[4], m[8], m[12]];
+    const r1 = [m[1], m[5], m[9], m[13]];
+    const r2 = [m[2], m[6], m[10], m[14]];
+    const r3 = [m[3], m[7], m[11], m[15]];
+    setPlane(out, 0, r3[0] + r0[0], r3[1] + r0[1], r3[2] + r0[2], r3[3] + r0[3]);
+    setPlane(out, 4, r3[0] - r0[0], r3[1] - r0[1], r3[2] - r0[2], r3[3] - r0[3]);
+    setPlane(out, 8, r3[0] + r1[0], r3[1] + r1[1], r3[2] + r1[2], r3[3] + r1[3]);
+    setPlane(out, 12, r3[0] - r1[0], r3[1] - r1[1], r3[2] - r1[2], r3[3] - r1[3]);
+    /* The two depth planes, in clip terms rather than near/far terms. See the header. */
+    setPlane(out, 16, r2[0], r2[1], r2[2], r2[3]);
+    setPlane(out, 20, r3[0] - r2[0], r3[1] - r2[1], r3[2] - r2[2], r3[3] - r2[3]);
+}
+/**
+ * Whether a bounding sphere is entirely outside the frustum.
+ *
+ * **Conservative in one direction only.** A sphere straddling a plane survives, because culling
+ * something visible is a hole in the picture and keeping something invisible is a wasted draw.
+ */
+export function sphereOutsideFrustum(planes, cx, cy, cz, radius) {
+    for (let p = 0; p < 6; p += 1) {
+        const at = p * 4;
+        const distance = planes[at] * cx +
+            planes[at + 1] * cy +
+            planes[at + 2] * cz +
+            planes[at + 3];
+        if (distance < -radius)
+            return true;
+    }
+    return false;
+}

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

@@ -0,0 +1,15 @@
+import type { GeometrySink, StreamCapacity } from './streamScene.ts';
+export interface MirrorWrite {
+    readonly kind: 'vertices' | 'indices';
+    readonly first: number;
+    readonly count: number;
+    /** The array the scene handed over, kept so a test can ask whether it was the same one. */
+    readonly source: Float32Array | Uint32Array;
+}
+export interface MirrorSink extends GeometrySink {
+    readonly vertices: Float32Array;
+    readonly indices: Uint32Array;
+    readonly writes: MirrorWrite[];
+}
+/** A mirror as large as the capacity: what the pass's two buffers would hold. */
+export declare function mirrorSink(capacity: StreamCapacity): MirrorSink;

package/dist/render/gpudriven/geometryHarness.js

@@ -0,0 +1,31 @@
+/**
+ * A sink that keeps what a streaming scene writes, for tests that read its geometry back.
+ *
+ * **Not a `.test.ts` file**, for the reason `rendererHarness.ts` gives: Vitest registers a test
+ * when the file declaring it is imported, so a helper living beside tests would re-run them in
+ * every file that imported it.
+ *
+ * **The scene keeps no copy of its vertices and indices** — they go to the device of the pass
+ * that draws them, through a `GeometrySink` — so a test that wants to read them attaches one of
+ * these where the pass would have attached itself, and reads the mirror.
+ */
+import { GPU_DRIVEN_VERTEX_FLOATS } from './sceneUpload.js';
+/** A mirror as large as the capacity: what the pass's two buffers would hold. */
+export function mirrorSink(capacity) {
+    const vertices = new Float32Array(capacity.vertices * GPU_DRIVEN_VERTEX_FLOATS);
+    const indices = new Uint32Array(capacity.indices);
+    const writes = [];
+    return {
+        vertices,
+        indices,
+        writes,
+        writeVertices(first, rows, count) {
+            vertices.set(rows.subarray(0, count * GPU_DRIVEN_VERTEX_FLOATS), first * GPU_DRIVEN_VERTEX_FLOATS);
+            writes.push({ kind: 'vertices', first, count, source: rows });
+        },
+        writeIndices(first, values, count) {
+            indices.set(values.subarray(0, count), first);
+            writes.push({ kind: 'indices', first, count, source: values });
+        },
+    };
+}