MaterialInstance Class

Represents an instance of a specific material.

Inheritance Hierarchy

SystemObject
DigitalRune.Graphics.SceneGraphMaterialInstance

Namespace: DigitalRune.Graphics.SceneGraph
Assembly: DigitalRune.Graphics (in DigitalRune.Graphics.dll) Version: 1.2.0.0 (1.2.1.14562)

Syntax

C++

Copy

public class MaterialInstance : IDictionary<string, EffectBinding>, 
	ICollection<KeyValuePair<string, EffectBinding>>, IEnumerable<KeyValuePair<string, EffectBinding>>, 
	IEnumerable

Public Class MaterialInstance
	Implements IDictionary(Of String, EffectBinding), 
	ICollection(Of KeyValuePair(Of String, EffectBinding)), IEnumerable(Of KeyValuePair(Of String, EffectBinding)), 
	IEnumerable

public ref class MaterialInstance : IDictionary<String^, EffectBinding^>, 
	ICollection<KeyValuePair<String^, EffectBinding^>>, IEnumerable<KeyValuePair<String^, EffectBinding^>>, 
	IEnumerable

type MaterialInstance =  
    class
        interface IDictionary<string, EffectBinding>
        interface ICollection<KeyValuePair<string, EffectBinding>>
        interface IEnumerable<KeyValuePair<string, EffectBinding>>
        interface IEnumerable
    end

The MaterialInstance type exposes the following members.

Constructors

	Name	Description
	MaterialInstance	Initializes a new instance of the MaterialInstance class. (This constructor creates an uninitialized instance. Use this constructor only for cloning or other special cases!)
	MaterialInstance(Material)	Initializes a new instance of the MaterialInstance class.

Top

Methods

	Name	Description
	Clone	Creates a new MaterialInstance that is a clone of the current instance.
	CloneCore	Makes the instance a clone (deep copy) of the specified MaterialInstance.
	Contains	Determines whether the material instance contains effect parameter bindings for the specified render pass.
	CreateInstanceCore	When implemented in a derived class, creates a new instance of the MaterialInstance derived class.
	Equals	Determines whether the specified Object is equal to the current Object. (Inherited from Object.)
	Finalize	Allows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from Object.)
	GetEnumerator	Returns an enumerator that iterates through a collection.
	GetHashCode	Serves as a hash function for a particular type. (Inherited from Object.)
	GetType	Gets the Type of the current instance. (Inherited from Object.)
	MemberwiseClone	Creates a shallow copy of the current Object. (Inherited from Object.)
	ToString	Returns a string that represents the current object. (Inherited from Object.)
	TryGet	Gets the effect parameter bindings for the specified render pass.

Top

Extension Methods

	Name	Description
	AddRangeKeyValuePairString, EffectBinding	Adds the specified items to the ICollectionT. (Defined by CollectionHelper.)
	DoKeyValuePairString, EffectBinding(ActionKeyValuePairString, EffectBinding)	Overloaded. Performs the given action on each element in a sequence when it is enumerated. (Defined by LinqHelper.)
	DoKeyValuePairString, EffectBinding(ActionKeyValuePairString, EffectBinding, Int32)	Overloaded. Performs the given action on each element (incorporating its index) in a sequence when it is enumerated. (Defined by LinqHelper.)
	ForEachKeyValuePairString, EffectBinding(ActionKeyValuePairString, EffectBinding)	Overloaded. Immediately performs the given action on each element in a sequence. (Defined by LinqHelper.)
	ForEachKeyValuePairString, EffectBinding(ActionKeyValuePairString, EffectBinding, Int32)	Overloaded. Immediately performs the given action on each element (incorporating its index) in a sequence. (Defined by LinqHelper.)
	IndexOfKeyValuePairString, EffectBinding	Returns the index of the first element in a sequence that satisfies the specified condition. (Defined by LinqHelper.)

Top

Properties

	Name	Description
	Count	Gets the number of render passes supported by this material instance.
	EffectBindings	Gets a read-only collection of effect bindings used by this material instance.
	Item	Gets or sets the effect parameter bindings for the specified render pass.
	Material	Gets the material.
	Passes	Gets a read-only collection of all the render passes supported by this material instance.

Top

Explicit Interface Implementations

	Name	Description
	ICollectionKeyValuePairString, EffectBindingAdd	Adds an item to the ICollectionT.
	IDictionaryString, EffectBindingAdd	Adds an element with the provided key and value to the IDictionaryTKey, TValue.
	ICollectionKeyValuePairString, EffectBindingClear	Removes all items from the ICollectionT.
	ICollectionKeyValuePairString, EffectBindingContains	Determines whether the ICollectionT contains a specific value.
	IDictionaryString, EffectBindingContainsKey	Determines whether the IDictionaryTKey, TValue contains an element with the specified key.
	ICollectionKeyValuePairString, EffectBindingCopyTo	Copies the elements of the ICollectionT to an Array, starting at a particular Array index.
	IEnumerableKeyValuePairString, EffectBindingGetEnumerator	Returns an enumerator that iterates through the collection.
	IEnumerableGetEnumerator	Returns an enumerator that iterates through a collection.
	ICollectionKeyValuePairString, EffectBindingIsReadOnly	Gets a value indicating whether the ICollectionT is read-only.
	IDictionaryString, EffectBindingKeys	Gets an ICollectionT containing the keys of the IDictionaryTKey, TValue.
	ICollectionKeyValuePairString, EffectBindingRemove	Removes the first occurrence of a specific object from the ICollectionT.
	IDictionaryString, EffectBindingRemove	Removes the element with the specified key from the IDictionaryTKey, TValue.
	IDictionaryString, EffectBindingTryGetValue	Gets the value associated with the specified key.
	IDictionaryString, EffectBindingValues	Gets an ICollectionT containing the values in the IDictionaryTKey, TValue.

Top

Remarks

Each mesh has a set of materials (see class Material). A material defines the effect bindings (see class EffectBinding) for all required render passes.

The effect parameters basically fall into two categories:

Non-shared parameters, which are unique for each mesh node. Examples are world matrices, light properties, etc. These effect parameters depend on the actual mesh instance that is rendered.
Shared parameters, which are shared by mesh nodes with the same base mesh. Examples are view/projection matrices, most material properties, etc.

When a new mesh node (see class MeshNode) is created for a mesh (see class Mesh), all materials are instanced. That means, a new object of type MaterialInstance is created for each material. A material instance references the base material from which it was created (see property Material).

Both, the base material and the material instance are dictionaries of effect bindings: They contain one effect binding for each render pass that is required to render the mesh. The base material contains the bindings for all shared parameters. The material instance contains the bindings for non-shared parameters. Materials can be shared between different meshes - they are not bound to a specific mesh, but material instances belong to a certain mesh node!

Cloning:
MaterialInstances can be cloned. When Clone is called all EffectBindings are duplicated (deep copy). The base Material is copied by reference (shallow copy).

Reference

DigitalRune.Graphics.SceneGraph Namespace

DigitalRune.Graphics.EffectsEffectBinding

MaterialInstanceMaterial