Torque3D Documentation / _generateds / GFXTextureManager

GFXTextureManager

Engine/source/gfx/gfxTextureManager.h

More...

Texture Necromancy

Texture necromancy in three easy steps:

  • If you want to destroy the texture manager, call kill().

  • If you want to switch resolutions, or otherwise reset the device, call zombify().

  • When you want to bring the manager back from zombie state, call resurrect().

void

kill()

void

zombify()

void

resurrect()

void

cleanupPool()

This releases any pooled textures which are currently unused freeing up video memory.

void

reloadTextures()

void

cleanupCache(U32 secondsToLive)

This releases cached textures that have not been referenced for a period of time.

void

addEventDelegate(T obj, U func)

Registers a callback for texture zombify and resurrect events.

void

removeEventDelegate(T obj, U func)

Unregisteres a texture event callback.

Public User Defined

GFXTextureObject *

_createTextureObject(U32 height, U32 width, U32 depth, GFXFormat format, GFXTextureProfile * profile, U32 numMipLevels, bool forceMips, S32 antialiasLevel, GFXTextureObject * inTex)

@group Internal Texture Manager Interface

bool

_loadTexture(GFXTextureObject * texture, DDSFile * dds)

Load a texture from a proper DDSFile instance.

bool

_loadTexture(GFXTextureObject * texture, GBitmap * bmp)

Load data into a texture from a GBitmap using the internal API.

bool

_loadTexture(GFXTextureObject * texture, void * raw)

Load data into a texture from a raw buffer using the internal API.

bool

_refreshTexture(GFXTextureObject * texture)

Refresh a texture using the internal API.

bool

_freeTexture(GFXTextureObject * texture, bool zombify)

Free a texture (but do not delete the GFXTextureObject) using the internal API.

Public Types

enum
_Anonymous_ {  AA_MATCH_BACKBUFFER = -1
}

Protected Types

enum
TextureManagerState {
  Living 
  Zombie 
  Dead 
}

HashTable< String, GFXCubemap * >

CubemapTable 

Signal< void(GFXTexCallbackCode code)>

EventSignal

The texture event signal type.

HashTable< GFXTextureProfile *, StrongRefPtr< GFXTextureObject > >

TexturePoolMap

The texture pool collection type.

Public Static Attributes

S32

smTextureReductionLevel

The amount of texture mipmaps to skip when loading a texture that allows downscaling.

Protected Static Attributes

String

smBRDFTexturePath 

String

smDefaultIrradianceCubemapPath 

String

smDefaultPrefilterCubemapPath 

EventSignal

smEventSignal

The texture event signal.

String

smMissingTexturePath

File path to the missing texture.

String

smUnavailableTexturePath

File path to the unavailable texture.

String

smWarningTexturePath

File path to the warning texture.

Protected Attributes

CubemapTable

mCubemapTable 

U32

mHashCount 

GFXTextureObject **

mHashTable 

GFXTextureObject *

mListHead 

GFXTextureObject *

mListTail 

enum GFXTextureManager::TextureManagerState

mTextureManagerState 

TexturePoolMap

mTexturePool

All the allocated texture pool textures.

Vector< GFXTextureObject * >

mToDelete

The textures waiting to be deleted.

Public Functions

GFXTextureManager()

~GFXTextureManager()

GFXTextureObject *

createCompositeTexture(const Torque::Path & pathR, const Torque::Path & pathG, const Torque::Path & pathB, const Torque::Path & pathA, U32 inputKey, GFXTextureProfile * profile)

GFXTextureObject *

createCompositeTexture(GBitmap * bmp, U32 inputKey, const String & resourceName, GFXTextureProfile * profile, bool deleteBmp)

GFXCubemap *

createCubemap(const Torque::Path & path)

Load a cubemap from a texture file.
GFXTextureObject *

createTexture(const Torque::Path & path, GFXTextureProfile * profile)

GFXTextureObject *

createTexture(DDSFile * dds, GFXTextureProfile * profile, bool deleteDDS)

GFXTextureObject *

createTexture(GBitmap * bmp, const String & resourceName, GFXTextureProfile * profile, bool deleteBmp)

GFXTextureObject *

createTexture(U32 width, U32 height, GFXFormat format, GFXTextureProfile * profile, U32 numMipLevels, S32 antialiasLevel)

GFXTextureObject *

createTexture(U32 width, U32 height, U32 depth, GFXFormat format, GFXTextureProfile * profile, U32 numMipLevels)

GFXTextureObject *

createTexture(U32 width, U32 height, void * pixels, GFXFormat format, GFXTextureProfile * profile)

void

deleteTexture(GFXTextureObject * texture)

GBitmap *

loadUncompressedTexture(const Torque::Path & path, GFXTextureProfile * profile)

GBitmap *

loadUncompressedTexture(const Torque::Path & path, GFXTextureProfile * profile, U32 width, U32 height, bool genMips)

void

releaseCubemap(GFXCubemap * cubemap)

Used to remove a cubemap from the cache.
void

reloadTexture(GFXTextureObject * texture)

void

requestDeleteTexture(GFXTextureObject * texture)

Request that the texture be deleted which will either occur immediately or delayed if its cached.
void

saveCompositeTexture(const Torque::Path & pathR, const Torque::Path & pathG, const Torque::Path & pathB, const Torque::Path & pathA, U32 inputKey, const Torque::Path & saveAs, GFXTextureProfile * profile)

Torque::Path

validatePath(const Torque::Path & path)

bool

validateTextureQuality(GFXTextureProfile * profile, U32 & width, U32 & height)

Update width and height based on available resources.
Public Static Functions
const String &

getBRDFTexturePath()

const String &

getDefaultIrradianceCubemapPath()

const String &

getDefaultPrefilterCubemapPath()

const String &

getMissingTexturePath()

Provide the path to the texture to use when the requested one is missing.
U32

getTextureDownscalePower(GFXTextureProfile * profile)

const String &

getUnavailableTexturePath()

Provide the path to the texture to use when the requested one is unavailable.
const String &

getWarningTexturePath()

Provide the path to the texture used to warn the developer.
void

init()

Set up some global script interface stuff.
Protected Functions
GFXTextureObject *

_createTexture(DDSFile * dds, GFXTextureProfile * profile, bool deleteDDS, GFXTextureObject * inObj)

GFXTextureObject *

_createTexture(GBitmap * bmp, const String & resourceName, GFXTextureProfile * profile, bool deleteBmp, GFXTextureObject * inObj)

GFXTextureObject *

_findPooledTexure(U32 width, U32 height, GFXFormat format, GFXTextureProfile * profile, U32 numMipLevels, S32 antialiasLevel)

Returns a free texture of the requested attributes from from the shared texture pool.
void

_linkTexture(GFXTextureObject * obj)

Store texture into the hash table cache and linked list.
GFXTextureObject *

_lookupTexture(const char * filename, const GFXTextureProfile * profile)

GFXTextureObject *

_lookupTexture(const DDSFile * ddsFile, const GFXTextureProfile * profile)

void

_onFileChanged(const Torque::Path & path)

void

_validateTexParams(const U32 width, const U32 height, const GFXTextureProfile * profile, U32 & inOutNumMips, GFXFormat & inOutFormat)

Validate the parameters for creating a texture.
void

freeTexture(GFXTextureObject * texture, bool zombify)

Frees the API handles to the texture, for D3D this is a release call.
GFXTextureObject *

hashFind(const String & name)

void

hashInsert(GFXTextureObject * object)

void

hashRemove(GFXTextureObject * object)

void

refreshTexture(GFXTextureObject * texture)

Detailed Description
Texture Necromancy
Texture necromancy in three easy steps:
  • If you want to destroy the texture manager, call kill().
  • If you want to switch resolutions, or otherwise reset the device, call zombify().
  • When you want to bring the manager back from zombie state, call resurrect().
kill()

zombify()

resurrect()

cleanupPool()

This releases any pooled textures which are currently unused freeing up video memory.
reloadTextures()

cleanupCache(U32 secondsToLive)

This releases cached textures that have not been referenced for a period of time.
addEventDelegate(T obj, U func)

Registers a callback for texture zombify and resurrect events.
see:
GFXTexCallbackCode
see:
removeEventDelegate
removeEventDelegate(T obj, U func)

Unregisteres a texture event callback.
see:
addEventDelegate
Public User Defined
_createTextureObject(U32 height, U32 width, U32 depth, GFXFormat format, GFXTextureProfile * profile, U32 numMipLevels, bool forceMips, S32 antialiasLevel, GFXTextureObject * inTex)

@group Internal Texture Manager Interface
These pure virtual functions are overloaded by each API-specific subclass.
The order of calls is:
_createTexture()
_loadTexture
_refreshTexture()
_refreshTexture()
_refreshTexture()
...
_freeTexture()

Allocate a texture with the internal API.
Parameters:
height
Height of the texture.
width
Width of the texture.
depth
Depth of the texture. (Will normally be 1 unless we are doing a cubemap or volumetexture.)
format
Pixel format of the texture.
profile
Profile for the texture.
numMipLevels
If not-NULL, then use that many mips. If NULL create the full mip chain
Use
GFXTextureManager::AA_MATCH_BACKBUFFER to match the backbuffer settings (for render targets that want to share the backbuffer z buffer. 0 for no antialiasing, > 0 for levels that match the GFXVideoMode struct.
Reimplemented by: GFXD3D11TextureManager, GFXGLTextureManager, GFXNullTextureManager
_loadTexture(GFXTextureObject * texture, DDSFile * dds)

Load a texture from a proper DDSFile instance.
Reimplemented by: GFXD3D11TextureManager, GFXGLTextureManager, GFXNullTextureManager
_loadTexture(GFXTextureObject * texture, GBitmap * bmp)

Load data into a texture from a GBitmap using the internal API.
Reimplemented by: GFXD3D11TextureManager, GFXGLTextureManager, GFXNullTextureManager
_loadTexture(GFXTextureObject * texture, void * raw)

Load data into a texture from a raw buffer using the internal API.
Note that the size of the buffer is assumed from the parameters used for this GFXTextureObject's _createTexture call.
Reimplemented by: GFXD3D11TextureManager, GFXGLTextureManager, GFXNullTextureManager
_refreshTexture(GFXTextureObject * texture)

Refresh a texture using the internal API.
Reimplemented by: GFXD3D11TextureManager, GFXGLTextureManager, GFXNullTextureManager
_freeTexture(GFXTextureObject * texture, bool zombify)

Free a texture (but do not delete the GFXTextureObject) using the internal API.
This is only called during zombification for textures which need it, so you don't need to do any internal safety checks.
Reimplemented by: GFXD3D11TextureManager, GFXGLTextureManager, GFXNullTextureManager
Public Types
@85

Enumerator
AA_MATCH_BACKBUFFER = -1
Protected Types
TextureManagerState

Enumerator
Living 
Zombie 
Dead 
typedef HashTable< String, GFXCubemap * > CubemapTable 

typedef Signal< void(GFXTexCallbackCode code)> EventSignal 

The texture event signal type.
typedef HashTable< GFXTextureProfile *, StrongRefPtr< GFXTextureObject > > TexturePoolMap 

The texture pool collection type.
Public Static Attributes
S32 smTextureReductionLevel 

The amount of texture mipmaps to skip when loading a texture that allows downscaling.
Exposed to script via $pref::Video::textureReductionLevel.
see:
GFXTextureProfile::PreserveSize
Protected Static Attributes
String smBRDFTexturePath 

String smDefaultIrradianceCubemapPath 

String smDefaultPrefilterCubemapPath 

EventSignal smEventSignal 

The texture event signal.
String smMissingTexturePath 

File path to the missing texture.
String smUnavailableTexturePath 

File path to the unavailable texture.
Often used by GUI controls when the requested image is not available.
String smWarningTexturePath 

File path to the warning texture.
Protected Attributes
CubemapTable mCubemapTable 

U32 mHashCount 

GFXTextureObject ** mHashTable 

GFXTextureObject * mListHead 

GFXTextureObject * mListTail 

enum GFXTextureManager::TextureManagerState mTextureManagerState 

TexturePoolMap mTexturePool 

All the allocated texture pool textures.
Vector< GFXTextureObject * > mToDelete 

The textures waiting to be deleted.
Public Functions
GFXTextureManager()

~GFXTextureManager()

createCompositeTexture(const Torque::Path & pathR, const Torque::Path & pathG, const Torque::Path & pathB, const Torque::Path & pathA, U32 inputKey, GFXTextureProfile * profile)

createCompositeTexture(GBitmap * bmp, U32 inputKey, const String & resourceName, GFXTextureProfile * profile, bool deleteBmp)

createCubemap(const Torque::Path & path)

Load a cubemap from a texture file.
createTexture(const Torque::Path & path, GFXTextureProfile * profile)

createTexture(DDSFile * dds, GFXTextureProfile * profile, bool deleteDDS)

createTexture(GBitmap * bmp, const String & resourceName, GFXTextureProfile * profile, bool deleteBmp)

createTexture(U32 width, U32 height, GFXFormat format, GFXTextureProfile * profile, U32 numMipLevels, S32 antialiasLevel)

createTexture(U32 width, U32 height, U32 depth, GFXFormat format, GFXTextureProfile * profile, U32 numMipLevels)

createTexture(U32 width, U32 height, void * pixels, GFXFormat format, GFXTextureProfile * profile)

deleteTexture(GFXTextureObject * texture)

loadUncompressedTexture(const Torque::Path & path, GFXTextureProfile * profile)

loadUncompressedTexture(const Torque::Path & path, GFXTextureProfile * profile, U32 width, U32 height, bool genMips)

releaseCubemap(GFXCubemap * cubemap)

Used to remove a cubemap from the cache.
reloadTexture(GFXTextureObject * texture)

requestDeleteTexture(GFXTextureObject * texture)

Request that the texture be deleted which will either occur immediately or delayed if its cached.
saveCompositeTexture(const Torque::Path & pathR, const Torque::Path & pathG, const Torque::Path & pathB, const Torque::Path & pathA, U32 inputKey, const Torque::Path & saveAs, GFXTextureProfile * profile)

validatePath(const Torque::Path & path)

validateTextureQuality(GFXTextureProfile * profile, U32 & width, U32 & height)

Update width and height based on available resources.
We provide a simple interface for managing texture memory usage. Specifically, if the total video memory is below a certain threshold, we scale all texture resolutions down by a specific factor (you can specify different scale factors for different types of textures).
note:
The base GFXTextureManager class provides all the logic to do this scaling. Subclasses need only implement getTotalVideoMemory().
Parameters:
type
Type of the requested texture. This is used to determine scaling factors.
width
Requested width - is changed to the actual width that should be used.
height
Requested height - is changed to the actual height that should be used.
return:
True if the texture request should be granted, false otherwise.
Public Static Functions
getBRDFTexturePath()

getDefaultIrradianceCubemapPath()

getDefaultPrefilterCubemapPath()

getMissingTexturePath()

Provide the path to the texture to use when the requested one is missing.
getTextureDownscalePower(GFXTextureProfile * profile)

getUnavailableTexturePath()

Provide the path to the texture to use when the requested one is unavailable.
getWarningTexturePath()

Provide the path to the texture used to warn the developer.
init()

Set up some global script interface stuff.
Protected Functions
_createTexture(DDSFile * dds, GFXTextureProfile * profile, bool deleteDDS, GFXTextureObject * inObj)

_createTexture(GBitmap * bmp, const String & resourceName, GFXTextureProfile * profile, bool deleteBmp, GFXTextureObject * inObj)

_findPooledTexure(U32 width, U32 height, GFXFormat format, GFXTextureProfile * profile, U32 numMipLevels, S32 antialiasLevel)

Returns a free texture of the requested attributes from from the shared texture pool.
It returns NULL if no match is found.
_linkTexture(GFXTextureObject * obj)

Store texture into the hash table cache and linked list.
_lookupTexture(const char * filename, const GFXTextureProfile * profile)

_lookupTexture(const DDSFile * ddsFile, const GFXTextureProfile * profile)

_onFileChanged(const Torque::Path & path)

_validateTexParams(const U32 width, const U32 height, const GFXTextureProfile * profile, U32 & inOutNumMips, GFXFormat & inOutFormat)

Validate the parameters for creating a texture.
freeTexture(GFXTextureObject * texture, bool zombify)

Frees the API handles to the texture, for D3D this is a release call.
note:
freeTexture MUST NOT DELETE THE TEXTURE OBJECT
hashFind(const String & name)

hashInsert(GFXTextureObject * object)

hashRemove(GFXTextureObject * object)

refreshTexture(GFXTextureObject * texture)