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(renderer): native window surface seam for the WebGPU backend

esenginebfc495da7d06
diff --git a/sdk/src/app.ts b/sdk/src/app.ts
index 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.cpp
index 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 universally
diff --git a/src/esengine/renderer/webgpu/WebGPUDevice.hpp b/src/esengine/renderer/webgpu/WebGPUDevice.hpp
index 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);
+#endif
usize bufferCount() const { return buffers_.size(); }
usize textureCount() const { return textures_.size(); }
usize layoutCount() const { return layouts_.size(); }