@driftengine/core 4.2.1 → 4.4.0

package/dist/render/gi/fieldReach.js

@@ -0,0 +1,62 @@
+/**
+ * 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.js';
+/** 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, radius, least, most) {
+    let span = 0;
+    let step = 0;
+    for (let axis = 0; axis < 3; axis++) {
+        const spacing = grid.spacing[axis];
+        span = Math.max(span, spacing * (grid.counts[axis] - 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 = [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, scheduled, count, bounds) {
+    let kept = 0;
+    for (let i = 0; i < count; i++) {
+        const layer = scheduled[i];
+        grid.positionOf(layer, at);
+        let inside = true;
+        for (let axis = 0; axis < 3; axis++) {
+            const low = bounds[axis];
+            const high = bounds[axis + 3];
+            const band = GLOBAL_FIELD_BLEND * (high - low);
+            const p = at[axis];
+            if (p < low + band || p > high - band)
+                inside = false;
+        }
+        if (inside)
+            scheduled[kept++] = layer;
+    }
+    return kept;
+}

package/dist/render/gi/globalField.d.ts

@@ -131,6 +131,14 @@ export declare function composeGlobalField(instances: readonly GlobalFieldInstan
  * is the honest one.
  */
 export declare function sampleGlobalField(field: GlobalField, x: number, y: number, z: number): number;
+/**
+ * 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 declare function distanceToInstances(instances: readonly GlobalFieldInstance[]): (x: number, y: number, z: number) => number;
 /**
  * Refuse a source whose voxels are not cubic, which `sourceAt` and the shader both assume.
  *

package/dist/render/gi/globalField.js

@@ -187,6 +187,37 @@ function insideBy(cascade, x, y, z) {
     }
     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) {
+    const inverses = [];
+    const scales = [];
+    const kept = [];
+    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], inverses[at], scales[at], x, y, z);
+            if (distance < nearest)
+                nearest = distance;
+        }
+        return nearest;
+    };
+}
 /**
  * The distance one instance reports at a world point.
  *

package/dist/render/gi/probeTrace.d.ts

@@ -53,8 +53,10 @@ export declare const GOLDEN_ANGLE: number;
 /**
  * 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 declare const FRAME_TURN = 0.618033988749895;
 /**

package/dist/render/gi/probeTrace.js

@@ -56,8 +56,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/dist/render/gpuCapability.js

@@ -143,10 +143,25 @@ export async function describeGpu(options = {}) {
         weak: isWeakGpuFamily(rendererName),
         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 = null;
+    try {
+        canvas =
+            options.createCanvas === undefined
+                ? (globalThis.document?.createElement('canvas') ?? null)
+                : options.createCanvas();
+    }
+    catch {
+        canvas = null;
+    }
     if (canvas !== null) {
         let gl = null;
         try {

package/dist/render/lightBudget.d.ts

@@ -201,6 +201,17 @@ export declare const COOKIE_ATLAS_TEXTURE_UNIT: number;
  * `textureUnitBudget.test.ts` carries the phone that budget was written for.
  */
 export declare const REFRACT_SCENE_TEXTURE_UNIT: number;
+/**
+ * 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 declare const DRIFT_LIGHT_INDEX_TEXTURE_UNIT: number;
+export declare const DRIFT_LIGHT_ATLAS_TEXTURE_UNIT: number;
 /**
  * A cookie's tile, in texels a side.
  *

package/dist/render/lightBudget.js

@@ -199,6 +199,17 @@ export const COOKIE_ATLAS_TEXTURE_UNIT = MORPH_DELTA_TEXTURE_UNIT + 1;
  * `textureUnitBudget.test.ts` carries the phone that budget was written for.
  */
 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.
  *

package/dist/render/pointLightSelection.d.ts

@@ -59,6 +59,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 {
     readonly positions: Float32Array;
@@ -132,6 +141,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;
 }
 /**
  * A buffer for the selection to fill, sized to what the caller can actually bind.

package/dist/render/pointLightSelection.js

@@ -40,6 +40,82 @@ const FADE_BAND_M = 40;
 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) {
+    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, b) {
+    const da = candidateDistance[a] ?? 0;
+    const db = candidateDistance[b] ?? 0;
+    return da < db || (da === db && (candidateIndex[a] ?? 0) < (candidateIndex[b] ?? 0));
+}
+function swap(a, b) {
+    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, keep) {
+    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) {
+    for (let at = 1; at < count; at++) {
+        let back = at;
+        while (back > 0 && before(back, back - 1)) {
+            swap(back, back - 1);
+            back--;
+        }
+    }
+}
 /**
  * A buffer for the selection to fill, sized to what the caller can actually bind.
  *
@@ -72,6 +148,7 @@ export function createPointLightBuffer(capacity = MAX_POINT_LIGHTS) {
         scratchDistance: new Float32Array(Math.max(shaded, POINT_SHADOW_POOL)),
         shadowIndex: new Int32Array(POINT_SHADOW_POOL),
         shadowCount: 0,
+        complete: 0,
     };
 }
 /**
@@ -115,6 +192,7 @@ export function selectPointLights(sources, x, y, z, out, timeSeconds = 0, viewRa
      * 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];
         if (light === undefined)
@@ -153,88 +231,14 @@ export function selectPointLights(sources, x, y, z, out, timeSeconds = 0, viewRa
          *
          * 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
          * to cast. Nearest first, capped at the pool, and independent of whether the
@@ -275,6 +279,86 @@ export function selectPointLights(sources, x, y, z, out, timeSeconds = 0, viewRa
         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
@@ -289,8 +373,19 @@ export function selectPointLights(sources, x, y, z, out, timeSeconds = 0, viewRa
         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, timeSeconds) {
     if (light.flicker <= 0)

package/dist/render/probeGrid.d.ts

@@ -32,6 +32,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;
 }
 /**
  * The eight probes surrounding a point, and how much of each it takes.
@@ -87,8 +95,10 @@ export declare 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;
     constructor(options: ProbeGridOptions);

package/dist/render/probeGrid.js

@@ -46,14 +46,16 @@ export function sameGrid(a, b) {
         if (a.spacing[axis] !== b.spacing[axis])
             return false;
     }
-    return true;
+    return a.crossfade === b.crossfade;
 }
 export class ProbeGrid {
     origin;
     spacing;
     counts;
-    /** 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. */
     layers;
+    /** Whether sweeps blend into one another. See `ProbeGridOptions.crossfade`. */
+    crossfade;
     /** The reciprocal of the spacing, because the shader multiplies and so does everything here. */
     invSpacing;
     constructor(options) {
@@ -91,6 +93,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;
     }
     /**
      * The layer a probe at whole lattice coordinates occupies.

package/dist/render/probeSweeps.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 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 declare class ProbeSweeps {
+    /** Sets of layers the array holds: three for a crossfading grid, one otherwise. */
+    readonly sets: 1 | 3;
+    private readonly layers;
+    /** Which probes the sweep being baked has reached, and how many. */
+    private readonly reached;
+    private reachedCount;
+    private from;
+    private to;
+    private write;
+    /** Whether a whole sweep has been rotated in. */
+    private whole;
+    constructor(layers: number, crossfade: boolean);
+    /** The array layer a bake of probe `layer` writes. */
+    writeLayer(layer: number): number;
+    /** Record that probe `layer` was baked into the set being written; a whole sweep rotates. */
+    baked(layer: number): void;
+    /** Whether the shading may read the grid: once a sweep is whole. */
+    get ready(): boolean;
+    /** The layer offsets of the two sets shown and the blend between them, into `out`. */
+    uniforms(out: Float32Array): Float32Array;
+}