Texture manager with asynchronous loading and automatic DDS conversion/compression. More...

#include <TextureManager.h>

Collaboration diagram for CTextureManager:

[legend]

Public Member Functions
	CTextureManager (PIVFS vfs, bool highQuality, Renderer::Backend::IDevice *device)
	Construct texture manager. More...

	~CTextureManager ()

CTexturePtr	CreateTexture (const CTextureProperties &props)
	Create a texture with the given properties. More...

CTexturePtr	WrapBackendTexture (std::unique_ptr< Renderer::Backend::ITexture > backendTexture)
	Wraps a backend texture. More...

const CTexturePtr &	GetErrorTexture ()
	Returns a magenta texture. More...

const CTexturePtr &	GetWhiteTexture ()
	Returns a single color RGBA texture with CColor(1.0f, 1.0f, 1.0f, 1.0f). More...

const CTexturePtr &	GetTransparentTexture ()
	Returns a single color RGBA texture with CColor(0.0f, 0.0f, 0.0f, 0.0f). More...

const CTexturePtr &	GetAlphaGradientTexture ()
	Returns a white RGBA texture with alpha gradient. More...

const CTexturePtr &	GetBlackTextureCube ()
	Returns a single color RGBA texture cube with CColor(0.0f, 0.0f, 0.0f, 1.0f). More...

bool	MakeProgress ()
	Work on asynchronous texture loading operations, if any. More...

bool	MakeUploadProgress (Renderer::Backend::IDeviceCommandContext *deviceCommandContext)
	Work on asynchronous texture uploading operations, if any. More...

bool	GenerateCachedTexture (const VfsPath &path, VfsPath &outputPath)
	Synchronously converts and compresses and saves the texture, and returns the output path (minus a "cache/" prefix). More...

VfsPath	GetCachedPath (const VfsPath &path) const

bool	TextureExists (const VfsPath &path) const
	Returns true if the given texture exists. More...

size_t	GetBytesUploaded () const
	Returns total number of bytes uploaded for all current texture. More...

void	OnQualityChanged ()
	Should be called on any quality or anisotropic change. More...

Private Member Functions
	NONCOPYABLE (CTextureManager)

Private Attributes
CTextureManagerImpl *	m

Detailed Description

Texture manager with asynchronous loading and automatic DDS conversion/compression.

Input textures can be any format. They will be converted to DDS using settings defined in files named "texture.xml", in the same directory as the texture and in its parent directories. See CTextureConverter for the XML syntax. The DDS file will be cached for faster loading in the future.

Typically the graphics code will initialise many textures at the start of the game, mostly for off-screen objects, by calling CreateTexture(). Loading texture data may be very slow (especially if it needs to be converted to DDS), and we don't want the game to become unresponsive. CreateTexture therefore returns an object immediately, without loading the texture. If the object is never used then the data will never be loaded.

Typically, the renderer will call CTexture::Bind() when it wants to use the texture. This will trigger the loading of the texture data. If it can be loaded quickly (i.e. there is already a cached DDS version), then it will be loaded before the function returns, and the texture can be rendered as normal.

If loading will take a long time, then Bind() binds a default placeholder texture and starts loading the texture in the background. It will use the correct texture when the renderer next calls Bind() after the load has finished.

It is also possible to prefetch textures which are not being rendered yet, but are expected to be rendered soon (e.g. for off-screen terrain tiles). These will be loaded in the background, when there are no higher-priority textures to load.

The same texture file can be safely loaded multiple times with different backend parameters (but this should be avoided whenever possible, as it wastes VRAM).

For release packages, DDS files can be precached by appending ".dds" to their name, which will be used instead of doing runtime conversion. This means most players should never experience the slow asynchronous conversion behaviour. These cache files will typically be packed into an archive for faster loading; if no archive cache is available then the source file will be converted and stored as a loose cache file on the user's disk.

Constructor & Destructor Documentation

◆ CTextureManager()

CTextureManager::CTextureManager	(	PIVFS	vfs,
		bool	highQuality,
		Renderer::Backend::IDevice *	device
	)

Construct texture manager.

vfs must be the VFS instance used for all textures loaded from this object. highQuality is slower and intended for batch-conversion modes.

◆ ~CTextureManager()

CTextureManager::~CTextureManager ( )

Member Function Documentation

◆ CreateTexture()

CTexturePtr CTextureManager::CreateTexture ( const CTextureProperties & props )

Create a texture with the given properties.

The texture data will not be loaded immediately.

◆ GenerateCachedTexture()

bool CTextureManager::GenerateCachedTexture	(	const VfsPath &	path,
		VfsPath &	outputPath
	)

Synchronously converts and compresses and saves the texture, and returns the output path (minus a "cache/" prefix).

This is intended for pre-caching textures in release archives.

Returns: true on success

◆ GetAlphaGradientTexture()

const CTexturePtr & CTextureManager::GetAlphaGradientTexture ( )

Returns a white RGBA texture with alpha gradient.

◆ GetBlackTextureCube()

const CTexturePtr & CTextureManager::GetBlackTextureCube ( )

Returns a single color RGBA texture cube with CColor(0.0f, 0.0f, 0.0f, 1.0f).

◆ GetBytesUploaded()

size_t CTextureManager::GetBytesUploaded ( ) const

Returns total number of bytes uploaded for all current texture.

◆ GetCachedPath()

VfsPath CTextureManager::GetCachedPath ( const VfsPath & path ) const

Returns: a cached version of the path

◆ GetErrorTexture()

const CTexturePtr & CTextureManager::GetErrorTexture ( )

Returns a magenta texture.

Use this for highlighting errors (e.g. missing terrain textures).

◆ GetTransparentTexture()

const CTexturePtr & CTextureManager::GetTransparentTexture ( )

Returns a single color RGBA texture with CColor(0.0f, 0.0f, 0.0f, 0.0f).

◆ GetWhiteTexture()

const CTexturePtr & CTextureManager::GetWhiteTexture ( )

Returns a single color RGBA texture with CColor(1.0f, 1.0f, 1.0f, 1.0f).

◆ MakeProgress()

bool CTextureManager::MakeProgress ( )

Work on asynchronous texture loading operations, if any.

Returns true if it did any work. The caller should typically loop this per frame until it returns false or exceeds the allocated time for this frame.

◆ MakeUploadProgress()

bool CTextureManager::MakeUploadProgress ( Renderer::Backend::IDeviceCommandContext * deviceCommandContext )

Work on asynchronous texture uploading operations, if any.

Returns true if it did any work. Mostly the same as MakeProgress.

◆ NONCOPYABLE()

CTextureManager::NONCOPYABLE ( CTextureManager )

private

◆ OnQualityChanged()

void CTextureManager::OnQualityChanged ( )

Should be called on any quality or anisotropic change.

◆ TextureExists()

bool CTextureManager::TextureExists ( const VfsPath & path ) const

Returns true if the given texture exists.

This tests both for the original and converted filename.

◆ WrapBackendTexture()

CTexturePtr CTextureManager::WrapBackendTexture ( std::unique_ptr< Renderer::Backend::ITexture > backendTexture )

Wraps a backend texture.

Member Data Documentation

◆ m

CTextureManagerImpl* CTextureManager::m