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): render passes — target + clears as one begin/end boundary

yhh39e9bacd8aa8
diff --git a/src/esengine/bindings/PostProcessBindings.cpp b/src/esengine/bindings/PostProcessBindings.cpp
index 5ca58edb1..30aa61352 100644
--- a/src/esengine/bindings/PostProcessBindings.cpp
+++ b/src/esengine/bindings/PostProcessBindings.cpp
@@ -35,7 +35,7 @@ bool postprocess_init(u32 width, u32 height) {
}
g_postProcessPipeline->init(width, height);
- g_device->bindFramebuffer(FramebufferHandle::Default);
+ g_device->endRenderPass();
return g_postProcessPipeline->isInitialized();
}
diff --git a/src/esengine/renderer/Framebuffer.cpp b/src/esengine/renderer/Framebuffer.cpp
index b3714cc27..426fdb52f 100644
--- a/src/esengine/renderer/Framebuffer.cpp
+++ b/src/esengine/renderer/Framebuffer.cpp
@@ -75,11 +75,11 @@ Unique<Framebuffer> Framebuffer::create(GfxDevice& device, const FramebufferSpec
// =============================================================================
void Framebuffer::bind() const {
- if (device_) device_->bindFramebuffer(handle_);
+ if (device_) device_->beginRenderPass({handle_});
}
void Framebuffer::unbind() const {
- if (device_) device_->bindFramebuffer(FramebufferHandle::Default);
+ if (device_) device_->endRenderPass();
}
void Framebuffer::resize(u32 width, u32 height) {
diff --git a/src/esengine/renderer/GLDevice.cpp b/src/esengine/renderer/GLDevice.cpp
index 7330b64b6..829d7de4e 100644
--- a/src/esengine/renderer/GLDevice.cpp
+++ b/src/esengine/renderer/GLDevice.cpp
@@ -907,8 +907,23 @@ void GLDevice::deleteFramebuffer(FramebufferHandle framebuffer) {
if (id != 0) glDeleteFramebuffers(1, &id);
}
-void GLDevice::bindFramebuffer(FramebufferHandle framebuffer) {
- glBindFramebuffer(GL_FRAMEBUFFER, static_cast<GLuint>(framebuffer));
+void GLDevice::beginRenderPass(const RenderPassDesc& desc) {
+ glBindFramebuffer(GL_FRAMEBUFFER, static_cast<GLuint>(desc.target));
+ if (desc.clearColor || desc.clearDepth || desc.clearStencil) {
+ // Load-op semantics: a clear must not be vetoed by write masks a prior
+ // pipeline left restrictive (glClear honors them), so force the cleared
+ // attachments' masks open and drop the cached pipeline — the next
+ // setPipeline re-applies its own masks.
+ if (desc.clearColor) setColorMask(true, true, true, true);
+ if (desc.clearDepth) setDepthWrite(true);
+ if (desc.clearStencil) setStencilMask(0xFF);
+ clear(desc.clearColor, desc.clearDepth, desc.clearStencil);
+ invalidatePipelineCache();
+ }
+}
+
+void GLDevice::endRenderPass() {
+ glBindFramebuffer(GL_FRAMEBUFFER, 0);
}
// =============================================================================
diff --git a/src/esengine/renderer/GLDevice.hpp b/src/esengine/renderer/GLDevice.hpp
index 5486d87d4..9cc430214 100644
--- a/src/esengine/renderer/GLDevice.hpp
+++ b/src/esengine/renderer/GLDevice.hpp
@@ -117,7 +117,8 @@ public:
FramebufferHandle createFramebuffer(const FramebufferDesc& desc) override;
void deleteFramebuffer(FramebufferHandle framebuffer) override;
- void bindFramebuffer(FramebufferHandle framebuffer) override;
+ void beginRenderPass(const RenderPassDesc& desc) override;
+ void endRenderPass() override;
void readPixels(i32 x, i32 y, u32 w, u32 h, GfxPixelFormat format, void* data) override;
diff --git a/src/esengine/renderer/GfxDevice.hpp b/src/esengine/renderer/GfxDevice.hpp
index de47ce9e7..30aea5445 100644
--- a/src/esengine/renderer/GfxDevice.hpp
+++ b/src/esengine/renderer/GfxDevice.hpp
@@ -347,8 +347,20 @@ public:
/** @brief Deletes a framebuffer (its attachment textures are owned by the caller) */
virtual void deleteFramebuffer(FramebufferHandle framebuffer) = 0;
- /** @brief Binds a framebuffer (Default = backbuffer) */
- virtual void bindFramebuffer(FramebufferHandle framebuffer) = 0;
+ // =========================================================================
+ // Render Pass
+ // =========================================================================
+
+ /**
+ * @brief Targets a framebuffer for subsequent draws and applies the pass's clears.
+ * @details Beginning a pass while another is open retargets directly (the GL
+ * model has no explicit pass object); endRenderPass returns to the
+ * backbuffer. A WebGPU backend maps this to real pass boundaries.
+ */
+ virtual void beginRenderPass(const RenderPassDesc& desc) = 0;
+
+ /** @brief Ends the current pass, restoring the default framebuffer */
+ virtual void endRenderPass() = 0;
// =========================================================================
// Readback
diff --git a/src/esengine/renderer/GfxEnums.hpp b/src/esengine/renderer/GfxEnums.hpp
index 6627fe4cb..f769c8ab6 100644
--- a/src/esengine/renderer/GfxEnums.hpp
+++ b/src/esengine/renderer/GfxEnums.hpp
@@ -229,6 +229,20 @@ struct FramebufferDesc {
TextureHandle depthStencil = TextureHandle::Invalid;
};
+/**
+ * @brief One render pass: a target plus which attachments to clear on entry.
+ * @details Clears use the device's current clear color / clear stencil values
+ * and ignore write masks a prior pipeline left restrictive (load-op
+ * semantics) — but they do honor the current scissor rectangle, which
+ * the TS-driven multi-camera flow relies on for per-camera clears.
+ */
+struct RenderPassDesc {
+ FramebufferHandle target = FramebufferHandle::Default;
+ bool clearColor = false;
+ bool clearDepth = false;
+ bool clearStencil = false;
+};
+
// =============================================================================
// Backend Queries (diagnostics / capabilities)
// =============================================================================
diff --git a/src/esengine/renderer/PostProcessPipeline.cpp b/src/esengine/renderer/PostProcessPipeline.cpp
index 71f1e110b..cd2653264 100644
--- a/src/esengine/renderer/PostProcessPipeline.cpp
+++ b/src/esengine/renderer/PostProcessPipeline.cpp
@@ -288,10 +288,8 @@ void PostProcessPipeline::begin() {
ensureFBOs();
if (!fboOriginalCreated_) return;
- auto* device = &device_;
- fboOriginal_->bind();
- device->setViewport(0, 0, width_, height_);
- device->clear(true, true, false);
+ device_.beginRenderPass({fboOriginal_->handle(), /*clearColor=*/true, /*clearDepth=*/true});
+ device_.setViewport(0, 0, width_, height_);
inFrame_ = true;
currentFBO_ = 0;
@@ -400,7 +398,7 @@ void PostProcessPipeline::blitToOutput(TextureHandle texture) {
if (!shader) return;
auto* device = &device_;
- device->bindFramebuffer(output_target_fbo_);
+ device->beginRenderPass({output_target_fbo_});
if (output_vp_w_ > 0 && output_vp_h_ > 0) {
device->setViewport(output_vp_x_, output_vp_y_, output_vp_w_, output_vp_h_);
@@ -447,10 +445,8 @@ void PostProcessPipeline::beginScreenCapture() {
ensureScreenFBO();
if (!screenFBOCreated_) return;
- auto* device = &device_;
- screenFBO_->bind();
- device->setViewport(0, 0, width_, height_);
- device->clear(true, true, false);
+ device_.beginRenderPass({screenFBO_->handle(), /*clearColor=*/true, /*clearDepth=*/true});
+ device_.setViewport(0, 0, width_, height_);
screenCaptureActive_ = true;
}
@@ -508,7 +504,7 @@ void PostProcessPipeline::executeScreenPasses() {
Framebuffer* lastFBO = (pingPong == 0) ? fboA_.get() : fboB_.get();
lastFBO->unbind();
- device->bindFramebuffer(FramebufferHandle::Default);
+ device->endRenderPass();
device->setViewport(0, 0, width_, height_);
blitToOutput(inputTexture);
diff --git a/src/esengine/renderer/RenderFrame.cpp b/src/esengine/renderer/RenderFrame.cpp
index 0bdc1b1de..b18d2373d 100644
--- a/src/esengine/renderer/RenderFrame.cpp
+++ b/src/esengine/renderer/RenderFrame.cpp
@@ -335,12 +335,9 @@ void RenderFrame::replayToDrawCall(i32 stopAtDrawCall) {
auto* rt = target_manager_.get(replay_rt_);
if (!rt) return;
- rt->bind();
- device_.setViewport(0, 0, width_, height_);
device_.setClearColor(0.0f, 0.0f, 0.0f, 0.0f);
- device_.clear(true, false, false);
-
- device_.invalidatePipelineCache();
+ device_.beginRenderPass({rt->getFramebuffer(), /*clearColor=*/true});
+ device_.setViewport(0, 0, width_, height_);
frame_capture_.setReplayMode(stopAtDrawCall + 1);
@@ -376,11 +373,9 @@ void RenderFrame::renderToTarget(ecs::Registry& registry, const glm::mat4& viewP
auto* rt = target_manager_.get(preview_rt_);
if (!rt) return;
- rt->bind();
- device_.setViewport(0, 0, w, h);
device_.setClearColor(0.0f, 0.0f, 0.0f, 0.0f);
- device_.clear(true, false, false);
- device_.invalidatePipelineCache();
+ device_.beginRenderPass({rt->getFramebuffer(), /*clearColor=*/true});
+ device_.setViewport(0, 0, w, h);
// A self-contained collect (begin()'s setup minus post-process) + execute (flush()'s body),
// drawn to the bound preview target. Reuses the real collect+material+execute path so a
diff --git a/tests/renderer/MockGfxDevice.hpp b/tests/renderer/MockGfxDevice.hpp
index f487a5cd7..616b12eda 100644
--- a/tests/renderer/MockGfxDevice.hpp
+++ b/tests/renderer/MockGfxDevice.hpp
@@ -15,7 +15,8 @@ struct MockGfxDevice final : GfxDevice {
// call counters
int useProgramCalls = 0;
int bindTextureCalls = 0;
- int bindFramebufferCalls = 0;
+ int beginRenderPassCalls = 0;
+ int endRenderPassCalls = 0;
int createProgramCalls = 0;
int deleteProgramCalls = 0;
int setUniform1iCalls = 0;
@@ -55,7 +56,7 @@ struct MockGfxDevice final : GfxDevice {
VertexLayoutDesc lastVertexLayoutDesc{};
BufferHandle lastVbo = BufferHandle::Invalid;
BufferHandle lastIbo = BufferHandle::Invalid;
- FramebufferHandle lastFbo = FramebufferHandle::Default;
+ RenderPassDesc lastPassDesc{};
i32 lastUniform1iLoc = -999, lastUniform1iVal = 0;
BufferDesc lastBufferDesc{};
bool lastCreateBufferHadData = false;
@@ -177,7 +178,8 @@ struct MockGfxDevice final : GfxDevice {
return FramebufferHandle{nextFramebufferId++};
}
void deleteFramebuffer(FramebufferHandle) override { ++deleteFramebufferCalls; }
- void bindFramebuffer(FramebufferHandle framebuffer) override { ++bindFramebufferCalls; lastFbo = framebuffer; }
+ void beginRenderPass(const RenderPassDesc& desc) override { ++beginRenderPassCalls; lastPassDesc = desc; }
+ void endRenderPass() override { ++endRenderPassCalls; }
void readPixels(i32, i32, u32, u32, GfxPixelFormat, void*) override {}
diff --git a/tests/renderer/test_texture_fb.cpp b/tests/renderer/test_texture_fb.cpp
index 0d2437ad9..eb60a17b8 100644
--- a/tests/renderer/test_texture_fb.cpp
+++ b/tests/renderer/test_texture_fb.cpp
@@ -119,7 +119,10 @@ int main() {
d.lastFramebufferDesc.depthStencil != TextureHandle::Invalid,
"both attachments are declared in the framebuffer descriptor");
fbo->bind();
- CHECK(d.bindFramebufferCalls >= 1, "bind routes through device.bindFramebuffer");
+ CHECK(d.beginRenderPassCalls == 1 && d.lastPassDesc.target == fbo->handle(),
+ "bind begins a render pass targeting the framebuffer");
+ fbo->unbind();
+ CHECK(d.endRenderPassCalls == 1, "unbind ends the render pass");
}
CHECK(d.deleteFramebufferCalls == 1, "destructor deletes the framebuffer via device");
CHECK(d.deleteTextureCalls == 2, "destructor deletes both attachments via device");