@driftengine/core 3.61.0

package/dist/render/shaders/flat/directionalShadow.js

@@ -0,0 +1,195 @@
+/** Filtering the directional cascade, with receiver-plane depth gradient compensation. */
+import { DIRECTIONAL_SHADOW_FADE_START, MAX_SHADOW_FILTER_TAPS } from '../../renderQuality.js';
+export const DIRECTIONALSHADOW_GLSL = `vec2 receiverPlaneDepthGradient(vec3 p) {
+  vec3 dx = dFdx(p);
+  vec3 dy = dFdy(p);
+  float determinant = dx.x * dy.y - dx.y * dy.x;
+  /*
+   * **A relative floor, because the absolute one it replaces could not fire.**
+   *
+   * This determinant is the area scaling of screen space into the light's UV, so its own
+   * magnitude is a UV-per-pixel squared — on a 2048 map under an ordinary camera, around 1e-6.
+   * A fixed 1e-8 guard is therefore one percent of the quantity it is guarding and only ever
+   * catches an exactly singular quad; the ratio blows up long before it, and what comes back is
+   * not a gradient but the amplified rounding error in two derivatives that nearly cancel.
+   *
+   * Compared against the product of the two derivative lengths instead, this is the sine of the
+   * angle between them, which is dimensionless and means the same thing at any map size, any
+   * resolution and any sun. The two go parallel where the receiving plane collapses toward a
+   * line in light space — a surface edge-on to the sun, which is a large deck under a low one —
+   * and that is the configuration the bands were reported in.
+   */
+  float conditioning = length(dx.xy) * length(dy.xy);
+  if (abs(determinant) < 1e-4 * conditioning) return vec2(0.0);
+  return vec2(
+    (dx.z * dy.y - dx.y * dy.z) / determinant,
+    (dx.x * dy.z - dx.z * dy.x) / determinant
+  );
+}
+
+float directionalVisibility(float receiverDepth, float compareDepth, float storedDepth) {
+  if (compareDepth <= storedDepth) return 1.0;
+  float rayDistance = max(receiverDepth - storedDepth, 0.0) * uShadowDepthSpan;
+  float groundDistance = rayDistance * length(uDirectionalDir.xz);
+  return 1.0 - shadowReach(groundDistance, uShadowMaxDistance);
+}
+
+float shadowFactor(float directionalNdl) {
+  if (uShadowStrength <= 0.0) return 1.0;
+
+  /*
+   * The receiver's position and its plane gradient, computed **above every early return
+   * that depends on a varying** — which is what makes the derivatives inside
+   * \`receiverPlaneDepthGradient\` legal.
+   *
+   * \`dFdx\` is only defined under uniform control flow. GLSL leaves a derivative reached
+   * through a varying-dependent branch undefined and compiles it anyway; **WGSL makes it an
+   * error and refuses the whole module**:
+   *
+   *     error: 'dpdx' must only be called from uniform control flow
+   *
+   * So this used to sit after four early returns, three of them varying-dependent, and the
+   * shader could not be translated at all. It is the same requirement \`AGENTS.md\` records
+   * on 2026-08-07 for \`texture()\` in a non-uniform branch, arriving from the other side:
+   * there a compiler was free to flatten the branch and charge for every arm, here it simply
+   * declines. Hoisting satisfies both.
+   *
+   * The \`uShadowStrength\` test above stays where it is because it reads a uniform, and a
+   * branch on a uniform is uniform control flow.
+   *
+   * The cost is the gradient computed on fragments that then return early: two derivatives
+   * and six multiplies, against a pass that was already sampling the map twelve times.
+   */
+  vec3 p = vLightPos.xyz / vLightPos.w;
+  p = p * 0.5 + 0.5;
+  vec2 depthGradient = receiverPlaneDepthGradient(p);
+
+  // 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.
+  float receiverFade = smoothstep(0.08, 0.20, directionalNdl);
+  if (receiverFade <= 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
+  // a top onto a side. Receiver-plane compensation and the light-axis residual
+  // below handle acne without moving adjacent faces apart.
+  if (p.z > 1.0 || p.x < 0.0 || p.x > 1.0 || p.y < 0.0 || p.y > 1.0) return 1.0;
+
+  // Fade toward lit near the frustum border instead of cutting at it. The map
+  // only covers a radius around the viewer, and a hard edge makes distant
+  // shadows blink out the moment geometry crosses it — which reads as flashing,
+  // not as distance.
+  vec2 fromCentre = abs(p.xy - 0.5) * 2.0;
+  float edgeFade = 1.0 - smoothstep(0.72, 0.98, max(fromCentre.x, fromCentre.y));
+  // The far plane needs the same treatment, or shadows vanish by depth instead.
+  edgeFade *= 1.0 - smoothstep(0.90, 1.0, p.z);
+  if (edgeFade <= 0.0) return 1.0;
+
+  /*
+   * Fade the directional shadow once, by source elevation.
+   *
+   * Source elevation is shared by the whole map, so low-angle stripes disappear
+   * without creating a hard length cut. Per-caster distance fade is handled
+   * independently below for static and moving geometry.
+   */
+  float shadowSlope = length(uDirectionalDir.xz) / max(uDirectionalDir.y, 0.001);
+  float lowElevationFade = 1.0 - smoothstep(
+    uShadowMaxSlope * ${DIRECTIONAL_SHADOW_FADE_START.toFixed(2)},
+    uShadowMaxSlope,
+    shadowSlope
+  );
+  if (lowElevationFade <= 0.0) return 1.0;
+
+  float texel = 1.35 / uShadowMapSize;
+  /*
+   * How far the plane compensation below may carry a tap's depth, in the map's own units.
+   *
+   * **The compensation is a product of an unbounded gradient and a bounded offset, and only one
+   * of the two was ever bounded.** A tap lands at most 1.85 texels from the receiver — the
+   * filter radius plus the texel-centre snap — so a gradient that has blown up turns a fraction
+   * of a texel into a depth swing of whole map units. The comparison then flips on alternate
+   * shadow texels, and what draws is a run of hard straight stripes lying along the map's texel
+   * grid: oblique on screen, because that grid is turned by the sun rather than by the camera,
+   * and only where the map holds an occluder at all, because a tap that reads the far plane is
+   * lit whatever depth it compares against. Reported exactly that way — bands near the shadows,
+   * not everywhere, and only at some hours of the day.
+   *
+   * Nine texels' worth of depth, which is not a taste. The receiver fade above already gives up
+   * below a directional n·l of 0.20, a surface 78 degrees off the sun, whose plane climbs 4.9
+   * units of depth per unit across the map. Over the 1.85 texels a tap can reach that is 9.1, so
+   * this bound sits above every slope the shader still draws a shadow on and below the ones it
+   * cannot represent. Stated against uShadowMapSize rather than in metres so it tracks the texel
+   * it is derived from: a 1024 map has texels twice as long and gets twice the allowance.
+   */
+  float slopeLimit = 9.1 / uShadowMapSize;
+  // Each PCF tap lands at a different point on the receiving plane. Following
+  // that plane's depth removes the striped self-shadowing a single constant
+  // comparison creates on large grazing surfaces, without increasing the
+  // contact gap. The residual 14 cm tolerance is projection-size independent;
+  // unlike the old normalised bias, it cannot silently grow toward a metre.
+  float staticLit = 0.0;
+  float peeledLit = 0.0;
+  float dynamicLit = 0.0;
+  for (int i = 0; i < ${MAX_SHADOW_FILTER_TAPS}; i++) {
+    if (i >= uShadowFilterTaps) break;
+    vec2 offset = DIRECTIONAL_PCF_OFFSETS[i] * texel;
+    vec2 sampleUv = p.xy + offset;
+    // Depth textures use NEAREST filtering, so the fetched depth belongs to
+    // the centre of the containing texel, not to the continuous Poisson UV.
+    // Following the continuous UV leaves up to half a texel of uncompensated
+    // plane slope; on a grazing face that becomes the repeating light/dark
+    // ribs seen as the receiver crosses shadow texels.
+    vec2 texelCentre = (floor(sampleUv * uShadowMapSize) + 0.5) / uShadowMapSize;
+    /* Clamped, not the raw product: see slopeLimit above. Compensation this large is already past
+       the slope the receiver fade draws anything on, so the clamp costs no picture. */
+    float slopeOffset = clamp(dot(depthGradient, texelCentre - p.xy), -slopeLimit, slopeLimit);
+    float tapReceiverDepth = p.z + slopeOffset;
+    float compare = tapReceiverDepth - 0.14 / uShadowDepthSpan;
+    /*
+     * \`textureLod\` rather than \`texture\`, by the rule \`AGENTS.md\` records on 2026-08-07:
+     * this loop is reached through a branch on \`vLightPos\`, which is not uniform, and an
+     * implicit derivative there is undefined. **WGSL does not merely leave it undefined, it
+     * refuses to compile the module**: *"'textureSample' must only be called from uniform
+     * control flow"*.
+     *
+     * Bit-for-bit identical on WebGL2 for the same reason the point-light samples were:
+     * \`shadowMap.ts\` allocates these with one storage level and \`NEAREST\` filtering, so
+     * there is no mip to select and level zero is the only thing \`texture\` could have read.
+     */
+    float staticDepth = textureLod(uStaticShadowMap, sampleUv, 0.0).r;
+    float dynamicDepth = textureLod(uDynamicShadowMap, sampleUv, 0.0).r;
+    staticLit += directionalVisibility(tapReceiverDepth, compare, staticDepth);
+    if (uPeeledShadowEnabled != 0) {
+      float peeledDepth = textureLod(uPeeledShadowMap, sampleUv, 0.0).r;
+      peeledLit += directionalVisibility(tapReceiverDepth, compare, peeledDepth);
+    } else {
+      peeledLit += 1.0;
+    }
+    dynamicLit += directionalVisibility(tapReceiverDepth, compare, dynamicDepth);
+  }
+  float tapCount = float(max(uShadowFilterTaps, 1));
+  staticLit /= tapCount;
+  peeledLit /= tapCount;
+  dynamicLit /= tapCount;
+
+  // Independent layers preserve every recorded fact at an overlap: each
+  // caster keeps its own distance fade, and their transmissions compose
+  // monotonically. The peeled layer holds the second static occluder that a
+  // conventional one-depth map would discard; movers remain independent too.
+  float lit = staticLit * peeledLit * dynamicLit;
+
+  return mix(1.0, lit, uShadowStrength * edgeFade * lowElevationFade * receiverFade);
+}
+#endif
+
+/**
+ * Value noise on a world position, for the grain term.
+ *
+ * Its own hash rather than the one the plume shaders use, because those work in 2D and
+ * grain on a solid has to be three-dimensional — a 2D pattern projected onto a turning
+ * object slides across its faces, which is precisely the "painted on" look this exists
+ * to avoid.
+ */`;

package/dist/render/shaders/flat/index.d.ts

@@ -0,0 +1,135 @@
+/** What the flat *vertex* stage compiles, as opposed to what it decides per frame. */
+export interface FlatVertexOptions {
+    /**
+     * Whether this variant reads morph deltas and adds them to the bind-pose position.
+     *
+     * The vertex stage's second axis, which takes it from two variants to four, for **1,674 gzipped
+     * bytes** against the 246,925 one more *fragment* flag costs. §3.2 of the plan asked for a
+     * re-measurement before adding this on the assumption four diverging variants would dedupe far
+     * worse than two; they dedupe somewhat worse, which is a different answer from the one feared.
+     */
+    readonly morphed: boolean;
+    /**
+     * Whether this variant reads a joint palette and moves the vertex by it.
+     *
+     * A permutation rather than a uniform gate, and the difference is measured rather than argued.
+     * The vertex shader had no permutation axis at all until skinning, so a second variant costs
+     * **1,118 bytes gzipped**, measured on the regenerated file. The two strings are 4.4 KB and
+     * mostly alike, so deflate's 32 KB window dedupes most of it. One more *fragment* flag costs
+     * **246,925** by the same measurement, because a fragment permutation is larger than that
+     * window and sixteen copies cannot dedupe — so this is 0.45% of what the rule is written about.
+     *
+     * The estimate before it was built was 357, taken by duplicating the existing string with a
+     * hand-written skinning body spliced in. It was a floor and is recorded as one: naga's real
+     * output carries the palette binding, two more entry-point parameters and its own temporaries,
+     * which the hand-written delta did not model. Three times an estimate is worth knowing about;
+     * three orders of magnitude is what the decision turned on, and that did not move. So the 2^n rule `ARCHITECTURE.md` §1 states is a fact about the fragment
+     * corpus and not about permutation itself.
+     *
+     * What a uniform gate would have cost instead is a branch on every vertex of every static mesh
+     * in the engine, forever, for a feature most scenes never use. What would make the permutation
+     * wrong is a second vertex flag: four diverging variants dedupe less well than two, so
+     * re-measure before adding one.
+     */
+    readonly skinned: boolean;
+    /**
+     * Whether placement and tint arrive once per instance instead of once per draw.
+     *
+     * Excludes `skinned`: the joint attributes and the instance matrix want the same locations.
+     */
+    readonly instanced: boolean;
+}
+/**
+ * The flat vertex shader, built for one variant.
+ *
+ * `resolveConditionals` cuts the skinning prelude and both attribute declarations out entirely
+ * when `skinned` is false, so an unskinned pipeline declares locations 11 and 12 nowhere and a
+ * driver is never handed a palette sampler it cannot reach.
+ */
+export declare function flatVert(options: FlatVertexOptions): string;
+/** What the flat pass *compiles*, as opposed to what it decides per frame. */
+export interface FlatShaderOptions {
+    readonly pointShadows: boolean;
+    readonly directionalShadows: boolean;
+    /**
+     * Whether the mirror direction samples a baked cubemap of the scene.
+     *
+     * Cut out of the source rather than left in and multiplied by zero, and that is a
+     * correctness matter rather than a saving. The lit pass already binds sixteen texture
+     * units, which is exactly what WebGL2 guarantees, so a seventeenth sampler that is
+     * *declared* would default to unit 0 and share it with a `sampler2D` shadow map. Two
+     * sampler types on one unit is undefined at best and an INVALID_OPERATION at worst, for
+     * a fetch whose result was going to be discarded.
+     */
+    readonly environmentProbe: boolean;
+    /**
+     * Whether the night-side emissive term is compiled in at all.
+     *
+     * **Cut out rather than multiplied by zero, and that is measured rather than tidiness.** The
+     * term names `emissiveTint` and `vEmissive`, which the ordinary emissive line above it also
+     * names, and giving those a second consumer lets the compiler re-plan the arithmetic they
+     * share. Held on the gilded chamber with the amount at 0, against the build before the term
+     * existed: **109 pixels of 750,080 moved**, mean delta 17, where a shadow tap sat exactly on
+     * its boundary and flipped sides on an emissive surface.
+     *
+     * Isolated by elimination rather than guessed. The uniform declared and never used moves 0
+     * pixels; the branch present with an empty body moves 1, which is that scene's own floor; a
+     * body naming nothing the emissive line names moves 0; the real expression moves 109. So the
+     * cost is the operands, and the only way to charge nothing for a feature nobody asked for is
+     * for its instructions not to be there.
+     */
+    readonly nightEmissive: boolean;
+    /**
+     * How many point lights this build declares room for. `MAX_POINT_LIGHTS` when absent.
+     *
+     * **Not a permutation axis and not a picture setting: a way to fit the uniform grid.** Ten of
+     * this shader's uniform arrays are sized by it with point shadows off and twenty with them on,
+     * and GLSL ES gives an array one row of the grid per element whatever its base type — so
+     * `uniform float uLightRadius[16]` costs the same sixteen rows a `vec3` array of sixteen does.
+     * At the full budget the lit fragment stage declares **440** rows with point shadows and **248**
+     * without; an Adreno 740 offers **256** and WebGL2 guarantees only **224**. So a phone could not
+     * link this shader at all, and switching point shadows off — the only lever a consumer had — pays
+     * a whole feature and still does not reach a conforming device.
+     *
+     * Lowering it costs lights, which is a picture decision, and that is why it is stated rather
+     * than derived: 8 lights and 2 rectangles is 252 rows **with** point shadows compiled in.
+     *
+     * **WebGL2 only in effect.** The generated WGSL is built at the full budget and committed, and
+     * WebGPU has no per-stage uniform-vector ceiling to be short of — its whole block is about 7 KB
+     * against a 64 KB guaranteed binding size. A consumer that sets this and lands on WebGPU gets
+     * the full budget, which is the better picture and the one the device can afford.
+     */
+    readonly maxLights?: number;
+    /** How many rectangular emitters this build declares room for. `MAX_AREA_LIGHTS` when absent. */
+    readonly maxAreaLights?: number;
+}
+/**
+ * The flat fragment shader, built for one quality profile.
+ *
+ * A permutation rather than a constant, because a profile with shadows off was still
+ * compiling every line of shadow code it could never reach: ten `samplerCube` uniforms, a
+ * ten-way branch chain over them, a 190-line cubemap filter and two PCF loops. GLSL has no
+ * way to prove at compile time that `uPointShadowIndex[k]` is always -1, so none of it is
+ * eliminated — it becomes register pressure and sampler state paid by every fragment of
+ * every frame, in a shader whose author had already switched the feature off.
+ *
+ * That is ordinary waste on most parts and not ordinary on all of them. On a Radeon RX
+ * 9070 XT (RDNA4, Mesa 25.2.8) a dense interior world drawn with the full shader faults the
+ * GPU within seconds — an `SQC (data)` page fault, then a `gfx_0.0.0` ring timeout and a
+ * driver reset that takes the WebGL context with it. The fault scales with fragment count:
+ * a quarter of the pixels bought four times the survival time, and the same scene under
+ * the renderer this replaced never faults at all. A driver should not fault whatever it is
+ * handed, so that half is a driver bug worth reporting — but a shader carrying five times
+ * the work it needs is ours, and this is the half we own.
+ *
+ * `#if` rather than stripping by hand, so the enabled path stays one readable shader and
+ * the disabled one is genuinely absent rather than merely unreachable.
+ */
+/**
+ * The fragment shader, assembled from its sections.
+ *
+ * The sections concatenate in exactly the order they occupied when this was one file, and
+ * `flatSource.test.ts` is what holds that: sixteen permutations pinned by hash and one in
+ * full. A reordering here changes the picture, and the snapshot is what says it has not.
+ */
+export declare function flatFrag(options: FlatShaderOptions): string;