Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

feat(render): a shadow's edge is as soft as the light source is big

yhh978c9c736aff
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 76c369481..512f2e3be 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,39 @@ published separately; it ships inside the editor.
### Added
+- **A shadow map's edge is as soft as the light source is big.** `shadowSoftness` — the
+ light's half-extent in world units — reached only the 2D occluder path, which samples
+ five points across the source and counts what each of them can see. A mesh shadow map
+ ignored it and drew one edge, so the field's own documentation was false for maps.
+
+ It reaches the map now, by the physics the occluder path integrates: a source of
+ half-extent s at distance db throws a penumbra of s*(dr-db)/db across a receiver at dr.
+ The receiver finds db by looking — eight taps in a disc as wide as the source is, and
+ then the map's own depth inverted back into a distance. That inversion needs nothing
+ new: the projection writes z = A - A*near/d and A is the length of its depth row, so
+ one stored depth and this fragment's own distance give the other exactly. The filter is
+ thirty-two taps over a disc of the width that produces, spread by the golden angle so
+ the pattern follows the count instead of being pasted in beside it.
+
+ What this buys over a blur is contact hardening, and that is what the gates pin.
+ `soft-shadow` and `soft-shadow-contact` are one scene with the caster at two points
+ along the SAME light ray: the shadow lands in the same place both times and only its
+ edge differs — 25 world units of penumbra with the caster halfway to the light, 9 with
+ it nearly touching the floor. The two gates read the same four probes, and two of those
+ probes disagree by 85 and by 95.
+
+ Where a map has no eye — a sun's cascades are orthographic — a source's size in world
+ units says nothing about a penumbra, because there is no distance to measure it
+ against. Those keep the one edge and the four taps, which is also what every light
+ whose `shadowSoftness` is still 0 pays.
+
+ Verified against three defects. With the softness zeroed, the soft gate's penumbra
+ probe reads 0 where it wants 75. With the filter's radius made independent of the
+ blocker's distance, the contact gate reads 124 where it wants 180. And with the blocker
+ search comparing against a one-texel bias rather than its own reach, the receiver's own
+ slope counts as the thing shadowing it — which collapses the whole feature back to a
+ hard edge, and is how it first behaved.
+
- **A point light casts a shadow in every direction.** A spot's map is the cone it
opens. A point light opens none, and no single projection covers everywhere at once —
so its map is a cube: six cones at right angles, six tiles out of the same atlas,
diff --git a/desktop/public/scenes/soft-shadow-contact.esscene b/desktop/public/scenes/soft-shadow-contact.esscene
new file mode 100644
index 000000000..770acf877
--- /dev/null
+++ b/desktop/public/scenes/soft-shadow-contact.esscene
@@ -0,0 +1,34 @@
+{
+ "version": 1,
+ "name": "SoftShadowContact",
+ "entities": [
+ {
+ "id": 0, "name": "Camera", "parent": null, "children": [], "visible": true,
+ "components": [
+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 10 } } },
+ { "type": "Camera", "data": { "projectionType": 1, "orthoSize": 300, "isActive": true, "priority": 0 } }
+ ]
+ },
+ {
+ "id": 1, "name": "Ground", "parent": null, "children": [], "visible": true,
+ "components": [
+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": -200 }, "scale": { "x": 900, "y": 900, "z": 1 } } },
+ { "type": "Mesh2D", "data": { "mesh": "/scenes/shadow-quad.esmesh", "color": { "r": 1, "g": 1, "b": 1, "a": 1 }, "lit": true, "opaque": true, "enabled": true } }
+ ]
+ },
+ {
+ "id": 2, "name": "Blocker", "parent": null, "children": [], "visible": true,
+ "components": [
+ { "type": "Transform", "data": { "position": { "x": 80, "y": 0, "z": -160 }, "scale": { "x": 100, "y": 100, "z": 1 } } },
+ { "type": "Mesh2D", "data": { "mesh": "/scenes/shadow-quad.esmesh", "color": { "r": 1, "g": 1, "b": 1, "a": 1 }, "lit": true, "opaque": true, "enabled": true } }
+ ]
+ },
+ {
+ "id": 3, "name": "Lamp", "parent": null, "children": [], "visible": true,
+ "components": [
+ { "type": "Transform", "data": { "position": { "x": -100, "y": 0, "z": 200 } } },
+ { "type": "Light2D", "data": { "type": 3, "color": { "r": 1, "g": 1, "b": 1, "a": 1 }, "intensity": 1, "radius": 3000, "innerAngle": 80, "outerAngle": 90, "meshShadows": true, "shadowSoftness": 40 } }
+ ]
+ }
+ ]
+}
diff --git a/desktop/public/scenes/soft-shadow.esscene b/desktop/public/scenes/soft-shadow.esscene
new file mode 100644
index 000000000..e398efe38
--- /dev/null
+++ b/desktop/public/scenes/soft-shadow.esscene
@@ -0,0 +1,34 @@
+{
+ "version": 1,
+ "name": "SoftShadow",
+ "entities": [
+ {
+ "id": 0, "name": "Camera", "parent": null, "children": [], "visible": true,
+ "components": [
+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 10 } } },
+ { "type": "Camera", "data": { "projectionType": 1, "orthoSize": 300, "isActive": true, "priority": 0 } }
+ ]
+ },
+ {
+ "id": 1, "name": "Ground", "parent": null, "children": [], "visible": true,
+ "components": [
+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": -200 }, "scale": { "x": 900, "y": 900, "z": 1 } } },
+ { "type": "Mesh2D", "data": { "mesh": "/scenes/shadow-quad.esmesh", "color": { "r": 1, "g": 1, "b": 1, "a": 1 }, "lit": true, "opaque": true, "enabled": true } }
+ ]
+ },
+ {
+ "id": 2, "name": "Blocker", "parent": null, "children": [], "visible": true,
+ "components": [
+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 0 }, "scale": { "x": 100, "y": 100, "z": 1 } } },
+ { "type": "Mesh2D", "data": { "mesh": "/scenes/shadow-quad.esmesh", "color": { "r": 1, "g": 1, "b": 1, "a": 1 }, "lit": true, "opaque": true, "enabled": true } }
+ ]
+ },
+ {
+ "id": 3, "name": "Lamp", "parent": null, "children": [], "visible": true,
+ "components": [
+ { "type": "Transform", "data": { "position": { "x": -100, "y": 0, "z": 200 } } },
+ { "type": "Light2D", "data": { "type": 3, "color": { "r": 1, "g": 1, "b": 1, "a": 1 }, "intensity": 1, "radius": 3000, "innerAngle": 80, "outerAngle": 90, "meshShadows": true, "shadowSoftness": 40 } }
+ ]
+ }
+ ]
+}
diff --git a/src/esengine/ecs/components/Light2D.hpp b/src/esengine/ecs/components/Light2D.hpp
index 229959525..88a4b4370 100644
--- a/src/esengine/ecs/components/Light2D.hpp
+++ b/src/esengine/ecs/components/Light2D.hpp
@@ -78,9 +78,10 @@ struct Light2D {
ES_PROPERTY(animatable, min=0, max=180, unit="°", advanced)
f32 outerAngle{45.0f};
- /** @brief Shadow penumbra softness = light-source half-extent in world units. 0 = hard-edged
- * shadow (default; identical to no softening). Larger values widen the penumbra the way
- * a bigger area light does. Applies to every light type that casts a shadow. */
+ /** @brief Shadow penumbra softness = the light source's half-extent in world units; 0 is a
+ * hard edge (default). It widens a penumbra the way a bigger source does, and the edge
+ * sharpens as a caster nears what it falls on. Read by the 2D occluder boxes of every
+ * type, and by a mesh shadow map only where the light HAS a position (Point/Spot). */
ES_PROPERTY(animatable, min=0, tooltip="Shadow softness (light-source size); 0 = hard edge.")
f32 shadowSoftness{0.0f};
diff --git a/src/esengine/resource/ShaderParser.cpp b/src/esengine/resource/ShaderParser.cpp
index fc2fcfe60..2c0677d7b 100644
--- a/src/esengine/resource/ShaderParser.cpp
+++ b/src/esengine/resource/ShaderParser.cpp
@@ -746,7 +746,35 @@ fn packDepth(d : f32) -> vec3f {
fn unpackDepth(c : vec3f) -> f32 {
return dot(c, vec3f(1.0, 1.0 / 255.0, 1.0 / 65025.0));
}
-fn shadowFactor3D(worldPos : vec3f, N : vec3f, L : vec3f, first : i32, count : i32) -> f32 {
+fn stepFor(texel : f32, slope : f32, reach : f32) -> f32 {
+ // How far toward the light a lookup has to ask from: one texel of doubt about where
+ // the map sampled this surface, plus whatever `reach` texels of it are worth at the
+ // angle it stands.
+ return texel * (1.5 * (1.0 + slope) + reach * slope);
+}
+fn shadowDepth(m : mat4x4f, p : vec3f) -> f32 {
+ let c = m * vec4f(p, 1.0);
+ return clamp(c.z / max(c.w, 1e-6) * 0.5 + 0.5, 0.0, 1.0);
+}
+fn shadowTap(at : vec2f, lo : vec2f, hi : vec2f, here : f32) -> f32 {
+#ifdef ES_RECEIVE_SHADOW
+ // A tap that leaves its tile reads another map entirely — a neighbouring cube face,
+ // which is the least related depth in the atlas.
+ let d = unpackDepth(textureSampleLevel(t2, s2, clamp(at, lo, hi), 0.0).rgb);
+ return select(1.0, 0.0, d < here);
+#else
+ // The map's sampler is only declared where a shader receives one.
+ return 1.0;
+#endif
+}
+fn diskTap(i : i32, n : i32, radius : f32) -> vec2f {
+ // A spiral, not a table: the golden angle spreads any number of taps evenly over a
+ // disc, so the pattern follows the count instead of being pasted in beside it.
+ let a = f32(i) * 2.3999632;
+ return radius * sqrt((f32(i) + 0.5) / f32(n)) * vec2f(cos(a), sin(a));
+}
+fn shadowFactor3D(worldPos : vec3f, N : vec3f, L : vec3f, softness : f32,
+ first : i32, count : i32) -> f32 {
#ifndef ES_RECEIVE_SHADOW
return 1.0;
#else
@@ -784,26 +812,60 @@ fn shadowFactor3D(worldPos : vec3f, N : vec3f, L : vec3f, first : i32, count : i
// Ask a step toward the light rather than shift the answer: a step in world units
// is the same step whether a map's depth runs linearly with distance or
// hyperbolically, which is what lets one expression serve a cascade and a cone.
- let lb = m * vec4f(worldPos + L * (texel * 1.5 * (1.0 + slope)), 1.0);
- let here = clamp(lb.z / max(lb.w, 1e-6) * 0.5 + 0.5, 0.0, 1.0);
+ let here = shadowDepth(m, worldPos + L * stepFor(texel, slope, 0.0));
// The ONE place the two backends must not agree: v = 0 samples a texture's
// bottom in GL and its top here, and the rect arrives with its low corner in
// GL's terms — so the tile and the square inside it are both turned over.
let base = vec2f(rect.x, 1.0 - rect.y - rect.z);
- // A tap that leaves this tile reads another map entirely — a neighbouring cube
- // face, which is the least related depth in the atlas.
+ let at0 = base + vec2f(uv.x, 1.0 - uv.y) * rect.z;
let lo = base + lc.u_shadowParams.y * 0.5;
let hi = base + rect.z - lc.u_shadowParams.y * 0.5;
- var lit = 0.0;
- for (var y = 0; y < 2; y++) {
- for (var x = 0; x < 2; x++) {
- let o = (vec2f(f32(x), f32(y)) - 0.5) * lc.u_shadowParams.y;
- let at = clamp(base + vec2f(uv.x, 1.0 - uv.y) * rect.z + o, lo, hi);
- let d = unpackDepth(textureSampleLevel(t2, s2, at, 0.0).rgb);
- if (d >= here) { lit += 1.0; }
+ // A source with no size — or a map whose w does not vary with position, which is
+ // a map with no eye and so no distance to measure a source against — throws one
+ // edge, and four taps are its whole cost.
+ if (softness <= 0.0 || length(vec3f(m[0].w, m[1].w, m[2].w)) < 0.5) {
+ var lit = 0.0;
+ for (var y = 0; y < 2; y++) {
+ for (var x = 0; x < 2; x++) {
+ let o = (vec2f(f32(x), f32(y)) - 0.5) * lc.u_shadowParams.y;
+ lit += shadowTap(at0 + o, lo, hi, here);
+ }
}
+ return lit * 0.25;
+ }
+ // What blocks this fragment. The search is the source's own half-extent in
+ // texels, capped: the tap count is fixed, so a wider disc than this samples too
+ // sparsely to average.
+ let searchR = clamp(softness / texel, 1.0, 8.0);
+ // Against a depth that forgives the reach, not the texel: a tap r texels away
+ // lands r texels along the surface too, and comparing it to a one-texel bias
+ // counts the receiver's own slope as the thing shadowing it.
+ let reach = shadowDepth(m, worldPos + L * stepFor(texel, slope, searchR));
+ var sum = 0.0;
+ var hits = 0.0;
+ for (var i = 0; i < 8; i++) {
+ let at = clamp(at0 + diskTap(i, 8, searchR) * lc.u_shadowParams.y, lo, hi);
+ let d = unpackDepth(textureSampleLevel(t2, s2, at, 0.0).rgb);
+ if (d < reach) { sum += d; hits += 1.0; }
+ }
+ if (hits < 0.5) { return 1.0; }
+ // How far from the light that blocker stands, out of the map's own depth: this
+ // projection writes z = A - A*near/d, and A is the length of its depth row, so
+ // one stored depth and this fragment's own distance inverts the other exactly.
+ let A = length(vec3f(m[0].z, m[1].z, m[2].z));
+ let db = lcp.w * (A - proj.z) / max(A - (2.0 * (sum / hits) - 1.0), 1e-6);
+ // A source of half-extent `softness` at db throws this much penumbra across a
+ // receiver at lcp.w — which is why a shadow hardens as its caster nears the
+ // surface, and why one number governs both.
+ let radius = clamp(softness * (lcp.w - db) / max(db * texel, 1e-4), 0.5, 8.0);
+ let wide = shadowDepth(m, worldPos + L * stepFor(texel, slope, radius));
+ // Thirty-two, where the hard edge needs four: the disc is as wide as the source
+ // makes it, and a penumbra averaged over too few taps bands instead of blurring.
+ var soft = 0.0;
+ for (var i = 0; i < 32; i++) {
+ soft += shadowTap(at0 + diskTap(i, 32, radius) * lc.u_shadowParams.y, lo, hi, wide);
}
- return lit * 0.25;
+ return soft * (1.0 / 32.0);
}
return 1.0;
#endif
@@ -1010,7 +1072,7 @@ fn applyLightingPBR(albedo : vec3f, N : vec3f, worldPos : vec3f, V : vec3f, meta
}
let sm = lc.u_lights[i].shadowMap;
if (sm.y > 0.0 && atten > 0.0) {
- atten *= shadowFactor3D(worldPos, N, L, i32(sm.x), i32(sm.y));
+ atten *= shadowFactor3D(worldPos, N, L, sh.x, i32(sm.x), i32(sm.y));
}
let ndotl = max(dot(N, L), 0.0);
let radiance = col.rgb * (col.a * ndotl * atten);
@@ -1356,11 +1418,39 @@ ShaderParser::AssembledStage ShaderParser::assembleStageEx(const ParsedShader& p
"highp float unpackDepth(in highp vec3 c) {\n"
" return dot(c, vec3(1.0, 1.0 / 255.0, 1.0 / 65025.0));\n"
"}\n"
+ // How far toward the light a lookup has to ask from: one texel of doubt about
+ // where the map sampled this surface, plus whatever `reach` texels of it are
+ // worth at the angle it stands.
+ "highp float stepFor(in highp float texel, in highp float slope,\n"
+ " in highp float reach) {\n"
+ " return texel * (1.5 * (1.0 + slope) + reach * slope);\n"
+ "}\n"
+ "highp float shadowDepth(in highp mat4 m, in highp vec3 p) {\n"
+ " highp vec4 c = m * vec4(p, 1.0);\n"
+ " return clamp(c.z / max(c.w, 1e-6) * 0.5 + 0.5, 0.0, 1.0);\n"
+ "}\n"
+ // A tap that leaves its tile reads another map entirely — a neighbouring
+ // cube face, which is the least related depth in the atlas.
+ "highp float shadowTap(in highp vec2 at, in highp vec2 lo, in highp vec2 hi,\n"
+ " in highp float here) {\n"
+ "#ifdef ES_RECEIVE_SHADOW\n"
+ " return unpackDepth(texture(u_shadowMap, clamp(at, lo, hi)).rgb) < here\n"
+ " ? 0.0 : 1.0;\n"
+ "#else\n"
+ " return 1.0;\n"
+ "#endif\n"
+ "}\n"
+ // A spiral, not a table: the golden angle spreads any number of taps evenly
+ // over a disc, so the pattern follows the count instead of sitting beside it.
+ "highp vec2 diskTap(in int i, in int n, in highp float radius) {\n"
+ " highp float a = float(i) * 2.3999632;\n"
+ " return radius * sqrt((float(i) + 0.5) / float(n)) * vec2(cos(a), sin(a));\n"
+ "}\n"
// Visibility of a world point from the light that rendered the map. Depth is
// written and compared through the SAME matrix and expression, so the two
// backends' clip-z conventions cancel. 2x2 taps: one is a staircase.
"highp float shadowFactor3D(in highp vec3 worldPos, in highp vec3 N, in highp vec3 L,\n"
- " in int first, in int count) {\n"
+ " in highp float softness, in int first, in int count) {\n"
"#ifndef ES_RECEIVE_SHADOW\n"
" return 1.0;\n"
"#else\n"
@@ -1400,21 +1490,61 @@ ShaderParser::AssembledStage ShaderParser::assembleStageEx(const ParsedShader& p
// Ask a step toward the light rather than shift the answer: a step in world
// units is the same step whether a map's depth runs linearly with distance or
// hyperbolically, which is what lets one expression serve a cascade and a cone.
- " highp vec4 lb = m * vec4(worldPos + L * (texel * 1.5 * (1.0 + slope)), 1.0);\n"
- " highp float here = clamp(lb.z / max(lb.w, 1e-6) * 0.5 + 0.5, 0.0, 1.0);\n"
- // A tap that leaves this tile reads another map entirely — a neighbouring
- // cube face, which is the least related depth in the atlas.
+ " highp float here = shadowDepth(m, worldPos + L * stepFor(texel, slope, 0.0));\n"
+ " highp vec2 at0 = rect.xy + uv * rect.z;\n"
" highp vec2 lo = rect.xy + u_shadowParams.y * 0.5;\n"
" highp vec2 hi = rect.xy + rect.z - u_shadowParams.y * 0.5;\n"
- " highp float lit = 0.0;\n"
- " for (int y = 0; y < 2; ++y) {\n"
- " for (int x = 0; x < 2; ++x) {\n"
- " highp vec2 o = (vec2(float(x), float(y)) - 0.5) * u_shadowParams.y;\n"
- " highp vec2 at = clamp(rect.xy + uv * rect.z + o, lo, hi);\n"
- " lit += unpackDepth(texture(u_shadowMap, at).rgb) < here ? 0.0 : 1.0;\n"
+ // A source with no size — or a map whose w does not vary with position, which
+ // is a map with no eye and so no distance to measure a source against —
+ // throws one edge, and four taps are its whole cost.
+ " if (softness <= 0.0\n"
+ " || length(vec3(m[0][3], m[1][3], m[2][3])) < 0.5) {\n"
+ " highp float lit = 0.0;\n"
+ " for (int y = 0; y < 2; ++y) {\n"
+ " for (int x = 0; x < 2; ++x) {\n"
+ " highp vec2 o = (vec2(float(x), float(y)) - 0.5) * u_shadowParams.y;\n"
+ " lit += shadowTap(at0 + o, lo, hi, here);\n"
+ " }\n"
" }\n"
+ " return lit * 0.25;\n"
+ " }\n"
+ // What blocks this fragment. The search is the source's own half-extent in
+ // texels, capped: the tap count is fixed, so a wider disc than this samples
+ // too sparsely to average.
+ " highp float searchR = clamp(softness / texel, 1.0, 8.0);\n"
+ // Against a depth that forgives the reach, not the texel: a tap r texels away
+ // lands r texels along the surface too, and comparing it to a one-texel bias
+ // counts the receiver's own slope as the thing shadowing it.
+ " highp float reach = shadowDepth(m, worldPos + L * stepFor(texel, slope, searchR));\n"
+ " highp float sum = 0.0;\n"
+ " highp float hits = 0.0;\n"
+ " for (int i = 0; i < 8; ++i) {\n"
+ " highp vec2 at = clamp(at0 + diskTap(i, 8, searchR) * u_shadowParams.y, lo, hi);\n"
+ " highp float d = unpackDepth(texture(u_shadowMap, at).rgb);\n"
+ " if (d < reach) { sum += d; hits += 1.0; }\n"
+ " }\n"
+ " if (hits < 0.5) return 1.0;\n"
+ // How far from the light that blocker stands, out of the map's own depth:
+ // this projection writes z = A - A*near/d, and A is the length of its depth
+ // row, so one stored depth and this fragment's distance invert the other.
+ " highp float A = length(vec3(m[0][2], m[1][2], m[2][2]));\n"
+ " highp float db = lc.w * (A - proj.z)\n"
+ " / max(A - (2.0 * (sum / hits) - 1.0), 1e-6);\n"
+ // A source of half-extent `softness` at db throws this much penumbra across a
+ // receiver at lc.w — which is why a shadow hardens as its caster nears the
+ // surface, and why one number governs both.
+ " highp float radius = clamp(softness * (lc.w - db) / max(db * texel, 1e-4),\n"
+ " 0.5, 8.0);\n"
+ " highp float wide = shadowDepth(m, worldPos + L * stepFor(texel, slope, radius));\n"
+ // Thirty-two, where the hard edge needs four: the disc is as wide as the
+ // source makes it, and a penumbra averaged over too few taps bands rather
+ // than blurs.
+ " highp float soft = 0.0;\n"
+ " for (int i = 0; i < 32; ++i) {\n"
+ " soft += shadowTap(at0 + diskTap(i, 32, radius) * u_shadowParams.y,\n"
+ " lo, hi, wide);\n"
" }\n"
- " return lit * 0.25;\n"
+ " return soft * (1.0 / 32.0);\n"
" }\n"
" return 1.0;\n"
"#endif\n"
@@ -1677,7 +1807,7 @@ ShaderParser::AssembledStage ShaderParser::assembleStageEx(const ParsedShader& p
// seen from somewhere no light reaching it is standing.
" highp vec4 sm = u_lights[i].shadowMap;\n"
" if (sm.y > 0.0 && atten > 0.0) {\n"
- " atten *= shadowFactor3D(worldPos, N, L, int(sm.x), int(sm.y));\n"
+ " atten *= shadowFactor3D(worldPos, N, L, sh.x, int(sm.x), int(sm.y));\n"
" }\n"
" highp float ndotl = max(dot(N, L), 0.0);\n"
" highp vec3 radiance = col.rgb * (col.a * ndotl * atten);\n"
diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjs
index 8dd75d941..3ba3c5099 100644
--- a/tools/renderScenes.mjs
+++ b/tools/renderScenes.mjs
@@ -84,6 +84,14 @@ export const SCENES = [
// face it lands in. TWO shadows in two faces is what makes that choice visible: report
// one tile for every tile and both come back lit. The casters are probed as well.
{ id: "point-shadow", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/point-shadow.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.167,\"y\":0.5,\"rgb\":[0,0,0],\"tol\":20},{\"x\":0.5,\"y\":0.833,\"rgb\":[0,0,0],\"tol\":20},{\"x\":0.333,\"y\":0.5,\"rgb\":[108,108,108],\"tol\":25},{\"x\":0.833,\"y\":0.5,\"rgb\":[102,102,102],\"tol\":25},{\"x\":0.5,\"y\":0.5,\"rgb\":[242,242,242],\"tol\":20}]" } },
+ // A SOURCE WITH SIZE. The light's half-extent, the blocker's distance from it and the
+ // receiver's are the whole penumbra, so these probes read a soft edge here and a hard
+ // one in the gate below, where the same scene's caster stands near what it falls on.
+ { id: "soft-shadow", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/soft-shadow.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.73,\"y\":0.5,\"rgb\":[0,0,0],\"tol\":20},{\"x\":0.759,\"y\":0.5,\"rgb\":[0,0,0],\"tol\":20},{\"x\":0.833,\"y\":0.5,\"rgb\":[75,75,75],\"tol\":45},{\"x\":0.9,\"y\":0.5,\"rgb\":[158,158,158],\"tol\":25}]" } },
+ // The same scene with the caster moved DOWN the light's own ray: its shadow lands where
+ // it did and the edge sharpens by the ratio of the two distances. A fixed blur would
+ // read the same in both gates, and one that ignores the source's size neither.
+ { id: "soft-shadow-contact", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/soft-shadow-contact.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.745,\"y\":0.5,\"rgb\":[0,0,0],\"tol\":20},{\"x\":0.759,\"y\":0.5,\"rgb\":[85,85,85],\"tol\":55},{\"x\":0.77,\"y\":0.5,\"rgb\":[180,180,180],\"tol\":25},{\"x\":0.833,\"y\":0.5,\"rgb\":[170,170,170],\"tol\":25}]" } },
{ id: "mesh-shadow-cascade", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mesh-shadow-cascade.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.657,\"y\":0.452,\"rgb\":[0,0,0],\"tol\":20},{\"x\":0.6,\"y\":0.452,\"rgb\":[252,252,252],\"tol\":20},{\"x\":0.72,\"y\":0.452,\"rgb\":[252,252,252],\"tol\":20}]" } },
{ id: "mesh-shadow-perspective", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mesh-shadow-perspective.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.86,\"y\":0.5,\"rgb\":[0,0,0],\"tol\":20},{\"x\":0.10,\"y\":0.5,\"rgb\":[228,228,228],\"tol\":20},{\"x\":0.5,\"y\":0.5,\"rgb\":[228,228,228],\"tol\":20}]" } },
// A sun aimed OUT of the plane: 0.25 in x and 0.25 in depth throws the blocker's