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(render): the WebGPU backend draws the scene and the backbuffer multisampled

esengine3561766d673f
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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 the
last build.** A big texture now names the chain that pulled it in — the scene, prefab or
material that references it, or the rule that force-included it (a subpackage group, an
diff --git a/docs/astro/src/content/docs/graphics/post-processing.mdx b/docs/astro/src/content/docs/graphics/post-processing.mdx
index 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.mdx
index 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.cpp
index 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.cpp
index 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.hpp
index 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.hpp
index 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.cpp
index 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, u32
if (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, Text
td.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, Text
out = 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 queue
WGPUTextureView 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.hpp
index 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.mjs
index 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.mjs
index 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}]" } },