@driftengine/core 4.2.1 → 4.4.0

package/src/render/shaders/exposure.ts

@@ -0,0 +1,128 @@
+/**
+ * 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: number, snap: boolean): number {
+  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: number, strength: number): number {
+  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: number): number {
+  return Number.isFinite(strength) ? Math.min(Math.max(strength, 0), 1) : 0;
+}

package/src/render/shaders/filmLook.ts

@@ -0,0 +1,111 @@
+/**
+ * The lens and the print: a vignette in scene light, and grain in display values.
+ *
+ * **The vignette is the lens's, so it acts on light rather than on the picture.** A lens loses light
+ * toward its corners by roughly the fourth power of the cosine of the angle off axis, which for a
+ * point `r` from the centre is `1 / (1 + k r^2)^2`. Applied to scene light before the tone curve,
+ * a bright corner rolls off through the curve's shoulder the way a photographed one does, where a
+ * vignette painted over the finished picture greys it. `r` is measured to the frame's corner on a
+ * circle, not an ellipse, so a wide window is not darker at its sides than at its top.
+ *
+ * **The grain is the print's, so it acts on display values after the grade and the veil.** It is
+ * one value a pixel, the same on all three channels, weighted toward the midtones where film shows
+ * it and kept faint in deep shadow and highlight, where adding it would lift black and grey white.
+ * It also dithers: a dark gradient quantised to eight bits bands, and a noise of a few levels breaks
+ * the bands up. **The seed is the caller's**, because the engine takes time from its caller: a held
+ * capture passes the same seed and is identical run to run, and a playing scene passes a new one
+ * each frame and the grain moves as film does.
+ *
+ * Zero strength for each is the whole of its off path: a branch on a uniform, and the frame is what
+ * it was byte for byte.
+ */
+
+/**
+ * `uVignette`, `uGrain`, `withVignette` and `withGrain`. The rush composite includes it once.
+ *
+ * `withVignette` takes the pixel's coordinate and the scene's size, since a distance to the corner
+ * has to know the aspect. `withGrain` takes the fragment's integer position, so the grain is one
+ * value a pixel whatever the resolution.
+ */
+export const FILM_LOOK_GLSL = `
+/** How strongly the lens darkens its corners: 0 is none, 0.5 about 1.2 stops at the corner. */
+uniform float uVignette;
+/** x: the grain's amplitude in display values, 0 for none. y: this frame's seed, the caller's. */
+uniform vec2 uGrain;
+
+vec3 withVignette(vec3 c, vec2 uv, vec2 size) {
+  if (uVignette <= 0.0) return c;
+  vec2 d = (uv - 0.5) * size;
+  vec2 corner = 0.5 * size;
+  float r2 = dot(d, d) / dot(corner, corner);
+  float falloff = 1.0 + uVignette * r2;
+  return c / (falloff * falloff);
+}
+
+float grainNoise(uvec2 p, uint seed) {
+  uint h = p.x * 1664525u + p.y * 1013904223u + seed * 2654435769u;
+  h ^= h >> 16u;
+  h *= 2246822519u;
+  h ^= h >> 13u;
+  h *= 3266489917u;
+  h ^= h >> 16u;
+  return float(h) * (1.0 / 4294967295.0);
+}
+
+vec3 withGrain(vec3 c, vec2 fragCoord) {
+  if (uGrain.x <= 0.0) return c;
+  float luma = dot(clamp(c, 0.0, 1.0), vec3(0.2126, 0.7152, 0.0722));
+  float weight = 0.25 + 3.0 * luma * (1.0 - luma);
+  float n = grainNoise(uvec2(fragCoord), uint(uGrain.y)) - 0.5;
+  return c + vec3(2.0 * n * uGrain.x * weight);
+}
+`;
+
+/**
+ * The vignette's factor at `uv` on a `width` by `height` frame, as the shader computes it.
+ * The shader's arithmetic written out once more, so a test can pin it to hand-derived values.
+ */
+export function vignetteFactor(
+  u: number,
+  v: number,
+  width: number,
+  height: number,
+  strength: number,
+): number {
+  if (strength <= 0) return 1;
+  const dx = (u - 0.5) * width;
+  const dy = (v - 0.5) * height;
+  const r2 = (dx * dx + dy * dy) / (0.25 * (width * width + height * height));
+  const falloff = 1 + strength * r2;
+  return 1 / (falloff * falloff);
+}
+
+/** How much of the grain a display luminance takes: full in the midtones, a quarter at the ends. */
+export function grainWeight(luma: number): number {
+  const l = Math.min(Math.max(luma, 0), 1);
+  return 0.25 + 3 * l * (1 - l);
+}
+
+/** Both backends' words when there is no composite to apply the look in. */
+export const FILM_LOOK_WITHOUT_COMPOSITE =
+  '[driftengine] setVignette and setFilmGrain need `screenEffects`: without a composite every ' +
+  'pass is the last thing to touch the frame, so there is no one place to apply a lens or a ' +
+  'print. The look was not applied.';
+
+/** A vignette strength as the shader takes it: 0 to 4, anything else off. */
+export function clampVignette(strength: number): number {
+  return Number.isFinite(strength) ? Math.min(Math.max(strength, 0), 4) : 0;
+}
+
+/** A grain amplitude in display values: 0 to 0.5, anything else off. */
+export function clampGrain(strength: number): number {
+  return Number.isFinite(strength) ? Math.min(Math.max(strength, 0), 0.5) : 0;
+}
+
+/**
+ * A seed as the shader reads it: a whole number below 2^24, which a 32-bit float carries exactly,
+ * so the same seed is the same grain on both backends. Any number a caller has is accepted.
+ */
+export function grainSeed(seed: number): number {
+  return Number.isFinite(seed) ? Math.floor(Math.abs(seed)) % 16777216 : 0;
+}

package/src/render/shaders/flat/directionalShadow.ts

@@ -68,10 +68,13 @@ float shadowFactor(float directionalNdl) {
   // Near a surface's own light terminator its direct-light term is already
   // approaching zero, while the orthographic projection of that surface
   // collapses toward a line. No finite contact-safe bias can represent that
-  // slope reliably. Fade only the shadow modulation through this narrow band;
-  // the Lambert term still supplies the physically dominant falloff.
+  // slope reliably, so through this band the fine filter below hands over to the
+  // coarse test after it. \`directionalNdl\` is the surface's own, before any normal
+  // map: the band is about the receiving plane, and a map's tilt says nothing about it.
   float receiverFade = smoothstep(0.08, 0.20, directionalNdl);
-  if (receiverFade <= 0.0) return 1.0;
+  /* A surface turned from the light takes none of it, so there is nothing to shadow; what reads
+     this there is the emissive share, which has always seen such a surface as unshadowed. */
+  if (directionalNdl <= 0.0) return 1.0;
 
   // The receiver stays at its real position, computed above. A normal offset changes
   // direction at a hard mesh edge and tears one continuous shadow where it crosses from
@@ -104,6 +107,34 @@ float shadowFactor(float directionalNdl) {
   );
   if (lowElevationFade <= 0.0) return 1.0;
 
+  /*
+   * **The coarse test: is there anything a metre or more between this point and the sun.**
+   *
+   * One tap at the receiver's own texel, with a metre of tolerance where the filter below allows
+   * fourteen centimetres. It cannot see a contact shadow, and it does not need the plane's slope:
+   * a grazing plane's own depth moves about a centimetre times the tangent of its angle to the
+   * light across a texel, which stays under a metre down to a hundredth of n·l on a map with
+   * centimetre texels. What it does see is a roof.
+   *
+   * **This band used to return fully lit**, on the argument that the Lambert term was already
+   * near zero there. Under a high sun that is every vertical wall: at 70° of elevation a wall's
+   * n·l is at most 0.34, and one turned from the sun's bearing sits inside the band. A gallery's
+   * back wall under its vault took the sun through the vault, and so did the faces of its
+   * columns, which read as lit stone in shade; with a normal map carrying that n·l per texel it
+   * was a field of white specks. What would make this wrong is a map whose texels are tens of
+   * centimetres, where a grazing plane's own depth moves more than the tolerance and the band
+   * draws the acne it exists to avoid.
+   */
+  float coarseCompare = p.z - 1.0 / uShadowDepthSpan;
+  float coarse =
+    directionalVisibility(p.z, coarseCompare, textureLod(uStaticShadowMap, p.xy, 0.0).r) *
+    directionalVisibility(p.z, coarseCompare, textureLod(uDynamicShadowMap, p.xy, 0.0).r);
+  if (uPeeledShadowEnabled != 0) {
+    coarse *= directionalVisibility(p.z, coarseCompare, textureLod(uPeeledShadowMap, p.xy, 0.0).r);
+  }
+  float strength = uShadowStrength * edgeFade * lowElevationFade;
+  if (receiverFade <= 0.0) return mix(1.0, coarse, strength);
+
   float texel = 1.35 / uShadowMapSize;
   /*
    * How far the plane compensation below may carry a tap's depth, in the map's own units.
@@ -182,7 +213,7 @@ float shadowFactor(float directionalNdl) {
   // conventional one-depth map would discard; movers remain independent too.
   float lit = staticLit * peeledLit * dynamicLit;
 
-  return mix(1.0, lit, uShadowStrength * edgeFade * lowElevationFade * receiverFade);
+  return mix(1.0, mix(coarse, lit, receiverFade), strength);
 }
 #endif
 

package/src/render/shaders/flat/driftLight.ts

@@ -0,0 +1,75 @@
+/**
+ * DriftLight in the lit shader: how much of a pixel the summed light stands in for, and the summed
+ * light itself, read from the field's sparse volume.
+ *
+ * **The split is per pixel.** Inside the frame's completeness radius (`uDriftLight.y`, measured from
+ * the eye) every light that reaches the pixel was chosen, so it is shaded exactly; past it the
+ * volume stands in, and across the band before the radius the two crossfade. The choice was made
+ * about some centre, which need not be the eye; `uniforms.ts` takes the distance between the two
+ * off the radius, so a pixel inside it is inside the choice's radius too. A field light's
+ * exact contribution is scaled by the share left over (`main.ts`, where its weight's sign is read),
+ * so a light is counted once however the pixel is split.
+ *
+ * **One index fetch and two filtered ones.** The index finds the brick; the brick's four samples a
+ * side share their faces with the next brick's, so the hardware's trilinear lookup inside one is
+ * seamless across the join. The light texel carries in its fourth channel whether each sample is a
+ * sample at all, and dividing by the filtered value drops the samples buried in walls rather than
+ * blending their darkness into the surface. The lookup is nudged half a spacing along the normal,
+ * which keeps a surface reading the air in front of it rather than the wall it is part of.
+ *
+ * **Two vectors of uniforms, and the sizes read off the textures.** The lit stage sits two vectors
+ * under the 256 a reported part offers at eight lights, and the first cut of this, at five, took that
+ * part down a rung to four. So the grid's extent and the atlas's are what `textureSize` answers, and
+ * the radius is measured from `uCameraPos`, which the stage already has, rather than from a centre
+ * of its own. What it gives up is two integer queries a pixel past the radius.
+ *
+ * `textureLod` throughout, by the 2026-08-07 rule: this is reached through branches no compiler can
+ * prove uniform. Both samplers are declared `highp` because GLSL ES gives 3D samplers no default.
+ */
+export const DRIFT_LIGHT_GLSL = /* glsl */ `
+/** x how much of the summed light is in the frame (0 off), y the radius, z the band, w the scale. */
+uniform vec4 uDriftLight;
+/** xyz the first brick's first sample; w metres between samples, a third of a brick. */
+uniform vec4 uDriftLightOrigin;
+uniform highp usampler3D uDriftLightIndex;  // wgsl:share shadow
+uniform highp sampler3D uDriftLightAtlas;
+
+/** The share of this pixel's field light the volume stands in for: 0 inside the radius, 1 past it. */
+float driftLightShare(vec3 world) {
+  if (uDriftLight.x <= 0.0) return 0.0;
+  float away = distance(world, uCameraPos);
+  return smoothstep(uDriftLight.y - uDriftLight.z, uDriftLight.y, away) * uDriftLight.x;
+}
+
+/** The summed light arriving on a surface at \`world\` facing \`n\`. */
+vec3 driftLightIrradiance(vec3 world, vec3 n) {
+  float spacing = uDriftLightOrigin.w;
+  vec3 at = (world + n * (0.5 * spacing) - uDriftLightOrigin.xyz) / (3.0 * spacing);
+  ivec3 cell = ivec3(floor(at));
+  if (any(lessThan(cell, ivec3(0))) || any(greaterThanEqual(cell, textureSize(uDriftLightIndex, 0)))) {
+    return vec3(0.0);
+  }
+  uint id = texelFetch(uDriftLightIndex, cell, 0).r;
+  if (id == 0u) return vec3(0.0);
+  /* A brick is eight texels across (its light block, then its direction block) and four up and deep. */
+  ivec3 size = textureSize(uDriftLightAtlas, 0);
+  int brick = int(id) - 1;
+  int across = size.x / 8;
+  int down = size.y / 4;
+  vec3 corner = vec3(
+    float((brick % across) * 8),
+    float(((brick / across) % down) * 4),
+    float((brick / (across * down)) * 4)
+  );
+  vec3 texel = 1.0 / vec3(size);
+  vec3 inside = (at - vec3(cell)) * 3.0 + 0.5;
+  vec4 light = textureLod(uDriftLightAtlas, (corner + inside) * texel, 0.0);
+  if (light.a < 1e-3) return vec3(0.0);
+  vec4 toward = textureLod(uDriftLightAtlas, (corner + vec3(4.0, 0.0, 0.0) + inside) * texel, 0.0);
+  vec3 arriving = light.rgb / light.a;
+  vec3 from = toward.xyz / light.a;
+  /* Lambert for a single light, a quarter for light arriving from everywhere: see \`bake.ts\`. */
+  float facing = max(dot(n, from), 0.0) + (1.0 - min(length(from), 1.0)) * 0.25;
+  return arriving * facing;
+}
+`;

package/src/render/shaders/flat/index.ts

@@ -2,6 +2,7 @@ import { resolveConditionals } from '../conditionals.ts';
 import { OCTAHEDRAL_GLSL } from '../octahedral.ts';
 import { PROBEGRID_GLSL } from './probeGrid.ts';
 import { TANGENT_FRAME_GLSL } from '../tangentFrame.ts';
+import { CUTOUT_COVERAGE_GLSL } from '../cutoutCoverage.ts';
 import { preambleGlsl } from './preamble.ts';
 import { LOBES_GLSL } from './lobes.ts';
 import { POINTSHADOW_GLSL } from './pointShadow.ts';
@@ -10,6 +11,7 @@ import { MORPH_GLSL } from '../morph.ts';
 import { SKINNING_GLSL } from '../skinning.ts';
 import { SURFACE_GLSL } from './surface.ts';
 import { MAIN_GLSL } from './main.ts';
+import { DRIFT_LIGHT_GLSL } from './driftLight.ts';
 import { CHANNEL_ATTRIBUTE, CHANNEL_BEND } from '../vertexChannel.ts';
 import { FULL_LIGHT_BUDGET, type LightBudget } from '../../uniformVectorBudget.ts';
 
@@ -489,6 +491,9 @@ export function flatFrag(options: FlatShaderOptions): string {
        * and `main` is unconditional by construction.
        */
       TANGENT_FRAME_GLSL,
+      /* Unconditional for the same reason, and called only where a cutoff was asked for. */
+      CUTOUT_COVERAGE_GLSL,
+      DRIFT_LIGHT_GLSL,
       MAIN_GLSL,
     ].join('\n'),
     {

package/src/render/shaders/flat/lobes.ts

@@ -74,6 +74,19 @@ const float PENUMBRA_FADE = 1.6;
  */
 const float MAX_FILTER_RADIUS = 0.25;
 
+/**
+ * The weight below which a point light's shadow is not looked up at all.
+ *
+ * A light's shadow is blended toward none as the light falls off, \`mix(1, occl, weight)\` with the
+ * weight twice the falloff, so a shadow looked up under this floor changes at most three per cent
+ * of a light that has already all but faded: with the inverse-square falloff, past about eight
+ * metres from it. Measured on a lantern-lit courtyard, the lookups the floor skips were most of a
+ * night's frame: 14 ms of 26 at 1440p, a blocker tap and twelve filter taps for every light in every
+ * froxel. What it gives up is the last three per cent of a distant light's shadow, which the blend
+ * was already taking away; what would make it wrong is a falloff that stays strong far out.
+ */
+const float POINT_SHADOW_MIN_WEIGHT = 0.03;
+
 /**
  * How much of a self-lit surface's glow a lamp's shadow may take.
  *

package/src/render/shaders/flat/main.ts

@@ -37,8 +37,13 @@ export const MAIN_GLSL = `void main() {
   if (uAlbedoEnabled != 0) {
     vec4 texel = texture(uAlbedo, vUv);
     // Discarded before anything else is computed: a thrown-away fragment should not pay
-    // for the lighting it will never contribute to.
-    if (texel.a < uAlbedoCutout) discard;
+    // for the lighting it will never contribute to. The test credits alpha for the mip level
+    // it samples, so a needle averaged thin down the chain is not lost; see cutoutCoverage.ts.
+    // Behind a branch on a uniform, so a material with no cutoff pays nothing for it.
+    if (uAlbedoCutout > 0.0) {
+      float tested = cutoutAlpha(texel.a, vUv * vec2(textureSize(uAlbedo, 0)));
+      if (tested < uAlbedoCutout) discard;
+    }
     albedo *= texel.rgb;
     coverage = texel.a;
   }
@@ -81,6 +86,15 @@ export const MAIN_GLSL = `void main() {
 
   if (uLightingEnabled != 0) {
     vec3 n = normalize(vNormal);
+    /*
+     * **Which face of a two-sided surface this is, from the normal and not from the rasteriser.**
+     * The rasteriser's own facing flag would say it exactly, and it is one more input to the stage: the flat
+     * shader already carries sixteen, WebGPU's ceiling, and the seventeenth made every pipeline
+     * invalid and every mesh draw nothing. A face whose own normal points away from the eye is the
+     * back of the sheet; what that gives up is a sliver at a curved silhouette, where a front face's
+     * interpolated normal already leans away and is lit as the back.
+     */
+    bool backFace = uDoubleSided != 0 && dot(n, uCameraPos - vWorldPos) < 0.0;
     /*
      * The authored normal, before either relief perturbs it.
      *
@@ -260,6 +274,15 @@ export const MAIN_GLSL = `void main() {
       );
     }
 
+    /*
+     * **The back face of a two-sided surface is lit as its front**, which is glTF's rule for
+     * \`doubleSided\`: the whole shading normal turned toward the viewer, after the map and the
+     * relief have perturbed it, as three.js turns its normal, tangent and bitangent together.
+     * Turning only the interpolated normal would leave a normal map's tilt pointing the wrong way
+     * across the fold of every curtain.
+     */
+    if (backFace) n = -n;
+
     /*
      * One dot product, used twice: ndl is the lit side and its negative is the night side below.
      * Shared rather than issued twice because it is the same number and one is cheaper, and not
@@ -273,8 +296,23 @@ export const MAIN_GLSL = `void main() {
      * term below needs it too. The sun and the moon are the only sources whose shadow
      * used to stop at a glowing surface.
      */
+    /*
+     * **The surface's own n·l, before any map tilted it: the side of the surface the sun is on.**
+     *
+     * A normal map says which way each texel faces within its surface; it cannot put a texel on the
+     * other side of that surface from the sun. Read from the mapped normal alone, the texels of a
+     * column's face turned from a high sun that leaned into the light were lit as though the column
+     * were not in the way: a field of white specks over stone in shade. So the shadow's band is
+     * chosen by this, and the sun is taken away as it reaches zero, over the last two hundredths of
+     * n·l, where an unmapped surface's own Lambert term is already under 0.02. Over a tenth it moved
+     * every smooth column's terminator in the published scenes. What it gives up is the bump-lit
+     * relief of a surface barely facing the sun, where the light was already grazing.
+     */
+    vec3 surfaceN = normalize(vNormal);
+    if (backFace) surfaceN = -surfaceN;
+    float surfaceNdl = dot(surfaceN, uDirectionalDir);
 #if DIRECTIONAL_SHADOWS
-    float sunShade = shadowFactor(ndl);
+    float sunShade = shadowFactor(max(surfaceNdl, 0.0));
 #else
     float sunShade = 1.0;
 #endif
@@ -298,7 +336,13 @@ export const MAIN_GLSL = `void main() {
      * that shipped before it.
      */
     sunShade *= vSkyDirect;
-    float direct = ndl * sunShade;
+    /*
+     * And the sun gone from a surface turned from it, whatever its map says. See \`surfaceNdl\`.
+     * Its own factor rather than folded into sunShade, which the emissive share reads as the sun's
+     * shadow: a lamp's pane turned from the moon is not in shadow, it is only unlit.
+     */
+    float sunFacing = smoothstep(0.0, 0.02, surfaceNdl);
+    float direct = ndl * sunShade * sunFacing;
 
     /*
      * Hemispheric: sky above, ground below, mixed by which way the surface looks. An
@@ -328,6 +372,7 @@ export const MAIN_GLSL = `void main() {
      * set, which is the guarantee that option was added to give.
      */
     vec3 irradiance = gridIrradiance(n, vWorldPos);
+    irradiance = mix(irradiance, ambient, probeGridOutside(surfaceN, vWorldPos));
     ambient = mix(ambient, irradiance, uProbeGridAmbient * uEnvironmentEnabled);
 #endif
     /*
@@ -406,7 +451,7 @@ export const MAIN_GLSL = `void main() {
      * before: \`sunSpec\` is \`vec3(vSpecular)\` at metal 0 and \`vSpecular\` defaults to 0.
      */
     vec3 sunHighlight =
-      uDirectionalColor * specularLobe(max(dot(n, halfway), 0.0), surfaceRoughness) * sunSpec * sunShade;
+      uDirectionalColor * specularLobe(max(dot(n, halfway), 0.0), surfaceRoughness) * sunSpec * sunShade * sunFacing;
     /*
      * The dielectric's share goes in here, where it has always gone, so the environment blend
      * below dims it by exactly the reflectance it always dimmed it by. The metal's share is added
@@ -813,6 +858,7 @@ export const MAIN_GLSL = `void main() {
      */
     vec3 lampOpen = vec3(0.0);
     vec3 lampShadowed = vec3(0.0);
+    float driftShare = driftLightShare(vWorldPos);
 
     /*
      * Which froxel this fragment is in.
@@ -912,7 +958,7 @@ export const MAIN_GLSL = `void main() {
       cookie = uintBitsToFloat(rec4.w);
       } else {
       i = slot;
-      if (i >= uLightCount) break;
+      if (i >= uLightCount || i >= MAX_LIGHTS) break;
       lightPos = uLightPos[i];
       lightRadius = uLightRadius[i];
       lightColor = uLightColor[i];
@@ -925,6 +971,9 @@ export const MAIN_GLSL = `void main() {
       iesAxis = uLightIesAxis[i];
       cookie = uLightCookie[i];
       }
+      /* A DriftLight field's own light carries a negative weight, and is shaded exactly only for the
+         share of this pixel the field does not stand in for. See \`driftLight.ts\`. */
+      if (lightWeight < 0.0) lightWeight = -lightWeight * (1.0 - driftShare);
       /*
        * **The cone, and a point light's is one that admits every direction.**
        *
@@ -987,6 +1036,8 @@ export const MAIN_GLSL = `void main() {
        * grazing the angle is. Without it the cubemap's face seams show as a
        * diagonal cross and the whole plane bands.
        */
+      /* How present this light's shadow is. See \`POINT_SHADOW_MIN_WEIGHT\`. */
+      float shadowWeight = clamp(falloff * 2.0, 0.0, 1.0);
 #if POINT_SHADOWS
       float grazing = 1.0 - ndl;
       float normalOffset = (0.06 + dist * 0.05) * grazing * grazing + 0.02;
@@ -1025,7 +1076,7 @@ export const MAIN_GLSL = `void main() {
        */
       int shadowRead = clamp(shadowSlot, 0, MAX_LIGHTS - 1);
       int layer = shadowSlot >= 0 && shadowSlot < MAX_LIGHTS ? uPointShadowLayer[shadowRead] : -1;
-      if (layer >= 0) {
+      if (layer >= 0 && shadowWeight > POINT_SHADOW_MIN_WEIGHT) {
         occl = mix(
           1.0,
           pointShadow(
@@ -1054,7 +1105,7 @@ export const MAIN_GLSL = `void main() {
       float liveWeight = 0.0;
       int liveLayer =
         shadowSlot >= 0 && shadowSlot < MAX_LIGHTS ? uLivePointShadowLayer[shadowRead] : -1;
-      if (liveLayer >= 0) {
+      if (liveLayer >= 0 && shadowWeight > POINT_SHADOW_MIN_WEIGHT) {
         liveOccl = pointShadow(
           uPointShadows,
           float(liveLayer),
@@ -1074,7 +1125,7 @@ export const MAIN_GLSL = `void main() {
       // Blend occlusion out as the light fades, so a shadow can never be more
       // present than the light casting it — and slot changes at the edge of
       // range become invisible rather than a pop.
-      float shaded = mix(1.0, occl, clamp(falloff * 2.0, 0.0, 1.0));
+      float shaded = mix(1.0, occl, shadowWeight);
       /*
        * The cone multiplies the distance falloff rather than replacing it, which is what makes a
        * spot a point light with a direction rather than a second kind of light. It is exactly 1
@@ -1494,6 +1545,14 @@ export const MAIN_GLSL = `void main() {
     );
 #endif
     lit += lampOpenFloor * lampShade;
+    /*
+     * DriftLight: every fixed light past the frame's choice, summed and occluded, for the share of
+     * this pixel the exact lights above no longer cover. Diffuse only, and so no metal term: see
+     * \`driftLight.ts\`.
+     */
+    if (driftShare > 0.0) {
+      lit += albedo * driftLightIrradiance(vWorldPos, n) * (driftShare * uDriftLight.w) * (1.0 - metal);
+    }
 
     /*
      * Self-illuminated geometry, dimmed where a lamp's shadow crosses it.

package/src/render/shaders/flat/preamble.ts

@@ -38,6 +38,12 @@ import { FOG_GLSL } from '../fog.ts';
 export function preambleGlsl({ maxLights, maxAreaLights }: LightBudget): string {
   return `#version 300 es
 precision highp float;
+/*
+ * highp int as well: a clustered light is decoded with uintBitsToFloat from texels that arrive as
+ * uvec4, and its texel index passes 32767 in a big world. The fragment default for int and uint is
+ * mediump, which a sixteen-bit driver truncates, and every clustered light then lights nothing.
+ */
+precision highp int;
 
 in vec3 vNormal;
 in vec3 vColor;
@@ -140,6 +146,12 @@ uniform int uAlbedoEnabled;
  */
 uniform float uAlbedoCutout;
 
+/**
+ * 1 for a surface seen from both faces: glTF's doubleSided, a curtain or a leaf card. Its draw culls
+ * nothing, and a back face is lit as a front, with the shading normal turned toward the viewer.
+ */
+uniform int uDoubleSided;
+
 /**
  * A normal map, in the surface's own space.
  *
@@ -550,6 +562,12 @@ uniform vec3 uProbeGridCounts;
  * exactly as it did before any probe existed.
  */
 uniform float uProbeGridAmbient;
+/**
+ * Which sets of layers the shading reads, and how far between them: the last whole sweep's layer
+ * offset, the newest whole sweep's, and the blend from the first toward the second. \`(0, 0, 0)\`
+ * for a grid that does not crossfade. See \`probeSweeps.ts\`.
+ */
+uniform vec3 uProbeGridSets;
 #endif
 /** A world-space box that lights up regardless of time of day (run finished). */
 uniform vec3 uHighlightMin;
@@ -637,12 +655,12 @@ uvec4 clusterTexel(int texel) {
  * both numbers sit beside the budgets they come from.
  */
 /*
- * **Both arms have the same bound, and that equality is deliberate.** There is one loop, so a
- * larger clustered cap would raise the bound for the fixed path too, and a scene that never asks
- * for froxels would carry a loop of 28 where it carries 16 today. \`MAX_LIGHTS_PER_CLUSTER\` is
- * pinned equal to \`MAX_LIGHTS\` for that reason; a test in \`textureUnitBudget.test.ts\` asserts it.
+ * **The bound is the froxel's cap, and the fixed arm leaves long before it.** The two were equal
+ * until a candlelit interior needed more than sixteen lights in a froxel; see
+ * \`MAX_LIGHTS_PER_CLUSTER\`. The fixed arm breaks at \`uLightCount\` and at \`MAX_LIGHTS\`, so it
+ * iterates exactly what it did and never indexes its uniform arrays past their end.
  */
-#define LIGHT_LOOP_MAX MAX_LIGHTS
+#define LIGHT_LOOP_MAX MAX_LIGHTS_PER_CLUSTER
 uniform int uLightCount;
 /** 0 keeps the radius-shaped falloff; 1 is physical inverse-square with a soft cutoff. */
 uniform int uLightFalloff;