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(shadow): the atlas records who it turned down, and why

esengineaa4e28a92581
diff --git a/src/esengine/renderer/frame/RenderFrame.cpp b/src/esengine/renderer/frame/RenderFrame.cpp
index dccaf7865..243fd3a8f 100644
--- a/src/esengine/renderer/frame/RenderFrame.cpp
+++ b/src/esengine/renderer/frame/RenderFrame.cpp
@@ -947,6 +947,7 @@ void RenderFrame::collectLights(ecs::Registry& registry) {
GpuLight gpu;
bool castsMeshShadow = false;
ShadowCaster caster;
+ caster.light = entity;
gpu.color = glm::vec4(rgb, light.intensity);
// shadow.x = penumbra softness (all types); shadow.y = directional march distance (only the
// directional branch of shadowFactor2D reads it; 0 keeps directional shadows off).
@@ -1209,22 +1210,39 @@ void RenderFrame::buildShadowPlan(ecs::Registry& registry) {
u32 count = 0;
};
std::vector<TilePlan> plan(shadow_casters_.size());
+ shadow_plan_.clear();
+ shadow_plan_.atlasSize = kShadowAtlasSize;
+ shadow_plan_.cellSize = kShadowCellSize;
for (usize i = 0; i < shadow_casters_.size(); ++i) {
- const ShadowShape shape = shadow_casters_[i].shape;
- if (shape == ShadowShape::Box) continue;
- const u32 want = shape == ShadowShape::Cube ? SHADOW_CUBE_FACES : 1;
- const i32 at = shadow_atlas_.allocate(want, 1);
- if (at >= 0) plan[i] = {static_cast<u32>(at), want};
+ const ShadowCaster& caster = shadow_casters_[i];
+ if (caster.shape == ShadowShape::Box) continue;
+ const u32 want = caster.shape == ShadowShape::Cube ? SHADOW_CUBE_FACES : 1;
+ i32 at = -1;
+ const ShadowGrant grant = claimTiles(shadow_atlas_, caster.light, want, 1, at);
+ if (at >= 0) plan[i] = {static_cast<u32>(at), grant.granted};
+ shadow_plan_.grants.push_back(grant);
}
for (usize i = 0; i < shadow_casters_.size(); ++i) {
const ShadowCaster& caster = shadow_casters_[i];
if (caster.shape != ShadowShape::Box) continue;
// A fixed reach is the author saying what the map covers; splitting it would
// hand the rest of the atlas to slices they never asked for.
- u32 want = (perspective && caster.extent <= 0.0f) ? MAX_SHADOW_CASCADES : 1;
- for (; want > 0; --want) {
- const i32 at = shadow_atlas_.allocate(want, kShadowCascadeCells);
- if (at >= 0) { plan[i] = {static_cast<u32>(at), want}; break; }
+ const u32 want = (perspective && caster.extent <= 0.0f) ? MAX_SHADOW_CASCADES : 1;
+ i32 at = -1;
+ const ShadowGrant grant = claimTiles(shadow_atlas_, caster.light, want,
+ kShadowCascadeCells, at);
+ if (at >= 0) plan[i] = {static_cast<u32>(at), grant.granted};
+ shadow_plan_.grants.push_back(grant);
+ }
+ for (const ShadowGrant& g : shadow_plan_.grants) {
+ shadow_plan_.requestedTiles += g.requested;
+ shadow_plan_.grantedTiles += g.granted;
+ // 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()) {
+ ES_LOG_WARN("shadow atlas: light {} asked for {} tile(s) and got none ({})",
+ g.light.raw, g.requested, refusalName(g.refusal));
}
}
@@ -1353,6 +1371,11 @@ void RenderFrame::buildShadowPlan(ecs::Registry& registry) {
}
ES_PROFILE_COUNTER("render.shadow.collects", static_cast<u32>(shadow_views_.size()));
+ // Asked for BESIDE handed out: the two being equal is the only reading under
+ // which "16 tiles" says the frame got what it wanted.
+ ES_PROFILE_COUNTER("render.shadow.requested", shadow_plan_.requestedTiles);
+ ES_PROFILE_COUNTER("render.shadow.denied", shadow_plan_.deniedCasters());
+ ES_PROFILE_COUNTER("render.shadow.reduced", shadow_plan_.reducedCasters());
if (!anyTile) return;
// Borrowed, not held for the run: 2048² with depth is ~32MB. External because
diff --git a/src/esengine/renderer/frame/RenderFrame.hpp b/src/esengine/renderer/frame/RenderFrame.hpp
index 98398025c..1e9146e06 100644
--- a/src/esengine/renderer/frame/RenderFrame.hpp
+++ b/src/esengine/renderer/frame/RenderFrame.hpp
@@ -8,6 +8,7 @@
#include "./RenderContext.hpp"
#include "../store/LightConstants.hpp"
#include "../store/ShadowAtlas.hpp"
+#include "../store/ShadowPlan.hpp"
#include "../graph/TargetPool.hpp"
#include "../graph/RenderGraph.hpp"
#include "../RenderTypePlugin.hpp"
@@ -310,6 +311,14 @@ public:
/** @brief How many (view, entity) pairs are held up for inspection. */
usize lodPreviewCount() const { return lod_view_state_.previewCount(); }
+ /**
+ * @brief What each caster asked the shadow atlas for last frame, and what it got.
+ *
+ * @details The answer to "why does this object have no shadow", which the engine
+ * could not give at all: tiles handed out were counted, refusals were not.
+ */
+ const ShadowPlanReport& shadowPlan() const { return shadow_plan_; }
+
/**
* @brief Switch the frame to linear-light rendering (project colorSpace).
* @details Sets the global ES_LINEAR shader input, linearizes CPU-side
@@ -597,6 +606,9 @@ private:
*/
struct ShadowCaster {
u32 slot = 0;
+ /// The light that asked. Carried for the same reason `slot` is — the cap sort
+ /// reorders these, and a refusal has to be able to name who was refused.
+ Entity light{};
ShadowShape shape = ShadowShape::Box;
/// Which way it points — the aim, not the direction light travels. A cube aims
/// six ways of its own and reads none of it.
@@ -676,6 +688,7 @@ private:
/// Who owns which square of the atlas. Rebuilt every frame: a tile means
/// nothing once the depths in it belong to a frame that is gone.
ShadowAtlas shadow_atlas_{kShadowAtlasSize, kShadowCellSize};
+ ShadowPlanReport shadow_plan_;
/// The map's colour texture, handed to every mesh that receives it. 0 = none this frame.
u32 shadow_texture_id_ = 0;
/// The frame environment's reflection atlas, on the same terms. 0 = none this frame.
diff --git a/src/esengine/renderer/store/ShadowAtlas.hpp b/src/esengine/renderer/store/ShadowAtlas.hpp
index 44bef358f..fa617b360 100644
--- a/src/esengine/renderer/store/ShadowAtlas.hpp
+++ b/src/esengine/renderer/store/ShadowAtlas.hpp
@@ -22,6 +22,31 @@
namespace esengine {
+/**
+ * @brief Why a claim was turned down. Three different answers on purpose: raising
+ * the atlas size fixes @ref NoSpace and neither of the others.
+ */
+enum class AtlasRefusal : u8 {
+ None = 0,
+ /// More tiles than the shader's arrays are sized for (@ref MAX_SHADOW_TILES).
+ TileBudget,
+ /// One tile is wider than the whole atlas — the request cannot fit at any size.
+ TooLarge,
+ /// The atlas has no free block that size left. The one raising the size fixes.
+ NoSpace,
+};
+
+/** @brief The refusal as a word, for a log line and, later, for a reader. */
+inline const char* refusalName(AtlasRefusal why) {
+ switch (why) {
+ case AtlasRefusal::TileBudget: return "tile budget";
+ case AtlasRefusal::TooLarge: return "tile larger than the atlas";
+ case AtlasRefusal::NoSpace: return "atlas full";
+ case AtlasRefusal::None: break;
+ }
+ return "none";
+}
+
/** @brief One tile's square, in atlas texels. */
struct ShadowTile {
u32 x = 0;
@@ -52,18 +77,32 @@ public:
/**
* @brief Claims @p count tiles of @p cells x @p cells cells each.
+ * @param why Set to the reason on a refusal, @ref AtlasRefusal::None otherwise.
* @return The first tile's index, or -1 when the atlas or the tile budget has no
* room for all of them — all or nothing, so a caller never renders half a
* cascade set and leaves the rest reading someone else's depths.
+ *
+ * @details The reason is an OUT PARAMETER rather than something a caller may ask
+ * for: every refusal here is a light that silently stops casting, and a
+ * signature nobody had to read is how that went unrecorded for as long
+ * as it did.
*/
- i32 allocate(u32 count, u32 cells) {
- if (count == 0 || cells == 0 || cells > cols_) return -1;
- if (tiles_.size() + count > MAX_SHADOW_TILES) return -1;
+ i32 allocate(u32 count, u32 cells, AtlasRefusal& why) {
+ why = AtlasRefusal::None;
+ if (count == 0 || cells == 0 || cells > cols_) {
+ why = AtlasRefusal::TooLarge;
+ return -1;
+ }
+ if (tiles_.size() + count > MAX_SHADOW_TILES) {
+ why = AtlasRefusal::TileBudget;
+ return -1;
+ }
const usize before = tiles_.size();
for (u32 i = 0; i < count; ++i) {
if (!claim(cells)) {
tiles_.resize(before);
rebuildUsed();
+ why = AtlasRefusal::NoSpace;
return -1;
}
}
diff --git a/src/esengine/renderer/store/ShadowPlan.hpp b/src/esengine/renderer/store/ShadowPlan.hpp
new file mode 100644
index 000000000..ab7b31779
--- /dev/null
+++ b/src/esengine/renderer/store/ShadowPlan.hpp
@@ -0,0 +1,99 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file ShadowPlan.hpp
+ * @brief What each caster asked the shadow atlas for, and what it got.
+ *
+ * @details A caster the atlas could not fit kept no tiles and cast nothing, and
+ * the frame counted the tiles it DID hand out. So "why does this object
+ * have no shadow" had no answer anywhere in the engine — not a missing
+ * panel, a missing fact.
+ *
+ * Header-only and free of the renderer, like LodSelection.hpp: the
+ * giving-way rule is the part worth holding to a criterion, and it
+ * needs no device to be wrong.
+ */
+#pragma once
+
+#include "../../core/Types.hpp"
+#include "./ShadowAtlas.hpp"
+
+#include <vector>
+
+namespace esengine {
+
+/**
+ * @brief One caster's claim on the atlas: what it wanted, what it kept, and why
+ * the difference.
+ *
+ * @details `granted < requested` with no refusal is impossible — something gave
+ * way and the reason is the whole point of recording this.
+ */
+struct ShadowGrant {
+ /// The light that asked. Carried so a reader can name it rather than an index.
+ Entity light{};
+ /// Tiles asked for: a sun's cascade set, a cube's six faces, or one.
+ u32 requested = 0;
+ /// Tiles kept. 0 means this light casts no shadow at all this frame.
+ u32 granted = 0;
+ /// Why it did not get what it asked for, from the FIRST attempt that failed —
+ /// which is the answer to "why not what I asked", not "why not one less".
+ AtlasRefusal refusal = AtlasRefusal::None;
+
+ bool denied() const { return granted == 0; }
+ bool reduced() const { return granted > 0 && granted < requested; }
+};
+
+/** @brief The frame's whole shadow allocation, as numbers something outside it can check. */
+struct ShadowPlanReport {
+ u32 atlasSize = 0;
+ u32 cellSize = 0;
+ u32 requestedTiles = 0;
+ u32 grantedTiles = 0;
+ std::vector<ShadowGrant> grants;
+
+ void clear() {
+ requestedTiles = 0;
+ grantedTiles = 0;
+ grants.clear();
+ }
+
+ u32 deniedCasters() const {
+ u32 n = 0;
+ for (const ShadowGrant& g : grants) n += g.denied() ? 1u : 0u;
+ return n;
+ }
+
+ u32 reducedCasters() const {
+ u32 n = 0;
+ for (const ShadowGrant& g : grants) n += g.reduced() ? 1u : 0u;
+ return n;
+ }
+};
+
+/**
+ * @brief Claim as much of @p want as the atlas will give, down to one tile.
+ *
+ * @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.
+ */
+inline ShadowGrant claimTiles(ShadowAtlas& atlas, Entity light, u32 want, u32 cells,
+ i32& outFirst) {
+ ShadowGrant grant{light, want, 0, AtlasRefusal::None};
+ outFirst = -1;
+ for (u32 take = want; take > 0; --take) {
+ AtlasRefusal why = AtlasRefusal::None;
+ const i32 at = atlas.allocate(take, cells, why);
+ if (at >= 0) {
+ outFirst = at;
+ grant.granted = take;
+ return grant;
+ }
+ // The first refusal is the one that answers the question a reader has.
+ if (take == want) grant.refusal = why;
+ }
+ return grant;
+}
+
+} // namespace esengine
diff --git a/tests/renderer/test_shadow_atlas.cpp b/tests/renderer/test_shadow_atlas.cpp
index e501caeaf..6e824952b 100644
--- a/tests/renderer/test_shadow_atlas.cpp
+++ b/tests/renderer/test_shadow_atlas.cpp
@@ -3,6 +3,7 @@
// rect — but only the tiles its own fragments land in. The arithmetic is pinned here.
#include "esengine/renderer/store/ShadowAtlas.hpp"
+#include "esengine/renderer/store/ShadowPlan.hpp"
#include <cstdio>
#include <cmath>
@@ -27,10 +28,11 @@ static bool isRect(const glm::vec4& r, f32 x, f32 y, f32 size) {
}
int main() {
+ AtlasRefusal why = AtlasRefusal::None;
// The frame's own atlas: 2048 handed out in 512 cells, a cascade taking 2x2.
ShadowAtlas atlas(2048, 512);
- const i32 first = atlas.allocate(4, 2);
+ const i32 first = atlas.allocate(4, 2, why);
CHECK(first == 0, "the first claim starts at tile 0");
CHECK(atlas.tileCount() == 4, "four cascades claim four tiles");
@@ -50,21 +52,21 @@ int main() {
// A full atlas has nothing left, and says so rather than handing out a square
// somebody else is already drawing into.
- CHECK(atlas.allocate(1, 2) < 0, "a full atlas refuses the next claim");
+ CHECK(atlas.allocate(1, 2, why) < 0, "a full atlas refuses the next claim");
// All or nothing: a caller that gets half a cascade set would leave the rest
// reading depths that belong to another light.
ShadowAtlas partial(2048, 512);
- CHECK(partial.allocate(3, 2) == 0, "three of the four fit");
- CHECK(partial.allocate(2, 2) < 0, "two more do not, and the claim is refused");
+ CHECK(partial.allocate(3, 2, why) == 0, "three of the four fit");
+ CHECK(partial.allocate(2, 2, why) < 0, "two more do not, and the claim is refused");
CHECK(partial.tileCount() == 3, "a refused claim leaves the atlas as it was");
- CHECK(partial.allocate(1, 2) == 3, "and the one that does fit still can");
+ CHECK(partial.allocate(1, 2, why) == 3, "and the one that does fit still can");
// Tiles need not all be one size — which is the whole reason the rect is data.
// A spot light taking one cell sits beside a cascade taking four.
ShadowAtlas mixed(2048, 512);
- CHECK(mixed.allocate(1, 2) == 0, "a 2x2 block lands first");
- const i32 small = mixed.allocate(2, 1);
+ CHECK(mixed.allocate(1, 2, why) == 0, "a 2x2 block lands first");
+ const i32 small = mixed.allocate(2, 1, why);
CHECK(small == 1, "single cells claim after it");
CHECK(isTile(mixed.tile(1), 1024, 0, 512), "the first single cell clears the block");
CHECK(isRect(mixed.unitRect(1), 0.5f, 0.0f, 0.25f), "and reports a quarter-side rect");
@@ -73,37 +75,92 @@ int main() {
// order the faces are rendered — which is what lets a light name a first tile and a
// count rather than six indices.
ShadowAtlas cube(2048, 512);
- CHECK(cube.allocate(SHADOW_CUBE_FACES, 1) == 0, "a cube claims its six faces at once");
+ CHECK(cube.allocate(SHADOW_CUBE_FACES, 1, why) == 0, "a cube claims its six faces at once");
CHECK(cube.tileCount() == 6, "and gets all six");
CHECK(isTile(cube.tile(0), 0, 0, 512), "face 0 takes the first cell");
CHECK(isTile(cube.tile(5), 512, 512, 512), "face 5 the sixth, the row filled in order");
// What a sun standing beside it can still have: the cube left a row half used, and a
// 2x2 block only starts on a multiple of 2 — so the sun loses cascades, not its map.
- CHECK(cube.allocate(4, 2) < 0, "four cascades no longer fit beside a cube");
- CHECK(cube.allocate(2, 2) == 6, "two do, in the rows the cube did not reach");
+ CHECK(cube.allocate(4, 2, why) < 0, "four cascades no longer fit beside a cube");
+ CHECK(cube.allocate(2, 2, why) == 6, "two do, in the rows the cube did not reach");
CHECK(isTile(cube.tile(6), 0, 1024, 1024), "the first of them clearing the cube's rows");
// The budget is the shader's array bound, not the texture's room: a 4096 atlas
// of 512 cells has 64 of them and the block still stops at MAX_SHADOW_TILES.
ShadowAtlas wide(4096, 512);
- CHECK(wide.allocate(MAX_SHADOW_TILES + 1, 1) < 0, "the tile budget is a hard bound");
- CHECK(wide.allocate(MAX_SHADOW_TILES, 1) == 0, "and exactly the bound fits");
+ CHECK(wide.allocate(MAX_SHADOW_TILES + 1, 1, why) < 0, "the tile budget is a hard bound");
+ CHECK(wide.allocate(MAX_SHADOW_TILES, 1, why) == 0, "and exactly the bound fits");
// A frame gives it all back: a tile means nothing once the depths in it are
// from a frame that is gone.
ShadowAtlas reused(2048, 512);
- reused.allocate(4, 2);
+ reused.allocate(4, 2, why);
reused.reset();
CHECK(reused.tileCount() == 0, "reset empties the atlas");
- CHECK(reused.allocate(4, 2) == 0, "and the next frame claims the same squares");
+ CHECK(reused.allocate(4, 2, why) == 0, "and the next frame claims the same squares");
CHECK(isTile(reused.tile(0), 0, 0, 1024), "starting again at the lower-left");
// A block larger than the grid has nowhere to go, and a zero-sized claim is not
// a claim — both answer rather than indexing something that is not there.
ShadowAtlas small2(1024, 512);
- CHECK(small2.allocate(1, 4) < 0, "a block wider than the atlas is refused");
- CHECK(small2.allocate(0, 2) < 0, "so is a claim for no tiles");
- CHECK(small2.allocate(1, 0) < 0, "so is a claim for empty ones");
+ CHECK(small2.allocate(1, 4, why) < 0, "a block wider than the atlas is refused");
+ CHECK(small2.allocate(0, 2, why) < 0, "so is a claim for no tiles");
+ CHECK(small2.allocate(1, 0, why) < 0, "so is a claim for empty ones");
+
+ // Each refusal is a DIFFERENT answer, and only one of them is fixed by a bigger
+ // atlas. Folded into one "no room" they would send a reader to raise a size that
+ // was never the limit.
+ ShadowAtlas reasons(2048, 512);
+ reasons.allocate(1, 8, why);
+ CHECK(why == AtlasRefusal::TooLarge, "a block wider than the atlas says so");
+ reasons.allocate(MAX_SHADOW_TILES + 1, 1, why);
+ CHECK(why == AtlasRefusal::TileBudget, "past the shader's array bound says budget");
+ ShadowAtlas filled(1024, 512);
+ filled.allocate(4, 1, why);
+ CHECK(why == AtlasRefusal::None, "a claim that fits refuses nothing");
+ filled.allocate(1, 1, why);
+ CHECK(why == AtlasRefusal::NoSpace, "and the one after it is out of room, not out of budget");
+
+ // Giving way, and what it gives way FROM. A sun asks for a cascade set and takes
+ // fewer rather than costing a positional light its map — which is correct, and was
+ // indistinguishable from casting nothing.
+ ShadowAtlas contended(2048, 512);
+ 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);
+ 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");
+ CHECK(sun.refusal == AtlasRefusal::NoSpace,
+ "and the reason is the FIRST attempt's, not the last one that happened to work");
+
+ // A smaller atlas is the case a reader hits first, and the one they can act on.
+ ShadowAtlas cramped(1024, 512);
+ i32 none = -1;
+ claimTiles(cramped, Entity::make(3, 1), 4, 1, none);
+ const ShadowGrant denied = claimTiles(cramped, Entity::make(4, 1), 1, 1, none);
+ CHECK(denied.denied() && none < 0, "a caster the atlas cannot fit keeps nothing");
+ CHECK(denied.refusal == AtlasRefusal::NoSpace, "and says the atlas was full");
+ CHECK(denied.granted == 0 && denied.requested == 1, "recording both halves of the claim");
+
+ // 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;
+ ShadowAtlas counted(2048, 512);
+ for (u32 i = 0; i < 3; ++i) {
+ i32 first = -1;
+ report.grants.push_back(claimTiles(counted, Entity::make(i + 10, 1), 2, 2, first));
+ }
+ for (const ShadowGrant& g : report.grants) {
+ report.requestedTiles += g.requested;
+ report.grantedTiles += g.granted;
+ }
+ CHECK(report.grantedTiles == counted.tileCount(),
+ "the tiles the report says were granted are the tiles the atlas holds");
+ CHECK(report.requestedTiles == 6, "and what was asked for is counted apart from it");
+ CHECK(report.deniedCasters() + report.reducedCasters() > 0,
+ "three two-tile claims do not all fit in four cells, and the report says which");
std::printf(g_failures ? "\n%d check(s) failed\n" : "\nall checks passed\n", g_failures);
return g_failures == 0 ? 0 : 1;
diff --git a/tools/check-shadow-plan.mjs b/tools/check-shadow-plan.mjs
new file mode 100644
index 000000000..2769f6a81
--- /dev/null
+++ b/tools/check-shadow-plan.mjs
@@ -0,0 +1,71 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file check-shadow-plan.mjs — a caster the shadow atlas turns down is recorded.
+ *
+ * A light the atlas could not fit kept no tiles and cast nothing. The frame
+ * counted the tiles it handed OUT, so "why does this object have no shadow" had
+ * no answer anywhere in the engine — while the light cap two hundred lines up in
+ * the same file logged every light it dropped.
+ *
+ * What test_shadow_atlas proves about the giving-way rule, this holds about the
+ * wiring: the recording path is the ONLY way to claim a tile, the reason is kept,
+ * and a denial still reaches a reader. Each is a line somebody could delete
+ * without a pixel moving.
+ */
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const FRAME = 'src/esengine/renderer/frame/RenderFrame.cpp';
+const PLAN = 'src/esengine/renderer/store/ShadowPlan.hpp';
+
+const read = (rel) => readFileSync(path.join(ROOT, rel), 'utf8');
+const problems = [];
+const frame = read(FRAME);
+const plan = read(PLAN);
+
+// 1. One door. `claimTiles` is the only thing that writes a grant, so a claim made
+// around it is a caster that can be refused with nothing recording it — which is
+// the state this whole file exists to have left.
+const direct = [...frame.matchAll(/shadow_atlas_\.allocate\(/g)].length;
+if (direct > 0) {
+ problems.push(`${FRAME} claims atlas tiles directly (${direct} site(s)) instead of through`
+ + ' claimTiles — a claim that does not go through the recording path is a light that can'
+ + ' stop casting with nothing to say why');
+}
+if (!/claimTiles\(/.test(frame)) {
+ problems.push(`${FRAME} never calls claimTiles — nothing is recording what the atlas refused`);
+}
+
+// 2. The reason, kept. Which of the three refusals happened decides what a reader
+// would do about it: only one of them is fixed by a bigger atlas.
+if (!/grant\.refusal = why/.test(plan)) {
+ problems.push(`${PLAN} no longer keeps the refusal — a denial becomes a fact with no cause,`
+ + ' and "atlas full" stops being distinguishable from "tile budget"');
+}
+if (!/if \(take == want\)/.test(plan)) {
+ problems.push(`${PLAN} no longer takes the FIRST attempt's refusal — the reason a caster did`
+ + ' not get what it ASKED for is not the reason one tile fewer also failed');
+}
+
+// 3. It reaches somebody. A record nothing reports is the same silence in a struct.
+if (!/ES_LOG_WARN\("shadow atlas/.test(frame)) {
+ problems.push(`${FRAME} no longer warns on a denied caster — the light cap in this same file`
+ + ' warns, and these are the same contention over the same frame');
+}
+for (const counter of ['render.shadow.denied', 'render.shadow.requested']) {
+ if (!frame.includes(counter)) {
+ problems.push(`${FRAME} no longer reports ${counter} — tiles handed out without tiles asked`
+ + ' for is a number that cannot be read as a shortfall');
+ }
+}
+
+if (problems.length) {
+ console.error(`check-shadow-plan: ${problems.length} problem(s)`);
+ for (const p of problems) console.error(` - ${p}`);
+ process.exit(1);
+}
+console.log('check-shadow-plan: every atlas claim goes through the recording path, the refusal is'
+ + ' kept, and a denied caster is both warned and counted.');
diff --git a/tools/gates.mjs b/tools/gates.mjs
index 439f47466..e02b6edbc 100644
--- a/tools/gates.mjs
+++ b/tools/gates.mjs
@@ -186,6 +186,7 @@ export const GATES = [
{ id: 'import-settings', run: 'node tools/check-import-settings.mjs' },
{ id: 'gizmo-coverage', run: 'node tools/check-gizmo-coverage.mjs', needs: 'editor' },
{ id: 'lod-authoring', run: 'node tools/check-lod-authoring.mjs', needs: 'editor' },
+ { id: 'shadow-plan', run: 'node tools/check-shadow-plan.mjs' },
{ id: 'decision-inventory', run: 'node tools/check-decision-inventory.mjs', needs: 'editor' },
{ id: 'mutator-parity', run: 'node tools/check-mutator-parity.mjs', needs: 'editor' },
{ id: 'dirty-source', run: 'node tools/check-dirty-source.mjs', needs: 'editor' },
diff --git a/tools/lib/runtimeDecisions.mjs b/tools/lib/runtimeDecisions.mjs
index d07a73b9e..22fdef75d 100644
--- a/tools/lib/runtimeDecisions.mjs
+++ b/tools/lib/runtimeDecisions.mjs
@@ -75,14 +75,13 @@ export const DECISIONS = [
id: 'shadow.atlasAllocation',
what: 'Which casters get shadow tiles, how many cascades the sun keeps, and who is denied.',
kind: 'contended-resource',
- owner: { path: 'src/esengine/renderer/frame/RenderFrame.cpp', probe: /shadow_atlas_\.allocate\(want, kShadowCascadeCells\)/ },
- runtime: {
+ owner: { path: 'src/esengine/renderer/store/ShadowPlan.hpp', probe: /inline ShadowGrant claimTiles/ },
+ runtime: { has: true, cite: { path: 'src/esengine/renderer/store/ShadowPlan.hpp', probe: /grant\.refusal = why/ } },
+ editor: {
has: false,
- owed: 'a caster the atlas cannot fit keeps plan[i].count == 0 and casts nothing. Tiles and draws '
- + 'are counted; DENIALS are not, and no log names the light. The light cap two hundred lines '
- + 'up warns — this one is silent, in the same file',
+ owed: 'the frame now records who was refused and why (ShadowPlanReport, render.shadow.denied), '
+ + 'and nothing reads it — a light stops casting and the viewport still gives no reason',
},
- editor: { has: false, owed: 'a light stops casting and the viewport gives no reason' },
agent: { has: false, owed: 'nothing to read' },
},
{