rendering_engine::TextureCache Class Reference

Manages texture loading, GPU uploading, and caching for reuse. More...

#include <texture_cache.hpp>

Inherits rendering_engine::IRendererObserver.

Public Member Functions
	TextureCache (IRenderer *renderer)
	Constructs the TextureCache with a reference to the renderer. More...
	~TextureCache ()
void	LoadTexturesFromFolder (std::string pathToFolder)
	Loads all supported texture files (*.jpg, *.png) from a specified folder into RAM and uploads them to the GPU. More...
void	LoadTexture (std::string textureName, ImageData imageData)
void	LoadTexturesFromPackage ()
	Loads all textures from the packed asset archive. More...
std::string	UploadTextureToRAM (std::string path)
	Loads a single texture into RAM from the given file path. More...
std::string	UploadTextureToRAM (std::string textureFileName, std::vector< uint8_t > const &fileBytes)
	Loads a single texture into RAM from raw file bytes. More...
std::string	UploadTextureToRAM (std::string textureName, ImageData imageData)
void	UploadTextureToGPU (std::string textureName)
	Uploads a texture (previously loaded into RAM) to GPU. More...
void	ReleaseTextureFromGPU (std::string textureName)
	Releases a texture from GPU memory. More...
void	ReleaseAllFromGPU ()
	Releases all cached textures from GPU memory. More...
void	ReleaseAll ()
	Fully clears the texture cache, including both RAM and GPU resources. More...
std::shared_ptr< ImageDataGpu >	GetTextureResources (std::string filename)
	Retrieves the full texture resource wrapper from cache. More...
ITextureRenderResources *	GetTextureRenderResources (std::string filename)
	Retrieves only the GPU render resources of a cached texture. More...
size_t	GetSizeInRAM () const
	Gets the total size of all currently cached textures in RAM. More...
size_t	GetSizeInGPU () const
	Gets the total size of all textures currently uploaded to GPU. More...
Public Member Functions inherited from rendering_engine::IRendererObserver
virtual void	OnRenderResourcesRelease ()=0
	Renderer callback: release all GPU resources (used during device loss/reset). More...
virtual void	OnRenderResourcesRebuild ()=0
	Renderer callback: re-upload or recreate all GPU resources (used after device reset/rebuild). More...
virtual	~IRendererObserver ()=default
	Virtual destructor. More...

Protected Member Functions
void	OnRenderResourcesRelease () override
	Renderer callback: release all GPU resources (used during device loss/reset). More...
void	OnRenderResourcesRebuild () override
	Renderer callback: re-upload or recreate all GPU resources (used after device reset/rebuild). More...

Protected Attributes
IRenderer *	mRenderer
std::unordered_map< std::string, std::shared_ptr< ImageDataGpu > >	mTextures
size_t	mTotalSizeRAM
size_t	mTotalSizeGPU

Detailed Description

Manages texture loading, GPU uploading, and caching for reuse.

This class handles texture resource management at runtime. It supports loading image files (JPG and PNG) from a folder or path into RAM, uploading them to GPU, and provides access to the texture resources through string identifiers (filenames without extensions).

Textures are stored using shared pointers to ImageDataGpu, and memory tracking is performed for both RAM and GPU sides.

Definition at line 31 of file texture_cache.hpp.

Constructor & Destructor Documentation

TextureCache()

rendering_engine::TextureCache::TextureCache

(

IRenderer *

renderer

)

Constructs the TextureCache with a reference to the renderer.

Parameters

renderer

Pointer to the active rendering backend.

Definition at line 16 of file texture_cache.cpp.

    :
    mRenderer(renderer),
    mTotalSizeRAM(0),
    mTotalSizeGPU(0)
{
    LOG_INFO("TextureCache created.");
    mRenderer->RegisterObserver(this);
}

~TextureCache()

rendering_engine::TextureCache::~TextureCache

(

)

Definition at line 26 of file texture_cache.cpp.

{
    LOG_DEBUG("TextureCache destroyed.");
    mRenderer->UnregisterObserver(this);
}

Member Function Documentation

GetSizeInGPU()

size_t rendering_engine::TextureCache::GetSizeInGPU

(

)

const

Gets the total size of all textures currently uploaded to GPU.

Returns

GPU memory usage in bytes.

Definition at line 284 of file texture_cache.cpp.

{
    return mTotalSizeGPU;
}

GetSizeInRAM()

size_t rendering_engine::TextureCache::GetSizeInRAM

(

)

const

Gets the total size of all currently cached textures in RAM.

Returns

Memory usage in bytes.

Definition at line 279 of file texture_cache.cpp.

{
    return mTotalSizeRAM;
}

GetTextureRenderResources()

ITextureRenderResources * rendering_engine::TextureCache::GetTextureRenderResources

(

std::string

filename

)

Retrieves only the GPU render resources of a cached texture.

Useful when the caller only needs GPU handles and does not care about image metadata.

Parameters

filename

Base filename used during loading.

Returns

Raw pointer to ITextureRenderResources, or nullptr if not found or not uploaded to GPU.

Definition at line 269 of file texture_cache.cpp.

{
    if (auto search = mTextures.find(filename); search == mTextures.end())
    {
        return nullptr;
    }
 
    return mTextures.at(filename)->GetTextureRenderResources();
}

GetTextureResources()

std::shared_ptr< ImageDataGpu > rendering_engine::TextureCache::GetTextureResources

(

std::string

filename

)

Retrieves the full texture resource wrapper from cache.

Parameters

filename

Base filename used during loading.

Returns

Shared pointer to ImageDataGpu, or nullptr if not found.

Definition at line 259 of file texture_cache.cpp.

{
    auto search = mTextures.find(filename);
    if (search == mTextures.end())
    {
        return nullptr;
    }
    return search->second;
}

LoadTexture()

void rendering_engine::TextureCache::LoadTexture	(	std::string	textureName,
		ImageData	imageData
	)

Definition at line 63 of file texture_cache.cpp.

{
    // Upload to RAM with textureName + binaryFileData
    auto textureNameUploaded = UploadTextureToRAM(textureName, imageData);
    if (!textureNameUploaded.empty())
    {
        UploadTextureToGPU(textureNameUploaded);
    }
}

LoadTexturesFromFolder()

void rendering_engine::TextureCache::LoadTexturesFromFolder

(

std::string

pathToFolder

)

Loads all supported texture files (*.jpg, *.png) from a specified folder into RAM and uploads them to the GPU.

Each texture is registered under its base filename (without extension) for later access. Invalid paths or unsupported file types are skipped silently.

Parameters

pathToFolder

Absolute or relative path to the folder containing texture files.

Definition at line 32 of file texture_cache.cpp.

{
    LOG_INFO("Loading textures from folder: " + pathToFolder);
    auto start = std::chrono::steady_clock::now();
    // 1. Check if path is valid and exist
    boost::filesystem::path pathToDirectory = boost::filesystem::path(pathToFolder);
    const bool isValidFolderPath = boost::filesystem::exists(boost::filesystem::path(pathToFolder)) && boost::filesystem::is_directory(boost::filesystem::path(pathToFolder));
    if (!isValidFolderPath)
    {
        return;
    }
    // 2. Iterate through files in the folder.
    //    if file is in the list of supported extensions
    for (boost::filesystem::directory_entry& x : boost::filesystem::directory_iterator(pathToDirectory))
    {
        auto textureName = UploadTextureToRAM(x.path().string());
        if (!textureName.empty())
        {
            UploadTextureToGPU(textureName);
        }
    }
 
    auto end = std::chrono::steady_clock::now();
    float ms = std::chrono::duration<float, std::milli>(end - start).count();
 
    LOG_INFO("Loaded " + std::to_string(mTextures.size()) +
        " textures from folder in " +
        std::to_string(ms) + " ms. RAM usage: " +
        std::to_string(mTotalSizeRAM) + " bytes.");
}

LoadTexturesFromPackage()

void rendering_engine::TextureCache::LoadTexturesFromPackage

(

)

Loads all textures from the packed asset archive.

This function behaves similarly to LoadTexturesFromFolder(), but instead of scanning a filesystem directory, it iterates over virtual file entries stored inside the packed content system created by the packaging tool.

Only entries located under the virtual folder: "Textures/" are considered valid texture resources.

For each entry, the raw file bytes are retrieved via Utility::ReadPackedFile(), decoded into an ImageDataGpu instance, and stored in the RAM cache. GPU uploading must still be triggered via UploadTextureToGPU().

Definition at line 73 of file texture_cache.cpp.

{
    LOG_INFO("Loading textures from package.");
    auto start = std::chrono::steady_clock::now();
    const auto& entries = Utility::GetPackEntries();
 
    std::string folderEntry = { "Textures/" };
    for (auto& entry : entries)
    {
        const std::string& virtualPath = entry.first;
        if (virtualPath.rfind(folderEntry, 0) == 0) // starts with Textures/
        {
            std::string textureFileName = virtualPath.substr(folderEntry.size());
 
            std::vector<uint8_t> binaryFileData = Utility::ReadPackedFile(virtualPath);
            if (binaryFileData.empty())
            {
                LOG_ERROR("[TextureCache] Could not read packed texture: "
                    + virtualPath);
                continue;
            }
 
            // Upload to RAM with textureName + binaryFileData
            auto textureName = UploadTextureToRAM(textureFileName, binaryFileData);
            if (!textureName.empty())
            {
                UploadTextureToGPU(textureName);
            }
        }
    }
    auto end = std::chrono::steady_clock::now();
    float ms = std::chrono::duration<float, std::milli>(end - start).count();
 
    LOG_INFO("Loaded " + std::to_string(mTextures.size()) +
        " textures from package in " +
        std::to_string(ms) + " ms. RAM usage: " +
        std::to_string(mTotalSizeRAM) + " bytes.");
}

OnRenderResourcesRebuild()

void rendering_engine::TextureCache::OnRenderResourcesRebuild ( )

overrideprotectedvirtual

Renderer callback: re-upload or recreate all GPU resources (used after device reset/rebuild).

This method will be called after the device or swapchain is recreated, allowing the observer to re-upload or recreate all necessary resources for rendering.

Implements rendering_engine::IRendererObserver.

Definition at line 294 of file texture_cache.cpp.

{
    for (auto& texture : mTextures)
    {
        texture.second->UploadToGPU();
        size_t size = texture.second->GetSizeInGPU();
        mTotalSizeGPU += size;
    }
}

OnRenderResourcesRelease()

void rendering_engine::TextureCache::OnRenderResourcesRelease ( )

overrideprotectedvirtual

Renderer callback: release all GPU resources (used during device loss/reset).

This method will be called before any device or swapchain is destroyed, allowing the observer to safely release all handles and deallocate any GPU memory.

Implements rendering_engine::IRendererObserver.

Definition at line 289 of file texture_cache.cpp.

{
    ReleaseAllFromGPU();
}

ReleaseAll()

void rendering_engine::TextureCache::ReleaseAll

(

)

Fully clears the texture cache, including both RAM and GPU resources.

Definition at line 247 of file texture_cache.cpp.

{
    LOG_INFO("Releasing all textures. RAM usage before clear: " +
        std::to_string(mTotalSizeRAM) +
        ", GPU usage: " +
        std::to_string(mTotalSizeGPU));
    ReleaseAllFromGPU();
    mTextures.clear();
    mTotalSizeRAM = 0;
    mTotalSizeGPU = 0;
}

ReleaseAllFromGPU()

void rendering_engine::TextureCache::ReleaseAllFromGPU

(

)

Releases all cached textures from GPU memory.

This does not affect RAM-side caching.

Definition at line 238 of file texture_cache.cpp.

{
    for (auto& texture : mTextures)
    {
        texture.second->ReleaseFromGPU();
    }
    mTotalSizeGPU = 0;
}

ReleaseTextureFromGPU()

void rendering_engine::TextureCache::ReleaseTextureFromGPU

(

std::string

textureName

)

Releases a texture from GPU memory.

The texture remains in RAM cache and can be uploaded again later.

Parameters

filename

Cache key of the texture to release (base filename).

Definition at line 223 of file texture_cache.cpp.

{
    LOG_DEBUG("Releasing texture from GPU: " + textureName);
    if (auto search = mTextures.find(textureName); search == mTextures.end())
    {
        return;
    }
 
    auto& texture = mTextures[textureName];
    size_t size = texture->GetSizeInGPU();
    texture->ReleaseFromGPU();
 
    mTotalSizeGPU -= size;
}

UploadTextureToGPU()

void rendering_engine::TextureCache::UploadTextureToGPU

(

std::string

textureName

)

Uploads a texture (previously loaded into RAM) to GPU.

If the texture is not found in RAM cache, the function does nothing.

Parameters

textureName

Base texture name (no path, no extension) used as the cache key.

Definition at line 197 of file texture_cache.cpp.

{
    LOG_DEBUG("Uploading texture to GPU: " + textureName);
    auto start = std::chrono::steady_clock::now();
    // If texture is not loaded in RAM yet, skip loading to GPU.
    if (auto search = mTextures.find(textureName); search == mTextures.end())
    {
        return;
    }
    if (mTextures[textureName]->IsOnGPU())
    {
        return;
    }
 
    mTextures[textureName]->UploadToGPU();
    size_t size = mTextures[textureName]->GetSizeInGPU();
    mTotalSizeGPU += size;
 
    auto end = std::chrono::steady_clock::now();
    float ms = std::chrono::duration<float, std::milli>(end - start).count();
 
    LOG_DEBUG("Texture uploaded to GPU: " + textureName +
        " (" + std::to_string(size) +
        " bytes, " + std::to_string(ms) + " ms)");
}

UploadTextureToRAM() [1/3]

std::string rendering_engine::TextureCache::UploadTextureToRAM

(

std::string

path

)

Loads a single texture into RAM from the given file path.

The texture will not be uploaded to GPU automatically. The caller must use UploadTextureToGPU() after this call if GPU usage is needed.

Parameters

path	Full file path to the texture image (JPG/PNG).

Returns

The base filename used as the cache key, or an empty string if loading failed.

Definition at line 112 of file texture_cache.cpp.

{
    auto filePath = boost::filesystem::path(path);
    if (!boost::filesystem::is_regular_file(filePath))
    {
        return std::string{};
    }
    
    const std::string ext = filePath.extension().string();
    const bool isExtensionSupported = (ext == ".jpg") || (ext == ".png");
    if (!isExtensionSupported)
    {
        return std::string{};
    }
 
    std::string filename = filePath.stem().string();
    // If texture is already loaded into RAM yet, do not add again.
    if (auto search = mTextures.find(filename); search != mTextures.end())
    {
        return std::string{};
    }
    LOG_DEBUG("Uploading texture to RAM: " + filename);
    auto start = std::chrono::steady_clock::now();
    mTextures[filename] = std::make_shared<ImageDataGpu>(path, mRenderer);
 
    size_t size = mTextures.at(filename)->GetSizeInRAM();
    mTotalSizeRAM += size;
 
    auto end = std::chrono::steady_clock::now();
    float ms = std::chrono::duration<float, std::milli>(end - start).count();
 
    LOG_DEBUG("Texture loaded to RAM: " + filename +
        " (" + std::to_string(size) +
        " bytes, " + std::to_string(ms) + " ms)");
 
    return filename;
}

UploadTextureToRAM() [2/3]

std::string rendering_engine::TextureCache::UploadTextureToRAM	(	std::string	textureFileName,
		std::vector< uint8_t > const &	fileBytes
	)

Loads a single texture into RAM from raw file bytes.

This overload enables texture loading from virtual files stored in a packed asset archive or from any memory-based source rather than the OS filesystem.

The fileBytes buffer must contain the complete encoded texture data (e.g., PNG or JPEG). The data is decoded and stored inside ImageDataGpu.

Parameters

textureFileName	Cache key representing the virtual texture path (e.g., "Textures/myTexture.png" or simply "myTexture").
fileBytes	Raw encoded texture file data (PNG/JPG).

Returns

The cache key on success, or an empty string on failure.

Definition at line 150 of file texture_cache.cpp.

{
    auto textureName = boost::filesystem::path(textureFileName).stem().string();
    // If texture is already loaded into RAM yet, do not add again.
    if (auto search = mTextures.find(textureName); search != mTextures.end())
    {
        return std::string{};
    }
    LOG_DEBUG("Uploading texture to RAM: " + textureName);
    auto start = std::chrono::steady_clock::now();
    mTextures[textureName] = std::make_shared<ImageDataGpu>(fileBytes, mRenderer);
 
    size_t size = mTextures.at(textureName)->GetSizeInRAM();
    mTotalSizeRAM += size;
    auto end = std::chrono::steady_clock::now();
    float ms = std::chrono::duration<float, std::milli>(end - start).count();
 
    LOG_DEBUG("Texture loaded to RAM: " + textureName +
        " (" + std::to_string(size) +
        " bytes, " + std::to_string(ms) + " ms)");
 
    return textureName;
}

UploadTextureToRAM() [3/3]

std::string rendering_engine::TextureCache::UploadTextureToRAM	(	std::string	textureName,
		ImageData	imageData
	)

Definition at line 174 of file texture_cache.cpp.

{
    // If texture is already loaded into RAM yet, do not add again.
    if (auto search = mTextures.find(textureName); search != mTextures.end())
    {
        return std::string{};
    }
    LOG_DEBUG("Uploading texture to RAM: " + textureName);
    auto start = std::chrono::steady_clock::now();
    mTextures[textureName] = std::make_shared<ImageDataGpu>(imageData, mRenderer);
 
    size_t size = mTextures.at(textureName)->GetSizeInRAM();
    mTotalSizeRAM += size;
    auto end = std::chrono::steady_clock::now();
    float ms = std::chrono::duration<float, std::milli>(end - start).count();
 
    LOG_DEBUG("Texture loaded to RAM: " + textureName +
        " (" + std::to_string(size) +
        " bytes, " + std::to_string(ms) + " ms)");
 
    return textureName;
}

Member Data Documentation

mRenderer

IRenderer* rendering_engine::TextureCache::mRenderer

protected

Definition at line 170 of file texture_cache.hpp.

mTextures

std::unordered_map<std::string, std::shared_ptr<ImageDataGpu> > rendering_engine::TextureCache::mTextures

protected

Definition at line 171 of file texture_cache.hpp.

mTotalSizeGPU

size_t rendering_engine::TextureCache::mTotalSizeGPU

protected

Definition at line 174 of file texture_cache.hpp.

mTotalSizeRAM

size_t rendering_engine::TextureCache::mTotalSizeRAM

protected

Definition at line 173 of file texture_cache.hpp.

---

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

• texture_cache.hpp
• texture_cache.cpp