@driftengine/core 4.3.0 → 4.4.1

package/src/render/exposurePass.ts

@@ -0,0 +1,186 @@
+import {
+  EXPOSURE_ADAPT_FRAG,
+  EXPOSURE_METER_FRAG,
+  METER_GRID,
+  adaptBlend,
+} from './shaders/exposure.ts';
+import { EXPOSURE_LOCAL_FRAG, LOCAL_GRID_WIDTH } from './shaders/localExposure.ts';
+import { FULLSCREEN_VERT } from './shaders/fullscreen.ts';
+import { compileProgram, uniformLocations } from './shader.ts';
+
+/**
+ * Eye adaptation on WebGL2: meter the finished scene, and follow it with a held brightness the
+ * composite reads. See `shaders/exposure.ts` for the design; this owns the targets and the draws.
+ *
+ * **Two one-texel targets that swap roles each frame**, because the adaptation reads what it held
+ * and a texture cannot be read and written in one draw. The composite is handed whichever was
+ * written last. `R16F`, because the held value is in stops and eight bits of a range twenty stops
+ * wide is an exposure that steps visibly as it moves.
+ *
+ * **And local exposure's grid, when that is asked for**: `RG16F`, a sum and a count per tile per
+ * band, filtered linearly because the composite reads it between tiles. See `localExposure.ts`.
+ */
+export class ExposurePass {
+  private meter: WebGLTexture | null = null;
+  private meterFramebuffer: WebGLFramebuffer | null = null;
+  private localGrid: WebGLTexture | null = null;
+  private localFramebuffer: WebGLFramebuffer | null = null;
+  private readonly held: (WebGLTexture | null)[] = [null, null];
+  private readonly heldFramebuffers: (WebGLFramebuffer | null)[] = [null, null];
+  /** Which of the two held texels the next adaptation writes. */
+  private writing = 0;
+  /** Whether anything is held yet: the first frame, and the first after a cut, snaps. */
+  private holding = false;
+  private allocated = false;
+  /** Set once if a half-float target will not complete; the pass is then off and says so once. */
+  private unavailable = false;
+
+  private readonly meterProgram: WebGLProgram;
+  private readonly meterUniforms: Record<string, WebGLUniformLocation | null>;
+  private readonly adaptProgram: WebGLProgram;
+  private readonly adaptUniforms: Record<string, WebGLUniformLocation | null>;
+  private readonly localProgram: WebGLProgram;
+  private readonly localUniforms: Record<string, WebGLUniformLocation | null>;
+  private readonly vao: WebGLVertexArrayObject;
+
+  constructor(private readonly gl: WebGL2RenderingContext) {
+    this.meterProgram = compileProgram(gl, FULLSCREEN_VERT, EXPOSURE_METER_FRAG, 'exposureMeter');
+    this.meterUniforms = uniformLocations(gl, this.meterProgram, 'exposureMeter');
+    this.adaptProgram = compileProgram(gl, FULLSCREEN_VERT, EXPOSURE_ADAPT_FRAG, 'exposureAdapt');
+    this.adaptUniforms = uniformLocations(gl, this.adaptProgram, 'exposureAdapt');
+    this.localProgram = compileProgram(gl, FULLSCREEN_VERT, EXPOSURE_LOCAL_FRAG, 'exposureLocal');
+    this.localUniforms = uniformLocations(gl, this.localProgram, 'exposureLocal');
+    const vao = gl.createVertexArray();
+    if (vao === null) throw new Error('ExposurePass: createVertexArray failed');
+    this.vao = vao;
+  }
+
+  /** Forget what is held, so the next frame meters afresh rather than easing from another shot. */
+  cut(): void {
+    this.holding = false;
+  }
+
+  private ensure(): boolean {
+    if (this.unavailable) return false;
+    if (this.allocated) return true;
+    const { gl } = this;
+    const target = (
+      size: number,
+      height = size,
+      pair = false,
+    ): { texture: WebGLTexture | null; framebuffer: WebGLFramebuffer | null; ok: boolean } => {
+      const texture = gl.createTexture();
+      gl.bindTexture(gl.TEXTURE_2D, texture);
+      if (pair)
+        gl.texImage2D(gl.TEXTURE_2D, 0, gl.RG16F, size, height, 0, gl.RG, gl.HALF_FLOAT, null);
+      else gl.texImage2D(gl.TEXTURE_2D, 0, gl.R16F, size, height, 0, gl.RED, gl.HALF_FLOAT, null);
+      const filter = pair ? gl.LINEAR : gl.NEAREST;
+      gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, filter);
+      gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, filter);
+      gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+      gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+      const framebuffer = gl.createFramebuffer();
+      gl.bindFramebuffer(gl.FRAMEBUFFER, framebuffer);
+      gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_2D, texture, 0);
+      const ok = gl.checkFramebufferStatus(gl.FRAMEBUFFER) === gl.FRAMEBUFFER_COMPLETE;
+      return { texture, framebuffer, ok };
+    };
+    const meter = target(METER_GRID);
+    const first = target(1);
+    const second = target(1);
+    const local = target(LOCAL_GRID_WIDTH, METER_GRID, true);
+    gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+    gl.bindTexture(gl.TEXTURE_2D, null);
+    this.meter = meter.texture;
+    this.meterFramebuffer = meter.framebuffer;
+    this.held[0] = first.texture;
+    this.held[1] = second.texture;
+    this.heldFramebuffers[0] = first.framebuffer;
+    this.heldFramebuffers[1] = second.framebuffer;
+    this.localGrid = local.texture;
+    this.localFramebuffer = local.framebuffer;
+    this.allocated = true;
+    if (!meter.ok || !first.ok || !second.ok || !local.ok) {
+      this.unavailable = true;
+      console.warn(
+        'ExposurePass: this driver will not render to a half-float target, so eye adaptation is ' +
+          'off and the exposure is the one set. The frame itself is unaffected.',
+      );
+      return false;
+    }
+    return true;
+  }
+
+  /**
+   * Meter `scene` and move the held brightness toward it by `dtSec` of adaptation, and with `local`
+   * draw local exposure's grid too. Returns the texel the composite reads, or null where this pass
+   * could not run, which the caller reads as off.
+   */
+  run(scene: WebGLTexture, dtSec: number, local = false): WebGLTexture | null {
+    if (!this.ensure()) return null;
+    const { gl } = this;
+    gl.disable(gl.DEPTH_TEST);
+    gl.disable(gl.BLEND);
+    gl.disable(gl.CULL_FACE);
+    gl.depthMask(false);
+    gl.bindVertexArray(this.vao);
+
+    gl.bindFramebuffer(gl.FRAMEBUFFER, this.meterFramebuffer);
+    gl.viewport(0, 0, METER_GRID, METER_GRID);
+    gl.useProgram(this.meterProgram);
+    gl.activeTexture(gl.TEXTURE0);
+    gl.bindTexture(gl.TEXTURE_2D, scene);
+    gl.uniform1i(this.meterUniforms['uScene'] ?? null, 0);
+    gl.drawArrays(gl.TRIANGLES, 0, 3);
+
+    if (local) {
+      gl.bindFramebuffer(gl.FRAMEBUFFER, this.localFramebuffer);
+      gl.viewport(0, 0, LOCAL_GRID_WIDTH, METER_GRID);
+      gl.useProgram(this.localProgram);
+      gl.uniform1i(this.localUniforms['uScene'] ?? null, 0);
+      gl.drawArrays(gl.TRIANGLES, 0, 3);
+    }
+
+    const into = this.writing;
+    const from = 1 - into;
+    gl.bindFramebuffer(gl.FRAMEBUFFER, this.heldFramebuffers[into] ?? null);
+    gl.viewport(0, 0, 1, 1);
+    gl.useProgram(this.adaptProgram);
+    gl.activeTexture(gl.TEXTURE0);
+    gl.bindTexture(gl.TEXTURE_2D, this.meter);
+    gl.uniform1i(this.adaptUniforms['uMeter'] ?? null, 0);
+    gl.activeTexture(gl.TEXTURE1);
+    gl.bindTexture(gl.TEXTURE_2D, this.held[from] ?? null);
+    gl.uniform1i(this.adaptUniforms['uHeld'] ?? null, 1);
+    gl.uniform1f(this.adaptUniforms['uBlend'] ?? null, adaptBlend(dtSec, !this.holding));
+    gl.drawArrays(gl.TRIANGLES, 0, 3);
+
+    this.holding = true;
+    this.writing = from;
+    gl.bindVertexArray(null);
+    gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+    return this.held[into] ?? null;
+  }
+
+  /** Local exposure's grid as the last `run` drew it, or null before one has. */
+  get localTexture(): WebGLTexture | null {
+    return this.localGrid;
+  }
+
+  dispose(): void {
+    const { gl } = this;
+    for (const framebuffer of [
+      this.meterFramebuffer,
+      this.localFramebuffer,
+      ...this.heldFramebuffers,
+    ]) {
+      if (framebuffer !== null) gl.deleteFramebuffer(framebuffer);
+    }
+    for (const texture of [this.meter, this.localGrid, ...this.held])
+      if (texture !== null) gl.deleteTexture(texture);
+    gl.deleteProgram(this.meterProgram);
+    gl.deleteProgram(this.localProgram);
+    gl.deleteProgram(this.adaptProgram);
+    gl.deleteVertexArray(this.vao);
+  }
+}

package/src/render/flameLight.ts

@@ -0,0 +1,135 @@
+/**
+ * A flame: one point light and one plume from a single description, flickering at the rate a flame
+ * of that size flickers.
+ *
+ * **The rate is physics, not taste.** A buoyant flame puffs at about 1.5 / √D times a second for a
+ * burning area D metres across (Cetegen and Ahmed, 1993). That is 15 Hz for a candle's centimetre,
+ * which is why a candle trembles, and 2.4 Hz for a 40 cm brazier, which is why a fire breathes.
+ * Before this, a scene wired its plume, its light and a flicker amplitude by hand. The selection's
+ * shared wobble ran every light at the same two rates, so a candle and a bonfire pulsed together.
+ *
+ * **What the description fixes.** The flame stands 2.5 D tall, which is a candle's 2.5 cm and a
+ * brazier's metre. The light sits a third of the way up it, where a flame is brightest, and its
+ * physical radius is D / 2, so its shadows soften as a fire's do. It sways by up to 6 per cent of
+ * the flame's height on each axis, a few centimetres for a brazier, so a shadow it casts travels
+ * rather than only dimming.
+ *
+ * **What it gives up.** The waveform is two sines, the pulse and a harmonic, which never gust. A
+ * fire in wind wants its sway driven by the scene's `WindField`, and nothing here reads one. What
+ * would make the rate wrong is a flame far outside the law's range: a jet, or a pool fire of
+ * several metres, which puffs slower than the formula says.
+ *
+ * Plain data and two functions. `updateFlame` writes into the light it made and allocates nothing,
+ * so a scene updates every flame in its frame and hands the lights to `selectPointLights`.
+ */
+import type { Vec3 } from '../math/color.ts';
+import type { PlumePlacement } from './plumeRenderer.ts';
+import type { PointLightSource } from './pointLightSelection.ts';
+
+export interface FlameOptions {
+  /** Where the fire burns from, world space: the wick's tip, the top of the coals. */
+  readonly x: number;
+  readonly y: number;
+  readonly z: number;
+  /** How wide the burning area is, metres: a candle 0.01, a lantern 0.03, a brazier's bowl 0.4. */
+  readonly diameterM: number;
+  /** The light's colour at its mean brightness, in the caller's light units. */
+  readonly color: Vec3;
+  /** Metres at which the light ends. */
+  readonly radius: number;
+  /** How far the brightness swings either side of its mean, 0 to 1. Defaults to 0.18. */
+  readonly flicker?: number;
+  /** Keeps two flames of one size out of step. Defaults to 0. */
+  readonly seed?: number;
+  /** Whether the light may take a shadow slot. Defaults to true, as `PointLightSource` does. */
+  readonly castsShadow?: boolean;
+  /**
+   * How far the light wanders on each axis, as a share of the flame's height. Defaults to 0.06.
+   *
+   * 0 holds it still. A point light's static shadow map is baked from where the light stood, so a
+   * light that wanders reads that map from a few centimetres off. What would make the default wrong
+   * is a flame near a surface it shadows, where that offset shows as a band.
+   */
+  readonly sway?: number;
+}
+
+export interface Flame {
+  /** Rewritten by `updateFlame`. Offer it to `selectPointLights` with the scene's other lights. */
+  readonly light: PointLightSource;
+  /** Where the plume stands and how big it is, for `createPlumes`. */
+  readonly plume: PlumePlacement;
+  /** Pulses a second: 1.5 / √D. */
+  readonly frequencyHz: number;
+  readonly centre: Vec3;
+  readonly color: Vec3;
+  readonly flicker: number;
+  readonly phase: number;
+  readonly swayM: number;
+}
+
+/** How tall a flame stands, as a multiple of the width it burns from. */
+const HEIGHT_PER_DIAMETER = 2.5;
+/** How far the light sways on each axis, as a share of the flame's height. */
+const SWAY_PER_HEIGHT = 0.06;
+/** The harmonic's rate against the pulse's, chosen irrational so the two never lock. */
+const HARMONIC = 2.37;
+
+/** The puffing rate of a flame burning from `diameterM` metres across. */
+export function flameFrequencyHz(diameterM: number): number {
+  return 1.5 / Math.sqrt(Math.max(diameterM, 1e-3));
+}
+
+export function createFlame(options: FlameOptions): Flame {
+  const height = HEIGHT_PER_DIAMETER * options.diameterM;
+  const centre: Vec3 = [options.x, options.y + height / 3, options.z];
+  /* A seed spread over the whole turn, so seeds 1 and 2 are not neighbours in phase. */
+  const phase = ((options.seed ?? 0) * 2.399963) % (Math.PI * 2);
+  const light: PointLightSource = {
+    x: centre[0],
+    y: centre[1],
+    z: centre[2],
+    r: options.color[0],
+    g: options.color[1],
+    b: options.color[2],
+    radius: options.radius,
+    /* Off, because this helper is the flicker; the selection's own would apply a second one. */
+    flicker: 0,
+    shadowNear: Math.max(0.05, options.diameterM),
+    sourceRadius: options.diameterM / 2,
+    ...(options.castsShadow === false ? { castsShadow: false } : {}),
+  };
+  return {
+    light,
+    plume: {
+      x: options.x,
+      y: options.y,
+      z: options.z,
+      width: options.diameterM / 2,
+      height,
+    },
+    frequencyHz: flameFrequencyHz(options.diameterM),
+    centre,
+    color: [options.color[0], options.color[1], options.color[2]],
+    flicker: options.flicker ?? 0.18,
+    phase,
+    swayM: (options.sway ?? SWAY_PER_HEIGHT) * height,
+  };
+}
+
+/** Where the flame's light is and how bright, at `timeSeconds`. Writes `flame.light` in place. */
+export function updateFlame(flame: Flame, timeSeconds: number): void {
+  const w = 2 * Math.PI * flame.frequencyHz * timeSeconds;
+  const p = flame.phase;
+  const pulse = 0.65 * Math.sin(w + p) + 0.35 * Math.sin(HARMONIC * w + 1.9 * p);
+  const scale = 1 + flame.flicker * pulse;
+  const light = flame.light;
+  light.r = flame.color[0] * scale;
+  light.g = flame.color[1] * scale;
+  light.b = flame.color[2] * scale;
+  /* The sway runs slower than the pulse and on its own rates, so the light wanders rather than
+     tracing one loop. Up when the flame puffs up. */
+  const sway = flame.swayM;
+  light.x = flame.centre[0] + sway * Math.sin(0.83 * w + 2.1 * p);
+  light.y = flame.centre[1] + sway * Math.sin(w + p);
+  light.z = flame.centre[2] + sway * Math.cos(0.71 * w + 3.3 * p);
+}

package/src/render/gi/bounceLights.ts

@@ -0,0 +1,68 @@
+/**
+ * The frame's exact lights as DriftRay's probe bake reads them: what a surface a probe's ray
+ * strikes is lit by, besides the sun, the bounce already in the grid and a DriftLight field.
+ *
+ * **Why the trace needs them at all.** A probe ray shades what it hits itself rather than reading
+ * a capture, which is what lets the bounce follow a light that moves; but it shaded with the sun
+ * alone, so a courtyard at night bounced no firelight into the corners the fires could not see. A
+ * field carries the many fixed lights; these are the rest, the lights the frame shades one by one,
+ * flickering and moving as they do in the frame.
+ *
+ * **Decided here and bound there**, by the 2026-08-13 rule: which lights, in what order and at what
+ * weight is one decision for any backend that traces. A light a field sums carries a negative
+ * weight and is left out, because the field already brings it to the bounce; a fading light goes in
+ * at its weight, as the lit shader scales it.
+ *
+ * **At most `MAX_BOUNCE_LIGHTS`, the first the selection chose**, which is nearest the camera: each
+ * one is a march per ray that reaches it, and a probe far from the camera is lit by lights further
+ * down the list that this leaves out. What would change that is a scene whose bounce is dominated
+ * by lights far from where it is looked at, which would want the selection run again from the grid.
+ *
+ * What it gives up against the frame: a photometric profile and a cookie, which the bounce reads as
+ * a plain cone, and a light's specular, which a diffuse bounce has no use for.
+ */
+
+import type { PointLightSet } from '../lightBudget.ts';
+import { POINT_LIGHT_COS_INNER, POINT_LIGHT_COS_OUTER } from '../clusteredLights.ts';
+
+/** Lights the probe bake shades a hit with. */
+export const MAX_BOUNCE_LIGHTS = 32;
+/**
+ * Floats a light takes: where it is and how far it reaches; its colour at its weight and the cosine
+ * of its inner cone; the way it points and the cosine of its outer cone.
+ */
+export const BOUNCE_LIGHT_FLOATS = 12;
+
+export function createBounceLights(): Float32Array {
+  return new Float32Array(MAX_BOUNCE_LIGHTS * BOUNCE_LIGHT_FLOATS);
+}
+
+/** Pack the lights of `lights` the bounce reads into `out`, and answer how many. */
+export function resolveBounceLights(lights: PointLightSet | null, out: Float32Array): number {
+  if (lights === null) return 0;
+  let count = 0;
+  for (let i = 0; i < lights.lightCount && count < MAX_BOUNCE_LIGHTS; i++) {
+    const weight = lights.lightWeights[i] ?? 0;
+    const radius = lights.lightRadii[i] ?? 0;
+    if (!(weight > 0) || !(radius > 0)) continue;
+    const r = lights.lightColors[i * 3] ?? 0;
+    const g = lights.lightColors[i * 3 + 1] ?? 0;
+    const b = lights.lightColors[i * 3 + 2] ?? 0;
+    if (!(r + g + b > 0)) continue;
+    const at = count * BOUNCE_LIGHT_FLOATS;
+    out[at] = lights.lightPositions[i * 3] ?? 0;
+    out[at + 1] = lights.lightPositions[i * 3 + 1] ?? 0;
+    out[at + 2] = lights.lightPositions[i * 3 + 2] ?? 0;
+    out[at + 3] = radius;
+    out[at + 4] = r * weight;
+    out[at + 5] = g * weight;
+    out[at + 6] = b * weight;
+    out[at + 7] = lights.lightConeCos?.[i * 2] ?? POINT_LIGHT_COS_INNER;
+    out[at + 8] = lights.lightDirections?.[i * 3] ?? 0;
+    out[at + 9] = lights.lightDirections?.[i * 3 + 1] ?? 0;
+    out[at + 10] = lights.lightDirections?.[i * 3 + 2] ?? 0;
+    out[at + 11] = lights.lightConeCos?.[i * 2 + 1] ?? POINT_LIGHT_COS_OUTER;
+    count++;
+  }
+  return count;
+}

package/src/render/gi/fieldReach.ts

@@ -0,0 +1,74 @@
+/**
+ * Whether the traced field reaches the probes it lights: how many cascades a grid needs, and which
+ * scheduled probes the field reaches this frame.
+ *
+ * **A probe traced where the field is not learns that the world is sky.** Every ray it casts finds
+ * nothing and falls to the sky colour, the floor under it and the wall beside it included, so it
+ * reports the open sky from every side: a covered arcade lit like a field at noon. The field is
+ * composed around the camera, and three cascades from a 4 m inner one reach 16 m, so a courtyard 36
+ * m long had its far end lit exactly that way from wherever the viewer stood, a milky wash over
+ * everything past the outermost cascade that the rasterised grid did not have.
+ *
+ * Two answers, one for each way it happens. A grid is given the cascades that reach all of it from
+ * anywhere inside it; and a probe the field still does not reach, because the camera has left the
+ * grid, is left out of the schedule and keeps the light it has, rather than being overwritten with
+ * a sky it never saw. What it gives up is that probe following a change while the camera is away.
+ */
+import { GLOBAL_FIELD_BLEND } from './globalField.ts';
+import type { ProbeGrid } from '../probeGrid.ts';
+
+/** The share of the outermost cascade's half-extent a probe can trust, inside its fading faces. */
+const TRUSTED = 1 - 2 * GLOBAL_FIELD_BLEND;
+
+/**
+ * Cascades enough for the outermost to hold the whole grid, and one probe step past it, within the
+ * part of it that is trusted, wherever inside the grid the camera stands. At least `least` and at
+ * most `most`: each cascade is the same number of samples, so the bound is on memory, not reach.
+ */
+export function cascadesForGrid(
+  grid: ProbeGrid,
+  radius: number,
+  least: number,
+  most: number,
+): number {
+  let span = 0;
+  let step = 0;
+  for (let axis = 0; axis < 3; axis++) {
+    const spacing = grid.spacing[axis] as number;
+    span = Math.max(span, spacing * ((grid.counts[axis] as number) - 1));
+    step = Math.max(step, spacing);
+  }
+  const needed = (span + step) / TRUSTED;
+  let cascades = 1;
+  while (radius * 2 ** (cascades - 1) < needed && cascades < most) cascades++;
+  return Math.min(most, Math.max(least, cascades));
+}
+
+const at: [number, number, number] = [0, 0, 0];
+
+/**
+ * Keeps, in place and in order, the scheduled probes inside the trusted part of the outermost
+ * cascade, `bounds` as `[minX, minY, minZ, maxX, maxY, maxZ]`. Returns how many are kept.
+ */
+export function probesTheFieldReaches(
+  grid: ProbeGrid,
+  scheduled: Int32Array,
+  count: number,
+  bounds: ArrayLike<number>,
+): number {
+  let kept = 0;
+  for (let i = 0; i < count; i++) {
+    const layer = scheduled[i] as number;
+    grid.positionOf(layer, at);
+    let inside = true;
+    for (let axis = 0; axis < 3; axis++) {
+      const low = bounds[axis] as number;
+      const high = bounds[axis + 3] as number;
+      const band = GLOBAL_FIELD_BLEND * (high - low);
+      const p = at[axis] as number;
+      if (p < low + band || p > high - band) inside = false;
+    }
+    if (inside) scheduled[kept++] = layer;
+  }
+  return kept;
+}

package/src/render/gi/globalField.ts

@@ -308,6 +308,45 @@ function insideBy(cascade: GlobalFieldCascade, x: number, y: number, z: number):
   return least;
 }
 
+/**
+ * The world distance to the nearest of `instances` at any point, rather than composed onto a grid
+ * around the camera: for a caller that traces through the scene once instead of every frame, such
+ * as DriftLight's occlusion bake. The same sampling `composeGlobalField` does, under the same
+ * refusals of a non-uniform scale and non-cubic voxels, so the two cannot disagree about a surface.
+ * Nothing placed answers a very large distance: open space everywhere.
+ */
+export function distanceToInstances(
+  instances: readonly GlobalFieldInstance[],
+): (x: number, y: number, z: number) => number {
+  const inverses: Float32Array[] = [];
+  const scales: number[] = [];
+  const kept: GlobalFieldInstance[] = [];
+  for (const instance of instances) {
+    assertUniformScale(instance.transform);
+    assertCubicVoxels(instance.source);
+    const inverse = new Float32Array(16);
+    if (mat4.invert(inverse, instance.transform) === null) continue;
+    inverses.push(inverse);
+    scales.push(uniformScaleOf(instance.transform));
+    kept.push(instance);
+  }
+  return (x, y, z) => {
+    let nearest = 1e9;
+    for (let at = 0; at < kept.length; at++) {
+      const distance = sampleInstance(
+        kept[at] as GlobalFieldInstance,
+        inverses[at] as Float32Array,
+        scales[at] as number,
+        x,
+        y,
+        z,
+      );
+      if (distance < nearest) nearest = distance;
+    }
+    return nearest;
+  };
+}
+
 /**
  * The distance one instance reports at a world point.
  *

package/src/render/gi/probeTrace.ts

@@ -62,8 +62,10 @@ export const GOLDEN_ANGLE = Math.PI * (3 - Math.sqrt(5));
 /**
  * How far the set turns between one refresh and the next, in turns.
  *
- * The golden ratio's fractional part: successive frames land their offsets as far from each other
+ * The golden ratio's fractional part: successive turns land their offsets as far from each other
  * as the sequence allows, for the same reason the spiral's own points do, and it never repeats.
+ * The WebGPU bake holds the turn at 0, because a set that turns makes every refresh a new estimate
+ * and a still scene flicker; see `ProbeBaker.bake`.
  */
 export const FRAME_TURN = 0.618033988749895;
 

package/src/render/gpuCapability.ts

@@ -194,11 +194,24 @@ export async function describeGpu(options: DescribeGpuOptions = {}): Promise<Gpu
     source,
   });
 
-  /* WebGL2 first: it is the API that gives a model number. See the header for the measurement. */
-  const canvas =
-    options.createCanvas === undefined
-      ? (globalThis.document?.createElement('canvas') ?? null)
-      : options.createCanvas();
+  /*
+   * WebGL2 first: it is the API that gives a model number. See the header for the measurement.
+   *
+   * **The canvas is made inside the guard as well as the context.** A host can have a `document`
+   * and still refuse to make one: the native host installs a page so a game finds what it expects,
+   * and its `createElement` throws, because there is no DOM behind it. Made outside the guard, that
+   * took a scene's mount down on the second host; inside it, such a host is simply one without
+   * WebGL2, and the adapter below names the part.
+   */
+  let canvas: HTMLCanvasElement | null = null;
+  try {
+    canvas =
+      options.createCanvas === undefined
+        ? (globalThis.document?.createElement('canvas') ?? null)
+        : options.createCanvas();
+  } catch {
+    canvas = null;
+  }
   if (canvas !== null) {
     let gl: WebGL2RenderingContext | null = null;
     try {

package/src/render/lightBudget.ts

@@ -218,6 +218,18 @@ export const COOKIE_ATLAS_TEXTURE_UNIT = MORPH_DELTA_TEXTURE_UNIT + 1;
  */
 export const REFRACT_SCENE_TEXTURE_UNIT = COOKIE_ATLAS_TEXTURE_UNIT + 1;
 
+/**
+ * DriftLight's brick index and atlas, the lit program's fourteenth and fifteenth fragment samplers.
+ *
+ * Units past fifteen are legal: `MAX_TEXTURE_IMAGE_UNITS` caps how many samplers a stage *uses*,
+ * sixteen at the least, while a unit's number only has to be under the combined limit, which WebGL2
+ * guarantees is at least thirty-two. The skin palette and morph deltas below them are vertex
+ * textures and count against the vertex stage instead. What would make this wrong is a sixteenth
+ * fragment sampler, which the lit program would then be one short of on the guaranteed minimum.
+ */
+export const DRIFT_LIGHT_INDEX_TEXTURE_UNIT = REFRACT_SCENE_TEXTURE_UNIT + 1;
+export const DRIFT_LIGHT_ATLAS_TEXTURE_UNIT = DRIFT_LIGHT_INDEX_TEXTURE_UNIT + 1;
+
 /**
  * A cookie's tile, in texels a side.
  *