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.

fix(render): allocate complete point shadows and report new denials

yhh93badd5c2e47
diff --git a/docs/astro/src/content/docs/graphics/lighting.mdx b/docs/astro/src/content/docs/graphics/lighting.mdx
index 4e829ed1e..4a9ee0d9f 100644
--- a/docs/astro/src/content/docs/graphics/lighting.mdx
+++ b/docs/astro/src/content/docs/graphics/lighting.mdx
@@ -338,8 +338,8 @@ coefficients are zero, and the same expression is the flat term again.
A `ShadowCaster2D` box (below) shadows in the XY plane, which is what a 2D scene means
by a shadow. Geometry with height needs the other kind: turn on **`meshShadows`** on a
-`Directional` light and the frame renders the scene's meshes once from that light, so a
-mesh standing above another darkens it.
+`Directional`, `Spot`, or `Point` light. The frame renders mesh depth from that
+light's views, so geometry blocks the light reaching other surfaces.
```typescript
cmds.spawn()
@@ -350,7 +350,11 @@ cmds.spawn()
});
```
-- One light per frame casts a map — the first that asks for one.
+- One directional light can cast alongside point and spot lights. They share an
+ atlas and a sixteen-tile limit: a spot needs one tile, a point needs all six
+ cube faces, and a directional light can use several cascades. A point that
+ cannot fit all six faces receives none; cascades may be reduced. Atlas space
+ is a separate limit because a directional tile occupies a larger block.
- Only `MeshRenderer` geometry the GPU holds casts and receives. Sprites are lit by the same
light but shadow through `ShadowCaster2D`, which is the 2D answer.
- Coverage follows the camera. `shadowExtent` fixes it instead, to one map of that radius
@@ -358,8 +362,10 @@ cmds.spawn()
`castShadows: false` and it does not pull the map away from what stands in front of it.
<Aside type="caution">
- A shadow map is a second pass over the scene's meshes. It costs a draw call per
- caster and is off until a light asks, so a scene that wants none pays nothing.
+ Each shadow view renders the meshes that cast into it. A point light needs six
+ views; use a spot for a fixture that illuminates a cone. The Light Status in
+ the editor reports granted tiles and the reason for a shortfall. New denials
+ also produce a warning; an unchanged denial is not logged every frame.
</Aside>
## Casting shadows
diff --git a/docs/astro/src/content/docs/zh-cn/graphics/lighting.mdx b/docs/astro/src/content/docs/zh-cn/graphics/lighting.mdx
index 2acb370b4..4f7009f67 100644
--- a/docs/astro/src/content/docs/zh-cn/graphics/lighting.mdx
+++ b/docs/astro/src/content/docs/zh-cn/graphics/lighting.mdx
@@ -311,8 +311,8 @@ cmds.spawn().insert(Light, {
## mesh 之间的阴影
`ShadowCaster2D` 的方块(见下)在 XY 平面上投影,那是 2D 场景所说的阴影。有高度的几何
-需要另一种:给一盏 `Directional` 灯打开 **`meshShadows`**,引擎每帧会从那盏灯的方向把场景的
-mesh 再画一遍,于是站得高的 mesh 会让下面的暗下来。
+需要另一种:给 `Directional`、`Spot` 或 `Point` 灯打开 **`meshShadows`**,引擎从灯的各个
+投影视角绘制网格深度,让几何遮挡照向其他表面的光。
```typescript
cmds.spawn()
@@ -323,14 +323,17 @@ cmds.spawn()
});
```
-- 每帧只有一盏灯投出这张图 —— 第一盏要求它的。
+- 一盏方向光可以和点光、聚光灯同时投影,共享图集和十六块阴影图的上限。聚光灯需要一块,
+ 点光需要完整的六个立方体面,方向光可以使用多个级联。点光放不下完整六面时不分配;
+ 方向光可以减少级联。图集空间是另一个限制,因为方向光的每块图占用更大的区域。
- 只有 GPU 持有的 `MeshRenderer` 几何参与投射与接收。精灵被同一盏灯照亮,但它们的阴影走
`ShadowCaster2D`,那才是 2D 的答案。
- 覆盖范围跟着相机走。`shadowExtent` 把它固定成一张该半径的图,覆盖投射阴影的网格,用锐度换范围。给远处的背景设 `castShadows: false`,它就不会把这张图从前景拉走。
<Aside type="caution">
- 阴影贴图是对场景 mesh 的第二遍绘制,每个投射者一次 draw call。没有灯要求它时它根本不跑,
- 所以不需要阴影的场景一分钱不付。
+ 每个阴影视角都需要绘制参与投影的网格,点光需要六个视角。只向一个锥形区域照射的灯具应使用
+ 聚光灯。编辑器的灯光状态会显示分配到的块数和不足原因;新的分配失败也会产生警告,
+ 同一失败不会每帧重复输出。
</Aside>
## 投射阴影
diff --git a/src/esengine/renderer/frame/RenderFrame.cpp b/src/esengine/renderer/frame/RenderFrame.cpp
index 76c3cd7f5..031b6b89a 100644
--- a/src/esengine/renderer/frame/RenderFrame.cpp
+++ b/src/esengine/renderer/frame/RenderFrame.cpp
@@ -2088,6 +2088,10 @@ void RenderFrame::buildShadowPlan(ecs::Registry& registry) {
// Zeroed first, and the atlas given back: a tile that outlived its map would
// shadow the scene against geometry from a frame that no longer exists.
shadow_atlas_.reset();
+ std::swap(shadow_plan_, previous_shadow_plan_);
+ shadow_plan_.clear();
+ shadow_plan_.atlasSize = shadow_atlas_size_;
+ shadow_plan_.cellSize = shadow_cell_size_;
context_.lights().setShadowTiles(nullptr, nullptr, 0, glm::vec4(0.0f));
if (!in_frame_ || shadow_casters_.empty() || !device_.isDeviceUsable()) return;
@@ -2154,9 +2158,6 @@ void RenderFrame::buildShadowPlan(ecs::Registry& registry) {
u32 count = 0;
};
std::vector<TilePlan> plan(shadow_casters_.size());
- shadow_plan_.clear();
- shadow_plan_.atlasSize = shadow_atlas_size_;
- shadow_plan_.cellSize = shadow_cell_size_;
for (usize i = 0; i < shadow_casters_.size(); ++i) {
const ShadowCaster& caster = shadow_casters_[i];
if (caster.shape == ShadowShape::Box) continue;
@@ -2175,7 +2176,7 @@ void RenderFrame::buildShadowPlan(ecs::Registry& registry) {
const u32 want = (perspective && caster.extent <= 0.0f) ? shadow_cascades_ + (focus ? 1u : 0u) : 1;
i32 at = -1;
const ShadowGrant grant = claimTiles(shadow_atlas_, caster.light, want,
- kShadowCascadeCells, at);
+ kShadowCascadeCells, at, ShadowClaim::AllowFewer);
if (at >= 0) plan[i] = {static_cast<u32>(at), grant.granted};
shadow_plan_.grants.push_back(grant);
}
@@ -2185,7 +2186,9 @@ void RenderFrame::buildShadowPlan(ecs::Registry& registry) {
// The light cap two hundred lines up warns when it drops a light. This is the
// same contention over the same frame and said nothing at all, which is how a
// light that stopped casting became a question with no answer in the engine.
- if (g.denied()) {
+ // Keep the live report every frame, but only log a new denial. A stable
+ // over-budget scene must not spend every frame formatting the same warning.
+ if (g.denied() && !previous_shadow_plan_.hasSameDenial(g)) {
ES_LOG_WARN("shadow atlas: light {} asked for {} tile(s) and got none ({})",
g.light.raw, g.requested, refusalName(g.refusal));
}
diff --git a/src/esengine/renderer/frame/RenderFrame.hpp b/src/esengine/renderer/frame/RenderFrame.hpp
index caf6f5280..02577483a 100644
--- a/src/esengine/renderer/frame/RenderFrame.hpp
+++ b/src/esengine/renderer/frame/RenderFrame.hpp
@@ -1100,6 +1100,7 @@ private:
f32 shadow_distance_ = 0.0f;
u32 shadow_2d_soft_samples_ = 16;
ShadowPlanReport shadow_plan_;
+ ShadowPlanReport previous_shadow_plan_;
LightCapReport light_cap_;
ViewLighting view_lighting_;
bool scene_sky_available_ = false;
diff --git a/src/esengine/renderer/store/ShadowPlan.hpp b/src/esengine/renderer/store/ShadowPlan.hpp
index edf20f4d0..0317cb3a1 100644
--- a/src/esengine/renderer/store/ShadowPlan.hpp
+++ b/src/esengine/renderer/store/ShadowPlan.hpp
@@ -72,6 +72,13 @@ struct ShadowPlanReport {
return nullptr;
}
+ /** @brief Whether this report already contains the same denied claim. */
+ bool hasSameDenial(const ShadowGrant& claim) const {
+ const ShadowGrant* previous = grantFor(claim.light);
+ return claim.denied() && previous && previous->denied()
+ && previous->requested == claim.requested && previous->refusal == claim.refusal;
+ }
+
u32 reducedCasters() const {
u32 n = 0;
for (const ShadowGrant& g : grants) n += g.reduced() ? 1u : 0u;
@@ -79,15 +86,22 @@ struct ShadowPlanReport {
}
};
+enum class ShadowClaim : u8 {
+ AllOrNothing,
+ AllowFewer,
+};
+
/**
- * @brief Claim as much of @p want as the atlas will give, down to one tile.
+ * @brief Claim a complete shadow map, or explicitly allow fewer cascades.
*
* @details A sun settles for fewer rather than costing a positional light the map
* it cannot shorten. Giving way and RECORDING what it gave way from are
* one function, so a caller cannot take the first without the second.
+ * A point light needs all six faces: a partial cube leaves directions
+ * unshadowed and consumes tiles that another complete map could use.
*/
inline ShadowGrant claimTiles(ShadowAtlas& atlas, Entity light, u32 want, u32 cells,
- i32& outFirst) {
+ i32& outFirst, ShadowClaim policy = ShadowClaim::AllOrNothing) {
ShadowGrant grant{light, want, 0, AtlasRefusal::None};
outFirst = -1;
for (u32 take = want; take > 0; --take) {
@@ -100,6 +114,7 @@ inline ShadowGrant claimTiles(ShadowAtlas& atlas, Entity light, u32 want, u32 ce
}
// The first refusal is the one that answers the question a reader has.
if (take == want) grant.refusal = why;
+ if (policy == ShadowClaim::AllOrNothing) break;
}
return grant;
}
diff --git a/tests/renderer/test_shadow_atlas.cpp b/tests/renderer/test_shadow_atlas.cpp
index 6e824952b..592c5e4c1 100644
--- a/tests/renderer/test_shadow_atlas.cpp
+++ b/tests/renderer/test_shadow_atlas.cpp
@@ -128,7 +128,8 @@ int main() {
i32 at = -1;
const ShadowGrant cubeGrant = claimTiles(contended, Entity::make(1, 1), SHADOW_CUBE_FACES, 1, at);
CHECK(cubeGrant.granted == SHADOW_CUBE_FACES && at == 0, "the cube claims first and whole");
- const ShadowGrant sun = claimTiles(contended, Entity::make(2, 1), MAX_SHADOW_CASCADES, 2, at);
+ const ShadowGrant sun = claimTiles(contended, Entity::make(2, 1), MAX_SHADOW_CASCADES, 2, at,
+ ShadowClaim::AllowFewer);
CHECK(sun.requested == MAX_SHADOW_CASCADES, "the sun asked for a whole cascade set");
CHECK(sun.granted > 0 && sun.granted < sun.requested, "and settled for fewer");
CHECK(sun.reduced() && !sun.denied(), "which is a reduction, not a denial");
@@ -144,6 +145,47 @@ int main() {
CHECK(denied.refusal == AtlasRefusal::NoSpace, "and says the atlas was full");
CHECK(denied.granted == 0 && denied.requested == 1, "recording both halves of the claim");
+ // Three point lights in a sixteen-tile budget must never leave the third
+ // with four cube faces. The refused claim leaves room for the sun instead.
+ for (const u32 size : {2048u, 4096u}) {
+ ShadowAtlas points(size, 512);
+ claimTiles(points, Entity::make(20, 1), SHADOW_CUBE_FACES, 1, at);
+ claimTiles(points, Entity::make(21, 1), SHADOW_CUBE_FACES, 1, at);
+ const ShadowGrant third = claimTiles(points, Entity::make(22, 1), SHADOW_CUBE_FACES, 1, at);
+ CHECK(third.denied() && at < 0, "a point shadow cannot keep an incomplete cube");
+ CHECK(third.refusal == AtlasRefusal::TileBudget, "a larger atlas does not bypass the tile limit");
+ CHECK(points.tileCount() == 12, "a refused cube consumes no tiles");
+ const ShadowGrant moon = claimTiles(points, Entity::make(23, 1), 1, 2, at);
+ if (size == 4096) {
+ CHECK(moon.granted == 1 && at == 12, "a free 2x2 block holds a complete sun map");
+ } else {
+ CHECK(moon.denied() && moon.refusal == AtlasRefusal::NoSpace,
+ "a single free row cannot fit a 2x2 sun map");
+ const ShadowGrant spot = claimTiles(points, Entity::make(25, 1), 1, 1, at);
+ CHECK(spot.granted == 1 && at == 12, "the free row still holds a complete spot map");
+ }
+ }
+ ShadowAtlas tooSmallForCube(1024, 512);
+ const ShadowGrant noCube = claimTiles(tooSmallForCube, Entity::make(24, 1), SHADOW_CUBE_FACES, 1, at);
+ CHECK(noCube.denied() && noCube.refusal == AtlasRefusal::NoSpace,
+ "four free cells still cannot hold a six-face point shadow");
+ CHECK(tooSmallForCube.tileCount() == 0, "a spatial refusal also rolls back every cube face");
+
+ ShadowPlanReport previous;
+ previous.grants.push_back(denied);
+ CHECK(previous.hasSameDenial(denied), "an unchanged denied light does not need another warning");
+ ShadowGrant changed = denied;
+ changed.refusal = AtlasRefusal::TileBudget;
+ CHECK(!previous.hasSameDenial(changed), "a different refusal needs a new warning");
+ changed = denied; changed.requested++;
+ CHECK(!previous.hasSameDenial(changed), "a changed claim needs a new warning");
+ changed = denied; changed.light = Entity::make(4, 2);
+ CHECK(!previous.hasSameDenial(changed), "a reused entity slot is a new light");
+ previous.grants[0].granted = 1;
+ CHECK(!previous.hasSameDenial(denied), "a recovered light can warn if it loses its map again");
+ previous.clear();
+ CHECK(!previous.hasSameDenial(denied), "a light returning after an empty frame can warn again");
+
// The report's own arithmetic: what a frame says it handed out is what the atlas
// actually holds. A grant nobody claimed would make every later number a guess.
ShadowPlanReport report;