TextureContainer.hpp

Go to the documentation of this file.

#pragma once
 
#include "MayaFlux/Kakshya/SignalSourceContainer.hpp"
#include "MayaFlux/Portal/Graphics/TextureLoom.hpp"
 
#include "MayaFlux/Transitive/Memory/SeqLock.hpp"
 
namespace MayaFlux::Core {
class VKImage;
}
 
namespace MayaFlux::Buffers {
class VKBuffer;
}
 
namespace MayaFlux::Kakshya {
 
/**
 * @class TextureContainer
 * @brief SignalSourceContainer wrapping GPU texture data as addressable pixel bytes.
 *
 * TextureContainer is the Kakshya-layer representation of a 2D texture.
 * It owns a flat interleaved RGBA/float pixel buffer matching the declared
 * ImageFormat, described with IMAGE_COLOR or IMAGE_2D dimensions.
 *
 * The container is the data carrier for Yantra::Texture workflow pipelines.
 * GPU materialization is intentionally not automatic: callers drive upload
 * and download explicitly via from_image() and to_image(), keeping the
 * container decoupled from any specific VKImage lifetime.
 *
 * Dimension convention (IMAGE_COLOR, INTERLEAVED):
 *   dims[0] -> SPATIAL_Y (height)
 *   dims[1] -> SPATIAL_X (width)
 *   dims[2] -> CHANNEL   (bytes per pixel for format)
 *
 * Processing model:
 *   No default processor is created. The container holds bytes passively.
 *   Workflow operations receive and return TextureContainer instances;
 *   TextureExecutionContext dispatches compute shaders against them.
 *   Concurrent image materialization calls on one container are serialized.
 */
class MAYAFLUX_API TextureContainer : public SignalSourceContainer {
public:
    /**
     * @brief Construct an empty container with declared dimensions.
     * @param width   Texture width in pixels.
     * @param height  Texture height in pixels.
     * @param format  Pixel format; determines bytes per pixel.
     * @param layers   Number of array layers (default 1). set when using with array textures.
     *
     * Allocates a zeroed pixel buffer. No GPU resource is created.
     */
    TextureContainer(uint32_t width, uint32_t height, ImageFormat format, uint32_t layers = 1);
 
    /**
     * @brief Construct from an existing VKImage, downloading its pixel data.
     * @param image  Source GPU texture. Must be initialized.
     * @param format Pixel format of the image.
     *
     * Performs a blocking GPU->CPU download via TextureLoom.
     * Equivalent to constructing empty then calling from_image().
     */
    TextureContainer(
        const std::shared_ptr<Core::VKImage>& image,
        ImageFormat format);
 
    ~TextureContainer() override = default;
 
    TextureContainer(const TextureContainer&) = delete;
    TextureContainer& operator=(const TextureContainer&) = delete;
    TextureContainer(TextureContainer&&) = delete;
    TextureContainer& operator=(TextureContainer&&) = delete;
 
    [[nodiscard]] uint32_t get_layer_count() const { return static_cast<uint32_t>(m_data.size()); }
 
    //=========================================================================
    // GPU bridge
    //=========================================================================
 
    /**
     * @brief Download pixel data from a VKImage into this container.
     * @param image Source GPU texture. Must be initialized and match dimensions.
     * @param layer Array layer index for array textures (default 0).
     *
     * Blocking. Overwrites the existing pixel buffer. Does not change
     * declared width, height, or format — caller must ensure consistency.
     */
    void from_image(const std::shared_ptr<Core::VKImage>& image, uint32_t layer = 0);
 
    /**
     * @brief Download pixel data from a VKImage, reusing a caller-supplied
     *        persistent staging buffer.
     *
     * Identical to from_image() but passes @p staging through to
     * TextureLoom::download_data, eliminating the per-call Vulkan object
     * allocation. Use Buffers::create_image_staging_buffer(byte_size())
     * to allocate the staging buffer once before the render loop.
     *
     * @param image   Source GPU texture. Must be initialised and match dimensions.
     * @param staging Host-visible staging VKBuffer sized to at least byte_size().
     * @param layer   Array layer index (default 0).
     */
    void from_image(
        const std::shared_ptr<Core::VKImage>& image,
        const std::shared_ptr<Buffers::VKBuffer>& staging,
        uint32_t layer = 0);
 
    /**
     * @brief Download each array layer of a Vulkan 2D array image into
     *        the corresponding layer slot.
     *
     * Expects @p image to have array_layers == get_layer_count(). Downloads
     * each layer via a separate blocking TextureLoom::download_data call.
     * Resizes m_data to match if necessary.
     *
     * @param image Source VKImage with array_layers >= get_layer_count().
     */
    void from_image_array(const std::shared_ptr<Core::VKImage>& image);
 
    /**
     * @brief Download all array layers from a VKImage, reusing a caller-supplied
     *        persistent staging buffer.
     *
     * Identical to from_image_array() but passes @p staging through to
     * TextureLoom::download_data. The staging buffer must be at least
     * byte_size() * get_layer_count() bytes.
     * Use Buffers::create_image_staging_buffer(byte_size() * get_layer_count())
     * to allocate it once before the render loop.
     *
     * @param image   Source VKImage with array_layers >= get_layer_count().
     * @param staging Host-visible staging VKBuffer sized to at least
     *                byte_size() * get_layer_count().
     */
    void from_image_array(
        const std::shared_ptr<Core::VKImage>& image,
        const std::shared_ptr<Buffers::VKBuffer>& staging);
 
    /**
     * @brief Refresh the container-owned VKImage for one layer.
     * @param layer Array layer index for array textures (default 0).
     * @return Cached and uploaded VKImage. Null on failure.
     *
     * Reuses a container-owned image for this layer while dimensions and
     * format match. Later calls refresh the same image, so it is live rather
     * than a snapshot. A layer held on the GPU is returned as is, without an
     * upload.
     */
    [[nodiscard]] std::shared_ptr<Core::VKImage> to_image(uint32_t layer = 0) const;
 
    /**
     * @brief Refresh one layer's cached VKImage with caller-supplied staging.
     *
     * Reuses the container-owned image and uploads via the supplied staging
     * buffer.
     *
     * @param layer   Array layer index (default 0).
     * @param staging Host-visible staging VKBuffer sized to at least byte_size().
     * @return Cached VKImage, or nullptr on failure.
     */
    [[nodiscard]] std::shared_ptr<Core::VKImage> to_image(
        uint32_t layer,
        const std::shared_ptr<Buffers::VKBuffer>& staging) const;
 
    /**
     * @brief Upload all layers as a Vulkan 2D array texture.
     *
     * Concatenates pixel data from all layers in order (layer 0 first) and
     * refreshes a container-owned array image. The returned VKImage has
     * array_layers == get_layer_count() and an image view of type
     * VK_IMAGE_VIEW_TYPE_2D_ARRAY, making it bindable as sampler2DArray
     * in GLSL.
     *
     * All layers must have the expected byte count; otherwise this returns null.
     *
     * @return Cached array image when multiple layers exist, or a cached 2D
     *         image for one layer. Null on failure.
     */
    [[nodiscard]] std::shared_ptr<Core::VKImage> to_image_array() const;
 
    /**
     * @brief Upload all layers as a Vulkan 2D array texture, reusing a staging buffer.
     *
     * Concatenates pixel data from all layers in order (layer 0 first) and
     * refreshes a container-owned array image. The returned VKImage has
     * array_layers == get_layer_count() and an image view of type
     * VK_IMAGE_VIEW_TYPE_2D_ARRAY, making it bindable as sampler2DArray
     * in GLSL.
     *
     * All layers must have the expected byte count; otherwise this returns null.
     *
     * @param staging Host-visible staging VKBuffer sized to at least
     *                byte_size() * get_layer_count().
     * @return Cached array image when multiple layers exist, or a cached 2D
     *         image for one layer. Null on failure.
     */
    [[nodiscard]] std::shared_ptr<Core::VKImage> to_image_array(
        const std::shared_ptr<Buffers::VKBuffer>& staging) const;
 
    /**
     * @brief Upload one layer into an existing VKImage instead of creating one.
     *
     * Use this for an image retained separately from the container, such as
     * an execution context's input image.
     *
     * @param image   Target image. Must match this container's width, height
     *                and format, and be a single layer 2D image.
     * @param layer   Array layer index (default 0).
     * @param staging Host-visible staging VKBuffer sized to at least byte_size().
     * @return True when the layer was uploaded, false when the layer is out of
     *         range, empty, or the image is null.
     */
    bool upload_image(
        const std::shared_ptr<Core::VKImage>& image,
        uint32_t layer,
        const std::shared_ptr<Buffers::VKBuffer>& staging) const;
 
    /**
     * @brief Upload all layers into an existing VKImage instead of creating one.
     *
     * The counterpart of to_image_array(staging). A single layer container
     * targets a plain 2D image, more layers a 2D array image with
     * array_layers == get_layer_count().
     *
     * @param image   Target image created by to_image_array.
     * @param staging Host-visible staging VKBuffer sized to at least
     *                byte_size() * get_layer_count().
     * @return True when every layer was uploaded, false on a null image, an
     *         empty container, or a layer of unexpected size.
     */
    bool upload_image_array(
        const std::shared_ptr<Core::VKImage>& image,
        const std::shared_ptr<Buffers::VKBuffer>& staging) const;
 
    //=========================================================================
    // Pixel access
    //=========================================================================
 
    /**
     * @brief Read-only byte-level view over the pixel buffer.
     *
     * The returned span covers the raw byte footprint of the layer,
     * regardless of the underlying variant type. For uint8 formats this
     * is the natural view; for uint16 and float formats the caller can
     * reinterpret_cast for typed access, or prefer the as_uint16 /
     * as_float accessors below.
     *
     * @param layer Array layer index for array textures (default 0).
     */
    [[nodiscard]] std::span<const uint8_t> pixel_bytes(uint32_t layer = 0) const;
 
    /**
     * @brief Read-write byte-level view over the pixel buffer.
     * @param layer Array layer index for array textures (default 0).
     */
    [[nodiscard]] std::span<uint8_t> pixel_bytes(uint32_t layer = 0);
 
    /**
     * @brief Typed view over the uint8 variant.
     *        Returns an empty span if the layer's variant is not uint8.
     */
    [[nodiscard]] std::span<const uint8_t> as_uint8(uint32_t layer = 0) const;
 
    /**
     * @brief Typed view over the uint16 variant.
     *        Returns an empty span if the layer's variant is not uint16.
     *        16-bit UNORM formats and half-float formats both reside here;
     *        for half-float, the uint16 bits are the IEEE-754 binary16
     *        encoding.
     */
    [[nodiscard]] std::span<const uint16_t> as_uint16(uint32_t layer = 0) const;
 
    /**
     * @brief Typed view over the float variant.
     *        Returns an empty span if the layer's variant is not float.
     */
    [[nodiscard]] std::span<const float> as_float(uint32_t layer = 0) const;
 
    /**
     * @brief Replace the layer's pixel buffer with a byte source.
     *        Valid only when the declared format is uint8-backed.
     *        Size must equal width * height * bytes_per_pixel.
     */
    void set_pixels(std::span<const uint8_t> data, uint32_t layer = 0);
 
    /**
     * @brief Replace the layer's pixel buffer with a uint16 source.
     *        Valid when the declared format is uint16-backed
     *        (R16/RG16/RGBA16, R16F/RG16F/RGBA16F).
     *        Size must equal width * height * channels.
     */
    void set_pixels(std::span<const uint16_t> data, uint32_t layer = 0);
 
    /**
     * @brief Replace the layer's pixel buffer with a float source.
     *        Valid when the declared format is float-backed
     *        (R32F/RG32F/RGBA32F).
     *        Size must equal width * height * channels.
     */
    void set_pixels(std::span<const float> data, uint32_t layer = 0);
 
    /**
     * @brief Layer pixel data as a normalised float span.
     *
     * uint8_t source is divided by 255.0f. uint16_t by 65535.0f.
     * float source is zero-copy into the variant's own storage.
     * Returns empty span if layer is out of range or the variant
     * holds a non-pixel type.
     *
     * Result is cached per layer and reused until set_pixels()
     * or from_image() invalidates it for that layer.
     *
     * @param layer Array layer index. Defaults to 0.
     * @return Normalised float span, w * h * channels elements.
     */
    [[nodiscard]] std::span<const float> as_normalised_float(uint32_t layer = 0) const;
 
    //=========================================================================
    // Metadata
    //=========================================================================
 
    [[nodiscard]] uint32_t get_width() const { return m_width; }
    [[nodiscard]] uint32_t get_height() const { return m_height; }
    [[nodiscard]] ImageFormat get_format() const { return m_format; }
    [[nodiscard]] uint32_t get_channel_count() const { return m_channels; }
 
    /** @brief Byte count of one complete pixel row. */
    [[nodiscard]] size_t row_stride() const { return static_cast<size_t>(m_width) * m_bpp; }
 
    /** @brief Total byte count of the pixel buffer. */
    [[nodiscard]] size_t byte_size() const { return static_cast<size_t>(m_width) * m_height * m_bpp; }
 
    //=========================================================================
    // NDDimensionalContainer
    //=========================================================================
 
    [[nodiscard]] std::vector<DataDimension> get_dimensions() const override;
    [[nodiscard]] uint64_t get_total_elements() const override;
    [[nodiscard]] MemoryLayout get_memory_layout() const override;
    void set_memory_layout(MemoryLayout layout) override;
    [[nodiscard]] uint64_t get_frame_size() const override;
    [[nodiscard]] uint64_t get_num_frames() const override;
 
    [[nodiscard]] std::vector<DataVariant> get_region_data(const Region& region) const override;
    [[nodiscard]] std::vector<DataVariant> get_segments_data(
        const std::vector<RegionSegment>& segments) const override;
    [[nodiscard]] std::vector<DataVariant> get_region_group_data(const RegionGroup&) const override { return m_processed_data; }
 
    [[nodiscard]] std::type_index value_element_type() const override;
    [[nodiscard]] uint64_t coordinates_to_linear_index(const std::vector<uint64_t>& coords) const override;
    [[nodiscard]] std::vector<uint64_t> linear_index_to_coordinates(uint64_t index) const override;
    void clear() override;
 
    //=========================================================================
    // SignalSourceContainer
    //=========================================================================
 
    /**
     * @brief Write DataVariant bytes into the pixel buffer at the region bounds.
     *
     * The region's SPATIAL_Y / SPATIAL_X coordinates are used as the destination
     * rectangle. The first DataVariant in @p data must hold std::vector<uint8_t>
     * with exactly region_width * region_height * channels bytes.
     *
     * @param region Destination region (start/end SPATIAL_Y, SPATIAL_X coords).
     * @param data   Source data. First element must be vector<uint8_t>.
     */
    void set_region_data(const Region& region,
        const std::vector<DataVariant>& data) override;
 
    [[nodiscard]] ProcessingState get_processing_state() const override;
    void update_processing_state(ProcessingState state) override;
    void register_state_change_callback(
        std::function<void(const std::shared_ptr<SignalSourceContainer>&, ProcessingState)> cb) override;
    void unregister_state_change_callback() override;
 
    [[nodiscard]] bool is_ready_for_processing() const override;
    void mark_ready_for_processing(bool ready) override;
 
    [[nodiscard]] std::vector<DataVariant>& get_processed_data() override;
    [[nodiscard]] const std::vector<DataVariant>& get_processed_data() const override;
    [[nodiscard]] const std::vector<DataVariant>& get_data() override;
 
    /** @brief No-op. TextureContainer has no BufferManager integration. */
    void mark_buffers_for_processing(bool) override { }
 
    /** @brief No-op. TextureContainer has no BufferManager integration. */
    void mark_buffers_for_removal() override { }
 
    [[nodiscard]] DataAccess channel_data(size_t channel_index) override;
    [[nodiscard]] std::vector<DataAccess> all_channel_data() override;
 
    /** @brief No-op. All pixel data is always resident; no streaming regions. */
    void load_region(const Region&) override { }
 
    /** @brief No-op. All pixel data is always resident; no streaming regions. */
    void unload_region(const Region&) override { }
    [[nodiscard]] bool is_region_loaded(const Region&) const override { return true; }
 
    void add_region_group(const RegionGroup& group) override;
    [[nodiscard]] RegionGroup get_region_group(const std::string& name) const override;
    [[nodiscard]] std::unordered_map<std::string, RegionGroup> get_all_region_groups() const override;
    void remove_region_group(const std::string& name) override;
 
    [[nodiscard]] const void* get_raw_data() const override;
    [[nodiscard]] bool has_data() const override;
 
    [[nodiscard]] ContainerDataStructure& get_structure() override { return m_structure; }
    [[nodiscard]] const ContainerDataStructure& get_structure() const override { return m_structure; }
    void set_structure(ContainerDataStructure s) override { m_structure = std::move(s); }
 
    void reset_processing_token() { m_processing_token.store(-1); }
    bool try_acquire_processing_token(int ch)
    {
        int expected = -1;
        return m_processing_token.compare_exchange_strong(expected, ch);
    }
    [[nodiscard]] bool has_processing_token(int ch) const
    {
        return m_processing_token.load() == ch;
    }
 
    /** @brief No-op. TextureContainer holds bytes passively; no processor lifecycle. */
    void create_default_processor() override { }
 
    /** @brief No-op. TextureContainer holds bytes passively; no processor lifecycle. */
    void process_default() override { }
 
    void set_default_processor(const std::shared_ptr<DataProcessor>& p) override { m_processor = p; }
    std::shared_ptr<DataProcessor> get_default_processor() const override { return m_processor; }
    std::shared_ptr<DataProcessingChain> get_processing_chain() override;
    void set_processing_chain(const std::shared_ptr<DataProcessingChain>& c) override { m_chain = c; }
 
    /**
     * @brief No-op. TextureContainer does not track concurrent dimension readers.
     * @return Always 0.
     */
    uint32_t register_dimension_reader(uint32_t) override { return 0; }
 
    /** @brief No-op. TextureContainer does not track concurrent dimension readers. */
    void unregister_dimension_reader(uint32_t) override { }
 
    /**
     * @brief No-op. TextureContainer does not track concurrent dimension readers.
     * @return Always false.
     */
    [[nodiscard]] bool has_active_readers() const override { return false; }
 
    /** @brief No-op. TextureContainer does not track concurrent dimension readers. */
    void mark_dimension_consumed(uint32_t, uint32_t) override { }
 
    /**
     * @brief No-op. TextureContainer does not track concurrent dimension readers.
     * @return Always true.
     */
    [[nodiscard]] bool all_dimensions_consumed() const override { return true; }
 
protected:
    /** @brief Exact layer count for subclasses, zero allowed. */
    struct LayerCount {
        uint32_t value {};
    };
 
    /**
     * @brief Construct with exactly @p layers layers, which may be zero.
     */
    TextureContainer(uint32_t width, uint32_t height, ImageFormat format, LayerCount layers);
 
    /**
     * @brief Append one layer held on the GPU by @p image.
     *
     * The layer has no CPU pixels until a CPU accessor reads it, which
     * downloads @p image once. Writing CPU pixels replaces the content.
     * @p image must be a single layer sampled 2D image with this container's
     * width, height and format. Not safe while another thread reads or writes
     * the container.
     *
     * @return Index of the new layer.
     */
    uint32_t append_image_layer(std::shared_ptr<Core::VKImage> image);
 
    /**
     * @brief The GPU image backing @p layer, without uploading CPU pixels.
     * @return Null when @p layer is out of range or has no image yet.
     */
    [[nodiscard]] std::shared_ptr<Core::VKImage> layer_image(uint32_t layer) const;
 
    /**
     * @brief Mark @p layer as held on the GPU after its image was rewritten.
     *
     * Drops the layer's CPU pixels, which a CPU accessor downloads again on
     * its next read. Not safe while another thread reads or writes the
     * container.
     */
    void hold_layer(uint32_t layer);
 
    [[nodiscard]] auto get_frame_span_impl(uint64_t frame_index) const -> DataSpanVariant override
    {
        return get_frame_typed(frame_index);
    }
 
    void get_frames_impl(void* output, size_t count, uint64_t start_frame, uint64_t num_frames, const std::type_info& type) const override;
 
    void get_value_impl(const std::vector<uint64_t>& coords,
        void* out, const std::type_info& type) const override;
 
    void set_value_impl(const std::vector<uint64_t>& coords,
        const void* in, const std::type_info& type) override;
 
private:
    void setup_dimensions();
 
    uint32_t m_width {};
    uint32_t m_height {};
    ImageFormat m_format {};
    uint32_t m_channels {};
    size_t m_bpp {};
 
    mutable std::vector<DataVariant> m_data;
    std::vector<DataVariant> m_processed_data;
    mutable std::vector<Portal::Graphics::ImageCacheEntry> m_layer_image_cache;
    mutable Portal::Graphics::ImageCacheEntry m_array_image_cache;
    mutable Memory::Seqlock m_image_cache_lock;
    std::shared_ptr<DataProcessor> m_processor;
    std::shared_ptr<DataProcessingChain> m_chain;
 
    mutable std::vector<std::vector<float>> m_normalised_cache;
    mutable std::vector<std::atomic<bool>> m_normalised_dirty;
 
    /** @brief Per layer: the GPU image in m_layer_image_cache holds the content, m_data does not. */
    mutable std::vector<std::atomic<bool>> m_cpu_stale;
 
    ContainerDataStructure m_structure;
 
    std::atomic<ProcessingState> m_processing_state { ProcessingState::IDLE };
    std::atomic<bool> m_ready_for_processing { false };
    std::atomic<int> m_processing_token { -1 };
 
    mutable Memory::SeqlockArray m_slot_locks;
    Memory::Seqlock m_region_lock;
    mutable Memory::Seqlock m_cb_lock;
 
    std::function<void(const std::shared_ptr<SignalSourceContainer>&, ProcessingState)> m_state_cb;
    std::unordered_map<std::string, RegionGroup> m_region_groups;
 
    /** @brief Row cache backing the double span returned by get_frame(). */
    mutable std::vector<double> m_frame_cache;
 
    [[nodiscard]] std::shared_ptr<Core::VKImage> cached_layer_image(
        uint32_t layer, const std::shared_ptr<Buffers::VKBuffer>& staging) const;
    [[nodiscard]] std::shared_ptr<Core::VKImage> cached_array_image(
        const std::shared_ptr<Buffers::VKBuffer>& staging) const;
 
    /** @brief Download a GPU-held layer into m_data before a CPU read. */
    void ensure_cpu(uint32_t layer) const;
    void ensure_cpu_all() const;
 
    /** @brief Give a GPU-held layer fresh CPU storage before a full overwrite. */
    void claim_cpu(uint32_t layer);
 
    [[nodiscard]] auto get_frame_typed(uint64_t frame_index) const -> DataSpanVariant;
    void get_frames_typed(void* output, size_t count, uint64_t start_frame, uint64_t num_frames, const std::type_info& type) const;
 
    template <typename T>
    [[nodiscard]] auto get_frame_typed_as(uint64_t frame_index) const -> std::span<const T>;
 
    template <typename T>
    void get_frames_typed_as(std::span<T> output, uint64_t start_frame, uint64_t num_frames) const;
};
 
} // namespace MayaFlux::Kakshya