TurtleBrains  0.3.5
High quality, portable, C++ framework for rapid 2D game development.
TurtleBrains::Graphics::TextureManager Class Reference

#include <tb_texture_manager.hpp>

Inheritance diagram for TurtleBrains::Graphics::TextureManager:
TurtleBrains::Core::Noncopyable

Public Member Functions

TextureHandle CreateTextureFromFile (const tbCore::tbString &filename)
 
TextureHandle CreateTextureFromFileData (const unsigned char *fileDataInMemory, const size_t &fileSizeInBytes)
 
TextureHandle CreateTextureFromPixelData (const unsigned char *pixelDataARGB, const PixelSpace &textureWidth, const PixelSpace &textureHeight)
 
TextureHandle CreateTextureEmpty (const PixelSpace &textureWidth, const PixelSpace &textureHeight, const TextureFormat &format=TextureFormat::ColorARGB8)
 
TextureHandle CreateTextureReference (const TextureHandle &textureHandle)
 
void DestroyTexture (const TextureHandle &textureHandle)
 
void BindTexture (const TextureHandle &textureHandle)
 
void BindTexture (const TextureHandle &textureHandle, tbCore::uint8 textureUnit)
 
PixelSpace GetTextureWidth (const TextureHandle &textureHandle) const
 
PixelSpace GetTextureHeight (const TextureHandle &textureHandle) const
 
void SetTextureWrapMode (const TextureHandle &textureHandle, TextureWrapMode wrapMode)
 
void SetTextureWrapMode (const TextureHandle &textureHandle, TextureWrapMode wrapModeU, TextureWrapMode wrapModeV)
 
tbCore::uint64 ComputeMemoryUsage (void) const
 
void CreateGraphicsContext (void)
 
void DestroyGraphicsContext (void)
 

Static Public Member Functions

static void PreMultiplyAlpha (tbCore::byte *imageData, const PixelSpace &imageWidth, const PixelSpace &imageHeight)
 

Friends

class tbImplementation::TextureManagerCreator
 

Detailed Description

A basic texture manager to load images from disk or file/pixel data in memory while using a caching technique so using the same file path will not create more textures. TurtleBrains makes use of Sean Barrett's stb_image API to process the file, which supports the following file formats with some limitations:

  • JPEG baseline (no JPEG progressive)
  • PNG 8-bit-per-channel only
  • TGA (not sure what subset, if a subset)
  • BMP non-1bpp, non-RLE
  • PSD (composited view only, no extra channels)
  • GIF (*comp always reports as 4-channel)
  • HDR (radiance rgbE format)
  • PIC (Softimage PIC)

Member Function Documentation

void TurtleBrains::Graphics::TextureManager::BindTexture ( const TextureHandle textureHandle)

Binds the texture associated with the textureHandle to the GL context for rendering calls. An error condition will be triggered if textureHandle is the handle was not initialized or the associated texture has been destroyed.

Parameters
textureHandleof the texture to apply to the GL context.
void TurtleBrains::Graphics::TextureManager::BindTexture ( const TextureHandle textureHandle,
tbCore::uint8  textureUnit 
)

Binds the texture associated with the textureHandle to the GL context for rendering calls. An error condition will be triggered if textureHandle is the handle was not initialized or the associated texture has been destroyed.

Parameters
textureHandleof the texture to apply to the GL context.
textureUnitWhich texture unit will be the handle be bound to.
tbCore::uint64 TurtleBrains::Graphics::TextureManager::ComputeMemoryUsage ( void  ) const

Returns the number of bytes in memory from all textures currently loaded in the manager/texture cache.

Note
May not count texture memory loaded from ALL other sources, such as the RenderTargets objects.
void TurtleBrains::Graphics::TextureManager::CreateGraphicsContext ( void  )

When a new Graphics Context is created this should be called to allow the TextureManager to reload any managed textures to the context, and create any generated textures for generaly use like the Blank Texture.

TextureHandle TurtleBrains::Graphics::TextureManager::CreateTextureEmpty ( const PixelSpace textureWidth,
const PixelSpace textureHeight,
const TextureFormat format = TextureFormat::ColorARGB8 
)

Creates a texture with specified width and height then sets all the pixels to white. Textures created empty do not get cached, so be aware that calling this several times with the same width/height will create new textures. Any texture created must be cleaned up by calling DestroyTexture().

Parameters
textureWidthis the width of the texture to be created, in pixels, must be greater than 0.
textureHeightis the height of the texture to be created, in pixels, must be greater than 0.
Note
to create multiple references to the texture created by empty pixel data you can use CreateTextureReference().
TextureHandle TurtleBrains::Graphics::TextureManager::CreateTextureFromFile ( const tbCore::tbString filename)

Checks the cache if the file has already been opened, if not, the file will be opened from disk and processed creating an ARGB texture with OpenGL. Any texture created must be cleaned up by calling DestroyTexture. Although the texture may not actually be destroyed if there are still others referencing the texture object (via other calls to CreateTextureFromFile).

Parameters
filenamethe path of the file to open and process.
TextureHandle TurtleBrains::Graphics::TextureManager::CreateTextureFromFileData ( const unsigned char *  fileDataInMemory,
const size_t &  fileSizeInBytes 
)

Creates a texture from the data of a file already in memory, this is not the uncompressed pixel data. Textures created from file data do not get cached, so be aware that calling this several times with the same file data will create new textures. Any texture created must be cleaned up by calling DestroyTexture().

Parameters
fileDataInMemoryshould contain an entire supported file in memory which can be removed after the call.
fileSizeInBytesis how many bytes make up the file.
Note
to create multiple references to the texture created by file data you can use CreateTextureReference().
TextureHandle TurtleBrains::Graphics::TextureManager::CreateTextureFromPixelData ( const unsigned char *  pixelDataARGB,
const PixelSpace textureWidth,
const PixelSpace textureHeight 
)

Creates a texture from the data of each pixel color, this is the uncompressed 32bit ARGB pixel data format. A 1x1 texture would be 4 bytes, first byte Alpha, second Red, then Green and final byte Blue. Textures created from pixel data do not get cached, so be aware that calling this several times with the same pixel data will create new textures. Any texture created must be cleaned up by calling DestroyTexture().

Parameters
pixelDataARGBmust contain at least (textureWidth * textureHeight * 4) bytes of data for each byte.
textureWidthis the width of the supplied pixelData in pixels wide, must be greater than 0.
textureHeightis the height of the supplied pixelData in pixels tall, must be greater than 0.
Note
to create multiple references to the texture created by pixel data you can use CreateTextureReference().
TextureHandle TurtleBrains::Graphics::TextureManager::CreateTextureReference ( const TextureHandle textureHandle)

This does not actually create a texture but will increase the reference count so it does not get unloaded/cleaned on the call to DestroyTexture. This is meant to allow textured created by file data or pixel data to be shared more easily in the reference counted manner. Any texture created must be cleaned up by calling DestroyTexture().

Parameters
textureHandleThe texture associated with this handle will increment the reference count and be returned back. Must be a valid TextureHandle or an error condition will be triggered.
void TurtleBrains::Graphics::TextureManager::DestroyGraphicsContext ( void  )

This should be called just before the graphics context is destroyed so the TextureManager can cleanup any resources and deal with the managed textures.

void TurtleBrains::Graphics::TextureManager::DestroyTexture ( const TextureHandle textureHandle)

Decrements the textures reference count and if needed will destroys the texture, removing it from the OpenGL pipeline and cleaning any other associated resources. Each texture handle is reference counted, so every call to Create needs a matching call to destroy.

Parameters
textureHandleof the texture to destroy and remove completely from the GL context and TextureManager.
PixelSpace TurtleBrains::Graphics::TextureManager::GetTextureHeight ( const TextureHandle textureHandle) const

Returns the width of the texture associated with the textureHandle provided. If InvalidTexture() is provided 0 will be returned. An error condition will be triggered if textureHandle is the handle was not initialized or the associated texture has been destroyed.

PixelSpace TurtleBrains::Graphics::TextureManager::GetTextureWidth ( const TextureHandle textureHandle) const

Returns the width of the texture associated with the textureHandle provided. If InvalidTexture() is provided 0 will be returned. An error condition will be triggered if textureHandle is the handle was not initialized or the associated texture has been destroyed.

static void TurtleBrains::Graphics::TextureManager::PreMultiplyAlpha ( tbCore::byte imageData,
const PixelSpace imageWidth,
const PixelSpace imageHeight 
)
static

This will take the imageData in ARGB format, and pre-multiplies the RGB channels by the alpha channel since the TurtleBrains shader and blend mode is set for premultiplied alpha.

Parameters
imageDataThe data to be modified in place.
imageWidthThe width of the image in pixels.
imageHightThe height of the image in pixels.
void TurtleBrains::Graphics::TextureManager::SetTextureWrapMode ( const TextureHandle textureHandle,
TextureWrapMode  wrapMode 
)

Set the TextureWrapMode for a specific texture to change how the U and V coordinates behave outside the 0 to 1 range.

textureHandle The texture to change the wrap mode for, if not bound this may incur state changes but previously bound texture will remain bound after finished. wrapMode The mode to use for both U and V coordinates. wrapModeU The mode to use for the horizontal U coordinates. wrapModeV The mode to use for the vertical V coordinates.

void TurtleBrains::Graphics::TextureManager::SetTextureWrapMode ( const TextureHandle textureHandle,
TextureWrapMode  wrapModeU,
TextureWrapMode  wrapModeV 
)

Set the TextureWrapMode for a specific texture to change how the U and V coordinates behave outside the 0 to 1 range.

textureHandle The texture to change the wrap mode for, if not bound this may incur state changes but previously bound texture will remain bound after finished. wrapMode The mode to use for both U and V coordinates. wrapModeU The mode to use for the horizontal U coordinates. wrapModeV The mode to use for the vertical V coordinates.