#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
	Returns the frame graph attachment builder, which allows the user to declare global attachments.

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.

virtual FrameGraphAttachmentInterface	GetAttachmentDatabase ()=0
	Returns the frame graph attachment builder, which allows the user to declare global attachments.

virtual ResultCode	ImportScopeProducer (ScopeProducer &scopeProducer)=0

Detailed Description

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

Member Function Documentation

◆ Compile()

MessageOutcome AZ::RHI::FrameScheduler::Compile ( const FrameSchedulerCompileRequest & compileRequest )

Compiles the schedule. This should be called after successive calls to RegisterScope, and before calling Execute.

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

Parameters

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.

◆ GetAttachmentDatabase()

FrameGraphAttachmentInterface AZ::RHI::FrameScheduler::GetAttachmentDatabase ( )

overridevirtual

Returns the frame graph attachment builder, which allows the user to declare global attachments.

Implements AZ::RHI::FrameGraphBuilder.

◆ ImportScopeProducer()

ResultCode AZ::RHI::FrameScheduler::ImportScopeProducer ( ScopeProducer & scopeProducer )