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.

19.9 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    Shader.cpp
 * @brief   Shader program implementation
 * @details Thin RAII handle over a GPU program. All GL is delegated to GfxDevice
 *          (compile/link via createProgram, uniforms via setUniform*, reflection
 *          via getActiveUniforms) — this file contains no GL calls.
 *
 * @author  ESEngine Team
 * @date    2025
 *
 * @copyright Copyright (c) 2025 ESEngine Team
 *            Licensed under the Apache License, Version 2.0.
 */

#include "./Shader.hpp"
#include "./GfxDevice.hpp"
#include "../frame/FrameConstants.hpp"
#include "../store/MaterialConstants.hpp"
#include "../store/SkinConstants.hpp"
#include "../store/LightConstants.hpp"
#include "../store/InstanceConstants.hpp"
#include "../store/MorphConstants.hpp"
#include "../store/ProbeConstants.hpp"
#include "../store/PlanarConstants.hpp"
#include "../../core/Log.hpp"

#include <cstring>
#include <cstdio>
#include <vector>

namespace esengine {

Shader::~Shader() {
    if (device_) {
        if (program_ != ShaderHandle::Invalid) {
            device_->deleteProgram(program_);
            program_ = ShaderHandle::Invalid;
        }
        if (paramsUbo_ != BufferHandle::Invalid) {
            device_->deleteBuffer(paramsUbo_);
            paramsUbo_ = BufferHandle::Invalid;
        }
    }
}

Shader::Shader(Shader&& other) noexcept
    : device_(other.device_)
    , program_(other.program_)
    , uniformCache_(std::move(other.uniformCache_))
    , attribCache_(std::move(other.attribCache_))
    , activeUniforms_(std::move(other.activeUniforms_))
    , drawParams_(std::move(other.drawParams_))
    , paramsShadow_(std::move(other.paramsShadow_))
    , paramsDirty_(other.paramsDirty_)
    , paramsUbo_(other.paramsUbo_) {
    linked_ = other.linked_;
    afterLink_ = std::move(other.afterLink_);
    other.program_ = ShaderHandle::Invalid;
    other.paramsUbo_ = BufferHandle::Invalid;
    other.linked_ = true;
    if (!linked_ && device_) device_->onProgramLinked(program_, [this] { finishLink(); });
}

Shader& Shader::operator=(Shader&& other) noexcept {
    if (this != &other) {
        if (device_) {
            if (program_ != ShaderHandle::Invalid) device_->deleteProgram(program_);
            if (paramsUbo_ != BufferHandle::Invalid) device_->deleteBuffer(paramsUbo_);
        }
        device_ = other.device_;
        program_ = other.program_;
        uniformCache_ = std::move(other.uniformCache_);
        attribCache_ = std::move(other.attribCache_);
        activeUniforms_ = std::move(other.activeUniforms_);
        drawParams_ = std::move(other.drawParams_);
        paramsShadow_ = std::move(other.paramsShadow_);
        paramsDirty_ = other.paramsDirty_;
        paramsUbo_ = other.paramsUbo_;
        linked_ = other.linked_;
        afterLink_ = std::move(other.afterLink_);
        other.program_ = ShaderHandle::Invalid;
        other.paramsUbo_ = BufferHandle::Invalid;
        other.linked_ = true;
        if (!linked_ && device_) device_->onProgramLinked(program_, [this] { finishLink(); });
    }
    return *this;
}

Unique<Shader> Shader::create(GfxDevice& device, const std::string& vertexSrc, const std::string& fragmentSrc,
                              GfxShaderLanguage language) {
    auto shader = makeUnique<Shader>();
    shader->device_ = &device;
    if (!shader->compile(vertexSrc, fragmentSrc, {}, nullptr, nullptr, language)) {
        return nullptr;
    }
    return shader;
}

Unique<Shader> Shader::createWithBindings(GfxDevice& device,
                                          const std::string& vertexSrc, const std::string& fragmentSrc,
                                          std::initializer_list<AttribBinding> bindings,
                                          GfxShaderLanguage language, bool deferLink) {
    auto shader = makeUnique<Shader>();
    shader->device_ = &device;
    if (!shader->compile(vertexSrc, fragmentSrc, bindings, nullptr, nullptr, language, deferLink)) {
        return nullptr;
    }
    return shader;
}

Unique<Shader> Shader::createFromFile(GfxDevice& device,
                                      const std::string& vertexPath, const std::string& fragmentPath) {
    auto readFile = [](const std::string& filepath) -> std::string {
        std::FILE* file = std::fopen(filepath.c_str(), "rb");
        if (!file) {
            ES_LOG_ERROR("Failed to open shader file: {}", filepath);
            return "";
        }

        std::string content;
        char chunk[4096];
        usize n;
        while ((n = std::fread(chunk, 1, sizeof chunk, file)) > 0) content.append(chunk, n);
        const bool failed = std::ferror(file) != 0;
        std::fclose(file);

        if (failed) {
            ES_LOG_ERROR("Failed to read shader file: {}", filepath);
            return "";
        }
        if (content.empty()) {
            ES_LOG_ERROR("Shader file is empty: {}", filepath);
            return "";
        }

        return content;
    };

    std::string vertexSrc = readFile(vertexPath);
    std::string fragmentSrc = readFile(fragmentPath);

    if (vertexSrc.empty() || fragmentSrc.empty()) {
        ES_LOG_ERROR("Failed to load shader files: vertex={}, fragment={}", vertexPath, fragmentPath);
        return nullptr;
    }

    return create(device, vertexSrc, fragmentSrc);
}

void Shader::bind() const {
    // Direct program bind for setup-time use (e.g. seeding a sampler uniform). Per-frame
    // rendering binds programs through GfxDevice::setPipeline, not here.
    ensureLinked();
    if (device_) device_->useProgram(program_);
}

void Shader::ensureLinked() const {
    if (linked_ || !device_) return;
    // The device runs finishLink as the program links; a program that failed to never does, and is not waited for twice.
    if (!device_->finishProgram(program_)) linked_ = true;
}

void Shader::whenLinked(std::function<void(Shader&)> fn) {
    if (!fn) return;
    if (linked_) {
        fn(*this);
        return;
    }
    afterLink_.push_back(std::move(fn));
}

void Shader::unbind() const {
    if (device_) device_->useProgram(ShaderHandle::Invalid);
}

bool Shader::compile(const std::string& vertexSrc, const std::string& fragmentSrc,
                     const std::vector<AttribBinding>& bindings,
                     std::string* outLog,
                     ShaderStageFailure* outFailedStage,
                     GfxShaderLanguage language,
                     bool deferLink) {
    language_ = language;
    linked_ = false;

    // Fail fast on a language the backend cannot compile, before any GPU call —
    // the caller gets a diagnostic instead of a backend-specific compile error.
    if (!device_->supportsShaderLanguage(language)) {
        if (outLog) *outLog = "backend does not support the shader source language";
        if (outFailedStage) *outFailedStage = ShaderStageFailure::Vertex;
        ES_LOG_ERROR("Shader::compile: backend does not support the requested shader language");
        return false;
    }

    std::vector<GfxAttribBinding> binds;
    binds.reserve(bindings.size());
    for (const auto& b : bindings) {
        binds.push_back(GfxAttribBinding{b.index, b.name});
    }

    GfxShaderStage stage = GfxShaderStage::None;
    GfxShaderSource source{language, vertexSrc.c_str(), fragmentSrc.c_str()};
    source.deferLink = deferLink && device_->supportsDeferredLink();
    program_ = device_->createProgram(source,
                                      binds.data(), static_cast<u32>(binds.size()),
                                      outLog, &stage);

    if (outFailedStage) {
        switch (stage) {
        case GfxShaderStage::Vertex:   *outFailedStage = ShaderStageFailure::Vertex; break;
        case GfxShaderStage::Fragment: *outFailedStage = ShaderStageFailure::Fragment; break;
        case GfxShaderStage::Link:     *outFailedStage = ShaderStageFailure::Link; break;
        case GfxShaderStage::None:     *outFailedStage = ShaderStageFailure::None; break;
        }
    }

    if (program_ == ShaderHandle::Invalid) {
        linked_ = true;
        return false;
    }

    if (source.deferLink) {
        // Queued, not waited for: the device finishes it (block bindings, pinned samplers) when something first needs the program.
        device_->onProgramLinked(program_, [this] { finishLink(); });
        return true;
    }
    finishLink();
    return true;
}

void Shader::finishLink() {
    linked_ = true;
    reflectActiveUniforms();

    // Link the per-frame constants block to its shared binding point, so the program
    // reads u_projection from the FrameConstants UBO with no loose uniform upload.
    // Programs without the block (custom/user shaders) simply skip this.
    u32 frameBlock = device_->getUniformBlockIndex(program_, FRAME_CONSTANTS_BLOCK);
    if (frameBlock != GFX_INVALID_UNIFORM_BLOCK) {
        device_->uniformBlockBinding(program_, frameBlock, FRAME_CONSTANTS_BINDING);
    }

    // Same for the per-material constants block (ShaderParser auto-generates it for shaders
    // authored with #pragma param); the render path binds each material's UBO here per draw.
    u32 materialBlock = device_->getUniformBlockIndex(program_, MATERIAL_CONSTANTS_BLOCK);
    if (materialBlock != GFX_INVALID_UNIFORM_BLOCK) {
        device_->uniformBlockBinding(program_, materialBlock, MATERIAL_CONSTANTS_BINDING);
    }

    // Same for the per-frame 2D light block (ShaderParser injects it for Lit-domain shaders);
    // the render path uploads + binds the shared LightConstants UBO here once per frame.
    u32 lightBlock = device_->getUniformBlockIndex(program_, LIGHT_CONSTANTS_BLOCK);
    if (lightBlock != GFX_INVALID_UNIFORM_BLOCK) {
        device_->uniformBlockBinding(program_, lightBlock, LIGHT_CONSTANTS_BINDING);
    }

    // Same for the injected frame clock (u_time).
    u32 timeBlock = device_->getUniformBlockIndex(program_, TIME_CONSTANTS_BLOCK);
    if (timeBlock != GFX_INVALID_UNIFORM_BLOCK) {
        device_->uniformBlockBinding(program_, timeBlock, TIME_CONSTANTS_BINDING);
    }

    // Same for a skinned mesh's pose, which DrawList rewrites per draw.
    u32 skinBlock = device_->getUniformBlockIndex(program_, SKIN_CONSTANTS_BLOCK);
    if (skinBlock != GFX_INVALID_UNIFORM_BLOCK) {
        device_->uniformBlockBinding(program_, skinBlock, SKIN_CONSTANTS_BINDING);
    }

    // And the per-draw shape weights, which every mesh vertex stage declares —
    // whether a draw HAS shapes is a number in the block, not a variant.
    u32 morphBlock = device_->getUniformBlockIndex(program_, MORPH_CONSTANTS_BLOCK);
    if (morphBlock != GFX_INVALID_UNIFORM_BLOCK) {
        device_->uniformBlockBinding(program_, morphBlock, MORPH_CONSTANTS_BINDING);
    }

    // And the indirect light where this draw stands, which DrawList rewrites per
    // draw. Every Lit fragment stage declares it — whether a draw STANDS in a
    // volume is a number in the block, not a variant.
    u32 probeBlock = device_->getUniformBlockIndex(program_, PROBE_CONSTANTS_BLOCK);
    if (probeBlock != GFX_INVALID_UNIFORM_BLOCK) {
        device_->uniformBlockBinding(program_, probeBlock, PROBE_CONSTANTS_BINDING);
    }

    // And where this draw's objects start in the frame's record texture, which
    // DrawList rewrites per draw for the same reason.
    u32 instanceBlock = device_->getUniformBlockIndex(program_, INSTANCE_CONSTANTS_BLOCK);
    if (instanceBlock != GFX_INVALID_UNIFORM_BLOCK) {
        device_->uniformBlockBinding(program_, instanceBlock, INSTANCE_CONSTANTS_BINDING);
    }

    const u32 planarBlock = device_->getUniformBlockIndex(program_, PLANAR_CONSTANTS_BLOCK);
    if (planarBlock != GFX_INVALID_UNIFORM_BLOCK) {
        device_->uniformBlockBinding(program_, planarBlock, PLANAR_CONSTANTS_BINDING);
    }

    // Same for the per-draw params block (rewriteLooseUniforms generates it for
    // shaders whose loose uniforms were lifted); commitParams binds the UBO.
    u32 drawParamsBlock = device_->getUniformBlockIndex(program_, DRAW_PARAMS_BLOCK);
    if (drawParamsBlock != GFX_INVALID_UNIFORM_BLOCK) {
        device_->uniformBlockBinding(program_, drawParamsBlock, DRAW_PARAMS_BINDING);
    }

    // Engine-injected samplers sit on fixed units, pinned here because GLSL ES 300
    // has no layout(binding) and a compile site that forgot one samples slot 0
    // silently. The last two are read by the VERTEX stage.
    struct PinnedSampler { const char* name; u32 unit; };
    static const PinnedSampler kPinned[] = {
        {SHADOW_MAP_SAMPLER, SHADOW_MAP_TEXTURE_UNIT},
        {ENV_MAP_SAMPLER, ENV_MAP_TEXTURE_UNIT},
        {SHADOW_2D_SAMPLER, SHADOW_2D_TEXTURE_UNIT},
        {SHAPE_2D_SAMPLER, SHAPE_2D_TEXTURE_UNIT},
        {LIGHTMAP_SAMPLER, LIGHTMAP_TEXTURE_UNIT},
        {PROBE_GRID_SAMPLER, LIGHTMAP_TEXTURE_UNIT},
        {MORPH_DELTA_SAMPLER, MORPH_DELTA_TEXTURE_UNIT},
        {INSTANCE_DATA_SAMPLER, MESH_INSTANCE_TEXTURE_UNIT},
    };
    bool pinned = false;
    for (const PinnedSampler& p : kPinned) {
        if (!hasUniform(p.name)) continue;
        if (!pinned) { bind(); pinned = true; }
        setUniform(p.name, static_cast<i32>(p.unit));
    }
    if (pinned) unbind();

    ES_LOG_DEBUG("Shader compiled successfully (program handle: {}, active uniforms: {})",
                 static_cast<u32>(program_), activeUniforms_.size());
    auto after = std::move(afterLink_);
    afterLink_.clear();
    for (auto& fn : after) fn(*this);
}

ShaderCompileOutcome Shader::createEx(GfxDevice& device,
                                      const std::string& vertexSrc,
                                      const std::string& fragmentSrc,
                                      std::initializer_list<AttribBinding> bindings,
                                      GfxShaderLanguage language,
                                      bool deferLink) {
    ShaderCompileOutcome outcome;
    auto shader = makeUnique<Shader>();
    shader->device_ = &device;
    if (!shader->compile(vertexSrc, fragmentSrc, bindings, &outcome.log, &outcome.failedStage,
                         language, deferLink)) {
        return outcome;
    }
    outcome.shader = std::move(shader);
    return outcome;
}

void Shader::reflectActiveUniforms() {
    activeUniforms_ = device_->getActiveUniforms(program_);
}

i32 Shader::cacheUniformLocation(const std::string& name, bool warnOnMiss) const {
    ensureLinked();
    auto [it, inserted] = uniformCache_.emplace(name, -1);
    if (inserted) {
        it->second = device_->getUniformLocation(program_, name.c_str());
        if (it->second < 0 && warnOnMiss) {
            ES_LOG_WARN("Shader {}: uniform '{}' not found (typo or optimized out)",
                        static_cast<u32>(program_), name);
        }
    }
    return it->second;
}

i32 Shader::getUniformLocation(const std::string& name) const {
    return cacheUniformLocation(name, /*warnOnMiss=*/true);
}

bool Shader::hasUniform(const std::string& name) const {
    // A lifted uniform is a block member: it has no location, but callers that
    // guard with hasUniform (e.g. the post-process pass loop) must still see it.
    if (drawParams_.find(name) != nullptr) return true;
    return cacheUniformLocation(name, /*warnOnMiss=*/false) >= 0;
}

void Shader::adoptDrawParams(DrawParamsLayout layout) {
    drawParams_ = std::move(layout);
    paramsShadow_.assign(drawParams_.blockSize, 0);
    paramsDirty_ = false;  // commitParams creates the UBO from the zeroed shadow
    if (drawParams_.blockSize > DRAW_PARAMS_FALLBACK_SIZE) {
        ES_LOG_WARN("Shader {}: DrawParams block ({} bytes) exceeds the frame fallback ({}); "
                    "draws that skip commitParams may be rejected",
                    static_cast<u32>(program_), drawParams_.blockSize, DRAW_PARAMS_FALLBACK_SIZE);
    }
}

void Shader::commitParams() {
    if (drawParams_.empty() || !device_) return;
    if (paramsUbo_ == BufferHandle::Invalid) {
        paramsUbo_ = device_->createBuffer(
            {GfxBufferUsage::Uniform, drawParams_.blockSize, /*dynamic=*/true}, GfxContent::retained(),
            paramsShadow_.data());
        paramsDirty_ = false;
    } else if (paramsDirty_) {
        device_->updateBuffer(paramsUbo_, 0, paramsShadow_.data(), drawParams_.blockSize);
        paramsDirty_ = false;
    }
    // Rebind even when clean: the slot is shared, another shader's commit (or
    // the frame fallback) owns it otherwise.
    device_->setUniformBuffer(DRAW_PARAMS_BINDING, paramsUbo_);
}

bool Shader::writeParam(const std::string& name, DrawParamType type, const void* src) const {
    const DrawParamSlot* slot = drawParams_.find(name);
    if (slot == nullptr) return false;
    if (slot->type != type) {
        ES_LOG_WARN("Shader {}: setUniform('{}') type mismatch with its DrawParams slot",
                    static_cast<u32>(program_), name);
        return true;  // consumed: the name has no loose location to fall back to
    }
    u8* dst = paramsShadow_.data() + slot->offset;
    if (type == DrawParamType::Mat3) {
        // std140 mat3 columns have vec4 stride; glm::mat3 is 3 packed vec3s.
        const f32* m = static_cast<const f32*>(src);
        for (u32 col = 0; col < 3; ++col) {
            std::memcpy(dst + col * 16, m + col * 3, 3 * sizeof(f32));
        }
    } else {
        u32 size = 0, align = 0;
        drawParamSizeAlign(type, size, align);
        std::memcpy(dst, src, size);
    }
    paramsDirty_ = true;
    return true;
}

void Shader::setUniform(const std::string& name, i32 value) const {
    if (writeParam(name, DrawParamType::Int, &value)) return;
    device_->setUniform1i(getUniformLocation(name), value);
}

void Shader::setUniform(const std::string& name, f32 value) const {
    if (writeParam(name, DrawParamType::Float, &value)) return;
    device_->setUniform1f(getUniformLocation(name), value);
}

void Shader::setUniform(const std::string& name, const glm::vec2& value) const {
    if (writeParam(name, DrawParamType::Vec2, glm::value_ptr(value))) return;
    device_->setUniform2f(getUniformLocation(name), value.x, value.y);
}

void Shader::setUniform(const std::string& name, const glm::vec3& value) const {
    if (writeParam(name, DrawParamType::Vec3, glm::value_ptr(value))) return;
    device_->setUniform3f(getUniformLocation(name), value.x, value.y, value.z);
}

void Shader::setUniform(const std::string& name, const glm::vec4& value) const {
    if (writeParam(name, DrawParamType::Vec4, glm::value_ptr(value))) return;
    device_->setUniform4f(getUniformLocation(name), value.x, value.y, value.z, value.w);
}

void Shader::setUniform(const std::string& name, const glm::mat3& value) const {
    if (writeParam(name, DrawParamType::Mat3, glm::value_ptr(value))) return;
    device_->setUniformMat3(getUniformLocation(name), glm::value_ptr(value));
}

void Shader::setUniform(const std::string& name, const glm::mat4& value) const {
    if (writeParam(name, DrawParamType::Mat4, glm::value_ptr(value))) return;
    device_->setUniformMat4(getUniformLocation(name), glm::value_ptr(value));
}

void Shader::setUniform(i32 location, i32 value) const {
    device_->setUniform1i(location, value);
}

void Shader::setUniform(i32 location, f32 value) const {
    device_->setUniform1f(location, value);
}

void Shader::setUniform(i32 location, const glm::vec2& value) const {
    device_->setUniform2f(location, value.x, value.y);
}

void Shader::setUniform(i32 location, const glm::vec3& value) const {
    device_->setUniform3f(location, value.x, value.y, value.z);
}

void Shader::setUniform(i32 location, const glm::vec4& value) const {
    device_->setUniform4f(location, value.x, value.y, value.z, value.w);
}

void Shader::setUniform(i32 location, const glm::mat3& value) const {
    device_->setUniformMat3(location, glm::value_ptr(value));
}

void Shader::setUniform(i32 location, const glm::mat4& value) const {
    device_->setUniformMat4(location, glm::value_ptr(value));
}

i32 Shader::getAttribLocation(const std::string& name) const {
    ensureLinked();
    auto [it, inserted] = attribCache_.emplace(name, -1);
    if (inserted) {
        it->second = device_->getAttribLocation(program_, name.c_str());
    }
    return it->second;
}

}  // namespace esengine