SignalSourceContainer wrapping a live Vulkan window surface. More...

#include <WindowContainer.hpp>

Inheritance diagram for MayaFlux::Kakshya::WindowContainer:

Collaboration diagram for MayaFlux::Kakshya::WindowContainer:

Classes
struct	PixelSnapshot

Public Member Functions
void	add_region_group (const RegionGroup &group) override
	Add a named group of regions to the container.

void	advance_write_head ()
	Advance the write head index, wrapping around frame_capacity.

std::vector< DataAccess >	all_channel_data () override
	Get all channel data as accessors.

bool	all_dimensions_consumed () const override
	Check if all active dimensions have been consumed in this cycle.

DataAccess	channel_data (size_t channel_index) override
	Get channel data with semantic interpretation.

void	clear () override
	Clear all data in the container.

uint64_t	coordinates_to_linear_index (const std::vector< uint64_t > &coordinates) const override
	Convert coordinates to linear index based on current memory layout.

void	create_default_processor () override
	Create and configure a default processor for this container.

std::unordered_map< std::string, RegionGroup >	get_all_region_groups () const override
	Get all region groups in the container.

const std::vector< DataVariant > &	get_data () override
	Get a reference to the raw data stored in the container.

std::shared_ptr< DataProcessor >	get_default_processor () const override
	Get the current default data processor.

std::vector< DataDimension >	get_dimensions () const override
	Get the dimensions describing the structure of the data.

uint32_t	get_frame_capacity () const

uint64_t	get_frame_size () const override
	Get the number of elements that constitute one "frame".

ImageFormat	get_image_format () const
	Portal ImageFormat corresponding to the live swapchain surface format.

MemoryLayout	get_memory_layout () const override
	Get the memory layout used by this container.

uint64_t	get_num_frames () const override
	Get the number of frames in the primary (temporal) dimension.

const std::vector< DataVariant > &	get_processed_data () const override
	Get a const reference to the processed data buffer.

std::vector< DataVariant > &	get_processed_data () override
	Get a mutable reference to the processed data buffer.

std::shared_ptr< DataProcessingChain >	get_processing_chain () override
	Get the current processing chain for this container.

ProcessingState	get_processing_state () const override
	Get the current processing state of the container.

const void *	get_raw_data () const override
	Get a raw pointer to the underlying data storage.

std::vector< DataVariant >	get_region_data (const Region &region) const override
	Extract data for all regions across all region groups that spatially intersect `region`.

RegionGroup	get_region_group (const std::string &name) const override
	Get a region group by name.

std::vector< DataVariant >	get_region_group_data (const RegionGroup &group) const override
	Get data for multiple regions efficiently.

std::vector< DataVariant >	get_segments_data (const std::vector< RegionSegment > &segments) const override
	Get data for multiple region segments efficiently.

const ContainerDataStructure &	get_structure () const override

ContainerDataStructure &	get_structure () override
	Get the data structure defining this container's layout.

uint64_t	get_total_elements () const override
	Get the total number of elements in the container.

std::shared_ptr< Core::Window >	get_window () const
	The underlying window.

uint32_t	get_write_head () const
	Current write head index in m_data, advanced by the default processor after each readback.

void	handle_surface_resize ()
	Reallocate m_data and m_processed_data to match the current window dimensions.

bool	has_active_readers () const override
	Check if any dimensions currently have active readers.

bool	has_data () const override
	Check if the container currently holds any data.

std::shared_ptr< Core::VKImage >	image_at (uint32_t frame_index) const
	Refresh the cached VKImage for m_data[frame_index].

std::shared_ptr< Core::VKImage >	image_at (uint32_t frame_index, const std::shared_ptr< Buffers::VKBuffer > &staging) const
	Upload m_data[frame_index] reusing a caller-supplied staging buffer.

void	invalidate_float_frame_cache (uint32_t frame_index=0)
	Invalidate the normalised float cache for a specific processed_data slot.

bool	is_ready_for_processing () const override
	Check if the container is ready for processing.

bool	is_region_loaded (const Region &region) const override
	Always returns true.

std::vector< uint64_t >	linear_index_to_coordinates (uint64_t linear_index) const override
	Convert linear index to coordinates based on current memory layout.

void	load_region (const Region &region) override
	No-op.

void	mark_buffers_for_processing (bool) override
	Mark associated buffers for processing in the next cycle.

void	mark_buffers_for_removal () override
	Mark associated buffers for removal from the system.

void	mark_dimension_consumed (uint32_t dimension_index, uint32_t reader_id) override
	Mark a dimension as consumed for the current processing cycle.

void	mark_ready_for_processing (bool ready) override
	Mark the container as ready or not ready for processing.

uint8_t *	mutable_frame_ptr (uint32_t frame_index)
	Mutable pointer into m_data[frame_index] for the processor to write into.

WindowContainer &	operator= (const WindowContainer &)=delete

WindowContainer &	operator= (WindowContainer &&)=delete

void	process_default () override
	Process the container's data using the default processor.

std::span< const float >	processed_frame_as_float (uint32_t frame_index=0) const
	processed_data[frame_index] as a normalised float span.

std::shared_ptr< Core::VKImage >	region_to_image (const Region &region) const
	Crop a region from the last readback and refresh its cached VKImage.

uint32_t	register_dimension_reader (uint32_t dimension_index) override
	Register a reader for a specific dimension.

void	register_state_change_callback (std::function< void(const std::shared_ptr< SignalSourceContainer > &, ProcessingState)> callback) override
	Register a callback to be invoked on processing state changes.

void	remove_region_group (const std::string &name) override
	Remove a region group by name.

void	set_default_processor (const std::shared_ptr< DataProcessor > &processor) override
	Set the default data processor for this container.

void	set_memory_layout (MemoryLayout layout) override
	Set the memory layout for this container.

void	set_processing_chain (const std::shared_ptr< DataProcessingChain > &chain) override
	Set the processing chain for this container.

void	set_region_data (const Region &region, const std::vector< DataVariant > &data) override
	Set data for a specific region.

void	set_structure (ContainerDataStructure s) override
	Set the data structure for this container.

std::shared_ptr< Core::VKImage >	to_image () const
	Upload the full surface readback to a container-owned VKImage.

std::shared_ptr< Core::VKImage >	to_image (const std::shared_ptr< Buffers::VKBuffer > &staging) const
	Refresh the full surface VKImage, reusing a caller-supplied persistent staging buffer.

void	unload_region (const Region &region) override
	No-op.

void	unregister_dimension_reader (uint32_t dimension_index) override
	Unregister a reader for a specific dimension.

void	unregister_state_change_callback () override
	Unregister the state change callback, if any.

void	update_processing_state (ProcessingState new_state) override
	Update the processing state of the container.

std::type_index	value_element_type () const override
	Runtime query for the native scalar element type of this container.

	WindowContainer (const WindowContainer &)=delete

	WindowContainer (std::shared_ptr< Core::Window > window, uint32_t frame_capacity=60)
	Construct from an existing managed window.

	WindowContainer (WindowContainer &&)=delete

	~WindowContainer () override=default

Public Member Functions inherited from MayaFlux::Kakshya::SignalSourceContainer
	~SignalSourceContainer () override=default

Public Member Functions inherited from MayaFlux::Kakshya::NDDataContainer< DataVariant >
auto	get_frame (uint64_t frame_index) const -> FrameView
	Get a single frame of data efficiently.

auto	get_frame_as (uint64_t frame_index) const -> std::span< const ValueT >
	Get a single frame of data as a typed span.

void	get_frames (std::span< ValueT > output, uint64_t start_frame, uint64_t num_frames) const
	Get multiple frames efficiently.

void	get_frames_as (std::vector< ValueT > &output, uint64_t start_frame, uint64_t num_frames) const
	Get multiple frames efficiently as a typed span.

ValueT	get_value_at (const std::vector< uint64_t > &coordinates) const
	Read a single element at the given N-dimensional coordinates.

void	set_value_at (const std::vector< uint64_t > &coordinates, ValueT value)
	Write a single element at the given N-dimensional coordinates.

virtual	~NDDataContainer ()=default

Protected Member Functions
auto	get_frame_span_impl (uint64_t frame_index) const -> DataSpanVariant override
	Implementation-specific method to retrieve a frame span.

void	get_frames_impl (void *output, size_t count, uint64_t start_frame, uint64_t num_frames, const std::type_info &type) const override
	Implementation-specific method to retrieve multiple frames.

void	get_value_impl (const std::vector< uint64_t > &coords, void *out, const std::type_info &type) const override
	Type-erased single-element read.

void	set_value_impl (const std::vector< uint64_t > &coords, const void *in, const std::type_info &type) override
	Type-erased single-element write.

Private Member Functions
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

void	setup_dimensions ()

std::optional< PixelSnapshot >	snapshot_pixels (std::optional< uint32_t > frame_index=std::nullopt) const

Private Attributes
Memory::Seqlock	m_cb_lock

std::atomic< uint32_t >	m_consumed_readers { 0 }

std::vector< DataVariant >	m_data

Memory::Seqlock	m_data_lock

std::shared_ptr< DataProcessor >	m_default_processor

uint32_t	m_frame_capacity { 1 }

std::vector< Portal::Graphics::ImageCacheEntry >	m_frame_images

std::atomic< uint64_t >	m_frames_written { 0 }

Memory::Seqlock	m_image_cache_lock

std::atomic< uint32_t >	m_next_reader_id { 0 }

std::vector< std::vector< float > >	m_normalised_cache

std::vector< std::atomic< bool > >	m_normalised_dirty

std::vector< DataVariant >	m_processed_data

std::shared_ptr< DataProcessingChain >	m_processing_chain

std::atomic< ProcessingState >	m_processing_state { ProcessingState::IDLE }

std::atomic< bool >	m_ready_for_processing { false }

std::unordered_map< std::string, RegionGroup >	m_region_groups

std::map< std::pair< uint32_t, uint32_t >, Portal::Graphics::ImageCacheEntry >	m_region_images

Memory::Seqlock	m_region_lock

std::atomic< uint32_t >	m_registered_readers { 0 }

std::function< void(const std::shared_ptr< SignalSourceContainer > &, ProcessingState)>	m_state_callback

ContainerDataStructure	m_structure

Portal::Graphics::ImageCacheEntry	m_surface_image

std::shared_ptr< Core::Window >	m_window

std::atomic< uint32_t >	m_write_head { 0 }

Detailed Description

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.

Definition at line 54 of file WindowContainer.hpp.

The documentation for this class was generated from the following files:

Classes

Public Member Functions

Protected Member Functions

Private Member Functions

Private Attributes

Detailed Description