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(renderer): the graph owns the scene target, and the frame asks once whether it is captured

yhh55b4d49b0b5e
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 412347d82..41fb99798 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,6 +14,39 @@ published separately; it ships inside the editor.
## [Unreleased]
+### Changed
+
+- **The render graph owns the scene target now, not the post-process pipeline.**
+ `RenderGraph.hpp` used to say so in its own header — *"The graph does NOT own
+ scene geometry"* — and the reason was real: one frame reaches the host as
+ several calls (`renderer_begin`, `submitAll`, `flush`, `end`) with the geometry
+ drawn between them, so the scene cannot be filled from inside a pass callback
+ the way every full-screen pass is. The pipeline answered that by owning a
+ private `fboOriginal_` and handing the graph a texture afterwards.
+
+ It did not need a private framebuffer, it needed a target it could draw into
+ BEFORE the graph runs. `createExternalTarget` is that: the graph allocates it
+ from the same pool, at the same declared format and scale, and recycles it at
+ its last read like any other transient — the exception is WHEN it is filled,
+ not who owns it. The graph now opens at `begin()` rather than at `end()`,
+ because the scene target is its first resource.
+
+ What that deletes: the bespoke lifecycle around that one framebuffer.
+ `fboOriginal_`, `fboOriginalCreated_`, its re-creation in `resize` and
+ `recreateGpuResources`, and the FBO surgery inside `setSceneNeedsDepth` — which
+ dropped and rebuilt the framebuffer to change one attachment — are gone;
+ depth is a field in the desc the next frame declares. Format follows the same
+ way, so a colour-space change no longer has to invalidate anything.
+
+ **One predicate for "is the capture engaged".** RenderFrame spelled the same
+ three-term expression out twice, at both ends of the frame, and had to agree
+ with itself or leave a capture opened and never resolved. It asks
+ `PostProcessPipeline::isEngaged()` at both ends now.
+
+ No pixel moves: same format, same passes, same order. Verified on the pr tier,
+ both backends (98/98 webgl2, 96/96 webgpu) — device loss and resize included,
+ which is where a pooled scene target would fail if it were going to.
+
### Added
- **The 3D path can be held to what it COST, not just to what it drew.**
diff --git a/src/esengine/renderer/frame/PostProcessPipeline.cpp b/src/esengine/renderer/frame/PostProcessPipeline.cpp
index 21d7bd0df..21e37ddf9 100644
--- a/src/esengine/renderer/frame/PostProcessPipeline.cpp
+++ b/src/esengine/renderer/frame/PostProcessPipeline.cpp
@@ -76,36 +76,29 @@ GfxPixelFormat PostProcessPipeline::interFormat() const {
: GfxPixelFormat::SRGB8_ALPHA8;
}
-void PostProcessPipeline::ensureFBOs() {
- const GfxPixelFormat interFmt = interFormat();
- if (!graph_) graph_ = makeUnique<rg::RenderGraph>(device_);
- if (!fboOriginalCreated_) {
- FramebufferSpec origSpec;
- origSpec.width = width_;
- origSpec.height = height_;
- origSpec.depthStencil = scene_needs_depth_;
- origSpec.colorFormat = interFmt;
- // Bilinear intermediates: fullscreen passes sample at texel centers
- // (where LINEAR == NEAREST), but Kawase blur deliberately samples at
- // half-texel offsets — with NEAREST those land ON texel boundaries,
- // whose rounding is backend-dependent (GL vs Dawn diverged visibly).
- // LINEAR makes the tap a well-defined 2x2 average — the actual Kawase
- // algorithm — identical on every backend.
- origSpec.linearFilter = true;
-
- fboOriginal_ = Framebuffer::create(device_, origSpec);
- if (!fboOriginal_) {
- ES_LOG_ERROR("PostProcessPipeline: Failed to create original FBO");
- return;
- }
- fboOriginalCreated_ = true;
- if (linear_output_) {
- ES_LOG_INFO("PostProcess intermediates: {}",
- interFmt == GfxPixelFormat::RGBA16F ? "RGBA16F (HDR)"
+void PostProcessPipeline::ensureGraph() {
+ if (graph_) return;
+ graph_ = makeUnique<rg::RenderGraph>(device_);
+ if (linear_output_) {
+ ES_LOG_INFO("PostProcess intermediates: {}",
+ interFormat() == GfxPixelFormat::RGBA16F ? "RGBA16F (HDR)"
: "SRGB8_ALPHA8 (LDR linear)");
- }
}
+}
+/**
+ * The shape every target in a chain has, the one the scene lands in included.
+ *
+ * Bilinear throughout: Kawase blur samples at half-texel offsets, which under
+ * NEAREST land ON texel boundaries whose rounding is backend-dependent (GL and
+ * Dawn diverged visibly). LINEAR makes the tap the 2x2 average it means.
+ */
+rg::TargetDesc PostProcessPipeline::chainTarget(bool withDepth) const {
+ rg::TargetDesc desc;
+ desc.format = interFormat();
+ desc.linearFilter = true;
+ desc.depthStencil = withDepth;
+ return desc;
}
void PostProcessPipeline::shutdown() {
@@ -127,9 +120,8 @@ void PostProcessPipeline::shutdown() {
}
graph_.reset();
- fboOriginal_.reset();
screenFBO_.reset();
- fboOriginalCreated_ = false;
+ sceneResource_ = rg::kNoResource;
screenCaptureActive_ = false;
screenFBOCreated_ = false;
sceneTexture_ = TextureHandle::Invalid;
@@ -154,12 +146,11 @@ void PostProcessPipeline::recreateGpuResources() {
for (auto& pass : screenPasses_) { pass.paramUbo = BufferHandle::Invalid; pass.paramDirty = true; }
if (graph_) graph_->releasePool();
- fboOriginal_.reset();
screenFBO_.reset();
- fboOriginalCreated_ = false;
+ sceneResource_ = rg::kNoResource;
screenFBOCreated_ = false;
screenCaptureActive_ = false;
- ensureFBOs();
+ ensureGraph();
}
void PostProcessPipeline::resize(u32 width, u32 height) {
@@ -169,15 +160,12 @@ void PostProcessPipeline::resize(u32 width, u32 height) {
width_ = width;
height_ = height;
- if (fboOriginalCreated_) {
- fboOriginal_.reset();
- fboOriginalCreated_ = false;
- }
// The pool is keyed by shape, so targets at the old size would never be
// handed out again — they would just sit there holding memory.
if (graph_) graph_->releasePool();
+ sceneResource_ = rg::kNoResource;
- ensureFBOs();
+ ensureGraph();
if (screenFBOCreated_) {
screenFBO_.reset();
@@ -293,17 +281,27 @@ void PostProcessPipeline::applyPassPipeline(const Shader& shader) {
FramebufferHandle PostProcessPipeline::currentSceneFBO() const {
if (screenCaptureActive_ && screenFBOCreated_) return screenFBO_->handle();
- if (inFrame_ && fboOriginalCreated_) return fboOriginal_->handle();
+ if (inFrame_ && graph_) return graph_->framebufferOf(sceneResource_);
return FramebufferHandle::Default;
}
void PostProcessPipeline::begin(const f32* clearColor) {
if (!initialized_ || inFrame_ || (bypass_ && !linear_output_)) return;
- ensureFBOs();
- if (!fboOriginalCreated_) return;
+ ensureGraph();
+ if (!graph_) return;
+
+ // The graph opens HERE and not at end(), because the scene target is its
+ // first resource and the scene is drawn before any pass can be declared.
+ graph_->begin(width_, height_);
+ sceneResource_ = graph_->createExternalTarget(chainTarget(scene_needs_depth_));
+ if (sceneResource_ == rg::kNoResource) {
+ ES_LOG_ERROR("PostProcessPipeline: no scene target this frame");
+ return;
+ }
- RenderPassDesc pass{fboOriginal_->handle(), /*clearColor=*/true, /*clearDepth=*/true};
+ RenderPassDesc pass{graph_->framebufferOf(sceneResource_),
+ /*clearColor=*/true, /*clearDepth=*/true};
if (clearColor) {
for (int i = 0; i < 4; ++i) pass.clearColorValue[i] = clearColor[i];
if (linear_output_) {
@@ -331,10 +329,12 @@ void PostProcessPipeline::end() {
device->invalidatePipelineCache();
device->setScissorTest(false);
- sceneTexture_ = fboOriginal_->getColorAttachment();
- fboOriginal_->unbind();
+ sceneTexture_ = graph_->textureOf(sceneResource_);
+ // What Framebuffer::unbind did for the FBO this replaced: a WebGPU pass
+ // encoder has to be closed before the graph opens the first chain pass.
+ device->endRenderPass();
- runChain(passes_, sceneTexture_);
+ runChain(passes_, sceneResource_);
device->invalidatePipelineCache();
inFrame_ = false;
@@ -464,19 +464,11 @@ void PostProcessPipeline::blitPass() {
drawScreenQuad();
}
-void PostProcessPipeline::runChain(std::vector<PostProcessPass>& passes, TextureHandle sceneTexture) {
- if (!graph_) return;
+void PostProcessPipeline::runChain(std::vector<PostProcessPass>& passes, rg::ResourceId scene) {
+ if (!graph_ || scene == rg::kNoResource) return;
- graph_->begin(width_, height_);
- const rg::ResourceId scene = graph_->importTexture(sceneTexture, width_, height_);
const rg::ResourceId out = graph_->importTarget(output_target_fbo_, width_, height_);
-
- rg::TargetDesc desc;
- desc.format = interFormat();
- // Bilinear intermediates: fullscreen passes sample at texel centers (where
- // LINEAR == NEAREST), but Kawase blur samples at half-texel offsets, whose
- // NEAREST rounding is backend-dependent (GL and Dawn diverged visibly).
- desc.linearFilter = true;
+ const rg::TargetDesc desc = chainTarget(/*withDepth=*/false);
rg::ResourceId input = scene;
for (auto& pass : passes) {
@@ -551,12 +543,17 @@ void PostProcessPipeline::executeScreenPasses() {
device->invalidatePipelineCache();
device->setScissorTest(false);
- ensureFBOs();
+ ensureGraph();
+ if (!graph_) return;
sceneTexture_ = screenFBO_->getColorAttachment();
screenFBO_->unbind();
- runChain(screenPasses_, sceneTexture_);
+ // The composition surface every camera drew into is NOT a transient (it
+ // outlives each camera graph), so this chain imports it and opens a graph
+ // of its own.
+ graph_->begin(width_, height_);
+ runChain(screenPasses_, graph_->importTexture(sceneTexture_, width_, height_));
device->invalidatePipelineCache();
}
diff --git a/src/esengine/renderer/frame/PostProcessPipeline.hpp b/src/esengine/renderer/frame/PostProcessPipeline.hpp
index 987573e1a..2325b501d 100644
--- a/src/esengine/renderer/frame/PostProcessPipeline.hpp
+++ b/src/esengine/renderer/frame/PostProcessPipeline.hpp
@@ -152,6 +152,18 @@ public:
*/
bool isInitialized() const { return initialized_; }
+ /**
+ * @brief Whether the scene goes through the graph or straight to the surface.
+ *
+ * @details Two things engage it: effects to run, or the linear pipeline, whose
+ * final pass carries an encode a WebGL2 canvas framebuffer cannot do
+ * for itself. One predicate because RenderFrame asked at both ends of
+ * the frame, and two copies is one edit from a capture never resolved.
+ */
+ bool isEngaged() const {
+ return initialized_ && ((!bypass_ && !passes_.empty()) || linear_output_);
+ }
+
/**
* @brief Sets bypass mode to skip FBO rendering entirely
* @param bypass If true, begin()/end() become no-ops
@@ -170,18 +182,11 @@ public:
*
* @details A depth buffer is per-frame memory and clear bandwidth (≈8MB at 1080p),
* which a project with no depth layer should not pay for a feature it does
- * not use. Drops the scene FBO when the answer changes so the next
- * ensureFBOs rebuilds it with the right attachments — the same way resize
- * handles a size change.
+ * not use. A flag and nothing more: the scene target is declared to the
+ * graph at every begin(), so the next frame asks the pool for the shape
+ * this answer describes and the old one is simply never handed out again.
*/
- void setSceneNeedsDepth(bool needs) {
- if (needs == scene_needs_depth_) return;
- scene_needs_depth_ = needs;
- if (fboOriginalCreated_) {
- fboOriginal_.reset();
- fboOriginalCreated_ = false;
- }
- }
+ void setSceneNeedsDepth(bool needs) { scene_needs_depth_ = needs; }
bool linearOutput() const { return linear_output_; }
/**
@@ -259,13 +264,16 @@ private:
PostProcessPass* findPass(const std::string& name);
/** Intermediate/capture attachment format for the active pipeline mode. */
GfxPixelFormat interFormat() const;
- void ensureFBOs();
+ /** The shape of every target in a chain, the scene target included. */
+ rg::TargetDesc chainTarget(bool withDepth) const;
+ void ensureGraph();
void ensureScreenQuad();
void drawScreenQuad();
void applyPassPipeline(const Shader& shader);
void renderPass(PostProcessPass& pass, const rg::PassContext& ctx);
- /// Declares one chain to the graph and runs it, ending in the output target.
- void runChain(std::vector<PostProcessPass>& passes, TextureHandle sceneTexture);
+ /// Declares one chain onto an already-begun graph and runs it, ending in the
+ /// output target. @p scene is the resource the first effect reads.
+ void runChain(std::vector<PostProcessPass>& passes, rg::ResourceId scene);
/// The chain's last pass: the copy into the output target's viewport.
void blitPass();
/// Frees a pass's GPU-side param UBO (clearPasses/shutdown).
@@ -276,7 +284,6 @@ private:
resource::ResourceManager& resourceManager_;
Unique<rg::RenderGraph> graph_;
- Unique<Framebuffer> fboOriginal_;
VertexLayoutHandle screen_quad_layout_ = VertexLayoutHandle::Invalid;
BufferHandle screen_quad_vbo_ = BufferHandle::Invalid;
resource::ShaderHandle blitShader_;
@@ -285,11 +292,12 @@ private:
u32 width_ = 0;
u32 height_ = 0;
bool initialized_ = false;
- bool fboOriginalCreated_ = false;
bool inFrame_ = false;
bool bypass_ = false;
bool linear_output_ = false;
bool scene_needs_depth_ = false;
+ /// The graph resource the scene is drawn into, live between begin() and end().
+ rg::ResourceId sceneResource_ = rg::kNoResource;
TextureHandle sceneTexture_ = TextureHandle::Invalid;
FramebufferHandle output_target_fbo_ = FramebufferHandle::Default;
diff --git a/src/esengine/renderer/frame/RenderFrame.cpp b/src/esengine/renderer/frame/RenderFrame.cpp
index 4cb03f57e..66a582dce 100644
--- a/src/esengine/renderer/frame/RenderFrame.cpp
+++ b/src/esengine/renderer/frame/RenderFrame.cpp
@@ -277,14 +277,9 @@ void RenderFrame::begin(const glm::mat4& view_projection, RenderTargetManager::H
// through a target of its own and has to hand this one back when it is done.
void RenderFrame::openPass(const PassClear& clear, RenderTargetManager::Handle target) {
#ifdef ES_ENABLE_POSTPROCESS
- // Linear mode keeps the capture+blit engaged even with zero passes: the
- // final blit is where the mandatory linear->sRGB encode lives (the WebGL2
- // canvas framebuffer cannot be made sRGB).
- bool usePostProcess = post_process_ && post_process_->isInitialized() &&
- ((!post_process_->isBypassed() && post_process_->getPassCount() > 0)
- || linear_color_);
+ const bool usePostProcess = post_process_ && post_process_->isEngaged();
#else
- bool usePostProcess = false;
+ const bool usePostProcess = false;
#endif
// The pass's load-op clear, values carried in the desc (never sticky device
@@ -422,14 +417,9 @@ void RenderFrame::end() {
}
#ifdef ES_ENABLE_POSTPROCESS
- // Linear mode keeps the capture+blit engaged even with zero passes: the
- // final blit is where the mandatory linear->sRGB encode lives (the WebGL2
- // canvas framebuffer cannot be made sRGB).
- bool usePostProcess = post_process_ && post_process_->isInitialized() &&
- ((!post_process_->isBypassed() && post_process_->getPassCount() > 0)
- || linear_color_);
+ const bool usePostProcess = post_process_ && post_process_->isEngaged();
#else
- bool usePostProcess = false;
+ const bool usePostProcess = false;
#endif
if (usePostProcess) {
diff --git a/src/esengine/renderer/graph/RenderGraph.cpp b/src/esengine/renderer/graph/RenderGraph.cpp
index 6b5c2479a..481106fad 100644
--- a/src/esengine/renderer/graph/RenderGraph.cpp
+++ b/src/esengine/renderer/graph/RenderGraph.cpp
@@ -60,6 +60,23 @@ ResourceId RenderGraph::createTarget(const TargetDesc& desc) {
return static_cast<ResourceId>(resources_.size() - 1);
}
+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();
+ return id;
+}
+
+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();
+}
+
void RenderGraph::addPass(PassDesc pass) {
passes_.push_back(std::move(pass));
}
diff --git a/src/esengine/renderer/graph/RenderGraph.hpp b/src/esengine/renderer/graph/RenderGraph.hpp
index 5ceb3f4c7..a122e1772 100644
--- a/src/esengine/renderer/graph/RenderGraph.hpp
+++ b/src/esengine/renderer/graph/RenderGraph.hpp
@@ -114,6 +114,19 @@ public:
/** A target the graph allocates from the pool and recycles after its last read. */
ResourceId createTarget(const TargetDesc& desc);
+ /**
+ * @brief A pooled target filled by a producer OUTSIDE any pass callback.
+ *
+ * @details The scene cannot be written from inside execute(): a frame reaches
+ * the host as several calls with the geometry drawn between them, so
+ * its target has to exist first. Pooled and recycled at its last read
+ * like any transient — the exception is WHEN it is filled, not who owns it.
+ */
+ ResourceId createExternalTarget(const TargetDesc& desc);
+
+ /** The framebuffer behind a resource, for an external target to be drawn into. */
+ FramebufferHandle framebufferOf(ResourceId id) const;
+
void addPass(PassDesc pass);
/** Culls, assigns physical targets, and runs what survives. */
diff --git a/tests/renderer/test_render_graph.cpp b/tests/renderer/test_render_graph.cpp
index e1bfeb1d7..0962f37ff 100644
--- a/tests/renderer/test_render_graph.cpp
+++ b/tests/renderer/test_render_graph.cpp
@@ -186,6 +186,35 @@ int main() {
CHECK(ran.empty(), "a graph with no output runs nothing");
}
+ // --- the scene target: owned and pooled here, filled somewhere else ---
+ {
+ MockGfxDevice d;
+ rg::RenderGraph graph(d);
+
+ graph.begin(256, 128);
+ const auto sceneId = graph.createExternalTarget({});
+ // Drawable BEFORE execute, which is the whole point: a frame reaches the
+ // host as several calls and the geometry lands between them.
+ CHECK(sceneId != rg::kNoResource, "an external target is handed out at declaration");
+ CHECK(graph.framebufferOf(sceneId) != FramebufferHandle::Default,
+ "and names a real framebuffer to draw into");
+ CHECK(d.createFramebufferCalls == 1, "allocated once, at that moment");
+
+ const auto out = graph.importTarget(FramebufferHandle{9}, 256, 128);
+ const auto a = graph.createTarget({});
+ const auto b = graph.createTarget({});
+ graph.addPass(fullscreen("effect", {sceneId}, a));
+ graph.addPass(fullscreen("grade", {a}, b));
+ graph.addPass(fullscreen("blit", {b}, out));
+ graph.execute();
+
+ // Recycled at its last read like any other transient: nothing after
+ // "effect" reads the scene, so "grade" is handed that same physical
+ // target back — two allocations for a three-link chain, not three.
+ CHECK(d.createFramebufferCalls == 2, "the scene target goes back to the pool and is reused");
+ CHECK(graph.pooledTargetCount() == 2, "the pool owns it, not the pipeline");
+ }
+
std::printf(g_failures == 0 ? "\nALL PASS\n" : "\n%d FAILURE(S)\n", g_failures);
return g_failures == 0 ? 0 : 1;
}