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
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.hppindex 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.cppindex 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) {#endifpool_.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, ®istry](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.hppindex 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.cppindex 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_SKINNEDdiff --git a/tools/check-shadow-pass.mjs b/tools/check-shadow-pass.mjsnew file mode 100644index 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.mjsindex 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' },