@driftengine/core 3.63.0 → 4.0.0

package/src/render/gpudriven/decodeTables.ts

@@ -0,0 +1,332 @@
+/** 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.ts';
+
+/**
+ * **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 function programFromEncoded(encoded: EncodedProgramShape): GpuDrivenProgram {
+  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: Readonly<Record<number, readonly [boolean, boolean]>> = {
+  [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: string): never {
+  throw new Error(`[driftengine] ${message}`);
+}
+
+/** `networkWeightCount`, again, for the same reason `REGISTER_ARGS` is. */
+function weightCount(shape: GpuDrivenNetwork['shape']): number {
+  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: readonly GpuDrivenProgram[]): DecodeTables {
+  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: Uint8Array[][] = Array.from({ length: levelCount }, () => []);
+
+  let layers = 0;
+  let networkCount = 0;
+  let nodeCount = 0;
+  let weightAt = 0;
+  let constantCount = 0;
+
+  const addLatent = (latent: GpuDrivenLatent): number => {
+    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] as Uint8Array;
+      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] as number)
+              : c === 3
+                ? 255
+                : 0;
+        }
+      }
+      (chunks[level] as Uint8Array[]).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: number[] = [];
+    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] as number;
+      let a = graph.nodes[i * 4 + 1] as number;
+      let b = graph.nodes[i * 4 + 2] as number;
+      const dst = graph.nodes[i * 4 + 3] as number;
+      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/src/render/gpudriven/frustum.ts

@@ -0,0 +1,70 @@
+/**
+ * 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: Float32Array, at: number, a: number, b: number, c: number, d: number): void {
+  /* 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: Float32Array, out: Float32Array): void {
+  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] as number, m[4] as number, m[8] as number, m[12] as number];
+  const r1 = [m[1] as number, m[5] as number, m[9] as number, m[13] as number];
+  const r2 = [m[2] as number, m[6] as number, m[10] as number, m[14] as number];
+  const r3 = [m[3] as number, m[7] as number, m[11] as number, m[15] as number];
+
+  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: Float32Array,
+  cx: number,
+  cy: number,
+  cz: number,
+  radius: number,
+): boolean {
+  for (let p = 0; p < 6; p += 1) {
+    const at = p * 4;
+    const distance =
+      (planes[at] as number) * cx +
+      (planes[at + 1] as number) * cy +
+      (planes[at + 2] as number) * cz +
+      (planes[at + 3] as number);
+    if (distance < -radius) return true;
+  }
+  return false;
+}

package/src/render/gpudriven/geometryHarness.ts

@@ -0,0 +1,51 @@
+/**
+ * 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.ts';
+
+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 function mirrorSink(capacity: StreamCapacity): MirrorSink {
+  const vertices = new Float32Array(capacity.vertices * GPU_DRIVEN_VERTEX_FLOATS);
+  const indices = new Uint32Array(capacity.indices);
+  const writes: MirrorWrite[] = [];
+  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 });
+    },
+  };
+}

package/src/render/gpudriven/hzb.ts

@@ -0,0 +1,113 @@
+/**
+ * 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: number, height: number): number {
+  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: number, height: number): { width: number; height: number } {
+  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: Float32Array,
+  width: number,
+  height: number,
+  out: Float32Array,
+): { width: number; height: number } {
+  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] as number);
+        }
+      }
+      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: Float32Array,
+  width: number,
+  height: number,
+  out: Float32Array,
+): { width: number; height: number } {
+  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] as number);
+        }
+      }
+      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: number, occluderFurthestDepth: number): boolean {
+  return sphereNearestDepth < occluderFurthestDepth;
+}