@driftengine/core 3.63.0 → 4.1.0

package/dist/render/gi/globalField.js

@@ -0,0 +1,373 @@
+/** The world near the camera as one distance field, assembled from the objects standing in it. */
+import { mat4 } from 'gl-matrix';
+/**
+ * How much of a cascade's extent, at each face, fades into the cascade outside it.
+ *
+ * **A hard switch between cascades is worse than either cascade's own error.** An error that is
+ * wrong everywhere reads as a coarse solution; one that changes abruptly along a surface reads as
+ * a crack, and the crack moves with the camera because the boundary does. A tenth of the extent
+ * is wide enough that the fade is below a voxel per step and narrow enough that the inner
+ * cascade's resolution is what most of the inner cascade actually delivers.
+ */
+export const GLOBAL_FIELD_BLEND = 0.1;
+/** Allocate a field. Called once; `composeGlobalField` fills it and allocates nothing. */
+export function createGlobalField(resolution, cascades) {
+    const samples = Math.trunc(resolution);
+    if (!(samples >= 2)) {
+        throw new Error(`createGlobalField: resolution is ${String(resolution)} and the minimum is 2. One sample on ` +
+            'an axis has nothing to interpolate between.');
+    }
+    const levels = Math.trunc(cascades);
+    if (!(levels >= 1)) {
+        throw new Error(`createGlobalField: cascade count is ${String(cascades)} and the minimum is 1.`);
+    }
+    const out = [];
+    for (let level = 0; level < levels; level++) {
+        out.push({
+            field: new Float32Array(samples ** 3),
+            albedo: new Float32Array(samples ** 3 * 3),
+            dims: [samples, samples, samples],
+            bounds: new Float32Array(6),
+            step: 0,
+        });
+    }
+    return { cascades: out };
+}
+/**
+ * Put one cascade where the camera is, and answer its half-extent.
+ *
+ * **Exported because the compute path needs the same placement and two spellings drift.** A pass
+ * filling these on a device has to agree with this about where every cascade stands, to the last
+ * bit: disagree by a fraction of a step and the fade between cascades lands somewhere different on
+ * each side, which is a seam that appears only when both paths are compared.
+ *
+ * The snapping is the decision. See `composeGlobalField` for why a grid centred on the exact camera
+ * position makes the whole field shimmer.
+ */
+export function placeCascade(cascade, level, radius, cameraPos) {
+    const half = radius * 2 ** level;
+    const step = (2 * half) / (cascade.dims[0] - 1);
+    cascade.step = step;
+    for (let axis = 0; axis < 3; axis++) {
+        const centre = Math.round(cameraPos[axis] / step) * step;
+        cascade.bounds[axis] = centre - half;
+        cascade.bounds[axis + 3] = centre + half;
+    }
+    return half;
+}
+/** Scratch the composer reuses, because it runs once a frame and the rule about that is absolute. */
+const INVERSE = new Float32Array(16);
+const OBJECT = new Float32Array(3);
+/** The nearest point of a source's box to the sample, for the bound outside it. */
+const CLAMPED = new Float32Array(3);
+/**
+ * Fill every cascade from the instances standing near the camera.
+ *
+ * `radius` is the innermost cascade's half-extent in metres; each cascade outside it reaches twice
+ * as far at the same sample count.
+ *
+ * **Every cascade's centre is snapped to a multiple of its own step, and that is the decision this
+ * function exists to make.** A grid centred on the exact camera position resamples the entire
+ * world at a new sub-pixel offset every frame, so every value changes slightly every frame and the
+ * indirect light shimmers — worst on a slow camera, which is exactly when a viewer is looking at
+ * it. Snapped, a camera move is either nothing at all or a whole voxel, and a whole voxel leaves
+ * every sample the two grids share bit-identical.
+ *
+ * **A point no instance is near takes the cascade's own reach rather than infinity.** That is an
+ * underestimate of the true distance, which is the safe direction: a march that steps by it takes
+ * a shorter step than it could and converges anyway, where an overestimate steps through the wall
+ * it was meant to stop at.
+ *
+ * **This is the reference, and it visits every sample of every cascade for every instance that is
+ * not culled outright.** `scripts/gpu-parity.mjs` is the pattern the WGSL will be checked against,
+ * and the WGSL is where the brick culling belongs — a CPU implementation that was already
+ * accelerated would be a second thing to be wrong rather than the thing the first is checked by.
+ */
+export function composeGlobalField(instances, cameraPos, radius, out) {
+    if (!(radius > 0)) {
+        throw new Error(`composeGlobalField: radius is ${String(radius)} and must be positive.`);
+    }
+    for (const instance of instances) {
+        assertUniformScale(instance.transform);
+        assertCubicVoxels(instance.source);
+    }
+    for (let level = 0; level < out.cascades.length; level++) {
+        const cascade = out.cascades[level];
+        const half = placeCascade(cascade, level, radius, cameraPos);
+        const [nx, ny, nz] = cascade.dims;
+        const step = cascade.step;
+        /* The reach, which is both the initial value and the distance past which an instance cannot
+           change one — so it is also what culls an instance whose box is further away than that. */
+        cascade.field.fill(half);
+        /* White, so a sample no instance reached is neutral. See `GlobalFieldCascade.albedo`. */
+        cascade.albedo.fill(1);
+        const ox = cascade.bounds[0];
+        const oy = cascade.bounds[1];
+        const oz = cascade.bounds[2];
+        for (const instance of instances) {
+            const albedo = instance.albedo;
+            const ar = albedo === undefined ? 1 : (albedo[0] ?? 1);
+            const ag = albedo === undefined ? 1 : (albedo[1] ?? 1);
+            const ab = albedo === undefined ? 1 : (albedo[2] ?? 1);
+            const scale = uniformScaleOf(instance.transform);
+            if (mat4.invert(INVERSE, instance.transform) === null)
+                continue;
+            /*
+             * **An instance further from this cascade than the cascade's own reach cannot change a
+             * single sample in it**, because every sample already holds the reach and the minimum keeps
+             * the smaller. So this is a pure speed decision and no test can see it: 64 instances over a
+             * kilometre with four of them near the camera, four cascades of 33, compose in **19.4 ms
+             * with this line and 150.2 ms without it**, to bit-identical output. Recorded as a
+             * measurement for that reason — `sdf.ts`'s `NEIGHBOURS` is the same situation arriving from
+             * the other direction, where the measurement said the extra work bought nothing.
+             */
+            if (boxDistance(instance, INVERSE, scale, ox, oy, oz, ox + 2 * half, oy + 2 * half, oz + 2 * half) > half) {
+                continue;
+            }
+            for (let iz = 0; iz < nz; iz++) {
+                const wz = oz + iz * step;
+                for (let iy = 0; iy < ny; iy++) {
+                    const wy = oy + iy * step;
+                    for (let ix = 0; ix < nx; ix++) {
+                        const index = ix + nx * (iy + ny * iz);
+                        const current = cascade.field[index];
+                        const distance = sampleInstance(instance, INVERSE, scale, ox + ix * step, wy, wz);
+                        /* **The minimum, because the union of two solids is the nearer surface.** A maximum
+                           is the intersection and carves a groove along the seam of every wall that meets
+                           another wall, with the sign right on both sides of it. */
+                        /* **Written only where the instance won**, which is what makes the colour the
+                           nearest surface's rather than the last one's. A composer that wrote it beside the
+                           comparison would paint the whole field with whichever instance came last. */
+                        if (distance < current) {
+                            cascade.field[index] = distance;
+                            cascade.albedo[index * 3] = ar;
+                            cascade.albedo[index * 3 + 1] = ag;
+                            cascade.albedo[index * 3 + 2] = ab;
+                        }
+                    }
+                }
+            }
+        }
+    }
+}
+/**
+ * The field at a world point, from the finest cascade that holds it.
+ *
+ * A point past every cascade reads the outermost one clamped to its edge, rather than a sentinel:
+ * a caller marching outward wants a number it can step by, and the outermost cascade's own reach
+ * is the honest one.
+ */
+export function sampleGlobalField(field, x, y, z) {
+    const last = field.cascades.length - 1;
+    for (let level = 0; level <= last; level++) {
+        const cascade = field.cascades[level];
+        const inside = insideBy(cascade, x, y, z);
+        if (inside <= 0)
+            continue;
+        const value = trilinear(cascade, x, y, z);
+        if (level === last)
+            return value;
+        const band = GLOBAL_FIELD_BLEND * (cascade.bounds[3] - cascade.bounds[0]);
+        if (inside >= band)
+            return value;
+        const outer = trilinear(field.cascades[level + 1], x, y, z);
+        const weight = inside / band;
+        return outer + (value - outer) * weight;
+    }
+    return trilinear(field.cascades[last], x, y, z);
+}
+/** How far inside a cascade a point is, measured to the nearest face. Negative means outside. */
+function insideBy(cascade, x, y, z) {
+    const p = [x, y, z];
+    let least = Infinity;
+    for (let axis = 0; axis < 3; axis++) {
+        const min = cascade.bounds[axis];
+        const max = cascade.bounds[axis + 3];
+        least = Math.min(least, p[axis] - min, max - p[axis]);
+    }
+    return least;
+}
+/**
+ * The distance one instance reports at a world point.
+ *
+ * **The world point is carried into object space through the inverse**, which is the transform
+ * every implementation gets wrong first — and a sphere cannot see the mistake, because a sphere is
+ * invariant under every rotation. Using the placement matrix itself puts the object at the mirror
+ * of where it was asked to stand.
+ *
+ * **Outside the source's own box, the distance to the box is a bound and on its own it is a
+ * useless one.** Every surface the field describes is inside the box, so nothing can be nearer
+ * than the box is — true, and just outside the box it says *zero*, which is an underestimate of a
+ * distance that is really most of a metre. Safe for a march in the sense that it never steps
+ * through anything, and fatal in practice: a sphere trace stops where the field falls under its
+ * epsilon, so a shell of near-zero around every instance's bounding box is a **phantom surface**.
+ * It draws as dark fins radiating from every object, which is how it was found — by looking at
+ * `demo/giFieldRig.ts`, after `globalField.test.ts`'s "never overestimates" passed it happily,
+ * zero being an underestimate of everything.
+ *
+ * So the bound is taken against the field's own value at the nearest point of the box as well:
+ * `d(q) >= d(c) - |q - c|` by the triangle inequality, and `d(q) >= |q - c|` because the surface
+ * is inside. The larger of the two is still an underestimate and is the useful one — it reports
+ * the real clearance just outside the box and falls back to the box distance far away.
+ */
+function sampleInstance(instance, inverse, scale, x, y, z) {
+    const source = instance.source;
+    OBJECT[0] =
+        inverse[0] * x +
+            inverse[4] * y +
+            inverse[8] * z +
+            inverse[12];
+    OBJECT[1] =
+        inverse[1] * x +
+            inverse[5] * y +
+            inverse[9] * z +
+            inverse[13];
+    OBJECT[2] =
+        inverse[2] * x +
+            inverse[6] * y +
+            inverse[10] * z +
+            inverse[14];
+    let outsideSq = 0;
+    for (let axis = 0; axis < 3; axis++) {
+        const min = source.bounds[axis];
+        const max = source.bounds[axis + 3];
+        const value = OBJECT[axis];
+        CLAMPED[axis] = value < min ? min : value > max ? max : value;
+        const over = value - CLAMPED[axis];
+        outsideSq += over * over;
+    }
+    if (outsideSq > 0) {
+        const outside = Math.sqrt(outsideSq);
+        const atBox = sourceAt(source, CLAMPED[0], CLAMPED[1], CLAMPED[2]);
+        return Math.max(outside, atBox - outside) * scale;
+    }
+    return sourceAt(source, OBJECT[0], OBJECT[1], OBJECT[2]) * scale;
+}
+/** How far an instance's box is from a cascade's, so an instance too far away is skipped whole. */
+function boxDistance(instance, inverse, scale, minX, minY, minZ, maxX, maxY, maxZ) {
+    /*
+     * The nearest point of the cascade to the instance's own centre, then that point's distance to
+     * the instance's box. Conservative in the right direction: it never reports further than the
+     * true separation, so an instance that could contribute is never culled.
+     */
+    const centre = instance.source.bounds;
+    const world = instance.transform;
+    const cx = (centre[0] + centre[3]) / 2;
+    const cy = (centre[1] + centre[4]) / 2;
+    const cz = (centre[2] + centre[5]) / 2;
+    const wx = world[0] * cx +
+        world[4] * cy +
+        world[8] * cz +
+        world[12];
+    const wy = world[1] * cx +
+        world[5] * cy +
+        world[9] * cz +
+        world[13];
+    const wz = world[2] * cx +
+        world[6] * cy +
+        world[10] * cz +
+        world[14];
+    const nearX = Math.min(Math.max(wx, minX), maxX);
+    const nearY = Math.min(Math.max(wy, minY), maxY);
+    const nearZ = Math.min(Math.max(wz, minZ), maxZ);
+    return sampleInstance(instance, inverse, scale, nearX, nearY, nearZ);
+}
+/** Trilinear read of a cascade, clamped at its own edge. */
+function trilinear(cascade, x, y, z) {
+    return read(cascade.field, cascade.dims, cascade.bounds, cascade.step, x, y, z);
+}
+/** Trilinear read of a source field, whose step this has to derive from its own bounds. */
+function sourceAt(source, x, y, z) {
+    const step = (source.bounds[3] - source.bounds[0]) /
+        (source.dims[0] - 1);
+    return read(source.field, source.dims, source.bounds, step, x, y, z);
+}
+/** The one trilinear read both grids use, so the two cannot disagree about the layout. */
+function read(field, dims, bounds, step, x, y, z) {
+    const [nx, ny, nz] = dims;
+    const counts = [nx, ny, nz];
+    const p = [x, y, z];
+    const low = [0, 0, 0];
+    const fraction = [0, 0, 0];
+    for (let axis = 0; axis < 3; axis++) {
+        const count = counts[axis];
+        const local = (p[axis] - bounds[axis]) / step;
+        const clamped = local <= 0 ? 0 : local >= count - 1 ? count - 1 : local;
+        const index = Math.min(Math.floor(clamped), count - 2);
+        low[axis] = index;
+        fraction[axis] = clamped - index;
+    }
+    const [lx, ly, lz] = low;
+    const [fx, fy, fz] = fraction;
+    let total = 0;
+    for (let cz = 0; cz < 2; cz++) {
+        const wz = cz === 0 ? 1 - fz : fz;
+        for (let cy = 0; cy < 2; cy++) {
+            const wy = cy === 0 ? 1 - fy : fy;
+            for (let cx = 0; cx < 2; cx++) {
+                const wx = cx === 0 ? 1 - fx : fx;
+                const index = lx + cx + nx * (ly + cy + ny * (lz + cz));
+                total += field[index] * wx * wy * wz;
+            }
+        }
+    }
+    return total;
+}
+/** The scale a transform applies, refusing one that differs between axes. See `transform`. */
+function uniformScaleOf(transform) {
+    return Math.hypot(transform[0], transform[1], transform[2]);
+}
+/**
+ * Refuse a source whose voxels are not cubic, which `sourceAt` and the shader both assume.
+ *
+ * **One step for all three axes is the contract, and it was unwritten until it cost a feature.**
+ * `bakeObjectSdf` picks its step from the object's longest axis and gives each axis whatever count
+ * it needs at that step, so `dims` differ per axis and the spacing does not. Both readers rely on
+ * that: `sourceAt` here derives the step from x alone, and `composeField.wgsl.ts` says so in a
+ * comment. A source sampled with the same count on every axis of a box that is not a cube has
+ * oblong voxels, and every sample of it is taken at the wrong place along y and z — far enough
+ * wrong that a point at the centre of a slab reads the slab's corner.
+ *
+ * **Measured on `demo/dev/bounce.html`**, whose room is five such slabs: the composed field held
+ * almost no room, 98.9% of every probe's rays left a closed room, and the traced bounce delivered a
+ * thirty-fifth of the light. Nothing failed; the field was simply empty. Refusing is the only
+ * honest answer, because a distance field carries no record of the axis it was sampled along and
+ * there is nothing here to correct it with — the same reason a non-uniform scale is refused above.
+ *
+ * **An axis of one sample is refused here too, and by its own sentence**, because `read` addresses
+ * `index` and `index + 1` on every axis and cannot be given an axis with no pair. `bakeObjectSdf`
+ * never produces one — its counts are a ceiling plus one over a span that includes two voxels of
+ * padding — but `FieldSource` is a shape a consumer may build by hand, which is the whole reason
+ * this function exists.
+ */
+export function assertCubicVoxels(source) {
+    const steps = [0, 1, 2].map((axis) => {
+        const count = source.dims[axis];
+        if (count < 2) {
+            throw new Error(`driftengine: a distance field source is ${source.dims.join('x')} samples and every axis ` +
+                'needs at least two. One sample on an axis has no neighbour to interpolate towards.');
+        }
+        return (source.bounds[axis + 3] - source.bounds[axis]) / (count - 1);
+    });
+    const low = Math.min(...steps);
+    const high = Math.max(...steps);
+    if (high - low <= 1e-3 * high)
+        return;
+    throw new Error(`driftengine: a distance field source's voxels are ${steps
+        .map((step) => step.toFixed(4))
+        .join(' by ')} metres and have to be cubic. Its dims are ${source.dims.join('x')} over a ` +
+        'box that is not that shape; give each axis the count it needs at one step, as ' +
+        'bakeObjectSdf does.');
+}
+function assertUniformScale(transform) {
+    const x = Math.hypot(transform[0], transform[1], transform[2]);
+    const y = Math.hypot(transform[4], transform[5], transform[6]);
+    const z = Math.hypot(transform[8], transform[9], transform[10]);
+    const spread = Math.max(x, y, z) - Math.min(x, y, z);
+    if (spread > 1e-4 * Math.max(x, y, z)) {
+        throw new Error(`composeGlobalField: an instance is scaled ${x.toFixed(3)}, ${y.toFixed(3)}, ` +
+            `${z.toFixed(3)}, and a distance field takes a uniform scale only. There is no factor to ` +
+            'correct a non-uniform one by: it depends on the direction to the nearest surface, which ' +
+            'is what the field does not record.');
+    }
+}

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

@@ -0,0 +1,24 @@
+/**
+ * A probe grid for a scene that asked for indirect light and declared no grid.
+ *
+ * **A declared grid always wins.** This exists so that turning the feature on shows light rather
+ * than a warning, which is the difference between a feature a consumer can try and one they have
+ * to study first. A scene that cares about where its probes stand says so and this is never asked.
+ *
+ * **Every axis carries the same spacing.** Fitting each axis to its own extent would make a probe's
+ * cell a slab, and a slab interpolates over different distances along different axes — so a
+ * surface's indirect light would change as it turned, which is the one thing an irradiance probe
+ * must not do. When the budget bites, the spacing widens uniformly and the cells stay cubic.
+ */
+import type { ProbeGridOptions } from '../probeGrid.ts';
+/**
+ * A grid covering `bounds` at about `spacing` metres, within `maxProbes`.
+ *
+ * The probes surround the scene rather than stopping at it: a surface on the boundary has to be
+ * between probes on both sides of it, and a grid that stopped at the bounds would leave every
+ * outward-facing wall interpolating between probes that are all behind it.
+ */
+export declare function fitProbeGrid(bounds: {
+    readonly min: ArrayLike<number>;
+    readonly max: ArrayLike<number>;
+}, spacing: number, maxProbes: number): ProbeGridOptions;

package/dist/render/gi/probeGridFit.js

@@ -0,0 +1,71 @@
+/**
+ * A probe grid for a scene that asked for indirect light and declared no grid.
+ *
+ * **A declared grid always wins.** This exists so that turning the feature on shows light rather
+ * than a warning, which is the difference between a feature a consumer can try and one they have
+ * to study first. A scene that cares about where its probes stand says so and this is never asked.
+ *
+ * **Every axis carries the same spacing.** Fitting each axis to its own extent would make a probe's
+ * cell a slab, and a slab interpolates over different distances along different axes — so a
+ * surface's indirect light would change as it turned, which is the one thing an irradiance probe
+ * must not do. When the budget bites, the spacing widens uniformly and the cells stay cubic.
+ */
+import {} from '../../math/color.js';
+/** How far outside the scene the outermost probes stand, in cells. */
+const MARGIN_CELLS = 1;
+/**
+ * A grid covering `bounds` at about `spacing` metres, within `maxProbes`.
+ *
+ * The probes surround the scene rather than stopping at it: a surface on the boundary has to be
+ * between probes on both sides of it, and a grid that stopped at the bounds would leave every
+ * outward-facing wall interpolating between probes that are all behind it.
+ */
+export function fitProbeGrid(bounds, spacing, maxProbes) {
+    const budget = Math.max(1, Math.floor(maxProbes));
+    const extent = [0, 1, 2].map((axis) => Math.max(0, bounds.max[axis] - bounds.min[axis]));
+    const centre = [0, 1, 2].map((axis) => (bounds.min[axis] + bounds.max[axis]) / 2);
+    /*
+     * Widened until the whole grid fits the budget, by whole steps rather than by solving for it:
+     * the count is a ceiling of a ratio, so the closed form would still have to be checked and a
+     * loop over a handful of doublings is clearer than a formula nobody can verify by reading.
+     */
+    let step = Math.max(1e-3, spacing);
+    let counts = countsFor(extent, step);
+    while (counts[0] * counts[1] * counts[2] > budget && step < 1e9) {
+        step *= 1.5;
+        counts = countsFor(extent, step);
+    }
+    /*
+     * **A budget too small for a margin collapses to one probe**, which is not a special case
+     * anywhere: `probeGrid.ts` says a world that bakes one environment is a grid of one, through the
+     * same array, convolution and shader. An axis with any extent needs three probes to surround it,
+     * so the smallest grid that surrounds anything is twenty-seven — and a budget below that cannot
+     * be met by widening, however far the step goes.
+     */
+    if (counts[0] * counts[1] * counts[2] > budget) {
+        return {
+            origin: [centre[0], centre[1], centre[2]],
+            spacing: [step, step, step],
+            counts: [1, 1, 1],
+        };
+    }
+    const origin = [0, 0, 0];
+    for (let axis = 0; axis < 3; axis += 1) {
+        /* Centred on the scene, so the margin outside each face is the same. */
+        origin[axis] = centre[axis] - (step * (counts[axis] - 1)) / 2;
+    }
+    return {
+        origin,
+        spacing: [step, step, step],
+        counts: [counts[0], counts[1], counts[2]],
+    };
+}
+/**
+ * Probes an axis needs to span `extent` at `step`, with a cell of margin at each end.
+ *
+ * At least one, always: an axis with no extent — a scene that is a floor, or a point — is a single
+ * probe rather than a count of zero, which would make the grid empty and the shading read nothing.
+ */
+function countsFor(extent, step) {
+    return extent.map((length) => length <= 0 ? 1 : Math.ceil(length / step) + 1 + 2 * MARGIN_CELLS - 1);
+}

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

@@ -0,0 +1,82 @@
+/**
+ * What a probe asks the indirect chain, and what it does with the answers.
+ *
+ * **A probe's measurement is an octahedral irradiance map**, because that is what the shading
+ * already samples: `gridIrradiance` in `shaders/flat/probeGrid.ts` blends eight probes and reads
+ * each through `probeIrradiance(dir, layer)`. So nothing downstream of a probe changes — only where
+ * the numbers in that map came from. Today they come from six rasterised faces of the world;
+ * `chain.ts` is what they come from once this is wired up, and the difference is a second bounce
+ * and radiance from surfaces that were never in frame.
+ *
+ * **Why a spherical Fibonacci spiral and not random directions.** At a few hundred samples a random
+ * set leaves holes and pairs, and a probe with a hole in its sphere has looked at part of its world
+ * and reports all of it — as a dark patch in a direction nothing happened to be traced along. The
+ * spiral's points are as far from each other as the count allows, and its cost is one sine and one
+ * cosine a direction.
+ *
+ * **And the set turns every frame, which is what makes a probe converge.** A fixed set measures the
+ * same few hundred directions for ever, so whatever it misses it misses permanently. Rotating it by
+ * an irrational fraction of a turn each refresh means successive refreshes sample different
+ * directions, and the accumulation over a few refreshes is a denser set than any one of them.
+ */
+/**
+ * Why a scene is not lit by what bounces on WebGL2, in words, so both backends read one sentence.
+ *
+ * **A probe is a few hundred rays and that is a compute dispatch.** This backend has no compute
+ * stage, and the alternatives are both worse than saying so: tracing on the processor is a
+ * main-thread cost proportional to the grid, and approximating with more frequent cube bakes means
+ * the two backends light one scene differently — which is the disagreement every published scene's
+ * pixel gate exists to prevent.
+ *
+ * Written here rather than in either renderer for the reason `OIT_MULTISAMPLE_REFUSAL` is written
+ * outside both: it is a decision the two share, so it belongs where neither owns it.
+ */
+export declare const INDIRECT_LIGHT_WEBGL2_REFUSAL: string;
+/**
+ * Directions a probe traces per refresh.
+ *
+ * **A few hundred, and the number is a cost rather than a quality.** A refresh is this many rays
+ * down a three-level chain, and `probeUpdateSchedule` decides how many probes pay it a frame. The
+ * convergence comes from the rotation between refreshes, not from this count, so it is set where a
+ * single refresh is already recognisable rather than where one refresh is final.
+ */
+export declare const PROBE_DIRECTIONS = 256;
+/**
+ * The golden angle, which is what spaces a spiral's points as far apart as a count allows.
+ *
+ * Exported because `shaders/gi/probeBake.wgsl.ts` interpolates it: a shader cannot import a
+ * constant, so the choice is one value written here and pasted in, or two literals kept in step by
+ * hand. `probe-bake-parity.mjs` checks the result either way, but only one of them can be right by
+ * construction.
+ */
+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
+ * as the sequence allows, for the same reason the spiral's own points do, and it never repeats.
+ */
+export declare const FRAME_TURN = 0.618033988749895;
+/**
+ * Direction `index` of the set this `frame` traces, into `out`.
+ *
+ * The spiral runs `z` from near `+1` to near `-1` in equal steps and turns by the golden angle at
+ * each, which is the construction whose points are evenly spread on a sphere; the frame's own
+ * rotation is added to that turn.
+ */
+export declare function probeDirection(index: number, frame: number, out: Float32Array): void;
+/**
+ * The cosine convolution of `count` radiance samples into an octahedral map of `edge` texels.
+ *
+ * Each texel's direction is the normal of a surface facing that way, and its value is the
+ * irradiance such a surface receives: every sample weighted by how much of its hemisphere it
+ * occupies, which for a cosine lobe is `max(0, dot(normal, direction))`.
+ *
+ * **Normalised by the weights that were actually used, and that is the whole of the white-furnace
+ * property.** Dividing by an analytic constant — pi, or the sample count — is right only in the
+ * limit and wrong for any finite set, so a uniformly white sphere would convolve to something
+ * slightly other than white and a room would brighten or darken a little at every refresh. Dividing
+ * by the sum of the weights is exact for any set, and it is what makes a constant come back
+ * constant to the last place a float holds.
+ */
+export declare function convolveProbe(samples: Float32Array, directions: Float32Array, count: number, edge: number, out: Float32Array): void;