Open 3D Engine Atom Gem API Reference 23.10.0
O3DE is an open-source, fully-featured, high-fidelity, modular 3D engine for building games and simulations, available to every industry.
Public Member Functions | Protected Member Functions | List of all members
AZ::RHI::BufferPool Class Reference

#include <BufferPool.h>

Inherits AZ::RHI::BufferPoolBase.

Inherited by AZ::DX12::BufferPool, AZ::Metal::BufferPool, AZ::Null::BufferPool, and AZ::Vulkan::BufferPool.

Public Member Functions

ResultCode Init (Device &device, const BufferPoolDescriptor &descriptor)
 
ResultCode InitBuffer (const BufferInitRequest &request)
 
ResultCode OrphanBuffer (Buffer &buffer)
 
ResultCode MapBuffer (const BufferMapRequest &request, BufferMapResponse &response)
 
void UnmapBuffer (Buffer &buffer)
 
ResultCode StreamBuffer (const BufferStreamRequest &request)
 
const BufferPoolDescriptor & GetDescriptor () const override final
 
- Public Member Functions inherited from AZ::RHI::BufferPoolBase
 AZ_RTTI (BufferPoolBase, "{28D265BB-3B90-4676-BBA9-3F933F14CB01}", ResourcePool)
 
- Public Member Functions inherited from AZ::RHI::ResourcePool
 AZ_RTTI (ResourcePool, "{757EB674-25DC-4D00-9808-D3DAF33A4EFE}", DeviceObject)
 
void Shutdown () override final
 Shuts down the pool. This method will shutdown all resources associated with the pool.
 
template<typename ResourceType >
void ForEach (AZStd::function< void(ResourceType &)> callback)
 
template<typename ResourceType >
void ForEach (AZStd::function< void(const ResourceType &)> callback) const
 
uint32_t GetResourceCount () const
 Returns the number of resources in the pool.
 
ResourcePoolResolver * GetResolver ()
 Returns the resolver for this pool.
 
const ResourcePoolResolver * GetResolver () const
 
virtual const ResourcePoolDescriptor & GetDescriptor () const =0
 Returns the resource pool descriptor.
 
const HeapMemoryUsage & GetHeapMemoryUsage (HeapMemoryLevel heapMemoryLevel) const
 Returns the memory used by this pool for a specific heap type.
 
const PoolMemoryUsage & GetMemoryUsage () const
 Returns the memory used by this pool.
 
- Public Member Functions inherited from AZ::RHI::DeviceObject
 AZ_RTTI (DeviceObject, "{17D34F71-944C-4AF5-9823-627474C4C0A6}", Object)
 
bool IsInitialized () const
 Returns whether the device object is initialized.
 
Device & GetDevice () const
 
- Public Member Functions inherited from AZ::RHI::Object
 AZ_RTTI (Object, "{E43378F1-2331-4173-94B8-990ED20E6003}")
 
void SetName (const Name &name)
 Sets the name of the object.
 
const Name & GetName () const
 Returns the name set on the object by SetName.
 
uint32_t use_count ()
 Returns the current use count of the object.
 

Protected Member Functions

void OnFrameBegin () override
 
bool ValidateNotProcessingFrame () const
 
- Protected Member Functions inherited from AZ::RHI::BufferPoolBase
ResultCode InitBuffer (Buffer *buffer, const BufferDescriptor &descriptor, PlatformMethod platformInitResourceMethod)
 
void ValidateBufferMap (Buffer &buffer, bool isDataValid)
 
bool ValidateBufferUnmap (Buffer &buffer)
 
uint32_t GetMapRefCount () const
 
- Protected Member Functions inherited from AZ::RHI::ResourcePool
void OnFrameBegin () override
 
void OnFrameCompile () override
 
void OnFrameEnd () override
 
void SetResolver (AZStd::unique_ptr< ResourcePoolResolver > &&resolvePolicy)
 
virtual void ComputeFragmentation () const =0
 
ResultCode Init (Device &device, const ResourcePoolDescriptor &descriptor, const PlatformMethod &initMethod)
 
ResultCode InitResource (Resource *resource, const PlatformMethod &initResourceMethod)
 
bool ValidateIsRegistered (const Resource *resource) const
 
bool ValidateIsUnregistered (const Resource *resource) const
 
bool ValidateIsInitialized () const
 Validates that the resource pool is initialized and ready to service requests.
 
bool ValidateNotProcessingFrame () const
 Validates that we are not in the frame processing phase.
 
- Protected Member Functions inherited from AZ::RHI::DeviceObject
void Init (Device &device)
 The derived class should call this method to assign the device.
 
void Shutdown () override
 Clears the current bound device to null.
 
- Protected Member Functions inherited from AZ::RHI::Object
void add_ref () const
 
void release () const
 

Additional Inherited Members

- Protected Types inherited from AZ::RHI::ResourcePool
using PlatformMethod = AZStd::function< RHI::ResultCode()>
 A simple functor that returns a result code.
 
- Protected Attributes inherited from AZ::RHI::ResourcePool
PoolMemoryUsage m_memoryUsage
 
- Protected Attributes inherited from AZ::RHI::Object
AZStd::atomic_int m_useCount = 0
 

Detailed Description

Buffer pool provides backing storage and context for buffer instances. The BufferPoolDescriptor contains properties defining memory characteristics of buffer pools. All buffers created on a pool share the same backing heap and buffer bind flags.

Member Function Documentation

◆ GetDescriptor()

const BufferPoolDescriptor & AZ::RHI::BufferPool::GetDescriptor ( ) const
finaloverridevirtual

Returns the buffer descriptor used to initialize the buffer pool. Descriptor contents are undefined for uninitialized pools.

Implements AZ::RHI::ResourcePool.

◆ Init()

ResultCode AZ::RHI::BufferPool::Init ( Device &  device,
const BufferPoolDescriptor &  descriptor 
)

Initializes the buffer pool with a provided descriptor. The pool must be in an uninitialized state, or this call will fail. To re-use an existing pool, you must first call Shutdown before calling Init again.

Parameters
descriptorThe descriptor containing properties used to initialize the pool.
Returns
A result code denoting the status of the call. If successful, the pool is considered initialized and is able to service buffer requests. If failure, the pool remains uninitialized.

◆ InitBuffer()

ResultCode AZ::RHI::BufferPool::InitBuffer ( const BufferInitRequest &  request)

Initializes a buffer instance created from this pool. The buffer must be in an uninitialized state, or the call will fail. To re-use an existing buffer instance, first call Shutdown on the buffer prior to calling InitBuffer on the pool.

Parameters
requestThe request used to initialize a buffer instance.
Returns
A result code denoting the status of the call. If successful, the buffer is considered initialized and 'registered' with the pool. If the pool fails to secure an allocation for the buffer, it remain in a shutdown state. If the initial data upload fails, the buffer will be initialized, but will remain empty and the call will return ResultCode::OutOfMemory. Checking this amounts to seeing if buffer.IsInitialized() is true.

◆ MapBuffer()

ResultCode AZ::RHI::BufferPool::MapBuffer ( const BufferMapRequest &  request,
BufferMapResponse &  response 
)

Maps a buffer region for CPU access. The type of access (read or write) is dictated by the type of buffer pool. Host pools with host read access may read from the buffer–the contents of which are written by the GPU. All other modes only expose write-only access by the CPU.

Is it safe to nest Map operations if the regions are disjoint. Calling Map is reference counted, so calling Unmap is required for each Map call. Map operations will block the frame scheduler from recording staging operations to the command lists. To avoid this, unmap all buffer regions before the frame execution phase.

Parameters
requestThe map request structure holding properties for the map operation.
responseThe map response structure holding the mapped data pointer (if successful), or null.
Returns
Returns a result code specifying whether the call succeeded, or a failure code specifying why the call failed.

◆ OrphanBuffer()

ResultCode AZ::RHI::BufferPool::OrphanBuffer ( Buffer &  buffer)

NOTE: Only applicable to 'Host' pools. Device pools will fail with ResultCode::InvalidOperation.

Instructs the pool to allocate a new backing allocation for the buffer. This enables the user to ignore tracking hazards between the CPU and GPU timelines. Call this method if the entire buffer contents are being overwritten for a new frame.

The user may instead do hazard tracking manually by not overwriting regions in-flight on the GPU. To ensure that a region has flushed through the GPU, either use Fences to track when a Scope has completed, or rely on RHI::Limits::Device::FrameCountMax (for example, by N-buffering the data in a round-robin fashion).

If the new allocation is small enough to be page-allocated, the buffer's debug name will be lost. If the allocation is large enough to create a new buffer object, it will call SetName() with the old name.

Parameters
bufferThe buffer whose backing allocation to orphan. The buffer must be registered and initialized with this pool.
Returns
On success, the buffer is considered to have a new backing allocation. On failure, the existing buffer allocation remains intact.

◆ StreamBuffer()

ResultCode AZ::RHI::BufferPool::StreamBuffer ( const BufferStreamRequest &  request)

Asynchronously streams buffer data up to the GPU. The operation is decoupled from the frame scheduler. It is not valid to use the buffer while the upload is running. The provided fence is signaled when the upload completes.

◆ UnmapBuffer()

void AZ::RHI::BufferPool::UnmapBuffer ( Buffer &  buffer)

Unmaps a buffer for CPU access. The mapped data pointer is considered invalid after this call and should not be accessed. This call unmaps the data region and unblocks the GPU for access.

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