@driftengine/core 3.63.0 → 4.1.0

package/src/render/gpudriven/clusterWorld.ts

@@ -0,0 +1,239 @@
+/** Where a cluster actually stands: its bounds, its cone and its error through its mesh transform. */
+
+/**
+ * **The cull asks about the world and a cluster is baked in its mesh's own space.**
+ *
+ * `visbufferRaster.wgsl.ts` multiplies every vertex by `transforms[mesh]` and `shade.wgsl.ts`
+ * multiplies every normal by the same upper three-by-three. The culling did neither: it read
+ * `ClusterBuffers.bounds` and `ClusterBuffers.cones` as they came out of the bake, so a mesh placed
+ * anywhere but the origin was frustum-culled against the wrong region, cone-culled with the wrong
+ * orientation, LOD-cut on a misprojected error and occlusion-tested on the wrong rectangle — while
+ * the picture it drew was still drawn in the right place, because the raster had the transform.
+ *
+ * **Every rig in `DRAFT_SCENES` uses an identity transform**, which is the only reason it never
+ * showed. That is the shape §3 row 79 is about: the device check agreed, the reference agreed, and
+ * nothing in the repository placed a mesh anywhere.
+ *
+ * **It happens once, at upload, and not per frame.** This pipeline owns a fixed cluster set with
+ * static transforms — the same property `shadowCamera.ts` fits the light's box to — so the world
+ * bounds are a property of the scene. A pipeline that ever moves a mesh has to rewrite these two
+ * buffers when it does, and that is the cost of having them.
+ */
+
+/** What the transform needs of a packed cluster set. `ClusterBuffers` satisfies it. */
+export interface ClusterWorldSource {
+  /** Four floats a cluster: centre and radius, in the mesh's own space. */
+  readonly bounds: Float32Array;
+  /** Four floats a cluster: cone axis and cutoff, in the mesh's own space. */
+  readonly cones: Float32Array;
+  /** Two floats a cluster: its own error and its parent's. */
+  readonly errors: Float32Array;
+  /** Which mesh each cluster belongs to, which is what it reaches a transform through. */
+  readonly meshOf: Uint32Array;
+  readonly count: number;
+}
+
+/** The two buffers the culling stages read, in the layout they are bound in. */
+export interface ClusterWorld {
+  /** Eight floats a cluster: world centre, radius, cone axis, cutoff. `cullClusters` takes this. */
+  cull: Float32Array;
+  /** Six floats a cluster: world centre, radius, own error, parent error. `lodCut` reads these. */
+  lod: Float32Array;
+}
+
+/** Eight floats a cluster in `cull`, matching `CLUSTER_CULL_FLOATS` 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;
+
+/**
+ * How far from a similarity a transform may be before the cone is refused.
+ *
+ * Relative, and loose on purpose: a rotation composed in single precision loses a few parts in ten
+ * million, and the comparison has to pass every matrix a `Transform` produces without passing a
+ * scale a modeller meant. A hundredth of a per cent is three orders of magnitude clear of the one
+ * and four clear of the other.
+ */
+const SIMILARITY_TOLERANCE = 1e-4;
+
+/**
+ * Transform every cluster into the world, once.
+ *
+ * `transforms` is sixteen floats a mesh, column-major, indexed by `meshOf`.
+ */
+export function worldClusters(
+  clusters: ClusterWorldSource,
+  transforms: Float32Array,
+): ClusterWorld {
+  const cull = new Float32Array(clusters.count * CULL_FLOATS);
+  const lod = new Float32Array(clusters.count * LOD_FLOATS);
+  worldClustersInto(clusters, transforms, cull, lod, 0);
+  return { cull, lod };
+}
+
+/**
+ * The same arithmetic, writing into arrays the caller owns at a cluster offset it chooses.
+ *
+ * **This exists because a streamed mesh computes its own bounds**, at the moment it is added, into
+ * the middle of a scene-sized buffer that already holds other meshes'. `worldClusters` is this
+ * with the allocation, so the two cannot drift — which this file asserts by composing two meshes
+ * both ways and comparing byte for byte.
+ *
+ * `base` is in clusters, not floats: the record at `base + c` is written for every cluster `c` of
+ * the source, and everything outside that range is left exactly as it was found.
+ */
+export function worldClustersInto(
+  clusters: ClusterWorldSource,
+  transforms: Float32Array,
+  cull: Float32Array,
+  lod: Float32Array,
+  base: number,
+): void {
+  const count = clusters.count;
+
+  /*
+   * Per mesh rather than per cluster: a scene is thousands of clusters over a handful of meshes,
+   * and the two questions asked of a matrix — how much it scales, and whether it scales evenly —
+   * are nine multiplies each.
+   */
+  const meshes = Math.floor(transforms.length / 16);
+  const scales = new Float64Array(meshes);
+  const similar = new Uint8Array(meshes);
+  for (let m = 0; m < meshes; m += 1) {
+    const at = m * 16;
+    const l0 = Math.hypot(
+      transforms[at] as number,
+      transforms[at + 1] as number,
+      transforms[at + 2] as number,
+    );
+    const l1 = Math.hypot(
+      transforms[at + 4] as number,
+      transforms[at + 5] as number,
+      transforms[at + 6] as number,
+    );
+    const l2 = Math.hypot(
+      transforms[at + 8] as number,
+      transforms[at + 9] as number,
+      transforms[at + 10] as number,
+    );
+    const longest = Math.max(l0, l1, l2);
+    scales[m] = longest;
+
+    /*
+     * **The longest basis vector is the scale, which is exact for `T · R · S` and conservative for
+     * nothing else.** A sphere of radius `r` maps to an ellipsoid whose longest semi-axis is the
+     * matrix's largest singular value, and for a rotation applied *after* a scale the columns are
+     * the scaled axes and their lengths are exactly the singular values. A sheared matrix — a scale
+     * applied after a rotation, which nothing in this engine composes — has a largest singular
+     * value above its longest column, and there the bound is too small and clusters are culled that
+     * should be drawn. `sceneShadowBounds` reads the same number and carries the same limit.
+     *
+     * A similarity is the case where the *cone* survives too: three columns of equal length, at
+     * right angles. Then the inverse transpose is the matrix over the scale squared, so a normal
+     * multiplied by the matrix and renormalised is the right direction and the cone's half-angle is
+     * unchanged. Anywhere else the two disagree by up to a right angle and the cone is refused.
+     */
+    const even =
+      Math.abs(l0 - longest) <= SIMILARITY_TOLERANCE * longest &&
+      Math.abs(l1 - longest) <= SIMILARITY_TOLERANCE * longest &&
+      Math.abs(l2 - longest) <= SIMILARITY_TOLERANCE * longest;
+    const square = longest * longest;
+    const d01 =
+      (transforms[at] as number) * (transforms[at + 4] as number) +
+      (transforms[at + 1] as number) * (transforms[at + 5] as number) +
+      (transforms[at + 2] as number) * (transforms[at + 6] as number);
+    const d02 =
+      (transforms[at] as number) * (transforms[at + 8] as number) +
+      (transforms[at + 1] as number) * (transforms[at + 9] as number) +
+      (transforms[at + 2] as number) * (transforms[at + 10] as number);
+    const d12 =
+      (transforms[at + 4] as number) * (transforms[at + 8] as number) +
+      (transforms[at + 5] as number) * (transforms[at + 9] as number) +
+      (transforms[at + 6] as number) * (transforms[at + 10] as number);
+    const square90 =
+      Math.abs(d01) <= SIMILARITY_TOLERANCE * square &&
+      Math.abs(d02) <= SIMILARITY_TOLERANCE * square &&
+      Math.abs(d12) <= SIMILARITY_TOLERANCE * square;
+    similar[m] = longest > 0 && even && square90 ? 1 : 0;
+  }
+
+  for (let c = 0; c < count; c += 1) {
+    const at = (clusters.meshOf[c] as number) * 16;
+    const scale = scales[clusters.meshOf[c] as number] as number;
+
+    const cx = clusters.bounds[c * 4] as number;
+    const cy = clusters.bounds[c * 4 + 1] as number;
+    const cz = clusters.bounds[c * 4 + 2] as number;
+    const wx =
+      (transforms[at] as number) * cx +
+      (transforms[at + 4] as number) * cy +
+      (transforms[at + 8] as number) * cz +
+      (transforms[at + 12] as number);
+    const wy =
+      (transforms[at + 1] as number) * cx +
+      (transforms[at + 5] as number) * cy +
+      (transforms[at + 9] as number) * cz +
+      (transforms[at + 13] as number);
+    const wz =
+      (transforms[at + 2] as number) * cx +
+      (transforms[at + 6] as number) * cy +
+      (transforms[at + 10] as number) * cz +
+      (transforms[at + 14] as number);
+    const radius = (clusters.bounds[c * 4 + 3] as number) * scale;
+
+    const ax = clusters.cones[c * 4] as number;
+    const ay = clusters.cones[c * 4 + 1] as number;
+    const az = clusters.cones[c * 4 + 2] as number;
+    const tx =
+      (transforms[at] as number) * ax +
+      (transforms[at + 4] as number) * ay +
+      (transforms[at + 8] as number) * az;
+    const ty =
+      (transforms[at + 1] as number) * ax +
+      (transforms[at + 5] as number) * ay +
+      (transforms[at + 9] as number) * az;
+    const tz =
+      (transforms[at + 2] as number) * ax +
+      (transforms[at + 6] as number) * ay +
+      (transforms[at + 10] as number) * az;
+    const length = Math.hypot(tx, ty, tz);
+    /*
+     * **A cutoff of one is a refusal rather than a wide cone.** `cullClusters` culls when
+     * `dot(axis, d) >= cutoff * |d| + radius`, and for a unit axis the left-hand side is at most
+     * `|d|` — so at one the test cannot fire however the cluster is aimed, which is the
+     * conservative answer and is already what a bake writes for a cluster whose normals span a
+     * hemisphere.
+     */
+    const keepsCone = similar[clusters.meshOf[c] as number] === 1 && length > 0;
+    const out = (base + c) * CULL_FLOATS;
+    cull[out] = wx;
+    cull[out + 1] = wy;
+    cull[out + 2] = wz;
+    cull[out + 3] = radius;
+    cull[out + 4] = keepsCone ? tx / length : ax;
+    cull[out + 5] = keepsCone ? ty / length : ay;
+    cull[out + 6] = keepsCone ? tz / length : az;
+    cull[out + 7] = keepsCone ? (clusters.cones[c * 4 + 3] as number) : 1;
+
+    /*
+     * **The errors are lengths and a scale is a length's units.** `projectedError` divides a
+     * geometric error by the distance to the eye and multiplies by the screen height; the distance
+     * is in world metres now, so the error has to be. A mesh scaled up with its model-space error
+     * left alone draws its coarsest level everywhere.
+     *
+     * `Infinity` is how the coarsest level says it has no parent, and it is left alone: multiplied
+     * by a scale of zero it is `NaN`, every comparison against it is false, and the root of every
+     * mesh disappears.
+     */
+    const ownError = clusters.errors[c * 2] as number;
+    const parentError = clusters.errors[c * 2 + 1] as number;
+    const into = (base + c) * LOD_FLOATS;
+    lod[into] = wx;
+    lod[into + 1] = wy;
+    lod[into + 2] = wz;
+    lod[into + 3] = radius;
+    lod[into + 4] = ownError * scale;
+    lod[into + 5] = Number.isFinite(parentError) ? parentError * scale : parentError;
+  }
+}

package/src/render/gpudriven/compact.ts

@@ -0,0 +1,80 @@
+/**
+ * Turning three flag buffers into the one list a draw can read, and the block that draws it.
+ *
+ * **The culls answer per cluster and a draw wants a list.** `lodCut` writes a flag, `cullClusters`
+ * writes a flag, and the history is a flag — all three addressed by cluster identifier, because a
+ * dispatch decides every cluster at once and cannot append in input order without a prefix sum.
+ * The compaction is the step that turns the three into `[4, 17, 18, 40]` and says how many there
+ * are, which is what `instanceCount` in an indirect block is.
+ *
+ * **Order is not part of the answer.** The device appends with an atomic and the arrival order is
+ * whatever the scheduler did; this reference appends in cluster order because a loop has one. So a
+ * check comparing the two sorts both — the same rule `cullClusters.ts` avoids needing by answering
+ * in flags, and the reason the compaction is the one stage that cannot.
+ *
+ * **Four words, not `INDIRECT_DRAW_WORDS`' five, and that is the plan being wrong rather than a
+ * shortcut.** The plan has this as `drawIndexedIndirect`. It cannot be: one block covers every
+ * surviving cluster, each cluster's indices begin somewhere different, and an indexed draw has one
+ * `firstIndex` for the whole block. So the raster shader fetches indices out of a storage buffer
+ * itself — `visbufferRaster.wgsl.ts` already does — and what is issued is the non-indexed
+ * `drawIndirect`, whose block is vertex count, instances, first vertex, first instance. The five
+ * word block would *happen* to work, because its extra words are zero where the four-word one
+ * wants zero; that is a coincidence and not a layout.
+ *
+ * **The history is per cluster here rather than the bit set `twoPhase.ts` holds.** A shader
+ * addressing a bit needs a shift and a mask around every read and write, and the atomic that
+ * records this frame's would be a read-modify-write on a word shared by thirty-two clusters. One
+ * word a cluster is the device's shape; the bit set is the processor's, and they answer the same
+ * question.
+ */
+
+import { CLUSTER_INDEX_CAP } from './indirect.ts';
+
+/** Words in a non-indexed `drawIndirect` block: vertex count, instances, first vertex, first instance. */
+export const DRAW_INDIRECT_WORDS = 4;
+
+/**
+ * Which half of the frame a compaction is building.
+ *
+ * Phase one draws what the history holds; phase two draws what it does not. **Never "whether" —
+ * every live cluster is in exactly one of the two lists**, which is the invariant `twoPhase.ts`
+ * exists to state and the reason a history that is entirely stale costs a test rather than a hole.
+ */
+export const PHASE_ONE = 0;
+export const PHASE_TWO = 1;
+export type ClusterPhase = typeof PHASE_ONE | typeof PHASE_TWO;
+
+/**
+ * Append every cluster this phase draws, and write the block that draws them.
+ *
+ * **`drawn` is next frame's history, and only phase two writes it** — for every cluster, seen last
+ * frame or not, from its own cull, which is the only one that tested against this frame's pyramid.
+ * That is `updateHistory` in `twoPhase.ts`: the history is replaced, not accumulated. Phase one's
+ * cull has no pyramid, so a cluster it keeps may be hidden; marking it there kept every cluster ever
+ * seen drawn for as long as it stayed in the frustum. The caller clears `drawn` once a frame.
+ */
+export function compactPhase(
+  phase: ClusterPhase,
+  selected: Uint32Array,
+  keep: Uint32Array,
+  history: Uint32Array,
+  count: number,
+  list: Uint32Array,
+  drawn: Uint32Array,
+  args: Uint32Array,
+): number {
+  let at = 0;
+  for (let cluster = 0; cluster < count; cluster += 1) {
+    const seen = (history[cluster] ?? 0) !== 0;
+    const visible = (selected[cluster] ?? 0) !== 0 && (keep[cluster] ?? 0) !== 0;
+    if (phase === PHASE_TWO && visible) drawn[cluster] = 1;
+    if (seen !== (phase === PHASE_ONE) || !visible) continue;
+    list[at] = cluster;
+    at += 1;
+  }
+  args[0] = CLUSTER_INDEX_CAP;
+  args[1] = at;
+  args[2] = 0;
+  args[3] = 0;
+  return at;
+}

package/src/render/gpudriven/cullClusters.ts

@@ -0,0 +1,333 @@
+/**
+ * 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.ts';
+import { hzbOccluded } from './hzb.ts';
+
+/** 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 depth pyramid as a dispatch binds it: one flat buffer, one offset a level. */
+export interface ClusterHzb {
+  /** Every level's texels, coarsest last, as `hzbReduce` leaves them. */
+  readonly depths: Float32Array;
+  /** Where each level starts in `depths`. Its length is the level count. */
+  readonly offsets: Int32Array;
+  /** The base level's dimensions. Every level below is halved, never past one. */
+  readonly width: number;
+  readonly height: number;
+  /** The camera the pyramid was built with, which is this frame's in a two-phase pass. */
+  readonly viewProj: Float32Array;
+}
+
+/**
+ * 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: number): number {
+  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: number,
+  axisY: number,
+  axisZ: number,
+  cutoff: number,
+  centreX: number,
+  centreY: number,
+  centreZ: number,
+  radius: number,
+  eyeX: number,
+  eyeY: number,
+  eyeZ: number,
+): boolean {
+  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: Float32Array,
+  centreX: number,
+  centreY: number,
+  centreZ: number,
+  radius: number,
+  out: Float32Array,
+): boolean {
+  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] as number) * x +
+      (viewProj[7] as number) * y +
+      (viewProj[11] as number) * z +
+      (viewProj[15] as number);
+    /* At or behind the eye, so there is no rectangle. See the header. */
+    if (cw <= 1e-6) return false;
+    const cx =
+      (viewProj[0] as number) * x +
+      (viewProj[4] as number) * y +
+      (viewProj[8] as number) * z +
+      (viewProj[12] as number);
+    const cy =
+      (viewProj[1] as number) * x +
+      (viewProj[5] as number) * y +
+      (viewProj[9] as number) * z +
+      (viewProj[13] as number);
+    const cz =
+      (viewProj[2] as number) * x +
+      (viewProj[6] as number) * y +
+      (viewProj[10] as number) * z +
+      (viewProj[14] as number);
+    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: number,
+  rectHeightTexels: number,
+  width: number,
+  height: number,
+): number {
+  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: Float32Array,
+  offsets: Int32Array,
+  width: number,
+  height: number,
+  minX: number,
+  minY: number,
+  maxX: number,
+  maxY: number,
+  nearestDepth: number,
+): boolean {
+  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] as number;
+
+  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] as number);
+    }
+  }
+  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: Float32Array,
+  planes: Float32Array,
+  eyeX: number,
+  eyeY: number,
+  eyeZ: number,
+  hzb: ClusterHzb | null,
+  keep: Uint32Array,
+  list: Uint32Array,
+  selected: ArrayLike<number> | null = null,
+  /** False for the blended run, whose raster draws both sides. See `CULL_CONES`. */
+  cones = true,
+): number {
+  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] as number;
+    const cy = clusters[at + 1] as number;
+    const cz = clusters[at + 2] as number;
+    const radius = clusters[at + 3] as number;
+
+    let survives = !sphereOutsideFrustum(planes, cx, cy, cz, radius);
+    if (survives && cones) {
+      survives = !coneBackfacing(
+        clusters[at + 4] as number,
+        clusters[at + 5] as number,
+        clusters[at + 6] as number,
+        clusters[at + 7] as number,
+        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] as number,
+        bounds[1] as number,
+        bounds[2] as number,
+        bounds[3] as number,
+        bounds[4] as number,
+      );
+    }
+
+    keep[i] = survives ? CLUSTER_KEEP : 0;
+    if (survives) {
+      list[kept] = i;
+      kept += 1;
+    }
+  }
+  return kept;
+}