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
feat(renderer): native window surface seam for the WebGPU backend
esenginebfc495da7d06
diff --git a/sdk/src/app.ts b/sdk/src/app.tsindex c10980d65..8d525abdc 100644--- a/sdk/src/app.ts+++ b/sdk/src/app.ts@@ -1041,11 +1041,13 @@ export class App {* via document.querySelector — so the canvas must be in the DOM).* - `default`: the module resolves its own surface (module.initRenderer()).*- * NATIVE (embedded Dawn on iOS/Android) will provide its WebGPU device the same+ * NATIVE (embedded Dawn on iOS/Android) provides its WebGPU device the same* `preinitializedWebGPUDevice` way, but bound to a native surface (CAMetalLayer /* ANativeWindow) rather than a DOM canvas — it uses `{ kind: 'webgpu' }` with- * `canvasSelector` omitted, and the C++/glue native-surface resolution lands with- * the native shell.+ * `canvasSelector` omitted. The C++ renderer seam for this exists:+ * `WebGPUDevice::configureSurface(const NativeSurface&)` builds the surface from a+ * native window handle (the counterpart of this union). What still lands with the+ * native shell is the glue that acquires the Dawn device and calls that overload.*/export type RenderSurfaceSource =| { readonly kind: 'gl-context'; readonly handle: number }diff --git a/src/esengine/renderer/webgpu/WebGPUDevice.cpp b/src/esengine/renderer/webgpu/WebGPUDevice.cppindex 153edae97..2d3b8b8ca 100644--- a/src/esengine/renderer/webgpu/WebGPUDevice.cpp+++ b/src/esengine/renderer/webgpu/WebGPUDevice.cpp@@ -136,6 +136,7 @@ void WebGPUDevice::shutdown() {// Surface (bring-up: a canvas is the Default framebuffer)// =============================================================================+#if defined(__EMSCRIPTEN__)bool WebGPUDevice::configureSurface(const char* selector, u32 width, u32 height) {if (!device_ || !instance_) {ES_LOG_ERROR("WebGPUDevice::configureSurface: no device/instance");@@ -156,6 +157,51 @@ bool WebGPUDevice::configureSurface(const char* selector, u32 width, u32 height)return configureSwapchain(width, height);}+#endif // __EMSCRIPTEN__++#if !defined(__EMSCRIPTEN__)+// The native (iOS/Android) surface source: the same instance + swapchain as the web+// path, but the surface is created from a native window handle instead of a canvas+// selector. Dawn's Metal/Android surface descriptors replace the emscripten one; the+// host owns the CAMetalLayer / ANativeWindow lifetime. Compiled only in a native Dawn+// build (emscripten's emdawnwebgpu has no native window source).+bool WebGPUDevice::configureSurface(const NativeSurface& window, u32 width, u32 height) {+ if (!device_ || !instance_) {+ ES_LOG_ERROR("WebGPUDevice::configureSurface(native): no device/instance");+ return false;+ }+ if (!window.handle) {+ ES_LOG_ERROR("WebGPUDevice::configureSurface(native): null window handle");+ return false;+ }++ WGPUSurfaceDescriptor sd{};+ switch (window.kind) {+ case NativeWindowKind::MetalLayer: {+ WGPUSurfaceSourceMetalLayer metal{};+ metal.chain.sType = WGPUSType_SurfaceSourceMetalLayer;+ metal.layer = window.handle; // CAMetalLayer*+ sd.nextInChain = &metal.chain;+ surface_ = wgpuInstanceCreateSurface(instance_, &sd);+ break;+ }+ case NativeWindowKind::AndroidWindow: {+ WGPUSurfaceSourceAndroidNativeWindow android{};+ android.chain.sType = WGPUSType_SurfaceSourceAndroidNativeWindow;+ android.window = window.handle; // ANativeWindow*+ sd.nextInChain = &android.chain;+ surface_ = wgpuInstanceCreateSurface(instance_, &sd);+ break;+ }+ }+ if (!surface_) {+ ES_LOG_ERROR("WebGPUDevice::configureSurface(native): surface creation failed");+ return false;+ }++ return configureSwapchain(width, height);+}+#endif // !__EMSCRIPTEN__bool WebGPUDevice::configureSwapchain(u32 width, u32 height) {// The canvas swapchain prefers BGRA on most platforms; RGBA8 is universallydiff --git a/src/esengine/renderer/webgpu/WebGPUDevice.hpp b/src/esengine/renderer/webgpu/WebGPUDevice.hppindex 505ed78f1..f5172283a 100644--- a/src/esengine/renderer/webgpu/WebGPUDevice.hpp+++ b/src/esengine/renderer/webgpu/WebGPUDevice.hpp@@ -154,9 +154,38 @@ public:/*** @brief Binds a canvas as the default render target (bring-up entry, not part* of the GfxDevice interface). @p selector is a CSS selector the- * emscripten surface source resolves, e.g. "#canvas".+ * emscripten surface source resolves, e.g. "#canvas". The web build's+ * surface source; a native Dawn build reaches the surface through the+ * {@link NativeSurface} overload instead.*/+#if defined(__EMSCRIPTEN__)bool configureSurface(const char* selector, u32 width, u32 height);+#endif++ /** The kind of native window a non-emscripten (iOS/Android) host draws into. */+ enum class NativeWindowKind { MetalLayer, AndroidWindow };++ /**+ * A native window handle the host hands the renderer in place of a canvas+ * selector: a `CAMetalLayer*` (MetalLayer, iOS/macOS) or an `ANativeWindow*`+ * (AndroidWindow). This is the C++ counterpart of the TS+ * `RenderSurfaceSource { kind: 'webgpu' }` seam — the one point where the+ * embedded-Dawn native host (NOT a WebView) reaches the C++ renderer.+ */+ struct NativeSurface {+ NativeWindowKind kind;+ void* handle;+ };++#if !defined(__EMSCRIPTEN__)+ /**+ * @brief Binds a native window (CAMetalLayer / ANativeWindow) as the default+ * render target — the native shell's boot entry, standing in for the+ * canvas-selector overload. Shares configureSwapchain with the web path;+ * only the surface source differs. Compiled only in a native Dawn build.+ */+ bool configureSurface(const NativeSurface& window, u32 width, u32 height);+#endifusize bufferCount() const { return buffers_.size(); }usize textureCount() const { return textures_.size(); }usize layoutCount() const { return layouts_.size(); }