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 sun has a size too, and it is an angle

yhhca768ce9b82c
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9444fbdd5..fab6c776e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,35 @@ published separately; it ships inside the editor.
### Added
+- **A sun has a size too, and it is an angle.** A light with a position carries its source
+ as a half-extent in world units, and the penumbra follows from dividing that by the
+ distance to what blocks it. A directional light has no such distance — its source is
+ infinitely far away — so a length says nothing about its shadow's edge, and its cascades
+ stayed hard while every other light's softened. `Light2D::sourceAngle` is what it
+ carries instead: the full angle its source subtends, in degrees, 0.53 being the real
+ sun's. Every engine that does this splits it the same way, and for the same reason.
+
+ One expression still serves both, which is the point: the penumbra is the tangent of the
+ angle the source subtends AT THE BLOCKER, times how far the receiver stands beyond it.
+ A map with an eye divides a half-extent by the blocker's distance to get that tangent; a
+ map without one measures its own w as 1 everywhere, so what it divides is the tangent
+ itself. The shader picks between them on a property of the matrix — whether its w varies
+ with position — and the same line computes the radius either way.
+
+ What it costs to know the blocker's distance is nothing new either. The map's depth row
+ has length A, and each kind of map inverts its own depth with it: hyperbolic where there
+ is an eye, linear where there is not.
+
+ Gates `sun-shadow` and `sun-shadow-contact`, both backends: one scene with the caster at
+ two points along the SAME sunbeam, so its shadow lands in the same place and only the
+ edge differs — 9 world units of penumbra with the caster 100 above the ground, 2.4 with
+ it a quarter of that. Two of the four shared probes differ by 70 and 38.
+
+ Verified against the defect and against the neighbouring field: with `sourceAngle` zeroed
+ the edge collapses to one sample step (0 → 124 → 247) and both differing probes go red,
+ and with `shadowSoftness` set to 200 on the same sun the frame does not move by a single
+ value — a length is not what a sun's map reads.
+
- **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
diff --git a/desktop/public/scenes/sun-shadow-contact.esscene b/desktop/public/scenes/sun-shadow-contact.esscene
new file mode 100644
index 000000000..abc9f2085
--- /dev/null
+++ b/desktop/public/scenes/sun-shadow-contact.esscene
@@ -0,0 +1,34 @@
+{
+ "version": 1,
+ "name": "SunShadowContact",
+ "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": 40, "isActive": true, "priority": 0 } }
+ ]
+ },
+ {
+ "id": 1, "name": "Ground", "parent": null, "children": [], "visible": true,
+ "components": [
+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": -100 }, "scale": { "x": 1000, "y": 1000, "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": -1.25, "y": 0, "z": -75 }, "scale": { "x": 20, "y": 20, "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": "Sun", "parent": null, "children": [], "visible": true,
+ "components": [
+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 0 } } },
+ { "type": "Light2D", "data": { "type": 1, "color": { "r": 1, "g": 1, "b": 1, "a": 1 }, "intensity": 1, "direction": { "x": 0.25, "y": 0 }, "meshShadows": true, "shadowExtent": 500, "sourceAngle": 5.6 } }
+ ]
+ }
+ ]
+}
diff --git a/desktop/public/scenes/sun-shadow.esscene b/desktop/public/scenes/sun-shadow.esscene
new file mode 100644
index 000000000..12a7dae8b
--- /dev/null
+++ b/desktop/public/scenes/sun-shadow.esscene
@@ -0,0 +1,34 @@
+{
+ "version": 1,
+ "name": "SunShadow",
+ "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": 40, "isActive": true, "priority": 0 } }
+ ]
+ },
+ {
+ "id": 1, "name": "Ground", "parent": null, "children": [], "visible": true,
+ "components": [
+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": -100 }, "scale": { "x": 1000, "y": 1000, "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": -20, "y": 0, "z": 0 }, "scale": { "x": 20, "y": 20, "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": "Sun", "parent": null, "children": [], "visible": true,
+ "components": [
+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 0 } } },
+ { "type": "Light2D", "data": { "type": 1, "color": { "r": 1, "g": 1, "b": 1, "a": 1 }, "intensity": 1, "direction": { "x": 0.25, "y": 0 }, "meshShadows": true, "shadowExtent": 500, "sourceAngle": 5.6 } }
+ ]
+ }
+ ]
+}
diff --git a/docs/astro/src/data/components.generated.json b/docs/astro/src/data/components.generated.json
index 64d6fa05f..c014e66f5 100644
--- a/docs/astro/src/data/components.generated.json
+++ b/docs/astro/src/data/components.generated.json
@@ -1592,6 +1592,14 @@
"doc": "Shadow softness (light-source size); 0 = hard edge.",
"range": "≥ 0"
},
+ {
+ "key": "sourceAngle",
+ "type": "number",
+ "default": "0",
+ "doc": "Angular size of a Directional light's source; 0 = hard edge (sun ~0.53).",
+ "range": "0–90",
+ "advanced": true
+ },
{
"key": "shadowDistance",
"type": "number",
@@ -1642,6 +1650,7 @@
"innerAngle",
"outerAngle",
"shadowSoftness",
+ "sourceAngle",
"shadowDistance"
]
},
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index c23c4b8ba..2e55b6b5f 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -5,7 +5,7 @@ Symbols: 113 public · 66 beta · 1481 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
-"e868cc33a27b61d4"
+"4f073fe384c59476"
```
## ANCHOR_AXES — const @experimental
@@ -4020,6 +4020,7 @@ radius: number
shadowDistance: number
shadowExtent: number
shadowSoftness: number
+sourceAngle: number
type: number
```
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 14d72068e..688f0ce50 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -5,7 +5,7 @@ Symbols: 113 public · 71 beta · 1500 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
-"e868cc33a27b61d4"
+"4f073fe384c59476"
```
## ANCHOR_AXES — const @experimental
@@ -4028,6 +4028,7 @@ radius: number
shadowDistance: number
shadowExtent: number
shadowSoftness: number
+sourceAngle: number
type: number
```
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 043956bd3..eba1dfdad 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -4015,6 +4015,7 @@ radius: number
shadowDistance: number
shadowExtent: number
shadowSoftness: number
+sourceAngle: number
type: number
```
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 2c17dfa23..507d308ae 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -4015,6 +4015,7 @@ radius: number
shadowDistance: number
shadowExtent: number
shadowSoftness: number
+sourceAngle: number
type: number
```
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index b3a9b4da9..74d536477 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -4022,6 +4022,7 @@ radius: number
shadowDistance: number
shadowExtent: number
shadowSoftness: number
+sourceAngle: number
type: number
```
diff --git a/sdk/src/ecs/bridge/ptrAccessors.generated.ts b/sdk/src/ecs/bridge/ptrAccessors.generated.ts
index e00559db4..424009502 100644
--- a/sdk/src/ecs/bridge/ptrAccessors.generated.ts
+++ b/sdk/src/ecs/bridge/ptrAccessors.generated.ts
@@ -693,6 +693,7 @@ export interface Light2DPtrData {
innerAngle: number;
outerAngle: number;
shadowSoftness: number;
+ sourceAngle: number;
shadowDistance: number;
meshShadows: boolean;
shadowExtent: number;
@@ -712,12 +713,13 @@ export function fillLight2D(
out.innerAngle = f32[(ptr + 28) >> 2];
out.outerAngle = f32[(ptr + 32) >> 2];
out.shadowSoftness = f32[(ptr + 36) >> 2];
- out.shadowDistance = f32[(ptr + 40) >> 2];
- out.meshShadows = u8[ptr + 44] !== 0;
- out.shadowExtent = f32[(ptr + 48) >> 2];
- out.environment = u32[(ptr + 52) >> 2];
- out.drawEnvironment = u8[ptr + 56] !== 0;
- out.enabled = u8[ptr + 57] !== 0;
+ out.sourceAngle = f32[(ptr + 40) >> 2];
+ out.shadowDistance = f32[(ptr + 44) >> 2];
+ out.meshShadows = u8[ptr + 48] !== 0;
+ out.shadowExtent = f32[(ptr + 52) >> 2];
+ out.environment = u32[(ptr + 56) >> 2];
+ out.drawEnvironment = u8[ptr + 60] !== 0;
+ out.enabled = u8[ptr + 61] !== 0;
}
export function writeLight2D(
@@ -731,12 +733,13 @@ export function writeLight2D(
f32[(ptr + 28) >> 2] = data.innerAngle;
f32[(ptr + 32) >> 2] = data.outerAngle;
f32[(ptr + 36) >> 2] = data.shadowSoftness;
- f32[(ptr + 40) >> 2] = data.shadowDistance;
- u8[ptr + 44] = data.meshShadows ? 1 : 0;
- f32[(ptr + 48) >> 2] = data.shadowExtent;
- u32[(ptr + 52) >> 2] = data.environment;
- u8[ptr + 56] = data.drawEnvironment ? 1 : 0;
- u8[ptr + 57] = data.enabled ? 1 : 0;
+ f32[(ptr + 40) >> 2] = data.sourceAngle;
+ f32[(ptr + 44) >> 2] = data.shadowDistance;
+ u8[ptr + 48] = data.meshShadows ? 1 : 0;
+ f32[(ptr + 52) >> 2] = data.shadowExtent;
+ u32[(ptr + 56) >> 2] = data.environment;
+ u8[ptr + 60] = data.drawEnvironment ? 1 : 0;
+ u8[ptr + 61] = data.enabled ? 1 : 0;
}
export function createLight2DData(): Light2DPtrData {
@@ -748,6 +751,7 @@ export function createLight2DData(): Light2DPtrData {
innerAngle: 0,
outerAngle: 0,
shadowSoftness: 0,
+ sourceAngle: 0,
shadowDistance: 0,
meshShadows: false,
shadowExtent: 0,
diff --git a/sdk/src/ecs/component.generated.ts b/sdk/src/ecs/component.generated.ts
index 750c5083e..9389de579 100644
--- a/sdk/src/ecs/component.generated.ts
+++ b/sdk/src/ecs/component.generated.ts
@@ -15,7 +15,7 @@ import type { Dimension, Padding } from '../wasm/wasm.generated';
* getAbiLayoutHash(); BuiltinBridge.connect() compares them and refuses to
* run on mismatch, because mismatched offsets read the wrong heap bytes.
*/
-export const ABI_LAYOUT_HASH = 'e868cc33a27b61d4';
+export const ABI_LAYOUT_HASH = '4f073fe384c59476';
/**
* One asset-valued field of a component: which field, and what kind of
@@ -395,6 +395,7 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {
innerAngle: 30,
outerAngle: 45,
shadowSoftness: 0,
+ sourceAngle: 0,
shadowDistance: 0,
meshShadows: false,
shadowExtent: 0,
@@ -406,7 +407,7 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {
assetFields: [{ field: 'environment', type: 'environment' as AssetFieldType }],
entityFields: [],
colorFields: ['color'],
- animatableFields: ['color.r', 'color.g', 'color.b', 'color.a', 'intensity', 'radius', 'innerAngle', 'outerAngle', 'shadowSoftness', 'shadowDistance'],
+ animatableFields: ['color.r', 'color.g', 'color.b', 'color.a', 'intensity', 'radius', 'innerAngle', 'outerAngle', 'shadowSoftness', 'sourceAngle', 'shadowDistance'],
fields: {
type: { enum: [{ label: 'Point', value: 0 }, { label: 'Directional', value: 1 }, { label: 'Ambient', value: 2 }, { label: 'Spot', value: 3 }], tooltip: "Point, Directional, Ambient, or Spot." },
intensity: { min: 0, tooltip: "Brightness multiplier of the light." },
@@ -414,6 +415,7 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {
innerAngle: { min: 0, max: 180, unit: "°", advanced: true },
outerAngle: { min: 0, max: 180, unit: "°", advanced: true },
shadowSoftness: { min: 0, tooltip: "Shadow softness (light-source size); 0 = hard edge." },
+ sourceAngle: { min: 0, max: 90, unit: "°", tooltip: "Angular size of a Directional light's source; 0 = hard edge (sun ~0.53).", advanced: true },
shadowDistance: { min: 0, tooltip: "Directional shadow distance; 0 = no directional shadow.", advanced: true },
meshShadows: { tooltip: "Cast a shadow map over 3D meshes (Directional, Spot, Point)." },
shadowExtent: { min: 0, tooltip: "Shadow map coverage radius; 0 = fit the view.", advanced: true },
@@ -1205,6 +1207,7 @@ export interface Light2DData {
innerAngle: number;
outerAngle: number;
shadowSoftness: number;
+ sourceAngle: number;
shadowDistance: number;
meshShadows: boolean;
shadowExtent: number;
diff --git a/sdk/src/wasm/ptrLayouts.generated.ts b/sdk/src/wasm/ptrLayouts.generated.ts
index 5959d5716..978ec47ca 100644
--- a/sdk/src/wasm/ptrLayouts.generated.ts
+++ b/sdk/src/wasm/ptrLayouts.generated.ts
@@ -206,12 +206,13 @@ export const PTR_LAYOUTS: Record<string, PtrLayout> = {
{ name: 'innerAngle', type: 'f32', offset: 28 },
{ name: 'outerAngle', type: 'f32', offset: 32 },
{ name: 'shadowSoftness', type: 'f32', offset: 36 },
- { name: 'shadowDistance', type: 'f32', offset: 40 },
- { name: 'meshShadows', type: 'bool', offset: 44 },
- { name: 'shadowExtent', type: 'f32', offset: 48 },
- { name: 'environment', type: 'u32', offset: 52 },
- { name: 'drawEnvironment', type: 'bool', offset: 56 },
- { name: 'enabled', type: 'bool', offset: 57 },
+ { name: 'sourceAngle', type: 'f32', offset: 40 },
+ { name: 'shadowDistance', type: 'f32', offset: 44 },
+ { name: 'meshShadows', type: 'bool', offset: 48 },
+ { name: 'shadowExtent', type: 'f32', offset: 52 },
+ { name: 'environment', type: 'u32', offset: 56 },
+ { name: 'drawEnvironment', type: 'bool', offset: 60 },
+ { name: 'enabled', type: 'bool', offset: 61 },
],
},
Mesh2D: {
diff --git a/sdk/src/wasm/wasm.generated.ts b/sdk/src/wasm/wasm.generated.ts
index c1979c0fb..df349910d 100644
--- a/sdk/src/wasm/wasm.generated.ts
+++ b/sdk/src/wasm/wasm.generated.ts
@@ -378,6 +378,7 @@ export interface Light2D {
innerAngle: number;
outerAngle: number;
shadowSoftness: number;
+ sourceAngle: number;
shadowDistance: number;
meshShadows: boolean;
shadowExtent: number;
diff --git a/src/esengine/bindings/EditorAPI.generated.cpp b/src/esengine/bindings/EditorAPI.generated.cpp
index cc265f43e..e0236bbd2 100644
--- a/src/esengine/bindings/EditorAPI.generated.cpp
+++ b/src/esengine/bindings/EditorAPI.generated.cpp
@@ -2,10 +2,10 @@
* @file EditorAPI.generated.cpp
* @brief Auto-generated editor API with string-dispatched component access
* @details Generated by EHT - DO NOT EDIT
- * @schema_hash 4fbe43821df1cf73
+ * @schema_hash 03aa2865f562634e
*/
-#define ES_EDITOR_API_SCHEMA_HASH "4fbe43821df1cf73"
+#define ES_EDITOR_API_SCHEMA_HASH "03aa2865f562634e"
#include <emscripten/bind.h>
#include <string>
@@ -296,6 +296,7 @@ std::string editor_getComponentSchema(const std::string& name) {
{"key":"innerAngle","type":"float","group":"Light2D"},
{"key":"outerAngle","type":"float","group":"Light2D"},
{"key":"shadowSoftness","type":"float","group":"Light2D"},
+ {"key":"sourceAngle","type":"float","group":"Light2D"},
{"key":"shadowDistance","type":"float","group":"Light2D"},
{"key":"meshShadows","type":"bool","group":"Light2D"},
{"key":"shadowExtent","type":"float","group":"Light2D"},
@@ -1144,6 +1145,7 @@ bool editor_setFloat(Registry& reg, u32 e, const std::string& comp, const std::s
else if (field == "innerAngle") { c.innerAngle = value; }
else if (field == "outerAngle") { c.outerAngle = value; }
else if (field == "shadowSoftness") { c.shadowSoftness = value; }
+ else if (field == "sourceAngle") { c.sourceAngle = value; }
else if (field == "shadowDistance") { c.shadowDistance = value; }
else if (field == "shadowExtent") { c.shadowExtent = value; }
else { return false; }
@@ -1597,6 +1599,7 @@ f32 editor_getFloat(Registry& reg, u32 e, const std::string& comp, const std::st
else if (field == "innerAngle") { return c.innerAngle; }
else if (field == "outerAngle") { return c.outerAngle; }
else if (field == "shadowSoftness") { return c.shadowSoftness; }
+ else if (field == "sourceAngle") { return c.sourceAngle; }
else if (field == "shadowDistance") { return c.shadowDistance; }
else if (field == "shadowExtent") { return c.shadowExtent; }
} else if (comp == "Mesh2D") {
diff --git a/src/esengine/bindings/WebBindings.generated.cpp b/src/esengine/bindings/WebBindings.generated.cpp
index 11aded93e..6cd61e04b 100644
--- a/src/esengine/bindings/WebBindings.generated.cpp
+++ b/src/esengine/bindings/WebBindings.generated.cpp
@@ -479,6 +479,7 @@ struct Light2DJS {
f32 innerAngle;
f32 outerAngle;
f32 shadowSoftness;
+ f32 sourceAngle;
f32 shadowDistance;
bool meshShadows;
f32 shadowExtent;
@@ -495,6 +496,7 @@ void light2dApplyJS(esengine::ecs::Light2D& c, const Light2DJS& js) {
c.innerAngle = js.innerAngle;
c.outerAngle = js.outerAngle;
c.shadowSoftness = js.shadowSoftness;
+ c.sourceAngle = js.sourceAngle;
c.shadowDistance = js.shadowDistance;
c.meshShadows = js.meshShadows;
c.shadowExtent = js.shadowExtent;
@@ -518,6 +520,7 @@ Light2DJS light2dToJS(const esengine::ecs::Light2D& c) {
js.innerAngle = c.innerAngle;
js.outerAngle = c.outerAngle;
js.shadowSoftness = c.shadowSoftness;
+ js.sourceAngle = c.sourceAngle;
js.shadowDistance = c.shadowDistance;
js.meshShadows = c.meshShadows;
js.shadowExtent = c.shadowExtent;
@@ -1437,6 +1440,7 @@ EMSCRIPTEN_BINDINGS(esengine_components) {
.field("innerAngle", &Light2DJS::innerAngle)
.field("outerAngle", &Light2DJS::outerAngle)
.field("shadowSoftness", &Light2DJS::shadowSoftness)
+ .field("sourceAngle", &Light2DJS::sourceAngle)
.field("shadowDistance", &Light2DJS::shadowDistance)
.field("meshShadows", &Light2DJS::meshShadows)
.field("shadowExtent", &Light2DJS::shadowExtent)
@@ -2781,12 +2785,13 @@ static_assert(offsetof(esengine::ecs::Light2D, radius) == 24, "ABI offset drift:
static_assert(offsetof(esengine::ecs::Light2D, innerAngle) == 28, "ABI offset drift: esengine::ecs::Light2D.innerAngle (EHT expected 28)");
static_assert(offsetof(esengine::ecs::Light2D, outerAngle) == 32, "ABI offset drift: esengine::ecs::Light2D.outerAngle (EHT expected 32)");
static_assert(offsetof(esengine::ecs::Light2D, shadowSoftness) == 36, "ABI offset drift: esengine::ecs::Light2D.shadowSoftness (EHT expected 36)");
-static_assert(offsetof(esengine::ecs::Light2D, shadowDistance) == 40, "ABI offset drift: esengine::ecs::Light2D.shadowDistance (EHT expected 40)");
-static_assert(offsetof(esengine::ecs::Light2D, meshShadows) == 44, "ABI offset drift: esengine::ecs::Light2D.meshShadows (EHT expected 44)");
-static_assert(offsetof(esengine::ecs::Light2D, shadowExtent) == 48, "ABI offset drift: esengine::ecs::Light2D.shadowExtent (EHT expected 48)");
-static_assert(offsetof(esengine::ecs::Light2D, environment) == 52, "ABI offset drift: esengine::ecs::Light2D.environment (EHT expected 52)");
-static_assert(offsetof(esengine::ecs::Light2D, drawEnvironment) == 56, "ABI offset drift: esengine::ecs::Light2D.drawEnvironment (EHT expected 56)");
-static_assert(offsetof(esengine::ecs::Light2D, enabled) == 57, "ABI offset drift: esengine::ecs::Light2D.enabled (EHT expected 57)");
+static_assert(offsetof(esengine::ecs::Light2D, sourceAngle) == 40, "ABI offset drift: esengine::ecs::Light2D.sourceAngle (EHT expected 40)");
+static_assert(offsetof(esengine::ecs::Light2D, shadowDistance) == 44, "ABI offset drift: esengine::ecs::Light2D.shadowDistance (EHT expected 44)");
+static_assert(offsetof(esengine::ecs::Light2D, meshShadows) == 48, "ABI offset drift: esengine::ecs::Light2D.meshShadows (EHT expected 48)");
+static_assert(offsetof(esengine::ecs::Light2D, shadowExtent) == 52, "ABI offset drift: esengine::ecs::Light2D.shadowExtent (EHT expected 52)");
+static_assert(offsetof(esengine::ecs::Light2D, environment) == 56, "ABI offset drift: esengine::ecs::Light2D.environment (EHT expected 56)");
+static_assert(offsetof(esengine::ecs::Light2D, drawEnvironment) == 60, "ABI offset drift: esengine::ecs::Light2D.drawEnvironment (EHT expected 60)");
+static_assert(offsetof(esengine::ecs::Light2D, enabled) == 61, "ABI offset drift: esengine::ecs::Light2D.enabled (EHT expected 61)");
static_assert(offsetof(esengine::ecs::Mesh2D, texture) == 0, "ABI offset drift: esengine::ecs::Mesh2D.texture (EHT expected 0)");
static_assert(offsetof(esengine::ecs::Mesh2D, normalMap) == 4, "ABI offset drift: esengine::ecs::Mesh2D.normalMap (EHT expected 4)");
static_assert(offsetof(esengine::ecs::Mesh2D, color) == 8, "ABI offset drift: esengine::ecs::Mesh2D.color (EHT expected 8)");
@@ -3019,7 +3024,7 @@ static_assert(offsetof(esengine::ecs::Velocity, angular) == 12, "ABI offset drif
// ABI Hash -- runtime handshake against the SDK bundle
// =============================================================================
-static const char* kEsAbiLayoutHash = "e868cc33a27b61d4";
+static const char* kEsAbiLayoutHash = "4f073fe384c59476";
std::string esengineGetAbiLayoutHash() {
return std::string(kEsAbiLayoutHash);
diff --git a/src/esengine/ecs/components/Light2D.hpp b/src/esengine/ecs/components/Light2D.hpp
index 88a4b4370..f184e9ffd 100644
--- a/src/esengine/ecs/components/Light2D.hpp
+++ b/src/esengine/ecs/components/Light2D.hpp
@@ -85,6 +85,14 @@ struct Light2D {
ES_PROPERTY(animatable, min=0, tooltip="Shadow softness (light-source size); 0 = hard edge.")
f32 shadowSoftness{0.0f};
+ /** @brief How wide a Directional light's source is, as the angle it subtends — the full
+ * angular diameter in degrees, 0.53 being the real sun's. A length cannot say it:
+ * the source is infinitely far away, so only an angle carries a penumbra. 0 is a
+ * hard edge (default); ignored by the types that have a position and a size. */
+ ES_PROPERTY(animatable, min=0, max=90, unit="°", advanced,
+ tooltip="Angular size of a Directional light's source; 0 = hard edge (sun ~0.53).")
+ f32 sourceAngle{0.0f};
+
/** @brief Directional-light shadow reach in world units: how far back toward the light a
* fragment searches for an occluder. 0 = a Directional light casts no shadow (default).
* Ignored by Point/Spot, which shadow along the segment to the light position. */
diff --git a/src/esengine/renderer/frame/RenderFrame.cpp b/src/esengine/renderer/frame/RenderFrame.cpp
index 6f805a928..e5f910896 100644
--- a/src/esengine/renderer/frame/RenderFrame.cpp
+++ b/src/esengine/renderer/frame/RenderFrame.cpp
@@ -720,6 +720,11 @@ void RenderFrame::collectLights(ecs::Registry& registry) {
// that slot on their falloff radius.
const glm::vec3 aim = lightForward(registry.tryGet<ecs::Transform>(entity));
gpu.posDir = glm::vec4(aim.x, aim.y, 1.0f, aim.z);
+ // A source infinitely far away has no half-extent a map can divide by a
+ // distance, so what it carries is the angle it subtends — as its tangent,
+ // which is what the penumbra is made of either way.
+ gpu.shadowMap.z = std::tan(glm::radians(
+ std::clamp(light.sourceAngle, 0.0f, 179.0f) * 0.5f));
// One sun: a second set of cascades would claim the atlas a first one is
// already spending, and two suns is not a scene anybody authors.
if (light.meshShadows && !haveSun) {
diff --git a/src/esengine/renderer/store/LightConstants.hpp b/src/esengine/renderer/store/LightConstants.hpp
index 85721281c..d1ca48c94 100644
--- a/src/esengine/renderer/store/LightConstants.hpp
+++ b/src/esengine/renderer/store/LightConstants.hpp
@@ -98,8 +98,11 @@ struct GpuLight2D {
glm::vec4 color{0.0f};
glm::vec4 spot{0.0f};
glm::vec4 shadow{0.0f};
- /// x = this light's first tile in the shadow atlas, y = how many it owns; zw unused.
+ /// x = this light's first tile in the shadow atlas, y = how many it owns; w unused.
/// y = 0 is a light with no map, which is every light that did not ask for one.
+ /// z = how wide its source is where its own map cannot measure a distance to divide
+ /// by: the tangent of the angle it subtends, which is what a directional light has
+ /// instead of a half-extent. Zero for a light that stands somewhere.
glm::vec4 shadowMap{0.0f};
};
diff --git a/src/esengine/renderer/store/LightStore.hpp b/src/esengine/renderer/store/LightStore.hpp
index b5719674a..1ce4e5bf5 100644
--- a/src/esengine/renderer/store/LightStore.hpp
+++ b/src/esengine/renderer/store/LightStore.hpp
@@ -87,8 +87,10 @@ public:
/// the zeroed count, which is a light with no map.
void setLightShadowTiles(u32 slot, u32 first, u32 tiles) {
if (slot >= count_) return;
- data_.lights[slot].shadowMap = glm::vec4(static_cast<f32>(first),
- static_cast<f32>(tiles), 0.0f, 0.0f);
+ // The two the atlas decides, and nothing else: z is the light's own source size,
+ // written when it was collected and not this pass's to overwrite.
+ data_.lights[slot].shadowMap.x = static_cast<f32>(first);
+ data_.lights[slot].shadowMap.y = static_cast<f32>(tiles);
dirty_ = true;
}
diff --git a/src/esengine/resource/ShaderParser.cpp b/src/esengine/resource/ShaderParser.cpp
index 2c0677d7b..118a5fe70 100644
--- a/src/esengine/resource/ShaderParser.cpp
+++ b/src/esengine/resource/ShaderParser.cpp
@@ -771,9 +771,16 @@ 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));
+ // Turned over in v for the reason the tile's rect is: an offset in texture space
+ // follows the axis the texture is sampled along, and this backend's runs the other
+ // way. A spiral is not its own mirror, so without this the two average other points.
+ return radius * sqrt((f32(i) + 0.5) / f32(n)) * vec2f(cos(a), -sin(a));
}
-fn shadowFactor3D(worldPos : vec3f, N : vec3f, L : vec3f, softness : f32,
+// The widest disc the tap count below can average over: past it the samples sit further
+// apart than the texels they average, and a penumbra bands instead of blurring. It bounds
+// the search too — a blocker outside it cannot widen an edge that cannot be drawn wider.
+const kShadowDisc = 8.0;
+fn shadowFactor3D(worldPos : vec3f, N : vec3f, L : vec3f, source : vec2f,
first : i32, count : i32) -> f32 {
#ifndef ES_RECEIVE_SHADOW
return 1.0;
@@ -820,10 +827,13 @@ fn shadowFactor3D(worldPos : vec3f, N : vec3f, L : vec3f, softness : f32,
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;
- // 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) {
+ // How wide the source is in the unit this map measures depth in: world units
+ // where its w varies with position, so it has an eye to measure them from, and
+ // the tangent of the angle it subtends where its w is 1 everywhere.
+ let hasEye = length(vec3f(m[0].w, m[1].w, m[2].w)) > 0.5;
+ let src = select(source.y, source.x, hasEye);
+ // A source with no size throws one edge, and four taps are its whole cost.
+ if (src <= 0.0) {
var lit = 0.0;
for (var y = 0; y < 2; y++) {
for (var x = 0; x < 2; x++) {
@@ -833,31 +843,33 @@ fn shadowFactor3D(worldPos : vec3f, N : vec3f, L : vec3f, softness : f32,
}
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));
+ // What blocks this fragment, over the whole disc an edge can reach across — and
+ // against a depth that forgives that reach, since a tap r texels away lands r
+ // texels along the surface and a one-texel bias would call the slope a blocker.
+ let reach = shadowDepth(m, worldPos + L * stepFor(texel, slope, kShadowDisc));
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 at = clamp(at0 + diskTap(i, 8, kShadowDisc) * 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.
+ // How far the receiver stands beyond what blocks it, and how far from the light
+ // that blocker is. A is the length of the map's depth row, and each kind of map
+ // inverts its own with it: hyperbolic where it has an eye, linear where w is 1.
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 zb = 2.0 * (sum / hits) - 1.0;
+ var dbw = 1.0;
+ var span = (proj.z - zb) / max(A, 1e-9);
+ if (hasEye) {
+ dbw = lcp.w * (A - proj.z) / max(A - zb, 1e-6);
+ span = lcp.w - dbw;
+ }
+ // A source subtending src/dbw at the blocker throws that much penumbra across the
+ // span beyond it — which is why a shadow hardens as its caster nears what it
+ // falls on, and why a sun's angle and a lamp's size are the same expression.
+ let radius = clamp(src * span / max(dbw * texel, 1e-4), 0.5, kShadowDisc);
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.
@@ -1072,7 +1084,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, sh.x, i32(sm.x), i32(sm.y));
+ atten *= shadowFactor3D(worldPos, N, L, vec2f(sh.x, sm.z), i32(sm.x), i32(sm.y));
}
let ndotl = max(dot(N, L), 0.0);
let radiance = col.rgb * (col.a * ndotl * atten);
@@ -1440,6 +1452,10 @@ ShaderParser::AssembledStage ShaderParser::assembleStageEx(const ParsedShader& p
" return 1.0;\n"
"#endif\n"
"}\n"
+ // The widest disc the tap count below can average over: past it the samples
+ // sit further apart than the texels they average, and a penumbra bands rather
+ // than blurs. It bounds the search too, which can find no wider an edge.
+ "const highp float kShadowDisc = 8.0;\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"
@@ -1450,7 +1466,7 @@ ShaderParser::AssembledStage ShaderParser::assembleStageEx(const ParsedShader& p
// 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 highp float softness, in int first, in int count) {\n"
+ " in highp vec2 source, in int first, in int count) {\n"
"#ifndef ES_RECEIVE_SHADOW\n"
" return 1.0;\n"
"#else\n"
@@ -1494,11 +1510,13 @@ ShaderParser::AssembledStage ShaderParser::assembleStageEx(const ParsedShader& p
" 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"
- // 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"
+ // How wide the source is in the unit this map measures depth in: world units
+ // where its w varies with position, so it has an eye to measure them from, and
+ // the tangent of the angle it subtends where its w is 1 everywhere.
+ " bool hasEye = length(vec3(m[0][3], m[1][3], m[2][3])) > 0.5;\n"
+ " highp float src = hasEye ? source.x : source.y;\n"
+ // A source with no size throws one edge, and four taps are its whole cost.
+ " if (src <= 0.0) {\n"
" highp float lit = 0.0;\n"
" for (int y = 0; y < 2; ++y) {\n"
" for (int x = 0; x < 2; ++x) {\n"
@@ -1508,33 +1526,34 @@ ShaderParser::AssembledStage ShaderParser::assembleStageEx(const ParsedShader& p
" }\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"
+ // What blocks this fragment, over the whole disc an edge can reach across —
+ // against a depth that forgives that reach, since a tap r texels out lands r
+ // texels along the surface and a one-texel bias would call the slope one.
+ " highp float reach = shadowDepth(m, worldPos + L * stepFor(texel, slope, kShadowDisc));\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 vec2 at = clamp(at0 + diskTap(i, 8, kShadowDisc) * 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.
+ // How far the receiver stands beyond what blocks it, and how far from the
+ // light that blocker is. A is the length of the map's depth row, and each map
+ // inverts its own with it: hyperbolic where it has an eye, linear where w is 1.
" 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 zb = 2.0 * (sum / hits) - 1.0;\n"
+ " highp float dbw = 1.0;\n"
+ " highp float span = (proj.z - zb) / max(A, 1e-9);\n"
+ " if (hasEye) {\n"
+ " dbw = lc.w * (A - proj.z) / max(A - zb, 1e-6);\n"
+ " span = lc.w - dbw;\n"
+ " }\n"
+ // A source subtending src/dbw at the blocker throws that much penumbra across
+ // the span beyond it — which is why a shadow hardens as its caster nears what
+ // it falls on, and why a sun's angle and a lamp's size are one expression.
+ " highp float radius = clamp(src * span / max(dbw * texel, 1e-4),\n"
+ " 0.5, kShadowDisc);\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
@@ -1807,7 +1826,8 @@ 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, sh.x, int(sm.x), int(sm.y));\n"
+ " atten *= shadowFactor3D(worldPos, N, L, vec2(sh.x, sm.z),\n"
+ " 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 8d5779634..132baae02 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 SUN WITH A SIZE: its source is infinitely far away, so what it carries is an angle
+ // and not a length — the penumbra is tan(sourceAngle/2) times how far the caster stands
+ // above what it falls on. Its ramp sits one sample step along on the second backend.
+ { id: "sun-shadow", tier: "pr", webgpu: { ESTELLA_VERIFY_EXPECT: "[{\"x\":0.62,\"y\":0.5,\"rgb\":[0,0,0],\"tol\":20},{\"x\":0.66,\"y\":0.5,\"rgb\":[39,39,39],\"tol\":30},{\"x\":0.72,\"y\":0.5,\"rgb\":[186,186,186],\"tol\":30},{\"x\":0.85,\"y\":0.5,\"rgb\":[247,247,247],\"tol\":20}]" }, env: { ESTELLA_VERIFY_SCENE: "/scenes/sun-shadow.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.62,\"y\":0.5,\"rgb\":[0,0,0],\"tol\":20},{\"x\":0.66,\"y\":0.5,\"rgb\":[70,70,70],\"tol\":35},{\"x\":0.72,\"y\":0.5,\"rgb\":[209,209,209],\"tol\":25},{\"x\":0.85,\"y\":0.5,\"rgb\":[247,247,247],\"tol\":20}]" } },
+ // The same scene with the caster moved DOWN the sun's own ray: its shadow lands where it
+ // did and the edge sharpens by the ratio of the distances. Two of these four probes
+ // differ from the gate above by 70 and 38, which a fixed blur could not produce.
+ { id: "sun-shadow-contact", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/sun-shadow-contact.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.62,\"y\":0.5,\"rgb\":[0,0,0],\"tol\":20},{\"x\":0.66,\"y\":0.5,\"rgb\":[0,0,0],\"tol\":20},{\"x\":0.72,\"y\":0.5,\"rgb\":[247,247,247],\"tol\":25},{\"x\":0.85,\"y\":0.5,\"rgb\":[247,247,247],\"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.