GPU-resident, double-buffered SSBO state for synchronous local-rule systems evaluated over a fixed 2D topology: cellular automata, Jacobi/Gauss-Seidel relaxation, discrete diffusion, and any rule where every cell updates from its own and neighbors' previous-generation state. More...

#include <RelaxationGridBuffer.hpp>

Inheritance diagram for MayaFlux::Buffers::RelaxationGridBuffer:

Collaboration diagram for MayaFlux::Buffers::RelaxationGridBuffer:

Public Types
using	ShaderSource = std::variant< std::string, Portal::Graphics::ShaderSpec >
	Either a shader file path or a generated ShaderSpec, resolved at construction time by setup_processors().

Public Types inherited from MayaFlux::Buffers::VKBuffer
using	RenderConfig = Portal::Graphics::RenderConfig

using	Usage = Portal::Graphics::BufferUsageHint

Public Member Functions
uint32_t	back_index () const
	Index into m_resources.back_buffers currently serving as the write target for the next rule dispatch.

std::shared_ptr< RelaxationEmitProcessor >	emit_processor () const
	The attached emit-stage processor, valid after setup_processors().

uint32_t	front_index () const
	Index into m_resources.back_buffers currently holding the most recently completed generation's state.

uint32_t	get_cell_count () const
	Total cell count, width * height.

uint32_t	get_grid_height () const
	Grid height in cells.

uint32_t	get_grid_width () const
	Grid width in cells.

size_t	get_state_bytes () const
	Total byte size of one generation's state buffer.

	RelaxationGridBuffer (uint32_t width, uint32_t height, size_t cell_stride_bytes, ShaderSource rule_source, ShaderSource emit_source)
	Construct an unregistered double-buffered grid buffer.

void	request_snapshot ()
	Request a snapshot of the next completed generation.

void	seed_state (const void *data, size_t size)
	Write initial state directly into the current front generation.

void	setup_processors (ProcessingToken token) override
	Create and attach RelaxationStepProcessor (default processor) and RelaxationEmitProcessor (flat processor), and set the per-cell vertex layout on this buffer's own storage.

void	setup_rendering (const RenderConfig &config)
	Attach a RenderProcessor drawing the emitted vertex output as ordinary untextured point geometry.

std::shared_ptr< Vruta::BroadcastSource< std::vector< uint8_t > > >	snapshot_source () const
	BroadcastSource of completed generation snapshots.

std::shared_ptr< RelaxationStepProcessor >	step_processor () const
	The attached rule-stage processor, valid after setup_processors().

	~RelaxationGridBuffer () override=default
	Destructor.

Public Member Functions inherited from MayaFlux::Buffers::VKBuffer
void	clear () override
	Clear buffer contents.

void	clear_pipeline_commands ()
	Clear all recorded commands (called after presentation)

void	clear_vertex_layout ()
	Clear vertex layout.

std::shared_ptr< Buffer >	clone_to (uint8_t dest_desc) override
	Creates a clone of this buffer for a specific channel or usage enum.

std::shared_ptr< VKBuffer >	clone_to (Usage usage)
	Create a clone of this buffer with the same data and properties.

void	enforce_default_processing (bool should_process) override
	Controls whether the buffer should use default processing.

void	force_internal_usage (bool internal) override
	Set whether this buffer is for internal engine usage.

std::vector< std::pair< size_t, size_t > >	get_and_clear_dirty_ranges ()
	Retrieve and clear all dirty ranges.

std::vector< std::pair< size_t, size_t > >	get_and_clear_invalid_ranges ()
	Retrieve and clear all invalid ranges.

vk::Buffer &	get_buffer ()
	Get VkBuffer handle (VK_NULL_HANDLE if not registered)

VKBufferResources &	get_buffer_resources ()
	Get all buffer resources at once (mutable).

const VKBufferResources &	get_buffer_resources () const
	Get all buffer resources at once (read-only)

std::vector< Kakshya::DataVariant >	get_data ()
	Read buffer contents as Kakshya DataVariant.

std::shared_ptr< Buffers::BufferProcessor >	get_default_processor () const override
	Get the currently attached default processor.

uint64_t	get_device_address () const
	Get the Vulkan device address for this buffer (if applicable)

const std::vector< Kakshya::DataDimension > &	get_dimensions () const
	Get the inferred data dimensions for the buffer contents.

EngineContext &	get_engine_context ()

const EngineContext &	get_engine_context () const

vk::Buffer	get_index_buffer () const
	Return the raw index buffer handle.

size_t	get_index_buffer_size () const
	Number of bytes in the index buffer.

void *	get_mapped_ptr () const
	Get mapped host pointer (nullptr if not host-visible or unmapped)

vk::MemoryPropertyFlags	get_memory_properties () const
	Get appropriate VkMemoryPropertyFlags for allocation based on Usage.

Kakshya::DataModality	get_modality () const
	Get the buffer's semantic modality.

CommandBufferID	get_pipeline_command (RenderPipelineID pipeline_id) const
	Get recorded command buffer for a pipeline.

PipelineContext &	get_pipeline_context ()
	Access the pipeline context for custom metadata (non-const)

const PipelineContext &	get_pipeline_context () const
	Access the pipeline context for custom metadata (const)

std::shared_ptr< Core::Window >	get_pipeline_window (RenderPipelineID id) const
	Get the window associated with this buffer.

std::shared_ptr< Buffers::BufferProcessingChain >	get_processing_chain () override
	Access the buffer's processing chain.

RenderConfig	get_render_config () const
	Get the current render configuration.

std::unordered_map< RenderPipelineID, std::shared_ptr< Core::Window > >	get_render_pipelines () const
	Get all render pipelines associated with this buffer.

virtual std::shared_ptr< RenderProcessor >	get_render_processor () const
	Get a RenderProcessor suitable for rendering this buffer.

size_t	get_size () const
	Get current logical size in bytes.

vk::DeviceSize	get_size_bytes () const

Usage	get_usage () const
	Retrieve the declared usage intent.

vk::BufferUsageFlags	get_usage_flags () const
	Get appropriate VkBufferUsageFlags for creation based on Usage.

std::optional< Kakshya::VertexLayout >	get_vertex_layout () const
	Get vertex layout if set.

bool	has_data_for_cycle () const override
	Checks if the buffer has data for the current processing cycle.

bool	has_index_buffer () const
	True when an index buffer has been associated with this buffer.

bool	has_render_pipeline () const
	Check if this buffer has a rendering pipeline configured.

bool	has_vertex_layout () const
	Check if this buffer has vertex layout configured.

bool	is_host_visible () const
	Whether this VKBuffer should be host-visible.

bool	is_initialized () const
	Check whether Vulkan handles are present (buffer registered)

bool	is_internal_only () const override
	Check whether this buffer is for internal engine usage.

bool	is_processing () const override
	Query whether the buffer is currently being processed.

bool	is_render_config_dirty () const
	Check if config has changed since last frame.

void	mark_dirty_range (size_t offset, size_t size)
	Get device memory handle.

void	mark_for_processing (bool has_data) override
	Marks the buffer's data availability for the current processing cycle.

void	mark_for_removal () override
	Marks the buffer for removal from processing chains.

void	mark_invalid_range (size_t offset, size_t size)
	Mark a range as invalid (needs download)

virtual void	mark_render_config_dirty (bool is_dirty=true)
	Mark config as changed (processors will detect and react)

bool	needs_default_processing () override
	Checks if the buffer should undergo default processing.

bool	needs_depth_attachment () const
	Check if this buffer requires depth attachment for rendering.

bool	needs_removal () const override
	Checks if the buffer should be removed from processing chains.

void	process_default () override
	Run the buffer's default processor (if set and enabled)

void	release_processing () override
	Release previously acquired processing lock.

void	resize (size_t new_size, bool preserve_data=false)
	Resize buffer and recreate GPU resources if needed.

void	set_buffer (vk::Buffer buffer)
	Set VkBuffer handle after backend allocation.

void	set_buffer_resources (const VKBufferResources &resources)
	Set all buffer resources at once.

void	set_data (const std::vector< Kakshya::DataVariant > &data)
	Write data into the buffer.

void	set_default_processor (const std::shared_ptr< BufferProcessor > &processor) override
	Set the buffer's default processor.

void	set_index_resources (vk::Buffer buf, vk::DeviceMemory mem, size_t size)
	Store raw index buffer handles produced by the geometry upload path.

void	set_mapped_ptr (void *ptr)
	Set mapped host pointer (for host-visible allocations)

void	set_memory (vk::DeviceMemory memory)
	Set device memory handle after backend allocation.

void	set_modality (Kakshya::DataModality modality)
	Update the semantic modality and re-infer dimensions.

void	set_needs_depth_attachment (bool needs)
	Mark this buffer as requiring depth testing when rendered.

void	set_pipeline_command (RenderPipelineID pipeline_id, CommandBufferID cmd_id)
	Store recorded command buffer for a pipeline.

void	set_pipeline_window (RenderPipelineID id, const std::shared_ptr< Core::Window > &window)
	Associate this buffer with a window for rendering.

void	set_processing_chain (const std::shared_ptr< BufferProcessingChain > &chain, bool force=false) override
	Replace the buffer's processing chain.

virtual void	set_render_config (const RenderConfig &config)
	Update the render configuration and mark as dirty.

void	set_render_processor (std::shared_ptr< RenderProcessor > rp)

void	set_vertex_layout (const Kakshya::VertexLayout &layout)
	Set vertex layout for this buffer.

bool	try_acquire_processing () override
	Try to acquire processing lock for this buffer.

	VKBuffer ()=default

	VKBuffer (size_t size_bytes, Usage usage, Kakshya::DataModality modality=Kakshya::DataModality::VERTICES_3D)
	Construct an unregistered VKBuffer.

	~VKBuffer () override
	Virtual destructor.

Public Member Functions inherited from MayaFlux::Buffers::Buffer
virtual	~Buffer ()=default
	Virtual destructor for proper resource management.

Private Member Functions
bool	consume_snapshot_request ()

void	swap_generation ()

Private Attributes
size_t	m_cell_stride_bytes
	Size in bytes of one cell's state, fixed at construction.

std::shared_ptr< RelaxationEmitProcessor >	m_emit_processor
	Emit stage, retained for parameter access.

ShaderSource	m_emit_source
	Either a path to a hand-written emit shader or a generated ShaderSpec.

bool	m_front_is_a { true }
	True when back_buffers[0] holds the current front generation.

uint32_t	m_height
	Grid height in cells.

ShaderSource	m_rule_source
	Either a path to a hand-written rule shader or a generated ShaderSpec.

std::atomic< bool >	m_snapshot_requested { false }
	Set by request_snapshot(), cleared by consume_snapshot_request().

std::shared_ptr< Vruta::BroadcastSource< std::vector< uint8_t > > >	m_snapshot_source
	Signaled by RelaxationStepProcessor when a requested snapshot completes.

std::shared_ptr< RelaxationStepProcessor >	m_step_processor
	Rule stage, retained for parameter access.

uint32_t	m_width
	Grid width in cells.

Friends
class	RelaxationEmitProcessor

class	RelaxationStepProcessor

Additional Inherited Members
Protected Member Functions inherited from MayaFlux::Buffers::VKBuffer
void	apply_render_config (const RenderConfig &config, const ShaderConfig &shader_config)
	Configure the internal m_render_processor from a RenderConfig.

void	apply_render_config (std::shared_ptr< RenderProcessor > &render_processor, const RenderConfig &config, const ShaderConfig &shader_config)
	Configure a RenderProcessor, creating one if null.

void	set_default_render_config (const RenderConfig &config)
	Called by derived classes to set their context-specific defaults.

Protected Attributes inherited from MayaFlux::Buffers::VKBuffer
RenderConfig	m_render_config

bool	m_render_config_dirty {}

std::shared_ptr< RenderProcessor >	m_render_processor

Detailed Description

GPU-resident, double-buffered SSBO state for synchronous local-rule systems evaluated over a fixed 2D topology: cellular automata, Jacobi/Gauss-Seidel relaxation, discrete diffusion, and any rule where every cell updates from its own and neighbors' previous-generation state.

Grid state lives entirely as two raw Vulkan handle pairs inside VKBufferResources::back_buffers, allocated once at construction. No VKBuffer object represents the grid state at any point; descriptor writes for these handles are issued directly against ShaderFoundry by RelaxationStepProcessor and RelaxationEmitProcessor, bypassing ShaderProcessor::bind_buffer entirely, since that call requires a VKBuffer wrapper this design does not create.

The VKBuffer base itself (this object) owns only the emitted vertex output (Usage::VERTEX), written each generation by RelaxationEmitProcessor from the front generation's state, then drawn directly by RenderProcessor as ordinary untextured point geometry.

Chain order: default — RelaxationStepProcessor (rule shader: state front -> back) flat[0] — RelaxationEmitProcessor (emit shader: front state -> vertices) final — RenderProcessor

Snapshot delivery uses a BroadcastSource<std::vector<uint8_t>>, owned by this buffer and exposed via snapshot_source(). RelaxationStepProcessor signals it directly once a requested download completes; there is no intermediate queue or poll. Subscribe via Kriya::on_signal() or on_signal_matching() at whatever cadence the caller chooses — the class imposes none.

Usage:

auto grid = std::make_shared<RelaxationGridBuffer>(
    256, 256, sizeof(uint32_t), "ca_rule.comp", "ca_emit.comp");
grid->setup_processors(ProcessingToken::GRAPHICS_BACKEND);
grid->setup_rendering({ .target_window = window });

Definition at line 54 of file RelaxationGridBuffer.hpp.

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

Public Types

Public Member Functions

Private Member Functions

Private Attributes

Friends

Additional Inherited Members

Detailed Description