Main Page   Namespace List   Class Hierarchy   Alphabetical List   Compound List   File List   Namespace Members   Compound Members   File Members   Related Pages  

Ogre::Material::TextureLayer Class Reference

Nested class representing a single texture layer of a material. More...

#include <OgreMaterial.h>

List of all members.

Public Types

enum  TextureEffectType {
  ET_BUMP_MAP, ET_ENVIRONMENT_MAP, ET_SCROLL, ET_ROTATE,
  ET_TRANSFORM
}
 Definition of the broad types of texture effect you can apply to a texture layer. More...

enum  EnvMapType { ENV_PLANAR, ENV_CURVED }
 Enumeration to specify type of envmap. More...

enum  TextureTransformType {
  TT_TRANSLATE_U, TT_TRANSLATE_V, TT_SCALE_U, TT_SCALE_V,
  TT_ROTATE
}
 Useful enumeration when dealing with procedural transforms. More...

enum  TextureAddressingMode { TAM_WRAP, TAM_MIRROR, TAM_CLAMP }
 Texture addressing modes - default is TAM_WRAP. More...

enum  TextureCubeFace {
  CUBE_FRONT = 0, CUBE_BACK = 1, CUBE_LEFT = 2, CUBE_RIGHT = 3,
  CUBE_UP = 4, CUBE_DOWN = 5
}
 Enum identifying the frame indexes for faces of a cube map (not the composite 3D type. More...


Public Methods

 TextureLayer (bool deferLoad=false)
 Default constructor. More...

 TextureLayer (const TextureLayer &oth)
TextureLayer & operator= (const TextureLayer &oth)
 ~TextureLayer ()
 Default destructor. More...

 TextureLayer (const String &texName, int texCoordSet=0, bool deferLoad=false)
 Name-based constructor. More...

void setDeferredLoad (bool defer)
 Mostly internal method to indicate a deferred load texture layer. More...

const String & getTextureName (void) const
 Get the name of current texture image for this layer. More...

void setTextureName (const String &name)
 Sets this texture layer to use a single texture, given the name of the texture to use on this layer. More...

void setCubicTextureName (const String &name, bool forUVW=false)
 Sets this texture layer to use a combination of 6 texture maps, each one relating to a face of a cube. More...

void setCubicTextureName (const String *const names, bool forUVW=false)
 Sets this texture layer to use a combination of 6 texture maps, each one relating to a face of a cube. More...

void setAnimatedTextureName (const String &name, int numFrames, Real duration=0)
 Sets the names of the texture images for an animated texture. More...

void setAnimatedTextureName (const String *const names, int numFrames, Real duration=0)
 Sets the names of the texture images for an animated texture. More...

std::pair< uint, uint > getTextureDimensions (int frame=0) const
 Returns the width and height of the texture in the given frame. More...

void setCurrentFrame (int frameNumber)
 Changes the active frame in an animated or multi-image texture. More...

int getCurrentFrame (void) const
 Gets the active frame in an animated or multi-image texture layer. More...

const String & getFrameTextureName (int frameNumber) const
 Gets the name of the texture associated with a frame. More...

int getNumFrames (void) const
 Gets the number of frames for a texture. More...

bool isCubic (void) const
 Returns true if this texture layer is a cubic texture, false otherwise. More...

bool is3D (void) const
 Returns true if this texture layer uses a composite 3D cubic texture. More...

int getTextureCoordSet (void) const
 Gets the index of the set of texture co-ords this layer uses. More...

void setTextureCoordSet (int set)
 Sets the index of the set of texture co-ords this layer uses. More...

void setTextureTransform (const Matrix4 &xform)
 Sets a matrix used to transform any texture coordinates on this layer. More...

const Matrix4 & getTextureTransform (void)
 Gets the current texture transformation matrix. More...

void setTextureScroll (Real u, Real v)
 Sets the translation offset of the texture, ie scrolls the texture. More...

void setTextureUScroll (Real value)
 As setTextureScroll, but sets only U value. More...

void setTextureVScroll (Real value)
 As setTextureScroll, but sets only V value. More...

void setTextureUScale (Real value)
 As setTextureScale, but sets only U value. More...

void setTextureVScale (Real value)
 As setTextureScale, but sets only V value. More...

void setTextureScale (Real uScale, Real vScale)
 Sets the scaling factor applied to texture coordinates. More...

void setTextureRotate (Real degrees)
 Sets the anticlockwise rotation factor applied to texture coordinates. More...

TextureAddressingMode getTextureAddressingMode (void) const
 Gets the texture addressing mode, i.e. More...

void setTextureAddressingMode (TextureAddressingMode tam)
 Sets the texture addressing mode, i.e. More...

void setColourOperationEx (LayerBlendOperationEx op, LayerBlendSource source1=LBS_TEXTURE, LayerBlendSource source2=LBS_CURRENT, const ColourValue &arg1=ColourValue::White, const ColourValue &arg2=ColourValue::White, Real manualBlend=0.0)
 Setting advanced blending options. More...

void setColourOperation (const LayerBlendOperation op)
 Determines how this texture layer is combined with the one below it (or the diffuse colour of the geometry if this is layer 0). More...

void setColourOpMultipassFallback (const SceneBlendFactor sourceFactor, const SceneBlendFactor destFactor)
 Sets the multipass fallback operation for this layer, if you used TextureLayer::setColourOperationEx and not enough multitexturing hardware is available. More...

LayerBlendModeEx getColourBlendMode (void) const
 Get multitexturing colour blending mode. More...

LayerBlendModeEx getAlphaBlendMode (void) const
 Get multitexturing alpha blending mode. More...

SceneBlendFactor getColourBlendFallbackSrc (void) const
 Get the multipass fallback for colour blending operation source factor. More...

SceneBlendFactor getColourBlendFallbackDest (void) const
 Get the multipass fallback for colour blending operation destination factor. More...

void setAlphaOperation (LayerBlendOperationEx op, LayerBlendSource source1=LBS_TEXTURE, LayerBlendSource source2=LBS_CURRENT, Real arg1=1.0, Real arg2=1.0, Real manualBlend=0.0)
 Sets the alpha operation to be applied to this texture. More...

void addEffect (TextureEffect &effect)
 Generic method for setting up texture effects. More...

void setEnvironmentMap (bool enable, bool planar=false)
 Turns on/off texture coordinate effect that makes this layer an environment map. More...

void setScrollAnimation (Real uSpeed, Real vSpeed)
 Sets up an animated scroll for the texture layer. More...

void setRotateAnimation (Real speed)
 Sets up an animated texture rotation for this layer. More...

void setTransformAnimation (const TextureTransformType ttype, const WaveformType waveType, Real base=0, Real frequency=1, Real phase=0, Real amplitude=1)
 Sets up a general time-relative texture modification effect. More...

void setAlphaRejectSettings (const CompareFunction func, unsigned char value)
 Sets the way the layer will have use alpha to totally reject pixels from the pipeline. More...

CompareFunction getAlphaRejectFunction (void) const
 Gets the alpha reject function. More...

unsigned char getAlphaRejectValue (void) const
 Gets the alpha reject value. More...

void removeAllEffects (void)
 Removes all effects applied to this texture layer. More...

void removeEffect (const TextureEffectType type)
 Removes a single effect applied to this texture layer. More...

bool isBlank (void) const
 Determines if this texture layer is currently blank. More...

void setBlank (void)
 Sets this texture layer to be blank. More...

void _load (void)
 Internal method for dealing with deferred texture loading. More...


Protected Types

typedef std::multimap< TextureEffectType,
TextureEffect > 		EffectMap

Protected Methods

void recalcTextureMatrix (void)
 Internal method for calculating texture matrix. More...

void createAnimController (void)
 Internal method for creating animation controller. More...

void createEffectController (TextureEffect &effect)
 Internal method for creating texture effect controller. More...


Protected Attributes

int mNumFrames
 Number of frames of animation, or frames making up cubic. More...

int mCurrentFrame
 The xurrent animation frame. More...

Real mAnimDuration
 Duration of animation in seconds. More...

Controller * mAnimController
bool mCubic
int textureCoordSetIndex
TextureAddressingMode mAddressMode
LayerBlendModeEx colourBlendMode
SceneBlendFactor colourBlendFallbackSrc
SceneBlendFactor colourBlendFallbackDest
LayerBlendModeEx alphaBlendMode
bool mIsBlank
bool mDeferLoad
bool mRecalcTexMatrix
Real mUMod
Real mVMod
Real mUScale
Real mVScale
Real mRotate
Matrix4 mTexModMatrix
CompareFunction mAlphaRejectFunc
unsigned char mAlphaRejectVal
Real mUScrollAnim
Real mVScrollAnim
Real mRotateAnim
String mFrames [MAX_FRAMES]
EffectMap mEffects

Friends

class RenderSystem

Detailed Description

Nested class representing a single texture layer of a material.

Member Typedef Documentation

typedef std::multimap<TextureEffectType, TextureEffect> Ogre::Material::TextureLayer::EffectMap [protected]
 

Member Enumeration Documentation

enum Ogre::Material::TextureLayer::EnvMapType
 

Enumeration to specify type of envmap.

Enumeration values:
ENV_PLANAR  Envmap based on vector from camera to vertex position, good for planar geometry.
ENV_CURVED  Envmap based on dot of vector from camera to vertex and vertex normal, good for curves.

enum Ogre::Material::TextureLayer::TextureAddressingMode
 

Texture addressing modes - default is TAM_WRAP.

Enumeration values:
TAM_WRAP  Texture wraps at values over 1.0.
TAM_MIRROR  Texture mirrors (flips) at joins over 1.0.
TAM_CLAMP  Texture clamps at 1.0.

enum Ogre::Material::TextureLayer::TextureCubeFace
 

Enum identifying the frame indexes for faces of a cube map (not the composite 3D type.

Enumeration values:
CUBE_FRONT 
CUBE_BACK 
CUBE_LEFT 
CUBE_RIGHT 
CUBE_UP 
CUBE_DOWN 

enum Ogre::Material::TextureLayer::TextureEffectType
 

Definition of the broad types of texture effect you can apply to a texture layer.

Enumeration values:
ET_BUMP_MAP  Bump mapping.
ET_ENVIRONMENT_MAP  Generate all texture coords based on angle between camera and vertex.
ET_SCROLL  Constant u/v scrolling effect.
ET_ROTATE  Constant rotation.
ET_TRANSFORM  More complex transform.

enum Ogre::Material::TextureLayer::TextureTransformType
 

Useful enumeration when dealing with procedural transforms.

Enumeration values:
TT_TRANSLATE_U 
TT_TRANSLATE_V 
TT_SCALE_U 
TT_SCALE_V 
TT_ROTATE 

Constructor & Destructor Documentation

Ogre::Material::TextureLayer::TextureLayer (  bool    deferLoad = false ) 
 

Default constructor.

Ogre::Material::TextureLayer::TextureLayer (  const TextureLayer &    oth ) 
 

Ogre::Material::TextureLayer::~TextureLayer (    ) 
 

Default destructor.

Ogre::Material::TextureLayer::TextureLayer (  const String &    texName,
int    texCoordSet = 0,
bool    deferLoad = false
)  [explicit]
 

Name-based constructor.

Note:
Explicit to stop implicit conversion from char, causes ambiguity problems on addTextureLayer(char*).
Parameters:
name  The basic name of the texture e.g. brickwall.jpg, stonefloor.png
texCoordSet  The index of the texture coordinate set to use.

Member Function Documentation

void Ogre::Material::TextureLayer::_load (  void    ) 
 

Internal method for dealing with deferred texture loading.

void Ogre::Material::TextureLayer::addEffect (  TextureEffect &    effect ) 
 

Generic method for setting up texture effects.

Remarks:
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 by Ogre but it is better generally for applications to use the more intuitive specialised methods such as setEnvironmentMap and setScroll.

void Ogre::Material::TextureLayer::createAnimController (  void    )  [protected]
 

Internal method for creating animation controller.

void Ogre::Material::TextureLayer::createEffectController (  TextureEffect &    effect )  [protected]
 

Internal method for creating texture effect controller.

LayerBlendModeEx Ogre::Material::TextureLayer::getAlphaBlendMode (  void    )  const
 

Get multitexturing alpha blending mode.

CompareFunction Ogre::Material::TextureLayer::getAlphaRejectFunction (  void    )  const
 

Gets the alpha reject function.

See setAlphaRejectSettings for more information.

unsigned char Ogre::Material::TextureLayer::getAlphaRejectValue (  void    )  const
 

Gets the alpha reject value.

See setAlphaRejectSettings for more information.

SceneBlendFactor Ogre::Material::TextureLayer::getColourBlendFallbackDest (  void    )  const
 

Get the multipass fallback for colour blending operation destination factor.

SceneBlendFactor Ogre::Material::TextureLayer::getColourBlendFallbackSrc (  void    )  const
 

Get the multipass fallback for colour blending operation source factor.

LayerBlendModeEx Ogre::Material::TextureLayer::getColourBlendMode (  void    )  const
 

Get multitexturing colour blending mode.

int Ogre::Material::TextureLayer::getCurrentFrame (  void    )  const
 

Gets the active frame in an animated or multi-image texture layer.

const String & Ogre::Material::TextureLayer::getFrameTextureName (  int    frameNumber )  const
 

Gets the name of the texture associated with a frame.

int Ogre::Material::TextureLayer::getNumFrames (  void    )  const
 

Gets the number of frames for a texture.

Material::TextureLayer::TextureAddressingMode Ogre::Material::TextureLayer::getTextureAddressingMode (  void    )  const
 

Gets the texture addressing mode, i.e.

what happens at uv values above 1.0.

Note:
The default is TAM_WRAP i.e. the texture repeats over values of 1.0.

int Ogre::Material::TextureLayer::getTextureCoordSet (  void    )  const
 

Gets the index of the set of texture co-ords this layer uses.

std::pair< uint, uint > Ogre::Material::TextureLayer::getTextureDimensions (  int    frame = 0 )  const
 

Returns the width and height of the texture in the given frame.

const String & Ogre::Material::TextureLayer::getTextureName (  void    )  const
 

Get the name of current texture image for this layer.

Remarks:
This will either always be a single name for this layer, or will be the name of the current frame for an animated or otherwise multi-frame texture.

const Matrix4 & Ogre::Material::TextureLayer::getTextureTransform (  void    ) 
 

Gets the current texture transformation matrix.

Remarks:
Causes a reclaculation of the matrix if any parameters have been changed via setTextureScroll, setTextureScale and setTextureRotate.

bool Ogre::Material::TextureLayer::is3D (  void    )  const
 

Returns true if this texture layer uses a composite 3D cubic texture.

bool Ogre::Material::TextureLayer::isBlank (  void    )  const
 

Determines if this texture layer is currently blank.

Note:
This can happen if a texture fails to load or some other non-fatal error. Worth checking after setting texture name.

bool Ogre::Material::TextureLayer::isCubic (  void    )  const
 

Returns true if this texture layer is a cubic texture, false otherwise.

Material::TextureLayer & Ogre::Material::TextureLayer::operator= (  const TextureLayer &    oth ) 
 

void Ogre::Material::TextureLayer::recalcTextureMatrix (  void    )  [protected]
 

Internal method for calculating texture matrix.

void Ogre::Material::TextureLayer::removeAllEffects (  void    ) 
 

Removes all effects applied to this texture layer.

void Ogre::Material::TextureLayer::removeEffect (  const TextureEffectType    type ) 
 

Removes a single effect applied to this texture layer.

Note:
Because you can only have 1 effect of each type (e.g. 1 texture coordinate generation) applied to a layer, only the effect type is required.

void Ogre::Material::TextureLayer::setAlphaOperation (  LayerBlendOperationEx    op,
LayerBlendSource    source1 = LBS_TEXTURE,
LayerBlendSource    source2 = LBS_CURRENT,
Real    arg1 = 1.0,
Real    arg2 = 1.0,
Real    manualBlend = 0.0
) 
 

Sets the alpha operation to be applied to this texture.

Remarks:
This works in exactly the same way as setColourOperation, except that the effect is applied to the level of alpha (i.e. transparency) of the texture rather than its colour. 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 setColourOperation method for more info.
Parameters:
op  The operation to be used, e.g. modulate (multiply), add, subtract
source1  The source of the first alpha value to the operation e.g. texture alpha
source2  The source of the second alpha value to the operation e.g. current surface alpha
arg1  Manually supplied alpha value (only required if source1 = LBS_MANUAL)
arg2  Manually supplied alpha value (only required if source2 = LBS_MANUAL)
manualBlend  Manually supplied 'blend' value - only required for operations which require manual blend e.g. LBX_BLEND_MANUAL
See also:
setColourOperation

void Ogre::Material::TextureLayer::setAlphaRejectSettings (  const CompareFunction    func,
unsigned char    value
) 
 

Sets the way the layer will have use alpha to totally reject pixels from the pipeline.

Note:
The default is CMPF_ALWAYS_PASS i.e. alpha is not used to reject pixels.
Parameters:
func  The comparison which must pass for the pixel to be written.
value  1 byte value against which alpha values will be tested. Recommended 0 or 128 for compatibility.

void Ogre::Material::TextureLayer::setAnimatedTextureName (  const String *const    names,
int    numFrames,
Real    duration = 0
) 
 

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

Remarks:
This an alternative method to the one where you specify a single name and let the system derive the names of each frame, incase your images can't conform to this naming standard.

Animated textures are just a series of images making up the frames of the animation. All the images must be the same size, and you must provide their names as an array in the first parameter. You can change the active frame on a texture layer by calling the setCurrentFrame method.

Note:
If you can make your texture images conform to a naming standard of basicName_frame.ext, you can call the alternative setAnimatedTextureName method which just takes a base name instead.
Parameters:
names  Pointer to array of names of the textures to use, in frame order.
numFrames  The number of frames in the sequence.
duration  The length of time it takes to display the whole animation sequence, in seconds. If 0, no automatic transition occurs.

void Ogre::Material::TextureLayer::setAnimatedTextureName (  const String &    name,
int    numFrames,
Real    duration = 0
) 
 

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

Remarks:
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 calling the setCurrentFrame method.

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.
Parameters:
name  The base name of the textures to use e.g. wall.jpg for frames wall_1.jpg, wall_2.jpg etc.
numFrames  The number of frames in the sequence.
duration  The length of time it takes to display the whole animation sequence, in seconds. If 0, no automatic transition occurs.

void Ogre::Material::TextureLayer::setBlank (  void    ) 
 

Sets this texture layer to be blank.

void Ogre::Material::TextureLayer::setColourOperation (  const LayerBlendOperation    op ) 
 

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

Remarks:
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 TextureLayer::setColourOperationEx, but you'll either have to be sure that enough multitexturing units will be available, or you should explicitly set a fallback using TextureLayer::setColourOpMultipassFallback.
Note:
The default method is LBO_MODULATE for all layers.
Parameters:
op  One of the LayerBlendOperation enumerated blending types.

void Ogre::Material::TextureLayer::setColourOperationEx (  LayerBlendOperationEx    op,
LayerBlendSource    source1 = LBS_TEXTURE,
LayerBlendSource    source2 = LBS_CURRENT,
const ColourValue &    arg1 = ColourValue::White,
const ColourValue &    arg2 = ColourValue::White,
Real    manualBlend = 0.0
) 
 

Setting advanced blending options.

Remarks:
This is an extended version of the TextureLayer::setColourOperation 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 colour operations determine how the final colour of the surface appears when rendered. Texture units are used to combine colour values from various sources (ie. the diffuse colour of the surface from lighting calculations, combined with the colour 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 = LBX_MODULATE
  • source1 = LBS_TEXTURE
  • source2 = LBS_CURRENT
ie. each layer takes the colour results of the previous layer, and multiplies them with the new texture being applied. Bear in mind that colours 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 LBO_MODULATE_X2. See the LayerBlendOperation and LayerBlendSource enumerated types for full details.
Note:
Because of the limitations on some underlying APIs (Direct3D included) the LBS_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 colour calculation to come from a fixed value that you supply. Hence you only need to fill these in if you supply LBS_MANUAL to the corresponding source, or use the LBX_BLEND_MANUAL operation.

Warning:
Ogre 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 TextureLayer::setColourOpMultipassFallback to specify which effect you want to fall back on if sufficient hardware is not available.
Parameters:
If  you wish to avoid having to do this, use the simpler TextureLayer::setColourOperation method which allows less flexible blending options but sets up the multipass fallback automatically, since it only allows operations which have direct multipass equivalents.
op  The operation to be used, e.g. modulate (multiply), add, subtract
source1  The source of the first colour to the operation e.g. texture colour
source2  The source of the second colour to the operation e.g. current surface colour
arg1  Manually supplied colour value (only required if source1 = LBS_MANUAL)
arg2  Manually supplied colour value (only required if source2 = LBS_MANUAL)
manualBlend  Manually supplied 'blend' value - only required for operations which require manual blend e.g. LBX_BLEND_MANUAL

void Ogre::Material::TextureLayer::setColourOpMultipassFallback (  const SceneBlendFactor    sourceFactor,
const SceneBlendFactor    destFactor
) 
 

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

Remarks:
Because some effects exposed using TextureLayer::setColourOperationEx 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) TextureLayer::setColourOperation method you don't need to call this as the system sets up the fallback for you.

void Ogre::Material::TextureLayer::setCubicTextureName (  const String *const    names,
bool    forUVW = false
) 
 

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

Remarks:
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:

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.

  • 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.

    Parameters:
    name  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  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.

    • void Ogre::Material::TextureLayer::setCubicTextureName (  const String &    name,
    bool    forUVW = false
    ) 
     

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

    Remarks:
    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:

    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.

  • 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.

    Parameters:
    name  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  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.

    • void Ogre::Material::TextureLayer::setCurrentFrame (  int    frameNumber ) 
     

    Changes the active frame in an animated or multi-image texture.

    Remarks:
    An animated texture (or a cubic texture where the images are not combined for 3D use) is made up of a number of frames. This method sets the active frame.

    void Ogre::Material::TextureLayer::setDeferredLoad (  bool    defer ) 
     

    Mostly internal method to indicate a deferred load texture layer.

    void Ogre::Material::TextureLayer::setEnvironmentMap (  bool    enable,
    bool    planar = false
    ) 
     

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

    Remarks:
    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.

    Note:
    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.
    Parameters:
    enable  True to enable, false to disable
    planar  If set to true, instead of being based on normals the environment effect is based on vertex positions. This is good for planar surfaces.

    void Ogre::Material::TextureLayer::setRotateAnimation (  Real    speed ) 
     

    Sets up an animated texture rotation for this layer.

    Note:
    Useful for constant rotations (for varying rotations, see setTransformAnimation).
    Parameters:
    speed  The number of complete anticlockwise revolutions per second (use -ve for clockwise)

    void Ogre::Material::TextureLayer::setScrollAnimation (  Real    uSpeed,
    Real    vSpeed
    ) 
     

    Sets up an animated scroll for the texture layer.

    Note:
    Useful for creating constant scrolling effects on a texture layer (for varying scrolls, see setTransformAnimation).
    Parameters:
    uSpeed  The number of horizontal loops per second (+ve=moving right, -ve = moving left)
    vSpeed  The number of vertical loops per second (+ve=moving up, -ve= moving down)

    void Ogre::Material::TextureLayer::setTextureAddressingMode (  TextureAddressingMode    tam ) 
     

    Sets the texture addressing mode, i.e.

    what happens at uv values above 1.0.

    Note:
    The default is TAM_WRAP i.e. the texture repeats over values of 1.0.

    void Ogre::Material::TextureLayer::setTextureCoordSet (  int    set ) 
     

    Sets the index of the set of texture co-ords this layer uses.

    Note:
    Default is 0 for all layers. Only change this if you have provided multiple texture co-ords per vertex.

    void Ogre::Material::TextureLayer::setTextureName (  const String &    name ) 
     

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

    void Ogre::Material::TextureLayer::setTextureRotate (  Real    degrees ) 
     

    Sets the anticlockwise rotation factor applied to texture coordinates.

    Remarks:
    This sets a fixed rotation angle - if you wish to animate this, see the ControllerManager::createTextureRotater method.
    Parameters:
    degrees  The angle of rotation in degrees (anticlockwise).

    void Ogre::Material::TextureLayer::setTextureScale (  Real    uScale,
    Real    vScale
    ) 
     

    Sets the scaling factor applied to texture coordinates.

    Remarks:
    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).
    Parameters:
    uScale  The value by which the texture is to be scaled horizontally.
    vScale  The value by which the texture is to be scaled vertically.

    void Ogre::Material::TextureLayer::setTextureScroll (  Real    u,
    Real    v
    ) 
     

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

    Remarks:
    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
    Parameters:
    u  The amount the texture should be moved horizontally (u direction).
    v  The amount the texture should be moved vertically (v direction).
    See also:
    ControllerManager, Controller

    void Ogre::Material::TextureLayer::setTextureTransform (  const Matrix4 &    xform ) 
     

    Sets a matrix used to transform any texture coordinates on this layer.

    Remarks:
    Texture coordinates can be modified on a texture layer to create effects like scrolling textures. A texture transform can either be applied to a layer which takes the source coordinates from a fixed set in the geometry, or to one which generates them dynamically (e.g. environment mapping).

    It's obviously a bit impractical to create scrolling effects by calling this method manually since you would have to call it every framw with a slight alteration each time, which is tedious. Instead you can use the ControllerManager class to create a Controller object which will manage the effect over time for you. See the ControllerManager::createTextureScroller and it's sibling methods for details.
    In addition, if you want to set the individual texture transformations rather than concatenating them yourself, use setTextureScroll, setTextureScale and setTextureRotate.

    void Ogre::Material::TextureLayer::setTextureUScale (  Real    value ) 
     

    As setTextureScale, but sets only U value.

    void Ogre::Material::TextureLayer::setTextureUScroll (  Real    value ) 
     

    As setTextureScroll, but sets only U value.

    void Ogre::Material::TextureLayer::setTextureVScale (  Real    value ) 
     

    As setTextureScale, but sets only V value.

    void Ogre::Material::TextureLayer::setTextureVScroll (  Real    value ) 
     

    As setTextureScroll, but sets only V value.

    void Ogre::Material::TextureLayer::setTransformAnimation (  const TextureTransformType    ttype,
    const WaveformType    waveType,
    Real    base = 0,
    Real    frequency = 1,
    Real    phase = 0,
    Real    amplitude = 1
    ) 
     

    Sets up a general time-relative texture modification effect.

    Note:
    This can be called multiple times for different values of ttype, but only the latest effect applies if called multiple time for the same ttype.
    Parameters:
    ttype  The type of transform, either translate (scroll), scale (stretch) or rotate (spin)
    waveType  The shape of the wave, see WaveformType enum for details
    base  The base value for the function (range of output = {base, base + amplitude})
    frequency  The speed of the wave in cycles per second
    phase  The offset of the start of the wave, e.g. 0.5 to start half-way through the wave
    amplitude  Scales the output so that instead of lying within 0..1 it lies within 0..1*amplitude for exaggerated effects

    Friends And Related Function Documentation

    friend class RenderSystem [friend]
     

    Member Data Documentation

    LayerBlendModeEx Ogre::Material::TextureLayer::alphaBlendMode [protected]
     

    SceneBlendFactor Ogre::Material::TextureLayer::colourBlendFallbackDest [protected]
     

    SceneBlendFactor Ogre::Material::TextureLayer::colourBlendFallbackSrc [protected]
     

    LayerBlendModeEx Ogre::Material::TextureLayer::colourBlendMode [protected]
     

    TextureAddressingMode Ogre::Material::TextureLayer::mAddressMode [protected]
     

    CompareFunction Ogre::Material::TextureLayer::mAlphaRejectFunc [protected]
     

    unsigned char Ogre::Material::TextureLayer::mAlphaRejectVal [protected]
     

    Controller* Ogre::Material::TextureLayer::mAnimController [protected]
     

    Real Ogre::Material::TextureLayer::mAnimDuration [protected]
     

    Duration of animation in seconds.

    bool Ogre::Material::TextureLayer::mCubic [protected]
     

    int Ogre::Material::TextureLayer::mCurrentFrame [protected]
     

    The xurrent animation frame.

    bool Ogre::Material::TextureLayer::mDeferLoad [protected]
     

    EffectMap Ogre::Material::TextureLayer::mEffects [protected]
     

    String Ogre::Material::TextureLayer::mFrames[MAX_FRAMES] [protected]
     

    bool Ogre::Material::TextureLayer::mIsBlank [protected]
     

    int Ogre::Material::TextureLayer::mNumFrames [protected]
     

    Number of frames of animation, or frames making up cubic.

    bool Ogre::Material::TextureLayer::mRecalcTexMatrix [protected]
     

    Real Ogre::Material::TextureLayer::mRotate [protected]
     

    Real Ogre::Material::TextureLayer::mRotateAnim [protected]
     

    Matrix4 Ogre::Material::TextureLayer::mTexModMatrix [protected]
     

    Real Ogre::Material::TextureLayer::mUMod [protected]
     

    Real Ogre::Material::TextureLayer::mUScale [protected]
     

    Real Ogre::Material::TextureLayer::mUScrollAnim [protected]
     

    Real Ogre::Material::TextureLayer::mVMod [protected]
     

    Real Ogre::Material::TextureLayer::mVScale [protected]
     

    Real Ogre::Material::TextureLayer::mVScrollAnim [protected]
     

    int Ogre::Material::TextureLayer::textureCoordSetIndex [protected]
     

    Copyright © 2002 by The OGRE Team