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 Types | Public Member Functions | Static Public Member Functions | Static Public Attributes | Friends | List of all members
AZ::RPI::Material Class Reference

#include <Material.h>

Inherits InstanceData, Handler, MultiHandler, and Handler.

Public Types

using ChangeId = size_t
 Material objects use a ChangeId to track when changes have been made to the material at runtime. See GetCurrentChangeId()

Public Member Functions

 AZ_INSTANCE_DATA (Material, "{C99F75B2-8BD5-4CD8-8672-1E01EF0A04CF}")
 AZ_CLASS_ALLOCATOR (Material, SystemAllocator, 0)
MaterialPropertyIndex FindPropertyIndex (const Name &propertyId, bool *wasRenamed=nullptr, Name *newName=nullptr) const
template<typename Type >
bool SetPropertyValue (MaterialPropertyIndex index, const Type &value)
template<typename Type >
const Type & GetPropertyValue (MaterialPropertyIndex index) const
 Gets the value of a material property. The template data type must match the property's data type.
bool SetPropertyValue (MaterialPropertyIndex index, const MaterialPropertyValue &value)
const MaterialPropertyValueGetPropertyValue (MaterialPropertyIndex index) const
const AZStd::vector< MaterialPropertyValue > & GetPropertyValues () const
const MaterialPropertyFlags & GetPropertyDirtyFlags () const
 Gets flags indicating which properties have been modified.
RHI::ConstPtr< MaterialPropertiesLayoutGetMaterialPropertiesLayout () const
 Gets the material properties layout.
bool Compile ()
ChangeId GetCurrentChangeId () const
const ShaderCollectionGetShaderCollection () const
 Return the set of shaders to be run by this material.
AZ::Outcome< uint32_t > SetSystemShaderOption (const Name &shaderOptionName, RPI::ShaderOptionValue value)
void SetPsoHandlingOverride (MaterialPropertyPsoHandling psoHandlingOverride)
const RHI::ShaderResourceGroupGetRHIShaderResourceGroup () const
const Data::Asset< MaterialAsset > & GetAsset () const
bool CanCompile () const
 Returns whether the material is ready to compile pending changes. (Materials can only be compiled once per frame because SRGs can only be compiled once per frame).
bool NeedsCompile () const
 Returns whether the material has property changes that have not been compiled yet.

Static Public Member Functions

static Data::Instance< MaterialFindOrCreate (const Data::Asset< MaterialAsset > &materialAsset)
static Data::Instance< MaterialCreate (const Data::Asset< MaterialAsset > &materialAsset)

Static Public Attributes

static const ChangeId DEFAULT_CHANGE_ID = 0
 GetCurrentChangeId() will never return this value, so client code can use this to initialize a ChangeId that is immediately dirty.


class MaterialSystem

Detailed Description

Provides runtime material functionality based on a MaterialAsset. The material operates on a set of properties, which are configured primarily at build-time through the MaterialAsset. These properties are used to configure shader system inputs at runtime.

Material property values can be accessed at runtime, using the SetPropertyValue() and GetPropertyValue(). After applying all property changes, Compile() must be called to apply those changes to the shader system.

If RPI validation is enabled, the class will perform additional error checking. If a setter method fails an error is emitted and the call returns false without performing the requested operation. Likewise, if a getter method fails, an error is emitted and an empty value is returned. If validation is disabled, the operation is always performed.

Member Function Documentation

◆ Compile()

bool AZ::RPI::Material::Compile ( )

Must be called after changing any material property values in order to apply those changes to the shader. Does nothing if NeedsCompile() is false or CanCompile() is false.

whether compilation occurred

◆ FindPropertyIndex()

MaterialPropertyIndex AZ::RPI::Material::FindPropertyIndex ( const Name &  propertyId,
bool *  wasRenamed = nullptr,
Name *  newName = nullptr 
) const

Finds the material property index from the material property ID

wasRenamedoptional parameter that is set to true if @propertyId is an old name and an automatic rename was applied to find the index.
newNameoptional parameter that is set to the new property name, if the property was renamed.

◆ GetCurrentChangeId()

ChangeId AZ::RPI::Material::GetCurrentChangeId ( ) const

Returns an ID that can be used to track whether the material has changed since the last time client code read it. This gets incremented every time a change is made, like by calling SetPropertyValue().

◆ SetPropertyValue() [1/2]

bool AZ::RPI::Material::SetPropertyValue ( MaterialPropertyIndex  index,
const MaterialPropertyValue value 

Sets the value of a material property. The @value data type must match the property's data type.

true if property value was changed

◆ SetPropertyValue() [2/2]

template<typename Type >
bool AZ::RPI::Material::SetPropertyValue ( MaterialPropertyIndex  index,
const Type &  value 

Sets the value of a material property. The template data type must match the property's data type.

true if property value was changed

◆ SetPsoHandlingOverride()

void AZ::RPI::Material::SetPsoHandlingOverride ( MaterialPropertyPsoHandling  psoHandlingOverride)

Override the material's default PSO handling setting. This is normally used in tools like Asset Processor or Material Editor to allow changes that impact Pipeline State Objects which is not allowed at runtime. See MaterialPropertyPsoHandling for more details. Do not set this in the shipping runtime unless you know what you are doing.

◆ SetSystemShaderOption()

AZ::Outcome<uint32_t> AZ::RPI::Material::SetSystemShaderOption ( const Name &  shaderOptionName,
RPI::ShaderOptionValue  value 

Attempts to set the value of a system-level shader option that is controlled by this material. This applies to all shaders in the material's ShaderCollection. Note, this may only be used to set shader options that are not "owned" by the material.

shaderOptionNamethe name of the shader option(s) to set
valuethe new value for the shader option(s)
returnthe number of shader options that were updated, or Failure if the material owns the indicated shader option.

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