GPU Buffers

Haiku provides a data structure GPUBuffer and assiociated utility functions in Buffer:: namespace.

To create a GPUBuffer, it requires a description of the type of buffer and it differs depending on the OpenGL backend:

mat4 matrices[10];
/* ... */

GPUBuffer   buff;
BufferDesc  desc = BufferDesc::Storage(GL_SHADER_STORAGE_BUFFER,GL_DYNAMIC_STORAGE_BIT);

Buffer::Create(&buff, desc, 10*sizeof(mat4), &matrices[0]);
Buffer::BindToUnit(buff, 0);

mat4 matrices[10];
/* ... */

GPUBuffer   buff;
BufferDesc  desc = BufferDesc::Data(GL_UNIFORM_BUFFER,GL_STATIC_DRAW);

Buffer::Create(&buff, desc, 10*sizeof(mat4), &matrices[0]);
Buffer::BindToUnit(buff, 0);

To access these buffers on the GPU side :

layout(std430, binding = 0) buffer transforms
{
    mat4 matrices[];
};

layout(std140) uniform transforms
{
    mat4 matrices[10];
};

BufferDesc Description

struct BufferDesc

OpenGL Buffer Object description data structure

Public Members

uint32_t type = 0

Specifies the target to which the buffer object is bound:

  • GL_ARRAY_BUFFER : Vertex attributes

  • GL_ATOMIC_COUNTER_BUFFER : Atomic counter storage

  • GL_COPY_READ_BUFFER : Buffer copy source

  • GL_COPY_WRITE_BUFFER : Buffer copy destination

  • GL_DISPATCH_INDIRECT_BUFFER : Indirect compute dispatch commands

  • GL_DRAW_INDIRECT_BUFFER : Indirect command arguments

  • GL_ELEMENT_ARRAY_BUFFER : Vertex array indices

  • GL_PIXEL_PACK_BUFFER : Pixel read target

  • GL_PIXEL_UNPACK_BUFFER : Texture data source

  • GL_QUERY_BUFFER : Query result buffer

  • GL_SHADER_STORAGE_BUFFER : Read-write storage for shaders

  • GL_TEXTURE_BUFFER : Texture data buffer

  • GL_TRANSFORM_FEEDBACK_BUFFER : Transform feedback buffer

  • GL_UNIFORM_BUFFER : Uniform block storage

uint32_t flags = 0

Intented usage of the buffer’s data storage. Bitwise combination of a subset including

  • GL_DYNAMIC_STORAGE_BIT : content may be updated after creation glBufferSubData

  • GL_MAP_READ_BIT : read-only access

  • GL_MAP_WRITE_BIT : write-only access

  • GL_MAP_PERSISTENT_BIT : must contain at least one GL_MAP_READ_BIT or GL_MAP_WRITE_BIT

  • GL_MAP_COHERENT_BIT : must contain GL_MAP_PERSISTENT_BIT

uint32_t usage = 0

Specifies the expected usage pattern of the data store :

  • GL_DYNAMIC_DRAW, GL_STATIC_DRAW, GL_STREAM_DRAW

  • GL_DYNAMIC_READ, GL_STATIC_READ, GL_STREAM_READ

  • GL_DYNAMIC_COPY, GL_STATIC_COPY, GL_STREAM_COPY

Public Static Functions

static BufferDesc Create(uint32_t type, uint32_t flags, uint32_t usage)

Buffer Descriptor verbose constructor.

static BufferDesc Storage(uint32_t type, uint32_t flags)

Buffer Descriptor using glBufferStorage.

static BufferDesc Data(uint32_t type, uint32_t usage)

Buffer Descriptor using glBufferData.

Buffer Description

struct GPUBuffer

OpenGL Buffer Object data structure

Public Members

uint32_t id = 0u

OpenGL Buffer ID

BufferDesc desc

Buffer description

namespace Buffer

Functions

void Create(GPUBuffer *b, const BufferDesc &desc, size_t size, const void *data_ptr)

Creates an opengl gpu buffer with existing data.

Parameters:

  • b – The GPUBuffer pointer

  • desc – The buffer description

  • size – size of data stored (sizeof)

  • data_ptr – Data pointer

void Create(GPUBuffer *b, const BufferDesc &desc, size_t size)

Creates an empty opengl gpu buffer.

Parameters:

  • b – The GPUBuffer pointer

  • desc – The buffer description

  • size – size of data stored (sizeof)

void Destroy(GPUBuffer *b)

Cleans up the gpu buffer data structure.

void Update(GPUBuffer *b, size_t offset, size_t size, const void *data)

Update data stored in the gpu buffer.

Parameters:

  • b – The GPUBuffer pointer

  • offset – Starting offset of data to update

  • size – Size of data to update

  • data – new data

void *Map(GPUBuffer *b, const uint32_t access)

Maps the entire data of the specified buffer into the client’s address space.

Parameters:

  • b – The GPUBuffer pointer

  • access – How the data is accessed :

    • GL_READ_ONLY : returned pointer may be used to read buffer object data

    • GL_WRITE_ONLY : returned pointer may be used to modify buffer object data

    • GL_READ_WRITE : returned pointer may be used to read and to modify buffer object data

Returns:

void* data pointer (NULL is returned if an error occured)

void *MapRange(GPUBuffer *b, const uint32_t access, const GLintptr offset, const GLsizeiptr length)

Maps all or part of a buffer object’s data into the client’s address space.

Parameters:

  • b – The GPUBuffer pointer

  • offset – Starting offset within the buffer of the range to be mapped

  • length – Length of the range to be mapped

  • access – How the data is accessed :

    • GL_READ_ONLY : returned pointer may be used to read buffer object data

    • GL_WRITE_ONLY : returned pointer may be used to modify buffer object data

    • GL_READ_WRITE : returned pointer may be used to read and to modify buffer object data

Returns:

void* data pointer (NULL is returned if an error occured)

void Unmap(GPUBuffer *b)

Releases the mapping of a buffer object’s data store into the client’s address space.

void BindToUnit(const GPUBuffer &b, uint32_t unit)

Binds the buffer to a specific unit index.

Parameters:

  • b – The GPUBuffer pointer

  • unit – Unit index

void ReleaseUnit(const GPUBuffer &b, uint32_t unit)

Releases the buffer from a specific unit index.

Parameters:

  • b – The GPUBuffer pointer

  • unit – Unit index

void Bind(const GPUBuffer &b)

Binds a named buffer object.

void UnBind(const GPUBuffer &b)

UnBinds a named buffer object.

void ResetAtomic(GPUBuffer *b, uint32_t value)

Resets an atomic buffer object to a specific value.