Xors3d Engine
Textures

Functions

void xClearTextureFilters ()
 Clears the current texture filter list.
Texture * xCreateTexture (int width, int height, int flags=9, int frames=1)
 Creates a texture and returns its handle.
Texture * xCreateTextureFromData (void *pixelsData, int width, int height, int flags=9, int frames=1)
 Creates texture from user data.
void xFreeTexture (Texture *texture)
 Frees up a texture.
int xGetCubeFace (Texture *texture)
 Returns current cube face of a cubemap texture.
int xGetCubeMode (Texture *texture)
 Returns the rendering mode of a cubemap texture.
float xGetTextureAngle (Texture *texture)
 Returns the absolute angle of texture rotation.
int xGetTextureBlend (Texture *texture)
 Returns the blending mode for a texture.
int xGetTextureCoords (Texture *texture)
 Returns the coordinate set of a texture.
void * xGetTextureData (Texture *texture, int frame=0)
 Returns texture pixels data.
int xGetTextureDataPitch (Texture *texture, int frame=0)
 Returns texture pixels data pitch.
int xGetTextureFrames (Texture *texture)
 Returns a count of texture frames.
float xGetTextureScaleX (Texture *texture)
 Returns the absolute X (U) scale of a texture.
float xGetTextureScaleY (Texture *texture)
 Returns the absolute Y (V) scale of a texture.
LPDIRECT3DTEXTURE9 xGetTextureSurface (Texture *texture, int frame=0)
 Returns a pointer to Direct3D texture surface.
float xGetTextureX (Texture *texture)
 Returns the absolute X (U) position of a texture.
float xGetTextureY (Texture *texture)
 Returns the absolute Y (V) position of a texture.
Texture * xLoadAnimTexture (const char *path, int flags, int width, int height, int startFrame, int frames)
 Loads an animated texture.
Texture * xLoadTexture (const char *path, int flags=9)
 Loads a texture from an image file and returns the texture's handle.
void xPositionTexture (Texture *texture, float x, float y)
 Positions a texture at an absolute position.
void xRotateTexture (Texture *texture, float angle)
 Rotates a texture.
void xScaleTexture (Texture *texture, float x, float y)
 Scales a texture by an absolute amount.
void xSetCubeFace (Texture *texture, int face)
 Selects a cube face for direct rendering to a texture.
void xSetCubeMode (Texture *texture, int mode)
 Sets the rendering mode of a cubemap texture.
void xStretchRect (Texture *texture1, int x1, int y1, int width1, int height1, Texture *texture2, int x2, int y2, int width2, int height2, int filter)
 Copys data from one texture to another using hardware accelerated method.
void xTextureBlend (Texture *texture, int blend)
 Sets the blending mode for a texture.
TextureBuffer * xTextureBuffer (Texture *texture, int frame=0)
 Returns the handle of a texture's drawing buffer.
void xTextureCoords (Texture *texture, int coords)
 Sets the texture coordinate mode for a texture.
void xTextureFilter (const char *matchText, int flags)
 Sets texture filtering.
int xTextureHeight (Texture *texture)
 Returns the height of a texture.
const char * xTextureName (Texture *texture)
 Returns a texture's absolute filename.
int xTextureWidth (Texture *texture)
 Returns the width of a texture.

Function Documentation

TextureBuffer* xTextureBuffer ( Texture *  texture,
int  frame = 0 
)

Returns the handle of a texture's drawing buffer.

This can be used with xSetBuffer() to perform direct drawing operations to the texture

Parameters:
textureTexture handle
frameTexture frame
void xStretchRect ( Texture *  texture1,
int  x1,
int  y1,
int  width1,
int  height1,
Texture *  texture2,
int  x2,
int  y2,
int  width2,
int  height2,
int  filter 
)

Copys data from one texture to another using hardware accelerated method.

Parameters:
texture1Source texture handle
x1x coordinate of top left corner of source rectangle
y1y coordinate of top left corner of source rectangle
width1Width of source rectangle
height1Height of source rectangle
texture2Destination texture handle
x2x coordinate of top left corner of destination rectangle
y2y coordinate of top left corner of destination rectangle
width2Width of destination rectangle
height2Height of destination rectangle
filterFiltering method
int xTextureWidth ( Texture *  texture)

Returns the width of a texture.

Parameters:
textureTexture handle
int xTextureHeight ( Texture *  texture)

Returns the height of a texture.

Parameters:
textureTexture handle
Texture* xCreateTexture ( int  width,
int  height,
int  flags = 9,
int  frames = 1 
)

Creates a texture and returns its handle.

Width and height are the size of the texture. Note that the actual texture size may be different from the width and height requested, as different types of 3D hardware support different sizes of texture. The optional flags parameter allows you to apply certain effects to the texture. Flags can be added to combine two or more effects. See 'Texture loading flags' for more information Once you have created a texture, use xSetBuffer(xTextureBuffer()) to draw to it. Xors3D supports direct rendering into textures.

Parameters:
widthWidth of texture
heightHeight of texture
flagsTexture creation flags
framesNumber of frames texture will have
void xFreeTexture ( Texture *  texture)

Frees up a texture.

Parameters:
textureTexture handle
void xTextureBlend ( Texture *  texture,
int  blend 
)

Sets the blending mode for a texture.

The texture blend mode determines how the texture will blend with the texture or polygon which is 'below' it. Texture 0 will blend with the polygons of the entity it is applied to. Texture 1 will blend with texture 0. Texture 2 will blend with texture 1. And so on. Texture blending effectively takes the highest order texture (the one with the highest index) and it blends with the texture below it, then that result to the texture directly below again, and so on until texture 0 which is blended with the polygons of the entity it is applied to and thus the world, depending on the xEntityBlend() of the object. Each of the blend modes are identical to their xEntityBlend() counterparts.

Parameters:
textureTexture handle
blendBlending mode. See 'Textures blending types (fixed-function pipeline)' for more infromation
void xTextureCoords ( Texture *  texture,
int  coords 
)

Sets the texture coordinate mode for a texture.

This determines where the UV values used to look up a texture come from

Parameters:
textureTexture handle
coordsUV coordinates number (0 or 1)
void xTextureFilter ( const char *  matchText,
int  flags 
)

Sets texture filtering.

Loaded textures that contain text specified by 'matchText' in file name param will have the provided flags added.

Parameters:
matchTextText string that, if found in texture filename, will activate certain filters.
flagsTexture flags to be applied, see 'Texture loading flags' for more information.
See also:
xClearTextureFilters()
void xClearTextureFilters ( )

Clears the current texture filter list.

See also:
xTextureFilter()
Texture* xLoadTexture ( const char *  path,
int  flags = 9 
)

Loads a texture from an image file and returns the texture's handle.

The optional flags parameter allows you to apply certain effects to the texture. Flags can be added to combine two or more effects. See 'Texture loading flags' for more infromation. Supported file formats are: bmp, dds, dib, hdr, jpg, pfm, png, ppm, tga.

Parameters:
pathFilename of image file to be used as texture
flagsLoading flags, see 'Texture loading flags'
const char* xTextureName ( Texture *  texture)

Returns a texture's absolute filename.

To find out just the name of the texture, you will need to parse the string returned by xTextureName().

Parameters:
textureTexture handle
void xPositionTexture ( Texture *  texture,
float  x,
float  y 
)

Positions a texture at an absolute position.

This will have an immediate effect on all instances of the texture being used. Positioning a texture is useful for performing scrolling texture effects, such as for water etc.

Parameters:
textureTexture handle
xu position of texture
yv position of texture
void xScaleTexture ( Texture *  texture,
float  x,
float  y 
)

Scales a texture by an absolute amount.

This will have an immediate effect on all instances of the texture being used

Parameters:
textureTexture handle
xx scale of texture
yy scale of texture
void xRotateTexture ( Texture *  texture,
float  angle 
)

Rotates a texture.

This will have an immediate effect on all instances of the texture being used. Rotating a texture is useful for performing swirling texture effects, such as for smoke etc

Parameters:
textureTexture handle
angleTexture otation angle
Texture* xLoadAnimTexture ( const char *  path,
int  flags,
int  width,
int  height,
int  startFrame,
int  frames 
)

Loads an animated texture.

The 'flags' parameter allows you to apply certain effects to the texture. Flags can be added to combine two or more effects. See 'Texture loading flags' for more infromation.

Parameters:
pathName of image file
flagsLoading flags
widthWidth in pixels of each frame in the texture
heightHeight in pixels of each frame in the texture
startFrameThe frame to start with (usually 0)
framesHow many frames you are using of the imagestrip
Texture* xCreateTextureFromData ( void *  pixelsData,
int  width,
int  height,
int  flags = 9,
int  frames = 1 
)

Creates texture from user data.

Parameters:
pixelsDataPointer to pixels data
widthTexture width
heightTexture height
flagsTexture creation flags. See '/ref tlflags' for more information
framesNumber of texture frames
void* xGetTextureData ( Texture *  texture,
int  frame = 0 
)

Returns texture pixels data.

NOTE: You may get pixels data only from locked texture frames

Parameters:
textureTexture handle
frameFrame index
int xGetTextureDataPitch ( Texture *  texture,
int  frame = 0 
)

Returns texture pixels data pitch.

You must use this value for computing pixel position instead texture width (e.g. value = pixels[y * xGetTextureDataPitch() + x]) if you use non power-of-two textures.

NOTE: You can get pixels data only from locked texture frames

Parameters:
textureTexture handle
frameFrame index
LPDIRECT3DTEXTURE9 xGetTextureSurface ( Texture *  texture,
int  frame = 0 
)

Returns a pointer to Direct3D texture surface.

Parameters:
textureTexture handle
frameFrame index
int xGetTextureFrames ( Texture *  texture)

Returns a count of texture frames.

Parameters:
textureTexture handle
void xSetCubeFace ( Texture *  texture,
int  face 
)

Selects a cube face for direct rendering to a texture.

This command should only be used when you wish to draw directly to a cubemap texture in real-time. Otherwise, just loading a pre-rendered cubemap with a flag of FLAGS_CUBICENVMAP will suffice. To understand how this command works exactly it is important to recognise that Xors3D treats cubemap textures slightly differently to how it treats other textures. Here's how it works... A cubemap texture in Xors3D actually consists of six images, each of which must be square 'power' of two size - e.g. 32, 64, 128 etc. Each corresponds to a particular cube face. These images are stored internally by Xors3D, and the texture handle that is returned by xLoadTexture()/xCreateTexture() when specifying the cubemap flag, only provides access to one of these six images at once (by default the first one, or 'FACE_FORWARD' face). How do we get access to the other five images? This is where xSetCubeFace() comes in. It will tell Xors3D that whenever you next draw to a cubemap texture, to draw to the particular image representing the face you have specified with the face parameter.

Parameters:
textureTexture handle
faceCubemap face. See 'Cubemap faces' for more infromation
void xSetCubeMode ( Texture *  texture,
int  mode 
)

Sets the rendering mode of a cubemap texture.

Parameters:
textureTexture handle
modeRendering mode. See 'Cubemap rendering modes' for more infromation
int xGetTextureBlend ( Texture *  texture)

Returns the blending mode for a texture.

For more details see xTextureBlend.

Parameters:
textureTexture handle
float xGetTextureX ( Texture *  texture)

Returns the absolute X (U) position of a texture.

For more details see xPositionTexture.

Parameters:
textureTexture handle
float xGetTextureY ( Texture *  texture)

Returns the absolute Y (V) position of a texture.

For more details see xPositionTexture.

Parameters:
textureTexture handle
float xGetTextureScaleX ( Texture *  texture)

Returns the absolute X (U) scale of a texture.

For more details see xScaleTexture.

Parameters:
textureTexture handle
float xGetTextureScaleY ( Texture *  texture)

Returns the absolute Y (V) scale of a texture.

For more details see xScaleTexture.

Parameters:
textureTexture handle
float xGetTextureAngle ( Texture *  texture)

Returns the absolute angle of texture rotation.

For more details see xRotateTexture.

Parameters:
textureTexture handle
int xGetTextureCoords ( Texture *  texture)

Returns the coordinate set of a texture.

For more details see xTextureCoords.

Parameters:
textureTexture handle
int xGetCubeFace ( Texture *  texture)

Returns current cube face of a cubemap texture.

For more details see xSetCubeFace.

Parameters:
textureTexture handle
int xGetCubeMode ( Texture *  texture)

Returns the rendering mode of a cubemap texture.

For more details see xSetCubeMode.

Parameters:
textureTexture handle