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(renderer): the graph owns the scene target, and the frame asks once whether it is captured
yhh55b4d49b0b5e
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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.cppindex 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.hppindex 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.cppindex 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;#endifif (usePostProcess) {diff --git a/src/esengine/renderer/graph/RenderGraph.cpp b/src/esengine/renderer/graph/RenderGraph.cppindex 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.hppindex 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.cppindex 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;}