Buffers

klartraum::VulkanBuffer owns a typed Vulkan allocation. klartraum::BufferElement makes that storage available to a compute graph, with one allocation per render path.

Type

Allocation lifetime

Sharing

VulkanBuffer<T>

Allocated by its constructor; released by its destructor

One allocation

BufferElement<VulkanBuffer<T>>

Allocated during graph compilation

One independent allocation per path

BufferElementSinglePath<VulkanBuffer<T>>

Allocated by its constructor

One allocation shared by every path

BufferElement defers allocation because the number of paths is supplied during graph compilation. Its constructor stores the capacity, usage and memory properties. When compileFrom() calls _setup(context, numberPaths), it creates one buffer for each path. This supports independent per-frame inputs and outputs.

BufferElementSinglePath already knows it needs exactly one buffer. Its constructor directly constructs its VulkanBuffer member, which allocates immediately. Its _setup() does nothing, and getBuffer(pathId) ignores the path index.

The Vulkan context must outlive the allocations. Finish GPU use before destroying them. Shared single-path buffers are useful for model data that stays unchanged while several paths read it.

CPU access and memory placement

The usage flags describe GPU operations, such as storage-buffer or indirect-draw access. The memory flags select a memory type. Transfer-source and transfer-destination usage are enabled automatically by VulkanBuffer.

Requested memory flags

CPU copy helpers

Typical use

HOST_VISIBLE_BIT | HOST_COHERENT_BIT (default)

Map the allocation directly

Small, frequent CPU updates

DEVICE_LOCAL_BIT, without HOST_VISIBLE_BIT

Copy through temporary coherent staging buffers

GPU model data and working buffers

These names abbreviate the VK_MEMORY_PROPERTY_ flags. Device-local and host-visible properties can coexist on a memory type. The helpers choose mapping or staging from the requested HOST_VISIBLE_BIT; getMemoryProperties() reports the actual selected memory type’s flags.

Direct mapping requires coherent host-visible memory: these helpers do not flush or invalidate non-coherent allocations. Coherence does not replace synchronization; wait for conflicting GPU work before CPU access. For engine-driven per-frame uploads, use setFrameUpdate() to update only the acquired path.

Staged uploads, readback, GPU prefix copies and device-local zero() wait for the graphics queue to become idle. Use them for initialization and explicit readback. Per-frame GPU processing stays in shaders and recorded command buffers.

With an initialized VulkanContext vc, both access modes use the same copy API:

std::vector<float> data{1, 2, 3, 4};

klartraum::VulkanBuffer<float> cpuUpdates(vc, 4);
cpuUpdates.memcopyFrom(data);

klartraum::VulkanBuffer<float> gpuData(
    vc, 4, VK_BUFFER_USAGE_STORAGE_BUFFER_BIT,
    VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT);
gpuData.memcopyFrom(data);

std::vector<float> result(4);
gpuData.memcopyTo(result);

Graph paths

See Paths for path IDs and resource isolation.

Connect buffer elements before compileFrom() and access per-path allocations after compilation. For example, a two-path graph can copy mapped input to device-local output:

using Floats = klartraum::VulkanBuffer<float>;
auto input = std::make_shared<klartraum::BufferElement<Floats>>(vc, 4);
auto output = std::make_shared<klartraum::BufferElement<Floats>>(
    vc, 4, VK_BUFFER_USAGE_STORAGE_BUFFER_BIT,
    VK_MEMORY_PROPERTY_DEVICE_LOCAL_BIT);
auto copy = std::make_shared<klartraum::CopyBuffer>(vc);
copy->setInput(input, 0);
copy->setInput(output, 1);

klartraum::ComputeGraph graph(vc, 2);
graph.compileFrom(copy);
input->getBuffer(0).memcopyFrom(data);
graph.submitAndWait(vc.getGraphicsQueue(), 0);
output->getBuffer(0).memcopyTo(result);

BufferElement::zero() immediately clears every path. Configure setRecordToZero(), setRecordToZeroRange() or setRecordToFill() before compilation to perform fills on the GPU each time the graph runs.

Allocation API

template<typename T>
class VulkanBuffer

Vulkan buffer of size elements of type T in host-visible, host-coherent memory.

The usage flags default to storage buffer and transfer destination. memcopyFrom() and memcopyTo() copy between host memory and the buffer; zero() sets it to zero.

Graph buffer API

template<typename BufferType>
class BufferElement : public klartraum::TemplatedBufferElementInterface<BufferType>

Owns one independent buffer per compute-graph path.

Graph compilation creates the allocations. Access getBuffer(pathId) after compilation and synchronize that path’s GPU use before CPU transfers. VulkanBuffer allocations default to coherent host-visible memory.

Template Parameters:

BufferType – Buffer implementation, usually VulkanBuffer<T>.

Public Functions

inline BufferElement(VulkanContext &vulkanContext, uint32_t numberElements)

Configures per-path capacity using the buffer type’s default usage and memory properties.

inline BufferElement(VulkanContext &vulkanContext, uint32_t numberElements, VkBufferUsageFlags flags)

Configures GPU usage and per-path capacity, with coherent host-visible memory.

inline BufferElement(VulkanContext &vulkanContext, uint32_t numberElements, VkBufferUsageFlags flags, VkMemoryPropertyFlags memory)

Configures per-path buffers with explicit usage and memory properties.

Parameters:
  • vulkanContext – Context owning the device; it must outlive the allocations.

  • numberElements – Capacity of each buffer in elements.

  • flags – GPU buffer usage flags.

  • memory – Required memory properties; pass DEVICE_LOCAL without HOST_VISIBLE for staged CPU access.

inline virtual void _setup(VulkanContext &vulkanContext, uint32_t numberPaths, VkQueue setupQueue = VK_NULL_HANDLE)

Initializes resources for the graph paths.

Parameters:
  • vulkanContext – The context providing the resources and queues.

  • numberPaths – The number of execution paths.

  • setupQueue – The queue for uploads and immediate submissions. VK_NULL_HANDLE uses the graphics queue. Pass this queue to nested elements.

inline virtual size_t getBufferMemSize() const

Returns the byte capacity of one buffer after setup.

inline virtual BufferType &getBuffer(uint32_t pathId)

Returns the allocation for pathId after graph compilation.

inline void zero()

Immediately clears every path through the underlying buffer’s zero() helper.

inline void setRecordToZero(bool _setToZero)

Configures whole-buffer GPU zeroing on each submission; set before graph compilation.

inline void setRecordToZeroRange(VkDeviceSize byteOffset, VkDeviceSize byteSize)

Configures a GPU-cleared byte range on each submission, preserving other fields.

Note

Set before graph compilation. Range zeroing takes precedence over whole-buffer zeroing and filling.

Parameters:
  • byteOffset – Start of the range in bytes.

  • byteSize – Length of the range in bytes.

inline void setRecordToFill(uint32_t value)

Configures a repeating 32-bit GPU fill pattern for each submission.

Note

Set before graph compilation. Zeroing options take precedence over filling.

Parameters:

value – Pattern to repeat, e.g. a sort-key sentinel.

inline virtual VkBuffer &getVkBuffer(uint32_t pathId)

Returns the Vulkan handle for an initialized path.

template<typename BufferType>
class BufferElementSinglePath : public klartraum::TemplatedBufferElementInterface<BufferType>

Owns one buffer shared by every compute-graph path.

Construction forwards its arguments to BufferType and allocates immediately. The path index is ignored. Use shared storage for data such as immutable models; writes must be synchronized with GPU use across all paths.

Template Parameters:

BufferType – Buffer implementation, usually VulkanBuffer<T>.

Public Functions

template<typename ...Args>
inline BufferElementSinglePath(Args&&... args)

Constructs the shared buffer with the supplied allocation arguments.

inline virtual void _setup(VulkanContext &vulkanContext, uint32_t numberPaths, VkQueue setupQueue = VK_NULL_HANDLE)

Initializes resources for the graph paths.

Parameters:
  • vulkanContext – The context providing the resources and queues.

  • numberPaths – The number of execution paths.

  • setupQueue – The queue for uploads and immediate submissions. VK_NULL_HANDLE uses the graphics queue. Pass this queue to nested elements.

inline virtual size_t getBufferMemSize() const

Returns the byte capacity of one buffer after setup.

inline virtual BufferType &getBuffer(uint32_t pathId = 0)

Returns the shared typed allocation; pathId is ignored.

inline virtual VkBuffer &getVkBuffer(uint32_t pathId = 0)

Returns the shared Vulkan handle; pathId is ignored.

Interfaces

class BufferElementInterface : public klartraum::ComputeGraphElement

Untyped graph interface for a path’s Vulkan buffer handle and byte capacity.

Subclassed by klartraum::TemplatedBufferElementInterface< R >, klartraum::TemplatedBufferElementInterface< VulkanBuffer< T > >, klartraum::TemplatedBufferElementInterface< BufferType >, klartraum::TensorElementInterface

Public Functions

virtual void _setup(VulkanContext &vulkanContext, uint32_t numberPaths, VkQueue setupQueue = VK_NULL_HANDLE) override = 0

Initializes resources for the graph paths.

Parameters:
  • vulkanContext – The context providing the resources and queues.

  • numberPaths – The number of execution paths.

  • setupQueue – The queue for uploads and immediate submissions. VK_NULL_HANDLE uses the graphics queue. Pass this queue to nested elements.

virtual size_t getBufferMemSize() const = 0

Returns the byte capacity of one buffer after setup.

virtual VkBuffer &getVkBuffer(uint32_t pathId) = 0

Returns the Vulkan handle for an initialized path.

template<typename BufferType>
class TemplatedBufferElementInterface : public klartraum::BufferElementInterface

Buffer element whose buffers have the type BufferType; getBuffer() returns the buffer of one path.

Subclassed by klartraum::BufferElement< VulkanBuffer< T > >, klartraum::BufferElement< BufferType >, klartraum::BufferElementSinglePath< BufferType >

Public Functions

virtual BufferType &getBuffer(uint32_t pathId) = 0

Returns the typed allocation for an initialized path.