GPU-resident state for multi-field simulations evaluated over a fixed 3D topology: incompressible fluid, gas and smoke, reaction systems, and any process where several quantities co-evolve over the same cell lattice. More...

#include <VolumeGridBuffer.hpp>

Inheritance diagram for MayaFlux::Buffers::VolumeGridBuffer:

Collaboration diagram for MayaFlux::Buffers::VolumeGridBuffer:

Classes
struct	Field

struct	FieldDecl
	One field's declaration within a volume. More...

struct	FlowConfig
	Parameters for the incompressible flow stage arrangement. More...

struct	FlowStages
	Every stage setup_flow built, in no particular order. More...

struct	SurfaceConfig
	Isosurface extraction parameters for a scalar field. More...

Public Member Functions
void	accumulate (const std::string &name, const Kinesis::SpatialField &field)
	Add sampled values into a scalar field.

void	accumulate (const std::string &name, const Kinesis::VectorField &field)
	Add sampled values into a vector field.

ScalarRef	declare_scalar (std::string name)
	Declare a double-buffered scalar field.

ScalarRef	declare_scratch (std::string name)
	Declare a single-slot scalar field.

VectorRef	declare_vector (std::string name)
	Declare a double-buffered vector field.

const Kinesis::AABB3D &	get_bounds () const
	World-space extent the lattice covers.

uint32_t	get_cell_count () const
	Total cell count.

glm::vec3	get_cell_size () const
	World-space size of one cell along each axis.

uint32_t	get_depth () const
	Cell count along Z.

size_t	get_field_bytes (const std::string &name) const
	Byte size of one slot of the named field, or 0 if undeclared.

std::vector< std::string >	get_field_names () const
	Names of every declared field, in declaration order.

uint32_t	get_height () const
	Cell count along Y.

const Kinesis::Lattice3D &	get_lattice () const
	The lattice every field is discretized over.

uint32_t	get_width () const
	Cell count along X.

bool	has_field (const std::string &name) const
	Whether a field of this name was declared.

std::shared_ptr< SDFMeshProcessor >	mesh_processor () const
	The marching cubes stage, valid after setup_rendering.

void	read_field (const std::string &name, void *data, size_t size)
	Copy the current read slot of a field to host memory.

vk::Buffer	read_handle (const std::string &name) const
	Handle a stage should read the named field from.

void	seed (const std::string &name, const Kinesis::SpatialField &field)
	Write initial values into a scalar field from a Kinesis field.

void	seed (const std::string &name, const Kinesis::VectorField &field)
	Write initial values into a vector field from a Kinesis field.

void	seed_raw (const std::string &name, const void *data, size_t size)
	Write initial values into a field from raw host memory.

FlowStages	setup_flow (const FlowConfig &config)
	Build and append the incompressible flow stages.

void	setup_processors (ProcessingToken token) override
	Establish the processing chain without attaching any stage.

void	setup_rendering (const RenderConfig &config)
	Attach a RenderProcessor drawing the extracted surface.

std::shared_ptr< VolumeSurfaceProcessor >	surface_processor () const
	The surface extraction stage, valid after setup_rendering.

void	swap_field (const std::string &name)
	Exchange read and write slots for the named field.

	VolumeGridBuffer (Kinesis::Lattice3D lattice, std::initializer_list< FieldDecl > fields, std::optional< SurfaceConfig > surface=std::nullopt)
	Construct an unregistered multi-field volume.

	VolumeGridBuffer (Kinesis::Lattice3D lattice, std::optional< SurfaceConfig > surface=std::nullopt)
	Construct a volume with no fields, to be declared after.

	VolumeGridBuffer (Kinesis::Lattice3D lattice, std::vector< FieldDecl > fields, std::optional< SurfaceConfig > surface=std::nullopt)
	Construct from a runtime-built field list.

vk::Buffer	write_handle (const std::string &name) const
	Handle a stage should write the named field to.

	~VolumeGridBuffer () override
	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	allocate_field (const std::string &name, size_t stride_bytes, bool double_buffered)
	Allocate one field's slots and register it.

void	allocate_fields (const std::vector< FieldDecl > &decls)
	Populate m_fields from declarations.

const Field *	find_field (const std::string &name, const char *context) const
	Resolve a field by name.

Static Private Member Functions
static size_t	surface_storage_bytes (const std::optional< SurfaceConfig > &surface)
	Bytes of vertex storage the extraction resolution requires.

Private Attributes
std::shared_ptr< VKBuffer >	m_counter_buf
	Atomic vertex counter for the extraction stage.

std::vector< std::string >	m_field_order

std::unordered_map< std::string, Field >	m_fields

Kinesis::Lattice3D	m_lattice

std::shared_ptr< SDFMeshProcessor >	m_mesh_processor

TransferHandle	m_pending_transfer
	In-flight seed upload, resolved before the next transfer.

std::optional< SurfaceConfig >	m_surface

std::shared_ptr< VolumeSurfaceProcessor >	m_surface_processor

std::shared_ptr< VKBuffer >	m_transfer_staging
	Reused across seed and read calls.

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

using	Usage = Portal::Graphics::BufferUsageHint

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 state for multi-field simulations evaluated over a fixed 3D topology: incompressible fluid, gas and smoke, reaction systems, and any process where several quantities co-evolve over the same cell lattice.

Where RelaxationGridBuffer carries one field over a 2D topology and advances it with one rule dispatch per cycle, this carries N named fields over a 3D topology and advances them with a chain of processors, each responsible for one stage. A velocity field, a pressure field, a divergence scratch field and one or more carried scalars are the ordinary case; nothing in the class knows what any of them mean.

All field storage lives as raw Vulkan handle pairs inside VKBufferResources::back_buffers, allocated once at construction as device-local with transfer source and destination usage. Fields are addressed by name; each declares its own component stride and whether it needs a second slot for ping-pong. Single-slot fields resolve read and write to the same handle, which suits scratch quantities recomputed from nothing each stage.

No VKBuffer object represents any field. Processors write descriptors for these handles directly against ShaderFoundry, as RelaxationStepProcessor does, resolving them through read_handle() and write_handle().

Chain layout: default - VolumeSurfaceProcessor, resampling the surfaced field flat[0] - SDFMeshProcessor, extracting the isosurface flat[1..] - simulation stages, added by the caller at any point final - RenderProcessor

Extraction occupies the default and first flat slots so that simulation stages appended by the caller always follow it. The surface therefore reflects the previous cycle's field rather than the current one, which at frame rate is not observable.

The VKBuffer base owns no vertex output. Extraction is a separate concern: attach SDFMeshProcessor against a scalar field for an isosurface, or a bespoke processor for raymarching or debug points. The buffer emits nothing on its own.

Usage:

auto vol = std::make_shared<VolumeGridBuffer>(
    64, 64, 64,
    { { "velocity", sizeof(glm::vec4) },
      { "pressure", sizeof(float) },
      { "divergence", sizeof(float), false },
      { "density", sizeof(float) } },
    Kinesis::AABB3D { { -1, -1, -1 }, { 1, 1, 1 } });
 
vol->seed("density", Kinesis::SpatialField { ... });
vol->setup_processors(ProcessingToken::GRAPHICS_BACKEND);

Definition at line 142 of file VolumeGridBuffer.hpp.

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

Classes

Public Member Functions

Private Member Functions

Static Private Member Functions

Private Attributes

Additional Inherited Members

Detailed Description