WindowContainer.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 Window;
class VKImage;
}
 
namespace MayaFlux::Buffers {
class VKBuffer;
}
 
namespace MayaFlux::Kakshya {
 
/**
 * @class WindowContainer
 * @brief SignalSourceContainer wrapping a live Vulkan window surface.
 *
 * Exposes a window's rendered surface as addressable N-dimensional data.
 * Dimensions follow IMAGE_COLOR convention:
 *   dims[0] → SPATIAL_Y (height)
 *   dims[1] → SPATIAL_X (width)
 *   dims[2] → CHANNEL
 *
 * Region semantics:
 *   Regions are registered through the inherited RegionGroup API
 *   (add_region_group / get_all_region_groups / remove_region_group).
 *   load_region() and unload_region() are no-ops on this container — all
 *   surface data is always available after a GPU readback; region selection
 *   is a processor concern, not a container concern.
 *
 * Processing model:
 *   - The default processor (WindowAccessProcessor) performs one full-surface
 *     GPU readback per process() call into processed_data[0].
 *   - The processing chain (SpatialRegionProcessor) extracts registered
 *     regions from the readback as separate DataVariant entries.
 *   - get_region_data() crops directly from processed_data[0] if it is
 *     non-empty; returns empty if no readback has occurred yet.
 *   - The container never calls process() itself — callers drive the chain.
 * GPU bridge:
 *   - to_image() refreshes a container-owned VKImage from processed_data[0].
 *   - image_at() refreshes a container-owned VKImage for the selected slot.
 *   - region_to_image() crops on the CPU and refreshes an image for that region.
 *   - get_image_format() returns the live swapchain format as a Portal
 *     ImageFormat, suitable for constructing a matching TextureBuffer.
 *   - Concurrent image materialization calls on one container are serialized.
 *
 * Write semantics (compositing) are deferred to a future processor.
 */
class MAYAFLUX_API WindowContainer : public SignalSourceContainer {
public:
    /**
     * @brief Construct from an existing managed window.
     * @param window         Live window whose surface will be addressed as NDData.
     * @param frame_capacity Number of rendered images to retain in m_data.
     *                       Defaults to 60.
     */
    explicit WindowContainer(std::shared_ptr<Core::Window> window,
        uint32_t frame_capacity = 60);
 
    ~WindowContainer() override = default;
 
    WindowContainer(const WindowContainer&) = delete;
    WindowContainer& operator=(const WindowContainer&) = delete;
    WindowContainer(WindowContainer&&) = delete;
    WindowContainer& operator=(WindowContainer&&) = delete;
 
    /**
     * @brief The underlying window.
     */
    [[nodiscard]] std::shared_ptr<Core::Window> get_window() const { return m_window; }
 
    /**
     * @brief Portal ImageFormat corresponding to the live swapchain surface format.
     *
     * Derived from the actual negotiated swapchain format via DisplayService,
     * not from the WindowCreateInfo declaration. Use this when constructing a
     * TextureBuffer to receive the output of to_image().
     */
    [[nodiscard]] ImageFormat get_image_format() const;
 
    /**
     * @brief Mutable pointer into m_data[frame_index] for the processor to write into.
     * @param frame_index Slot index in [0, frame_capacity).
     * @return Pointer to the pixel buffer, or nullptr if out of range or unallocated.
     */
    [[nodiscard]] uint8_t* mutable_frame_ptr(uint32_t frame_index);
 
    [[nodiscard]] uint32_t get_frame_capacity() const { return m_frame_capacity; }
 
    /**
     * @brief Current write head index in m_data, advanced by the default processor after each readback.
     *        Exposed for testing and potential future use by custom processors.
     */
    [[nodiscard]] uint32_t get_write_head() const { return m_write_head.load(); }
 
    /** @brief Advance the write head index, wrapping around frame_capacity. */
    void advance_write_head();
 
    // =========================================================================
    // 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;
 
    /**
     * @brief Extract data for all regions across all region groups that
     *        spatially intersect @p region.
     *        Crops from the last full-surface readback — no GPU work.
     *        Returns empty if no readback has been performed yet.
     */
    [[nodiscard]] std::vector<DataVariant> get_region_data(const Region& region) const override;
 
    /**
     * @brief Upload the full surface readback to a container-owned VKImage.
     *
     * Requires at least one completed readback (processed_data[0] non-empty
     * and of type vector<uint8_t>). Reuses the image while dimensions and
     * format match. The returned image is refreshed in place
     * by later calls, so it is a live image rather than a snapshot.
     *
     * @return Cached VKImage, or nullptr on failure.
     */
    [[nodiscard]] std::shared_ptr<Core::VKImage> to_image() const;
 
    /**
     * @brief Refresh the full surface VKImage, reusing a
     *        caller-supplied persistent staging buffer.
     *
     * The container retains the image. The supplied staging buffer is used
     * for this upload.
     *
     * @param staging Host-visible staging VKBuffer sized to at least
     *                width * height * bytes_per_pixel.
     * @return Cached VKImage, or nullptr on failure.
     */
    [[nodiscard]] std::shared_ptr<Core::VKImage> to_image(
        const std::shared_ptr<Buffers::VKBuffer>& staging) const;
 
    /**
     * @brief Refresh the cached VKImage for m_data[frame_index].
     * @param frame_index Index into m_data in [0, frame_capacity).
     */
    [[nodiscard]] std::shared_ptr<Core::VKImage> image_at(uint32_t frame_index) const;
 
    /**
     * @brief Upload m_data[frame_index] reusing a caller-supplied staging buffer.
     * @param frame_index Index into m_data in [0, frame_capacity).
     * @param staging     Host-visible VKBuffer sized to at least w * h * bpp.
     */
    [[nodiscard]] std::shared_ptr<Core::VKImage> image_at(
        uint32_t frame_index,
        const std::shared_ptr<Buffers::VKBuffer>& staging) const;
 
    /**
     * @brief Crop a region from the last readback and refresh its cached VKImage.
     *
     * Performs a CPU-side crop via extract_region_data and uploads it. Region
     * coordinates follow IMAGE_COLOR convention: [SPATIAL_Y, SPATIAL_X].
     * The returned image dimensions are derived from the region extent. The
     * image is retained by the container and refreshed for any later region
     * with the same width and height.
     *
     * @param region Pixel rectangle. Must have at least 2 coordinates.
     * @return VKImage sized to the region, or nullptr on failure.
     */
    [[nodiscard]] std::shared_ptr<Core::VKImage> region_to_image(const Region& region) const;
 
    void set_region_data(const Region& region, const std::vector<DataVariant>& data) override;
 
    [[nodiscard]] std::vector<DataVariant> get_region_group_data(const RegionGroup& group) const override;
    [[nodiscard]] std::vector<DataVariant> get_segments_data(const std::vector<RegionSegment>& segments) const override;
 
    [[nodiscard]] std::type_index value_element_type() const override { return typeid(uint8_t); }
 
    [[nodiscard]] uint64_t coordinates_to_linear_index(const std::vector<uint64_t>& coordinates) const override;
    [[nodiscard]] std::vector<uint64_t> linear_index_to_coordinates(uint64_t linear_index) const override;
 
    void clear() 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); }
 
    // -------------------------------------------------------------------------
    // RegionGroup API — primary region registration interface.
    // -------------------------------------------------------------------------
 
    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;
 
    /**
     * @brief No-op. All surface data is continuously available after readback.
     *        Register regions via add_region_group() instead.
     */
    void load_region(const Region& region) override;
 
    /**
     * @brief No-op. See load_region().
     */
    void unload_region(const Region& region) override;
 
    /**
     * @brief Always returns true. Surface data is available after any readback.
     */
    [[nodiscard]] bool is_region_loaded(const Region& region) const override;
 
    /**
     * @brief Reallocate m_data and m_processed_data to match the current window
     *        dimensions. Called by WindowAccessProcessor when a surface resize is
     *        detected. Holds the data seqlock's serialized write claim.
     */
    void handle_surface_resize();
 
    /**
     * @brief processed_data[frame_index] as a normalised float span.
     *
     * Valid after WindowAccessProcessor has written processed_data[frame_index].
     * uint8_t values divided by 255.0f; uint16_t by 65535.0f; float is zero-copy.
     * Returns empty span if frame_index is out of range or the variant holds a
     * non-pixel type.
     *
     * Result is cached per slot and reused until invalidate_float_frame_cache()
     * is called for that slot.
     *
     * @param frame_index Zero-based index into processed_data. Defaults to 0.
     * @return Normalised float span, width * height * channels elements.
     */
    [[nodiscard]] std::span<const float> processed_frame_as_float(uint32_t frame_index = 0) const;
 
    /**
     * @brief Invalidate the normalised float cache for a specific processed_data slot.
     *
     * Called by WindowAccessProcessor after each successful readback into
     * processed_data[frame_index]. Forces recomputation on the next
     * processed_frame_as_float() call for that slot.
     *
     * @param frame_index Zero-based index into processed_data.
     */
    void invalidate_float_frame_cache(uint32_t frame_index = 0);
 
    // =========================================================================
    // SignalSourceContainer
    // =========================================================================
 
    [[nodiscard]] ProcessingState get_processing_state() const override;
    void update_processing_state(ProcessingState new_state) override;
 
    void register_state_change_callback(
        std::function<void(const std::shared_ptr<SignalSourceContainer>&, ProcessingState)> callback) override;
    void unregister_state_change_callback() override;
 
    [[nodiscard]] bool is_ready_for_processing() const override;
    void mark_ready_for_processing(bool ready) override;
 
    void create_default_processor() override;
    void process_default() override;
 
    void set_default_processor(const std::shared_ptr<DataProcessor>& processor) override;
    [[nodiscard]] std::shared_ptr<DataProcessor> get_default_processor() const override;
 
    [[nodiscard]] std::shared_ptr<DataProcessingChain> get_processing_chain() override;
    void set_processing_chain(const std::shared_ptr<DataProcessingChain>& chain) override;
 
    [[nodiscard]] uint64_t get_frame_size() const override;
    [[nodiscard]] uint64_t get_num_frames() const override;
 
    // -------------------------------------------------------------------------
    // Consumer tracking — dimension_index and reader_id are opaque slot handles.
    // Tracks whether all registered consumers have read processed_data[0] this
    // cycle. The slot index argument exists for interface compliance; internally
    // this container tracks a single consumer count across all slots.
    // -------------------------------------------------------------------------
    uint32_t register_dimension_reader(uint32_t dimension_index) override;
    void unregister_dimension_reader(uint32_t dimension_index) override;
    [[nodiscard]] bool has_active_readers() const override;
    void mark_dimension_consumed(uint32_t dimension_index, uint32_t reader_id) override;
    [[nodiscard]] bool all_dimensions_consumed() const 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;
 
    void mark_buffers_for_processing(bool) override { }
    void mark_buffers_for_removal() override { }
 
    [[nodiscard]] DataAccess channel_data(size_t channel_index) override;
    [[nodiscard]] std::vector<DataAccess> all_channel_data() override;
 
protected:
    [[nodiscard]] auto get_frame_span_impl(uint64_t frame_index) const -> DataSpanVariant override;
    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:
    struct PixelSnapshot {
        std::vector<uint8_t> pixels;
        std::vector<DataDimension> dimensions;
        uint32_t width { 0 };
        uint32_t height { 0 };
    };
 
    std::shared_ptr<Core::Window> m_window;
 
    mutable Portal::Graphics::ImageCacheEntry m_surface_image;
    mutable std::vector<Portal::Graphics::ImageCacheEntry> m_frame_images;
    mutable std::map<std::pair<uint32_t, uint32_t>, Portal::Graphics::ImageCacheEntry> m_region_images;
    mutable Memory::Seqlock m_image_cache_lock;
 
    ContainerDataStructure m_structure;
    std::vector<DataVariant> m_data;
    std::vector<DataVariant> m_processed_data;
 
    mutable std::vector<std::vector<float>> m_normalised_cache;
    mutable std::vector<std::atomic<bool>> m_normalised_dirty;
 
    std::unordered_map<std::string, RegionGroup> m_region_groups;
 
    std::shared_ptr<DataProcessor> m_default_processor;
    std::shared_ptr<DataProcessingChain> m_processing_chain;
 
    std::atomic<ProcessingState> m_processing_state { ProcessingState::IDLE };
    std::atomic<bool> m_ready_for_processing { false };
 
    std::function<void(const std::shared_ptr<SignalSourceContainer>&, ProcessingState)> m_state_callback;
 
    mutable Memory::Seqlock m_data_lock;
    mutable Memory::Seqlock m_region_lock;
    mutable Memory::Seqlock m_cb_lock;
 
    std::atomic<uint32_t> m_registered_readers { 0 };
    std::atomic<uint32_t> m_consumed_readers { 0 };
    std::atomic<uint32_t> m_next_reader_id { 0 };
    std::atomic<uint32_t> m_write_head { 0 };
    uint32_t m_frame_capacity { 1 };
    std::atomic<uint64_t> m_frames_written { 0 };
 
    void setup_dimensions();
 
    [[nodiscard]] std::optional<PixelSnapshot> snapshot_pixels(
        std::optional<uint32_t> frame_index = std::nullopt) const;
    [[nodiscard]] auto get_frame_typed(uint64_t frame_index) const -> std::span<const uint8_t>;
    void get_frames_typed(std::span<uint8_t> output, uint64_t start_frame, uint64_t num_frames) const;
};
 
} // namespace MayaFlux::Kakshya