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.

20.4 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    WebGPUMappings.hpp
 * @brief   Pure RHI-enum → WebGPU translations (REARCH_WGSL Phase 2).
 * @details Every GfxEnums/PipelineState concept the GL backend consumes has its
 *          WebGPU spelling here, as free functions with no device dependency — so
 *          the mapping layer is unit-testable long before a live adapter exists,
 *          and WebGPUDevice stays a thin orchestration shell over these.
 *
 *          Compiled only under ES_ENABLE_WEBGPU (emdawnwebgpu port supplies
 *          <webgpu/webgpu.h>); 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 "../../core/Types.hpp"
#include "../rhi/GfxEnums.hpp"
#include "../draw/BlendMode.hpp"
#include "../rhi/PipelineState.hpp"
#include "../rhi/WgslBindings.hpp"

#include <webgpu/webgpu.h>

#include <cstdlib>
#include <cstring>

namespace esengine::webgpu {

// =============================================================================
// Blend
// =============================================================================

/** @brief One RHI blend mode as a full WebGPU blend state (color + alpha). */
struct BlendStateWGPU {
    WGPUBlendComponent color;
    WGPUBlendComponent alpha;
};

/** @brief Maps BlendMode to its WebGPU blend components — mirrors GLDevice's
 *         setBlendMode table (Overlay renders as Normal there too; the real
 *         overlay math lives in shaders). */
inline BlendStateWGPU toWGPUBlend(BlendMode mode) {
    auto comp = [](WGPUBlendOperation op, WGPUBlendFactor src, WGPUBlendFactor dst) {
        WGPUBlendComponent c{};
        c.operation = op;
        c.srcFactor = src;
        c.dstFactor = dst;
        return c;
    };
    const auto add = WGPUBlendOperation_Add;
    switch (mode) {
    case BlendMode::Additive:
        return { comp(add, WGPUBlendFactor_SrcAlpha, WGPUBlendFactor_One),
                 comp(add, WGPUBlendFactor_One, WGPUBlendFactor_One) };
    case BlendMode::Multiply:
        return { comp(add, WGPUBlendFactor_Dst, WGPUBlendFactor_OneMinusSrcAlpha),
                 comp(add, WGPUBlendFactor_One, WGPUBlendFactor_OneMinusSrcAlpha) };
    case BlendMode::Screen:
        return { comp(add, WGPUBlendFactor_One, WGPUBlendFactor_OneMinusSrc),
                 comp(add, WGPUBlendFactor_One, WGPUBlendFactor_OneMinusSrcAlpha) };
    case BlendMode::PremultipliedAlpha:
        return { comp(add, WGPUBlendFactor_One, WGPUBlendFactor_OneMinusSrcAlpha),
                 comp(add, WGPUBlendFactor_One, WGPUBlendFactor_OneMinusSrcAlpha) };
    case BlendMode::PmaAdditive:
        return { comp(add, WGPUBlendFactor_One, WGPUBlendFactor_One),
                 comp(add, WGPUBlendFactor_One, WGPUBlendFactor_One) };
    case BlendMode::Lighten:
        return { comp(WGPUBlendOperation_Max, WGPUBlendFactor_One, WGPUBlendFactor_One),
                 comp(WGPUBlendOperation_Max, WGPUBlendFactor_One, WGPUBlendFactor_One) };
    case BlendMode::Darken:
        return { comp(WGPUBlendOperation_Min, WGPUBlendFactor_One, WGPUBlendFactor_One),
                 comp(WGPUBlendOperation_Min, WGPUBlendFactor_One, WGPUBlendFactor_One) };
    // None never reaches a live blend state — the pipeline drops the blend target
    // entirely (WebGPUDevice: target.blend = blendEnabled ? &state : nullptr) — but
    // it is spelled out so the mapping stays total rather than leaning on `default`.
    case BlendMode::None:
    case BlendMode::Normal:
    case BlendMode::Overlay:
    default:
        return { comp(add, WGPUBlendFactor_SrcAlpha, WGPUBlendFactor_OneMinusSrcAlpha),
                 comp(add, WGPUBlendFactor_One, WGPUBlendFactor_OneMinusSrcAlpha) };
    }
}

// =============================================================================
// Vertex layout
// =============================================================================

/** @brief Sentinel for "no WGPU spelling": the header defines no Undefined vertex
 *         format, so the enum's non-value stands in. Callers treat it as a hard error. */
inline constexpr WGPUVertexFormat kInvalidVertexFormat = WGPUVertexFormat_Force32;

/** @brief Maps one RHI attribute (components × type × normalized) to a
 *         WGPUVertexFormat, or kInvalidVertexFormat for combinations the engine
 *         never produces. */
inline WGPUVertexFormat toWGPUVertexFormat(u8 components, GfxDataType type, bool normalized) {
    switch (type) {
    case GfxDataType::Float:
        switch (components) {
        case 1: return WGPUVertexFormat_Float32;
        case 2: return WGPUVertexFormat_Float32x2;
        case 3: return WGPUVertexFormat_Float32x3;
        case 4: return WGPUVertexFormat_Float32x4;
        default: return kInvalidVertexFormat;
        }
    case GfxDataType::UnsignedByte:
        // The engine's u8 attributes are colors (normalized RGBA8) — 4 lanes only.
        if (components == 4) return normalized ? WGPUVertexFormat_Unorm8x4 : WGPUVertexFormat_Uint8x4;
        if (components == 2) return normalized ? WGPUVertexFormat_Unorm8x2 : WGPUVertexFormat_Uint8x2;
        return kInvalidVertexFormat;
    case GfxDataType::UnsignedShort:
        if (components == 2) return normalized ? WGPUVertexFormat_Unorm16x2 : WGPUVertexFormat_Uint16x2;
        if (components == 4) return normalized ? WGPUVertexFormat_Unorm16x4 : WGPUVertexFormat_Uint16x4;
        return kInvalidVertexFormat;
    case GfxDataType::Int:
        switch (components) {
        case 1: return WGPUVertexFormat_Sint32;
        case 2: return WGPUVertexFormat_Sint32x2;
        case 3: return WGPUVertexFormat_Sint32x3;
        case 4: return WGPUVertexFormat_Sint32x4;
        default: return kInvalidVertexFormat;
        }
    case GfxDataType::UnsignedInt:
        switch (components) {
        case 1: return WGPUVertexFormat_Uint32;
        case 2: return WGPUVertexFormat_Uint32x2;
        case 3: return WGPUVertexFormat_Uint32x3;
        case 4: return WGPUVertexFormat_Uint32x4;
        default: return kInvalidVertexFormat;
        }
    default:
        return kInvalidVertexFormat;
    }
}

/** @brief Index type for drawElements' GfxDataType. */
inline WGPUIndexFormat toWGPUIndexFormat(GfxDataType type) {
    switch (type) {
    case GfxDataType::UnsignedShort: return WGPUIndexFormat_Uint16;
    case GfxDataType::UnsignedInt:   return WGPUIndexFormat_Uint32;
    default:                         return WGPUIndexFormat_Undefined;
    }
}

// =============================================================================
// Textures / samplers
// =============================================================================

inline WGPUTextureFormat toWGPUTextureFormat(GfxPixelFormat fmt) {
    switch (fmt) {
    // WebGPU has no 3-channel color format; RGB8 sources upload as RGBA8
    // (the GL backend's swizzle-free equivalent — expansion happens at upload).
    case GfxPixelFormat::RGB8:             return WGPUTextureFormat_RGBA8Unorm;
    case GfxPixelFormat::RGBA8:            return WGPUTextureFormat_RGBA8Unorm;
    case GfxPixelFormat::SRGB8_ALPHA8:     return WGPUTextureFormat_RGBA8UnormSrgb;
    case GfxPixelFormat::RGBA16F:          return WGPUTextureFormat_RGBA16Float;
    case GfxPixelFormat::RGBA32F:          return WGPUTextureFormat_RGBA32Float;
    case GfxPixelFormat::DepthComponent24: return WGPUTextureFormat_Depth24Plus;
    case GfxPixelFormat::Depth24Stencil8:  return WGPUTextureFormat_Depth24PlusStencil8;
    default:                               return WGPUTextureFormat_RGBA8Unorm;
    }
}

/** Bytes per pixel of an uncompressed upload in @p fmt (RGB8 expands to RGBA8). */
inline u32 wgpuBytesPerPixel(GfxPixelFormat fmt) {
    if (fmt == GfxPixelFormat::RGBA16F) return 8u;
    if (fmt == GfxPixelFormat::RGBA32F) return 16u;
    return 4u;
}

inline WGPUTextureFormat toWGPUCompressedFormat(GfxCompressedFormat fmt) {
    switch (fmt) {
    case GfxCompressedFormat::ETC2_RGB8:  return WGPUTextureFormat_ETC2RGB8Unorm;
    case GfxCompressedFormat::ETC2_RGBA8: return WGPUTextureFormat_ETC2RGBA8Unorm;
    case GfxCompressedFormat::ASTC_4x4:   return WGPUTextureFormat_ASTC4x4Unorm;
    case GfxCompressedFormat::ASTC_8x8:   return WGPUTextureFormat_ASTC8x8Unorm;
    case GfxCompressedFormat::S3TC_DXT1:  return WGPUTextureFormat_BC1RGBAUnorm;
    case GfxCompressedFormat::S3TC_DXT5:  return WGPUTextureFormat_BC3RGBAUnorm;
    case GfxCompressedFormat::ETC2_RGBA8_SRGB: return WGPUTextureFormat_ETC2RGBA8UnormSrgb;
    case GfxCompressedFormat::ASTC_4x4_SRGB:   return WGPUTextureFormat_ASTC4x4UnormSrgb;
    case GfxCompressedFormat::S3TC_DXT5_SRGB:  return WGPUTextureFormat_BC3RGBAUnormSrgb;
    default:                              return WGPUTextureFormat_Undefined;
    }
}

/** The device feature that gates a compressed-format family (BC / ETC2 / ASTC). */
inline WGPUFeatureName compressionFeatureFor(GfxCompressedFormat fmt) {
    switch (fmt) {
    case GfxCompressedFormat::S3TC_DXT1:
    case GfxCompressedFormat::S3TC_DXT5:
    case GfxCompressedFormat::S3TC_DXT5_SRGB:   return WGPUFeatureName_TextureCompressionBC;
    case GfxCompressedFormat::ASTC_4x4:
    case GfxCompressedFormat::ASTC_8x8:
    case GfxCompressedFormat::ASTC_4x4_SRGB:    return WGPUFeatureName_TextureCompressionASTC;
    case GfxCompressedFormat::ETC2_RGB8:
    case GfxCompressedFormat::ETC2_RGBA8:
    case GfxCompressedFormat::ETC2_RGBA8_SRGB:
    default:                                    return WGPUFeatureName_TextureCompressionETC2;
    }
}

inline WGPUFilterMode toWGPUFilter(TextureFilter filter) {
    return filter == TextureFilter::Nearest ? WGPUFilterMode_Nearest : WGPUFilterMode_Linear;
}

inline WGPUAddressMode toWGPUAddressMode(TextureWrap wrap) {
    switch (wrap) {
    case TextureWrap::ClampToEdge:    return WGPUAddressMode_ClampToEdge;
    case TextureWrap::MirroredRepeat: return WGPUAddressMode_MirrorRepeat;
    case TextureWrap::Repeat:
    default:                          return WGPUAddressMode_Repeat;
    }
}

// =============================================================================
// Buffers
// =============================================================================

inline WGPUBufferUsage toWGPUBufferUsage(GfxBufferUsage usage) {
    switch (usage) {
    case GfxBufferUsage::Vertex:  return WGPUBufferUsage_Vertex | WGPUBufferUsage_CopyDst;
    case GfxBufferUsage::Index:   return WGPUBufferUsage_Index | WGPUBufferUsage_CopyDst;
    case GfxBufferUsage::Uniform: return WGPUBufferUsage_Uniform | WGPUBufferUsage_CopyDst;
    // Copy both ways: a compute buffer is filled from the CPU and read back to it. Vertex too: what a
    // kernel wrote can be drawn as it lies (GPU particles), in a later pass.
    case GfxBufferUsage::Storage: return WGPUBufferUsage_Storage | WGPUBufferUsage_Vertex | WGPUBufferUsage_CopyDst | WGPUBufferUsage_CopySrc;
    default:                      return WGPUBufferUsage_CopyDst;
    }
}

// =============================================================================
// Depth / stencil (PipelineDesc → WGPUDepthStencilState pieces)
// =============================================================================

inline WGPUCompareFunction toWGPUCompare(GfxStencilFunc func) {
    switch (func) {
    case GfxStencilFunc::Never:    return WGPUCompareFunction_Never;
    case GfxStencilFunc::Less:     return WGPUCompareFunction_Less;
    case GfxStencilFunc::Equal:    return WGPUCompareFunction_Equal;
    case GfxStencilFunc::LEqual:   return WGPUCompareFunction_LessEqual;
    case GfxStencilFunc::Greater:  return WGPUCompareFunction_Greater;
    case GfxStencilFunc::NotEqual: return WGPUCompareFunction_NotEqual;
    case GfxStencilFunc::GEqual:   return WGPUCompareFunction_GreaterEqual;
    case GfxStencilFunc::Always:
    default:                       return WGPUCompareFunction_Always;
    }
}

inline WGPUStencilOperation toWGPUStencilOp(GfxStencilOp op) {
    switch (op) {
    case GfxStencilOp::Zero:     return WGPUStencilOperation_Zero;
    case GfxStencilOp::Replace:  return WGPUStencilOperation_Replace;
    case GfxStencilOp::Incr:     return WGPUStencilOperation_IncrementClamp;
    case GfxStencilOp::Decr:     return WGPUStencilOperation_DecrementClamp;
    case GfxStencilOp::Invert:   return WGPUStencilOperation_Invert;
    case GfxStencilOp::IncrWrap: return WGPUStencilOperation_IncrementWrap;
    case GfxStencilOp::DecrWrap: return WGPUStencilOperation_DecrementWrap;
    case GfxStencilOp::Keep:
    default:                     return WGPUStencilOperation_Keep;
    }
}

/** @brief The engine's two stencil modes as WebGPU face states (same table as
 *         GLDevice::applyPipeline: Write = Always/Replace + no color write,
 *         Test = Equal/Keep). */
inline WGPUStencilFaceState toWGPUStencilFace(GfxStencilMode mode) {
    WGPUStencilFaceState face{};
    face.depthFailOp = WGPUStencilOperation_Keep;
    switch (mode) {
    case GfxStencilMode::Write:
        face.compare = WGPUCompareFunction_Always;
        face.failOp = WGPUStencilOperation_Replace;
        face.passOp = WGPUStencilOperation_Replace;
        break;
    case GfxStencilMode::Test:
        face.compare = WGPUCompareFunction_Equal;
        face.failOp = WGPUStencilOperation_Keep;
        face.passOp = WGPUStencilOperation_Keep;
        break;
    case GfxStencilMode::Increment:
    case GfxStencilMode::Decrement:
    case GfxStencilMode::Zero:
        face.compare = WGPUCompareFunction_Equal;
        face.failOp = WGPUStencilOperation_Keep;
        face.passOp = mode == GfxStencilMode::Increment ? WGPUStencilOperation_IncrementClamp
            : mode == GfxStencilMode::Decrement ? WGPUStencilOperation_DecrementClamp
            : WGPUStencilOperation_Zero;
        break;
    case GfxStencilMode::TestOutside:
        face.compare = WGPUCompareFunction_NotEqual;
        face.failOp = WGPUStencilOperation_Keep;
        face.passOp = WGPUStencilOperation_Keep;
        break;
    case GfxStencilMode::Off:
    default:
        face.compare = WGPUCompareFunction_Always;
        face.failOp = WGPUStencilOperation_Keep;
        face.passOp = WGPUStencilOperation_Keep;
        break;
    }
    return face;
}

/** @brief Stencil write mask per mode — the applyStencilMode table: Write fills
 *         all planes, Test reads without writing, Off never touches stencil. */
inline u32 toWGPUStencilWriteMask(GfxStencilMode mode) {
    return writesStencil(mode) ? 0xFFu : 0x00u;
}

/**
 * @brief A pipeline's full depth-stencil state against a pass attachment format.
 * @details GL semantics carried over exactly: a disabled depth test neither
 *          compares NOR writes (glDepthMask only applies while GL_DEPTH_TEST is
 *          on); an enabled one compares with GL's default Less func. Stencil
 *          faces/masks come from the same tables applyStencilMode uses.
 */
inline WGPUDepthStencilState toWGPUDepthStencil(const PipelineDesc& desc, WGPUTextureFormat format) {
    WGPUDepthStencilState ds{};
    ds.format = format;
    ds.depthWriteEnabled = (desc.depthTest && desc.depthWrite) ? WGPUOptionalBool_True
                                                               : WGPUOptionalBool_False;
    ds.depthCompare = desc.depthTest ? (desc.depthEqual ? WGPUCompareFunction_LessEqual : WGPUCompareFunction_Less) : WGPUCompareFunction_Always;
    ds.stencilFront = toWGPUStencilFace(desc.stencil);
    ds.stencilBack = toWGPUStencilFace(desc.stencil);
    ds.stencilReadMask = 0xFFu;
    ds.stencilWriteMask = toWGPUStencilWriteMask(desc.stencil);
    // Both terms, for the reason GLDevice::setDepthBias gives: head-on the
    // constant separates coplanar surfaces, at a grazing angle only the
    // slope-scaled one does.
    ds.depthBias = desc.depthBias;
    ds.depthBiasSlopeScale = static_cast<float>(desc.depthBias);
    return ds;
}

/** @brief True when a depth-stencil format carries stencil planes (drives whether
 *         a pass may set stencil load/store ops — Depth24Plus alone must not). */
inline bool hasStencilPlanes(WGPUTextureFormat format) {
    return format == WGPUTextureFormat_Depth24PlusStencil8 ||
           format == WGPUTextureFormat_Depth32FloatStencil8 ||
           format == WGPUTextureFormat_Stencil8;
}

// =============================================================================
// Render pass load-ops (RenderPassDesc carries the values since the load-op
// unification; a scoped clear region has NO load-op equivalent — the device
// emulates it with a scissored clear-quad, exactly as documented in GfxEnums).
// =============================================================================

inline WGPULoadOp toWGPULoadOp(bool clearRequested, bool scoped) {
    // A region-scoped clear must LOAD the attachment and clear the region by
    // other means; only a full-target clear maps to a real load-op.
    return (clearRequested && !scoped) ? WGPULoadOp_Clear : WGPULoadOp_Load;
}

inline WGPUColor toWGPUClearColor(const RenderPassDesc& desc) {
    return WGPUColor{ desc.clearColorValue[0], desc.clearColorValue[1],
                      desc.clearColorValue[2], desc.clearColorValue[3] };
}

/** @brief Cull state (PipelineDesc.cullEnabled/cullFront). Front face is CCW,
 *         matching the GL backend's default winding. */
inline WGPUCullMode toWGPUCullMode(bool enabled, bool front) {
    if (!enabled) return WGPUCullMode_None;
    return front ? WGPUCullMode_Front : WGPUCullMode_Back;
}

// =============================================================================
// Group-1 binding convention (texture units → bindings)
// =============================================================================

/** @brief Texture units the group-1 convention spans — see WGSL_MAX_TEXTURE_UNITS. */
inline constexpr u32 kGroup1TextureUnits = WGSL_MAX_TEXTURE_UNITS;

// The unit -> binding convention and the two source scans live in rhi/WgslBindings.hpp:
// the shader assembler EMITS what this backend reads back, so one of them owns the rule.

/**
 * @brief Bit mask of the group's bindings whose declaration names the type `kind`.
 * @details Same source scan as {@link scanWGSLBindingMask}, reading the declaration that follows each binding.
 */
inline u32 scanWGSLTextureKindMask(const char* source, u32 group, const char* kind) {
    if (!source) return 0;
    u32 mask = 0;
    for (const char* p = source; (p = std::strstr(p, "@group(")) != nullptr;) {
        p += 7;
        char* end = nullptr;
        const unsigned long g = std::strtoul(p, &end, 10);
        if (end == p) continue;
        p = end;
        if (g != group) continue;
        const char* b = std::strstr(p, "@binding(");
        if (!b) break;
        b += 9;
        const unsigned long idx = std::strtoul(b, &end, 10);
        if (end == b) continue;
        p = end;
        // The declaration this binding attributes: up to the `;` that ends it,
        // so a matching type further down the file cannot be read as this one's.
        const char* semi = std::strchr(p, ';');
        const char* type = std::strstr(p, kind);
        if (idx < 32 && type && (!semi || type < semi)) mask |= (1u << idx);
    }
    return mask;
}

/**
 * @brief Bit mask of the group's bindings a WGSL source declares as DEPTH textures.
 * @details A `texture_depth_2d` binding needs `sampleType = Depth` in its layout
 *          entry and a depth-aspect view under it; bound as an ordinary float
 *          texture WebGPU rejects the pipeline.
 */
inline u32 scanWGSLDepthTextureMask(const char* source, u32 group) {
    return scanWGSLTextureKindMask(source, group, "texture_depth_2d");
}

/**
 * @brief Bit mask of the group's bindings a WGSL source declares as `texture_2d_array`.
 * @details Such a binding's layout entry is `viewDimension = 2DArray`, and only an array view binds under it.
 */
inline u32 scanWGSLArrayTextureMask(const char* source, u32 group) {
    return scanWGSLTextureKindMask(source, group, "texture_2d_array");
}

/// WriteBuffer's size (and offset) must be a 4-byte multiple; buffers are allocated
/// rounded up so the slack exists. Callers supply exactly `size` bytes, so an
/// unaligned size must be staged, never read up to `alignedWriteSize` in place.
inline u32 alignedWriteSize(u32 size) { return (size + 3u) & ~3u; }
inline bool needsWriteStaging(u32 size) { return (size & 3u) != 0; }

/// Whether a write lands inside a buffer. Subtraction, not addition: `offset + size`
/// can wrap past UINT32_MAX and compare as in-range.
inline bool writeFitsInBuffer(u32 offset, u32 size, u32 capacity) {
    return size <= capacity && offset <= capacity - size;
}

}  // namespace esengine::webgpu