SignalSourceContainer wrapping GPU texture data as addressable pixel bytes. More...

#include <TextureContainer.hpp>

Inheritance diagram for MayaFlux::Kakshya::TextureContainer:

Collaboration diagram for MayaFlux::Kakshya::TextureContainer:

Classes
struct	LayerCount
	Exact layer count for subclasses, zero allowed. More...

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

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

bool	all_dimensions_consumed () const override
	No-op.

std::span< const float >	as_float (uint32_t layer=0) const
	Typed view over the float variant.

std::span< const float >	as_normalised_float (uint32_t layer=0) const
	Layer pixel data as a normalised float span.

std::span< const uint16_t >	as_uint16 (uint32_t layer=0) const
	Typed view over the uint16 variant.

std::span< const uint8_t >	as_uint8 (uint32_t layer=0) const
	Typed view over the uint8 variant.

size_t	byte_size () const
	Total byte count of the pixel buffer.

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 > &coords) const override
	Convert coordinates to linear index based on current memory layout.

void	create_default_processor () override
	No-op.

void	from_image (const std::shared_ptr< Core::VKImage > &image, const std::shared_ptr< Buffers::VKBuffer > &staging, uint32_t layer=0)
	Download pixel data from a VKImage, reusing a caller-supplied persistent staging buffer.

void	from_image (const std::shared_ptr< Core::VKImage > &image, uint32_t layer=0)
	Download pixel data from a VKImage into this container.

void	from_image_array (const std::shared_ptr< Core::VKImage > &image)
	Download each array layer of a Vulkan 2D array image into the corresponding layer slot.

void	from_image_array (const std::shared_ptr< Core::VKImage > &image, const std::shared_ptr< Buffers::VKBuffer > &staging)
	Download all array layers from a VKImage, reusing a caller-supplied persistent staging buffer.

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

uint32_t	get_channel_count () const

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.

ImageFormat	get_format () const

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

uint32_t	get_height () const

uint32_t	get_layer_count () const

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
	Get data for a specific 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 &) 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.

uint32_t	get_width () const

bool	has_active_readers () const override
	No-op.

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

bool	has_processing_token (int ch) const

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

bool	is_region_loaded (const Region &) const override
	Check if a region is loaded in memory.

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

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

void	mark_buffers_for_processing (bool) override
	No-op.

void	mark_buffers_for_removal () override
	No-op.

void	mark_dimension_consumed (uint32_t, uint32_t) override
	No-op.

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

TextureContainer &	operator= (const TextureContainer &)=delete

TextureContainer &	operator= (TextureContainer &&)=delete

std::span< uint8_t >	pixel_bytes (uint32_t layer=0)
	Read-write byte-level view over the pixel buffer.

std::span< const uint8_t >	pixel_bytes (uint32_t layer=0) const
	Read-only byte-level view over the pixel buffer.

void	process_default () override
	No-op.

uint32_t	register_dimension_reader (uint32_t) override
	No-op.

void	register_state_change_callback (std::function< void(const std::shared_ptr< SignalSourceContainer > &, ProcessingState)> cb) 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	reset_processing_token ()

size_t	row_stride () const
	Byte count of one complete pixel row.

void	set_default_processor (const std::shared_ptr< DataProcessor > &p) 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_pixels (std::span< const float > data, uint32_t layer=0)
	Replace the layer's pixel buffer with a float source.

void	set_pixels (std::span< const uint16_t > data, uint32_t layer=0)
	Replace the layer's pixel buffer with a uint16 source.

void	set_pixels (std::span< const uint8_t > data, uint32_t layer=0)
	Replace the layer's pixel buffer with a byte source.

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

void	set_region_data (const Region &region, const std::vector< DataVariant > &data) override
	Write DataVariant bytes into the pixel buffer at the region bounds.

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

	TextureContainer (const std::shared_ptr< Core::VKImage > &image, ImageFormat format)
	Construct from an existing VKImage, downloading its pixel data.

	TextureContainer (const TextureContainer &)=delete

	TextureContainer (TextureContainer &&)=delete

	TextureContainer (uint32_t width, uint32_t height, ImageFormat format, uint32_t layers=1)
	Construct an empty container with declared dimensions.

std::shared_ptr< Core::VKImage >	to_image (uint32_t layer, const std::shared_ptr< Buffers::VKBuffer > &staging) const
	Refresh one layer's cached VKImage with caller-supplied staging.

std::shared_ptr< Core::VKImage >	to_image (uint32_t layer=0) const
	Refresh the container-owned VKImage for one layer.

std::shared_ptr< Core::VKImage >	to_image_array () const
	Upload all layers as a Vulkan 2D array texture.

std::shared_ptr< Core::VKImage >	to_image_array (const std::shared_ptr< Buffers::VKBuffer > &staging) const
	Upload all layers as a Vulkan 2D array texture, reusing a staging buffer.

bool	try_acquire_processing_token (int ch)

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

void	unregister_dimension_reader (uint32_t) override
	No-op.

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

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

bool	upload_image (const std::shared_ptr< Core::VKImage > &image, uint32_t layer, const std::shared_ptr< Buffers::VKBuffer > &staging) const
	Upload one layer into an existing VKImage instead of creating one.

bool	upload_image_array (const std::shared_ptr< Core::VKImage > &image, const std::shared_ptr< Buffers::VKBuffer > &staging) const
	Upload all layers into an existing VKImage instead of creating one.

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

	~TextureContainer () 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
uint32_t	append_image_layer (std::shared_ptr< Core::VKImage > image)
	Append one layer held on the GPU by `image`.

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	hold_layer (uint32_t layer)
	Mark `layer` as held on the GPU after its image was rewritten.

std::shared_ptr< Core::VKImage >	layer_image (uint32_t layer) const
	The GPU image backing `layer`, without uploading CPU pixels.

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

	TextureContainer (uint32_t width, uint32_t height, ImageFormat format, LayerCount layers)
	Construct with exactly `layers` layers, which may be zero.

Private Member Functions
std::shared_ptr< Core::VKImage >	cached_array_image (const std::shared_ptr< Buffers::VKBuffer > &staging) const

std::shared_ptr< Core::VKImage >	cached_layer_image (uint32_t layer, const std::shared_ptr< Buffers::VKBuffer > &staging) const

void	claim_cpu (uint32_t layer)
	Give a GPU-held layer fresh CPU storage before a full overwrite.

void	ensure_cpu (uint32_t layer) const
	Download a GPU-held layer into m_data before a CPU read.

void	ensure_cpu_all () const

auto	get_frame_typed (uint64_t frame_index) const -> DataSpanVariant

template<typename T >
auto	get_frame_typed_as (uint64_t frame_index) const -> std::span< const T >

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 >
void	get_frames_typed_as (std::span< T > output, uint64_t start_frame, uint64_t num_frames) const

void	setup_dimensions ()

Private Attributes
Portal::Graphics::ImageCacheEntry	m_array_image_cache

size_t	m_bpp {}

Memory::Seqlock	m_cb_lock

std::shared_ptr< DataProcessingChain >	m_chain

uint32_t	m_channels {}

std::vector< std::atomic< bool > >	m_cpu_stale
	Per layer: the GPU image in m_layer_image_cache holds the content, m_data does not.

std::vector< DataVariant >	m_data

ImageFormat	m_format {}

std::vector< double >	m_frame_cache
	Row cache backing the double span returned by get_frame().

uint32_t	m_height {}

Memory::Seqlock	m_image_cache_lock

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

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

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

std::vector< DataVariant >	m_processed_data

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

std::atomic< int >	m_processing_token { -1 }

std::shared_ptr< DataProcessor >	m_processor

std::atomic< bool >	m_ready_for_processing { false }

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

Memory::Seqlock	m_region_lock

Memory::SeqlockArray	m_slot_locks

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

ContainerDataStructure	m_structure

uint32_t	m_width {}

Detailed Description

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.

Definition at line 42 of file TextureContainer.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