AZ::RPI::Material Class Reference

#include <Material.h>

Inherits Data::InstanceData, Data::AssetBus::Handler, and ShaderReloadNotificationBus::MultiHandler.

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)
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 MaterialPropertyCollection &	GetPropertyCollection () const
const MaterialPropertyValue &	GetPropertyValue (MaterialPropertyIndex index) const
const AZStd::vector< MaterialPropertyValue > &	GetPropertyValues () const
const MaterialPropertyFlags &	GetPropertyDirtyFlags () const
	Gets flags indicating which properties have been modified.
RHI::ConstPtr< MaterialPropertiesLayout >	GetMaterialPropertiesLayout () const
	Gets the material properties layout.
bool	Compile ()
ChangeId	GetCurrentChangeId () const
const ShaderCollection &	GetGeneralShaderCollection () const
	Return the general purpose shader collection that applies to any render pipeline.
const ShaderCollection &	GetShaderCollection (const Name &forPipeline) const
void	ForAllShaderItems (AZStd::function< bool(const Name &materialPipelineName, const ShaderCollection::Item &shaderItem)> callback) const
bool	MaterialOwnsShaderOption (const Name &shaderOptionName) const
	Returns whether this material owns a particular shader option. In that case, SetSystemShaderOption may not be used.
AZ::Outcome< uint32_t >	SetSystemShaderOption (const Name &shaderOptionName, RPI::ShaderOptionValue value)
void	ApplyGlobalShaderOptions ()
	Apply all global shader options to this material.
void	SetPsoHandlingOverride (MaterialPropertyPsoHandling psoHandlingOverride)
const RHI::ShaderResourceGroup *	GetRHIShaderResourceGroup () 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< Material >	FindOrCreate (const Data::Asset< MaterialAsset > &materialAsset)
static Data::Instance< Material >	Create (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.

Friends
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.

Returns

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

Parameters

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

ForAllShaderItems()

void AZ::RPI::Material::ForAllShaderItems

(

AZStd::function< bool(const Name &materialPipelineName, const ShaderCollection::Item &shaderItem)>

callback

)

const

Iterates through all shader items in the material, for all render pipelines, including the general shader collection.

Parameters

callback	function is called for each shader item
materialPipelineName	the name of the shader's material pipeline, or empty (MaterialPipelineNone) for items in the general shader collection.

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().

GetShaderCollection()

const ShaderCollection & AZ::RPI::Material::GetShaderCollection

(

const Name &

forPipeline

)

const

Returns the shader collection for a specific material pipeline.

Parameters

forPipeline

the name of the material pipeline to query for shaders.

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.

Returns

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.

Returns

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, see MaterialOwnsShaderOption().

Parameters

shaderOptionName	the name of the shader option(s) to set
value	the new value for the shader option(s)
return	the 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:

• Gems/Atom/RPI/Code/Include/Atom/RPI.Public/Material/Material.h