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.

11.8 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    Texture.hpp
 * @brief   GPU texture abstraction for 2D images
 * @details Provides cross-platform texture handling for OpenGL ES/WebGL
 *          including creation, binding, and pixel data management.
 *
 * @author  ESEngine Team
 * @date    2026
 *
 * @copyright Copyright (c) 2026 ESEngine Team
 *            Licensed under the Apache License, Version 2.0.
 */
#pragma once

// =============================================================================
// Includes
// =============================================================================

// Project includes
#include "../../core/Types.hpp"
#include "./GfxContent.hpp"
#include "./GfxEnums.hpp"

// Standard library
#include <span>
#include <string>
#include <vector>

namespace esengine {

class GfxDevice;

// =============================================================================
// Texture Enums
// =============================================================================

// TextureFilter / TextureWrap live in GfxEnums.hpp with the other backend-agnostic
// sampling enums; TextureFormat below is this wrapper's user-facing format set.

/**
 * @brief Texture pixel format
 */
enum class TextureFormat {
    None = 0,
    RGB8,     ///< 3 channels, 8 bits each (24 bpp)
    RGBA8,    ///< 4 channels, 8 bits each (32 bpp)
    SRGB8A8,  ///< sRGB-encoded RGBA8: hardware-linearized on sample (32 bpp)
    RGBA16F,  ///< Half-float HDR (64 bpp); render use gated on supportsFloatTargets
    RGBA32F,  ///< Full-float storage (128 bpp); fetched by texel, never filtered
    Depth24   ///< Depth buffer format (24 bits)
};

// =============================================================================
// Texture Specification
// =============================================================================

/**
 * @brief Texture creation parameters
 *
 * @details Specifies all properties for texture creation including
 *          dimensions, format, filtering, and wrapping.
 *
 * @code
 * TextureSpecification spec;
 * spec.width = 256;
 * spec.height = 256;
 * spec.format = TextureFormat::RGBA8;
 * spec.minFilter = TextureFilter::Nearest;
 * auto texture = Texture::create(spec);
 * @endcode
 */
struct TextureSpecification {
    /** @brief Texture width in pixels */
    u32 width = 1;
    /** @brief Texture height in pixels */
    u32 height = 1;
    /** @brief Pixel format */
    TextureFormat format = TextureFormat::RGBA8;
    /** @brief Minification filter */
    TextureFilter minFilter = TextureFilter::Linear;
    /** @brief Magnification filter */
    TextureFilter magFilter = TextureFilter::Linear;
    /** @brief Horizontal wrap mode */
    TextureWrap wrapS = TextureWrap::Repeat;
    /** @brief Vertical wrap mode */
    TextureWrap wrapT = TextureWrap::Repeat;
    /** @brief Generate mipmaps automatically */
    bool generateMips = true;
    /** @brief Above 1, a 2D texture array of this many layers (see TextureDesc::layers) */
    u32 layers = 1;
};

// =============================================================================
// Texture Class
// =============================================================================

/**
 * @brief 2D texture for GPU rendering
 *
 * @details Encapsulates an OpenGL/WebGL texture object. Supports
 *          creation from pixel data, files, or empty specifications.
 *
 * @code
 * // Create from pixel data
 * std::vector<u8> pixels = {...}; // RGBA data
 * auto texture = Texture::create(64, 64, std::span(pixels));
 *
 * // Bind for rendering
 * texture->bind(0); // Bind to texture unit 0
 * @endcode
 */
class Texture {
public:
    Texture() = default;
    virtual ~Texture();

    // Non-copyable, movable
    Texture(const Texture&) = delete;
    Texture& operator=(const Texture&) = delete;
    Texture(Texture&& other) noexcept;
    Texture& operator=(Texture&& other) noexcept;

    // =========================================================================
    // Creation
    // =========================================================================

    /**
     * @brief Creates an empty texture from specification
     * @param spec Texture parameters
     * @return Unique pointer to the texture
     *
     * @details Creates a texture with uninitialized pixel data.
     *          Use setData() to upload pixels later.
     */
    static Unique<Texture> create(GfxDevice& device, GfxContent content, const TextureSpecification& spec);

    /**
     * @brief Creates a texture from a span of pixel data
     * @param width Texture width in pixels
     * @param height Texture height in pixels
     * @param pixels Pixel data (size must match width*height*channels)
     * @param format Pixel format (default RGBA8)
     * @return Unique pointer to the texture
     */
    static Unique<Texture> create(GfxDevice& device, GfxContent content, u32 width, u32 height,
                                   std::span<const u8> pixels,
                                   TextureFormat format = TextureFormat::RGBA8,
                                   bool flipY = false);

    /**
     * @brief Creates a texture from pixel vector
     * @param width Texture width in pixels
     * @param height Texture height in pixels
     * @param pixels Pixel data (size must match width*height*channels)
     * @param format Pixel format (default RGBA8)
     * @param flipY Flip vertically on upload (for web image data)
     * @return Unique pointer to the texture
     */
    static Unique<Texture> create(GfxDevice& device, GfxContent content, u32 width, u32 height,
                                   const std::vector<u8>& pixels,
                                   TextureFormat format = TextureFormat::RGBA8,
                                   bool flipY = false);

    /**
     * @brief Names a texture the device already holds for another owner (a render
     *        target's colour plane), without taking it over.
     */
    static Unique<Texture> borrow(GfxDevice& device, TextureHandle texture, u32 width, u32 height);

    /**
     * @brief Creates a 2D texture array from `spec.layers` layers of `spec.width` x `spec.height`.
     * @param pixels The layers back to back, layer 0 first, rows bottom-up as the engine samples them;
     *        `spec.width * spec.height * bpp * spec.layers` bytes. Its contents are fixed: setData is refused.
     */
    static Unique<Texture> createArray(GfxDevice& device, GfxContent content, const TextureSpecification& spec,
                                       const void* pixels);

    /**
     * @brief Takes @p from's pixels behind this texture's handle; @p from is empty afterwards.
     * @details How owed content is paid: the provider loads it the ordinary way and
     *          hands the result over, so nothing that names this texture changes.
     */
    bool adoptContent(Texture& from);

    // =========================================================================
    // Operations
    // =========================================================================

    /**
     * @brief Binds the texture to a texture unit
     * @param slot Texture unit index (0-7 typical for WebGL)
     */
    void bind(u32 slot = 0) const;

    /** @brief Unbinds the texture */
    void unbind() const;

    /**
     * @brief Updates texture pixel data from span
     * @param pixels New pixel data
     */
    void setData(std::span<const u8> pixels);

    /**
     * @brief Updates texture pixel data from vector
     * @param pixels New pixel data
     */
    void setData(const std::vector<u8>& pixels);

    /**
     * @brief Uploads pixel data to a sub-rectangle of the texture.
     *
     * Lets the dynamic glyph atlas pack glyphs one-by-one
     * without re-uploading the whole atlas. The sub-rect must lie fully inside
     * the texture and `data` must be tightly packed in this texture's format.
     *
     * @param xoffset,yoffset top-left of the sub-rect, in texels
     * @param width,height    sub-rect size, in texels
     * @param data,sizeBytes  pixel buffer matching the texture's format
     */
    void updateSubRegion(u32 xoffset, u32 yoffset, u32 width, u32 height,
                         const void* data, u32 sizeBytes, bool flipY = false);

    // =========================================================================
    // Properties
    // =========================================================================

    /** @brief Gets the device texture handle */
    TextureHandle handle() const { return handle_; }

    /** @brief Gets the texture handle's raw value, for command payloads and the WASM boundary */
    u32 getId() const { return static_cast<u32>(handle_); }

    /** @brief Gets the texture width in pixels */
    u32 getWidth() const { return width_; }

    /** @brief Gets the texture height in pixels */
    u32 getHeight() const { return height_; }

    /** @brief Gets the pixel format */
    TextureFormat getFormat() const { return format_; }

    /**
     * @brief Compares textures by GPU ID
     * @param other Texture to compare with
     * @return True if same GPU texture
     */
    bool operator==(const Texture& other) const {
        return handle_ == other.handle_;
    }

    // =========================================================================
    // Raw API for internal use only
    // =========================================================================

    /**
     * @brief Creates a texture from raw pixel pointer (internal use)
     * @param width Texture width in pixels
     * @param height Texture height in pixels
     * @param data Pointer to pixel data
     * @param format Pixel format (default RGBA8)
     * @return Unique pointer to the texture
     */
    static Unique<Texture> createRaw(GfxDevice& device, GfxContent content, u32 width, u32 height,
                                      const void* data,
                                      TextureFormat format = TextureFormat::RGBA8,
                                      bool flipY = false);

    /**
     * @brief Creates a block-compressed texture (KTX2 → ETC2/ASTC/BC), uploading
     *        the pre-compressed blocks in one shot. No setDataRaw afterward —
     *        compressed data is immutable here.
     * @param data Compressed block data for mip level 0.
     */
    static Unique<Texture> createCompressed(GfxDevice& device, GfxContent content, u32 width, u32 height,
                                            GfxCompressedFormat format, std::span<const u8> data,
                                            u32 mipLevels = 1);

    /**
     * @brief Hands the device a texture the host made with its own API; the device owns it from here.
     * @param glTextureId The host's id for it (a WebGL texture registered with the GL layer)
     */
    static Unique<Texture> createFromExternalId(GfxDevice& device, GfxContent content, u32 glTextureId,
                                                 u32 width, u32 height,
                                                 TextureFormat format = TextureFormat::RGBA8);

    /**
     * @brief Updates texture pixel data from raw pointer (internal use)
     * @param data Pointer to pixel data
     * @param sizeBytes Size of data in bytes
     */
    void setDataRaw(const void* data, u32 sizeBytes, bool flipY = false);

private:
    /**
     * @brief Initializes the texture on GPU
     * @param spec Texture parameters
     * @param pixels Optional initial pixel data
     * @param flipY Vertical flip on the initial upload
     * @return True on success
     */
    bool initialize(const TextureSpecification& spec, GfxContent content, const void* pixels, bool flipY);

    GfxDevice* device_ = nullptr;  ///< Set by the create* factories; all GL goes through it.
    TextureHandle handle_ = TextureHandle::Invalid;
    u32 width_ = 0;
    u32 height_ = 0;
    TextureFormat format_ = TextureFormat::None;
    /// False for a borrowed texture, whose owner deletes it.
    bool owns_ = true;
};

}  // namespace esengine