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.
Classes | Public Types | Public Member Functions | List of all members
AZ::RHI::ShaderResourceGroupData Class Reference

#include <ShaderResourceGroupData.h>

Classes

struct  BindlessResourceViews
 

Public Types

enum class  ResourceType : uint32_t {
  ConstantData , BufferView , ImageView , BufferViewUnboundedArray ,
  ImageViewUnboundedArray , Sampler , Count
}
 
enum class  ResourceTypeMask : uint32_t {
  None = 0 , ConstantDataMask = AZ_BIT(static_cast<uint32_t>(ResourceType::ConstantData)) , BufferViewMask = AZ_BIT(static_cast<uint32_t>(ResourceType::BufferView)) , ImageViewMask = AZ_BIT(static_cast<uint32_t>(ResourceType::ImageView)) ,
  BufferViewUnboundedArrayMask = AZ_BIT(static_cast<uint32_t>(ResourceType::BufferViewUnboundedArray)) , ImageViewUnboundedArrayMask = AZ_BIT(static_cast<uint32_t>(ResourceType::ImageViewUnboundedArray)) , SamplerMask = AZ_BIT(static_cast<uint32_t>(ResourceType::Sampler))
}
 

Public Member Functions

 ShaderResourceGroupData ()
 By default creates an empty data structure. Must be initialized before use.
 
 ShaderResourceGroupData (const ShaderResourceGroupLayout *shaderResourceGroupLayout)
 Creates shader resource group data from a layout.
 
 ShaderResourceGroupData (const ShaderResourceGroupPool &shaderResourceGroupPool)
 Creates shader resource group data from a pool (usable on any SRG with the same layout).
 
 ShaderResourceGroupData (const ShaderResourceGroup &shaderResourceGroup)
 Creates shader resource group data from an SRG instance (usable on any SRG with the same layout).
 
 AZ_DEFAULT_COPY_MOVE (ShaderResourceGroupData)
 
ShaderInputBufferIndex FindShaderInputBufferIndex (const Name &name) const
 
ShaderInputImageIndex FindShaderInputImageIndex (const Name &name) const
 
ShaderInputSamplerIndex FindShaderInputSamplerIndex (const Name &name) const
 
ShaderInputConstantIndex FindShaderInputConstantIndex (const Name &name) const
 
bool SetImageView (ShaderInputImageIndex inputIndex, const ImageView *imageView, uint32_t arrayIndex)
 Sets one image view for the given shader input index.
 
bool SetImageViewArray (ShaderInputImageIndex inputIndex, AZStd::span< const ImageView *const > imageViews, uint32_t arrayIndex=0)
 Sets an array of image view for the given shader input index.
 
bool SetImageViewUnboundedArray (ShaderInputImageUnboundedArrayIndex inputIndex, AZStd::span< const ImageView *const > imageViews)
 Sets an unbounded array of image view for the given shader input index.
 
bool SetBufferView (ShaderInputBufferIndex inputIndex, const BufferView *bufferView, uint32_t arrayIndex=0)
 Sets one buffer view for the given shader input index.
 
bool SetBufferViewArray (ShaderInputBufferIndex inputIndex, AZStd::span< const BufferView *const > bufferViews, uint32_t arrayIndex=0)
 Sets an array of image view for the given shader input index.
 
bool SetBufferViewUnboundedArray (ShaderInputBufferUnboundedArrayIndex inputIndex, AZStd::span< const BufferView *const > bufferViews)
 Sets an unbounded array of buffer view for the given shader input index.
 
bool SetSampler (ShaderInputSamplerIndex inputIndex, const SamplerState &sampler, uint32_t arrayIndex=0)
 Sets one sampler for the given shader input index, using the bindingIndex as the key.
 
bool SetSamplerArray (ShaderInputSamplerIndex inputIndex, AZStd::span< const SamplerState > samplers, uint32_t arrayIndex=0)
 Sets an array of samplers for the given shader input index.
 
bool SetConstantRaw (ShaderInputConstantIndex inputIndex, const void *bytes, uint32_t byteCount)
 Assigns constant data for the given constant shader input index.
 
bool SetConstantRaw (ShaderInputConstantIndex inputIndex, const void *bytes, uint32_t byteOffset, uint32_t byteCount)
 
template<typename T >
bool SetConstant (ShaderInputConstantIndex inputIndex, const T &value)
 Assigns a value of type T to the constant shader input.
 
template<typename T >
bool SetConstantMatrixRows (ShaderInputConstantIndex inputIndex, const T &value, uint32_t rowCount)
 Assigns a specified number of rows from a Matrix.
 
template<typename T >
bool SetConstant (ShaderInputConstantIndex inputIndex, const T &value, uint32_t arrayIndex)
 Assigns a value of type T to the constant shader input, at an array offset.
 
template<typename T >
bool SetConstantArray (ShaderInputConstantIndex inputIndex, AZStd::span< const T > values)
 Assigns an array of type T to the constant shader input.
 
bool SetConstantData (const void *bytes, uint32_t byteCount)
 
bool SetConstantData (const void *bytes, uint32_t byteOffset, uint32_t byteCount)
 
const ConstPtr< ImageView > & GetImageView (ShaderInputImageIndex inputIndex, uint32_t arrayIndex) const
 Returns a single image view associated with the image shader input index and array offset.
 
AZStd::span< const ConstPtr< ImageView > > GetImageViewArray (ShaderInputImageIndex inputIndex) const
 Returns a span of image views associated with the given image shader input index.
 
AZStd::span< const ConstPtr< ImageView > > GetImageViewUnboundedArray (ShaderInputImageUnboundedArrayIndex inputIndex) const
 Returns an unbounded span of image views associated with the given buffer shader input index.
 
const ConstPtr< BufferView > & GetBufferView (ShaderInputBufferIndex inputIndex, uint32_t arrayIndex) const
 Returns a single buffer view associated with the buffer shader input index and array offset.
 
AZStd::span< const ConstPtr< BufferView > > GetBufferViewArray (ShaderInputBufferIndex inputIndex) const
 Returns a span of buffer views associated with the given buffer shader input index.
 
AZStd::span< const ConstPtr< BufferView > > GetBufferViewUnboundedArray (ShaderInputBufferUnboundedArrayIndex inputIndex) const
 Returns an unbounded span of buffer views associated with the given buffer shader input index.
 
const SamplerState & GetSampler (ShaderInputSamplerIndex inputIndex, uint32_t arrayIndex) const
 Returns a single sampler associated with the sampler shader input index and array offset.
 
AZStd::span< const SamplerState > GetSamplerArray (ShaderInputSamplerIndex inputIndex) const
 Returns a span of samplers associated with the sampler shader input index.
 
template<typename T >
AZStd::span< const T > GetConstantArray (ShaderInputConstantIndex inputIndex) const
 
template<typename T >
T GetConstant (ShaderInputConstantIndex inputIndex) const
 
template<typename T >
T GetConstant (ShaderInputConstantIndex inputIndex, uint32_t arrayIndex) const
 
AZStd::span< const uint8_t > GetConstantRaw (ShaderInputConstantIndex inputIndex) const
 Returns constant data for the given shader input index as a span of bytes.
 
AZStd::span< const ConstPtr< ImageView > > GetImageGroup () const
 
AZStd::span< const ConstPtr< BufferView > > GetBufferGroup () const
 
AZStd::span< const SamplerState > GetSamplerGroup () const
 
void ResetViews ()
 
AZStd::span< const uint8_t > GetConstantData () const
 
const ConstantsData & GetConstantsData () const
 Returns the underlying ConstantsData struct.
 
const ShaderResourceGroupLayout * GetLayout () const
 Returns the shader resource layout for this group.
 
void ResetUpdateMask ()
 Reset the update mask.
 
void EnableResourceTypeCompilation (ResourceTypeMask resourceTypeMask)
 Enable compilation for a resourceType specified by resourceTypeMask.
 
uint32_t GetUpdateMask () const
 Returns the mask that is suppose to indicate which resource type was updated.
 
void SetBindlessViews (ShaderInputBufferIndex indirectResourceBufferIndex, const RHI::BufferView *indirectResourceBuffer, AZStd::span< const ImageView *const > imageViews, uint32_t *outIndices, AZStd::span< bool > isViewReadOnly, uint32_t arrayIndex=0)
 
void SetBindlessViews (ShaderInputBufferIndex indirectResourceBufferIndex, const RHI::BufferView *indirectResourceBuffer, AZStd::span< const BufferView *const > bufferViews, uint32_t *outIndices, AZStd::span< bool > isViewReadOnly, uint32_t arrayIndex=0)
 
const uint32_t GetBindlessViewsSize () const
 Get the size of the bindless view map.
 
const AZStd::unordered_map< AZStd::pair< ShaderInputBufferIndex, uint32_t >, BindlessResourceViews > & GetBindlessResourceViews () const
 Return all the bindless views referenced indirectly via SetBindlessViews api.
 

Detailed Description

Shader resource group data is a light abstraction over a flat table of shader resources and shader constants. It utilizes basic reflection information from the shader resource group layout to construct the table in the correct format for the platform-specific compile phase. The user is expected to create instances of this class, fill data, and then push it to an SRG instance.

The shader resource group (SRG) includes a set of built-in SRG constants in a single internally-managed constant buffer. This is separate from any custom constant buffers that some SRG layouts may include as shader resources. SRG constants can be conveniently accessed through a variety of SetConstant.

This data structure holds strong references to the resource views bound onto it.

NOTE [Performance Warning]: This data structure allocates memory. If compiling several SRG's in a batch, prefer to share the data between them (i.e. within a single job).

NOTE [SRG Constants]: The ConstantsData class is used for efficiently setting/getting the constants values of the SRG.

Member Function Documentation

◆ FindShaderInputBufferIndex()

ShaderInputBufferIndex AZ::RHI::ShaderResourceGroupData::FindShaderInputBufferIndex ( const Name &  name) const

Resolves a shader input name to an index using reflection. For performance reasons, this resolve operation should be performed once at initialization time (or as infrequently as possible). Assignment of shader inputs is faster when done using the shader input index directly.

◆ GetConstant() [1/2]

template<typename T >
T AZ::RHI::ShaderResourceGroupData::GetConstant ( ShaderInputConstantIndex  inputIndex) const

Returns the constant data as type 'T' returned by value. The size of the constant region must match the size of T exactly. Otherwise, an empty instance is returned.

◆ GetConstant() [2/2]

template<typename T >
T AZ::RHI::ShaderResourceGroupData::GetConstant ( ShaderInputConstantIndex  inputIndex,
uint32_t  arrayIndex 
) const

Treats the constant input as an array of type T, returning the element by value at the specified array index. The size of the constant region must equally partition into an array of type T. Otherwise, an empty instance is returned.

◆ GetConstantArray()

template<typename T >
AZStd::span< const T > AZ::RHI::ShaderResourceGroupData::GetConstantArray ( ShaderInputConstantIndex  inputIndex) const

Returns constant data for the given shader input index as a template type. The stride of T must match the size of the constant input region. The number of elements in the returned span is the number of evenly divisible elements. If the strides do not match, an empty span is returned.

◆ GetConstantData()

AZStd::span< const uint8_t > AZ::RHI::ShaderResourceGroupData::GetConstantData ( ) const

Returns the opaque constant data populated by calls to SetConstant and SetConstantData.

CAUTION! Different platforms might follow different packing rules for the internally-managed SRG constant buffer.

◆ GetImageGroup()

AZStd::span< const ConstPtr< ImageView > > AZ::RHI::ShaderResourceGroupData::GetImageGroup ( ) const

Returns a {Buffer, Image, Sampler} shader resource group. Each resource type has its own separate group.

◆ ResetViews()

void AZ::RHI::ShaderResourceGroupData::ResetViews ( )

Reset image and buffer views setup for this ShaderResourceGroupData So it won't hold references for any RHI resources

◆ SetBindlessViews() [1/2]

void AZ::RHI::ShaderResourceGroupData::SetBindlessViews ( ShaderInputBufferIndex  indirectResourceBufferIndex,
const RHI::BufferView *  indirectResourceBuffer,
AZStd::span< const BufferView *const >  bufferViews,
uint32_t *  outIndices,
AZStd::span< bool >  isViewReadOnly,
uint32_t  arrayIndex = 0 
)

Update the indirect buffer view with the indices of all the buffer views which reside in the global gpu heap. Ideally higher level code can access bindless heap indices directly from the view and populate any indirect buffer directly. This API is present in case we want RHI to track bindless resources which may be needed for backends like the metal.

◆ SetBindlessViews() [2/2]

void AZ::RHI::ShaderResourceGroupData::SetBindlessViews ( ShaderInputBufferIndex  indirectResourceBufferIndex,
const RHI::BufferView *  indirectResourceBuffer,
AZStd::span< const ImageView *const >  imageViews,
uint32_t *  outIndices,
AZStd::span< bool >  isViewReadOnly,
uint32_t  arrayIndex = 0 
)

Update the indirect buffer view with the indices of all the image views which reside in the global gpu heap. Ideally higher level code can access bindless heap indices directly from the view and populate any indirect buffer directly. This API is present in case we want RHI to track bindless resources which may be needed for backends like the metal.

◆ SetConstantData()

bool AZ::RHI::ShaderResourceGroupData::SetConstantData ( const void *  bytes,
uint32_t  byteCount 
)

Assigns constant data as a whole.

CAUTION! Different platforms might follow different packing rules for the internally-managed SRG constant buffer. To set manually a constant buffer as a whole please use Constant Buffers in AZSL, instead of SRG Constants, then use RHI Buffers with constant binding flag and set the buffer memory following pragma 4 packing rule.

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