C# Class Axiom.Graphics.Material

Class encapsulating the rendering properties of an object.
Inheritance: Axiom.Core.Resource, IComparable
Mostrar archivo 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.
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 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.
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 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_oe property

List of LOD distances specified for this material.
protected LodValueList UserLodValues
return LodValueList

autoNumber protected_oe static_oe property

Auto incrementing number for creating unique names.
protected static int autoNumber
return int

bestTechniquesByScheme protected_oe property

protected Dictionary> bestTechniquesByScheme
return Dictionary>

defaultSettings protected_oe static_oe property

A reference to a precreated Material that contains all the default settings.
protected static Material,Axiom.Graphics defaultSettings
return Material