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(render): the WebGPU backend draws the scene and the backbuffer multisampled
esengine3561766d673f
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 010d679a0..6e42eb2f8 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -16,6 +16,13 @@ published separately; it ships inside the editor.### Added+- **Geometry edges are anti-aliased on WebGPU, which is every native build.** MSAA was+ wired on WebGL2 only, so an iOS, Android, desktop or Steam package — all of which run on+ WebGPU — drew hard stairstep edges. The WebGPU backend now renders the scene and the+ backbuffer multisampled (4× by default, `createWebApp({ msaaSamples })` to change or turn+ off) and resolves both, including the depth buffer WebGPU cannot resolve by itself, so+ effects that read scene depth keep working.+- **The build size report says why a file is in your package, and what changed since thelast build.** A big texture now names the chain that pulled it in — the scene, prefab ormaterial that references it, or the rule that force-included it (a subpackage group, andiff --git a/docs/astro/src/content/docs/graphics/post-processing.mdx b/docs/astro/src/content/docs/graphics/post-processing.mdxindex be5a4cb82..159102f31 100644--- a/docs/astro/src/content/docs/graphics/post-processing.mdx+++ b/docs/astro/src/content/docs/graphics/post-processing.mdx@@ -27,6 +27,15 @@ several can stack in one frame at no extra target cost beyond the passes.| `outline` | Ink-edge outlines (Sobel edge darkening) | `intensity`, `threshold`, `thickness` || `grayscale` | Desaturate | `intensity` |+### Anti-aliasing before the chain++Geometry edges are smoothed by **MSAA on the scene itself**, not by an effect: 4×+by default, on WebGL2 and on WebGPU — which is what every native build (iOS,+Android, desktop, Steam) runs on. `createWebApp({ msaaSamples })` sizes it, and+`msaaSamples: 1` turns it off where the fill cost matters more than the edges.+`fxaa` is the cheaper, blurrier alternative for devices where even one sample+extra is too much.+The uniform names above are the friendly labels; **in code they are `u_`-prefixed**(`u_intensity`, `u_exposure`, …). Most effects are identity at their defaults(`colorGrade`, `blur`, `chromaticAberration`, `fxaa`, `lensDistortion`, `lutGrade`),diff --git a/docs/astro/src/content/docs/zh-cn/graphics/post-processing.mdx b/docs/astro/src/content/docs/zh-cn/graphics/post-processing.mdxindex a157d491d..5950d8b51 100644--- a/docs/astro/src/content/docs/zh-cn/graphics/post-processing.mdx+++ b/docs/astro/src/content/docs/zh-cn/graphics/post-processing.mdx@@ -26,6 +26,13 @@ Estella 通过 ping-pong 帧缓冲运行全屏后处理。加一个 `PostProcess| `outline` | 墨线描边(Sobel 边缘压暗) | `intensity`、`threshold`、`thickness` || `grayscale` | 去色 | `intensity` |+### 链路之前的抗锯齿++几何边缘由**场景本身的 MSAA** 抹平,不是某个效果做的:默认 4×,WebGL2 与 WebGPU 都有——+所有原生包(iOS、Android、桌面、Steam)跑的都是 WebGPU。用+`createWebApp({ msaaSamples })` 调它的大小,`msaaSamples: 1` 在填充率比边缘更要紧的设备上关掉它。+`fxaa` 是更便宜也更糊的替代品,留给连多一个采样都吃不下的设备。+上面是友好标签;**在代码里它们带 `u_` 前缀**(`u_intensity`、`u_exposure`……)。多数效果在默认值下是恒等(`colorGrade`、`blur`、`chromaticAberration`、`fxaa`、`lensDistortion`、`lutGrade`),加进去不调参不改画面。少数一加就可见——`grayscale`(完全去色)、`vignette`、diff --git a/src/esengine/renderer/frame/PostProcessPipeline.cpp b/src/esengine/renderer/frame/PostProcessPipeline.cppindex 68ad1126f..c7ab1fe94 100644--- a/src/esengine/renderer/frame/PostProcessPipeline.cpp+++ b/src/esengine/renderer/frame/PostProcessPipeline.cpp@@ -233,6 +233,9 @@ u32 PostProcessPipeline::addPass(const std::string& name, resource::ShaderHandle*/void PostProcessPipeline::applySampleRequest() {scene_samples_ = std::clamp(requested_samples_, 1u, device_.maxSamples());+ // A frame with no chain draws straight to the backbuffer, which on a surface+ // the host does not antialias needs the same answer — one setting, both paths.+ device_.setSurfaceSamples(scene_samples_);}void PostProcessPipeline::setRequestedSamples(u32 samples) {diff --git a/src/esengine/renderer/rhi/Framebuffer.cpp b/src/esengine/renderer/rhi/Framebuffer.cppindex e2f8bf546..0d1a21c48 100644--- a/src/esengine/renderer/rhi/Framebuffer.cpp+++ b/src/esengine/renderer/rhi/Framebuffer.cpp@@ -143,7 +143,10 @@ bool Framebuffer::initialize() {if (samples > 1) {colorDesc.samples = 1;resolveColor_ = device_->createTexture(colorDesc, GfxContent::transient(), nullptr);- if (spec_.depthStencil) {+ // Depth resolves only where the backend can: WebGPU has no depth resolve,+ // and a twin nothing ever writes would hand an effect an empty depth+ // buffer that looks like a working one.+ if (spec_.depthStencil && device_->resolvesDepth()) {depthDesc.samples = 1;resolveDepth_ = device_->createTexture(depthDesc, GfxContent::transient(), nullptr);}diff --git a/src/esengine/renderer/rhi/GLDevice.hpp b/src/esengine/renderer/rhi/GLDevice.hppindex 6c24a3cd5..5686e5103 100644--- a/src/esengine/renderer/rhi/GLDevice.hpp+++ b/src/esengine/renderer/rhi/GLDevice.hpp@@ -59,6 +59,8 @@ public:bool supportsCompressedFormat(GfxCompressedFormat format) override;bool supportsFloatTargets() override;u32 maxSamples() override;+ /** A GL blit resolves depth as well as colour. */+ bool resolvesDepth() const override { return true; }bool supportsShaderLanguage(GfxShaderLanguage language) const override {return language == GfxShaderLanguage::GLSL_ES300;diff --git a/src/esengine/renderer/rhi/GfxDevice.hpp b/src/esengine/renderer/rhi/GfxDevice.hppindex d148a629a..cdae0994a 100644--- a/src/esengine/renderer/rhi/GfxDevice.hpp+++ b/src/esengine/renderer/rhi/GfxDevice.hpp@@ -438,6 +438,22 @@ public:*/virtual u32 maxSamples() = 0;+ /**+ * @brief Whether this backend can resolve a multisampled DEPTH attachment.+ * @details GL blits one; WebGPU has no depth resolve at all, so a pass that+ * SAMPLES scene depth cannot run multisampled there. Colour resolves+ * on both, which is what MSAA is usually asked for.+ */+ virtual bool resolvesDepth() const { return false; }++ /**+ * @brief Asks for the backbuffer to be drawn with this many samples.+ * @details Only a backend whose surface is NOT antialiased by the host has+ * anything to do here: a WebGL canvas is created antialiased, a+ * WebGPU surface texture never is. Ignored where it is free.+ */+ virtual void setSurfaceSamples(u32 samples) { (void)samples; }+// =========================================================================// Shader Programs// =========================================================================diff --git a/src/esengine/renderer/webgpu/WebGPUDevice.cpp b/src/esengine/renderer/webgpu/WebGPUDevice.cppindex 519d261a2..707ffaf54 100644--- a/src/esengine/renderer/webgpu/WebGPUDevice.cpp+++ b/src/esengine/renderer/webgpu/WebGPUDevice.cpp@@ -74,10 +74,10 @@ WebGPUDevice::~WebGPUDevice() {shutdown();}-// MSAA is not wired on this backend yet: its targets are all sampleCount 1 and-// its pipelines multisample.count 1, so a caller must not ask for more — a-// target that did would resolve out of an attachment that was never multisampled.-u32 WebGPUDevice::maxSamples() { return 1; }+// One and four: what WebGPU guarantees for every renderable format. A target+// asking for more gets four, and its pipelines are built to match the pass they+// draw into — which WebGPU validates, unlike GL.+u32 WebGPUDevice::maxSamples() { return kMsaaSamples; }void WebGPUDevice::init() {captureDeviceIdentity();@@ -228,6 +228,16 @@ void WebGPUDevice::releaseDeviceObjects() {clear_pipelines_.clear();if (clear_layout_) { wgpuPipelineLayoutRelease(clear_layout_); clear_layout_ = nullptr; }if (clear_bgl_) { wgpuBindGroupLayoutRelease(clear_bgl_); clear_bgl_ = nullptr; }+ // The depth-resolve family, for the same reason: every one of these belongs to+ // the device that made it, and Dawn refuses one from the generation before.+ for (auto& [key, pipeline] : depth_resolve_pipelines_) {+ if (pipeline) wgpuRenderPipelineRelease(pipeline);+ }+ depth_resolve_pipelines_.clear();+ if (depth_resolve_layout_) { wgpuPipelineLayoutRelease(depth_resolve_layout_); depth_resolve_layout_ = nullptr; }+ if (depth_resolve_bgl_) { wgpuBindGroupLayoutRelease(depth_resolve_bgl_); depth_resolve_bgl_ = nullptr; }+ if (depth_resolve_vs_) { wgpuShaderModuleRelease(depth_resolve_vs_); depth_resolve_vs_ = nullptr; }+ if (depth_resolve_fs_) { wgpuShaderModuleRelease(depth_resolve_fs_); depth_resolve_fs_ = nullptr; }for (auto& [key, layout] : pipeline_layouts_) {if (layout) wgpuPipelineLayoutRelease(layout);}@@ -245,6 +255,10 @@ void WebGPUDevice::releaseDeviceObjects() {samplers_.clear();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_msaa_view_) { wgpuTextureViewRelease(surface_msaa_view_); surface_msaa_view_ = nullptr; }+ if (surface_msaa_texture_) { wgpuTextureRelease(surface_msaa_texture_); surface_msaa_texture_ = nullptr; }+ surface_msaa_width_ = surface_msaa_height_ = 0;+ surface_msaa_samples_ = 0;if (surface_) { wgpuSurfaceRelease(surface_); surface_ = nullptr; }// Sizes are kept: a re-configured surface has to come back the same shape,// and the depth companion is rebuilt against them.@@ -319,6 +333,11 @@ bool WebGPUDevice::configureSurface(const NativeSurface& window, u32 width, u32if (surface_depth_view_) { wgpuTextureViewRelease(surface_depth_view_); surface_depth_view_ = nullptr; }if (surface_depth_texture_) { wgpuTextureRelease(surface_depth_texture_); surface_depth_texture_ = nullptr; }surface_depth_width_ = surface_depth_height_ = 0;+ if (surface_msaa_view_) { wgpuTextureViewRelease(surface_msaa_view_); surface_msaa_view_ = nullptr; }+ if (surface_msaa_texture_) { wgpuTextureRelease(surface_msaa_texture_); surface_msaa_texture_ = nullptr; }+ surface_msaa_width_ = surface_msaa_height_ = 0;+ surface_msaa_samples_ = 0;+WGPUSurfaceDescriptor sd{};switch (window.kind) {@@ -506,7 +525,8 @@ bool WebGPUDevice::configureSwapchain(u32 width, u32 height) {* that is dropped.*/bool WebGPUDevice::ensureSurfaceDepth(u32 width, u32 height) {- if (surface_depth_view_ && width == surface_depth_width_ && height == surface_depth_height_) {+ if (surface_depth_view_ && width == surface_depth_width_ && height == surface_depth_height_+ && surface_depth_samples_ == surface_samples_) {return true;}if (surface_depth_view_) { wgpuTextureViewRelease(surface_depth_view_); surface_depth_view_ = nullptr; }@@ -516,17 +536,56 @@ bool WebGPUDevice::ensureSurfaceDepth(u32 width, u32 height) {dd.format = WGPUTextureFormat_Depth24PlusStencil8;dd.size = WGPUExtent3D{width, height, 1};dd.mipLevelCount = 1;- dd.sampleCount = 1;+ // Every attachment of a pass shares its sample count, so the backbuffer's+ // depth follows the colour it is paired with.+ dd.sampleCount = surface_samples_;dd.usage = WGPUTextureUsage_RenderAttachment;surface_depth_texture_ = wgpuDeviceCreateTexture(device_, &dd);if (surface_depth_texture_) {surface_depth_view_ = wgpuTextureCreateView(surface_depth_texture_, nullptr);surface_depth_width_ = width;surface_depth_height_ = height;+ surface_depth_samples_ = surface_samples_;}return surface_depth_view_ != nullptr;}+/**+ * The backbuffer's multisampled companion: what a surface pass draws into when+ * the project asks for MSAA, resolving into the surface texture at pass end. A+ * WebGL canvas is created antialiased; a WebGPU surface texture never is, so+ * this is where the two backends are made to agree.+ */+bool WebGPUDevice::ensureSurfaceMsaa(u32 width, u32 height) {+ if (surface_samples_ <= 1) {+ if (surface_msaa_view_) { wgpuTextureViewRelease(surface_msaa_view_); surface_msaa_view_ = nullptr; }+ if (surface_msaa_texture_) { wgpuTextureRelease(surface_msaa_texture_); surface_msaa_texture_ = nullptr; }+ surface_msaa_samples_ = 0;+ return false;+ }+ if (surface_msaa_view_ && width == surface_msaa_width_ && height == surface_msaa_height_+ && surface_samples_ == surface_msaa_samples_) {+ return true;+ }+ if (surface_msaa_view_) { wgpuTextureViewRelease(surface_msaa_view_); surface_msaa_view_ = nullptr; }+ if (surface_msaa_texture_) { wgpuTextureRelease(surface_msaa_texture_); surface_msaa_texture_ = nullptr; }+ WGPUTextureDescriptor cd{};+ cd.dimension = WGPUTextureDimension_2D;+ cd.format = surface_format_;+ cd.size = WGPUExtent3D{width, height, 1};+ cd.mipLevelCount = 1;+ cd.sampleCount = surface_samples_;+ cd.usage = WGPUTextureUsage_RenderAttachment;+ surface_msaa_texture_ = wgpuDeviceCreateTexture(device_, &cd);+ if (surface_msaa_texture_) {+ surface_msaa_view_ = wgpuTextureCreateView(surface_msaa_texture_, nullptr);+ surface_msaa_width_ = width;+ surface_msaa_height_ = height;+ surface_msaa_samples_ = surface_samples_;+ }+ return surface_msaa_view_ != nullptr;+}+void WebGPUDevice::resizeBackbuffer(u32 width, u32 height) {if (!surface_ || !device_ || width == 0 || height == 0) return;if (width == surface_width_ && height == surface_height_) return;@@ -771,7 +830,7 @@ bool WebGPUDevice::makeTexture(const TextureDesc& desc, const void* pixels, Texttd.format = toWGPUTextureFormat(desc.format);td.size = WGPUExtent3D{desc.width, desc.height, 1};td.mipLevelCount = 1;- td.sampleCount = 1;+ td.sampleCount = desc.samples > 1 ? kMsaaSamples : 1;// Depth-stencil takes no upload and no readback (writeTexture cannot fill// it, CopySrc is refused on depth24plus) but IS sampled: an effect reads the// scene's depth. Colour carries CopySrc for the async readback seam.@@ -779,6 +838,14 @@ bool WebGPUDevice::makeTexture(const TextureDesc& desc, const void* pixels, Text? (WGPUTextureUsage_TextureBinding | WGPUTextureUsage_RenderAttachment): (WGPUTextureUsage_TextureBinding | WGPUTextureUsage_CopyDst |WGPUTextureUsage_CopySrc | WGPUTextureUsage_RenderAttachment);+ // No copies: invalid on a multisampled texture. Depth keeps TextureBinding+ // because resolveDepthAttachment samples it; colour is read through the+ // single-sample twin the pass resolves into.+ if (td.sampleCount > 1) {+ td.usage = isDepthFormat(td.format)+ ? (WGPUTextureUsage_RenderAttachment | WGPUTextureUsage_TextureBinding)+ : WGPUTextureUsage_RenderAttachment;+ }WGPUTexture texture = wgpuDeviceCreateTexture(device_, &td);if (!texture) {@@ -808,7 +875,8 @@ bool WebGPUDevice::makeTexture(const TextureDesc& desc, const void* pixels, Textout = TextureRec{texture, view, sampleView,desc.width, desc.height, td.format, desc.format,- packSamplerKey(desc.minFilter, desc.magFilter, desc.wrapS, desc.wrapT)};+ packSamplerKey(desc.minFilter, desc.magFilter, desc.wrapS, desc.wrapT),+ td.sampleCount};if (pixels && !isDepthFormat(td.format)) {// desc.flipY, not false: the caller's orientation request has to reach the@@ -1107,7 +1175,8 @@ WGPURenderPipeline WebGPUDevice::ensurePipeline(u32 id) {if (!described || !device_) return nullptr;PipelineRec& built = pipelines_[id];const u32 dsVariant = dsVariantOf(pass_ds_format_);- const u32 variant = dsVariant * kColorVariantCount + colorVariantOf(pass_color_format_);+ const u32 variant = (dsVariant * kColorVariantCount + colorVariantOf(pass_color_format_))+ * kSampleVariantCount + (pass_samples_ > 1 ? kMultiSample : kSingleSample);if (built.variants[variant]) return built.variants[variant];const PipelineDesc& desc = *described;@@ -1175,7 +1244,9 @@ WGPURenderPipeline WebGPUDevice::ensurePipeline(u32 id) {pd.primitive.topology = WGPUPrimitiveTopology_TriangleList;pd.primitive.frontFace = WGPUFrontFace_CCW;pd.primitive.cullMode = toWGPUCullMode(desc.cullEnabled, desc.cullFront);- pd.multisample.count = 1;+ // The pass's count, which WebGPU validates against the attachment: a pipeline+ // built for one sample cannot draw into a multisampled target at all.+ pd.multisample.count = pass_samples_;pd.multisample.mask = 0xFFFFFFFFu;pd.fragment = &fragment;WGPUDepthStencilState ds{};@@ -1231,6 +1302,138 @@ WGPUSampler WebGPUDevice::samplerFor(u8 key) {return sampler;}+// =============================================================================+// Depth resolve — the half WebGPU does not do: a depth attachment has no+// resolveTarget, so a fullscreen pass writes sample 0 into the single-sample+// twin. Stencil does not come along; a shader cannot write it.+// =============================================================================++WGPURenderPipeline WebGPUDevice::ensureDepthResolvePipeline(WGPUTextureFormat format) {+ const u32 key = static_cast<u32>(format);+ auto it = depth_resolve_pipelines_.find(key);+ if (it != depth_resolve_pipelines_.end()) return it->second;+ if (!device_) return nullptr;++ static const char* kVS = R"(+@vertex fn vs_main(@builtin(vertex_index) i : u32) -> @builtin(position) vec4f {+ var p = array<vec2f, 3>(vec2f(-1.0, -3.0), vec2f(3.0, 1.0), vec2f(-1.0, 1.0));+ return vec4f(p[i], 0.0, 1.0);+}+)";+ static const char* kFS = R"(+@group(0) @binding(0) var src : texture_depth_multisampled_2d;+@fragment fn fs_main(@builtin(position) pos : vec4f) -> @builtin(frag_depth) f32 {+ return textureLoad(src, vec2i(i32(pos.x), i32(pos.y)), 0);+}+)";+ auto makeModule = [&](const char* code) {+ WGPUShaderSourceWGSL wgsl{};+ wgsl.chain.sType = WGPUSType_ShaderSourceWGSL;+ wgsl.code = sv(code);+ WGPUShaderModuleDescriptor md{};+ md.nextInChain = &wgsl.chain;+ return wgpuDeviceCreateShaderModule(device_, &md);+ };+ if (!depth_resolve_vs_) depth_resolve_vs_ = makeModule(kVS);+ if (!depth_resolve_fs_) depth_resolve_fs_ = makeModule(kFS);+ if (!depth_resolve_bgl_) {+ WGPUBindGroupLayoutEntry ble{};+ ble.binding = 0;+ ble.visibility = WGPUShaderStage_Fragment;+ ble.texture.sampleType = WGPUTextureSampleType_Depth;+ ble.texture.viewDimension = WGPUTextureViewDimension_2D;+ ble.texture.multisampled = true;+ WGPUBindGroupLayoutDescriptor bld{};+ bld.entryCount = 1;+ bld.entries = &ble;+ depth_resolve_bgl_ = wgpuDeviceCreateBindGroupLayout(device_, &bld);+ WGPUPipelineLayoutDescriptor pld{};+ pld.bindGroupLayoutCount = 1;+ pld.bindGroupLayouts = &depth_resolve_bgl_;+ depth_resolve_layout_ = wgpuDeviceCreatePipelineLayout(device_, &pld);+ }++ WGPURenderPipelineDescriptor pd{};+ pd.layout = depth_resolve_layout_;+ pd.vertex.module = depth_resolve_vs_;+ pd.vertex.entryPoint = sv("vs_main");+ pd.primitive.topology = WGPUPrimitiveTopology_TriangleList;+ pd.primitive.frontFace = WGPUFrontFace_CCW;+ pd.primitive.cullMode = WGPUCullMode_None;+ pd.multisample.count = 1;+ pd.multisample.mask = 0xFFFFFFFFu;+ // No colour target: the pass writes depth and nothing else.+ WGPUFragmentState fragment{};+ fragment.module = depth_resolve_fs_;+ fragment.entryPoint = sv("fs_main");+ fragment.targetCount = 0;+ pd.fragment = &fragment;+ WGPUDepthStencilState ds{};+ ds.format = format;+ ds.depthWriteEnabled = WGPUOptionalBool_True;+ ds.depthCompare = WGPUCompareFunction_Always;+ WGPUStencilFaceState face{};+ face.compare = WGPUCompareFunction_Always;+ face.failOp = WGPUStencilOperation_Keep;+ face.depthFailOp = WGPUStencilOperation_Keep;+ face.passOp = WGPUStencilOperation_Keep;+ ds.stencilFront = face;+ ds.stencilBack = face;+ ds.stencilReadMask = 0xFFFFFFFFu;+ ds.stencilWriteMask = 0u;+ pd.depthStencil = &ds;++ WGPURenderPipeline pipeline = wgpuDeviceCreateRenderPipeline(device_, &pd);+ if (!pipeline) ES_LOG_ERROR("WebGPUDevice: depth resolve pipeline creation failed");+ depth_resolve_pipelines_[key] = pipeline;+ return pipeline;+}++void WebGPUDevice::resolveDepthAttachment(u32 msaaDepth, u32 resolveDepth) {+ if (!device_ || !encoder_) return;+ auto srcIt = textures_.find(msaaDepth);+ auto dstIt = textures_.find(resolveDepth);+ if (srcIt == textures_.end() || dstIt == textures_.end()) return;+ WGPURenderPipeline pipeline = ensureDepthResolvePipeline(dstIt->second.format);+ if (!pipeline) return;++ // The MULTISAMPLED view, not the depth-only sample view: a multisampled depth+ // texture is read through `texture_depth_multisampled_2d`, whose view carries+ // every aspect the texture has.+ WGPUBindGroupEntry entry{};+ entry.binding = 0;+ entry.textureView = srcIt->second.sampleView;+ WGPUBindGroupDescriptor bgd{};+ bgd.layout = depth_resolve_bgl_;+ bgd.entryCount = 1;+ bgd.entries = &entry;+ WGPUBindGroup group = wgpuDeviceCreateBindGroup(device_, &bgd);+ if (!group) return;++ WGPURenderPassDepthStencilAttachment ds{};+ ds.view = dstIt->second.view;+ ds.depthLoadOp = WGPULoadOp_Clear;+ ds.depthStoreOp = WGPUStoreOp_Store;+ ds.depthClearValue = 1.0f;+ if (hasStencilPlanes(dstIt->second.format)) {+ ds.stencilLoadOp = WGPULoadOp_Clear;+ ds.stencilStoreOp = WGPUStoreOp_Store;+ }+ WGPURenderPassDescriptor rp{};+ rp.colorAttachmentCount = 0;+ rp.depthStencilAttachment = &ds;++ WGPURenderPassEncoder pass = wgpuCommandEncoderBeginRenderPass(encoder_, &rp);+ if (pass) {+ wgpuRenderPassEncoderSetPipeline(pass, pipeline);+ wgpuRenderPassEncoderSetBindGroup(pass, 0, group, 0, nullptr);+ wgpuRenderPassEncoderDraw(pass, 3, 1, 0, 0);+ wgpuRenderPassEncoderEnd(pass);+ wgpuRenderPassEncoderRelease(pass);+ }+ wgpuBindGroupRelease(group);+}+// =============================================================================// Internal clear family — the two clears WebGPU load-ops cannot spell: a// region-scoped pass clear and a mid-pass stencil reset. A fullscreen triangle@@ -1240,8 +1443,11 @@ WGPUSampler WebGPUDevice::samplerFor(u8 key) {// =============================================================================WGPURenderPipeline WebGPUDevice::ensureClearPipeline(bool color, bool depth, bool stencil) {- const u32 key = colorVariantOf(pass_color_format_) << 5 |- dsVariantOf(pass_ds_format_) << 3 |+ // The sample count is part of the key for the same reason the formats are:+ // a clear pipeline is validated against the pass it runs in.+ const u32 key = colorVariantOf(pass_color_format_) << 6 |+ dsVariantOf(pass_ds_format_) << 4 |+ (pass_samples_ > 1 ? 8u : 0u) |(color ? 1u : 0u) | (depth ? 2u : 0u) | (stencil ? 4u : 0u);auto it = clear_pipelines_.find(key);if (it != clear_pipelines_.end()) return it->second;@@ -1317,7 +1523,7 @@ struct ClearColor { value : vec4f };pd.primitive.topology = WGPUPrimitiveTopology_TriangleList;pd.primitive.frontFace = WGPUFrontFace_CCW;pd.primitive.cullMode = WGPUCullMode_None;- pd.multisample.count = 1;+ pd.multisample.count = pass_samples_;pd.multisample.mask = 0xFFFFFFFFu;pd.fragment = &fragment;@@ -1686,12 +1892,16 @@ void WebGPUDevice::beginRenderPass(const RenderPassDesc& desc) {if (pass_) endRenderPass(); // defensive: a dangling pass would deadlock the queueWGPUTextureView targetView = nullptr;+ WGPUTextureView resolveView = nullptr;WGPUTextureView dsView = nullptr;pass_ds_format_ = WGPUTextureFormat_Undefined;pass_color_format_ = surface_format_;pass_color_texture_ = 0;pass_depth_texture_ = 0;pass_is_surface_ = desc.target == FramebufferHandle::Default;+ pass_samples_ = 1;+ pass_depth_msaa_ = 0;+ pass_depth_resolve_ = 0;if (desc.target != FramebufferHandle::Default) {const FramebufferDesc* fb = framebufferDesc(desc.target);if (!fb) {@@ -1708,14 +1918,37 @@ void WebGPUDevice::beginRenderPass(const RenderPassDesc& desc) {targetView = texIt->second.view;pass_color_format_ = texIt->second.format;pass_color_texture_ = color0;+ pass_samples_ = texIt->second.samples;pass_width_ = texIt->second.width;pass_height_ = texIt->second.height;+ // A multisampled attachment is written, never read: the frame's readback+ // and everything that samples the scene take the single-sample twin the+ // pass resolves into, so that is the texture this pass ANSWERS with.+ if (pass_samples_ > 1) {+ const u32 resolve = static_cast<u32>(fb->resolveColor0);+ auto resolveIt = textures_.find(resolve);+ if (resolveIt == textures_.end()) {+ ES_LOG_ERROR("WebGPUDevice::beginRenderPass: a multisampled target with no resolve twin");+ return;+ }+ resolveView = resolveIt->second.view;+ pass_color_texture_ = resolve;+ }if (depthStencil != 0) {auto dsIt = textures_.find(depthStencil);if (dsIt != textures_.end()) {dsView = dsIt->second.view;pass_ds_format_ = dsIt->second.format;pass_depth_texture_ = depthStencil;+ // A multisampled depth attachment owes its contents to the twin+ // whatever samples scene depth will read; the resolve runs once+ // the pass is closed, on the same encoder.+ const u32 resolveDepth = static_cast<u32>(fb->resolveDepthStencil);+ if (dsIt->second.samples > 1 && resolveDepth != 0) {+ pass_depth_msaa_ = depthStencil;+ pass_depth_resolve_ = resolveDepth;+ pass_depth_texture_ = resolveDepth;+ }}}} else {@@ -1756,9 +1989,18 @@ void WebGPUDevice::beginRenderPass(const RenderPassDesc& desc) {ensureSurfaceDepth(texW, texH);}}- targetView = frame_view_;pass_width_ = surface_width_;pass_height_ = surface_height_;+ // Multisampled: draw into the companion and resolve into the surface+ // texture the browser presents. Single-sampled: draw into it directly.+ if (ensureSurfaceMsaa(surface_width_, surface_height_)) {+ ensureSurfaceDepth(surface_width_, surface_height_);+ targetView = surface_msaa_view_;+ resolveView = frame_view_;+ pass_samples_ = surface_msaa_samples_;+ } else {+ targetView = frame_view_;+ }dsView = surface_depth_view_;pass_ds_format_ = WGPUTextureFormat_Depth24PlusStencil8;}@@ -1784,6 +2026,7 @@ void WebGPUDevice::beginRenderPass(const RenderPassDesc& desc) {const bool scoped = desc.clearW != 0;WGPURenderPassColorAttachment color{};color.view = targetView;+ color.resolveTarget = resolveView;color.depthSlice = WGPU_DEPTH_SLICE_UNDEFINED;color.loadOp = toWGPULoadOp(desc.clearColor, scoped);color.storeOp = WGPUStoreOp_Store;@@ -1832,6 +2075,14 @@ void WebGPUDevice::endRenderPass() {wgpuRenderPassEncoderRelease(pass_);pass_ = nullptr;+ // Depth, on the same encoder and after the pass that wrote it: colour was+ // resolved by the pass itself, and this is the half WebGPU leaves to us.+ if (pass_depth_msaa_ && pass_depth_resolve_) {+ resolveDepthAttachment(pass_depth_msaa_, pass_depth_resolve_);+ pass_depth_msaa_ = 0;+ pass_depth_resolve_ = 0;+ }+// GPU timing: resolve this pass's begin/end timestamps into the reserved ring// slot (recorded on the same encoder, so it runs after the pass on the GPU).const bool timed = pass_timed_ && gpu_time_slot_ < kGpuTimeRing && encoder_;diff --git a/src/esengine/renderer/webgpu/WebGPUDevice.hpp b/src/esengine/renderer/webgpu/WebGPUDevice.hppindex dcf8e8bdc..9a833fb45 100644--- a/src/esengine/renderer/webgpu/WebGPUDevice.hpp+++ b/src/esengine/renderer/webgpu/WebGPUDevice.hpp@@ -57,6 +57,15 @@ public:kColorRgba8 = 0, kColorBgra8 = 1, kColorSrgb8 = 2, kColorRgba16f = 3, kColorVariantCount = 4,};+ /** @brief Sample count of a pass — a third thing WebGPU validates a pipeline+ * against, and the reason a multisampled scene needs its own variant+ * of every pipeline that draws into it. One or {@link kMsaaSamples}. */+ enum SampleVariant : u32 { kSingleSample = 0, kMultiSample = 1, kSampleVariantCount = 2 };++ /** @brief The multisampled count this backend offers. WebGPU guarantees 1 and+ * 4 for every renderable format; nothing else is portable. */+ static constexpr u32 kMsaaSamples = 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. */@@ -112,6 +121,20 @@ public:// Float-target rendering is a WebGPU core capability.bool supportsFloatTargets() override { return true; }u32 maxSamples() override;+ /** Colour resolves in the pass; depth is resolved by a pass of our own+ * ({@link resolveDepthAttachment}), since WebGPU's depth attachment has no+ * resolve target. Either way nothing above the RHI knows. */+ bool resolvesDepth() const override { return true; }+ /**+ * @brief How many samples a SURFACE pass draws with — a frame with no post+ * chain draws straight to the backbuffer.+ * @details A WebGL canvas is created antialiased; a WebGPU surface texture+ * never is, so the backbuffer gets a multisampled companion that+ * resolves into it. The change lands on the next frame.+ */+ void setSurfaceSamples(u32 samples) override {+ surface_samples_ = samples > 1 ? kMsaaSamples : 1;+ }bool supportsShaderLanguage(GfxShaderLanguage language) const override {return language == GfxShaderLanguage::WGSL;@@ -329,6 +352,8 @@ private:/// land in an RGBA8 texture and `format` alone cannot size the source rows.GfxPixelFormat srcFormat = GfxPixelFormat::RGBA8;u8 samplerKey = 0; ///< Packed filter/wrap params (sampler cache key).+ /// 1, or kMsaaSamples for an attachment drawn into and resolved out of.+ u32 samples = 1;};struct ProgramRec {WGPUShaderModule vertex = nullptr;@@ -349,8 +374,9 @@ private:u32 group1DepthMask = 0;};struct PipelineRec {- /// Lazily built per pass shape: [ds * kColorVariantCount + color].- WGPURenderPipeline variants[static_cast<u32>(kDsVariantCount) * static_cast<u32>(kColorVariantCount)] = {};+ /// Lazily built per pass shape: [(ds * kColorVariantCount + color) * kSampleVariantCount + samples].+ WGPURenderPipeline variants[static_cast<u32>(kDsVariantCount) * static_cast<u32>(kColorVariantCount)+ * static_cast<u32>(kSampleVariantCount)] = {};};struct ReadbackRec {WGPUBuffer buffer = nullptr; ///< CopyDst|MapRead staging buffer.@@ -482,6 +508,35 @@ private:u32 pass_height_ = 0;WGPUTextureFormat pass_ds_format_ = WGPUTextureFormat_Undefined;WGPUTextureFormat pass_color_format_ = WGPUTextureFormat_RGBA8Unorm;+ /// Samples of the pass's colour attachment — what its pipelines must declare.+ u32 pass_samples_ = 1;+ /// The multisampled depth attachment of the pass being ended, and the+ /// single-sample texture it owes its contents to. Both 0 unless resolving.+ u32 pass_depth_msaa_ = 0;+ u32 pass_depth_resolve_ = 0;+ /// Samples the backbuffer is drawn with (see setSurfaceSamples).+ u32 surface_samples_ = 1;+ /// The multisampled companion the backbuffer resolves out of, and the depth+ /// beside it. Rebuilt whenever the surface size or sample count changes.+ WGPUTexture surface_msaa_texture_ = nullptr;+ WGPUTextureView surface_msaa_view_ = nullptr;+ u32 surface_msaa_width_ = 0;+ u32 surface_msaa_height_ = 0;+ u32 surface_msaa_samples_ = 0;+ /// Samples the backbuffer's depth companion was built with.+ u32 surface_depth_samples_ = 1;+ bool ensureSurfaceMsaa(u32 width, u32 height);++ /** @brief Copies sample 0 of a multisampled depth attachment into its+ * single-sample twin, so an effect can sample scene depth on a+ * multisampled target. WebGPU has no depth resolve of its own. */+ void resolveDepthAttachment(u32 msaaDepth, u32 resolveDepth);+ WGPURenderPipeline ensureDepthResolvePipeline(WGPUTextureFormat format);+ WGPUShaderModule depth_resolve_vs_ = nullptr;+ WGPUShaderModule depth_resolve_fs_ = nullptr;+ WGPUBindGroupLayout depth_resolve_bgl_ = nullptr;+ WGPUPipelineLayout depth_resolve_layout_ = nullptr;+ std::unordered_map<u32, WGPURenderPipeline> depth_resolve_pipelines_;/// What this pass draws INTO, so flushBindGroup can refuse to also sample it./// 0 = none (the surface, which nothing can hold as a texture anyway).u32 pass_color_texture_ = 0;diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex 2a302a001..0e602aef4 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -28,6 +28,12 @@ export const NOTES_FLOOR = 'v0.65.0';* the reader recognises anyway.*/export const NOTED = {+ 'fix(gates): project-health tests a warning with a field that still is one':+ { internal: "The preflight check's own fixture; it follows the sprite-texture change and no creator runs it." },++ 'feat(render): the WebGPU backend draws the scene and the backbuffer multisampled':+ { note: 'Geometry edges are anti-aliased on WebGPU, which is every native build.' },+'feat(build): a limit that is over names the files filling it, and what to do':{ note: 'The build size report says why a file is in your package, and what changed since the' },'fix(inspector): a Sprite with no texture is not an unfinished entity':diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjsindex d05c5060f..af48db222 100644--- a/tools/renderScenes.mjs+++ b/tools/renderScenes.mjs@@ -663,9 +663,9 @@ export const SCENES = [// A quad turned 20 degrees on black, read twice: the SAME values with and// without a post chain is the claim. WebGPU has no MSAA yet, so both its// halves read the hard step — still the claim, that the chain changes nothing.- { id: "aa-edge", tier: "pr", webgpu: { ESTELLA_VERIFY_EXPECT: "[{\"x\":0.2353,\"y\":0.502,\"rgb\":[0,0,0],\"tol\":6},{\"x\":0.2392,\"y\":0.502,\"rgb\":[255,255,255],\"tol\":6},{\"x\":0.749,\"y\":0.502,\"rgb\":[255,255,255],\"tol\":6},{\"x\":0.7529,\"y\":0.502,\"rgb\":[0,0,0],\"tol\":6},{\"x\":0.502,\"y\":0.502,\"rgb\":[255,255,255],\"tol\":6},{\"x\":0.0784,\"y\":0.0784,\"rgb\":[0,0,0],\"tol\":6}]" }, env: { ESTELLA_VERIFY_SCENE: "/scenes/aa-edge.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.2353,\"y\":0.502,\"rgb\":[128,128,128],\"tol\":64},{\"x\":0.2392,\"y\":0.502,\"rgb\":[128,128,128],\"tol\":64},{\"x\":0.749,\"y\":0.502,\"rgb\":[128,128,128],\"tol\":64},{\"x\":0.7529,\"y\":0.502,\"rgb\":[128,128,128],\"tol\":64},{\"x\":0.502,\"y\":0.502,\"rgb\":[255,255,255],\"tol\":6},{\"x\":0.0784,\"y\":0.0784,\"rgb\":[0,0,0],\"tol\":6}]" } },+ { id: "aa-edge", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/aa-edge.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.2353,\"y\":0.502,\"rgb\":[128,128,128],\"tol\":64},{\"x\":0.2392,\"y\":0.502,\"rgb\":[128,128,128],\"tol\":64},{\"x\":0.749,\"y\":0.502,\"rgb\":[128,128,128],\"tol\":64},{\"x\":0.7529,\"y\":0.502,\"rgb\":[128,128,128],\"tol\":64},{\"x\":0.502,\"y\":0.502,\"rgb\":[255,255,255],\"tol\":6},{\"x\":0.0784,\"y\":0.0784,\"rgb\":[0,0,0],\"tol\":6}]" } },// The other half: the same edges, read through an identity post chain.- { id: "aa-edge-post", tier: "pr", webgpu: { ESTELLA_VERIFY_EXPECT: "[{\"x\":0.2353,\"y\":0.502,\"rgb\":[0,0,0],\"tol\":6},{\"x\":0.2392,\"y\":0.502,\"rgb\":[255,255,255],\"tol\":6},{\"x\":0.749,\"y\":0.502,\"rgb\":[255,255,255],\"tol\":6},{\"x\":0.7529,\"y\":0.502,\"rgb\":[0,0,0],\"tol\":6},{\"x\":0.502,\"y\":0.502,\"rgb\":[255,255,255],\"tol\":6},{\"x\":0.0784,\"y\":0.0784,\"rgb\":[0,0,0],\"tol\":6}]" }, env: { ESTELLA_VERIFY_SCENE: "/scenes/aa-edge-post.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.2353,\"y\":0.502,\"rgb\":[128,128,128],\"tol\":64},{\"x\":0.2392,\"y\":0.502,\"rgb\":[128,128,128],\"tol\":64},{\"x\":0.749,\"y\":0.502,\"rgb\":[128,128,128],\"tol\":64},{\"x\":0.7529,\"y\":0.502,\"rgb\":[128,128,128],\"tol\":64},{\"x\":0.502,\"y\":0.502,\"rgb\":[255,255,255],\"tol\":6},{\"x\":0.0784,\"y\":0.0784,\"rgb\":[0,0,0],\"tol\":6}]" } },+ { id: "aa-edge-post", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/aa-edge-post.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.2353,\"y\":0.502,\"rgb\":[128,128,128],\"tol\":64},{\"x\":0.2392,\"y\":0.502,\"rgb\":[128,128,128],\"tol\":64},{\"x\":0.749,\"y\":0.502,\"rgb\":[128,128,128],\"tol\":64},{\"x\":0.7529,\"y\":0.502,\"rgb\":[128,128,128],\"tol\":64},{\"x\":0.502,\"y\":0.502,\"rgb\":[255,255,255],\"tol\":6},{\"x\":0.0784,\"y\":0.0784,\"rgb\":[0,0,0],\"tol\":6}]" } },{ id: "ssao", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/ssao.esscene", ESTELLA_VERIFY_W: "320", ESTELLA_VERIFY_H: "240", ESTELLA_VERIFY_STEPS: "4", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.5016,\"y\":0.8996,\"rgb\":[191,191,191],\"tol\":6},{\"x\":0.3762,\"y\":0.4937,\"rgb\":[144,144,144],\"tol\":20},{\"x\":0.627,\"y\":0.4812,\"rgb\":[172,172,172],\"tol\":9},{\"x\":0.8527,\"y\":0.4686,\"rgb\":[147,147,147],\"tol\":9},{\"x\":0.1881,\"y\":0.5272,\"rgb\":[123,141,113],\"tol\":22},{\"x\":0.1285,\"y\":0.1967,\"rgb\":[133,136,148],\"tol\":9},{\"x\":0.627,\"y\":0.2008,\"rgb\":[179,184,199],\"tol\":5}]" } },{ id: "depth-outline-flat", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/depth-outline-flat.esscene", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.5,\"y\":0.5,\"rgb\":[230,102,26],\"tol\":20}]" } },{ id: "mesh-opaque", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/mesh-depth.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/mesh-depth.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "4", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.42,\"y\":0.5,\"rgb\":[0,255,0],\"tol\":40},{\"x\":0.58,\"y\":0.5,\"rgb\":[255,0,0],\"tol\":40}]" } },