Open 3D Engine Atom Gem API Reference 25.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 | Friends | List of all members
AZ::RHI::BufferPool Class Reference

#include <BufferPool.h>

Inherits AZ::RHI::BufferPoolBase.

Public Member Functions

 AZ_CLASS_ALLOCATOR (BufferPool, AZ::SystemAllocator, 0)
 
 AZ_RHI_MULTI_DEVICE_OBJECT_GETTER (BufferPool)
 
ResultCode Init (const BufferPoolDescriptor &descriptor)
 
ResultCode InitBuffer (const BufferInitRequest &request)
 
ResultCode UpdateBufferDeviceMask (const BufferDeviceMaskRequest &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
 
void Shutdown () override final
 Shuts down the pool. This method will shutdown all resources associated with the pool.
 
- Public Member Functions inherited from AZ::RHI::BufferPoolBase
 AZ_RTTI (BufferPoolBase, "{08EC3384-CC9F-4F04-B87E-0BB9D23F7CB0}", ResourcePool)
 
- Public Member Functions inherited from AZ::RHI::ResourcePool
 AZ_RTTI (ResourcePool, "{BAE5442C-A312-4133-AE80-1200753A7C3E}", MultiDeviceObject)
 
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.
 
- Public Member Functions inherited from AZ::RHI::MultiDeviceObject
 AZ_RTTI (MultiDeviceObject, "{17D34F71-944C-4AF5-9823-627474C4C0A6}", Object)
 
bool IsInitialized () const
 Returns whether the device object is initialized.
 
AZ_FORCE_INLINE bool IsDeviceSet (int deviceIndex) const
 
MultiDevice::DeviceMask GetDeviceMask () 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.
 

Friends

class RayTracingBufferPools
 

Additional Inherited Members

- Static Public Member Functions inherited from AZ::RHI::MultiDeviceObject
template<typename T >
static AZ_FORCE_INLINE void IterateDevices (MultiDevice::DeviceMask deviceMask, T callback)
 
- Protected Types inherited from AZ::RHI::ResourcePool
using PlatformMethod = AZStd::function< RHI::ResultCode()>
 //!//!//!//!//!//!//!//!//!//!//!//!//!//!//!//!//!//!//!//!//!//!//!//
 
- Protected Member Functions inherited from AZ::RHI::BufferPoolBase
ResultCode InitBuffer (Buffer *buffer, const BufferDescriptor &descriptor, PlatformMethod platformInitResourceMethod)
 
- Protected Member Functions inherited from AZ::RHI::ResourcePool
ResultCode Init (MultiDevice::DeviceMask deviceMask, 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.
 
- Protected Member Functions inherited from AZ::RHI::MultiDeviceObject
void Init (MultiDevice::DeviceMask deviceMask)
 The derived class should call this method to assign the device.
 
template<typename T >
AZ_FORCE_INLINE void IterateDevices (T callback)
 Helper method that will iterate over all selected devices and call the provided callback.
 
template<typename T , typename U >
AZ_FORCE_INLINE decltype(auto) IterateObjects (U callback)
 
template<typename T , typename U >
AZ_FORCE_INLINE decltype(auto) IterateObjects (U callback) const
 
template<typename T >
AZ_FORCE_INLINE Ptr< T > GetDeviceObject (int deviceIndex) const
 
- Protected Member Functions inherited from AZ::RHI::Object
void add_ref () const
 
void release () const
 
- Protected Attributes inherited from AZ::RHI::MultiDeviceObject
AZStd::unordered_map< int, Ptr< DeviceObject > > m_deviceObjects
 A map of all device-specific objects, indexed by the device index.
 
- 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 ( 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.

◆ Shutdown()

void AZ::RHI::BufferPool::Shutdown ( )
finaloverridevirtual

Shuts down the pool. This method will shutdown all resources associated with the pool.

Implements AZ::RHI::ResourcePool.

◆ 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.

◆ UpdateBufferDeviceMask()

ResultCode AZ::RHI::BufferPool::UpdateBufferDeviceMask ( const BufferDeviceMaskRequest &  request)

Updates the device mask of a buffer instance created from this pool. The buffer must be in an initialized state, or the call will fail, i.e., first call InitBuffer on the pool.

Parameters
requestThe request used to update a buffer instance's device mask and device buffer allocations.
Returns
A result code denoting the status of the call. If successful, the buffer device mask is considered updated. If the pool fails to secure an allocation for the device buffers, it's device mask may only partially change. If the initial data upload fails, the buffer will be initialized, but will remain empty and the call will return ResultCode::OutOfMemory.
The documentation for this class was generated from the following file: