Torque2D Reference

- Main Page
- Related Pages
- Modules
- Namespaces
- Classes

- Class List
- Class Index
- Class Hierarchy
- Class Members

Public Types | Public Member Functions | List of all members
TextureHandle Class Reference

`#include <TextureHandle.h>`

## Public Types
enum | TextureHandleType { InvalidTexture = 0, BitmapTexture = 100, BitmapKeepTexture = 200 }

## Public Member Functions
| TextureHandle ()
| TextureHandle (TextureObject *to)
| TextureHandle (const TextureHandle &th)
| TextureHandle (const char *textureKey, TextureHandleType type, bool clampToEdge=false, bool force16Bit=false)
| TextureHandle (const char *textureKey, GBitmap *bmp, TextureHandleType type, bool clampToEdge=false)
| ~TextureHandle ()
TextureHandle & | operator= (const TextureHandle &t)
bool | set (const char *pTextureKey, TextureHandleType type=BitmapTexture, bool clampToEdge=false, bool force16Bit=false)
bool | set (const char *pTextureKey, GBitmap *bmp, TextureHandleType type, bool clampToEdge=false)
bool | operator== (const TextureHandle &handle) const
bool | operator!= (const TextureHandle &handle) const
void | setClamp (const bool clamp)
void | setFilter (const GLuint filter)
void | clear (void)
void | refresh (void)
| operator TextureObject * ()
bool | NotNull (void) const
bool | IsNull (void) const
const char * | getTextureKey (void) const
U32 | getWidth (void) const
U32 | getHeight (void) const
GBitmap * | getBitmap (void)
const GBitmap * | getBitmap (void) const
U32 | getGLName (void) const

## Detailed Description

This is the main texture manager interface. Texturing can be a bit complicated, but if you follow these easy steps, it is really quite simple!

In order to use a texture on disk, first you must create a TextureHandle data structure for it.

TextureHandle handle = TextureHandle("pathToTexture", textureType);

See the documentation on the different enumerated types for more info on texture types.

Ok, now you have your texture loaded into video memory or ram, whichever is chooses. In order to tell OpenGL to use your texture, you have to bind it. GL_TEXTURE_2D is the type of texture you're binding - a 2 dimisional texture. Also note that you only have to do this if you are using direct OpenGL commands to draw rather than dgl. Dgl manages the below on it's own so you don't have to worry about it.

glBindTexture(GL_TEXTURE_2D, handle.getGLName());

Now you can begin to draw you texture. If you havn't already, make sure you make a call to glEnable(GL_TEXTURE_2D); before you start drawing and a call to glDisable(GL_TEXTURE_2D); when you're done. Failure to call glEnable will cause the texture not to draw, and failure to call glDisable will probably case an assert in debug mode and ugly artifacts in release.

If you are going through dgl, all you need is the TextureHandle and some points. See the dgl documentation for more info on each individual function in the dgl library. However, most dgl functions will take a TextureObject data type. And, it just so happens that a TextureHandle has a TextureObject! It also has an operator TextureObject*(), which lets you cast a TextureHandle to a TextureObject. That means that all you have to do is ignore the TextureObject parameter and just give it a TextureHandle.

Some tips on texture performance:

Instead of using hard-coded paths, use a hook to a console variable. You will probably change the directory structure for your game, and that means that you will have to go back to all of the hardcoded paths and change them by hand, then rebuild the engine. It is much better to use script variables since they are all in one place and easier to change.

Add the path string for your texture to the StringTable. Doing so helps in string lookups and faster string performance.

Don't create the texture every frame if at all possible. Make it a global variable if you have to - just don't load every frame. Loading data off of the disk every frame WILL cause massive performance loss and should be avoided at all costs. This is not to mention the overhead of generating mip map levels and uploading the texture into memory when the texture is created.

Note
  Texture handles can be allocated in 2 ways - by name to be loaded from disk, or by name to a dynamically generated texture

If you create a GBitmap and register it, the Texture manager owns the pointer - so if you re-register a texture with the same name, the texture manager will delete the second copy.

Also note the operator TextureObject*, as you can actually cast a TextureHandle to a TextureObject* if necessary.

## Member Enumeration Documentation

enum TextureHandleType

Enumerator
InvalidTexture |
BitmapTexture | Bitmap that will be unloaded after texture has been uploaded. The bitmap will need reloading if the textures need to be restored. This is the preferred type.
BitmapKeepTexture | Same as BitmapTexture except that the bitmap is kept which occupies main memory however it does not require loading if textures need to be restored.

## Constructor & Destructor Documentation

TextureHandle | ( |  | ) |
| inline

TextureHandle | ( | TextureObject * | to | ) |
| inline

TextureHandle | ( | const TextureHandle & | th | ) |
| inline

TextureHandle | ( | const char * | textureKey,
|  | TextureHandleType | type,
|  | bool | clampToEdge = `false`,
|  | bool | force16Bit = `false`
| ) |  |

TextureHandle | ( | const char * | textureKey,
|  | GBitmap * | bmp,
|  | TextureHandleType | type,
|  | bool | clampToEdge = `false`
| ) |  |

~TextureHandle | ( |  | ) |
| inline

## Member Function Documentation

void clear | ( | void |  | ) |
| inline

GBitmap * getBitmap | ( | void |  | ) |

const GBitmap * getBitmap | ( | void |  | ) | const

U32 getGLName | ( | void |  | ) | const

U32 getHeight | ( | void |  | ) | const

const char * getTextureKey | ( | void |  | ) | const

U32 getWidth | ( | void |  | ) | const

bool IsNull | ( | void |  | ) | const
| inline

bool NotNull | ( | void |  | ) | const
| inline

operator TextureObject * | ( |  | ) |
| inline

bool operator!= | ( | const TextureHandle & | handle | ) | const
| inline

TextureHandle& operator= | ( | const TextureHandle & | t | ) |
| inline

bool operator== | ( | const TextureHandle & | handle | ) | const
| inline

void refresh | ( | void |  | ) |

bool set | ( | const char * | pTextureKey,
|  | TextureHandleType | type = `BitmapTexture`,
|  | bool | clampToEdge = `false`,
|  | bool | force16Bit = `false`
| ) |  |

bool set | ( | const char * | pTextureKey,
|  | GBitmap * | bmp,
|  | TextureHandleType | type,
|  | bool | clampToEdge = `false`
| ) |  |

void setClamp | ( | const bool | clamp | ) |

void setFilter | ( | const GLuint | filter | ) |

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

- graphics/TextureHandle.h
- graphics/TextureHandle.cc