Foundation::Rendering::StagedBuffer Class Reference

Helper class for GPU buffer updates. More...

#include <StagingBuffer.hpp>

Inheritance diagram for Foundation::Rendering::StagedBuffer:

Public Types
enum class	State { Idle , Transfer }

Public Member Functions
	StagedBuffer (RHIDevice *device, Allocator *allocator, RHIBufferDesc const &desc={}, size_t stagingBudget=kFullSize, Optional< uint32_t > clearValue={})
	Create the staging arena buffers.
RHIBuffer *	GetBuffer ()
	Gets the GPU-only backing buffer.
void	BeginTransfer ()
	Resets the staging buffer and aborts all pending data updates.
StagingBuffer *	GetStagingBuffer ()
	Gets the current staging buffer for data uploads.
void	Transfer (size_t dst_offset, Span< const char > data, size_t alignment=4)
	Schedules a data upload to the given buffer at the given offset.
void	EndTransfer ()
	Ends the transfer state, and pushes optimized copy commands to the given command list.
bool	HasUpdates ()
	Check if there are any pending updates to be performed.
void	Update (RHICommandList *cmd)
	Push the scheduled uploads onto the command list.
Public Member Functions inherited from Foundation::RHI::RHIObject
	RHIObject ()=default
	RHIObject (RHIObject const &)=delete
RHIObject &	operator= (const RHIObject &)=delete
	RHIObject (RHIObject &&)=delete
RHIObject &	operator= (RHIObject &&)=delete
virtual	~RHIObject ()=default

Private Attributes
RHIDevice *	mDevice {nullptr}
Allocator *	mAllocator {nullptr}
StagingBuffer	mStagingBuffer
RHIDeviceScopedObjectHandle< RHIBuffer >	mBuffer
State	mState {State::Idle}
BufferStagingList	mBufferStagings
RHIDeviceIdleGuard	mIdleGuard
Optional< uint32_t >	mClearValue

Detailed Description

Helper class for GPU buffer updates.

This creates a GPU-only local buffer, and a staging buffer of arbitrary size

Note

For one-shot, uploaded static content that doesn't change, consider using UploadContext instead. Don't forget that Push Constant also exists.

The user should ensure correct synchronization of the buffer usage e.g. avoid performing Transfer while the buffer is being read by the GPU. Thus a CPU-only buffer is recommended to be used as an intermediate cache before accessing the GPU buffer. See StagedDoubleBuffer in GPUScene for details.

Member Enumeration Documentation

State

enum class Foundation::Rendering::StagedBuffer::State

strong

Enumerator
Idle
Transfer

Constructor & Destructor Documentation

StagedBuffer()

Foundation::Rendering::StagedBuffer::StagedBuffer	(	RHIDevice *	device,
		Allocator *	allocator,
		RHIBufferDesc const &	desc = {},
		size_t	stagingBudget = kFullSize,
		Optional< uint32_t >	clearValue = {}
	)

Create the staging arena buffers.

Parameters

desc	Description of the data buffer to be created.
stagingBudget	Size of the staging buffer. Defaults to kFullSize, which is the same size of the buffer created.
clearValue	Value to clear the buffer with at first update. Defaults to {}, which leaves the buffer uninitialized.

Member Function Documentation

BeginTransfer()

void Foundation::Rendering::StagedBuffer::BeginTransfer

(

)

Resets the staging buffer and aborts all pending data updates.

Note

This MUST be called after the Renderer's BeginExecute, and before ExecuteFrame as the staging buffer is tied to the frame fences.

EndTransfer()

void Foundation::Rendering::StagedBuffer::EndTransfer

(

)

Ends the transfer state, and pushes optimized copy commands to the given command list.

GetBuffer()

RHIBuffer * Foundation::Rendering::StagedBuffer::GetBuffer ( )

inline

Gets the GPU-only backing buffer.

GetStagingBuffer()

StagingBuffer * Foundation::Rendering::StagedBuffer::GetStagingBuffer

(

)

Gets the current staging buffer for data uploads.

This MUST be called between BeginTransfer and EndTransfer.

HasUpdates()

bool Foundation::Rendering::StagedBuffer::HasUpdates ( )

inline

Check if there are any pending updates to be performed.

Transfer()

void Foundation::Rendering::StagedBuffer::Transfer	(	size_t	dst_offset,
		Span< const char >	data,
		size_t	alignment = 4
	)

Schedules a data upload to the given buffer at the given offset.

This MUST be called between BeginTransfer and EndTransfer.

Note

No transfer is performed until EndTransfer is called, and its command list is executed.

Overlapping transfers is undefined behavior.

Update()

void Foundation::Rendering::StagedBuffer::Update

(

RHICommandList *

cmd

)

Push the scheduled uploads onto the command list.

This MUST be called after EndTransfer, and before the command list is submitted.

Once executed, the previously scheduled uploads are considered done, and will be flushed.

Note

No resource transitions are performed here. It's up to the caller to ensure correct access patterns. Thus, it's recommended to use createStagedBufferUpdatePass to create a pass that performs everything above with optimal synchronization.

Member Data Documentation

mAllocator

Allocator* Foundation::Rendering::StagedBuffer::mAllocator {nullptr}

private

mBuffer

RHIDeviceScopedObjectHandle<RHIBuffer> Foundation::Rendering::StagedBuffer::mBuffer

private

mBufferStagings

BufferStagingList Foundation::Rendering::StagedBuffer::mBufferStagings

private

mClearValue

Optional<uint32_t> Foundation::Rendering::StagedBuffer::mClearValue

private

mDevice

RHIDevice* Foundation::Rendering::StagedBuffer::mDevice {nullptr}

private

mIdleGuard

RHIDeviceIdleGuard Foundation::Rendering::StagedBuffer::mIdleGuard

private

mStagingBuffer

StagingBuffer Foundation::Rendering::StagedBuffer::mStagingBuffer

private

mState

State Foundation::Rendering::StagedBuffer::mState {State::Idle}

private

---

The documentation for this class was generated from the following files:

• Source/Rendering/StagingBuffer.hpp
• Source/Rendering/StagingBuffer.cpp