@driftengine/core 4.1.3 → 4.1.5

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

@@ -15,7 +15,40 @@
 import { MAX_SHADOW_FILTER_TAPS } from '../../renderQuality.ts';
 import { OUTPUT_TRANSFORM_GLSL } from '../outputTransform.ts';
 
-export const POINTSHADOW_GLSL = `float pointShadow(
+export const POINTSHADOW_GLSL = `/**
+ * How much of one tap's occlusion survives its own penumbra.
+ *
+ * **How much of a shadow survives, as well as how soft it is.** A penumbra does not merely blur
+ * with distance from its caster, it *takes over*: far enough from the occluder, relative to how
+ * big the source is, every point on the receiver can see part of the flame and there is no umbra
+ * left at all. The shadow is gone, not blurry. Without it, two columns lit by a brazier threw
+ * full-strength edges fifteen metres across the terrace, and the gap between them read as a
+ * spotlight cone with straight sides rather than as a fire.
+ *
+ * **Per tap, and it was once for the whole filter, taken from the centre tap alone.** That is a
+ * blocker search of one sample standing in for twelve, and it is right wherever the taps agree —
+ * inside an umbra they all find the same occluder, so this returns exactly what the shared value
+ * did, and the umbra is unchanged to the bit. It is wrong exactly where they disagree, which is
+ * the silhouette: there the centre ray *misses*, so the search reports no occluder, the spread is
+ * zero and the fade is switched off — while the taps that do land on the caster then draw at full
+ * strength. What that paints is a hard one-texel line around a shadow whose interior has
+ * correctly faded to nothing.
+ *
+ * Reported as shadows "faded out but NOT shadow outlines, generating long lines around the
+ * world", and on a brazier as a bare square outline lying on the ground with no shadow inside it.
+ *
+ * **What it costs** is two multiplies and a divide per occluded tap, against a tap that has
+ * already paid for a texture fetch. **What would make it wrong** is a filter wide enough that one
+ * tap's occluder is not the occluder a neighbouring tap is estimating for, which is the same
+ * limit the shared value had and is what \`MAX_FILTER_RADIUS\` bounds.
+ */
+float tapStrength(float receiverDistance, float occluderDistance, float sourceRadius) {
+  float spread = max(receiverDistance - occluderDistance, 0.0) / max(occluderDistance, 0.05);
+  float penumbra = clamp(sourceRadius * spread * PENUMBRA_FADE, 0.0, 1.0);
+  return 1.0 - penumbra * penumbra;
+}
+
+float pointShadow(
   highp sampler2DArray maps,
   float layer,
   vec3 toFrag,
@@ -98,26 +131,8 @@ export const POINTSHADOW_GLSL = `float pointShadow(
   float radius = clamp(sourceRadius * spread, 0.01, MAX_FILTER_RADIUS) + 0.012;
 
   /*
-   * How much of a shadow survives, as well as how soft it is.
-   *
-   * This is the half that was missing, and it is why widening the filter never
-   * fixed anything. A penumbra does not merely blur with distance from its
-   * caster — it *takes over*. Far enough from the occluder, relative to how big
-   * the source is, every point on the receiver can see part of the flame and
-   * there is no umbra left at all: the shadow is gone, not blurry.
-   *
-   * Without it, two columns lit by a brazier threw full-strength edges fifteen
-   * metres across the terrace, and the gap between them read as a spotlight cone
-   * with straight sides rather than as a fire. Three attempts in, the note that
-   * unlocked it was that the pool should still fade naturally at its rim — a
-   * description of the falloff, not of the blur.
-   */
-  float penumbra = clamp(sourceRadius * spread * PENUMBRA_FADE, 0.0, 1.0);
-  float strength = 1.0 - penumbra * penumbra;
-
-  /*
-   * Taps are placed on a disk *perpendicular to the light ray*, rotated per
-   * fragment.
+   * Taps are placed on a disk *perpendicular to the light ray*, turned by half a golden
+   * angle on every other column of pixels.
    *
    * Offsetting the ray by fixed 3D vectors was the earlier approach and it has
    * two faults that only show on a wide filter. The offsets are not
@@ -127,8 +142,33 @@ export const POINTSHADOW_GLSL = `float pointShadow(
    * tap pattern — reported, on a brazier behind a rank of columns, as strange
    * straight lines across the light pool.
    *
-   * A per-fragment rotation turns that banding into a fine dither, which the eye
-   * reads as smooth — the standard cure, and it costs one hash.
+   * **The cure for that was a per-fragment hash, and it is what made the penumbra
+   * stipple.** Twelve taps are a coarse estimate of how much of the emitter this point can
+   * see; turning them by an unrelated angle at every pixel makes each pixel's error
+   * independent of its neighbour's, which is the definition of noise. Something has to
+   * average that back out, and this engine's lit pass is the last thing to touch the frame —
+   * there is no blur and no temporal resolve behind it, so the noise reached the screen. Two
+   * games reported the same coarse cross-hatch across a light pool.
+   *
+   * **So the turn comes from a two-pixel tile instead, and the pair is averaged afterwards.**
+   * A pixel's own x parity picks one of two tap sets half a golden angle apart, and
+   * \`main\` folds the pair together once the light loop is over — see the resolve there. The
+   * pair's twenty-four taps are the filter; each pixel pays for twelve of them.
+   *
+   * **A *column* pair rather than a 2x2 square, and that was measured rather than assumed.**
+   * Four turns on a square tile, resolved with both derivatives, came back at 3.88 against this
+   * pair's 2.46 on the same build — because the second derivative hands the lower row of a quad
+   * the upper row's difference on hardware that answers a coarse derivative, and with four turns
+   * that is the wrong difference. Two turns keyed on the column alone make it the right one,
+   * which is why the tile's shape and the resolve are one decision rather than two.
+   *
+   * **Neither half works alone**, which is the same pairing \`ambientOcclusion.ts\` describes
+   * between its rotation tile and its blur. Measured on \`demo/dev/pointshadow.html\` at
+   * \`?exposure=6\`, as mean absolute luminance difference to the right and down neighbour over
+   * the mover's penumbra, on WebGL2: **4.60** for the per-fragment hash this replaces, **2.88**
+   * for this tile with no resolve — and a one-pixel vertical comb in the picture, which is the
+   * tile itself on screen — against **2.37** for the pair resolved. A frame with the shadow
+   * switched off measures 0.81, and WebGPU answers 4.56 and 2.33 for the same two builds.
    *
    * **Unchanged by the move to an octahedral map, and that is the point.** The offsets are
    * angular perturbations of a direction, so every tap is still a direction and octEncode is
@@ -139,17 +179,19 @@ export const POINTSHADOW_GLSL = `float pointShadow(
   vec3 up = abs(fwd.y) < 0.9 ? vec3(0.0, 1.0, 0.0) : vec3(1.0, 0.0, 0.0);
   vec3 tu = normalize(cross(up, fwd));
   vec3 tv = cross(fwd, tu);
-  // Interleaved gradient noise: cheap, and stable enough per pixel that the
-  // dither does not crawl while the camera moves.
-  float angle = fract(52.9829189 * fract(dot(gl_FragCoord.xy, vec2(0.06711056, 0.00583715))))
-    * 6.28318530718;
+  /*
+   * Integer arithmetic, because this is a lattice: a shader compiler is free to implement
+   * \`mod(x, 2.0)\` as a multiply by a reciprocal, and a GPU here answers 3 for \`3.0 % 3.0\`.
+   * \`gl_FragCoord.x\` is the pixel's centre, so truncating it is the pixel's own column.
+   */
+  float angle = float(int(gl_FragCoord.x) & 1) * PCF_PAIR_TURN;
   float ca = cos(angle);
   float sa = sin(angle);
 
   float lit = 0.0;
   for (int i = 0; i < ${MAX_SHADOW_FILTER_TAPS}; i++) {
     if (i >= uShadowFilterTaps) break;
-    vec2 disk = PCF_OFFSETS[i].xy;
+    vec2 disk = PCF_OFFSETS[i];
     vec2 turned = vec2(disk.x * ca - disk.y * sa, disk.x * sa + disk.y * ca);
     // Perpendicular to the ray, and *not* scaled by its length: the offsets are
     // an angular perturbation of a direction, which is what the encoding takes.
@@ -164,14 +206,13 @@ export const POINTSHADOW_GLSL = `float pointShadow(
     if (dist - bias > storedDistance) {
       // A point shadow cannot outlive the finite light that casts it, so its
       // occlusion fades smoothly before the light's far plane.
-      lit += 1.0 - shadowReach(max(dist - storedDistance, 0.0), far);
+      float reach = shadowReach(max(dist - storedDistance, 0.0), far);
+      lit += 1.0 - reach * tapStrength(dist, storedDistance, sourceRadius);
     } else {
       lit += 1.0;
     }
   }
-  float shaded = lit / float(max(uShadowFilterTaps, 1));
-  // Fade the whole shadow toward lit as the penumbra swallows it.
-  return mix(1.0, shaded, strength);
+  return lit / float(max(uShadowFilterTaps, 1));
 }
 
 /**
@@ -262,25 +303,20 @@ float areaShadow(
   float widthX = min(halfX * spread, MAX_FILTER_RADIUS) + 0.012;
   float widthY = min(halfY * spread, MAX_FILTER_RADIUS) + 0.012;
 
-  /* The narrower half extent, for the reason in the header: it is what keeps a strip's umbra. */
-  float penumbra = clamp(min(halfX, halfY) * spread * PENUMBRA_FADE, 0.0, 1.0);
-  float strength = 1.0 - penumbra * penumbra;
-
   /*
-   * Rotated per fragment inside the unit disk *before* the ellipse maps it, so the dither that
-   * breaks up twelve aligned taps survives the anisotropy. Interleaved gradient noise, one hash;
-   * without it a wide filter bands along the tap pattern — reported on a brazier behind a rank of
-   * columns as straight lines across the light pool.
+   * Turned inside the unit disk *before* the ellipse maps it, so the half-turn that separates
+   * the two halves of a pixel pair survives the anisotropy. The same two-pixel tile the round
+   * filter uses and for the same reasons — see \`pointShadow\`, which carries the measurement;
+   * a rectangle's shadow stippled exactly as a lamp's did, because it is the same twelve taps.
    */
-  float angle = fract(52.9829189 * fract(dot(gl_FragCoord.xy, vec2(0.06711056, 0.00583715))))
-    * 6.28318530718;
+  float angle = float(int(gl_FragCoord.x) & 1) * PCF_PAIR_TURN;
   float ca = cos(angle);
   float sa = sin(angle);
 
   float lit = 0.0;
   for (int i = 0; i < ${MAX_SHADOW_FILTER_TAPS}; i++) {
     if (i >= uShadowFilterTaps) break;
-    vec2 disk = PCF_OFFSETS[i].xy;
+    vec2 disk = PCF_OFFSETS[i];
     vec2 turned = vec2(disk.x * ca - disk.y * sa, disk.x * sa + disk.y * ca);
     vec3 sampleDir = toFrag + alongX * (turned.x * widthX) + alongY * (turned.y * widthY);
     float stored = textureLod(maps, vec3(octEncode(sampleDir), layer), 0.0).r;
@@ -292,13 +328,15 @@ float areaShadow(
     float storedDistance = stored * far;
     if (dist - bias > storedDistance) {
       /* An area light's occlusion cannot outlive the map that carries it either. */
-      lit += 1.0 - shadowReach(max(dist - storedDistance, 0.0), far);
+      float reach = shadowReach(max(dist - storedDistance, 0.0), far);
+      /* The narrower half extent, for the reason in the header: it is what keeps a strip's
+         umbra. Per tap, for the reason \`tapStrength\` gives. */
+      lit += 1.0 - reach * tapStrength(dist, storedDistance, min(halfX, halfY));
     } else {
       lit += 1.0;
     }
   }
-  float shaded = lit / float(max(uShadowFilterTaps, 1));
-  return mix(1.0, shaded, strength);
+  return lit / float(max(uShadowFilterTaps, 1));
 }
 #endif
 

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

@@ -803,7 +803,30 @@ uniform float uAreaLightTwoSided[MAX_AREA_LIGHTS];
 #if POINT_SHADOWS
 /** Which array layer holds this light's shadow, or -1 for none. */
 uniform int uPointShadowLayer[MAX_LIGHTS];
-uniform float uPointShadowFar[MAX_LIGHTS];
+/*
+ * **The projection each map was rendered under: \`xyz\` where from, \`w\` how far.**
+ *
+ * The origin is the half that is new and it is **not** the light's position. A light may drift
+ * \`pointShadowRebakeDistance\` from its image before the image is re-rendered, because
+ * re-baking six faces of the static world on every frame of a flicker is what made a brazier
+ * the most expensive object in a scene. The ray below is built from this point rather than from
+ * \`uLightPos\`, so it is the ray the picture was drawn along and the drift costs nothing.
+ *
+ * **It rides with the far plane because a row is a row.** A default-block \`float[N]\` spends a
+ * whole uniform vector per element and uses one of its four components, so the far plane was
+ * already paying for three floats it threw away — see \`uniformVectorBudget.ts\`. Declared as a
+ * separate \`vec3\` array this would have cost sixteen more rows on each of the two sets, and
+ * the ladder answers a 256-vector phone by halving \`MAX_LIGHTS\`: the measured price of a
+ * separate array was **eight lights becoming four**. Folded in, the whole fix is free.
+ *
+ * **What it gives up** is that the shadow stops tracking the flame *within* the tolerance — a
+ * flicker no longer nudges the shadow it casts, because the image it is read from did not move
+ * either. That is the trade the tolerance was always making, now made honestly instead of by
+ * reading a picture from the wrong place. **What would make it wrong** is a tolerance large
+ * enough that a shadow visibly lags its light, which is a reason to lower
+ * \`pointShadowRebakeDistance\` rather than to sample from a point the image cannot answer for.
+ */
+uniform vec4 uPointShadowProjection[MAX_LIGHTS];
 uniform float uPointShadowNear[MAX_LIGHTS];
 /** Emitter radius per light — drives how soft its shadows are. */
 uniform float uPointShadowSize[MAX_LIGHTS];
@@ -834,7 +857,8 @@ uniform highp sampler2DArray uPointShadows;  // wgsl:share shadow
  * light owns at most one of the two at a time.
  */
 uniform int uLivePointShadowLayer[MAX_LIGHTS];
-uniform float uLivePointShadowFar[MAX_LIGHTS];
+/** The live pair's own projection, by the same rule. See \`uPointShadowProjection\`. */
+uniform vec4 uLivePointShadowProjection[MAX_LIGHTS];
 uniform float uLivePointShadowNear[MAX_LIGHTS];
 uniform float uLivePointShadowSize[MAX_LIGHTS];
 uniform float uLivePointShadowWeight[MAX_LIGHTS];
@@ -883,16 +907,53 @@ uniform float uLiveAreaShadowWeight[MAX_AREA_LIGHTS];
  * where a bias means what it looks like it means.
  */
 /**
- * Sample offsets forming a rough sphere, for filtering a cubemap shadow.
- * Perturbing the *direction* is how PCF works on a cube — there is no 2D UV
- * neighbourhood to step across the way there is for the sun's cascade.
+ * Twelve places on a disk across the light ray, for filtering an omnidirectional shadow.
+ *
+ * **These were eight, and the count is why a penumbra was stippled.** The list used to be the
+ * eight corners and six faces of a cube, carried as \`vec3\` from the era when a tap offset a
+ * direction by a 3D vector. Nothing has read the third component since the map became
+ * octahedral — both filters take \`.xy\` — and flattening a cube's corners onto a plane makes
+ * pairs of them coincide: \`(1, 1, 1)\` and \`(1, 1, -1)\` are one 2D offset, four times over. So
+ * twelve taps asked eight questions and answered four of them twice, and every one of the eight
+ * sat on the rim at radius 1 or 1.414 with nothing in between. A coverage estimate from a ring
+ * moves in steps of two twelfths as the penumbra's edge sweeps a doubled pair across it, which
+ * is the size of the speckle that was reported.
+ *
+ * **The replacement is the golden-angle disk this repository already uses for ambient
+ * occlusion** — angle \`i\` turns of 137.5 degrees, radius \`sqrt((k + 0.5) / 12)\` — so the taps
+ * are spread evenly over the area rather than crowded on the rim or at the centre, and no two
+ * coincide. The nearest pair is 0.355 apart where the old set had a pair at zero.
+ *
+ * **The radii are dealt round rather than taken in order, and that is what makes a short filter
+ * work.** \`shadowFilterTaps\` is 4, 8 or 12 and the loop below simply stops early, so every
+ * prefix of this list is a filter somebody ships: in spiral order the first four taps would be
+ * the four innermost and a low profile would quietly get a filter a third of the width it asked
+ * for. Interleaved, the first four already span 0.21 to 0.91 of the disk's reach and sit around
+ * its centre rather than to one side, which is a small filter rather than a narrow one.
+ *
+ * **What it gives up** is a little softness. The old set put two thirds of its taps at the
+ * outermost radius, so it read the penumbra's widest part twice as often as an even disk does
+ * and drew a shadow edge softer than the emitter's size calls for; an even disk is the honest
+ * estimate and is very slightly crisper. **What would make it wrong** is a caller wanting the
+ * filter's *reach* changed — that is \`MAX_FILTER_RADIUS\`, and the outermost tap here is 1.384
+ * against the old 1.414 precisely so this change does not move it.
  */
 #if POINT_SHADOWS
-const vec3 PCF_OFFSETS[${MAX_SHADOW_FILTER_TAPS}] = vec3[${MAX_SHADOW_FILTER_TAPS}](
-  vec3( 1.0,  1.0,  1.0), vec3( 1.0, -1.0, -1.0), vec3(-1.0,  1.0, -1.0), vec3(-1.0, -1.0,  1.0),
-  vec3( 1.0, -1.0,  1.0), vec3(-1.0,  1.0,  1.0), vec3( 1.0,  1.0, -1.0), vec3(-1.0, -1.0, -1.0),
-  vec3( 1.0,  0.0,  0.0), vec3(-1.0,  0.0,  0.0), vec3( 0.0,  1.0,  0.0), vec3( 0.0, -1.0,  0.0)
+const vec2 PCF_OFFSETS[${MAX_SHADOW_FILTER_TAPS}] = vec2[${MAX_SHADOW_FILTER_TAPS}](
+  vec2( 0.289,  0.000), vec2(-0.767,  0.703), vec2( 0.067, -0.761), vec2( 0.766,  0.999),
+  vec2(-0.492, -0.087), vec2( 0.943, -0.600), vec2(-0.225,  0.836), vec2(-0.610, -1.174),
+  vec2( 0.606,  0.221), vec2(-1.100,  0.454), vec2( 0.406, -0.867), vec2( 0.414,  1.321)
 );
+/**
+ * The angle between the two tap sets a pair of neighbouring pixels uses. See \`pointShadow\`.
+ *
+ * Half the golden angle, because the offsets above are a golden-angle spiral: turning the whole
+ * set by half a step drops the second pixel's taps between the first pixel's arms rather than
+ * on top of them. Measured on the pair, the closest two of the twenty-four are 0.305 apart,
+ * against 0.175 for a half turn and 0.233 for a whole golden angle — so this is the choice that
+ * makes the pair's combined filter as even as the twelve it is built from.
+ */
+const float PCF_PAIR_TURN = 1.19998161;
 #endif
 
 /** A finite point-light shadow loses strength with the light that casts it. */`;