MayaFlux::Yantra::TextureExecutionContext Class Reference

GpuExecutionContext specialisation for image compute shaders. More...

#include <TextureExecutionContext.hpp>

Inheritance diagram for MayaFlux::Yantra::TextureExecutionContext:

Collaboration diagram for MayaFlux::Yantra::TextureExecutionContext:

Classes
struct	ImageSlot
	One declared image binding: its GpuBufferBinding descriptor, the currently staged VKImage, and cached dimensions. More...

Public Types
using	Base = GpuExecutionContext< std::vector< Kakshya::DataVariant >, std::vector< Kakshya::DataVariant > >
enum class	OutputMode : uint8_t { CONTAINER , SCALAR , IMAGE }
Public Types inherited from MayaFlux::Yantra::GpuExecutionContext< std::vector< Kakshya::DataVariant >, std::vector< Kakshya::DataVariant > >
using	input_type = Datum< InputType >
using	output_type = Datum< OutputType >

Public Member Functions
void	clear_output_dimensions ()
output_type	collect_container_result ()
	Collect the output TextureContainer after a signaled async dispatch.
GpuChannelResult	collect_result ()
	Collect SSBO readback after a signaled async dispatch.
Portal::Graphics::FenceID	dispatch_async (const input_type &input)
	Non-blocking dispatch.
output_type	execute (const input_type &input, const ExecutionContext &ctx) override
	Override for CHAINED mode: skips collect_gpu_outputs().
void	prepare_output_image (uint32_t width, uint32_t height)
	Allocates the output storage image and stages it at the declared output binding.
void	set_avoid_output_alias (bool enabled)
	Select a distinct cached output image when the input is the current output image.
void	set_input_layer (uint32_t layer)
	Set the array layer staged from the input TextureContainer on the next dispatch_async call.
void	set_output_dimensions (uint32_t w, uint32_t h)
	Override the output storage image dimensions for the next dispatch.
GpuBufferBinding &	slot_binding (uint32_t binding_index)
	Direct access to an image slot's binding descriptor by index.
void	stage_container (const Kakshya::TextureContainer &container, uint32_t layer=0, vk::Sampler sampler=nullptr)
	Stage a TextureContainer layer at the declared input image binding.
void	stage_image (const std::shared_ptr< Core::VKImage > &image, vk::Sampler sampler=nullptr)
	Stage an arbitrary VKImage at the declared input image binding.
	TextureExecutionContext (GpuComputeConfig config, const std::vector< GpuBufferBinding > &bindings, OutputMode mode=OutputMode::SCALAR)
	Construct from an explicit, fully-specified binding list.
	TextureExecutionContext (GpuComputeConfig config, Portal::Graphics::ImageFormat output_format=Portal::Graphics::ImageFormat::RGBA8, OutputMode mode=OutputMode::CONTAINER, uint32_t image_binding=1, std::vector< GpuBufferBinding > aux_bindings={}, GpuBufferBinding::ElementType image_access=GpuBufferBinding::ElementType::IMAGE_SAMPLED, uint32_t output_binding=0)
Public Member Functions inherited from MayaFlux::Yantra::GpuExecutionContext< std::vector< Kakshya::DataVariant >, std::vector< Kakshya::DataVariant > >
	GpuExecutionContext (const GpuExecutionContext &)=delete
	GpuExecutionContext (GpuComputeConfig config)
	GpuExecutionContext (GpuExecutionContext &&)=delete
GpuExecutionContext &	operator= (const GpuExecutionContext &)=delete
GpuExecutionContext &	operator= (GpuExecutionContext &&)=delete
	~GpuExecutionContext () override=default
Public Member Functions inherited from MayaFlux::Yantra::GpuDispatchCore
const std::string &	dispatch_key () const
	The key used for this context's GpuResourceManager unit.
void	download_binding (size_t index, void *dest, size_t byte_size)
	Read back a specific binding into a caller-provided destination.
void	download_shared (uint32_t set, size_t binding_index, void *dest, size_t byte_size)
bool	ensure_gpu_ready ()
	Ensure GPU resources are initialised.
void	ensure_shared_buffer (uint32_t set, size_t binding_index, size_t element_count, GpuBufferBinding::ElementType element_type, Portal::Graphics::BufferUsageHint usage_hint=Portal::Graphics::BufferUsageHint::COMPUTE_STORAGE)
	Ensure a shared storage buffer of at least element_count elements exists at (set, binding_index).
std::shared_ptr< Core::VKImage >	get_output_image (size_t binding_index) const
	Return the image registered at an IMAGE_STORAGE output binding.
	GpuDispatchCore (const GpuDispatchCore &)=delete
	GpuDispatchCore (GpuComputeConfig config)
	GpuDispatchCore (GpuDispatchCore &&)=delete
bool	is_gpu_ready () const
	Query GPU readiness without attempting initialisation.
GpuDispatchCore &	operator= (const GpuDispatchCore &)=delete
GpuDispatchCore &	operator= (GpuDispatchCore &&)=delete
template<typename T >
void	set_binding_data (size_t index, const std::vector< T > &data)
template<typename T >
void	set_binding_data (size_t index, std::span< const T > data)
	Pre-stage typed data for a specific binding slot, bypassing the default channel-flattening path in prepare_gpu_inputs.
void	set_output_size (size_t index, size_t byte_size)
	Declare the byte capacity of an output binding independently of input data.
template<typename T >
void	set_push_constants (const T &data)
	Typed convenience wrapper for set_push_constants(const void*, size_t).
void	set_push_constants (const void *data, size_t bytes)
	Set push constant data from a raw byte pointer.
Portal::Graphics::GpuBufferHandle	shared_buffer_handle (uint32_t set, size_t binding_index) const
	Non-owning view of the shared buffer at (set, binding_index).
Portal::Graphics::HazardResource	shared_buffer_hazard (const GpuBufferBinding &spec) const
void	stage_image_at (size_t binding_index, std::shared_ptr< Core::VKImage > image, GpuBufferBinding::ElementType kind, vk::Sampler sampler=nullptr)
	Register a VKImage at an explicit binding index.
void	swap_shader (GpuComputeConfig config)
	Switch which shader subsequent dispatch_core calls target.
void	upload_shared_raw (uint32_t set, size_t binding_index, const uint8_t *data, size_t byte_size)
virtual	~GpuDispatchCore ()=default

Protected Member Functions
std::array< uint32_t, 3 >	calculate_dispatch_size (size_t total_elements, const DataStructureInfo &structure_info) const override
	Derives dispatch size from the staged container dimensions when available; falls back to element-count dispatch otherwise.
output_type	collect_gpu_outputs (const GpuChannelResult &, const std::vector< std::vector< double > > &, const DataStructureInfo &) override
	In CONTAINER mode: downloads the storage image at the declared output binding into a new TextureContainer placed in output.container.
std::vector< GpuBufferBinding >	declare_buffer_bindings () const override
	Declare the image bindings from m_image_slots, plus any aux SSBO bindings provided at construction.
std::pair< std::vector< std::vector< double > >, DataStructureInfo >	extract_inputs (const input_type &input) override
	Stashes the TextureContainer from datum.container for use in on_before_gpu_dispatch; returns empty channels (image shaders do not use the numeric channel path).
void	on_before_gpu_dispatch (const std::vector< std::vector< double > > &, const DataStructureInfo &) override
	Stages the pending TextureContainer at the declared input image binding and, in CONTAINER or IMAGE mode, allocates the output storage image at the declared output binding.
Protected Member Functions inherited from MayaFlux::Yantra::GpuDispatchCore
GpuChannelResult	dispatch_core (const std::vector< std::vector< double > > &channels, const DataStructureInfo &structure_info)
	Full single-pass dispatch.
Portal::Graphics::FenceID	dispatch_core_async (const std::vector< std::vector< double > > &channels, const DataStructureInfo &structure_info)
	Non-blocking variant of dispatch_core.
GpuChannelResult	dispatch_core_chained (const std::vector< std::vector< double > > &channels, const DataStructureInfo &structure_info, const ExecutionContext &ctx)
	Multi-pass (chained) dispatch.
GpuChannelResult	dispatch_core_chained_indirect (const std::vector< std::vector< double > > &channels, const DataStructureInfo &structure_info, const ExecutionContext &ctx)
	Multi-pass dispatch where a GPU-resident indirect buffer gates each pass's workgroup count instead of a fixed pass_count.
void	dispatch_core_dependency (const std::vector< DependencyStage > &stages)
	Multi-pipeline dependency dispatch.
Portal::Graphics::FenceID	dispatch_core_dependency_async (const std::vector< DependencyStage > &stages)
	Non-blocking variant of dispatch_core_dependency.
size_t	find_first_output_index () const
void	flatten_channels_to_staging (const std::vector< std::vector< double > > &channels, const DataStructureInfo &structure_info)
	Flatten planar double channels into m_staging_floats.
void	flatten_native_variants_to_staging (const std::vector< Kakshya::DataVariant > &variants, const DataStructureInfo &structure_info)
	Flatten native-typed DataVariant channels into m_native_staging_bytes without any conversion.
const GpuComputeConfig &	gpu_config () const
size_t	largest_binding_data_element_count () const
size_t	last_effective_element_count () const
	Effective element count used by the last dispatch_core or dispatch_core_async call.
virtual void	prepare_gpu_inputs (const std::vector< std::vector< double > > &channels, const DataStructureInfo &structure_info)
	Marshal channel data into GPU input buffers.
void	readback_aux (GpuChannelResult &result)
	Read back all OUTPUT bindings that have explicit size overrides into the aux map of a GpuChannelResult.
std::vector< float >	readback_primary (size_t float_count)
	Read back the primary output buffer into a float vector.
void	stage_native_bytes (size_t binding_index, const void *data, size_t byte_size)
	Stage a flat native-typed byte buffer for FLOAT32 bindings, bypassing the double-to-float cast in flatten_channels_to_staging.
void	stage_passthrough (size_t binding_index, const void *data, size_t byte_size)
	Stage raw bytes for a PASSTHROUGH binding before dispatch.

Private Types
using	ImageKey = Portal::Graphics::ImageKey

Private Member Functions
std::shared_ptr< Core::VKImage >	acquire_output_image (ImageSlot &slot, uint32_t width, uint32_t height, bool alternate=false)
	Return this slot's cached image for these creation parameters, creating and caching one when there is none.
std::shared_ptr< Core::VKImage >	container_image (const Kakshya::TextureContainer &container, uint32_t layer)
	The container's pixels as a GPU image, without allocating one per call.
ImageSlot &	input_slot ()
	Find the declared input image slot.
ImageSlot &	output_slot ()
	Find the declared output image slot.

Static Private Member Functions
static std::shared_ptr< Kakshya::TextureContainer >	resolve_texture_container (const input_type &input)
	Extracts a TextureContainer pointer from datum.container if present.

Private Attributes
std::vector< GpuBufferBinding >	m_aux_bindings
bool	m_avoid_output_alias { false }
std::shared_ptr< Buffers::VKBuffer >	m_download_staging
std::vector< ImageSlot >	m_image_slots
Portal::Graphics::ImageCacheEntry	m_input_cache
std::shared_ptr< Kakshya::TextureContainer >	m_output_container
std::optional< std::pair< uint32_t, uint32_t > >	m_output_dim_override
Portal::Graphics::ImageFormat	m_output_format
OutputMode	m_output_mode
std::shared_ptr< Kakshya::TextureContainer >	m_pending_container
uint32_t	m_pending_layer {}
std::shared_ptr< Buffers::VKBuffer >	m_upload_staging

Static Private Attributes
static constexpr size_t	k_slot_cache_budget_bytes = size_t { 256 } << 20

Additional Inherited Members
Protected Attributes inherited from MayaFlux::Yantra::GpuDispatchCore
std::vector< std::vector< uint8_t > >	m_binding_data
std::vector< GpuBufferBinding >	m_bindings
std::vector< ImageBinding >	m_image_bindings
std::vector< size_t >	m_output_size_overrides
std::vector< std::vector< uint8_t > >	m_passthrough_bytes
std::vector< uint8_t >	m_push_constants
GpuResourceManager	m_resources
std::vector< float >	m_staging_floats

Detailed Description

GpuExecutionContext specialisation for image compute shaders.

Accepts DataIO (Datum<vector<DataVariant>>) as both input and output, matching the standard ComputeOperation contract. Image staging is driven by the optional container field on the input Datum:

• When datum.container holds a TextureContainer, extract_inputs() stashes it and on_before_gpu_dispatch() uploads it to a VKImage staged at the declared image input binding. This is the preferred path: the container carries format, layer count, mip metadata, and sampler config.
• When datum.container is absent or not a TextureContainer, no image staging occurs. The shader receives whatever bindings the caller declared via set_binding_data / stage_passthrough / stage_image_sampled directly. dispatch_async still works; it is a no-op on the image side.

Output options (select one at construction):

OutputMode::CONTAINER — the storage image at binding 0 is downloaded into a new TextureContainer and placed in the output Datum's container field. Primary float readback is empty. Mirrors the original behaviour for texture-transform pipelines (blur, colour grade, format convert).

OutputMode::SCALAR — no image download. collect_result() returns the primary float readback and aux SSBOs from GpuChannelResult, exactly as ShaderExecutionContext does. Use for reduction shaders that write a small SSBO (spatial average, histogram, region sample) and feed the node graph.

dispatch_async / collect_result mirror ShaderExecutionContext so GpuComputeNode can own this class without modification.

calculate_dispatch_size() uses image dimensions when a TextureContainer is present, otherwise falls through to the standard element-count path.

A context has one owner. Its image cache is accessed only after the previous dispatch has completed, so ImageCacheSet::acquire and TextureLoom::acquire_cached_image are not synchronized here. Do not invoke dispatch or image staging concurrently on the same context.

Definition at line 56 of file TextureExecutionContext.hpp.

---

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

• TextureExecutionContext.hpp