Rebel Fork Framework
Urho3D::Material Class Reference

Describes how to render 3D geometries. More...

#include <Urho3D/Graphics/Material.h>

Inheritance diagram for Urho3D::Material:
Urho3D::Resource Urho3D::PipelineStateTracker Urho3D::IDFamily< Material > Urho3D::Object Urho3D::RefCounted

Public Member Functions

 Material (Context *context)
 ~Material () override
bool BeginLoad (Deserializer &source) override
 Load resource from stream. May be called from a worker thread. Return true if successful.
bool EndLoad () override
 Finish resource loading. Always called from the main thread. Return true if successful.
bool Save (Serializer &dest) const override
 Save resource. Return true if successful.
bool Load (const XMLElement &source)
 Load from an XML element. Return true if successful.
bool Save (XMLElement &dest) const
 Save to an XML element. Return true if successful.
void SetNumTechniques (unsigned num)
void SetTechnique (unsigned index, Technique *tech, MaterialQuality qualityLevel=QUALITY_LOW, float lodDistance=0.0f)
 Set technique.
void SetTechniques (const ea::vector< TechniqueEntry > &techniques)
 Set all techniques in bulk.
void SetVertexShaderDefines (const ea::string &defines)
void SetPixelShaderDefines (const ea::string &defines)
void SetShaderParameter (const ea::string &name, const Variant &value, bool isCustom=false)
void SetShaderParameterAnimation (const ea::string &name, ValueAnimation *animation, WrapMode wrapMode=WM_LOOP, float speed=1.0f)
 Set shader parameter animation.
void SetShaderParameterAnimationWrapMode (const ea::string &name, WrapMode wrapMode)
 Set shader parameter animation wrap mode.
void SetShaderParameterAnimationSpeed (const ea::string &name, float speed)
 Set shader parameter animation speed.
void SetTexture (ea::string_view name, Texture *texture)
 Set texture.
void SetUVTransform (const Vector2 &offset, float rotation, const Vector2 &repeat)
 Set texture coordinate transform.
void SetUVTransform (const Vector2 &offset, float rotation, float repeat)
 Set texture coordinate transform.
void SetCullMode (CullMode mode)
void SetShadowCullMode (CullMode mode)
void SetFillMode (FillMode mode)
void SetDepthBias (const BiasParameters &parameters)
void SetAlphaToCoverage (bool enable)
void SetLineAntiAlias (bool enable)
void SetRenderOrder (unsigned char order)
void SetOcclusion (bool enable)
void SetScene (Scene *scene)
void RemoveShaderParameter (const ea::string &name)
 Remove shader parameter.
void ReleaseShaders ()
 Reset all shader pointers.
SharedPtr< MaterialClone (const ea::string &cloneName=EMPTY_STRING) const
 Clone the material.
void CopyFrom (const Material *material)
 Copy another material. This is useful for a pool of Material objects.
void SortTechniques ()
 Ensure that material techniques are listed in correct order.
void MarkForAuxView (unsigned frameNumber)
 Mark material for auxiliary view rendering.
unsigned GetNumTechniques () const
const ea::vector< TechniqueEntry > & GetTechniques () const
 Return all techniques.
const TechniqueEntryGetTechniqueEntry (unsigned index) const
 Return technique entry by index.
TechniqueGetTechnique (unsigned index) const
TechniqueFindTechnique (Drawable *drawable, MaterialQuality materialQuality) const
 Find best technique for given drawable and quality settings.
PassGetPass (unsigned index, const ea::string &passName) const
 Return pass by technique index and pass name.
PassGetDefaultPass () const
 Return default pass. Used by UI materials. It's base pass of 0-th technique assigned to Material.
TextureGetTexture (StringHash nameHash) const
 Return texture by unit.
const StringTextureMap & GetTextures () const
 Return all textures.
const ea::string & GetVertexShaderDefines () const
const ea::string & GetPixelShaderDefines () const
const VariantGetShaderParameter (const ea::string &name) const
ValueAnimationGetShaderParameterAnimation (const ea::string &name) const
 Return shader parameter animation.
WrapMode GetShaderParameterAnimationWrapMode (const ea::string &name) const
 Return shader parameter animation wrap mode.
float GetShaderParameterAnimationSpeed (const ea::string &name) const
 Return shader parameter animation speed.
const ea::unordered_map< StringHash, MaterialShaderParameter > & GetShaderParameters () const
 Return all shader parameters.
CullMode GetCullMode () const
CullMode GetShadowCullMode () const
FillMode GetFillMode () const
const BiasParametersGetDepthBias () const
bool GetAlphaToCoverage () const
bool GetLineAntiAlias () const
unsigned char GetRenderOrder () const
unsigned GetAuxViewFrameNumber () const
 Return last auxiliary view rendered frame number.
bool GetOcclusion () const
bool GetSpecular () const
 Return whether should render specular.
SceneGetScene () const
unsigned GetShaderParameterHash () const
 Return shader parameter hash value. Used as an optimization to avoid setting shader parameters unnecessarily.
bool Load (Deserializer &source)
 Load resource synchronously. Call both BeginLoad() & EndLoad() and return true if both succeeded.
- Public Member Functions inherited from Urho3D::Resource
 Resource (Context *context)
bool Load (Deserializer &source)
 Load resource synchronously. Call both BeginLoad() & EndLoad() and return true if both succeeded.
bool LoadFile (const FileIdentifier &fileName)
 Load resource from file.
virtual bool SaveFile (const FileIdentifier &fileName) const
 Save resource to file.
void SetName (const ea::string &name)
void SetMemoryUse (unsigned size)
 Set memory use in bytes, possibly approximate.
void ResetUseTimer ()
 Reset last used timer.
void SetAsyncLoadState (AsyncLoadState newState)
 Set the asynchronous loading state. Called by ResourceCache. Resources in the middle of asynchronous loading are not normally returned to user.
void SetAbsoluteFileName (const ea::string &fileName)
 Set absolute file name.
const ea::string & GetName () const
StringHash GetNameHash () const
 Return name hash.
unsigned GetMemoryUse () const
unsigned GetUseTimer ()
AsyncLoadState GetAsyncLoadState () const
 Return the asynchronous loading state.
const ea::string & GetAbsoluteFileName () const
 Return absolute file name.
- Public Member Functions inherited from Urho3D::Object
 Object (Context *context)
 ~Object () override
 Destruct. Clean up self from event sender & receiver structures.
virtual StringHash GetType () const =0
virtual const ea::string & GetTypeName () const =0
virtual const TypeInfoGetTypeInfo () const =0
 Return type info.
virtual bool IsInstanceOf (StringHash type) const =0
 Check whether current instance implements specified type.
virtual void OnEvent (Object *sender, StringHash eventType, VariantMap &eventData)
 Handle event.
virtual void SerializeInBlock (Archive &archive)
 Serialize content from/to archive. May throw ArchiveException.
template<typename T >
bool IsInstanceOf () const
 Check current instance is type of specified class.
template<typename T >
T * Cast ()
 Cast the object to specified most derived class.
template<typename T >
const T * Cast () const
 Cast the object to specified most derived class.
void SubscribeToEventManual (StringHash eventType, EventHandler *handler)
 Subscribe to an event that can be sent by any sender.
void SubscribeToEventManual (Object *sender, StringHash eventType, EventHandler *handler)
 Subscribe to a specific sender's event.
template<class T >
void SubscribeToEvent (StringHash eventType, T handler)
 Subscribe to an event that can be sent by any sender.
template<class T >
void SubscribeToEvent (Object *sender, StringHash eventType, T handler)
 Subscribe to a specific sender's event.
void UnsubscribeFromEvent (StringHash eventType)
 Unsubscribe from an event.
void UnsubscribeFromEvent (Object *sender, StringHash eventType)
 Unsubscribe from a specific sender's event.
void UnsubscribeFromEvents (Object *sender)
 Unsubscribe from a specific sender's events.
void UnsubscribeFromAllEvents ()
 Unsubscribe from all events.
void UnsubscribeFromAllEventsExcept (const ea::vector< StringHash > &exceptions)
 Unsubscribe from all events except those listed.
void UnsubscribeFromAllEventsExcept (const ea::vector< Object * > &exceptions)
 Unsubscribe from all events except those with listed senders.
void SendEvent (StringHash eventType)
 Send event to all subscribers.
void SendEvent (StringHash eventType, VariantMap &eventData)
 Send event with parameters to all subscribers.
VariantMapGetEventDataMap () const
 Return a preallocated map for event data. Used for optimization to avoid constant re-allocation of event data maps.
template<typename... Args>
void SendEvent (StringHash eventType, const Args &... args)
 Send event with variadic parameter pairs to all subscribers. The parameters are (paramID, paramValue) pairs.
ContextGetContext () const
 Return execution context.
const VariantGetGlobalVar (StringHash key) const
const VariantMapGetGlobalVars () const
void SetGlobalVar (StringHash key, const Variant &value)
ObjectGetSubsystem (StringHash type) const
 Return subsystem by type.
ObjectGetEventSender () const
 Return active event sender. Null outside event handling.
EventHandlerGetEventHandler () const
 Return active event handler. Null outside event handling.
bool HasSubscribedToEvent (StringHash eventType) const
 Return whether has subscribed to an event without specific sender.
bool HasSubscribedToEvent (Object *sender, StringHash eventType) const
 Return whether has subscribed to a specific sender's event.
bool HasEventHandlers () const
 Return whether has subscribed to any event.
template<class T >
T * GetSubsystem () const
 Template version of returning a subsystem.
const ea::string & GetCategory () const
void SendEvent (StringHash eventType, const VariantMap &eventData)
 Send event with parameters to all subscribers.
void SetBlockEvents (bool block)
 Block object from sending and receiving events.
bool GetBlockEvents () const
 Return sending and receiving events blocking status.
- Public Member Functions inherited from Urho3D::RefCounted
 RefCounted ()
 Construct. Allocate the reference count structure and set an initial self weak reference.
virtual ~RefCounted ()
 Destruct. Mark as expired and also delete the reference count structure if no outside weak references exist.
 RefCounted (const RefCounted &rhs)=delete
 Prevent copy construction.
RefCountedoperator= (const RefCounted &rhs)=delete
 Prevent assignment.
int AddRef ()
int ReleaseRef ()
int Refs () const
int WeakRefs () const
RefCountRefCountPtr () const
 Return pointer to the reference count structure.
bool HasScriptObject () const
 Return true if script runtime object wrapping this native object exists.
bool IsScriptStrongRef () const
 Return true if script reference is strong.
- Public Member Functions inherited from Urho3D::PipelineStateTracker
virtual ~PipelineStateTracker ()
unsigned GetPipelineStateHash () const
 Return (partial) pipeline state hash. Save to call from multiple threads as long as the object is not changing.
void MarkPipelineStateHashDirty ()
 Mark pipeline state hash as dirty.
- Public Member Functions inherited from Urho3D::IDFamily< Material >
 IDFamily ()
 ~IDFamily ()
unsigned GetObjectID () const
 Return unique object ID or 0 if not assigned.
void AcquireObjectID ()
 Acquire unique object ID. Ignored if unique ID is already acquired.
void ReleaseObjectID ()
 Release unique object ID. Ignored if unique ID is already released.

Static Public Member Functions

static void RegisterObject (Context *context)
static SharedPtr< MaterialCreateBaseMaterial (Context *context, const ea::string &shaderName, const ea::string &vsDefines, const ea::string &psDefines)
 Create simple material with only base pass. Used by UI renderers.
static Variant ParseShaderParameterValue (const ea::string &value)
 Parse a shader parameter value from a string. Retunrs either a bool, a float, or a 2 to 4-component vector.
- Static Public Member Functions inherited from Urho3D::Resource
static ResourceLoadFromCache (Context *context, StringHash type, const ea::string &name)
 Load resource by reference.
- Static Public Member Functions inherited from Urho3D::Object
static const TypeInfoGetTypeInfoStatic ()
 Return type info static.
- Static Public Member Functions inherited from Urho3D::IDFamily< Material >
static const unsigned GetNextFreeObjectID ()
 Return upper bound of all used object IDs within family.

Private Member Functions

 URHO3D_OBJECT (Material, Resource)
bool BeginLoadXML (Deserializer &source)
 Helper function for loading XML files.
void ResetToDefaults ()
 Reset to defaults.
void RefreshShaderParameterHash ()
 Recalculate shader parameter hash.
void RefreshMemoryUse ()
 Recalculate the memory used by the material.
void ApplyShaderDefines (unsigned index=M_MAX_UNSIGNED)
 Reapply shader defines to technique index. By default reapply all.
ShaderParameterAnimationInfoGetShaderParameterAnimationInfo (const ea::string &name) const
 Return shader parameter animation info.
void UpdateEventSubscription ()
 Update whether should be subscribed to scene or global update events for shader parameter animation.
void HandleAttributeAnimationUpdate (StringHash eventType, VariantMap &eventData)
 Update shader parameter animations.
void RefreshTextureEventSubscriptions ()
 Refresh subscriptions to texture events.
void SetTextureInternal (ea::string_view name, Texture *texture)
 Set texture without event resubscription.
unsigned RecalculatePipelineStateHash () const override
 Recalculate hash of pipeline state configuration.

Private Attributes

ea::vector< TechniqueEntrytechniques_
StringTextureMap textures_
ea::unordered_map< StringHash, MaterialShaderParametershaderParameters_
 Shader parameters.
ea::unordered_map< StringHash, SharedPtr< ShaderParameterAnimationInfo > > shaderParameterAnimationInfos_
 Shader parameters animation infos.
ea::string vertexShaderDefines_
 Vertex shader defines.
ea::string pixelShaderDefines_
 Pixel shader defines.
CullMode cullMode_ {}
 Normal culling mode.
CullMode shadowCullMode_ {}
 Culling mode for shadow rendering.
FillMode fillMode_ {}
 Polygon fill mode.
BiasParameters depthBias_ {}
 Depth bias parameters.
unsigned char renderOrder_ {}
 Render order value.
std::atomic_uint32_t auxViewFrameNumber_ { 0 }
 Last auxiliary view rendered frame number.
unsigned shaderParameterHash_ {}
 Shader parameter hash value.
bool alphaToCoverage_ {}
 Alpha-to-coverage flag.
bool lineAntiAlias_ {}
 Line antialiasing flag.
bool occlusion_ {true}
 Render occlusion flag.
bool specular_ {}
 Specular lighting flag.
bool subscribed_ {}
 Flag for whether is subscribed to animation updates.
bool batchedParameterUpdate_ {}
 Flag to suppress parameter hash and memory use recalculation when setting multiple shader parameters (loading or resetting the material).
SharedPtr< XMLFileloadXMLFile_
 XML file used while loading.
WeakPtr< Scenescene_
 Associated scene for shader parameter animation updates.

Additional Inherited Members

- Static Public Attributes inherited from Urho3D::Object
static constexpr ea::array< StringHash, 0 > TypeHierarchy {}
- Protected Member Functions inherited from Urho3D::PipelineStateTracker
PipelineStateSubscription CreateDependency (PipelineStateTracker *dependency)
 Create dependency onto another pipeline state.
void AddSubscriberReference (PipelineStateTracker *subscriber)
 Add reference to subscriber pipeline state tracker.
void RemoveSubscriberReference (PipelineStateTracker *subscriber)
 Remove reference to subscriber pipeline state tracker.
- Protected Attributes inherited from Urho3D::Object
WeakPtr< Contextcontext_
 Execution context.

Detailed Description

Describes how to render 3D geometries.

Member Function Documentation

◆ GetAlphaToCoverage()

bool Urho3D::Material::GetAlphaToCoverage ( ) const

Return alpha-to-coverage mode.

◆ GetCullMode()

CullMode Urho3D::Material::GetCullMode ( ) const

Return normal culling mode.

◆ GetDepthBias()

const BiasParameters& Urho3D::Material::GetDepthBias ( ) const

Return depth bias.

◆ GetFillMode()

FillMode Urho3D::Material::GetFillMode ( ) const

Return polygon fill mode.

◆ GetLineAntiAlias()

bool Urho3D::Material::GetLineAntiAlias ( ) const

Return whether line antialiasing is enabled.

◆ GetNumTechniques()

unsigned Urho3D::Material::GetNumTechniques ( ) const

Return number of techniques.

◆ GetOcclusion()

bool Urho3D::Material::GetOcclusion ( ) const

Return whether should render occlusion.

◆ GetPixelShaderDefines()

const ea::string& Urho3D::Material::GetPixelShaderDefines ( ) const

Return additional pixel shader defines.

◆ GetRenderOrder()

unsigned char Urho3D::Material::GetRenderOrder ( ) const

Return render order.

◆ GetScene()

Scene * Urho3D::Material::GetScene ( ) const

Return the scene associated with the material for shader parameter animation updates.

◆ GetShaderParameter()

const Variant & Urho3D::Material::GetShaderParameter ( const ea::string &  name) const

Return shader parameter.

◆ GetShadowCullMode()

CullMode Urho3D::Material::GetShadowCullMode ( ) const

Return culling mode for shadows.

◆ GetTechnique()

Technique * Urho3D::Material::GetTechnique ( unsigned  index) const

Return technique by index.

◆ GetVertexShaderDefines()

const ea::string& Urho3D::Material::GetVertexShaderDefines ( ) const

Return additional vertex shader defines.

◆ RegisterObject()

void Urho3D::Material::RegisterObject ( Context context)

Register object factory.

◆ SetAlphaToCoverage()

void Urho3D::Material::SetAlphaToCoverage ( bool  enable)

Set alpha-to-coverage mode on all passes.

◆ SetCullMode()

void Urho3D::Material::SetCullMode ( CullMode  mode)

Set culling mode.

◆ SetDepthBias()

void Urho3D::Material::SetDepthBias ( const BiasParameters parameters)

Set depth bias parameters for depth write and compare. Note that the normal offset parameter is not used and will not be saved, as it affects only shadow map sampling during light rendering.

◆ SetFillMode()

void Urho3D::Material::SetFillMode ( FillMode  mode)

Set polygon fill mode. Interacts with the camera's fill mode setting so that the "least filled" mode will be used.

◆ SetLineAntiAlias()

void Urho3D::Material::SetLineAntiAlias ( bool  enable)

Set line antialiasing on/off. Has effect only on models that consist of line lists.

◆ SetNumTechniques()

void Urho3D::Material::SetNumTechniques ( unsigned  num)

Set number of techniques.

◆ SetOcclusion()

void Urho3D::Material::SetOcclusion ( bool  enable)

Set whether to use in occlusion rendering. Default true.

◆ SetPixelShaderDefines()

void Urho3D::Material::SetPixelShaderDefines ( const ea::string &  defines)

Set additional pixel shader defines. Separate multiple defines with spaces. Setting defines at the material level causes technique(s) to be cloned as necessary.

◆ SetRenderOrder()

void Urho3D::Material::SetRenderOrder ( unsigned char  order)

Set 8-bit render order within pass. Default 128. Lower values will render earlier and higher values later, taking precedence over e.g. state and distance sorting.

◆ SetScene()

void Urho3D::Material::SetScene ( Scene scene)

Associate the material with a scene to ensure that shader parameter animation happens in sync with scene update, respecting the scene time scale. If no scene is set, the global update events will be used.

◆ SetShaderParameter()

void Urho3D::Material::SetShaderParameter ( const ea::string &  name,
const Variant value,
bool  isCustom = false 

Set shader parameter.

◆ SetShadowCullMode()

void Urho3D::Material::SetShadowCullMode ( CullMode  mode)

Set culling mode for shadows.

◆ SetVertexShaderDefines()

void Urho3D::Material::SetVertexShaderDefines ( const ea::string &  defines)

Set additional vertex shader defines. Separate multiple defines with spaces. Setting defines at the material level causes technique(s) to be cloned as necessary.

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