@driftengine/core 4.1.4 → 4.2.0

package/src/render/renderQuality.ts

@@ -162,10 +162,33 @@ export interface RenderQuality {
    * sampled lights flickering at once accounted for 174 of the frame's 296 draw
    * calls, and for the game being unplayable exactly where lamps cluster.
    *
-   * The default clears a flame's own wander with room to spare, because drift is
-   * measured from the baked origin and a wander can be caught at either extreme
-   * of its travel. A light that really moves still re-bakes; it just does so once
-   * per this much movement instead of once per frame.
+   * **It was 0.4 until 4.1.5, chosen to clear a flame's whole wander with room to spare** — so
+   * a flame never re-baked at all, and its shadow of the static world stood still while the live
+   * map under the same light, which is re-rendered every frame because it holds the movers, swung
+   * with the flame. One light, two shadows, visibly disagreeing about where it was. Reported as
+   * the runner's shadow following the fire and the brazier's not.
+   *
+   * **A millimetre instead, which is as near to "whenever it moved" as makes sense**, so a shadow
+   * travels with its light rather than freezing between re-bakes. A centimetre was tried first and
+   * left a visible vibration: a light wandering on a curve moves less than that in a frame near
+   * the turning points of its travel, so the shadow ran smoothly through the fast part and stepped
+   * through the slow part. What the tolerance is still for is not re-baking on arithmetic noise.
+   *
+   * A light that does not move never goes stale at any positive value, so the whole cost falls on
+   * the lights that need it, and it is bounded rather than proportional: one such light takes a
+   * whole cube in a frame and the rest dribble under the ordinary face budget.
+   *
+   * **What makes that affordable is not this number.** The 174-of-296 draw calls this paragraph
+   * used to cite was measured before `pointShadowFacesPerFrame` capped the whole static bake, and
+   * before `planPointShadowBakes` learned to put a chronically stale map behind every cold and
+   * settling one. A flame now spends leftover budget and can never hold another light's first
+   * image hostage. One such light also finishes its cube inside a single frame rather than
+   * dribbling it over three, which is what makes the motion smooth instead of stepped; see
+   * `pointShadowBudget.ts`.
+   *
+   * **What would make it wrong** is a caster set heavy enough that six passes over it does not
+   * fit the frame, where a stepped shadow is the better trade and this should go back up.
+   * `gpuTiming` is how to tell which, and it is a number rather than an opinion.
    */
   readonly pointShadowRebakeDistance: number;
   /**
@@ -815,7 +838,7 @@ export const DEFAULT_RENDER_QUALITY: Readonly<RenderQuality> = Object.freeze({
   directionalShadowDepthLayers: 2,
   directionalShadowMaxDistance: 6,
   directionalShadowMaxSlope: 3,
-  pointShadowRebakeDistance: 0.4,
+  pointShadowRebakeDistance: 0.001,
   pointShadowFacesPerFrame: 2,
   /*
    * Twelve, which is `LIVE_POINT_SHADOW_MAPS` cubemaps of six faces: exactly what the live

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

@@ -990,7 +990,7 @@ export const MAIN_GLSL = `void main() {
 #if POINT_SHADOWS
       float grazing = 1.0 - ndl;
       float normalOffset = (0.06 + dist * 0.05) * grazing * grazing + 0.02;
-      vec3 shadowFrom = (vWorldPos + n * normalOffset) - lightPos;
+      vec3 receiverPoint = vWorldPos + n * normalOffset;
 
       /*
        * uPointShadowWeight is how present the cubemap is, and it is the difference
@@ -1031,8 +1031,15 @@ export const MAIN_GLSL = `void main() {
           pointShadow(
             uPointShadows,
             float(layer),
-            shadowFrom,
-            uPointShadowFar[shadowRead],
+            /*
+             * **From where the map was baked, not from where the light is.** The two are apart
+             * by up to \`pointShadowRebakeDistance\` for anything that wanders, and both things
+             * this asks the picture move with that gap: the distance it compares against the
+             * stored one, and which texel the single-tap blocker search lands in. See
+             * \`uPointShadowOrigin\`.
+             */
+            receiverPoint - uPointShadowProjection[shadowRead].xyz,
+            uPointShadowProjection[shadowRead].w,
             uPointShadowNear[shadowRead],
             uPointShadowSize[shadowRead]
           ),
@@ -1051,8 +1058,9 @@ export const MAIN_GLSL = `void main() {
         liveOccl = pointShadow(
           uPointShadows,
           float(liveLayer),
-          shadowFrom,
-          uLivePointShadowFar[shadowRead],
+          /* Its own bake origin, for the reason the static layer above gives. */
+          receiverPoint - uLivePointShadowProjection[shadowRead].xyz,
+          uLivePointShadowProjection[shadowRead].w,
           uLivePointShadowNear[shadowRead],
           uLivePointShadowSize[shadowRead]
         );

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,
@@ -97,24 +130,6 @@ 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*, turned by half a golden
    * angle on every other column of pixels.
@@ -191,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));
 }
 
 /**
@@ -289,10 +303,6 @@ 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;
-
   /*
    * 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
@@ -318,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];