@driftengine/core 3.61.0

package/dist/render/pointShadowSystem.d.ts

@@ -0,0 +1,195 @@
+import type { PointShadowSource, ResolvedPointShadows } from './pointShadowImage.ts';
+/**
+ * A pool of point-light shadow maps and the fixed set the shader samples.
+ *
+ * World lights do not own maps. They borrow one from a pool of
+ * `POINT_SHADOW_POOL`, handed out to whichever lights the shading pass chose and
+ * reclaimed from whichever was sampled least recently. Live maps contain moving
+ * casters only, so they compose with the borrowed maps rather than overwriting
+ * them. Normally one is active; both are used briefly while ownership crossfades
+ * to another light.
+ *
+ * **It used to be one permanent map per light**, which read as the generous
+ * choice and was the renderer's worst bug: a world with 50 lights allocated
+ * roughly 327 MB of cubemaps so that eight of them could be read. See
+ * `POINT_SHADOW_POOL` for what that did to integrated GPUs. Borrowing costs a
+ * six-face bake when a light enters the sampled set after being away, and buys
+ * back memory that scales with the light *budget* rather than with how many lamps
+ * the day's world happened to generate.
+ *
+ * Nothing is lost visually, and that is the point rather than a hope: a light
+ * outside the sampled set has no `samplerCube` bound to it and could not be read
+ * however long its map was kept.
+ *
+ * Selection is adopted from the shading pass verbatim. If lighting and shadow
+ * code choose independently, a small camera movement can reorder the two sets
+ * and make a lamp's static shadow switch off while its illumination remains.
+ */
+export interface ShadowLight {
+    x: number;
+    y: number;
+    z: number;
+    /** Distance at which the light falls to zero; the map's far plane. */
+    radius: number;
+    /** Where casting begins. Keep small — it clips every caster, not just fixtures. */
+    shadowNear: number;
+    /** Physical emitter radius in metres; it controls penumbra width. */
+    sourceRadius: number;
+    /**
+     * Whether this light is worth a cubemap at all. Defaults to true.
+     *
+     * The same flag `PointLightSource` carries, declared here because the renderer checks
+     * it against the *shaded* set before handing out a pool slot. It used to be read only
+     * while building the eligible list, so a light that declined to cast still got a map
+     * whenever it was one of the lights being shaded — which is every light near the
+     * camera, and so every light whose bake anybody would notice.
+     */
+    castsShadow?: boolean;
+}
+/**
+ * The shader's own name for the point-shadow array.
+ *
+ * Exported because *both* backends address it: WebGL2 looks it up in its uniform table and
+ * WebGPU looks it up in the generated binding table. One name, so the two cannot bind different
+ * things.
+ *
+ * **It was twelve names, one per cubemap sampler**, because GLSL ES cannot index a sampler
+ * array with a non-constant expression and the shader therefore declared each map separately.
+ * One array texture with a layer per light needs one.
+ */
+export declare const POINT_SHADOW_SAMPLER = "uPointShadows";
+export declare class PointShadowSystem<M extends PointShadowSource> {
+    private readonly createMap;
+    private readonly releaseMap;
+    /** The pool. Indexed by pool slot, never by world light. */
+    private readonly maps;
+    private readonly live;
+    private staticLightCount;
+    /** Which world light currently holds each pool slot, or -1 while free. */
+    private readonly slotOwner;
+    /** The lights held ready but not shaded, so joining the sampled set costs no bake. */
+    private readonly warm;
+    private warmCount;
+    /** Frame stamp of the last time each slot was wanted, for the eviction choice. */
+    private readonly slotUsed;
+    /** Reverse of `slotOwner`: pool slot per world light, or -1 while unassigned. */
+    private lightSlot;
+    private useStamp;
+    private readonly chosen;
+    /** Shader light slot each chosen world map belongs to. */
+    private readonly slots;
+    private chosenCount;
+    /** Batched array uniforms; WebGL exposes each array at its `[0]` location. */
+    private readonly far;
+    private readonly near;
+    private readonly sourceRadius;
+    /** How present each bound map is, so a re-baked one arrives rather than appears. */
+    private readonly presence;
+    /**
+     * `createMap` rather than a context and a size, so the pool never names a device.
+     *
+     * The whole of this class is pooling, staleness and selection — decisions a second backend
+     * must make identically or its shadows change hands at different moments. Taking a factory is
+     * what lets both share it; see `PointShadowSource`.
+     */
+    constructor(createMap: (layer: number) => M, releaseMap: (map: M) => void);
+    /**
+     * Size the pool and forget every assignment. Called once the light count is known.
+     *
+     * The pool is capped at `POINT_SHADOW_POOL` however many lights the caller has,
+     * and at the light count when that is smaller — a world with three lamps has no
+     * use for twelve cubemaps.
+     */
+    prepareStaticMaps(lightCount: number): void;
+    /**
+     * The map a light is currently borrowing, if any.
+     *
+     * A pure lookup: assignment happens once a frame in `sync`, because handing out
+     * slots from here would let a caller iterating lights evict the map it is about
+     * to read.
+     */
+    mapForLight(lightIndex: number): M | undefined;
+    /** Adopt the shading pass's world-light list, including its exact order. */
+    sync(activeWorldIndices: Int32Array, activeCount: number, warmWorldIndices?: Int32Array, warmCount?: number): void;
+    /**
+     * Give every chosen light a pool slot, evicting the least recently wanted.
+     *
+     * One stamp for the whole call, so every light chosen this frame is equally
+     * recent and `claimSlot` can refuse to evict any of them.
+     */
+    private assignSlots;
+    private give;
+    /**
+     * Take a free slot, or the one wanted longest ago.
+     *
+     * Slots already stamped with this frame belong to lights the shader is about to
+     * read, so they are never candidates. The pool has more slots than
+     * `MAX_POINT_LIGHTS`, so a candidate always exists.
+     */
+    private claimSlot;
+    /** Ramp every pooled image toward full presence. See `PointShadowMap.advance`. */
+    /**
+     * Ramp every image toward full presence: the pool's, **and the live pair's**.
+     *
+     * The second half was missing, and it is the whole of why a moving caster was never shadowed by
+     * a point light. `this.maps` is the pool; the live pair belongs to `LivePointShadowSet`, which
+     * publishes `crossfade weight * presence` and therefore published zero for ever. Every other
+     * part of that path reports itself healthy, which is what made it survive.
+     */
+    advance(dt: number): void;
+    get sampledCount(): number;
+    /** How many lights hold a slot this frame: the shaded ones plus the warming ones. */
+    get pooledCount(): number;
+    /**
+     * A light holding a slot, shaded ones first.
+     *
+     * The renderer bakes across this rather than across `sampledCount`, which is the
+     * whole point: a warm light's map is baked *before* it is bound, so being chosen
+     * for shading never costs six face passes.
+     */
+    pooledLight(index: number): number;
+    sampledLight(slot: number): number;
+    /**
+     * Select the live shadow around a moving caster and advance any ownership
+     * crossfade. The position is caller-provided and has no gameplay meaning to
+     * the engine.
+     */
+    updateLiveSelection(lights: readonly ShadowLight[], x: number, y: number, z: number, frameDt: number): void;
+    get liveMapCount(): number;
+    liveOwner(slot: number): number;
+    liveMap(slot: number): M | undefined;
+    /**
+     * Bind every selected map and upload its metadata as whole arrays.
+     *
+     * WebGL reports an active uniform array only as `name[0]`. Looking up
+     * `name[1]` in the cached uniform table therefore returns nothing; uploading
+     * each element that way left slots 1–7 at zero and made their shadows vanish.
+     */
+    /**
+     * Settle every shader slot's map choice and parameters into the caller's arrays.
+     *
+     * **The arrays are the decision and the cubemaps are the binding.** Which light samples which
+     * slot, whether its image has landed and how present it is are answers this pool computes;
+     * turning them into `uniform1fv` or into bytes of a uniform block is all that differs between
+     * backends. A caller walks `mapForShaderSlot` for the textures.
+     */
+    resolve(out: ResolvedPointShadows): void;
+    /**
+     * The map a shader slot samples, or undefined.
+     *
+     * Separate from `resolve` because a backend needs it for the *texture* while the arrays are
+     * already settled, and because a slot with no map still has to be filled with something —
+     * see `emptyTexture.ts` on one side and the one-texel cube on the other.
+     */
+    mapForShaderSlot(slot: number): M | undefined;
+    /**
+     * Throw away every baked image, keeping the maps and their layers.
+     *
+     * For a backend that had to rebuild the storage under them — the array is immutable once
+     * allocated, so growing it for a bigger world replaces the pixels with nothing. A map that
+     * still reported `hasBaked` afterwards would be sampled, and what it would read is whatever
+     * the new allocation happens to contain.
+     */
+    forgetEveryImage(): void;
+    dispose(): void;
+}

package/dist/render/pointShadowSystem.js

@@ -0,0 +1,336 @@
+import { LIVE_POINT_SHADOW_MAPS, MAX_POINT_LIGHTS, POINT_SHADOW_POOL } from './lightBudget.js';
+import { LivePointShadowSet } from './livePointShadowSet.js';
+/**
+ * The shader's own name for the point-shadow array.
+ *
+ * Exported because *both* backends address it: WebGL2 looks it up in its uniform table and
+ * WebGPU looks it up in the generated binding table. One name, so the two cannot bind different
+ * things.
+ *
+ * **It was twelve names, one per cubemap sampler**, because GLSL ES cannot index a sampler
+ * array with a non-constant expression and the shader therefore declared each map separately.
+ * One array texture with a layer per light needs one.
+ */
+export const POINT_SHADOW_SAMPLER = 'uPointShadows';
+export class PointShadowSystem {
+    createMap;
+    releaseMap;
+    /** The pool. Indexed by pool slot, never by world light. */
+    maps = [];
+    live;
+    staticLightCount = 0;
+    /** Which world light currently holds each pool slot, or -1 while free. */
+    slotOwner = new Int32Array(POINT_SHADOW_POOL).fill(-1);
+    /** The lights held ready but not shaded, so joining the sampled set costs no bake. */
+    warm = new Int32Array(POINT_SHADOW_POOL);
+    warmCount = 0;
+    /** Frame stamp of the last time each slot was wanted, for the eviction choice. */
+    slotUsed = new Float64Array(POINT_SHADOW_POOL);
+    /** Reverse of `slotOwner`: pool slot per world light, or -1 while unassigned. */
+    lightSlot = new Int32Array(0);
+    useStamp = 0;
+    chosen = new Int32Array(MAX_POINT_LIGHTS);
+    /** Shader light slot each chosen world map belongs to. */
+    slots = new Int32Array(MAX_POINT_LIGHTS);
+    chosenCount = 0;
+    /** Batched array uniforms; WebGL exposes each array at its `[0]` location. */
+    far = new Float32Array(MAX_POINT_LIGHTS);
+    near = new Float32Array(MAX_POINT_LIGHTS);
+    sourceRadius = new Float32Array(MAX_POINT_LIGHTS);
+    /** How present each bound map is, so a re-baked one arrives rather than appears. */
+    presence = new Float32Array(MAX_POINT_LIGHTS);
+    /**
+     * `createMap` rather than a context and a size, so the pool never names a device.
+     *
+     * The whole of this class is pooling, staleness and selection — decisions a second backend
+     * must make identically or its shadows change hands at different moments. Taking a factory is
+     * what lets both share it; see `PointShadowSource`.
+     */
+    constructor(createMap, releaseMap) {
+        this.createMap = createMap;
+        this.releaseMap = releaseMap;
+        this.live = new LivePointShadowSet(createMap, releaseMap);
+    }
+    /**
+     * Size the pool and forget every assignment. Called once the light count is known.
+     *
+     * The pool is capped at `POINT_SHADOW_POOL` however many lights the caller has,
+     * and at the light count when that is smaller — a world with three lamps has no
+     * use for twelve cubemaps.
+     */
+    prepareStaticMaps(lightCount) {
+        const wanted = Math.min(lightCount, POINT_SHADOW_POOL);
+        while (this.maps.length < wanted) {
+            /* Pool slot i takes layer LIVE + i; the live maps hold 0 and 1. See PointShadowArray. */
+            this.maps.push(this.createMap(LIVE_POINT_SHADOW_MAPS + this.maps.length));
+        }
+        if (this.lightSlot.length < lightCount)
+            this.lightSlot = new Int32Array(lightCount);
+        this.lightSlot.fill(-1);
+        this.slotOwner.fill(-1);
+        this.slotUsed.fill(0);
+        this.staticLightCount = lightCount;
+    }
+    /**
+     * The map a light is currently borrowing, if any.
+     *
+     * A pure lookup: assignment happens once a frame in `sync`, because handing out
+     * slots from here would let a caller iterating lights evict the map it is about
+     * to read.
+     */
+    mapForLight(lightIndex) {
+        if (lightIndex < 0 || lightIndex >= this.staticLightCount)
+            return undefined;
+        const slot = this.lightSlot[lightIndex] ?? -1;
+        return slot < 0 ? undefined : this.maps[slot];
+    }
+    /** Adopt the shading pass's world-light list, including its exact order. */
+    sync(activeWorldIndices, activeCount, warmWorldIndices, warmCount = 0) {
+        this.chosenCount = 0;
+        const limit = Math.min(activeCount, MAX_POINT_LIGHTS);
+        for (let shaderSlot = 0; shaderSlot < limit; shaderSlot++) {
+            const worldIndex = activeWorldIndices[shaderSlot] ?? -1;
+            if (worldIndex < 0 || worldIndex >= this.staticLightCount)
+                continue;
+            this.chosen[this.chosenCount] = worldIndex;
+            this.slots[this.chosenCount] = shaderSlot;
+            this.chosenCount++;
+        }
+        /*
+         * The lights about to be wanted, given slots and baked before they are.
+         *
+         * Every light owned a permanent map before the pool, so joining the sampled set
+         * meant its shadow was already correct. Borrowing broke that: joining meant
+         * evicting somebody and baking six faces at two a frame, which is the on/off as a
+         * lamp comes into range. The pool has always carried four slots more than the
+         * shader can bind, and until now they only absorbed churn — these are the lights
+         * they were for.
+         *
+         * Warm lights hold a slot and take bake budget. They are never bound: `sampledCount`
+         * still counts only what the shader reads.
+         */
+        this.warmCount = 0;
+        if (warmWorldIndices !== undefined) {
+            const warmLimit = Math.min(warmCount, this.maps.length);
+            for (let i = 0; i < warmLimit; i++) {
+                const worldIndex = warmWorldIndices[i] ?? -1;
+                if (worldIndex < 0 || worldIndex >= this.staticLightCount)
+                    continue;
+                /*
+                 * Already being shaded, so it is not warming for anything: it holds its slot
+                 * from the loop above and it is baked across `pooledCount` either way.
+                 *
+                 * Without this the two lists overlap almost entirely — the shadow list is the
+                 * lights inside their own radius, and a light that close is nearly always in
+                 * the shaded set already — so `pooledCount` counted the same lights twice, and
+                 * `bakeStale` being pool-length meant the genuinely extra ones fell off the
+                 * end. The spare slots the pool carries for exactly this never held anything.
+                 */
+                let shaded = false;
+                for (let k = 0; k < this.chosenCount; k++) {
+                    if (this.chosen[k] === worldIndex) {
+                        shaded = true;
+                        break;
+                    }
+                }
+                if (shaded)
+                    continue;
+                this.warm[this.warmCount] = worldIndex;
+                this.warmCount++;
+            }
+        }
+        this.assignSlots();
+    }
+    /**
+     * Give every chosen light a pool slot, evicting the least recently wanted.
+     *
+     * One stamp for the whole call, so every light chosen this frame is equally
+     * recent and `claimSlot` can refuse to evict any of them.
+     */
+    assignSlots() {
+        this.useStamp++;
+        // Sampled first, so a warm light can never take a slot from one being shaded.
+        for (let k = 0; k < this.chosenCount; k++)
+            this.give(this.chosen[k] ?? -1);
+        for (let k = 0; k < this.warmCount; k++)
+            this.give(this.warm[k] ?? -1);
+    }
+    give(light) {
+        if (light < 0)
+            return;
+        const existing = this.lightSlot[light] ?? -1;
+        const slot = existing >= 0 ? existing : this.claimSlot(light);
+        if (slot >= 0)
+            this.slotUsed[slot] = this.useStamp;
+    }
+    /**
+     * Take a free slot, or the one wanted longest ago.
+     *
+     * Slots already stamped with this frame belong to lights the shader is about to
+     * read, so they are never candidates. The pool has more slots than
+     * `MAX_POINT_LIGHTS`, so a candidate always exists.
+     */
+    claimSlot(light) {
+        let best = -1;
+        let bestStamp = Infinity;
+        for (let slot = 0; slot < this.maps.length; slot++) {
+            if ((this.slotUsed[slot] ?? 0) === this.useStamp)
+                continue;
+            if ((this.slotOwner[slot] ?? -1) < 0) {
+                best = slot;
+                break;
+            }
+            const stamp = this.slotUsed[slot] ?? 0;
+            if (stamp < bestStamp) {
+                bestStamp = stamp;
+                best = slot;
+            }
+        }
+        if (best < 0)
+            return -1;
+        const previous = this.slotOwner[best] ?? -1;
+        if (previous >= 0) {
+            this.lightSlot[previous] = -1;
+            // The image belongs to the light losing the slot, not to the one taking it.
+            // Left in place it is sampled as the new light's shadow until a re-bake lands.
+            this.maps[best]?.forget();
+        }
+        this.slotOwner[best] = light;
+        this.lightSlot[light] = best;
+        return best;
+    }
+    /** Ramp every pooled image toward full presence. See `PointShadowMap.advance`. */
+    /**
+     * Ramp every image toward full presence: the pool's, **and the live pair's**.
+     *
+     * The second half was missing, and it is the whole of why a moving caster was never shadowed by
+     * a point light. `this.maps` is the pool; the live pair belongs to `LivePointShadowSet`, which
+     * publishes `crossfade weight * presence` and therefore published zero for ever. Every other
+     * part of that path reports itself healthy, which is what made it survive.
+     */
+    advance(dt) {
+        for (const map of this.maps)
+            map.advance(dt);
+        this.live.advance(dt);
+    }
+    get sampledCount() {
+        return this.chosenCount;
+    }
+    /** How many lights hold a slot this frame: the shaded ones plus the warming ones. */
+    get pooledCount() {
+        return this.chosenCount + this.warmCount;
+    }
+    /**
+     * A light holding a slot, shaded ones first.
+     *
+     * The renderer bakes across this rather than across `sampledCount`, which is the
+     * whole point: a warm light's map is baked *before* it is bound, so being chosen
+     * for shading never costs six face passes.
+     */
+    pooledLight(index) {
+        if (index < this.chosenCount)
+            return this.chosen[index] ?? -1;
+        return this.warm[index - this.chosenCount] ?? -1;
+    }
+    sampledLight(slot) {
+        return slot >= 0 && slot < this.chosenCount ? (this.chosen[slot] ?? -1) : -1;
+    }
+    /**
+     * Select the live shadow around a moving caster and advance any ownership
+     * crossfade. The position is caller-provided and has no gameplay meaning to
+     * the engine.
+     */
+    updateLiveSelection(lights, x, y, z, frameDt) {
+        this.live.update(lights, this.chosen, this.chosenCount, x, y, z, frameDt);
+    }
+    get liveMapCount() {
+        return LIVE_POINT_SHADOW_MAPS;
+    }
+    liveOwner(slot) {
+        return this.live.owner(slot, this.chosen, this.chosenCount);
+    }
+    liveMap(slot) {
+        return this.live.map(slot);
+    }
+    /**
+     * Bind every selected map and upload its metadata as whole arrays.
+     *
+     * WebGL reports an active uniform array only as `name[0]`. Looking up
+     * `name[1]` in the cached uniform table therefore returns nothing; uploading
+     * each element that way left slots 1–7 at zero and made their shadows vanish.
+     */
+    /**
+     * Settle every shader slot's map choice and parameters into the caller's arrays.
+     *
+     * **The arrays are the decision and the cubemaps are the binding.** Which light samples which
+     * slot, whether its image has landed and how present it is are answers this pool computes;
+     * turning them into `uniform1fv` or into bytes of a uniform block is all that differs between
+     * backends. A caller walks `mapForShaderSlot` for the textures.
+     */
+    resolve(out) {
+        out.layers.fill(-1);
+        out.far.fill(1);
+        out.near.fill(0.01);
+        out.sourceRadius.fill(0);
+        out.presence.fill(0);
+        for (let k = 0; k < MAX_POINT_LIGHTS; k++) {
+            const map = this.mapForShaderSlot(k);
+            /*
+             * A map with no image yet contributes nothing, exactly as an unassigned one does.
+             *
+             * Bakes are spread over frames rather than all done the moment they are noticed (see
+             * `pointShadowBudget.ts`), so a light can be selected a frame or two before its cubemap
+             * exists. Sampling it then would read whatever the pool slot held previously — another
+             * lamp's shadow, from somewhere else entirely — which is far worse than the light simply
+             * not casting for two frames. The index stays −1, which is the path the shader already
+             * takes for a light with no map at all.
+             */
+            if (map === undefined || !map.hasBaked)
+                continue;
+            /*
+             * `slots[k]` is the shading pass's own index for this light, which is the `i` the shader
+             * loops over — so it is the index everything about this map is written under. The chosen
+             * order and the shading order are not the same order, and writing under `k` here would
+             * hand light 2 the parameters of light 0 in any scene where they differ.
+             */
+            const light = this.slots[k] ?? -1;
+            if (light < 0 || light >= out.layers.length)
+                continue;
+            out.far[light] = map.far;
+            out.near[light] = map.near;
+            out.sourceRadius[light] = map.sourceRadius;
+            out.presence[light] = map.presence;
+            out.layers[light] = map.layer;
+        }
+        this.live.resolve(this.chosen, this.slots, this.chosenCount, out);
+    }
+    /**
+     * The map a shader slot samples, or undefined.
+     *
+     * Separate from `resolve` because a backend needs it for the *texture* while the arrays are
+     * already settled, and because a slot with no map still has to be filled with something —
+     * see `emptyTexture.ts` on one side and the one-texel cube on the other.
+     */
+    mapForShaderSlot(slot) {
+        const lightIndex = slot < this.chosenCount ? (this.chosen[slot] ?? -1) : -1;
+        return this.mapForLight(lightIndex);
+    }
+    /**
+     * Throw away every baked image, keeping the maps and their layers.
+     *
+     * For a backend that had to rebuild the storage under them — the array is immutable once
+     * allocated, so growing it for a bigger world replaces the pixels with nothing. A map that
+     * still reported `hasBaked` afterwards would be sampled, and what it would read is whatever
+     * the new allocation happens to contain.
+     */
+    forgetEveryImage() {
+        for (const map of this.maps)
+            map.forget();
+        this.live.forgetEveryImage();
+    }
+    dispose() {
+        for (const map of this.maps)
+            this.releaseMap(map);
+        this.live.dispose();
+    }
+}

package/dist/render/prefilterEnvMap.d.ts

@@ -0,0 +1,124 @@
+/**
+ * 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 declare const PREFILTER_SAMPLE_COUNTS: {
+    readonly low: 16;
+    readonly medium: 32;
+    readonly high: 128;
+};
+/** The tier names, so a quality option can take one without restating them. */
+export type PrefilterQuality = keyof typeof PREFILTER_SAMPLE_COUNTS;
+/**
+ * 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 declare function octahedralEdgeFor(faceSize: number): number;
+/**
+ * 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 declare 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 declare function irradianceLevelFor(edge: number): number;
+/**
+ * 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 declare function ggxMaxLevelFor(edge: number): number;
+/**
+ * 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 declare function roughnessForLevel(level: number, maxLevel: number): number;
+/**
+ * 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 declare function sourceLevelForSample(pdf: number, faceTexels: number, count: number, maxLevel: number): number;