TextureLoom.hpp

Go to the documentation of this file.

#pragma once
 
#include <vulkan/vulkan.hpp>
 
#include "GraphicsUtils.hpp"
 
#include "MayaFlux/Kakshya/NDData/NDData.hpp"
 
namespace MayaFlux::Core {
class VulkanBackend;
class BackendResourceManager;
}
 
namespace MayaFlux::Buffers {
class VKBuffer;
}
 
namespace MayaFlux::Portal::Graphics {
 
/** @brief Immutable properties that determine whether an image can be reused. */
struct ImageKey {
    enum class Kind : uint8_t {
        SAMPLED_2D,
        SAMPLED_ARRAY,
        STORAGE_2D
    };
 
    uint32_t width {};
    uint32_t height {};
    uint32_t layers { 1 };
    uint32_t mip_levels { 1 };
    ImageFormat format {};
    Kind kind { Kind::SAMPLED_2D };
 
    [[nodiscard]] bool operator==(const ImageKey&) const = default;
};
 
/** @brief Hash image allocation properties for keyed reuse. */
struct MAYAFLUX_API ImageKeyHash {
    [[nodiscard]] size_t operator()(const ImageKey& key) const noexcept;
};
 
/** @brief Image retained by the producing owner. */
struct ImageCacheEntry {
    ImageKey key;
    std::shared_ptr<Core::VKImage> image;
};
 
/**
 * @brief One layer to layer copy that scales and converts format.
 *
 * Whole images by default, stretched to fit. Rectangles are in pixels and a zero
 * extent runs to the image edge. A smaller @c dst rectangle letterboxes, a smaller
 * @c src rectangle crops, and the flips mirror the destination.
 */
struct LayerBlit {
    uint32_t src_layer {};
    uint32_t dst_layer {};
    vk::Rect2D src {};
    vk::Rect2D dst {};
    FilterMode filter { FilterMode::LINEAR };
    bool flip_x {};
    bool flip_y {};
};
 
/**
 * @class TextureLoom
 * @brief Portal-level texture creation and management
 *
 * TextureLoom is the primary Portal::Graphics class for creating and
 * managing GPU textures. It bridges between user-friendly Portal API and
 * backend VKImage resources via BufferService registry.
 *
 * Key Responsibilities:
 * - Create textures (2D, 3D, cubemaps, render targets)
 * - Load textures from files (delegates to IO namespace)
 * - Manage sampler objects (filtering, addressing)
 * - Track texture lifecycle for cleanup
 * - Provide convenient format conversions
 *
 * Design Philosophy:
 * - Manages creation, NOT rendering (that's Pipeline/RenderPass)
 * - Returns VKImage directly (no wrapping yet)
 * - Simple, focused API (file loading deferred to IO)
 * - Integrates with BufferService for backend independence
 *
 * Usage:
 *   auto& mgr = Portal::Graphics::TextureLoom::instance();
 *
 *   // Create basic texture
 *   auto texture = mgr.create_2d(512, 512, ImageFormat::RGBA8);
 *
 *   // Create with data
 *   std::vector<uint8_t> pixels = {...};
 *   auto texture = mgr.create_2d(512, 512, ImageFormat::RGBA8, pixels.data());
 *
 *   // Create render target
 *   auto target = mgr.create_render_target(1920, 1080);
 *
 *   // Get sampler
 *   SamplerConfig config;
 *   config.mag_filter = FilterMode::LINEAR;
 *   auto sampler = mgr.get_or_create_sampler(config);
 */
class MAYAFLUX_API TextureLoom {
public:
    static TextureLoom& instance()
    {
        static TextureLoom manager;
        return manager;
    }
 
    // Non-copyable, movable
    TextureLoom(const TextureLoom&) = delete;
    TextureLoom& operator=(const TextureLoom&) = delete;
    TextureLoom(TextureLoom&&) noexcept = default;
    TextureLoom& operator=(TextureLoom&&) noexcept = default;
 
    /**
     * @brief Initialize texture manager
     * @param backend Shared pointer to VulkanBackend
     * @return True if initialization succeeded
     *
     * Queries BufferService from BackendRegistry.
     * Must be called before creating any textures.
     */
    bool initialize(const std::shared_ptr<Core::VulkanBackend>& backend);
 
    /**
     * @brief Shutdown and cleanup all textures
     *
     * Destroys all managed textures and samplers.
     * Safe to call multiple times.
     */
    void shutdown();
 
    /**
     * @brief Check if manager is initialized
     */
    [[nodiscard]] bool is_initialized() const { return m_backend != nullptr; }
 
    //==========================================================================
    // Texture Creation
    //==========================================================================
 
    /**
     * @brief Create a 2D texture
     * @param width Width in pixels
     * @param height Height in pixels
     * @param format Image format
     * @param data Optional initial pixel data (nullptr = empty)
     * @param mip_levels Number of mipmap levels (1 = no mipmaps)
     * @return Initialized VKImage ready for use
     *
     * Creates device-local texture optimized for shader sampling.
     * If data provided, uploads immediately and transitions to shader read layout.
     */
    std::shared_ptr<Core::VKImage> create_2d(
        uint32_t width,
        uint32_t height,
        ImageFormat format = ImageFormat::RGBA8,
        const void* data = nullptr,
        uint32_t mip_levels = 1);
 
    /**
     * @brief Allocate a 2D texture without uploading data or transitioning
     *        its layout - left VK_IMAGE_LAYOUT_UNDEFINED.
     *
     * Every create_2d*() overload above performs (and blocks on) an initial
     * layout transition or upload of its own, even when called with no
     * data - create_2d(w, h, format, nullptr) still does a blocking
     * transition to eShaderReadOnlyOptimal before returning. Use this
     * instead when the caller is about to record its own upload right
     * after (e.g. upload_data(image, data, size, staging, true) with
     * deferred=true), so the whole undefined -> transfer-dst -> copy ->
     * shader-read sequence is recorded once into a deferred command batch instead of
     * paying for a separate blocking queue.waitIdle() first.
     *
     * @param width      Width in pixels.
     * @param height     Height in pixels.
     * @param format     Image format (default RGBA8).
     * @param mip_levels Number of mipmap levels (1 = no mipmaps).
     * @return           VKImage with device memory allocated, still in
     *                   VK_IMAGE_LAYOUT_UNDEFINED, or nullptr on failure.
     *                   The caller owns transitioning it before use.
     */
    [[nodiscard]] std::shared_ptr<Core::VKImage> create_2d_uninitialized(
        uint32_t width,
        uint32_t height,
        ImageFormat format = ImageFormat::RGBA8,
        uint32_t mip_levels = 1);
 
    /**
     * @brief Create a 3D texture (volumetric)
     * @param width Width in pixels
     * @param height Height in pixels
     * @param depth Depth in pixels
     * @param format Image format
     * @param data Optional initial pixel data
     * @return Initialized VKImage
     */
    std::shared_ptr<Core::VKImage> create_3d(
        uint32_t width,
        uint32_t height,
        uint32_t depth,
        ImageFormat format = ImageFormat::RGBA8,
        const void* data = nullptr);
 
    /**
     * @brief Create a cubemap texture
     * @param size Cubemap face size in pixels (square)
     * @param format Image format
     * @param data Optional face data (6 faces in order: +X,-X,+Y,-Y,+Z,-Z)
     * @return Initialized VKImage configured as cubemap
     */
    std::shared_ptr<Core::VKImage> create_cubemap(
        uint32_t size,
        ImageFormat format = ImageFormat::RGBA8,
        const void* data = nullptr);
 
    /**
     * @brief Create a 2D texture array.
     *
     * All layers share the same width, height, and format. The image view
     * type is VK_IMAGE_VIEW_TYPE_2D_ARRAY, making it bindable as
     * sampler2DArray in GLSL.
     *
     * @param width   Width in pixels per layer.
     * @param height  Height in pixels per layer.
     * @param layers  Number of array layers. Must be > 0.
     * @param format  Image format (default RGBA8).
     * @param data    Optional pixel data for all layers concatenated in order
     *                (layer 0 first). Must be exactly
     *                width * height * bpp(format) * layers bytes when non-null.
     *                Pass nullptr to allocate without uploading; the image is
     *                transitioned to eShaderReadOnlyOptimal.
     * @return Initialised VKImage with array_layers == layers, or nullptr on failure.
     */
    std::shared_ptr<Core::VKImage> create_2d_array(
        uint32_t width,
        uint32_t height,
        uint32_t layers,
        ImageFormat format = ImageFormat::RGBA8,
        const void* data = nullptr);
 
    /**
     * @brief Create a render target (color attachment)
     * @param width Width in pixels
     * @param height Height in pixels
     * @param format Image format (default RGBA8)
     * @return Initialized VKImage configured for rendering
     *
     * Creates image suitable for use as framebuffer color attachment.
     * Can also be sampled in shaders after rendering.
     */
    std::shared_ptr<Core::VKImage> create_render_target(
        uint32_t width,
        uint32_t height,
        ImageFormat format = ImageFormat::RGBA8);
 
    /**
     * @brief Create a depth buffer
     * @param width Width in pixels
     * @param height Height in pixels
     * @param with_stencil Whether to include stencil component
     * @return Initialized VKImage configured as depth/stencil attachment
     */
    std::shared_ptr<Core::VKImage> create_depth_buffer(
        uint32_t width,
        uint32_t height,
        bool with_stencil = false);
 
    /**
     * @brief Create a storage image (compute shader read/write)
     * @param width Width in pixels
     * @param height Height in pixels
     * @param format Image format
     * @return Initialized VKImage configured for compute storage
     */
    std::shared_ptr<Core::VKImage> create_storage_image(
        uint32_t width,
        uint32_t height,
        ImageFormat format = ImageFormat::RGBA8);
 
    /**
     * @brief Reuse a matching image in an owner-held entry or create it once.
     * @param entry Cache entry retained by the image producer.
     * @param key Immutable image allocation properties.
     * @return Matching image, or nullptr on failure.
     */
    [[nodiscard]] std::shared_ptr<Core::VKImage> acquire_cached_image(
        ImageCacheEntry& entry, const ImageKey& key);
 
    /**
     * @brief Refresh a sampled image in an owner-held cache entry.
     * @param entry Cache entry retained by the image producer.
     * @param key Sampled image allocation properties.
     * @param pixels Complete pixel bytes for every layer.
     * @param staging Optional caller staging buffer. Without one, upload_data
     *                uses its existing transient staging path.
     * @return Refreshed image, or nullptr when validation or creation fails.
     */
    [[nodiscard]] std::shared_ptr<Core::VKImage> refresh_cached_image(
        ImageCacheEntry& entry,
        const ImageKey& key,
        std::span<const uint8_t> pixels,
        const std::shared_ptr<Buffers::VKBuffer>& staging = {});
 
    /**
     * @brief Create a 2D texture from a DataVariant in one shot.
     * @param variant  Source data. Conversion and validation delegated to
     *                 Kakshya::as_texture_access(): vec3 is promoted to vec4
     *                 with W=0 (warned); complex<double> and mat4 are rejected.
     * @param width    Texture width in texels.
     * @param height   Texture height in texels.
     * @param format   Target image format (default: RGBA32F).
     * @return         Initialised VKImage in shader-read layout, or nullptr on failure.
     *
     * Validates byte count against width * height * bpp(format) before upload.
     * Throws std::invalid_argument on mismatch.
     */
    [[nodiscard]] std::shared_ptr<Core::VKImage> create_2d(
        const Kakshya::DataVariant& variant,
        uint32_t width,
        uint32_t height,
        ImageFormat format = ImageFormat::RGBA32F);
 
    //==========================================================================
    // Data Upload/Download
    //==========================================================================
 
    /**
     * @brief Upload pixel data to an existing texture
     * @param image Target image
     * @param data Pixel data pointer
     * @param size Data size in bytes
     *
     * Handles staging buffer, layout transitions, and cleanup.
     * Blocks until upload completes.
     */
    void upload_data(
        const std::shared_ptr<Core::VKImage>& image,
        const void* data,
        size_t size);
 
    /**
     * @brief Upload pixel data reusing a caller-supplied persistent staging buffer.
     *        Identical to upload_data() but skips the per-call VkBuffer allocation,
     *        eliminating the Vulkan object churn that causes VK_ERROR_DEVICE_LOST
     *        under sustained per-frame texture updates (e.g. video playback).
     * @param image   Target VKImage (must already be initialised).
     * @param data    Pixel data pointer (at least @p size bytes).
     * @param size    Byte count — must match the image footprint.
     * @param staging Host-visible staging VKBuffer from create_streaming_staging().
     * @param deferred. If true, record_deferred_commands will be used by the backend.
     */
    void upload_data(
        const std::shared_ptr<Core::VKImage>& image,
        const void* data,
        size_t size,
        const std::shared_ptr<Buffers::VKBuffer>& staging, bool deferred = false);
 
    /**
     * @brief Download pixel data from a VKImage, reusing a caller-supplied
     *        persistent staging buffer.
     *
     * When @p staging is null, falls through to the per-call blocking path.
     * When @p staging is supplied, submits under a fence (fenced, not waitIdle)
     * so other GPU work proceeds concurrently during the wait.
     * When @p deferred is true, records commands for deferred submission;
     * the caller is responsible for flushing. Ignored when staging is null.
     *
     * The staging buffer must be host-visible and at least @p size bytes.
     * Allocate once with Buffers::create_image_staging_buffer(size).
     *
     * @param image    Source VKImage. Must be initialised.
     * @param data     Destination host pointer, at least @p size bytes.
     * @param size     Byte count to read.
     * @param staging  Persistent staging buffer, or nullptr for per-call path.
     * @param deferred When true and staging is supplied, records for deferred
     *                 submission rather than immediate fenced execution.
     * @param restore_layout Layout the image is left in. The default matches the
     *                 layout the download previously always restored.
     * @param restore_stage  Pipeline stage that consumes the image after restore.
     */
    void download_data(
        const std::shared_ptr<Core::VKImage>& image,
        void* data,
        size_t size,
        const std::shared_ptr<Buffers::VKBuffer>& staging,
        bool deferred = false,
        vk::ImageLayout restore_layout = vk::ImageLayout::eShaderReadOnlyOptimal,
        vk::PipelineStageFlags restore_stage = vk::PipelineStageFlagBits::eFragmentShader);
 
    /**
     * @brief Download the base level of an image as typed pixels.
     *
     * Blocking. The element type of the returned storage follows the format:
     * one byte per channel gives uint8, two gives uint16, four gives float.
     *
     * @param image          Source image. Must satisfy readable_format().
     * @param staging        Persistent host-visible staging buffer of at least
     *                       the base level's byte size, or nullptr for a per-call one.
     * @param restore_layout Layout the image is left in.
     * @param restore_stage  Pipeline stage that consumes the image after restore.
     * @return The pixels with width, height, channels and format set, or
     *         nullopt, with an error logged, if the image is not readable or
     *         the loom is not initialised.
     */
    [[nodiscard]] std::optional<Kakshya::ImageData> download_image(
        const std::shared_ptr<Core::VKImage>& image,
        const std::shared_ptr<Buffers::VKBuffer>& staging = nullptr,
        vk::ImageLayout restore_layout = vk::ImageLayout::eShaderReadOnlyOptimal,
        vk::PipelineStageFlags restore_stage = vk::PipelineStageFlagBits::eFragmentShader);
 
    /**
     * @brief Transition a VKImage to a new Vulkan layout via an immediate submission.
     * @param image       Image to transition. Must be initialised.
     * @param old_layout  Current layout of the image.
     * @param new_layout  Target layout.
     * @param mip_levels  Number of mip levels covered by the transition.
     * @param array_layers Number of array layers covered by the transition.
     * @param aspect_mask Image aspect flags (colour, depth, stencil).
     *
     * Delegates to BackendResourceManager and updates the image's tracked layout.
     * Use before binding an image to a compute shader descriptor or before
     * upload/download operations that require a specific layout.
     */
    void transition_layout(
        const std::shared_ptr<Core::VKImage>& image,
        vk::ImageLayout old_layout,
        vk::ImageLayout new_layout,
        uint32_t mip_levels = 1,
        uint32_t array_layers = 1,
        vk::ImageAspectFlags aspect_mask = vk::ImageAspectFlagBits::eColor);
 
    /**
     * @brief Upload pixels into one layer of an array image.
     *
     * The other layers keep their contents. @p size must be one layer's byte count.
     *
     * @param image    Array image.
     * @param layer    Layer index.
     * @param data     Pixels of one layer.
     * @param size     Byte count of one layer.
     * @param staging  Persistent staging buffer, or nullptr for a per-call one.
     * @param deferred Record for deferred submission (requires @p staging).
     * @return True if the upload was recorded or executed.
     */
    bool upload_layer(
        const std::shared_ptr<Core::VKImage>& image,
        uint32_t layer,
        const void* data,
        size_t size,
        const std::shared_ptr<Buffers::VKBuffer>& staging = nullptr,
        bool deferred = false);
 
    /**
     * @brief Copy a layer of one image into a layer of another, scaling to fit.
     *
     * Works between any two color images, so it writes GPU images into an array
     * layer without a host read, and also converts between supported formats. A
     * cubic filter is not available and falls back to linear.
     *
     * @param src      Source image, distinct from @p dst.
     * @param dst      Destination image.
     * @param blit     Layers, rectangles, filter and flips.
     * @param deferred Record for deferred submission.
     * @return True if the blit was recorded or executed.
     */
    bool blit_layer(
        const std::shared_ptr<Core::VKImage>& src,
        const std::shared_ptr<Core::VKImage>& dst,
        const LayerBlit& blit = {},
        bool deferred = false);
 
    /**
     * @brief Whether the device can blit between two images with a filter.
     */
    [[nodiscard]] bool can_blit(
        const std::shared_ptr<Core::VKImage>& src,
        const std::shared_ptr<Core::VKImage>& dst,
        FilterMode filter = FilterMode::LINEAR) const;
 
    //==========================================================================
    // Sampler Management
    //==========================================================================
 
    /**
     * @brief Get or create a sampler with the given configuration
     * @param config Sampler configuration
     * @return Vulkan sampler handle (cached)
     *
     * Samplers are cached - identical configs return same sampler.
     * Managed by TextureLoom, destroyed on shutdown.
     */
    vk::Sampler get_or_create_sampler(const SamplerConfig& config);
 
    /**
     * @brief Get a default linear sampler (for convenience)
     */
    vk::Sampler get_default_sampler();
 
    /**
     * @brief Get a default nearest sampler (for pixel-perfect sampling)
     */
    vk::Sampler get_nearest_sampler();
 
    //==========================================================================
    // Utilities
    //==========================================================================
 
    /**
     * @brief Convert Portal ImageFormat to Vulkan format
     */
    static vk::Format to_vulkan_format(ImageFormat format);
 
    /**
     * @brief Get bytes per pixel for a format
     */
    static size_t get_bytes_per_pixel(ImageFormat format);
 
    /**
     * @brief Convert Vulkan format to Portal ImageFormat.
     *
     * Reverse twin of to_vulkan_format. Returns std::nullopt for Vulkan
     * formats with no ImageFormat equivalent rather than guessing.
     */
    static std::optional<ImageFormat> from_vulkan_format(vk::Format vk_format);
 
    /**
     * @brief ImageFormat of an image that can be read back as one flat block.
     *
     * Requires an initialised 2D image of one layer and depth 1 with a
     * transfer-source usage, a format with an ImageFormat mapping that is not
     * combined depth-stencil, and a nonzero base level that fits the image's
     * allocation. The base level's byte count is
     * calculate_image_size(width, height, 1, format).
     *
     * Checks structure only: it says nothing about the image's current layout
     * or whether anything has been written to it.
     *
     * @return The format, or nullopt when any requirement is not met.
     */
    [[nodiscard]] static std::optional<ImageFormat> readable_format(
        const std::shared_ptr<Core::VKImage>& image);
 
    /**
     * @brief ImageFormat of an image that can be written as one flat block.
     *
     * The mirror of readable_format() with transfer-destination usage in
     * place of transfer-source: an initialised single-layer 2D image of depth 1,
     * a mapped format that is not combined depth-stencil, and a nonzero base
     * level that fits the image's allocation.
     *
     * @return The format, or nullopt when any requirement is not met.
     */
    [[nodiscard]] static std::optional<ImageFormat> writable_format(
        const std::shared_ptr<Core::VKImage>& image);
 
    /**
     * @brief Calculate image data size
     */
    static size_t calculate_image_size(
        uint32_t width,
        uint32_t height,
        uint32_t depth,
        ImageFormat format);
 
    /**
     * @brief Get the number of color channels for a given format
     */
    static uint32_t get_channel_count(ImageFormat format);
 
private:
    static std::optional<ImageFormat> transfer_format(
        const std::shared_ptr<Core::VKImage>& image,
        vk::ImageUsageFlagBits required_usage);
 
    TextureLoom() = default;
    ~TextureLoom() { shutdown(); }
 
    std::shared_ptr<Core::VulkanBackend> m_backend;
    Core::BackendResourceManager* m_resource_manager = nullptr;
 
    // Managed textures (for cleanup)
    std::vector<std::shared_ptr<Core::VKImage>> m_textures;
 
    // Sampler cache (config hash -> sampler)
    std::unordered_map<size_t, vk::Sampler> m_sampler_cache;
 
    // Helper: create sampler from config
    vk::Sampler create_sampler(const SamplerConfig& config);
 
    // Helper: hash sampler config for caching
    static size_t hash_sampler_config(const SamplerConfig& config);
 
    static bool s_initialized;
};
 
/**
 * @brief Cache images keyed by immutable allocation properties.
 *
 * The byte budget is a warning threshold. Entries remain cached after the
 * threshold is exceeded because TextureLoom retains created images until
 * shutdown and eviction would recreate them on a later request.
 */
class MAYAFLUX_API ImageCacheSet {
public:
    explicit ImageCacheSet(size_t byte_budget)
        : m_byte_budget(byte_budget)
    {
    }
 
    ImageCacheSet(const ImageCacheSet&) = delete;
    ImageCacheSet& operator=(const ImageCacheSet&) = delete;
    ImageCacheSet(ImageCacheSet&&) noexcept = default;
    ImageCacheSet& operator=(ImageCacheSet&&) noexcept = default;
    ~ImageCacheSet() = default;
 
    [[nodiscard]] std::shared_ptr<Core::VKImage> acquire(
        TextureLoom& loom, const ImageKey& key);
 
private:
    struct Entry {
        ImageCacheEntry cache;
    };
 
    std::unordered_map<ImageKey, Entry, ImageKeyHash> m_entries;
    size_t m_byte_budget;
    size_t m_cached_bytes {};
    bool m_budget_warned {};
    std::optional<ImageKey> m_last_key;
    Entry* m_last_entry {};
};
 
/**
 * @brief Get the global texture manager instance
 * @return Reference to singleton texture manager
 *
 * Must call initialize() before first use.
 * Thread-safe after initialization.
 */
inline MAYAFLUX_API TextureLoom& get_texture_manager()
{
    return TextureLoom::instance();
}
 
} // namespace MayaFlux::Portal::Graphics