@driftengine/core 4.3.0 → 4.4.1

package/src/render/sceneTarget.ts

@@ -1,5 +1,9 @@
 import { glSceneDepthFormat } from './depthConvention.ts';
+import { clampGrain, clampVignette, grainSeed } from './shaders/filmLook.ts';
 import { AmbientOcclusionPass } from './ambientOcclusionPass.ts';
+import { ExposurePass } from './exposurePass.ts';
+import { clampAutoExposure } from './shaders/exposure.ts';
+import { clampLocalExposure } from './shaders/localExposure.ts';
 import { BloomPass } from './bloomPass.ts';
 import {
   type ColourGradeLut,
@@ -91,6 +95,16 @@ export class SceneTarget {
   private gradeSource: ColourGradeLut | null = null;
   private gradeSize = GRADE_PLACEHOLDER_SIZE;
   private gradeStrength = 0;
+  /** The lens and the print, held like the grade. See `filmLook.ts`. */
+  private vignette = 0;
+  private grain = 0;
+  private grainSeed = 0;
+  /** Eye adaptation: how far, and this frame's time step. See `Renderer.setAutoExposure`. */
+  private autoExposure = 0;
+  private autoExposureDt = 0;
+  /** How far each region is brought toward the frame. See `Renderer.setLocalExposure`. */
+  private localExposure = 0;
+  private exposure: ExposurePass | null = null;
   private width = 0;
   private height = 0;
 
@@ -606,6 +620,33 @@ 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: number): void {
+    this.vignette = clampVignette(strength);
+  }
+
+  /** The print's grain and this frame's seed, held until changed. See `Renderer.setFilmGrain`. */
+  setFilmGrain(strength: number, seed: number): void {
+    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: number, dtSec: number): void {
+    this.autoExposure = clampAutoExposure(strength);
+    this.autoExposureDt = dtSec;
+  }
+
+  /** How far each region is brought toward the frame. See `Renderer.setLocalExposure`. */
+  setLocalExposure(strength: number): void {
+    this.localExposure = clampLocalExposure(strength);
+  }
+
+  /** A new shot: the eye meters it afresh rather than easing in from the last one. */
+  cutExposure(): void {
+    this.exposure?.cut();
+  }
+
   setColourGrade(lut: ColourGradeLut | null, strength: number): void {
     this.gradeStrength = lut === null ? 0 : Math.max(0, Math.min(1, strength));
     if (lut === null || lut === this.gradeSource) return;
@@ -851,6 +892,17 @@ export class SceneTarget {
       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: WebGLTexture | null = 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);
@@ -946,6 +998,25 @@ 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
@@ -954,6 +1025,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);
@@ -970,7 +1043,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);
     }
@@ -999,6 +1072,7 @@ export class SceneTarget {
   dispose(): void {
     const { gl } = this;
     this.ao?.dispose();
+    this.exposure?.dispose();
     this.ao = null;
     this.bloom?.dispose();
     this.bloom = null;

package/src/render/shaders/ambientOcclusion.ts

@@ -26,13 +26,23 @@ import { glslIsFarDepth, glslSceneDepthToNdc } from '../depthConvention.ts';
  */
 
 /**
- * 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 const AO_FRAG = `#version 300 es
 precision highp float;
@@ -69,16 +79,18 @@ uniform float uRadius;
 
 out float fragColor;
 
-/** How many depths each pixel compares itself against. Fixed, so the cost is fixed. */
-const int AO_TAPS = 12;
+/** Lines across the screen a pixel walks, each both ways. Fixed, so the cost is fixed. */
+const int AO_SLICES = 2;
+/** Depth samples each way along a line: two lines, two ways, six steps is 24 a pixel. */
+const int AO_STEPS = 6;
 /**
- * The golden angle, in radians.
+ * How far the horizon sinks back toward each later sample once the walk has passed the highest one.
  *
- * Successive taps turned by it never line up into spokes, which a rational fraction of a
- * turn does: a kernel that repeats a direction is blind along it, and it is blind the same
- * way in every pixel, so it reads as a pattern in the surface rather than as noise.
+ * The paper's thickness heuristic. At zero anything within the radius shades for good, which is the
+ * halo; at one a horizon lasts one sample and a real corner loses its shade. A fifth keeps a corner,
+ * whose samples keep rising, and lets a curtain's shade drop within the few samples past its edge.
  */
-const float AO_GOLDEN_ANGLE = 2.39996323;
+const float AO_THIN = 0.2;
 /**
  * How far the sampling may reach across the frame, whatever the depth says.
  *
@@ -87,25 +99,6 @@ const float AO_GOLDEN_ANGLE = 2.39996323;
  * being contact shading and becomes an expensive wide darkening. 6% of the frame.
  */
 const float AO_MAX_REACH_UV = 0.06;
-/**
- * Self-occlusion guard, as a fraction of the pixel's own view depth.
- *
- * Depth is quantised, so a flat surface samples itself very slightly in front of itself and
- * every flat surface in the world comes back faintly dirty. The error grows with distance,
- * which is why the guard is proportional to depth rather than a constant.
- */
-const float AO_BIAS = 0.004;
-/**
- * The floor under the 1 / (v·v) weighting, in square metres.
- *
- * Not a guard against dividing by zero, which is what a value near the float epsilon would
- * be. The nearest taps land about a centimetre away, where v·v is 1e-4 and the weight is ten
- * thousand — so a depth quantised to a millimetre yields several units of occlusion out of
- * nothing at all. Measured that way first, with 1e-4 here: a flat floor came back as static.
- * A hundredth of a square metre is a tenth of a metre of separation, which is the scale
- * below which two samples are the same surface rather than one occluding the other.
- */
-const float AO_EPSILON = 0.01;
 /**
  * How many times further one neighbour may be than the other before the pair straddles an edge.
  *
@@ -126,6 +119,8 @@ const float AO_EDGE_RATIO = 8.0;
  * and far below the step at any edge worth shading — a kerb against a deck is metres of it.
  */
 const float AO_EDGE_FLOOR = 0.05;
+/** Stored at half, so a turn the closed form credits past one reaches the blur whole. See AO_STORE in the module. */
+const float AO_STORE = 0.5;
 
 /** View-space position of whatever is at this pixel, from its depth alone. */
 vec3 viewPosition(vec2 uv, float depth) {
@@ -134,6 +129,17 @@ vec3 viewPosition(vec2 uv, float depth) {
   return view.xyz / view.w;
 }
 
+/**
+ * The cosine-weighted sky between two horizon angles h0 < 0 < h1, measured from the eye, for a
+ * normal at the angle given in the same plane: the paper's closed form. 1 for an open plane facing
+ * the eye.
+ */
+float gtaoArc(float h0, float h1, float normal) {
+  float c = cos(normal);
+  float s2 = 2.0 * sin(normal);
+  return 0.25 * (-cos(2.0 * h0 - normal) + c + h0 * s2) + 0.25 * (-cos(2.0 * h1 - normal) + c + h1 * s2);
+}
+
 void main() {
   /*
    * One output pixel, in UV, along each axis.
@@ -215,15 +221,16 @@ void main() {
   vec3 n = normalize(cross(dpdx, dpdy));
   /*
    * Turned to face the eye. Which sign the cross product comes out with is a fact about the
-   * screen-space winding and the handedness of the projection, and a normal pointing away
-   * from the camera makes every v·n come back zero, which is a frame with no occlusion in it
-   * anywhere. In view space the eye is the origin, so a normal facing it satisfies n·p < 0.
+   * screen-space winding and the handedness of the projection, and a normal pointing away from the
+   * camera puts every horizon behind the surface. In view space the eye is the origin, so a normal
+   * facing it satisfies n·p < 0.
    */
   if (dot(n, p) > 0.0) n = -n;
+  vec3 toEye = normalize(-p);
 
   /*
-   * The radius as a fraction of the frame. A metre subtends less of the screen the further
-   * away it is, which is the entire reason this is computed per pixel rather than handed in.
+   * The radius as a fraction of the frame. A metre subtends less of the screen the further away it
+   * is, which is the entire reason this is computed per pixel rather than handed in.
    */
   vec2 reach = min(
     uRadius * uProjScale * 0.5 / max(-p.z, 1e-3),
@@ -231,41 +238,77 @@ void main() {
   );
 
   /*
-   * A rotation that repeats every four pixels: sixteen distinct turns laid out over a 4x4
-   * tile. Paired with the four-wide blur that follows, every blurred pixel averages all
-   * sixteen, which is what makes twelve taps enough. A per-pixel hash would decorrelate
-   * neighbours better in principle and is worse here, because the blur can then only soften
-   * the noise rather than complete the kernel.
+   * A rotation that repeats every four pixels: sixteen turns laid out over a 4x4 tile, spanning the
+   * quarter turn between one line and the next, so the eight-wide blur that follows averages every
+   * turn of both lines. The first step's distance is staggered by the same tile, so neighbouring
+   * pixels do not all sample the same rings either.
    */
   float tile = mod(gl_FragCoord.x, 4.0) + 4.0 * mod(gl_FragCoord.y, 4.0);
-  float turn = tile * (6.2831853 / 16.0);
-
-  float sum = 0.0;
-  for (int i = 0; i < AO_TAPS; i++) {
-    float t = (float(i) + 0.5) / float(AO_TAPS);
-    float angle = turn + float(i) * AO_GOLDEN_ANGLE;
-    /* The square root spreads the taps evenly over the disk; without it they crowd the
-       centre, where they are measuring the pixel's own depth. */
-    vec2 uv = vUv + vec2(cos(angle), sin(angle)) * sqrt(t) * reach;
+  float turn = tile * (1.5707963 / 16.0);
+  float stagger = fract(tile * 0.618034);
+  /* One output pixel along each axis, in UV. */
+  vec2 pixel = vec2(length(stepX), length(stepY));
 
+  float visible = 0.0;
+  for (int slice = 0; slice < AO_SLICES; slice++) {
+    float angle = turn + float(slice) * (3.1415927 / float(AO_SLICES));
     /*
-     * textureLod, not texture, and it is the rule rather than a preference: this sample sits
-     * inside a loop whose iterations a compiler cannot prove uniform, and an implicit
-     * derivative there is what lets one flatten the body and pay for every arm. The fetch is
-     * identical — the depth texture has one storage level and NEAREST filters, so there is no
-     * mip for a derivative to select. See AGENTS.md, 2026-08-07.
+     * **Even in pixels, not in UV.** A UV step across a wide frame is longer than one down it, so
+     * turns spread evenly in UV crowd toward the horizontal once they reach the screen, and on a
+     * floor the horizontal lines are the ones that see least of its normal: every flat floor and
+     * ceiling came back at 0.82 open, measured, where the construction gives 0.97. A pixel is as
+     * wide as it is tall in view space, so a direction even in pixels is even in the world. It is
+     * scaled here into UV, and the reach is taken down the frame, whose UV is the same pixels.
      */
-    float sampled = textureLod(uDepth, uv, 0.0).r;
-    if (${glslIsFarDepth('sampled')}) continue;
+    vec2 screen = vec2(cos(angle) * pixel.x / pixel.y, sin(angle));
+    /*
+     * The line in view space, taken through the same reconstruction the samples use: a step along
+     * the screen at this pixel's own depth, so the samples lie in the plane the arc is measured in
+     * whatever the frame's aspect and whichever way a backend's clip space counts up.
+     */
+    vec3 along = normalize(viewPosition(vUv + screen * 1e-3, depth) - p);
+    vec3 across = normalize(along - toEye * dot(along, toEye));
+    vec3 axis = cross(across, toEye);
+    /* The normal projected into the line's plane, and its angle from the eye toward +across. */
+    vec3 projected = n - axis * dot(n, axis);
+    float projectedLength = length(projected);
+    if (projectedLength < 1e-4) continue;
+    float normalAngle = atan(dot(projected, across), dot(projected, toEye));
 
-    vec3 v = viewPosition(uv, sampled) - p;
-    float vv = dot(v, v);
-    /* Past the radius it is a different surface rather than a neighbour of this one. */
-    if (vv > uRadius * uRadius) continue;
-    sum += max(0.0, dot(v, n) - AO_BIAS * (-p.z)) / (vv + AO_EPSILON);
+    /* The highest cosine seen each way. */
+    float horizon0 = -1.0;
+    float horizon1 = -1.0;
+    for (int k = 0; k < AO_STEPS; k++) {
+      float t = (float(k) + stagger) / float(AO_STEPS);
+      /* Squared, so the steps crowd the pixel, where contact shade lives. */
+      vec2 stride = screen * reach.y * (t * t + 0.5 / float(AO_STEPS * AO_STEPS));
+      for (int side = 0; side < 2; side++) {
+        vec2 uv = side == 0 ? vUv - stride : vUv + stride;
+        /*
+         * textureLod, not texture, and it is the rule rather than a preference: this sits inside a
+         * loop whose iterations a compiler cannot prove uniform. The depth texture has one level and
+         * NEAREST filters, so the fetch is identical. See AGENTS.md, 2026-08-07.
+         */
+        float sampled = textureLod(uDepth, uv, 0.0).r;
+        if (${glslIsFarDepth('sampled')}) continue;
+        vec3 v = viewPosition(uv, sampled) - p;
+        float distance2 = dot(v, v);
+        if (distance2 < 1e-8) continue;
+        float cosine = dot(v, toEye) * inversesqrt(distance2);
+        /* Faded to nothing at the radius: a far wall is not an occluder of this surface. */
+        float fade = clamp(1.0 - distance2 / (uRadius * uRadius), 0.0, 1.0);
+        cosine = mix(-1.0, cosine, fade);
+        if (side == 0) horizon0 = cosine > horizon0 ? cosine : mix(horizon0, cosine, AO_THIN);
+        else horizon1 = cosine > horizon1 ? cosine : mix(horizon1, cosine, AO_THIN);
+      }
+    }
+    /* Angles from the eye, negative toward -across, and never below the surface's own tangent. */
+    float h0 = max(-acos(clamp(horizon0, -1.0, 1.0)), normalAngle - 1.5707963);
+    float h1 = min(acos(clamp(horizon1, -1.0, 1.0)), normalAngle + 1.5707963);
+    visible += projectedLength * gtaoArc(h0, h1, normalAngle);
   }
 
-  fragColor = clamp(1.0 - 2.0 * uRadius * sum / float(AO_TAPS), 0.0, 1.0);
+  fragColor = clamp(visible / float(AO_SLICES) * AO_STORE, 0.0, 1.0);
 }
 `;
 
@@ -295,12 +338,14 @@ uniform vec2 uStep;
  * asks that question five times per pixel.
  */
 uniform vec4 uDepthToViewZ;
+/** One across, carrying the estimate's AO_STORE scale; its inverse down, decoding it. */
+uniform float uAoScale;
 
 out float fragColor;
 
 /**
- * How far apart two pixels may be, as a fraction of their distance from the eye, before they
- * stop being the same surface.
+ * How far a neighbour may sit from the depth this pixel's own surface predicts there, as a
+ * fraction of that depth, before it stops being the same surface.
  *
  * Relative rather than absolute, because the same 5 cm step is a cliff on a dashboard and
  * nothing at all on a far wall.
@@ -313,8 +358,19 @@ float viewZ(float depth) {
 }
 
 void main() {
-  float centre = viewZ(textureLod(uDepth, vUv, 0.0).r);
-  float tolerance = AO_BLUR_DEPTH_TOLERANCE * abs(centre) + 1e-4;
+  float depth = textureLod(uDepth, vUv, 0.0).r;
+  float own = textureLod(uAo, vUv, 0.0).r;
+  /* Nothing to average over the sky, and no surface to predict one from. */
+  if (${glslIsFarDepth('depth')}) {
+    fragColor = min(own * uAoScale, 1.0);
+    return;
+  }
+  float centre = viewZ(depth);
+  /* Each tap is compared with this pixel's plane, not with its depth. See blurWeight in the module. */
+  float inverse = 1.0 / centre;
+  float stepAfter = 1.0 / viewZ(textureLod(uDepth, vUv + uStep, 0.0).r) - inverse;
+  float stepBefore = inverse - 1.0 / viewZ(textureLod(uDepth, vUv - uStep, 0.0).r);
+  float slope = abs(stepAfter) < abs(stepBefore) ? stepAfter : stepBefore;
   float sum = 0.0;
   float weight = 0.0;
   /*
@@ -342,13 +398,91 @@ void main() {
   for (int i = -3; i <= 4; i++) {
     vec2 uv = vUv + uStep * float(i);
     float z = viewZ(textureLod(uDepth, uv, 0.0).r);
-    /* One if this neighbour is on the same surface, falling to zero across an edge. */
-    float w = max(0.0, 1.0 - abs(z - centre) / tolerance);
+    /* One if this neighbour is on this pixel's surface, falling to zero as it leaves it. */
+    float w = max(0.0, 1.0 - abs(z * (inverse + slope * float(i)) - 1.0) / AO_BLUR_DEPTH_TOLERANCE);
     sum += textureLod(uAo, uv, 0.0).r * w;
     weight += w;
   }
   /* An isolated pixel — a thin rail against a far wall — keeps its own estimate rather than
      dividing by nothing. */
-  fragColor = weight > 0.0 ? sum / weight : textureLod(uAo, vUv, 0.0).r;
+  float blurred = weight > 0.0 ? sum / weight : own;
+  fragColor = min(blurred * uAoScale, 1.0);
 }
 `;
+
+/**
+ * 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 function gtaoArc(h0: number, h1: number, normal: number): number {
+  const c = Math.cos(normal);
+  const s2 = 2 * Math.sin(normal);
+  return (
+    0.25 * (-Math.cos(2 * h0 - normal) + c + h0 * s2) +
+    0.25 * (-Math.cos(2 * h1 - normal) + c + h1 * s2)
+  );
+}
+
+/** One step of a horizon: up to a higher sample, or a fifth of the way down toward a lower one. */
+export function nextHorizon(horizon: number, cosine: number): number {
+  return cosine > horizon ? cosine : horizon + (cosine - horizon) * AO_THIN;
+}
+
+/** The shader's thickness heuristic. See `AO_THIN` inside `AO_FRAG`. */
+export 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 const AO_STORE = 0.5;
+
+/** How far a neighbour may sit from this pixel's surface, as a fraction of its distance. */
+export 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 function blurWeight(
+  centre: number,
+  before: number,
+  after: number,
+  neighbour: number,
+  offset: number,
+): number {
+  const inverse = 1 / centre;
+  const stepAfter = 1 / after - inverse;
+  const stepBefore = inverse - 1 / before;
+  const slope = Math.abs(stepAfter) < Math.abs(stepBefore) ? stepAfter : stepBefore;
+  return Math.max(
+    0,
+    1 - Math.abs(neighbour * (inverse + slope * offset) - 1) / AO_BLUR_DEPTH_TOLERANCE,
+  );
+}

package/src/render/shaders/cutoutCoverage.ts

@@ -0,0 +1,43 @@
+/**
+ * A cutout that keeps its coverage down the mip chain.
+ *
+ * **Averaging alpha thins everything that is thinner than a texel.** Each level of a mip chain is
+ * the mean of four texels of the one above, so a needle one texel wide on a clear background is 0.5
+ * at the next level, 0.25 at the one after, and gone against a cutoff of 0.5 two levels down. A
+ * tree that is dense up close then stands bare a few metres off, which on a bought courtyard was a
+ * cypress drawn as bare branches at 1280 pixels across and in full leaf at 2000.
+ *
+ * **So the test scales alpha up by the level it is sampling**: a quarter more per level, the figure
+ * Ben Golus measured on foliage in "Anti-aliased Alpha Test" (2017). Only the test sees the scaled
+ * value; what a translucent draw blends with is the texture's own alpha, and a material with no
+ * cutoff is untouched. What it gives up is exactness: coverage is held roughly rather than measured
+ * per image, which Ignacio Castaño's method would do at upload from a readback this engine does not
+ * make. What would make it wrong is an image whose mips were built to keep coverage already, which
+ * this would then thicken.
+ *
+ * The level is estimated from the texture coordinate's screen derivatives, the isotropic formula;
+ * a sampler with anisotropic filtering reads a lower level at a grazing angle, so there a cutout
+ * comes out slightly fuller than its own mip would have made it.
+ */
+
+/** How much more alpha each mip level down is credited with in the test. */
+export const CUTOUT_MIP_SCALE = 0.25;
+
+/**
+ * `cutoutAlpha(alpha, texels)`: the alpha the cutout test should see, for a sample at `texels`, the
+ * texture coordinate times the texture's size. Called in uniform control flow, since it takes
+ * derivatives.
+ */
+export const CUTOUT_COVERAGE_GLSL = `
+float cutoutAlpha(float alpha, vec2 texels) {
+  vec2 dx = dFdx(texels);
+  vec2 dy = dFdy(texels);
+  float level = max(0.0, 0.5 * log2(max(dot(dx, dx), dot(dy, dy))));
+  return alpha * (1.0 + level * ${CUTOUT_MIP_SCALE.toFixed(2)});
+}
+`;
+
+/** The same, given the level, for a test to pin: what the shader compares against the cutoff. */
+export function cutoutAlpha(alpha: number, level: number): number {
+  return alpha * (1 + Math.max(0, level) * CUTOUT_MIP_SCALE);
+}