@driftengine/core 4.2.1 → 4.4.0

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/agx.d.ts

@@ -0,0 +1,31 @@
+/**
+ * AgX: a tone curve whose shade stays open, for scenes lit mostly by bounce.
+ *
+ * **What ACES does to a courtyard.** The reference RRT and ODT are graded for a dark cinema, and
+ * their toe is steep: a surface at 1% of white leaves the curve at 4 of 255. A room lit by light
+ * bounced off its own walls lives in exactly that range, so its arcades read black beside renders
+ * of the same model, and the grime in its stone reads as ink. Measured on a bought courtyard: 39%
+ * of the frame below 16 of 255, against about 5% in the model maker's own renders.
+ *
+ * **AgX encodes the scene logarithmically and draws one sigmoid through it**, Troy Sobotka's
+ * construction as Blender, Filament and three.js ship it. The same 1% leaves at 18 of 255, middle
+ * grey lands at half the display range, and a highlight desaturates toward white instead of
+ * clipping to a hue. What it gives up is ACES's punch in the midtones: the same scene reads
+ * flatter, which a grade adds back as a look where ACES bakes it into the conversion. What would
+ * make it the wrong choice is a world graded against three.js's or Unreal's ACES, which is the
+ * match `aces` exists for.
+ *
+ * The constants are the Filament and three.js ones: Rec. 2020 primaries, the inset and outset
+ * matrices, an encoding from 2^-10 to 2^6.5 times middle grey, and the iolite polynomial fit of
+ * the default contrast curve, whose mean squared error against Blender's is 3.7e-6.
+ */
+/**
+ * `agxFilmic(vec3)`: linear sRGB in, linear sRGB out, clamped to [0, 1]. Reads `uOutputExposure`,
+ * which the including source declares.
+ */
+export declare const AGX_GLSL = "\nvec3 agxContrast(vec3 x) {\n  vec3 x2 = x * x;\n  vec3 x4 = x2 * x2;\n  return 15.5 * x4 * x2 - 40.14 * x4 * x + 31.96 * x4 - 6.868 * x2 * x + 0.4298 * x2 + 0.1191 * x - 0.00232;\n}\n\nvec3 agxFilmic(vec3 x) {\n  x *= uOutputExposure;\n  // Columns, as GLSL reads them: linear sRGB to linear Rec. 2020, then the inset.\n  const mat3 SRGB_TO_REC2020 = mat3(\n    0.6274, 0.0691, 0.0164,\n    0.3293, 0.9195, 0.0880,\n    0.0433, 0.0113, 0.8956\n  );\n  const mat3 AGX_INSET = mat3(\n    0.856627153315983, 0.137318972929847, 0.11189821299995,\n    0.0951212405381588, 0.761241990602591, 0.0767994186031903,\n    0.0482516061458583, 0.101439036467562, 0.811302368396859\n  );\n  const mat3 AGX_OUTSET = mat3(\n    1.1271005818144368, -0.1413297634984383, -0.14132976349843826,\n    -0.11060664309660323, 1.157823702216272, -0.11060664309660294,\n    -0.016493938717834573, -0.016493938717834257, 1.2519364065950405\n  );\n  const mat3 REC2020_TO_SRGB = mat3(\n    1.6605, -0.1246, -0.0182,\n    -0.5876, 1.1329, -0.1006,\n    -0.0728, -0.0083, 1.1187\n  );\n  vec3 c = AGX_INSET * (SRGB_TO_REC2020 * x);\n  /* log2 of middle grey times 2^-10 and 2^6.5: -12.47393 and 4.026069, 16.5 stops apart. */\n  c = clamp((log2(max(c, vec3(1e-10))) + 12.47393) / 16.5, 0.0, 1.0);\n  c = AGX_OUTSET * agxContrast(c);\n  c = pow(max(c, vec3(0.0)), vec3(2.2));\n  return clamp(REC2020_TO_SRGB * c, 0.0, 1.0);\n}\n";
+/**
+ * The curve for a neutral grey, as the shader computes it: every matrix above keeps grey grey, so
+ * one channel is the whole of it. For a test to pin to hand-derived values.
+ */
+export declare function agxGrey(linear: number, exposure?: number): number;

package/dist/render/shaders/agx.js

@@ -0,0 +1,81 @@
+/**
+ * AgX: a tone curve whose shade stays open, for scenes lit mostly by bounce.
+ *
+ * **What ACES does to a courtyard.** The reference RRT and ODT are graded for a dark cinema, and
+ * their toe is steep: a surface at 1% of white leaves the curve at 4 of 255. A room lit by light
+ * bounced off its own walls lives in exactly that range, so its arcades read black beside renders
+ * of the same model, and the grime in its stone reads as ink. Measured on a bought courtyard: 39%
+ * of the frame below 16 of 255, against about 5% in the model maker's own renders.
+ *
+ * **AgX encodes the scene logarithmically and draws one sigmoid through it**, Troy Sobotka's
+ * construction as Blender, Filament and three.js ship it. The same 1% leaves at 18 of 255, middle
+ * grey lands at half the display range, and a highlight desaturates toward white instead of
+ * clipping to a hue. What it gives up is ACES's punch in the midtones: the same scene reads
+ * flatter, which a grade adds back as a look where ACES bakes it into the conversion. What would
+ * make it the wrong choice is a world graded against three.js's or Unreal's ACES, which is the
+ * match `aces` exists for.
+ *
+ * The constants are the Filament and three.js ones: Rec. 2020 primaries, the inset and outset
+ * matrices, an encoding from 2^-10 to 2^6.5 times middle grey, and the iolite polynomial fit of
+ * the default contrast curve, whose mean squared error against Blender's is 3.7e-6.
+ */
+/**
+ * `agxFilmic(vec3)`: linear sRGB in, linear sRGB out, clamped to [0, 1]. Reads `uOutputExposure`,
+ * which the including source declares.
+ */
+export const AGX_GLSL = `
+vec3 agxContrast(vec3 x) {
+  vec3 x2 = x * x;
+  vec3 x4 = x2 * x2;
+  return 15.5 * x4 * x2 - 40.14 * x4 * x + 31.96 * x4 - 6.868 * x2 * x + 0.4298 * x2 + 0.1191 * x - 0.00232;
+}
+
+vec3 agxFilmic(vec3 x) {
+  x *= uOutputExposure;
+  // Columns, as GLSL reads them: linear sRGB to linear Rec. 2020, then the inset.
+  const mat3 SRGB_TO_REC2020 = mat3(
+    0.6274, 0.0691, 0.0164,
+    0.3293, 0.9195, 0.0880,
+    0.0433, 0.0113, 0.8956
+  );
+  const mat3 AGX_INSET = mat3(
+    0.856627153315983, 0.137318972929847, 0.11189821299995,
+    0.0951212405381588, 0.761241990602591, 0.0767994186031903,
+    0.0482516061458583, 0.101439036467562, 0.811302368396859
+  );
+  const mat3 AGX_OUTSET = mat3(
+    1.1271005818144368, -0.1413297634984383, -0.14132976349843826,
+    -0.11060664309660323, 1.157823702216272, -0.11060664309660294,
+    -0.016493938717834573, -0.016493938717834257, 1.2519364065950405
+  );
+  const mat3 REC2020_TO_SRGB = mat3(
+    1.6605, -0.1246, -0.0182,
+    -0.5876, 1.1329, -0.1006,
+    -0.0728, -0.0083, 1.1187
+  );
+  vec3 c = AGX_INSET * (SRGB_TO_REC2020 * x);
+  /* log2 of middle grey times 2^-10 and 2^6.5: -12.47393 and 4.026069, 16.5 stops apart. */
+  c = clamp((log2(max(c, vec3(1e-10))) + 12.47393) / 16.5, 0.0, 1.0);
+  c = AGX_OUTSET * agxContrast(c);
+  c = pow(max(c, vec3(0.0)), vec3(2.2));
+  return clamp(REC2020_TO_SRGB * c, 0.0, 1.0);
+}
+`;
+/**
+ * The curve for a neutral grey, as the shader computes it: every matrix above keeps grey grey, so
+ * one channel is the whole of it. For a test to pin to hand-derived values.
+ */
+export function agxGrey(linear, exposure = 1) {
+    const x = Math.max(linear * exposure, 1e-10);
+    const t = Math.min(Math.max((Math.log2(x) + 12.47393) / 16.5, 0), 1);
+    const t2 = t * t;
+    const t4 = t2 * t2;
+    const s = 15.5 * t4 * t2 -
+        40.14 * t4 * t +
+        31.96 * t4 -
+        6.868 * t2 * t +
+        0.4298 * t2 +
+        0.1191 * t -
+        0.00232;
+    return Math.min(Math.max(Math.max(s, 0) ** 2.2, 0), 1);
+}

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

@@ -26,11 +26,20 @@
 /**
  * The estimate. Writes one channel: 1 is open sky, 0 is fully enclosed.
  *
- * 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 +52,13 @@ 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;