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.

docs(native): clarify the staged WebGPU surface seam

esenginea9c931731382
diff --git a/sdk/src/app.ts b/sdk/src/app.ts
index 8d525abdc..7e44d27d1 100644
--- a/sdk/src/app.ts
+++ b/sdk/src/app.ts
@@ -1041,13 +1041,9 @@ 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) 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. 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.
+ * Native (wasm-on-JSC, no DOM): the host injects the device AND an already-built
+ * CAMetalLayer/ANativeWindow surface, so `{ kind: 'webgpu' }` omits `canvasSelector`
+ * and must not reach the '#canvas' fallback.
*/
export type RenderSurfaceSource =
| { readonly kind: 'gl-context'; readonly handle: number }
diff --git a/src/esengine/renderer/webgpu/WebGPUDevice.hpp b/src/esengine/renderer/webgpu/WebGPUDevice.hpp
index f5172283a..8af638e9d 100644
--- a/src/esengine/renderer/webgpu/WebGPUDevice.hpp
+++ b/src/esengine/renderer/webgpu/WebGPUDevice.hpp
@@ -165,25 +165,16 @@ public:
/** 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.
- */
+ /** A `CAMetalLayer*` / `ANativeWindow*` for a native-C++ build; compiled out of
+ * the wasm build, where the host injects an already-built surface instead. */
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.
- */
+ /** @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);
#endif
usize bufferCount() const { return buffers_.size(); }