C# Class Axiom.Graphics.TextureUnitState

Class representing the state of a single texture unit during a Pass of a Technique, of a Material.
Texture units are pipelines for retrieving texture data for rendering onto your objects in the world. Using them is common to both the fixed-function and the programmable (vertex and fragment program) pipeline, but some of the settings will only have an effect in the fixed-function pipeline (for example, setting a texture rotation will have no effect if you use the programmable pipeline, because this is overridden by the fragment program). The effect of each setting as regards the 2 pipelines is commented in each setting.

When I use the term 'fixed-function pipeline' I mean traditional rendering where you do not use vertex or fragment programs (shaders). Programmable pipeline means that for this pass you are using vertex or fragment programs.

显示文件 Open project: WolfgangSt/axiom Class Usage Examples

Protected Properties

Property Type Description
parent Pass
texAddressingMode UVWAddressing

Private Properties

Property Type Description
CreateAnimationController void
CreateEffectController void
RecalcTextureMatrix void
RemoveEffect void

Public Methods

Method Description
AddEffect ( TextureEffect effect ) : void

Generic method for setting up texture effects.

Allows you to specify effects directly by using the TextureEffectType enumeration. The arguments that go with it depend on the effect type. Only one effect of each type can be applied to a texture layer.

This method is used internally, but it is better generally for applications to use the more intuitive specialized methods such as SetEnvironmentMap and SetScroll.

ApplyTextureAliases ( string>.Dictionary aliasList, bool apply ) : bool

Applies texture names to Texture Unit State with matching texture name aliases. If no matching aliases are found then the TUS state does not change.

Cubic, 1d, 2d, and 3d textures are determined from current state of the Texture Unit. Assumes animated frames are sequentially numbered in the name. If matching texture aliases are found then true is returned.

Clone ( Pass parent ) : TextureUnitState

Used to clone a texture layer. Mainly used during a call to Clone on a Material or Pass.

CopyTo ( TextureUnitState target ) : void

Used to clone a texture layer. Mainly used during a call to Clone on a Material.

GetEffect ( int index ) : TextureEffect

Gets the texture effect at the specified index.

GetEnvironmentMap ( ) : EnvironmentMap
GetFrameTextureName ( int frame ) : string

Gets the name of the texture associated with a frame.

Applies to both fixed-function and programmable pipeline.

GetTextureFiltering ( FilterType type ) : FilterOptions

Gets the texture filtering for the given type.

Load ( ) : void

Internal method for loading this texture stage as part of Material.Load.

NotifyNeedsRecompile ( ) : void

Notifies the parent that it needs recompilation.

RemoveAllEffects ( ) : void

Removes all effects from this texture stage.

RemoveEffect ( TextureEffect effect ) : void

Removes the specified effect from the list of effects being applied during this texture stage.

SetAlphaOperation ( LayerBlendOperationEx operation ) : void

Overloaded method.

SetAlphaOperation ( LayerBlendOperationEx operation, LayerBlendSource source1, LayerBlendSource source2, float arg1, float arg2, float blendFactor ) : void

Sets the alpha operation to be applied to this texture.

This works in exactly the same way as SetColorOperation, except that the effect is applied to the level of alpha (i.e. transparency) of the texture rather than its color. When the alpha of a texel (a pixel on a texture) is 1.0, it is opaque, wheras it is fully transparent if the alpha is 0.0. Please refer to the SetColorOperation method for more info.

SetAnimatedTextureName ( string name, int numFrames, float duration ) : void

Sets the names of the texture images for an animated texture.

Animated textures are just a series of images making up the frames of the animation. All the images must be the same size, and their names must have a frame number appended before the extension, e.g. if you specify a name of "wall.jpg" with 3 frames, the image names must be "wall_1.jpg" and "wall_2.jpg".

You can change the active frame on a texture layer by setting the CurrentFrame property.

Note: If you can't make your texture images conform to the naming standard layed out here, you can call the alternative SetAnimatedTextureName method which takes an array of names instead.

SetColorOpMultipassFallback ( SceneBlendFactor src, SceneBlendFactor dest ) : void

Sets the multipass fallback operation for this layer, if you used TextureUnitState.SetColorOperationEx and not enough multitexturing hardware is available.

Because some effects exposed using TextureUnitState.SetColorOperationEx are only supported under multitexturing hardware, if the hardware is lacking the system must fallback on multipass rendering, which unfortunately doesn't support as many effects. This method is for you to specify the fallback operation which most suits you.

You'll notice that the interface is the same as the Material.SetSceneBlending method; this is because multipass rendering IS effectively scene blending, since each layer is rendered on top of the last using the same mechanism as making an object transparent, it's just being rendered in the same place repeatedly to get the multitexture effect.

If you use the simpler (and hence less flexible) TextureUnitState.SetColorOperation method you don't need to call this as the system sets up the fallback for you.

This option has no effect in the programmable pipeline, because there is no multipass fallback and multitexture blending is handled by the fragment shader.

SetColorOperation ( LayerBlendOperation operation ) : void

Determines how this texture layer is combined with the one below it (or the diffuse color of the geometry if this is layer 0).

This method is the simplest way to blend tetxure layers, because it requires only one parameter, gives you the most common blending types, and automatically sets up 2 blending methods: one for if single-pass multitexturing hardware is available, and another for if it is not and the blending must be achieved through multiple rendering passes. It is, however, quite limited and does not expose the more flexible multitexturing operations, simply because these can't be automatically supported in multipass fallback mode. If want to use the fancier options, use , but you'll either have to be sure that enough multitexturing units will be available, or you should explicitly set a fallback using TextureUnitState.SetColorOpMultipassFallback.

The default method is LayerBlendOperation.Modulate for all layers.

This option has no effect in the programmable pipeline.

SetColorOperationEx ( LayerBlendOperationEx operation ) : void

Overloaded method.

SetColorOperationEx ( LayerBlendOperationEx operation, LayerBlendSource source1, LayerBlendSource source2 ) : void

Overloaded method.

SetColorOperationEx ( LayerBlendOperationEx operation, LayerBlendSource source1, LayerBlendSource source2, ColorEx arg1 ) : void

Overloaded method.

SetColorOperationEx ( LayerBlendOperationEx operation, LayerBlendSource source1, LayerBlendSource source2, ColorEx arg1, ColorEx arg2, float blendFactor ) : void

For setting advanced blending options.

This is an extended version of the TextureUnitState.SetColorOperation method which allows extremely detailed control over the blending applied between this and earlier layers. See the IMPORTANT note below about the issues between mulitpass and multitexturing that using this method can create.

Texture color operations determine how the final color of the surface appears when rendered. Texture units are used to combine color values from various sources (ie. the diffuse color of the surface from lighting calculations, combined with the color of the texture). This method allows you to specify the 'operation' to be used, ie. the calculation such as adds or multiplies, and which values to use as arguments, such as a fixed value or a value from a previous calculation.

The defaults for each layer are:

  • op = Modulate
  • source1 = Texture
  • source2 = Current
ie. each layer takes the color results of the previous layer, and multiplies them with the new texture being applied. Bear in mind that colors are RGB values from 0.0 - 1.0 so multiplying them together will result in values in the same range, 'tinted' by the multiply. Note however that a straight multiply normally has the effect of darkening the textures - for this reason there are brightening operations like ModulateX2. See the LayerBlendOperation and LayerBlendSource enumerated types for full details.

Because of the limitations on some underlying APIs (Direct3D included) the Texture argument can only be used as the first argument, not the second.

The final 3 parameters are only required if you decide to pass values manually into the operation, i.e. you want one or more of the inputs to the color calculation to come from a fixed value that you supply. Hence you only need to fill these in if you supply Manual to the corresponding source, or use the BlendManual operation.

The engine tries to use multitexturing hardware to blend texture layers together. However, if it runs out of texturing units (e.g. 2 of a GeForce2, 4 on a GeForce3) it has to fall back on multipass rendering, i.e. rendering the same object multiple times with different textures. This is both less efficient and there is a smaller range of blending operations which can be performed. For this reason, if you use this method you MUST also call TextureUnitState.SetColorOpMultipassFallback to specify which effect you want to fall back on if sufficient hardware is not available.

If you wish to avoid having to do this, use the simpler TextureUnitState.SetColorOperation method which allows less flexible blending options but sets up the multipass fallback automatically, since it only allows operations which have direct multipass equivalents.

This has no effect in the programmable pipeline.

SetCubicTextureName ( string textureName, bool forUVW ) : void

Sets this texture layer to use a combination of 6 texture maps, each one relating to a face of a cube.

Cubic textures are made up of 6 separate texture images. Each one of these is an orthoganal view of the world with a FOV of 90 degrees and an aspect ratio of 1:1. You can generate these from 3D Studio by rendering a scene to a reflection map of a transparent cube and saving the output files.

Cubic maps can be used either for skyboxes (complete wrap-around skies, like space) or as environment maps to simulate reflections. The system deals with these 2 scenarios in different ways:

  1. For cubic environment maps, the 6 textures are combined into a single 'cubic' texture map which is then addressed using 3D texture coordinates. This is required because you don't know what face of the box you're going to need to address when you render an object, and typically you need to reflect more than one face on the one object, so all 6 textures are needed to be 'active' at once. Cubic environment maps are enabled by calling this method with the forUVW parameter set to true, and then calling SetEnvironmentMap(true).

    Note that not all cards support cubic environment mapping.

  2. For skyboxes, the 6 textures are kept separate and used independently for each face of the skybox. This is done because not all cards support 3D cubic maps and skyboxes do not need to use 3D texture coordinates so it is simpler to render each face of the box with 2D coordinates, changing texture between faces.

    Skyboxes are created by calling SceneManager.SetSkyBox.

Applies to both fixed-function and programmable pipeline.

SetEnvironmentMap ( bool enable ) : void

Overloaded method.

SetEnvironmentMap ( bool enable, EnvironmentMap envMap ) : void

Turns on/off texture coordinate effect that makes this layer an environment map.

Environment maps make an object look reflective by using the object's vertex normals relative to the camera view to generate texture coordinates.

The vectors generated can either be used to address a single 2D texture which is a 'fish-eye' lens view of a scene, or a 3D cubic environment map which requires 6 textures for each side of the inside of a cube. The type depends on what texture you set up - if you use the setTextureName method then a 2D fisheye lens texture is required, whereas if you used setCubicTextureName then a cubic environemnt map will be used.

This effect works best if the object has lots of gradually changing normals. The texture also has to be designed for this effect - see the example spheremap.png included with the sample application for a 2D environment map; a cubic map can be generated by rendering 6 views of a scene to each of the cube faces with orthoganal views.

Enabling this disables any other texture coordinate generation effects. However it can be combined with texture coordinate modification functions, which then operate on the generated coordinates rather than static model texture coordinates.

This option has no effect in the programmable pipeline.

SetProjectiveTexturing ( bool enable, Frustum projectionSettings ) : void

Enables or disables projective texturing on this texture unit.

Projective texturing allows you to generate texture coordinates based on a Frustum, which gives the impression that a texture is being projected onto the surface. Note that once you have called this method, the texture unit continues to monitor the Frustum you passed in and the projection will change if you can alter it. It also means that the Frustum object you pass remains in existence for as long as this TextureUnitState does.

This effect cannot be combined with other texture generation effects, such as environment mapping. It also has no effect on passes which have a vertex program enabled - projective texturing has to be done in the vertex program instead.

SetRotateAnimation ( float speed ) : void

Sets up an animated texture rotation for this layer.

Useful for constant rotations (for varying rotations, SetTransformAnimation).

This option has no effect in the programmable pipeline.

SetScrollAnimation ( float uSpeed, float vSpeed ) : void

Sets up an animated scroll for the texture layer.

Useful for creating constant scrolling effects on a texture layer (for varying scrolls, SetTransformAnimation).

This option has no effect in the programmable pipeline.

SetTextureAddressingMode ( TextureAddressing tam ) : void

Sets the texture addressing mode, i.e. what happens at uv values above 1.0.

The default is TAM_WRAP i.e. the texture repeats over values of 1.0. This is a shortcut method which sets the addressing mode for all coordinates at once; you can also call the more specific method to set the addressing mode per coordinate. This applies for both the fixed-function and programmable pipelines.

SetTextureAddressingMode ( TextureAddressing u, TextureAddressing v, TextureAddressing w ) : void

Sets the texture addressing mode, i.e. what happens at uv values above 1.0.

The default is TAM_WRAP i.e. the texture repeats over values of 1.0. This applies for both the fixed-function and programmable pipelines.

SetTextureAddressingMode ( UVWAddressing uvw ) : void

Sets the texture addressing mode, i.e. what happens at uv values above 1.0.

The default is TAM_WRAP i.e. the texture repeats over values of 1.0. This applies for both the fixed-function and programmable pipelines.

SetTextureFiltering ( FilterOptions minFilter, FilterOptions magFilter, FilterOptions mipFilter ) : void

Set a the detailed filtering options on this texture unit.

SetTextureFiltering ( FilterType type, FilterOptions options ) : void

Set a single filtering option on this texture unit.

SetTextureFiltering ( TextureFiltering filter ) : void

Set the texture filtering for this unit, using the simplified interface.

You also have the option of specifying the minification, magnification and mip filter individually if you want more control over filtering options. See the SetTextureFiltering overloads for details.

Note: This option applies in both the fixed function and programmable pipeline.

SetTextureName ( string name ) : void

Sets this texture layer to use a single texture, given the name of the texture to use on this layer.

Applies to both fixed-function and programmable pipeline.

SetTextureName ( string name, TextureType type ) : void
SetTextureName ( string name, TextureType type, int mipmaps ) : void

SetTextureName ( string name, TextureType type, int mipmaps, bool alpha ) : void

Sets this texture layer to use a single texture, given the name of the texture to use on this layer.

Applies to both fixed-function and programmable pipeline.

SetTextureRotate ( float degrees ) : void

Sets the counter-clockwise rotation factor applied to texture coordinates.

This sets a fixed rotation angle - if you wish to animate this, see the ControllerManager.CreateTextureRotator method.

Has no effect in the programmable pipeline.

SetTextureScale ( float u, float v ) : void

Sets the scaling factor of the texture.

This method sets the scale element of the texture transformation, and is easier to use than setTextureTransform if you are combining translation, scaling and rotation in your texture transformation. Again if you want to animate these values you need to use a Controller (see ControllerManager and it's methods for more information).

Has no effect in the programmable pipeline.

SetTextureScaleU ( float u ) : void

Same as in SetTextureScale, but sets only U value.

Has no effect in the programmable pipeline.

SetTextureScaleV ( float v ) : void

Same as in SetTextureScale, but sets only V value.

Has no effect in the programmable pipeline.

SetTextureScroll ( float u, float v ) : void

Sets the translation offset of the texture, ie scrolls the texture.

This method sets the translation element of the texture transformation, and is easier to use than setTextureTransform if you are combining translation, scaling and rotation in your texture transformation. Again if you want to animate these values you need to use a Controller

Has no effect in the programmable pipeline.

SetTextureScrollU ( float u ) : void

Same as in SetTextureScroll, but sets only U value.

Has no effect in the programmable pipeline.

SetTextureScrollV ( float v ) : void

Same as in SetTextureScroll, but sets only V value.

Has no effect in the programmable pipeline.

SetTransformAnimation ( TextureTransform transType, WaveformType waveType, float baseVal, float frequency, float phase, float amplitude ) : void

Sets up a general time-relative texture modification effect.

This can be called multiple times for different values of transType, but only the latest effect applies if called multiple time for the same transType.

This option has no effect in the programmable pipeline.

TextureUnitState ( Pass parent ) : System

Default constructor.

TextureUnitState ( Pass parent, string textureName ) : System

Name based constructor.

TextureUnitState ( Pass parent, string textureName, int texCoordSet ) : System

Constructor.

Unload ( ) : void

Internal method for unloading this object as part of Material.Unload.

Private Methods

Method Description
CreateAnimationController ( ) : void

Creates an animation controller if needed for this texture unit.

CreateEffectController ( TextureEffect effect ) : void

Used internally to create a new controller for this layer given the requested effect.

RecalcTextureMatrix ( ) : void

Used to update the texture matrix if need be.

RemoveEffect ( TextureEffectType type ) : void

Removes effects of the specified type from this layers effect list.

Method Details

AddEffect() public method

Generic method for setting up texture effects.
Allows you to specify effects directly by using the TextureEffectType enumeration. The arguments that go with it depend on the effect type. Only one effect of each type can be applied to a texture layer.

This method is used internally, but it is better generally for applications to use the more intuitive specialized methods such as SetEnvironmentMap and SetScroll.

public AddEffect ( TextureEffect effect ) : void
effect TextureEffect
return void

ApplyTextureAliases() public method

Applies texture names to Texture Unit State with matching texture name aliases. If no matching aliases are found then the TUS state does not change.
Cubic, 1d, 2d, and 3d textures are determined from current state of the Texture Unit. Assumes animated frames are sequentially numbered in the name. 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

Used to clone a texture layer. Mainly used during a call to Clone on a Material or Pass.
public Clone ( Pass parent ) : TextureUnitState
parent Pass
return TextureUnitState

CopyTo() public method

Used to clone a texture layer. Mainly used during a call to Clone on a Material.
public CopyTo ( TextureUnitState target ) : void
target TextureUnitState
return void

GetEffect() public method

Gets the texture effect at the specified index.
public GetEffect ( int index ) : TextureEffect
index int Index of the texture effect to retrieve.
return TextureEffect

GetEnvironmentMap() public method

public GetEnvironmentMap ( ) : EnvironmentMap
return EnvironmentMap

GetFrameTextureName() public method

Gets the name of the texture associated with a frame.
Applies to both fixed-function and programmable pipeline.
public GetFrameTextureName ( int frame ) : string
frame int Index of the frame to retreive the texture name for.
return string

GetTextureFiltering() public method

Gets the texture filtering for the given type.
public GetTextureFiltering ( FilterType type ) : FilterOptions
type FilterType Type of filtering options to retreive.
return FilterOptions

Load() public method

Internal method for loading this texture stage as part of Material.Load.
public Load ( ) : void
return void

NotifyNeedsRecompile() public method

Notifies the parent that it needs recompilation.
public NotifyNeedsRecompile ( ) : void
return void

RemoveAllEffects() public method

Removes all effects from this texture stage.
public RemoveAllEffects ( ) : void
return void

RemoveEffect() public method

Removes the specified effect from the list of effects being applied during this texture stage.
public RemoveEffect ( TextureEffect effect ) : void
effect TextureEffect Effect to remove.
return void

SetAlphaOperation() public method

Overloaded method.
public SetAlphaOperation ( LayerBlendOperationEx operation ) : void
operation LayerBlendOperationEx The operation to be used, e.g. modulate (multiply), add, subtract.
return void

SetAlphaOperation() public method

Sets the alpha operation to be applied to this texture.
This works in exactly the same way as SetColorOperation, except that the effect is applied to the level of alpha (i.e. transparency) of the texture rather than its color. When the alpha of a texel (a pixel on a texture) is 1.0, it is opaque, wheras it is fully transparent if the alpha is 0.0. Please refer to the SetColorOperation method for more info.
public SetAlphaOperation ( LayerBlendOperationEx operation, LayerBlendSource source1, LayerBlendSource source2, float arg1, float arg2, float blendFactor ) : void
operation LayerBlendOperationEx The operation to be used, e.g. modulate (multiply), add, subtract.
source1 LayerBlendSource The source of the first alpha value to the operation e.g. texture alpha.
source2 LayerBlendSource The source of the second alpha value to the operation e.g. current surface alpha.
arg1 float Manually supplied alpha value (only required if source1 = LayerBlendSource.Manual).
arg2 float Manually supplied alpha value (only required if source2 = LayerBlendSource.Manual).
blendFactor float Manually supplied 'blend' value - only required for operations /// which require manual blend e.g. LayerBlendOperationEx.BlendManual. ///
return void

SetAnimatedTextureName() public method

Sets the names of the texture images for an animated texture.
Animated textures are just a series of images making up the frames of the animation. All the images must be the same size, and their names must have a frame number appended before the extension, e.g. if you specify a name of "wall.jpg" with 3 frames, the image names must be "wall_1.jpg" and "wall_2.jpg".

You can change the active frame on a texture layer by setting the CurrentFrame property.

Note: If you can't make your texture images conform to the naming standard layed out here, you can call the alternative SetAnimatedTextureName method which takes an array of names instead.

public SetAnimatedTextureName ( string name, int numFrames, float duration ) : void
name string The base name of the series of textures to use.
numFrames int Number of frames to be used for this animation.
duration float /// Total length of the animation sequence. When set to 0, automatic animation does not occur. /// In that scenario, the values can be changed manually by setting the CurrentFrame property. ///
return void

SetColorOpMultipassFallback() public method

Sets the multipass fallback operation for this layer, if you used TextureUnitState.SetColorOperationEx and not enough multitexturing hardware is available.
Because some effects exposed using TextureUnitState.SetColorOperationEx are only supported under multitexturing hardware, if the hardware is lacking the system must fallback on multipass rendering, which unfortunately doesn't support as many effects. This method is for you to specify the fallback operation which most suits you.

You'll notice that the interface is the same as the Material.SetSceneBlending method; this is because multipass rendering IS effectively scene blending, since each layer is rendered on top of the last using the same mechanism as making an object transparent, it's just being rendered in the same place repeatedly to get the multitexture effect.

If you use the simpler (and hence less flexible) TextureUnitState.SetColorOperation method you don't need to call this as the system sets up the fallback for you.

This option has no effect in the programmable pipeline, because there is no multipass fallback and multitexture blending is handled by the fragment shader.

public SetColorOpMultipassFallback ( SceneBlendFactor src, SceneBlendFactor dest ) : void
src SceneBlendFactor How to apply the source color during blending.
dest SceneBlendFactor How to affect the destination color during blending.
return void

SetColorOperation() public method

Determines how this texture layer is combined with the one below it (or the diffuse color of the geometry if this is layer 0).
This method is the simplest way to blend tetxure layers, because it requires only one parameter, gives you the most common blending types, and automatically sets up 2 blending methods: one for if single-pass multitexturing hardware is available, and another for if it is not and the blending must be achieved through multiple rendering passes. It is, however, quite limited and does not expose the more flexible multitexturing operations, simply because these can't be automatically supported in multipass fallback mode. If want to use the fancier options, use , but you'll either have to be sure that enough multitexturing units will be available, or you should explicitly set a fallback using TextureUnitState.SetColorOpMultipassFallback.

The default method is LayerBlendOperation.Modulate for all layers.

This option has no effect in the programmable pipeline.

public SetColorOperation ( LayerBlendOperation operation ) : void
operation LayerBlendOperation One of the LayerBlendOperation enumerated blending types.
return void

SetColorOperationEx() public method

Overloaded method.
public SetColorOperationEx ( LayerBlendOperationEx operation ) : void
operation LayerBlendOperationEx The operation to be used, e.g. modulate (multiply), add, subtract.
return void

SetColorOperationEx() public method

Overloaded method.
public SetColorOperationEx ( LayerBlendOperationEx operation, LayerBlendSource source1, LayerBlendSource source2 ) : void
operation LayerBlendOperationEx The operation to be used, e.g. modulate (multiply), add, subtract.
source1 LayerBlendSource The source of the first color to the operation e.g. texture color.
source2 LayerBlendSource The source of the second color to the operation e.g. current surface color.
return void

SetColorOperationEx() public method

Overloaded method.
public SetColorOperationEx ( LayerBlendOperationEx operation, LayerBlendSource source1, LayerBlendSource source2, ColorEx arg1 ) : void
operation LayerBlendOperationEx The operation to be used, e.g. modulate (multiply), add, subtract.
source1 LayerBlendSource The source of the first color to the operation e.g. texture color.
source2 LayerBlendSource The source of the second color to the operation e.g. current surface color.
arg1 Axiom.Core.ColorEx Manually supplied color value (only required if source1 = Manual).
return void

SetColorOperationEx() public method

For setting advanced blending options.
This is an extended version of the TextureUnitState.SetColorOperation method which allows extremely detailed control over the blending applied between this and earlier layers. See the IMPORTANT note below about the issues between mulitpass and multitexturing that using this method can create.

Texture color operations determine how the final color of the surface appears when rendered. Texture units are used to combine color values from various sources (ie. the diffuse color of the surface from lighting calculations, combined with the color of the texture). This method allows you to specify the 'operation' to be used, ie. the calculation such as adds or multiplies, and which values to use as arguments, such as a fixed value or a value from a previous calculation.

The defaults for each layer are:

  • op = Modulate
  • source1 = Texture
  • source2 = Current
ie. each layer takes the color results of the previous layer, and multiplies them with the new texture being applied. Bear in mind that colors are RGB values from 0.0 - 1.0 so multiplying them together will result in values in the same range, 'tinted' by the multiply. Note however that a straight multiply normally has the effect of darkening the textures - for this reason there are brightening operations like ModulateX2. See the LayerBlendOperation and LayerBlendSource enumerated types for full details.

Because of the limitations on some underlying APIs (Direct3D included) the Texture argument can only be used as the first argument, not the second.

The final 3 parameters are only required if you decide to pass values manually into the operation, i.e. you want one or more of the inputs to the color calculation to come from a fixed value that you supply. Hence you only need to fill these in if you supply Manual to the corresponding source, or use the BlendManual operation.

The engine tries to use multitexturing hardware to blend texture layers together. However, if it runs out of texturing units (e.g. 2 of a GeForce2, 4 on a GeForce3) it has to fall back on multipass rendering, i.e. rendering the same object multiple times with different textures. This is both less efficient and there is a smaller range of blending operations which can be performed. For this reason, if you use this method you MUST also call TextureUnitState.SetColorOpMultipassFallback to specify which effect you want to fall back on if sufficient hardware is not available.

If you wish to avoid having to do this, use the simpler TextureUnitState.SetColorOperation method which allows less flexible blending options but sets up the multipass fallback automatically, since it only allows operations which have direct multipass equivalents.

This has no effect in the programmable pipeline.

public SetColorOperationEx ( LayerBlendOperationEx operation, LayerBlendSource source1, LayerBlendSource source2, ColorEx arg1, ColorEx arg2, float blendFactor ) : void
operation LayerBlendOperationEx The operation to be used, e.g. modulate (multiply), add, subtract.
source1 LayerBlendSource The source of the first color to the operation e.g. texture color.
source2 LayerBlendSource The source of the second color to the operation e.g. current surface color.
arg1 Axiom.Core.ColorEx Manually supplied color value (only required if source1 = Manual).
arg2 Axiom.Core.ColorEx Manually supplied color value (only required if source2 = Manual)
blendFactor float /// Manually supplied 'blend' value - only required for operations /// which require manual blend e.g. LayerBlendOperationEx.BlendManual ///
return void

SetCubicTextureName() public method

Sets this texture layer to use a combination of 6 texture maps, each one relating to a face of a cube.
Cubic textures are made up of 6 separate texture images. Each one of these is an orthoganal view of the world with a FOV of 90 degrees and an aspect ratio of 1:1. You can generate these from 3D Studio by rendering a scene to a reflection map of a transparent cube and saving the output files.

Cubic maps can be used either for skyboxes (complete wrap-around skies, like space) or as environment maps to simulate reflections. The system deals with these 2 scenarios in different ways:

  1. For cubic environment maps, the 6 textures are combined into a single 'cubic' texture map which is then addressed using 3D texture coordinates. This is required because you don't know what face of the box you're going to need to address when you render an object, and typically you need to reflect more than one face on the one object, so all 6 textures are needed to be 'active' at once. Cubic environment maps are enabled by calling this method with the forUVW parameter set to true, and then calling SetEnvironmentMap(true).

    Note that not all cards support cubic environment mapping.

  2. For skyboxes, the 6 textures are kept separate and used independently for each face of the skybox. This is done because not all cards support 3D cubic maps and skyboxes do not need to use 3D texture coordinates so it is simpler to render each face of the box with 2D coordinates, changing texture between faces.

    Skyboxes are created by calling SceneManager.SetSkyBox.

Applies to both fixed-function and programmable pipeline.

public SetCubicTextureName ( string textureName, bool forUVW ) : void
textureName string /// The basic name of the texture e.g. brickwall.jpg, stonefloor.png. There must be 6 versions /// of this texture with the suffixes _fr, _bk, _up, _dn, _lf, and _rt (before the extension) which /// make up the 6 sides of the box. The textures must all be the same size and be powers of 2 in width & height. /// If you can't make your texture names conform to this, use the alternative method of the same name which takes /// an array of texture names instead. ///
forUVW bool /// Set to true if you want a single 3D texture addressable with 3D texture coordinates rather than /// 6 separate textures. Useful for cubic environment mapping. ///
return void

SetEnvironmentMap() public method

Overloaded method.
public SetEnvironmentMap ( bool enable ) : void
enable bool
return void

SetEnvironmentMap() public method

Turns on/off texture coordinate effect that makes this layer an environment map.
Environment maps make an object look reflective by using the object's vertex normals relative to the camera view to generate texture coordinates.

The vectors generated can either be used to address a single 2D texture which is a 'fish-eye' lens view of a scene, or a 3D cubic environment map which requires 6 textures for each side of the inside of a cube. The type depends on what texture you set up - if you use the setTextureName method then a 2D fisheye lens texture is required, whereas if you used setCubicTextureName then a cubic environemnt map will be used.

This effect works best if the object has lots of gradually changing normals. The texture also has to be designed for this effect - see the example spheremap.png included with the sample application for a 2D environment map; a cubic map can be generated by rendering 6 views of a scene to each of the cube faces with orthoganal views.

Enabling this disables any other texture coordinate generation effects. However it can be combined with texture coordinate modification functions, which then operate on the generated coordinates rather than static model texture coordinates.

This option has no effect in the programmable pipeline.

public SetEnvironmentMap ( bool enable, EnvironmentMap envMap ) : void
enable bool True to enable, false to disable.
envMap EnvironmentMap /// If set to true, instead of being based on normals the environment effect is based on /// vertex positions. This is good for planar surfaces. ///
return void

SetProjectiveTexturing() public method

Enables or disables projective texturing on this texture unit.

Projective texturing allows you to generate texture coordinates based on a Frustum, which gives the impression that a texture is being projected onto the surface. Note that once you have called this method, the texture unit continues to monitor the Frustum you passed in and the projection will change if you can alter it. It also means that the Frustum object you pass remains in existence for as long as this TextureUnitState does.

This effect cannot be combined with other texture generation effects, such as environment mapping. It also has no effect on passes which have a vertex program enabled - projective texturing has to be done in the vertex program instead.

public SetProjectiveTexturing ( bool enable, Frustum projectionSettings ) : void
enable bool /// Whether to enable / disable ///
projectionSettings Axiom.Core.Frustum /// The Frustum which will be used to derive the projection parameters. ///
return void

SetRotateAnimation() public method

Sets up an animated texture rotation for this layer.
Useful for constant rotations (for varying rotations, SetTransformAnimation).

This option has no effect in the programmable pipeline.

public SetRotateAnimation ( float speed ) : void
speed float The number of complete counter-clockwise revolutions per second (use -ve for clockwise)
return void

SetScrollAnimation() public method

Sets up an animated scroll for the texture layer.
Useful for creating constant scrolling effects on a texture layer (for varying scrolls, SetTransformAnimation).

This option has no effect in the programmable pipeline.

public SetScrollAnimation ( float uSpeed, float vSpeed ) : void
uSpeed float The number of horizontal loops per second (+ve=moving right, -ve = moving left).
vSpeed float The number of vertical loops per second (+ve=moving up, -ve= moving down).
return void

SetTextureAddressingMode() public method

Sets the texture addressing mode, i.e. what happens at uv values above 1.0.
The default is TAM_WRAP i.e. the texture repeats over values of 1.0. This is a shortcut method which sets the addressing mode for all coordinates at once; you can also call the more specific method to set the addressing mode per coordinate. This applies for both the fixed-function and programmable pipelines.
public SetTextureAddressingMode ( TextureAddressing tam ) : void
tam TextureAddressing
return void

SetTextureAddressingMode() public method

Sets the texture addressing mode, i.e. what happens at uv values above 1.0.
The default is TAM_WRAP i.e. the texture repeats over values of 1.0. This applies for both the fixed-function and programmable pipelines.
public SetTextureAddressingMode ( TextureAddressing u, TextureAddressing v, TextureAddressing w ) : void
u TextureAddressing
v TextureAddressing
w TextureAddressing
return void

SetTextureAddressingMode() public method

Sets the texture addressing mode, i.e. what happens at uv values above 1.0.
The default is TAM_WRAP i.e. the texture repeats over values of 1.0. This applies for both the fixed-function and programmable pipelines.
public SetTextureAddressingMode ( UVWAddressing uvw ) : void
uvw UVWAddressing
return void

SetTextureFiltering() public method

Set a the detailed filtering options on this texture unit.
public SetTextureFiltering ( FilterOptions minFilter, FilterOptions magFilter, FilterOptions mipFilter ) : void
minFilter FilterOptions /// The filtering to use when reducing the size of the texture. Can be Point, Linear or Anisotropic. ///
magFilter FilterOptions /// The filtering to use when increasing the size of the texture. Can be Point, Linear or Anisotropic. ///
mipFilter FilterOptions /// The filtering to use between mipmap levels. Can be None (no mipmap), Point or Linear (trilinear). ///
return void

SetTextureFiltering() public method

Set a single filtering option on this texture unit.
public SetTextureFiltering ( FilterType type, FilterOptions options ) : void
type FilterType /// The filtering type to set. ///
options FilterOptions /// The filtering options to set. ///
return void

SetTextureFiltering() public method

Set the texture filtering for this unit, using the simplified interface.
You also have the option of specifying the minification, magnification and mip filter individually if you want more control over filtering options. See the SetTextureFiltering overloads for details.

Note: This option applies in both the fixed function and programmable pipeline.

public SetTextureFiltering ( TextureFiltering filter ) : void
filter TextureFiltering /// The high-level filter type to use. ///
return void

SetTextureName() public method

Sets this texture layer to use a single texture, given the name of the texture to use on this layer.
Applies to both fixed-function and programmable pipeline.
public SetTextureName ( string name ) : void
name string Name of the texture.
return void

SetTextureName() public method

public SetTextureName ( string name, TextureType type ) : void
name string
type TextureType
return void

SetTextureName() public method

public SetTextureName ( string name, TextureType type, int mipmaps ) : void
name string
type TextureType
mipmaps int
return void

SetTextureName() public method

Sets this texture layer to use a single texture, given the name of the texture to use on this layer.
Applies to both fixed-function and programmable pipeline.
public SetTextureName ( string name, TextureType type, int mipmaps, bool alpha ) : void
name string Name of the texture.
type TextureType Type of texture this is.
mipmaps int
alpha bool
return void

SetTextureRotate() public method

Sets the counter-clockwise rotation factor applied to texture coordinates.
This sets a fixed rotation angle - if you wish to animate this, see the ControllerManager.CreateTextureRotator method.

Has no effect in the programmable pipeline.

public SetTextureRotate ( float degrees ) : void
degrees float The angle of rotation in degrees (counter-clockwise).
return void

SetTextureScale() public method

Sets the scaling factor of the texture.
This method sets the scale element of the texture transformation, and is easier to use than setTextureTransform if you are combining translation, scaling and rotation in your texture transformation. Again if you want to animate these values you need to use a Controller (see ControllerManager and it's methods for more information).

Has no effect in the programmable pipeline.

public SetTextureScale ( float u, float v ) : void
u float The value by which the texture is to be scaled horizontally.
v float The value by which the texture is to be scaled vertically.
return void

SetTextureScaleU() public method

Same as in SetTextureScale, but sets only U value.
Has no effect in the programmable pipeline.
public SetTextureScaleU ( float u ) : void
u float The value by which the texture is to be scaled horizontally.
return void

SetTextureScaleV() public method

Same as in SetTextureScale, but sets only V value.
Has no effect in the programmable pipeline.
public SetTextureScaleV ( float v ) : void
v float The value by which the texture is to be scaled vertically.
return void

SetTextureScroll() public method

Sets the translation offset of the texture, ie scrolls the texture.
This method sets the translation element of the texture transformation, and is easier to use than setTextureTransform if you are combining translation, scaling and rotation in your texture transformation. Again if you want to animate these values you need to use a Controller

Has no effect in the programmable pipeline.

public SetTextureScroll ( float u, float v ) : void
u float The amount the texture should be moved horizontally (u direction).
v float The amount the texture should be moved vertically (v direction).
return void

SetTextureScrollU() public method

Same as in SetTextureScroll, but sets only U value.
Has no effect in the programmable pipeline.
public SetTextureScrollU ( float u ) : void
u float The amount the texture should be moved horizontally (u direction).
return void

SetTextureScrollV() public method

Same as in SetTextureScroll, but sets only V value.
Has no effect in the programmable pipeline.
public SetTextureScrollV ( float v ) : void
v float The amount the texture should be moved vertically (v direction).
return void

SetTransformAnimation() public method

Sets up a general time-relative texture modification effect.
This can be called multiple times for different values of transType, but only the latest effect applies if called multiple time for the same transType.

This option has no effect in the programmable pipeline.

public SetTransformAnimation ( TextureTransform transType, WaveformType waveType, float baseVal, float frequency, float phase, float amplitude ) : void
transType TextureTransform The type of transform, either translate (scroll), scale (stretch) or rotate (spin).
waveType WaveformType The shape of the wave, see enum for details
baseVal float The base value for the function (range of output = {base, base + amplitude}).
frequency float The speed of the wave in cycles per second.
phase float The offset of the start of the wave, e.g. 0.5 to start half-way through the wave.
amplitude float Scales the output so that instead of lying within [0..1] it lies within [0..(1 * amplitude)] for exaggerated effects.
return void

TextureUnitState() public method

Default constructor.
public TextureUnitState ( Pass parent ) : System
parent Pass Parent Pass of this TextureUnitState.
return System

TextureUnitState() public method

Name based constructor.
public TextureUnitState ( Pass parent, string textureName ) : System
parent Pass Parent Pass of this texture stage.
textureName string Name of the texture for this texture stage.
return System

TextureUnitState() public method

Constructor.
public TextureUnitState ( Pass parent, string textureName, int texCoordSet ) : System
parent Pass
textureName string
texCoordSet int
return System

Unload() public method

Internal method for unloading this object as part of Material.Unload.
public Unload ( ) : void
return void

Property Details

parent protected_oe property

The parent Pass that owns this TextureUnitState.
protected Pass,Axiom.Graphics parent
return Pass

texAddressingMode protected_oe property

Addressing mode to use for texture coordinates.
protected UVWAddressing,Axiom.Graphics texAddressingMode
return UVWAddressing