Open 3D Engine Atom Gem API Reference  2205.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 Types | Protected Member Functions | Protected Attributes | List of all members
AZ::RHI::Device Class Referenceabstract

#include <Device.h>

Inherits AZ::RHI::Object.

Public Member Functions

 AZ_RTTI (Device, "{C7E70BE4-3AA5-4214-91E6-52A8ECC31A34}", Object)
bool IsInitialized () const
 Returns whether the device is initialized.
ResultCode Init (PhysicalDevice &physicalDevice)
ResultCode BeginFrame ()
ResultCode EndFrame ()
ResultCode WaitForIdle ()
ResultCode CompileMemoryStatistics (MemoryStatistics &memoryStatistics, MemoryStatisticsReportFlags reportFlags)
ResultCode UpdateCpuTimingStatistics () const
const PhysicalDeviceGetPhysicalDevice () const
 Returns the physical device associated with this device.
const DeviceDescriptorGetDescriptor () const
 Returns the descriptor associated with the device.
const DeviceFeaturesGetFeatures () const
 Returns the set of features supported by this device.
const DeviceLimitsGetLimits () const
 Returns the set of hardware limits for this device.
const ResourcePoolDatabaseGetResourcePoolDatabase () const
 Returns the resource pool database.
ResourcePoolDatabaseGetResourcePoolDatabase ()
 Returns the mutable resource pool database.
FormatCapabilities GetFormatCapabilities (Format format) const
 Returns a union of all capabilities of a specific format.
Format GetNearestSupportedFormat (Format requestedFormat, FormatCapabilities requestedCapabilities) const
 Return the nearest supported format for this device.
virtual AZStd::vector< Format > GetValidSwapChainImageFormats (const WindowHandle &windowHandle) const
virtual AZStd::chrono::microseconds GpuTimestampToMicroseconds (uint64_t gpuTimestamp, HardwareQueueClass queueClass) const =0
 Converts a GPU timestamp to microseconds.
virtual void PreShutdown ()=0
virtual ResourceMemoryRequirements GetResourceMemoryRequirements (const ImageDescriptor &descriptor)=0
 Get the memory requirements for allocating an image resource.
virtual ResourceMemoryRequirements GetResourceMemoryRequirements (const BufferDescriptor &descriptor)=0
 Get the memory requirements for allocating a buffer resource.
virtual void ObjectCollectionNotify (RHI::ObjectCollectorNotifyFunction notifyFunction)=0
 Notifies after all objects currently in the platform release queue are released.
virtual RHI::ResultCode CompactSRGMemory ()
 Allows the back-ends to compact SRG related memory if applicable.
bool WasDeviceRemoved ()
- Public Member Functions inherited from AZ::RHI::Object
 AZ_RTTI (Object, "{E43378F1-2331-4173-94B8-990ED20E6003}")
void SetName (const Name &name)
const Name & GetName () const

Protected Types

using FormatCapabilitiesList = AZStd::array< FormatCapabilities, static_cast< uint32_t >(Format::Count)>

Protected Member Functions

void SetDeviceRemoved ()

Protected Attributes

DeviceFeatures m_features
DeviceLimits m_limits
ResourcePoolDatabase m_resourcePoolDatabase
DeviceDescriptor m_descriptor

Detailed Description

The Device is a context for managing GPU state and memory on a physical device. The user creates a device instance from a PhysicalDevice. Each device has its own capabilities and limits, and can be configured to buffer a specific number of frames.

Certain objects in the RHI associate to a single device. This includes resource pools (and their associated resources), pipeline states, and frame scheduler support classes. It is valid to create multiple device instances, but they currently don't have a way to interact with each other. It is invalid to use an object associated with one device in a rendering operation associated with another device.

Multi-Device interop support is planned in the future and will likely require API changes.

Member Function Documentation

◆ BeginFrame()

ResultCode AZ::RHI::Device::BeginFrame ( )

Begins execution of a frame. The device internally manages a set of command queues. This method will synchronize the CPU with the GPU according to the number of in-light frames configured on the device. This means you should make sure any manipulation of N-buffered CPU data read by the GPU occurs after this method. This method must be called prior to FrameGraph execution.

If the call fails, an error code is returned and the device is left in a state as if the call had never occurred.

◆ CompileMemoryStatistics()

ResultCode AZ::RHI::Device::CompileMemoryStatistics ( MemoryStatistics memoryStatistics,
MemoryStatisticsReportFlags  reportFlags 

Fills the provided data structure with memory usage statistics specific to this device. This method can only be called on an initialized device, and outside of the BeginFrame / EndFrame scope. Otherwise, an error code is returned.

◆ EndFrame()

ResultCode AZ::RHI::Device::EndFrame ( )

Ends execution of a frame. This flushes all CPU state to the GPU. All FrameGraphExecuter execution phases must be complete before calling this method. If the call fails, an error code is returned and the device is left in a state as if the call had never occurred.

◆ GetValidSwapChainImageFormats()

virtual AZStd::vector<Format> AZ::RHI::Device::GetValidSwapChainImageFormats ( const WindowHandle windowHandle) const

Small API to support getting supported/working swapchain formats for a window. Returns the set of supported formats for swapchain images.

◆ Init()

ResultCode AZ::RHI::Device::Init ( PhysicalDevice physicalDevice)

Initializes just the native device using the provided physical device. The device must be initialized before it can be used. Explicit shutdown is not exposed due to the number of dependencies. Instead, the device is reference counted by child objects.

If initialization fails. The device is left in an uninitialized state (as if Init had never been called), and an error code is returned.

◆ PreShutdown()

virtual void AZ::RHI::Device::PreShutdown ( )
pure virtual

Called before the device is going to be shutdown. This lets the device release any resources that also hold on to a Ptr to Device.

◆ UpdateCpuTimingStatistics()

ResultCode AZ::RHI::Device::UpdateCpuTimingStatistics ( ) const

Pushes internally recorded timing statistics upwards into the global stats profiler, under the RHI section. This method can only be called on an initialized device, and outside of the BeginFrame / EndFrame scope. Otherwise, an error code is returned.

◆ WaitForIdle()

ResultCode AZ::RHI::Device::WaitForIdle ( )

Flushes all GPU work and waits for idle on the CPU. Naturally, this is a synchronous command and will block the CPU for an extended amount of time. However, it may be necessary in certain circumstances where memory must be reclaimed immediately. For example, any resource released on a pool is deferred until the GPU has completed processing of the frame. This method will ensure that all memory is reclaimed.

An important constraint on this method is that it cannot be called during execution of a frame (i.e. within the BeginFrame / EndFrame scope). Attempting to do so will return ResultCode::InvalidOperation.

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