Pyrogenesis HEAD
Pyrogenesis, a RTS Engine
CTextureManager Class Reference

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

#include <TextureManager.h>

Collaboration diagram for CTextureManager:

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 CTexturePtrGetErrorTexture ()
 Returns a magenta texture. More...
 
const CTexturePtrGetWhiteTexture ()
 Returns a single color RGBA texture with CColor(1.0f, 1.0f, 1.0f, 1.0f). More...
 
const CTexturePtrGetTransparentTexture ()
 Returns a single color RGBA texture with CColor(0.0f, 0.0f, 0.0f, 0.0f). More...
 
const CTexturePtrGetAlphaGradientTexture ()
 Returns a white RGBA texture with alpha gradient. More...
 
const CTexturePtrGetBlackTextureCube ()
 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

CTextureManagerImplm
 

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
private

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