Open 3D Engine Atom Gem API Reference  2205.0
O3DE is an open-source, fully-featured, high-fidelity, modular 3D engine for building games and simulations, available to every industry.
Public Member Functions | Static Public Member Functions | Friends | List of all members
AZ::RPI::Shader Class Referencefinal

#include <Shader.h>

Inherits InstanceData, MultiHandler, and Handler.

Public Member Functions

 AZ_INSTANCE_DATA (Shader, "{232D8BD6-3BD4-4842-ABD2-F380BD5B0863}")
 AZ_CLASS_ALLOCATOR (Shader, SystemAllocator, 0)
SupervariantIndex GetSupervariantIndex ()
 returns the SupervariantIndex that corresponds to the given supervariant name given at instantiation.
ShaderOptionGroup CreateShaderOptionGroup () const
 Constructs a shader option group suitable to generate a shader variant key for this shader.
const ShaderVariantGetVariant (const ShaderVariantId &shaderVariantId)
ShaderVariantSearchResult FindVariantStableId (const ShaderVariantId &shaderVariantId) const
const ShaderVariantGetVariant (ShaderVariantStableId shaderVariantStableId)
const ShaderVariantGetRootVariant ()
 Convenient function that returns the root variant.
RHI::PipelineStateType GetPipelineStateType () const
 Returns the pipeline state type generated by variants of this shader.
const ShaderInputContractGetInputContract () const
 Returns the ShaderInputContract which describes which inputs the shader requires.
const ShaderOutputContractGetOutputContract () const
 Returns the ShaderOutputContract which describes which outputs the shader requires.
const RHI::PipelineStateAcquirePipelineState (const RHI::PipelineStateDescriptor &descriptor) const
 Acquires a pipeline state directly from a descriptor.
const RHI::Ptr< RHI::ShaderResourceGroupLayout > & FindShaderResourceGroupLayout (const Name &shaderResourceGroupName) const
 Finds and returns the shader resource group asset with the requested name. Returns an empty handle if no matching group was found.
const RHI::Ptr< RHI::ShaderResourceGroupLayout > & FindShaderResourceGroupLayout (uint32_t bindingSlot) const
 Finds and returns the shader resource group asset associated with the requested binding slot. Returns an empty handle if no matching group was found.
const RHI::Ptr< RHI::ShaderResourceGroupLayout > & FindFallbackShaderResourceGroupLayout () const
 Finds and returns the shader resource group asset designated as a ShaderVariantKey fallback.
AZStd::span< const RHI::Ptr< RHI::ShaderResourceGroupLayout > > GetShaderResourceGroupLayouts () const
 Returns the set of shader resource groups referenced by all variants in the shader asset.
const Data::Asset< ShaderAsset > & GetAsset () const
 Returns a reference to the asset used to initialize this shader.
RHI::DrawListTag GetDrawListTag () const

Static Public Member Functions

static Data::Instance< ShaderFindOrCreate (const Data::Asset< ShaderAsset > &shaderAsset, const Name &supervariantName)
 Returns the shader instance associated with the provided asset.
static Data::Instance< ShaderFindOrCreate (const Data::Asset< ShaderAsset > &shaderAsset)
 Same as above, but uses the default supervariant.


class ShaderSystem

Detailed Description

Shader is effectively an 'uber-shader' containing a collection of 'variants'. Variants are designed to be 'variations' on the same core shader technique. To enforce this, every variant in the shader shares the same pipeline layout (i.e. set of shader resource groups).

A shader owns a library of pipeline states. When a variant is resolved to a pipeline state, its lifetime is determined by the lifetime of the Shader (unless an explicit reference is taken). If an asset reload event occurs, the pipeline state cache is reset.

To use Shader: 1) Construct a ShaderOptionGroup instance using CreateShaderOptionGroup. 2) Configure the group by setting values on shader options. 3) Find the ShaderVariantStableId using the ShaderVariantId generated from the configured ShaderOptionGroup. 4) Acquire the ShaderVariant instance using the ShaderVariantStableId. 5) Configure a pipeline state descriptor on the variant; make local overrides as necessary (e.g. to configure runtime render state). 6) Acquire a RHI::PipelineState instance from the shader using the configured pipeline state descriptor.

Remember that the returned RHI::PipelineState instance lifetime is tied to the Shader lifetime. If you need guarantee lifetime, it is safe to take a reference on the returned pipeline state.

Member Function Documentation

◆ FindVariantStableId()

ShaderVariantSearchResult AZ::RPI::Shader::FindVariantStableId ( const ShaderVariantId shaderVariantId) const

Finds the best matching shader variant asset and returns its StableId. In cases where you can't cache the ShaderVariant, and recurrently you may need the same ShaderVariant at different times, then it can be convenient (and more performant) to call this method to cache the ShaderVariantStableId and call GetVariant(ShaderVariantStableId) when needed. If the asset is not immediately found in the file system, it will return the StableId of the root variant. Callers should listen to ShaderReloadNotificationBus to get notified whenever the exact variant is loaded and available or if a variant changes, etc.

◆ GetDrawListTag()

RHI::DrawListTag AZ::RPI::Shader::GetDrawListTag ( ) const

Returns the DrawListTag that identifies which Pass and View objects will process this shader. This tag corresponds to the ShaderAsset object's DrawListName.

◆ GetVariant() [1/2]

const ShaderVariant& AZ::RPI::Shader::GetVariant ( const ShaderVariantId shaderVariantId)

Finds the best matching ShaderVariant for the given shaderVariantId, If the variant is loaded and ready it will return the corresponding ShaderVariant. If the variant is not yet available it will return the root ShaderVariant. Callers should listen to ShaderReloadNotificationBus to get notified whenever the exact variant is loaded and available or if a variant changes, etc. This function should be your one stop shop to get a ShaderVariant from a ShaderVariantId. Alternatively: You can call FindVariantStableId() followed by GetVariant(shaderVariantStableId).

◆ GetVariant() [2/2]

const ShaderVariant& AZ::RPI::Shader::GetVariant ( ShaderVariantStableId  shaderVariantStableId)

Returns the variant associated with the provided StableId. You should call FindVariantStableId() which caches the variant, later when this function is called the variant is fetched from a local map. If the variant is not found, the root variant is returned. "Alternatively: a more convenient approach is to call GetVariant(ShaderVariantId) which does both, the find and the get."

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