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.

feat(webgpu): backbuffer follows the viewport - swapchain reconfigures on resize

yhhe2d819efb251
diff --git a/desktop/scripts/headless-verify.mjs b/desktop/scripts/headless-verify.mjs
index 23ccd30e1..947ca7781 100644
--- a/desktop/scripts/headless-verify.mjs
+++ b/desktop/scripts/headless-verify.mjs
@@ -74,7 +74,8 @@ function serveDist() {
}
function finish(result, server) {
- const ok = result.ok && result.capture?.rendered && (result.expect?.ok ?? true) && (result.preview?.ok ?? true);
+ const ok = result.ok && result.capture?.rendered && (result.expect?.ok ?? true) &&
+ (result.resize?.ok ?? true) && (result.preview?.ok ?? true);
console.log(`\n[verify:render] ${ok ? 'PASS' : 'FAIL'} — ${SCENE} (${BACKEND})`);
console.log('DRIVE_RESULT ' + JSON.stringify(result));
process.exitCode = ok ? 0 : 1;
@@ -222,6 +223,29 @@ app.whenReady().then(async () => {
})()`);
await writeFile(process.env.ESTELLA_VERIFY_OUT, Buffer.from(dataUrl.split(',')[1], 'base64'));
}
+ // Optional resize assertion (ESTELLA_VERIFY_RESIZE = "WxH"): shrink the
+ // canvas mid-run, step, and re-capture — the backbuffer must follow the
+ // viewport (the WebGPU swapchain reconfigure; a no-op contract on GL).
+ let resize = null;
+ if (process.env.ESTELLA_VERIFY_RESIZE) {
+ const [rw, rh] = process.env.ESTELLA_VERIFY_RESIZE.split('x').map(Number);
+ await exec(`window.__estellaHeadless.api.resizeViewport(${rw}, ${rh})`);
+ await exec('window.__estellaHeadless.api.step(2, 1 / 60)');
+ if (BACKEND === 'webgpu') {
+ const image = await win.webContents.capturePage({ x: 0, y: 0, width: rw, height: rh });
+ const bmp = image.toBitmap();
+ let nonZero = 0;
+ for (let i = 0; i < bmp.length; i += 4) if (bmp[i] | bmp[i + 1] | bmp[i + 2]) nonZero++;
+ resize = { w: rw, h: rh, nonZeroPixels: nonZero, ok: nonZero > 0 };
+ } else {
+ resize = await exec(`(() => {
+ const c = window.__estellaHeadless.api.captureViewport();
+ let nonZero = 0;
+ for (let i = 0; i < c.rgba.length; i += 4) if (c.rgba[i] | c.rgba[i + 1] | c.rgba[i + 2]) nonZero++;
+ return { w: c.width, h: c.height, nonZeroPixels: nonZero, ok: c.width === ${rw} && c.height === ${rh} && nonZero > 0 };
+ })()`);
+ }
+ }
// Optional offscreen material-preview assertion (ESTELLA_VERIFY_PREVIEW =
// {w,h,rgb:[r,g,b],tol?}): renders a scene material to an offscreen target and checks the
// center pixel — proves the render-to-texture preview primitive, not just the viewport.
@@ -243,7 +267,7 @@ app.whenReady().then(async () => {
return { ok: got.every((g, k) => Math.abs(g - cfg.rgb[k]) <= tol), want: cfg.rgb, got, w, h };
})()`);
}
- finish({ ok: true, entityCount, drawCalls, capture, expect, preview }, server);
+ finish({ ok: true, entityCount, drawCalls, capture, expect, resize, preview }, server);
} catch (e) {
finish({ ok: false, error: String((e && e.stack) || e) }, server);
}
diff --git a/desktop/src/engine/EditorControlSurface.ts b/desktop/src/engine/EditorControlSurface.ts
index c86b673f4..7d60887b1 100644
--- a/desktop/src/engine/EditorControlSurface.ts
+++ b/desktop/src/engine/EditorControlSurface.ts
@@ -281,6 +281,20 @@ export class EditorControlSurfaceImpl {
* Capture right after a step(): the drawing buffer is valid until the next
* frame, and with no rAF loop the headless host's buffer persists.
*/
+ /**
+ * Resize the render canvas (headless drivers): the engine follows on the
+ * next stepped frame — GL tracks the canvas drawing buffer implicitly,
+ * WebGPU reconfigures its swapchain through the same per-frame size source.
+ */
+ resizeViewport(width: number, height: number): void {
+ const canvas = EngineHost.canvas;
+ if (!canvas) throw new Error('resizeViewport requires a render host (no canvas)');
+ canvas.width = width;
+ canvas.height = height;
+ canvas.style.width = `${width}px`;
+ canvas.style.height = `${height}px`;
+ }
+
captureViewport(): ViewportCapture {
const canvas = EngineHost.canvas;
if (!canvas) {
diff --git a/src/esengine/renderer/GfxDevice.hpp b/src/esengine/renderer/GfxDevice.hpp
index 2c4769b71..5ca1183cb 100644
--- a/src/esengine/renderer/GfxDevice.hpp
+++ b/src/esengine/renderer/GfxDevice.hpp
@@ -320,6 +320,19 @@ public:
/** @brief Ends the current pass, restoring the default framebuffer */
virtual void endRenderPass() = 0;
+ /**
+ * @brief Resizes the default backbuffer to the viewport size.
+ * @details GL tracks the canvas drawing buffer implicitly (default no-op);
+ * WebGPU swapchains are fixed-size, so its backend reconfigures
+ * the surface + companion depth-stencil when the size changes.
+ * Called once per frame with the current viewport (cheap when
+ * unchanged); must not be called inside a render pass.
+ */
+ virtual void resizeBackbuffer(u32 width, u32 height) {
+ (void)width;
+ (void)height;
+ }
+
// =========================================================================
// Readback
// =========================================================================
diff --git a/src/esengine/renderer/RenderContext.cpp b/src/esengine/renderer/RenderContext.cpp
index d00b3fc0f..607e1677e 100644
--- a/src/esengine/renderer/RenderContext.cpp
+++ b/src/esengine/renderer/RenderContext.cpp
@@ -149,6 +149,12 @@ void RenderContext::setFrameTime(f32 elapsedSec, u32 viewportW, u32 viewportH) {
glm::vec4(w, h, w > 0.0f ? 1.0f / w : 0.0f, h > 0.0f ? 1.0f / h : 0.0f),
};
device_.updateBuffer(timeUbo_, 0, &time, sizeof(TimeConstants));
+
+ // The backbuffer follows the viewport from the same size source the frame
+ // clock carries: GL tracks the canvas implicitly (no-op), WebGPU
+ // reconfigures its fixed-size swapchain when the size changes. Called at
+ // the top of the frame, before any pass opens.
+ device_.resizeBackbuffer(viewportW, viewportH);
}
} // namespace esengine
diff --git a/src/esengine/renderer/webgpu/WebGPUDevice.cpp b/src/esengine/renderer/webgpu/WebGPUDevice.cpp
index 8d5d19163..76a0ba2d3 100644
--- a/src/esengine/renderer/webgpu/WebGPUDevice.cpp
+++ b/src/esengine/renderer/webgpu/WebGPUDevice.cpp
@@ -132,6 +132,10 @@ bool WebGPUDevice::configureSurface(const char* selector, u32 width, u32 height)
return false;
}
+ return configureSwapchain(width, height);
+}
+
+bool WebGPUDevice::configureSwapchain(u32 width, u32 height) {
// The canvas swapchain prefers BGRA on most platforms; RGBA8 is universally
// valid for emscripten surfaces and keeps readback simple during bring-up.
surface_format_ = WGPUTextureFormat_RGBA8Unorm;
@@ -166,6 +170,16 @@ bool WebGPUDevice::configureSurface(const char* selector, u32 width, u32 height)
return surface_depth_view_ != nullptr;
}
+void WebGPUDevice::resizeBackbuffer(u32 width, u32 height) {
+ if (!surface_ || !device_ || width == 0 || height == 0) return;
+ if (width == surface_width_ && height == surface_height_) return;
+ if (pass_) {
+ ES_LOG_WARN("WebGPUDevice::resizeBackbuffer: ignored inside a render pass");
+ return;
+ }
+ configureSwapchain(width, height);
+}
+
void WebGPUDevice::stubOnce(const char* what) {
for (const auto& logged : stub_logged_) {
if (logged == what) return;
diff --git a/src/esengine/renderer/webgpu/WebGPUDevice.hpp b/src/esengine/renderer/webgpu/WebGPUDevice.hpp
index e62de395b..1f3e0e7a1 100644
--- a/src/esengine/renderer/webgpu/WebGPUDevice.hpp
+++ b/src/esengine/renderer/webgpu/WebGPUDevice.hpp
@@ -121,6 +121,7 @@ public:
void deleteFramebuffer(FramebufferHandle framebuffer) override;
void beginRenderPass(const RenderPassDesc& desc) override;
void endRenderPass() override;
+ void resizeBackbuffer(u32 width, u32 height) override;
void readPixels(i32 x, i32 y, u32 w, u32 h, GfxPixelFormat format, void* data) override;
@@ -192,6 +193,11 @@ private:
/** @brief Logs a not-yet-implemented path once per entry point. */
void stubOnce(const char* what);
+ /** @brief (Re)configures the surface swapchain + companion depth-stencil
+ * at @p width x @p height (configureSurface's second half; also the
+ * resizeBackbuffer implementation). */
+ bool configureSwapchain(u32 width, u32 height);
+
/** @brief Builds (once) and returns the WGPURenderPipeline for a handle,
* in the variant matching the current pass's depth-stencil shape. */
WGPURenderPipeline ensurePipeline(u32 id);