- Generated on Thu Apr 20 2023 21:34:04 for Open 3D Engine Atom Gem API Reference by
1.8.5
|
Open 3D Engine Atom Gem API Reference
23.05.0
O3DE is an open-source, fully-featured, high-fidelity, modular 3D engine for building games and simulations, available to every industry.
|
#include <FrameScheduler.h>
Inherits AZ::RHI::FrameGraphBuilder.
Public Member Functions | |
| AZ_CLASS_ALLOCATOR (FrameScheduler, AZ::SystemAllocator) | |
| FrameScheduler (const FrameScheduler &)=delete | |
| bool | IsInitialized () const |
| ResultCode | Init (Device &device, const FrameSchedulerDescriptor &descriptor) |
| Initializes the frame scheduler and connects it to the buses. | |
| void | Shutdown () |
| Shuts down the frame scheduler. | |
| ResultCode | BeginFrame () |
| Begin GPU frame. Any GPU-related operations should occur between this call and EndFrame. | |
| ResultCode | EndFrame () |
| Ends GPU frame. Must be called after Execute if Compile was called. | |
| FrameGraphAttachmentInterface | GetAttachmentDatabase () override |
| ResultCode | ImportScopeProducer (ScopeProducer &scopeProducer) override |
| MessageOutcome | Compile (const FrameSchedulerCompileRequest &compileRequest) |
| void | Execute (JobPolicy jobPolicy) |
|
const TransientAttachmentStatistics * | GetTransientAttachmentStatistics () const |
| Returns the timing statistics for the previous frame. | |
| double | GetCpuFrameTime () const |
| Returns current CPU frame to frame time in milliseconds. | |
| const MemoryStatistics * | GetMemoryStatistics () const |
| Returns memory statistics for the previous frame. | |
| ScopeId | GetRootScopeId () const |
| Returns the implicit root scope id. | |
|
const TransientAttachmentPoolDescriptor * | GetTransientAttachmentPoolDescriptor () const |
| Returns the descriptor which has information on the properties of a TransientAttachmentPool. | |
| void | QueueRayTracingShaderTableForBuild (RayTracingShaderTable *rayTracingShaderTable) |
| Adds a RayTracingShaderTable to be built this frame. | |
| const PhysicalDeviceDescriptor & | GetPhysicalDeviceDescriptor () |
| Returns PhysicalDeviceDescriptor which can be used to extract vendor/driver information. | |
== Overview ==
The frame scheduler is a system for facilitating efficient GPU work submission. It provides a user-facing API for preparing (constructing), compiling, and executing a frame graph. The graph provides knowledge of the whole frame and is processed through phases down to platform-specific actions. Because the graph is known up front, hazard tracking, memory aliasing, and cross-queue synchronization become much simpler problems. The frame becomes fully deterministic.
The graph is constructed from ScopeProducers–user overridden classes which declare information to the graph. ScopeProducers own and maintain a Scope, which contains the generated graph node data. ScopeProducer is overridden by the end-user (feature author), while Scope is overridden by the internal platform implementation. Effectively, scopes contain private data, while ScopeProducers are public producers of that data.
In addition to scopes, the frame graph supports attachments. An attachment is effectively some metadata around a buffer / image resource which tracks its usage across all scopes in a frame. This usage is vital for controlling low-level resource transitions or memory aliasing on the GPU.
FrameScheduler delegates most of the heavy lifting to the FrameGraphCompiler and FrameGraphExecuter classes, which are the platform-overridden interfaces for graph construction / execution, respectively. It effectively ties everything together by owning the frame graph and all the necessary sub-components. The class also facilitates jobification of command list recording.
== Usage ==
To use the frame scheduler: 1) Instantiate a FrameScheduler instance with a valid RHI device. 2) Override and instantiate ScopeProducers. 3) Once per frame: 3.1) Call BeginFrame(). 3.2) Import ScopeProducers with ImportScopeProducer. You may also directly import / create attachments via GetAttachmentDatabase. 3.3) Call Compile (and validate the return code). 3.4) Call Execute (and validate the return code). 3.5) Call EndFrame() to complete execution.
== Statistics ==
Statistics may be gathered for a frame after EndFrame completes. The following statistics are reported: 1) Transient attachment usages with scope timeline. This data represents a grid where one axis is the scope execution order for the current frame, and the other axis is the internal aliased heap (i.e. starting at 0 bytes). The grid communicates the start and end points for each attachment. This data is useful when visualized to show overlap between attachments. 2) GPU timing information of each scope for each queue. GPU timing accuracy depends on the platform; certain platforms (like mobile) do not have a way to extract exact GPU timings. Thus, they may instead represent approximations. 3) GPU memory usage across the RHI associated with the device.
The platform may or may not publish this information. If not, the method will return a null pointer.
== Pool Resolves ==
FrameScheduler contains a single "root" Graphics scope which is always the first scope added to the graph. All subsequent scopes take on a dependency to this root scope. The reason for this is twofold: 1) ResourcePool implementations need a scope to perform resolves (DMA uploads) to GPU memory. These operations occur first in the frame to avoid complicating pool / scope dependencies. Hence, this is done synchronously on the Graphics queue. 2) To make resource transitions and aliasing easier, the first scope in an attachment chain should be a Graphics scope. The root scope guarantees this to be true for any scenario.
== Restrictions ==
Currently, only a one frame scheduler instance is supported. This restriction can be lifted if the ResourceEventBus is replaced with a non-singleton queue data structure. Currently, it is only possible to flush this queue globally, which is incompatible with multiple frame schedulers. See [LY-83241] for more information.
| MessageOutcome AZ::RHI::FrameScheduler::Compile | ( | const FrameSchedulerCompileRequest & | compileRequest | ) |
Compiles the schedule. This should be called after successive calls to RegisterScope, and before calling Execute.
| void AZ::RHI::FrameScheduler::Execute | ( | JobPolicy | jobPolicy | ) |
Executes the compiled schedule. Must be called after Compile. This will jobify recording and of command lists associated with each scope in the dependency graph.
| jobPolicy | The global job policy for the current frame. If serial, it will force serial execution even if the platform supports parallel dispatch. If parallel, it will defer to the platform for parallel dispatch support. |
|
overridevirtual |
Returns the frame graph attachment builder, which allows the user to declare global attachments.
Implements AZ::RHI::FrameGraphBuilder.
|
overridevirtual |
Imports a scope producer into the frame graph. Scope producers are prepared in the order they are imported, however the compile phase runs a topological sort based on the attachment and explicit scope dependencies.
Implements AZ::RHI::FrameGraphBuilder.
1.8.5