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-portability seams for WebGPUDevice (instance, present, Auto alpha)

yhh87c9abdc3da6
diff --git a/src/esengine/renderer/webgpu/WebGPUDevice.cpp b/src/esengine/renderer/webgpu/WebGPUDevice.cpp
index 2d3b8b8ca..75030561d 100644
--- a/src/esengine/renderer/webgpu/WebGPUDevice.cpp
+++ b/src/esengine/renderer/webgpu/WebGPUDevice.cpp
@@ -53,10 +53,16 @@ u8 packSamplerKey(TextureFilter minFilter, TextureFilter magFilter,
}
} // namespace
-WebGPUDevice::WebGPUDevice(WGPUDevice device) : device_(device) {
+WebGPUDevice::WebGPUDevice(WGPUDevice device, WGPUInstance instance) : device_(device) {
if (device_) {
queue_ = wgpuDeviceGetQueue(device_);
- instance_ = wgpuCreateInstance(nullptr);
+ if (instance) {
+ instance_ = instance; // native shell shares its instance (surface must match it)
+ owns_instance_ = false;
+ } else {
+ instance_ = wgpuCreateInstance(nullptr); // web/standalone: own one (emscripten singleton)
+ owns_instance_ = true;
+ }
}
}
@@ -129,7 +135,8 @@ void WebGPUDevice::shutdown() {
if (surface_depth_view_) { wgpuTextureViewRelease(surface_depth_view_); surface_depth_view_ = nullptr; }
if (surface_depth_texture_) { wgpuTextureRelease(surface_depth_texture_); surface_depth_texture_ = nullptr; }
if (surface_) { wgpuSurfaceRelease(surface_); surface_ = nullptr; }
- if (instance_) { wgpuInstanceRelease(instance_); instance_ = nullptr; }
+ if (instance_ && owns_instance_) { wgpuInstanceRelease(instance_); }
+ instance_ = nullptr;
}
// =============================================================================
@@ -201,6 +208,10 @@ bool WebGPUDevice::configureSurface(const NativeSurface& window, u32 width, u32
return configureSwapchain(width, height);
}
+
+void WebGPUDevice::present() {
+ if (surface_) wgpuSurfacePresent(surface_);
+}
#endif // !__EMSCRIPTEN__
bool WebGPUDevice::configureSwapchain(u32 width, u32 height) {
@@ -213,7 +224,11 @@ bool WebGPUDevice::configureSwapchain(u32 width, u32 height) {
cfg.usage = WGPUTextureUsage_RenderAttachment;
cfg.width = width;
cfg.height = height;
- cfg.alphaMode = WGPUCompositeAlphaMode_Opaque;
+ // Auto, not Opaque: let the backend pick a mode the surface advertises. A
+ // browser canvas supports Opaque, but a native Vulkan surface may not (e.g.
+ // Adreno on Android only offers Inherit/PreMultiplied) — Configure() rejects
+ // an unsupported mode outright.
+ cfg.alphaMode = WGPUCompositeAlphaMode_Auto;
cfg.presentMode = WGPUPresentMode_Fifo;
wgpuSurfaceConfigure(surface_, &cfg);
surface_width_ = width;
diff --git a/src/esengine/renderer/webgpu/WebGPUDevice.hpp b/src/esengine/renderer/webgpu/WebGPUDevice.hpp
index 8af638e9d..f47150809 100644
--- a/src/esengine/renderer/webgpu/WebGPUDevice.hpp
+++ b/src/esengine/renderer/webgpu/WebGPUDevice.hpp
@@ -52,8 +52,13 @@ public:
* validates the pipeline's color target format against the pass. */
enum ColorVariant : u32 { kColorRgba8 = 0, kColorSrgb8 = 1, kColorRgba16f = 2, kColorVariantCount = 3 };
- /** @brief @p device may be null for bookkeeping-only use (tests, bring-up). */
- explicit WebGPUDevice(WGPUDevice device = nullptr);
+ /** @brief @p device may be null for bookkeeping-only use (tests, bring-up).
+ * @param instance The host's WGPUInstance to share. Web/emscripten passes
+ * null and the device creates its own (the emscripten singleton). A
+ * native shell that already built the instance to acquire the
+ * adapter/device passes it here so the surface is created on the SAME
+ * instance — native Dawn ties a surface to its creating instance. */
+ explicit WebGPUDevice(WGPUDevice device = nullptr, WGPUInstance instance = nullptr);
~WebGPUDevice() override;
void init() override;
@@ -176,6 +181,12 @@ public:
/** @brief Binds a native window as the render target; shares configureSwapchain
* with the web path. Native Dawn build only. */
bool configureSurface(const NativeSurface& window, u32 width, u32 height);
+
+ /** @brief Flips the swapchain to the display. The web path relies on the
+ * browser presenting the canvas after the frame callback; a native
+ * host must present the surface explicitly, once per frame after
+ * endRenderPass. No-op until a surface is configured. */
+ void present();
#endif
usize bufferCount() const { return buffers_.size(); }
usize textureCount() const { return textures_.size(); }
@@ -277,6 +288,7 @@ private:
WGPUDevice device_ = nullptr;
WGPUQueue queue_ = nullptr;
WGPUInstance instance_ = nullptr;
+ bool owns_instance_ = true; ///< False when a native host injected its instance (don't release it).
// Surface (the Default framebuffer target). The companion depth-stencil
// texture mirrors the WebGL canvas's depth+stencil planes — engine stencil