Xors3d Engine
Textures

Functions

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

Function Documentation

BBDECL TextureBuffer* BBCALL 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
BBDECL void BBCALL 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
BBDECL int BBCALL xTextureWidth ( Texture *  texture)

Returns the width of a texture.

Parameters:
textureTexture handle
BBDECL int BBCALL xTextureHeight ( Texture *  texture)

Returns the height of a texture.

Parameters:
textureTexture handle
BBDECL Texture* BBCALL 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
BBDECL void BBCALL xFreeTexture ( Texture *  texture)

Frees up a texture.

Parameters:
textureTexture handle
BBDECL void BBCALL 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' for more infromation
BBDECL void BBCALL 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)
BBDECL void BBCALL 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()
BBDECL void BBCALL xClearTextureFilters ( )

Clears the current texture filter list.

See also:
xTextureFilter()
BBDECL Texture* BBCALL 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'
BBDECL const char* BBCALL 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
BBDECL void BBCALL 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
BBDECL void BBCALL 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
BBDECL void BBCALL 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
BBDECL Texture* BBCALL 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
BBDECL Texture* BBCALL 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
BBDECL void* BBCALL 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
BBDECL int BBCALL 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
BBDECL LPDIRECT3DTEXTURE9 BBCALL xGetTextureSurface ( Texture *  texture,
int  frame = 0 
)

Returns a pointer to Direct3D texture surface.

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

Returns a count of texture frames.

Parameters:
textureTexture handle
BBDECL void BBCALL 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
BBDECL void BBCALL 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
BBDECL int BBCALL xGetTextureBlend ( Texture *  texture)

Returns the blending mode for a texture.

For more details see xTextureBlend.

Parameters:
textureTexture handle
BBDECL float BBCALL xGetTextureX ( Texture *  texture)

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

For more details see xPositionTexture.

Parameters:
textureTexture handle
BBDECL float BBCALL xGetTextureY ( Texture *  texture)

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

For more details see xPositionTexture.

Parameters:
textureTexture handle
BBDECL float BBCALL xGetTextureScaleX ( Texture *  texture)

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

For more details see xScaleTexture.

Parameters:
textureTexture handle
BBDECL float BBCALL xGetTextureScaleY ( Texture *  texture)

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

For more details see xScaleTexture.

Parameters:
textureTexture handle
BBDECL float BBCALL xGetTextureAngle ( Texture *  texture)

Returns the absolute angle of texture rotation.

For more details see xRotateTexture.

Parameters:
textureTexture handle
BBDECL int BBCALL xGetTextureCoords ( Texture *  texture)

Returns the coordinate set of a texture.

For more details see xTextureCoords.

Parameters:
textureTexture handle
BBDECL int BBCALL xGetCubeFace ( Texture *  texture)

Returns current cube face of a cubemap texture.

For more details see xSetCubeFace.

Parameters:
textureTexture handle
BBDECL int BBCALL xGetCubeMode ( Texture *  texture)

Returns the rendering mode of a cubemap texture.

For more details see xSetCubeMode.

Parameters:
textureTexture handle