AZ::RHI::FrameGraphExecuter Class Reference

#include <FrameGraphExecuter.h>

Inherits AZ::RHI::DeviceObject.

Inherited by AZ::DX12::FrameGraphExecuter, AZ::Metal::FrameGraphExecuter, AZ::Null::FrameGraphExecuter, and AZ::Vulkan::FrameGraphExecuter.

Public Member Functions
	AZ_RTTI (FrameGraphExecuter, "{9DF0B900-A426-4056-8638-38A5007825F5}", Object)
ResultCode	Init (const FrameGraphExecuterDescriptor &descriptor)
void	Shutdown () override final
JobPolicy	GetJobPolicy () const
uint32_t	GetGroupCount () const
void	Begin (const FrameGraph &frameGraph)
FrameGraphExecuteGroup *	BeginGroup (uint32_t groupIndex)
void	EndGroup (uint32_t groupIndex)
void	End ()
Public Member Functions inherited from AZ::RHI::DeviceObject
	AZ_RTTI (DeviceObject, "{17D34F71-944C-4AF5-9823-627474C4C0A6}", Object)
bool	IsInitialized () const
	Returns whether the device object is initialized.
Device &	GetDevice () 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.

Protected Member Functions
void	SetJobPolicy (JobPolicy jobPolicy)
template<typename FrameGraphExecuteGroupType >
FrameGraphExecuteGroupType *	AddGroup ()
AZStd::span< const AZStd::unique_ptr< FrameGraphExecuteGroup > >	GetGroups () const
	Returns a list of the registered execute groups.
Protected Member Functions inherited from AZ::RHI::DeviceObject
void	Init (Device &device)
	The derived class should call this method to assign the device.
void	Shutdown () override
	Clears the current bound device to null.
Protected Member Functions inherited from AZ::RHI::Object
void	add_ref () const
void	release () const

Additional Inherited Members
Protected Attributes inherited from AZ::RHI::Object
AZStd::atomic_int	m_useCount = 0

Detailed Description

FrameGraphExecuter is a context for executing the scopes of a compiled FrameGraph on the GPU using the associated device instance. The details of how scopes are executed are platform specific.

The goal of this class is enable users to record and submit command lists at a granularity prescribed by the platform, while also respecting the 'threading' policy of the underlying platform. Modern platform implementations will allow full multi-threaded recording of command lists, while others will require serialization onto a single thread.

To ensure the maximum flexibility for each platform, scope execution is divided into two layers: 'Execute Groups', and 'Execute Contexts'.

• Execute Groups contain a list of Execute Contexts. FrameGraphExecuter::GetJobPolicy() describes the policy for whether groups can be processed serially or independently. Again, the underlying platform assigns this policy.
• Execute Contexts provides a mapping between a command list and scope. A context can either represent the full set of work for scope, or it can be 1 in a set of several contexts processing the same scope. The latter scenario is common in cases where many commands are processed within the same scope and the platform decides to partition the work across several jobs. Each execute group describes its policy for whether contexts can be recorded independently on separate threads. The class provides two API's: one for external users (e.g. the FrameScheduler), and one for the derived platform implementation. To use this class, first call Begin to prepare the executer using a compiled FrameGraph instance. Then, iterate over the execute groups and process each one (either independently or serially, depending on the platform policy). Call End to complete processing of the graph.

To implement this class, assign the job policy specific to your platform, and every Begin call, use the provided AddGroup method to partition the FrameGraph into execution groups. Each group and context will have platform specific overrides.

Member Function Documentation

AddGroup()

template<typename FrameGraphExecuteGroupType >

FrameGraphExecuteGroupType * AZ::RHI::FrameGraphExecuter::AddGroup

protected

Adds a new group of the specified type (must inherit from FrameGraphExecuteGroup) and returns an instance. The schedule maintains ownership of the class. The user is expected to initialize the instance before returning the schedule to the external client. The returned instance is not persistent and will be deleted in Reset.

Begin()

void AZ::RHI::FrameGraphExecuter::Begin

(

const FrameGraph &

frameGraph

)

Begins a new execution phase by inspecting an generating context groups from the provided frame graph instance. State within the executer is reset between each Begin / End cycle, so the implementor must rebuild the context groups each time. The frame graph instance is not stored, and must be in a compiled state.

BeginGroup()

FrameGraphExecuteGroup * AZ::RHI::FrameGraphExecuter::BeginGroup

(

uint32_t

groupIndex

)

Begins the group at specified index

Parameters

groupIndex.

The index must be less than GetGroupCount. All groups must be processed each cycle prior to calling end. The returned execute group instance is valid until EndGroup is called (using the same group index), after which the user must not access it.

End()

void AZ::RHI::FrameGraphExecuter::End

(

)

Ends the graph execution phase. Call this after all execution jobs have joined. This resets all state held by the executer.

EndGroup()

void AZ::RHI::FrameGraphExecuter::EndGroup

(

uint32_t

groupIndex

)

Ends the group at index

Parameters

groupIndex.

This invalidates the pointer returned by BeginGroup.

GetGroupCount()

uint32_t AZ::RHI::FrameGraphExecuter::GetGroupCount

(

)

const

Returns the number of context groups in the executer. The user must call BeginGroup and EndGroup on all instances prior to calling End.

GetJobPolicy()

JobPolicy AZ::RHI::FrameGraphExecuter::GetJobPolicy

(

)

const

Returns the job policy for context groups. The policy dictates whether groups can be independently traversed across multiple threads. If the value is JobPolicy::Serial, BeginGroup and EndGroup must be called in order for each group index. If the value is JobPolicy::Parallel, BeginGroup and EndGroup can be called for each group independently from any thread.

Init()

ResultCode AZ::RHI::FrameGraphExecuter::Init

(

const FrameGraphExecuterDescriptor &

descriptor

)

Initializes the frame graph executer. Instances are created in an uninitialized state. Attempting to use an uninitialized instance will result in an error (when validation is enabled). If the call fails, an error code is returned and the instance will remain in an uninitialized state.

Parameters

device

The device associated with the executer instance.

SetJobPolicy()

void AZ::RHI::FrameGraphExecuter::SetJobPolicy ( JobPolicy  jobPolicy )

protected

Platform implementations should assign the job policy for context groups if multi-threaded recording is desired. By default, it is set to JobPolicy::Serial.

Shutdown()

void AZ::RHI::FrameGraphExecuter::Shutdown ( )

finaloverridevirtual

Shuts down the frame graph executer, releasing all internal allocations. The user may re-initialize.

Reimplemented from AZ::RHI::DeviceObject.

---

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

• Gems/Atom/RHI/Code/Include/Atom/RHI/FrameGraphExecuter.h