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): a frame says what it draws in one place, and runs it once
yhhd11c38732e60
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 753fd8d2a..401c7917a 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -36,6 +36,26 @@ published separately; it ships inside the editor.- **`estella.mjs export --minify`**, for the targets whose default it is not.+- **A frame states what it draws in one place, and runs it once.** The scene was+ not a pass: `openPass` bound a target, `flush` drew into whatever was bound,+ and `end` ran the post chain through a graph of its own — three places, and a+ fourth wart where the shadow pass had to hand the frame's target back after+ drawing through one of its own. The render graph belongs to the FRAME now, not+ to the post-process pipeline, and the scene is a declared pass on it beside+ the effects that read it: the graph binds its target, sets the camera's rect,+ and calls the draw. One `execute()` per camera runs the lot.++ A pass carries its viewport (`PassDesc.viewportW/H`), which a fullscreen effect+ leaves at zero to mean "all of my target". That is not decoration: opening a+ render pass resets the viewport, so a scene drawing into one camera's slice of+ a shared target has to carry the rect rather than inherit it.++ `RenderGraph` compiles unconditionally now rather than behind+ `ES_ENABLE_POSTPROCESS` — the frame declares its own passes to it whether or+ not a post stack was built in. The frame's GPU time is the graph's, not the+ submit timer plus the chain: the scene runs inside the graph, so adding them+ would have counted it twice.+- **An effect can read the scene's DEPTH.** Nothing could: the depth attachmentwas written every frame and sampled by nothing, and on WebGPU it was not evensampleable — `createTexture` gave depth formats `RenderAttachment` alone, withdiff --git a/cmake/ESEngineSources.cmake b/cmake/ESEngineSources.cmakeindex 2b9fcaaee..9d712b873 100644--- a/cmake/ESEngineSources.cmake+++ b/cmake/ESEngineSources.cmake@@ -18,9 +18,10 @@ 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.+ # Not behind ES_ENABLE_POSTPROCESS: the frame declares its own passes to the+ # graph and borrows their targets from this pool, post stack or no post stack.${ESENGINE_ROOT}/src/esengine/renderer/graph/TargetPool.cpp+ ${ESENGINE_ROOT}/src/esengine/renderer/graph/RenderGraph.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@@ -98,7 +99,6 @@ endif()if(ES_ENABLE_POSTPROCESS)list(APPEND ESENGINE_SOURCES${ESENGINE_ROOT}/src/esengine/renderer/frame/PostProcessPipeline.cpp- ${ESENGINE_ROOT}/src/esengine/renderer/graph/RenderGraph.cpp)endif()diff --git a/src/esengine/bindings/PostProcessBindings.cpp b/src/esengine/bindings/PostProcessBindings.cppindex 7d234540a..40b0829c4 100644--- a/src/esengine/bindings/PostProcessBindings.cpp+++ b/src/esengine/bindings/PostProcessBindings.cpp@@ -101,8 +101,10 @@ void postprocess_begin() {}void postprocess_end() {+ // The chain itself ran inside Renderer.end(), declared to the frame's graph+ // beside the scene pass that feeds it. This closes the capture.if (g_postProcessPipeline) {- g_postProcessPipeline->end();+ g_postProcessPipeline->chainDone();}}diff --git a/src/esengine/renderer/frame/PostProcessPipeline.cpp b/src/esengine/renderer/frame/PostProcessPipeline.cppindex 88182b183..f1b21605e 100644--- a/src/esengine/renderer/frame/PostProcessPipeline.cpp+++ b/src/esengine/renderer/frame/PostProcessPipeline.cpp@@ -30,11 +30,11 @@ namespace esengine {PostProcessPipeline::PostProcessPipeline(GfxDevice& device,RenderContext& context,resource::ResourceManager& resourceManager,- rg::TargetPool& pool)+ rg::RenderGraph& graph): device_(device), context_(context), resourceManager_(resourceManager)- , pool_(&pool) {+ , graph_(&graph) {}PostProcessPipeline::PostProcessPipeline(GfxDevice& device,@@ -112,8 +112,10 @@ GfxPixelFormat PostProcessPipeline::interFormat() const {void PostProcessPipeline::ensureGraph() {if (graph_) return;- graph_ = pool_ ? makeUnique<rg::RenderGraph>(device_, *pool_)- : makeUnique<rg::RenderGraph>(device_);+ // Only the frame-less fallback reaches here; with a frame, graph_ is the+ // frame's from construction and this is a no-op.+ ownedGraph_ = makeUnique<rg::RenderGraph>(device_);+ graph_ = ownedGraph_.get();if (linear_output_) {ES_LOG_INFO("PostProcess intermediates: {}",interFormat() == GfxPixelFormat::RGBA16F ? "RGBA16F (HDR)"@@ -154,7 +156,8 @@ void PostProcessPipeline::shutdown() {screen_quad_layout_ = VertexLayoutHandle::Invalid;}- graph_.reset();+ ownedGraph_.reset();+ graph_ = nullptr;screenFBO_.reset();sceneResource_ = rg::kNoResource;screenCaptureActive_ = false;@@ -358,26 +361,24 @@ void PostProcessPipeline::begin(const f32* clearColor) {inFrame_ = true;}-void PostProcessPipeline::end() {+void PostProcessPipeline::declareChain() {// Gated on inFrame_ alone, not on isEngaged(): whatever begin() opened has// to be resolved even if the answer changed underneath in between.if (!initialized_ || !inFrame_) return;- auto* device = &device_;-- // Blend/depth/stencil/color-mask come from the fullscreen pass pipeline;- // scissor is dynamic state and must be dropped explicitly.- device->invalidatePipelineCache();- device->setScissorTest(false);-+ // Read while the resource still holds its target — the graph hands it back+ // at the last pass that reads it.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();+ // encoder has to be closed before the graph opens the first one of its own.+ device_.endRenderPass();runChain(passes_, sceneResource_);+}- device->invalidatePipelineCache();+void PostProcessPipeline::chainDone() {+ if (!initialized_ || !inFrame_) return;+ device_.invalidatePipelineCache();inFrame_ = false;output_target_fbo_ = FramebufferHandle::Default;}@@ -547,8 +548,6 @@ void PostProcessPipeline::runChain(std::vector<PostProcessPass>& passes, rg::Resblit.write = out;blit.execute = [this](const rg::PassContext&) { blitPass(); };graph_->addPass(std::move(blit));-- graph_->execute();}void PostProcessPipeline::ensureScreenFBO() {@@ -610,6 +609,9 @@ void PostProcessPipeline::executeScreenPasses() {// of its own.graph_->begin(width_, height_);runChain(screenPasses_, graph_->importTexture(sceneTexture_, width_, height_));+ // Its own graph and its own run: this chain composes what every camera drew+ // and happens after the last of them ended, so no frame is declaring here.+ graph_->execute();device->invalidatePipelineCache();}diff --git a/src/esengine/renderer/frame/PostProcessPipeline.hpp b/src/esengine/renderer/frame/PostProcessPipeline.hppindex 7419a527d..e5c5314ba 100644--- a/src/esengine/renderer/frame/PostProcessPipeline.hpp+++ b/src/esengine/renderer/frame/PostProcessPipeline.hpp@@ -80,21 +80,20 @@ struct PostProcessPass {class PostProcessPipeline {public:/**- * @brief Builds a pipeline whose chains draw from the frame's target pool.+ * @brief Builds a pipeline that declares its chains onto the FRAME's graph.*- * @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.+ * @details A chain is not a graph of its own: the frame declares the scene+ * and the effects that read it to one graph and executes it once,+ * so every pass a frame runs is stated in one place.*/PostProcessPipeline(GfxDevice& device, RenderContext& context,- resource::ResourceManager& resourceManager, rg::TargetPool& pool);+ resource::ResourceManager& resourceManager, rg::RenderGraph& graph);/**- * @brief Builds one with no frame behind it; its chains get a pool of their own.+ * @brief Builds one with no frame behind it; it gets a graph of its 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.+ * without a RenderFrame having made one.*/PostProcessPipeline(GfxDevice& device, RenderContext& context,resource::ResourceManager& resourceManager);@@ -172,11 +171,14 @@ public:*/void begin(const f32* clearColor = nullptr);- /**- * @brief Ends and processes all passes- * @details Applies all enabled passes and outputs to screen.- */- void end();+ /** The graph resource the scene is captured into, for the frame to declare+ * its scene pass against. kNoResource when no capture is open. */+ rg::ResourceId sceneResource() const { return inFrame_ ? sceneResource_ : rg::kNoResource; }++ /** Declares this camera's chain onto the frame's graph. The frame runs it. */+ void declareChain();+ /** Closes the capture once the graph has run it. */+ void chainDone();/*** @brief Checks if pipeline is initialized@@ -331,9 +333,9 @@ 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_;+ /// The frame's graph when one was given; `ownedGraph_` otherwise.+ rg::RenderGraph* graph_ = nullptr;+ Unique<rg::RenderGraph> ownedGraph_;VertexLayoutHandle screen_quad_layout_ = VertexLayoutHandle::Invalid;BufferHandle screen_quad_vbo_ = BufferHandle::Invalid;resource::ShaderHandle blitShader_;diff --git a/src/esengine/renderer/frame/RenderFrame.cpp b/src/esengine/renderer/frame/RenderFrame.cppindex cb056167e..8cafd5a4d 100644--- a/src/esengine/renderer/frame/RenderFrame.cpp+++ b/src/esengine/renderer/frame/RenderFrame.cpp@@ -120,7 +120,8 @@ RenderFrame::RenderFrame(GfxDevice& device, RenderContext& context,, context_(context), resource_manager_(resource_manager), pool_(device)- , target_pool_(device) {+ , target_pool_(device)+ , graph_(device, target_pool_) {target_manager_.setDevice(device);}@@ -141,7 +142,7 @@ void RenderFrame::init(u32 width, u32 height) {#ifdef ES_ENABLE_POSTPROCESSpost_process_ = makeUnique<PostProcessPipeline>(device_, context_, resource_manager_,- target_pool_);+ graph_);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@@ -230,6 +231,31 @@ void RenderFrame::resize(u32 width, u32 height) {#endif}+// The scene pass's body. The graph has bound the target and set the camera's+// viewport; this is the draw and the constants it needs current.+void RenderFrame::drawScene() {+ context_.updateCameraConstants(view_projection_);+ // Here and not in flush(): the shadow pass runs before this one and decides+ // which atlas tile each light reads, so the block has to go up after it.+ context_.lights().uploadAndBind();++ gpu_timer_.poll(device_);+ {+ ES_PROFILE_SCOPE("render.submit");+ gpu_timer_.begin(device_);+ draw_list_.execute(device_, pool_, context_.materials(), context_.getWhiteTextureId(),+ &frame_capture_, context_.skinUbo());+ gpu_timer_.end(device_);+ }+ FrameProfiler::get().gpuScope("submit", gpu_timer_.lastMs());++ // Handed over to whatever the graph runs next. Blend/depth/colour-mask come+ // from each fullscreen pass's own pipeline, but scissor is dynamic state and+ // a chain pass would inherit whatever the last scene draw left.+ device_.invalidatePipelineCache();+ device_.setScissorTest(false);+}+// Every target this frame borrowed, given back. Three callers owe it: the end// of a frame, a device loss, and shutdown.void RenderFrame::releaseFrameTargets() {@@ -295,11 +321,25 @@ void RenderFrame::begin(const glm::mat4& view_projection, RenderTargetManager::Hclip_state_.clear();openPass(clear, target);++ // What the scene pass writes. With a chain engaged the capture is already a+ // graph resource (the pipeline declared it when it opened); without one the+ // frame's own target is imported, and the graph culls back from it.+ scene_resource_ = rg::kNoResource;+#ifdef ES_ENABLE_POSTPROCESS+ if (post_process_ && post_process_->isEngaged()) {+ scene_resource_ = post_process_->sceneResource();+ }+#endif+ if (scene_resource_ == rg::kNoResource) {+ graph_.begin(width_, height_);+ scene_resource_ = graph_.importTarget(scene_fbo_, width_, height_);+ }}-// Opening the frame's target: the load-op clear, the post-process capture when one is-// engaged, the default surface otherwise. Its own method because the shadow pass draws-// through a target of its own and has to hand this one back when it is done.+// Opening the frame's target: the load-op clear, the post-process capture when+// one is engaged, the default surface otherwise. Bound EAGERLY, before the graph+// runs, so a host draw between this call and end() lands in the scene.void RenderFrame::openPass(const PassClear& clear, RenderTargetManager::Handle target) {#ifdef ES_ENABLE_POSTPROCESSconst bool usePostProcess = post_process_ && post_process_->isEngaged();@@ -338,7 +378,7 @@ void RenderFrame::openPass(const PassClear& clear, RenderTargetManager::Handle t// began the capture (renderCamera drives pp.begin first) this no-ops.post_process_->begin(pass.clearColorValue);// Then BIND it, clear or no clear: this is where the frame gets its target- // back after the shadow pass drew through one of its own. Skipping that for+ // back after the shadow pass drew through one of its own. Skipping it for// a camera with nothing to clear left the atlas current — a black frame.pass.target = post_process_->currentSceneFBO();device_.beginRenderPass(pass);@@ -358,6 +398,11 @@ void RenderFrame::openPass(const PassClear& clear, RenderTargetManager::Handle t#endifdevice_.beginRenderPass(pass);}++ // What the scene pass will draw into. Bound already, because a host draw+ // between this call and the graph's run (the editor's grid) has to land in+ // the scene; the pass re-opens it with a load, so that work survives.+ scene_fbo_ = pass.target;}void RenderFrame::flush() {@@ -374,25 +419,18 @@ void RenderFrame::flush() {device_.invalidatePipelineCache();// finalize() sorts + coalesces and rewrites per-vertex texIndex into the staging, so it- // must run before upload() ships that staging to the GPU.+ // must run before upload() ships that staging to the GPU. Both stay here rather+ // than riding the pass: the counters below read what finalize decided, and the+ // host asks for them before the graph has run.{ES_PROFILE_SCOPE("render.finalize");draw_list_.finalize(pool_);pool_.upload();}- context_.updateCameraConstants(view_projection_);- context_.lights().uploadAndBind();-- gpu_timer_.poll(device_);- {- ES_PROFILE_SCOPE("render.submit");- gpu_timer_.begin(device_);- draw_list_.execute(device_, pool_, context_.materials(), context_.getWhiteTextureId(),- &frame_capture_, context_.skinUbo());- gpu_timer_.end(device_);- }- FrameProfiler::get().gpuScope("submit", gpu_timer_.lastMs());+ // The rect the scene draws into. Opening a pass resets the viewport, so the+ // pass carries the camera's own rather than inheriting it.+ scene_viewport_ = device_.viewport();stats_.draw_calls = draw_list_.mergedDrawCallCount();for (u32 i = 0; i < draw_list_.commandCount(); ++i) {@@ -452,14 +490,40 @@ void RenderFrame::end() {const bool usePostProcess = false;#endif+ // Everything this camera draws, declared in one place and run once. The+ // scene is a pass like the effects that read it: the graph binds its target,+ // sets the camera's rect and calls drawScene.+ if (scene_resource_ != rg::kNoResource) {+ rg::PassDesc scene;+ scene.name = "scene";+ scene.write = scene_resource_;+ scene.viewportX = static_cast<u32>(std::max(scene_viewport_.x, 0));+ scene.viewportY = static_cast<u32>(std::max(scene_viewport_.y, 0));+ scene.viewportW = scene_viewport_.w;+ scene.viewportH = scene_viewport_.h;+ scene.execute = [this](const rg::PassContext&) { drawScene(); };+ graph_.addPass(std::move(scene));+ }+if (usePostProcess) {#ifdef ES_ENABLE_POSTPROCESS- ES_PROFILE_SCOPE("render.postprocess");+ post_process_->declareChain();+#endif+ }++ {+ ES_PROFILE_SCOPE("render.graph");gpu_timer_pp_.poll(device_);gpu_timer_pp_.begin(device_);- post_process_->end();+ graph_.execute();gpu_timer_pp_.end(device_);- FrameProfiler::get().gpuScope("postprocess", gpu_timer_pp_.lastMs());+ FrameProfiler::get().gpuScope("graph", gpu_timer_pp_.lastMs());+ }+ scene_resource_ = rg::kNoResource;++ if (usePostProcess) {+#ifdef ES_ENABLE_POSTPROCESS+ post_process_->chainDone();#endif} else if (current_target_ != RenderTargetManager::INVALID_HANDLE) {auto* rt = target_manager_.get(current_target_);@@ -468,9 +532,11 @@ void RenderFrame::end() {}}- const f32 submitMs = gpu_timer_.lastMs();- const f32 ppMs = usePostProcess ? gpu_timer_pp_.lastMs() : 0.0f;- stats_.gpu_time_ms = submitMs < 0.0f ? -1.0f : submitMs + (ppMs > 0.0f ? ppMs : 0.0f);+ // The graph's own time is the whole of it — the scene pass runs inside it, so+ // adding the submit timer to this would count the scene twice. The submit+ // timer stays as the scene's own share, published as its gpuScope.+ const f32 graphMs = gpu_timer_pp_.lastMs();+ stats_.gpu_time_ms = graphMs < 0.0f ? gpu_timer_.lastMs() : graphMs;// The frame's pass closes HERE, not at the next begin: a WebGPU backend// submits on endRenderPass, and a surface texture acquired this task mustdiff --git a/src/esengine/renderer/frame/RenderFrame.hpp b/src/esengine/renderer/frame/RenderFrame.hppindex e69ecff2a..c32e6f7c2 100644--- a/src/esengine/renderer/frame/RenderFrame.hpp+++ b/src/esengine/renderer/frame/RenderFrame.hpp@@ -9,6 +9,7 @@#include "../store/LightConstants.hpp"#include "../store/ShadowAtlas.hpp"#include "../graph/TargetPool.hpp"+#include "../graph/RenderGraph.hpp"#include "../RenderTypePlugin.hpp"#ifdef ES_ENABLE_POSTPROCESS#include "./PostProcessPipeline.hpp"@@ -360,6 +361,8 @@ private:* of it is ShadowAtlas's answer rather than the light type's.*/void renderShadowMap(ecs::Registry& registry);+ /// The scene pass's body: the draw, and the constants it needs current.+ void drawScene();/// Gives back every target this frame borrowed from {@link target_pool_}.void releaseFrameTargets();@@ -411,6 +414,18 @@ private:/// 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_;+ /// Every pass a frame runs, declared in one place and executed in end():+ /// the scene, and the post chains that read it. One per CAMERA, which is+ /// what a chain has always been — begin() opens it, end() runs it.+ rg::RenderGraph graph_;+ /// What the scene draws into, declared at begin(): the post capture when a+ /// chain is engaged, the frame's own target otherwise.+ rg::ResourceId scene_resource_ = rg::kNoResource;+ /// The framebuffer behind it, bound eagerly so a host draw between calls+ /// (the editor's grid) lands in the scene rather than on the screen.+ FramebufferHandle scene_fbo_ = FramebufferHandle::Default;+ /// The camera's rect within its target; the scene pass carries it.+ GfxDevice::Viewport scene_viewport_{};/// The atlas this frame borrowed, released at end(). kNoTarget = none.rg::TargetHandle shadow_target_ = rg::kNoTarget;/// Who owns which square of it. Rebuilt every frame: a tile means nothing oncediff --git a/src/esengine/renderer/graph/RenderGraph.cpp b/src/esengine/renderer/graph/RenderGraph.cppindex a8bbeccff..83ac9efde 100644--- a/src/esengine/renderer/graph/RenderGraph.cpp+++ b/src/esengine/renderer/graph/RenderGraph.cpp@@ -189,7 +189,11 @@ void RenderGraph::execute() {for (u32 c = 0; c < 4; ++c) rp.clearColorValue[c] = pass.clearColor[c];}device_.beginRenderPass(rp);- device_.setViewport(0, 0, target.width, target.height);+ if (pass.viewportW > 0 && pass.viewportH > 0) {+ device_.setViewport(pass.viewportX, pass.viewportY, pass.viewportW, pass.viewportH);+ } else {+ device_.setViewport(0, 0, target.width, target.height);+ }inputScratch_.clear();for (u32 unit = 0; unit < pass.reads.size(); ++unit) {diff --git a/src/esengine/renderer/graph/RenderGraph.hpp b/src/esengine/renderer/graph/RenderGraph.hppindex 1dba410cf..27a700a0e 100644--- a/src/esengine/renderer/graph/RenderGraph.hpp+++ b/src/esengine/renderer/graph/RenderGraph.hpp@@ -88,6 +88,18 @@ struct PassDesc {ResourceId write = kNoResource;bool clear = false;f32 clearColor[4] = {0.0f, 0.0f, 0.0f, 1.0f};+ /**+ * @brief The rect of its target this pass draws into. Zero width = all of it.+ *+ * @details Opening a render pass resets the viewport, so a pass that does+ * not cover its whole target has to carry the rect: a fullscreen+ * effect always covers its own, a camera's scene covers whatever+ * slice of a shared target that camera was given.+ */+ u32 viewportX = 0;+ u32 viewportY = 0;+ u32 viewportW = 0;+ u32 viewportH = 0;std::function<void(const PassContext&)> execute;};