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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
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.mdxindex 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 meansby 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.```typescriptcmds.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 samelight 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 shadowsdiff --git a/docs/astro/src/content/docs/zh-cn/graphics/lighting.mdx b/docs/astro/src/content/docs/zh-cn/graphics/lighting.mdxindex 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`**,引擎从灯的各个+投影视角绘制网格深度,让几何遮挡照向其他表面的光。```typescriptcmds.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.cppindex 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.hppindex 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.hppindex 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.cppindex 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;