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
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file WebGPUDevice.cpp
* @brief WebGPU backend (REARCH_WGSL Phase 2): resources + the live render
* path — surface, pass encoding with depth-stencil attachments, lazy
* per-DS-shape pipelines, texture/sampler bind groups, draws, and the
* internal clear-triangle emulations.
*/
#include "WebGPUDevice.hpp"
#include "WebGPUMappings.hpp"
#include "../rhi/PixelUpload.hpp"
#include "../../core/Log.hpp"
#include <algorithm>
#include <cstring>
#include <string>
#include <vector>
namespace esengine {
using namespace webgpu;
namespace {
WGPUStringView sv(const char* text) {
WGPUStringView view{};
view.data = text;
view.length = text ? std::strlen(text) : 0;
return view;
}
std::string fromSv(const WGPUStringView& view) {
if (!view.data) return {};
return std::string(view.data,
view.length == WGPU_STRLEN ? std::strlen(view.data) : view.length);
}
bool isDepthFormat(WGPUTextureFormat format) {
return format == WGPUTextureFormat_Depth24Plus ||
format == WGPUTextureFormat_Depth24PlusStencil8;
}
u32 dsVariantOf(WGPUTextureFormat format) {
if (format == WGPUTextureFormat_Undefined) return WebGPUDevice::kDsNone;
return hasStencilPlanes(format) ? WebGPUDevice::kDsDepthStencil : WebGPUDevice::kDsDepthOnly;
}
u8 packSamplerKey(TextureFilter minFilter, TextureFilter magFilter,
TextureWrap wrapS, TextureWrap wrapT) {
return static_cast<u8>((minFilter == TextureFilter::Nearest ? 1u : 0u) |
(magFilter == TextureFilter::Nearest ? 2u : 0u) |
(static_cast<u32>(wrapS) << 2) |
(static_cast<u32>(wrapT) << 4));
}
} // namespace
WebGPUDevice::WebGPUDevice(WGPUDevice device, WGPUInstance instance, WGPUAdapter adapter)
: device_(device), adapter_(adapter) {
if (device_) {
queue_ = wgpuDeviceGetQueue(device_);
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;
}
}
}
WebGPUDevice::~WebGPUDevice() {
shutdown();
}
// 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();
}
void WebGPUDevice::captureDeviceIdentity() {
// Ask the adapter who this GPU is. getString() below answers with constants
// true of every WebGPU build, and so useless in a loss report; the adapter
// knows the vendor, the chip and the driver build.
std::string vendor = "WebGPU";
std::string renderer = getString(GfxStringName::Renderer);
std::string version = getString(GfxStringName::Version);
if (adapter_) {
WGPUAdapterInfo info = {};
if (wgpuAdapterGetInfo(adapter_, &info) == WGPUStatus_Success) {
vendor = fromSv(info.vendor);
renderer = fromSv(info.device) + " (" + fromSv(info.architecture) + ")";
version = fromSv(info.description);
wgpuAdapterInfoFreeMembers(info);
}
}
setDeviceIdentity("WebGPU", std::move(vendor), std::move(renderer), std::move(version));
}
GfxDeviceLostReason WebGPUDevice::reasonFromWgpu(u32 wgpuReason) {
switch (static_cast<WGPUDeviceLostReason>(wgpuReason)) {
// Not a failure: this is the device we destroyed reporting that it is gone.
case WGPUDeviceLostReason_Destroyed: return GfxDeviceLostReason::Destroyed;
case WGPUDeviceLostReason_FailedCreation: return GfxDeviceLostReason::Internal;
default: return GfxDeviceLostReason::Unknown;
}
}
bool WebGPUDevice::pollDeviceLost() {
// The device-lost callback is registered AllowSpontaneous and so fires on
// its own, but pumping here gives it a guaranteed point in the frame — and
// keeps the loss detectable if the mode ever tightens to ProcessEvents.
if (instance_) wgpuInstanceProcessEvents(instance_);
return false;
}
void WebGPUDevice::reportUncapturedError(u32 wgpuErrorType, const char* message) {
// Only errors that mean the device is finished become losses. A validation
// error is a bug in the frame we just built — WebGPU drops the call and keeps
// the device — so promoting it would end the game over one bad draw.
const auto type = static_cast<WGPUErrorType>(wgpuErrorType);
if (type == WGPUErrorType_OutOfMemory) {
markDeviceLost(GfxDeviceLostReason::OutOfMemory, message ? message : "",
"uncaptured error");
} else if (type == WGPUErrorType_Internal) {
markDeviceLost(GfxDeviceLostReason::Internal, message ? message : "",
"uncaptured error");
} else if (type == WGPUErrorType_Validation && validation_errors_logged_ < 8) {
// Said, the first few: otherwise all that reaches the console is the queue refusing an invalid command buffer, which names
// nothing that made it invalid.
++validation_errors_logged_;
ES_LOG_WARN("WebGPU validation error: {}", message ? message : "(no message)");
}
}
bool WebGPUDevice::adoptDevice(WGPUDevice device) {
if (!device) return false;
// Everything below the device goes: a WebGPU object belongs to the device
// that made it, so none of these caches can be carried over. The instance
// stays — it outlives devices, and on native the surface must match it.
releaseDeviceObjects();
device_ = device;
queue_ = wgpuDeviceGetQueue(device_);
init();
#if defined(__EMSCRIPTEN__)
if (surface_selector_.empty()) return true;
return configureSurface(surface_selector_.c_str(), surface_width_, surface_height_);
#else
if (!surface_window_) return true;
NativeSurface window{};
window.handle = surface_window_;
return configureSurface(window, surface_width_, surface_height_);
#endif
}
bool WebGPUDevice::recreateDevice() {
// "Not yet", not "never": only whoever created the device can replace it, so
// this waits for a host to hand one over rather than claiming a recovery it
// cannot perform. The GL path waits on the browser the same way.
if (!pending_device_) return false;
WGPUDevice next = pending_device_;
pending_device_ = nullptr;
return adoptDevice(next);
}
void WebGPUDevice::shutdown() {
releaseDeviceObjects();
if (instance_ && owns_instance_) { wgpuInstanceRelease(instance_); }
instance_ = nullptr;
}
void WebGPUDevice::releaseDeviceObjects() {
if (pass_) { wgpuRenderPassEncoderRelease(pass_); pass_ = nullptr; }
if (encoder_) { wgpuCommandEncoderRelease(encoder_); encoder_ = nullptr; }
if (frame_view_) { wgpuTextureViewRelease(frame_view_); frame_view_ = nullptr; }
if (frame_texture_) { wgpuTextureRelease(frame_texture_); frame_texture_ = nullptr; }
capture_id_ = 0;
capture_copied_ = false;
pass_is_surface_ = false;
pass_timed_ = false;
span_open_ = false;
span_closing_ = false;
span_slot_ = kGpuTimeRing;
span_passes_ = 0;
// bind_group_/texture_group_ point INTO the cache — release the cache, not them.
for (auto& bucket : bind_group_cache_) for (auto& e : bucket.second) if (e.bg) wgpuBindGroupRelease(e.bg);
bind_group_cache_.clear();
bind_group_count_ = 0;
bind_group_ = nullptr;
texture_group_ = nullptr;
bind_group_dirty_ = true;
bound_pipeline_ = 0;
for (auto& [id, rec] : buffers_) {
if (rec.buffer) wgpuBufferRelease(rec.buffer);
}
buffers_.clear();
for (auto& [id, rec] : textures_) releaseTexture(rec);
textures_.clear();
for (auto& [id, rec] : programs_) {
if (rec.vertex) wgpuShaderModuleRelease(rec.vertex);
if (rec.fragment) wgpuShaderModuleRelease(rec.fragment);
}
programs_.clear();
for (auto& [id, rec] : computes_) {
for (auto& [key, pipeline] : rec.pipelines) {
if (pipeline) wgpuComputePipelineRelease(pipeline);
}
if (rec.module) wgpuShaderModuleRelease(rec.module);
}
computes_.clear();
for (auto& [key, layout] : compute_pipeline_layouts_) {
if (layout) wgpuPipelineLayoutRelease(layout);
}
compute_pipeline_layouts_.clear();
for (auto& [key, layout] : compute_layouts_) {
if (layout) wgpuBindGroupLayoutRelease(layout);
}
compute_layouts_.clear();
for (auto& [id, rec] : pipelines_) {
for (WGPURenderPipeline variant : rec.variants) {
if (variant) wgpuRenderPipelineRelease(variant);
}
}
pipelines_.clear();
if (dummy_ubo_.buffer) wgpuBufferRelease(dummy_ubo_.buffer);
dummy_ubo_ = BufferRec{};
releaseTexture(dummy_texture_);
releaseTexture(dummy_depth_texture_);
releaseTexture(dummy_array_texture_);
// GPU timing resources.
if (timestamp_qset_) { wgpuQuerySetRelease(timestamp_qset_); timestamp_qset_ = nullptr; }
if (timestamp_resolve_) { wgpuBufferRelease(timestamp_resolve_); timestamp_resolve_ = nullptr; }
for (auto& s : gpu_time_ring_) { if (s.buf) wgpuBufferRelease(s.buf); s.buf = nullptr; s.pending = false; }
gpu_time_results_.clear();
for (auto& ps : pass_time_pool_) { if (ps.buf) wgpuBufferRelease(ps.buf); }
pass_time_pool_.clear();
pass_time_results_.clear();
pass_time_slot_ = kNoPassSlot;
armed_pass_tag_ = 0;
timestamp_supported_ = false;
timestamp_init_done_ = false;
if (clear_bind_group_) { wgpuBindGroupRelease(clear_bind_group_); clear_bind_group_ = nullptr; }
if (clear_color_buffer_) { wgpuBufferRelease(clear_color_buffer_); clear_color_buffer_ = nullptr; }
for (auto& [key, pipeline] : clear_pipelines_) {
if (pipeline) wgpuRenderPipelineRelease(pipeline);
}
clear_pipelines_.clear();
if (clear_layout_) { wgpuPipelineLayoutRelease(clear_layout_); clear_layout_ = nullptr; }
if (clear_bgl_) { wgpuBindGroupLayoutRelease(clear_bgl_); clear_bgl_ = nullptr; }
for (auto& [key, pipeline] : flip_pipelines_) {
if (pipeline) wgpuRenderPipelineRelease(pipeline);
}
flip_pipelines_.clear();
if (flip_layout_) { wgpuPipelineLayoutRelease(flip_layout_); flip_layout_ = nullptr; }
if (flip_bgl_) { wgpuBindGroupLayoutRelease(flip_bgl_); flip_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, pipeline] : mip_pipelines_) {
if (pipeline) wgpuRenderPipelineRelease(pipeline);
}
mip_pipelines_.clear();
if (mip_layout_) { wgpuPipelineLayoutRelease(mip_layout_); mip_layout_ = nullptr; }
if (mip_bgl_) { wgpuBindGroupLayoutRelease(mip_bgl_); mip_bgl_ = nullptr; }
if (mip_module_) { wgpuShaderModuleRelease(mip_module_); mip_module_ = nullptr; }
if (mip_sampler_) { wgpuSamplerRelease(mip_sampler_); mip_sampler_ = nullptr; }
for (auto& [key, layout] : pipeline_layouts_) {
if (layout) wgpuPipelineLayoutRelease(layout);
}
pipeline_layouts_.clear();
for (auto& [key, layout] : group_layouts_) {
if (layout) wgpuBindGroupLayoutRelease(layout);
}
group_layouts_.clear();
// Erase before release: aborting a pending map fires the callback, which must
// miss the lookup rather than see a half-dead record.
while (!readbacks_.empty()) releaseReadback(readbacks_.begin()->first);
for (auto& [key, sampler] : samplers_) {
if (sampler) wgpuSamplerRelease(sampler);
}
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.
surface_depth_width_ = 0;
surface_depth_height_ = 0;
}
// =============================================================================
// Surface (bring-up: a canvas is the Default framebuffer)
// =============================================================================
#if defined(__EMSCRIPTEN__)
bool WebGPUDevice::configureSurface(const char* selector, u32 width, u32 height) {
if (!device_ || !instance_) {
ES_LOG_ERROR("WebGPUDevice::configureSurface: no device/instance");
return false;
}
WGPUEmscriptenSurfaceSourceCanvasHTMLSelector canvas{};
canvas.chain.sType = WGPUSType_EmscriptenSurfaceSourceCanvasHTMLSelector;
canvas.selector = sv(selector);
WGPUSurfaceDescriptor sd{};
sd.nextInChain = &canvas.chain;
// Kept so a replacement device can re-make the surface: the old one belonged
// to the device that died, and nothing else records which canvas it was.
surface_selector_ = selector;
surface_ = wgpuInstanceCreateSurface(instance_, &sd);
if (!surface_) {
ES_LOG_ERROR("WebGPUDevice::configureSurface: surface creation failed for '{}'", selector);
return false;
}
return configureSwapchain(width, height);
}
#endif // __EMSCRIPTEN__
#if !defined(__EMSCRIPTEN__)
// The native (iOS/Android) surface source: the same instance + swapchain as the web
// path, but the surface is created from a native window handle instead of a canvas
// selector. Dawn's Metal/Android surface descriptors replace the emscripten one; the
// host owns the CAMetalLayer / ANativeWindow lifetime. Compiled only in a native Dawn
// build (emscripten's emdawnwebgpu has no native window source).
bool WebGPUDevice::configureSurface(const NativeSurface& window, u32 width, u32 height) {
if (!device_ || !instance_) {
ES_LOG_ERROR("WebGPUDevice::configureSurface(native): no device/instance");
return false;
}
if (!window.handle) {
ES_LOG_ERROR("WebGPUDevice::configureSurface(native): null window handle");
return false;
}
// The SAME window, a new size — a rotation, insets changing, the system bars
// leaving — is a reconfigure, not a new surface. Creating a second surface for
// a window the first one still holds leaves every getCurrentTexture in error
// on Vulkan (the old swapchain owns it), which is a black screen with nothing
// else wrong.
if (surface_ && surface_window_ == window.handle) {
endFrame(); // a held texture belongs to the swapchain being replaced
return configureSwapchain(width, height);
}
// A genuinely new window (an Android screen-off/on destroys it and hands back
// another): let go of the old swapchain before building one on the new one.
if (surface_) {
endFrame();
wgpuSurfaceUnconfigure(surface_);
wgpuSurfaceRelease(surface_);
surface_ = nullptr;
}
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) {
case NativeWindowKind::MetalLayer: {
WGPUSurfaceSourceMetalLayer metal{};
metal.chain.sType = WGPUSType_SurfaceSourceMetalLayer;
metal.layer = window.handle; // CAMetalLayer*
sd.nextInChain = &metal.chain;
surface_ = wgpuInstanceCreateSurface(instance_, &sd);
break;
}
case NativeWindowKind::AndroidWindow: {
WGPUSurfaceSourceAndroidNativeWindow android{};
android.chain.sType = WGPUSType_SurfaceSourceAndroidNativeWindow;
android.window = window.handle; // ANativeWindow*
sd.nextInChain = &android.chain;
surface_ = wgpuInstanceCreateSurface(instance_, &sd);
break;
}
case NativeWindowKind::Win32Hwnd: {
#if defined(_WIN32)
WGPUSurfaceSourceWindowsHWND win32{};
win32.chain.sType = WGPUSType_SurfaceSourceWindowsHWND;
win32.hinstance = window.instance;
win32.hwnd = window.handle;
sd.nextInChain = &win32.chain;
surface_ = wgpuInstanceCreateSurface(instance_, &sd);
#endif
break;
}
case NativeWindowKind::WaylandSurface: {
#if defined(__linux__)
WGPUSurfaceSourceWaylandSurface wayland{};
wayland.chain.sType = WGPUSType_SurfaceSourceWaylandSurface;
wayland.display = window.instance; // wl_display*
wayland.surface = window.handle; // wl_surface*
sd.nextInChain = &wayland.chain;
surface_ = wgpuInstanceCreateSurface(instance_, &sd);
#endif
break;
}
case NativeWindowKind::XlibWindow: {
#if defined(__linux__)
WGPUSurfaceSourceXlibWindow xlib{};
xlib.chain.sType = WGPUSType_SurfaceSourceXlibWindow;
xlib.display = window.instance; // Display*
// The XID is an integer, not a pointer — it travels in `handle`
// because the seam carries one window field, and is read back as the
// integer it is rather than dereferenced.
xlib.window = static_cast<uint64_t>(reinterpret_cast<uintptr_t>(window.handle));
sd.nextInChain = &xlib.chain;
surface_ = wgpuInstanceCreateSurface(instance_, &sd);
#endif
break;
}
}
if (!surface_) {
ES_LOG_ERROR("WebGPUDevice::configureSurface(native): surface creation failed");
return false;
}
surface_window_ = window.handle;
return configureSwapchain(width, height);
}
/** Whether a surface format makes the hardware encode on write. */
static bool isSrgbFormat(WGPUTextureFormat f) {
return f == WGPUTextureFormat_BGRA8UnormSrgb || f == WGPUTextureFormat_RGBA8UnormSrgb;
}
void WebGPUDevice::present() {
if (!surface_) return;
wgpuSurfacePresent(surface_);
// Also the frame's end, for a frame the renderer never finished (the host's
// fallback frame, or a tick that drew nothing): a swapchain texture must
// never outlive the present it belongs to.
endFrame();
}
#endif // !__EMSCRIPTEN__
// Not native-only: a web surface can be BGRA too, and a capture consumer has to
// know which order the bytes came back in.
bool WebGPUDevice::surfaceBytesAreBGRA() const {
return surface_format_ == WGPUTextureFormat_BGRA8Unorm
|| surface_format_ == WGPUTextureFormat_BGRA8UnormSrgb;
}
/**
* The fastest present mode this surface actually advertises.
*
* Immediate FIRST, and the order is load-bearing: Dawn's Metal backend clears
* `displaySyncEnabled` for Immediate ALONE (`SwapChainMTL.mm`), so a surface
* offering both hands back a Mailbox that is still vsynced — measured, every
* span pinned to 16.6 ms. Fifo is the fallback, and then the frame is throttled.
*/
WGPUPresentMode WebGPUDevice::pickUncappedPresentMode() const {
#if !defined(__EMSCRIPTEN__)
if (surface_ && adapter_) {
WGPUSurfaceCapabilities caps{};
if (wgpuSurfaceGetCapabilities(surface_, adapter_, &caps) == WGPUStatus_Success) {
WGPUPresentMode chosen = WGPUPresentMode_Fifo;
for (size_t i = 0; i < caps.presentModeCount; ++i) {
if (caps.presentModes[i] == WGPUPresentMode_Immediate) {
chosen = WGPUPresentMode_Immediate;
break;
}
if (caps.presentModes[i] == WGPUPresentMode_Mailbox) chosen = WGPUPresentMode_Mailbox;
}
wgpuSurfaceCapabilitiesFreeMembers(caps);
return chosen;
}
}
#endif
return WGPUPresentMode_Fifo;
}
bool WebGPUDevice::configureSwapchain(u32 width, u32 height) {
// Anything but the canvas' preferred format costs a full-frame copy per
// present, and only the page can name it (setPreferredSurfaceBGRA). Readback
// asks frameCaptureIsBGRA which order it got.
surface_format_ = prefer_surface_bgra_ ? WGPUTextureFormat_BGRA8Unorm
: WGPUTextureFormat_RGBA8Unorm;
#if !defined(__EMSCRIPTEN__)
// A native surface may accept nothing of the sort — a CAMetalLayer offers only
// BGRA8Unorm, while Vulkan happens to take RGBA8 — and configuring a format the
// surface does not advertise leaves every getCurrentTexture in error rather
// than failing here. So ask, and take the surface's preferred (first) format.
//
// Of the formats it advertises, take a NON-sRGB one: the engine hands the
// surface values that are already display-encoded (the shaders in gamma
// mode, the final blit in linear), so an *Srgb surface encodes them twice.
if (adapter_) {
WGPUSurfaceCapabilities caps{};
if (wgpuSurfaceGetCapabilities(surface_, adapter_, &caps) == WGPUStatus_Success
&& caps.formatCount > 0) {
surface_format_ = caps.formats[0];
for (size_t i = 0; i < caps.formatCount; ++i) {
if (!isSrgbFormat(caps.formats[i])) {
surface_format_ = caps.formats[i];
break;
}
}
wgpuSurfaceCapabilitiesFreeMembers(caps);
}
}
#endif
WGPUSurfaceConfiguration cfg{};
cfg.device = device_;
cfg.format = surface_format_;
cfg.usage = WGPUTextureUsage_RenderAttachment;
// Opt-in (setSurfaceReadback): lets captureNextFrame copy the presented frame.
if (surface_readback_) cfg.usage |= WGPUTextureUsage_CopySrc;
cfg.width = width;
cfg.height = height;
// 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;
// Fifo is the only mode every surface must support, and the only one a shipped
// game should want. setPresentUncapped asks for a measurable frame instead —
// see its comment for why a vsynced one cannot be measured.
cfg.presentMode = present_uncapped_ ? pickUncappedPresentMode() : WGPUPresentMode_Fifo;
// Said out loud, because a fallback here makes a measurement WRONG rather than
// absent: a frame that was throttled reads as the refresh interval, and the
// bench consuming it cannot tell that from a frame that cost that much.
if (present_uncapped_) {
ES_LOG_WARN("WebGPUDevice: uncapped present asked for, surface gave {}",
cfg.presentMode == WGPUPresentMode_Immediate ? "Immediate"
: cfg.presentMode == WGPUPresentMode_Mailbox ? "Mailbox — the compositor still shows one frame per vsync"
: "Fifo — the frame IS the refresh interval");
}
wgpuSurfaceConfigure(surface_, &cfg);
surface_width_ = width;
surface_height_ = height;
return ensureSurfaceDepth(width, height);
}
/**
* The default target's companion depth-stencil planes — the WebGL canvas has
* them implicitly, and engine stencil masks / depth-tested draws target the
* backbuffer expecting both. Recreated whenever the size it must match changes;
* a pass whose attachments disagree is rejected outright, and every draw after
* that is dropped.
*/
bool WebGPUDevice::ensureSurfaceDepth(u32 width, u32 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; }
if (surface_depth_texture_) { wgpuTextureRelease(surface_depth_texture_); surface_depth_texture_ = nullptr; }
WGPUTextureDescriptor dd{};
dd.dimension = WGPUTextureDimension_2D;
dd.format = WGPUTextureFormat_Depth24PlusStencil8;
dd.size = WGPUExtent3D{width, height, 1};
dd.mipLevelCount = 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;
if (pass_) {
ES_LOG_WARN("WebGPUDevice::resizeBackbuffer: ignored inside a render pass");
return;
}
configureSwapchain(width, height);
}
void WebGPUDevice::stubOnce(const char* what) {
for (const auto& logged : stub_logged_) {
if (logged == what) return;
}
stub_logged_.emplace_back(what);
ES_LOG_WARN("WebGPUDevice: {} not implemented yet (REARCH_WGSL Phase 2 slice 2)", what);
}
// =============================================================================
// Dynamic state (recorded in slice 2's pass encoder)
// =============================================================================
// The RHI states a rectangle the way GL does: origin bottom-left, y up. WebGPU
// measures from the top-left, so any rect that is not the whole target arrives
// upside down here — a UI mask's scissor, a camera viewport sharing the target,
// a region clear. A full-target rect flips to itself, which is why only masked
// content showed it.
i32 WebGPUDevice::flipRectY(i32 y, i32 height) const {
return static_cast<i32>(pass_height_) - (y + height);
}
void WebGPUDevice::setViewport(i32 x, i32 y, u32 w, u32 h) {
viewport_ = {x, y, w, h};
if (pass_) {
wgpuRenderPassEncoderSetViewport(pass_, static_cast<f32>(x),
static_cast<f32>(flipRectY(y, static_cast<i32>(h))),
static_cast<f32>(w), static_cast<f32>(h), 0.0f, 1.0f);
}
}
void WebGPUDevice::clearStencil(i32 value) {
// Mid-pass stencil reset (mask rebuild) — the one clear that cannot restart
// the pass. Emulated with a stencil-write triangle under whatever scissor is
// currently active, matching GL's glClear-honors-scissor semantics.
if (!pass_) {
ES_LOG_WARN("WebGPUDevice::clearStencil: no active pass");
return;
}
if (!hasStencilPlanes(pass_ds_format_)) {
ES_LOG_WARN("WebGPUDevice::clearStencil: pass target has no stencil planes");
return;
}
drawInternalClear(false, false, true, nullptr, value, nullptr);
}
void WebGPUDevice::setScissorTest(bool enabled) {
// WebGPU's scissor is always on; "disabled" = the full target rectangle.
if (pass_ && !enabled) {
wgpuRenderPassEncoderSetScissorRect(pass_, 0, 0, pass_width_, pass_height_);
}
}
void WebGPUDevice::setScissor(i32 x, i32 y, i32 w, i32 h) {
if (!pass_ || w <= 0 || h <= 0) return;
// Clamped to the attachment: WebGPU rejects a rect that leaves it, where GL
// simply clips — and a mask scrolled half off screen is ordinary.
const i32 top = flipRectY(y, h);
const i32 x0 = std::clamp(x, 0, static_cast<i32>(pass_width_));
const i32 y0 = std::clamp(top, 0, static_cast<i32>(pass_height_));
const i32 x1 = std::clamp(x + w, 0, static_cast<i32>(pass_width_));
const i32 y1 = std::clamp(top + h, 0, static_cast<i32>(pass_height_));
wgpuRenderPassEncoderSetScissorRect(pass_, static_cast<u32>(x0), static_cast<u32>(y0),
static_cast<u32>(std::max(0, x1 - x0)),
static_cast<u32>(std::max(0, y1 - y0)));
}
// =============================================================================
// Buffers
// =============================================================================
u64 WebGPUDevice::estimatedGpuBytes() const {
if (!device_ || !isDeviceUsable()) return 0;
u64 bytes = 0;
const auto bufferBytes = [](WGPUBuffer buffer) -> u64 { return buffer ? wgpuBufferGetSize(buffer) : 0; };
for (const auto& [id, buffer] : buffers_) bytes += bufferBytes(buffer.buffer);
bytes += bufferBytes(dummy_ubo_.buffer) + bufferBytes(clear_color_buffer_) + bufferBytes(timestamp_resolve_);
for (const auto& slot : gpu_time_ring_) bytes += bufferBytes(slot.buf);
for (const auto& [id, readback] : readbacks_) bytes += bufferBytes(readback.buffer);
const auto textureBytes = [](WGPUTexture texture) -> u64 {
if (!texture) return 0;
u32 width = wgpuTextureGetWidth(texture), height = wgpuTextureGetHeight(texture);
const auto format = wgpuTextureGetFormat(texture);
const u32 pixelBytes = format == WGPUTextureFormat_RGBA32Float ? 16 : format == WGPUTextureFormat_RGBA16Float ? 8 : 4;
GfxBlockInfo block{1, 1, pixelBytes};
for (const auto compressed : {GfxCompressedFormat::ETC2_RGB8, GfxCompressedFormat::ETC2_RGBA8,
GfxCompressedFormat::ASTC_4x4, GfxCompressedFormat::ASTC_8x8, GfxCompressedFormat::S3TC_DXT1,
GfxCompressedFormat::S3TC_DXT5, GfxCompressedFormat::ETC2_RGBA8_SRGB,
GfxCompressedFormat::ASTC_4x4_SRGB, GfxCompressedFormat::S3TC_DXT5_SRGB}) {
if (format == toWGPUCompressedFormat(compressed)) { block = gfxCompressedBlockInfo(compressed); break; }
}
u64 size = 0;
for (u32 level = 0; level < wgpuTextureGetMipLevelCount(texture); ++level) {
size += ((static_cast<u64>(width) + block.blockWidth - 1) / block.blockWidth)
* ((static_cast<u64>(height) + block.blockHeight - 1) / block.blockHeight) * block.bytesPerBlock
* wgpuTextureGetSampleCount(texture);
width = std::max(1u, width / 2); height = std::max(1u, height / 2);
}
return size * wgpuTextureGetDepthOrArrayLayers(texture);
};
for (const auto& [id, texture] : textures_) bytes += textureBytes(texture.texture);
bytes += textureBytes(dummy_texture_.texture) + textureBytes(dummy_depth_texture_.texture)
+ textureBytes(dummy_array_texture_.texture);
bytes += textureBytes(surface_depth_texture_) + textureBytes(surface_msaa_texture_);
return bytes;
}
WGPUBuffer WebGPUDevice::makeBuffer(GfxBufferUsage usage, u32 size, const void* data) {
if (!device_) {
ES_LOG_ERROR("WebGPUDevice: no device to create a buffer on");
return nullptr;
}
WGPUBufferDescriptor bd{};
bd.usage = toWGPUBufferUsage(usage);
// Round the allocation, never the caller's data — see alignedWriteSize.
bd.size = webgpu::alignedWriteSize(size);
WGPUBuffer buffer = wgpuDeviceCreateBuffer(device_, &bd);
if (!buffer) {
ES_LOG_ERROR("WebGPUDevice: buffer creation failed ({} bytes)", size);
return nullptr;
}
if (data && size > 0) writeBufferPadded(buffer, 0, data, size);
return buffer;
}
bool WebGPUDevice::backendCreateBuffer(u32 id, const BufferDesc& desc, const void* data) {
WGPUBuffer buffer = makeBuffer(desc.usage, desc.size, data);
if (!buffer) return false;
buffers_[id] = BufferRec{buffer, desc.size, desc.usage};
return true;
}
void WebGPUDevice::writeBufferPadded(WGPUBuffer buffer, u32 offset, const void* data, u32 size) {
if (!webgpu::needsWriteStaging(size)) {
wgpuQueueWriteBuffer(queue_, buffer, offset, data, size);
return;
}
std::vector<u8> padded(webgpu::alignedWriteSize(size), 0);
std::memcpy(padded.data(), data, size);
wgpuQueueWriteBuffer(queue_, buffer, offset, padded.data(), padded.size());
}
void WebGPUDevice::backendDeleteBuffer(u32 id) {
auto it = buffers_.find(id);
if (it == buffers_.end()) return;
if (it->second.buffer) {
evictBindGroups(static_cast<u64>(reinterpret_cast<uintptr_t>(it->second.buffer)));
wgpuBufferRelease(it->second.buffer);
}
buffers_.erase(it);
}
void WebGPUDevice::evictBindGroups(u64 id) {
for (auto it = bind_group_cache_.begin(); it != bind_group_cache_.end();) {
auto& bucket = it->second;
for (usize i = bucket.size(); i-- > 0;) {
auto& e = bucket[i];
bool hit = false;
for (u64 v : e.ids) {
if (v == id) { hit = true; break; }
}
if (!hit) continue;
if (e.bg == bind_group_) bind_group_ = nullptr;
if (e.bg == texture_group_) texture_group_ = nullptr;
if (e.bg) wgpuBindGroupRelease(e.bg);
bucket.erase(bucket.begin() + static_cast<std::ptrdiff_t>(i));
--bind_group_count_;
bind_group_dirty_ = true;
}
it = bucket.empty() ? bind_group_cache_.erase(it) : std::next(it);
}
}
void WebGPUDevice::backendUpdateBuffer(u32 id, u32 offsetBytes, const void* data, u32 sizeBytes) {
auto it = buffers_.find(id);
if (it == buffers_.end() || !it->second.buffer || !data || sizeBytes == 0) return;
if (!webgpu::writeFitsInBuffer(offsetBytes, sizeBytes, it->second.size)) {
ES_LOG_ERROR("WebGPUDevice::updateBuffer: range {}+{} exceeds buffer size {}",
offsetBytes, sizeBytes, it->second.size);
return;
}
// GL takes any offset and size; WriteBuffer takes 4-byte multiples of both.
if ((offsetBytes & 3u) != 0) {
ES_LOG_ERROR("WebGPUDevice::updateBuffer: offset {} is not 4-byte aligned", offsetBytes);
return;
}
// Only a write ending at the logical end may pad, into the slack the rounded
// allocation has. One ending mid-buffer would clobber the next field.
if (webgpu::needsWriteStaging(sizeBytes) && offsetBytes + sizeBytes != it->second.size) {
ES_LOG_ERROR("WebGPUDevice::updateBuffer: unaligned partial write {}+{} of {}",
offsetBytes, sizeBytes, it->second.size);
return;
}
writeBufferPadded(it->second.buffer, offsetBytes, data, sizeBytes);
}
void WebGPUDevice::backendResizeBuffer(u32 id, const BufferDesc& desc, const void* data) {
auto it = buffers_.find(id);
if (it == buffers_.end()) return;
// WebGPU buffers are fixed-size, so the store is re-created behind the same id.
// A cached bind group names the old WGPUBuffer, not the id, and would keep
// drawing its bytes.
if (it->second.buffer) {
evictBindGroups(static_cast<u64>(reinterpret_cast<uintptr_t>(it->second.buffer)));
wgpuBufferRelease(it->second.buffer);
}
bind_group_dirty_ = true;
it->second.buffer = makeBuffer(desc.usage, desc.size, data);
it->second.size = desc.size;
}
void WebGPUDevice::backendSetUniformBuffer(u32 slot, BufferHandle buffer, u32 offsetBytes, u32 sizeBytes) {
if (slot >= kUniformSlots) return;
const u32 id = static_cast<u32>(buffer);
if (uniform_slots_[slot] != id || uniform_offsets_[slot] != offsetBytes ||
uniform_sizes_[slot] != sizeBytes) {
uniform_slots_[slot] = id;
uniform_offsets_[slot] = offsetBytes;
uniform_sizes_[slot] = sizeBytes;
bind_group_dirty_ = true;
}
}
// =============================================================================
// Vertex layouts (descriptors retained; pipelines consume them at build time)
// =============================================================================
bool WebGPUDevice::backendAcceptsVertexLayout(const VertexLayoutDesc& desc) {
// Every attribute needs a WebGPU spelling — a mismatch is an engine bug, not a
// runtime condition, so it is refused where the layout is declared.
for (u32 i = 0; i < desc.attributeCount; ++i) {
const auto& a = desc.attributes[i];
if (toWGPUVertexFormat(a.components, a.type, a.normalized) == kInvalidVertexFormat) {
ES_LOG_ERROR("WebGPUDevice::createVertexLayout: attribute {} ({} x type {}) has no WGPU format",
i, a.components, static_cast<u32>(a.type));
return false;
}
}
return true;
}
void WebGPUDevice::setVertexBuffer(u32 slot, BufferHandle buffer, u32 offsetBytes) {
auto it = buffers_.find(static_cast<u32>(buffer));
if (!pass_ || it == buffers_.end()) return;
wgpuRenderPassEncoderSetVertexBuffer(pass_, slot, it->second.buffer, offsetBytes,
it->second.size - offsetBytes);
}
void WebGPUDevice::setIndexBuffer(BufferHandle buffer) {
// The RHI carries the index TYPE on the draw, not the bind - record the
// buffer and bind it at draw time with the draw's format.
bound_index_buffer_ = static_cast<u32>(buffer);
}
// =============================================================================
// Textures
// =============================================================================
u32 WebGPUDevice::colorVariantOf(WGPUTextureFormat format) {
switch (format) {
case WGPUTextureFormat_RGBA8UnormSrgb: return kColorSrgb8;
case WGPUTextureFormat_RGBA16Float: return kColorRgba16f;
case WGPUTextureFormat_RGBA32Float: return kColorRgba32f;
case WGPUTextureFormat_BGRA8Unorm: return kColorBgra8;
default: return kColorRgba8;
}
}
bool WebGPUDevice::makeTexture(const TextureDesc& desc, const void* pixels, TextureRec& out) {
if (!device_) {
ES_LOG_ERROR("WebGPUDevice: no device to create a texture on");
return false;
}
const u32 layers = desc.layers > 1 ? desc.layers : 1;
WGPUTextureDescriptor td{};
td.dimension = WGPUTextureDimension_2D;
td.format = toWGPUTextureFormat(desc.format);
td.size = WGPUExtent3D{desc.width, desc.height, layers};
td.sampleCount = desc.samples > 1 ? kMsaaSamples : 1;
td.mipLevelCount = 1;
if (desc.mipmaps && td.sampleCount == 1 && !isDepthFormat(td.format)) {
for (u32 side = std::max(desc.width, desc.height); side > 1; side >>= 1) ++td.mipLevelCount;
}
// 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.
td.usage = isDepthFormat(td.format)
? (WGPUTextureUsage_TextureBinding | WGPUTextureUsage_RenderAttachment)
: (WGPUTextureUsage_TextureBinding | WGPUTextureUsage_CopyDst |
WGPUTextureUsage_CopySrc | WGPUTextureUsage_RenderAttachment);
// A compute target is also written by shaders. Only these formats have the capability in core WebGPU,
// and one that does not is created plain rather than refused: the record says what it got.
const bool storage = desc.storage && td.sampleCount == 1 &&
(td.format == WGPUTextureFormat_RGBA8Unorm || td.format == WGPUTextureFormat_RGBA16Float ||
td.format == WGPUTextureFormat_RGBA32Float);
if (storage) td.usage |= WGPUTextureUsage_StorageBinding;
// 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) {
ES_LOG_ERROR("WebGPUDevice: texture creation failed ({}x{})", desc.width, desc.height);
return false;
}
WGPUTextureView view = nullptr;
if (layers > 1) {
// Never an attachment, so the one view is the sampled one: every layer, every level.
WGPUTextureViewDescriptor vd{};
vd.format = td.format;
vd.dimension = WGPUTextureViewDimension_2DArray;
vd.mipLevelCount = td.mipLevelCount;
vd.arrayLayerCount = layers;
vd.aspect = WGPUTextureAspect_All;
view = wgpuTextureCreateView(texture, &vd);
} else if (td.mipLevelCount > 1) {
WGPUTextureViewDescriptor vd{};
vd.format = td.format;
vd.dimension = WGPUTextureViewDimension_2D;
vd.mipLevelCount = 1;
vd.arrayLayerCount = 1;
vd.aspect = WGPUTextureAspect_All;
view = wgpuTextureCreateView(texture, &vd);
} else {
view = wgpuTextureCreateView(texture, nullptr);
}
// A depth-stencil texture has two aspects and a sample may name only one, so
// the view a binding uses is depth-only. Every other format samples through
// the view it already has — the two members alias, and cleanup knows it.
WGPUTextureView sampleView = view;
if (isDepthFormat(td.format)) {
WGPUTextureViewDescriptor vd{};
// The ASPECT's format, not the texture's: a depth-only view of a
// depth24plus-stencil8 texture is a depth24plus view, and asking for it
// under the combined format is rejected as incompatible.
vd.format = td.format == WGPUTextureFormat_Depth24PlusStencil8
? WGPUTextureFormat_Depth24Plus
: td.format;
vd.dimension = WGPUTextureViewDimension_2D;
vd.mipLevelCount = 1;
vd.arrayLayerCount = 1;
vd.aspect = WGPUTextureAspect_DepthOnly;
sampleView = wgpuTextureCreateView(texture, &vd);
} else if (td.mipLevelCount > 1 && layers == 1) {
sampleView = wgpuTextureCreateView(texture, nullptr);
}
out = TextureRec{texture, view, sampleView,
desc.width, desc.height, td.format, desc.format,
packSamplerKey(desc.minFilter, desc.magFilter, desc.wrapS, desc.wrapT),
td.sampleCount, td.mipLevelCount};
out.storage = storage;
out.layers = layers;
if (pixels && !isDepthFormat(td.format) && layers > 1) {
// An array takes its layers in the rows given, as GL does (which cannot flip a 3D upload).
const usize layerBytes = static_cast<usize>(desc.width) * desc.height * gfxBytesPerPixel(desc.format);
for (u32 layer = 0; layer < layers; ++layer) {
writeTexture(out, 0, 0, desc.width, desc.height,
static_cast<const u8*>(pixels) + layerBytes * layer, false, layer);
}
if (out.mipLevels > 1) buildMipChain(out);
} else if (pixels && !isDepthFormat(td.format)) {
// desc.flipY, not false: the caller's orientation request has to reach the
// upload, which is where the row reversal happens (see writeTexture).
writeTexture(out, 0, 0, desc.width, desc.height, pixels, desc.flipY);
if (out.mipLevels > 1) buildMipChain(out);
}
return true;
}
bool WebGPUDevice::backendCreateTexture(u32 id, const TextureDesc& desc, const void* pixels) {
TextureRec rec;
if (!makeTexture(desc, pixels, rec)) return false;
textures_[id] = rec;
return true;
}
bool WebGPUDevice::backendCreateCompressedTexture(u32 id, const TextureDesc& desc, GfxCompressedFormat format,
const void* data, u32 byteLength, u32 mipLevels) {
if (!device_ || !queue_) {
ES_LOG_ERROR("WebGPUDevice::createCompressedTexture: no device");
return false;
}
const WGPUTextureFormat wgpuFmt = toWGPUCompressedFormat(format);
if (wgpuFmt == WGPUTextureFormat_Undefined) {
ES_LOG_ERROR("WebGPUDevice::createCompressedTexture: unmapped format");
return false;
}
const u32 levels = mipLevels ? mipLevels : 1;
WGPUTextureDescriptor td{};
td.dimension = WGPUTextureDimension_2D;
td.format = wgpuFmt;
td.size = WGPUExtent3D{desc.width, desc.height, 1};
td.mipLevelCount = levels;
td.sampleCount = 1;
td.usage = WGPUTextureUsage_TextureBinding | WGPUTextureUsage_CopyDst; // compressed = sampled, never a target
WGPUTexture texture = wgpuDeviceCreateTexture(device_, &td);
if (!texture) {
ES_LOG_ERROR("WebGPUDevice::createCompressedTexture: creation failed ({}x{})", desc.width, desc.height);
return false;
}
// Upload each mip level from the concatenated pyramid. writeTexture counts
// BLOCKS, not pixels (a partial edge block still counts a whole block).
const GfxBlockInfo bi = gfxCompressedBlockInfo(format);
const u8* ptr = static_cast<const u8*>(data);
const u8* end = ptr + byteLength;
for (u32 level = 0; ptr && level < levels; ++level) {
const u32 lw = (desc.width >> level) ? (desc.width >> level) : 1u;
const u32 lh = (desc.height >> level) ? (desc.height >> level) : 1u;
const u32 blocksX = (lw + bi.blockWidth - 1) / bi.blockWidth;
const u32 blocksY = (lh + bi.blockHeight - 1) / bi.blockHeight;
const u32 levelBytes = blocksX * blocksY * bi.bytesPerBlock;
if (levelBytes > static_cast<usize>(end - ptr)) break; // truncated pyramid
WGPUTexelCopyTextureInfo dst{};
dst.texture = texture;
dst.mipLevel = level;
dst.origin = WGPUOrigin3D{0, 0, 0};
WGPUTexelCopyBufferLayout layout{};
layout.bytesPerRow = blocksX * bi.bytesPerBlock;
layout.rowsPerImage = blocksY;
// The level's physical size, whole blocks: a level 634 texels tall is stored as 636, and a copy must name whole blocks. Its last
// block row holds texels past the edge, which the sampler never reads.
WGPUExtent3D extent{blocksX * bi.blockWidth, blocksY * bi.blockHeight, 1};
wgpuQueueWriteTexture(queue_, &dst, ptr, levelBytes, &layout, &extent);
ptr += levelBytes;
}
// A compressed texture is never a depth one, so it samples through the view
// it already has — the two members alias, as they do for any colour format.
WGPUTextureView view = wgpuTextureCreateView(texture, nullptr);
textures_[id] = TextureRec{texture, view, view,
desc.width, desc.height, wgpuFmt, desc.format,
packSamplerKey(desc.minFilter, desc.magFilter,
desc.wrapS, desc.wrapT)};
return true;
}
void WebGPUDevice::releaseTexture(TextureRec& rec) {
// The sample view first, and only when it is a view of its own: for a colour
// texture it aliases `view`, and releasing that twice frees a live object.
if (rec.sampleView && rec.sampleView != rec.view) {
evictBindGroups(static_cast<u64>(reinterpret_cast<uintptr_t>(rec.sampleView)));
wgpuTextureViewRelease(rec.sampleView);
}
if (rec.view) {
evictBindGroups(static_cast<u64>(reinterpret_cast<uintptr_t>(rec.view)));
wgpuTextureViewRelease(rec.view);
}
if (rec.texture) wgpuTextureRelease(rec.texture);
rec = TextureRec{};
}
void WebGPUDevice::backendDeleteTexture(u32 id) {
auto it = textures_.find(id);
if (it == textures_.end()) return;
releaseTexture(it->second);
textures_.erase(it);
}
void WebGPUDevice::backendMoveTexture(u32 into, u32 from) {
auto it = textures_.find(from);
if (it == textures_.end()) return;
textures_[into] = it->second;
textures_.erase(from);
for (u32 slot = 0; slot < kTextureSlots; ++slot) {
if (texture_slots_[slot] == into || texture_slots_[slot] == from) bind_group_dirty_ = true;
}
}
void WebGPUDevice::backendUpdateTexture(u32 id, i32 x, i32 y, u32 width, u32 height,
const void* pixels, bool flipY) {
auto it = textures_.find(id);
if (it == textures_.end()) return;
writeTexture(it->second, x, y, width, height, pixels, flipY);
}
void WebGPUDevice::writeTexture(const TextureRec& rec, i32 x, i32 y, u32 width, u32 height,
const void* pixels, bool flipY, u32 layer) {
if (!pixels || !queue_ || !rec.texture) return;
if (isDepthFormat(rec.format)) {
ES_LOG_ERROR("WebGPUDevice::updateTexture: depth-stencil textures are attachment-only");
return;
}
WGPUTexelCopyTextureInfo dst{};
dst.texture = rec.texture;
dst.origin = WGPUOrigin3D{static_cast<u32>(x), static_cast<u32>(y), layer};
// Source rows are what the caller allocated; destination rows are the texel
// size WebGPU stores. They differ for RGB8, which has no WebGPU format and so
// lands in an RGBA8 texture — reading dstRow from the source is the over-read.
const u32 srcBpp = gfxBytesPerPixel(rec.srcFormat);
const u32 dstBpp = wgpuBytesPerPixel(rec.srcFormat);
const usize dstRow = static_cast<usize>(width) * dstBpp;
WGPUTexelCopyBufferLayout layout{};
layout.bytesPerRow = static_cast<u32>(dstRow);
layout.rowsPerImage = height;
// Decoded images arrive top-first while the engine samples v upward. GL flips
// with UNPACK_FLIP_Y_WEBGL; WebGPU has no pixel-store parameter, so rows are
// reversed here — the same bytes GL sends, which is what keeps the two equal.
const bool reverseRows = flipY && height > 1;
std::vector<u8> staged;
const void* src = pixels;
if (reverseRows || srcBpp != dstBpp) {
staged.resize(dstRow * height);
stageTextureRows(staged.data(), static_cast<const u8*>(pixels),
width, height, srcBpp, dstBpp, reverseRows);
src = staged.data();
}
WGPUExtent3D extent{width, height, 1};
wgpuQueueWriteTexture(queue_, &dst, src, dstRow * height, &layout, &extent);
}
void WebGPUDevice::backendSetTextureParams(u32 id, const TextureDesc& desc) {
// GL's texture-object sampler state, de-combined: the texture record carries
// its params key and the bind group pairs it with a cached sampler object.
auto it = textures_.find(id);
if (it == textures_.end()) return;
const u8 key = packSamplerKey(desc.minFilter, desc.magFilter, desc.wrapS, desc.wrapT);
if (it->second.samplerKey == key) return;
it->second.samplerKey = key;
for (u32 slot = 0; slot < kTextureSlots; ++slot) {
if (texture_slots_[slot] == id) {
bind_group_dirty_ = true;
break;
}
}
}
void WebGPUDevice::backendGenerateMipmaps(u32 id) {
auto it = textures_.find(id);
if (it != textures_.end() && it->second.mipLevels > 1) buildMipChain(it->second);
}
void WebGPUDevice::bindTexture(u32 slot, TextureHandle texture) {
if (slot >= kTextureSlots) return;
const u32 id = static_cast<u32>(texture);
if (texture_slots_[slot] != id) {
texture_slots_[slot] = id;
bind_group_dirty_ = true;
}
}
bool WebGPUDevice::supportsCompressedFormat(GfxCompressedFormat format) {
if (toWGPUCompressedFormat(format) == WGPUTextureFormat_Undefined) return false;
if (!device_) return false;
// The DEVICE, not the adapter: a format the adapter offers is unusable until
// the device was created asking for its feature, and createTexture rejects it
// — which arrives as a texture that never loaded rather than as this answer.
return wgpuDeviceHasFeature(device_, compressionFeatureFor(format)) != 0;
}
// =============================================================================
// Programs (WGSL shader modules)
// =============================================================================
bool WebGPUDevice::backendCreateProgram(u32 id, const GfxShaderSource& source,
const GfxAttribBinding*, u32,
std::string* outLog, GfxShaderStage* outFailedStage) {
if (source.language != GfxShaderLanguage::WGSL) {
if (outLog) *outLog = "WebGPUDevice compiles WGSL only";
if (outFailedStage) *outFailedStage = GfxShaderStage::Vertex;
ES_LOG_ERROR("WebGPUDevice::createProgram: unsupported shader language");
return false;
}
if (!device_) {
if (outLog) *outLog = "no WGPUDevice";
ES_LOG_ERROR("WebGPUDevice::createProgram: no device");
return false;
}
// A stage that names `tN`/`sN` without declaring it cannot compile, and WebGPU says
// so as an invalid PIPELINE naming no shader — so the refusal is here, where the
// source is still in hand. check-wgsl-twin holds the repo's own to the same rule.
const auto undeclared = [&](const char* src, const char* stage) -> bool {
u32 reachedTex = 0;
u32 reachedSam = 0;
scanWGSLReachedUnits(src, reachedTex, reachedSam);
const u32 declared = scanWGSLBindingMask(src, 1);
for (u32 unit = 0; unit < 16; ++unit) {
const bool tex = (reachedTex & (1u << unit)) != 0
&& (declared & (1u << textureBindingForUnit(unit))) == 0;
const bool sam = (reachedSam & (1u << unit)) != 0
&& (declared & (1u << samplerBindingForUnit(unit))) == 0;
if (!tex && !sam) continue;
if (outLog) {
*outLog = std::string("the ") + stage + " stage reaches "
+ (tex ? "t" : "s") + std::to_string(unit) + " and declares no binding for it";
}
ES_LOG_ERROR("WebGPUDevice::createProgram: the {} stage reaches {}{} and declares "
"no binding for it", stage, tex ? "t" : "s", unit);
return true;
}
return false;
};
if (undeclared(source.vertexSrc, "vertex")) {
if (outFailedStage) *outFailedStage = GfxShaderStage::Vertex;
return false;
}
if (undeclared(source.fragmentSrc, "fragment")) {
if (outFailedStage) *outFailedStage = GfxShaderStage::Fragment;
return false;
}
auto makeModule = [&](const char* code) -> WGPUShaderModule {
WGPUShaderSourceWGSL wgsl{};
wgsl.chain.sType = WGPUSType_ShaderSourceWGSL;
wgsl.code = sv(code);
WGPUShaderModuleDescriptor md{};
md.nextInChain = &wgsl.chain;
return wgpuDeviceCreateShaderModule(device_, &md);
};
ProgramRec rec{};
rec.vertex = makeModule(source.vertexSrc);
rec.fragment = makeModule(source.fragmentSrc);
// Reflection-by-scan: bind groups must match the pipeline's auto layout
// exactly, so record which group-0 UBO slots and group-1 texture/sampler
// bindings the program declares (twin discipline: declare = use).
rec.group0Mask = scanWGSLBindingMask(source.vertexSrc, 0) |
scanWGSLBindingMask(source.fragmentSrc, 0);
rec.group1Mask = scanWGSLBindingMask(source.vertexSrc, 1) |
scanWGSLBindingMask(source.fragmentSrc, 1);
rec.group1DepthMask = scanWGSLDepthTextureMask(source.vertexSrc, 1) |
scanWGSLDepthTextureMask(source.fragmentSrc, 1);
rec.group1ArrayMask = scanWGSLArrayTextureMask(source.vertexSrc, 1) |
scanWGSLArrayTextureMask(source.fragmentSrc, 1);
// What the VERTEX stage declares, on its own: a sampled texture is visible
// to the fragment stage alone unless the layout says otherwise, and reading
// one it was not given is a pipeline WebGPU rejects with nothing named.
rec.group1VertexMask = scanWGSLBindingMask(source.vertexSrc, 1);
if (!rec.vertex || !rec.fragment) {
if (rec.vertex) wgpuShaderModuleRelease(rec.vertex);
if (rec.fragment) wgpuShaderModuleRelease(rec.fragment);
if (outLog) *outLog = "shader module creation failed";
if (outFailedStage) *outFailedStage = rec.vertex ? GfxShaderStage::Fragment : GfxShaderStage::Vertex;
return false;
}
programs_[id] = rec;
return true;
}
void WebGPUDevice::backendDeleteProgram(u32 id) {
auto it = programs_.find(id);
if (it == programs_.end()) return;
if (it->second.vertex) wgpuShaderModuleRelease(it->second.vertex);
if (it->second.fragment) wgpuShaderModuleRelease(it->second.fragment);
programs_.erase(it);
}
// =============================================================================
// Pipelines (descriptors retained; WGPURenderPipeline built lazily per pass
// depth-stencil shape — WebGPU validates that coupling, GL never had it)
// =============================================================================
WGPURenderPipeline WebGPUDevice::ensurePipeline(u32 id) {
const PipelineDesc* described = pipelineDesc(PipelineHandle{id});
if (!described || !device_) return nullptr;
PipelineRec& built = pipelines_[id];
const u32 dsVariant = dsVariantOf(pass_ds_format_);
const PipelineDesc& desc = *described;
const bool writesAlbedo = pass_albedo_ && desc.gbuffer && desc.albedo;
const u32 gbufferVariant = !pass_gbuffer_ ? kGBufferNone
: writesAlbedo ? kGBufferWritesAlbedo
: desc.gbuffer ? kGBufferWrites : kGBufferSkips;
const u32 variant = ((dsVariant * kColorVariantCount + colorVariantOf(pass_color_format_))
* kSampleVariantCount + (pass_samples_ > 1 ? kMultiSample : kSingleSample))
* kGBufferVariantCount + gbufferVariant;
if (built.variants[variant]) return built.variants[variant];
auto progIt = programs_.find(static_cast<u32>(desc.program));
const VertexLayoutDesc* layout = vertexLayoutDesc(desc.vertexLayout);
if (progIt == programs_.end() || !layout) {
ES_LOG_ERROR("WebGPUDevice::ensurePipeline: missing program or layout");
return nullptr;
}
const VertexLayoutDesc& vl = *layout;
// RHI layout (attributes across up to 2 slots) -> per-slot WGPU buffer layouts.
WGPUVertexAttribute attrs[MAX_VERTEX_ATTRIBUTES] = {};
WGPUVertexBufferLayout slots[MAX_VERTEX_BUFFER_SLOTS] = {};
u32 attrCursor = 0;
u32 slotCount = 0;
for (u32 slot = 0; slot < MAX_VERTEX_BUFFER_SLOTS; ++slot) {
const u32 first = attrCursor;
for (u32 i = 0; i < vl.attributeCount; ++i) {
const auto& a = vl.attributes[i];
if (a.bufferSlot != slot) continue;
attrs[attrCursor].format = toWGPUVertexFormat(a.components, a.type, a.normalized);
attrs[attrCursor].offset = a.offset;
attrs[attrCursor].shaderLocation = a.location;
++attrCursor;
}
if (attrCursor == first) continue;
slots[slotCount].stepMode = vl.instanceStep[slot] ? WGPUVertexStepMode_Instance
: WGPUVertexStepMode_Vertex;
slots[slotCount].arrayStride = vl.strides[slot];
slots[slotCount].attributeCount = attrCursor - first;
slots[slotCount].attributes = &attrs[first];
++slotCount;
}
const BlendStateWGPU blend = toWGPUBlend(desc.blend);
WGPUBlendState blendState{};
blendState.color = blend.color;
blendState.alpha = blend.alpha;
WGPUColorTargetState targets[3]{};
targets[0].format = pass_color_format_;
targets[0].blend = desc.blendEnabled ? &blendState : nullptr;
targets[0].writeMask = (writesStencil(desc.stencil) || !desc.colorWrite) ? WGPUColorWriteMask_None
: WGPUColorWriteMask_All;
// The second attachment, when the pass has one: written by a shader that has the output, and
// declared with an empty write mask by every other — WebGPU asks the pipeline to account for
// every attachment of the pass, and a shader with one output may not be given a mask that
// would write the second. Never blended: a normal averaged with what was there is neither's.
targets[1].format = WGPUTextureFormat_RGBA8Unorm;
targets[1].writeMask = (desc.gbuffer && desc.colorWrite && !writesStencil(desc.stencil)) ? WGPUColorWriteMask_All
: WGPUColorWriteMask_None;
// The third, the albedo, the same way: written only by a shader that has a location-2 output.
targets[2].format = WGPUTextureFormat_RGBA8Unorm;
targets[2].writeMask = (writesAlbedo && desc.colorWrite && !writesStencil(desc.stencil)) ? WGPUColorWriteMask_All
: WGPUColorWriteMask_None;
WGPUFragmentState fragment{};
fragment.module = progIt->second.fragment;
fragment.entryPoint = sv("fs_main");
fragment.targetCount = !pass_gbuffer_ ? 1 : pass_albedo_ ? 3 : 2;
fragment.targets = targets;
WGPURenderPipelineDescriptor pd{};
// Explicit layout from the program's binding masks — the same cached
// objects flushBindGroup builds bind groups against, so declared-but-
// unbound bindings are legal (dummy backfill) and group compatibility
// holds by identity.
pd.layout = pipelineLayoutFor(progIt->second.group0Mask, progIt->second.group1Mask,
progIt->second.group1DepthMask,
progIt->second.group1VertexMask,
progIt->second.group1ArrayMask);
pd.vertex.module = progIt->second.vertex;
pd.vertex.entryPoint = sv("vs_main");
pd.vertex.bufferCount = slotCount;
pd.vertex.buffers = slots;
pd.primitive.topology = desc.topology == GfxTopology::Lines ? WGPUPrimitiveTopology_LineList
: WGPUPrimitiveTopology_TriangleList;
pd.primitive.frontFace = WGPUFrontFace_CCW;
pd.primitive.cullMode = toWGPUCullMode(desc.cullEnabled, desc.cullFront);
// 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;
// WebGPU refuses coverage from alpha on a single-sampled pipeline.
pd.multisample.alphaToCoverageEnabled = desc.alphaToCoverage && pass_samples_ > 1;
pd.fragment = &fragment;
WGPUDepthStencilState ds{};
if (dsVariant != kDsNone) {
ds = toWGPUDepthStencil(desc, pass_ds_format_);
pd.depthStencil = &ds;
} else if (desc.depthTest || desc.stencil != GfxStencilMode::Off) {
ES_LOG_WARN("WebGPUDevice::ensurePipeline: depth/stencil requested but the "
"pass target has no depth-stencil attachment");
}
built.variants[variant] = wgpuDeviceCreateRenderPipeline(device_, &pd);
if (!built.variants[variant]) {
ES_LOG_ERROR("WebGPUDevice::ensurePipeline: creation failed");
}
return built.variants[variant];
}
void WebGPUDevice::backendSetPipeline(u32 id, const PipelineDesc&) {
bound_pipeline_ = id;
if (!pass_) return;
if (WGPURenderPipeline p = ensurePipeline(id)) {
wgpuRenderPassEncoderSetPipeline(pass_, p);
bind_group_dirty_ = true; // group layout may differ across pipelines
}
}
void WebGPUDevice::setStencilReference(i32 reference) {
stencil_ref_ = reference;
if (pass_) wgpuRenderPassEncoderSetStencilReference(pass_, static_cast<u32>(reference));
}
WGPUSampler WebGPUDevice::samplerFor(u8 key) {
auto it = samplers_.find(key);
if (it != samplers_.end()) return it->second;
if (!device_) return nullptr;
WGPUSamplerDescriptor sd{};
sd.minFilter = (key & 1u) ? WGPUFilterMode_Nearest : WGPUFilterMode_Linear;
sd.magFilter = (key & 2u) ? WGPUFilterMode_Nearest : WGPUFilterMode_Linear;
sd.addressModeU = toWGPUAddressMode(static_cast<TextureWrap>((key >> 2) & 3u));
sd.addressModeV = toWGPUAddressMode(static_cast<TextureWrap>((key >> 4) & 3u));
sd.addressModeW = WGPUAddressMode_ClampToEdge;
// Trilinear across mips when a texture has them (compressed KTX2 pyramids);
// with a single mip WebGPU samples level 0 unchanged, so this is harmless for
// the still-common single-mip textures.
sd.mipmapFilter = WGPUMipmapFilterMode_Linear;
sd.lodMinClamp = 0.0f;
sd.lodMaxClamp = 32.0f;
// Sharpened at a slant (a floor, a hair card, a sleeve seen edge-on): the sampler takes extra samples along the footprint's long side.
// WebGPU allows it only when every filter is linear, so a nearest-filtered sampler stays at one.
sd.maxAnisotropy = (key & 3u) == 0u ? 16 : 1;
WGPUSampler sampler = wgpuDeviceCreateSampler(device_, &sd);
samplers_[key] = sampler;
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;
}
WGPURenderPipeline WebGPUDevice::ensureMipPipeline(WGPUTextureFormat format) {
const u32 key = static_cast<u32>(format);
auto it = mip_pipelines_.find(key);
if (it != mip_pipelines_.end()) return it->second;
if (!device_) return nullptr;
// The triangle's uv runs down the target as its rows do, so a level keeps the
// orientation of the one it is made from.
static const char* kWGSL = R"(
struct VSOut { @builtin(position) pos : vec4f, @location(0) uv : vec2f };
@vertex fn vs_main(@builtin(vertex_index) i : u32) -> VSOut {
var p = array<vec2f, 3>(vec2f(-1.0, 1.0), vec2f(3.0, 1.0), vec2f(-1.0, -3.0));
var out : VSOut;
out.pos = vec4f(p[i], 0.0, 1.0);
out.uv = vec2f(p[i].x * 0.5 + 0.5, 0.5 - p[i].y * 0.5);
return out;
}
@group(0) @binding(0) var src : texture_2d<f32>;
@group(0) @binding(1) var smp : sampler;
@fragment fn fs_main(v : VSOut) -> @location(0) vec4f {
return textureSampleLevel(src, smp, v.uv, 0.0);
}
)";
if (!mip_module_) {
WGPUShaderSourceWGSL wgsl{};
wgsl.chain.sType = WGPUSType_ShaderSourceWGSL;
wgsl.code = sv(kWGSL);
WGPUShaderModuleDescriptor md{};
md.nextInChain = &wgsl.chain;
mip_module_ = wgpuDeviceCreateShaderModule(device_, &md);
}
if (!mip_bgl_) {
WGPUBindGroupLayoutEntry entries[2]{};
entries[0].binding = 0;
entries[0].visibility = WGPUShaderStage_Fragment;
entries[0].texture.sampleType = WGPUTextureSampleType_Float;
entries[0].texture.viewDimension = WGPUTextureViewDimension_2D;
entries[1].binding = 1;
entries[1].visibility = WGPUShaderStage_Fragment;
entries[1].sampler.type = WGPUSamplerBindingType_Filtering;
WGPUBindGroupLayoutDescriptor bld{};
bld.entryCount = 2;
bld.entries = entries;
mip_bgl_ = wgpuDeviceCreateBindGroupLayout(device_, &bld);
WGPUPipelineLayoutDescriptor pld{};
pld.bindGroupLayoutCount = 1;
pld.bindGroupLayouts = &mip_bgl_;
mip_layout_ = wgpuDeviceCreatePipelineLayout(device_, &pld);
WGPUSamplerDescriptor sd{};
sd.minFilter = WGPUFilterMode_Linear;
sd.magFilter = WGPUFilterMode_Linear;
sd.mipmapFilter = WGPUMipmapFilterMode_Nearest;
sd.addressModeU = WGPUAddressMode_ClampToEdge;
sd.addressModeV = WGPUAddressMode_ClampToEdge;
sd.addressModeW = WGPUAddressMode_ClampToEdge;
sd.lodMaxClamp = 32.0f;
sd.maxAnisotropy = 1;
mip_sampler_ = wgpuDeviceCreateSampler(device_, &sd);
}
WGPURenderPipelineDescriptor pd{};
pd.layout = mip_layout_;
pd.vertex.module = mip_module_;
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;
WGPUColorTargetState target{};
target.format = format;
target.writeMask = WGPUColorWriteMask_All;
WGPUFragmentState fragment{};
fragment.module = mip_module_;
fragment.entryPoint = sv("fs_main");
fragment.targetCount = 1;
fragment.targets = ⌖
pd.fragment = &fragment;
WGPURenderPipeline pipeline = wgpuDeviceCreateRenderPipeline(device_, &pd);
if (!pipeline) ES_LOG_ERROR("WebGPUDevice: mip pipeline creation failed");
mip_pipelines_[key] = pipeline;
return pipeline;
}
void WebGPUDevice::buildMipChain(const TextureRec& rec) {
if (!device_ || !queue_ || rec.mipLevels < 2) return;
WGPURenderPipeline pipeline = ensureMipPipeline(rec.format);
if (!pipeline) return;
// Its own encoder, submitted at once: an upload can land in the middle of a
// frame, and the frame's encoder may have a pass open.
WGPUCommandEncoder encoder = wgpuDeviceCreateCommandEncoder(device_, nullptr);
if (!encoder) return;
// Each layer of an array is its own chain: views[layer * mipLevels + level] is one level of one layer.
std::vector<WGPUTextureView> views;
std::vector<WGPUBindGroup> groups;
for (u32 layer = 0; layer < rec.layers; ++layer) {
for (u32 level = 0; level < rec.mipLevels; ++level) {
WGPUTextureViewDescriptor vd{};
vd.format = rec.format;
vd.dimension = WGPUTextureViewDimension_2D;
vd.baseMipLevel = level;
vd.mipLevelCount = 1;
vd.baseArrayLayer = layer;
vd.arrayLayerCount = 1;
vd.aspect = WGPUTextureAspect_All;
views.push_back(wgpuTextureCreateView(rec.texture, &vd));
}
}
for (u32 step = 0; step < rec.layers * rec.mipLevels; ++step) {
const u32 level = step % rec.mipLevels;
if (level == 0) continue;
WGPUBindGroupEntry entries[2]{};
entries[0].binding = 0;
entries[0].textureView = views[step - 1];
entries[1].binding = 1;
entries[1].sampler = mip_sampler_;
WGPUBindGroupDescriptor bgd{};
bgd.layout = mip_bgl_;
bgd.entryCount = 2;
bgd.entries = entries;
WGPUBindGroup group = wgpuDeviceCreateBindGroup(device_, &bgd);
if (!group) break;
groups.push_back(group);
WGPURenderPassColorAttachment color{};
color.view = views[step];
color.depthSlice = WGPU_DEPTH_SLICE_UNDEFINED;
color.loadOp = WGPULoadOp_Clear;
color.storeOp = WGPUStoreOp_Store;
WGPURenderPassDescriptor rp{};
rp.colorAttachmentCount = 1;
rp.colorAttachments = &color;
WGPURenderPassEncoder pass = wgpuCommandEncoderBeginRenderPass(encoder, &rp);
if (!pass) break;
wgpuRenderPassEncoderSetPipeline(pass, pipeline);
wgpuRenderPassEncoderSetBindGroup(pass, 0, group, 0, nullptr);
wgpuRenderPassEncoderDraw(pass, 3, 1, 0, 0);
wgpuRenderPassEncoderEnd(pass);
wgpuRenderPassEncoderRelease(pass);
}
WGPUCommandBuffer commands = wgpuCommandEncoderFinish(encoder, nullptr);
if (commands) {
wgpuQueueSubmit(queue_, 1, &commands);
wgpuCommandBufferRelease(commands);
}
wgpuCommandEncoderRelease(encoder);
for (WGPUBindGroup group : groups) wgpuBindGroupRelease(group);
for (WGPUTextureView view : views) wgpuTextureViewRelease(view);
}
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
// at z=1 (GL's clear depth) writes exactly the attachments requested: color via
// the write mask, depth via depthWriteEnabled + Always, stencil via
// Replace + the encoder's stencil reference.
// =============================================================================
WGPURenderPipeline WebGPUDevice::ensureClearPipeline(bool color, bool depth, bool stencil) {
// 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 = (pass_gbuffer_ ? 1u << 12 : 0u) | (pass_albedo_ ? 1u << 13 : 0u) |
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;
static const char* kClearVS = 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], 1.0, 1.0);
}
)";
static const char* kClearFS = R"(
struct ClearColor { value : vec4f };
@group(0) @binding(0) var<uniform> clearColor : ClearColor;
@fragment fn fs_main() -> @location(0) vec4f { return clearColor.value; }
)";
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);
};
// One explicit layout for the whole family, so the single bind group is
// valid with every write-mask variant (auto layouts are per-pipeline).
if (!clear_bgl_) {
WGPUBindGroupLayoutEntry ble{};
ble.binding = 0;
ble.visibility = WGPUShaderStage_Fragment;
ble.buffer.type = WGPUBufferBindingType_Uniform;
ble.buffer.minBindingSize = 16;
WGPUBindGroupLayoutDescriptor bld{};
bld.entryCount = 1;
bld.entries = &ble;
clear_bgl_ = wgpuDeviceCreateBindGroupLayout(device_, &bld);
WGPUPipelineLayoutDescriptor pld{};
pld.bindGroupLayoutCount = 1;
pld.bindGroupLayouts = &clear_bgl_;
clear_layout_ = wgpuDeviceCreatePipelineLayout(device_, &pld);
clear_color_buffer_ = makeBuffer(GfxBufferUsage::Uniform, 16, nullptr);
WGPUBindGroupEntry entry{};
entry.binding = 0;
entry.buffer = clear_color_buffer_;
entry.offset = 0;
entry.size = 16;
WGPUBindGroupDescriptor bgd{};
bgd.layout = clear_bgl_;
bgd.entryCount = 1;
bgd.entries = &entry;
clear_bind_group_ = wgpuDeviceCreateBindGroup(device_, &bgd);
}
WGPUShaderModule vs = makeModule(kClearVS);
WGPUShaderModule fs = makeModule(kClearFS);
WGPUColorTargetState clearTargets[3]{};
clearTargets[0].format = pass_color_format_;
clearTargets[0].writeMask = color ? WGPUColorWriteMask_All : WGPUColorWriteMask_None;
// A scoped clear is the camera's background, which a surface record has no part in.
clearTargets[1].format = WGPUTextureFormat_RGBA8Unorm;
clearTargets[1].writeMask = WGPUColorWriteMask_None;
clearTargets[2].format = WGPUTextureFormat_RGBA8Unorm;
clearTargets[2].writeMask = WGPUColorWriteMask_None;
WGPUFragmentState fragment{};
fragment.module = fs;
fragment.entryPoint = sv("fs_main");
fragment.targetCount = !pass_gbuffer_ ? 1 : pass_albedo_ ? 3 : 2;
fragment.targets = clearTargets;
WGPURenderPipelineDescriptor pd{};
pd.layout = clear_layout_;
pd.vertex.module = 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 = pass_samples_;
pd.multisample.mask = 0xFFFFFFFFu;
pd.fragment = &fragment;
WGPUDepthStencilState ds{};
if (pass_ds_format_ != WGPUTextureFormat_Undefined) {
ds.format = pass_ds_format_;
ds.depthCompare = WGPUCompareFunction_Always;
ds.depthWriteEnabled = depth ? WGPUOptionalBool_True : WGPUOptionalBool_False;
WGPUStencilFaceState face{};
face.compare = WGPUCompareFunction_Always;
face.failOp = stencil ? WGPUStencilOperation_Replace : WGPUStencilOperation_Keep;
face.depthFailOp = face.failOp;
face.passOp = face.failOp;
ds.stencilFront = face;
ds.stencilBack = face;
ds.stencilReadMask = 0xFFu;
ds.stencilWriteMask = stencil ? 0xFFu : 0x00u;
pd.depthStencil = &ds;
}
WGPURenderPipeline pipeline = wgpuDeviceCreateRenderPipeline(device_, &pd);
wgpuShaderModuleRelease(vs);
wgpuShaderModuleRelease(fs);
clear_pipelines_[key] = pipeline;
return pipeline;
}
void WebGPUDevice::drawInternalClear(bool color, bool depth, bool stencil,
const f32 rgba[4], i32 stencilValue,
const RenderPassDesc* region) {
if (!pass_ || !device_) return;
WGPURenderPipeline pipeline = ensureClearPipeline(color, depth, stencil);
if (!pipeline || !clear_bind_group_) return;
const f32 black[4] = {0.0f, 0.0f, 0.0f, 0.0f};
writeBufferPadded(clear_color_buffer_, 0, rgba ? rgba : black, 16);
// A region rides its own scissor and restores the full target; without one
// (mid-pass stencil reset) the currently active scissor applies — the same
// rectangle glClear would have honored.
if (region) {
setScissor(region->clearX, region->clearY,
static_cast<i32>(region->clearW), static_cast<i32>(region->clearH));
}
wgpuRenderPassEncoderSetPipeline(pass_, pipeline);
wgpuRenderPassEncoderSetBindGroup(pass_, 0, clear_bind_group_, 0, nullptr);
if (stencil) {
wgpuRenderPassEncoderSetStencilReference(pass_, static_cast<u32>(stencilValue));
}
wgpuRenderPassEncoderDraw(pass_, 3, 1, 0, 0);
if (region) {
wgpuRenderPassEncoderSetScissorRect(pass_, 0, 0, pass_width_, pass_height_);
}
if (stencil) {
wgpuRenderPassEncoderSetStencilReference(pass_, static_cast<u32>(stencil_ref_));
}
// The triangle clobbered pipeline/bind-group pass state; force the next
// user draw to re-establish everything.
bound_pipeline_ = 0;
bind_group_dirty_ = true;
}
WGPURenderPipeline WebGPUDevice::ensureFlipPipeline(WGPUTextureFormat format) {
const u32 key = static_cast<u32>(format);
if (auto it = flip_pipelines_.find(key); it != flip_pipelines_.end()) return it->second;
static const char* kFlipVS = 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* kFlipFS = R"(
@group(0) @binding(0) var source : texture_2d<f32>;
@fragment fn fs_main(@builtin(position) at : vec4f) -> @location(0) vec4f {
let size = vec2i(textureDimensions(source));
return textureLoad(source, vec2i(i32(at.x), size.y - 1 - i32(at.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 (!flip_bgl_) {
WGPUBindGroupLayoutEntry entry{};
entry.binding = 0;
entry.visibility = WGPUShaderStage_Fragment;
entry.texture.sampleType = WGPUTextureSampleType_UnfilterableFloat;
entry.texture.viewDimension = WGPUTextureViewDimension_2D;
WGPUBindGroupLayoutDescriptor bld{};
bld.entryCount = 1;
bld.entries = &entry;
flip_bgl_ = wgpuDeviceCreateBindGroupLayout(device_, &bld);
WGPUPipelineLayoutDescriptor pld{};
pld.bindGroupLayoutCount = 1;
pld.bindGroupLayouts = &flip_bgl_;
flip_layout_ = wgpuDeviceCreatePipelineLayout(device_, &pld);
}
WGPUShaderModule vs = makeModule(kFlipVS);
WGPUShaderModule fs = makeModule(kFlipFS);
WGPUColorTargetState target{};
target.format = format;
target.writeMask = WGPUColorWriteMask_All;
WGPUFragmentState fragment{};
fragment.module = fs;
fragment.entryPoint = sv("fs_main");
fragment.targetCount = 1;
fragment.targets = ⌖
WGPURenderPipelineDescriptor pd{};
pd.layout = flip_layout_;
pd.vertex.module = 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;
pd.fragment = &fragment;
WGPURenderPipeline pipeline = wgpuDeviceCreateRenderPipeline(device_, &pd);
wgpuShaderModuleRelease(vs);
wgpuShaderModuleRelease(fs);
flip_pipelines_[key] = pipeline;
return pipeline;
}
void WebGPUDevice::copyTextureFlippedY(TextureHandle src, TextureHandle dst) {
if (!device_ || !isDeviceUsable()) return;
const auto from = textures_.find(static_cast<u32>(src));
const auto to = textures_.find(static_cast<u32>(dst));
if (from == textures_.end() || to == textures_.end()) return;
if (from->second.samples > 1 || to->second.samples > 1
|| from->second.width != to->second.width || from->second.height != to->second.height) {
ES_LOG_ERROR("WebGPUDevice::copyTextureFlippedY: the two textures must be single-sampled and the same size");
return;
}
if (pass_) endRenderPass();
WGPURenderPipeline pipeline = ensureFlipPipeline(to->second.format);
if (!pipeline) return;
WGPUBindGroupEntry entry{};
entry.binding = 0;
entry.textureView = from->second.sampleView ? from->second.sampleView : from->second.view;
WGPUBindGroupDescriptor bgd{};
bgd.layout = flip_bgl_;
bgd.entryCount = 1;
bgd.entries = &entry;
WGPUBindGroup group = wgpuDeviceCreateBindGroup(device_, &bgd);
WGPURenderPassColorAttachment color{};
color.view = to->second.view;
color.depthSlice = WGPU_DEPTH_SLICE_UNDEFINED;
color.loadOp = WGPULoadOp_Clear;
color.storeOp = WGPUStoreOp_Store;
WGPURenderPassDescriptor rp{};
rp.colorAttachmentCount = 1;
rp.colorAttachments = &color;
WGPUCommandEncoder encoder = wgpuDeviceCreateCommandEncoder(device_, nullptr);
WGPURenderPassEncoder pass = wgpuCommandEncoderBeginRenderPass(encoder, &rp);
wgpuRenderPassEncoderSetPipeline(pass, pipeline);
wgpuRenderPassEncoderSetBindGroup(pass, 0, group, 0, nullptr);
wgpuRenderPassEncoderDraw(pass, 3, 1, 0, 0);
wgpuRenderPassEncoderEnd(pass);
wgpuRenderPassEncoderRelease(pass);
WGPUCommandBuffer commands = wgpuCommandEncoderFinish(encoder, nullptr);
wgpuQueueSubmit(queue_, 1, &commands);
wgpuCommandBufferRelease(commands);
wgpuCommandEncoderRelease(encoder);
wgpuBindGroupRelease(group);
}
WGPUBindGroupLayout WebGPUDevice::groupLayoutFor(u32 group, u32 mask, u32 depthMask,
u32 vertexMask, u32 arrayMask) {
// Every mask is part of the key: the same bindings sampled as depth or as an
// array are a DIFFERENT layout, and visibility is part of an entry too.
const std::array<u32, 5> key{group, mask, depthMask, vertexMask, arrayMask};
auto cached = group_layouts_.find(key);
if (cached != group_layouts_.end()) return cached->second;
if (!device_) return nullptr;
WGPUBindGroupLayoutEntry entries[kTextureSlots * 2];
u32 count = 0;
if (group == 0) {
// Engine UBO slots. minBindingSize stays 0: the shader's own struct
// size is validated per draw, and dummy backfill covers unbound slots.
for (u32 slot = 0; slot < kUniformSlots; ++slot) {
if ((mask & (1u << slot)) == 0) continue;
WGPUBindGroupLayoutEntry e{};
e.binding = slot;
e.visibility = WGPUShaderStage_Vertex | WGPUShaderStage_Fragment;
e.buffer.type = WGPUBufferBindingType_Uniform;
entries[count++] = e;
}
} else {
// Texture units through the unit→binding convention. Fragment-only
// visibility unless the vertex stage declared the binding itself: a
// stage sees only what its entry admits.
static_assert(kTextureSlots == kGroup1TextureUnits,
"device texture slots mirror the group-1 convention");
for (u32 unit = 0; unit < kTextureSlots; ++unit) {
const u32 tb = textureBindingForUnit(unit);
const u32 sb = samplerBindingForUnit(unit);
const auto stages = [&](u32 binding) {
return (vertexMask & (1u << binding))
? (WGPUShaderStage_Vertex | WGPUShaderStage_Fragment)
: WGPUShaderStage_Fragment;
};
if (mask & (1u << tb)) {
WGPUBindGroupLayoutEntry e{};
e.binding = tb;
e.visibility = stages(tb);
// A unit with no sampler cannot be textureSample'd, so it is
// unfilterable by construction — which is what lets rgba32float
// bind here. Filterable formats satisfy it too.
e.texture.sampleType =
(depthMask & (1u << tb)) ? WGPUTextureSampleType_Depth
: (mask & (1u << sb)) ? WGPUTextureSampleType_Float
: WGPUTextureSampleType_UnfilterableFloat;
e.texture.viewDimension = (arrayMask & (1u << tb)) ? WGPUTextureViewDimension_2DArray
: WGPUTextureViewDimension_2D;
entries[count++] = e;
}
if (mask & (1u << sb)) {
WGPUBindGroupLayoutEntry e{};
e.binding = sb;
e.visibility = stages(sb);
e.sampler.type = WGPUSamplerBindingType_Filtering;
entries[count++] = e;
}
}
}
WGPUBindGroupLayoutDescriptor bld{};
bld.entryCount = count;
bld.entries = entries;
WGPUBindGroupLayout layout = wgpuDeviceCreateBindGroupLayout(device_, &bld);
group_layouts_[key] = layout;
return layout;
}
WGPUPipelineLayout WebGPUDevice::pipelineLayoutFor(u32 group0Mask, u32 group1Mask,
u32 group1DepthMask, u32 group1VertexMask,
u32 group1ArrayMask) {
// The depth, visibility and array masks change the group-1 layout under this
// pipeline, so they have to reach the key here too — see groupLayoutFor.
const std::array<u32, 5> key{group0Mask, group1Mask, group1DepthMask, group1VertexMask, group1ArrayMask};
auto cached = pipeline_layouts_.find(key);
if (cached != pipeline_layouts_.end()) return cached->second;
if (!device_) return nullptr;
// Group indices are positional: a program with group-1 bindings always
// carries a group-0 layout too (zero entries when the mask is empty).
WGPUBindGroupLayout bgls[2];
u32 count = 0;
if (group0Mask != 0 || group1Mask != 0) bgls[count++] = groupLayoutFor(0, group0Mask);
if (group1Mask != 0) {
bgls[count++] = groupLayoutFor(1, group1Mask, group1DepthMask, group1VertexMask, group1ArrayMask);
}
WGPUPipelineLayoutDescriptor pld{};
pld.bindGroupLayoutCount = count;
pld.bindGroupLayouts = bgls;
WGPUPipelineLayout layout = wgpuDeviceCreatePipelineLayout(device_, &pld);
pipeline_layouts_[key] = layout;
return layout;
}
void WebGPUDevice::ensureDummies() {
if (!dummy_ubo_.buffer) {
// Sized past the largest engine block (LightConstants, just under 16 KB with the tiled lights) so a
// declared-but-unbound block always satisfies draw-time size validation.
const std::vector<u8> zeros(16384, 0);
dummy_ubo_ = BufferRec{makeBuffer(GfxBufferUsage::Uniform, 16384, zeros.data()), 16384,
GfxBufferUsage::Uniform};
}
if (!dummy_texture_.texture) {
const u8 white[4] = {255, 255, 255, 255};
makeTexture(TextureDesc{}, white, dummy_texture_);
}
if (!dummy_depth_texture_.texture) {
// Never written, only bound: a depth format takes no upload, and the
// point is a texture of the right KIND under a declared depth binding.
TextureDesc td{};
td.format = GfxPixelFormat::Depth24Stencil8;
makeTexture(td, nullptr, dummy_depth_texture_);
}
if (!dummy_array_texture_.texture) {
const u8 white[8] = {255, 255, 255, 255, 255, 255, 255, 255};
TextureDesc td{};
td.layers = 2;
makeTexture(td, white, dummy_array_texture_);
}
}
WGPUBindGroup WebGPUDevice::cachedBindGroup(const u64* ids, u32 idCount,
const WGPUBindGroupDescriptor& desc) {
u64 hash = 1469598103934665603ull ^ reinterpret_cast<uintptr_t>(desc.layout);
for (u32 i = 0; i < idCount; ++i) hash = (hash ^ ids[i]) * 1099511628211ull;
auto found = bind_group_cache_.find(hash);
if (found != bind_group_cache_.end()) {
for (auto& e : found->second) {
if (e.layout != desc.layout || e.ids.size() != idCount) continue;
bool same = true;
for (u32 i = 0; i < idCount; ++i) {
if (e.ids[i] != ids[i]) { same = false; break; }
}
if (same) { e.used = bind_group_frame_; return e.bg; } // hit — reuse, no wgpuDeviceCreateBindGroup
}
}
// Miss. When full, only what neither this frame nor the last bound goes: emptying the cache made a view of more groups than
// it holds create every one of them again each frame, and the device ran out of descriptors within some hundreds of frames.
if (bind_group_count_ >= kBindGroupCacheCap) {
for (auto it = bind_group_cache_.begin(); it != bind_group_cache_.end();) {
auto& bucket = it->second;
for (usize i = bucket.size(); i-- > 0;) {
if (bucket[i].used + 1 >= bind_group_frame_) continue;
if (bucket[i].bg) wgpuBindGroupRelease(bucket[i].bg);
bucket.erase(bucket.begin() + static_cast<std::ptrdiff_t>(i));
--bind_group_count_;
}
it = bucket.empty() ? bind_group_cache_.erase(it) : std::next(it);
}
}
WGPUBindGroup bg = wgpuDeviceCreateBindGroup(device_, &desc);
if (bg) {
bind_group_cache_[hash].push_back({desc.layout, std::vector<u64>(ids, ids + idCount), bg, bind_group_frame_});
++bind_group_count_;
}
return bg;
}
void WebGPUDevice::flushBindGroup() {
if (!bind_group_dirty_ || !pass_ || !device_) return;
WGPURenderPipeline p = ensurePipeline(bound_pipeline_);
if (!p) return;
const ProgramRec* prog = nullptr;
if (const PipelineDesc* desc = pipelineDesc(PipelineHandle{bound_pipeline_})) {
auto progIt = programs_.find(static_cast<u32>(desc->program));
if (progIt != programs_.end()) prog = &progIt->second;
}
if (!prog) return;
if (prog->group0Mask == 0 && prog->group1Mask == 0) {
bind_group_dirty_ = false;
return;
}
ensureDummies();
// Group 0 = the engine's UBO bindings (0..4). Every mask bit gets an entry
// against the explicit layout: the armed slot's buffer (the engine keeps
// Frame/Time/DrawParams on 0/3/4, Material/Light arrive per draw/frame), or
// the zeroed dummy for a declared-but-unbound slot. A group-1-only program
// still sets a (zero-entry) group 0, keeping indices positional.
{
WGPUBindGroupEntry entries[kUniformSlots];
u32 count = 0;
for (u32 slot = 0; slot < kUniformSlots; ++slot) {
if ((prog->group0Mask & (1u << slot)) == 0) continue;
auto it = buffers_.find(uniform_slots_[slot]);
const bool armed = it != buffers_.end() && it->second.buffer;
const BufferRec& bound = armed ? it->second : dummy_ubo_;
if (!bound.buffer) continue;
WGPUBindGroupEntry e{};
e.binding = slot;
e.buffer = bound.buffer;
e.offset = armed ? uniform_offsets_[slot] : 0;
e.size = armed && uniform_sizes_[slot] ? uniform_sizes_[slot] : bound.size;
entries[count++] = e;
}
WGPUBindGroupDescriptor bgd{};
bgd.layout = groupLayoutFor(0, prog->group0Mask);
bgd.entryCount = count;
bgd.entries = entries;
// An offset is keyed with its top bit set, so it never equals the buffer
// pointer evictBindGroups looks for.
u64 ids[kUniformSlots * 2];
for (u32 i = 0; i < count; ++i) {
ids[i * 2] = static_cast<u64>(reinterpret_cast<uintptr_t>(entries[i].buffer));
ids[i * 2 + 1] = (u64{1} << 63) | (entries[i].offset << 20) | entries[i].size;
}
bind_group_ = cachedBindGroup(ids, count * 2, bgd);
if (bind_group_) wgpuRenderPassEncoderSetBindGroup(pass_, 0, bind_group_, 0, nullptr);
}
// Group 1: the texture units through the unit→binding convention (engine
// units 0..7 at texture bindings 0..7 / samplers 8..15, material units
// 8..15 at 16..23 / 24..31; sampler i carries texture i's filter/wrap
// params via the sampler cache). Every declared binding gets an entry —
// the bound unit's view/sampler or the 1x1 white dummy — so the group
// always matches the explicit layout, textures bound or not.
if (prog->group1Mask != 0) {
const TextureRec* dummy = dummy_texture_.texture ? &dummy_texture_ : nullptr;
const TextureRec* depthDummy = dummy_depth_texture_.texture ? &dummy_depth_texture_ : nullptr;
const TextureRec* arrayDummy = dummy_array_texture_.texture ? &dummy_array_texture_ : nullptr;
WGPUBindGroupEntry texEntries[kTextureSlots * 2];
u32 texCount = 0;
for (u32 unit = 0; unit < kTextureSlots; ++unit) {
// A pass may not sample what it draws into: WebGPU rejects the whole
// COMMAND BUFFER for it, not the draw. The dummy stands in — reading
// one's own attachment is undefined under every backend anyway.
const u32 bound = texture_slots_[unit];
const bool feedback = bound != 0 && (bound == pass_color_texture_ ||
bound == pass_depth_texture_);
auto it = feedback ? textures_.end() : textures_.find(bound);
const TextureRec* rec = (it != textures_.end()) ? &it->second : dummy;
if (!rec) continue;
const u32 tb = textureBindingForUnit(unit);
const u32 sb = samplerBindingForUnit(unit);
if (prog->group1Mask & (1u << tb)) {
// A depth declaration must be fed a depth texture even when the
// unit is unbound: the white dummy under `sampleType = Depth` is
// a validation error, not a blank sample.
const bool wantsDepth = (prog->group1DepthMask & (1u << tb)) != 0;
// The view's dimension must be the declaration's: an array where a
// 2D texture is declared, or the reverse, is the dummy of the right kind.
const bool wantsArray = (prog->group1ArrayMask & (1u << tb)) != 0;
const TextureRec* src = rec;
if (wantsDepth && !isDepthFormat(src->format)) src = depthDummy;
else if (wantsArray && src->layers == 1) src = arrayDummy;
else if (!wantsArray && src->layers > 1) src = dummy;
if (!src) continue;
WGPUBindGroupEntry e{};
e.binding = tb;
e.textureView = src->sampleView;
texEntries[texCount++] = e;
}
if (prog->group1Mask & (1u << sb)) {
WGPUBindGroupEntry e{};
e.binding = sb;
e.sampler = samplerFor(rec->samplerKey);
texEntries[texCount++] = e;
}
}
WGPUBindGroupDescriptor tgd{};
tgd.layout = groupLayoutFor(1, prog->group1Mask, prog->group1DepthMask,
prog->group1VertexMask, prog->group1ArrayMask);
tgd.entryCount = texCount;
tgd.entries = texEntries;
u64 tids[kTextureSlots * 2];
for (u32 i = 0; i < texCount; ++i) {
const uintptr_t p = texEntries[i].textureView
? reinterpret_cast<uintptr_t>(texEntries[i].textureView)
: reinterpret_cast<uintptr_t>(texEntries[i].sampler);
tids[i] = static_cast<u64>(p);
}
texture_group_ = cachedBindGroup(tids, texCount, tgd);
if (texture_group_) wgpuRenderPassEncoderSetBindGroup(pass_, 1, texture_group_, 0, nullptr);
}
bind_group_dirty_ = false;
}
// =============================================================================
// Draws / passes — slice 2 (per-frame command encoder + surface plumbing)
// =============================================================================
void WebGPUDevice::drawElements(u32 indexCount, GfxDataType indexType, u32 indexByteOffset) {
if (!isDeviceUsable() || !pass_) return;
auto it = buffers_.find(bound_index_buffer_);
if (it == buffers_.end()) return;
flushBindGroup();
wgpuRenderPassEncoderSetIndexBuffer(pass_, it->second.buffer, toWGPUIndexFormat(indexType),
0, it->second.size);
const u32 indexSize = (indexType == GfxDataType::UnsignedShort) ? 2 : 4;
countDraw();
wgpuRenderPassEncoderDrawIndexed(pass_, indexCount, 1, indexByteOffset / indexSize, 0, 0);
}
void WebGPUDevice::drawArrays(u32 firstVertex, u32 vertexCount) {
if (!isDeviceUsable() || !pass_) return;
flushBindGroup();
countDraw();
wgpuRenderPassEncoderDraw(pass_, vertexCount, 1, firstVertex, 0);
}
void WebGPUDevice::drawElementsInstanced(u32 indexCount, GfxDataType indexType, u32 indexByteOffset,
u32 instanceCount) {
if (!isDeviceUsable() || !pass_) return;
auto it = buffers_.find(bound_index_buffer_);
if (it == buffers_.end()) return;
flushBindGroup();
wgpuRenderPassEncoderSetIndexBuffer(pass_, it->second.buffer, toWGPUIndexFormat(indexType),
0, it->second.size);
const u32 indexSize = (indexType == GfxDataType::UnsignedShort) ? 2 : 4;
countDraw();
wgpuRenderPassEncoderDrawIndexed(pass_, indexCount, instanceCount,
indexByteOffset / indexSize, 0, 0);
}
bool WebGPUDevice::backendCreateFramebuffer(u32, const FramebufferDesc& desc) {
const u32 depthStencil = static_cast<u32>(desc.depthStencil);
if (depthStencil != 0 && !textures_.count(depthStencil)) {
ES_LOG_ERROR("WebGPUDevice::createFramebuffer: unknown depth-stencil texture");
return false;
}
return true;
}
void WebGPUDevice::beginRenderPass(const RenderPassDesc& desc) {
if (!isDeviceUsable()) return;
if (!device_) return;
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_gbuffer_ = false;
pass_albedo_ = false;
WGPUTextureView gbufferView = nullptr;
WGPUTextureView gbufferResolveView = nullptr;
WGPUTextureView albedoView = nullptr;
WGPUTextureView albedoResolveView = nullptr;
pass_depth_msaa_ = 0;
pass_depth_resolve_ = 0;
if (desc.target != FramebufferHandle::Default) {
const FramebufferDesc* fb = framebufferDesc(desc.target);
if (!fb) {
ES_LOG_ERROR("WebGPUDevice::beginRenderPass: unknown framebuffer");
return;
}
const u32 color0 = static_cast<u32>(fb->color0);
const u32 depthStencil = static_cast<u32>(fb->depthStencil);
auto texIt = textures_.find(color0);
if (texIt == textures_.end()) {
ES_LOG_ERROR("WebGPUDevice::beginRenderPass: framebuffer color texture missing");
return;
}
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 (fb->color1 != TextureHandle::Invalid) {
auto gIt = textures_.find(static_cast<u32>(fb->color1));
if (gIt != textures_.end()) {
gbufferView = gIt->second.view;
pass_gbuffer_ = true;
if (gIt->second.samples > 1) {
auto gResolve = textures_.find(static_cast<u32>(fb->resolveColor1));
if (gResolve == textures_.end()) {
ES_LOG_ERROR("WebGPUDevice::beginRenderPass: a multisampled surface record with no resolve twin");
return;
}
gbufferResolveView = gResolve->second.view;
}
}
}
if (pass_gbuffer_ && fb->color2 != TextureHandle::Invalid) {
auto aIt = textures_.find(static_cast<u32>(fb->color2));
if (aIt != textures_.end()) {
albedoView = aIt->second.view;
pass_albedo_ = true;
if (aIt->second.samples > 1) {
auto aResolve = textures_.find(static_cast<u32>(fb->resolveColor2));
if (aResolve == textures_.end()) {
ES_LOG_ERROR("WebGPUDevice::beginRenderPass: a multisampled albedo with no resolve twin");
return;
}
albedoResolveView = aResolve->second.view;
}
}
}
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 {
if (!surface_) {
ES_LOG_ERROR("WebGPUDevice::beginRenderPass: no surface configured");
return;
}
// The swapchain texture belongs to the FRAME, not to one pass: WebGPU
// hands it out once and takes it back at present. A frame that opens a
// second pass on it — a post-process blit over the captured scene, a
// second camera — must reuse the one it already holds; re-acquiring
// after releasing it returns an error, and every draw after that is
// dropped, which is a black screen with nothing else wrong.
// A web boot logs one "Destroyed texture used in a submit" from a frame
// that is never ended; the frames are correct and it happens once. See
// docs/REARCH_RENDER.md §9 for what was measured and what it costs.
if (!frame_view_) {
WGPUSurfaceTexture st{};
wgpuSurfaceGetCurrentTexture(surface_, &st);
if (st.status != WGPUSurfaceGetCurrentTextureStatus_SuccessOptimal &&
st.status != WGPUSurfaceGetCurrentTextureStatus_SuccessSuboptimal) {
ES_LOG_ERROR("WebGPUDevice::beginRenderPass: surface texture unavailable ({})",
static_cast<u32>(st.status));
return;
}
frame_texture_ = st.texture;
frame_view_ = wgpuTextureCreateView(frame_texture_, nullptr);
// The texture the surface hands back is the truth about its size: a
// native surface may ignore the configured extent (a window mid-
// rotation still reports the old one), and a depth companion built
// for the size we ASKED for is then the wrong shape, which invalidates
// the pass and takes the whole frame with it.
const u32 texW = wgpuTextureGetWidth(frame_texture_);
const u32 texH = wgpuTextureGetHeight(frame_texture_);
if (texW > 0 && texH > 0) {
surface_width_ = texW;
surface_height_ = texH;
ensureSurfaceDepth(texW, texH);
}
}
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;
}
encoder_ = wgpuDeviceCreateCommandEncoder(device_, nullptr);
// GPU timing. A pass the graph armed is timed under its own name; any other pass that opens inside a timer span
// adds its time to the span, whatever it draws to — the span is the frame's, not the surface pass's.
pass_time_slot_ = takePassTimeSlot();
pass_timed_ = pass_time_slot_ == kNoPassSlot && spanTakesPass();
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);
// Resolved into its single-sample twin by the pass itself; when nothing continues on this target the samples need not be kept.
color.storeOp = (desc.discardMultisampled && resolveView) ? WGPUStoreOp_Discard : WGPUStoreOp_Store;
color.clearValue = toWGPUClearColor(desc);
// The surface record clears to zero — "nothing wrote here" — whatever the background is.
WGPURenderPassColorAttachment colors[3]{};
colors[0] = color;
if (pass_gbuffer_) {
colors[1].view = gbufferView;
colors[1].resolveTarget = gbufferResolveView;
colors[1].depthSlice = WGPU_DEPTH_SLICE_UNDEFINED;
colors[1].loadOp = toWGPULoadOp(desc.clearColor, scoped);
colors[1].storeOp = (desc.discardMultisampled && gbufferResolveView) ? WGPUStoreOp_Discard : WGPUStoreOp_Store;
colors[1].clearValue = {0.0, 0.0, 0.0, 0.0};
}
if (pass_albedo_) {
colors[2].view = albedoView;
colors[2].resolveTarget = albedoResolveView;
colors[2].depthSlice = WGPU_DEPTH_SLICE_UNDEFINED;
colors[2].loadOp = toWGPULoadOp(desc.clearColor, scoped);
colors[2].storeOp = (desc.discardMultisampled && albedoResolveView) ? WGPUStoreOp_Discard : WGPUStoreOp_Store;
colors[2].clearValue = {0.0, 0.0, 0.0, 0.0};
}
WGPURenderPassDescriptor rp{};
rp.colorAttachmentCount = !pass_gbuffer_ ? 1 : pass_albedo_ ? 3 : 2;
rp.colorAttachments = colors;
WGPURenderPassDepthStencilAttachment ds{};
if (dsView) {
ds.view = dsView;
ds.depthLoadOp = toWGPULoadOp(desc.clearDepth, scoped);
// Kept unless the pass said it is only for testing, and unless a multisampled one is resolved by hand after the pass.
ds.depthStoreOp = (desc.discardDepth && pass_depth_msaa_ == 0) ? WGPUStoreOp_Discard : WGPUStoreOp_Store;
ds.depthClearValue = 1.0f; // GL's default clear depth; no RHI override exists
if (hasStencilPlanes(pass_ds_format_)) {
ds.stencilLoadOp = toWGPULoadOp(desc.clearStencil, scoped);
ds.stencilStoreOp = WGPUStoreOp_Store;
ds.stencilClearValue = static_cast<u32>(desc.clearStencilValue);
}
rp.depthStencilAttachment = &ds;
}
WGPUPassTimestampWrites tw{};
if (pass_timed_ || pass_time_slot_ != kNoPassSlot) {
tw.querySet = timestamp_qset_;
tw.beginningOfPassWriteIndex = 0;
tw.endOfPassWriteIndex = 1;
rp.timestampWrites = &tw; // outlives the call below (same scope)
}
pass_ = wgpuCommandEncoderBeginRenderPass(encoder_, &rp);
bind_group_dirty_ = true;
stencil_ref_ = 0; // a fresh pass encoder resets its stencil reference
// Region-scoped clear = load + scissored clear-triangle, per the RHI
// contract — for every attachment the desc asks to clear.
if (scoped && (desc.clearColor || desc.clearDepth || desc.clearStencil)) {
drawInternalClear(desc.clearColor, desc.clearDepth && dsView,
desc.clearStencil && hasStencilPlanes(pass_ds_format_),
desc.clearColorValue, desc.clearStencilValue, &desc);
}
}
void WebGPUDevice::endRenderPass() {
if (!pass_) return;
wgpuRenderPassEncoderEnd(pass_);
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 u32 passSlot = encoder_ ? pass_time_slot_ : kNoPassSlot;
pass_time_slot_ = kNoPassSlot;
if (passSlot != kNoPassSlot) resolvePassTime(encoder_, passSlot);
if (pass_timed_ && encoder_) resolveSpanPass(encoder_);
pass_timed_ = false;
// A booked capture rides the pass's OWN encoder: the browser presents the
// swapchain image with this submit, so a copy encoded afterwards copies a
// destroyed texture. Several surface passes overwrite; the last one wins.
if (capture_id_ && pass_is_surface_ && frame_texture_ && encoder_) {
encodeReadbackCopy(encoder_, capture_id_, frame_texture_);
capture_copied_ = true;
}
pass_is_surface_ = false;
WGPUCommandBuffer commands = wgpuCommandEncoderFinish(encoder_, nullptr);
wgpuCommandEncoderRelease(encoder_);
encoder_ = nullptr;
wgpuQueueSubmit(queue_, 1, &commands);
wgpuCommandBufferRelease(commands);
if (passSlot != kNoPassSlot) mapPassTime(passSlot);
// The span was closed while this pass was still open: it was the last one in it.
if (span_closing_) {
span_closing_ = false;
finishSpan();
}
}
/** Give the swapchain texture back: the frame is over (see GfxDevice::endFrame).
* A frame may have opened several passes on it, so no single pass may do this. */
void WebGPUDevice::endFrame() {
++bind_group_frame_;
// A capture is served HERE and nowhere else: this is the last instant at which
// the frame is both finished and still ours. Asking from outside cannot work —
// whoever could ask runs after the renderer has already given the image back.
if (capture_id_) {
const u32 id = capture_id_;
capture_id_ = 0;
if (capture_copied_) {
capture_copied_ = false;
mapReadback(id);
} else if (frame_texture_) {
submitReadbackCopy(id, frame_texture_);
} else {
// Nothing drew, so there is no image to copy. Leaving the record
// Pending would hang whoever is polling it.
auto it = readbacks_.find(id);
if (it != readbacks_.end()) it->second.status = GfxReadbackStatus::Failed;
}
}
if (frame_view_) { wgpuTextureViewRelease(frame_view_); frame_view_ = nullptr; }
if (frame_texture_) { wgpuTextureRelease(frame_texture_); frame_texture_ = nullptr; }
}
ReadbackHandle WebGPUDevice::captureNextFrame(u32 w, u32 h) {
if (!isDeviceUsable() || !device_ || w == 0 || h == 0) return ReadbackHandle::Invalid;
if (!surface_readback_) {
ES_LOG_ERROR("WebGPUDevice::captureNextFrame: the surface was configured without CopySrc "
"(setSurfaceReadback must be on before configureSurface)");
return ReadbackHandle::Invalid;
}
if (capture_id_) return ReadbackHandle::Invalid; // one in flight is enough
capture_id_ = allocReadback(w, h);
return static_cast<ReadbackHandle>(capture_id_);
}
// =============================================================================
// Readback (async seam: texture → staging copy, resolved when the map lands)
// =============================================================================
void WebGPUDevice::onReadbackMapped(WGPUMapAsyncStatus status, WGPUStringView /*message*/,
void* userdata1, void* userdata2) {
auto* self = static_cast<WebGPUDevice*>(userdata1);
const u32 id = static_cast<u32>(reinterpret_cast<uintptr_t>(userdata2));
auto it = self->readbacks_.find(id);
if (it == self->readbacks_.end()) return; // taken or discarded while in flight
it->second.status = (status == WGPUMapAsyncStatus_Success) ? GfxReadbackStatus::Ready
: GfxReadbackStatus::Failed;
}
void WebGPUDevice::releaseReadback(u32 id) {
auto it = readbacks_.find(id);
if (it == readbacks_.end()) return;
WGPUBuffer buffer = it->second.buffer;
// Erase first: releasing a buffer with a pending map fires the callback with
// an abort status, which must miss the lookup.
readbacks_.erase(it);
if (buffer) wgpuBufferRelease(buffer);
}
ReadbackHandle WebGPUDevice::requestReadback(FramebufferHandle target, u32 w, u32 h) {
if (!isDeviceUsable()) return ReadbackHandle::Invalid;
if (!device_ || w == 0 || h == 0) return ReadbackHandle::Invalid;
if (inPass()) {
ES_LOG_ERROR("WebGPUDevice::requestReadback: must be called outside a render pass");
return ReadbackHandle::Invalid;
}
if (target == FramebufferHandle::Default) {
// Not addressable from out here: the renderer gives the swapchain image
// back at the end of its own frame, so any caller is already too late.
// captureNextFrame reads the presented frame instead.
stubOnce("requestReadback(default framebuffer) — use captureNextFrame");
return ReadbackHandle::Invalid;
}
const FramebufferDesc* fb = framebufferDesc(target);
if (!fb) return ReadbackHandle::Invalid;
auto tit = textures_.find(static_cast<u32>(fb->color0));
if (tit == textures_.end() || !tit->second.texture) return ReadbackHandle::Invalid;
const u32 id = allocReadback(w, h);
if (!id) return ReadbackHandle::Invalid;
submitReadbackCopy(id, tit->second.texture);
return static_cast<ReadbackHandle>(id);
}
/** The staging buffer and its record, with no copy yet. Split from the copy so a
* capture can be handed a handle to poll NOW and filled in later, at the only
* moment the swapchain image exists (see captureNextFrame). */
u32 WebGPUDevice::allocReadback(u32 w, u32 h) {
// copyTextureToBuffer requires a 256-byte row alignment; rows are compacted
// (and flipped to the bottom-up contract) in takeReadback.
const u32 padded = (w * 4u + 255u) & ~255u;
WGPUBufferDescriptor bd{};
bd.usage = WGPUBufferUsage_CopyDst | WGPUBufferUsage_MapRead;
bd.size = static_cast<u64>(padded) * h;
WGPUBuffer buffer = wgpuDeviceCreateBuffer(device_, &bd);
if (!buffer) return 0;
const u32 id = next_readback_id_++;
readbacks_[id] = ReadbackRec{buffer, w, h, padded, GfxReadbackStatus::Pending};
return id;
}
void WebGPUDevice::encodeReadbackCopy(WGPUCommandEncoder encoder, u32 id, WGPUTexture source) {
auto it = readbacks_.find(id);
if (it == readbacks_.end() || !source || !encoder) return;
ReadbackRec& rec = it->second;
WGPUTexelCopyTextureInfo src = WGPU_TEXEL_COPY_TEXTURE_INFO_INIT;
src.texture = source;
WGPUTexelCopyBufferInfo dst = WGPU_TEXEL_COPY_BUFFER_INFO_INIT;
dst.buffer = rec.buffer;
dst.layout.offset = 0;
dst.layout.bytesPerRow = rec.paddedBytesPerRow;
dst.layout.rowsPerImage = rec.height;
WGPUExtent3D size{rec.width, rec.height, 1};
wgpuCommandEncoderCopyTextureToBuffer(encoder, &src, &dst, &size);
}
void WebGPUDevice::mapReadback(u32 id) {
auto it = readbacks_.find(id);
if (it == readbacks_.end()) return;
ReadbackRec& rec = it->second;
WGPUBufferMapCallbackInfo cb = WGPU_BUFFER_MAP_CALLBACK_INFO_INIT;
cb.mode = WGPUCallbackMode_AllowSpontaneous;
cb.callback = &WebGPUDevice::onReadbackMapped;
cb.userdata1 = this;
cb.userdata2 = reinterpret_cast<void*>(static_cast<uintptr_t>(id));
wgpuBufferMapAsync(rec.buffer, WGPUMapMode_Read, 0,
static_cast<u64>(rec.paddedBytesPerRow) * rec.height, cb);
}
void WebGPUDevice::submitReadbackCopy(u32 id, WGPUTexture source) {
if (readbacks_.find(id) == readbacks_.end() || !source) return;
WGPUCommandEncoder encoder = wgpuDeviceCreateCommandEncoder(device_, nullptr);
encodeReadbackCopy(encoder, id, source);
WGPUCommandBuffer commands = wgpuCommandEncoderFinish(encoder, nullptr);
wgpuCommandEncoderRelease(encoder);
wgpuQueueSubmit(queue_, 1, &commands);
wgpuCommandBufferRelease(commands);
mapReadback(id);
}
GfxReadbackStatus WebGPUDevice::pollReadback(ReadbackHandle handle) {
// AllowSpontaneous callbacks fire from the browser's event loop on their own;
// the pump is defensive (and required if the callback mode ever tightens).
if (instance_) wgpuInstanceProcessEvents(instance_);
auto it = readbacks_.find(static_cast<u32>(handle));
if (it == readbacks_.end()) return GfxReadbackStatus::Failed;
if (it->second.status == GfxReadbackStatus::Failed) {
releaseReadback(static_cast<u32>(handle));
return GfxReadbackStatus::Failed;
}
return it->second.status;
}
bool WebGPUDevice::takeReadback(ReadbackHandle handle, void* dest, usize destSize) {
auto it = readbacks_.find(static_cast<u32>(handle));
if (it == readbacks_.end() || it->second.status != GfxReadbackStatus::Ready) return false;
ReadbackRec& rec = it->second;
if (rec.raw) {
// A compute readback: the source's own bytes, rows top-down with the padding taken out.
if (destSize < rec.tightBytes) return false;
const auto* mapped = static_cast<const u8*>(
wgpuBufferGetConstMappedRange(rec.buffer, 0, static_cast<u64>(rec.paddedBytesPerRow) * rec.height));
if (!mapped) {
releaseReadback(static_cast<u32>(handle));
return false;
}
auto* out = static_cast<u8*>(dest);
const u32 rowBytes = rec.width * rec.bytesPerTexel;
for (u32 row = 0; row < rec.height; ++row) {
std::memcpy(out + static_cast<usize>(row) * rowBytes, mapped + static_cast<usize>(row) * rec.paddedBytesPerRow, rowBytes);
}
wgpuBufferUnmap(rec.buffer);
releaseReadback(static_cast<u32>(handle));
return true;
}
const usize tight = static_cast<usize>(rec.width) * rec.height * 4;
if (destSize < tight) return false;
const auto* mapped = static_cast<const u8*>(
wgpuBufferGetConstMappedRange(rec.buffer, 0, static_cast<u64>(rec.paddedBytesPerRow) * rec.height));
if (!mapped) {
releaseReadback(static_cast<u32>(handle));
return false;
}
// The copy lands top-down; the contract (GL readPixels) is bottom-up rows.
auto* out = static_cast<u8*>(dest);
const u32 rowBytes = rec.width * 4u;
for (u32 row = 0; row < rec.height; ++row) {
std::memcpy(out + static_cast<usize>(rec.height - 1 - row) * rowBytes,
mapped + static_cast<usize>(row) * rec.paddedBytesPerRow, rowBytes);
}
wgpuBufferUnmap(rec.buffer);
releaseReadback(static_cast<u32>(handle));
return true;
}
void WebGPUDevice::discardReadback(ReadbackHandle handle) {
releaseReadback(static_cast<u32>(handle));
}
// =============================================================================
// Timing / queries / debug
// =============================================================================
void WebGPUDevice::ensureTimestamps() {
if (timestamp_init_done_) return;
timestamp_init_done_ = true;
if (!device_ || !wgpuDeviceHasFeature(device_, WGPUFeatureName_TimestampQuery)) return;
WGPUQuerySetDescriptor qd{};
qd.type = WGPUQueryType_Timestamp;
qd.count = 2; // begin + end of the pass being timed; resolved out before the next pass reuses them
timestamp_qset_ = wgpuDeviceCreateQuerySet(device_, &qd);
if (!timestamp_qset_) return;
WGPUBufferDescriptor rd{};
rd.usage = WGPUBufferUsage_QueryResolve | WGPUBufferUsage_CopySrc;
rd.size = 16; // 2 × u64 nanosecond timestamps
timestamp_resolve_ = wgpuDeviceCreateBuffer(device_, &rd);
for (u32 i = 0; i < kGpuTimeRing; ++i) {
WGPUBufferDescriptor bd{};
bd.usage = WGPUBufferUsage_MapRead | WGPUBufferUsage_CopyDst;
bd.size = 16 * kSpanPasses;
gpu_time_ring_[i].buf = wgpuDeviceCreateBuffer(device_, &bd);
}
timestamp_supported_ = timestamp_resolve_ && gpu_time_ring_[0].buf;
}
// One query set serves every timer: timing rides the passes, so a query id
// only has to exist for the engine's GpuTimer to turn on.
bool WebGPUDevice::backendCreateTimerQuery(u32) {
ensureTimestamps();
return timestamp_supported_;
}
// A span is what GL's GL_TIME_ELAPSED gives between the same two calls: the GPU's time for everything issued inside
// it. WebGPU can only stamp a pass, so every pass that opens inside the span is stamped and the span is their sum.
void WebGPUDevice::beginTimerQuery(u32) {
if (!timestamp_supported_) return;
span_closing_ = false;
span_slot_ = kGpuTimeRing;
span_passes_ = 0;
for (u32 i = 0; i < kGpuTimeRing; ++i) {
const u32 s = (gpu_time_next_ + i) % kGpuTimeRing;
if (!gpu_time_ring_[s].pending) {
span_slot_ = s;
gpu_time_next_ = (s + 1) % kGpuTimeRing;
break;
}
}
// With every readback still in flight the span goes untimed, and says so with a zero rather than no answer:
// the caller keeps one query in flight per span and would otherwise wait on this one for good.
span_open_ = true;
}
void WebGPUDevice::endTimerQuery() {
if (!span_open_) return;
span_open_ = false;
// A pass still open belongs to the span and has not been stamped yet; its end finishes the span.
if (pass_) span_closing_ = true;
else finishSpan();
}
bool WebGPUDevice::spanTakesPass() const {
return timestamp_supported_ && span_open_ && span_slot_ < kGpuTimeRing && span_passes_ < kSpanPasses;
}
void WebGPUDevice::resolveSpanPass(WGPUCommandEncoder encoder) {
wgpuCommandEncoderResolveQuerySet(encoder, timestamp_qset_, 0, 2, timestamp_resolve_, 0);
wgpuCommandEncoderCopyBufferToBuffer(encoder, timestamp_resolve_, 0,
gpu_time_ring_[span_slot_].buf, 16ull * span_passes_, 16);
++span_passes_;
}
void WebGPUDevice::finishSpan() {
const u32 slot = span_slot_;
const u32 passes = span_passes_;
span_slot_ = kGpuTimeRing;
span_passes_ = 0;
if (!timestamp_supported_) return;
if (slot >= kGpuTimeRing || passes == 0) {
if (gpu_time_results_.size() < 16) gpu_time_results_.push_back(0);
return;
}
// Map async — drained by getTimerQueryNs a few frames later (the GpuTimer ring tolerates the latency).
gpu_time_ring_[slot].pending = true;
gpu_time_ring_[slot].passes = passes;
WGPUBufferMapCallbackInfo cb = WGPU_BUFFER_MAP_CALLBACK_INFO_INIT;
cb.mode = WGPUCallbackMode_AllowSpontaneous;
cb.callback = &WebGPUDevice::onGpuTimeMapped;
cb.userdata1 = this;
cb.userdata2 = reinterpret_cast<void*>(static_cast<uintptr_t>(slot));
wgpuBufferMapAsync(gpu_time_ring_[slot].buf, WGPUMapMode_Read, 0, 16ull * passes, cb);
}
bool WebGPUDevice::timerDisjoint() { return false; }
bool WebGPUDevice::getTimerQueryNs(u32 query, u64* outNs) {
if (pass_time_tags_.count(query)) {
const auto it = pass_time_results_.find(query);
if (it == pass_time_results_.end()) return false;
if (outNs) *outNs = it->second;
pass_time_results_.erase(it);
return true;
}
if (gpu_time_results_.empty()) return false;
if (outNs) *outNs = gpu_time_results_.front();
gpu_time_results_.erase(gpu_time_results_.begin());
return true;
}
void WebGPUDevice::armPassTimer(u32 query) {
armed_pass_tag_ = timestamp_supported_ ? query : 0;
if (armed_pass_tag_) pass_time_tags_.insert(armed_pass_tag_);
}
u32 WebGPUDevice::takePassTimeSlot() {
const u32 tag = armed_pass_tag_;
armed_pass_tag_ = 0;
if (!tag || !timestamp_supported_) return kNoPassSlot;
u32 slot = kNoPassSlot;
for (u32 i = 0; i < pass_time_pool_.size(); ++i) {
if (!pass_time_pool_[i].pending) { slot = i; break; }
}
if (slot == kNoPassSlot) {
if (pass_time_pool_.size() >= kPassTimePool) return kNoPassSlot; // readbacks are not coming back: skip, don't grow
WGPUBufferDescriptor bd{};
bd.usage = WGPUBufferUsage_MapRead | WGPUBufferUsage_CopyDst;
bd.size = 16;
PassTimeSlot fresh;
fresh.buf = wgpuDeviceCreateBuffer(device_, &bd);
if (!fresh.buf) return kNoPassSlot;
pass_time_pool_.push_back(fresh);
slot = static_cast<u32>(pass_time_pool_.size() - 1);
}
pass_time_pool_[slot].tag = tag;
return slot;
}
void WebGPUDevice::resolvePassTime(WGPUCommandEncoder encoder, u32 slot) {
wgpuCommandEncoderResolveQuerySet(encoder, timestamp_qset_, 0, 2, timestamp_resolve_, 0);
wgpuCommandEncoderCopyBufferToBuffer(encoder, timestamp_resolve_, 0, pass_time_pool_[slot].buf, 0, 16);
}
void WebGPUDevice::mapPassTime(u32 slot) {
pass_time_pool_[slot].pending = true;
WGPUBufferMapCallbackInfo cb = WGPU_BUFFER_MAP_CALLBACK_INFO_INIT;
cb.mode = WGPUCallbackMode_AllowSpontaneous;
cb.callback = &WebGPUDevice::onPassTimeMapped;
cb.userdata1 = this;
cb.userdata2 = reinterpret_cast<void*>(static_cast<uintptr_t>(slot));
wgpuBufferMapAsync(pass_time_pool_[slot].buf, WGPUMapMode_Read, 0, 16, cb);
}
void WebGPUDevice::onPassTimeMapped(WGPUMapAsyncStatus status, WGPUStringView /*message*/,
void* userdata1, void* userdata2) {
auto* self = static_cast<WebGPUDevice*>(userdata1);
const u32 slot = static_cast<u32>(reinterpret_cast<uintptr_t>(userdata2));
if (!self || slot >= self->pass_time_pool_.size()) return;
PassTimeSlot& ps = self->pass_time_pool_[slot];
if (status == WGPUMapAsyncStatus_Success && ps.buf) {
const auto* ts = static_cast<const u64*>(wgpuBufferGetConstMappedRange(ps.buf, 0, 16));
if (ts && ts[1] >= ts[0]) self->pass_time_results_[ps.tag] = ts[1] - ts[0];
wgpuBufferUnmap(ps.buf);
}
ps.pending = false;
}
void WebGPUDevice::onGpuTimeMapped(WGPUMapAsyncStatus status, WGPUStringView /*message*/,
void* userdata1, void* userdata2) {
auto* self = static_cast<WebGPUDevice*>(userdata1);
const u32 slot = static_cast<u32>(reinterpret_cast<uintptr_t>(userdata2));
if (!self || slot >= kGpuTimeRing) return;
WGPUBuffer buf = self->gpu_time_ring_[slot].buf;
const u32 passes = self->gpu_time_ring_[slot].passes;
if (status == WGPUMapAsyncStatus_Success && buf) {
const auto* ts = static_cast<const u64*>(wgpuBufferGetConstMappedRange(buf, 0, 16ull * passes));
// The span is the sum of its passes; a pair that ran backwards (a timestamp reset) counts for nothing.
u64 total = 0;
for (u32 i = 0; ts && i < passes; ++i) {
if (ts[2 * i + 1] >= ts[2 * i]) total += ts[2 * i + 1] - ts[2 * i];
}
// Cap the FIFO so a stalled consumer can't grow it without bound.
if (ts && self->gpu_time_results_.size() < 16) self->gpu_time_results_.push_back(total);
wgpuBufferUnmap(buf);
}
self->gpu_time_ring_[slot].pending = false;
}
void WebGPUDevice::setWireframe(bool) {}
u32 WebGPUDevice::getError() { return 0; }
std::string WebGPUDevice::getString(GfxStringName name) {
switch (name) {
case GfxStringName::Renderer: return "WebGPU (Dawn/emdawnwebgpu)";
case GfxStringName::Vendor: return "WebGPU";
case GfxStringName::Version: return "WebGPU 1.0";
case GfxStringName::ShadingLanguageVersion: return "WGSL";
default: return {};
}
}
i32 WebGPUDevice::getInt(GfxIntParam param) {
switch (param) {
case GfxIntParam::MaxTextureSize: return 8192;
case GfxIntParam::MaxTextureImageUnits: return 16;
case GfxIntParam::MaxVertexAttribs: return 16;
default: return 0;
}
}
// =============================================================================
// Compute
// =============================================================================
namespace {
/// Bytes a texel takes in the formats a compute shader can write, 0 for the rest.
u32 storageTexelBytes(WGPUTextureFormat format) {
switch (format) {
case WGPUTextureFormat_RGBA8Unorm:
case WGPUTextureFormat_BGRA8Unorm:
case WGPUTextureFormat_RGBA8UnormSrgb: return 4;
case WGPUTextureFormat_RGBA16Float: return 8;
case WGPUTextureFormat_RGBA32Float: return 16;
default: return 0;
}
}
constexpr u32 kMaxComputeBindings = 16;
constexpr u32 kMaxWorkgroupsPerDimension = 65535;
} // namespace
bool WebGPUDevice::backendCreateCompute(u32 id, const GfxComputeSource& source, std::string* outLog) {
if (source.language != GfxShaderLanguage::WGSL || !source.source) {
if (outLog) *outLog = "WebGPUDevice compiles WGSL only";
return false;
}
if (!device_) {
if (outLog) *outLog = "no WGPUDevice";
return false;
}
WGPUShaderSourceWGSL wgsl{};
wgsl.chain.sType = WGPUSType_ShaderSourceWGSL;
wgsl.code = sv(source.source);
WGPUShaderModuleDescriptor md{};
md.nextInChain = &wgsl.chain;
WGPUShaderModule module = wgpuDeviceCreateShaderModule(device_, &md);
if (!module) {
if (outLog) *outLog = "shader module creation failed";
return false;
}
ComputeRec rec;
rec.module = module;
rec.entry = source.entry && *source.entry ? source.entry : "main";
computes_[id] = std::move(rec);
return true;
}
void WebGPUDevice::backendDeleteCompute(u32 id) {
auto it = computes_.find(id);
if (it == computes_.end()) return;
for (auto& [key, pipeline] : it->second.pipelines) {
if (pipeline) wgpuComputePipelineRelease(pipeline);
}
if (it->second.module) wgpuShaderModuleRelease(it->second.module);
computes_.erase(it);
}
bool WebGPUDevice::backendDispatchCompute(u32 id, const GfxComputeBinding* bindings, u32 bindingCount,
u32 groupsX, u32 groupsY, u32 groupsZ) {
if (inPass()) {
ES_LOG_ERROR("WebGPUDevice::dispatchCompute: must be called outside a render pass");
return false;
}
auto program = computes_.find(id);
if (program == computes_.end() || !program->second.module) return false;
if (groupsX > kMaxWorkgroupsPerDimension || groupsY > kMaxWorkgroupsPerDimension ||
groupsZ > kMaxWorkgroupsPerDimension || bindingCount > kMaxComputeBindings) {
ES_LOG_ERROR("WebGPUDevice::dispatchCompute: {}x{}x{} groups with {} bindings is over the limit",
groupsX, groupsY, groupsZ, bindingCount);
return false;
}
WGPUBindGroupLayoutEntry layoutEntries[kMaxComputeBindings] = {};
WGPUBindGroupEntry groupEntries[kMaxComputeBindings] = {};
std::string key;
for (u32 i = 0; i < bindingCount; ++i) {
const GfxComputeBinding& b = bindings[i];
WGPUBindGroupLayoutEntry& le = layoutEntries[i];
WGPUBindGroupEntry& ge = groupEntries[i];
le.binding = ge.binding = b.binding;
le.visibility = WGPUShaderStage_Compute;
key += std::to_string(b.binding) + "." + std::to_string(static_cast<u32>(b.kind));
switch (b.kind) {
case GfxComputeBinding::Kind::Uniform:
case GfxComputeBinding::Kind::StorageRead:
case GfxComputeBinding::Kind::Storage: {
auto it = buffers_.find(static_cast<u32>(b.buffer));
if (it == buffers_.end() || !it->second.buffer) {
ES_LOG_ERROR("WebGPUDevice::dispatchCompute: binding {} names a buffer that is gone", b.binding);
return false;
}
const bool uniform = b.kind == GfxComputeBinding::Kind::Uniform;
if ((uniform && it->second.usage != GfxBufferUsage::Uniform) ||
(!uniform && it->second.usage != GfxBufferUsage::Storage)) {
ES_LOG_ERROR("WebGPUDevice::dispatchCompute: binding {} is bound as {} but the buffer was not made for it",
b.binding, uniform ? "a uniform" : "storage");
return false;
}
le.buffer.type = uniform ? WGPUBufferBindingType_Uniform
: b.kind == GfxComputeBinding::Kind::StorageRead ? WGPUBufferBindingType_ReadOnlyStorage
: WGPUBufferBindingType_Storage;
ge.buffer = it->second.buffer;
ge.offset = b.offset;
const u32 whole = webgpu::alignedWriteSize(it->second.size);
ge.size = b.size ? b.size : (whole > b.offset ? whole - b.offset : 0);
break;
}
case GfxComputeBinding::Kind::Texture: {
auto it = textures_.find(static_cast<u32>(b.texture));
if (it == textures_.end() || !it->second.texture) {
ES_LOG_ERROR("WebGPUDevice::dispatchCompute: binding {} names a texture that is gone", b.binding);
return false;
}
const WGPUTextureFormat f = it->second.format;
le.texture.sampleType = isDepthFormat(f) ? WGPUTextureSampleType_Depth
: f == WGPUTextureFormat_RGBA32Float ? WGPUTextureSampleType_UnfilterableFloat
: WGPUTextureSampleType_Float;
le.texture.viewDimension = WGPUTextureViewDimension_2D;
ge.textureView = it->second.sampleView;
key += "." + std::to_string(static_cast<u32>(le.texture.sampleType));
break;
}
case GfxComputeBinding::Kind::DepthTexture: {
auto it = textures_.find(static_cast<u32>(b.texture));
const TextureRec* rec = (it != textures_.end() && it->second.texture && isDepthFormat(it->second.format)) ? &it->second : nullptr;
if (!rec) {
ensureDummies();
rec = &dummy_depth_texture_;
}
le.texture.sampleType = WGPUTextureSampleType_Depth;
le.texture.viewDimension = WGPUTextureViewDimension_2D;
ge.textureView = rec->sampleView;
break;
}
case GfxComputeBinding::Kind::StorageTexture: {
auto it = textures_.find(static_cast<u32>(b.texture));
if (it == textures_.end() || !it->second.texture) {
ES_LOG_ERROR("WebGPUDevice::dispatchCompute: binding {} names a texture that is gone", b.binding);
return false;
}
if (!it->second.storage) {
ES_LOG_ERROR("WebGPUDevice::dispatchCompute: binding {} is a storage texture but the texture was not made with storage", b.binding);
return false;
}
le.storageTexture.access = WGPUStorageTextureAccess_WriteOnly;
le.storageTexture.format = it->second.format;
le.storageTexture.viewDimension = WGPUTextureViewDimension_2D;
ge.textureView = it->second.view;
key += "." + std::to_string(static_cast<u32>(it->second.format));
break;
}
case GfxComputeBinding::Kind::Sampler:
le.sampler.type = WGPUSamplerBindingType_Filtering;
ge.sampler = samplerFor(packSamplerKey(b.filter, b.filter, TextureWrap::ClampToEdge, TextureWrap::ClampToEdge));
break;
}
key += "/";
}
WGPUBindGroupLayout layout = nullptr;
auto cachedLayout = compute_layouts_.find(key);
if (cachedLayout != compute_layouts_.end()) {
layout = cachedLayout->second;
} else {
WGPUBindGroupLayoutDescriptor bld{};
bld.entryCount = bindingCount;
bld.entries = layoutEntries;
layout = wgpuDeviceCreateBindGroupLayout(device_, &bld);
compute_layouts_[key] = layout;
}
if (!layout) return false;
WGPUPipelineLayout pipelineLayout = nullptr;
auto cachedPipelineLayout = compute_pipeline_layouts_.find(key);
if (cachedPipelineLayout != compute_pipeline_layouts_.end()) {
pipelineLayout = cachedPipelineLayout->second;
} else {
WGPUPipelineLayoutDescriptor pld{};
pld.bindGroupLayoutCount = 1;
pld.bindGroupLayouts = &layout;
pipelineLayout = wgpuDeviceCreatePipelineLayout(device_, &pld);
compute_pipeline_layouts_[key] = pipelineLayout;
}
if (!pipelineLayout) return false;
WGPUComputePipeline pipeline = nullptr;
auto cachedPipeline = program->second.pipelines.find(key);
if (cachedPipeline != program->second.pipelines.end()) {
pipeline = cachedPipeline->second;
} else {
WGPUComputePipelineDescriptor cpd = WGPU_COMPUTE_PIPELINE_DESCRIPTOR_INIT;
cpd.layout = pipelineLayout;
cpd.compute.module = program->second.module;
cpd.compute.entryPoint = sv(program->second.entry.c_str());
pipeline = wgpuDeviceCreateComputePipeline(device_, &cpd);
program->second.pipelines[key] = pipeline;
}
if (!pipeline) return false;
WGPUBindGroupDescriptor bgd{};
bgd.layout = layout;
bgd.entryCount = bindingCount;
bgd.entries = groupEntries;
WGPUBindGroup group = wgpuDeviceCreateBindGroup(device_, &bgd);
if (!group) return false;
WGPUCommandEncoder encoder = wgpuDeviceCreateCommandEncoder(device_, nullptr);
WGPUComputePassDescriptor pd = WGPU_COMPUTE_PASS_DESCRIPTOR_INIT;
const u32 passSlot = takePassTimeSlot();
// A kernel is the frame's GPU time as much as a draw is. No render pass is open here to carry a span past its
// end, so this one is resolved and counted before the call returns.
const bool inSpan = passSlot == kNoPassSlot && spanTakesPass();
WGPUPassTimestampWrites tw{};
if (passSlot != kNoPassSlot || inSpan) {
tw.querySet = timestamp_qset_;
tw.beginningOfPassWriteIndex = 0;
tw.endOfPassWriteIndex = 1;
pd.timestampWrites = &tw;
}
WGPUComputePassEncoder pass = wgpuCommandEncoderBeginComputePass(encoder, &pd);
wgpuComputePassEncoderSetPipeline(pass, pipeline);
wgpuComputePassEncoderSetBindGroup(pass, 0, group, 0, nullptr);
wgpuComputePassEncoderDispatchWorkgroups(pass, groupsX, groupsY, groupsZ);
wgpuComputePassEncoderEnd(pass);
wgpuComputePassEncoderRelease(pass);
if (passSlot != kNoPassSlot) resolvePassTime(encoder, passSlot);
if (inSpan) resolveSpanPass(encoder);
WGPUCommandBuffer commands = wgpuCommandEncoderFinish(encoder, nullptr);
wgpuCommandEncoderRelease(encoder);
wgpuQueueSubmit(queue_, 1, &commands);
wgpuCommandBufferRelease(commands);
if (passSlot != kNoPassSlot) mapPassTime(passSlot);
wgpuBindGroupRelease(group);
return true;
}
u32 WebGPUDevice::allocRawReadback(u32 w, u32 h, u32 bytesPerTexel, u32 tightBytes) {
// A texture copy wants 256-byte rows; a buffer copy is one row of any multiple of four.
const u32 padded = (h > 1 || bytesPerTexel != 1) ? ((w * bytesPerTexel + 255u) & ~255u) : tightBytes;
WGPUBufferDescriptor bd{};
bd.usage = WGPUBufferUsage_CopyDst | WGPUBufferUsage_MapRead;
bd.size = static_cast<u64>(padded) * h;
WGPUBuffer buffer = wgpuDeviceCreateBuffer(device_, &bd);
if (!buffer) return 0;
const u32 id = next_readback_id_++;
ReadbackRec rec{buffer, w, h, padded, GfxReadbackStatus::Pending};
rec.raw = true;
rec.bytesPerTexel = bytesPerTexel;
rec.tightBytes = tightBytes;
readbacks_[id] = rec;
return id;
}
ReadbackHandle WebGPUDevice::requestBufferReadback(BufferHandle buffer, u32 offsetBytes, u32 sizeBytes) {
if (!isDeviceUsable() || !device_ || sizeBytes == 0 || (offsetBytes & 3u) || (sizeBytes & 3u)) {
return ReadbackHandle::Invalid;
}
if (inPass()) {
ES_LOG_ERROR("WebGPUDevice::requestBufferReadback: must be called outside a render pass");
return ReadbackHandle::Invalid;
}
auto it = buffers_.find(static_cast<u32>(buffer));
if (it == buffers_.end() || !it->second.buffer || it->second.usage != GfxBufferUsage::Storage ||
static_cast<u64>(offsetBytes) + sizeBytes > webgpu::alignedWriteSize(it->second.size)) {
return ReadbackHandle::Invalid;
}
// One row of sizeBytes bytes: width counts bytes, a texel is one.
const u32 id = allocRawReadback(sizeBytes, 1, 1, sizeBytes);
if (!id) return ReadbackHandle::Invalid;
WGPUCommandEncoder encoder = wgpuDeviceCreateCommandEncoder(device_, nullptr);
wgpuCommandEncoderCopyBufferToBuffer(encoder, it->second.buffer, offsetBytes, readbacks_[id].buffer, 0, sizeBytes);
WGPUCommandBuffer commands = wgpuCommandEncoderFinish(encoder, nullptr);
wgpuCommandEncoderRelease(encoder);
wgpuQueueSubmit(queue_, 1, &commands);
wgpuCommandBufferRelease(commands);
mapReadback(id);
return static_cast<ReadbackHandle>(id);
}
ReadbackHandle WebGPUDevice::requestTextureReadback(TextureHandle texture) {
if (!isDeviceUsable() || !device_) return ReadbackHandle::Invalid;
if (inPass()) {
ES_LOG_ERROR("WebGPUDevice::requestTextureReadback: must be called outside a render pass");
return ReadbackHandle::Invalid;
}
auto it = textures_.find(static_cast<u32>(texture));
if (it == textures_.end() || !it->second.texture || it->second.samples > 1) return ReadbackHandle::Invalid;
const u32 bpt = storageTexelBytes(it->second.format);
if (bpt == 0) return ReadbackHandle::Invalid;
const u32 w = it->second.width, h = it->second.height;
const u32 id = allocRawReadback(w, h, bpt, w * h * bpt);
if (!id) return ReadbackHandle::Invalid;
submitReadbackCopy(id, it->second.texture);
return static_cast<ReadbackHandle>(id);
}
} // namespace esengine