@driftengine/core 4.3.0 → 4.4.0

package/src/render/backend/webgpu/scatterPass.ts

@@ -165,18 +165,18 @@ export function createScatterBindGroupLayout(device: GPUDevice): GPUBindGroupLay
     label: 'scatter.layout',
     entries: [
       /*
-       * **The vertex block is per draw and the fragment block is not.**
+       * **Both blocks are per draw.**
        *
        * The vertex block carries the gust and the trample field, and both arrive as arguments
        * to `drawScatter` — so a scene bending its grass by one press field and its canopy by
        * another gets whichever was written last for both, from a single buffer. That is not
        * hypothetical elsewhere: the plume pass had exactly this and drew a flame bent by the
-       * smoke's wind response. The demo that exercises this today happens to pass both
-       * batches the same wind and no trample, which is luck rather than a guarantee.
+       * smoke's wind response.
        *
-       * The fragment block holds the camera, the sun, the point lights and the medium, which
-       * are settled per pass rather than per batch. It stops being safe the day something
-       * per-batch is added to it, and that is what would make this a ring too.
+       * The fragment block holds the camera, the sun, the point lights and the medium. It was one
+       * buffer on the argument that those are settled per pass, and a pass is not an encoder: a
+       * probe records six passes in one, a mirror shares the frame's, and queue writes land before
+       * either runs. So every pass drew its blades from the last camera, and it is a ring too.
        */
       {
         binding: VERT_BINDING,
@@ -186,7 +186,7 @@ export function createScatterBindGroupLayout(device: GPUDevice): GPUBindGroupLay
       {
         binding: FRAG_BINDING,
         visibility: VISIBILITY_FRAGMENT,
-        buffer: { type: 'uniform', minBindingSize: SCATTER_FRAG_SIZE },
+        buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: SCATTER_FRAG_SIZE },
       },
     ],
   });

package/src/render/backend/webgpu/skinPaletteRing.ts

@@ -63,6 +63,16 @@ export class SkinPaletteRing {
     this.used = 0;
   }
 
+  /** Where the ring stands, to hand back to `rewind`. See `UniformRing.rewind` for when it is safe. */
+  mark(): number {
+    return this.used;
+  }
+
+  /** Give back every slot taken since `mark`, once the commands reading them are submitted. */
+  rewind(mark: number): void {
+    if (mark < this.used) this.used = mark;
+  }
+
   /**
    * Upload a palette into a slot of its own and return that slot, or null when the ring is full.
    *

package/src/render/backend/webgpu/skyPass.ts

@@ -26,7 +26,11 @@ export function createSkyBindGroupLayout(device: GPUDevice): GPUBindGroupLayout
       {
         binding: SKY_BINDING,
         visibility: VISIBILITY_FRAGMENT,
-        buffer: { type: 'uniform', minBindingSize: SKY_UNIFORM_SIZE },
+        /*
+         * A dynamic offset, because a frame draws more than one sky — a probe's six faces, a mirror
+         * and the view — and one buffer rewritten between them hands every draw the last write.
+         */
+        buffer: { type: 'uniform', hasDynamicOffset: true, minBindingSize: SKY_UNIFORM_SIZE },
       },
     ],
   });

package/src/render/backend/webgpu/uniformRing.ts

@@ -58,6 +58,11 @@ export class UniformRing {
   private ints: Int32Array;
   private capacity: number;
   private used = 0;
+  /**
+   * The byte below which the device already holds what the staging does: the end of the last
+   * flush, lowered by any write under it since. See `flush`.
+   */
+  private clean = 0;
 
   /**
    * `label` names the buffer on the device, and it is not decoration.
@@ -124,6 +129,7 @@ export class UniformRing {
 
     this.buffer.destroy();
     this.capacity = slots;
+    this.clean = 0;
     this.staging = new ArrayBuffer(bytes);
     this.floats = new Float32Array(this.staging);
     this.ints = new Int32Array(this.staging);
@@ -143,6 +149,28 @@ export class UniformRing {
   /** Start a frame. Slots are reused; nothing is freed. */
   reset(): void {
     this.used = 0;
+    this.clean = 0;
+  }
+
+  /** Where the ring stands, to hand back to `rewind`. */
+  mark(): number {
+    return this.used;
+  }
+
+  /**
+   * Give back every slot taken since `mark`, for a caller that has already submitted the commands
+   * reading them.
+   *
+   * **Safe because the queue is ordered, and only then.** A `writeBuffer` issued after a submit
+   * cannot reach the commands in it, so slots a submitted encoder read may be rewritten by the next
+   * one. A slot taken by an encoder not yet submitted may not be: every draw pointing at it would
+   * read whatever overwrote it, which is the defect this class exists to prevent. What uses it is
+   * work that submits encoders of its own mid-frame — a probe bake — so the frame's rings are not
+   * spent by something the frame never draws.
+   */
+  rewind(mark: number): void {
+    if (mark < this.used) this.used = mark;
+    if (this.used * this.slotSize < this.clean) this.clean = this.used * this.slotSize;
   }
 
   /**
@@ -180,6 +208,7 @@ export class UniformRing {
 
   /** Write floats into a slot, at a byte offset within it. */
   writeFloats(slot: number, byteOffset: number, values: ArrayLike<number>): void {
+    if (slot < this.clean) this.clean = slot;
     this.floats.set(values, (slot + byteOffset) / 4);
   }
 
@@ -192,11 +221,13 @@ export class UniformRing {
    * buffer being reused.
    */
   writeFloat(slot: number, byteOffset: number, value: number): void {
+    if (slot < this.clean) this.clean = slot;
     this.floats[(slot + byteOffset) / 4] = value;
   }
 
   /** Write one integer into a slot. Separate because a `Float32Array` cannot hold an `i32`. */
   writeInt(slot: number, byteOffset: number, value: number): void {
+    if (slot < this.clean) this.clean = slot;
     this.ints[(slot + byteOffset) / 4] = value;
   }
 
@@ -213,13 +244,28 @@ export class UniformRing {
    * `Int32Array.set` from an `Int32Array` is an exact copy of every bit, whatever the bits mean.
    */
   writeBlock(slot: number, block: Int32Array): void {
+    if (slot < this.clean) this.clean = slot;
     this.ints.set(block, slot / 4);
   }
 
-  /** Upload every slot taken this frame, in one write. */
+  /**
+   * Upload every slot taken this frame that the device does not already hold, in one write.
+   *
+   * **From the watermark, not from zero, because a frame flushes more than once.** Every submit in
+   * the middle of a frame flushes first, and a probe bake submits per face: sending the whole used
+   * range each time sent a courtyard's first slots two hundred times over, 2.3 GB in a two-second
+   * grid bake, measured. Queue writes are ordered, so bytes already sent and not written since are
+   * on the device for every command after them, and resending them changed nothing.
+   *
+   * What it gives up is one compare per write. What would make it wrong is a write that reached the
+   * staging without passing a method that lowers `clean` — which is why the staging stays private.
+   */
   flush(): void {
-    if (this.used === 0) return;
-    this.device.queue.writeBuffer(this.buffer, 0, this.staging, 0, this.used * this.slotSize);
+    const end = this.used * this.slotSize;
+    if (end <= this.clean) return;
+    const from = this.clean;
+    this.device.queue.writeBuffer(this.buffer, from, this.staging, from, end - from);
+    this.clean = end;
   }
 
   dispose(): void {

package/src/render/bloomChain.ts

@@ -49,6 +49,15 @@ export const BLOOM_FILTER_RADIUS_UV = 0.005;
  * an exposure with no curve to be exposed into — where everything is switched on, nothing is
  * wrong, and nothing happens.
  */
+/**
+ * A threshold a frame asked for through `setBloom`, made safe: at least a thousandth of a scene
+ * unit, because zero blooms the whole frame including what is meant to be dark, and a
+ * non-number would reach the shader as one. Decided here so both backends answer the same.
+ */
+export function bloomThresholdOf(threshold: number): number {
+  return Number.isFinite(threshold) ? Math.max(threshold, 1e-3) : 1e-3;
+}
+
 export function bloomProfileWarning(quality: {
   readonly bloom: number;
   readonly screenEffects: boolean;

package/src/render/clusteredLights.ts

@@ -24,27 +24,35 @@ export const CLUSTER_Z = 24;
 export const CLUSTER_COUNT = CLUSTER_X * CLUSTER_Y * CLUSTER_Z;
 
 /**
- * Texels a cluster occupies: one for its count, seven holding four light indices each.
+ * Texels a cluster occupies: one for its count, nineteen holding four light indices each.
  *
  * **Fixed rather than packed, and that is what removes the atomics.** One invocation owns one
  * cluster and writes only its own run, so nothing is appended to a shared list, there is no
  * counter to increment atomically and no compaction pass. That is also what lets the GPU binner
  * write through a *write-only* storage texture, which is all core WGSL gives.
  */
-export const CLUSTER_TEXELS = 5;
+export const CLUSTER_TEXELS = 20;
 
 /**
- * How many lights one cluster can hold. Four index texels at four indices each.
+ * How many lights one cluster can hold: nineteen index texels at four indices each, 76.
  *
- * **Sixteen because that is `MAX_POINT_LIGHTS`, and the equality is the point.** The light loop's
- * bound has to be a constant and there is only one loop, so a larger cap here would raise it for
- * the fixed path too — a scene that never asks for froxels would carry a loop bound of 28 where it
- * carries 16 today, which on the driver that faulted under the full shader is precisely the sort
- * of change nobody would attribute to clustering. Equal bounds mean the fixed path is untouched.
+ * **Sixteen until a candlelit interior drew its froxels as rectangles.** The cap was pinned to
+ * `MAX_POINT_LIGHTS` so the one light loop kept one bound. Then a courtyard of candles, lanterns
+ * and braziers asked 461 of its 3,456 froxels for more than sixteen, and up to fifty. A full froxel
+ * keeps its nearest and drops the rest, and its neighbour keeps a different set, so the step
+ * between them drew as hard-edged, screen-aligned rectangles on every vault, on both backends.
+ *
+ * Seventy-six because it is the next cap the table's shape allows above what was measured: a run
+ * must divide the 320-texel row, and the two regions must end on one. What it costs is the table,
+ * 292 KB to 1.1 MB, and the loop's bound. The bound is the clustered arm's alone in effect: the
+ * fixed arm still leaves at its own count and never passes `MAX_LIGHTS`, so a consumer that does
+ * not cluster iterates what it did. What would make 76 wrong is content that asks more of one
+ * froxel, and the answer then is the next cap rather than a softer overflow: any overflow rule
+ * draws the cluster's edge.
  *
  * **It is not the old limit wearing a new hat.** Sixteen was a budget for the *whole scene*, chosen
- * by distance with a contention band because somebody always had to be last. Sixteen per froxel is
- * a different sixteen in every froxel, out of `MAX_CLUSTERED_LIGHTS` in the scene.
+ * by distance with a contention band because somebody always had to be last. This is a different
+ * set in every froxel, out of `MAX_CLUSTERED_LIGHTS` in the scene.
  */
 export const MAX_LIGHTS_PER_CLUSTER = (CLUSTER_TEXELS - 1) * 4;
 
@@ -162,7 +170,7 @@ export const LIGHT_REGION_TEXELS = MAX_CLUSTERED_LIGHTS * LIGHT_TEXELS;
  */
 export const TABLE_WIDTH = 320;
 
-/** Rows: three of light records and 54 of cluster runs. 292 KB of `RGBA32UI`, allocated once. */
+/** Rows: five of light records and 216 of cluster runs. 1.1 MB of `RGBA32UI`, allocated once. */
 export const TABLE_HEIGHT = (LIGHT_REGION_TEXELS + CLUSTER_COUNT * CLUSTER_TEXELS) / TABLE_WIDTH;
 
 /** The table, as the `Uint32Array` both a texture upload and a readback comparison want. */
@@ -247,6 +255,33 @@ export function clusterViewBounds(
   out[5] = zFar;
 }
 
+/**
+ * `clusterViewBounds` for a slice whose depths and half extents the caller already has. The same
+ * arithmetic in the same order, so the same box to the bit; the binner's inner loop uses this.
+ */
+function sliceBounds(
+  i: number,
+  j: number,
+  zNear: number,
+  zFar: number,
+  halfWNear: number,
+  halfWFar: number,
+  halfHNear: number,
+  halfHFar: number,
+  out: Float32Array,
+): void {
+  const xLo = -1 + (2 * i) / CLUSTER_X;
+  const xHi = -1 + (2 * (i + 1)) / CLUSTER_X;
+  const yLo = -1 + (2 * j) / CLUSTER_Y;
+  const yHi = -1 + (2 * (j + 1)) / CLUSTER_Y;
+  out[0] = Math.min(xLo * halfWNear, xLo * halfWFar, xHi * halfWNear, xHi * halfWFar);
+  out[3] = Math.max(xLo * halfWNear, xLo * halfWFar, xHi * halfWNear, xHi * halfWFar);
+  out[1] = Math.min(yLo * halfHNear, yLo * halfHFar, yHi * halfHNear, yHi * halfHFar);
+  out[4] = Math.max(yLo * halfHNear, yLo * halfHFar, yHi * halfHNear, yHi * halfHFar);
+  out[2] = zNear;
+  out[5] = zFar;
+}
+
 /** The light arrays the binner reads, in the shape `Environment` already carries them. */
 export interface ClusterLightSet {
   readonly count: number;
@@ -282,6 +317,16 @@ export interface ClusterLightSet {
  * rule forbids allocating there.
  */
 const bounds = new Float32Array(6);
+/**
+ * Where each slice begins, for the frame being binned: `sliceNearDepth` for every slice and the
+ * far plane, computed once. The same expression as a call per cluster, so the same numbers.
+ *
+ * **Once a binning rather than once a cluster**, which was two `pow` for every light and every
+ * cluster it might touch. A courtyard of candles within a few metres of the camera is 640,000 of
+ * those pairs, and the binning took 47 ms of a frame. On WebGL2 it runs every `bindMeshPass`, so a
+ * probe grid baked at night binned for a minute.
+ */
+const sliceDepths = new Float64Array(CLUSTER_Z + 1);
 /** View-space light centres, kept for the overflow rule, which needs them after the fact. */
 const viewX = new Float32Array(MAX_CLUSTERED_LIGHTS);
 const viewY = new Float32Array(MAX_CLUSTERED_LIGHTS);
@@ -312,19 +357,6 @@ function distanceSqToBounds(x: number, y: number, z: number, b: Float32Array): n
   return dx * dx + dy * dy + dz * dz;
 }
 
-/** Insertion sort over a cluster's index slots. At most 28 integers, so this is not a hot loop. */
-function sortIndices(table: Uint32Array, base: number, count: number): void {
-  for (let n = 1; n < count; n++) {
-    const value = table[base + 4 + n] ?? 0;
-    let m = n - 1;
-    while (m >= 0 && (table[base + 4 + m] ?? 0) > value) {
-      table[base + 4 + m + 1] = table[base + 4 + m] ?? 0;
-      m--;
-    }
-    table[base + 4 + m + 1] = value;
-  }
-}
-
 /**
  * Fill the table with this frame's light assignment, and answer how many lights it carried.
  *
@@ -393,6 +425,7 @@ export function buildLightClusters(
    * replaces; agreeing about the invisible bytes is what keeps the comparison exact.
    */
   table.fill(0, LIGHT_REGION_TEXELS * 4);
+  for (let k = 0; k <= CLUSTER_Z; k++) sliceDepths[k] = sliceNearDepth(k, near, far);
 
   for (let light = 0; light < count; light++) {
     const x = lights.positions[light * 3] ?? 0;
@@ -492,8 +525,10 @@ export function buildLightClusters(
     const radiusSq = radius * radius;
     for (let k = kLo; k <= kHi; k++) {
       /* The same two depths `clusterViewBounds` builds this slice's box from. */
-      const halfHNear = sliceNearDepth(k, near, far) * tanHalfFovY;
-      const halfHFar = sliceNearDepth(k + 1, near, far) * tanHalfFovY;
+      const zNear = sliceDepths[k] ?? 0;
+      const zFar = sliceDepths[k + 1] ?? 0;
+      const halfHNear = zNear * tanHalfFovY;
+      const halfHFar = zFar * tanHalfFovY;
       const halfWNear = halfHNear * aspect;
       const halfWFar = halfHFar * aspect;
       const iLo = tileOf(
@@ -514,17 +549,9 @@ export function buildLightClusters(
       );
       for (let j = jLo; j <= jHi; j++) {
         for (let i = iLo; i <= iHi; i++) {
-          clusterViewBounds(i, j, k, near, far, tanHalfFovY, aspect, bounds);
+          sliceBounds(i, j, zNear, zFar, halfWNear, halfWFar, halfHNear, halfHFar, bounds);
           if (distanceSqToBounds(vx, vy, depth, bounds) > radiusSq) continue;
-          insert(
-            table,
-            i + j * CLUSTER_X + k * CLUSTER_X * CLUSTER_Y,
-            light,
-            near,
-            far,
-            tanHalfFovY,
-            aspect,
-          );
+          insert(table, i + j * CLUSTER_X + k * CLUSTER_X * CLUSTER_Y, light, bounds);
         }
       }
     }
@@ -539,47 +566,45 @@ function tileOf(ndc: number, tiles: number): number {
 }
 
 /**
- * Put a light into a cluster, applying the overflow rule.
+ * Each member's squared distance from its cluster's centre, slot for slot with the table, for the
+ * frame being binned. Allocated on the first binning, so a consumer that never clusters pays nothing.
+ *
+ * **Measured rather than assumed rare.** The overflow rule used to recompute the cluster's box and
+ * all sixteen members' distances on every insert into a full cluster, on the argument that full
+ * clusters are rare. Three hundred candles within a few metres of the camera fill 2,152 of the
+ * 3,456, and the binning spent 47 ms a frame there. Each distance is the same number whenever it is
+ * computed, so it is computed once, at the insert that placed the member.
+ */
+let memberDistance: Float64Array | null = null;
+
+/**
+ * Put a light into a cluster, applying the overflow rule. `box` is the cluster's bounds, which the
+ * caller has just tested the light against.
  *
  * Lights arrive in increasing index, so the common path appends and the list is already sorted.
  * The sort only runs on the rare path where a replacement broke that order.
  */
-function insert(
-  table: Uint32Array,
-  cluster: number,
-  light: number,
-  near: number,
-  far: number,
-  tanHalfFovY: number,
-  aspect: number,
-): void {
+function insert(table: Uint32Array, cluster: number, light: number, box: Float32Array): void {
   const base = clusterBase(cluster);
   const count = table[base] ?? 0;
+  const distances = (memberDistance ??= new Float64Array(CLUSTER_COUNT * MAX_LIGHTS_PER_CLUSTER));
+  const at = cluster * MAX_LIGHTS_PER_CLUSTER;
+  const cx = ((box[0] ?? 0) + (box[3] ?? 0)) * 0.5;
+  const cy = ((box[1] ?? 0) + (box[4] ?? 0)) * 0.5;
+  const cz = ((box[2] ?? 0) + (box[5] ?? 0)) * 0.5;
+  const mine = centreDistanceSq(light, cx, cy, cz);
   if (count < MAX_LIGHTS_PER_CLUSTER) {
     table[base + 4 + count] = light;
+    distances[at + count] = mine;
     table[base] = count + 1;
     return;
   }
 
-  /*
-   * Full. Drop the farthest member if this one is nearer, measured from the cluster's own centre.
-   * Rare enough that recomputing the members' distances beats carrying 96,768 floats of scratch
-   * for a case most frames never reach.
-   */
-  const k = Math.floor(cluster / (CLUSTER_X * CLUSTER_Y));
-  const j = Math.floor((cluster - k * CLUSTER_X * CLUSTER_Y) / CLUSTER_X);
-  const i = cluster - k * CLUSTER_X * CLUSTER_Y - j * CLUSTER_X;
-  clusterViewBounds(i, j, k, near, far, tanHalfFovY, aspect, bounds);
-  const cx = ((bounds[0] ?? 0) + (bounds[3] ?? 0)) * 0.5;
-  const cy = ((bounds[1] ?? 0) + (bounds[4] ?? 0)) * 0.5;
-  const cz = ((bounds[2] ?? 0) + (bounds[5] ?? 0)) * 0.5;
-
-  const mine = centreDistanceSq(light, cx, cy, cz);
+  /* Full. Drop the farthest member if this one is nearer, measured from the cluster's own centre. */
   let worstSlot = -1;
   let worst = mine;
   for (let n = 0; n < MAX_LIGHTS_PER_CLUSTER; n++) {
-    const held = table[base + 4 + n] ?? 0;
-    const d = centreDistanceSq(held, cx, cy, cz);
+    const d = distances[at + n] ?? 0;
     if (d > worst) {
       worst = d;
       worstSlot = n;
@@ -587,7 +612,27 @@ function insert(
   }
   if (worstSlot < 0) return;
   table[base + 4 + worstSlot] = light;
-  sortIndices(table, base, MAX_LIGHTS_PER_CLUSTER);
+  distances[at + worstSlot] = mine;
+  sortMembers(table, base, distances, at);
+}
+
+/**
+ * Sort a full cluster's index slots ascending, carrying each member's distance with it. An insertion
+ * sort: sixteen integers, so this is not a hot loop.
+ */
+function sortMembers(table: Uint32Array, base: number, distances: Float64Array, at: number): void {
+  for (let n = 1; n < MAX_LIGHTS_PER_CLUSTER; n++) {
+    const value = table[base + 4 + n] ?? 0;
+    const distance = distances[at + n] ?? 0;
+    let m = n - 1;
+    while (m >= 0 && (table[base + 4 + m] ?? 0) > value) {
+      table[base + 4 + m + 1] = table[base + 4 + m] ?? 0;
+      distances[at + m + 1] = distances[at + m] ?? 0;
+      m--;
+    }
+    table[base + 4 + m + 1] = value;
+    distances[at + m + 1] = distance;
+  }
 }
 
 function centreDistanceSq(light: number, cx: number, cy: number, cz: number): number {

package/src/render/cutoutCaster.ts

@@ -0,0 +1,44 @@
+/**
+ * Which shadow casters cut their shadow out of their texture's alpha, decided once for both backends.
+ *
+ * **A caster with an albedo and a cutoff above zero is a cutout**: a leaf card, a chain link, a
+ * fence, whose shape is in its alpha and not in its geometry. The same test the colour pass makes
+ * when it discards, so a surface that is a hole in the picture is a hole in its shadow. Written once,
+ * here, because two backends deciding it separately is how they come to disagree about a leaf
+ * (AGENTS.md, 2026-08-13).
+ *
+ * Called per draw, so the answer is written into one object and returned again: a draw allocates
+ * nothing. What that gives up is holding two answers at once, which no caller does; the depth pass
+ * reads it and binds before it asks again.
+ */
+import type { SurfaceMaterial } from './surfaceTexture.ts';
+
+/** A cutout caster's texture, its cutoff and its UV scale. */
+export interface CutoutCaster<Texture> {
+  readonly albedo: Texture;
+  readonly cutoff: number;
+  readonly u: number;
+  readonly v: number;
+}
+
+const answer: { albedo: unknown; cutoff: number; u: number; v: number } = {
+  albedo: null,
+  cutoff: 0,
+  u: 1,
+  v: 1,
+};
+
+/** The cutout `material` casts, or null for an ordinary caster. */
+export function cutoutOf<Texture>(
+  material: SurfaceMaterial<Texture> | null | undefined,
+): CutoutCaster<Texture> | null {
+  if (material === null || material === undefined) return null;
+  const albedo = material.albedo ?? null;
+  const cutoff = material.cutout ?? 0;
+  if (albedo === null || !(cutoff > 0)) return null;
+  answer.albedo = albedo;
+  answer.cutoff = cutoff;
+  answer.u = material.uScale ?? 1;
+  answer.v = material.vScale ?? 1;
+  return answer as CutoutCaster<Texture>;
+}

package/src/render/driftLight/bake.ts

@@ -0,0 +1,125 @@
+/**
+ * One brick of DriftLight's volume: at every sample, the light that arrives from every light that
+ * reaches it, and the direction it mostly arrives from.
+ *
+ * **Two texels a sample.** The first is the summed colour, and in its fourth channel whether the
+ * sample is a sample at all: one standing inside solid geometry is not, and its zero lets the
+ * shader's filtered lookup leave it out rather than blend darkness into the wall beside it. The
+ * second is the arrival direction, weighted by each light's brightness, so it points at a lone light
+ * with a length of one and shrinks towards zero as lights surround the sample from all sides. The
+ * shader turns the pair back into the light on a surface of any facing: exactly Lambert for a single
+ * light, a quarter of the sum, the mean of a clamped cosine, for light from everywhere.
+ *
+ * **What it gives up is the specular.** Two numbers of direction cannot say where a highlight
+ * falls, which is why the exact lights near the camera are shaded exactly and this stands in only
+ * past them, where a highlight from a candle is a fraction of a pixel.
+ */
+
+import type { PointLightFalloff } from './falloff.ts';
+import { pointLightShape } from './falloff.ts';
+import type { LightFieldLayout, LightReach } from './layout.ts';
+import { BRICK_SAMPLES } from './layout.ts';
+import type { DistanceAt } from './visibility.ts';
+import { softVisibility } from './visibility.ts';
+
+/** Samples in a brick, and so texels in each of its two blocks. */
+export const BRICK_TEXELS = BRICK_SAMPLES * BRICK_SAMPLES * BRICK_SAMPLES;
+
+/** What the bake reads of a light, which a `PointLightSource` already carries. */
+export interface FieldLight extends LightReach {
+  readonly r: number;
+  readonly g: number;
+  readonly b: number;
+  /** The emitter's physical radius, which widens its penumbra. */
+  readonly sourceRadius: number;
+}
+
+/**
+ * Fill `light` and `direction`, `BRICK_TEXELS * 4` floats each, x fastest, for brick `brick`.
+ * `distance` is the scene's distance field, or null for no occlusion.
+ */
+export function bakeBrick(
+  layout: LightFieldLayout,
+  brick: number,
+  lights: readonly FieldLight[],
+  falloff: PointLightFalloff,
+  distance: DistanceAt | null,
+  light: Float32Array,
+  direction: Float32Array,
+): void {
+  const { spacing, span, origin } = layout;
+  const bx = origin[0] + (layout.brickCoords[brick * 3] as number) * span;
+  const by = origin[1] + (layout.brickCoords[brick * 3 + 1] as number) * span;
+  const bz = origin[2] + (layout.brickCoords[brick * 3 + 2] as number) * span;
+  const first = layout.lightStart[brick] as number;
+  const last = layout.lightStart[brick + 1] as number;
+
+  for (let k = 0; k < BRICK_SAMPLES; k++) {
+    for (let j = 0; j < BRICK_SAMPLES; j++) {
+      for (let i = 0; i < BRICK_SAMPLES; i++) {
+        const texel = (i + BRICK_SAMPLES * (j + BRICK_SAMPLES * k)) * 4;
+        const px = bx + i * spacing;
+        const py = by + j * spacing;
+        const pz = bz + k * spacing;
+        light.fill(0, texel, texel + 4);
+        direction.fill(0, texel, texel + 4);
+        if (distance !== null && distance(px, py, pz) < 0) continue;
+
+        let r = 0;
+        let g = 0;
+        let b = 0;
+        let towardX = 0;
+        let towardY = 0;
+        let towardZ = 0;
+        let weight = 0;
+        for (let listed = first; listed < last; listed++) {
+          const source = lights[layout.lights[listed] as number];
+          if (source === undefined) continue;
+          const dx = source.x - px;
+          const dy = source.y - py;
+          const dz = source.z - pz;
+          const dist = Math.hypot(dx, dy, dz);
+          if (dist >= source.radius) continue;
+          const shape = pointLightShape(dist, source.radius, falloff);
+          if (shape <= 0) continue;
+          const seen =
+            distance === null
+              ? 1
+              : softVisibility(
+                  distance,
+                  px,
+                  py,
+                  pz,
+                  source.x,
+                  source.y,
+                  source.z,
+                  source.sourceRadius,
+                );
+          if (seen <= 0) continue;
+          const lr = source.r * shape * seen;
+          const lg = source.g * shape * seen;
+          const lb = source.b * shape * seen;
+          r += lr;
+          g += lg;
+          b += lb;
+          const bright = 0.2126 * lr + 0.7152 * lg + 0.0722 * lb;
+          if (dist > 1e-6 && bright > 0) {
+            towardX += (bright * dx) / dist;
+            towardY += (bright * dy) / dist;
+            towardZ += (bright * dz) / dist;
+            weight += bright;
+          }
+        }
+        light[texel] = r;
+        light[texel + 1] = g;
+        light[texel + 2] = b;
+        light[texel + 3] = 1;
+        if (weight > 0) {
+          direction[texel] = towardX / weight;
+          direction[texel + 1] = towardY / weight;
+          direction[texel + 2] = towardZ / weight;
+        }
+      }
+    }
+  }
+}

package/src/render/driftLight/falloff.ts

@@ -0,0 +1,26 @@
+/**
+ * How a point light's brightness falls with distance, as the lit shader draws it, for the light
+ * DriftLight sums into its volume.
+ *
+ * **One formula in two languages, tied by a test.** The frame shades a light in GLSL; the volume is
+ * summed in TypeScript. If they disagree the summed light and the exact light differ where they
+ * crossfade, and a seam follows the camera across every surface. `falloff.test.ts` reads the
+ * shader's lines and asserts these numbers against them.
+ *
+ * Both of the renderer's falloffs: `smooth`, the default, is a linear ramp squared, reaching zero at
+ * the radius; `inverseSquare` is physical, windowed so it still reaches zero at the radius, and
+ * floored at ten centimetres so a surface touching a light is not infinitely bright.
+ */
+
+export type PointLightFalloff = 'smooth' | 'inverseSquare';
+
+/** The shader's `shape` for an unshaped point light: no cone, no photometric profile. */
+export function pointLightShape(dist: number, radius: number, falloff: PointLightFalloff): number {
+  if (falloff === 'inverseSquare') {
+    const ratio = dist / Math.max(radius, 1e-4);
+    const window = Math.min(1, Math.max(0, 1 - ratio ** 4));
+    return (window * window) / Math.max(dist * dist, 0.01);
+  }
+  const linear = Math.min(1, Math.max(0, 1 - dist / radius));
+  return linear * linear;
+}