TextureUnit

From oWiki

Contents 1 Attributes 1.1 mat 1.2 technique 1.3 pass 1.4 index 1.5 textureName 1.6 textureType 1.7 textureCoordSet 1.8 currentFrame 1.9 frameCount 1.10 animationDuration 1.11 bindingType 1.12 contentType 1.13 pixelFormat 1.14 numMidmaps 1.15 isAlpha 1.16 hardwareGamaEnabled 1.17 colorBlendMode 1.18 alphaBlendMode 2 Methods 2.1 setTextureName( name, type ) 2.2 setCubicTextureName( name, forUVW ) 2.3 setAnimatedTextureName( name, numFrames, duration ) 2.4 getTextureSize( frame ) 2.5 setProjectiveTexturing( enabled, proj ) 2.6 setFrameTextureName( name, frame ) 2.7 getFrameTextureName( frame ) 2.8 addFrameTextureName( name ) 2.9 deleteFrameTextureName( frame ) 2.10 isBlank() 2.11 setBlank() 2.12 isLoaded() 2.13 isTextureLoadFailing() 2.14 retryTextureLoad() 2.15 isCubic() 2.16 is3D() 2.17 setTextureScroll( u, v ) 2.18 getTextureScroll() 2.19 setTextureScale( u, v ) 2.20 getTextureScale() 2.21 setTextureRotate( a ) 2.22 getTextureRotate() 2.23 setTextureAddressingMode( u, v, w ) 2.24 getTextureAddressingMode() 2.25 setTextureBorderColor( c ) 2.26 getTextureBorderColor() 2.27 setTextureFiltering( type, opts ) 2.28 setTextureFiltering( minFilter, magFilter, mipFilter ) 2.29 setTextureFiltering( filterType ) 2.30 getTextureFiltering() 2.31 removeAllEffects() 2.32 removeEffect( t ) 2.33 setEnvironmentMap( enable, envMapType ) 2.34 setScrollAnimation( uSpeed, vSpeed ) 2.35 setRotateAnimation( speed ) 2.36 setTransformAnimation( type, waveType, base, frequency, phase, amplitude ) 2.37 setColorOperation( op, source1, source2, color1, color2, manualBlend ) 2.38 setAlphaOperation( op, source1, source2, color1, color2, manualBlend )

Attributes

mat

string  ( r )
The material name associated with this TextureUnit.

technique

int  ( r )
The index of technique associated with this TextureUnit.

pass

int  ( r )
The index of pass associated with this TextureUnit.

index

int  ( r )
The indexed location of this TextureUnit.

textureName

string  ( r, w )
Gets/Sets the name of this TextureUnit. This is a short hand method to setTextureName(name, TEX_TYPE_2D).

textureType

string  ( r )
Gets the type of this texture.

Possible types are:

Value	Description
TEX_TYPE_1D	1D texture, used in combination with 1D texture coordinates
TEX_TYPE_2D	2D texture, used in combination with 2D texture coordinates (default)
TEX_TYPE_3D	3D volume texture, used in combination with 3D texture coordinates
TEX_TYPE_CUBE_MAP	3D cube map, used in combination with 3D texture coordinates

textureCoordSet

int  ( r, w )
Gets/Sets the index of the set of texture co-ords this layer uses.
Default is 0 for all layers. Only change this if you have provided multiple texture co-ords per vertex. Applies to both fixed-function and programmable pipeline.

currentFrame

int  ( r, w )
Gets/Sets the active frame in an animated or multi-image texture. 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.

frameCount

int  ( r )
Gets the number of frames for a texture.

animationDuration

float  ( r )
Gets the duration of a texture animation in seconds.

bindingType

int  ( r, w )
Gets/Sets the type of unit these texture settings should be bound to.
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.
Possible types are: BT_FRAGMENT or BT_VERTEX.

contentType

int  ( r, w )
Gets/Sets the type of content this TextureUnit references.
Possible types are: CONTENT_NAMED, CONTENT_SHADOW, or CONTENT_COMPOSITOR.

pixelFormat

int  ( r, w )
Gets/Sets the desired pixel format when load the texture.

numMidmaps

int  ( r, w )
Gets/Sets how many mipmaps have been requested for the texture.

isAlpha

bool  ( r, w )
Gets/Sets whether this texture is requested to be loaded as alpha if single channel.

hardwareGamaEnabled

bool  ( r, w )
Gets/Sets whether this texture will be set up so that on sampling it, hardware gamma correction is applied.

colorBlendMode

int  ( r )
Gets multitexturing color blending mode.
The returned value is an object with the following properties:

Value	Description
blendType	The type of blending (LBT_COLOUR or LBT_ALPHA).
operation	The operation to be applied. Possible values are: LBX_SOURCE1: use source1 without modification. LBX_SOURCE2: use source2 without modification. LBX_MODULATE: multiply source1 and source2 together. LBX_MODULATE_X2: as LBX_MODULATE but brighten afterwards (x2). LBX_MODULATE_X4: as LBX_MODULATE but brighten more afterwards (x4). LBX_ADD : add source1 and source2 together. LBX_ADD_SIGNED: as LBX_ADD, but subtract 0.5 from the result. LBX_ADD_SMOOTH: as LBX_ADD, but subtract product from the sum. LBX_SUBTRACT : subtract source2 from source1. LBX_BLEND_DIFFUSE_ALPHA: use interpolated alpha value from vertices to scale source1, then add source2 scaled by (1-alpha). LBX_BLEND_TEXTURE_ALPHA: as LBX_BLEND_DIFFUSE_ALPHA, but use alpha from texture. LBX_BLEND_CURRENT_ALPHA: as LBX_BLEND_DIFFUSE_ALPHA, but use current alpha from previous stages. LBX_BLEND_MANUAL: as LBX_BLEND_DIFFUSE_ALPHA but use a constant manual blend value (0.0-1.0). LBX_DOTPRODUCT: dot product of color1 and color2. LBX_BLEND_DIFFUSE_COLOUR: use interpolated color values from vertices to scale source1, then add source2 scaled by (1-color)
source1	List of valid sources of values for blending operations. Possible values are: LBS_CURRENT : the colour as built up from previous stages. LBS_TEXTURE: the colour derived from the texture assigned to this layer. LBS_DIFFUSE: the interpolated diffuse colour from the vertices. LBS_SPECULAR: the interpolated specular colour from the vertices. LBS_MANUAL : a colour supplied manually as a separate argument
source2	List of valid sources of values for blending operations. Possible values are: LBS_CURRENT : the colour as built up from previous stages. LBS_TEXTURE: the colour derived from the texture assigned to this layer. LBS_DIFFUSE: the interpolated diffuse colour from the vertices. LBS_SPECULAR: the interpolated specular colour from the vertices. LBS_MANUAL : a colour supplied manually as a separate argument
color1	Manual colour value for manual source1. RGBA.
color2	Manual colour value for manual source2. RGBA.
alpha1	Manual alpha value for manual source1. float.
alpha2	Manual alpha value for manual source2. float.
factor	Manual blending factor. float.

alphaBlendMode

int  ( r )
Gets multitexturing alpha blending mode. The returned value is an object with the same properties as in colorBlendMode (see above.)

Methods

setTextureName( name, type )

name: string
type: int

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

Possible types are: Value Description TEX_TYPE_1D 1D texture, used in combination with 1D texture coordinates TEX_TYPE_2D 2D texture, used in combination with 2D texture coordinates (default) TEX_TYPE_3D 3D volume texture, used in combination with 3D texture coordinates TEX_TYPE_CUBE_MAP 3D cube map, used in combination with 3D texture coordinates

setCubicTextureName( name, forUVW )

name: string
forUVW: bool

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

The input parameter name is 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.

Set forUVW to true if you want a single 3D texture addressable with 3D texture coordinates rather than 6 separate textures. Useful for cubic environment mapping.

setAnimatedTextureName( name, numFrames, duration )

name: string
numFrames: int
duration: float

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

Animated textures are just a series of images making up the frames of the animation. All the images must be the same size, and their names must have a frame number appended before the extension, e.g. if you specify a name of "wall.jpg" with 3 frames, the image names must be "wall_0.jpg", "wall_1.jpg" and "wall_2.jpg". You can change the active frame on a texture layer by calling the setCurrentFrame method.

duration is the length of time it takes to display the whole animation sequence, in seconds. If 0, no automatic transition occurs.

getTextureSize( frame )

frame: int (optional)

Returns the width and height of the texture in the given frame. By default, frame is 0.

The returned value is an object with width and height properties.

setProjectiveTexturing( enabled, proj )

enabled: bool
proj: a Projector object

Enables or disables projective texturing on this texture unit.

Projective texturing allows you to generate texture coordinates based on a Projector, 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 Projector you passed in and the projection will change if you can alter it. It also means that you must ensure that the Projector object you pass a pointer to remains in existence for as long as this TextureUnit 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.

setFrameTextureName( name, frame )

name: string
frame: int

Sets the name of the texture associated with a frame.

getFrameTextureName( frame )

frame: int
Return: string

Gets the name of the texture associated with a frame.

addFrameTextureName( name )

name: string

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

deleteFrameTextureName( frame )

frame: int

deletes a specific texture frame.

isBlank()

Return: bool

Determines if this texture layer is currently blank.

setBlank()

Sets this texture layer to be blank.

isLoaded()

Return: bool

Tests if the texture associated with this unit is loaded.

isTextureLoadFailing()

Return: bool

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

retryTextureLoad()

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

isCubic()

Return: bool

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.

is3D()

Return: bool

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

setTextureScroll( u, v )

u: float. The amount the texture should be moved horizontally (u direction).
v: float. The amount the texture should be moved vertically (v direction).

Sets the translation offset of the texture, i.e. scrolls the texture.

getTextureScroll()

Return: object {u: 0.2, v: 0.5}

Gets the currently translation offset of the texture.

setTextureScale( u, v )

u: float. The value by which the texture is to be scaled horizontally.
v: float. The value by which the texture is to be scaled vertically.

Sets the scaling factor applied to texture coordinates.

getTextureScale()

Return: object {u: 0.2, v: 0.5}

Gets the current scaling factor applied to texture coordinates.

setTextureRotate( a )

a: float, the angle of rotation in degrees

Sets the anticlockwise rotation factor applied to texture coordinates.

getTextureRotate()

Return: float in degrees

Gets the current anticlockwise rotation factor applied to texture coordinates.

setTextureAddressingMode( u, v, w )

u: int. mode for u direction
v: int. mode for v direction
w: int. mode for w direction

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

Possible addressing modes are: Value Description 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. TAM_BORDER Texture coordinates outside the range [0.0, 1.0] are set to the border colour.

getTextureAddressingMode()

Return: object {u:int, v:int, w:int}

Gets the texture addressing mode for a given coordinate.

setTextureBorderColor( c )

c: RGBA

Sets the texture border color. The default is Black, and this value only used when addressing mode is TAM_BORDER.

getTextureBorderColor()

Return: RGBA

Gets the texture border color.

setTextureFiltering( type, opts )

type: int
opts: int

Set a single filtering option on this texture unit.

Possible filter types are: Value Description FT_MIN The filter used when shrinking a texture. FT_MAG The filter used when magnifying a texture. FT_MIP The filter used when determining the mipmap.

Possible filter options are: Value Description FO_NONE No filtering, used for FILT_MIP to turn off mipmapping. FO_POINT Use the closest pixel. FO_LINEAR Average of a 2x2 pixel area, denotes bilinear for MIN and MAG, trilinear for MIP. FO_ANISOTROPIC Similar to FO_LINEAR, but compensates for the angle of the texture plane.

setTextureFiltering( minFilter, magFilter, mipFilter )

minFilter: int
magFilter: int
mipFilter: int

Set a the detailed filtering options on this texture unit.

Possible filter options are: Value Description FO_NONE No filtering, used for FILT_MIP to turn off mipmapping. FO_POINT Use the closest pixel. FO_LINEAR Average of a 2x2 pixel area, denotes bilinear for MIN and MAG, trilinear for MIP. FO_ANISOTROPIC Similar to FO_LINEAR, but compensates for the angle of the texture plane.

setTextureFiltering( filterType )

filterType: int

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

Possible filter options are: Value Description TFO_NONE Equal to: min=FO_POINT, mag=FO_POINT, mip=FO_NONE. TFO_BILINEAR Equal to: min=FO_LINEAR, mag=FO_LINEAR, mip=FO_POINT. TFO_TRILINEAR Equal to: min=FO_LINEAR, mag=FO_LINEAR, mip=FO_LINEAR. TFO_ANISOTROPIC Equal to: min=FO_ANISOTROPIC, max=FO_ANISOTROPIC, mip=FO_LINEAR.

getTextureFiltering()

Return: {min:int, mag:int, mip:int}

Gets the texture filtering for this unit.

removeAllEffects()

Removes all effects applied to this texture layer.

removeEffect( t )

t: int, type of effect

Removes a single effect applied to this texture layer.

Possible effect types are: Value Description 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 v scrolling effect. ET_ROTATE Constant rotation. ET_TRANSFORM More complex transform.

setEnvironmentMap( enable, envMapType )

enable: bool
envMapType : int

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

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

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

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

Possible map types are: Value Description 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.

setScrollAnimation( uSpeed, vSpeed )

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

Sets up an animated scroll for the texture layer.

setRotateAnimation( speed )

speed: float. The number of complete anticlockwise revolutions per second (use -ve for clockwise)

Sets up an animated texture rotation for this layer. Note: Useful for constant rotations (for varying rotations, see setTransformAnimation).

setTransformAnimation( type, waveType, base, frequency, phase, amplitude )

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

Sets up a general time-relative texture modification effect.

Possible wave types are: Value Description WFT_SINE Standard sine wave which smoothly changes from low to high and back again. WFT_TRIANGLE An angular wave with a constant increase / decrease speed with pointed peaks. WFT_SQUARE Half of the time is spent at the min, half at the max with instant transition between. WFT_SAWTOOTH Gradual steady increase from min to max over the period with an instant return to min at the end. WFT_INVERSE_SAWTOOTH Gradual steady decrease from max to min over the period, with an instant return to max at the end. WFT_PWM Pulse Width Modulation. Works like WFT_SQUARE, except the high to low transition is controlled by duty cycle. With a duty cycle of 50% (0.5) will give the same output as WFT_SQUARE.

setColorOperation( op, source1, source2, color1, color2, manualBlend )

op: int. The operation to be used
source1: int. The source of the first color to the operation
source2: int. The source of the second color to the operation
color1: RGBA. Manually supplied color value (only required if source1 = LBS_MANUAL)
color2: RGBA. Manually supplied color value (only required if source1 = LBS_MANUAL)
manualBlend: float. Manually supplied 'blend' value - only required for operations which require manual blend e.g. LBX_BLEND_MANUAL

Setting advanced blending options.

Possible opertions are: Value Description LBX_SOURCE1 use source1 without modification. LBX_SOURCE2 use source2 without modification. LBX_MODULATE multiply source1 and source2 together. LBX_MODULATE_X2 as LBX_MODULATE but brighten afterwards (x2). LBX_MODULATE_X4 as LBX_MODULATE but brighten more afterwards (x4). LBX_ADD add source1 and source2 together. LBX_ADD_SIGNED as LBX_ADD, but subtract 0.5 from the result. LBX_ADD_SMOOTH as LBX_ADD, but subtract product from the sum. LBX_SUBTRACT subtract source2 from source1. LBX_BLEND_DIFFUSE_ALPHA use interpolated alpha value from vertices to scale source1, then add source2 scaled by (1-alpha). LBX_BLEND_TEXTURE_ALPHA as LBX_BLEND_DIFFUSE_ALPHA, but use alpha from texture. LBX_BLEND_CURRENT_ALPHA as LBX_BLEND_DIFFUSE_ALPHA, but use current alpha from previous stages. LBX_BLEND_MANUAL as LBX_BLEND_DIFFUSE_ALPHA but use a constant manual blend value (0.0-1.0). LBX_DOTPRODUCT dot product of color1 and color2. LBX_BLEND_DIFFUSE_COLOUR use interpolated color values from vertices to scale source1, then add source2 scaled by (1-color).

Possible blend sources are: Value Description LBS_CURRENT the color as built up from previous stages . LBS_TEXTURE the color derived from the texture assigned to this layer. LBS_DIFFUSE the interpolated diffuse color from the vertices. LBS_SPECULAR the interpolated specular color from the vertices. LBS_MANUAL a color supplied manually as a separate argument.

setAlphaOperation( op, source1, source2, color1, color2, manualBlend )

op: int. The operation to be used
source1: int. The source of the first alpha to the operation
source2: int. The source of the second alpha to the operation
color1: RGBA. Manually supplied alpha value (only required if source1 = LBS_MANUAL)
color2: RGBA. Manually supplied alpha value (only required if source1 = LBS_MANUAL)
manualBlend: float. Manually supplied 'blend' value - only required for operations which require manual blend e.g. LBX_BLEND_MANUAL

Sets the alpha operation to be applied to this texture. (see setColorOperation for details.)