Engine::Assets::Textures::TextureHandleRegistry Class Reference

Central registry for texture handles, providing O(1) descriptor index lookup. More...

#include <TextureHandleRegistry.h>

Collaboration diagram for Engine::Assets::Textures::TextureHandleRegistry:

Classes
struct	Entry
	Registry entry storing texture metadata. More...

Public Member Functions
	TextureHandleRegistry ()=default
	~TextureHandleRegistry ()=default
	TextureHandleRegistry (const TextureHandleRegistry &)=delete
TextureHandleRegistry &	operator= (const TextureHandleRegistry &)=delete
	TextureHandleRegistry (TextureHandleRegistry &&)=delete
TextureHandleRegistry &	operator= (TextureHandleRegistry &&)=delete
template<TextureType Type>
TypedTextureHandle< Type >	getOrCreateHandle (const std::filesystem::path &path)
	Get or create a typed handle for a texture path.
uint32_t	resolveDescriptorIndex (TextureHandle handle) const
	Resolve a handle to its descriptor index (O(1) operation)
TextureType	getTextureType (TextureHandle handle) const
	Get the texture type for a handle.
TextureType	getTextureTypeForPath (const std::filesystem::path &path) const
	Get the texture type for a path (if registered)
void	onTextureLoaded (const std::filesystem::path &path, RuntimeTexture *texture, uint32_t descriptorIndex)
	Called when a texture finishes loading.
void	onTextureUnloaded (const std::filesystem::path &path)
	Called when a texture is unloaded.
size_t	getHandleCount () const
	Get the total number of registered texture handles.
std::filesystem::path	getPathForHandle (TextureHandle handle) const
	Get the path associated with a handle (for debugging/validation)
void	clear ()
	Clear all registry entries (typically called on shutdown)

Private Member Functions
TextureHandle	getOrCreateHandleImpl (const std::filesystem::path &path, TextureType type)
	Internal implementation of getOrCreateHandle.

Private Attributes
std::vector< Entry >	entries_
std::unordered_map< std::string, uint32_t >	pathToHandleId_
std::shared_mutex	mutex_

Detailed Description

Central registry for texture handles, providing O(1) descriptor index lookup.

The TextureHandleRegistry solves two problems:

1. Performance: Instead of doing path-to-descriptor-index lookups via string hashing on every material buffer upload, handles can be resolved to indices via array indexing.
2. Type Safety: The registry tracks the semantic type of each texture, ensuring that textures are created with the correct VkFormat (SRGB vs UNORM).

Usage Flow

At import time (GLTF loading):

// Registry creates handle immediately (before texture loads)
auto handle = registry.getOrCreateHandle<TextureType::Normal>(normalMapPath);
materialAsset->setNormalTextureHandle(handle);

When texture loads asynchronously:

TextureType type = registry.getTextureTypeForPath(texturePath);
Texture vulkanTexture(imageData, type, context);  // Uses correct VkFormat!
Texture* registered = assetManager->registerTexture(texturePath, std::move(vulkanTexture));
registry.onTextureLoaded(texturePath, registered, registered->getDescriptorIndex());

At material buffer upload (hot path):

// O(1) array lookup instead of map lookup!
uint32_t descriptorIndex = registry.resolveDescriptorIndex(handle);

Definition at line 51 of file TextureHandleRegistry.h.

Constructor & Destructor Documentation

TextureHandleRegistry() [1/3]

Engine::Assets::Textures::TextureHandleRegistry::TextureHandleRegistry ( )

default

Referenced by operator=(), operator=(), TextureHandleRegistry(), and TextureHandleRegistry().

Here is the caller graph for this function:

~TextureHandleRegistry()

Engine::Assets::Textures::TextureHandleRegistry::~TextureHandleRegistry ( )

default

TextureHandleRegistry() [2/3]

Engine::Assets::Textures::TextureHandleRegistry::TextureHandleRegistry ( const TextureHandleRegistry & )

delete

References TextureHandleRegistry().

Here is the call graph for this function:

TextureHandleRegistry() [3/3]

Engine::Assets::Textures::TextureHandleRegistry::TextureHandleRegistry ( TextureHandleRegistry && )

delete

References TextureHandleRegistry().

Here is the call graph for this function:

Member Function Documentation

clear()

void Engine::Assets::Textures::TextureHandleRegistry::clear

(

)

Clear all registry entries (typically called on shutdown)

getHandleCount()

size_t Engine::Assets::Textures::TextureHandleRegistry::getHandleCount ( ) const

nodiscard

Get the total number of registered texture handles.

getOrCreateHandle()

template<TextureType Type>

TypedTextureHandle< Type > Engine::Assets::Textures::TextureHandleRegistry::getOrCreateHandle ( const std::filesystem::path & path )

inline

Get or create a typed handle for a texture path.

This can be called before the texture is actually loaded. The handle will initially resolve to INVALID descriptor index (0xFFFFFFFF) until the texture finishes loading and onTextureLoaded() is called.

Template Parameters

Type	The semantic texture type

Parameters

path	Path to the texture file

Returns

A type-safe handle for this texture

Definition at line 75 of file TextureHandleRegistry.h.

References getOrCreateHandleImpl().

Here is the call graph for this function:

getOrCreateHandleImpl()

TextureHandle Engine::Assets::Textures::TextureHandleRegistry::getOrCreateHandleImpl ( const std::filesystem::path & path, TextureType type )

private

Internal implementation of getOrCreateHandle.

Referenced by getOrCreateHandle().

Here is the caller graph for this function:

getPathForHandle()

std::filesystem::path Engine::Assets::Textures::TextureHandleRegistry::getPathForHandle ( TextureHandle handle ) const

nodiscard

Get the path associated with a handle (for debugging/validation)

Parameters

handle

The texture handle

Returns

The path associated with this handle, or empty path if invalid

getTextureType()

TextureType Engine::Assets::Textures::TextureHandleRegistry::getTextureType ( TextureHandle handle ) const

nodiscard

Get the texture type for a handle.

Parameters

handle

The texture handle

Returns

The texture type associated with this handle

getTextureTypeForPath()

TextureType Engine::Assets::Textures::TextureHandleRegistry::getTextureTypeForPath ( const std::filesystem::path & path ) const

nodiscard

Get the texture type for a path (if registered)

Used during texture loading to determine the correct VkFormat.

Parameters

path	The texture path

Returns

The texture type if path is registered, TextureType::Unknown otherwise

onTextureLoaded()

void Engine::Assets::Textures::TextureHandleRegistry::onTextureLoaded	(	const std::filesystem::path &	path,
		RuntimeTexture *	texture,
		uint32_t	descriptorIndex )

Called when a texture finishes loading.

Updates the registry entry with the loaded texture and its descriptor index.

Parameters

path	Path to the texture that was loaded
texture	Pointer to the loaded Texture object
descriptorIndex	The descriptor index assigned to this texture

onTextureUnloaded()

void Engine::Assets::Textures::TextureHandleRegistry::onTextureUnloaded

(

const std::filesystem::path &

path

)

Called when a texture is unloaded.

Resets the descriptor index to INVALID but keeps the handle valid.

Parameters

path	Path to the texture that was unloaded

operator=() [1/2]

TextureHandleRegistry & Engine::Assets::Textures::TextureHandleRegistry::operator= ( const TextureHandleRegistry & )

delete

References TextureHandleRegistry().

Here is the call graph for this function:

operator=() [2/2]

TextureHandleRegistry & Engine::Assets::Textures::TextureHandleRegistry::operator= ( TextureHandleRegistry && )

delete

References TextureHandleRegistry().

Here is the call graph for this function:

resolveDescriptorIndex()

uint32_t Engine::Assets::Textures::TextureHandleRegistry::resolveDescriptorIndex ( TextureHandle handle ) const

nodiscard

Resolve a handle to its descriptor index (O(1) operation)

Parameters

handle

The texture handle to resolve

Returns

Descriptor index if texture is loaded, 0xFFFFFFFF if not yet loaded

Member Data Documentation

entries_

std::vector<Entry> Engine::Assets::Textures::TextureHandleRegistry::entries_

private

Definition at line 166 of file TextureHandleRegistry.h.

mutex_

std::shared_mutex Engine::Assets::Textures::TextureHandleRegistry::mutex_

mutableprivate

Definition at line 168 of file TextureHandleRegistry.h.

pathToHandleId_

std::unordered_map<std::string, uint32_t> Engine::Assets::Textures::TextureHandleRegistry::pathToHandleId_

private

Definition at line 167 of file TextureHandleRegistry.h.

---

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

• /home/magerbeton/Documents/gl3-vulkan/Engine/include/Engine/Texture/TextureHandleRegistry.h