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.
AZ::RHI::Device Class Referenceabstract

#include <Device.h>

Inherits AZ::RHI::Object.

Inherited by AZ::DX12::Device_Windows, AZ::Metal::Device, AZ::Null::Device, and AZ::Vulkan::Device.

Public Member Functions

 AZ_RTTI (Device, "{C7E70BE4-3AA5-4214-91E6-52A8ECC31A34}", Object)
bool IsInitialized () const
 Returns whether the device is initialized.
ResultCode Init (int deviceIndex, 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.
int GetDeviceIndex () const
 Returns the device index.
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.
ResultCode InitBindlessSrg (RHI::Ptr< RHI::ShaderResourceGroupLayout > bindlessSrgLayout)
virtual RHI::ResultCode CompactSRGMemory ()
 Allows the back-ends to compact SRG related memory if applicable.
virtual ShadingRateImageValue ConvertShadingRate (ShadingRate rate) const =0
 Converts a shading rate enum to the proper texel value to be used in a shading rate image.
bool WasDeviceRemoved ()
void SetDeviceRemoved ()
void SetLastExecutingScope (const AZStd::string_view scopeName)
AZStd::string_view GetLastExecutingScope () const
virtual Ptr< XRDeviceDescriptorBuildXRDescriptor () const
 Builds an implementation specific XR device descriptor based on this graphics device.
- 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 Types

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

Protected Attributes

DeviceFeatures m_features
DeviceLimits m_limits
ResourcePoolDatabase m_resourcePoolDatabase
DeviceDescriptor m_descriptor
- Protected Attributes inherited from AZ::RHI::Object
AZStd::atomic_int m_useCount = 0

Additional Inherited Members

- Protected Member Functions inherited from AZ::RHI::Object
void add_ref () const
void release () const

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.

◆ GetResourceMemoryRequirements() [1/2]

virtual ResourceMemoryRequirements AZ::RHI::Device::GetResourceMemoryRequirements ( const BufferDescriptor descriptor)
pure virtual

Get the memory requirements for allocating a buffer resource.

Implemented in AZ::Metal::Device.

◆ GetResourceMemoryRequirements() [2/2]

virtual ResourceMemoryRequirements AZ::RHI::Device::GetResourceMemoryRequirements ( const ImageDescriptor descriptor)
pure virtual

Get the memory requirements for allocating an image resource.

Implemented in AZ::Metal::Device.

◆ 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 ( int  deviceIndex,
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.

◆ InitBindlessSrg()

ResultCode AZ::RHI::Device::InitBindlessSrg ( RHI::Ptr< RHI::ShaderResourceGroupLayout bindlessSrgLayout)

Called to initialize bindless SRG related native binding objects (i.e descriptor set/argument table). This is called after AssetCatalog is loaded and hence we can use bindless.azsli to data drive the binding indices.

◆ ObjectCollectionNotify()

virtual void AZ::RHI::Device::ObjectCollectionNotify ( RHI::ObjectCollectorNotifyFunction  notifyFunction)
pure virtual

Notifies after all objects currently in the platform release queue are released.

Implemented in AZ::Metal::Device.

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