MayaFlux::Kakshya::VideoStreamContainer Class Reference

Concrete base implementation for streaming video containers. More...

#include <VideoStreamContainer.hpp>

Inheritance diagram for MayaFlux::Kakshya::VideoStreamContainer:

Collaboration diagram for MayaFlux::Kakshya::VideoStreamContainer:

Public Member Functions
	VideoStreamContainer (uint32_t width=0, uint32_t height=0, uint32_t channels=4, double frame_rate=0.0)
	Construct a VideoStreamContainer with specified parameters.
	~VideoStreamContainer () override=default
std::vector< DataDimension >	get_dimensions () const override
	Get the dimensions describing the structure of the data.
uint64_t	get_total_elements () const override
	Get the total number of elements in the container.
MemoryLayout	get_memory_layout () const override
	Get the memory layout used by this container.
void	set_memory_layout (MemoryLayout layout) override
	Set the memory layout for this container.
uint64_t	get_frame_size () const override
	Get the number of elements that constitute one "frame".
uint64_t	get_num_frames () const override
	Get the number of frames in the primary (temporal) dimension.
std::vector< DataVariant >	get_region_data (const Region &region) const override
	Get data for a specific region.
void	set_region_data (const Region &region, const std::vector< DataVariant > &data) override
	Set data for a specific region.
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 > &segment) const override
	Get data for multiple region segments efficiently.
std::span< const double >	get_frame (uint64_t frame_index) const override
	Get a single frame of data efficiently.
void	get_frames (std::span< double > output, uint64_t start_frame, uint64_t num_frames) const override
	Get multiple frames efficiently.
double	get_value_at (const std::vector< uint64_t > &coordinates) const override
	Get a single value at the specified coordinates.
void	set_value_at (const std::vector< uint64_t > &coordinates, double value) override
	Set a single value at the specified coordinates.
uint64_t	coordinates_to_linear_index (const std::vector< uint64_t > &coordinates) const override
	Convert coordinates to linear index based on current memory layout.
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	clear () override
	Clear all data in the container.
void	lock () override
	Acquire a lock for thread-safe access.
void	unlock () override
	Release a previously acquired lock.
bool	try_lock () override
	Attempt to acquire a lock without blocking.
const void *	get_raw_data () const override
	Get a raw pointer to the underlying data storage.
bool	has_data () const override
	Check if the container currently holds any data.
ContainerDataStructure &	get_structure () override
	Get the data structure defining this container's layout.
const ContainerDataStructure &	get_structure () const override
void	set_structure (ContainerDataStructure structure) override
	Set the data structure for this container.
void	setup_ring (uint64_t total_frames, uint32_t ring_capacity, uint32_t width, uint32_t height, uint32_t channels, double frame_rate, uint32_t refill_threshold, uint64_t reader_id=0)
	Allocate m_data[0] as a ring of ring_capacity frames.
uint8_t *	mutable_slot_ptr (uint64_t frame_index)
	Mutable pointer into m_data[0] for the decode thread to write into.
void	commit_frame (uint64_t frame_index)
	Publish a decoded frame.
void	invalidate_ring ()
	Invalidate all ring slots.
bool	is_frame_available (uint64_t frame_index) const
	Check if a frame is currently valid in the ring.
bool	is_ring_mode () const
	True if the container is operating in ring mode.
uint32_t	get_ring_capacity () const
uint64_t	get_total_source_frames () const
void	set_refill_threshold (uint32_t threshold)
	Set the number of frames below which the refill callback fires.
void	advance_cache_head (uint64_t frame_index)
	Advance the container's view of how many frames have been decoded.
uint64_t	get_cache_head () const
	Total frame count known at construction / setup_ring() time.
void	add_region_group (const RegionGroup &group) override
	Add a named group of regions to the container.
const RegionGroup &	get_region_group (const std::string &name) const override
	Get a region group by name.
std::unordered_map< std::string, RegionGroup >	get_all_region_groups () const override
	Get all region groups in the container.
void	remove_region_group (const std::string &name) override
	Remove a region group by name.
bool	is_region_loaded (const Region &region) const override
	Check if a region is loaded in memory.
void	load_region (const Region &region) override
	Load a region into memory.
void	unload_region (const Region &region) override
	Unload a region from memory.
void	set_read_position (const std::vector< uint64_t > &position) override
	Set the current read position in the primary temporal dimension per channel.
void	update_read_position_for_channel (size_t channel, uint64_t frame) override
	Update the read position for a specific channel.
const std::vector< uint64_t > &	get_read_position () const override
	Get the current read position.
void	advance_read_position (const std::vector< uint64_t > &frames) override
	Advance the read position by a specified amount.
bool	is_at_end () const override
	Check if read position has reached the end of the stream.
void	reset_read_position () override
	Reset read position to the beginning of the stream.
uint64_t	get_temporal_rate () const override
	Get the temporal rate (e.g., sample rate, frame rate) of the stream.
uint64_t	time_to_position (double time) const override
	Convert from time (seconds) to position units (e.g., frame/sample index).
double	position_to_time (uint64_t position) const override
	Convert from position units (e.g., frame/sample index) to time (seconds).
void	set_looping (bool enable) override
	Enable or disable looping behavior for the stream.
bool	is_looping () const override
	Check if looping is enabled for the stream.
void	set_loop_region (const Region &region) override
	Set the loop region using a Region.
Region	get_loop_region () const override
	Get the current loop region.
bool	is_ready () const override
	Check if the stream is ready for reading.
std::vector< uint64_t >	get_remaining_frames () const override
	Get the number of remaining frames from the current position, per channel.
uint64_t	read_sequential (std::span< double > output, uint64_t count) override
	Read data sequentially from the current position.
uint64_t	peek_sequential (std::span< double > output, uint64_t count, uint64_t offset) const override
	Peek at data without advancing the read position.
ProcessingState	get_processing_state () const override
	Get the current processing state of the container.
void	update_processing_state (ProcessingState new_state) override
	Update the processing state of the container.
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	unregister_state_change_callback () override
	Unregister the state change callback, if any.
bool	is_ready_for_processing () const override
	Check if the container is ready for processing.
void	mark_ready_for_processing (bool ready) override
	Mark the container as ready or not ready for processing.
void	create_default_processor () override
	Create and configure a default processor for this container.
void	process_default () override
	Process the container's data using the default processor.
void	set_default_processor (const std::shared_ptr< DataProcessor > &processor) override
	Set the default data processor for this container.
std::shared_ptr< DataProcessor >	get_default_processor () const override
	Get the current default data processor.
std::shared_ptr< DataProcessingChain >	get_processing_chain () override
	Get the current processing chain for this container.
void	set_processing_chain (const std::shared_ptr< DataProcessingChain > &chain) override
	Set the processing chain for this container.
uint32_t	register_dimension_reader (uint32_t dimension_index) override
	Register a reader for a specific dimension.
void	unregister_dimension_reader (uint32_t dimension_index) override
	Unregister a reader for a specific dimension.
bool	has_active_readers () const override
	Check if any dimensions currently have active readers.
void	mark_dimension_consumed (uint32_t dimension_index, uint32_t reader_id) override
	Mark a dimension as consumed for the current processing cycle.
bool	all_dimensions_consumed () const override
	Check if all active dimensions have been consumed in this cycle.
void	reset_processing_token () override
bool	try_acquire_processing_token (int channel) override
bool	has_processing_token (int channel) const override
const std::vector< DataVariant > &	get_data () override
	Get a reference to the raw data stored in the container.
DataAccess	channel_data (size_t channel) override
	Get channel data with semantic interpretation.
std::vector< DataAccess >	all_channel_data () override
	Get all channel data as accessors.
std::vector< DataVariant > &	get_processed_data () override
	Get a mutable reference to the processed data buffer.
const std::vector< DataVariant > &	get_processed_data () const override
	Get a const reference to the processed data buffer.
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.
uint32_t	get_width () const
uint32_t	get_height () const
uint32_t	get_channels () const
double	get_frame_rate () const
std::span< const uint8_t >	get_frame_pixels (uint64_t frame_index) const
	Get raw pixel data for a single frame as uint8_t span.
size_t	get_frame_byte_size () const
	Get the total byte size of one frame (width * height * channels).
Public Member Functions inherited from MayaFlux::Kakshya::StreamContainer
virtual	~StreamContainer ()=default
Public Member Functions inherited from MayaFlux::Kakshya::SignalSourceContainer
	~SignalSourceContainer () override=default
Public Member Functions inherited from MayaFlux::Kakshya::NDDataContainer
virtual	~NDDataContainer ()=default

Protected Member Functions
void	setup_dimensions ()
void	notify_state_change (ProcessingState new_state)
uint32_t	slot_for (uint64_t frame_index) const

Protected Attributes
uint32_t	m_width = 0
uint32_t	m_height = 0
uint32_t	m_channels = 4
double	m_frame_rate = 0.0
uint64_t	m_num_frames = 0
ContainerDataStructure	m_structure
std::vector< DataVariant >	m_data
std::vector< DataVariant >	m_processed_data
std::shared_mutex	m_data_mutex
std::mutex	m_state_mutex
std::atomic< ProcessingState >	m_processing_state { ProcessingState::IDLE }
std::atomic< int >	m_processing_token_channel { -1 }
std::function< void(const std::shared_ptr< SignalSourceContainer > &, ProcessingState)>	m_state_callback
std::shared_ptr< DataProcessor >	m_default_processor
std::shared_ptr< DataProcessingChain >	m_processing_chain
std::unordered_map< std::string, RegionGroup >	m_region_groups
std::atomic< uint64_t >	m_read_position { 0 }
bool	m_looping_enabled = false
Region	m_loop_region
std::atomic< uint32_t >	m_registered_readers { 0 }
std::atomic< uint32_t >	m_consumed_readers { 0 }
uint32_t	m_ring_capacity { 0 }
uint64_t	m_total_source_frames { 0 }
std::vector< std::atomic< uint64_t > >	m_slot_frame
Memory::LockFreeQueue< uint64_t, READY_QUEUE_CAPACITY >	m_ready_queue
std::atomic< uint64_t >	m_cache_head { 0 }
	Highest frame index committed by the decode thread.
uint32_t	m_refill_threshold { 0 }
	Trigger refill when (m_cache_head - read_position) drops below this.
Registry::Service::IOService *	m_io_service { nullptr }
uint64_t	m_io_reader_id { 0 }

Static Protected Attributes
static constexpr uint32_t	READY_QUEUE_CAPACITY = 256

Detailed Description

Concrete base implementation for streaming video containers.

VideoStreamContainer provides a complete, concrete implementation of all StreamContainer functionality for decoded video frame data. It serves as:

1. A standalone streaming container for real-time video processing
2. A base class for specialized containers like VideoFileContainer

Data is stored as uint8_t pixels in RGBA interleaved layout (matching Vulkan VK_FORMAT_R8G8B8A8_UNORM and the TextureBuffer pipeline). Each frame is width * height * channels bytes. All frames are stored contiguously in a single DataVariant.

Dimensions follow VIDEO_COLOR convention: dims[0] → TIME (frame count) dims[1] → SPATIAL_Y (height) dims[2] → SPATIAL_X (width) dims[3] → CHANNEL (colour channels, typically 4 for RGBA)

Reader model follows WindowContainer's pattern: a simple atomic reader count rather than per-dimension/per-channel tracking. Video frames are atomic spatial units — channel-level access is a processor concern, not a container concern.

Uses virtual inheritance to support diamond inheritance when used as a base for FileContainer-derived classes.

Definition at line 43 of file VideoStreamContainer.hpp.

---

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

• VideoStreamContainer.hpp
• VideoStreamContainer.cpp