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
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.mdindex cdac0ff9b..ae2c2d3df 100644--- a/sdk/etc/wasm.api.md+++ b/sdk/etc/wasm.api.md@@ -247,7 +247,7 @@ getVelocityPtr: (registry: CppRegistry, entity: number) => numbergl_checkErrors: (context: string) => numbergl_enableErrorCheck: (enabled: boolean) => voidinitRenderer: () => void-initRendererWebGPU: (canvasSelector: string, width: number, height: number, readback: boolean) => boolean+initRendererWebGPU: (canvasSelector: string, width: number, height: number, readback: boolean, preferBGRA: boolean) => booleaninitRendererWithCanvas: (canvasSelector: string) => booleaninitRendererWithContext: (contextHandle: number) => booleanmarkDeviceRestored: (() => void) | undefineddiff --git a/sdk/src/app/app.ts b/sdk/src/app/app.tsindex 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): Aswitch (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.tsindex 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.cppindex 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.cppindex 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_WEBGPUif (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 heightg_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;#endifdiff --git a/src/esengine/renderer/rhi/GfxDevice.hpp b/src/esengine/renderer/rhi/GfxDevice.hppindex 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.cppindex 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 thediff --git a/src/esengine/renderer/webgpu/WebGPUDevice.hpp b/src/esengine/renderer/webgpu/WebGPUDevice.hppindex 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. */