nCine::RHI::GX2::Gx2BufferObject class

Buffer object of the GX2 backend (aliased as RHI::Buffer).

A vertex, index or uniform buffer keeps a resizable byte store in MEM2 (see Gx2Memory) that the pipeline maps and writes into, and that the GPU reads in place - there is no upload step. The CPU's data cache is not coherent with the GPU, so every write path ends in a flush of the written range: BufferData() and BufferSubData() flush what they copied, FlushMappedBufferRange() flushes the range it is given and Unmap() flushes the range the last MapBufferRange() handed out.

The store is grow-only: a BufferData() that fits the existing block reuses it, so the pipeline's per-frame ring buffers allocate once.

GX2 does not rename buffers, so a CPU write must not land in bytes a queued draw still reads. A draw stamps every vertex and index buffer it reads with its batch token (MarkUsed()), and a write to a buffer whose token has not retired either moves the store to a fresh block (when the write replaces all of it: an orphaning BufferData(), a whole-store BufferSubData() or a map that may discard the contents; the old block is retired) or waits for the token. A persistent mapping is never synchronised here: RenderBuffersManager's section ring fences it. Uniform buffers are never stamped, because the device copies their ranges into its own uniform ring at draw time and the GPU never reads them.

Public static functions

static void SetBoundHandle(std::uint32_t target, std::uint32_t glHandle)
Records the buffer handle bound for a target (inert).
static auto BindHandle(std::uint32_t target, std::uint32_t glHandle) -> bool
Marks a buffer handle as bound for a target (inert).

Constructors, destructors, conversion operators

Gx2BufferObject(BufferTarget target) explicit
~Gx2BufferObject()
Gx2BufferObject(const Gx2BufferObject&) deleted

Public functions

auto operator=(const Gx2BufferObject&) -> Gx2BufferObject& deleted
auto GetGLHandle() const -> std::uint32_t
Returns a synthetic handle uniquely identifying the buffer (used by material sort keys).
auto GetTarget() const -> BufferTarget
Returns the binding target of the buffer.
auto GetSize() const -> std::size_t
Returns the size in bytes of the data store.
auto HostData() -> std::uint8_t*
Returns the base pointer of the data store.
auto HostData() const -> const std::uint8_t*
Returns the base pointer of the data store.
auto GetGpuData() const -> const void*
Returns the GPU-visible base address of the store, or nullptr if it could not be allocated.
auto Bind() const -> bool
Marks the buffer as the currently bound one for its target (always issues the "bind").
auto Unbind() const -> bool
Marks no buffer as bound for this object's target.
void BufferData(std::size_t size, const void* data, BufferUsage usage)
(Re)creates the data store with the given size, optional initial data and usage hint
void BufferSubData(std::size_t offset, std::size_t size, const void* data)
Updates a subset of the data store starting at the given byte offset.
void BufferStorage(std::size_t size, const void* data, MapFlags flags)
(Re)creates the data store like BufferData(); there is no immutable storage, so the flags are ignored
void BindBufferBase(std::uint32_t index)
Binds the whole buffer to a uniform binding point index.
void BindBufferRange(std::uint32_t index, std::size_t offset, std::size_t size)
Binds a byte range of the buffer to a uniform binding point index (forwarded to the device).
auto MapBufferRange(std::size_t offset, std::size_t length, MapFlags access) -> void*
Returns a pointer to a byte range of the store (there is no real mapping).
void FlushMappedBufferRange(std::size_t offset, std::size_t length)
Flushes a mapped range out of the CPU cache so the GPU sees it.
auto Unmap() -> bool
Unmaps the buffer, flushing the range the last MapBufferRange() returned.
void SetObjectLabel(StringView label)
Sets a debug label for the buffer (ignored).
void MarkUsed(std::uint32_t token) const
Records that a draw of the batch with token reads the store (see Gx2Device::GetUseToken()).

Function documentation

const void* nCine::RHI::GX2::Gx2BufferObject::GetGpuData() const

Returns the GPU-visible base address of the store, or nullptr if it could not be allocated.

The same pointer HostData() returns, only named for the side that consumes it.