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.

fix(webgpu): a render target's texture can reach a component

esengined4a68d361878
diff --git a/CHANGELOG.md b/CHANGELOG.md
index bec3e0681..fcfada5e8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -27,9 +27,10 @@ published separately; it ships inside the editor.
the target, whose own size sets the resolution, and a released target falls back
to the screen rather than drawing nowhere.
- WebGL2 today. The WebGPU backend cannot yet adopt a device texture into the
- resource table (`importExternalTexture`), so the target a camera fills there
- cannot be handed to a `Sprite`.
+ WebGL2 today. On WebGPU the target now reaches a `Sprite` — adopting a texture
+ the backend already owns is a lookup, not an import, and that stub is gone —
+ but the frame readback returns nothing when one frame holds both an offscreen
+ and a surface pass, so the pixel criterion runs on WebGL2 until that is found.
- **Removed: 26 engine entry points no host called.** Five of them
(`renderer_submitSprites` / `submitUIElements` / `submitBitmapText` /
diff --git a/src/esengine/renderer/webgpu/WebGPUDevice.cpp b/src/esengine/renderer/webgpu/WebGPUDevice.cpp
index 8e4d4ca9f..4275a03fd 100644
--- a/src/esengine/renderer/webgpu/WebGPUDevice.cpp
+++ b/src/esengine/renderer/webgpu/WebGPUDevice.cpp
@@ -44,14 +44,7 @@ u32 dsVariantOf(WGPUTextureFormat format) {
return hasStencilPlanes(format) ? WebGPUDevice::kDsDepthStencil : WebGPUDevice::kDsDepthOnly;
}
-u32 colorVariantOf(WGPUTextureFormat format) {
- switch (format) {
- case WGPUTextureFormat_RGBA8UnormSrgb: return WebGPUDevice::kColorSrgb8;
- case WGPUTextureFormat_RGBA16Float: return WebGPUDevice::kColorRgba16f;
- case WGPUTextureFormat_BGRA8Unorm: return WebGPUDevice::kColorBgra8;
- default: return WebGPUDevice::kColorRgba8;
- }
-}
+
u8 packSamplerKey(TextureFilter minFilter, TextureFilter magFilter,
TextureWrap wrapS, TextureWrap wrapT) {
@@ -730,6 +723,15 @@ const PipelineDesc* WebGPUDevice::pipelineDesc(PipelineHandle handle) const {
// Textures
// =============================================================================
+u32 WebGPUDevice::colorVariantOf(WGPUTextureFormat format) {
+ switch (format) {
+ case WGPUTextureFormat_RGBA8UnormSrgb: return kColorSrgb8;
+ case WGPUTextureFormat_RGBA16Float: return kColorRgba16f;
+ case WGPUTextureFormat_BGRA8Unorm: return kColorBgra8;
+ default: return kColorRgba8;
+ }
+}
+
TextureHandle WebGPUDevice::createTexture(const TextureDesc& desc, const void* pixels) {
if (!isDeviceUsable()) return TextureHandle::Invalid;
if (!device_) {
@@ -831,9 +833,13 @@ TextureHandle WebGPUDevice::createCompressedTexture(const TextureDesc& desc, Gfx
return TextureHandle{id};
}
-TextureHandle WebGPUDevice::importExternalTexture(u32, const TextureDesc&) {
- // GL-id import has no WebGPU meaning; external surfaces arrive as WGPUTexture
- // in a later slice (canvas/video import path).
+TextureHandle WebGPUDevice::importExternalTexture(u32 nativeId, const TextureDesc&) {
+ // A "native id" this backend already owns is one of ours — a render target's
+ // colour plane, adopted so a component can name it. On GL the two ids are the
+ // same number by construction; here the lookup is what makes them one.
+ if (textures_.count(nativeId) != 0) return TextureHandle{nativeId};
+ // A genuinely foreign surface (canvas, video frame) arrives as a WGPUTexture
+ // in a later slice, not as an integer.
stubOnce("importExternalTexture");
return TextureHandle::Invalid;
}
diff --git a/src/esengine/renderer/webgpu/WebGPUDevice.hpp b/src/esengine/renderer/webgpu/WebGPUDevice.hpp
index ae48d2562..dc69b2c6a 100644
--- a/src/esengine/renderer/webgpu/WebGPUDevice.hpp
+++ b/src/esengine/renderer/webgpu/WebGPUDevice.hpp
@@ -57,6 +57,11 @@ public:
kColorRgba8 = 0, kColorBgra8 = 1, kColorSrgb8 = 2, kColorRgba16f = 3, kColorVariantCount = 4,
};
+ /** @brief Which variant slot a pass's colour format uses. Beside the enum
+ * because the two are one decision: a format that shares a slot with
+ * another is a pipeline handed to a pass that rejects it. */
+ static u32 colorVariantOf(WGPUTextureFormat format);
+
/** @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
diff --git a/tests/renderer/test_webgpu_device.cpp b/tests/renderer/test_webgpu_device.cpp
index 372de4e4e..61d0b99dc 100644
--- a/tests/renderer/test_webgpu_device.cpp
+++ b/tests/renderer/test_webgpu_device.cpp
@@ -158,6 +158,21 @@ TEST_CASE("binding-mask scan mirrors the declarations an explicit layout carries
CHECK(scanWGSLBindingMask("no bindings here", 0) == 0u);
}
+TEST_CASE("colour formats that a pass validates apart get variant slots apart") {
+ // WebGPU validates a pipeline's colour format against the pass and rejects
+ // the command buffer when they differ. A surface is BGRA and a render target
+ // RGBA, so a shared slot takes the whole frame down.
+ CHECK(WebGPUDevice::colorVariantOf(WGPUTextureFormat_BGRA8Unorm)
+ != WebGPUDevice::colorVariantOf(WGPUTextureFormat_RGBA8Unorm));
+ CHECK(WebGPUDevice::colorVariantOf(WGPUTextureFormat_RGBA8UnormSrgb)
+ != WebGPUDevice::colorVariantOf(WGPUTextureFormat_RGBA8Unorm));
+ CHECK(WebGPUDevice::colorVariantOf(WGPUTextureFormat_RGBA16Float)
+ != WebGPUDevice::colorVariantOf(WGPUTextureFormat_RGBA8Unorm));
+ // Every slot is inside the variant table the pipeline record allocates.
+ CHECK(WebGPUDevice::colorVariantOf(WGPUTextureFormat_BGRA8Unorm) < WebGPUDevice::kColorVariantCount);
+ CHECK(WebGPUDevice::colorVariantOf(WGPUTextureFormat_RGBA16Float) < WebGPUDevice::kColorVariantCount);
+}
+
TEST_CASE("pass load-ops: full-target clear is a real load-op, a scoped clear is not") {
CHECK(toWGPULoadOp(/*clear*/ true, /*scoped*/ false) == WGPULoadOp_Clear);
CHECK(toWGPULoadOp(true, true) == WGPULoadOp_Load); // region clear → emulate, load first
diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjs
index ec3fd4362..25a67d980 100644
--- a/tools/renderScenes.mjs
+++ b/tools/renderScenes.mjs
@@ -258,7 +258,8 @@ export const SCENES = [
{ id: "ui-text-box", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/ui-text-uinode.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/ui-text-uinode.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "4", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.36,\"y\":0.36,\"rgb\":[46,51,71],\"tol\":20},{\"x\":0.64,\"y\":0.36,\"rgb\":[46,51,71],\"tol\":20},{\"x\":0.5,\"y\":0.7,\"rgb\":[0,0,0],\"tol\":15}]" } },
// Red at the centre exists only if a camera rendered into a texture: the fill
// sits on a layer the screen camera culls, and the screen sprite wears that
- // target. webgl2 only — WebGPU has no importExternalTexture yet.
+ // target. webgl2 only — on WebGPU the frame readback returns nothing when one
+ // frame holds both an offscreen and a surface pass.
{ id: "camera-render-target", tier: "pr", env: { ESTELLA_VERIFY_SCENE: "/scenes/camera-target.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/camera-target.textures.json", ESTELLA_VERIFY_CAMERA_TARGET: "{\"camera\":0,\"sprite\":3,\"width\":128,\"height\":128}", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "4", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.5,\"y\":0.5,\"rgb\":[255,0,0],\"tol\":40}]" } },
{ id: "material-lit", tier: "nightly", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mat-lit.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/mat-lit.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.5,\"y\":0.5,\"rgb\":[0,255,0],\"tol\":50}]" } },
{ id: "material-lit-point", tier: "pr", webgpu: { ESTELLA_VERIFY_EXPECT: "[{\"x\":0.5,\"y\":0.5,\"rgb\":[0,253,0],\"tol\":25},{\"x\":0.75,\"y\":0.5,\"rgb\":[0,52,0],\"tol\":25}]" }, env: { ESTELLA_VERIFY_SCENE: "/scenes/mat-lit-point.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/mat-lit-point.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.5,\"y\":0.5,\"rgb\":[0,255,0],\"tol\":50},{\"x\":0.75,\"y\":0.5,\"rgb\":[0,64,0],\"tol\":60}]" } },