@driftengine/core 4.3.0 → 4.4.0

package/dist/render/shaders/ambientOcclusion.js

@@ -27,11 +27,20 @@ import { glslIsFarDepth, glslSceneDepthToNdc } from '../depthConvention.js';
 /**
  * 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 const AO_FRAG = `#version 300 es
 precision highp float;
@@ -68,16 +77,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.
  *
@@ -86,25 +97,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.
  *
@@ -133,6 +125,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.
@@ -214,15 +217,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),
@@ -230,41 +234,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));
+    /*
+     * **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.
+     */
+    vec2 screen = vec2(cos(angle) * pixel.x / pixel.y, sin(angle));
     /*
-     * 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.
+     * 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.
      */
-    float sampled = textureLod(uDepth, uv, 0.0).r;
-    if (${glslIsFarDepth('sampled')}) continue;
+    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), 0.0, 1.0);
 }
 `;
 /**
@@ -350,3 +390,20 @@ void main() {
   fragColor = weight > 0.0 ? sum / weight : textureLod(uAo, vUv, 0.0).r;
 }
 `;
+/**
+ * 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, h1, normal) {
+    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, cosine) {
+    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;

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

@@ -0,0 +1,31 @@
+/**
+ * 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 declare 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 declare const CUTOUT_COVERAGE_GLSL: string;
+/** The same, given the level, for a test to pin: what the shader compares against the cutoff. */
+export declare function cutoutAlpha(alpha: number, level: number): number;

package/dist/render/shaders/cutoutCoverage.js

@@ -0,0 +1,40 @@
+/**
+ * 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, level) {
+    return alpha * (1 + Math.max(0, level) * CUTOUT_MIP_SCALE);
+}

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

@@ -11,4 +11,29 @@ export declare const DEPTH_SKINNED_VERT: string;
  * a missing variant, and is the shape the per-draw ring exists to prevent one level up.
  */
 export declare const DEPTH_INSTANCED_VERT: string;
+/**
+ * The variants a cutout caster casts through: a leaf card, a chain link, a fence, whose shape is in
+ * its texture's alpha rather than in its geometry.
+ *
+ * **Variants, not a uniform gate on the plain program**, for this file's own reason: a gate would
+ * need the UV, a varying and a bound texture on every opaque caster, and a branch on a varying is
+ * not provably uniform, which forbids the implicit derivative the sample below wants. A variant
+ * leaves every opaque caster byte for byte as it was. What it costs is one more program each, and
+ * a skinned cutout, which nothing has asked for, is not among them.
+ */
+export declare const DEPTH_CUTOUT_VERT: string;
+export declare const DEPTH_INSTANCED_CUTOUT_VERT: string;
 export declare const DEPTH_FRAG = "#version 300 es\nprecision highp float;\nin vec4 vLightPosition;\n\nuniform highp sampler2D uPreviousShadowMap;\nuniform int uPeelShadowLayer;\n\nvoid main() {\n  if (uPeelShadowLayer != 0) {\n    vec3 p = vLightPosition.xyz / vLightPosition.w;\n    vec2 uv = p.xy * 0.5 + 0.5;\n    float previousDepth = texture(uPreviousShadowMap, uv).r;\n    // Discard the already-recorded surface and everything in front of it. The\n    // ordinary depth test then stores the next independently fading occluder.\n    if (gl_FragCoord.z <= previousDepth + 0.00001) discard;\n  }\n}\n";
+/**
+ * The cutout caster's depth: the plain pass, and a texel of alpha under the cutoff writes nothing.
+ *
+ * **The sample is the first statement, in uniform control flow**, so its implicit derivative picks
+ * the mip the shadow map's texel footprint wants; inside a branch it would be undefined (AGENTS.md,
+ * 2026-08-07). The peel's own sample becomes an explicit-level fetch for the same reason, and is
+ * bit for bit what it was: that map has one level and a nearest sampler. The discard is last, so
+ * nothing samples after it.
+ *
+ * `uCutoutMap` is declared after `uPreviousShadowMap`, so the peel keeps its bindings and the cutout
+ * map takes the next.
+ */
+export declare const DEPTH_CUTOUT_FRAG: string;

package/dist/render/shaders/depth.js

@@ -1,4 +1,5 @@
 import { resolveConditionals } from './conditionals.js';
+import { CUTOUT_COVERAGE_GLSL } from './cutoutCoverage.js';
 import { SKINNING_GLSL } from './skinning.js';
 import { CHANNEL_ATTRIBUTE, CHANNEL_BEND } from './vertexChannel.js';
 /**
@@ -55,7 +56,22 @@ ${CHANNEL_ATTRIBUTE}
 ${CHANNEL_BEND}
 #endif
 
+#if CUTOUT
+/*
+ * **What a cutout caster adds, and where.** The UV at location 5, where every mesh carries it; two
+ * uniforms declared after every other, so no field of the plain variant moves and a binder written
+ * against it stays right for this one; and two outputs after vLightPosition, which keeps location 0.
+ */
+layout(location = 5) in vec2 aUv;
+uniform vec2 uUvScale;
+uniform float uAlphaCutout;
+#endif
+
 out vec4 vLightPosition;
+#if CUTOUT
+out vec2 vUv;
+flat out float vAlphaCutout;
+#endif
 
 void main() {
 #if SKINNED
@@ -79,12 +95,16 @@ void main() {
 #endif
   vLightPosition = uLightViewProj * vec4(bent, world.w);
   gl_Position = vLightPosition;
+#if CUTOUT
+  vUv = aUv * uUvScale;
+  vAlphaCutout = uAlphaCutout;
+#endif
 }
 `;
 /** The rigid variant: the world, a prop, a mesh with no rig behind it. */
-export const DEPTH_VERT = resolveConditionals(DEPTH_VERT_SOURCE, { SKINNED: false, INSTANCED: false }, 'depth');
+export const DEPTH_VERT = resolveConditionals(DEPTH_VERT_SOURCE, { SKINNED: false, INSTANCED: false, CUTOUT: false }, 'depth');
 /** The skinned variant, which reads a joint palette and moves the vertex by it. */
-export const DEPTH_SKINNED_VERT = resolveConditionals(DEPTH_VERT_SOURCE, { SKINNED: true, INSTANCED: false }, 'depth-skinned');
+export const DEPTH_SKINNED_VERT = resolveConditionals(DEPTH_VERT_SOURCE, { SKINNED: true, INSTANCED: false, CUTOUT: false }, 'depth-skinned');
 /**
  * The variant an instanced draw casts its shadow through.
  *
@@ -93,7 +113,19 @@ export const DEPTH_SKINNED_VERT = resolveConditionals(DEPTH_VERT_SOURCE, { SKINN
  * right place and the rest stacked underneath it, which reads as a lighting fault rather than as
  * a missing variant, and is the shape the per-draw ring exists to prevent one level up.
  */
-export const DEPTH_INSTANCED_VERT = resolveConditionals(DEPTH_VERT_SOURCE, { SKINNED: false, INSTANCED: true }, 'depth-instanced');
+export const DEPTH_INSTANCED_VERT = resolveConditionals(DEPTH_VERT_SOURCE, { SKINNED: false, INSTANCED: true, CUTOUT: false }, 'depth-instanced');
+/**
+ * The variants a cutout caster casts through: a leaf card, a chain link, a fence, whose shape is in
+ * its texture's alpha rather than in its geometry.
+ *
+ * **Variants, not a uniform gate on the plain program**, for this file's own reason: a gate would
+ * need the UV, a varying and a bound texture on every opaque caster, and a branch on a varying is
+ * not provably uniform, which forbids the implicit derivative the sample below wants. A variant
+ * leaves every opaque caster byte for byte as it was. What it costs is one more program each, and
+ * a skinned cutout, which nothing has asked for, is not among them.
+ */
+export const DEPTH_CUTOUT_VERT = resolveConditionals(DEPTH_VERT_SOURCE, { SKINNED: false, INSTANCED: false, CUTOUT: true }, 'depth-cutout');
+export const DEPTH_INSTANCED_CUTOUT_VERT = resolveConditionals(DEPTH_VERT_SOURCE, { SKINNED: false, INSTANCED: true, CUTOUT: true }, 'depth-instanced-cutout');
 export const DEPTH_FRAG = `#version 300 es
 precision highp float;
 in vec4 vLightPosition;
@@ -112,3 +144,37 @@ void main() {
   }
 }
 `;
+/**
+ * The cutout caster's depth: the plain pass, and a texel of alpha under the cutoff writes nothing.
+ *
+ * **The sample is the first statement, in uniform control flow**, so its implicit derivative picks
+ * the mip the shadow map's texel footprint wants; inside a branch it would be undefined (AGENTS.md,
+ * 2026-08-07). The peel's own sample becomes an explicit-level fetch for the same reason, and is
+ * bit for bit what it was: that map has one level and a nearest sampler. The discard is last, so
+ * nothing samples after it.
+ *
+ * `uCutoutMap` is declared after `uPreviousShadowMap`, so the peel keeps its bindings and the cutout
+ * map takes the next.
+ */
+export const DEPTH_CUTOUT_FRAG = `#version 300 es
+precision highp float;
+in vec4 vLightPosition;
+in vec2 vUv;
+flat in float vAlphaCutout;
+
+uniform highp sampler2D uPreviousShadowMap;
+uniform int uPeelShadowLayer;
+uniform highp sampler2D uCutoutMap;
+${CUTOUT_COVERAGE_GLSL}
+void main() {
+  /* Credited for its mip level as the surface's own test is, so a leaf casts the shape it draws. */
+  float alpha = cutoutAlpha(texture(uCutoutMap, vUv).a, vUv * vec2(textureSize(uCutoutMap, 0)));
+  if (uPeelShadowLayer != 0) {
+    vec3 p = vLightPosition.xyz / vLightPosition.w;
+    vec2 uv = p.xy * 0.5 + 0.5;
+    float previousDepth = textureLod(uPreviousShadowMap, uv, 0.0).r;
+    if (gl_FragCoord.z <= previousDepth + 0.00001) discard;
+  }
+  if (alpha < vAlphaCutout) discard;
+}
+`;

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

@@ -0,0 +1,52 @@
+/**
+ * Eye adaptation: the frame's own brightness, measured on the GPU and followed over time.
+ *
+ * **A fixed exposure is right for one view and wrong for the next.** A courtyard with the sun on
+ * its upper walls and its floor in the shade of a 19 m wall is several stops darker at ground level
+ * than from the gallery, and an exposure set for one draws the other either clipped or black. A
+ * camera meters and an eye adapts; this does both, from the finished scene, with no readback.
+ *
+ * **Two passes, both tiny.** The meter writes a 32×32 grid, each texel the mean of 8×8 taps of log
+ * luminance over its share of the frame. The adaptation reads all 1,024 of them in one texel,
+ * averages them into the frame's log-mean luminance, and moves the held value toward it by a blend
+ * the caller's frame time decides. The composite reads the held value and scales the scene toward
+ * middle grey. Log luminance, because an eye's response is to ratios: one sunlit pixel beside a
+ * dark frame should not set the exposure the way an arithmetic mean lets it.
+ *
+ * What it gives up is metering by region: every pixel counts the same, so a small bright window in
+ * a dark room pulls less than a photographer's spot meter would. What would change it is a scene
+ * that needs a subject held at a brightness, and the answer then is a centre weight in the meter.
+ */
+/** Texels a side in the meter's grid, and taps a side within each. */
+export declare const METER_GRID = 32;
+export declare const METER_TAPS = 8;
+/** The luminance the meter clamps to, in stops: a black pixel is not minus infinity. */
+export declare const METER_MIN_LOG2 = -12;
+export declare const METER_MAX_LOG2 = 8;
+/** What full adaptation brings the frame's log-mean luminance to: middle grey. */
+export declare const ADAPTED_KEY = 0.18;
+/** The furthest adaptation moves the exposure either way, in stops. A black loading screen is not a
+ *  reason to multiply the next frame by a thousand. */
+export declare const ADAPT_RANGE_STOPS = 6;
+/**
+ * How fast the held brightness follows the measured one, per second: 1.5 closes about 78% of the
+ * way in a second. An eye takes longer to open than to close, and a camera's meter is faster than
+ * either; one rate is what a scene that cuts between shots can predict.
+ */
+export declare const ADAPT_RATE = 1.5;
+export declare const EXPOSURE_METER_FRAG: string;
+export declare const EXPOSURE_ADAPT_FRAG: string;
+/**
+ * `uAutoExposure`, `uExposureHeld` and `autoExposureGain`, for the composite. The gain scales scene
+ * light before the tone curve, toward the key by the fraction the caller asked for.
+ */
+export declare const AUTO_EXPOSURE_GLSL: string;
+/**
+ * The fraction of the way toward this frame's measurement to move, after `dtSec` seconds. A cut,
+ * or a first frame with nothing held, snaps.
+ */
+export declare function adaptBlend(dtSec: number, snap: boolean): number;
+/** The scene's gain for a held log-mean `heldLog2` at `strength`, as the composite computes it. */
+export declare function autoExposureGain(heldLog2: number, strength: number): number;
+/** An adaptation strength as the shader takes it: 0 to 1, anything else off. */
+export declare function clampAutoExposure(strength: number): number;

package/dist/render/shaders/exposure.js

@@ -0,0 +1,124 @@
+/**
+ * Eye adaptation: the frame's own brightness, measured on the GPU and followed over time.
+ *
+ * **A fixed exposure is right for one view and wrong for the next.** A courtyard with the sun on
+ * its upper walls and its floor in the shade of a 19 m wall is several stops darker at ground level
+ * than from the gallery, and an exposure set for one draws the other either clipped or black. A
+ * camera meters and an eye adapts; this does both, from the finished scene, with no readback.
+ *
+ * **Two passes, both tiny.** The meter writes a 32×32 grid, each texel the mean of 8×8 taps of log
+ * luminance over its share of the frame. The adaptation reads all 1,024 of them in one texel,
+ * averages them into the frame's log-mean luminance, and moves the held value toward it by a blend
+ * the caller's frame time decides. The composite reads the held value and scales the scene toward
+ * middle grey. Log luminance, because an eye's response is to ratios: one sunlit pixel beside a
+ * dark frame should not set the exposure the way an arithmetic mean lets it.
+ *
+ * What it gives up is metering by region: every pixel counts the same, so a small bright window in
+ * a dark room pulls less than a photographer's spot meter would. What would change it is a scene
+ * that needs a subject held at a brightness, and the answer then is a centre weight in the meter.
+ */
+/** Texels a side in the meter's grid, and taps a side within each. */
+export const METER_GRID = 32;
+export const METER_TAPS = 8;
+/** The luminance the meter clamps to, in stops: a black pixel is not minus infinity. */
+export const METER_MIN_LOG2 = -12;
+export const METER_MAX_LOG2 = 8;
+/** What full adaptation brings the frame's log-mean luminance to: middle grey. */
+export const ADAPTED_KEY = 0.18;
+/** The furthest adaptation moves the exposure either way, in stops. A black loading screen is not a
+ *  reason to multiply the next frame by a thousand. */
+export const ADAPT_RANGE_STOPS = 6;
+/**
+ * How fast the held brightness follows the measured one, per second: 1.5 closes about 78% of the
+ * way in a second. An eye takes longer to open than to close, and a camera's meter is faster than
+ * either; one rate is what a scene that cuts between shots can predict.
+ */
+export const ADAPT_RATE = 1.5;
+export const EXPOSURE_METER_FRAG = `#version 300 es
+precision highp float;
+
+in vec2 vUv;
+
+/** The finished scene, in scene light, before any exposure or curve. */
+uniform highp sampler2D uScene;
+
+out float fragColor;
+
+void main() {
+  /* This texel's corner, and taps spread evenly over its share of the frame. */
+  vec2 corner = vUv - vec2(0.5 / ${METER_GRID.toFixed(1)});
+  float sum = 0.0;
+  for (int y = 0; y < ${METER_TAPS}; y++) {
+    for (int x = 0; x < ${METER_TAPS}; x++) {
+      vec2 uv = corner + (vec2(float(x), float(y)) + 0.5) / ${(METER_GRID * METER_TAPS).toFixed(1)};
+      vec3 c = textureLod(uScene, uv, 0.0).rgb;
+      float luma = dot(c, vec3(0.2126, 0.7152, 0.0722));
+      sum += clamp(log2(max(luma, 1e-8)), ${METER_MIN_LOG2.toFixed(1)}, ${METER_MAX_LOG2.toFixed(1)});
+    }
+  }
+  fragColor = sum / ${(METER_TAPS * METER_TAPS).toFixed(1)};
+}
+`;
+export const EXPOSURE_ADAPT_FRAG = `#version 300 es
+precision highp float;
+
+/** The meter's grid of log luminances. */
+uniform highp sampler2D uMeter;
+/** The brightness held from the frames before, in stops, one texel. */
+uniform highp sampler2D uHeld;
+/** How far toward this frame's measurement to move: 1 snaps, 0 holds. */
+uniform float uBlend;
+
+out float fragColor;
+
+void main() {
+  float sum = 0.0;
+  for (int y = 0; y < ${METER_GRID}; y++) {
+    for (int x = 0; x < ${METER_GRID}; x++) {
+      sum += texelFetch(uMeter, ivec2(x, y), 0).r;
+    }
+  }
+  float measured = sum / ${(METER_GRID * METER_GRID).toFixed(1)};
+  float held = texelFetch(uHeld, ivec2(0, 0), 0).r;
+  fragColor = mix(held, measured, uBlend);
+}
+`;
+/**
+ * `uAutoExposure`, `uExposureHeld` and `autoExposureGain`, for the composite. The gain scales scene
+ * light before the tone curve, toward the key by the fraction the caller asked for.
+ */
+export const AUTO_EXPOSURE_GLSL = `
+/** How far the frame adapts toward middle grey, 0 to 1. 0 is off and the whole of the off path. */
+uniform float uAutoExposure;
+/** The held log-mean luminance, in stops, one texel. */
+uniform highp sampler2D uExposureHeld;
+
+float autoExposureGain() {
+  if (uAutoExposure <= 0.0) return 1.0;
+  float held = texelFetch(uExposureHeld, ivec2(0, 0), 0).r;
+  float stops = uAutoExposure * (${Math.log2(ADAPTED_KEY).toFixed(6)} - held);
+  return exp2(clamp(stops, -${ADAPT_RANGE_STOPS.toFixed(1)}, ${ADAPT_RANGE_STOPS.toFixed(1)}));
+}
+`;
+/**
+ * The fraction of the way toward this frame's measurement to move, after `dtSec` seconds. A cut,
+ * or a first frame with nothing held, snaps.
+ */
+export function adaptBlend(dtSec, snap) {
+    if (snap)
+        return 1;
+    if (!(dtSec > 0))
+        return 0;
+    return 1 - Math.exp(-ADAPT_RATE * dtSec);
+}
+/** The scene's gain for a held log-mean `heldLog2` at `strength`, as the composite computes it. */
+export function autoExposureGain(heldLog2, strength) {
+    if (!(strength > 0))
+        return 1;
+    const stops = strength * (Math.log2(ADAPTED_KEY) - heldLog2);
+    return 2 ** Math.min(Math.max(stops, -ADAPT_RANGE_STOPS), ADAPT_RANGE_STOPS);
+}
+/** An adaptation strength as the shader takes it: 0 to 1, anything else off. */
+export function clampAutoExposure(strength) {
+    return Number.isFinite(strength) ? Math.min(Math.max(strength, 0), 1) : 0;
+}