@driftengine/core 4.2.1 → 4.4.0

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

@@ -28,11 +28,20 @@ import { glslIsFarDepth, glslSceneDepthToNdc } from '../depthConvention.ts';
 /**
  * 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;
@@ -69,16 +78,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 +98,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.
  *
@@ -134,6 +126,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 +218,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 +235,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);
 }
 `;
 
@@ -352,3 +392,25 @@ 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: 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;

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);
+}

package/src/render/shaders/depth.ts

@@ -1,4 +1,5 @@
 import { resolveConditionals } from './conditionals.ts';
+import { CUTOUT_COVERAGE_GLSL } from './cutoutCoverage.ts';
 import { SKINNING_GLSL } from './skinning.ts';
 import { CHANNEL_ATTRIBUTE, CHANNEL_BEND } from './vertexChannel.ts';
 
@@ -56,7 +57,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
@@ -80,20 +96,24 @@ 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 },
+  { 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 },
+  { SKINNED: true, INSTANCED: false, CUTOUT: false },
   'depth-skinned',
 );
 
@@ -107,10 +127,32 @@ export const DEPTH_SKINNED_VERT = resolveConditionals(
  */
 export const DEPTH_INSTANCED_VERT = resolveConditionals(
   DEPTH_VERT_SOURCE,
-  { SKINNED: false, INSTANCED: true },
+  { 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;
@@ -129,3 +171,38 @@ 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;
+}
+`;