Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

40.4 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    WebGPUDevice.hpp
 * @brief   WebGPU (Dawn / emdawnwebgpu) backend for GfxDevice (REARCH_WGSL Phase 2).
 * @details The live render path: a canvas surface (configureSurface) with a
 *          companion depth-stencil texture, per-pass command encoding
 *          (beginRenderPass applies the RenderPassDesc load-ops on color AND
 *          depth-stencil; endRenderPass submits), lazy WGPURenderPipeline builds
 *          from the retained PipelineDesc + layout + shader modules — one variant
 *          per pass depth-stencil shape, since WebGPU validates that coupling —
 *          EXPLICIT bind-group layouts built from each program's binding masks
 *          (group 0 = UBO slots, group 1 = texture/sampler pairs per the
 *          WebGPUMappings unit→binding convention, with dummy backfill for
 *          declared-but-unbound bindings — GL's tolerance for unused
 *          declarations, which the dual-language emitter's uniform injection
 *          relies on), indexed/instanced draw recording, and an internal
 *          clear-triangle family that emulates region-scoped clears and
 *          mid-pass stencil resets (the two clears WebGPU load-ops cannot spell).
 *          The class stays null-device safe: constructed without a WGPUDevice it
 *          degrades every entry point to a logged no-op, so handle bookkeeping
 *          and the language gate are testable without an adapter.
 *
 *          Compiled only under ES_ENABLE_WEBGPU; never part of the GL build.
 *
 * @author  ESEngine Team
 * @date    2026
 *
 * @copyright Copyright (c) 2026 ESEngine Team
 *            Licensed under the Apache License, Version 2.0.
 */
#pragma once

#include "../rhi/GfxDevice.hpp"

#include <webgpu/webgpu.h>

#include <array>
#include <map>
#include <string>
#include <unordered_map>
#include <unordered_set>
#include <vector>

namespace esengine {

class WebGPUDevice final : public GfxDevice {
public:
    u64 estimatedGpuBytes() const override;
    /** @brief Depth-stencil attachment shape of a pass — one WGPURenderPipeline
     *         per shape, since WebGPU validates a pipeline's depthStencil state
     *         against the pass it draws into (GL has no such coupling). */
    enum DsVariant : u32 { kDsNone = 0, kDsDepthOnly = 1, kDsDepthStencil = 2, kDsVariantCount = 3 };

    /** @brief Color attachment format of a pass — like DsVariant, WebGPU
     *         validates the pipeline's color target format against the pass, and
     *         BGRA is a DIFFERENT format from RGBA to that check even though both
     *         are 8-bit unorm: a surface is usually the former, a render target
     *         the latter, so they cannot share a slot. */
    enum ColorVariant : u32 {
        kColorRgba8 = 0, kColorBgra8 = 1, kColorSrgb8 = 2, kColorRgba16f = 3, kColorRgba32f = 4, kColorVariantCount = 5,
    };

    /** @brief Sample count of a pass — a third thing WebGPU validates a pipeline
     *         against, and the reason a multisampled scene needs its own variant
     *         of every pipeline that draws into it. One or {@link kMsaaSamples}. */
    enum SampleVariant : u32 { kSingleSample = 0, kMultiSample = 1, kSampleVariantCount = 2 };

    /** @brief The multisampled count this backend offers. WebGPU guarantees 1 and
     *         4 for every renderable format; nothing else is portable. */
    static constexpr u32 kMsaaSamples = 4;

    /** @brief Which variant slot a pass's colour format uses. Beside the enum
     *         because the two are one decision: a format that shares a slot with
     *         another is a pipeline handed to a pass that rejects it. */
    static u32 colorVariantOf(WGPUTextureFormat format);

    /** @brief @p device may be null for bookkeeping-only use (tests, bring-up).
     *  @param instance  The host's WGPUInstance to share. Web/emscripten passes
     *         null and the device creates its own (the emscripten singleton). A
     *         native shell that already built the instance to acquire the
     *         adapter/device passes it here so the surface is created on the SAME
     *         instance — native Dawn ties a surface to its creating instance. */
    /** @param adapter Native hosts pass theirs so the swapchain can ask the surface
     *                 which formats it supports; omitting it assumes RGBA8. */
    explicit WebGPUDevice(WGPUDevice device = nullptr, WGPUInstance instance = nullptr,
                          WGPUAdapter adapter = nullptr);
    ~WebGPUDevice() override;

    ClipDepthRange clipDepthRange() const override { return ClipDepthRange::ZeroToOne; }

    void init() override;
    void shutdown() override;

    // Device loss reaches this class from OUTSIDE it: WebGPU accepts a
    // device-lost callback only in the descriptor that creates the device, and
    // both hosts create theirs before handing it over. Hence these entry points.

    /** @brief Maps a WGPUDeviceLostReason to the backend-neutral reason. */
    static GfxDeviceLostReason reasonFromWgpu(u32 wgpuReason);

    /** @brief Routes the device's uncaptured-error callback; only fatal kinds become losses. */
    void reportUncapturedError(u32 wgpuErrorType, const char* message);
    /// Validation errors said so far (reportUncapturedError says the first few).
    u32 validation_errors_logged_ = 0;

    bool pollDeviceLost() override;

    /** @brief Hands a replacement in for the next recovery attempt to take up. */
    bool provideReplacementDevice(void* nativeDevice) override {
        pending_device_ = static_cast<WGPUDevice>(nativeDevice);
        return pending_device_ != nullptr;
    }

    void setViewport(i32 x, i32 y, u32 w, u32 h) override;
    void clearStencil(i32 value) override;

    void setScissorTest(bool enabled) override;
    void setScissor(i32 x, i32 y, i32 w, i32 h) override;

    void setVertexBuffer(u32 slot, BufferHandle buffer, u32 offsetBytes) override;
    void setIndexBuffer(BufferHandle buffer) override;

    void bindTexture(u32 slot, TextureHandle texture) override;
    bool supportsCompressedFormat(GfxCompressedFormat format) override;
    // Float-target rendering is a WebGPU core capability.
    bool supportsFloatTargets() override { return true; }
    /** The surface record's target carries no blend state of its own (see createPipeline). */
    bool supportsUnblendedSurfaceTarget() const override { return true; }
    u32 maxSamples() override;
    /** Colour resolves in the pass; depth is resolved by a pass of our own
     *  ({@link resolveDepthAttachment}), since WebGPU's depth attachment has no
     *  resolve target. Either way nothing above the RHI knows. */
    bool resolvesDepth() const override { return true; }
    /**
     * @brief How many samples a SURFACE pass draws with — a frame with no post
     *        chain draws straight to the backbuffer.
     * @details A WebGL canvas is created antialiased; a WebGPU surface texture
     *          never is, so the backbuffer gets a multisampled companion that
     *          resolves into it. The change lands on the next frame.
     */
    void setSurfaceSamples(u32 samples) override {
        surface_samples_ = samples > 1 ? kMsaaSamples : 1;
    }

    /// WebGPU is the backend with a compute stage; a device-less instance (bookkeeping only) has none to offer.
    bool supportsCompute() const override { return device_ != nullptr; }
    ReadbackHandle requestBufferReadback(BufferHandle buffer, u32 offsetBytes, u32 sizeBytes) override;
    ReadbackHandle requestTextureReadback(TextureHandle texture) override;

    bool supportsShaderLanguage(GfxShaderLanguage language) const override {
        return language == GfxShaderLanguage::WGSL;
    }

    /// WebGPU stores a texture from the top down.
    bool textureOriginTopLeft() const override { return true; }

    void setStencilReference(i32 reference) override;

    void drawElements(u32 indexCount, GfxDataType indexType, u32 indexByteOffset) override;
    void drawArrays(u32 firstVertex, u32 vertexCount) override;
    void drawElementsInstanced(u32 indexCount, GfxDataType indexType, u32 indexByteOffset,
                               u32 instanceCount) override;

    void beginRenderPass(const RenderPassDesc& desc) override;
    void endRenderPass() override;
    void resizeBackbuffer(u32 width, u32 height) override;

    ReadbackHandle requestReadback(FramebufferHandle target, u32 w, u32 h) override;
    GfxReadbackStatus pollReadback(ReadbackHandle handle) override;
    bool takeReadback(ReadbackHandle handle, void* dest, usize destSize) override;
    void discardReadback(ReadbackHandle handle) override;

    void beginTimerQuery(u32 query) override;
    void endTimerQuery() override;
    bool timerDisjoint() override;
    bool getTimerQueryNs(u32 query, u64* outNs) override;

    void setWireframe(bool enabled) override;
    u32 getError() override;
    std::string getString(GfxStringName name) override;
    i32 getInt(GfxIntParam param) override;

protected:
    void captureDeviceIdentity() override;
    bool recreateDevice() override;

    bool backendCreateBuffer(u32 id, const BufferDesc& desc, const void* data) override;
    void backendDeleteBuffer(u32 id) override;
    void backendUpdateBuffer(u32 id, u32 offsetBytes, const void* data, u32 sizeBytes) override;
    void backendResizeBuffer(u32 id, const BufferDesc& desc, const void* data) override;
    void backendSetUniformBuffer(u32 slot, BufferHandle buffer, u32 offsetBytes, u32 sizeBytes) override;

    bool backendCreateTexture(u32 id, const TextureDesc& desc, const void* pixels) override;
    bool backendCreateCompressedTexture(u32 id, const TextureDesc& desc, GfxCompressedFormat format,
                                        const void* data, u32 byteLength, u32 mipLevels) override;
    /** A foreign surface (canvas, video frame) arrives as a WGPUTexture, never an integer. */
    bool backendAdoptTexture(u32, u32, const TextureDesc&) override { return false; }
    void backendDeleteTexture(u32 id) override;
    void backendMoveTexture(u32 into, u32 from) override;
    void backendUpdateTexture(u32 id, i32 x, i32 y, u32 width, u32 height,
                              const void* pixels, bool flipY) override;
    void backendSetTextureParams(u32 id, const TextureDesc& desc) override;
    void backendGenerateMipmaps(u32 id) override;

    bool backendCreateCompute(u32 id, const GfxComputeSource& source, std::string* outLog) override;
    void backendDeleteCompute(u32 id) override;
    bool backendDispatchCompute(u32 id, const GfxComputeBinding* bindings, u32 bindingCount,
                                u32 groupsX, u32 groupsY, u32 groupsZ) override;

    bool backendCreateProgram(u32 id, const GfxShaderSource& source,
                              const GfxAttribBinding* bindings, u32 bindingCount,
                              std::string* outLog, GfxShaderStage* outFailedStage) override;
    void backendDeleteProgram(u32 id) override;
    // Programs bind through pipelines, uniforms through UBO bindings and blocks by
    // @group/@binding: the GL-shaped program state has nothing to reach here.
    void backendUseProgram(u32) override {}
    i32 backendUniformLocation(u32, const char*) override { return -1; }
    i32 backendAttribLocation(u32, const char*) override { return -1; }
    void backendSetUniform(i32, const GfxUniformValue&) override {}
    std::vector<GfxUniformInfo> backendActiveUniforms(u32) override { return {}; }
    u32 backendUniformBlockIndex(u32, const char*) override { return GFX_INVALID_UNIFORM_BLOCK; }
    void backendUniformBlockBinding(u32, u32, u32) override {}

    bool backendAcceptsVertexLayout(const VertexLayoutDesc& desc) override;
    void backendDeleteVertexLayout(u32) override {}
    void backendSetPipeline(u32 id, const PipelineDesc& desc) override;
    void backendInvalidatePipelineCache() override {}

    bool backendCreateFramebuffer(u32 id, const FramebufferDesc& desc) override;
    void backendDeleteFramebuffer(u32) override {}

    bool backendCreateTimerQuery(u32 id) override;
    u32 backendReadbackCount() const override { return static_cast<u32>(readbacks_.size()); }

public:
    // -------------------------------------------------------------------------
    // Bring-up introspection (tests / slice-2 plumbing)
    // -------------------------------------------------------------------------

    bool hasDevice() const { return device_ != nullptr; }

    /**
     * @brief Binds a canvas as the default render target (bring-up entry, not part
     *        of the GfxDevice interface). @p selector is a CSS selector the
     *        emscripten surface source resolves, e.g. "#canvas". The web build's
     *        surface source; a native Dawn build reaches the surface through the
     *        {@link NativeSurface} overload instead.
     */
#if defined(__EMSCRIPTEN__)
    bool configureSurface(const char* selector, u32 width, u32 height);
#endif

    /** The kind of native window a non-emscripten host draws into. */
    /** Linux is TWO kinds because a Linux desktop is two display servers, and
     *  which one a machine is running is not a build-time fact. */
    enum class NativeWindowKind { MetalLayer, AndroidWindow, Win32Hwnd, WaylandSurface, XlibWindow };

    /** A `CAMetalLayer*` / `ANativeWindow*` / `HWND` / `wl_surface*` for a
     *  native-C++ build; compiled out of the wasm build, where the host injects an
     *  already-built surface instead. */
    struct NativeSurface {
        NativeWindowKind kind;
        /** The window: an `HWND`, a `wl_surface*` — or, for Xlib, the `Window`
         *  XID, which is an integer and travels here as one. */
        void* handle;
        /** What the window belongs to, which the descriptor asks for beside it:
         *  the `HINSTANCE` on Win32, the `wl_display*` on Wayland, the `Display*`
         *  on Xlib. */
        void* instance = nullptr;
    };

#if !defined(__EMSCRIPTEN__)
    /** @brief Binds a native window as the render target; shares configureSwapchain
     *         with the web path. Native Dawn build only. */
    bool configureSurface(const NativeSurface& window, u32 width, u32 height);

    /** @brief Flips the swapchain to the display. The web path relies on the
     *         browser presenting the canvas after the frame callback; a native
     *         host must present the surface explicitly, once per frame after
     *         endRenderPass. No-op until a surface is configured. */
    void present();

#endif

    /**
     * @brief Whether bytes read back from the DEFAULT framebuffer are BGRA rather
     *        than RGBA.
     *
     * The format is the surface's choice (BGRA8 on Metal, RGBA8 on Vulkan), so
     * anyone writing an image has to ask rather than assume.
     */
    bool surfaceBytesAreBGRA() const;

    bool frameCaptureIsBGRA() const override { return surfaceBytesAreBGRA(); }

    /**
     * @brief The surface format the host says its canvas prefers.
     *
     * Only the page can answer it (`navigator.gpu.getPreferredCanvasFormat()`),
     * and configuring anything else costs a full-frame copy per present. Must be
     * set BEFORE the surface is configured.
     */
    void setPreferredSurfaceBGRA(bool bgra) { prefer_surface_bgra_ = bgra; }

    /**
     * @brief Configure the swapchain with CopySrc, so {@link captureNextFrame}
     *        can read it. Must be set BEFORE the surface is configured.
     *
     * Off by default: a surface is entitled not to support the usage, and every
     * shipped frame would pay for a check nobody asked for.
     */
    void setSurfaceReadback(bool enabled) { surface_readback_ = enabled; }

    /**
     * @brief Present as fast as the surface allows instead of waiting for the
     *        display. Set BEFORE the surface is configured; off by default.
     *
     * For MEASUREMENT only: under Fifo every frame reads as the refresh interval
     * or a multiple of one, and a cost quantised to the panel is not a cost.
     * Best effort — Mailbox, then Immediate, then Fifo.
     */
    void setPresentUncapped(bool enabled) { present_uncapped_ = enabled; }

    /**
     * @brief Copy the next completed frame's swapchain image into a readback.
     *
     * Books the copy; endFrame performs it, because the renderer gives the
     * swapchain image back there and every caller outside runs too late. This is
     * the whole reason the seam is virtual: a GL default framebuffer can be read
     * on demand, and this one cannot.
     *
     * Invalid without {@link setSurfaceReadback}, or with a capture in flight.
     */
    ReadbackHandle captureNextFrame(u32 w, u32 h) override;

    void endFrame() override;

private:
    /** Match the backbuffer's depth-stencil companion to @p width x @p height. */
    bool ensureSurfaceDepth(u32 width, u32 height);

    /**
     * @brief Takes up a replacement device: every object of the old one is released
     *        and the surface is re-made, leaving the registry to rebuild the rest.
     */
    bool adoptDevice(WGPUDevice device);

    /** A GL-style rect's y (origin bottom-left) in this pass' coordinates
     *  (origin top-left). See the definition. */
    i32 flipRectY(i32 y, i32 height) const;

    struct BufferRec {
        WGPUBuffer buffer = nullptr;
        u32 size = 0;
        GfxBufferUsage usage = GfxBufferUsage::Vertex;
    };
    struct TextureRec {
        WGPUTexture texture = nullptr;
        WGPUTextureView view = nullptr;  ///< Default full view, created with the texture.
        /// The view a SAMPLE binds. Depth-stencil textures cannot be sampled
        /// through an all-aspects view, so theirs is depth-only; for every other
        /// format this is `view` and is not released twice.
        WGPUTextureView sampleView = nullptr;
        u32 width = 0;
        u32 height = 0;
        WGPUTextureFormat format = WGPUTextureFormat_RGBA8Unorm;
        /// The RHI format the texture was created with — the layout an upload reads
        /// the caller's pixels in. WebGPU has no 3-channel format, so RGB8 sources
        /// land in an RGBA8 texture and `format` alone cannot size the source rows.
        GfxPixelFormat srcFormat = GfxPixelFormat::RGBA8;
        u8 samplerKey = 0;  ///< Packed filter/wrap params (sampler cache key).
        /// 1, or kMsaaSamples for an attachment drawn into and resolved out of.
        u32 samples = 1;
        /// 1, or the whole chain for a texture that declared mipmaps. `view` is
        /// then level 0 alone (an attachment is one level) and `sampleView` all.
        u32 mipLevels = 1;
        /// Created with StorageBinding: a compute shader may write it.
        bool storage = false;
        /// Above 1 a 2D array: `view` and `sampleView` are then the one 2DArray view of every layer and level.
        u32 layers = 1;
    };
    struct ProgramRec {
        WGPUShaderModule vertex = nullptr;
        WGPUShaderModule fragment = nullptr;
        /** @brief `@group(0/1) @binding(i)` masks scanned from the WGSL (both
         *         stages). They drive the program's EXPLICIT bind-group and
         *         pipeline layouts: group 0 = which UBO slots the program
         *         declares, group 1 = which texture/sampler bindings. Declared
         *         bindings with no bound resource are backfilled with dummies,
         *         so an unused declaration is as legal as in GLSL. */
        u32 group0Mask = 0;
        u32 group1Mask = 0;
        /// Which of group1Mask's bindings the VERTEX stage declares. A texture is
        /// fragment-visible by default here; one the vertex stage names has to say
        /// so, and the layout it produces is a different layout.
        u32 group1VertexMask = 0;
        /// Which of group1Mask's bindings are `texture_depth_2d`.
        u32 group1DepthMask = 0;
        /// Which of group1Mask's bindings are `texture_2d_array`.
        u32 group1ArrayMask = 0;
    };
    /// What a pass's second colour attachment means to the pipeline drawn into it: there is none, the
    /// pipeline writes it, or the pipeline leaves it alone (its target is declared with an empty write mask).
    enum GBufferVariant : u32 { kGBufferNone = 0, kGBufferWrites = 1, kGBufferSkips = 2, kGBufferWritesAlbedo = 3, kGBufferVariantCount = 4 };
    struct PipelineRec {
        /// Lazily built per pass shape:
        /// [((ds * kColorVariantCount + color) * kSampleVariantCount + samples) * kGBufferVariantCount + gbuffer].
        WGPURenderPipeline variants[static_cast<u32>(kDsVariantCount) * static_cast<u32>(kColorVariantCount)
                                    * static_cast<u32>(kSampleVariantCount)
                                    * static_cast<u32>(kGBufferVariantCount)] = {};
    };
    struct ComputeRec {
        WGPUShaderModule module = nullptr;
        std::string entry;
        /// One pipeline per bind-group layout the program has been dispatched with.
        std::unordered_map<std::string, WGPUComputePipeline> pipelines;
    };
    struct ReadbackRec {
        WGPUBuffer buffer = nullptr;  ///< CopyDst|MapRead staging buffer.
        u32 width = 0;
        u32 height = 0;
        u32 paddedBytesPerRow = 0;  ///< Row stride in the buffer (256-aligned).
        GfxReadbackStatus status = GfxReadbackStatus::Pending;
        /// A compute readback: tight rows in the source's own bytes, top-down, never flipped to GL's order.
        bool raw = false;
        u32 bytesPerTexel = 4;
        u32 tightBytes = 0;  ///< What takeReadback hands back for a raw readback.
    };

    /** @brief Logs a not-yet-implemented path once per entry point. */
    void stubOnce(const char* what);

    /** @brief (Re)configures the surface swapchain + companion depth-stencil
     *         at @p width x @p height (configureSurface's second half; also the
     *         resizeBackbuffer implementation). */
    bool configureSwapchain(u32 width, u32 height);

    /** @brief Builds (once) and returns the WGPURenderPipeline for a handle,
     *         in the variant matching the current pass's depth-stencil shape. */
    WGPURenderPipeline ensurePipeline(u32 id);

    WGPUBuffer makeBuffer(GfxBufferUsage usage, u32 size, const void* data);
    /** @brief A texture and its views; false with @p out untouched when creation fails. */
    bool makeTexture(const TextureDesc& desc, const void* pixels, TextureRec& out);
    /** @brief Writes a rectangle of one layer (layer 0 of a plain 2D texture). */
    void writeTexture(const TextureRec& rec, i32 x, i32 y, u32 width, u32 height,
                      const void* pixels, bool flipY, u32 layer = 0);
    /** @brief Releases a texture's views and storage, dropping bind groups that name them. */
    void releaseTexture(TextureRec& rec);
    /** @brief Returns the cached explicit bind-group layout for a binding mask.
     *         Group 0 entries are uniform buffers at their slot; group 1 entries
     *         are texture_2d/sampler pairs per the WebGPUMappings unit→binding
     *         convention (engine units 0..7 at 0..7/8..15, material units 8..15
     *         at 16..23/24..31). */
    WGPUBindGroupLayout groupLayoutFor(u32 group, u32 mask, u32 depthMask = 0,
                                       u32 vertexMask = 0, u32 arrayMask = 0);
    /** @brief Returns the cached explicit pipeline layout for a program's masks.
     *         A program with group-1 bindings but an empty group 0 still gets a
     *         (zero-entry) group-0 layout, so group indices stay positional. */
    WGPUPipelineLayout pipelineLayoutFor(u32 group0Mask, u32 group1Mask, u32 group1DepthMask = 0,
                                        u32 group1VertexMask = 0, u32 group1ArrayMask = 0);
    /** @brief Lazily creates the dummy backfill resources: a zeroed uniform
     *         buffer and a 1x1 white texture, standing in for declared-but-
     *         unbound bindings (GL reads an unbound block/unit without
     *         validation errors; here it reads zeros/white). */
    void ensureDummies();
    /** @brief (Re)creates the bind groups against the program's explicit
     *         layouts: group 0 = UBO slots, group 1 = texture units mapped
     *         through the unit→binding convention, sampler i carrying texture
     *         i's filter/wrap params (GL's combined texture+sampler state
     *         de-combined). Every declared binding gets an entry — bound
     *         resource or dummy — so the groups always match the layouts. */
    void flushBindGroup();
    /** @brief Returns the cached sampler for packed filter/wrap params. */
    WGPUSampler samplerFor(u8 key);
    /** @brief Builds (once) an internal clear pipeline: fullscreen triangle at
     *         z=1, color from the internal UBO. Keyed on which attachments it
     *         writes (color/depth/stencil masks) plus the pass DS shape. */
    WGPURenderPipeline ensureClearPipeline(bool color, bool depth, bool stencil);
    /** @brief Draws the internal clear triangle mid-pass. Restores scissor (when
     *         @p region is given), the user's stencil reference, and forces
     *         pipeline + bind groups to re-establish on the next user draw. */
    bool storesTargetsTopDown() const override { return true; }
    void copyTextureFlippedY(TextureHandle src, TextureHandle dst) override;
    WGPURenderPipeline ensureFlipPipeline(WGPUTextureFormat format);
    void drawInternalClear(bool color, bool depth, bool stencil,
                           const f32 rgba[4], i32 stencilValue, const RenderPassDesc* region);
    /** @brief True while inside beginRenderPass/endRenderPass. */
    bool inPass() const { return pass_ != nullptr; }

    WGPUDevice device_ = nullptr;
    WGPUQueue queue_ = nullptr;
    WGPUDevice pending_device_ = nullptr;  ///< Replacement a host handed over, not yet adopted.
    WGPUInstance instance_ = nullptr;
    WGPUAdapter adapter_ = nullptr;  ///< Native only, host-owned: surface capability queries.
    bool owns_instance_ = true;  ///< False when a native host injected its instance (don't release it).

    // Surface (the Default framebuffer target). The companion depth-stencil
    // texture mirrors the WebGL canvas's depth+stencil planes — engine stencil
    // masks and depth-tested draws target the backbuffer and expect them.
    WGPUSurface surface_ = nullptr;
    WGPUTextureFormat surface_format_ = WGPUTextureFormat_RGBA8Unorm;
    /** Whether the host's canvas prefers BGRA8 (see setPreferredSurfaceBGRA). */
    bool prefer_surface_bgra_ = false;
    /** Whether the surface was configured with CopySrc — see setSurfaceReadback. */
    bool surface_readback_ = false;
    /** Whether the surface should present unthrottled — see setPresentUncapped. */
    bool present_uncapped_ = false;
    /** The fastest mode this surface advertises, for setPresentUncapped. */
    WGPUPresentMode pickUncappedPresentMode() const;
    /** The pass being recorded draws to the surface, so a capture rides its encoder. */
    bool pass_is_surface_ = false;
    /** A booked capture was already copied by a pass; endFrame only maps it. */
    bool capture_copied_ = false;
    /** A capture booked by captureNextFrame, served by endFrame. 0 = none. */
    u32 capture_id_ = 0;
    u32 surface_width_ = 0;
    u32 surface_height_ = 0;
    /** The canvas the surface was made for, so a replacement device can re-make it. */
    std::string surface_selector_;
    WGPUTexture surface_depth_texture_ = nullptr;
    WGPUTextureView surface_depth_view_ = nullptr;

    // In-flight readbacks: staging buffers whose mapAsync callback flips status.
    std::unordered_map<u32, ReadbackRec> readbacks_;
    u32 next_readback_id_ = 1;

    /** @brief mapAsync completion: flips the readback's status by id (userdata2).
     *         A discarded/taken readback simply misses the lookup and no-ops. */
    static void onReadbackMapped(WGPUMapAsyncStatus status, WGPUStringView message,
                                 void* userdata1, void* userdata2);
    /** @brief Erases + releases a readback record (aborts a still-pending map). */
    void releaseReadback(u32 id);

    /** Frees everything the device owns, keeping the instance and surface shape. */
    void releaseDeviceObjects();
    /** A staging buffer + record with no copy submitted yet; 0 on failure. */
    u32 allocReadback(u32 w, u32 h);
    /// The same for a compute readback: @p bytes of a buffer, or a w x h texture of @p bytesPerTexel.
    u32 allocRawReadback(u32 w, u32 h, u32 bytesPerTexel, u32 tightBytes);
    void submitReadbackCopy(u32 id, WGPUTexture source);
    void encodeReadbackCopy(WGPUCommandEncoder encoder, u32 id, WGPUTexture source);
    void mapReadback(u32 id);

    // Internal clear family (region-scoped clears + mid-pass clearStencil).
    // Explicit layout so ONE bind group serves every write-mask variant.
    std::unordered_map<u32, WGPURenderPipeline> clear_pipelines_;
    std::unordered_map<u32, WGPURenderPipeline> flip_pipelines_;
    WGPUBindGroupLayout flip_bgl_ = nullptr;
    WGPUPipelineLayout flip_layout_ = nullptr;
    WGPUBindGroupLayout clear_bgl_ = nullptr;
    WGPUPipelineLayout clear_layout_ = nullptr;
    WGPUBindGroup clear_bind_group_ = nullptr;
    WGPUBuffer clear_color_buffer_ = nullptr;

    // Per-pass state.
    u32 pass_width_ = 0;   ///< Current pass target size (scissor-off rectangle).
    u32 pass_height_ = 0;
    WGPUTextureFormat pass_ds_format_ = WGPUTextureFormat_Undefined;
    WGPUTextureFormat pass_color_format_ = WGPUTextureFormat_RGBA8Unorm;
    /// Samples of the pass's colour attachment — what its pipelines must declare.
    u32 pass_samples_ = 1;
    /// The pass draws into a second colour attachment (always RGBA8) beside the first.
    bool pass_gbuffer_ = false;
    /// The pass also carries the third attachment, the surface's diffuse colour (FramebufferDesc::color2).
    bool pass_albedo_ = false;
    /// The multisampled depth attachment of the pass being ended, and the
    /// single-sample texture it owes its contents to. Both 0 unless resolving.
    u32 pass_depth_msaa_ = 0;
    u32 pass_depth_resolve_ = 0;
    /// Samples the backbuffer is drawn with (see setSurfaceSamples).
    u32 surface_samples_ = 1;
    /// The multisampled companion the backbuffer resolves out of, and the depth
    /// beside it. Rebuilt whenever the surface size or sample count changes.
    WGPUTexture surface_msaa_texture_ = nullptr;
    WGPUTextureView surface_msaa_view_ = nullptr;
    u32 surface_msaa_width_ = 0;
    u32 surface_msaa_height_ = 0;
    u32 surface_msaa_samples_ = 0;
    /// Samples the backbuffer's depth companion was built with.
    u32 surface_depth_samples_ = 1;
    bool ensureSurfaceMsaa(u32 width, u32 height);

    /** @brief Copies sample 0 of a multisampled depth attachment into its
     *         single-sample twin, so an effect can sample scene depth on a
     *         multisampled target. WebGPU has no depth resolve of its own. */
    void resolveDepthAttachment(u32 msaaDepth, u32 resolveDepth);
    WGPURenderPipeline ensureDepthResolvePipeline(WGPUTextureFormat format);
    /** @brief Fills every level below 0 from the one above, a linear sample at each
     *         texel's centre — a box average of the four under it. */
    void buildMipChain(const TextureRec& rec);
    WGPURenderPipeline ensureMipPipeline(WGPUTextureFormat format);
    WGPUShaderModule mip_module_ = nullptr;
    WGPUBindGroupLayout mip_bgl_ = nullptr;
    WGPUPipelineLayout mip_layout_ = nullptr;
    WGPUSampler mip_sampler_ = nullptr;
    std::unordered_map<u32, WGPURenderPipeline> mip_pipelines_;
    WGPUShaderModule depth_resolve_vs_ = nullptr;
    WGPUShaderModule depth_resolve_fs_ = nullptr;
    WGPUBindGroupLayout depth_resolve_bgl_ = nullptr;
    WGPUPipelineLayout depth_resolve_layout_ = nullptr;
    std::unordered_map<u32, WGPURenderPipeline> depth_resolve_pipelines_;
    /// What this pass draws INTO, so flushBindGroup can refuse to also sample it.
    /// 0 = none (the surface, which nothing can hold as a texture anyway).
    u32 pass_color_texture_ = 0;
    u32 pass_depth_texture_ = 0;
    WGPUCommandEncoder encoder_ = nullptr;
    WGPURenderPassEncoder pass_ = nullptr;
    void* surface_window_ = nullptr;        ///< Native window the surface was made for.
    u32 surface_depth_width_ = 0;           ///< Size the depth companion was built for.
    u32 surface_depth_height_ = 0;
    WGPUTexture frame_texture_ = nullptr;   ///< The frame's swapchain texture (released at endFrame).
    WGPUTextureView frame_view_ = nullptr;
    u32 bound_pipeline_ = 0;
    u32 bound_index_buffer_ = 0;
    i32 stencil_ref_ = 0;  ///< Last user-set reference (re-applied after internal quads).
    /// Slots 0..9 include the per-draw planar capture. Ten is inside both
    /// WebGPU's and WebGL2's guaranteed 12 uniform buffers per stage.
    static constexpr u32 kUniformSlots = 10;
    u32 uniform_slots_[kUniformSlots] = {};  ///< BufferHandle id per UBO binding slot.
    u32 uniform_offsets_[kUniformSlots] = {};
    u32 uniform_sizes_[kUniformSlots] = {};  ///< 0 = the whole buffer.
    /// Engine units 0..7 (batch multi-texture) + material-param units 8..15
    /// (== webgpu::kGroup1TextureUnits, static_asserted in the .cpp).
    static constexpr u32 kTextureSlots = 16;
    u32 texture_slots_[kTextureSlots] = {};  ///< TextureHandle id per sampler unit.
    bool bind_group_dirty_ = true;
    WGPUBindGroup bind_group_ = nullptr;    ///< Currently bound group 0 (points INTO the cache; not owned).
    WGPUBindGroup texture_group_ = nullptr; ///< Currently bound group 1 (points INTO the cache; not owned).

    // Reuse immutable bind groups only when their layout and ordered bindings match.
    // Evict before resource release: emscripten reuses WGPU handle indices immediately.
    // Layouts belong to the device and outlive this cache.
    struct BindGroupCacheEntry {
        WGPUBindGroupLayout layout;
        std::vector<u64> ids;   ///< WGPU resource pointers (buffers, or view+sampler), binding order.
        WGPUBindGroup bg;
        u64 used;               ///< The frame that last bound it.
    };
    /// How many groups are kept before those no frame has bound lately are let go. A group bound this frame or the last is never
    /// let go for room: a view with more than this many is kept whole, since making them again every frame exhausts the device.
    static constexpr u32 kBindGroupCacheCap = 4096;
    /// By a hash of the layout and the ids; a bucket holds the few that share one.
    std::unordered_map<u64, std::vector<BindGroupCacheEntry>> bind_group_cache_;
    u32 bind_group_count_ = 0;
    u64 bind_group_frame_ = 0;
    /// Reuse a cached group with these exact contents, else create + insert one.
    WGPUBindGroup cachedBindGroup(const u64* ids, u32 idCount,
                                  const WGPUBindGroupDescriptor& desc);
    /// Drop every cached group referencing a dying resource id (see cache note).
    void evictBindGroups(u64 id);

    /// The single WriteBuffer call site. Its size must be a 4-byte multiple and the
    /// caller's allocation is only @p size bytes, so a short tail is staged through a
    /// zero-padded copy rather than over-read. @p offset must already be aligned.
    void writeBufferPadded(WGPUBuffer buffer, u32 offset, const void* data, u32 size);

    // GPU timing — the WebGPU analog of GLDevice's GL_TIME_ELAPSED timer, so the
    // profiler's gpuMs/gpuScopes populate on both backends. Active only when the
    // device has the timestamp-query feature; otherwise createTimerQuery returns 0
    // and timing stays off (unchanged behavior). begin/endTimerQuery bracket a span;
    // every render or compute pass that opens inside it writes a begin/end timestamp,
    // resolved into the span's readback buffer, and the span is their sum — the
    // whole frame's GPU time, as GL's query gives it, not one pass's. The buffers are
    // mapped asynchronously and getTimerQueryNs drains the elapsed ns into the
    // engine's GpuTimer (whose ring already tolerates a few frames of latency).
    bool timestamp_supported_ = false;
    bool timestamp_init_done_ = false;
    WGPUQuerySet timestamp_qset_ = nullptr;   ///< 2 slots: begin/end of the timed pass.
    WGPUBuffer timestamp_resolve_ = nullptr;  ///< QueryResolve target (16 bytes).
    static constexpr u32 kGpuTimeRing = 4;
    /// Passes one span can sum. A frame with more is timed up to here, which reads low rather than wrong-way.
    static constexpr u32 kSpanPasses = 96;
    struct GpuTimeSlot { WGPUBuffer buf = nullptr; bool pending = false; u32 passes = 0; };
    GpuTimeSlot gpu_time_ring_[kGpuTimeRing] = {};
    u32 gpu_time_next_ = 0;                ///< Round-robin cursor into the ring.
    bool span_open_ = false;               ///< Between beginTimerQuery and endTimerQuery.
    bool span_closing_ = false;            ///< Ended with a render pass still open; that pass's end finishes it.
    u32 span_slot_ = kGpuTimeRing;         ///< Ring slot the open span resolves into (== kGpuTimeRing: none).
    u32 span_passes_ = 0;                  ///< Passes resolved into it so far.
    bool pass_timed_ = false;              ///< Does the open render pass carry timestamps for the span?
    std::vector<u64> gpu_time_results_;    ///< Resolved elapsed-ns, FIFO, drained by getTimerQueryNs.
    void ensureTimestamps();               ///< Lazily create the query set + buffers (feature-gated).
    bool spanTakesPass() const;            ///< Should a pass opening now be stamped for the span?
    void resolveSpanPass(WGPUCommandEncoder encoder);  ///< After such a pass ends, on its encoder.
    void finishSpan();                     ///< Map the span's buffer; its sum arrives in gpu_time_results_.

    // Per-pass timing: armPassTimer names the next pass, which carries the timestamps and has them resolved into a
    // pooled readback buffer; the result is filed under the name (a timer query id) it was armed with.
    bool timesPassesByArming() const override { return true; }
    void armPassTimer(u32 query) override;
    static constexpr u32 kNoPassSlot = ~0u;
    static constexpr u32 kPassTimePool = 256;
    struct PassTimeSlot { WGPUBuffer buf = nullptr; bool pending = false; u32 tag = 0; };
    std::vector<PassTimeSlot> pass_time_pool_;
    std::unordered_map<u32, u64> pass_time_results_;  ///< Elapsed ns by tag, taken by getTimerQueryNs.
    std::unordered_set<u32> pass_time_tags_;          ///< Every id ever armed: those are answered from the map, not the FIFO.
    u32 armed_pass_tag_ = 0;
    u32 pass_time_slot_ = kNoPassSlot;                ///< Pool slot of the open render pass, if it is timed.
    /// Claims a pool slot for the armed tag and clears the arm; kNoPassSlot when nothing is armed or the pool is full.
    u32 takePassTimeSlot();
    void resolvePassTime(WGPUCommandEncoder encoder, u32 slot);
    void mapPassTime(u32 slot);
    static void onPassTimeMapped(WGPUMapAsyncStatus status, WGPUStringView message, void* userdata1, void* userdata2);
    static void onGpuTimeMapped(WGPUMapAsyncStatus status, WGPUStringView message,
                                void* userdata1, void* userdata2);

    std::unordered_map<u8, WGPUSampler> samplers_;  ///< Keyed by packed filter/wrap params.

    // Explicit layouts, cached by every mask that shapes them: {group, mask, depth, vertex, array} for
    // bind-group layouts, {group0, group1, depth, vertex, array} for pipeline layouts. Pipelines and bind groups
    // share the cached objects, so group compatibility holds by identity.
    std::map<std::array<u32, 5>, WGPUBindGroupLayout> group_layouts_;
    std::map<std::array<u32, 5>, WGPUPipelineLayout> pipeline_layouts_;
    // Backfill belongs to this backend, not to the registry: nothing above it can
    // name these, so they are made again lazily rather than recovered.
    BufferRec dummy_ubo_;         ///< Zeroed backfill for declared-but-unbound UBO slots.
    TextureRec dummy_texture_;    ///< 1x1 white backfill for declared-but-unbound units.
    /// The same for a depth unit: an RGBA8 dummy under a `sampleType = Depth`
    /// entry is a validation error, so a declared-but-unbound depth binding
    /// needs a depth texture to stand in.
    TextureRec dummy_depth_texture_;
    /// The same for an array unit: white layers under a `texture_2d_array` declaration (two, since one layer
    /// makes a plain 2D texture here).
    TextureRec dummy_array_texture_;

    /** This device's objects by registry id. */
    std::unordered_map<u32, BufferRec> buffers_;
    std::unordered_map<u32, TextureRec> textures_;
    std::unordered_map<u32, ProgramRec> programs_;
    std::unordered_map<u32, ComputeRec> computes_;
    /// Bind-group layouts of compute dispatches, by what they bind (see computeLayoutKey).
    std::unordered_map<std::string, WGPUBindGroupLayout> compute_layouts_;
    std::unordered_map<std::string, WGPUPipelineLayout> compute_pipeline_layouts_;
    std::unordered_map<u32, PipelineRec> pipelines_;
    std::vector<std::string> stub_logged_;
};

}  // namespace esengine