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::RPI::Pass Class Reference

#include <Pass.h>

Inherits AZStd::intrusive_base.

Inherited by AZ::RPI::ImageAttachmentPreviewPass, AZ::RPI::ParentPass, AZ::RPI::RenderPass, AZ::RPI::SelectorPass, AZ::Render::DepthOfFieldCopyFocusDepthToCpuPass, and AZ::Render::RayTracingAccelerationStructurePass.


struct  FramePrepareParams

Public Types

using ChildPassIndex = RHI::Handle< uint32_t, class ChildPass >

Public Member Functions

 AZ_RTTI (Pass, "{EA34FF66-631D-433B-B449-71F5647E7BB5}", AZStd::intrusive_base)
 AZ_CLASS_ALLOCATOR (Pass, SystemAllocator)
const Name & GetName () const
 Returns the name of the pass (example: Bloom)
const Name & GetPathName () const
 Return the path name of the pass (example: Root.SwapChain.Bloom)
uint32_t GetTreeDepth () const
 Returns the depth of this pass in the tree hierarchy (Root depth is 0)
uint32_t GetParentChildIndex () const
 Returns the index in the parent's array of children that this pass occupies (used for sorting passes)
uint32_t GetInputCount () const
 Returns the number of input attachment bindings.
uint32_t GetInputOutputCount () const
 Returns the number of input/output attachment bindings.
uint32_t GetOutputCount () const
 Returns the number of output attachment bindings.
const PassTemplateGetPassTemplate () const
void SetEnabled (bool enabled)
virtual bool IsEnabled () const
bool HasDrawListTag () const
bool HasPipelineViewTag () const
bool BindViewSrg () const
PassAttachmentBindingFindAttachmentBinding (const Name &slotName)
PassAttachmentBindingListView GetAttachmentBindings () const
 Return the set of attachment bindings.
ParentPassAsParent ()
 Casts the pass to a parent pass if valid, else returns nullptr.
const ParentPassAsParent () const
bool IsRootPass () const
 Returns whether the pass is the root pass.
PassTreeGetPassTree () const
 Returns the PassTree from the pass's RenderPipeline (or nullptr if there isn't one)
void QueueForBuildAndInitialization ()
 Queues the pass to have Build() and Initialize() called by the PassSystem on frame update.
void QueueForRemoval ()
 Queues the pass to have RemoveFromParent() called by the PassSystem on frame update.
void QueueForInitialization ()
 Queues the pass to have Initialize() called by the PassSystem on frame update.
void AddAttachmentBinding (PassAttachmentBinding attachmentBinding)
 Adds an attachment binding to the list of this Pass' attachment bindings.
PassAttachmentBindingGetInputBinding (uint32_t index)
PassAttachmentBindingGetInputOutputBinding (uint32_t index)
PassAttachmentBindingGetOutputBinding (uint32_t index)
void AttachBufferToSlot (AZStd::string_view slot, Data::Instance< Buffer > buffer)
void AttachBufferToSlot (const Name &slot, Data::Instance< Buffer > buffer)
void AttachImageToSlot (const Name &slot, Data::Instance< AttachmentImage > image)
virtual void GetPipelineViewTags (PipelineViewTags &outTags) const
 Collect all different view tags from this pass.
virtual void GetViewDrawListInfo (RHI::DrawListMask &outDrawListMask, PassesByDrawList &outPassesByDrawList, const PipelineViewTag &viewTag) const
 Adds this pass' DrawListTags to the outDrawListMask.
virtual RHI::DrawListTag GetDrawListTag () const
 Check if the pass has a DrawListTag. Pass' DrawListTag can be used to filter draw items.
virtual void SortDrawList (RHI::DrawList &drawList) const
 Function used by views to sort draw lists. Can be overridden so passes can provide custom sort functionality.
virtual const PipelineViewTag & GetPipelineViewTag () const
 Check if the pass is associated to a view. If pass has a pipeline view tag, the rpi view assigned to this view tag will have pass's draw list tag.
virtual void SetRenderPipeline (RenderPipeline *pipeline)
 Set render pipeline this pass belongs to.
RenderPipelineGetRenderPipeline () const
SceneGetScene () const
virtual void Validate (PassValidationResults &validationResults)
virtual void DebugPrint () const
 Prints the pass.
TimestampResult GetLatestTimestampResult () const
 Return the latest Timestamp result of this pass.
PipelineStatisticsResult GetLatestPipelineStatisticsResult () const
 Return the latest PipelineStatistic result of this pass.
virtual void SetTimestampQueryEnabled (bool enable)
 Enables/Disables Timestamp queries for this pass.
virtual void SetPipelineStatisticsQueryEnabled (bool enable)
 Enables/Disables PipelineStatistics queries for this pass.
bool ReadbackAttachment (AZStd::shared_ptr< AttachmentReadback > readback, uint32_t readbackIndex, const Name &slotName, PassAttachmentReadbackOption option=PassAttachmentReadbackOption::Output, const RHI::ImageSubresourceRange *mipsRange=nullptr)
bool IsTimestampQueryEnabled () const
 Returns whether the Timestamp queries is enabled/disabled for this pass.
bool IsPipelineStatisticsQueryEnabled () const
 Returns whether the PipelineStatistics queries is enabled/disabled for this pass.
void PrintIndent (AZStd::string &stringOutput, uint32_t indent) const
 Helper function to print spaces to indent the pass.
void PrintPassName (AZStd::string &stringOutput, uint32_t indent=0) const
 Prints the name of the pass.
void DebugPrintBinding (AZStd::string &stringOutput, const PassAttachmentBinding &binding) const
 Prints the attachment binding at the given index.
void DebugPrintBindingAndConnection (AZStd::string &stringOutput, uint8_t bindingIndex) const
 Prints the attachment binding at the given index and its connection.
void PrintErrors () const
 Prints the pass name and all the errors accumulated during build and setup.
void PrintWarnings () const
 Prints the pass name and all the warnings accumulated during build and setup.
void PrintMessages (const AZStd::vector< AZStd::string > &messages) const
 Helper function to print an array of messages (like errors or warnings) for a pass.
void PrintBindingsWithoutAttachments (uint32_t slotTypeMask) const
 Prints the pass and all the list of inputs and input/outputs that are missing an attachment.
ParentPassGetParent () const
 Returns pointer to the parent pass.
PassState GetPassState () const
void UpdateConnectedBindings ()
void UpdateConnectedInputBindings ()
void UpdateConnectedOutputBindings ()

Protected Member Functions

 Pass (const PassDescriptor &descriptor)
PassDescriptor GetPassDescriptor () const
void ImportAttachments (RHI::FrameGraphAttachmentInterface attachmentDatabase)
Ptr< PassFindAdjacentPass (const Name &passName)
const PassAttachmentBindingFindAttachmentBinding (const Name &slotName) const
Ptr< PassAttachmentFindOwnedAttachment (const Name &attachmentName) const
Ptr< PassAttachmentFindAttachment (const Name &slotName) const
const PassAttachmentBindingFindAdjacentBinding (const PassAttachmentRef &attachmentRef, const char *attachmentSourceTypeDebugName="attachment")
void ProcessConnection (const PassConnection &connection, uint32_t slotTypeMask=0xFFFFFFFF)
void LogError (AZStd::string &&message)
void LogWarning (AZStd::string &&message)
void Reset ()
void Build (bool calledFromPassSystem=false)
void Initialize ()
void OnInitializationFinished ()
void FrameBegin (FramePrepareParams params)
void FrameEnd ()
void UpdateReadbackAttachment (FramePrepareParams params, bool beforeAddScopes)
void UpdateAttachmentCopy (FramePrepareParams params)

Protected Attributes

const Name PassNameThis {"This"}
const Name PassNameParent {"Parent"}
const Name PipelineKeyword {"Pipeline"}
const Name PipelineGlobalKeyword {"PipelineGlobal"}
AZStd::fixed_vector< PassAttachmentBinding, PassAttachmentBindingCountMax > m_attachmentBindings
AZStd::vector< Ptr< PassAttachment > > m_ownedAttachments
AZStd::vector< Pass * > m_executeBeforePasses
AZStd::vector< Pass * > m_executeAfterPasses
RenderPipelinem_pipeline = nullptr
AZStd::shared_ptr< const PassTemplatem_template = nullptr
PassRequest m_request
ParentPassm_parent = nullptr
PipelineViewTag m_viewTag
struct {
   union {
      struct {
         uint64_t   m_createdByPassRequest: 1
         uint64_t   m_enabled: 1
         uint64_t   m_parentEnabled: 1
         uint64_t   m_alreadyCreatedChildren: 1
         uint64_t   m_createChildren: 1
         uint64_t   m_partOfHierarchy: 1
         uint64_t   m_hasDrawListTag: 1
         uint64_t   m_bindViewSrg: 1
         uint64_t   m_timestampQueryEnabled: 1
         uint64_t   m_pipelineStatisticsQueryEnabled: 1
         uint64_t   m_isPipelineRoot: 1
         uint64_t   m_containsGlobalReference: 1
      uint64_t   m_allFlags = 0
AZStd::vector< AZStd::string > m_errorMessages
AZStd::vector< AZStd::string > m_warningMessages
uint32_t m_errors = 0
uint32_t m_warnings = 0
RHI::DrawListSortType m_drawListSortType = RHI::DrawListSortType::KeyThenDepth
AZStd::shared_ptr< AttachmentReadbackm_attachmentReadback
PassAttachmentReadbackOption m_readbackOption
AZStd::weak_ptr< ImageAttachmentCopym_attachmentCopy
AZStd::shared_ptr< PassDatam_passData = nullptr
 Optional data used during pass initialization.

Static Protected Attributes

static const size_t MessageLogLimit = 256


class ImageAttachmentPreviewPass

Detailed Description

Atom's base pass class (every pass class in Atom must derive from this class).

Passes are organized into a tree hierarchy with the derived ParentPass class. The root of the entire hierarchy is owned by the PassSystem.

When authoring a new pass class, inherit from Pass and override any of the virtual functions ending with 'Internal' to define the behavior of your passes. These virtual are recursively called in preorder traversal throughout the pass tree. Only FrameBegin and FrameEnd are guaranteed to be called per frame. The other override-able functions are called as needed when scheduled with the PassSystem. See QueueForBuildAndInitialization, QueueForRemoval and QueueForInitialization.

Passes are created by the PassFactory. They can be created using either Pass Name, a PassTemplate, or a PassRequest. To register your pass class with the PassFactory, you'll need to write a static create method (see ParentPass and RenderPass for examples) and register this create method with the PassFactory.

Member Function Documentation

◆ AttachBufferToSlot()

void AZ::RPI::Pass::AttachBufferToSlot ( AZStd::string_view  slot,
Data::Instance< Buffer buffer 

Attach an external buffer resource as attachment to specified slot The buffer will be added as a pass attachment then attach to the pass slot Note: the pass attachment and binding will be removed after the general Build call. you can add this call in pass' BuildInternal so it will be added whenever attachments get rebuilt

◆ DebugPrint()

virtual void AZ::RPI::Pass::DebugPrint ( ) const

Prints the pass.

Reimplemented in AZ::RPI::ParentPass.

◆ GetDrawListTag()

virtual RHI::DrawListTag AZ::RPI::Pass::GetDrawListTag ( ) const

Check if the pass has a DrawListTag. Pass' DrawListTag can be used to filter draw items.

Reimplemented in AZ::Render::ProjectedShadowmapsPass, and AZ::RPI::RasterPass.

◆ GetPassTemplate()

const PassTemplate * AZ::RPI::Pass::GetPassTemplate ( ) const

Returns the pass template which was used for create this pass. It may return nullptr if the pass wasn't create from a template

◆ GetPipelineViewTag()

virtual const PipelineViewTag & AZ::RPI::Pass::GetPipelineViewTag ( ) const

Check if the pass is associated to a view. If pass has a pipeline view tag, the rpi view assigned to this view tag will have pass's draw list tag.

Reimplemented in AZ::Render::ProjectedShadowmapsPass.

◆ GetPipelineViewTags()

virtual void AZ::RPI::Pass::GetPipelineViewTags ( PipelineViewTags &  outTags) const

Collect all different view tags from this pass.

Reimplemented in AZ::RPI::ParentPass.

◆ GetViewDrawListInfo()

virtual void AZ::RPI::Pass::GetViewDrawListInfo ( RHI::DrawListMask &  outDrawListMask,
PassesByDrawList &  outPassesByDrawList,
const PipelineViewTag &  viewTag 
) const

Adds this pass' DrawListTags to the outDrawListMask.

Reimplemented in AZ::RPI::ParentPass.

◆ IsEnabled()

virtual bool AZ::RPI::Pass::IsEnabled ( ) const

Reimplemented in AZ::Render::BloomParentPass.

◆ ReadbackAttachment()

bool AZ::RPI::Pass::ReadbackAttachment ( AZStd::shared_ptr< AttachmentReadback readback,
uint32_t  readbackIndex,
const Name &  slotName,
PassAttachmentReadbackOption  option = PassAttachmentReadbackOption::Output,
const RHI::ImageSubresourceRange mipsRange = nullptr 

For an image attachment, attached to a specific slot name, reads back, from GPU to CPU memory, one or more mip levels. For a buffer attachment, attached to a specific slot name, reads it back from GPU memory to CPU memory.

readbackThe AttachmentReadback object which is used for readback. Its callback function will be called when readback is finished.
readbackIndexindex from the frame capture system to identify which capture is in progress.
slotNameThe attachment bound to the slot with this slotName is to be read back.
optionThe option is used for choosing input or output state when readback an InputOutput attachment. It's ignored if the attachment isn't an InputOutput attachment. This means that if @option == PassAttachmentReadbackOption::Input, then we'll read the attachment mips BEFORE the Pass runs its main shader. if @option == PassAttachmentReadbackOption::Output, then we'll read the attachment mips AFTER the Pass runs its main shader.
mipsRangeApplicable ONLY to Image Attachments. If NOT null, defines the list of mip levels that will be read back. If null, only mip level 0 will be read back. Return true if the readback request was successful. User may expect the AttachmentReadback's callback function would be called.

◆ SetEnabled()

void AZ::RPI::Pass::SetEnabled ( bool  enabled)

Enable/disable this pass If the pass is disabled, it (and any children if it's a ParentPass) won't be rendered.

◆ SetPipelineStatisticsQueryEnabled()

virtual void AZ::RPI::Pass::SetPipelineStatisticsQueryEnabled ( bool  enable)

Enables/Disables PipelineStatistics queries for this pass.

Reimplemented in AZ::RPI::ParentPass.

◆ SetRenderPipeline()

virtual void AZ::RPI::Pass::SetRenderPipeline ( RenderPipeline pipeline)

Set render pipeline this pass belongs to.

Reimplemented in AZ::RPI::ParentPass.

◆ SetTimestampQueryEnabled()

virtual void AZ::RPI::Pass::SetTimestampQueryEnabled ( bool  enable)

Enables/Disables Timestamp queries for this pass.

Reimplemented in AZ::RPI::ParentPass.

◆ Validate()

virtual void AZ::RPI::Pass::Validate ( PassValidationResults validationResults)

Validates entire tree hierarchy (ensures passes have valid state and attachments). Functionality compiled out if AZ_RPI_ENABLE_PASS_VALIDATION is not defined.

Reimplemented in AZ::RPI::ParentPass, and AZ::RPI::RasterPass.

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