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): a frame says what it draws in one place, and runs it once

yhhd11c38732e60
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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 attachment
was written every frame and sampled by nothing, and on WebGPU it was not even
sampleable — `createTexture` gave depth formats `RenderAttachment` alone, with
diff --git a/cmake/ESEngineSources.cmake b/cmake/ESEngineSources.cmake
index 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.cpp
index 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.cpp
index 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::Res
blit.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.hpp
index 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.cpp
index 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_POSTPROCESS
post_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::H
clip_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_POSTPROCESS
const 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
#endif
device_.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 must
diff --git a/src/esengine/renderer/frame/RenderFrame.hpp b/src/esengine/renderer/frame/RenderFrame.hpp
index 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 once
diff --git a/src/esengine/renderer/graph/RenderGraph.cpp b/src/esengine/renderer/graph/RenderGraph.cpp
index 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.hpp
index 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;
};