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

#include <TextureHandleRegistry.h>

Collaboration diagram for EngineCore::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, Texture *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:

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.
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);

Author: Konstantin Passig

Date: 2026-01-22

Definition at line 49 of file TextureHandleRegistry.h.

Constructor & Destructor Documentation

◆ TextureHandleRegistry() [1/3]

EngineCore::TextureHandleRegistry::TextureHandleRegistry ( )

default

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

Here is the caller graph for this function:

◆ ~TextureHandleRegistry()

EngineCore::TextureHandleRegistry::~TextureHandleRegistry ( )

default

◆ TextureHandleRegistry() [2/3]

EngineCore::TextureHandleRegistry::TextureHandleRegistry ( const TextureHandleRegistry & )

delete

References TextureHandleRegistry().

Here is the call graph for this function:

◆ TextureHandleRegistry() [3/3]

EngineCore::TextureHandleRegistry::TextureHandleRegistry ( TextureHandleRegistry && )

delete

References TextureHandleRegistry().

Here is the call graph for this function:

Member Function Documentation

◆ clear()

void EngineCore::TextureHandleRegistry::clear ( )

Clear all registry entries (typically called on shutdown)

Definition at line 175 of file TextureHandleRegistry.cpp.

References entries_, mutex_, and pathToHandleId_.

◆ getHandleCount()

size_t EngineCore::TextureHandleRegistry::getHandleCount ( ) const

nodiscard

Get the total number of registered texture handles.

Definition at line 155 of file TextureHandleRegistry.cpp.

References entries_, and mutex_.

◆ getOrCreateHandle()

template<TextureType Type>

TypedTextureHandle< Type > EngineCore::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 72 of file TextureHandleRegistry.h.

References getOrCreateHandleImpl().

Referenced by EngineCore::RenderingDataManager::initializeDefaultTextures(), Ecs::ModelAssetPipeline::processModel(), and Ecs::ModelAssetPipeline::processTextures().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getOrCreateHandleImpl()

TextureHandle EngineCore::TextureHandleRegistry::getOrCreateHandleImpl	(	const std::filesystem::path &	path,
		TextureType	type )

private

Internal implementation of getOrCreateHandle.

Definition at line 23 of file TextureHandleRegistry.cpp.

References EngineCore::TextureHandleRegistry::Entry::descriptorIndex, entries_, EngineCore::TextureHandle::INVALID_ID, mutex_, EngineCore::TextureHandleRegistry::Entry::path, pathToHandleId_, EngineCore::TextureHandleRegistry::Entry::texture, and EngineCore::TextureHandleRegistry::Entry::type.

Referenced by getOrCreateHandle().

Here is the caller graph for this function:

◆ getPathForHandle()

std::filesystem::path EngineCore::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

Definition at line 160 of file TextureHandleRegistry.cpp.

References entries_, EngineCore::TextureHandle::getId(), EngineCore::TextureHandle::isValid(), and mutex_.

Referenced by EngineCore::RenderingDataManager::uploadMaterialBuffers().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getTextureType()

TextureType EngineCore::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

Definition at line 88 of file TextureHandleRegistry.cpp.

References entries_, EngineCore::TextureHandle::getId(), EngineCore::TextureHandle::isValid(), mutex_, and EngineCore::Unknown.

Here is the call graph for this function:

◆ getTextureTypeForPath()

TextureType EngineCore::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

Definition at line 103 of file TextureHandleRegistry.cpp.

References entries_, mutex_, pathToHandleId_, and EngineCore::Unknown.

Referenced by EngineCore::RenderingDataManager::onTextureLoaded().

Here is the caller graph for this function:

◆ onTextureLoaded()

void EngineCore::TextureHandleRegistry::onTextureLoaded	(	const std::filesystem::path &	path,
		Texture *	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

Definition at line 117 of file TextureHandleRegistry.cpp.

References EngineCore::TextureHandleRegistry::Entry::descriptorIndex, entries_, mutex_, pathToHandleId_, and EngineCore::TextureHandleRegistry::Entry::texture.

Referenced by EngineCore::RenderingDataManager::onTextureLoaded().

Here is the caller graph for this function:

◆ onTextureUnloaded()

void EngineCore::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

Definition at line 137 of file TextureHandleRegistry.cpp.

References EngineCore::TextureHandleRegistry::Entry::descriptorIndex, entries_, EngineCore::TextureHandle::INVALID_ID, mutex_, pathToHandleId_, and EngineCore::TextureHandleRegistry::Entry::texture.

◆ operator=() [1/2]

TextureHandleRegistry & EngineCore::TextureHandleRegistry::operator= ( const TextureHandleRegistry & )

delete

References TextureHandleRegistry().

Here is the call graph for this function:

◆ operator=() [2/2]

TextureHandleRegistry & EngineCore::TextureHandleRegistry::operator= ( TextureHandleRegistry && )

delete

References TextureHandleRegistry().

Here is the call graph for this function:

◆ resolveDescriptorIndex()

uint32_t EngineCore::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

Definition at line 71 of file TextureHandleRegistry.cpp.

References entries_, EngineCore::TextureHandle::getId(), EngineCore::TextureHandle::INVALID_ID, EngineCore::TextureHandle::isValid(), and mutex_.

Referenced by EngineCore::RenderingDataManager::uploadMaterialBuffers().

Here is the call graph for this function:

Here is the caller graph for this function:

Member Data Documentation

◆ entries_

std::vector<Entry> EngineCore::TextureHandleRegistry::entries_

private

Definition at line 157 of file TextureHandleRegistry.h.

Referenced by clear(), getHandleCount(), getOrCreateHandleImpl(), getPathForHandle(), getTextureType(), getTextureTypeForPath(), onTextureLoaded(), onTextureUnloaded(), and resolveDescriptorIndex().

◆ mutex_

std::shared_mutex EngineCore::TextureHandleRegistry::mutex_

mutableprivate

Definition at line 159 of file TextureHandleRegistry.h.

Referenced by clear(), getHandleCount(), getOrCreateHandleImpl(), getPathForHandle(), getTextureType(), getTextureTypeForPath(), onTextureLoaded(), onTextureUnloaded(), and resolveDescriptorIndex().

◆ pathToHandleId_

std::unordered_map<std::string, uint32_t> EngineCore::TextureHandleRegistry::pathToHandleId_

private

Definition at line 158 of file TextureHandleRegistry.h.

Referenced by clear(), getOrCreateHandleImpl(), getTextureTypeForPath(), onTextureLoaded(), and onTextureUnloaded().

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

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

Classes

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Usage Flow

Constructor & Destructor Documentation

◆ TextureHandleRegistry() [1/3]

◆ ~TextureHandleRegistry()

◆ TextureHandleRegistry() [2/3]

◆ TextureHandleRegistry() [3/3]

Member Function Documentation

◆ clear()

◆ getHandleCount()

◆ getOrCreateHandle()

◆ getOrCreateHandleImpl()

◆ getPathForHandle()

◆ getTextureType()

◆ getTextureTypeForPath()

◆ onTextureLoaded()

◆ onTextureUnloaded()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ resolveDescriptorIndex()

Member Data Documentation

◆ entries_

◆ mutex_

◆ pathToHandleId_