@driftengine/core 4.3.0 → 4.4.1

package/dist/render/probeGrid.js

@@ -46,14 +46,16 @@ export function sameGrid(a, b) {
         if (a.spacing[axis] !== b.spacing[axis])
             return false;
     }
-    return true;
+    return a.crossfade === b.crossfade;
 }
 export class ProbeGrid {
     origin;
     spacing;
     counts;
-    /** Probes in total, which is also the array's layer count. */
+    /** Probes in total: the array's layer count, or a third of it for a crossfading grid. */
     layers;
+    /** Whether sweeps blend into one another. See `ProbeGridOptions.crossfade`. */
+    crossfade;
     /** The reciprocal of the spacing, because the shader multiplies and so does everything here. */
     invSpacing;
     constructor(options) {
@@ -91,6 +93,7 @@ export class ProbeGrid {
         this.invSpacing = [1 / this.spacing[0], 1 / this.spacing[1], 1 / this.spacing[2]];
         this.counts = counts;
         this.layers = layers;
+        this.crossfade = options.crossfade === true;
     }
     /**
      * The layer a probe at whole lattice coordinates occupies.

package/dist/render/probeSweeps.d.ts

@@ -0,0 +1,45 @@
+/**
+ * A probe grid's sweeps: which layer a bake writes, when a sweep is whole, and how far the shading
+ * has moved from the last whole sweep toward the newest.
+ *
+ * **A grid re-baked a probe a frame changes in steps.** Each probe holds the light of the moment it
+ * was baked until its turn comes round again, a sweep later, and then jumps to the light of that
+ * moment. Under a moving sun the jump is a pass of light across the scene once a sweep: reported as
+ * "a pass every second or two", which at sixty-four probes a frame at 60 Hz is exactly one sweep.
+ *
+ * **So a crossfading grid keeps three sets of layers**: the last whole sweep, the newest whole
+ * sweep, and the one being baked. The shading blends the first toward the second by how much of the
+ * third has been baked, so it reaches the newest sweep at the moment the next one is whole, and the
+ * light moves a sixty-fourth of a sweep a frame rather than a probe's worth at once. The set being
+ * written is never one the shading reads.
+ *
+ * What it gives up is three times the layers, and a sweep of lag: the light shown is a blend of what
+ * the grid saw one and two sweeps ago. What would make it wrong is a light that must follow a change
+ * faster than a sweep, which a burst of bakes serves, since the blend follows the bakes rather than
+ * the clock. A grid that does not crossfade is one set, ready once every probe is baked, as before.
+ *
+ * Backend-neutral, per the rule that a decision lives in one place and only the binding is per
+ * backend: both renderers ask this where to write and what to upload.
+ */
+export declare class ProbeSweeps {
+    /** Sets of layers the array holds: three for a crossfading grid, one otherwise. */
+    readonly sets: 1 | 3;
+    private readonly layers;
+    /** Which probes the sweep being baked has reached, and how many. */
+    private readonly reached;
+    private reachedCount;
+    private from;
+    private to;
+    private write;
+    /** Whether a whole sweep has been rotated in. */
+    private whole;
+    constructor(layers: number, crossfade: boolean);
+    /** The array layer a bake of probe `layer` writes. */
+    writeLayer(layer: number): number;
+    /** Record that probe `layer` was baked into the set being written; a whole sweep rotates. */
+    baked(layer: number): void;
+    /** Whether the shading may read the grid: once a sweep is whole. */
+    get ready(): boolean;
+    /** The layer offsets of the two sets shown and the blend between them, into `out`. */
+    uniforms(out: Float32Array): Float32Array;
+}

package/dist/render/probeSweeps.js

@@ -0,0 +1,77 @@
+/**
+ * A probe grid's sweeps: which layer a bake writes, when a sweep is whole, and how far the shading
+ * has moved from the last whole sweep toward the newest.
+ *
+ * **A grid re-baked a probe a frame changes in steps.** Each probe holds the light of the moment it
+ * was baked until its turn comes round again, a sweep later, and then jumps to the light of that
+ * moment. Under a moving sun the jump is a pass of light across the scene once a sweep: reported as
+ * "a pass every second or two", which at sixty-four probes a frame at 60 Hz is exactly one sweep.
+ *
+ * **So a crossfading grid keeps three sets of layers**: the last whole sweep, the newest whole
+ * sweep, and the one being baked. The shading blends the first toward the second by how much of the
+ * third has been baked, so it reaches the newest sweep at the moment the next one is whole, and the
+ * light moves a sixty-fourth of a sweep a frame rather than a probe's worth at once. The set being
+ * written is never one the shading reads.
+ *
+ * What it gives up is three times the layers, and a sweep of lag: the light shown is a blend of what
+ * the grid saw one and two sweeps ago. What would make it wrong is a light that must follow a change
+ * faster than a sweep, which a burst of bakes serves, since the blend follows the bakes rather than
+ * the clock. A grid that does not crossfade is one set, ready once every probe is baked, as before.
+ *
+ * Backend-neutral, per the rule that a decision lives in one place and only the binding is per
+ * backend: both renderers ask this where to write and what to upload.
+ */
+export class ProbeSweeps {
+    /** Sets of layers the array holds: three for a crossfading grid, one otherwise. */
+    sets;
+    layers;
+    /** Which probes the sweep being baked has reached, and how many. */
+    reached;
+    reachedCount = 0;
+    from = 0;
+    to = 0;
+    write = 0;
+    /** Whether a whole sweep has been rotated in. */
+    whole = false;
+    constructor(layers, crossfade) {
+        this.layers = Math.max(1, Math.trunc(layers));
+        this.sets = crossfade ? 3 : 1;
+        this.reached = new Uint8Array(this.layers);
+    }
+    /** The array layer a bake of probe `layer` writes. */
+    writeLayer(layer) {
+        return this.write * this.layers + layer;
+    }
+    /** Record that probe `layer` was baked into the set being written; a whole sweep rotates. */
+    baked(layer) {
+        if (layer < 0 || layer >= this.layers || this.reached[layer] === 1)
+            return;
+        this.reached[layer] = 1;
+        this.reachedCount++;
+        if (this.reachedCount < this.layers)
+            return;
+        this.reached.fill(0);
+        this.reachedCount = 0;
+        if (this.sets === 1) {
+            this.whole = true;
+            return;
+        }
+        /* The newest is shown from now on; the first whole sweep is shown alone, blending into itself. */
+        this.from = this.whole ? this.to : this.write;
+        this.to = this.write;
+        this.whole = true;
+        /* The set neither end of the blend holds. */
+        this.write = this.from === this.to ? (this.to + 1) % 3 : 3 - this.from - this.to;
+    }
+    /** Whether the shading may read the grid: once a sweep is whole. */
+    get ready() {
+        return this.whole;
+    }
+    /** The layer offsets of the two sets shown and the blend between them, into `out`. */
+    uniforms(out) {
+        out[0] = this.from * this.layers;
+        out[1] = this.to * this.layers;
+        out[2] = this.sets === 1 ? 0 : this.reachedCount / this.layers;
+        return out;
+    }
+}

package/dist/render/reflectionProbe.d.ts

@@ -59,7 +59,46 @@ export interface ProbeBakeOptions {
      * nothing gets the frame it already had.
      */
     readonly irradiance?: boolean;
+    /**
+     * Whether what the probe sees is lit by the grid's last bake, so each bake adds a bounce.
+     *
+     * Defaults to **false**, which is what every bake did before this existed. Then everything a
+     * probe sees is lit by the sun and by the hemispheric ambient, so the grid holds one bounce. An
+     * enclosed space is mostly lit at the second bounce and later. A courtyard's arcades are the
+     * case this was built for: one bounce came out about two stops under a reference render.
+     *
+     * With it on, the surfaces in each face take their ambient from the grid instead. Round-robin
+     * baking then converges on the space's full interreflection, about a bounce each time the grid
+     * is swept, and a scene holding one moment bakes the grid two or three times. It costs no pass
+     * and no memory. The faces are drawn into their own cube and only the resolve writes the array,
+     * so the array is never read and written in one pass.
+     *
+     * **Nothing changes until every probe has been baked once**, because until then the grid is not
+     * readable; the first sweep lights by the ambient as before. What it gives up: light that leaks
+     * through a wall into a probe is bounced again, so a leak grows with each sweep. What would make
+     * it wrong is a space with near-white walls, where a sweep adds almost as much as the last and
+     * convergence takes many sweeps.
+     */
+    readonly bounce?: boolean;
+    /**
+     * Which of the six faces this call draws, as `[first, count]`: all six when absent.
+     *
+     * **A bake is six draws of the scene, and a scene of millions of triangles makes it the most
+     * expensive thing in a frame.** Measured on a bought courtyard of eleven million: 6.4 ms of a
+     * 14 ms frame, on the frames it ran, which is a frame rate no display can hold steady. Spread over
+     * calls, each draws only its faces into the capture, and the convolution into the layer, which
+     * reads all six, runs when the sixth is drawn. Faces in the order a cube numbers them,
+     * `+X, -X, +Y, -Y, +Z, -Z`.
+     *
+     * **The caller finishes one probe before starting the next**, because the capture the faces are
+     * drawn into is one for the whole grid: faces of two probes interleaved make a cube of neither.
+     * What it gives up is a probe whose faces were drawn a few frames apart, under a light that moved
+     * a little between them.
+     */
+    readonly faces?: readonly [first: number, count: number];
 }
+/** The faces a bake draws, `[first, end)`, from `ProbeBakeOptions.faces`. All six when absent. */
+export declare function probeFaceRange(options: ProbeBakeOptions | undefined): [number, number];
 export declare class ReflectionProbe {
     /**
      * The captured cube, box-filtered, which the convolution reads and the projection reads.
@@ -188,8 +227,11 @@ export declare class ReflectionProbe {
      * Returns whether the bake happened. A false means the allocation was refused and the caller
      * should carry on without a probe, which is a picture with a gradient in its paint rather
      * than a room.
+     *
+     * `first` and `end` draw only those faces, and the chain the roughness reads is built when the
+     * sixth is drawn. See `ProbeBakeOptions.faces`.
      */
-    bake(gl: WebGL2RenderingContext, origin: Vec3, clearColor: Vec3, drawFace: (camera: Camera) => void): boolean;
+    bake(gl: WebGL2RenderingContext, origin: Vec3, clearColor: Vec3, drawFace: (camera: Camera) => void, first?: number, end?: number): boolean;
     /**
      * Read six faces back off the GPU, at one mip level, for the irradiance projection.
      *

package/dist/render/reflectionProbe.js

@@ -34,6 +34,15 @@ export function cubeFaceProjection(out, viewProj) {
     }
     return out;
 }
+/** The faces a bake draws, `[first, end)`, from `ProbeBakeOptions.faces`. All six when absent. */
+export function probeFaceRange(options) {
+    const asked = options?.faces;
+    if (asked === undefined)
+        return [0, 6];
+    const first = Math.min(Math.max(Math.trunc(asked[0]), 0), 5);
+    const count = Math.max(Math.trunc(asked[1]), 1);
+    return [first, Math.min(first + count, 6)];
+}
 /**
  * The six directions of a cubemap, as the yaw and pitch a `Camera` aims with.
  *
@@ -336,8 +345,11 @@ export class ReflectionProbe {
      * Returns whether the bake happened. A false means the allocation was refused and the caller
      * should carry on without a probe, which is a picture with a gradient in its paint rather
      * than a room.
+     *
+     * `first` and `end` draw only those faces, and the chain the roughness reads is built when the
+     * sixth is drawn. See `ProbeBakeOptions.faces`.
      */
-    bake(gl, origin, clearColor, drawFace) {
+    bake(gl, origin, clearColor, drawFace, first = 0, end = FACES.length) {
         if (this.unusable)
             return false;
         const camera = this.camera;
@@ -351,12 +363,12 @@ export class ReflectionProbe {
         gl.bindFramebuffer(gl.FRAMEBUFFER, this.framebuffer);
         gl.framebufferRenderbuffer(gl.FRAMEBUFFER, gl.DEPTH_ATTACHMENT, gl.RENDERBUFFER, this.depth);
         gl.viewport(0, 0, this.size, this.size);
-        for (let face = 0; face < FACES.length; face++) {
+        for (let face = first; face < end; face++) {
             const aim = FACES[face];
             if (aim === undefined)
                 continue;
             gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.COLOR_ATTACHMENT0, gl.TEXTURE_CUBE_MAP_POSITIVE_X + face, this.texture, 0);
-            if (face === 0 && gl.checkFramebufferStatus(gl.FRAMEBUFFER) !== gl.FRAMEBUFFER_COMPLETE) {
+            if (face === first && gl.checkFramebufferStatus(gl.FRAMEBUFFER) !== gl.FRAMEBUFFER_COMPLETE) {
                 this.unusable = true;
                 gl.bindFramebuffer(gl.FRAMEBUFFER, null);
                 console.warn('ReflectionProbe: this driver will not render to a cubemap face, so reflective ' +
@@ -376,6 +388,8 @@ export class ReflectionProbe {
             drawFace(camera);
         }
         gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+        if (end < FACES.length)
+            return true;
         /* The blur the roughness reads. Once per bake, not once per frame. */
         gl.bindTexture(gl.TEXTURE_CUBE_MAP, this.texture);
         gl.generateMipmap(gl.TEXTURE_CUBE_MAP);

package/dist/render/renderQuality.d.ts

@@ -552,7 +552,9 @@ export interface RenderQuality {
      */
     readonly reconstruction: number;
     /**
-     * Light a scene from what bounces, rather than from what was baked. **Off by default.**
+     * Light a scene from what bounces, rather than from what was baked: **DriftRay**, this engine's
+     * ray tracing, rays marched through the declared distance fields in GPU compute rather than on
+     * the dedicated ray-tracing units WebGPU does not expose. **Off by default.**
      *
      * On, the probe grid the shading already samples is filled by tracing `render/gi/`'s three-level
      * chain — the world distance field, and behind it the probes themselves, which is what makes the

package/dist/render/rendererHarness.d.ts

@@ -29,6 +29,15 @@ export declare function recordingGl(options?: {
      * `Infinity` by default, so a link only ever fails where a test asked for it.
      */
     readonly refuseLinkAbove?: number;
+    /**
+     * Uniforms every program reports as active, each located by a handle carrying its name.
+     *
+     * **None by default**, which ends every reflection loop at once and leaves every upload aimed
+     * at `null`. A test about what a frame *uploads* names the uniform here and then finds the
+     * calls whose location says that name, rather than guessing at an upload's position in the
+     * recording.
+     */
+    readonly uniforms?: readonly string[];
 }): {
     gl: WebGL2RenderingContext;
     canvas: HTMLCanvasElement;

package/dist/render/rendererHarness.js

@@ -18,6 +18,9 @@
 import { countUniformVectors } from './uniformVectorBudget.js';
 export function recordingGl(options = {}) {
     const extensions = new Set(options.extensions ?? []);
+    const uniforms = options.uniforms ?? [];
+    /* What `clearDepth` last set, so a module that borrows the value can be seen to put it back. */
+    let depthClear = 1;
     const reportedVectors = options.fragmentUniformVectors ?? 1024;
     const enforcedVectors = options.refuseLinkAbove ?? Number.POSITIVE_INFINITY;
     /** Fragment sources by shader handle, so a refusal can be decided from what was compiled. */
@@ -37,6 +40,7 @@ export function recordingGl(options = {}) {
         MAX_TEXTURE_IMAGE_UNITS: 0x8872,
         MAX_VERTEX_UNIFORM_VECTORS: 0x8dfb,
         MAX_FRAGMENT_UNIFORM_VECTORS: 0x8dfd,
+        DEPTH_CLEAR_VALUE: 0x0b73,
         /*
          * Enums a test needs to compare against, rather than merely to pass through.
          *
@@ -97,6 +101,8 @@ export function recordingGl(options = {}) {
                 return reportedVectors;
             if (pname === constants.MAX_VERTEX_UNIFORM_VECTORS)
                 return 1024;
+            if (pname === constants.DEPTH_CLEAR_VALUE)
+                return depthClear;
             /* Generous by default: every remaining limit is a ceiling something is checked against,
                and a small answer is read as a device that cannot do the thing. */
             return 4096;
@@ -129,7 +135,9 @@ export function recordingGl(options = {}) {
         /* Linked yes; zero active uniforms and attributes, which ends every reflection loop at once
            and is why this harness does not have to know a single uniform name. */
         getProgramParameter: (program, pname) => {
-            if (pname === constants.ACTIVE_UNIFORMS || pname === constants.ACTIVE_ATTRIBUTES)
+            if (pname === constants.ACTIVE_UNIFORMS)
+                return uniforms.length;
+            if (pname === constants.ACTIVE_ATTRIBUTES)
                 return 0;
             if (pname !== constants.LINK_STATUS)
                 return true;
@@ -140,9 +148,16 @@ export function recordingGl(options = {}) {
             const source = programFragments.get(program);
             return source === undefined || countUniformVectors(source) <= enforcedVectors;
         },
-        getActiveUniform: () => ({ name: '', size: 1, type: 0 }),
+        getActiveUniform: (_program, index) => ({
+            name: uniforms[Number(index)] ?? '',
+            size: 1,
+            type: 0,
+        }),
         getActiveAttrib: () => ({ name: '', size: 1, type: 0 }),
-        getUniformLocation: () => ({}),
+        getUniformLocation: (_program, name) => ({ name }),
+        clearDepth: (value) => {
+            depthClear = Number(value);
+        },
         getAttribLocation: () => -1,
         checkFramebufferStatus: () => constants.FRAMEBUFFER_COMPLETE,
         getError: () => constants.NO_ERROR,

package/dist/render/sceneTarget.d.ts

@@ -85,6 +85,16 @@ export declare class SceneTarget {
     private gradeSource;
     private gradeSize;
     private gradeStrength;
+    /** The lens and the print, held like the grade. See `filmLook.ts`. */
+    private vignette;
+    private grain;
+    private grainSeed;
+    /** Eye adaptation: how far, and this frame's time step. See `Renderer.setAutoExposure`. */
+    private autoExposure;
+    private autoExposureDt;
+    /** How far each region is brought toward the frame. See `Renderer.setLocalExposure`. */
+    private localExposure;
+    private exposure;
     private width;
     private height;
     /**
@@ -244,6 +254,16 @@ export declare class SceneTarget {
      * `null`, or a strength at or below zero, is exactly the frame that existed before the effect
      * did: the shader's branch is on a uniform, so no fetch happens at all.
      */
+    /** The lens's corner falloff, held until changed. See `Renderer.setVignette`. */
+    setVignette(strength: number): void;
+    /** The print's grain and this frame's seed, held until changed. See `Renderer.setFilmGrain`. */
+    setFilmGrain(strength: number, seed: number): void;
+    /** How far the eye adapts, and the time since the last frame. See `Renderer.setAutoExposure`. */
+    setAutoExposure(strength: number, dtSec: number): void;
+    /** How far each region is brought toward the frame. See `Renderer.setLocalExposure`. */
+    setLocalExposure(strength: number): void;
+    /** A new shot: the eye meters it afresh rather than easing in from the last one. */
+    cutExposure(): void;
     setColourGrade(lut: ColourGradeLut | null, strength: number): void;
     /**
      * Put a table on the device, replacing whatever was there.

package/dist/render/sceneTarget.js

@@ -1,5 +1,9 @@
 import { glSceneDepthFormat } from './depthConvention.js';
+import { clampGrain, clampVignette, grainSeed } from './shaders/filmLook.js';
 import { AmbientOcclusionPass } from './ambientOcclusionPass.js';
+import { ExposurePass } from './exposurePass.js';
+import { clampAutoExposure } from './shaders/exposure.js';
+import { clampLocalExposure } from './shaders/localExposure.js';
 import { BloomPass } from './bloomPass.js';
 import { GRADE_PLACEHOLDER_SIZE, identityGradeLut, validateGradeLut, } from './colourGrade.js';
 import { compileProgram, uniformLocations } from './shader.js';
@@ -85,6 +89,16 @@ export class SceneTarget {
     gradeSource = null;
     gradeSize = GRADE_PLACEHOLDER_SIZE;
     gradeStrength = 0;
+    /** The lens and the print, held like the grade. See `filmLook.ts`. */
+    vignette = 0;
+    grain = 0;
+    grainSeed = 0;
+    /** Eye adaptation: how far, and this frame's time step. See `Renderer.setAutoExposure`. */
+    autoExposure = 0;
+    autoExposureDt = 0;
+    /** How far each region is brought toward the frame. See `Renderer.setLocalExposure`. */
+    localExposure = 0;
+    exposure = null;
     width = 0;
     height = 0;
     /**
@@ -520,6 +534,28 @@ export class SceneTarget {
      * `null`, or a strength at or below zero, is exactly the frame that existed before the effect
      * did: the shader's branch is on a uniform, so no fetch happens at all.
      */
+    /** The lens's corner falloff, held until changed. See `Renderer.setVignette`. */
+    setVignette(strength) {
+        this.vignette = clampVignette(strength);
+    }
+    /** The print's grain and this frame's seed, held until changed. See `Renderer.setFilmGrain`. */
+    setFilmGrain(strength, seed) {
+        this.grain = clampGrain(strength);
+        this.grainSeed = grainSeed(seed);
+    }
+    /** How far the eye adapts, and the time since the last frame. See `Renderer.setAutoExposure`. */
+    setAutoExposure(strength, dtSec) {
+        this.autoExposure = clampAutoExposure(strength);
+        this.autoExposureDt = dtSec;
+    }
+    /** How far each region is brought toward the frame. See `Renderer.setLocalExposure`. */
+    setLocalExposure(strength) {
+        this.localExposure = clampLocalExposure(strength);
+    }
+    /** A new shot: the eye meters it afresh rather than easing in from the last one. */
+    cutExposure() {
+        this.exposure?.cut();
+    }
     setColourGrade(lut, strength) {
         this.gradeStrength = lut === null ? 0 : Math.max(0, Math.min(1, strength));
         if (lut === null || lut === this.gradeSource)
@@ -682,6 +718,16 @@ export class SceneTarget {
             this.bloom ??= new BloomPass(gl);
             bloomTexture = this.bloom.run(scene, this.width, this.height, bloom.threshold);
         }
+        /*
+         * Eye adaptation, metered from the same resolved scene bloom reads, and after it for the same
+         * reason: the composite consumes it. Off at zero strength, where nothing is allocated or drawn.
+         */
+        let heldExposure = null;
+        const local = this.localExposure > 0;
+        if ((this.autoExposure > 0 || local) && scene !== null) {
+            this.exposure ??= new ExposurePass(gl);
+            heldExposure = this.exposure.run(scene, this.autoExposureDt, local);
+        }
         gl.bindFramebuffer(gl.FRAMEBUFFER, null);
         gl.viewport(0, 0, this.width, this.height);
         gl.disable(gl.DEPTH_TEST);
@@ -767,6 +813,18 @@ export class SceneTarget {
         gl.uniform1i(this.uniforms['uGradeLut'] ?? null, 4);
         gl.uniform1f(this.uniforms['uGradeStrength'] ?? null, this.gradeStrength);
         gl.uniform1f(this.uniforms['uGradeSize'] ?? null, this.gradeSize);
+        /* The held brightness on unit 5, and the scene as the placeholder where there is none, for
+           the reason the occlusion's placeholder gives. Zero strength is the whole of the off path. */
+        gl.activeTexture(gl.TEXTURE5);
+        gl.bindTexture(gl.TEXTURE_2D, heldExposure ?? scene);
+        gl.uniform1i(this.uniforms['uExposureHeld'] ?? null, 5);
+        gl.uniform1f(this.uniforms['uAutoExposure'] ?? null, heldExposure === null ? 0 : this.autoExposure);
+        /* Local exposure's grid on unit 6, with the same placeholder and the same off path. */
+        const localGrid = local && heldExposure !== null ? (this.exposure?.localTexture ?? null) : null;
+        gl.activeTexture(gl.TEXTURE6);
+        gl.bindTexture(gl.TEXTURE_2D, localGrid ?? scene);
+        gl.uniform1i(this.uniforms['uExposureLocal'] ?? null, 6);
+        gl.uniform1f(this.uniforms['uLocalExposure'] ?? null, localGrid === null ? 0 : this.localExposure);
         gl.activeTexture(gl.TEXTURE0);
         /* No unit and no texture: a flat colour, not a sample. Uploaded unconditionally — two
            floats and a triplet cost nothing next to the triangle this pass already draws — and it
@@ -774,6 +832,8 @@ export class SceneTarget {
            mix it does not need. */
         gl.uniform3fv(this.uniforms['uVeilColor'] ?? null, veilColor);
         gl.uniform1f(this.uniforms['uVeilAlpha'] ?? null, veilAlpha);
+        gl.uniform1f(this.uniforms['uVignette'] ?? null, this.vignette);
+        gl.uniform2f(this.uniforms['uGrain'] ?? null, this.grain, this.grainSeed);
         gl.bindVertexArray(this.vao);
         gl.drawArrays(gl.TRIANGLES, 0, 3);
         gl.bindVertexArray(null);
@@ -788,7 +848,7 @@ export class SceneTarget {
          * own framebuffers on the next frame, and that is how this was found: 120 pixels of a frame
          * that should have been identical, and a warning per draw explaining why.
          */
-        for (let unit = 0; unit <= 4; unit++) {
+        for (let unit = 0; unit <= 5; unit++) {
             gl.activeTexture(gl.TEXTURE0 + unit);
             gl.bindTexture(gl.TEXTURE_2D, null);
         }
@@ -815,6 +875,7 @@ export class SceneTarget {
     dispose() {
         const { gl } = this;
         this.ao?.dispose();
+        this.exposure?.dispose();
         this.ao = null;
         this.bloom?.dispose();
         this.bloom = null;

package/dist/render/shaders/ambientOcclusion.d.ts

@@ -24,13 +24,23 @@
  * wherever the depth test cuts the window short, as a dotted line along every edge.
  */
 /**
- * The estimate. Writes one channel: 1 is open sky, 0 is fully enclosed.
+ * The estimate. Writes one channel at `AO_STORE`: that is open sky, 0 is fully enclosed, and the
+ * second axis of the blur decodes it.
  *
- * The estimator is the Alchemy/scalable-AO one — for each neighbour, the vector v from this
- * surface to it, weighted max(0, v·n) / (v·v). Two properties earn it its place over a
- * hemisphere of offset points: nothing has to be oriented, so there is no tangent frame and
- * no rotation matrix per pixel, and the 1 / v·v term falls away on its own, so a neighbour
- * further off contributes less without a second range test doing it by hand.
+ * **Horizons, not neighbours: ground-truth ambient occlusion (Jimenez et al. 2016).** Each pixel
+ * walks two lines across the screen, both ways, and keeps the highest thing it can see along each
+ * half: the horizon. The sky left between the two horizons of a line, weighted by the cosine to the
+ * surface's own normal, is that line's visibility in closed form, and two lines a pixel with the
+ * rotation tile below turning them is the hemisphere. It replaced a sum over twelve neighbours that
+ * counted anything within the radius as a blocker, however thin: cloth hanging a hand in front of a
+ * column darkened the column behind it, which read as a halo round every curtain in a courtyard.
+ *
+ * **What stops the halo is two rules about the horizon**, both the paper's. A sample fades out of
+ * the horizon as it approaches the radius, so a far wall does not shade a floor; and once the walk
+ * has passed the highest sample, the horizon sinks back toward what it sees next, so a thin thing
+ * in front raises it only while the walk is behind that thing. What that gives up is the shade under
+ * a thick object seen edge on, which reads as a thin one; the thickness is a constant because depth
+ * alone cannot say how deep anything is.
  */
 export declare const AO_FRAG: string;
 /**
@@ -43,3 +53,50 @@ export declare const AO_FRAG: string;
  * added to remove.
  */
 export declare const AO_BLUR_FRAG: string;
+/**
+ * The estimate's closed form, written out once more so a test can pin it to hand-derived values:
+ * the cosine-weighted sky between horizon angles `h0 < 0 < h1` for a normal at `normal`, all in
+ * radians from the eye within one line's plane.
+ */
+export declare function gtaoArc(h0: number, h1: number, normal: number): number;
+/** One step of a horizon: up to a higher sample, or a fifth of the way down toward a lower one. */
+export declare function nextHorizon(horizon: number, cosine: number): number;
+/** The shader's thickness heuristic. See `AO_THIN` inside `AO_FRAG`. */
+export declare const AO_THIN = 0.2;
+/**
+ * What the estimate is multiplied by before it is stored, and divided by once the blur is done.
+ *
+ * **Half, because an unblurred estimate is allowed past one.** A pixel's two lines see a plane
+ * turned away from the eye from two directions, and the closed form credits one of them more than
+ * the whole sky and the other less: it is the average over every turn that is exactly one, and the
+ * average is what the blur is for. Stored as it came, an eight-bit target clipped every turn above
+ * one before the blur could average it, and every surface seen edge on came back a few percent
+ * shaded with nothing on it. A line reaches π/2 at most, so half fits the whole range.
+ *
+ * What it gives up is one bit of the intermediate: steps of 1/128 rather than 1/256 until the
+ * second axis decodes, which the eight taps a pixel averages carry below what a frame can show.
+ */
+export declare const AO_STORE = 0.5;
+/** How far a neighbour may sit from this pixel's surface, as a fraction of its distance. */
+export declare const AO_BLUR_DEPTH_TOLERANCE = 0.02;
+/**
+ * The blur's weight for a neighbour `offset` pixels along the axis, from view depths: this pixel's
+ * own, the two either side of it, and the neighbour's. The shader's lines written out again.
+ *
+ * **The neighbour is compared with this pixel's plane, not with this pixel's depth.** Comparing
+ * depths refused every neighbour of a surface seen edge on: a floor forty metres out changes its
+ * depth by four percent a row, twice the tolerance, so the pass down the frame kept the centre alone
+ * and left the rotation tile's rows standing — four-pixel stripes across every ramp and far floor,
+ * reported as strips on a track. On a plane 1/z is affine in the screen, so one step of it predicts
+ * the plane's depth at every tap exactly, and a tap is refused only for leaving the plane.
+ *
+ * The step is taken from whichever neighbour is closer to the centre in 1/z. At a silhouette that is
+ * the one on this pixel's own side, so the far surface cannot bend the prediction toward it; on a
+ * plane the two agree to a quantisation step, which moves a weight by nothing a frame shows. What it
+ * gives up is a crease: past the fold between a floor and a wall the prediction runs on along the
+ * floor, so the wall's taps fade out over the tolerance rather than being kept.
+ *
+ * **Written here rather than in the shader**, because a comment inside the GLSL is part of the string
+ * a consumer ships.
+ */
+export declare function blurWeight(centre: number, before: number, after: number, neighbour: number, offset: number): number;