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 |
|---|---|---|
|
Allocated by its constructor; released by its destructor |
One allocation |
|
Allocated during graph compilation |
One independent allocation per path |
|
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 |
|---|---|---|
|
Map the allocation directly |
Small, frequent CPU updates |
|
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
sizeelements of typeTin 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 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.
-
virtual void _setup(VulkanContext &vulkanContext, uint32_t numberPaths, VkQueue setupQueue = VK_NULL_HANDLE) override = 0¶
-
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.
-
virtual BufferType &getBuffer(uint32_t pathId) = 0¶