TurtleBrains::Graphics::TextureManager Class Reference

#include <tb_texture_manager.hpp>

Inheritance diagram for TurtleBrains::Graphics::TextureManager:

Public Member Functions
TextureHandle	CreateTextureFromFile (const String &filename, const bool mipmapped=true)
TextureHandle	CreateTextureFromFileData (const unsigned char *fileDataInMemory, const tbCore::uint32 fileSizeInBytes, const bool mipmapped=true)
TextureHandle	CreateTextureFromPixelData (const PixelSpace &textureWidth, const PixelSpace &textureHeight, const TextureFormat &format, const unsigned char *pixelData, const bool mipmapped=true)
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)
void	SetTextureFiltering (const TextureHandle &textureHandle, TextureFilter filter)
void	CheckAndReloadTextures (void)
void	Unstable_RunSoftwareShader (const TextureHandle &textureHandle, std::function< tbCore::uint32(PixelSpace x, PixelSpace y, tbCore::uint32)> shader)
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	Implementation::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

BindTexture() [1/2]

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

textureHandle

of the texture to apply to the GL context.

BindTexture() [2/2]

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

textureHandle	of the texture to apply to the GL context.
textureUnit	Which texture unit will be the handle be bound to.

CheckAndReloadTextures()

void TurtleBrains::Graphics::TextureManager::CheckAndReloadTextures

(

void

)

For hot-reloading support.

ComputeMemoryUsage()

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.

CreateGraphicsContext()

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.

CreateTextureEmpty()

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

textureWidth	is the width of the texture to be created, in pixels, must be greater than 0.
textureHeight	is 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().

Due to the nature of all pixels being identical this does not generate mipmaps and the texture filtering will reflect that by default; if mipmaps are later generated the filtering will need to be updated too.

CreateTextureFromFile()

TextureHandle TurtleBrains::Graphics::TextureManager::CreateTextureFromFile	(	const String &	filename,
		const bool	mipmapped = true
	)

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

filename	the path of the file to open and process.
mipmapped	determines if the texture should be mipmapped or not.

CreateTextureFromFileData()

TextureHandle TurtleBrains::Graphics::TextureManager::CreateTextureFromFileData	(	const unsigned char *	fileDataInMemory,
		const tbCore::uint32	fileSizeInBytes,
		const bool	mipmapped = true
	)

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

fileDataInMemory	should contain an entire supported file in memory which can be removed after the call.
fileSizeInBytes	is how many bytes make up the file.
mipmapped	determines if the texture should be mipmapped or not.

Note

to create multiple references to the texture created by file data you can use CreateTextureReference().

CreateTextureFromPixelData()

TextureHandle TurtleBrains::Graphics::TextureManager::CreateTextureFromPixelData	(	const PixelSpace &	textureWidth,
		const PixelSpace &	textureHeight,
		const TextureFormat &	format,
		const unsigned char *	pixelData,
		const bool	mipmapped = true
	)

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

textureWidth	is the width of the supplied pixelData in pixels wide, must be greater than 0.
textureHeight	is the height of the supplied pixelData in pixels tall, must be greater than 0.
format	What format the texture should be (as well, somewhat, the input; may be mixed for formats that have partial bytes, like A2R5G5B3 might actually want input of A8R8G8B8 for simplicity...)
pixelData	must contain at least (textureWidth * textureHeight * 4) bytes of data for each pixel assuming a texture format of ColorARGB8. For any float textures, provide a float32 per pixel/channel and it will be converted as it loads into the GPU.
mipmapped	determines if the texture should be mipmapped or not.

Note

to create multiple references to the texture created by pixel data you can use CreateTextureReference().

Prior to summer 2023 the function took pixelData, width, height and now uses width, height, format, pixelData... use a format = TextureFormat::ColorARGB8 to match the previous behavior.

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

textureHandle

The 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.

DestroyGraphicsContext()

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.

DestroyTexture()

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

textureHandle

of the texture to destroy and remove completely from the GL context and TextureManager.

GetTextureHeight()

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.

GetTextureWidth()

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.

PreMultiplyAlpha()

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

imageData	The data to be modified in place.
imageWidth	The width of the image in pixels.
imageHight	The height of the image in pixels.

SetTextureWrapMode() [1/2]

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.

@parameter 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. @parameter wrapMode The mode to use for both U and V coordinates. @parameter wrapModeU The mode to use for the horizontal U coordinates. @parameter wrapModeV The mode to use for the vertical V coordinates.

SetTextureWrapMode() [2/2]

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.

@parameter 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. @parameter wrapMode The mode to use for both U and V coordinates. @parameter wrapModeU The mode to use for the horizontal U coordinates. @parameter wrapModeV The mode to use for the vertical V coordinates.