#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 |
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.
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.
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
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. |
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.
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. |
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().
const ShaderCollection & AZ::RPI::Material::GetShaderCollection | ( | const Name & | forPipeline | ) | const |
Returns the shader collection for a specific material pipeline.
forPipeline | the name of the material pipeline to query for shaders. |
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.
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.
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.
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().
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. |