C# Class Axiom.Graphics.Material

Class encapsulating the rendering properties of an object.

Inheritance: Axiom.Core.Resource, IComparable

Show file Open project: WolfgangSt/axiom Class Usage Examples

Protected Properties

Property	Type	Description
UserLodValues	LodValueList
autoNumber	int
bestTechniquesByScheme	Dictionary>
defaultSettings	Material

Public Methods

Method	Description
ApplyDefaults ( ) : void
ApplyTextureAliases ( string>.Dictionary aliasList ) : bool
ApplyTextureAliases ( string>.Dictionary aliasList, bool apply ) : bool	Applies texture names to Texture Unit State with matching texture name aliases. All techniques, passes, and Texture Unit States within the material are checked. If matching texture aliases are found then true is returned.
Clone ( string newName ) : Material	Creates a copy of this Material with the specified name (must be unique).
Clone ( string newName, bool changeGroup, string newGroup ) : Material
CompareTo ( object obj ) : int	Used for comparing 2 Material objects. This comparison will be used in RenderQueue group sorting of Materials materials. If this object is transparent and the object being compared is not, this is greater that obj. If this object is not transparent and the object being compared is, obj is greater than this.
Compile ( ) : void	'Compiles' this Material. Compiling a material involves determining which Techniques are supported on the card on which the engine is currently running, and for fixed-function Passes within those Techniques, splitting the passes down where they contain more TextureUnitState instances than the current card has texture units. This process is automatically done when the Material is loaded, but may be repeated if you make some procedural changes.By default, the engine will automatically split texture unit operations into multiple passes when the target hardware does not have enough texture units.
Compile ( bool autoManageTextureUnits ) : void
CopyTo ( Material target ) : void	Copies the details from the supplied material.
CopyTo ( Material target, bool copyUniqueInfo ) : void
CreateTechnique ( ) : Technique	Creates a new Technique for this Material. A Technique is a single way of rendering geometry in order to achieve the effect you are intending in a material. There are many reason why you would want more than one - the main one being to handle variable graphics card abilities; you might have one technique which is impressive but only runs on 4th-generation graphics cards, for example. In this case you will want to create at least one fallback Technique. The engine will work out which Techniques a card can support and pick the best one. If multiple Techniques are available, the order in which they are created is important - the engine will consider lower-indexed Techniques to be preferable to higher-indexed Techniques, ie when asked for the 'best' technique it will return the first one in the technique list which is supported by the hardware.
GetBestTechnique ( ) : Technique	Gets the best supported technique. This method returns the lowest-index supported Technique in this material (since lower-indexed Techniques are considered to be better than higher-indexed ones). The best supported technique is only available after this material has been compiled, which typically happens on loading the material. Therefore, if this method returns null, try calling Material.Load.
GetBestTechnique ( int lodIndex ) : Technique
GetBestTechnique ( int lodIndex, IRenderable renderable ) : Technique
GetHashCode ( ) : int	Overridden to give Materials a meaningful hash code.
GetLodIndex ( Real distance ) : int	Gets the LOD index to use at the given distance. The value passed in is the 'transformed' value. If you are dealing with an original source value (e.g. distance), use to turn this into a lookup value.
GetTechnique ( int index ) : Technique	Gets the technique at the specified index.
Material ( ResourceManager parent, string name, System.UInt64 handle, string group ) : System
Material ( ResourceManager parent, string name, System.UInt64 handle, string group, bool isManual, IManualResourceLoader loader ) : System
RemoveAllTechniques ( ) : void	Removes all techniques from this material.
RemoveTechnique ( Technique t ) : void	Removes the specified Technique from this material.
SetFog ( bool overrideScene ) : void
SetFog ( bool overrideScene, FogMode mode, ColorEx color, System.Single expDensity, System.Single linearStart, System.Single linearEnd ) : void	Sets the fogging mode applied to each pass. This property has been moved to the Pass class, which is accessible via the Technique. For simplicity, this method allows you to set these properties for every current Technique, and for every current Pass within those Techniques. If you need more precision, retrieve the Technique and Pass instances and set the property there.
SetLodLevels ( LodValueList lodDistanceList ) : void	Sets the distance at which level-of-detail (LOD) levels come into effect. You should only use this if you have assigned LOD indexes to the Technique instances attached to this Material. If you have done so, you should call this method to determine the distance at which the low levels of detail kick in. The decision about what distance is actually used is a combination of this and the LOD bias applied to both the current Camera and the current Entity.
SetSceneBlending ( SceneBlendFactor src, SceneBlendFactor dest ) : void	Allows very fine control of blending every Pass with the existing contents of the scene. This property has been moved to the Pass class, which is accessible via the Technique. For simplicity, this method allows you to set these properties for every current Technique, and for every current Pass within those Techniques. If you need more precision, retrieve the Technique and Pass instances and set the property there.
SetSceneBlending ( SceneBlendType blendType ) : void	Sets the kind of blending every pass has with the existing contents of the scene. This property has been moved to the Pass class, which is accessible via the Technique. For simplicity, this method allows you to set these properties for every current Technique, and for every current Pass within those Techniques. If you need more precision, retrieve the Technique and Pass instances and set the property there.
ToString ( ) : string	Overridden.
Touch ( ) : void	Overridden to ensure a recompile occurs if needed before use.

Protected Methods

Method	Description
calculateSize ( ) : int	Calculate the size of a material; this will only be called after 'load'
dispose ( bool disposeManagedResources ) : void	Overridden to ensure a release of techniques.
load ( ) : void	Overridden from Resource. By default, Materials are not loaded, and adding additional textures etc do not cause those textures to be loaded. When the `Load` method is called, all textures are loaded (if they are not already), GPU programs are created if applicable, and Controllers are instantiated. Once a material has been loaded, all changes made to it are immediately loaded too
unload ( ) : void	Unloads the material, frees resources etc. Resource

Private Methods

Method	Description
ClearBestTechniqueList ( ) : void
InsertSupportedTechnique ( Technique technique ) : void
NotifyNeedsRecompile ( ) : void	Tells the material that it needs recompilation.

Method Details

ApplyDefaults() public method

public ApplyDefaults ( ) : void
return	void

ApplyTextureAliases() public method

public ApplyTextureAliases ( string>.Dictionary aliasList ) : bool
aliasList	string>.Dictionary
return	bool

ApplyTextureAliases() public method

Applies texture names to Texture Unit State with matching texture name aliases. All techniques, passes, and Texture Unit States within the material are checked. If matching texture aliases are found then true is returned.

public ApplyTextureAliases ( string>.Dictionary aliasList, bool apply ) : bool
aliasList	string>.Dictionary	is a map container of texture alias, texture name pairs
apply	bool	set true to apply the texture aliases else just test to see if texture alias matches are found.
return	bool

Clone() public method

Creates a copy of this Material with the specified name (must be unique).

public Clone ( string newName ) : Material
newName	string	The name that the cloned material will be known as.
return	Material

Clone() public method

public Clone ( string newName, bool changeGroup, string newGroup ) : Material
newName	string
changeGroup	bool
newGroup	string
return	Material

CompareTo() public method

Used for comparing 2 Material objects.

This comparison will be used in RenderQueue group sorting of Materials materials. If this object is transparent and the object being compared is not, this is greater that obj. If this object is not transparent and the object being compared is, obj is greater than this.

public CompareTo ( object obj ) : int
obj	object
return	int

Compile() public method

'Compiles' this Material.

Compiling a material involves determining which Techniques are supported on the card on which the engine is currently running, and for fixed-function Passes within those Techniques, splitting the passes down where they contain more TextureUnitState instances than the current card has texture units.

This process is automatically done when the Material is loaded, but may be repeated if you make some procedural changes. By default, the engine will automatically split texture unit operations into multiple passes when the target hardware does not have enough texture units.

public Compile ( ) : void
return	void

Compile() public method

public Compile ( bool autoManageTextureUnits ) : void
autoManageTextureUnits	bool	/// If true, when a fixed function pass has too many TextureUnitState /// entries than the card has texture units, the Pass in question will be split into /// more than one Pass in order to emulate the Pass. If you set this to false and /// this situation arises, an Exception will be thrown. ///
return	void

CopyTo() public method

Copies the details from the supplied material.

public CopyTo ( Material target ) : void
target	Material	Material which will receive this material's settings.
return	void

CopyTo() public method

public CopyTo ( Material target, bool copyUniqueInfo ) : void
target	Material
copyUniqueInfo	bool	preserves the target's handle, group, name, and loading properties (unlike operator=) but copying everything else.
return	void

CreateTechnique() public method

Creates a new Technique for this Material.

A Technique is a single way of rendering geometry in order to achieve the effect you are intending in a material. There are many reason why you would want more than one - the main one being to handle variable graphics card abilities; you might have one technique which is impressive but only runs on 4th-generation graphics cards, for example. In this case you will want to create at least one fallback Technique. The engine will work out which Techniques a card can support and pick the best one.

If multiple Techniques are available, the order in which they are created is important - the engine will consider lower-indexed Techniques to be preferable to higher-indexed Techniques, ie when asked for the 'best' technique it will return the first one in the technique list which is supported by the hardware.

public CreateTechnique ( ) : Technique
return	Technique

GetBestTechnique() public method

Gets the best supported technique.

This method returns the lowest-index supported Technique in this material (since lower-indexed Techniques are considered to be better than higher-indexed ones).

The best supported technique is only available after this material has been compiled, which typically happens on loading the material. Therefore, if this method returns null, try calling Material.Load.

public GetBestTechnique ( ) : Technique
return	Technique

GetBestTechnique() public method

public GetBestTechnique ( int lodIndex ) : Technique
lodIndex	int
return	Technique

GetBestTechnique() public method

public GetBestTechnique ( int lodIndex, IRenderable renderable ) : Technique
lodIndex	int
renderable	IRenderable
return	Technique

GetHashCode() public method

Overridden to give Materials a meaningful hash code.

public GetHashCode ( ) : int
return	int

GetLodIndex() public method

Gets the LOD index to use at the given distance.

The value passed in is the 'transformed' value. If you are dealing with an original source value (e.g. distance), use to turn this into a lookup value.

public GetLodIndex ( Real distance ) : int
distance	Real
return	int

GetTechnique() public method

Gets the technique at the specified index.

public GetTechnique ( int index ) : Technique
index	int	Index of the technique to return.
return	Technique

Material() public method

public Material ( ResourceManager parent, string name, System.UInt64 handle, string group ) : System
parent	Axiom.Core.ResourceManager
name	string
handle	System.UInt64
group	string
return	System

Material() public method

public Material ( ResourceManager parent, string name, System.UInt64 handle, string group, bool isManual, IManualResourceLoader loader ) : System
parent	Axiom.Core.ResourceManager
name	string
handle	System.UInt64
group	string
isManual	bool
loader	IManualResourceLoader
return	System

RemoveAllTechniques() public method

Removes all techniques from this material.

public RemoveAllTechniques ( ) : void
return	void

RemoveTechnique() public method

Removes the specified Technique from this material.

public RemoveTechnique ( Technique t ) : void
t	Technique	A reference to the technique to remove
return	void

SetFog() public method

public SetFog ( bool overrideScene ) : void
overrideScene	bool
return	void

SetFog() public method

Sets the fogging mode applied to each pass.

This property has been moved to the Pass class, which is accessible via the Technique. For simplicity, this method allows you to set these properties for every current Technique, and for every current Pass within those Techniques. If you need more precision, retrieve the Technique and Pass instances and set the property there.

public SetFog ( bool overrideScene, FogMode mode, ColorEx color, System.Single expDensity, System.Single linearStart, System.Single linearEnd ) : void
overrideScene	bool
mode	FogMode
color	ColorEx
expDensity	System.Single
linearStart	System.Single
linearEnd	System.Single
return	void

SetLodLevels() public method

Sets the distance at which level-of-detail (LOD) levels come into effect.

You should only use this if you have assigned LOD indexes to the Technique instances attached to this Material. If you have done so, you should call this method to determine the distance at which the low levels of detail kick in. The decision about what distance is actually used is a combination of this and the LOD bias applied to both the current Camera and the current Entity.

public SetLodLevels ( LodValueList lodDistanceList ) : void
lodDistanceList	LodValueList	/// A list of floats which indicate the distance at which to /// switch to lower details. They are listed in LOD index order, starting at index /// 1 (ie the first level down from the highest level 0, which automatically applies /// from a distance of 0). ///
return	void

SetSceneBlending() public method

Allows very fine control of blending every Pass with the existing contents of the scene.

public SetSceneBlending ( SceneBlendFactor src, SceneBlendFactor dest ) : void
src	SceneBlendFactor
dest	SceneBlendFactor
return	void

SetSceneBlending() public method

Sets the kind of blending every pass has with the existing contents of the scene.

public SetSceneBlending ( SceneBlendType blendType ) : void
blendType	SceneBlendType
return	void

ToString() public method

Overridden.

public ToString ( ) : string
return	string

Touch() public method

Overridden to ensure a recompile occurs if needed before use.

public Touch ( ) : void
return	void

calculateSize() protected method

Calculate the size of a material; this will only be called after 'load'

protected calculateSize ( ) : int
return	int

dispose() protected method

Overridden to ensure a release of techniques.

protected dispose ( bool disposeManagedResources ) : void
disposeManagedResources	bool
return	void

load() protected method

Overridden from Resource.

By default, Materials are not loaded, and adding additional textures etc do not cause those textures to be loaded. When the Load method is called, all textures are loaded (if they are not already), GPU programs are created if applicable, and Controllers are instantiated. Once a material has been loaded, all changes made to it are immediately loaded too

protected load ( ) : void
return	void

unload() protected method

Unloads the material, frees resources etc. Resource

protected unload ( ) : void
return	void

Property Details

UserLodValues protected property

List of LOD distances specified for this material.

protected LodValueList UserLodValues
return	LodValueList

autoNumber protected static property

Auto incrementing number for creating unique names.

protected static int autoNumber
return	int

bestTechniquesByScheme protected property

protected Dictionary> bestTechniquesByScheme
return	Dictionary>

defaultSettings protected static property

A reference to a precreated Material that contains all the default settings.

protected static Material,Axiom.Graphics defaultSettings
return	Material