@driftengine/core 3.63.0 → 4.1.0

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

@@ -0,0 +1,60 @@
+/**
+ * The hierarchical depth buffer, and the one decision in it that is easy to get backwards.
+ *
+ * A texel of level *n+1* must hold the depth **furthest from the camera** of the four it covers.
+ * Taking the nearest culls geometry that is visible, which appears as holes that come and go with
+ * camera motion and is diagnosed as almost anything else first.
+ *
+ * **Under reversed-Z, furthest is the minimum value, not the maximum.** `depthConvention.ts` maps
+ * the near plane to 1 and the far plane to 0, so the conventional `max` reduction every published
+ * description gives is exactly wrong for this engine. That inversion is the reason this module
+ * exists as its own file with this paragraph in it rather than as four lines inside a pass.
+ *
+ * **An odd level includes its extra row and column rather than dropping them.** Dropping them
+ * loses the depth of a strip one texel wide along two edges, and a strip of missing occluder is a
+ * strip of geometry culled against nothing — conservative in the wrong direction.
+ */
+/** How many levels a pyramid over this size has, down to a single texel. */
+export declare function hzbMipCount(width: number, height: number): number;
+/** Dimensions of the level below one of this size: halved, never below one. */
+export declare function hzbMipSize(width: number, height: number): {
+    width: number;
+    height: number;
+};
+/**
+ * Reduce one level into the next, taking the furthest depth of each group.
+ *
+ * `out` must hold `hzbMipSize(width, height)` texels. Returns the size written.
+ */
+export declare function hzbReduce(src: Float32Array, width: number, height: number, out: Float32Array): {
+    width: number;
+    height: number;
+};
+/**
+ * A light's pyramid's base: half its shadow map, each texel the furthest of the group under it,
+ * **turned over into the camera's convention.**
+ *
+ * A shadow map's depth is conventional — near is zero — because the lookup both pipelines share
+ * reads it so, and `depthConvention.ts` leaves shadow maps alone. Everything downstream of a
+ * pyramid is written for reversed-Z, so this stores `1 - depth`, where the furthest of a group is
+ * the smallest value, and from here the light's pyramid is the camera's: `hzbReduce` builds the
+ * rest, and the cull reads it through a matrix whose depth is turned over to match. The groups are
+ * `hzbReduce`'s, an odd map's extra row and column folded in, and so is the answer — it is
+ * `hzbReduce` of the turned-over map, exactly.
+ *
+ * **Half the map rather than all of it**, because the base level is the one that costs: a whole
+ * 2048 map's pyramid would be 22 MB beside the 16 MB of the map itself. `out` holds
+ * `hzbMipSize(width, height)` texels; returns that size.
+ */
+export declare function shadowPyramidBase(depth: Float32Array, width: number, height: number, out: Float32Array): {
+    width: number;
+    height: number;
+};
+/**
+ * Whether a sphere is hidden behind the depth already in the pyramid.
+ *
+ * `sphereDepth` is the **nearest** clip depth of the sphere, which under reversed-Z is its
+ * *largest* value. It is hidden when even that is further away than the occluder depth — again a
+ * smaller number here.
+ */
+export declare function hzbOccluded(sphereNearestDepth: number, occluderFurthestDepth: number): boolean;

package/dist/render/gpudriven/hzb.js

@@ -0,0 +1,97 @@
+/**
+ * The hierarchical depth buffer, and the one decision in it that is easy to get backwards.
+ *
+ * A texel of level *n+1* must hold the depth **furthest from the camera** of the four it covers.
+ * Taking the nearest culls geometry that is visible, which appears as holes that come and go with
+ * camera motion and is diagnosed as almost anything else first.
+ *
+ * **Under reversed-Z, furthest is the minimum value, not the maximum.** `depthConvention.ts` maps
+ * the near plane to 1 and the far plane to 0, so the conventional `max` reduction every published
+ * description gives is exactly wrong for this engine. That inversion is the reason this module
+ * exists as its own file with this paragraph in it rather than as four lines inside a pass.
+ *
+ * **An odd level includes its extra row and column rather than dropping them.** Dropping them
+ * loses the depth of a strip one texel wide along two edges, and a strip of missing occluder is a
+ * strip of geometry culled against nothing — conservative in the wrong direction.
+ */
+/** How many levels a pyramid over this size has, down to a single texel. */
+export function hzbMipCount(width, height) {
+    return Math.floor(Math.log2(Math.max(1, Math.max(width, height)))) + 1;
+}
+/** Dimensions of the level below one of this size: halved, never below one. */
+export function hzbMipSize(width, height) {
+    return { width: Math.max(1, width >> 1), height: Math.max(1, height >> 1) };
+}
+/**
+ * Reduce one level into the next, taking the furthest depth of each group.
+ *
+ * `out` must hold `hzbMipSize(width, height)` texels. Returns the size written.
+ */
+export function hzbReduce(src, width, height, out) {
+    const size = hzbMipSize(width, height);
+    for (let y = 0; y < size.height; y += 1) {
+        for (let x = 0; x < size.width; x += 1) {
+            const x0 = x * 2;
+            const y0 = y * 2;
+            /* The extra row and column of an odd level are folded into the last group. See the header. */
+            const x1 = Math.min(width - 1, x0 + 1);
+            const y1 = Math.min(height - 1, y0 + 1);
+            const lastX = x === size.width - 1 ? width - 1 : x1;
+            const lastY = y === size.height - 1 ? height - 1 : y1;
+            let furthest = Infinity;
+            for (let sy = y0; sy <= lastY; sy += 1) {
+                for (let sx = x0; sx <= lastX; sx += 1) {
+                    /* Minimum, because reversed-Z puts the far plane at zero. */
+                    furthest = Math.min(furthest, src[sy * width + sx]);
+                }
+            }
+            out[y * size.width + x] = furthest;
+        }
+    }
+    return size;
+}
+/**
+ * A light's pyramid's base: half its shadow map, each texel the furthest of the group under it,
+ * **turned over into the camera's convention.**
+ *
+ * A shadow map's depth is conventional — near is zero — because the lookup both pipelines share
+ * reads it so, and `depthConvention.ts` leaves shadow maps alone. Everything downstream of a
+ * pyramid is written for reversed-Z, so this stores `1 - depth`, where the furthest of a group is
+ * the smallest value, and from here the light's pyramid is the camera's: `hzbReduce` builds the
+ * rest, and the cull reads it through a matrix whose depth is turned over to match. The groups are
+ * `hzbReduce`'s, an odd map's extra row and column folded in, and so is the answer — it is
+ * `hzbReduce` of the turned-over map, exactly.
+ *
+ * **Half the map rather than all of it**, because the base level is the one that costs: a whole
+ * 2048 map's pyramid would be 22 MB beside the 16 MB of the map itself. `out` holds
+ * `hzbMipSize(width, height)` texels; returns that size.
+ */
+export function shadowPyramidBase(depth, width, height, out) {
+    const size = hzbMipSize(width, height);
+    for (let y = 0; y < size.height; y += 1) {
+        for (let x = 0; x < size.width; x += 1) {
+            const x0 = x * 2;
+            const y0 = y * 2;
+            const lastX = x === size.width - 1 ? width - 1 : Math.min(width - 1, x0 + 1);
+            const lastY = y === size.height - 1 ? height - 1 : Math.min(height - 1, y0 + 1);
+            let deepest = -Infinity;
+            for (let sy = y0; sy <= lastY; sy += 1) {
+                for (let sx = x0; sx <= lastX; sx += 1) {
+                    deepest = Math.max(deepest, depth[sy * width + sx]);
+                }
+            }
+            out[y * size.width + x] = 1 - deepest;
+        }
+    }
+    return size;
+}
+/**
+ * Whether a sphere is hidden behind the depth already in the pyramid.
+ *
+ * `sphereDepth` is the **nearest** clip depth of the sphere, which under reversed-Z is its
+ * *largest* value. It is hidden when even that is further away than the occluder depth — again a
+ * smaller number here.
+ */
+export function hzbOccluded(sphereNearestDepth, occluderFurthestDepth) {
+    return sphereNearestDepth < occluderFurthestDepth;
+}

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

@@ -0,0 +1,85 @@
+/** The split sum's second half, in TypeScript, so the second pipeline's copy has a reference. */
+/**
+ * **`flat/lobes.ts` in TypeScript: how much of an environment a surface returns.**
+ *
+ * The convolution decides *what* a surface reflects — a rougher one reads a blurrier level of the
+ * prefiltered chain — and this decides *how much*. Both halves are a fit and an algebraic
+ * compensation, which is to say both are arithmetic nobody can check by looking at a frame: the
+ * failure they exist to prevent was reported twice from consumers as *metals reading opaque*, and
+ * traced to a term that asserts a perfect mirror absorbs 55% of the light once it is roughened.
+ *
+ * **Metalness is a per-material scalar here, not an ORM map.** `flat/main.ts` reads it per texel
+ * from the blue channel of an occlusion-roughness-metallic image, which is a thing this pipeline
+ * has no textures to read; a GPU-driven material carries one number instead. That is a *subset* and
+ * not a second opinion: everywhere a texel could vary, a material is constant, and every expression
+ * below is the forward path's with a uniform standing in for a fetch.
+ *
+ * **What stays collapsed is the environment gain.** `flat/main.ts` scales what a metal reflects by
+ * `uEnvironmentGain`, which exists because a metal has no diffuse behind its reflection and a probe
+ * that under-reports the room leaves it with no other way to be lit. `PassEnvironment` carries no
+ * such control, so the gain is 1 and `mix(1, gain, metal)` is exactly 1 at every metalness — a
+ * collapse that is exact rather than approximate, which is the standard every term here is held to.
+ */
+/** A dielectric's normal-incidence reflectance, which is what a material with no metalness is. */
+export declare const DIELECTRIC_F0 = 0.04;
+/**
+ * A surface's normal-incidence reflectance, from its metalness.
+ *
+ * **A metal's Fresnel base is close to its albedo and a dielectric's is four per cent**, and
+ * `flat/main.ts` records what leaving it at 0.04 costs: a smooth metal seen head-on takes a four
+ * per cent reflection and reads as dark paint. The chromatic half of that — a metal's `f0` being
+ * its own colour rather than white — is in `lit.ts`, where the albedo is; this is the scalar the
+ * split sum takes.
+ */
+export declare function surfaceF0(metalness: number): number;
+/**
+ * The split sum's second half, as a two-term fit: `dfg.x` scales `f0` and `dfg.y` is added on top.
+ *
+ * **Karis's analytic fit rather than the tabulated integral**, which is a texture this pipeline
+ * would otherwise have to carry and bind. Its published error is around one per cent of the
+ * tabulated term, far below what an eight-bit frame can show. **What would make it wrong** is a
+ * material model with a second lobe — a clearcoat or a sheen carries its own BRDF and its own
+ * integral, and this is Trowbridge-Reitz with Smith masking and nothing else.
+ */
+export declare function envBrdfApprox(ndv: number, roughness: number, out: Float32Array): Float32Array;
+/**
+ * The same, with the light that bounces more than once inside the microsurface put back.
+ *
+ * **The split sum integrates a *single* scattering event**, so it silently discards every ray that
+ * strikes one microfacet, bounces, and leaves. Roughness scatters light; it does not absorb it, so
+ * a surface with `f0` 1 has to return everything at every roughness — and the bare sum returns
+ * about `1 - 0.55 * roughness`, which is a 44% loss at roughness 0.8.
+ *
+ * Fdez-Agüera's compensation: the missing energy, returned at the surface's average Fresnel over
+ * the hemisphere, summed as a geometric series over repeated bounces. **At `f0` 1 it comes back to
+ * exactly 1.0 at every roughness** — `average` is 1, `multi` is `energy / energy`, and the sum
+ * telescopes — which is the invariant the test beside this file asserts across the whole range.
+ *
+ * **No divide guard, because the denominator cannot reach zero.** `missing` is at most 0.55 and
+ * `average` at most 1, so `1 - missing * average` bottoms out at 0.45 — the worst case in both
+ * variables at once.
+ */
+export declare function envSpecularEnergy(f0: number, dfgX: number, dfgY: number): number;
+/**
+ * How much of what the surface sees in the mirror direction reaches the frame.
+ *
+ * **Two expressions and a selector, because they answer different questions.** `prefiltered` is 1
+ * where the radiance came from a GGX-convolved chain, and there the split sum is the correct share
+ * of that integral — it carries the angular dependence itself, so it replaces the Fresnel sweep
+ * rather than multiplying it. Where the radiance is anything else, applying it would assert an
+ * integral that was never performed: `flat/main.ts` measured that mistake as the grazing-to-head-on
+ * ratio falling from about 15 to 1 down to 5 to 1, reported twice as a metal going opaque.
+ *
+ * So without a chain this is the engine's own long-standing weight — Schlick's Fresnel times
+ * `reflectivity * (1 - roughness)` — and with one it is the integral. The two are deliberately not
+ * blended into a single formula; a selector that is exactly 0 or exactly 1 is what makes a scene
+ * with no environment arithmetically identical to the frame it already rendered.
+ *
+ * `ndv` is `dot(n, toEye)` clamped at zero, as the caller's own facing term already computes.
+ */
+export declare function environmentWeight(ndv: number, roughness: number, reflectivity: number, prefiltered: number, 
+/**
+ * 0 is a dielectric and 1 is a metal. **Defaults to 0**, so every caller written before this
+ * argument existed gets the arithmetic it had.
+ */
+metalness?: number): number;

package/dist/render/gpudriven/ibl.js

@@ -0,0 +1,129 @@
+/** The split sum's second half, in TypeScript, so the second pipeline's copy has a reference. */
+/**
+ * **`flat/lobes.ts` in TypeScript: how much of an environment a surface returns.**
+ *
+ * The convolution decides *what* a surface reflects — a rougher one reads a blurrier level of the
+ * prefiltered chain — and this decides *how much*. Both halves are a fit and an algebraic
+ * compensation, which is to say both are arithmetic nobody can check by looking at a frame: the
+ * failure they exist to prevent was reported twice from consumers as *metals reading opaque*, and
+ * traced to a term that asserts a perfect mirror absorbs 55% of the light once it is roughened.
+ *
+ * **Metalness is a per-material scalar here, not an ORM map.** `flat/main.ts` reads it per texel
+ * from the blue channel of an occlusion-roughness-metallic image, which is a thing this pipeline
+ * has no textures to read; a GPU-driven material carries one number instead. That is a *subset* and
+ * not a second opinion: everywhere a texel could vary, a material is constant, and every expression
+ * below is the forward path's with a uniform standing in for a fetch.
+ *
+ * **What stays collapsed is the environment gain.** `flat/main.ts` scales what a metal reflects by
+ * `uEnvironmentGain`, which exists because a metal has no diffuse behind its reflection and a probe
+ * that under-reports the room leaves it with no other way to be lit. `PassEnvironment` carries no
+ * such control, so the gain is 1 and `mix(1, gain, metal)` is exactly 1 at every metalness — a
+ * collapse that is exact rather than approximate, which is the standard every term here is held to.
+ */
+/** A dielectric's normal-incidence reflectance, which is what a material with no metalness is. */
+export const DIELECTRIC_F0 = 0.04;
+/**
+ * A surface's normal-incidence reflectance, from its metalness.
+ *
+ * **A metal's Fresnel base is close to its albedo and a dielectric's is four per cent**, and
+ * `flat/main.ts` records what leaving it at 0.04 costs: a smooth metal seen head-on takes a four
+ * per cent reflection and reads as dark paint. The chromatic half of that — a metal's `f0` being
+ * its own colour rather than white — is in `lit.ts`, where the albedo is; this is the scalar the
+ * split sum takes.
+ */
+export function surfaceF0(metalness) {
+    return DIELECTRIC_F0 + (1 - DIELECTRIC_F0) * metalness;
+}
+/**
+ * The split sum's second half, as a two-term fit: `dfg.x` scales `f0` and `dfg.y` is added on top.
+ *
+ * **Karis's analytic fit rather than the tabulated integral**, which is a texture this pipeline
+ * would otherwise have to carry and bind. Its published error is around one per cent of the
+ * tabulated term, far below what an eight-bit frame can show. **What would make it wrong** is a
+ * material model with a second lobe — a clearcoat or a sheen carries its own BRDF and its own
+ * integral, and this is Trowbridge-Reitz with Smith masking and nothing else.
+ */
+export function envBrdfApprox(ndv, roughness, out) {
+    const c0 = [-1, -0.0275, -0.572, 0.022];
+    const c1 = [1, 0.0425, 1.04, -0.04];
+    const rx = roughness * c0[0] + c1[0];
+    const ry = roughness * c0[1] + c1[1];
+    const rz = roughness * c0[2] + c1[2];
+    const rw = roughness * c0[3] + c1[3];
+    const a004 = Math.min(rx * rx, Math.pow(2, -9.28 * ndv)) * rx + ry;
+    out[0] = -1.04 * a004 + rz;
+    out[1] = 1.04 * a004 + rw;
+    return out;
+}
+/**
+ * The same, with the light that bounces more than once inside the microsurface put back.
+ *
+ * **The split sum integrates a *single* scattering event**, so it silently discards every ray that
+ * strikes one microfacet, bounces, and leaves. Roughness scatters light; it does not absorb it, so
+ * a surface with `f0` 1 has to return everything at every roughness — and the bare sum returns
+ * about `1 - 0.55 * roughness`, which is a 44% loss at roughness 0.8.
+ *
+ * Fdez-Agüera's compensation: the missing energy, returned at the surface's average Fresnel over
+ * the hemisphere, summed as a geometric series over repeated bounces. **At `f0` 1 it comes back to
+ * exactly 1.0 at every roughness** — `average` is 1, `multi` is `energy / energy`, and the sum
+ * telescopes — which is the invariant the test beside this file asserts across the whole range.
+ *
+ * **No divide guard, because the denominator cannot reach zero.** `missing` is at most 0.55 and
+ * `average` at most 1, so `1 - missing * average` bottoms out at 0.45 — the worst case in both
+ * variables at once.
+ */
+export function envSpecularEnergy(f0, dfgX, dfgY) {
+    const single = f0 * dfgX + dfgY;
+    const energy = dfgX + dfgY;
+    const missing = 1 - energy;
+    const average = f0 + (1 - f0) / 21;
+    const multi = (single * average) / (1 - missing * average);
+    return single + multi * missing;
+}
+/**
+ * How much of what the surface sees in the mirror direction reaches the frame.
+ *
+ * **Two expressions and a selector, because they answer different questions.** `prefiltered` is 1
+ * where the radiance came from a GGX-convolved chain, and there the split sum is the correct share
+ * of that integral — it carries the angular dependence itself, so it replaces the Fresnel sweep
+ * rather than multiplying it. Where the radiance is anything else, applying it would assert an
+ * integral that was never performed: `flat/main.ts` measured that mistake as the grazing-to-head-on
+ * ratio falling from about 15 to 1 down to 5 to 1, reported twice as a metal going opaque.
+ *
+ * So without a chain this is the engine's own long-standing weight — Schlick's Fresnel times
+ * `reflectivity * (1 - roughness)` — and with one it is the integral. The two are deliberately not
+ * blended into a single formula; a selector that is exactly 0 or exactly 1 is what makes a scene
+ * with no environment arithmetically identical to the frame it already rendered.
+ *
+ * `ndv` is `dot(n, toEye)` clamped at zero, as the caller's own facing term already computes.
+ */
+export function environmentWeight(ndv, roughness, reflectivity, prefiltered, 
+/**
+ * 0 is a dielectric and 1 is a metal. **Defaults to 0**, so every caller written before this
+ * argument existed gets the arithmetic it had.
+ */
+metalness = 0) {
+    const f0 = surfaceF0(metalness);
+    const facing = 1 - ndv;
+    const fresnel = f0 + (1 - f0) * (facing * facing * facing * facing * facing);
+    /*
+     * **`max(reflectivity * (1 - roughness), metal)`, and both halves of that are repairs.**
+     *
+     * `reflectivity` is a per-material control, and it is zero for exactly the surfaces that carry
+     * their metalness some other way — `flat/main.ts` measured reading it alone as a chromed subject
+     * coming out near black with a baked probe sitting unread, because the whole block was skipped.
+     * So a metal reflects whether or not the material asked for reflections.
+     *
+     * And the `1 - roughness` thinning does not reach the metal. It stands for a polish that
+     * scatters a dielectric's reflection into no image at all; a metal has no diffuse to fall back
+     * on, so scaling it throws away 40% of everything a surface at roughness 0.4 shows and replaces
+     * it with a dark constant. It is also double counting — the level the sample comes from already
+     * *is* the roughness.
+     */
+    const amount = Math.max(reflectivity * (1 - roughness), metalness);
+    const sweep = Math.min(Math.max(fresnel * amount, 0), 1);
+    const dfg = new Float32Array(2);
+    envBrdfApprox(ndv, roughness, dfg);
+    const integrated = Math.min(Math.max(envSpecularEnergy(f0, dfg[0], dfg[1]) * Math.max(reflectivity, metalness), 0), 1);
+    return sweep + (integrated - sweep) * prefiltered;
+}

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

@@ -0,0 +1,67 @@
+/**
+ * The arguments a culled frame hands the rasteriser, written by the device and read by it.
+ *
+ * **The whole pipeline exists so that the processor never learns how much there is to draw.** A
+ * cull dispatch writes the count into a buffer and the draw reads it from the same buffer; the
+ * frame is submitted before either number exists. So these are layouts rather than calls: what a
+ * block holds, in what order, and what a caller must have cleared before the dispatch runs.
+ *
+ * **One draw for the whole frame, not one per cluster.** Every surviving cluster is an *instance*
+ * of a fixed 128-triangle draw, which is what `VIS_MAX_TRIANGLES` is for: the index count is the
+ * same for all of them, so there is one block instead of thousands and no multi-draw extension is
+ * needed. A cluster with fewer triangles emits degenerate ones for the remainder — see
+ * `clusterVertexCluster` — and a degenerate triangle covers no pixel, so the picture is unchanged
+ * and the cost is the vertex stage running on indices that produce nothing.
+ *
+ * **What that costs, stated rather than hidden**: a scene whose clusters average 64 triangles runs
+ * the vertex stage twice for every triangle it draws. The alternative is a block per cluster and a
+ * loop of indirect draws on the processor, which is the draw-call bound this pipeline exists to
+ * remove. If a consumer's clusters are persistently half full, the fix is in the *baker* — see
+ * `assets/src/bake/cluster.ts`, whose target is the full 128.
+ */
+/** Words in a `drawIndexedIndirect` block: index count, instances, first index, base vertex, first instance. */
+export declare const INDIRECT_DRAW_WORDS = 5;
+/** Words in a `dispatchWorkgroups` block: three group counts. */
+export declare const INDIRECT_DISPATCH_WORDS = 3;
+/** Indices a cluster draw always issues, whatever the cluster actually holds. */
+export declare const CLUSTER_INDEX_CAP: number;
+/**
+ * The draw block for a frame that kept `clusters` of them.
+ *
+ * `firstInstance` is zero and the *instance index* is the slot in the kept list rather than the
+ * cluster identifier: the list is compacted, so slot and identifier differ, and the shader reads
+ * the identifier out of the list. Putting the identifier here instead would need a block per
+ * cluster, which is the thing this avoids.
+ */
+export declare function writeClusterDrawArgs(out: Uint32Array, at: number, clusters: number): void;
+/**
+ * The dispatch block for `count` items at `groupSize` a group.
+ *
+ * **Rounded up, and zero items is zero groups rather than one.** A group that runs with nothing to
+ * do is harmless in this pipeline — every entry point range-checks its own invocation — but a
+ * dispatch of one group over an empty list still reads a buffer that a caller may not have bound,
+ * and "nothing to do" is the case a frame hits before anything has streamed in.
+ *
+ * **Zero falls out of the division rather than out of a special case**, and the special case that
+ * stood here is gone because a perturbation survived it: `ceil(0 / n)` is already 0, so the branch
+ * changed no answer and was a second statement of the rule to keep in step. The behaviour is still
+ * held by a test — what is gone is the code that was not doing the holding.
+ */
+export declare function writeDispatchArgs(out: Uint32Array, at: number, count: number, groupSize: number): void;
+/**
+ * Which slot of the kept list a vertex belongs to, and which triangle of that cluster.
+ *
+ * The vertex stage's whole addressing, on the processor so a test can read it. `vertex` is
+ * `@builtin(vertex_index)` and runs to `CLUSTER_INDEX_CAP`; `instance` is
+ * `@builtin(instance_index)` and is the slot.
+ *
+ * **A triangle past the cluster's own count is reported rather than clamped.** Clamping draws the
+ * last triangle of the cluster over and over, which is a visible sliver on every cluster that is
+ * not exactly full; reporting it lets the shader emit a degenerate triangle, which covers nothing.
+ */
+export declare function clusterVertexCluster(vertex: number, instance: number, triangleCount: number): {
+    slot: number;
+    triangle: number;
+    corner: number;
+    degenerate: boolean;
+};

package/dist/render/gpudriven/indirect.js

@@ -0,0 +1,77 @@
+/**
+ * The arguments a culled frame hands the rasteriser, written by the device and read by it.
+ *
+ * **The whole pipeline exists so that the processor never learns how much there is to draw.** A
+ * cull dispatch writes the count into a buffer and the draw reads it from the same buffer; the
+ * frame is submitted before either number exists. So these are layouts rather than calls: what a
+ * block holds, in what order, and what a caller must have cleared before the dispatch runs.
+ *
+ * **One draw for the whole frame, not one per cluster.** Every surviving cluster is an *instance*
+ * of a fixed 128-triangle draw, which is what `VIS_MAX_TRIANGLES` is for: the index count is the
+ * same for all of them, so there is one block instead of thousands and no multi-draw extension is
+ * needed. A cluster with fewer triangles emits degenerate ones for the remainder — see
+ * `clusterVertexCluster` — and a degenerate triangle covers no pixel, so the picture is unchanged
+ * and the cost is the vertex stage running on indices that produce nothing.
+ *
+ * **What that costs, stated rather than hidden**: a scene whose clusters average 64 triangles runs
+ * the vertex stage twice for every triangle it draws. The alternative is a block per cluster and a
+ * loop of indirect draws on the processor, which is the draw-call bound this pipeline exists to
+ * remove. If a consumer's clusters are persistently half full, the fix is in the *baker* — see
+ * `assets/src/bake/cluster.ts`, whose target is the full 128.
+ */
+import { VIS_MAX_TRIANGLES } from './visbuffer.js';
+/** Words in a `drawIndexedIndirect` block: index count, instances, first index, base vertex, first instance. */
+export const INDIRECT_DRAW_WORDS = 5;
+/** Words in a `dispatchWorkgroups` block: three group counts. */
+export const INDIRECT_DISPATCH_WORDS = 3;
+/** Indices a cluster draw always issues, whatever the cluster actually holds. */
+export const CLUSTER_INDEX_CAP = VIS_MAX_TRIANGLES * 3;
+/**
+ * The draw block for a frame that kept `clusters` of them.
+ *
+ * `firstInstance` is zero and the *instance index* is the slot in the kept list rather than the
+ * cluster identifier: the list is compacted, so slot and identifier differ, and the shader reads
+ * the identifier out of the list. Putting the identifier here instead would need a block per
+ * cluster, which is the thing this avoids.
+ */
+export function writeClusterDrawArgs(out, at, clusters) {
+    out[at] = CLUSTER_INDEX_CAP;
+    out[at + 1] = Math.max(0, clusters);
+    out[at + 2] = 0;
+    out[at + 3] = 0;
+    out[at + 4] = 0;
+}
+/**
+ * The dispatch block for `count` items at `groupSize` a group.
+ *
+ * **Rounded up, and zero items is zero groups rather than one.** A group that runs with nothing to
+ * do is harmless in this pipeline — every entry point range-checks its own invocation — but a
+ * dispatch of one group over an empty list still reads a buffer that a caller may not have bound,
+ * and "nothing to do" is the case a frame hits before anything has streamed in.
+ *
+ * **Zero falls out of the division rather than out of a special case**, and the special case that
+ * stood here is gone because a perturbation survived it: `ceil(0 / n)` is already 0, so the branch
+ * changed no answer and was a second statement of the rule to keep in step. The behaviour is still
+ * held by a test — what is gone is the code that was not doing the holding.
+ */
+export function writeDispatchArgs(out, at, count, groupSize) {
+    const groups = Math.ceil(Math.max(0, count) / Math.max(1, groupSize));
+    out[at] = groups;
+    out[at + 1] = 1;
+    out[at + 2] = 1;
+}
+/**
+ * Which slot of the kept list a vertex belongs to, and which triangle of that cluster.
+ *
+ * The vertex stage's whole addressing, on the processor so a test can read it. `vertex` is
+ * `@builtin(vertex_index)` and runs to `CLUSTER_INDEX_CAP`; `instance` is
+ * `@builtin(instance_index)` and is the slot.
+ *
+ * **A triangle past the cluster's own count is reported rather than clamped.** Clamping draws the
+ * last triangle of the cluster over and over, which is a visible sliver on every cluster that is
+ * not exactly full; reporting it lets the shader emit a degenerate triangle, which covers nothing.
+ */
+export function clusterVertexCluster(vertex, instance, triangleCount) {
+    const triangle = Math.floor(vertex / 3);
+    return { slot: instance, triangle, corner: vertex % 3, degenerate: triangle >= triangleCount };
+}

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

@@ -0,0 +1,43 @@
+/** Four floats a mesh: world centre and radius. `CULL_INSTANCES_WGSL` reads this stride. */
+export declare const INSTANCE_FLOATS = 4;
+/** What the instance cull writes for a mesh wholly outside the view. Zero is everything else. */
+export declare const INSTANCE_HIDDEN = 1;
+/** Four words a cluster in the uploaded meta: index offset, index count, identifier, mesh. */
+export declare const CLUSTER_META_WORDS = 4;
+/**
+ * Each mesh's world bounding sphere, from the world spheres of its clusters.
+ *
+ * **Held to the numbers the device reads.** The centre is the middle of the clusters' box, stored
+ * in single precision first; the radius is then measured from the *stored* centre and rounded up,
+ * never to nearest — a sphere rounded the wrong way is a few parts in ten million short of a
+ * cluster's far edge, and a cull that is not conservative is a hole in the picture.
+ *
+ * A mesh no cluster names is a point at the origin, which draws nothing whatever the cull says. A
+ * cluster naming a mesh past `meshCount` is refused: it would be bounded by nothing and drawn by a
+ * transform that does not exist.
+ */
+export declare function instanceBounds(cull: Float32Array, meshOf: Uint32Array, count: number, meshCount: number): Float32Array;
+/**
+ * One mesh's bounding sphere, from a contiguous run of its clusters' world bounds.
+ *
+ * **A run rather than a `meshOf` scan, because a streamed mesh's clusters are contiguous by
+ * construction** — the allocator hands out a range — so the scan `instanceBounds` does is work a
+ * streaming caller has already done.
+ *
+ * **A mesh with no clusters gets a sphere of zero radius rather than an empty box's arithmetic.**
+ * `Infinity - (-Infinity)` is `-Infinity`, and every comparison against `NaN` is false, which
+ * reads as a mesh that is never culled rather than one that is never drawn.
+ *
+ * The two forms must agree, and `instances.test.ts` is what holds them to it.
+ */
+export declare function instanceSphereInto(cull: Float32Array, from: number, count: number, out: Float32Array, at: number): void;
+/**
+ * One flag a mesh: `INSTANCE_HIDDEN` where its sphere is wholly outside the view. Returns how many
+ * are. Mirrors `CULL_INSTANCES_WGSL`, which `gpu-parity.mjs` holds to `sphereOutsideFrustum`.
+ */
+export declare function cullInstances(planes: Float32Array, spheres: Float32Array, count: number, out: Uint32Array): number;
+/**
+ * The cut, over every cluster, with the instance flags applied first: one flag a cluster, and how
+ * many were selected. Mirrors `LOD_CUT_WGSL`.
+ */
+export declare function selectClusters(lod: Float32Array, meta: Uint32Array, hidden: Uint32Array, screenHeight: number, fovY: number, thresholdPixels: number, eyeX: number, eyeY: number, eyeZ: number, out: Uint32Array): number;