KDGpu::Buffer

Module: Public API

Represents a GPU memory buffer for storing vertex, index, uniform data, etc. More...

#include <KDGpu/buffer.h>

Public Functions

	Name
	~Buffer()
	Buffer()
	Buffer(Buffer && other)
Buffer &	operator=(Buffer && other)
	Buffer(const Buffer & ) =delete
Buffer &	operator=(const Buffer & ) =delete
const Handle< Buffer_t > &	handle() const
bool	isValid() const
	operator Handle< Buffer_t >() const
void *	map()
void	unmap()
void	invalidate()
void	flush()
MemoryHandle	externalMemoryHandle() const
BufferDeviceAddress	bufferDeviceAddress() const

Friends

	Name
class	Device
class	Queue
KDGPU_EXPORT bool	operator==(const Buffer & a, const Buffer & b)

Detailed Description

class KDGpu::Buffer;

Represents a GPU memory buffer for storing vertex, index, uniform data, etc.

Vulkan equivalent:VkBuffer

Buffer represents a linear allocation of GPU memory that can store vertices, indices, uniform data, storage buffers, or any other structured data needed by shaders.

Key features:

• CPU-visible mapping for reading/writing buffer contents
• Various usage flags (vertex, index, uniform, storage, transfer)
• Memory placement control (CPU, GPU, or CPU->GPU)
• Buffer device addresses for bindless rendering

Lifetime: Buffers are created by Device and must remain valid while referenced by GPU commands. They use RAII and clean up automatically when destroyed.

Usage

Creating a vertex buffer:

    struct Vertex {
        float position[3];
        float color[3];
    };

    std::vector<Vertex> vertices = { /* ... */ };

    KDGpu::Buffer vertexBuffer = device.createBuffer(KDGpu::BufferOptions{
                                                             .size = vertices.size() * sizeof(Vertex),
                                                             .usage = KDGpu::BufferUsageFlagBits::VertexBufferBit,
                                                             .memoryUsage = KDGpu::MemoryUsage::CpuToGpu, // CPU-writable, GPU-readable
                                                     },
                                                     vertices.data()); // Optional initial data

Filename: kdgpu_doc_snippets.cpp

Creating an index buffer :

    std::vector<uint32_t> indices = { 0, 1, 2, 2, 3, 0 };

    KDGpu::Buffer indexBuffer = device.createBuffer(KDGpu::BufferOptions{
                                                            .size = indices.size() * sizeof(uint32_t),
                                                            .usage = KDGpu::BufferUsageFlagBits::IndexBufferBit,
                                                            .memoryUsage = KDGpu::MemoryUsage::CpuToGpu,
                                                    },
                                                    indices.data());

Filename: kdgpu_doc_snippets.cpp

Creating a uniform buffer(updated frequently) :

    struct CameraUniforms {
        glm::mat4 view;
        glm::mat4 projection;
    };

    KDGpu::Buffer uniformBuffer = device.createBuffer(KDGpu::BufferOptions{
            .size = sizeof(CameraUniforms),
            .usage = KDGpu::BufferUsageFlagBits::UniformBufferBit,
            .memoryUsage = KDGpu::MemoryUsage::CpuToGpu, // For frequent updates
    });

    // Update each frame
    Camera camera;
    void *mapped = uniformBuffer.map();
    CameraUniforms *uniforms = static_cast<CameraUniforms *>(mapped);
    uniforms->view = camera.viewMatrix();
    uniforms->projection = camera.projectionMatrix();
    uniformBuffer.flush(); // Ensure GPU sees changes
    uniformBuffer.unmap();

Filename: kdgpu_doc_snippets.cpp

Creating a storage buffer(shader read / write):

    KDGpu::Buffer storageBuffer = device.createBuffer(KDGpu::BufferOptions{
            .size = 1024 * 1024, // 1 MB
            .usage = KDGpu::BufferUsageFlagBits::StorageBufferBit,
            .memoryUsage = KDGpu::MemoryUsage::GpuOnly, // GPU-only for best performance
    });

Filename: kdgpu_doc_snippets.cpp

Memory usage patterns:

    // CPU to GPU: Writable from CPU, readable by GPU (staging, dynamic data)
    auto cpuToGpu = KDGpu::MemoryUsage::CpuToGpu;

    // GPU only: Best performance, require staging for uploads
    auto gpuOnly = KDGpu::MemoryUsage::GpuOnly;

    // GPU to CPU: For readback (screenshots, compute results)
    auto gpuToCpu = KDGpu::MemoryUsage::GpuToCpu;

Filename: kdgpu_doc_snippets.cpp

Mapping and unmapping:

    // Map for writing
    void *data = storageBuffer.map();
    memcpy(data, sourceData, dataSize);
    storageBuffer.unmap();

    // For non-coherent memory, flush to make changes visible to GPU
    storageBuffer.flush();

    // For reading GPU results, invalidate before reading
    storageBuffer.invalidate();
    void *results = storageBuffer.map();
    // ... read results ...
    storageBuffer.unmap();

Filename: kdgpu_doc_snippets.cpp

Buffer device addresses (for bindless):

    KDGpu::Buffer buffer2 = device.createBuffer(KDGpu::BufferOptions{
            .size = 1024,
            .usage = KDGpu::BufferUsageFlagBits::StorageBufferBit |
                    KDGpu::BufferUsageFlagBits::ShaderDeviceAddressBit,
            .memoryUsage = KDGpu::MemoryUsage::GpuOnly,
    });

    KDGpu::BufferDeviceAddress deviceAddress = buffer2.bufferDeviceAddress();
    // Pass deviceAddress to shader via push constants or uniforms

Filename: kdgpu_doc_snippets.cpp

Vulkan mapping:

• Buffer creation->vkCreateBuffer() + vkAllocateMemory() + vkBindBufferMemory()
• Buffer::map()->vkMapMemory() - Buffer::unmap()->vkUnmapMemory()
• Buffer::flush()->vkFlushMappedMemoryRanges()
• Buffer::invalidate()->vkInvalidateMappedMemoryRanges()
• Buffer::bufferDeviceAddress()->vkGetBufferDeviceAddress()

See also:

Device, BufferOptions, Queue, BufferOptions, BindGroup

KDGpu API Overview

KDGpu to Vulkan API Mapping

Public Functions Documentation

function ~Buffer

~Buffer()

function Buffer

Buffer()

function Buffer

Buffer(
    Buffer && other
)

function operator=

Buffer & operator=(
    Buffer && other
)

function Buffer

Buffer(
    const Buffer & 
) =delete

function operator=

Buffer & operator=(
    const Buffer & 
) =delete

function handle

inline const Handle< Buffer_t > & handle() const

function isValid

inline bool isValid() const

function operator Handle< Buffer_t >

inline operator Handle< Buffer_t >() const

function map

void * map()

function unmap

void unmap()

function invalidate

void invalidate()

function flush

void flush()

function externalMemoryHandle

MemoryHandle externalMemoryHandle() const

function bufferDeviceAddress

BufferDeviceAddress bufferDeviceAddress() const

Friends

friend Device

friend class Device(
    Device 
);

friend Queue

friend class Queue(
    Queue 
);

friend operator==

friend KDGPU_EXPORT bool operator==(
    const Buffer & a,

    const Buffer & b
);

---

Updated on 2026-03-31 at 00:02:07 +0000