@driftengine/core 4.3.0 → 4.4.0

package/src/render/pointLightSelection.ts

@@ -46,6 +46,81 @@ const CONTENTION_BAND_M = 3;
 /** Sort keys for the shadow list, which is ordered independently of the shaded one. */
 const shadowRank = new Float32Array(POINT_SHADOW_POOL);
 
+/**
+ * Every light in range this frame, by source index and squared distance, before the nearest are
+ * chosen. Grown when a world offers more than it has held, and never shrunk, so a frame allocates
+ * only when the world has grown. Float64, so two lights a hair apart are ordered by their real
+ * distances rather than by what survives a float's rounding.
+ */
+let candidateIndex = new Int32Array(64);
+let candidateDistance = new Float64Array(64);
+
+function growCandidates(needed: number): void {
+  if (needed <= candidateIndex.length) return;
+  const size = Math.max(needed, candidateIndex.length * 2);
+  const index = new Int32Array(size);
+  const distance = new Float64Array(size);
+  index.set(candidateIndex);
+  distance.set(candidateDistance);
+  candidateIndex = index;
+  candidateDistance = distance;
+}
+
+/** Whether candidate `a` goes before candidate `b`: nearer, or as near and offered first. */
+function before(a: number, b: number): boolean {
+  const da = candidateDistance[a] ?? 0;
+  const db = candidateDistance[b] ?? 0;
+  return da < db || (da === db && (candidateIndex[a] ?? 0) < (candidateIndex[b] ?? 0));
+}
+
+function swap(a: number, b: number): void {
+  const index = candidateIndex[a] ?? 0;
+  const distance = candidateDistance[a] ?? 0;
+  candidateIndex[a] = candidateIndex[b] ?? 0;
+  candidateDistance[a] = candidateDistance[b] ?? 0;
+  candidateIndex[b] = index;
+  candidateDistance[b] = distance;
+}
+
+/**
+ * Move the `keep` nearest of the first `count` candidates into `[0, keep)`, in no order: a
+ * quickselect, linear on average. The pivot is the median of three, which keeps a list that
+ * arrives already sorted — a world laid out along the camera's path — away from the quadratic case.
+ */
+function chooseNearest(count: number, keep: number): void {
+  let lo = 0;
+  let hi = count - 1;
+  while (lo < hi) {
+    const mid = (lo + hi) >> 1;
+    if (before(mid, lo)) swap(mid, lo);
+    if (before(hi, lo)) swap(hi, lo);
+    if (before(hi, mid)) swap(hi, mid);
+    swap(mid, hi);
+    let store = lo;
+    for (let at = lo; at < hi; at++) {
+      if (before(at, hi)) {
+        swap(at, store);
+        store++;
+      }
+    }
+    swap(store, hi);
+    if (store === keep || store === keep - 1) return;
+    if (store < keep) lo = store + 1;
+    else hi = store - 1;
+  }
+}
+
+/** Sort the first `count` candidates nearest first. An insertion sort: `count` is a slot budget. */
+function sortCandidates(count: number): void {
+  for (let at = 1; at < count; at++) {
+    let back = at;
+    while (back > 0 && before(back, back - 1)) {
+      swap(back, back - 1);
+      back--;
+    }
+  }
+}
+
 export interface PointLightSource {
   x: number;
   y: number;
@@ -105,6 +180,15 @@ export interface PointLightSource {
    * They are floor lighting 35 cm off the deck and were never meant to cast at all.
    */
   castsShadow?: boolean;
+  /**
+   * Whether a DriftLight field also sums this light (`createLightField` sets it).
+   *
+   * Then the lit shader shades it exactly only where the choice is complete and lets the field's
+   * summed light take over past it, so the light is never counted twice. Carried to the shader as
+   * the sign of the light's weight, which both light paths already have: no new storage on a part
+   * whose uniform budget has none to spare.
+   */
+  inLightField?: boolean;
 }
 
 export interface PointLightBuffer {
@@ -179,6 +263,13 @@ export interface PointLightBuffer {
    */
   readonly shadowIndex: Int32Array;
   shadowCount: number;
+  /**
+   * How far from the selection's centre the choice is complete for DriftLight field lights: a
+   * point nearer than this is reached only by field lights chosen at full strength. A field light
+   * left out at distance d reaching r first reaches d - r; one dimmed at the cut counts as left
+   * out. At most the view range, past which nothing is chosen.
+   */
+  complete: number;
 }
 
 /**
@@ -213,6 +304,7 @@ export function createPointLightBuffer(capacity: number = MAX_POINT_LIGHTS): Poi
     scratchDistance: new Float32Array(Math.max(shaded, POINT_SHADOW_POOL)),
     shadowIndex: new Int32Array(POINT_SHADOW_POOL),
     shadowCount: 0,
+    complete: 0,
   };
 }
 
@@ -268,6 +360,7 @@ export function selectPointLights(
    * shader binds, which is the case where nothing is contested and nothing dims.
    */
   let cutSq = Infinity;
+  let candidateCount = 0;
 
   for (let sourceIndex = 0; sourceIndex < sources.length; sourceIndex++) {
     const light = sources[sourceIndex];
@@ -305,84 +398,14 @@ export function selectPointLights(
      *
      * Sharing one sorted list is what made them drift apart, so they do not share one.
      */
-    let slot = out.count;
-    while (slot > 0 && (out.scratchDistance[slot - 1] ?? 0) > distanceSq) slot--;
-    if (slot >= shadedCapacity) {
-      // Rejected outright, so it is a candidate for the boundary the set fades against.
-      if (distanceSq < cutSq) cutSq = distanceSq;
-    } else {
-      // Full, so making room drops whoever was last off the end — and that is the
-      // nearest light not in the set unless something nearer is rejected later.
-      if (out.count >= shadedCapacity) {
-        const displaced = out.scratchDistance[shadedCapacity - 1] ?? Infinity;
-        if (displaced < cutSq) cutSq = displaced;
-      }
-      const last = Math.min(out.count, shadedCapacity - 1);
-      for (let index = last; index > slot; index--) {
-        out.scratchDistance[index] = out.scratchDistance[index - 1] ?? 0;
-        out.radii[index] = out.radii[index - 1] ?? 0;
-        out.sourceRadii[index] = out.sourceRadii[index - 1] ?? 0;
-        out.sourceIndex[index] = out.sourceIndex[index - 1] ?? -1;
-        for (let component = 0; component < 3; component++) {
-          out.positions[index * 3 + component] = out.positions[(index - 1) * 3 + component] ?? 0;
-          out.colors[index * 3 + component] = out.colors[(index - 1) * 3 + component] ?? 0;
-          out.directions[index * 3 + component] = out.directions[(index - 1) * 3 + component] ?? 0;
-        }
-        out.coneCos[index * 2] = out.coneCos[(index - 1) * 2] ?? 0;
-        out.coneCos[index * 2 + 1] = out.coneCos[(index - 1) * 2 + 1] ?? 0;
-        out.iesProfiles[index] = out.iesProfiles[index - 1] ?? -1;
-      }
-      out.scratchDistance[slot] = distanceSq;
-      out.sourceIndex[slot] = sourceIndex;
-      out.radii[slot] = light.radius;
-      out.sourceRadii[slot] = Math.max(light.sourceRadius, 0);
-      out.positions[slot * 3] = light.x;
-      out.positions[slot * 3 + 1] = light.y;
-      out.positions[slot * 3 + 2] = light.z;
-      const scale = flickerScale(light, timeSeconds);
-      out.colors[slot * 3] = light.r * scale;
-      out.colors[slot * 3 + 1] = light.g * scale;
-      out.colors[slot * 3 + 2] = light.b * scale;
-
-      /*
-       * **Normalised here rather than trusted**, because the cone is a comparison against a cosine
-       * and an un-normalised direction scales that cosine — so a vector of length 2 gives a cone of
-       * the wrong width, which reads as the angle having been set wrong rather than the vector.
-       * A zero-length direction is a light that declared no cone, and it takes the open pair.
-       */
-      const dx = light.dirX ?? 0;
-      const dy = light.dirY ?? 0;
-      const dz = light.dirZ ?? 0;
-      const length = Math.sqrt(dx * dx + dy * dy + dz * dz);
-      const aimed = length > 1e-6 && light.coneOuterDeg !== undefined;
-      const inverse = aimed ? 1 / length : 0;
-      out.directions[slot * 3] = dx * inverse;
-      out.directions[slot * 3 + 1] = dy * inverse;
-      out.directions[slot * 3 + 2] = dz * inverse;
-      if (aimed) {
-        /*
-         * Clamped so the inner edge never passes the outer. A caller that swaps them would
-         * otherwise get `smoothstep` with its edges inverted, which is a cone that is dark in the
-         * middle and bright at the rim — a picture nobody would attribute to two numbers being the
-         * wrong way round.
-         */
-        const outerDeg = Math.min(89.9, Math.max(0, light.coneOuterDeg ?? 45));
-        const innerDeg = Math.min(outerDeg, Math.max(0, light.coneInnerDeg ?? outerDeg * 0.75));
-        out.coneCos[slot * 2] = Math.cos((innerDeg * Math.PI) / 180);
-        out.coneCos[slot * 2 + 1] = Math.cos((outerDeg * Math.PI) / 180);
-      } else {
-        out.coneCos[slot * 2] = POINT_LIGHT_COS_INNER;
-        out.coneCos[slot * 2 + 1] = POINT_LIGHT_COS_OUTER;
-      }
-      /*
-       * The profile applies to a point light as readily as to a spot: a bare bulb has a measured
-       * distribution too, and the arithmetic does not care whether a cone is also being applied.
-       * Restricting it to spots would be a smaller feature for no saving.
-       */
-      out.iesProfiles[slot] = light.iesProfile ?? -1;
-
-      if (out.count < shadedCapacity) out.count++;
-    }
+    /*
+     * A candidate for the shaded list. Which of them win is decided once every source has been
+     * seen, below, rather than by keeping a sorted list as they arrive: see `chooseNearest`.
+     */
+    growCandidates(candidateCount + 1);
+    candidateIndex[candidateCount] = sourceIndex;
+    candidateDistance[candidateCount] = distanceSq;
+    candidateCount++;
 
     /*
      * Inside its own radius, so it is lighting something and therefore has something
@@ -420,6 +443,85 @@ export function selectPointLights(
     if (out.shadowCount < POINT_SHADOW_POOL) out.shadowCount++;
   }
 
+  /*
+   * The nearest `shadedCapacity` candidates, nearest first, and the nearest one left out.
+   *
+   * **Partitioned, then only the winners sorted.** This kept a sorted list as the sources arrived,
+   * shifting fourteen fields a slot to make room, which is O(sources × slots): 3.2 ms a frame to
+   * choose 320 of a courtyard's 10,000 candles, most of it moving lights that were then displaced.
+   * A quickselect finds the winners in time linear in the sources and the sort touches only them,
+   * and each winner is packed once. Ties go to the earlier source, as they did.
+   */
+  const chosen = Math.min(candidateCount, shadedCapacity);
+  let complete = viewRange;
+  if (candidateCount > shadedCapacity) {
+    chooseNearest(candidateCount, shadedCapacity);
+    for (let at = shadedCapacity; at < candidateCount; at++) {
+      const distanceSq = candidateDistance[at] ?? Infinity;
+      if (distanceSq < cutSq) cutSq = distanceSq;
+      const left = sources[candidateIndex[at] ?? 0];
+      if (left?.inLightField === true) {
+        complete = Math.min(complete, Math.sqrt(distanceSq) - left.radius);
+      }
+    }
+  }
+  sortCandidates(chosen);
+  for (let slot = 0; slot < chosen; slot++) {
+    const sourceIndex = candidateIndex[slot] ?? 0;
+    const light = sources[sourceIndex];
+    if (light === undefined) continue;
+    const distanceSq = candidateDistance[slot] ?? 0;
+    out.scratchDistance[slot] = distanceSq;
+    out.sourceIndex[slot] = sourceIndex;
+    out.radii[slot] = light.radius;
+    out.sourceRadii[slot] = Math.max(light.sourceRadius, 0);
+    out.positions[slot * 3] = light.x;
+    out.positions[slot * 3 + 1] = light.y;
+    out.positions[slot * 3 + 2] = light.z;
+    const scale = flickerScale(light, timeSeconds);
+    out.colors[slot * 3] = light.r * scale;
+    out.colors[slot * 3 + 1] = light.g * scale;
+    out.colors[slot * 3 + 2] = light.b * scale;
+
+    /*
+     * **Normalised here rather than trusted**, because the cone is a comparison against a cosine
+     * and an un-normalised direction scales that cosine — so a vector of length 2 gives a cone of
+     * the wrong width, which reads as the angle having been set wrong rather than the vector.
+     * A zero-length direction is a light that declared no cone, and it takes the open pair.
+     */
+    const dx = light.dirX ?? 0;
+    const dy = light.dirY ?? 0;
+    const dz = light.dirZ ?? 0;
+    const length = Math.sqrt(dx * dx + dy * dy + dz * dz);
+    const aimed = length > 1e-6 && light.coneOuterDeg !== undefined;
+    const inverse = aimed ? 1 / length : 0;
+    out.directions[slot * 3] = dx * inverse;
+    out.directions[slot * 3 + 1] = dy * inverse;
+    out.directions[slot * 3 + 2] = dz * inverse;
+    if (aimed) {
+      /*
+       * Clamped so the inner edge never passes the outer. A caller that swaps them would
+       * otherwise get `smoothstep` with its edges inverted, which is a cone that is dark in the
+       * middle and bright at the rim — a picture nobody would attribute to two numbers being the
+       * wrong way round.
+       */
+      const outerDeg = Math.min(89.9, Math.max(0, light.coneOuterDeg ?? 45));
+      const innerDeg = Math.min(outerDeg, Math.max(0, light.coneInnerDeg ?? outerDeg * 0.75));
+      out.coneCos[slot * 2] = Math.cos((innerDeg * Math.PI) / 180);
+      out.coneCos[slot * 2 + 1] = Math.cos((outerDeg * Math.PI) / 180);
+    } else {
+      out.coneCos[slot * 2] = POINT_LIGHT_COS_INNER;
+      out.coneCos[slot * 2 + 1] = POINT_LIGHT_COS_OUTER;
+    }
+    /*
+     * The profile applies to a point light as readily as to a spot: a bare bulb has a measured
+     * distribution too, and the arithmetic does not care whether a cone is also being applied.
+     * Restricting it to spots would be a smaller feature for no saving.
+     */
+    out.iesProfiles[slot] = light.iesProfile ?? -1;
+  }
+  out.count = chosen;
+
   /*
    * How present each of them is, now that the set — and with it the boundary — is
    * known. A second pass over at most eight entries, which is why the cut can be a
@@ -434,8 +536,18 @@ export function selectPointLights(
     const cullDistance = viewRange + (out.radii[index] ?? 0);
     const arriving = (cullDistance - distance) / FADE_BAND_M;
     const contested = (cut - distance) / CONTENTION_BAND_M;
-    out.weights[index] = Math.max(0, Math.min(1, arriving, contested));
+    const field = sources[out.sourceIndex[index] ?? 0]?.inLightField === true;
+    /*
+     * **A field light does not fade in at the edge of the view range**, because the field is what
+     * stands in for it past the choice: the fade exists so a light does not switch on in front of
+     * the player, and a light the field sums was never off. Kept, it dimmed every light across a
+     * short range, and a dimmed light is an incomplete one, so the field took over at the camera.
+     */
+    const weight = Math.max(0, Math.min(1, field ? contested : Math.min(arriving, contested)));
+    out.weights[index] = field ? -weight : weight;
+    if (field && weight < 1) complete = Math.min(complete, distance - (out.radii[index] ?? 0));
   }
+  out.complete = Math.max(0, complete);
 }
 
 function flickerScale(light: PointLightSource, timeSeconds: number): number {

package/src/render/probeGrid.ts

@@ -34,6 +34,14 @@ export interface ProbeGridOptions {
    * convolution and the shader instead of a grid path and a legacy path that drift.
    */
   readonly counts: Vec3;
+  /**
+   * Blend each sweep of bakes into the next rather than showing each probe's bake the moment it
+   * lands. For a grid re-baked a probe a frame under a moving light, where each probe otherwise
+   * jumps once a sweep and the jumps travel across the scene as a pass of light. Costs three times
+   * the layers and a sweep of lag; ignored where indirect light is traced, which writes the grid's
+   * layers itself. See `probeSweeps.ts`. Off by default.
+   */
+  readonly crossfade?: boolean;
 }
 
 /**
@@ -97,15 +105,17 @@ export function sameGrid(a: ProbeGrid, b: ProbeGrid): boolean {
     if (a.origin[axis] !== b.origin[axis]) return false;
     if (a.spacing[axis] !== b.spacing[axis]) return false;
   }
-  return true;
+  return a.crossfade === b.crossfade;
 }
 
 export class ProbeGrid {
   readonly origin: Vec3;
   readonly spacing: Vec3;
   readonly counts: Vec3;
-  /** Probes in total, which is also the array's layer count. */
+  /** Probes in total: the array's layer count, or a third of it for a crossfading grid. */
   readonly layers: number;
+  /** Whether sweeps blend into one another. See `ProbeGridOptions.crossfade`. */
+  readonly crossfade: boolean;
   /** The reciprocal of the spacing, because the shader multiplies and so does everything here. */
   readonly invSpacing: Vec3;
 
@@ -149,6 +159,7 @@ export class ProbeGrid {
     this.invSpacing = [1 / this.spacing[0], 1 / this.spacing[1], 1 / this.spacing[2]];
     this.counts = counts;
     this.layers = layers;
+    this.crossfade = options.crossfade === true;
   }
 
   /**

package/src/render/probeSweeps.ts

@@ -0,0 +1,80 @@
+/**
+ * A probe grid's sweeps: which layer a bake writes, when a sweep is whole, and how far the shading
+ * has moved from the last whole sweep toward the newest.
+ *
+ * **A grid re-baked a probe a frame changes in steps.** Each probe holds the light of the moment it
+ * was baked until its turn comes round again, a sweep later, and then jumps to the light of that
+ * moment. Under a moving sun the jump is a pass of light across the scene once a sweep: reported as
+ * "a pass every second or two", which at sixty-four probes a frame at 60 Hz is exactly one sweep.
+ *
+ * **So a crossfading grid keeps three sets of layers**: the last whole sweep, the newest whole
+ * sweep, and the one being baked. The shading blends the first toward the second by how much of the
+ * third has been baked, so it reaches the newest sweep at the moment the next one is whole, and the
+ * light moves a sixty-fourth of a sweep a frame rather than a probe's worth at once. The set being
+ * written is never one the shading reads.
+ *
+ * What it gives up is three times the layers, and a sweep of lag: the light shown is a blend of what
+ * the grid saw one and two sweeps ago. What would make it wrong is a light that must follow a change
+ * faster than a sweep, which a burst of bakes serves, since the blend follows the bakes rather than
+ * the clock. A grid that does not crossfade is one set, ready once every probe is baked, as before.
+ *
+ * Backend-neutral, per the rule that a decision lives in one place and only the binding is per
+ * backend: both renderers ask this where to write and what to upload.
+ */
+export class ProbeSweeps {
+  /** Sets of layers the array holds: three for a crossfading grid, one otherwise. */
+  readonly sets: 1 | 3;
+  private readonly layers: number;
+  /** Which probes the sweep being baked has reached, and how many. */
+  private readonly reached: Uint8Array;
+  private reachedCount = 0;
+  private from = 0;
+  private to = 0;
+  private write = 0;
+  /** Whether a whole sweep has been rotated in. */
+  private whole = false;
+
+  constructor(layers: number, crossfade: boolean) {
+    this.layers = Math.max(1, Math.trunc(layers));
+    this.sets = crossfade ? 3 : 1;
+    this.reached = new Uint8Array(this.layers);
+  }
+
+  /** The array layer a bake of probe `layer` writes. */
+  writeLayer(layer: number): number {
+    return this.write * this.layers + layer;
+  }
+
+  /** Record that probe `layer` was baked into the set being written; a whole sweep rotates. */
+  baked(layer: number): void {
+    if (layer < 0 || layer >= this.layers || this.reached[layer] === 1) return;
+    this.reached[layer] = 1;
+    this.reachedCount++;
+    if (this.reachedCount < this.layers) return;
+    this.reached.fill(0);
+    this.reachedCount = 0;
+    if (this.sets === 1) {
+      this.whole = true;
+      return;
+    }
+    /* The newest is shown from now on; the first whole sweep is shown alone, blending into itself. */
+    this.from = this.whole ? this.to : this.write;
+    this.to = this.write;
+    this.whole = true;
+    /* The set neither end of the blend holds. */
+    this.write = this.from === this.to ? (this.to + 1) % 3 : 3 - this.from - this.to;
+  }
+
+  /** Whether the shading may read the grid: once a sweep is whole. */
+  get ready(): boolean {
+    return this.whole;
+  }
+
+  /** The layer offsets of the two sets shown and the blend between them, into `out`. */
+  uniforms(out: Float32Array): Float32Array {
+    out[0] = this.from * this.layers;
+    out[1] = this.to * this.layers;
+    out[2] = this.sets === 1 ? 0 : this.reachedCount / this.layers;
+    return out;
+  }
+}

package/src/render/reflectionProbe.ts

@@ -70,6 +70,52 @@ export interface ProbeBakeOptions {
    * nothing gets the frame it already had.
    */
   readonly irradiance?: boolean;
+  /**
+   * Whether what the probe sees is lit by the grid's last bake, so each bake adds a bounce.
+   *
+   * Defaults to **false**, which is what every bake did before this existed. Then everything a
+   * probe sees is lit by the sun and by the hemispheric ambient, so the grid holds one bounce. An
+   * enclosed space is mostly lit at the second bounce and later. A courtyard's arcades are the
+   * case this was built for: one bounce came out about two stops under a reference render.
+   *
+   * With it on, the surfaces in each face take their ambient from the grid instead. Round-robin
+   * baking then converges on the space's full interreflection, about a bounce each time the grid
+   * is swept, and a scene holding one moment bakes the grid two or three times. It costs no pass
+   * and no memory. The faces are drawn into their own cube and only the resolve writes the array,
+   * so the array is never read and written in one pass.
+   *
+   * **Nothing changes until every probe has been baked once**, because until then the grid is not
+   * readable; the first sweep lights by the ambient as before. What it gives up: light that leaks
+   * through a wall into a probe is bounced again, so a leak grows with each sweep. What would make
+   * it wrong is a space with near-white walls, where a sweep adds almost as much as the last and
+   * convergence takes many sweeps.
+   */
+  readonly bounce?: boolean;
+  /**
+   * Which of the six faces this call draws, as `[first, count]`: all six when absent.
+   *
+   * **A bake is six draws of the scene, and a scene of millions of triangles makes it the most
+   * expensive thing in a frame.** Measured on a bought courtyard of eleven million: 6.4 ms of a
+   * 14 ms frame, on the frames it ran, which is a frame rate no display can hold steady. Spread over
+   * calls, each draws only its faces into the capture, and the convolution into the layer, which
+   * reads all six, runs when the sixth is drawn. Faces in the order a cube numbers them,
+   * `+X, -X, +Y, -Y, +Z, -Z`.
+   *
+   * **The caller finishes one probe before starting the next**, because the capture the faces are
+   * drawn into is one for the whole grid: faces of two probes interleaved make a cube of neither.
+   * What it gives up is a probe whose faces were drawn a few frames apart, under a light that moved
+   * a little between them.
+   */
+  readonly faces?: readonly [first: number, count: number];
+}
+
+/** The faces a bake draws, `[first, end)`, from `ProbeBakeOptions.faces`. All six when absent. */
+export function probeFaceRange(options: ProbeBakeOptions | undefined): [number, number] {
+  const asked = options?.faces;
+  if (asked === undefined) return [0, 6];
+  const first = Math.min(Math.max(Math.trunc(asked[0]), 0), 5);
+  const count = Math.max(Math.trunc(asked[1]), 1);
+  return [first, Math.min(first + count, 6)];
 }
 
 /**
@@ -407,12 +453,17 @@ export class ReflectionProbe {
    * Returns whether the bake happened. A false means the allocation was refused and the caller
    * should carry on without a probe, which is a picture with a gradient in its paint rather
    * than a room.
+   *
+   * `first` and `end` draw only those faces, and the chain the roughness reads is built when the
+   * sixth is drawn. See `ProbeBakeOptions.faces`.
    */
   bake(
     gl: WebGL2RenderingContext,
     origin: Vec3,
     clearColor: Vec3,
     drawFace: (camera: Camera) => void,
+    first = 0,
+    end = FACES.length,
   ): boolean {
     if (this.unusable) return false;
 
@@ -429,7 +480,7 @@ export class ReflectionProbe {
     gl.framebufferRenderbuffer(gl.FRAMEBUFFER, gl.DEPTH_ATTACHMENT, gl.RENDERBUFFER, this.depth);
     gl.viewport(0, 0, this.size, this.size);
 
-    for (let face = 0; face < FACES.length; face++) {
+    for (let face = first; face < end; face++) {
       const aim = FACES[face];
       if (aim === undefined) continue;
       gl.framebufferTexture2D(
@@ -439,7 +490,7 @@ export class ReflectionProbe {
         this.texture,
         0,
       );
-      if (face === 0 && gl.checkFramebufferStatus(gl.FRAMEBUFFER) !== gl.FRAMEBUFFER_COMPLETE) {
+      if (face === first && gl.checkFramebufferStatus(gl.FRAMEBUFFER) !== gl.FRAMEBUFFER_COMPLETE) {
         this.unusable = true;
         gl.bindFramebuffer(gl.FRAMEBUFFER, null);
         console.warn(
@@ -464,6 +515,7 @@ export class ReflectionProbe {
     }
 
     gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+    if (end < FACES.length) return true;
     /* The blur the roughness reads. Once per bake, not once per frame. */
     gl.bindTexture(gl.TEXTURE_CUBE_MAP, this.texture);
     gl.generateMipmap(gl.TEXTURE_CUBE_MAP);

package/src/render/renderQuality.ts

@@ -560,7 +560,9 @@ export interface RenderQuality {
    */
   readonly reconstruction: number;
   /**
-   * Light a scene from what bounces, rather than from what was baked. **Off by default.**
+   * Light a scene from what bounces, rather than from what was baked: **DriftRay**, this engine's
+   * ray tracing, rays marched through the declared distance fields in GPU compute rather than on
+   * the dedicated ray-tracing units WebGPU does not expose. **Off by default.**
    *
    * On, the probe grid the shading already samples is filled by tracing `render/gi/`'s three-level
    * chain — the world distance field, and behind it the probes themselves, which is what makes the

package/src/render/rendererHarness.ts

@@ -49,9 +49,21 @@ export function recordingGl(
      * `Infinity` by default, so a link only ever fails where a test asked for it.
      */
     readonly refuseLinkAbove?: number;
+    /**
+     * Uniforms every program reports as active, each located by a handle carrying its name.
+     *
+     * **None by default**, which ends every reflection loop at once and leaves every upload aimed
+     * at `null`. A test about what a frame *uploads* names the uniform here and then finds the
+     * calls whose location says that name, rather than guessing at an upload's position in the
+     * recording.
+     */
+    readonly uniforms?: readonly string[];
   } = {},
 ) {
   const extensions = new Set(options.extensions ?? []);
+  const uniforms = options.uniforms ?? [];
+  /* What `clearDepth` last set, so a module that borrows the value can be seen to put it back. */
+  let depthClear = 1;
   const reportedVectors = options.fragmentUniformVectors ?? 1024;
   const enforcedVectors = options.refuseLinkAbove ?? Number.POSITIVE_INFINITY;
   /** Fragment sources by shader handle, so a refusal can be decided from what was compiled. */
@@ -71,6 +83,7 @@ export function recordingGl(
     MAX_TEXTURE_IMAGE_UNITS: 0x8872,
     MAX_VERTEX_UNIFORM_VECTORS: 0x8dfb,
     MAX_FRAGMENT_UNIFORM_VECTORS: 0x8dfd,
+    DEPTH_CLEAR_VALUE: 0x0b73,
     /*
      * Enums a test needs to compare against, rather than merely to pass through.
      *
@@ -126,6 +139,7 @@ export function recordingGl(
       if (pname === constants.MAX_SAMPLES) return 4;
       if (pname === constants.MAX_FRAGMENT_UNIFORM_VECTORS) return reportedVectors;
       if (pname === constants.MAX_VERTEX_UNIFORM_VECTORS) return 1024;
+      if (pname === constants.DEPTH_CLEAR_VALUE) return depthClear;
       /* Generous by default: every remaining limit is a ceiling something is checked against,
          and a small answer is read as a device that cannot do the thing. */
       return 4096;
@@ -156,16 +170,24 @@ export function recordingGl(
     /* Linked yes; zero active uniforms and attributes, which ends every reflection loop at once
        and is why this harness does not have to know a single uniform name. */
     getProgramParameter: (program: unknown, pname: unknown) => {
-      if (pname === constants.ACTIVE_UNIFORMS || pname === constants.ACTIVE_ATTRIBUTES) return 0;
+      if (pname === constants.ACTIVE_UNIFORMS) return uniforms.length;
+      if (pname === constants.ACTIVE_ATTRIBUTES) return 0;
       if (pname !== constants.LINK_STATUS) return true;
       if (!Number.isFinite(enforcedVectors)) return true;
       if (typeof program !== 'object' || program === null) return true;
       const source = programFragments.get(program);
       return source === undefined || countUniformVectors(source) <= enforcedVectors;
     },
-    getActiveUniform: () => ({ name: '', size: 1, type: 0 }),
+    getActiveUniform: (_program: unknown, index: unknown) => ({
+      name: uniforms[Number(index)] ?? '',
+      size: 1,
+      type: 0,
+    }),
     getActiveAttrib: () => ({ name: '', size: 1, type: 0 }),
-    getUniformLocation: () => ({}),
+    getUniformLocation: (_program: unknown, name: unknown) => ({ name }),
+    clearDepth: (value: unknown) => {
+      depthClear = Number(value);
+    },
     getAttribLocation: () => -1,
     checkFramebufferStatus: () => constants.FRAMEBUFFER_COMPLETE,
     getError: () => constants.NO_ERROR,