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 target pool belongs to the frame, not to one chain

yhh7b5f9cb2d62c
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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 than
diff --git a/cmake/ESEngineSources.cmake b/cmake/ESEngineSources.cmake
index 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.cpp
diff --git a/src/esengine/renderer/frame/PostProcessPipeline.cpp b/src/esengine/renderer/frame/PostProcessPipeline.cpp
index 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.hpp
index 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.cpp
index 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_POSTPROCESS
if (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.hpp
index 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.cpp
index 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.hpp
index 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.cpp
new file mode 100644
index 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::rg
diff --git a/src/esengine/renderer/graph/TargetPool.hpp b/src/esengine/renderer/graph/TargetPool.hpp
new file mode 100644
index 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 esengine
diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt
index 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_graph
renderer/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.cpp
diff --git a/tests/renderer/test_render_graph.cpp b/tests/renderer/test_render_graph.cpp
index 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.mjs
index 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.