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.

refactor(render): the shadow atlas is filled by a graph pass, not during collect

esengine9bd6567a28fa
diff --git a/src/esengine/renderer/RenderTypePlugin.hpp b/src/esengine/renderer/RenderTypePlugin.hpp
index 5aa98a4c9..90467e747 100644
--- a/src/esengine/renderer/RenderTypePlugin.hpp
+++ b/src/esengine/renderer/RenderTypePlugin.hpp
@@ -27,6 +27,19 @@ class RenderContext;
class MaterialStore;
class RenderFrame;
+/**
+ * @brief What a collect is FOR — the phase, not a feature the geometry has.
+ *
+ * @details A shadow collect draws the scene's meshes from somewhere else for a
+ * different answer: depth only, no material, no light. A bool per phase
+ * would multiply as the frame gains passes, and two could be set at
+ * once — which no phase ever is.
+ */
+enum class RenderPurpose : u8 {
+ Scene,
+ ShadowDepth,
+};
+
struct RenderFrameContext {
RenderContext& render_context;
resource::ResourceManager& resources;
@@ -37,9 +50,9 @@ struct RenderFrameContext {
const MaterialStore* materials = nullptr;
/// The owning frame, for lazily-compiled batch variants (RenderFrame::batchProgram).
RenderFrame* frame = nullptr;
- /// This collect is the shadow pass: geometry draws depth-only, from the light.
- /// Set by the frame, which also skips every plugin that casts nothing.
- bool shadow_pass = false;
+ /// What this collect is for. The frame sets it, and also skips every plugin
+ /// that casts nothing when the purpose is a shadow map.
+ RenderPurpose purpose = RenderPurpose::Scene;
/// The map that pass produced, handed to the meshes that receive it (0 = none).
u32 shadow_texture_id = 0;
/// The frame environment's prefiltered reflection atlas (0 = none this frame).
diff --git a/src/esengine/renderer/frame/RenderFrame.cpp b/src/esengine/renderer/frame/RenderFrame.cpp
index dbabcf5f9..7fbda5d02 100644
--- a/src/esengine/renderer/frame/RenderFrame.cpp
+++ b/src/esengine/renderer/frame/RenderFrame.cpp
@@ -121,7 +121,8 @@ RenderFrame::RenderFrame(GfxDevice& device, RenderContext& context,
, resource_manager_(resource_manager)
, pool_(device)
, target_pool_(device)
- , graph_(device, target_pool_) {
+ , graph_(device, target_pool_)
+ , shadow_pool_(device) {
target_manager_.setDevice(device);
}
@@ -152,6 +153,7 @@ void RenderFrame::init(u32 width, u32 height) {
#endif
pool_.init();
+ shadow_pool_.init();
batch_shader_id_ = initBatchShader();
RenderFrameContext initCtx{
@@ -175,6 +177,7 @@ void RenderFrame::shutdown() {
}
plugins_.clear();
pool_.shutdown();
+ shadow_pool_.shutdown();
releaseFrameTargets();
target_pool_.clear();
@@ -190,6 +193,7 @@ void RenderFrame::shutdown() {
void RenderFrame::recreateGpuResources() {
pool_.recreateGpuResources();
+ shadow_pool_.recreateGpuResources();
target_manager_.recreateGpuResources();
// The framebuffers the pool is holding died with the device: the loans go
// back and the memory behind them goes with it, or the next frame would draw
@@ -252,20 +256,17 @@ void RenderFrame::drawScene() {
device_.setScissorTest(false);
}
-// Every target this frame borrowed, given back. Three callers owe it: the end
-// of a frame, a device loss, and shutdown.
+// The atlas texture this frame published, unpublished — the target behind it is
+// the graph's loan. Owed by a new frame, a device loss and shutdown, because the
+// id the receiving draws were keyed by names nothing once its device is gone.
void RenderFrame::releaseFrameTargets() {
- if (shadow_target_ != rg::kNoTarget) {
- target_pool_.release(shadow_target_);
- shadow_target_ = rg::kNoTarget;
- }
shadow_texture_id_ = 0;
}
void RenderFrame::beginFrame() {
- // Here and not at end(), which runs once per CAMERA: the atlas is borrowed
- // once, spans every camera that reads it, and goes back before the next
- // frame. Then one tick of the clock, by the frame that owns the pool.
+ // Here and not at end(), which runs once per CAMERA: every camera plans and
+ // renders its own maps, and the pool hands the same physical atlas to each in
+ // turn. Then one tick of the clock, by the frame that owns the pool.
releaseFrameTargets();
target_pool_.age();
@@ -497,6 +498,12 @@ void RenderFrame::end() {
scene.viewportY = static_cast<u32>(std::max(scene_viewport_.y, 0));
scene.viewportW = scene_viewport_.w;
scene.viewportH = scene_viewport_.h;
+ // Named, not read: every draw that receives a shadow carries the atlas in
+ // its own key, so the graph owes the scene ordering and lifetime but must
+ // not spend a texture unit on it.
+ if (shadow_resource_ != rg::kNoResource) {
+ scene.dependencies.push_back(shadow_resource_);
+ }
scene.execute = [this](const rg::PassContext&) { drawScene(); };
graph_.addPass(std::move(scene));
}
@@ -516,6 +523,8 @@ void RenderFrame::end() {
FrameProfiler::get().gpuScope("graph", gpu_timer_.lastMs());
}
scene_resource_ = rg::kNoResource;
+ shadow_resource_ = rg::kNoResource;
+ shadow_views_.clear();
if (usePostProcess) {
#ifdef ES_ENABLE_POSTPROCESS
@@ -732,7 +741,7 @@ RenderFrameContext RenderFrame::makeContext() {
view_projection_,
&context_.materials(),
this,
- false,
+ RenderPurpose::Scene,
shadow_texture_id_,
environment_texture_id_
};
@@ -1007,33 +1016,16 @@ static glm::vec3 cubeFace(u32 index) {
return dir;
}
-void RenderFrame::renderShadowMap(ecs::Registry& registry) {
+void RenderFrame::buildShadowPlan(ecs::Registry& registry) {
shadow_texture_id_ = 0;
+ shadow_resource_ = rg::kNoResource;
+ shadow_views_.clear();
// 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();
context_.lights().setShadowTiles(nullptr, nullptr, 0, glm::vec4(0.0f));
if (!in_frame_ || shadow_casters_.empty() || !device_.isDeviceUsable()) return;
- // Borrowed for the frame rather than created once and held for the run:
- // 2048² with depth is ~32MB, and a game that walks out of its one shadowed
- // room should stop paying for it. Given back at the next beginFrame.
-
- // A resize reclaims every target at the old size and a device loss frees
- // the lot, so this handle can outlive what it named. It comes back stale
- // rather than naming whatever refilled the slot, and re-borrows here.
- if (!target_pool_.holds(shadow_target_)) shadow_target_ = rg::kNoTarget;
- if (shadow_target_ == rg::kNoTarget) {
- rg::TargetShape shape;
- shape.width = kShadowAtlasSize;
- shape.height = kShadowAtlasSize;
- shape.depthStencil = true;
- shape.linearFilter = false;
- shadow_target_ = target_pool_.acquire(shape);
- }
- const FramebufferHandle shadowFbo = target_pool_.framebufferOf(shadow_target_);
- if (shadowFbo == FramebufferHandle::Default) return;
-
const glm::mat4 invVP = glm::inverse(view_projection_);
// Clip's z axis back in world: w != 0 is an eye point, w == 0 says the projection
// is orthographic and there is none. Cascades only pay off under perspective —
@@ -1084,24 +1076,15 @@ void RenderFrame::renderShadowMap(ecs::Registry& registry) {
}
}
- const glm::mat4 sceneVP = view_projection_;
- const GfxDevice::Viewport sceneViewport = device_.viewport();
glm::mat4 matrices[MAX_SHADOW_TILES];
glm::vec4 tiles[MAX_SHADOW_TILES];
- bool cleared = false;
bool anyTile = false;
- // What the pass cost, for a profiler and the gates that pin it: the maps it
- // actually rendered and the draws they took. Neither shows in a pixel, and a
- // face that stopped being skipped would look exactly like one that never was.
- u32 shadowTiles = 0;
- u32 shadowDraws = 0;
- u32 shadowCollects = 0;
for (usize ci = 0; ci < shadow_casters_.size(); ++ci) {
const ShadowCaster& caster = shadow_casters_[ci];
const TilePlan mine = plan[ci];
if (mine.count == 0) continue;
- u32 drawnTiles = 0;
+ u32 plannedTiles = 0;
for (u32 c = 0; c < mine.count; ++c) {
const u32 tileIndex = mine.first + c;
@@ -1127,7 +1110,7 @@ void RenderFrame::renderShadowMap(ecs::Registry& registry) {
if (mine.count == 1) {
// What the map covers: the 3D geometry, unless the light asked for a
// fixed reach. A radius, so coverage does not change as the light turns.
- const CameraView view = computeCameraView(sceneVP);
+ const CameraView view = computeCameraView(view_projection_);
const f32 fitted = haveBounds
? 0.5f * glm::length(boundsMax - boundsMin)
: 0.5f * glm::length(glm::vec2(view.right - view.left,
@@ -1193,101 +1176,135 @@ void RenderFrame::renderShadowMap(ecs::Registry& registry) {
// is derived there out of this matrix and the size of the square.
tiles[tileIndex] = shadow_atlas_.unitRect(tileIndex);
- view_projection_ = projection;
- frustum_.extractFromMatrix(projection);
// A face whose frustum misses the whole of the geometry gathers nothing, and
// asking each mesh in turn is the only way to find that out otherwise. The
// box every mesh is inside answers it once, for the price of one test.
- if (haveBounds && !frustum_.intersectsAABB((boundsMin + boundsMax) * 0.5f,
- (boundsMax - boundsMin) * 0.5f)) {
+ Frustum tileFrustum;
+ tileFrustum.extractFromMatrix(projection);
+ if (haveBounds && !tileFrustum.intersectsAABB((boundsMin + boundsMax) * 0.5f,
+ (boundsMax - boundsMin) * 0.5f)) {
continue;
}
- ++shadowCollects;
-
- // What the tile would hold, gathered before a pass is opened for it. Only
- // the plugins that cast are asked: a map holds depth, and everything else
- // would write colour into a texture every receiver reads back as one.
- pool_.beginFrame();
- draw_list_.clear();
-
- auto ctx = makeContext();
- ctx.shadow_pass = true;
- RenderCollectContext collectCtx{registry, frustum_, clip_state_, pool_, draw_list_,
- ctx, computeCameraView(projection)};
- for (auto& plugin : plugins_) {
- if (plugin->castsShadows()) plugin->collect(collectCtx);
- }
- draw_list_.finalize(pool_);
- // A cube face pointing away from every mesh collects nothing, and a point
- // light has six chances at that. The tile already holds what the atlas is
- // cleared to — depth 1, nothing here — so a pass for it would agree at cost.
- if (draw_list_.commandCount() == 0) continue;
-
- // A self-contained pass, in the shape renderToTarget uses: swap what the frame
- // looks through, draw, hand the target back. The first tile with anything in it
- // clears the atlas — white, which is depth 1 unpacked: nothing here.
- RenderPassDesc pass{shadowFbo, /*clearColor=*/!cleared};
- pass.clearDepth = !cleared;
- pass.clearColorValue[0] = pass.clearColorValue[1] = pass.clearColorValue[2] = 1.0f;
- pass.clearColorValue[3] = 1.0f;
- device_.beginRenderPass(pass);
- cleared = true;
- device_.setViewport(tile.x, tile.y, tile.size, tile.size);
- pool_.upload();
- // Not a camera's: this projection spans exactly the occluders it draws, so
- // it sits inside either clip volume as built, and the depths it writes are
- // compared against the copy of it the receiving shader holds.
- context_.updateFrameConstants(projection);
- // The depth variant is still a Lit shader and still declares the light block,
- // and a draw whose declared UBO is unbound is undefined behaviour that draws
- // nothing — the whole pass came back empty for exactly this.
- context_.lights().uploadAndBind();
- draw_list_.execute(device_, pool_, context_.materials(), context_.getWhiteTextureId(),
- nullptr, context_.skinUbo());
- ++drawnTiles;
- shadowDraws += draw_list_.mergedDrawCallCount();
+
+ shadow_views_.push_back(ShadowView{projection, tile.x, tile.y, tile.size});
+ ++plannedTiles;
}
- // A caster whose every tile came back empty has no map to read. Published
- // anyway, its range would cost each of the fragments it lights a fetch that
- // can only answer "nothing here".
- if (drawnTiles == 0) {
+ // A caster whose every tile was rejected has no map to read. Published anyway,
+ // its range would cost each of the fragments it lights a fetch that can only
+ // answer "nothing here".
+ if (plannedTiles == 0) {
plan[ci].count = 0;
} else {
- shadowTiles += drawnTiles;
anyTile = true;
}
}
- ES_PROFILE_COUNTER("render.shadow.tiles", shadowTiles);
- ES_PROFILE_COUNTER("render.shadow.draws", shadowDraws);
- ES_PROFILE_COUNTER("render.shadow.collects", shadowCollects);
+ ES_PROFILE_COUNTER("render.shadow.collects", static_cast<u32>(shadow_views_.size()));
+ if (!anyTile) return;
+
+ // Borrowed, not held for the run: 2048² with depth is ~32MB. External because
+ // the id has to exist NOW rather than when the pass runs — the atlas travels
+ // into the sort key of every draw that receives it, and the scene collects next.
+ rg::TargetDesc desc;
+ desc.width = kShadowAtlasSize;
+ desc.height = kShadowAtlasSize;
+ desc.depthStencil = true;
+ desc.linearFilter = false;
+ shadow_resource_ = graph_.createExternalTarget(desc);
+ if (shadow_resource_ == rg::kNoResource) {
+ shadow_views_.clear();
+ return;
+ }
- device_.endRenderPass();
- device_.invalidatePipelineCache();
+ shadow_texture_id_ = static_cast<u32>(graph_.textureOf(shadow_resource_));
+ context_.lights().setShadowTiles(
+ matrices, tiles, shadow_atlas_.tileCount(),
+ glm::vec4(1.0f, 1.0f / static_cast<f32>(kShadowAtlasSize), 0.0f, 0.0f));
+ // Which of them each light reads. Without it a fragment would test against
+ // every map in the atlas, including ones rendered from where it cannot see.
+ for (usize i = 0; i < shadow_casters_.size(); ++i) {
+ if (plan[i].count == 0) continue;
+ context_.lights().setLightShadowTiles(shadow_casters_[i].slot,
+ plan[i].first, plan[i].count);
+ }
+}
- if (anyTile) {
- shadow_texture_id_ = static_cast<u32>(target_pool_.textureOf(shadow_target_));
- context_.lights().setShadowTiles(
- matrices, tiles, shadow_atlas_.tileCount(),
- glm::vec4(1.0f, 1.0f / static_cast<f32>(kShadowAtlasSize), 0.0f, 0.0f));
- // Which of them each light reads. Without it a fragment would test against
- // every map in the atlas, including ones rendered from where it cannot see.
- for (usize i = 0; i < shadow_casters_.size(); ++i) {
- if (plan[i].count == 0) continue;
- context_.lights().setLightShadowTiles(shadow_casters_[i].slot,
- plan[i].first, plan[i].count);
+void RenderFrame::declareShadowPass(ecs::Registry& registry) {
+ if (shadow_resource_ == rg::kNoResource) return;
+
+ rg::PassDesc shadow;
+ shadow.name = "shadow-atlas";
+ shadow.write = shadow_resource_;
+ // One pass for every map the frame renders, because they share an attachment:
+ // a point light's six faces are six viewports inside this pass rather than six
+ // passes the device has to transition the atlas between.
+ shadow.clear = true;
+ shadow.clearDepth = true;
+ // White is depth 1 unpacked: nothing here. A square the plan kept but whose
+ // collect comes back empty reads as no occluder rather than as a black wall.
+ shadow.clearColor[0] = shadow.clearColor[1] = shadow.clearColor[2] = 1.0f;
+ shadow.clearColor[3] = 1.0f;
+ shadow.execute = [this, &registry](const rg::PassContext&) { executeShadowPass(registry); };
+ graph_.addPass(std::move(shadow));
+}
+
+void RenderFrame::executeShadowPass(ecs::Registry& registry) {
+ // What the pass cost, for a profiler and the gates that pin it: the maps it
+ // actually rendered and the draws they took. Neither shows in a pixel, and a
+ // face that stopped being skipped would look exactly like one that never was.
+ u32 shadowTiles = 0;
+ u32 shadowDraws = 0;
+
+ for (const ShadowView& view : shadow_views_) {
+ // Its own pool and list. The scene's are finalized and uploaded by now and
+ // its pass is still to come, so collecting through them here would overwrite
+ // the vertices the scene is about to draw from.
+ shadow_pool_.beginFrame();
+ shadow_draw_list_.clear();
+
+ // What this looks through is the view's, held here rather than swapped into
+ // the frame's own: the scene pass after this one still reads the camera it
+ // was given, so there is nothing to put back.
+ Frustum viewFrustum;
+ viewFrustum.extractFromMatrix(view.view_projection);
+ auto ctx = makeContext();
+ ctx.view_projection = view.view_projection;
+ ctx.purpose = RenderPurpose::ShadowDepth;
+ // Only the plugins that cast are asked: a map holds depth, and everything
+ // else would write colour into a texture every receiver reads back as one.
+ RenderCollectContext collectCtx{registry, viewFrustum, clip_state_, shadow_pool_,
+ shadow_draw_list_, ctx,
+ computeCameraView(view.view_projection)};
+ for (auto& plugin : plugins_) {
+ if (plugin->castsShadows()) plugin->collect(collectCtx);
}
+ shadow_draw_list_.finalize(shadow_pool_);
+ // A cube face pointing away from every mesh collects nothing, and a point
+ // light has six chances at that. The square already holds what the atlas was
+ // cleared to — depth 1, nothing here — so drawing it would agree at cost.
+ if (shadow_draw_list_.commandCount() == 0) continue;
+
+ device_.setViewport(view.x, view.y, view.size, view.size);
+ shadow_pool_.upload();
+ // Not a camera's: this projection spans exactly the occluders it draws, so
+ // it sits inside either clip volume as built, and the depths it writes are
+ // compared against the copy of it the receiving shader holds.
+ context_.updateFrameConstants(view.view_projection);
+ // The depth variant is still a Lit shader and still declares the light block,
+ // and a draw whose declared UBO is unbound is undefined behaviour that draws
+ // nothing — the whole pass came back empty for exactly this.
+ context_.lights().uploadAndBind();
+ shadow_draw_list_.execute(device_, shadow_pool_, context_.materials(),
+ context_.getWhiteTextureId(), nullptr, context_.skinUbo());
+ ++shadowTiles;
+ shadowDraws += shadow_draw_list_.mergedDrawCallCount();
}
- // Back to the frame's own target and camera. The scene has drawn nothing yet, so
- // re-opening the pass costs a load rather than the frame's contents.
- view_projection_ = sceneVP;
- frustum_.extractFromMatrix(sceneVP);
- pool_.beginFrame();
- draw_list_.clear();
- openPass(PassClear{}, current_target_);
- device_.setViewport(sceneViewport.x, sceneViewport.y, sceneViewport.w, sceneViewport.h);
+ ES_PROFILE_COUNTER("render.shadow.tiles", shadowTiles);
+ ES_PROFILE_COUNTER("render.shadow.draws", shadowDraws);
+ // The scene draws next, through pipelines nothing here matches.
+ device_.invalidatePipelineCache();
}
/**
@@ -1346,7 +1363,11 @@ void RenderFrame::collectAll(ecs::Registry& registry) {
ES_PROFILE_SCOPE("render.collect");
buildClipState();
collectLights(registry);
- renderShadowMap(registry);
+ // Decided here, drawn by the graph. Nothing in this function may touch the
+ // device: the frame reaches the host as several calls with its own draws
+ // between them, and a pass opened here would swallow them.
+ buildShadowPlan(registry);
+ declareShadowPass(registry);
auto ctx = makeContext();
diff --git a/src/esengine/renderer/frame/RenderFrame.hpp b/src/esengine/renderer/frame/RenderFrame.hpp
index 824a14f21..4269182ac 100644
--- a/src/esengine/renderer/frame/RenderFrame.hpp
+++ b/src/esengine/renderer/frame/RenderFrame.hpp
@@ -357,24 +357,37 @@ private:
/// @return false when it names none, leaving the caller to add a flat term.
bool collectEnvironment(const ecs::Light& light, const glm::vec3& scale);
/**
- * @brief Draws the scene's mesh occluders from the shadow-casting light, into a map
- * the main pass samples.
- * @details Runs at the top of collectAll and re-opens the frame's own target behind
- * itself. A no-op unless collectLights found a light asking for one. Every
- * map a frame renders shares one atlas texture, and who owns which square
- * of it is ShadowAtlas's answer rather than the light type's.
+ * @brief Decides what the shadow pass will draw, without drawing any of it.
+ *
+ * @details Runs in collectAll, where nothing may touch the GPU: it allocates
+ * the squares, builds each projection and drops the ones whose frustum
+ * misses the scene. The tiles are published before the scene collects,
+ * because the atlas id travels into every receiving draw's key.
+ */
+ void buildShadowPlan(ecs::Registry& registry);
+ /**
+ * @brief Declares the pass that fills the atlas, ahead of the scene that reads it.
+ *
+ * @details Ordering is the graph's to know, not a matter of this call coming
+ * first: the scene names the atlas, so the graph keeps this pass alive
+ * and runs it before the one that samples it. @p registry is captured
+ * for the collect the pass does, and outlives execute().
*/
- void renderShadowMap(ecs::Registry& registry);
+ void declareShadowPass(ecs::Registry& registry);
+ /// The shadow pass's body: for each planned square, collect the occluders it can
+ /// see and draw them. The graph has bound and cleared the atlas.
+ void executeShadowPass(ecs::Registry& registry);
/// The scene pass's body: the draw, and the constants it needs current.
void drawScene();
- /// Gives back every target this frame borrowed from {@link target_pool_}.
+ /// Drops the atlas texture id the frame published; its target is the graph's
+ /// to give back.
void releaseFrameTargets();
/// The world box the resident meshes occupy — what a shadow map must cover.
/// False when nothing 3D is in the scene.
bool meshWorldBounds(ecs::Registry& registry, glm::vec3& outMin, glm::vec3& outMax);
- /// Opens the frame's own target with @p clear's load-op. Shared by begin() and the
- /// shadow pass, which re-opens it after drawing through a target of its own.
+ /// Opens the frame's own target with @p clear's load-op, for begin() to bind it
+ /// eagerly. Every other pass of the frame is the graph's to open.
void openPass(const PassClear& clear, RenderTargetManager::Handle target);
u32 initBatchShader();
resource::ShaderHandle compileBatchVariant(const std::vector<std::string>& features);
@@ -412,7 +425,7 @@ private:
};
std::vector<CollectedLight> light_scratch_; // reused across frames; collectLights only
/// Every light that asked for a map this frame, in UBO slot order. Written by
- /// collectLights, read by renderShadowMap; empty = nobody asked.
+ /// collectLights, read by buildShadowPlan; empty = nobody asked.
std::vector<ShadowCaster> shadow_casters_;
/// The frame's render targets, borrowed by shape and given back when the
/// frame is done with them — shared with the post chains, which is what lets
@@ -430,10 +443,37 @@ private:
FramebufferHandle scene_fbo_ = FramebufferHandle::Default;
/// The camera's rect within its target; the scene pass carries it.
GfxDevice::Viewport scene_viewport_{};
- /// The atlas this frame borrowed, released at end(). kNoTarget = none.
- rg::TargetHandle shadow_target_ = rg::kNoTarget;
- /// Who owns which square of it. Rebuilt every frame: a tile means nothing once
- /// the depths in it belong to a frame that is gone.
+ /// The atlas as a graph resource: the shadow pass writes it and the scene names
+ /// it, which is what orders the two. Borrowed from the pool every other target
+ /// comes from. kNoResource = no map this frame.
+ rg::ResourceId shadow_resource_ = rg::kNoResource;
+ /**
+ * @brief One square of the atlas, and what fills it.
+ *
+ * @details Decided on the CPU: by the time the pass runs, where it draws and what
+ * it looks through are already answered, and all that is left is the draw.
+ */
+ struct ShadowView {
+ glm::mat4 view_projection{1.0f};
+ u32 x = 0;
+ u32 y = 0;
+ u32 size = 0;
+ };
+ /// What the pass will draw, in atlas order. Empty = nothing asked for a map, and
+ /// no pass is declared.
+ std::vector<ShadowView> shadow_views_;
+ /**
+ * @brief The shadow pass's own transient buffers and draw list.
+ *
+ * @details Not the scene's. By the time the graph runs the pass, flush() has
+ * finalized and uploaded the scene's list, and the scene pass is still to
+ * come — a shadow collect through the same pool would overwrite the
+ * vertices the scene is about to draw from.
+ */
+ TransientBufferPool shadow_pool_;
+ DrawList shadow_draw_list_;
+ /// 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};
/// The map's colour texture, handed to every mesh that receives it. 0 = none this frame.
u32 shadow_texture_id_ = 0;
diff --git a/src/esengine/renderer/plugins/MeshPlugin.cpp b/src/esengine/renderer/plugins/MeshPlugin.cpp
index 0b640c6c0..724aa3b4b 100644
--- a/src/esengine/renderer/plugins/MeshPlugin.cpp
+++ b/src/esengine/renderer/plugins/MeshPlugin.cpp
@@ -168,6 +168,8 @@ void MeshPlugin::collect(RenderCollectContext& collect_ctx) {
auto& draw_list = collect_ctx.draw_list;
auto& ctx = collect_ctx.frame_context;
auto meshView = registry.view<ecs::Transform, ecs::MeshRenderer>();
+ // Read once: the phase is the same for every mesh this collect walks.
+ const bool shadowDepth = ctx.purpose == RenderPurpose::ShadowDepth;
u32 litProgram = 0;
@@ -182,7 +184,7 @@ void MeshPlugin::collect(RenderCollectContext& collect_ctx) {
// scroll slower. A shadow pass looks from a light, whose centre means nothing to
// it, and its map is fitted to unshifted bounds: a caster stands where it is.
transform.ensureDecomposed();
- const glm::vec3 position = ctx.shadow_pass
+ const glm::vec3 position = shadowDepth
? transform.worldPosition
: parallaxedWorldPosition(transform, mesh.parallax, collect_ctx.camera);
const auto& rotation = transform.worldRotation;
@@ -195,7 +197,7 @@ void MeshPlugin::collect(RenderCollectContext& collect_ctx) {
// Only GPU-resident geometry casts: the inline payload takes the CPU path
// below, which bakes world space into vertices for the BATCH shader — a
// shader that writes colour, not the depth this pass is here to collect.
- if (ctx.shadow_pass && !resident) continue;
+ if (shadowDepth && !resident) continue;
const glm::vec3 localMin = resident ? resident->localMin : glm::vec3(mesh.localMin, 0.0f);
const glm::vec3 localMax = resident ? resident->localMax : glm::vec3(mesh.localMax, 0.0f);
@@ -263,7 +265,7 @@ void MeshPlugin::collect(RenderCollectContext& collect_ctx) {
// Casting into a shadow map: opaque and depth-tested whatever the camera's
// pass makes it, and none of the three ways to describe a surface — lit, a
// normal map, a material. LAST, so the pass outranks all three.
- if (ctx.shadow_pass) {
+ if (shadowDepth) {
key.stage = RenderStage::Opaque;
key.blend = BlendMode::None;
key.depthTest = true;
@@ -287,8 +289,8 @@ void MeshPlugin::collect(RenderCollectContext& collect_ctx) {
// with normals can be drawn unlit, and geometry without them takes
// light off the constant normal a 2D surface has.
const u32 residentShader =
- meshProgram(ctx, resident->hasNormals, mesh.lit && !ctx.shadow_pass,
- normalTextureId != 0 && !ctx.shadow_pass, skinned, ctx.shadow_pass,
+ meshProgram(ctx, resident->hasNormals, mesh.lit && !shadowDepth,
+ normalTextureId != 0 && !shadowDepth, skinned, shadowDepth,
key.envTextureId != 0);
if (resident->isDrawable() && residentShader != 0) {
const u32 stride = skinned ? MESH_INSTANCE_STRIDE_SKINNED
diff --git a/tools/check-shadow-pass.mjs b/tools/check-shadow-pass.mjs
new file mode 100644
index 000000000..7a2151684
--- /dev/null
+++ b/tools/check-shadow-pass.mjs
@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file check-shadow-pass.mjs — the shadow atlas is filled by a graph pass.
+ *
+ * Two shipped bugs came out of a fill that borrowed the frame's target, camera,
+ * draw list and buffer pool and then put them back by hand: a packaged game
+ * whose scene landed in the atlas, and a WebGPU frame rejected for sampling an
+ * attachment it was writing. Neither was a shadow-maths bug, so what is guarded
+ * here is the boundary rather than the picture:
+ *
+ * 1. Nothing reachable from collectAll() submits to the GPU. Work QUEUED for
+ * the graph is fine — a pass callback runs when the graph runs it — so
+ * lambda bodies are excluded from the walk.
+ * 2. openPass() has exactly one caller: begin(), which binds the frame's
+ * target eagerly. A second caller is a pass restoring state behind itself.
+ * 3. The scene declares the atlas, so the graph orders the two rather than
+ * the order the passes happen to be added in.
+ * 4. The shadow pass draws from its own pool and list and looks through its
+ * own camera. Reaching for the frame's is what makes a restore necessary.
+ *
+ * Run: node tools/check-shadow-pass.mjs (exit 1 on violation)
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+
+const FRAME = 'src/esengine/renderer/frame/RenderFrame.cpp';
+
+if (!existsSync(FRAME)) {
+ console.error(`Shadow-pass guard is stale: ${FRAME} does not exist.`);
+ process.exit(1);
+}
+/**
+ * Code only: the prose above names begin(), openPass() and beginRenderPass(),
+ * and describing the boundary must not read as crossing it.
+ */
+const stripComments = (text) =>
+ text.replace(/\/\*[\s\S]*?\*\//g, ' ').replace(/\/\/[^\n]*/g, '');
+
+const src = stripComments(readFileSync(FRAME, 'utf8'));
+
+/** Body text of every `RenderFrame::name(...) { ... }` in the file. */
+function methodBodies(text) {
+ const bodies = new Map();
+ const re = /\bRenderFrame::(\w+)\s*\([^;{]*?\)\s*(?:const\s*)?\{/g;
+ let m;
+ while ((m = re.exec(text))) {
+ let depth = 0;
+ let i = text.indexOf('{', m.index);
+ const start = i;
+ for (; i < text.length; i++) {
+ if (text[i] === '{') depth++;
+ else if (text[i] === '}' && --depth === 0) break;
+ }
+ bodies.set(m[1], text.slice(start + 1, i));
+ }
+ return bodies;
+}
+
+/**
+ * The body with every lambda body removed. What a callback does happens when
+ * whoever holds it runs it, so it is not part of the caller's own execution —
+ * declaring a graph pass is exactly this, and must not read as doing its work.
+ */
+function withoutLambdaBodies(body) {
+ let out = '';
+ for (let i = 0; i < body.length; i++) {
+ const rest = body.slice(i);
+ const intro = /^\[[^\]]*\]\s*(?:\([^)]*\)\s*)?(?:mutable\s*)?(?:->[^{]+)?\{/.exec(rest);
+ if (!intro) { out += body[i]; continue; }
+ let depth = 0;
+ let j = i + intro[0].length - 1;
+ for (; j < body.length; j++) {
+ if (body[j] === '{') depth++;
+ else if (body[j] === '}' && --depth === 0) break;
+ }
+ i = j;
+ }
+ return out;
+}
+
+const bodies = methodBodies(src);
+for (const required of ['collectAll', 'buildShadowPlan', 'declareShadowPass',
+ 'executeShadowPass', 'openPass', 'begin', 'end']) {
+ if (!bodies.has(required)) {
+ console.error(`Shadow-pass guard is stale: RenderFrame::${required} is gone. `
+ + 'If the pass was restructured, restate the invariant here rather than deleting it.');
+ process.exit(1);
+ }
+}
+
+const problems = [];
+
+// --- 1. collect queues work; it does not do it -------------------------------
+/**
+ * A call to a free/member function of this class BY NAME — not `v.begin()` or
+ * `p->end()`, which name a container's. Without the guard every std iterator
+ * walk in the file reads as a call to RenderFrame::begin.
+ */
+const callRe = (name) => new RegExp(`(?<![\\w:.])(?<!->)${name}\\s*\\(`);
+
+const GPU_CALLS = [
+ [/\bdevice_\s*\.\s*beginRenderPass\s*\(/, 'device_.beginRenderPass()'],
+ [/\bdevice_\s*\.\s*endRenderPass\s*\(/, 'device_.endRenderPass()'],
+ [callRe('openPass'), 'openPass()'],
+ // Opening a pass is not the only way to draw into one: a submission during
+ // collect lands in whatever begin() bound, which is the scene. So the
+ // boundary is the SUBMISSION, not the pass.
+ [/\b\w*draw_list_\s*\.\s*execute\s*\(/, 'a draw-list submission'],
+ [/\b\w*pool_\s*\.\s*upload\s*\(/, 'a transient-buffer upload'],
+ [/\bdevice_\s*\.\s*setViewport\s*\(/, 'device_.setViewport()'],
+];
+const reached = new Set();
+const walk = (name) => {
+ if (reached.has(name) || !bodies.has(name)) return;
+ reached.add(name);
+ const body = withoutLambdaBodies(bodies.get(name));
+ for (const [re, label] of GPU_CALLS) {
+ if (re.test(body)) {
+ problems.push(`collectAll reaches ${label} through RenderFrame::${name}() — `
+ + 'a pass opened during collect swallows the host draws that follow it. '
+ + 'Declare the work as a graph pass instead.');
+ }
+ }
+ for (const callee of bodies.keys()) {
+ if (callee === name) continue;
+ if (callRe(callee).test(body)) walk(callee);
+ }
+};
+walk('collectAll');
+
+// --- 2. one caller binds the frame's target; nothing restores it -------------
+const openPassCallers = [];
+for (const [name, body] of bodies) {
+ if (name === 'openPass') continue;
+ if (callRe('openPass').test(withoutLambdaBodies(body))) openPassCallers.push(name);
+}
+if (openPassCallers.join(',') !== 'begin') {
+ problems.push(`openPass() is called by [${openPassCallers.join(', ') || 'nobody'}] — `
+ + 'it may only be called by begin(), which binds the frame\'s target eagerly. '
+ + 'A second caller is a pass putting state back behind itself.');
+}
+
+// --- 3. the graph is told, not trusted to guess ------------------------------
+const declare = bodies.get('declareShadowPass');
+if (!/\bshadow\.write\s*=\s*shadow_resource_/.test(declare)) {
+ problems.push('the shadow pass does not declare shadow_resource_ as its write — '
+ + 'the graph cannot order or recycle a target nobody claims.');
+}
+if (!/dependencies\.push_back\(shadow_resource_\)/.test(bodies.get('end'))) {
+ problems.push('the scene pass does not name shadow_resource_ in its dependencies — '
+ + 'culling walks back from the final target, so the shadow pass would be dropped '
+ + 'entirely, and the order of the two would be an accident of addPass order.');
+}
+
+// --- 4. the pass brings its own buffers and its own camera -------------------
+const OWN_STATE = [
+ [/\bview_projection_\s*=/, "assigns the frame's view_projection_"],
+ [/\bfrustum_\s*\./, "reaches for the frame's frustum_"],
+ [/(?<![\w])pool_\s*\.\s*(?:beginFrame|upload)\s*\(/, "drives the scene's buffer pool"],
+ [/(?<![\w])draw_list_\s*\./, "drives the scene's draw list"],
+];
+for (const name of ['buildShadowPlan', 'executeShadowPass']) {
+ const body = withoutLambdaBodies(bodies.get(name));
+ for (const [re, what] of OWN_STATE) {
+ if (re.test(body)) {
+ problems.push(`RenderFrame::${name}() ${what} — the shadow pass runs between the `
+ + 'host\'s draws and the scene\'s, so borrowing either is what a restore then '
+ + 'has to undo. It has shadow_pool_, shadow_draw_list_ and its own frustum.');
+ }
+ }
+}
+
+if (problems.length) {
+ console.error('Shadow-pass boundary guard failed:\n');
+ for (const p of problems) console.error(` ✗ ${p}\n`);
+ process.exit(1);
+}
+console.log(`shadow-pass: collect reaches ${reached.size} method(s), none of them a render pass; `
+ + 'the atlas is declared and the scene names it.');
diff --git a/tools/gates.mjs b/tools/gates.mjs
index fca0a68be..4c3646a4b 100644
--- a/tools/gates.mjs
+++ b/tools/gates.mjs
@@ -35,6 +35,7 @@ export const GATES = [
{ id: 'tsc-compiler', run: 'pnpm --filter @estella/compiler exec tsc --noEmit -p tsconfig.json' },
{ id: 'gl-boundary', run: 'node tools/check-gl-boundary.mjs' },
{ id: 'draw-command-boundary', run: 'node tools/check-draw-command-boundary.mjs' },
+ { id: 'shadow-pass', run: 'node tools/check-shadow-pass.mjs' },
{ id: 'sidemodule-gates', run: 'node tools/check-sidemodule-gates.mjs' },
{ id: 'engine-exports', run: 'node tools/check-engine-exports.mjs' },
{ id: 'fixture-scenes', run: 'node tools/check-fixture-scenes.mjs' },