@driftengine/core 3.61.0

package/dist/render/prefilterEnvMap.js

@@ -0,0 +1,146 @@
+/**
+ * What a GGX prefilter has to decide before any device is involved: which roughness a mip level
+ * stands for, and which source level one importance sample is allowed to read.
+ *
+ * **Backend-neutral, and that is the 2026-08-13 rule rather than tidiness.** A helper taking a
+ * `WebGL2RenderingContext` is a decision the other backend cannot reach, so it gets reimplemented
+ * there and the two drift. Both backends convolve the same cube by the same lobe; only the binding
+ * differs. It is also what makes the arithmetic testable without a GPU, which is where the
+ * hand-derived numbers in the test beside this file come from.
+ *
+ * **What a prefilter is, against what shipped before it.** A box filter averages a square of
+ * texels. A GGX lobe is not square, is not symmetric about the reflection direction at grazing
+ * angles, and widens with roughness in a way that has an analytic form. Sampling a box-filtered
+ * chain by roughness is an approximation whose error is largest exactly where a surface looks most
+ * interesting, and `uEnvironmentGain` is the control that has been correcting it by brute force.
+ *
+ * **What it costs:** a bake goes from six passes plus a mip chain to six passes plus a convolution
+ * per level. That is affordable only because a bake is once per scene rather than once per frame,
+ * and the sample count is a quality option for the same reason a phone and a workstation should
+ * not agree on it. **What would make it wrong** is a caller baking per frame; at that point the
+ * convolution is the frame's cost and the box chain it replaced was the right trade.
+ */
+/**
+ * Samples per texel, per quality tier.
+ *
+ * **Powers of two, because the Hammersley sequence's radical inverse is a bit reversal.** A count
+ * that is not a power of two leaves the sequence unevenly stratified, which does not error — it
+ * shows as a faint directional bias in the rough levels that reads as the environment being
+ * slightly wrong rather than as a sampling fault.
+ *
+ * 32 is where a rough level stops showing individual bright sources as separate blobs on the
+ * scenes in this repository; 128 is where doubling it again stopped being visible. **What would
+ * make these wrong** is a much brighter environment than any tested here — a small sun in an
+ * otherwise dark sky is the worst case for variance, and it wants the high tier or a source level
+ * chosen more conservatively than `sourceLevelForSample` does.
+ */
+export const PREFILTER_SAMPLE_COUNTS = {
+    low: 16,
+    medium: 32,
+    high: 128,
+};
+/**
+ * The octahedral edge a probe of a given cube face size gets.
+ *
+ * **Twice the face, which is the ratio `OCTAHEDRAL_EDGE` already chose** for the point-shadow
+ * array and for the reason written down there: matching a cube face's angular density needs
+ * `face * sqrt(6)`, so twice the face is about **1.22x coarser in the worst direction**, taken
+ * because the filtering this unlocks is blurring the result anyway. 1024 for a 512 face there,
+ * 256 for the default 128 face here — one rule, so the two octahedral resources in this engine
+ * are calibrated against each other rather than each to taste.
+ */
+export function octahedralEdgeFor(faceSize) {
+    return Math.max(32, Math.trunc(faceSize) * 2);
+}
+/**
+ * The irradiance image's edge, and why the diffuse term is a level of the same chain.
+ *
+ * **Eight, which is what a probe's diffuse light actually needs.** A cosine convolution removes
+ * everything above the second band, so the image it produces has no detail an eighth of a sphere
+ * across to lose — the size irradiance probes are conventionally stored at, arrived at from the
+ * same place. It replaces nine spherical-harmonic coefficients, and 64 octahedral texels carry at
+ * least what nine coefficients did.
+ *
+ * **What this buys is the last texture unit.** A second array would be a second sampler, and
+ * WebGL2 guarantees sixteen units of which fifteen are spent. Folding the diffuse term into a
+ * level of the radiance chain is what `REFRACT_SCENE_TEXTURE_UNIT`'s comment asks the next
+ * sampler to do, and it leaves unit 15 free.
+ */
+export const IRRADIANCE_EDGE = 8;
+/**
+ * Which level of a chain holds the cosine convolution.
+ *
+ * The level whose image is `IRRADIANCE_EDGE` across. For the default 256 edge that is level 5, and
+ * **the chain stops there rather than carrying unread levels above it** — `texStorage3D` takes a
+ * level count, so the three that would hold sixteen, four and one texel are never created. Six
+ * levels, 87,360 texels, 683 KB a layer at half float.
+ */
+export function irradianceLevelFor(edge) {
+    return Math.max(1, Math.round(Math.log2(Math.max(IRRADIANCE_EDGE * 2, edge) / IRRADIANCE_EDGE)));
+}
+/**
+ * The coarsest level the GGX chain reaches, which is one below the irradiance level.
+ *
+ * This is `uEnvironmentMaxLod`, and it is what `roughnessForLevel` maps roughness 1 onto. For the
+ * default edge it is 4, so the roughest level is 16 texels across.
+ *
+ * **That is better at high roughness than the cube it replaces, not worse.** A 128 cube's chain
+ * ends at one texel a face, which the lit pass's own comment complains about — "one texel a face
+ * and therefore one colour for every direction". What is given up is roughness granularity, five
+ * stops against eight, and the level blend interpolates between them exactly as the cube's mip
+ * filter did.
+ */
+export function ggxMaxLevelFor(edge) {
+    return Math.max(1, irradianceLevelFor(edge) - 1);
+}
+/**
+ * The roughness mip level `level` is convolved for.
+ *
+ * **Linear in the level index, and it has to be**, because the lit pass already picks its level
+ * with `surfaceRoughness * uEnvironmentMaxLod`. This is that relation read backwards. A different
+ * curve here would not be an improvement in isolation — it would be the two halves disagreeing
+ * about what level three means, which reads as roughness being subtly miscalibrated everywhere and
+ * points at nothing.
+ *
+ * **What would make it wrong** is the lit pass changing how it selects a level; the two move
+ * together or neither moves.
+ */
+export function roughnessForLevel(level, maxLevel) {
+    /*
+     * A single-level chain has nowhere to go, and dividing by its zero top level is NaN — a
+     * roughness the convolution would carry into every sample, producing a picture nobody could
+     * attribute to a divide. A mirror is what one level honestly is.
+     */
+    if (maxLevel <= 0)
+        return 0;
+    return Math.min(1, Math.max(0, level / maxLevel));
+}
+/**
+ * Which level of the source cube one importance sample may read.
+ *
+ * **Filtered importance sampling, and the whole point of it is variance rather than speed.** A
+ * sample drawn from the GGX distribution covers a solid angle of `1 / (count * pdf)`; one texel of
+ * a cube with `faceTexels`-wide faces covers `4*pi / (6 * faceTexels^2)`. When a sample is much
+ * wider than a texel, reading the base level lets a few very bright texels land in some samples and
+ * not others, and that variance survives the average as fireflies. Reading a level where the sample
+ * covers roughly one texel is what removes them without raising the count.
+ *
+ * The half in front of the logarithm is not a fudge: a level step doubles a texel's width and so
+ * quadruples its solid angle, and the level is a length ratio rather than an area one.
+ *
+ * **What it costs** is that the source has to be a box-filtered chain, which is why the capture
+ * keeps its `generateMipmap` and the convolution writes a second cube. **What would make it wrong**
+ * is convolving from a source that is itself already convolved: the lobe would be applied twice and
+ * the error compounds up the chain, which is precisely the reason the two cubes are separate
+ * objects rather than one written in place.
+ */
+export function sourceLevelForSample(pdf, faceTexels, count, maxLevel) {
+    /* Guard the logarithm's arguments rather than its result; a zero here is a caller's bug. */
+    const texels = Math.max(1, faceTexels);
+    const samples = Math.max(1, count);
+    const density = Math.max(1e-12, pdf);
+    const texelSolidAngle = (4 * Math.PI) / (6 * texels * texels);
+    const sampleSolidAngle = 1 / (samples * density);
+    const level = 0.5 * Math.log2(sampleSolidAngle / texelSolidAngle);
+    return Math.min(maxLevel, Math.max(0, level));
+}

package/dist/render/prefilterPass.d.ts

@@ -0,0 +1,44 @@
+/** WebGL2's half of the environment prefilter: the program, and the draw for one level of a layer. */
+import type { EnvProbeArray } from './envProbeArray.ts';
+import type { ReflectionProbe } from './reflectionProbe.ts';
+/**
+ * Convolves a captured probe's box chain into one layer of the grid's array, once per bake.
+ *
+ * **Its own module rather than more of the renderer**, following `ambientOcclusionPass.ts` and
+ * `bloomPass.ts`: a program, its uniforms, a vertex array and one draw. The renderer owns when
+ * this happens; this owns what it is.
+ *
+ * **What it costs** is one program compile at construction and **one draw per level per bake**,
+ * where the cube it replaced needed six — an octahedral map has no faces, so the six-way loop is
+ * gone rather than moved. A bake is once per scene per probe, which is the whole reason a
+ * convolution is affordable where a per-frame version of it would not be. **What would make it
+ * wrong** is a caller baking every frame; at that point this is the frame's cost and the box chain
+ * it replaced was the right trade.
+ *
+ * **A grid multiplies a bake by its probe count**, which is the real budget question rather than
+ * the texture units. The caller drives one probe at a time for exactly that reason.
+ */
+export declare class EnvironmentPrefilterPass {
+    private readonly program;
+    private readonly uniforms;
+    private readonly vao;
+    constructor(gl: WebGL2RenderingContext);
+    /**
+     * Fill every level of the probe's prefiltered cube from its captured one.
+     *
+     * The source is bound on the unit the environment normally occupies, which is deliberate rather
+     * than convenient: that unit is rebound by the lit pass every frame, so borrowing it here cannot
+     * outlive the bake, and it keeps the pass out of the unit accounting `textureUnitBudget.test.ts`
+     * holds.
+     */
+    run(gl: WebGL2RenderingContext, source: ReflectionProbe, array: EnvProbeArray, layer: number, sourceUnit: number, samples: number, 
+    /**
+     * Whether the reflection chain is the GGX convolution rather than a box filter.
+     *
+     * `RenderQuality.environmentPrefilter`, and it is consulted here rather than at bind time
+     * because there is one chain now instead of two textures. A profile that has not asked for the
+     * lobe chain bakes the box one into the same layers and gets the picture it already had.
+     */
+    prefiltered: boolean): void;
+    dispose(gl: WebGL2RenderingContext): void;
+}

package/dist/render/prefilterPass.js

@@ -0,0 +1,98 @@
+/** WebGL2's half of the environment prefilter: the program, and the draw for one level of a layer. */
+import { compileProgram, uniformLocations } from './shader.js';
+import { PREFILTER_FRAG } from './shaders/prefilter.js';
+import { FULLSCREEN_VERT } from './shaders/fullscreen.js';
+/**
+ * Convolves a captured probe's box chain into one layer of the grid's array, once per bake.
+ *
+ * **Its own module rather than more of the renderer**, following `ambientOcclusionPass.ts` and
+ * `bloomPass.ts`: a program, its uniforms, a vertex array and one draw. The renderer owns when
+ * this happens; this owns what it is.
+ *
+ * **What it costs** is one program compile at construction and **one draw per level per bake**,
+ * where the cube it replaced needed six — an octahedral map has no faces, so the six-way loop is
+ * gone rather than moved. A bake is once per scene per probe, which is the whole reason a
+ * convolution is affordable where a per-frame version of it would not be. **What would make it
+ * wrong** is a caller baking every frame; at that point this is the frame's cost and the box chain
+ * it replaced was the right trade.
+ *
+ * **A grid multiplies a bake by its probe count**, which is the real budget question rather than
+ * the texture units. The caller drives one probe at a time for exactly that reason.
+ */
+export class EnvironmentPrefilterPass {
+    program;
+    uniforms;
+    vao;
+    constructor(gl) {
+        this.program = compileProgram(gl, FULLSCREEN_VERT, PREFILTER_FRAG, 'envPrefilter');
+        this.uniforms = uniformLocations(gl, this.program, 'envPrefilter');
+        const vao = gl.createVertexArray();
+        if (vao === null)
+            throw new Error('EnvironmentPrefilterPass: createVertexArray failed');
+        this.vao = vao;
+    }
+    /**
+     * Fill every level of the probe's prefiltered cube from its captured one.
+     *
+     * The source is bound on the unit the environment normally occupies, which is deliberate rather
+     * than convenient: that unit is rebound by the lit pass every frame, so borrowing it here cannot
+     * outlive the bake, and it keeps the pass out of the unit accounting `textureUnitBudget.test.ts`
+     * holds.
+     */
+    run(gl, source, array, layer, sourceUnit, samples, 
+    /**
+     * Whether the reflection chain is the GGX convolution rather than a box filter.
+     *
+     * `RenderQuality.environmentPrefilter`, and it is consulted here rather than at bind time
+     * because there is one chain now instead of two textures. A profile that has not asked for the
+     * lobe chain bakes the box one into the same layers and gets the picture it already had.
+     */
+    prefiltered) {
+        const previousProgram = gl.getParameter(gl.CURRENT_PROGRAM);
+        gl.useProgram(this.program);
+        gl.bindVertexArray(this.vao);
+        /*
+         * A convolution writes over a target it has no depth relationship with, so both the test and
+         * the write are off — and culling with it, because the fullscreen triangle's winding is
+         * whatever the vertex shader's corner arithmetic produced rather than something anybody chose.
+         */
+        gl.disable(gl.DEPTH_TEST);
+        gl.depthMask(false);
+        gl.disable(gl.CULL_FACE);
+        gl.disable(gl.BLEND);
+        gl.activeTexture(gl.TEXTURE0 + sourceUnit);
+        gl.bindTexture(gl.TEXTURE_CUBE_MAP, source.texture);
+        gl.uniform1i(this.uniforms['uPrefilterSource'] ?? null, sourceUnit);
+        gl.uniform1f(this.uniforms['uPrefilterSamples'] ?? null, samples);
+        gl.uniform1f(this.uniforms['uPrefilterSourceTexels'] ?? null, source.size);
+        gl.uniform1f(this.uniforms['uPrefilterSourceMaxLod'] ?? null, source.maxLod);
+        array.convolve(gl, layer, (level, roughness, kind) => {
+            /*
+             * **The level's own edge, not the array's.** A gutter is one texel at every level, so its
+             * share of the map doubles as the chain coarsens; insetting a coarse level by the base
+             * edge's fraction reads as the reflection sliding as roughness rises.
+             */
+            gl.uniform1f(this.uniforms['uPrefilterEdge'] ?? null, Math.max(1, array.edge >> level));
+            gl.uniform1f(this.uniforms['uPrefilterIrradiance'] ?? null, kind === 'irradiance' ? 1 : 0);
+            gl.uniform1f(this.uniforms['uPrefilterBox'] ?? null, prefiltered ? 0 : 1);
+            gl.uniform1f(this.uniforms['uPrefilterLevel'] ?? null, level);
+            gl.uniform1f(this.uniforms['uPrefilterRoughness'] ?? null, roughness);
+            gl.drawArrays(gl.TRIANGLES, 0, 3);
+        });
+        gl.bindVertexArray(null);
+        gl.depthMask(true);
+        gl.enable(gl.DEPTH_TEST);
+        gl.enable(gl.CULL_FACE);
+        /*
+         * Put the caller's program back rather than leaving ours current. The bake around this reads
+         * and restores flat-shader uniforms on either side of itself, and it would be doing that to
+         * whichever program happened to be bound.
+         */
+        if (previousProgram !== null)
+            gl.useProgram(previousProgram);
+    }
+    dispose(gl) {
+        gl.deleteProgram(this.program);
+        gl.deleteVertexArray(this.vao);
+    }
+}

package/dist/render/probeGrid.d.ts

@@ -0,0 +1,122 @@
+/** Where environment probes stand, and which of them light a point. */
+import type { Vec3 } from '../math/color.ts';
+/**
+ * A lattice, and the reason it is one.
+ *
+ * **A list of probes is what the shader cannot afford.** Free placement wants a position and an
+ * extent per probe, and `flatFrag` already declares 35 array uniforms totalling 385 uniform
+ * vectors against WebGL2's guaranteed `MAX_FRAGMENT_UNIFORM_VECTORS` of 224 — the widest
+ * permutation is 1.7x over the guarantee already and runs because real parts offer more. Sixteen
+ * probes of position and extent would add about 48 vectors to that, on a budget nobody can raise.
+ *
+ * A lattice needs four uniforms whatever the probe count: an origin, the reciprocal of the
+ * spacing, the counts, and whether the grid supplies ambient. The layer index is arithmetic and
+ * the blend is three lerps, so nothing here scales with how many probes a world has.
+ *
+ * **What it costs** is that probes cannot be placed where a room is. A world whose interesting
+ * volume is not a box spends layers on probes standing in walls, and the answer to that is a
+ * coarser grid rather than a list. **What would make it wrong** is the flat shader's uniform
+ * pressure falling far enough for per-probe data to fit, or probe data moving into a texture —
+ * which needs the last texture unit, and `lightBudget.ts` records why that one is being kept.
+ */
+export interface ProbeGridOptions {
+    /** Where probe (0, 0, 0) stands. Every other probe is offset from it by whole steps. */
+    readonly origin: Vec3;
+    /** Metres between neighbouring probes on each axis. Every component must be positive. */
+    readonly spacing: Vec3;
+    /**
+     * How many probes on each axis.
+     *
+     * **`[1, 1, 1]` is a single probe, and that is not a special case anywhere below.** A world that
+     * bakes one environment is a grid of one, so there is one code path through the array, the
+     * convolution and the shader instead of a grid path and a legacy path that drift.
+     */
+    readonly counts: Vec3;
+}
+/**
+ * The eight probes surrounding a point, and how much of each it takes.
+ *
+ * Filled rather than returned, because the renderer asks this per draw when it decides what to
+ * bake next, and the rule against allocating in a per-frame path is cheaper to keep than to
+ * reason about. Eight always, duplicates included: a point at the edge of the grid, or in a grid
+ * one probe wide, resolves several corners to the same layer and their weights add. That keeps
+ * the sum exactly one with no branch, which is what the shader wants too.
+ */
+export interface ProbeBlend {
+    readonly layers: Int32Array;
+    readonly weights: Float32Array;
+}
+/** A blend a caller owns and reuses. */
+export declare function createProbeBlend(): ProbeBlend;
+/**
+ * How many layers a grid may hold, and it is a memory limit rather than a binding one.
+ *
+ * Every probe is one layer of one array, so probes cost no texture units at all — the same thing
+ * the octahedral change bought the point lights, arrived at the same way. What they do cost is
+ * storage: a layer at the default size is 683 KB with its chain, so 64 layers is **43.7 MB**,
+ * comfortably under the 92.3 MB `pointShadowArray.ts` already spends.
+ *
+ * WebGL2 guarantees `MAX_ARRAY_TEXTURE_LAYERS` of 256, which would be 175 MB and is the number
+ * this is *not* set to. Raising it is an arithmetic decision about memory and the arithmetic is
+ * written here so nobody has to re-derive it.
+ */
+export declare const MAX_ENV_PROBES = 64;
+/**
+ * The lattice a single baked probe is, and the origin a loaded environment sits at.
+ *
+ * **Here rather than in either backend**, per the rule `prefilterEnvMap.ts` states at length: a
+ * value one backend defines is a decision the other cannot reach, so it gets restated there and the
+ * two drift. Both renderers turn `bakeReflectionProbe` into a grid of one, and they have to turn it
+ * into the *same* grid or a scene renders differently on each.
+ *
+ * A step is required even here, because `ProbeGrid` refuses a zero one — the blend divides by it —
+ * and one metre is the honest arbitrary choice for a grid with no extent.
+ */
+export declare const SINGLE_PROBE: Vec3;
+export declare const UNIT_STEP: Vec3;
+export declare const WORLD_ORIGIN: Vec3;
+/**
+ * Whether a declared grid is the one already allocated.
+ *
+ * `texStorage3D` and `createTexture` are both immutable in the size they take, so a grid that has
+ * not changed must not reallocate: `bakeReflectionProbe` declares its grid of one on every call,
+ * and a scene rebaking each frame would otherwise throw away its layers every frame.
+ */
+export declare function sameGrid(a: ProbeGrid, b: ProbeGrid): boolean;
+export declare class ProbeGrid {
+    readonly origin: Vec3;
+    readonly spacing: Vec3;
+    readonly counts: Vec3;
+    /** Probes in total, which is also the array's layer count. */
+    readonly layers: number;
+    /** The reciprocal of the spacing, because the shader multiplies and so does everything here. */
+    readonly invSpacing: Vec3;
+    constructor(options: ProbeGridOptions);
+    /**
+     * The layer a probe at whole lattice coordinates occupies.
+     *
+     * **x fastest, then y, then z**, and the order is written down because the shader computes the
+     * same expression and the two disagreeing would put every fragment's reflection in a different
+     * room. Out-of-range coordinates clamp; see `nearestProbes` for why clamping rather than
+     * wrapping is the behaviour at a grid's edge.
+     */
+    layerAt(ix: number, iy: number, iz: number): number;
+    /** Where a layer's probe stands, filling a vector the caller owns. */
+    positionOf(layer: number, out: Vec3): Vec3;
+}
+/**
+ * The eight probes around a world position, with trilinear weights that sum to one.
+ *
+ * **Clamped at the grid's edge rather than wrapped or faded.** A point outside the grid takes the
+ * nearest probes at full weight, which is the same environment it would have had one step inside —
+ * the honest degradation, and the one a consumer can see coming. Fading to the hemispheric
+ * gradient at the boundary was the alternative and it reads worse: an object walking out of a
+ * grid would change what lights it while nothing about it changed.
+ *
+ * **Weights sum to one everywhere, including outside**, which is what lets the shader multiply
+ * rather than normalise. In a grid one probe wide on an axis, that axis contributes a factor of
+ * one and the eight corners collapse onto fewer layers whose weights add — no branch, and a
+ * `[1, 1, 1]` grid returns the single probe at weight one with the other seven entries pointing
+ * at it too.
+ */
+export declare function nearestProbes(grid: ProbeGrid, x: number, y: number, z: number, out: ProbeBlend): ProbeBlend;

package/dist/render/probeGrid.js

@@ -0,0 +1,174 @@
+/** Where environment probes stand, and which of them light a point. */
+/** A blend a caller owns and reuses. */
+export function createProbeBlend() {
+    return { layers: new Int32Array(8), weights: new Float32Array(8) };
+}
+/**
+ * How many layers a grid may hold, and it is a memory limit rather than a binding one.
+ *
+ * Every probe is one layer of one array, so probes cost no texture units at all — the same thing
+ * the octahedral change bought the point lights, arrived at the same way. What they do cost is
+ * storage: a layer at the default size is 683 KB with its chain, so 64 layers is **43.7 MB**,
+ * comfortably under the 92.3 MB `pointShadowArray.ts` already spends.
+ *
+ * WebGL2 guarantees `MAX_ARRAY_TEXTURE_LAYERS` of 256, which would be 175 MB and is the number
+ * this is *not* set to. Raising it is an arithmetic decision about memory and the arithmetic is
+ * written here so nobody has to re-derive it.
+ */
+export const MAX_ENV_PROBES = 64;
+/**
+ * The lattice a single baked probe is, and the origin a loaded environment sits at.
+ *
+ * **Here rather than in either backend**, per the rule `prefilterEnvMap.ts` states at length: a
+ * value one backend defines is a decision the other cannot reach, so it gets restated there and the
+ * two drift. Both renderers turn `bakeReflectionProbe` into a grid of one, and they have to turn it
+ * into the *same* grid or a scene renders differently on each.
+ *
+ * A step is required even here, because `ProbeGrid` refuses a zero one — the blend divides by it —
+ * and one metre is the honest arbitrary choice for a grid with no extent.
+ */
+export const SINGLE_PROBE = [1, 1, 1];
+export const UNIT_STEP = [1, 1, 1];
+export const WORLD_ORIGIN = [0, 0, 0];
+/**
+ * Whether a declared grid is the one already allocated.
+ *
+ * `texStorage3D` and `createTexture` are both immutable in the size they take, so a grid that has
+ * not changed must not reallocate: `bakeReflectionProbe` declares its grid of one on every call,
+ * and a scene rebaking each frame would otherwise throw away its layers every frame.
+ */
+export function sameGrid(a, b) {
+    for (let axis = 0; axis < 3; axis++) {
+        if (a.counts[axis] !== b.counts[axis])
+            return false;
+        if (a.origin[axis] !== b.origin[axis])
+            return false;
+        if (a.spacing[axis] !== b.spacing[axis])
+            return false;
+    }
+    return true;
+}
+export class ProbeGrid {
+    origin;
+    spacing;
+    counts;
+    /** Probes in total, which is also the array's layer count. */
+    layers;
+    /** The reciprocal of the spacing, because the shader multiplies and so does everything here. */
+    invSpacing;
+    constructor(options) {
+        const counts = [
+            Math.max(1, Math.trunc(options.counts[0])),
+            Math.max(1, Math.trunc(options.counts[1])),
+            Math.max(1, Math.trunc(options.counts[2])),
+        ];
+        const layers = counts[0] * counts[1] * counts[2];
+        /*
+         * **Fail fast at init**, per `AGENTS.md`, and say the arithmetic rather than the rule. A grid
+         * too large to allocate is a consumer's typo far more often than an intention, and the cost of
+         * finding out at `texStorage3D` is a device-lost message with nothing in it about probes.
+         */
+        if (layers > MAX_ENV_PROBES) {
+            throw new Error(`ProbeGrid: ${counts[0]}x${counts[1]}x${counts[2]} is ${layers} probes and the limit is ` +
+                `${MAX_ENV_PROBES}. Each is one layer of one array texture; see MAX_ENV_PROBES for what ` +
+                `raising it costs in memory.`);
+        }
+        for (let axis = 0; axis < 3; axis++) {
+            const step = options.spacing[axis] ?? 0;
+            /*
+             * A zero step is a division by zero one line into `nearestProbes`, and the NaN it produces
+             * reaches the shader as a probe weight — which reads as the environment being wrong
+             * everywhere rather than as a grid being declared wrong once.
+             */
+            if (!(step > 0)) {
+                throw new Error(`ProbeGrid: spacing on axis ${axis} is ${String(step)}; every component must be ` +
+                    `positive. A grid one probe wide on an axis still needs a step, since the step is ` +
+                    `what the blend divides by.`);
+            }
+        }
+        this.origin = [options.origin[0], options.origin[1], options.origin[2]];
+        this.spacing = [options.spacing[0], options.spacing[1], options.spacing[2]];
+        this.invSpacing = [1 / this.spacing[0], 1 / this.spacing[1], 1 / this.spacing[2]];
+        this.counts = counts;
+        this.layers = layers;
+    }
+    /**
+     * The layer a probe at whole lattice coordinates occupies.
+     *
+     * **x fastest, then y, then z**, and the order is written down because the shader computes the
+     * same expression and the two disagreeing would put every fragment's reflection in a different
+     * room. Out-of-range coordinates clamp; see `nearestProbes` for why clamping rather than
+     * wrapping is the behaviour at a grid's edge.
+     */
+    layerAt(ix, iy, iz) {
+        const x = clampIndex(ix, this.counts[0]);
+        const y = clampIndex(iy, this.counts[1]);
+        const z = clampIndex(iz, this.counts[2]);
+        return x + this.counts[0] * (y + this.counts[1] * z);
+    }
+    /** Where a layer's probe stands, filling a vector the caller owns. */
+    positionOf(layer, out) {
+        const index = clampIndex(layer, this.layers);
+        const x = index % this.counts[0];
+        const y = Math.floor(index / this.counts[0]) % this.counts[1];
+        const z = Math.floor(index / (this.counts[0] * this.counts[1]));
+        out[0] = this.origin[0] + x * this.spacing[0];
+        out[1] = this.origin[1] + y * this.spacing[1];
+        out[2] = this.origin[2] + z * this.spacing[2];
+        return out;
+    }
+}
+/**
+ * The eight probes around a world position, with trilinear weights that sum to one.
+ *
+ * **Clamped at the grid's edge rather than wrapped or faded.** A point outside the grid takes the
+ * nearest probes at full weight, which is the same environment it would have had one step inside —
+ * the honest degradation, and the one a consumer can see coming. Fading to the hemispheric
+ * gradient at the boundary was the alternative and it reads worse: an object walking out of a
+ * grid would change what lights it while nothing about it changed.
+ *
+ * **Weights sum to one everywhere, including outside**, which is what lets the shader multiply
+ * rather than normalise. In a grid one probe wide on an axis, that axis contributes a factor of
+ * one and the eight corners collapse onto fewer layers whose weights add — no branch, and a
+ * `[1, 1, 1]` grid returns the single probe at weight one with the other seven entries pointing
+ * at it too.
+ */
+export function nearestProbes(grid, x, y, z, out) {
+    const lx = cellCoordinate(x, grid.origin[0], grid.invSpacing[0], grid.counts[0]);
+    const ly = cellCoordinate(y, grid.origin[1], grid.invSpacing[1], grid.counts[1]);
+    const lz = cellCoordinate(z, grid.origin[2], grid.invSpacing[2], grid.counts[2]);
+    let slot = 0;
+    for (let cz = 0; cz < 2; cz++) {
+        const wz = cz === 0 ? 1 - lz.fraction : lz.fraction;
+        for (let cy = 0; cy < 2; cy++) {
+            const wy = cy === 0 ? 1 - ly.fraction : ly.fraction;
+            for (let cx = 0; cx < 2; cx++) {
+                const wx = cx === 0 ? 1 - lx.fraction : lx.fraction;
+                out.layers[slot] = grid.layerAt(lx.index + cx, ly.index + cy, lz.index + cz);
+                out.weights[slot] = wx * wy * wz;
+                slot++;
+            }
+        }
+    }
+    return out;
+}
+/**
+ * One axis of the lookup: which probe is below the point, and how far past it the point is.
+ *
+ * The lower index stops one short of the last probe so the pair `index` and `index + 1` is always
+ * inside the grid, and a single-probe axis has no pair at all — both corners are probe zero and
+ * the fraction is zero, so that axis multiplies every weight by one.
+ */
+function cellCoordinate(value, origin, invSpacing, count) {
+    if (count <= 1)
+        return { index: 0, fraction: 0 };
+    const local = (value - origin) * invSpacing;
+    const clamped = local <= 0 ? 0 : local >= count - 1 ? count - 1 : local;
+    const index = Math.min(Math.floor(clamped), count - 2);
+    return { index, fraction: clamped - index };
+}
+/** A whole index forced into a range, for the two lookups that accept anything. */
+function clampIndex(value, count) {
+    const index = Math.trunc(value);
+    return index <= 0 ? 0 : index >= count - 1 ? count - 1 : index;
+}