@driftengine/core 3.63.0 → 4.0.0

package/dist/render/inference/splatTiles.d.ts

@@ -0,0 +1,79 @@
+/**
+ * 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 declare const SPLAT_TILE = 16;
+/** Floats a splat's screen footprint occupies: `x`, `y`, `radius`, `depth`. */
+export declare const SPLAT_BIN_FLOATS = 4;
+/** How many tiles a frame of this size is cut into, across and down. */
+export declare function splatTileGrid(width: number, height: number): {
+    across: number;
+    down: number;
+};
+/**
+ * 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 declare function splatPixelBox(bins: ArrayLike<number>, at: number, width: number, height: number, out: Int32Array): boolean;
+/**
+ * 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 declare function countSplatTiles(bins: ArrayLike<number>, count: number, width: number, height: number, counts: Uint32Array, tilesPerSplat?: Uint32Array): number;
+/**
+ * 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 declare function splatTileOffsets(counts: Uint32Array, offsets: Uint32Array): number;
+/**
+ * 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 declare 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;
+/**
+ * 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 declare function splatPairOffsets(tilesPerSplat: Uint32Array, offsets: Uint32Array): number;

package/dist/render/inference/splatTiles.js

@@ -0,0 +1,161 @@
+/**
+ * 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, height) {
+    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, at, width, height, out) {
+    const x = bins[at * SPLAT_BIN_FLOATS];
+    const y = bins[at * SPLAT_BIN_FLOATS + 1];
+    const radius = bins[at * SPLAT_BIN_FLOATS + 2];
+    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, count, width, height, counts, tilesPerSplat) {
+    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] / SPLAT_TILE);
+        const last = Math.floor(box[2] / SPLAT_TILE);
+        const top = Math.floor(box[1] / SPLAT_TILE);
+        const bottom = Math.floor(box[3] / 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] + 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, offsets) {
+    let running = 0;
+    for (let tile = 0; tile < counts.length; tile += 1) {
+        offsets[tile] = running;
+        running += counts[tile];
+    }
+    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, count, width, height, offsets, cursors, lists, pairs) {
+    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] / SPLAT_TILE);
+        const last = Math.floor(box[2] / SPLAT_TILE);
+        const top = Math.floor(box[1] / SPLAT_TILE);
+        const bottom = Math.floor(box[3] / 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];
+                if (slot >= lists.length)
+                    continue;
+                lists[slot] = at;
+                cursors[tile] = slot + 1;
+                if (pairs !== undefined) {
+                    pairs.pairOf[slot] = pairs.offsets[at] + 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, offsets) {
+    let running = 0;
+    for (let at = 0; at < tilesPerSplat.length; at += 1) {
+        offsets[at] = running;
+        running += tilesPerSplat[at];
+    }
+    return running;
+}

package/dist/render/lineBatch.d.ts

@@ -32,11 +32,8 @@ export declare 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;
     /**

package/dist/render/lineBatch.js

@@ -1,6 +1,6 @@
 import { compileProgram, uniformLocations } from './shader.js';
 import { LINE_FRAG, LINE_VERT } from './shaders/line.js';
-import { buildSegmentQuads } from './segmentQuads.js';
+import { buildSegmentQuads, expandLineSegments } from './segmentQuads.js';
 /**
  * One draw call for a polyline with a real width — an audio waveform, a trail, a plotted
  * curve, anything that is a stroke rather than a surface.
@@ -64,31 +64,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, data) {
-        const count = Math.min(data.count, this.capacity);
-        for (let s = 0; s < count; s++) {
-            const fx = data.from[s * 3];
-            const fy = data.from[s * 3 + 1];
-            const fz = data.from[s * 3 + 2];
-            const tx = data.to[s * 3];
-            const ty = data.to[s * 3 + 1];
-            const tz = data.to[s * 3 + 2];
-            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;

package/dist/render/mesh.d.ts

@@ -105,6 +105,10 @@ export declare class Mesh {
      * which wants a vertex array per batch rather than a flag here.
      */
     attachInstances(gl: WebGL2RenderingContext, buffer: WebGLBuffer, stride: number): void;
+    /** The instance columns, bound. Called at attach and again after a plain draw disabled them. */
+    private bindInstanceColumns;
+    private instanceBuffer;
+    private instanceStride;
     /** Whether `attachInstances` has already claimed locations 11 to 15 on this mesh's array. */
     private instanced;
     /**

package/dist/render/mesh.js

@@ -49,6 +49,14 @@ 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];
 const ATTR_WEIGHTS = 12;
 /**
  * One absent attribute's constant, at the width the table gave it.
@@ -295,6 +303,30 @@ export class Mesh {
     /** Caller is responsible for having the flat program + uniforms bound. */
     draw(gl) {
         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;
@@ -319,7 +351,15 @@ export class Mesh {
                 'second batch would rebind the attributes the first draws through.');
         }
         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. */
+    bindInstanceColumns(gl, buffer) {
+        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) {
@@ -331,8 +371,9 @@ export class Mesh {
         gl.enableVertexAttribArray(15);
         gl.vertexAttribPointer(15, 3, gl.FLOAT, false, stride, 64);
         gl.vertexAttribDivisor(15, 1);
-        gl.bindVertexArray(null);
     }
+    instanceBuffer = null;
+    instanceStride = 0;
     /** Whether `attachInstances` has already claimed locations 11 to 15 on this mesh's array. */
     instanced = false;
     /**
@@ -343,6 +384,9 @@ export class Mesh {
      */
     drawInstances(gl, count) {
         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/dist/render/pass.d.ts

@@ -34,22 +34,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;
@@ -59,6 +74,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;
 });
 /**
  * What it is handed each frame, at the point the caller asked for it.
@@ -90,6 +118,8 @@ export type PassContext = {
 } | {
     readonly backend: 'webgpu';
     readonly pass: GPURenderPassEncoder;
+    /** The frame's jitter, the same array `PrepareContext.jitter` held. */
+    readonly jitter: Float32Array;
 });
 /**
  * What a pass is handed once a frame, before the frame's own target exists.
@@ -121,7 +151,114 @@ export type PrepareContext = {
 } | {
     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. */
     readonly label: string;

package/dist/render/prefilterEnvMap.d.ts

@@ -122,3 +122,25 @@ export declare function roughnessForLevel(level: number, maxLevel: number): numb
  * objects rather than one written in place.
  */
 export declare function sourceLevelForSample(pdf: number, faceTexels: number, count: number, maxLevel: number): number;
+/**
+ * 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 declare function probeLevelEdge(edge: number, level: number): number;
+/**
+ * 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 declare function probeLevelMix(lod: number, maxLevel: number, out: Float32Array): Float32Array;

package/dist/render/prefilterEnvMap.js

@@ -144,3 +144,34 @@ export function sourceLevelForSample(pdf, faceTexels, count, maxLevel) {
     const level = 0.5 * Math.log2(sampleSolidAngle / texelSolidAngle);
     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, level) {
+    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, maxLevel, out) {
+    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;
+}