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.

perf(render): the web swapchain takes the format the canvas prefers

esengine3f1989e39ee0
diff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.md
index cdac0ff9b..ae2c2d3df 100644
--- a/sdk/etc/wasm.api.md
+++ b/sdk/etc/wasm.api.md
@@ -247,7 +247,7 @@ getVelocityPtr: (registry: CppRegistry, entity: number) => number
gl_checkErrors: (context: string) => number
gl_enableErrorCheck: (enabled: boolean) => void
initRenderer: () => void
-initRendererWebGPU: (canvasSelector: string, width: number, height: number, readback: boolean) => boolean
+initRendererWebGPU: (canvasSelector: string, width: number, height: number, readback: boolean, preferBGRA: boolean) => boolean
initRendererWithCanvas: (canvasSelector: string) => boolean
initRendererWithContext: (contextHandle: number) => boolean
markDeviceRestored: (() => void) | undefined
diff --git a/sdk/src/app/app.ts b/sdk/src/app/app.ts
index f6efe6221..984ab488d 100644
--- a/sdk/src/app/app.ts
+++ b/sdk/src/app/app.ts
@@ -1378,8 +1378,14 @@ export function createWebApp(module: ESEngineModule, options?: WebAppOptions): A
switch (surface.kind) {
case 'webgpu': {
const size = options?.getViewportSize?.() ?? { width: 800, height: 600 };
+ // The canvas' own preference: configuring anything else makes the
+ // browser copy the whole frame on every present.
+ const preferBGRA = (navigator as unknown as {
+ gpu?: { getPreferredCanvasFormat?(): string };
+ }).gpu?.getPreferredCanvasFormat?.() === 'bgra8unorm';
if (!module.initRendererWebGPU(
- surface.canvasSelector ?? '#canvas', size.width, size.height, surface.readback === true)) {
+ surface.canvasSelector ?? '#canvas', size.width, size.height,
+ surface.readback === true, preferBGRA)) {
throw new Error(
'WebGPU renderer initialization failed — the module needs a ' +
'preinitializedWebGPUDevice and a WebGPU-enabled engine build.');
diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.ts
index a0527bc02..75f9656d5 100644
--- a/sdk/src/wasm.ts
+++ b/sdk/src/wasm.ts
@@ -156,7 +156,8 @@ export interface ESEngineModule {
* instantiation; '#canvas' resolves to the module's canvas. Returns false
* when the build carries no WebGPU backend or no device was provided.
*/
- initRendererWebGPU(canvasSelector: string, width: number, height: number, readback: boolean): boolean;
+ initRendererWebGPU(canvasSelector: string, width: number, height: number,
+ readback: boolean, preferBGRA: boolean): boolean;
shutdownRenderer(): void;
/**
* Select which EstellaContext the bindings route through. Pass null to clear.
diff --git a/src/esengine/bindings/RendererBindings.cpp b/src/esengine/bindings/RendererBindings.cpp
index 118c6239b..b9552d229 100644
--- a/src/esengine/bindings/RendererBindings.cpp
+++ b/src/esengine/bindings/RendererBindings.cpp
@@ -36,6 +36,7 @@
#include <glm/glm.hpp>
#include <glm/gtc/matrix_transform.hpp>
#include <glm/gtc/type_ptr.hpp>
+#include <utility>
namespace esengine {
@@ -880,12 +881,25 @@ i32 renderer_pollFrameCapture(u32 handle) {
}
}
-/** Copies a ready capture into @p dest (w*h*4 bytes, bottom-up RGBA) and releases it. */
+/**
+ * Copies a ready capture into @p dest (w*h*4 bytes, bottom-up RGBA) and releases it.
+ *
+ * Always RGBA: a surface may be BGRA (which is what a canvas usually prefers, and
+ * configuring anything else costs a copy per present), and every consumer of this
+ * reads channels by index.
+ */
bool renderer_takeFrameCapture(u32 handle, uintptr_t dest, u32 destSize) {
auto* device = g_device;
if (!device || !handle || !dest) return false;
- return device->takeReadback(static_cast<ReadbackHandle>(handle),
- reinterpret_cast<void*>(dest), static_cast<usize>(destSize));
+ if (!device->takeReadback(static_cast<ReadbackHandle>(handle),
+ reinterpret_cast<void*>(dest), static_cast<usize>(destSize))) {
+ return false;
+ }
+ if (device->frameCaptureIsBGRA()) {
+ auto* px = reinterpret_cast<u8*>(dest);
+ for (u32 i = 0; i + 3 < destSize; i += 4) std::swap(px[i], px[i + 2]);
+ }
+ return true;
}
void renderer_renderMaterialPreview(u32 materialId, i32 w, i32 h) {
diff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cpp
index 08933d02b..0e92b2b76 100644
--- a/src/esengine/bindings/WebSDKEntry.cpp
+++ b/src/esengine/bindings/WebSDKEntry.cpp
@@ -191,7 +191,8 @@ bool initRendererInternal(const char* canvasSelector) {
// hands it over via Module.preinitializedWebGPUDevice; the wasm side stays
// fully synchronous. @p width/@p height size the canvas swapchain (the SDK
// passes the canvas backing size it already manages).
-bool initRendererWebGPU(const std::string& canvasSelector, u32 width, u32 height, bool readback) {
+bool initRendererWebGPU(const std::string& canvasSelector, u32 width, u32 height,
+ bool readback, bool preferBGRA) {
#ifdef ES_ENABLE_WEBGPU
if (g_initialized) return true;
@@ -206,6 +207,9 @@ bool initRendererWebGPU(const std::string& canvasSelector, u32 width, u32 height
// that will ask what was drawn (the editor's viewport capture, a pixel gate)
// has to say so now.
device->setSurfaceReadback(readback);
+ // navigator.gpu.getPreferredCanvasFormat(), as the page reported it: any other
+ // format makes the browser copy the whole frame on every present.
+ device->setPreferredSurfaceBGRA(preferBGRA);
if (!device->configureSurface(canvasSelector.c_str(), width, height)) {
ES_LOG_ERROR("initRendererWebGPU: surface configuration failed for '{}'", canvasSelector);
return false;
@@ -217,7 +221,7 @@ bool initRendererWebGPU(const std::string& canvasSelector, u32 width, u32 height
g_activeContext = &legacyCtx().context();
return g_activeContext->init(std::move(device));
#else
- (void)canvasSelector; (void)width; (void)height; (void)readback;
+ (void)canvasSelector; (void)width; (void)height; (void)readback; (void)preferBGRA;
ES_LOG_ERROR("initRendererWebGPU: this build carries no WebGPU backend (ES_ENABLE_WEBGPU off)");
return false;
#endif
diff --git a/src/esengine/renderer/rhi/GfxDevice.hpp b/src/esengine/renderer/rhi/GfxDevice.hpp
index e3a8f3109..3dd667285 100644
--- a/src/esengine/renderer/rhi/GfxDevice.hpp
+++ b/src/esengine/renderer/rhi/GfxDevice.hpp
@@ -547,6 +547,10 @@ public:
return requestReadback(FramebufferHandle::Default, w, h);
}
+ /** @brief Whether a captured frame's bytes are BGRA rather than RGBA — the
+ * surface's choice on a backend that has one, and never GL's. */
+ virtual bool frameCaptureIsBGRA() const { return false; }
+
// =========================================================================
// GPU Timing (optional; EXT_disjoint_timer_query on WebGL2)
// =========================================================================
diff --git a/src/esengine/renderer/webgpu/WebGPUDevice.cpp b/src/esengine/renderer/webgpu/WebGPUDevice.cpp
index 8dc4f31ef..8c9c845cb 100644
--- a/src/esengine/renderer/webgpu/WebGPUDevice.cpp
+++ b/src/esengine/renderer/webgpu/WebGPUDevice.cpp
@@ -334,11 +334,6 @@ static bool isSrgbFormat(WGPUTextureFormat f) {
return f == WGPUTextureFormat_BGRA8UnormSrgb || f == WGPUTextureFormat_RGBA8UnormSrgb;
}
-bool WebGPUDevice::surfaceBytesAreBGRA() const {
- return surface_format_ == WGPUTextureFormat_BGRA8Unorm
- || surface_format_ == WGPUTextureFormat_BGRA8UnormSrgb;
-}
-
void WebGPUDevice::present() {
if (!surface_) return;
wgpuSurfacePresent(surface_);
@@ -349,9 +344,19 @@ void WebGPUDevice::present() {
}
#endif // !__EMSCRIPTEN__
+// Not native-only: a web surface can be BGRA too, and a capture consumer has to
+// know which order the bytes came back in.
+bool WebGPUDevice::surfaceBytesAreBGRA() const {
+ return surface_format_ == WGPUTextureFormat_BGRA8Unorm
+ || surface_format_ == WGPUTextureFormat_BGRA8UnormSrgb;
+}
+
bool WebGPUDevice::configureSwapchain(u32 width, u32 height) {
- // RGBA8 is universally valid for emscripten surfaces and keeps readback simple.
- surface_format_ = WGPUTextureFormat_RGBA8Unorm;
+ // Anything but the canvas' preferred format costs a full-frame copy per
+ // present, and only the page can name it (setPreferredSurfaceBGRA). Readback
+ // asks frameCaptureIsBGRA which order it got.
+ surface_format_ = prefer_surface_bgra_ ? WGPUTextureFormat_BGRA8Unorm
+ : WGPUTextureFormat_RGBA8Unorm;
#if !defined(__EMSCRIPTEN__)
// A native surface may accept nothing of the sort — a CAMetalLayer offers only
// BGRA8Unorm, while Vulkan happens to take RGBA8 — and configuring a format the
diff --git a/src/esengine/renderer/webgpu/WebGPUDevice.hpp b/src/esengine/renderer/webgpu/WebGPUDevice.hpp
index 1e0afd868..6466618f7 100644
--- a/src/esengine/renderer/webgpu/WebGPUDevice.hpp
+++ b/src/esengine/renderer/webgpu/WebGPUDevice.hpp
@@ -220,6 +220,8 @@ public:
* endRenderPass. No-op until a surface is configured. */
void present();
+#endif
+
/**
* @brief Whether bytes read back from the DEFAULT framebuffer are BGRA rather
* than RGBA.
@@ -228,7 +230,17 @@ public:
* anyone writing an image has to ask rather than assume.
*/
bool surfaceBytesAreBGRA() const;
-#endif
+
+ bool frameCaptureIsBGRA() const override { return surfaceBytesAreBGRA(); }
+
+ /**
+ * @brief The surface format the host says its canvas prefers.
+ *
+ * Only the page can answer it (`navigator.gpu.getPreferredCanvasFormat()`),
+ * and configuring anything else costs a full-frame copy per present. Must be
+ * set BEFORE the surface is configured.
+ */
+ void setPreferredSurfaceBGRA(bool bgra) { prefer_surface_bgra_ = bgra; }
/**
* @brief Configure the swapchain with CopySrc, so {@link captureNextFrame}
@@ -386,6 +398,8 @@ private:
// masks and depth-tested draws target the backbuffer and expect them.
WGPUSurface surface_ = nullptr;
WGPUTextureFormat surface_format_ = WGPUTextureFormat_RGBA8Unorm;
+ /** Whether the host's canvas prefers BGRA8 (see setPreferredSurfaceBGRA). */
+ bool prefer_surface_bgra_ = false;
/** Whether the surface was configured with CopySrc — see setSurfaceReadback. */
bool surface_readback_ = false;
/** The pass being recorded draws to the surface, so a capture rides its encoder. */