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 target pool belongs to the frame, not to one chain
yhh7b5f9cb2d62c
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex c42933d76..d1228786b 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -36,6 +36,38 @@ published separately; it ships inside the editor.- **`estella.mjs export --minify`**, for the targets whose default it is not.+- **The shadow atlas is a loan now, not a framebuffer held for the run.** It was+ created on the first frame that cast a shadow and never given back — 2048²+ with depth, ~32MB, for as long as the process lived, so a game that walked out+ of its one shadowed room went on paying for it. It comes out of the frame's+ target pool instead: borrowed once per frame, spanning every camera that reads+ it, returned before the next one, and released for good when nothing has asked+ for it in 120 frames.++ What made that possible is that **a `RenderGraph` is one CHAIN and a frame+ holds several** — one per camera, plus the screen stack — and the pool used to+ live inside the graph, so every `begin()` handed every target back and nothing+ could be held across two chains. The pool is its own object now+ (`rg::TargetPool`), owned by the frame and borrowed by each chain: the atlas+ and the post-process intermediates come out of the same physical targets, and+ a target's lifetime is the borrower's to state rather than a side effect of+ which chain began last. Its handles carry a generation, so one held across a+ resize (which reclaims every target at the old size) comes back naming nothing+ rather than naming whatever refilled its slot.++ `rg::TargetDesc` gained a `width`/`height` in pixels for targets that are not+ a fraction of the frame: an atlas is 2048² because that is what its tiling+ divides, and as a `scale` it would have been a different resource on every+ monitor.++- **`render.targets` and `render.targets.bytes`** — what a frame's render+ targets cost, which no counter answered for. `point-shadow` pins a shadowed+ frame at exactly one target and 33,554,432 bytes, and `shadow-scale-cost`+ holds 3249 casters to the same ceiling. Sabotage-checked: a frame stranding+ its atlas each frame reaches 3 targets and 96MB **with every pixel probe still+ passing** — target memory is invisible in the image, which is why it needed a+ number.+### Changed- `EmbeddedSideModuleEntry` carries decoded bytes (`glue`, `wasm`) rather thandiff --git a/cmake/ESEngineSources.cmake b/cmake/ESEngineSources.cmakeindex 5da82db81..2b9fcaaee 100644--- a/cmake/ESEngineSources.cmake+++ b/cmake/ESEngineSources.cmake@@ -18,6 +18,9 @@ set(ESENGINE_SOURCES${ESENGINE_ROOT}/src/esengine/renderer/rhi/Buffer.cpp${ESENGINE_ROOT}/src/esengine/renderer/rhi/Texture.cpp${ESENGINE_ROOT}/src/esengine/renderer/rhi/Framebuffer.cpp+ # Not behind ES_ENABLE_POSTPROCESS with RenderGraph: the frame borrows its+ # own targets from this pool whether or not a post stack is compiled in.+ ${ESENGINE_ROOT}/src/esengine/renderer/graph/TargetPool.cpp${ESENGINE_ROOT}/src/esengine/renderer/frame/RenderFrame.cpp${ESENGINE_ROOT}/src/esengine/renderer/frame/RenderFrameMask.cpp${ESENGINE_ROOT}/src/esengine/renderer/frame/RenderFrameSubmit.cppdiff --git a/src/esengine/renderer/frame/PostProcessPipeline.cpp b/src/esengine/renderer/frame/PostProcessPipeline.cppindex 4a01bd99e..8077d01a9 100644--- a/src/esengine/renderer/frame/PostProcessPipeline.cpp+++ b/src/esengine/renderer/frame/PostProcessPipeline.cpp@@ -27,6 +27,16 @@namespace esengine {+PostProcessPipeline::PostProcessPipeline(GfxDevice& device,+ RenderContext& context,+ resource::ResourceManager& resourceManager,+ rg::TargetPool& pool)+ : device_(device)+ , context_(context)+ , resourceManager_(resourceManager)+ , pool_(&pool) {+}+PostProcessPipeline::PostProcessPipeline(GfxDevice& device,RenderContext& context,resource::ResourceManager& resourceManager)@@ -102,7 +112,8 @@ GfxPixelFormat PostProcessPipeline::interFormat() const {void PostProcessPipeline::ensureGraph() {if (graph_) return;- graph_ = makeUnique<rg::RenderGraph>(device_);+ graph_ = pool_ ? makeUnique<rg::RenderGraph>(device_, *pool_)+ : makeUnique<rg::RenderGraph>(device_);if (linear_output_) {ES_LOG_INFO("PostProcess intermediates: {}",interFormat() == GfxPixelFormat::RGBA16F ? "RGBA16F (HDR)"diff --git a/src/esengine/renderer/frame/PostProcessPipeline.hpp b/src/esengine/renderer/frame/PostProcessPipeline.hppindex a5d031a23..7419a527d 100644--- a/src/esengine/renderer/frame/PostProcessPipeline.hpp+++ b/src/esengine/renderer/frame/PostProcessPipeline.hpp@@ -79,7 +79,25 @@ struct PostProcessPass {*/class PostProcessPipeline {public:- PostProcessPipeline(GfxDevice& device, RenderContext& context, resource::ResourceManager& resourceManager);+ /**+ * @brief Builds a pipeline whose chains draw from the frame's target pool.+ *+ * @details The pool is the FRAME's, not a chain's. Every camera's chain and+ * the screen stack borrow from the same physical targets, and so+ * does whatever the frame holds across them — the shadow atlas.+ */+ PostProcessPipeline(GfxDevice& device, RenderContext& context,+ resource::ResourceManager& resourceManager, rg::TargetPool& pool);++ /**+ * @brief Builds one with no frame behind it; its chains get a pool of their own.+ *+ * @details The fallback path in the bindings, for a pipeline that exists+ * without a RenderFrame having made one. Same terms as+ * {@link rg::RenderGraph}'s pool-owning constructor.+ */+ PostProcessPipeline(GfxDevice& device, RenderContext& context,+ resource::ResourceManager& resourceManager);~PostProcessPipeline();PostProcessPipeline(const PostProcessPipeline&) = delete;@@ -313,6 +331,8 @@ private:RenderContext& context_;resource::ResourceManager& resourceManager_;+ /// The frame's pool when one was given, null when the graph owns its own.+ rg::TargetPool* pool_ = nullptr;Unique<rg::RenderGraph> graph_;VertexLayoutHandle screen_quad_layout_ = VertexLayoutHandle::Invalid;BufferHandle screen_quad_vbo_ = BufferHandle::Invalid;diff --git a/src/esengine/renderer/frame/RenderFrame.cpp b/src/esengine/renderer/frame/RenderFrame.cppindex 77acf561b..cb056167e 100644--- a/src/esengine/renderer/frame/RenderFrame.cpp+++ b/src/esengine/renderer/frame/RenderFrame.cpp@@ -119,7 +119,8 @@ RenderFrame::RenderFrame(GfxDevice& device, RenderContext& context,: device_(device), context_(context), resource_manager_(resource_manager)- , pool_(device) {+ , pool_(device)+ , target_pool_(device) {target_manager_.setDevice(device);}@@ -139,7 +140,8 @@ void RenderFrame::init(u32 width, u32 height) {linear_color_ = resource::ShaderParser::linearColorSpace();#ifdef ES_ENABLE_POSTPROCESS- post_process_ = makeUnique<PostProcessPipeline>(device_, context_, resource_manager_);+ post_process_ = makeUnique<PostProcessPipeline>(device_, context_, resource_manager_,+ target_pool_);post_process_->setLinearOutput(linear_color_);// The requirement may have been declared before the pipeline existed (a depth// layer arrives with the project, init happens on the first frame) — and until@@ -172,6 +174,8 @@ void RenderFrame::shutdown() {}plugins_.clear();pool_.shutdown();+ releaseFrameTargets();+ target_pool_.clear();#ifdef ES_ENABLE_POSTPROCESSif (post_process_) {@@ -186,6 +190,11 @@ void RenderFrame::shutdown() {void RenderFrame::recreateGpuResources() {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+ // its shadows into a handle that names nothing. Re-borrowed on demand.+ releaseFrameTargets();+ target_pool_.clear();// The variant handles are unchanged; this re-reads the program ids behind them.batch_shader_id_ = initBatchShader();#ifdef ES_ENABLE_POSTPROCESS@@ -221,7 +230,23 @@ void RenderFrame::resize(u32 width, u32 height) {#endif}+// Every target this frame borrowed, given back. Three callers owe it: the end+// of a frame, a device loss, and shutdown.+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.+ releaseFrameTargets();+ target_pool_.age();+// Last frame's answer becomes this frame's, once. A frame that collected// nothing answered nothing — an editor frame that only blits, a frame the host// skipped — so it neither latches nor releases.@@ -394,6 +419,12 @@ void RenderFrame::flush() {}}+ // What the frame's render targets cost. The atlas and every chain+ // intermediate come out of one pool, so one number answers for all of them —+ // and a pool that stopped giving targets back is visible in no pixel.+ ES_PROFILE_COUNTER("render.targets", target_pool_.count());+ ES_PROFILE_COUNTER("render.targets.bytes", target_pool_.bytes());+ES_PROFILE_COUNTER("render.culled", stats_.culled);ES_PROFILE_COUNTER("render.sprites", stats_.sprites);// The 3D path had no counter at all, and its cost is the one a pixel hides@@ -925,12 +956,24 @@ void RenderFrame::renderShadowMap(ecs::Registry& registry) {context_.lights().setShadowTiles(nullptr, nullptr, 0, glm::vec4(0.0f));if (!in_frame_ || shadow_casters_.empty() || !device_.isDeviceUsable()) return;- if (shadow_rt_ == 0) {- shadow_rt_ = target_manager_.create(kShadowAtlasSize, kShadowAtlasSize,- /*depth=*/true, /*linearFilter=*/false);+ // 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);}- auto* rt = target_manager_.get(shadow_rt_);- if (!rt) return;+ 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@@ -1124,7 +1167,7 @@ void RenderFrame::renderShadowMap(ecs::Registry& registry) {// 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{rt->getFramebuffer(), /*clearColor=*/!cleared};+ RenderPassDesc pass{shadowFbo, /*clearColor=*/!cleared};pass.clearDepth = !cleared;pass.clearColorValue[0] = pass.clearColorValue[1] = pass.clearColorValue[2] = 1.0f;pass.clearColorValue[3] = 1.0f;@@ -1161,11 +1204,11 @@ void RenderFrame::renderShadowMap(ecs::Registry& registry) {ES_PROFILE_COUNTER("render.shadow.draws", shadowDraws);ES_PROFILE_COUNTER("render.shadow.collects", shadowCollects);- rt->unbind();+ device_.endRenderPass();device_.invalidatePipelineCache();if (anyTile) {- shadow_texture_id_ = static_cast<u32>(rt->getColorTexture());+ 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));diff --git a/src/esengine/renderer/frame/RenderFrame.hpp b/src/esengine/renderer/frame/RenderFrame.hppindex 62b872c17..e69ecff2a 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 "../graph/TargetPool.hpp"#include "../RenderTypePlugin.hpp"#ifdef ES_ENABLE_POSTPROCESS#include "./PostProcessPipeline.hpp"@@ -359,6 +360,8 @@ private:* of it is ShadowAtlas's answer rather than the light type's.*/void renderShadowMap(ecs::Registry& registry);+ /// Gives back every target this frame borrowed from {@link target_pool_}.+ void releaseFrameTargets();/// The world box the resident meshes occupy — what a shadow map must cover./// False when nothing 3D is in the scene.@@ -404,7 +407,12 @@ private:/// Every light that asked for a map this frame, in UBO slot order. Written by/// collectLights, read by renderShadowMap; empty = nobody asked.std::vector<ShadowCaster> shadow_casters_;- RenderTargetManager::Handle shadow_rt_ = 0;+ /// 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+ /// the atlas be a loan rather than a framebuffer held for the whole run.+ rg::TargetPool target_pool_;+ /// 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.ShadowAtlas shadow_atlas_{kShadowAtlasSize, kShadowCellSize};diff --git a/src/esengine/renderer/graph/RenderGraph.cpp b/src/esengine/renderer/graph/RenderGraph.cppindex 481106fad..09a55b64f 100644--- a/src/esengine/renderer/graph/RenderGraph.cpp+++ b/src/esengine/renderer/graph/RenderGraph.cpp@@ -13,7 +13,11 @@namespace esengine::rg {-RenderGraph::RenderGraph(GfxDevice& device) : device_(device) {}+RenderGraph::RenderGraph(GfxDevice& device, TargetPool& pool)+ : device_(device), pool_(pool) {}++RenderGraph::RenderGraph(GfxDevice& device)+ : device_(device), ownedPool_(makeUnique<TargetPool>(device)), pool_(*ownedPool_) {}RenderGraph::~RenderGraph() = default;@@ -23,8 +27,17 @@ void RenderGraph::begin(u32 refWidth, u32 refHeight) {resources_.clear();passes_.clear();inputScratch_.clear();- for (auto& entry : pool_) entry.inUse = false;finalTarget_ = kNoResource;++ // Only what THIS graph borrowed goes back: the pool is shared with the+ // frame's other chains and with whatever holds a target across them.+ for (const TargetHandle handle : borrowed_) pool_.release(handle);+ borrowed_.clear();+ // The pool's OWNER ticks its clock. A borrowed one is ticked once per frame+ // by the frame; ticking it per chain would age a target faster on a scene+ // that happens to have more cameras.+ if (ownedPool_) pool_.age();+refWidth_ = refWidth;refHeight_ = refHeight;executed_ = 0;@@ -64,8 +77,8 @@ ResourceId RenderGraph::createExternalTarget(const TargetDesc& desc) {const ResourceId id = createTarget(desc);Resource& res = resources_[id];res.pooled = acquire(res);- if (res.pooled == kNoPooled) return kNoResource;- res.texture = pool_[res.pooled].fbo->getColorAttachment();+ if (res.pooled == kNoTarget) return kNoResource;+ res.texture = pool_.textureOf(res.pooled);return id;}@@ -73,8 +86,8 @@ FramebufferHandle RenderGraph::framebufferOf(ResourceId id) const {if (id >= resources_.size()) return FramebufferHandle::Default;const Resource& res = resources_[id];if (res.kind == Kind::ImportedTarget) return res.target;- if (res.pooled == kNoPooled) return FramebufferHandle::Default;- return pool_[res.pooled].fbo->handle();+ if (res.pooled == kNoTarget) return FramebufferHandle::Default;+ return pool_.framebufferOf(res.pooled);}void RenderGraph::addPass(PassDesc pass) {@@ -82,6 +95,14 @@ void RenderGraph::addPass(PassDesc pass) {}void RenderGraph::resolveSize(Resource& res) const {+ // An absolute size is the target saying its texels are its own — a shadow+ // atlas divides into tiles of a fixed size, so a fraction of the window+ // would change how many maps fit when the window changed.+ if (res.desc.width > 0 && res.desc.height > 0) {+ res.width = res.desc.width;+ res.height = res.desc.height;+ return;+ }const f32 scale = res.desc.scale > 0.0f ? res.desc.scale : 1.0f;res.width = std::max(1u, static_cast<u32>(static_cast<f32>(refWidth_) * scale));res.height = std::max(1u, static_cast<u32>(static_cast<f32>(refHeight_) * scale));@@ -106,45 +127,22 @@ void RenderGraph::cull(std::vector<bool>& live) const {}}-u32 RenderGraph::acquire(const Resource& res) {- for (u32 i = 0; i < pool_.size(); ++i) {- PooledTarget& entry = pool_[i];- if (entry.inUse || !entry.fbo) continue;- if (entry.width != res.width || entry.height != res.height) continue;- if (entry.format != res.desc.format || entry.linearFilter != res.desc.linearFilter) continue;- if (entry.depthStencil != res.desc.depthStencil) continue;- entry.inUse = true;- return i;- }-- FramebufferSpec spec;- spec.width = res.width;- spec.height = res.height;- spec.depthStencil = res.desc.depthStencil;- spec.linearFilter = res.desc.linearFilter;- spec.colorFormat = res.desc.format;- auto fbo = Framebuffer::create(device_, spec);- if (!fbo) {- ES_LOG_ERROR("RenderGraph: failed to create a {}x{} target", res.width, res.height);- return kNoPooled;- }-- PooledTarget entry;- entry.fbo = std::move(fbo);- entry.width = res.width;- entry.height = res.height;- entry.format = res.desc.format;- entry.linearFilter = res.desc.linearFilter;- entry.depthStencil = res.desc.depthStencil;- entry.inUse = true;- pool_.push_back(std::move(entry));- return static_cast<u32>(pool_.size() - 1);+TargetHandle RenderGraph::acquire(const Resource& res) {+ TargetShape shape;+ shape.width = res.width;+ shape.height = res.height;+ shape.format = res.desc.format;+ shape.linearFilter = res.desc.linearFilter;+ shape.depthStencil = res.desc.depthStencil;+ const TargetHandle handle = pool_.acquire(shape);+ if (handle != kNoTarget) borrowed_.push_back(handle);+ return handle;}void RenderGraph::release(Resource& res) {- if (res.pooled == kNoPooled) return;- pool_[res.pooled].inUse = false;- res.pooled = kNoPooled;+ if (res.pooled == kNoTarget) return;+ pool_.release(res.pooled);+ res.pooled = kNoTarget;res.texture = TextureHandle::Invalid;}@@ -174,12 +172,12 @@ void RenderGraph::execute() {FramebufferHandle fbo = FramebufferHandle::Default;if (target.kind == Kind::Transient) {- if (target.pooled == kNoPooled) {+ if (target.pooled == kNoTarget) {target.pooled = acquire(target);- if (target.pooled == kNoPooled) continue;- target.texture = pool_[target.pooled].fbo->getColorAttachment();+ if (target.pooled == kNoTarget) continue;+ target.texture = pool_.textureOf(target.pooled);}- fbo = pool_[target.pooled].fbo->handle();+ fbo = pool_.framebufferOf(target.pooled);} else {fbo = target.target;}@@ -225,9 +223,10 @@ TextureHandle RenderGraph::textureOf(ResourceId id) const {void RenderGraph::releasePool() {for (auto& res : resources_) {- res.pooled = kNoPooled;+ res.pooled = kNoTarget;if (res.kind == Kind::Transient) res.texture = TextureHandle::Invalid;}+ borrowed_.clear();pool_.clear();}diff --git a/src/esengine/renderer/graph/RenderGraph.hpp b/src/esengine/renderer/graph/RenderGraph.hppindex a122e1772..0d05fba4a 100644--- a/src/esengine/renderer/graph/RenderGraph.hpp+++ b/src/esengine/renderer/graph/RenderGraph.hpp@@ -24,8 +24,10 @@#include "../../core/Types.hpp"#include "../rhi/Framebuffer.hpp"#include "../rhi/GfxEnums.hpp"+#include "TargetPool.hpp"#include <functional>+#include <memory>#include <string>#include <vector>@@ -46,9 +48,16 @@ constexpr ResourceId kNoResource = static_cast<ResourceId>(-1);* a half-size blur stays half-size when the window resizes, and the* pool can hand the same physical target to any pass asking for that* fraction.+ *+ * `width`/`height` name pixels directly instead, for a target whose+ * texels are its own: a shadow atlas is 2048² because that is how many+ * its tiling divides, and as a `scale` it would be a different resource+ * on every monitor. Zero (the default) follows `scale`.*/struct TargetDesc {f32 scale = 1.0f;+ u32 width = 0;+ u32 height = 0;GfxPixelFormat format = GfxPixelFormat::RGBA8;bool linearFilter = true;bool depthStencil = false;@@ -88,9 +97,17 @@ struct PassDesc {* @details One instance is reused across frames: the graph is rebuilt every* frame (cheap — a handful of passes) while the target pool it draws* from persists, which is what makes reuse possible at all.+ *+ * The pool is BORROWED, not owned: a graph is one chain and a frame+ * holds several (per camera, plus the screen stack), so a pool inside+ * the graph could hold nothing across two of them. Given one, every+ * chain draws from the same targets, and so can a frame-lived resource.*/class RenderGraph {public:+ /** Borrows the caller's pool: a frame's chains share one. */+ RenderGraph(GfxDevice& device, TargetPool& pool);+ /** Owns a pool of its own — for a lone chain and for tests. */explicit RenderGraph(GfxDevice& device);~RenderGraph();@@ -140,8 +157,16 @@ public:* the handles the pool holds name nothing. */void releasePool();+ /** The targets this graph draws from — shared with the frame's other chains+ * when one was given, its own otherwise. */+ TargetPool& pool() { return pool_; }+/** How many physical targets the pool is holding. Diagnostics and tests. */- u32 pooledTargetCount() const { return static_cast<u32>(pool_.size()); }+ u32 pooledTargetCount() const { return pool_.count(); }++ /** What those targets cost in GPU memory, so the number a budget reads is+ * bytes rather than a count of things with no common size. */+ u64 pooledTargetBytes() const { return pool_.bytes(); }/** Passes the last execute() ran, after culling. Diagnostics and tests. */u32 lastExecutedPassCount() const { return executed_; }@@ -156,33 +181,28 @@ private:FramebufferHandle target = FramebufferHandle::Default;u32 width = 0;u32 height = 0;- /// Index into pool_ while a transient holds one; kNoPooled otherwise.- u32 pooled = kNoPooled;+ /// The pool target a transient holds; kNoTarget when it holds none.+ TargetHandle pooled = kNoTarget;i32 lastRead = -1;};- struct PooledTarget {- Unique<Framebuffer> fbo;- u32 width = 0;- u32 height = 0;- GfxPixelFormat format = GfxPixelFormat::RGBA8;- bool linearFilter = true;- bool depthStencil = false;- bool inUse = false;- };-- static constexpr u32 kNoPooled = static_cast<u32>(-1);void resolveSize(Resource& res) const;- u32 acquire(const Resource& res);+ TargetHandle acquire(const Resource& res);void release(Resource& res);/// Marks the passes that reach the imported target; false for everything else.void cull(std::vector<bool>& live) const;GfxDevice& device_;+ /// Set only by the pool-owning constructor; pool_ refers into it.+ Unique<TargetPool> ownedPool_;+ TargetPool& pool_;std::vector<Resource> resources_;std::vector<PassDesc> passes_;- std::vector<PooledTarget> pool_;+ /// What this graph has borrowed and still owes back, released at the next+ /// begin() — a transient nothing reads is never released mid-execute, and+ /// the pool is no longer the graph's to reset wholesale.+ std::vector<TargetHandle> borrowed_;std::vector<TextureHandle> inputScratch_;ResourceId finalTarget_ = kNoResource;u32 refWidth_ = 0;diff --git a/src/esengine/renderer/graph/TargetPool.cpp b/src/esengine/renderer/graph/TargetPool.cppnew file mode 100644index 000000000..221201112--- /dev/null+++ b/src/esengine/renderer/graph/TargetPool.cpp@@ -0,0 +1,163 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file TargetPool.cpp+ * @brief Borrow, return and age the frame's render targets. See TargetPool.hpp.+ */+#include "TargetPool.hpp"++#include "../../core/Log.hpp"+#include "../rhi/GfxDevice.hpp"++namespace esengine::rg {++namespace {++/** Bytes one texel of a target costs, colour and depth counted separately. */+u64 texelBytes(const TargetShape& shape) {+ // A colour attachment stored as RGB8 still occupies four bytes on both+ // backends (WebGPU has no 24-bit colour target and WebGL2 pads), so the+ // upload-side gfxBytesPerPixel would under-report a target by a quarter.+ u64 bytes = shape.format == GfxPixelFormat::RGBA16F ? 8u : 4u;+ // Depth24Stencil8 is what a depth-stencil attachment costs; the colour above+ // is separate storage, not a second view of it.+ if (shape.depthStencil) bytes += 4u;+ return bytes;+}++bool sameShape(const TargetShape& a, const TargetShape& b) {+ return a.width == b.width && a.height == b.height && a.format == b.format+ && a.linearFilter == b.linearFilter && a.depthStencil == b.depthStencil;+}++} // namespace++TargetPool::TargetPool(GfxDevice& device) : device_(device) {}++TargetPool::~TargetPool() = default;++const TargetPool::Entry* TargetPool::resolve(TargetHandle handle) const {+ if (handle == kNoTarget) return nullptr;+ const u32 slot = handle & kSlotMask;+ if (slot >= entries_.size()) return nullptr;+ const Entry& entry = entries_[slot];+ // The generation is what tells a live handle from one whose target was freed+ // and whose slot something else has since taken.+ if (!entry.fbo || entry.generation != (handle >> kSlotBits)) return nullptr;+ return &entry;+}++TargetHandle TargetPool::acquire(const TargetShape& shape) {+ auto handleFor = [&](usize slot) {+ return static_cast<TargetHandle>((entries_[slot].generation << kSlotBits)+ | static_cast<u32>(slot));+ };++ for (usize i = 0; i < entries_.size(); ++i) {+ Entry& entry = entries_[i];+ if (entry.inUse || !entry.fbo || !sameShape(entry.shape, shape)) continue;+ entry.inUse = true;+ // Borrowed, so it is not idle. The only place age is reset.+ entry.idle = 0;+ return handleFor(i);+ }++ FramebufferSpec spec;+ spec.width = shape.width;+ spec.height = shape.height;+ spec.depthStencil = shape.depthStencil;+ spec.linearFilter = shape.linearFilter;+ spec.colorFormat = shape.format;+ auto fbo = Framebuffer::create(device_, spec);+ if (!fbo) {+ ES_LOG_ERROR("TargetPool: failed to create a {}x{} target", shape.width, shape.height);+ return kNoTarget;+ }++ // An emptied slot is refilled before a new one is appended: the generation+ // in it has already moved on, so no handle from its last occupant matches.+ for (usize i = 0; i < entries_.size(); ++i) {+ if (entries_[i].fbo) continue;+ entries_[i].fbo = std::move(fbo);+ entries_[i].shape = shape;+ entries_[i].inUse = true;+ entries_[i].idle = 0;+ return handleFor(i);+ }++ if (entries_.size() > kSlotMask) {+ ES_LOG_ERROR("TargetPool: {} targets is past what a handle can name", entries_.size());+ return kNoTarget;+ }++ Entry entry;+ entry.fbo = std::move(fbo);+ entry.shape = shape;+ entry.inUse = true;+ entries_.push_back(std::move(entry));+ return handleFor(entries_.size() - 1);+}++void TargetPool::release(TargetHandle handle) {+ if (!resolve(handle)) return;+ entries_[handle & kSlotMask].inUse = false;+}++bool TargetPool::holds(TargetHandle handle) const {+ return resolve(handle) != nullptr;+}++FramebufferHandle TargetPool::framebufferOf(TargetHandle handle) const {+ const Entry* entry = resolve(handle);+ return entry ? entry->fbo->handle() : FramebufferHandle::Default;+}++TextureHandle TargetPool::textureOf(TargetHandle handle) const {+ const Entry* entry = resolve(handle);+ return entry ? entry->fbo->getColorAttachment() : TextureHandle::Invalid;+}++void TargetPool::age() {+ for (auto& entry : entries_) {+ if (!entry.fbo || entry.inUse) continue;+ if (++entry.idle >= kIdleTicksBeforeEvict) {+ // The slot stays and the generation moves on: the memory goes, and+ // every handle that named it stops naming anything.+ entry.fbo.reset();+ entry.idle = 0;+ ++entry.generation;+ }+ }+}++void TargetPool::clear() {+ // Same bargain as an eviction, for every slot at once. The slots themselves+ // are kept — a handle held across a device loss has to come back stale, not+ // come back naming whatever refills its index.+ for (auto& entry : entries_) {+ if (!entry.fbo) continue;+ entry.fbo.reset();+ entry.inUse = false;+ entry.idle = 0;+ ++entry.generation;+ }+}++u32 TargetPool::count() const {+ u32 live = 0;+ for (const auto& entry : entries_) {+ if (entry.fbo) ++live;+ }+ return live;+}++u64 TargetPool::bytes() const {+ u64 total = 0;+ for (const auto& entry : entries_) {+ if (!entry.fbo) continue;+ total += static_cast<u64>(entry.shape.width) * entry.shape.height * texelBytes(entry.shape);+ }+ return total;+}++} // namespace esengine::rgdiff --git a/src/esengine/renderer/graph/TargetPool.hpp b/src/esengine/renderer/graph/TargetPool.hppnew file mode 100644index 000000000..6680be524--- /dev/null+++ b/src/esengine/renderer/graph/TargetPool.hpp@@ -0,0 +1,137 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file TargetPool.hpp+ * @brief The render targets a frame borrows from, keyed by shape — owned by+ * the frame, not by any one graph that draws from it.+ *+ * A RenderGraph is a CHAIN, and a frame holds several of them: one per camera+ * and one for the screen-level stack. While the pool lived inside the graph,+ * every `begin()` handed every target back, so nothing could be borrowed across+ * two chains — which is why the shadow atlas had to be a framebuffer of its own,+ * created on the first shadowed frame and held for the rest of the run.+ *+ * Splitting it out makes the lifetime the borrower's to state: a chain's+ * transient goes back at its last read, the atlas goes back at the end of the+ * frame, and both come out of the same physical targets on the next one.+ *+ * Handles carry a generation. A slot outlives the target in it — evicting frees+ * the memory and leaves the slot to be refilled — so an index alone would let a+ * handle taken before an eviction name whatever landed in that slot afterwards,+ * and a frame holding the atlas across a window resize would draw its shadows+ * into a post-process target. The generation makes a stale handle name nothing.+ */+#pragma once++#include "../../core/Types.hpp"+#include "../rhi/Framebuffer.hpp"+#include "../rhi/GfxEnums.hpp"++#include <vector>++namespace esengine {++class GfxDevice;++namespace rg {++/**+ * @brief A borrowed target: a slot index, and the generation of what is in it.+ *+ * @details Opaque — pack and unpack are the pool's. Compare it, hold it, hand it+ * back; a handle whose target has since been freed resolves to nothing+ * rather than to the next thing that took the slot.+ */+using TargetHandle = u32;+constexpr TargetHandle kNoTarget = static_cast<TargetHandle>(-1);++/** What a borrower asks for. Sizes are pixels — a scale is the caller's to resolve. */+struct TargetShape {+ u32 width = 0;+ u32 height = 0;+ GfxPixelFormat format = GfxPixelFormat::RGBA8;+ bool linearFilter = true;+ bool depthStencil = false;+};++class TargetPool {+public:+ explicit TargetPool(GfxDevice& device);+ ~TargetPool();++ TargetPool(const TargetPool&) = delete;+ TargetPool& operator=(const TargetPool&) = delete;++ /**+ * @brief Borrow a target of this shape, reusing one or creating it.+ * @return kNoTarget if the device could not make one.+ */+ TargetHandle acquire(const TargetShape& shape);++ /** Give one back. Borrowing again may hand out the same physical target. */+ void release(TargetHandle handle);++ /** Whether a handle still names a live target — false once it was freed. */+ bool holds(TargetHandle handle) const;++ FramebufferHandle framebufferOf(TargetHandle handle) const;+ TextureHandle textureOf(TargetHandle handle) const;++ /**+ * @brief One tick of the clock every borrowed target is aged against.+ *+ * @details Called once per graph. A target out on loan does not age; one+ * nothing has borrowed for {@link kIdleTicksBeforeEvict} ticks is+ * memory held against a chain that was turned off, or a scene that+ * stopped casting shadows, and is destroyed.+ */+ void age();++ /** Drop everything. For shutdown and for device loss, after which the+ * handles the pool holds name nothing. */+ void clear();++ /** Physical targets currently allocated. Diagnostics and tests. */+ u32 count() const;++ /** What they cost in GPU memory, so a budget reads bytes rather than a+ * count of things with no common size. */+ u64 bytes() const;++ /**+ * @brief Ticks a target may go unborrowed before the pool destroys it.+ *+ * @details High on purpose: acquire() resets it, so this bounds only how+ * long a target NOTHING asks for is kept against being asked for+ * again. At a small number a target used by one of several chains+ * would thrash on the ticks the others take.+ */+ static constexpr u32 kIdleTicksBeforeEvict = 120;++private:+ struct Entry {+ Unique<Framebuffer> fbo;+ TargetShape shape;+ bool inUse = false;+ /// Ticks since anything borrowed it; age() adds, acquire() zeroes.+ u32 idle = 0;+ /// Bumped whenever the target in this slot is freed, which is what makes+ /// every handle to it stale.+ u32 generation = 0;+ };++ /// Slots live in the low bits so the count is what bounds them, not the+ /// generation: 64K slots is far past any frame, and a generation that wraps+ /// would need the same slot freed 64K times while one handle survived.+ static constexpr u32 kSlotBits = 16;+ static constexpr u32 kSlotMask = (1u << kSlotBits) - 1;++ /// The entry a handle names, or nullptr if it names one that has been freed.+ const Entry* resolve(TargetHandle handle) const;++ GfxDevice& device_;+ std::vector<Entry> entries_;+};++} // namespace rg+} // namespace esenginediff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txtindex 3901a8c86..6624c5d6b 100644--- a/tests/CMakeLists.txt+++ b/tests/CMakeLists.txt@@ -154,6 +154,7 @@ add_test(NAME test_texture_fb COMMAND test_texture_fb)add_executable(test_render_graphrenderer/test_render_graph.cpp${CMAKE_SOURCE_DIR}/src/esengine/renderer/graph/RenderGraph.cpp+ ${CMAKE_SOURCE_DIR}/src/esengine/renderer/graph/TargetPool.cpp${CMAKE_SOURCE_DIR}/src/esengine/renderer/rhi/Texture.cpp${CMAKE_SOURCE_DIR}/src/esengine/renderer/rhi/Framebuffer.cpp${CMAKE_SOURCE_DIR}/src/esengine/core/Log.cppdiff --git a/tests/renderer/test_render_graph.cpp b/tests/renderer/test_render_graph.cppindex 0962f37ff..761852302 100644--- a/tests/renderer/test_render_graph.cpp+++ b/tests/renderer/test_render_graph.cpp@@ -215,6 +215,162 @@ int main() {CHECK(graph.pooledTargetCount() == 2, "the pool owns it, not the pipeline");}+ // --- a target can name its pixels instead of a fraction of the frame ---+ {+ MockGfxDevice d;+ rg::RenderGraph graph(d);+ u32 atlasW = 0, atlasH = 0;++ graph.begin(800, 600);+ const auto out = graph.importTarget(FramebufferHandle{9}, 800, 600);+ rg::TargetDesc atlas;+ atlas.width = 2048;+ atlas.height = 2048;+ atlas.depthStencil = true;+ const auto maps = graph.createTarget(atlas);+ rg::PassDesc shadow = fullscreen("shadow", {}, maps);+ shadow.execute = [&](const rg::PassContext& ctx) { atlasW = ctx.width; atlasH = ctx.height; };+ graph.addPass(std::move(shadow));+ graph.addPass(fullscreen("scene", {maps}, out));+ graph.execute();++ CHECK(atlasW == 2048 && atlasH == 2048,+ "an absolute size is the target's own, not a fraction of the frame");++ // The point of asking in pixels: the same atlas at a different window+ // size is the same resource, so the pool hands back the one it has.+ graph.begin(1920, 1080);+ const auto out2 = graph.importTarget(FramebufferHandle{9}, 1920, 1080);+ const auto maps2 = graph.createTarget(atlas);+ graph.addPass(fullscreen("shadow", {}, maps2));+ graph.addPass(fullscreen("scene", {maps2}, out2));+ graph.execute();++ CHECK(d.createFramebufferCalls == 1,+ "and it survives a resize the fraction-sized targets do not");+ }++ // --- the pool gives back what nothing asks for any more ---+ {+ MockGfxDevice d;+ rg::RenderGraph graph(d);++ // A frame with a blur chain: the scene, plus the half-size target it runs on.+ graph.begin(256, 256);+ const auto scene = graph.importTexture(TextureHandle{7}, 256, 256);+ const auto out = graph.importTarget(FramebufferHandle{9}, 256, 256);+ rg::TargetDesc half;+ half.scale = 0.5f;+ const auto small = graph.createTarget(half);+ graph.addPass(fullscreen("blur", {scene}, small));+ graph.addPass(fullscreen("composite", {small, scene}, out));+ graph.execute();++ CHECK(graph.pooledTargetCount() == 1, "the chain's target is pooled");+ CHECK(graph.pooledTargetBytes() == 128ull * 128ull * 4ull,+ "and a budget can read what it costs in bytes");++ // The effect is turned off. Nothing asks for a 128x128 target again.+ for (int frame = 0; frame < 121; ++frame) {+ graph.begin(256, 256);+ const auto sc = graph.importTexture(TextureHandle{7}, 256, 256);+ const auto o = graph.importTarget(FramebufferHandle{9}, 256, 256);+ graph.addPass(fullscreen("blit", {sc}, o));+ graph.execute();+ }++ CHECK(graph.pooledTargetCount() == 0,+ "a target nothing has asked for in 120 graphs goes back");+ CHECK(graph.pooledTargetBytes() == 0, "and stops being counted against the budget");+ }++ // --- ...but not one that is still being used ---+ {+ MockGfxDevice d;+ rg::RenderGraph graph(d);++ for (int frame = 0; frame < 200; ++frame) {+ graph.begin(256, 256);+ const auto scene = graph.importTexture(TextureHandle{7}, 256, 256);+ const auto out = graph.importTarget(FramebufferHandle{9}, 256, 256);+ const auto mid = graph.createTarget({});+ graph.addPass(fullscreen("blur", {scene}, mid));+ graph.addPass(fullscreen("blit", {mid}, out));+ graph.execute();+ }++ // The count alone would not catch a wrong eviction: evicted and+ // reallocated leaves a pool of one too. What it cost to get there is+ // the half that bites.+ CHECK(graph.pooledTargetCount() == 1, "a target asked for every graph is kept");+ CHECK(d.createFramebufferCalls == 1, "and never reallocated");+ }++ // --- a frame's chains share one pool, and something can hold across them ---+ {+ MockGfxDevice d;+ rg::TargetPool pool(d);+ rg::RenderGraph graph(d, pool);++ // What the shadow atlas is: borrowed before any chain runs and still+ // its own after two have. Deliberately the SHAPE A CHAIN WANTS — a+ // 2048² one no chain asks for could not be taken either way.+ rg::TargetShape held_shape;+ held_shape.width = 256;+ held_shape.height = 256;+ const rg::TargetHandle held = pool.acquire(held_shape);+ const FramebufferHandle heldFbo = pool.framebufferOf(held);+ CHECK(held != rg::kNoTarget && heldFbo != FramebufferHandle::Default,+ "a frame can borrow a target before any chain begins");++ FramebufferHandle chainFbo = FramebufferHandle::Default;+ for (int camera = 0; camera < 2; ++camera) {+ graph.begin(256, 256);+ const auto scene = graph.createExternalTarget({});+ chainFbo = graph.framebufferOf(scene);+ const auto out = graph.importTarget(FramebufferHandle{9}, 256, 256);+ graph.addPass(fullscreen("blit", {scene}, out));+ graph.execute();+ }++ CHECK(chainFbo != heldFbo,+ "a chain is never handed the target the frame is still holding");+ CHECK(pool.framebufferOf(held) == heldFbo,+ "which is still the frame's after two chains ran over the same pool");+ CHECK(pool.count() == 2, "the held one and the chains' own, not one per chain");++ // Given back at the end of the frame, it is a candidate again — which is+ // the whole difference from a framebuffer the frame keeps forever.+ pool.release(held);+ for (int tick = 0; tick < rg::TargetPool::kIdleTicksBeforeEvict; ++tick) pool.age();+ CHECK(pool.count() == 0, "and once given back it ages out like anything else");+ }++ // --- a handle outliving its target names nothing, not the next thing ---+ {+ MockGfxDevice d;+ rg::TargetPool pool(d);++ rg::TargetShape shape;+ shape.width = 128;+ shape.height = 128;+ const rg::TargetHandle held = pool.acquire(shape);+ CHECK(pool.holds(held), "a fresh handle names its target");++ // What a window resize does: reclaim everything, then hand the slot to+ // the next borrower. Without a generation the stale handle would name+ // the newcomer, and the frame would draw its shadows into a post target.+ pool.clear();+ CHECK(!pool.holds(held), "a handle whose target was dropped names nothing");+ CHECK(pool.framebufferOf(held) == FramebufferHandle::Default,+ "and answers with no framebuffer rather than someone else's");++ const rg::TargetHandle next = pool.acquire(shape);+ CHECK(next != held, "the refilled slot is a different handle");+ CHECK(!pool.holds(held) && pool.holds(next),+ "so the newcomer is reachable and the ghost still is not");+ }+std::printf(g_failures == 0 ? "\nALL PASS\n" : "\n%d FAILURE(S)\n", g_failures);return g_failures == 0 ? 0 : 1;}diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjsindex caeb83b40..190568be0 100644--- a/tools/renderScenes.mjs+++ b/tools/renderScenes.mjs@@ -113,7 +113,7 @@ export const SCENES = [// A POINT light opens no cone, so its map is a cube and a fragment is shadowed by the face// it lands in: report one tile for every tile and both shadows come back lit. The casters// are probed too, and the sixth face never renders — nothing above the lamp is a mesh.- { id: "point-shadow", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/point-shadow.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_COUNTERS: "{\"render.shadow.tiles\":5}", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.167,\"y\":0.5,\"rgb\":[0,0,0],\"tol\":20},{\"x\":0.5,\"y\":0.833,\"rgb\":[0,0,0],\"tol\":20},{\"x\":0.333,\"y\":0.5,\"rgb\":[108,108,108],\"tol\":25},{\"x\":0.833,\"y\":0.5,\"rgb\":[102,102,102],\"tol\":25},{\"x\":0.5,\"y\":0.5,\"rgb\":[242,242,242],\"tol\":20}]" } },+ { id: "point-shadow", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/point-shadow.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_COUNTERS: "{\"render.shadow.tiles\":5,\"render.targets\":1,\"render.targets.bytes\":33554432}", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.167,\"y\":0.5,\"rgb\":[0,0,0],\"tol\":20},{\"x\":0.5,\"y\":0.833,\"rgb\":[0,0,0],\"tol\":20},{\"x\":0.333,\"y\":0.5,\"rgb\":[108,108,108],\"tol\":25},{\"x\":0.833,\"y\":0.5,\"rgb\":[102,102,102],\"tol\":25},{\"x\":0.5,\"y\":0.5,\"rgb\":[242,242,242],\"tol\":20}]" } },// A shadow map holds depth, so only geometry drawn depth-only belongs in one. A BLACK// sprite stands opposite a mesh blocker, both between lamp and floor: black unpacks as// depth 0, so a collected sprite would shadow its half — which has to come back lit.@@ -180,7 +180,7 @@ export const SCENES = [// Does an atlas draw scale with the CASTER count: 3249 casters are two draws (a ground quad,// then every cube instanced), and a fallback to one draw each changes no pixel. The probes take// the only ground the grid leaves bare — lit past its left edge, shadowed past its right.- { id: "shadow-scale-cost", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/scale-shadow.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_SCALE: "{\"copies\":3249,\"cols\":57,\"spacing\":[10,10],\"keep\":[\"Camera\",\"Light\",\"Ground\"]}", ESTELLA_VERIFY_COUNTERS_MAX: "{\"render.shadow.draws\":8}", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.012,\"y\":0.5,\"rgb\":[228,228,228],\"tol\":20},{\"x\":0.984,\"y\":0.5,\"rgb\":[0,0,0],\"tol\":20}]" } },+ { id: "shadow-scale-cost", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/scale-shadow.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_SCALE: "{\"copies\":3249,\"cols\":57,\"spacing\":[10,10],\"keep\":[\"Camera\",\"Light\",\"Ground\"]}", ESTELLA_VERIFY_COUNTERS_MAX: "{\"render.shadow.draws\":8,\"render.targets.bytes\":33554432}", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.012,\"y\":0.5,\"rgb\":[228,228,228],\"tol\":20},{\"x\":0.984,\"y\":0.5,\"rgb\":[0,0,0],\"tol\":20}]" } },// Two opaque cubes overlapping on screen, the red one 120 units nearer. Declares NO// depth layer and boots LINEAR — the cheap way to engage the post-process capture.// Opaque sorts front-to-back, so with no attachment the far cube paints over.