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.

10.3 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    Texture.cpp
 * @brief   Texture implementation (device-backed)
 * @details Thin RAII handle over a GPU texture. All GL is delegated to GfxDevice;
 *          this file contains no GL calls and no platform ifdefs — textures work
 *          on every platform the device backs (web and native alike).
 *
 * @author  ESEngine Team
 * @date    2026
 *
 * @copyright Copyright (c) 2026 ESEngine Team
 *            Licensed under the Apache License, Version 2.0.
 */

#include "./Texture.hpp"
#include "./GfxDevice.hpp"
#include "../../core/Log.hpp"

#include <span>

namespace esengine {

namespace {

GfxPixelFormat toGfxPixelFormat(TextureFormat format) {
    switch (format) {
    case TextureFormat::RGB8:    return GfxPixelFormat::RGB8;
    case TextureFormat::RGBA8:   return GfxPixelFormat::RGBA8;
    case TextureFormat::SRGB8A8: return GfxPixelFormat::SRGB8_ALPHA8;
    case TextureFormat::RGBA16F: return GfxPixelFormat::RGBA16F;
    case TextureFormat::RGBA32F: return GfxPixelFormat::RGBA32F;
    case TextureFormat::Depth24: return GfxPixelFormat::DepthComponent24;
    default:                     return GfxPixelFormat::RGBA8;
    }
}

u32 bytesPerPixel(TextureFormat format) {
    return gfxBytesPerPixel(toGfxPixelFormat(format));
}

}  // namespace

Texture::~Texture() {
    if (handle_ != TextureHandle::Invalid && device_ && owns_) {
        device_->deleteTexture(handle_);
    }
}

Texture::Texture(Texture&& other) noexcept
    : device_(other.device_)
    , handle_(other.handle_)
    , width_(other.width_)
    , height_(other.height_)
    , format_(other.format_)
    , owns_(other.owns_) {
    other.handle_ = TextureHandle::Invalid;
    other.width_ = 0;
    other.height_ = 0;
    other.format_ = TextureFormat::None;
}

Texture& Texture::operator=(Texture&& other) noexcept {
    if (this != &other) {
        if (handle_ != TextureHandle::Invalid && device_ && owns_) {
            device_->deleteTexture(handle_);
        }
        device_ = other.device_;
        handle_ = other.handle_;
        width_ = other.width_;
        height_ = other.height_;
        format_ = other.format_;
        owns_ = other.owns_;
        other.handle_ = TextureHandle::Invalid;
        other.width_ = 0;
        other.height_ = 0;
        other.format_ = TextureFormat::None;
    }
    return *this;
}

Unique<Texture> Texture::create(GfxDevice& device, GfxContent content, const TextureSpecification& spec) {
    auto texture = makeUnique<Texture>();
    texture->device_ = &device;
    if (!texture->initialize(spec, content, nullptr, false)) {
        return nullptr;
    }
    return texture;
}

Unique<Texture> Texture::createArray(GfxDevice& device, GfxContent content, const TextureSpecification& spec,
                                      const void* pixels) {
    auto texture = makeUnique<Texture>();
    texture->device_ = &device;
    if (!texture->initialize(spec, content, pixels, false)) {
        return nullptr;
    }
    return texture;
}

Unique<Texture> Texture::create(GfxDevice& device, GfxContent content, u32 width, u32 height,
                                 std::span<const u8> pixels, TextureFormat format, bool flipY) {
    [[maybe_unused]] u32 expectedSize = width * height * bytesPerPixel(format);
    ES_ASSERT(pixels.size() == expectedSize, "Pixel data size mismatch");
    return createRaw(device, content, width, height, pixels.data(), format, flipY);
}

Unique<Texture> Texture::create(GfxDevice& device, GfxContent content, u32 width, u32 height,
                                 const std::vector<u8>& pixels, TextureFormat format, bool flipY) {
    return create(device, content, width, height, std::span<const u8>(pixels), format, flipY);
}

Unique<Texture> Texture::createRaw(GfxDevice& device, GfxContent content, u32 width, u32 height,
                                    const void* data, TextureFormat format, bool flipY) {
    TextureSpecification spec;
    spec.width = width;
    spec.height = height;
    spec.format = format;
    spec.wrapS = TextureWrap::ClampToEdge;
    spec.wrapT = TextureWrap::ClampToEdge;
    spec.generateMips = false;

    auto texture = makeUnique<Texture>();
    texture->device_ = &device;
    if (!texture->initialize(spec, content, data, flipY)) {
        return nullptr;
    }
    return texture;
}

Unique<Texture> Texture::createCompressed(GfxDevice& device, GfxContent content, u32 width, u32 height,
                                          GfxCompressedFormat format, std::span<const u8> data,
                                          u32 mipLevels) {
    auto texture = makeUnique<Texture>();
    texture->device_ = &device;
    texture->width_ = width;
    texture->height_ = height;
    texture->format_ = TextureFormat::RGBA8;   // sampled as colour; the GPU format is the compressed one

    TextureDesc desc;
    desc.width = width;
    desc.height = height;
    desc.minFilter = TextureFilter::Linear;
    desc.magFilter = TextureFilter::Linear;
    desc.wrapS = TextureWrap::ClampToEdge;
    desc.wrapT = TextureWrap::ClampToEdge;
    desc.mipmaps = mipLevels > 1;

    texture->handle_ = device.createCompressedTexture(desc, content, format, data.data(),
                                                      static_cast<u32>(data.size()), mipLevels);
    if (texture->handle_ == TextureHandle::Invalid) {
        ES_LOG_ERROR("Texture::createCompressed: failed for {}x{}", width, height);
        return nullptr;
    }
    return texture;
}

Unique<Texture> Texture::createFromExternalId(GfxDevice& device, GfxContent content, u32 glTextureId,
                                              u32 width, u32 height, TextureFormat format) {
    TextureDesc desc;
    desc.width = width;
    desc.height = height;
    desc.format = toGfxPixelFormat(format);

    auto texture = makeUnique<Texture>();
    texture->device_ = &device;
    texture->handle_ = device.importExternalTexture(glTextureId, desc, content);
    texture->width_ = width;
    texture->height_ = height;
    texture->format_ = format;
    return texture;
}

Unique<Texture> Texture::borrow(GfxDevice& device, TextureHandle handle, u32 width, u32 height) {
    if (!device.textureDesc(handle)) return nullptr;
    auto texture = makeUnique<Texture>();
    texture->device_ = &device;
    texture->handle_ = handle;
    texture->width_ = width;
    texture->height_ = height;
    texture->format_ = TextureFormat::RGBA8;
    texture->owns_ = false;
    return texture;
}

bool Texture::adoptContent(Texture& from) {
    if (!device_ || !owns_ || !from.owns_ || !device_->adoptTextureContent(handle_, from.handle_)) {
        return false;
    }
    width_ = from.width_;
    height_ = from.height_;
    format_ = from.format_;
    from.handle_ = TextureHandle::Invalid;
    return true;
}

bool Texture::initialize(const TextureSpecification& spec, GfxContent content, const void* pixels, bool flipY) {
    width_ = spec.width;
    height_ = spec.height;
    format_ = spec.format;

    TextureDesc desc;
    desc.width = spec.width;
    desc.height = spec.height;
    desc.format = toGfxPixelFormat(spec.format);
    desc.minFilter = spec.minFilter;
    desc.magFilter = spec.magFilter;
    desc.wrapS = spec.wrapS;
    desc.wrapT = spec.wrapT;
    desc.mipmaps = spec.generateMips;
    desc.flipY = flipY;
    desc.layers = spec.layers ? spec.layers : 1;

    handle_ = device_->createTexture(desc, content, pixels);
    if (handle_ == TextureHandle::Invalid) {
        // Out of memory or a lost context: surface the failure instead of
        // returning a "valid" texture wrapping the null handle (renders as black).
        ES_LOG_ERROR("Texture::initialize: createTexture failed for {}x{}", width_, height_);
        return false;
    }

    ES_LOG_DEBUG("Created texture {}x{} (handle: {})", width_, height_, static_cast<u32>(handle_));
    return true;
}

void Texture::bind(u32 slot) const {
    if (device_) device_->bindTexture(slot, handle_);
}

void Texture::unbind() const {
    if (device_) device_->bindTexture(0, TextureHandle::Invalid);
}

void Texture::setData(std::span<const u8> pixels) {
    [[maybe_unused]] u32 expectedSize = width_ * height_ * bytesPerPixel(format_);
    ES_ASSERT(pixels.size() == expectedSize, "Pixel data size mismatch");
    setDataRaw(pixels.data(), static_cast<u32>(pixels.size()));
}

void Texture::setData(const std::vector<u8>& pixels) {
    setData(std::span<const u8>(pixels));
}

void Texture::setDataRaw(const void* data, u32 sizeBytes, bool flipY) {
    // Always-on size guard (independent of ES_ASSERT, which is stripped in release).
    // updateTexture below reads width_*height_*bpp bytes from `data`; a smaller
    // buffer would cause an out-of-bounds read of WASM linear memory.
    u32 expectedSize = width_ * height_ * bytesPerPixel(format_);
    if (sizeBytes < expectedSize) {
        ES_LOG_ERROR("Texture::setDataRaw: data size {} < required {} for {}x{}; skipping upload to avoid OOB read",
                     sizeBytes, expectedSize, width_, height_);
        return;
    }

    device_->updateTexture(handle_, 0, 0, width_, height_, data, flipY);
}

void Texture::updateSubRegion(u32 xoffset, u32 yoffset, u32 width, u32 height,
                              const void* data, u32 sizeBytes, bool flipY) {
    // The sub-rect must lie fully inside the texture; otherwise the upload
    // writes outside the allocated texture storage (GL error / undefined).
    if (width > width_ || xoffset > width_ - width ||
        height > height_ || yoffset > height_ - height) {
        ES_LOG_ERROR("Texture::updateSubRegion: rect {}x{} at ({},{}) exceeds texture {}x{}; skipping",
                     width, height, xoffset, yoffset, width_, height_);
        return;
    }
    // Always-on size guard (ES_ASSERT is stripped in release): updateTexture
    // reads width*height*bpp bytes from `data`; a smaller buffer would OOB-read
    // WASM linear memory.
    u32 expectedSize = width * height * bytesPerPixel(format_);
    if (sizeBytes < expectedSize) {
        ES_LOG_ERROR("Texture::updateSubRegion: data size {} < required {} for {}x{}; skipping to avoid OOB read",
                     sizeBytes, expectedSize, width, height);
        return;
    }

    device_->updateTexture(handle_, static_cast<i32>(xoffset), static_cast<i32>(yoffset),
                           width, height, data, flipY);
}

}  // namespace esengine