OGRE  2.3
Object-Oriented Graphics Rendering Engine
Ogre::TextureUnitState Class Reference

Class representing the state of a single texture unit during a Pass of a Technique, of a Material. More...

#include <OgreTextureUnitState.h>

+ Inheritance diagram for Ogre::TextureUnitState:

Classes

struct  TextureEffect
 Internal structure defining a texture effect. More...
 

Public Types

enum  BindingType {
  BT_FRAGMENT = 0 , BT_VERTEX = 1 , BT_GEOMETRY = 2 , BT_TESSELLATION_HULL = 3 ,
  BT_TESSELLATION_DOMAIN = 4
}
 The type of unit to bind the texture settings to. More...
 
enum  ContentType { CONTENT_NAMED = 0 , CONTENT_SHADOW = 1 , CONTENT_COMPOSITOR = 2 }
 Enum identifying the type of content this texture unit contains. More...
 
typedef multimap< TextureEffectType, TextureEffect >::type EffectMap
 Texture effects in a multimap paired array. More...
 
enum  EnvMapType { ENV_PLANAR , ENV_CURVED , ENV_REFLECTION , ENV_NORMAL }
 Enumeration to specify type of envmap. More...
 
enum  Reason {
  Unknown , FromStorageToSysRam , FromSysRamToStorage , GainedResidency ,
  LostResidency , PoolTextureSlotChanged , ResidentToSysRamSync , MetadataCacheOutOfDate ,
  ExceptionThrown , FsaaSettingAlteredByApi , ReadyForRendering , Deleted
}
 
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...
 
enum  TextureEffectType {
  ET_ENVIRONMENT_MAP , ET_PROJECTIVE_TEXTURE , ET_UVSCROLL , ET_USCROLL ,
  ET_VSCROLL , ET_ROTATE , ET_TRANSFORM
}
 Definition of the broad types of texture effect you can apply to a texture unit. 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...
 

Public Member Functions

 TextureUnitState (Pass *parent)
 Default constructor. More...
 
 TextureUnitState (Pass *parent, const String &texName, unsigned int texCoordSet=0)
 Name-based constructor. More...
 
 TextureUnitState (Pass *parent, const TextureUnitState &oth)
 
 ~TextureUnitState ()
 Default destructor. More...
 
Controller< Real > * _getAnimController () const
 Gets the animation controller (as created because of setAnimatedTexture) if it exists. More...
 
TextureGpu_getTexturePtr (size_t frame) const
 Get the texture pointer for a given frame. More...
 
TextureGpu_getTexturePtr (void) const
 Get the texture pointer for the current frame. More...
 
void _load (void)
 Internal method for loading this object as part of Material::load. More...
 
void _notifyParent (Pass *parent)
 Notify this object that its parent has changed. More...
 
void _prepare (void)
 Internal method for preparing this object for load, as part of Material::prepare. More...
 
void _setSamplerblock (const HlmsSamplerblock *samplerblock)
 Changes the current samplerblock for a new one. More...
 
void _setTexturePtr (TextureGpu *texptr)
 Set the texture pointer for the current frame (internal use only!). More...
 
void _setTexturePtr (TextureGpu *texptr, size_t frame)
 Set the texture pointer for a given frame (internal use only!). More...
 
void _unload (void)
 Internal method for unloading this object as part of Material::unload. More...
 
void _unprepare (void)
 Internal method for undoing the preparation this object as part of Material::unprepare. More...
 
void addEffect (TextureEffect &effect)
 Generic method for setting up texture effects. More...
 
void addFrameTextureName (const String &name)
 Add a Texture name to the end of the frame container. More...
 
bool applyTextureAliases (const AliasTextureNamePairList &aliasList, const bool apply=true)
 Applies texture names to Texture Unit State with matching texture name aliases. More...
 
size_t calculateSize (void) const
 
void deleteFrameTextureName (const size_t frameNumber)
 Deletes a specific texture frame. More...
 
const LayerBlendModeExgetAlphaBlendMode (void) const
 Get multitexturing alpha blending mode. More...
 
Real getAnimationDuration (void) const
 Get the animated-texture animation duration. More...
 
bool getAutomaticBatching (void) const
 
BindingType getBindingType (void) const
 Gets the type of unit these texture settings should be bound to. More...
 
SceneBlendFactor getColourBlendFallbackDest (void) const
 Get the multipass fallback for colour blending operation destination factor. More...
 
SceneBlendFactor getColourBlendFallbackSrc (void) const
 Get the multipass fallback for colour blending operation source factor. More...
 
const LayerBlendModeExgetColourBlendMode (void) const
 Get multitexturing colour blending mode. More...
 
ContentType getContentType (void) const
 Get the type of content this TextureUnitState references. More...
 
unsigned int getCurrentFrame (void) const
 Gets the active frame in an animated or multi-image texture layer. More...
 
const EffectMapgetEffects (void) const
 Get texture effects in a multimap paired array. More...
 
const StringgetFrameTextureName (unsigned int frameNumber) const
 Gets the name of the texture associated with a frame number. More...
 
Real getGamma () const
 Returns the gamma adjustment factor applied to this texture on loading. More...
 
bool getIsAlpha (void) const
 Gets whether this texture is requested to be loaded as alpha if single channel. More...
 
const StringgetName (void) const
 Get the name of the Texture Unit State. More...
 
unsigned int getNumFrames (void) const
 Gets the number of frames for a texture. More...
 
int getNumMipmaps (void) const
 Gets how many mipmaps have been requested for the texture. More...
 
PassgetParent (void) const
 Gets the parent Pass object. More...
 
IdString getReferencedTextureName () const
 Gets the name of the texture in the compositor that this texture references. More...
 
const HlmsSamplerblockgetSamplerblock (void) const
 Retrieves current samplerblock. More...
 
unsigned int getTextureCoordSet (void) const
 Gets the index of the set of texture co-ords this layer uses. More...
 
std::pair< size_t, size_t > getTextureDimensions (unsigned int frame=0) const
 Returns the width and height of the texture in the given frame. More...
 
const StringgetTextureName (void) const
 Get the name of current texture image for this layer. More...
 
const StringgetTextureNameAlias (void) const
 Gets the Texture Name Alias of the Texture Unit. More...
 
const RadiangetTextureRotate (void) const
 Get texture rotation effects angle value. More...
 
const Matrix4getTextureTransform (void) const
 Gets the current texture transformation matrix. More...
 
TextureTypes::TextureTypes getTextureType (void) const
 Returns the type of this texture. More...
 
Real getTextureUScale (void) const
 Get texture uscale value. More...
 
Real getTextureUScroll (void) const
 Get texture uscroll value. More...
 
Real getTextureVScale (void) const
 Get texture vscale value. More...
 
Real getTextureVScroll (void) const
 Get texture vscroll value. More...
 
bool hasViewRelativeTextureCoordinateGeneration (void) const
 Returns whether this unit has texture coordinate generation that depends on the camera. More...
 
bool is3D (void) const
 Returns true if this texture layer uses a composite 3D cubic texture. More...
 
bool isBlank (void) const
 Determines if this texture layer is currently blank. More...
 
bool isCubic (void) const
 Returns true if this texture unit is either a series of 6 2D textures, each in it's own frame, or is a full 3D cube map. More...
 
bool isHardwareGammaEnabled () const
 Gets whether this texture will be set up so that on sampling it, hardware gamma correction is applied. More...
 
bool isLoaded (void) const
 Is this loaded? More...
 
bool isTextureLoadFailing () const
 Tests if the texture associated with this unit has failed to load. More...
 
void operator delete (void *ptr)
 
void operator delete (void *ptr, const char *, int, const char *)
 
void operator delete (void *ptr, void *)
 
void operator delete[] (void *ptr)
 
void operator delete[] (void *ptr, const char *, int, const char *)
 
void * operator new (size_t sz)
 
void * operator new (size_t sz, const char *file, int line, const char *func)
 operator new, with debug line info More...
 
void * operator new (size_t sz, void *ptr)
 placement operator new More...
 
void * operator new[] (size_t sz)
 
void * operator new[] (size_t sz, const char *file, int line, const char *func)
 array operator new, with debug line info More...
 
TextureUnitStateoperator= (const TextureUnitState &oth)
 
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...
 
void retryTextureLoad ()
 Tells the unit to retry loading the texture if it had failed to load. 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 setAnimatedTextureName (const String &name, unsigned int numFrames, Real duration=0)
 Sets the names of the texture images for an animated texture. More...
 
void setAnimatedTextureName (const String *const names, unsigned int numFrames, Real duration=0)
 Sets the names of the texture images for an animated texture. More...
 
void setAutomaticBatching (bool automaticBatching)
 When a texture is used by both PBS datablocks and V1 materials it can lead to a few issues: More...
 
void setBindingType (BindingType bt)
 Sets the type of unit these texture settings should be bound to. More...
 
void setBlank (void)
 Sets this texture layer to be blank. 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 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 setColourOpMultipassFallback (const SceneBlendFactor sourceFactor, const SceneBlendFactor destFactor)
 Sets the multipass fallback operation for this layer, if you used TextureUnitState::setColourOperationEx and not enough multitexturing hardware is available. More...
 
void setCompositorReference (const String &textureName)
 Set the compositor reference for this texture unit state. More...
 
void setContentType (ContentType ct)
 Set the type of content this TextureUnitState references. More...
 
void setCubicTexture (TextureGpu *const *texPtrs, 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 &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 setCurrentFrame (unsigned int frameNumber)
 Changes the active frame in an animated or multi-image texture. More...
 
void setEnvironmentMap (bool enable, EnvMapType envMapType=ENV_CURVED)
 Turns on/off texture coordinate effect that makes this layer an environment map. More...
 
void setFrameTextureName (const String &name, unsigned int frameNumber)
 Sets the name of the texture associated with a frame. More...
 
void setGamma (Real gamma)
 Sets the gamma adjustment factor applied to this texture on loading the data. More...
 
void setHardwareGammaEnabled (bool enabled)
 Sets whether this texture will be set up so that on sampling it, hardware gamma correction is applied. More...
 
void setIsAlpha (bool isAlpha)
 Sets whether this texture is requested to be loaded as alpha if single channel. More...
 
void setName (const String &name)
 Set the name of the Texture Unit State. More...
 
void setNumMipmaps (int numMipmaps)
 Sets how many mipmaps have been requested for the texture. More...
 
void setProjectiveTexturing (bool enabled, const Frustum *projectionSettings=0)
 Enables or disables projective texturing on this texture unit. More...
 
void setRotateAnimation (Real speed)
 Sets up an animated texture rotation for this layer. More...
 
void setSamplerblock (const HlmsSamplerblock &samplerblock)
 Changes the current samplerblock for a new one. More...
 
void setScrollAnimation (Real uSpeed, Real vSpeed)
 Sets up an animated scroll for the texture layer. More...
 
void setTexture (TextureGpu *texPtr)
 Sets this texture layer to use a single texture, given the pointer to the texture to use on this layer. More...
 
void setTextureCoordSet (unsigned int set)
 Sets the index of the set of texture co-ords this layer uses. More...
 
void setTextureName (const String &name, TextureTypes::TextureTypes ttype=TextureTypes::Type2D)
 Sets this texture layer to use a single texture, given the name of the texture to use on this layer. More...
 
void setTextureNameAlias (const String &name)
 Set the alias name used for texture frame names. More...
 
void setTextureRotate (const Radian &angle)
 Sets the anticlockwise rotation factor applied to texture coordinates. More...
 
void setTextureScale (Real uScale, Real vScale)
 Sets the scaling factor applied to texture coordinates. More...
 
void setTextureScroll (Real u, Real v)
 Sets the translation offset of the texture, ie scrolls the texture. More...
 
void setTextureTransform (const Matrix4 &xform)
 Sets a matrix used to transform any texture coordinates on this layer. More...
 
void setTextureUScale (Real value)
 As setTextureScale, but sets only U value. More...
 
void setTextureUScroll (Real value)
 As setTextureScroll, but sets only U value. More...
 
void setTextureVScale (Real value)
 As setTextureScale, but sets only V value. More...
 
void setTextureVScroll (Real value)
 As setTextureScroll, but sets only V value. 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...
 
virtual bool shouldStayLoaded (TextureGpu *texture)
 Return true if this TextureGpu should likely stay loaded or else graphical changes could occur. More...
 

Friends

class RenderSystem
 

Detailed Description

Class representing the state of a single texture unit during a Pass of a Technique, of a Material.

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

Member Typedef Documentation

◆ EffectMap

Texture effects in a multimap paired array.

Member Enumeration Documentation

◆ BindingType

The type of unit to bind the texture settings to.

Enumerator
BT_FRAGMENT 

Regular fragment processing unit - the default.

BT_VERTEX 

Vertex processing unit - indicates this unit will be used for a vertex texture fetch.

BT_GEOMETRY 

Geometry processing unit

BT_TESSELLATION_HULL 

Tessellation control processing unit.

BT_TESSELLATION_DOMAIN 

Tessellation evaluation processing unit.

◆ ContentType

Enum identifying the type of content this texture unit contains.

Enumerator
CONTENT_NAMED 

Normal texture identified by name.

CONTENT_SHADOW 

A shadow texture, automatically bound by engine.

CONTENT_COMPOSITOR 

A compositor texture, automatically linked to active viewport's chain.

◆ EnvMapType

Enumeration to specify type of envmap.

Note
Note that these have no effect when using the programmable pipeline, since their effect is overridden by the vertex / fragment programs.
Enumerator
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.

ENV_REFLECTION 

Envmap intended to supply reflection vectors for cube mapping.

ENV_NORMAL 

Envmap intended to supply normal vectors for cube mapping.

◆ Reason

Enumerator
Unknown 
FromStorageToSysRam 

OnStorage -> OnSystemRam.

FromSysRamToStorage 

OnSystemRam -> OnStorage.

GainedResidency 

OnStorage -> Resident OnSystemRam -> Resident See ReadyForRendering.

LostResidency 

Resident -> OnStorage Resident -> OnSystemRam.

PoolTextureSlotChanged 
ResidentToSysRamSync 

Only called while TextureGpu is still Resident, and strategy is AlwaysKeepSystemRamCopy.

This listener happens when something was done to the TextureGpu that modifies its contents in the GPU, and were thus forced to sync those values back to SystemRam. This listener calls tells that sync is over.

MetadataCacheOutOfDate 

The Metadata cache was out of date and we had to do a ping-pong.

Expect this to be followed by at least LostResidency and GainedResidency calls

This is very important, because if you were expecting certain sequence of calls (e.g. you were expecting a LostResidency soon to arrive), expect that to be changed.

See TextureGpuManager for details about the metadata cache.

ExceptionThrown 

Called when the worker thread caught an exception.

This exception has already been logged, and the texture resumed loading normally with a white 2x2 RGBA8 fallback.

This listener will get called from the main thread.

The texture may still have pending residency transitions (e.g. it may still be loading the 2x2 fallback)

Cast Exception e = reinterpret_cast<Exception>( extraData ); to know more info

FsaaSettingAlteredByApi 

Requested FSAA (MSAA / CSAA / EQAA / etc) is not supported by the API, and thus the setting had to be downgraded.

Note this may happen on device lost, and a new GPU became in use; thus it's possible for a TextureGpu to initially support certain FSAA but later change.

ReadyForRendering 

This Reason is called when TextureGpu::notifyDataIsReady is called.

This normally means worker thread is done loading texture from file and uploading it to GPU; and can now be used for rendering. It does NOT mean that Ogre has finished issueing rendering commands to a RenderTexture and is now ready to be presented to the monitor.

Deleted 

◆ TextureCubeFace

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

Enumerator
CUBE_FRONT 
CUBE_BACK 
CUBE_LEFT 
CUBE_RIGHT 
CUBE_UP 
CUBE_DOWN 

◆ TextureEffectType

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

Note
Note that these have no effect when using the programmable pipeline, since their effect is overridden by the vertex / fragment programs.
Enumerator
ET_ENVIRONMENT_MAP 

Generate all texture coords based on angle between camera and vertex.

ET_PROJECTIVE_TEXTURE 

Generate texture coords based on a frustum.

ET_UVSCROLL 

Constant u/v scrolling effect.

ET_USCROLL 

Constant u scrolling effect.

ET_VSCROLL 

Constant u/v scrolling effect.

ET_ROTATE 

Constant rotation.

ET_TRANSFORM 

More complex transform.

◆ TextureTransformType

Useful enumeration when dealing with procedural transforms.

Note
Note that these have no effect when using the programmable pipeline, since their effect is overridden by the vertex / fragment programs.
Enumerator
TT_TRANSLATE_U 
TT_TRANSLATE_V 
TT_SCALE_U 
TT_SCALE_V 
TT_ROTATE 

Constructor & Destructor Documentation

◆ TextureUnitState() [1/3]

Ogre::TextureUnitState::TextureUnitState ( Pass parent)

Default constructor.

◆ TextureUnitState() [2/3]

Ogre::TextureUnitState::TextureUnitState ( Pass parent,
const TextureUnitState oth 
)

◆ ~TextureUnitState()

Ogre::TextureUnitState::~TextureUnitState ( )

Default destructor.

◆ TextureUnitState() [3/3]

Ogre::TextureUnitState::TextureUnitState ( Pass parent,
const String texName,
unsigned int  texCoordSet = 0 
)

Name-based constructor.

Parameters
texNameThe basic name of the texture e.g. brickwall.jpg, stonefloor.png.
texCoordSetThe index of the texture coordinate set to use.

Member Function Documentation

◆ _getAnimController()

Controller<Real>* Ogre::TextureUnitState::_getAnimController ( ) const
inline

Gets the animation controller (as created because of setAnimatedTexture) if it exists.

◆ _getTexturePtr() [1/2]

TextureGpu* Ogre::TextureUnitState::_getTexturePtr ( size_t  frame) const

Get the texture pointer for a given frame.

◆ _getTexturePtr() [2/2]

TextureGpu* Ogre::TextureUnitState::_getTexturePtr ( void  ) const

Get the texture pointer for the current frame.

◆ _load()

void Ogre::TextureUnitState::_load ( void  )

Internal method for loading this object as part of Material::load.

◆ _notifyParent()

void Ogre::TextureUnitState::_notifyParent ( Pass parent)

Notify this object that its parent has changed.

◆ _prepare()

void Ogre::TextureUnitState::_prepare ( void  )

Internal method for preparing this object for load, as part of Material::prepare.

◆ _setSamplerblock()

void Ogre::TextureUnitState::_setSamplerblock ( const HlmsSamplerblock samplerblock)

Changes the current samplerblock for a new one.

MUST'VE BEEN CREATED VIA HlmsManager!!! INCREASES THE REFERENCE COUNT OF THE SAMPLERBLOCK

◆ _setTexturePtr() [1/2]

void Ogre::TextureUnitState::_setTexturePtr ( TextureGpu texptr)

Set the texture pointer for the current frame (internal use only!).

◆ _setTexturePtr() [2/2]

void Ogre::TextureUnitState::_setTexturePtr ( TextureGpu texptr,
size_t  frame 
)

Set the texture pointer for a given frame (internal use only!).

◆ _unload()

void Ogre::TextureUnitState::_unload ( void  )

Internal method for unloading this object as part of Material::unload.

◆ _unprepare()

void Ogre::TextureUnitState::_unprepare ( void  )

Internal method for undoing the preparation this object as part of Material::unprepare.

◆ addEffect()

void Ogre::TextureUnitState::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.
Note
This option has no effect in the programmable pipeline.

◆ addFrameTextureName()

void Ogre::TextureUnitState::addFrameTextureName ( const String name)

Add a Texture name to the end of the frame container.

Parameters
nameThe name of the texture.
Note
Applies to both fixed-function and programmable pipeline.

◆ applyTextureAliases()

bool Ogre::TextureUnitState::applyTextureAliases ( const AliasTextureNamePairList aliasList,
const bool  apply = true 
)

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.

Remarks
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.
Parameters
aliasListA map container of texture alias, texture name pairs.
applySet true to apply the texture aliases else just test to see if texture alias matches are found.
Returns
True if matching texture aliases were found in the Texture Unit State.

◆ calculateSize()

size_t Ogre::TextureUnitState::calculateSize ( void  ) const

◆ deleteFrameTextureName()

void Ogre::TextureUnitState::deleteFrameTextureName ( const size_t  frameNumber)

Deletes a specific texture frame.

The texture used is not deleted but the texture will no longer be used by the Texture Unit. An exception is raised if the frame number exceeds the number of actual frames.

Parameters
frameNumberThe frame number of the texture to be deleted.
Note
Applies to both fixed-function and programmable pipeline.

◆ getAlphaBlendMode()

const LayerBlendModeEx& Ogre::TextureUnitState::getAlphaBlendMode ( void  ) const

Get multitexturing alpha blending mode.

◆ getAnimationDuration()

Real Ogre::TextureUnitState::getAnimationDuration ( void  ) const

Get the animated-texture animation duration.

◆ getAutomaticBatching()

bool Ogre::TextureUnitState::getAutomaticBatching ( void  ) const

◆ getBindingType()

BindingType Ogre::TextureUnitState::getBindingType ( void  ) const

Gets the type of unit these texture settings should be bound to.


◆ getColourBlendFallbackDest()

SceneBlendFactor Ogre::TextureUnitState::getColourBlendFallbackDest ( void  ) const

Get the multipass fallback for colour blending operation destination factor.

◆ getColourBlendFallbackSrc()

SceneBlendFactor Ogre::TextureUnitState::getColourBlendFallbackSrc ( void  ) const

Get the multipass fallback for colour blending operation source factor.

◆ getColourBlendMode()

const LayerBlendModeEx& Ogre::TextureUnitState::getColourBlendMode ( void  ) const

Get multitexturing colour blending mode.

◆ getContentType()

ContentType Ogre::TextureUnitState::getContentType ( void  ) const

Get the type of content this TextureUnitState references.

◆ getCurrentFrame()

unsigned int Ogre::TextureUnitState::getCurrentFrame ( void  ) const

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

Note
Applies to both fixed-function and programmable pipeline.

◆ getEffects()

const EffectMap& Ogre::TextureUnitState::getEffects ( void  ) const

Get texture effects in a multimap paired array.

◆ getFrameTextureName()

const String& Ogre::TextureUnitState::getFrameTextureName ( unsigned int  frameNumber) const

Gets the name of the texture associated with a frame number.

Throws an exception if frameNumber exceeds the number of stored frames.

Note
Applies to both fixed-function and programmable pipeline.

◆ getGamma()

Real Ogre::TextureUnitState::getGamma ( ) const
inline

Returns the gamma adjustment factor applied to this texture on loading.

◆ getIsAlpha()

bool Ogre::TextureUnitState::getIsAlpha ( void  ) const

Gets whether this texture is requested to be loaded as alpha if single channel.

◆ getName()

const String& Ogre::TextureUnitState::getName ( void  ) const
inline

Get the name of the Texture Unit State.

◆ getNumFrames()

unsigned int Ogre::TextureUnitState::getNumFrames ( void  ) const

Gets the number of frames for a texture.

Note
Applies to both fixed-function and programmable pipeline.

◆ getNumMipmaps()

int Ogre::TextureUnitState::getNumMipmaps ( void  ) const

Gets how many mipmaps have been requested for the texture.

◆ getParent()

Pass* Ogre::TextureUnitState::getParent ( void  ) const
inline

Gets the parent Pass object.

◆ getReferencedTextureName()

IdString Ogre::TextureUnitState::getReferencedTextureName ( ) const
inline

Gets the name of the texture in the compositor that this texture references.

◆ getSamplerblock()

const HlmsSamplerblock* Ogre::TextureUnitState::getSamplerblock ( void  ) const

Retrieves current samplerblock.

Don't const_cast the return value to modify it. @See HlmsDatablock remarks.

◆ getTextureCoordSet()

unsigned int Ogre::TextureUnitState::getTextureCoordSet ( void  ) const

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

Note
Only applies to the fixed function pipeline and has no effect if a fragment program is used.

◆ getTextureDimensions()

std::pair< size_t, size_t > Ogre::TextureUnitState::getTextureDimensions ( unsigned int  frame = 0) const

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

◆ getTextureName()

const String& Ogre::TextureUnitState::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.
Note
Applies to both fixed-function and programmable pipeline.

◆ getTextureNameAlias()

const String& Ogre::TextureUnitState::getTextureNameAlias ( void  ) const
inline

Gets the Texture Name Alias of the Texture Unit.

◆ getTextureRotate()

const Radian& Ogre::TextureUnitState::getTextureRotate ( void  ) const

Get texture rotation effects angle value.

◆ getTextureTransform()

const Matrix4& Ogre::TextureUnitState::getTextureTransform ( void  ) const

Gets the current texture transformation matrix.

Remarks
Causes a reclaculation of the matrix if any parameters have been changed via setTextureScroll, setTextureScale and setTextureRotate.
Note
Has no effect in the programmable pipeline.

◆ getTextureType()

TextureTypes::TextureTypes Ogre::TextureUnitState::getTextureType ( void  ) const

Returns the type of this texture.

Note
Applies to both fixed-function and programmable pipeline.

◆ getTextureUScale()

Real Ogre::TextureUnitState::getTextureUScale ( void  ) const

Get texture uscale value.

◆ getTextureUScroll()

Real Ogre::TextureUnitState::getTextureUScroll ( void  ) const

Get texture uscroll value.

◆ getTextureVScale()

Real Ogre::TextureUnitState::getTextureVScale ( void  ) const

Get texture vscale value.

◆ getTextureVScroll()

Real Ogre::TextureUnitState::getTextureVScroll ( void  ) const

Get texture vscroll value.

◆ hasViewRelativeTextureCoordinateGeneration()

bool Ogre::TextureUnitState::hasViewRelativeTextureCoordinateGeneration ( void  ) const

Returns whether this unit has texture coordinate generation that depends on the camera.

◆ is3D()

bool Ogre::TextureUnitState::is3D ( void  ) const

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

Note
Applies to both fixed-function and programmable pipeline.

◆ isBlank()

bool Ogre::TextureUnitState::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.

◆ isCubic()

bool Ogre::TextureUnitState::isCubic ( void  ) const

Returns true if this texture unit is either a series of 6 2D textures, each in it's own frame, or is a full 3D cube map.

You can tell which by checking getTextureType.

Note
Applies to both fixed-function and programmable pipeline.

◆ isHardwareGammaEnabled()

bool Ogre::TextureUnitState::isHardwareGammaEnabled ( ) const

Gets whether this texture will be set up so that on sampling it, hardware gamma correction is applied.

◆ isLoaded()

bool Ogre::TextureUnitState::isLoaded ( void  ) const

Is this loaded?

◆ isTextureLoadFailing()

bool Ogre::TextureUnitState::isTextureLoadFailing ( ) const
inline

Tests if the texture associated with this unit has failed to load.

◆ operator delete() [1/3]

template<class Alloc >
void Ogre::AllocatedObject< Alloc >::operator delete ( void *  ptr)
inlineinherited

◆ operator delete() [2/3]

template<class Alloc >
void Ogre::AllocatedObject< Alloc >::operator delete ( void *  ptr,
const char *  ,
int  ,
const char *   
)
inlineinherited

◆ operator delete() [3/3]

template<class Alloc >
void Ogre::AllocatedObject< Alloc >::operator delete ( void *  ptr,
void *   
)
inlineinherited

◆ operator delete[]() [1/2]

template<class Alloc >
void Ogre::AllocatedObject< Alloc >::operator delete[] ( void *  ptr)
inlineinherited

◆ operator delete[]() [2/2]

template<class Alloc >
void Ogre::AllocatedObject< Alloc >::operator delete[] ( void *  ptr,
const char *  ,
int  ,
const char *   
)
inlineinherited

◆ operator new() [1/3]

template<class Alloc >
void* Ogre::AllocatedObject< Alloc >::operator new ( size_t  sz)
inlineinherited

◆ operator new() [2/3]

template<class Alloc >
void* Ogre::AllocatedObject< Alloc >::operator new ( size_t  sz,
const char *  file,
int  line,
const char *  func 
)
inlineinherited

operator new, with debug line info

◆ operator new() [3/3]

template<class Alloc >
void* Ogre::AllocatedObject< Alloc >::operator new ( size_t  sz,
void *  ptr 
)
inlineinherited

placement operator new

◆ operator new[]() [1/2]

template<class Alloc >
void* Ogre::AllocatedObject< Alloc >::operator new[] ( size_t  sz)
inlineinherited

◆ operator new[]() [2/2]

template<class Alloc >
void* Ogre::AllocatedObject< Alloc >::operator new[] ( size_t  sz,
const char *  file,
int  line,
const char *  func 
)
inlineinherited

array operator new, with debug line info

◆ operator=()

TextureUnitState& Ogre::TextureUnitState::operator= ( const TextureUnitState oth)

◆ removeAllEffects()

void Ogre::TextureUnitState::removeAllEffects ( void  )

Removes all effects applied to this texture layer.

◆ removeEffect()

void Ogre::TextureUnitState::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.

◆ retryTextureLoad()

void Ogre::TextureUnitState::retryTextureLoad ( )
inline

Tells the unit to retry loading the texture if it had failed to load.

◆ setAlphaOperation()

void Ogre::TextureUnitState::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, whereas it is fully transparent if the alpha is 0.0. Please refer to the setColourOperation method for more info.
Parameters
opThe operation to be used, e.g. modulate (multiply), add, subtract
source1The source of the first alpha value to the operation e.g. texture alpha
source2The source of the second alpha value to the operation e.g. current surface alpha
arg1Manually supplied alpha value (only required if source1 = LBS_MANUAL)
arg2Manually supplied alpha value (only required if source2 = LBS_MANUAL)
manualBlendManually supplied 'blend' value - only required for operations which require manual blend e.g. LBX_BLEND_MANUAL
See also
setColourOperation
Note
This option has no effect in the programmable pipeline.

◆ setAnimatedTextureName() [1/2]

void Ogre::TextureUnitState::setAnimatedTextureName ( const String name,
unsigned 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_0.jpg", "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 laid out here, you can call the alternative setAnimatedTextureName method which takes an array of names instead.
Applies to both fixed-function and programmable pipeline.
Parameters
nameThe base name of the textures to use e.g. wall.jpg for frames wall_0.jpg, wall_1.jpg etc.
numFramesThe number of frames in the sequence.
durationThe length of time it takes to display the whole animation sequence, in seconds. If 0, no automatic transition occurs.

◆ setAnimatedTextureName() [2/2]

void Ogre::TextureUnitState::setAnimatedTextureName ( const String *const  names,
unsigned 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.
Applies to both fixed-function and programmable pipeline.
Parameters
namesPointer to array of names of the textures to use, in frame order.
numFramesThe number of frames in the sequence.
durationThe length of time it takes to display the whole animation sequence, in seconds. If 0, no automatic transition occurs.

◆ setAutomaticBatching()

void Ogre::TextureUnitState::setAutomaticBatching ( bool  automaticBatching)

When a texture is used by both PBS datablocks and V1 materials it can lead to a few issues:

  1. V1 materials will often expect a Type2D texture to actually be Type2D.
  2. PBS datablocks will use TextureFlags::AutomaticBatching to group several textures of same resolution and format into the same Type2DArray, and thus lower CPU overhead. This means the 2D texture is not actually Type2D, but rather Type2DArray, and the slice information is also required.
    The default is to disable this option, which means the texture may be loaded twice: one for V1 materials, and another for PBS. If you do not want this, call setAutomaticBatching( true ); before loading the texture. Note that you will have to provide the slice index by hand and make sure the shader you wrote understands this is a 2D Array texture.
    Parameters
    automaticBatching

◆ setBindingType()

void Ogre::TextureUnitState::setBindingType ( BindingType  bt)

Sets the type of unit these texture settings should be bound to.

Remarks
Some render systems, when implementing vertex texture fetch, separate the binding of textures for use in the vertex program versus those used in fragment programs. This setting allows you to target the vertex processing unit with a texture binding, in those cases. For rendersystems which have a unified binding for the vertex and fragment units, this setting makes no difference.

◆ setBlank()

void Ogre::TextureUnitState::setBlank ( void  )

Sets this texture layer to be blank.

◆ setColourOperation()

void Ogre::TextureUnitState::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 TextureUnitState::setColourOperationEx, but you'll either have to be sure that enough multitexturing units will be available, or you should explicitly set a fallback using TextureUnitState::setColourOpMultipassFallback.
Note
The default method is LBO_MODULATE for all layers.
This option has no effect in the programmable pipeline.
Parameters
opOne of the LayerBlendOperation enumerated blending types.

◆ setColourOperationEx()

void Ogre::TextureUnitState::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 TextureUnitState::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 TextureUnitState::setColourOpMultipassFallback to specify which effect you want to fall back on if sufficient hardware is not available.
Note
This has no effect in the programmable pipeline.
If you wish to avoid having to do this, use the simpler TextureUnitState::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.
Parameters
opThe operation to be used, e.g. modulate (multiply), add, subtract.
source1The source of the first colour to the operation e.g. texture colour.
source2The source of the second colour to the operation e.g. current surface colour.
arg1Manually supplied colour value (only required if source1 = LBS_MANUAL).
arg2Manually supplied colour value (only required if source2 = LBS_MANUAL).
manualBlendManually supplied 'blend' value - only required for operations which require manual blend e.g. LBX_BLEND_MANUAL.

◆ setColourOpMultipassFallback()

void Ogre::TextureUnitState::setColourOpMultipassFallback ( const SceneBlendFactor  sourceFactor,
const SceneBlendFactor  destFactor 
)

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

Remarks
Because some effects exposed using TextureUnitState::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) TextureUnitState::setColourOperation method you don't need to call this as the system sets up the fallback for you.
Note
This option has no effect in the programmable pipeline, because there is no multipass fallback and multitexture blending is handled by the fragment shader.

◆ setCompositorReference()

void Ogre::TextureUnitState::setCompositorReference ( const String textureName)

Set the compositor reference for this texture unit state.

Remarks
Only valid when content type is compositor.
Parameters
textureNameThe name of the texture to reference.

◆ setContentType()

void Ogre::TextureUnitState::setContentType ( ContentType  ct)

Set the type of content this TextureUnitState references.

Remarks
The default is to reference a standard named texture, but this unit can also reference automated content like a shadow texture.

◆ setCubicTexture()

void Ogre::TextureUnitState::setCubicTexture ( TextureGpu *const *  texPtrs,
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 orthogonal 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.

Note
Applies to both fixed-function and programmable pipeline.
Parameters
texPtrsThe 6 pointers to the textures 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. Must be an Ogre::TextureGpu array with a length of 6 unless forUVW is set to true.
forUVWSet to true if you want a single 3D texture addressable with 3D texture coordinates rather than 6 separate textures. Useful for cubic environment mapping.

◆ setCubicTextureName() [1/2]

void Ogre::TextureUnitState::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 orthogonal 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.

Note
Applies to both fixed-function and programmable pipeline.
Parameters
nameThe 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.
forUVWSet to true if you want a single 3D texture addressable with 3D texture coordinates rather than 6 separate textures. Useful for cubic environment mapping.

◆ setCubicTextureName() [2/2]

void Ogre::TextureUnitState::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 orthogonal 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.

Note
Applies to both fixed-function and programmable pipeline.
Parameters
namesThe 6 names of the textures 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. Must be an Ogre::String array with a length of 6 unless forUVW is set to true.
forUVWSet to true if you want a single 3D texture addressable with 3D texture coordinates rather than 6 separate textures. Useful for cubic environment mapping.

◆ setCurrentFrame()

void Ogre::TextureUnitState::setCurrentFrame ( unsigned 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.
Note
Applies to both fixed-function and programmable pipeline.

◆ setEnvironmentMap()

void Ogre::TextureUnitState::setEnvironmentMap ( bool  enable,
EnvMapType  envMapType = ENV_CURVED 
)

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 environment 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 orthogonal 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
enableTrue to enable, false to disable
envMapTypeThe type of environment mapping to perform. Planar, curved, reflection or normal.
See also
EnvMapType
Note
This option has no effect in the programmable pipeline.

◆ setFrameTextureName()

void Ogre::TextureUnitState::setFrameTextureName ( const String name,
unsigned int  frameNumber 
)

Sets the name of the texture associated with a frame.

Parameters
nameThe name of the texture.
frameNumberThe frame the texture name is to be placed in.
Note
Throws an exception if frameNumber exceeds the number of stored frames. Applies to both fixed-function and programmable pipeline.

◆ setGamma()

void Ogre::TextureUnitState::setGamma ( Real  gamma)
inline

Sets the gamma adjustment factor applied to this texture on loading the data.

Note
Must be called before any 'load' method. This gamma factor will be premultiplied in and may reduce the precision of your textures. You can use setHardwareGamma if supported to apply gamma on sampling the texture instead.

◆ setHardwareGammaEnabled()

void Ogre::TextureUnitState::setHardwareGammaEnabled ( bool  enabled)

Sets whether this texture will be set up so that on sampling it, hardware gamma correction is applied.

Remarks
24-bit textures are often saved in gamma colour space; this preserves precision in the 'darks'. However, if you're performing blending on the sampled colours, you really want to be doing it in linear space. One way is to apply a gamma correction value on loading (see setGamma), but this means you lose precision in those dark colours. An alternative is to get the hardware to do the gamma correction when reading the texture and converting it to a floating point value for the rest of the pipeline. This option allows you to do that; it's only supported in relatively recent hardware (others will ignore it) but can improve the quality of colour reproduction.
Note
Must be called before any 'load' method since it may affect the construction of the underlying hardware resources. Also note this only useful on textures using 8-bit colour channels.

◆ setIsAlpha()

void Ogre::TextureUnitState::setIsAlpha ( bool  isAlpha)

Sets whether this texture is requested to be loaded as alpha if single channel.

◆ setName()

void Ogre::TextureUnitState::setName ( const String name)

Set the name of the Texture Unit State.

Remarks
The name of the Texture Unit State is optional. Its useful in material scripts where a material could inherit from another material and only want to modify a particalar Texture Unit State.

◆ setNumMipmaps()

void Ogre::TextureUnitState::setNumMipmaps ( int  numMipmaps)

Sets how many mipmaps have been requested for the texture.

◆ setProjectiveTexturing()

void Ogre::TextureUnitState::setProjectiveTexturing ( bool  enabled,
const Frustum projectionSettings = 0 
)

Enables or disables projective texturing on this texture unit.

Remarks
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 you must ensure that the Frustum object you pass a pointer to 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.
Parameters
enabledWhether to enable / disable.
projectionSettingsThe Frustum which will be used to derive the projection parameters.

◆ setRotateAnimation()

void Ogre::TextureUnitState::setRotateAnimation ( Real  speed)

Sets up an animated texture rotation for this layer.

Note
Useful for constant rotations (for varying rotations, see setTransformAnimation).
Parameters
speedThe number of complete anticlockwise revolutions per second (use -ve for clockwise)
Note
This option has no effect in the programmable pipeline.

◆ setSamplerblock()

void Ogre::TextureUnitState::setSamplerblock ( const HlmsSamplerblock samplerblock)

Changes the current samplerblock for a new one.

◆ setScrollAnimation()

void Ogre::TextureUnitState::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
uSpeedThe number of horizontal loops per second (+ve=moving right, -ve = moving left).
vSpeedThe number of vertical loops per second (+ve=moving up, -ve= moving down).
Note
This option has no effect in the programmable pipeline.

◆ setTexture()

void Ogre::TextureUnitState::setTexture ( TextureGpu texPtr)

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

Note
Applies to both fixed-function and programmable pipeline.

◆ setTextureCoordSet()

void Ogre::TextureUnitState::setTextureCoordSet ( unsigned 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.
Only applies to the fixed function pipeline and has no effect if a fragment program is used.

◆ setTextureName()

void Ogre::TextureUnitState::setTextureName ( const String name,
TextureTypes::TextureTypes  ttype = TextureTypes::Type2D 
)

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

Note
Applies to both fixed-function and programmable pipeline.

◆ setTextureNameAlias()

void Ogre::TextureUnitState::setTextureNameAlias ( const String name)

Set the alias name used for texture frame names.

Parameters
nameCan be any sequence of characters and does not have to be unique.

◆ setTextureRotate()

void Ogre::TextureUnitState::setTextureRotate ( const Radian angle)

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.
Note
Has no effect in the programmable pipeline.
Parameters
angleThe angle of rotation (anticlockwise).

◆ setTextureScale()

void Ogre::TextureUnitState::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).
Note
Has no effect in the programmable pipeline.
Parameters
uScaleThe value by which the texture is to be scaled horizontally.
vScaleThe value by which the texture is to be scaled vertically.

◆ setTextureScroll()

void Ogre::TextureUnitState::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
Note
Has no effect in the programmable pipeline.
Parameters
uThe amount the texture should be moved horizontally (u direction).
vThe amount the texture should be moved vertically (v direction).
See also
ControllerManager, Controller

◆ setTextureTransform()

void Ogre::TextureUnitState::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.
Note
Has no effect in the programmable pipeline.

◆ setTextureUScale()

void Ogre::TextureUnitState::setTextureUScale ( Real  value)

As setTextureScale, but sets only U value.

Note
Has no effect in the programmable pipeline.

◆ setTextureUScroll()

void Ogre::TextureUnitState::setTextureUScroll ( Real  value)

As setTextureScroll, but sets only U value.

Note
Has no effect in the programmable pipeline.

◆ setTextureVScale()

void Ogre::TextureUnitState::setTextureVScale ( Real  value)

As setTextureScale, but sets only V value.

Note
Has no effect in the programmable pipeline.

◆ setTextureVScroll()

void Ogre::TextureUnitState::setTextureVScroll ( Real  value)

As setTextureScroll, but sets only V value.

Note
Has no effect in the programmable pipeline.

◆ setTransformAnimation()

void Ogre::TextureUnitState::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
ttypeThe type of transform, either translate (scroll), scale (stretch) or rotate (spin).
waveTypeThe shape of the wave, see WaveformType enum for details.
baseThe base value for the function (range of output = {base, base + amplitude}).
frequencyThe speed of the wave in cycles per second.
phaseThe offset of the start of the wave, e.g. 0.5 to start half-way through the wave.
amplitudeScales the output so that instead of lying within 0..1 it lies within 0..1*amplitude for exaggerated effects.
Note
This option has no effect in the programmable pipeline.

◆ shouldStayLoaded()

virtual bool Ogre::TextureGpuListener::shouldStayLoaded ( TextureGpu texture)
inlinevirtualinherited

Return true if this TextureGpu should likely stay loaded or else graphical changes could occur.

Return false if it is certainly safe to unload.

Reimplemented in Ogre::VctLighting, and Ogre::OGRE_HLMS_TEXTURE_BASE_CLASS.

Friends And Related Function Documentation

◆ RenderSystem

friend class RenderSystem
friend

The documentation for this class was generated from the following file: