@driftengine/core 3.62.0 → 4.0.0

package/src/render/inference/splatTiles.ts

@@ -0,0 +1,186 @@
+/**
+ * Which tile of the frame each splat lands in, so a device can draw a cloud one tile at a time.
+ *
+ * **A splat cannot be drawn by one invocation per splat**, because splats overlap and compositing
+ * is ordered: two invocations writing the same pixel have no way to agree who was in front. The
+ * answer every implementation reaches is to turn the problem inside out — one workgroup per tile
+ * of the frame, each walking a list of the splats that touch it, each pixel accumulating its own
+ * colour in a register. This builds those lists.
+ *
+ * **The lists keep the order the splats arrive in.** The scatter is stable, so a caller that hands
+ * over a cloud already sorted by depth gets tiles whose lists are sorted by depth, and the
+ * compositing is correct without a per-tile sort anywhere. That is the whole reason the sort is a
+ * separate step rather than part of this one, and it is a *contract*: a caller that presents its
+ * splats in an arbitrary order gets tiles that composite in that arbitrary order, which is a
+ * picture rather than an error.
+ *
+ * **The tile range is derived from the same pixel box the rasteriser loops over**, not from the
+ * ellipse again. Two derivations of one footprint drift, and the failure is a splat missing from a
+ * tile it actually covers — a hole in the picture that moves with the camera and looks like a
+ * culling bug.
+ *
+ * **The lists are built twice over, by tile and by splat, and the second is what makes a backward
+ * pass deterministic.** A tile's gradients have to be added into the splats it walked, and many
+ * tiles touch one splat — which on a device is a floating-point atomic. WGSL has none, and the
+ * usual answer, a compare-and-swap loop over the bits, sums in whatever order the tiles happen to
+ * finish: floating-point addition is not associative, so the same cloud gives a different gradient
+ * every run and a fit stops reproducing. So every (tile, splat) pair gets a slot of its own,
+ * `pairOf` says which, and a splat's slots are **contiguous** — a reduction over them is a loop in
+ * a fixed order, which is the same answer every time on every device.
+ */
+
+/** The side of a tile in pixels; one workgroup covers one tile. */
+export const SPLAT_TILE = 16;
+
+/** Floats a splat's screen footprint occupies: `x`, `y`, `radius`, `depth`. */
+export const SPLAT_BIN_FLOATS = 4;
+
+/** How many tiles a frame of this size is cut into, across and down. */
+export function splatTileGrid(width: number, height: number): { across: number; down: number } {
+  return {
+    across: Math.max(0, Math.ceil(width / SPLAT_TILE)),
+    down: Math.max(0, Math.ceil(height / SPLAT_TILE)),
+  };
+}
+
+/**
+ * The pixel box a splat covers, clamped to the frame, into `out` as `left`, `top`, `right`,
+ * `bottom` — or `false` where it covers nothing.
+ *
+ * **This is the rasteriser's own box.** A device that computed its footprint any other way would
+ * be a second answer to the same question.
+ */
+export function splatPixelBox(
+  bins: ArrayLike<number>,
+  at: number,
+  width: number,
+  height: number,
+  out: Int32Array,
+): boolean {
+  const x = bins[at * SPLAT_BIN_FLOATS] as number;
+  const y = bins[at * SPLAT_BIN_FLOATS + 1] as number;
+  const radius = bins[at * SPLAT_BIN_FLOATS + 2] as number;
+  if (!(radius > 0)) return false;
+  const left = Math.max(0, Math.floor(x - radius));
+  const right = Math.min(width - 1, Math.ceil(x + radius));
+  const top = Math.max(0, Math.floor(y - radius));
+  const bottom = Math.min(height - 1, Math.ceil(y + radius));
+  if (right < left || bottom < top) return false;
+  out[0] = left;
+  out[1] = top;
+  out[2] = right;
+  out[3] = bottom;
+  return true;
+}
+
+/**
+ * How many splats each tile holds, and how many entries the lists need in total.
+ *
+ * `counts` is cleared here rather than by the caller: a count buffer reused across steps without
+ * clearing grows without bound, and the lists then run off the end of themselves.
+ */
+export function countSplatTiles(
+  bins: ArrayLike<number>,
+  count: number,
+  width: number,
+  height: number,
+  counts: Uint32Array,
+  tilesPerSplat?: Uint32Array,
+): number {
+  counts.fill(0);
+  tilesPerSplat?.fill(0);
+  const { across } = splatTileGrid(width, height);
+  const box = new Int32Array(4);
+  let total = 0;
+  for (let at = 0; at < count; at += 1) {
+    if (!splatPixelBox(bins, at, width, height, box)) continue;
+    const first = Math.floor((box[0] as number) / SPLAT_TILE);
+    const last = Math.floor((box[2] as number) / SPLAT_TILE);
+    const top = Math.floor((box[1] as number) / SPLAT_TILE);
+    const bottom = Math.floor((box[3] as number) / SPLAT_TILE);
+    for (let row = top; row <= bottom; row += 1) {
+      for (let column = first; column <= last; column += 1) {
+        const tile = row * across + column;
+        counts[tile] = (counts[tile] as number) + 1;
+        total += 1;
+      }
+    }
+    if (tilesPerSplat !== undefined) {
+      tilesPerSplat[at] = (last - first + 1) * (bottom - top + 1);
+    }
+  }
+  return total;
+}
+
+/**
+ * Where each tile's list begins: the exclusive prefix sum of the counts. Answers the total.
+ *
+ * A tile with no splats gets a zero-length list at a real offset rather than no entry at all,
+ * because the offsets are indexed by tile and dropping an empty one moves every later tile's list.
+ */
+export function splatTileOffsets(counts: Uint32Array, offsets: Uint32Array): number {
+  let running = 0;
+  for (let tile = 0; tile < counts.length; tile += 1) {
+    offsets[tile] = running;
+    running += counts[tile] as number;
+  }
+  return running;
+}
+
+/**
+ * Every splat written into the list of each tile it touches, in the order the splats are given.
+ *
+ * `cursors` is where each tile has got to and starts as a copy of `offsets` — it cannot be the
+ * offsets themselves, or the second splat of a tile overwrites the first's offset and every later
+ * tile's list starts in the wrong place.
+ */
+export function fillSplatTiles(
+  bins: ArrayLike<number>,
+  count: number,
+  width: number,
+  height: number,
+  offsets: Uint32Array,
+  cursors: Uint32Array,
+  lists: Uint32Array,
+  pairs?: { readonly offsets: Uint32Array; readonly pairOf: Uint32Array },
+): void {
+  cursors.set(offsets);
+  const { across } = splatTileGrid(width, height);
+  const box = new Int32Array(4);
+  for (let at = 0; at < count; at += 1) {
+    if (!splatPixelBox(bins, at, width, height, box)) continue;
+    const first = Math.floor((box[0] as number) / SPLAT_TILE);
+    const last = Math.floor((box[2] as number) / SPLAT_TILE);
+    const top = Math.floor((box[1] as number) / SPLAT_TILE);
+    const bottom = Math.floor((box[3] as number) / SPLAT_TILE);
+    let taken = 0;
+    for (let row = top; row <= bottom; row += 1) {
+      for (let column = first; column <= last; column += 1) {
+        const tile = row * across + column;
+        const slot = cursors[tile] as number;
+        if (slot >= lists.length) continue;
+        lists[slot] = at;
+        cursors[tile] = slot + 1;
+        if (pairs !== undefined) {
+          pairs.pairOf[slot] = (pairs.offsets[at] as number) + taken;
+          taken += 1;
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Where each splat's own run of partial-gradient slots begins: the prefix sum over `tilesPerSplat`.
+ *
+ * The same shape as `splatTileOffsets` and for the opposite index. A splat that covers no tile gets
+ * an empty run rather than no entry, because a reduction is indexed by splat.
+ */
+export function splatPairOffsets(tilesPerSplat: Uint32Array, offsets: Uint32Array): number {
+  let running = 0;
+  for (let at = 0; at < tilesPerSplat.length; at += 1) {
+    offsets[at] = running;
+    running += tilesPerSplat[at] as number;
+  }
+  return running;
+}

package/src/render/lineBatch.ts

@@ -1,6 +1,6 @@
 import { compileProgram, uniformLocations } from './shader.ts';
 import { LINE_FRAG, LINE_VERT } from './shaders/line.ts';
-import { buildSegmentQuads } from './segmentQuads.ts';
+import { buildSegmentQuads, expandLineSegments } from './segmentQuads.ts';
 import type { LineSegments } from './linePoints.ts';
 
 /**
@@ -71,31 +71,11 @@ export class LineBatch {
   /**
    * Send this frame's polyline, expanding each segment to its four vertices.
    *
-   * The expansion is written here rather than folded into `expandBoltSegments`: that
-   * function reads a `BoltSegments` — five arrays beyond `from`/`to` — and teaching it to
-   * read a `LineSegments` too would grow a union that couples two renderers sharing only a
-   * quad. This walk is the same shape with none of that: two positions in, copied to four
-   * vertices each.
+   * The expansion is `expandLineSegments`, which the other backend calls too, so the number of
+   * segments drawn — and whether anything is — is decided in one place.
    */
   upload(gl: WebGL2RenderingContext, data: LineSegments): number {
-    const count = Math.min(data.count, this.capacity);
-    for (let s = 0; s < count; s++) {
-      const fx = data.from[s * 3] as number;
-      const fy = data.from[s * 3 + 1] as number;
-      const fz = data.from[s * 3 + 2] as number;
-      const tx = data.to[s * 3] as number;
-      const ty = data.to[s * 3 + 1] as number;
-      const tz = data.to[s * 3 + 2] as number;
-      for (let c = 0; c < 4; c++) {
-        const v = s * 4 + c;
-        this.from[v * 3] = fx;
-        this.from[v * 3 + 1] = fy;
-        this.from[v * 3 + 2] = fz;
-        this.to[v * 3] = tx;
-        this.to[v * 3 + 1] = ty;
-        this.to[v * 3 + 2] = tz;
-      }
-    }
+    const count = expandLineSegments(data, this.capacity, this.from, this.to);
     if (count === 0) return 0;
     const verts = count * 4;
     gl.bindBuffer(gl.ARRAY_BUFFER, this.fromBuffer);

package/src/render/mesh.ts

@@ -57,6 +57,15 @@ const ATTR_JOINTS = 11;
  * setting sway, watching nothing move, and having nothing to read about why.
  */
 const ATTR_CHANNEL = 13;
+
+/**
+ * The locations `attachInstances` claims, which a plain draw through the same array must not read.
+ *
+ * Eleven to fourteen are the model matrix's columns and fifteen is the tint. **Thirteen is also
+ * the channel**, and eleven and twelve are the skinning pair — which cannot collide, because
+ * `flatVert` refuses skinning with instancing. See `draw`.
+ */
+const INSTANCE_COLUMNS = [11, 12, 13, 14, 15] as const;
 const ATTR_WEIGHTS = 12;
 
 /**
@@ -312,6 +321,29 @@ export class Mesh {
   /** Caller is responsible for having the flat program + uniforms bound. */
   draw(gl: WebGL2RenderingContext): void {
     gl.bindVertexArray(this.vao);
+    /*
+     * **A mesh with a batch has the instance columns enabled on this very array, and location 13
+     * is the channel.** `attachInstances` claims 11 to 14 for the model matrix and 15 for the
+     * tint; a `Mesh` owns one vertex array, so those bindings are still live for a *plain* draw
+     * through it — and `aChannel` then reads the third column of instance zero's matrix instead
+     * of the absent-attribute constant. For a placement with no rotation that column is
+     * `(0, 0, 1, 0)`, so `aChannel.y` is zero, `vSkyDirect = aChannel.y` scales the directional
+     * term to nothing, and the mesh renders lit by the hemispheric ambient alone — correct
+     * normals, correct albedo, no error, no warning.
+     *
+     * Found on `demo/instancing.ts`, which exists to draw two ranks of one box the two ways and
+     * compare them: the `drawMesh` rank's top face read (51, 30, 21) against the `drawInstanced`
+     * rank's (218, 110, 59), and 51 is exactly the ambient. WebGPU has no array to share and drew
+     * them alike, which is what made it visible at all.
+     *
+     * Disabled here and put back by `drawInstances`, rather than given the batch an array of its
+     * own: that is the larger change this class's own note about two batches already contemplates,
+     * and it wants one for a different reason. Three calls on a mesh that has a batch and none on
+     * a mesh that does not.
+     */
+    if (this.instanced) {
+      for (const location of INSTANCE_COLUMNS) gl.disableVertexAttribArray(location);
+    }
     // The VAO restores the arrays; these it cannot. See `constants`.
     for (const constant of this.constants) {
       const value = constant.value;
@@ -339,7 +371,16 @@ export class Mesh {
       );
     }
     this.instanced = true;
+    this.instanceBuffer = buffer;
+    this.instanceStride = stride;
     gl.bindVertexArray(this.vao);
+    this.bindInstanceColumns(gl, buffer);
+    gl.bindVertexArray(null);
+  }
+
+  /** The instance columns, bound. Called at attach and again after a plain draw disabled them. */
+  private bindInstanceColumns(gl: WebGL2RenderingContext, buffer: WebGLBuffer): void {
+    const stride = this.instanceStride;
     gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
     /* Four vec4 columns then a vec3 tint: a mat4 is not a vertex attribute in GLSL ES 300. */
     for (let column = 0; column < 4; column += 1) {
@@ -351,9 +392,11 @@ export class Mesh {
     gl.enableVertexAttribArray(15);
     gl.vertexAttribPointer(15, 3, gl.FLOAT, false, stride, 64);
     gl.vertexAttribDivisor(15, 1);
-    gl.bindVertexArray(null);
   }
 
+  private instanceBuffer: WebGLBuffer | null = null;
+  private instanceStride = 0;
+
   /** Whether `attachInstances` has already claimed locations 11 to 15 on this mesh's array. */
   private instanced = false;
 
@@ -365,6 +408,8 @@ export class Mesh {
    */
   drawInstances(gl: WebGL2RenderingContext, count: number): void {
     gl.bindVertexArray(this.vao);
+    /* Put back what `draw` disabled, if a plain draw of this mesh came first. See its note. */
+    if (this.instanceBuffer !== null) this.bindInstanceColumns(gl, this.instanceBuffer);
     for (const constant of this.constants) {
       const value = constant.value;
       applyConstant(gl, constant.location, value);

package/src/render/pass.ts

@@ -37,22 +37,37 @@ import type { FrameResource } from './frame/index.ts';
  */
 export type PassDevice = {
   /**
-   * Pre-multiply a projection by this before uploading it. Identity on WebGL2.
-   *
-   * **The two APIs do not agree about which way clip space points, and the engine settles it in
-   * the matrix rather than in the shaders** — see `CLIP_CORRECTION`, whose own comment gives the
-   * reason: the shaders are generated from the GLSL the WebGL2 path uses, and a Y flip written
-   * into them would be a difference no generator could keep honest. WebGPU's framebuffer origin
-   * is the top-left and OpenGL's is the bottom-left, and depth clips to [0, 1] rather than
-   * [-1, 1].
+   * Pre-multiply a projection by this **if your WGSL was generated from GLSL**. Identity on WebGL2.
    *
    * A contributed pass takes its camera from its caller, so it never sees the corrected matrix the
    * renderer built for its own verbs. Without this it would have to copy four numbers — and a
    * copied convention is one that silently disagrees the day the original changes. The splat pass
    * drew the world upside down on WebGPU until this existed, which is the same first frame this
    * backend ever produced: a colonnade hanging from the ceiling.
+   *
+   * **It does two things and only one of them is about the APIs.** Depth: OpenGL clips z to
+   * [-1, 1] and WebGPU to [0, 1], so an uncorrected matrix throws away half the buffer. Y: it is
+   * negated — and *not* because the framebuffer origins differ, which is what this comment used to
+   * say. Both viewport transforms put clip `y = +1` at the top of the image. What flips it is
+   * `naga`, which ends every generated vertex entry point with `gl_Position.y = -gl_Position.y`;
+   * the negation here cancels that one. See `CLIP_CORRECTION` in `webgpu/renderer.ts`.
+   *
+   * So **a pass whose shader went through the engine's generator wants this one**, which is every
+   * pass that has ever used it — `@driftengine/splats` writes GLSL and generates its WGSL — and a
+   * pass that wrote WGSL by hand wants `depthCorrection` instead.
    */
   readonly clipCorrection: Float32Array;
+  /**
+   * Pre-multiply a projection by this **if you wrote your WGSL by hand**. Identity on WebGL2.
+   *
+   * The same matrix without the Y negation, because there is no generated negation to cancel.
+   * Taking `clipCorrection` in a hand-written shader mirrors the picture vertically — and mirrors
+   * the triangle winding with it, so it presents as a culling problem and is answered with
+   * `frontFace: 'cw'`, which draws the correct faces of a mirrored world. That is exactly what
+   * happened to the GPU-driven pipeline's raster, and the capture that settled it was the same
+   * scene through `drawMesh`: an exact vertical mirror about the canvas centre.
+   */
+  readonly depthCorrection: Float32Array;
 } & (
   | { readonly backend: 'webgl2'; readonly gl: WebGL2RenderingContext }
   | {
@@ -61,6 +76,19 @@ export type PassDevice = {
       readonly format: GPUTextureFormat;
       readonly depthFormat: GPUTextureFormat;
       readonly samples: number;
+      /**
+       * Whether this renderer reconstructs its frames, which is fixed at construction as `samples`
+       * is.
+       *
+       * **A pass drawing the world into a reconstructed frame owes it two things.** It draws with
+       * the frame's jitter (`PrepareContext.jitter`), and it leaves its depth in the frame's
+       * attachment: the resolve reprojects every pixel's history through that depth, and a pixel
+       * still holding the clear reads as infinitely far away — so a turning camera's history is
+       * moved correctly, since a turn moves every depth alike, and a sliding camera's is not moved
+       * at all and trails the picture. A pass that decides at `init` whether to write depth
+       * decides it by this.
+       */
+      readonly reconstruction: boolean;
     }
 );
 
@@ -90,7 +118,12 @@ export type PassContext = {
   readonly outputExposure: number;
 } & (
   | { readonly backend: 'webgl2'; readonly gl: WebGL2RenderingContext }
-  | { readonly backend: 'webgpu'; readonly pass: GPURenderPassEncoder }
+  | {
+      readonly backend: 'webgpu';
+      readonly pass: GPURenderPassEncoder;
+      /** The frame's jitter, the same array `PrepareContext.jitter` held. */
+      readonly jitter: Float32Array;
+    }
 );
 
 /**
@@ -119,7 +152,119 @@ export type PassContext = {
  */
 export type PrepareContext =
   | { readonly backend: 'webgl2'; readonly gl: WebGL2RenderingContext }
-  | { readonly backend: 'webgpu'; readonly encoder: GPUCommandEncoder };
+  | {
+      readonly backend: 'webgpu';
+      readonly encoder: GPUCommandEncoder;
+      /**
+       * The frame's environment probe, or null where the scene has not baked one.
+       *
+       * **The first thing this seam hands over that a pass could not render for itself**, and it
+       * is here rather than on `PassDevice` because a probe is baked by a scene whenever it likes
+       * — after registration, and again when the world changes — so a value captured once at
+       * `init` would be null for the life of a pass that registered before the bake.
+       *
+       * It is offered rather than promised: a pass that wants to light what it draws by the room
+       * the rest of the frame is lit by has no other way to reach it, and a pass that does not
+       * care ignores the field. What it is *not* is an attachment of the frame — the rule that a
+       * contributed pass renders its own targets is unchanged, and this is a resource the renderer
+       * owns for the whole frame rather than one it is in the middle of writing.
+       */
+      readonly environment: PassEnvironment | null;
+      /**
+       * The world's composed distance field, or null where the frame composed none.
+       *
+       * **One frame behind, and that is what it is for.** The renderer composes at `endFrame`,
+       * because a consumer declares its fields wherever in its own frame the objects live and the
+       * set is not complete until the last verb. `prepare` runs at `beginFrame`, so what a pass is
+       * handed here is the field the *previous* frame declared — which is right for everything
+       * that reads a distance field, since a field is the shape of the world and the world does
+       * not usually change between two frames.
+       *
+       * Offered rather than promised, as `environment` is: a pass that wants to march the world
+       * the renderer's own indirect light marches has no other way to reach it, and one that does
+       * not care ignores the field. It is null whenever `quality.indirectLight` is off, which is
+       * the default, and whenever the frame declared nothing.
+       */
+      readonly distanceField: PassDistanceField | null;
+      /**
+       * The offset the renderer's own verbs are drawn with this frame, as a fraction of the clip
+       * square — x rightward and y upward, the camera's own convention — and zero on a frame that
+       * is not reconstructed. Two floats, the same array every frame.
+       *
+       * **A pass that draws the world applies it**, with `jitterClip`, to the camera matrix it was
+       * given and before any correction. Reconstruction un-jitters every sample it takes, so
+       * geometry drawn without the offset is placed up to half a render pixel from where it was,
+       * differently every frame, and the picture shimmers and softens. Settled at `beginFrame`,
+       * before this runs, and once a frame however many mesh passes the frame binds.
+       *
+       * What it gives up: the temporal resolve's jitter is not handed over. That resolve never
+       * un-jitters, so a pass drawn without its offset is left unantialiased by it rather than
+       * misplaced — a lesser fault, and one a pass can live with. A pass drawing into a mirror
+       * should not apply it either; the renderer's own verbs do not jitter a mirror.
+       */
+      readonly jitter: Float32Array;
+    };
+
+/**
+ * The world's distance field on the device, as the two buffers and four numbers that address it.
+ *
+ * **Cascades rather than one grid.** A single grid fine enough to resolve a doorway and large
+ * enough to hold a street is not a thing that fits on a device; nested cascades each of the same
+ * sample count, each reaching twice as far as the one inside it, spend their resolution where the
+ * camera is. `gi/globalField.ts` composes them and `shaders/gi/sampleField.wgsl.ts` reads them,
+ * and the layout below is what the two agree on.
+ */
+export interface PassDistanceField {
+  /** Every cascade's samples, tightly packed, cascade 0 first. */
+  readonly samples: GPUBuffer;
+  /**
+   * The colour of whatever surface won the union at each sample, three floats, same order.
+   *
+   * **A union loses which instance won**, and a ray that lands on a wall needs to know what colour
+   * it is: what leaves a surface is the light arriving times its albedo, and a distance alone
+   * cannot say. `GlobalFieldCascade.albedo` is the reference's own copy of this.
+   */
+  readonly albedo: GPUBuffer;
+  /** Six bounds and a step per cascade, as `sampleField.wgsl.ts` reads them. */
+  readonly cascades: GPUBuffer;
+  /** How many cascades stand. */
+  readonly levels: number;
+  /** Samples along one side of every cascade. */
+  readonly side: number;
+  /** Metres between samples in the innermost cascade — the finest the field resolves. */
+  readonly finestStep: number;
+  /** The outermost cascade's corners, `[minX, minY, minZ, maxX, maxY, maxZ]`. */
+  readonly outerBounds: Float32Array;
+}
+
+/**
+ * A baked environment probe, as the two things that sample it and the four numbers that address it.
+ *
+ * **Octahedral rather than a cubemap**, which is the engine's own storage: one 2D array texture,
+ * one layer a probe, a one-texel gutter at every level so a bilinear tap at the border reads the
+ * folded direction rather than the other side of the map. `shaders/octahedral.ts` carries the
+ * mapping in GLSL and in TypeScript, and `octInsetUv` is what turns a direction into a coordinate.
+ *
+ * **The chain is roughness, not size.** Level 0 is the mirror and `maxLod` is the roughest GGX
+ * convolution; `irradianceLevel` sits one beyond it and holds the cosine convolution, which is the
+ * diffuse half. `prefilterEnvMap.ts` derives all three from the edge and is the one place that
+ * arithmetic lives.
+ */
+export interface PassEnvironment {
+  /** The whole array, `2d-array`, as the lit pass binds it. */
+  readonly view: GPUTextureView;
+  readonly sampler: GPUSampler;
+  /** Texels across level 0, gutter included. A level's own edge is this over `exp2(level)`. */
+  readonly edge: number;
+  /** The coarsest level of the GGX chain. */
+  readonly maxLod: number;
+  /** Which level holds the cosine convolution. */
+  readonly irradianceLevel: number;
+  /** Whether the scene asked this grid to supply its ambient. `ProbeBakeOptions.irradiance`. */
+  readonly irradiance: boolean;
+  /** How many probes stand in the grid. A pass reading layer 0 alone is right only for one. */
+  readonly layers: number;
+}
 
 export interface PassDefinition {
   /** For diagnostics, and for the label a backend gives the work. */

package/src/render/prefilterEnvMap.ts

@@ -160,3 +160,36 @@ export function sourceLevelForSample(
 
   return Math.min(maxLevel, Math.max(0, level));
 }
+
+/**
+ * A level's own edge in texels, which is not the map's.
+ *
+ * **The gutter is one texel at every level**, so its share of the map doubles as the chain
+ * coarsens and an inset computed once from the map's own size is wrong everywhere but level zero.
+ * `flat/probeGrid.ts` carries the same expression for the forward path and records the slide it
+ * prevents: a thirty-second of the map at the top of the chain, visible as a reflection sliding as
+ * roughness rises.
+ *
+ * Floored at four, which is where the chain stops — a level two texels across is all gutter.
+ */
+export function probeLevelEdge(edge: number, level: number): number {
+  return Math.max(edge / 2 ** level, 4);
+}
+
+/**
+ * The two levels a roughness reads and how far between them it sits, as `lo`, `hi`, `t`.
+ *
+ * **Mixed by hand rather than by hardware trilinear**, for the reason above: the two levels have
+ * different insets and hardware applies one coordinate to both. So the two fetches are issued at
+ * their own insets and blended here, and this is the arithmetic that says which two and by how
+ * much. Clamped at both ends, so a lod past the chain reads the coarsest level twice rather than
+ * sampling a level that does not exist.
+ */
+export function probeLevelMix(lod: number, maxLevel: number, out: Float32Array): Float32Array {
+  const lo = Math.min(Math.max(Math.floor(lod), 0), maxLevel);
+  const hi = Math.min(lo + 1, maxLevel);
+  out[0] = lo;
+  out[1] = hi;
+  out[2] = Math.min(Math.max(lod - lo, 0), 1);
+  return out;
+}

package/src/render/readback.ts

@@ -0,0 +1,73 @@
+/**
+ * Getting a number back from the GPU without waiting for it.
+ *
+ * The answer to a request made this frame arrives two or three frames later, and a caller that
+ * waits has stalled the pipeline to learn something it could have learned late for free. So this
+ * is a ring of slots: a request takes one, the completion fills it, and the caller collects
+ * whatever has arrived whenever it asks.
+ *
+ * **A full ring refuses rather than overwrites.** Silently dropping the oldest result produces a
+ * statistic that is wrong in a way nothing detects — a frame time that is quietly somebody
+ * else's, which is worse than a frame time that is missing.
+ *
+ * **Deliberately not what texture residency uses.** Reactive streaming is exactly the
+ * arrangement where this latency becomes visible as pop-in; the answer there is to predict
+ * rather than to read back. This ring is for timings and statistics, where being three frames
+ * late costs nothing.
+ */
+export interface ReadbackRing {
+  /** 0 free, 1 outstanding, 2 arrived, one per slot. */
+  state: Uint8Array;
+  /** The arrived buffer per slot, or null. */
+  data: (ArrayBuffer | null)[];
+  /** Where to start looking for a free slot, so requests spread rather than reusing one. */
+  next: number;
+}
+
+export function createReadbackRing(slots: number): ReadbackRing {
+  return {
+    state: new Uint8Array(slots),
+    data: Array.from({ length: slots }, () => null),
+    next: 0,
+  };
+}
+
+export function beginReadback(ring: ReadbackRing): number {
+  const slots = ring.state.length;
+  for (let i = 0; i < slots; i += 1) {
+    const slot = (ring.next + i) % slots;
+    if (ring.state[slot] === 0) {
+      ring.state[slot] = 1;
+      ring.next = (slot + 1) % slots;
+      return slot;
+    }
+  }
+  return -1;
+}
+
+export function completeReadback(ring: ReadbackRing, slot: number, data: ArrayBuffer): void {
+  if (slot < 0 || slot >= ring.state.length) return;
+  /* Only an outstanding slot may be completed: one that was evicted or never requested is not
+   * ours to fill, and filling it would hand the caller a result for a request it has forgotten. */
+  if (ring.state[slot] !== 1) return;
+  ring.state[slot] = 2;
+  ring.data[slot] = data;
+}
+
+export function takeReadback(ring: ReadbackRing): ArrayBuffer | null {
+  for (let slot = 0; slot < ring.state.length; slot += 1) {
+    if (ring.state[slot] === 2) {
+      const data = ring.data[slot] ?? null;
+      ring.state[slot] = 0;
+      ring.data[slot] = null;
+      return data;
+    }
+  }
+  return null;
+}
+
+export function readbackPending(ring: ReadbackRing): number {
+  let pending = 0;
+  for (let slot = 0; slot < ring.state.length; slot += 1) if (ring.state[slot] === 1) pending += 1;
+  return pending;
+}