OGRE: Ogre::HlmsTextureManager Class Reference

| OGRE 2.2.4 Object-Oriented Graphics Rendering Engine

Classes | Public Types | Public Member Functions | List of all members
Ogre::HlmsTextureManager Class Reference
Core » Resources

HLMS Texture Manager manages textures in the way HLMS expects. More...

`#include <OgreHlmsTextureManager.h>`

Inheritance diagram for Ogre::HlmsTextureManager:
[legend]

## Classes
struct | DefaultTextureParameters
struct | MetadataCacheEntry
struct | TextureLocation
struct | Threshold
| Textures whose size are less or equal to minTextureSize (without considering mipmaps) will have their maxTexturesPerArray clamped to the value given in this threshold structure. More...

## Public Types
typedef map< IdString, MetadataCacheEntry >::type | MetadataCacheMap
enum | PackingMethod { TextureArrays, Atlas }
enum | TextureMapType { TEXTURE_TYPE_DIFFUSE, TEXTURE_TYPE_MONOCHROME, TEXTURE_TYPE_NORMALS, TEXTURE_TYPE_ENV_MAP, TEXTURE_TYPE_DETAIL, TEXTURE_TYPE_DETAIL_NORMAL_MAP, TEXTURE_TYPE_NON_COLOR_DATA, NUM_TEXTURE_TYPES }
typedef vector< Threshold >::type | ThresholdVec

## Public Member Functions
| HlmsTextureManager ()
virtual | ~HlmsTextureManager ()
void | _changeRenderSystem (RenderSystem *newRs)
| Called when the RenderSystem changes. More...
void | clearTextureMetadataCache (void)
void | createFromTexturePack (const HlmsTexturePack &pack)
TextureLocation | createOrRetrieveTexture (const String &aliasName, const String &texName, TextureMapType mapType, uint32 uniqueSpecialId=0, Image *imgSource=0)
| See other overload. More...
TextureLocation | createOrRetrieveTexture (const String &texName, TextureMapType mapType)
| Create a texture based on its name. More...
void | destroyTexture (IdString aliasName)
| Destroys a texture. More...
void | dumpMemoryUsage (Log *log=NULL) const
| Dumps to the Ogre log passed as parameter (if NULL, uses the default one) in csv format (separator is '|') the usage statistics of all textures currently loaded by the texture manager. More...
void | exportTextureMetadataCache (String &outJson)
const String * | findAliasName (const TextureLocation &textureLocation) const
| Finds the alias name of a texture given its TextureLocation. More...
const String * | findResourceNameFromAlias (IdString aliasName) const
const String * | findResourceNameFromAlias (IdString aliasName, uint32 &outPoolId) const
| Output outPoolId is left untouched if returned pointer is null. More...
TextureLocation | getBlankTexture (void) const
| Returns the precreated blank texture. More...
DefaultTextureParameters * | getDefaultTextureParameters (void)
const HlmsTextureManager::MetadataCacheEntry * | getMetadataCacheEntry (IdString aliasName) const
| Retrieves an entry in the metadata cache that was loaded via HlmsTextureManager::importTextureMetadataCache. More...
HlmsTextureManager::MetadataCacheMap & | getTextureMetadataCache (void)
bool | hasPoolId (uint32 uniqueSpecialId, TextureMapType mapType) const
void | importTextureMetadataCache (const String &filename, const char *jsonString)
void | initialize (void)
void | operator delete (void *ptr)
void | operator delete (void *ptr, const char *, int, const char *)
void | operator delete (void *ptr, void *)
void | operator delete[] (void *ptr)
void | operator delete[] (void *ptr, const char *, int, const char *)
void * | operator new (size_t sz)
void * | operator new (size_t sz, const char *file, int line, const char *func)
| operator new, with debug line info More...
void * | operator new (size_t sz, void *ptr)
| placement operator new More...
void * | operator new[] (size_t sz)
void * | operator new[] (size_t sz, const char *file, int line, const char *func)
| array operator new, with debug line info More...
TexturePtr | reservePoolId (uint32 uniqueSpecialId, TextureMapType mapType, uint32 width, uint32 height, uint16 numSlices, uint8 numMipmaps, PixelFormat pixelFormat, bool isNormalMap, bool hwGammaCorrection)
| Reserves a specific pool ID with the given parameters and immediately creates that texture. More...
void | saveTexture (const HlmsTextureManager::TextureLocation &texLocation, const String &folderPath, set< String >::type &savedTextures, bool saveOitd, bool saveOriginal, uint32 slice, uint32 numSlices, HlmsTextureExportListener *listener)
| Saves a texture to the given folder. More...

## Detailed Description

HLMS Texture Manager manages textures in the way HLMS expects.

  Most HLMS implementations, when creating a datablock/material with a texture, you can't remove the texture or use a null ptr texture; either you create a new datablock, or use an empty dummy texture. This manager ensures you always get at least a dummy texture.

  Its other main job is to provide UV atlas on the fly and/or texture arrays on the fly. To do that, we group textures into categories: @TEXTURE_TYPE_DIFFUSE @TEXTURE_TYPE_MONOCHROME @TEXTURE_TYPE_NORMALS @TEXTURE_TYPE_ENV_MAP @TEXTURE_TYPE_DETAIL @TEXTURE_TYPE_DETAIL_NORMAL_MAP @TEXTURE_TYPE_NON_COLOR_DATA Different categories have different default parameters. By default all types try to use array textures unless the RenderSystem API doesn't support it (in which case fallbacks to UV atlas).

  For example, Diffuse & detail textures enable hardware gamma correction. Normal maps attempt to use BC5 compression, or uncompress UV8, in that order (depends on HW support). Detail maps default to not using UV atlas when texture arrays aren't supported (because detail maps are often meant to be tileable), etc

## Member Typedef Documentation

## ◆ MetadataCacheMap

typedef map<IdString, MetadataCacheEntry>::type Ogre::HlmsTextureManager::MetadataCacheMap

## ◆ ThresholdVec

typedef vector<Threshold>::type Ogre::HlmsTextureManager::ThresholdVec

## Member Enumeration Documentation

## ◆ PackingMethod

enum Ogre::HlmsTextureManager::PackingMethod

Enumerator
TextureArrays |
Atlas |

## ◆ TextureMapType

enum Ogre::HlmsTextureManager::TextureMapType

Enumerator
TEXTURE_TYPE_DIFFUSE |
TEXTURE_TYPE_MONOCHROME |
TEXTURE_TYPE_NORMALS |
TEXTURE_TYPE_ENV_MAP |
TEXTURE_TYPE_DETAIL |
TEXTURE_TYPE_DETAIL_NORMAL_MAP |
TEXTURE_TYPE_NON_COLOR_DATA |
NUM_TEXTURE_TYPES |

## Constructor & Destructor Documentation

## ◆ HlmsTextureManager()

Ogre::HlmsTextureManager::HlmsTextureManager | ( |  | ) |

## ◆ ~HlmsTextureManager()

virtual Ogre::HlmsTextureManager::~HlmsTextureManager | ( |  | ) |
| virtual

## Member Function Documentation

## ◆ _changeRenderSystem()

void Ogre::HlmsTextureManager::_changeRenderSystem | ( | RenderSystem * | newRs | ) |

Called when the RenderSystem changes.

Remarks
  Some settings in mDefaultTextureParameters will be reset

## ◆ clearTextureMetadataCache()

void Ogre::HlmsTextureManager::clearTextureMetadataCache | ( | void |  | ) |

## ◆ createFromTexturePack()

void Ogre::HlmsTextureManager::createFromTexturePack | ( | const HlmsTexturePack & | pack | ) |

## ◆ createOrRetrieveTexture() [1/2]

TextureLocation Ogre::HlmsTextureManager::createOrRetrieveTexture | ( | const String & | aliasName,
|  | const String & | texName,
|  | TextureMapType | mapType,
|  | uint32 | uniqueSpecialId = `0`,
|  | Image * | imgSource = `0`
| ) |  |

See other overload.

This one allows aliasing a texture. If you have "VERY_TECHNICAL_NAME_HASH_1234.png" as texName, you can make your first call with aliasName as "Tree Wood", and the next calls to createOrRetrieveTexture( "Tree Wood", mapType ) will refer to this texture NOTE: aliasName cannot be blank/empty.

Parameters

  uniqueSpecialId | Textures loaded with a value uniqueSpecialId != 0 will tried to be pooled together inside the same pool that has the same uniqueSpecialId. If we have to create more than one pool, you will get log warnings. This pool ID is intended for Decals and Area Lights as Ogre implementations only allow one global texture per pass; thus all decal/area light texture must have the same resolution, pixel format and live in the same array texture. See HlmsTextureManager::reservePoolId
  imgSource | When null, texture is loaded from texName as a file. When not null, texture is loaded from imgSource and texName is ignored (still used in logging messages though). Note imgSource may be modified (e.g. to generate mipmaps). Note this pointer is ignored if the texture already exists and is just being retrieved.

## ◆ createOrRetrieveTexture() [2/2]

TextureLocation Ogre::HlmsTextureManager::createOrRetrieveTexture | ( | const String & | texName,
|  | TextureMapType | mapType
| ) |  |

Create a texture based on its name.

If a texture with such name has already been created, retrieves the existing one.

Parameters

  texName | Name of the texture (e.g. "myTextureFile.dds" "penguin.jpg")
  mapType | The type of texture map this texture is going to be. See the class overview documentation for an explanation of the differences. If the texture has already been created, this parameter is ignored.

Returns
  retVal.texture The texture that should be bound

if packingMethond == TextureArrays retVal.xIdx: The array index in the texture array. if packingMethond == Atlas retVal.xIdx: The U offset to apply to UVs retVal.yIdx: The V offset to apply to UVs retVal.divisor: The value the original UVs have to be divided for

## ◆ destroyTexture()

void Ogre::HlmsTextureManager::destroyTexture | ( | IdString | aliasName | ) |

Destroys a texture.

If the array has multiple entries, the entry for this texture is sent back to a waiting list for a future new entry. Trying to read from this texture after this call may result in garbage.

## ◆ dumpMemoryUsage()

void Ogre::HlmsTextureManager::dumpMemoryUsage | ( | Log * | log = `NULL` | ) | const

Dumps to the Ogre log passed as parameter (if NULL, uses the default one) in csv format (separator is '|') the usage statistics of all textures currently loaded by the texture manager.

Useful for profiling or determining sources of waste GPU RAM.

## ◆ exportTextureMetadataCache()

void Ogre::HlmsTextureManager::exportTextureMetadataCache | ( | String & | outJson | ) |

## ◆ findAliasName()

const String* Ogre::HlmsTextureManager::findAliasName | ( | const TextureLocation & | textureLocation | ) | const

Finds the alias name of a texture given its TextureLocation.

Useful for retrieving back the name of a texture as it was called via createOrRetrieveTexture. Returns null if not found. Note the returned pointer may be invalidated if new calls are made to createOrRetrieveTexture or destroyTexture

## ◆ findResourceNameFromAlias() [1/2]

const String* Ogre::HlmsTextureManager::findResourceNameFromAlias | ( | IdString | aliasName | ) | const

## ◆ findResourceNameFromAlias() [2/2]

const String* Ogre::HlmsTextureManager::findResourceNameFromAlias | ( | IdString | aliasName,
|  | uint32 & | outPoolId
| ) |  | const

Output outPoolId is left untouched if returned pointer is null.

## ◆ getBlankTexture()

TextureLocation Ogre::HlmsTextureManager::getBlankTexture | ( | void |  | ) | const

Returns the precreated blank texture.

## ◆ getDefaultTextureParameters()

DefaultTextureParameters* Ogre::HlmsTextureManager::getDefaultTextureParameters | ( | void |  | ) |
| inline

## ◆ getMetadataCacheEntry()

const HlmsTextureManager::MetadataCacheEntry* Ogre::HlmsTextureManager::getMetadataCacheEntry | ( | IdString | aliasName | ) | const

Retrieves an entry in the metadata cache that was loaded via HlmsTextureManager::importTextureMetadataCache.

Note that this texture may not even have been ever loaded yet.

Parameters

  aliasName | Alias of the resource.

Returns
  Null if not found. The cache entry otherwise.

## ◆ getTextureMetadataCache()

HlmsTextureManager::MetadataCacheMap& Ogre::HlmsTextureManager::getTextureMetadataCache | ( | void |  | ) |
| inline

## ◆ hasPoolId()

bool Ogre::HlmsTextureManager::hasPoolId | ( | uint32 | uniqueSpecialId,
|  | TextureMapType | mapType
| ) |  | const

## ◆ importTextureMetadataCache()

void Ogre::HlmsTextureManager::importTextureMetadataCache | ( | const String & | filename,
|  | const char * | jsonString
| ) |  |

## ◆ initialize()

void Ogre::HlmsTextureManager::initialize | ( | void |  | ) |

## ◆ operator delete() [1/3]

template<class Alloc >

void Ogre::AllocatedObject< Alloc >::operator delete | ( | void * | ptr | ) |
| inlineinherited

## ◆ operator delete() [2/3]

template<class Alloc >

void Ogre::AllocatedObject< Alloc >::operator delete | ( | void * | ptr,
|  | const char * | ,
|  | int | ,
|  | const char * |
| ) |  |
| inlineinherited

## ◆ operator delete() [3/3]

template<class Alloc >

void Ogre::AllocatedObject< Alloc >::operator delete | ( | void * | ptr,
|  | void * |
| ) |  |
| inlineinherited

## ◆ operator delete[]() [1/2]

template<class Alloc >

void Ogre::AllocatedObject< Alloc >::operator delete[] | ( | void * | ptr | ) |
| inlineinherited

## ◆ operator delete[]() [2/2]

template<class Alloc >

void Ogre::AllocatedObject< Alloc >::operator delete[] | ( | void * | ptr,
|  | const char * | ,
|  | int | ,
|  | const char * |
| ) |  |
| inlineinherited

## ◆ operator new() [1/3]

template<class Alloc >

void* Ogre::AllocatedObject< Alloc >::operator new | ( | size_t | sz | ) |
| inlineinherited

## ◆ operator new() [2/3]

template<class Alloc >

void* Ogre::AllocatedObject< Alloc >::operator new | ( | size_t | sz,
|  | const char * | file,
|  | int | line,
|  | const char * | func
| ) |  |
| inlineinherited

operator new, with debug line info

## ◆ operator new() [3/3]

template<class Alloc >

void* Ogre::AllocatedObject< Alloc >::operator new | ( | size_t | sz,
|  | void * | ptr
| ) |  |
| inlineinherited

placement operator new

## ◆ operator new[]() [1/2]

template<class Alloc >

void* Ogre::AllocatedObject< Alloc >::operator new[] | ( | size_t | sz | ) |
| inlineinherited

## ◆ operator new[]() [2/2]

template<class Alloc >

void* Ogre::AllocatedObject< Alloc >::operator new[] | ( | size_t | sz,
|  | const char * | file,
|  | int | line,
|  | const char * | func
| ) |  |
| inlineinherited

array operator new, with debug line info

## ◆ reservePoolId()

TexturePtr Ogre::HlmsTextureManager::reservePoolId | ( | uint32 | uniqueSpecialId,
|  | TextureMapType | mapType,
|  | uint32 | width,
|  | uint32 | height,
|  | uint16 | numSlices,
|  | uint8 | numMipmaps,
|  | PixelFormat | pixelFormat,
|  | bool | isNormalMap,
|  | bool | hwGammaCorrection
| ) |  |

Reserves a specific pool ID with the given parameters and immediately creates that texture.

Parameters

  uniqueSpecialId |
  mapType |
  width |
  height |
  numSlices |
  numMipmaps |
  pixelFormat |
  isNormalMap |
  hwGammaCorrection |

Returns
  Created texture for the pool.

## ◆ saveTexture()

void Ogre::HlmsTextureManager::saveTexture | ( | const HlmsTextureManager::TextureLocation & | texLocation,
|  | const String & | folderPath,
|  | set< String >::type & | savedTextures,
|  | bool | saveOitd,
|  | bool | saveOriginal,
|  | uint32 | slice,
|  | uint32 | numSlices,
|  | HlmsTextureExportListener * | listener
| ) |  |

Saves a texture to the given folder.

Even if the texture was not created by HlmsTextureManager.

We will not save RenderTargets.

If the texture is managed by HlmsTextureManager, further information to obtain the original filename (even if it's aliased) will be used.

Parameters

  texLocation |
  folderPath | Folder where to dump the textures.
  savedTextures | [in/out] Set of texture names. Textures whose name is already in the set won't be saved again. Textures that were saved will be inserted into the set.
  saveOitd | When true, we will download the texture from GPU and save it in OITD format. OITD is faster to load as it's stored in Ogre's native format it understands, but it cannot be opened by traditional image editors; also OITD is not backwards compatible with older versions of Ogre.
  saveOriginal | When true, we will attempt to read the raw filestream of the original texture and save it (i.e. copy the original png/dds/etc file).
  listener |

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

- OgreHlmsTextureManager.h