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
	Creates an empty texture handle registry.
	~TextureHandleRegistry ()=default
	Destroys the registry without owning registered RuntimeTexture objects.
	TextureHandleRegistry (const TextureHandleRegistry &)=delete
	Copy construction is disabled because the registry contains synchronization state.
TextureHandleRegistry &	operator= (const TextureHandleRegistry &)=delete
	Copy assignment is disabled because registry entries must remain stable.
	TextureHandleRegistry (TextureHandleRegistry &&)=delete
	Move construction is disabled because handles refer to stable registry IDs.
TextureHandleRegistry &	operator= (TextureHandleRegistry &&)=delete
	Move assignment is disabled because handles refer to stable registry IDs.
template<TextureType Type>
TypedTextureHandle< Type >	getOrCreateHandle (const std::filesystem::path &path)
	Get or create a typed handle for a texture path.
TextureHandle	getOrCreateHandle (const std::filesystem::path &path, TextureType type)
	Gets or creates an untyped handle for a texture path and semantic type.
uint32_t	resolveDescriptorIndex (TextureHandle handle) const
	Resolve a handle to its descriptor index (O(1) operation)
uint32_t	resolveDescriptorSlot (TextureHandle handle) const
	Resolve a handle to its stable descriptor slot.
bool	isResident (TextureHandle handle) const
	True if the handle currently has a resident RuntimeTexture.
RuntimeTexture *	resolveTexture (TextureHandle handle) const
	Resolves a resident handle to its runtime Vulkan texture.
void	setDescriptorSlot (TextureHandle handle, uint32_t descriptorIndex)
	Assign a stable descriptor slot to a handle before the image is resident.
TextureIdentityKey	getIdentityForHandle (TextureHandle handle) const
	Gets the path/type identity associated with a handle.
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, TextureType type, RuntimeTexture *texture, uint32_t descriptorIndex)
	Called when a texture finishes loading.
void	onTextureLoaded (const TextureIdentityKey &identity, RuntimeTexture *texture, uint32_t descriptorIndex)
	Marks a registered texture identity as resident.
void	onTextureLoaded (const std::filesystem::path &path, RuntimeTexture *texture, uint32_t descriptorIndex)
	Marks a path as resident when it resolves to one registered texture type.
void	onTextureUnloaded (const std::filesystem::path &path)
	Called when a texture is unloaded.
void	onTextureUnloaded (const std::filesystem::path &path, TextureType type)
	Marks a registered path/type identity as not resident.
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< TextureIdentityKey, uint32_t, TextureIdentityKeyHash >	identityToHandleId_
std::unordered_map< std::string, std::vector< uint32_t > >	pathToHandleIds_
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 53 of file TextureHandleRegistry.h.

Constructor & Destructor Documentation

TextureHandleRegistry() [1/3]

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

default

Creates an empty texture handle registry.

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

Here is the caller graph for this function:

~TextureHandleRegistry()

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

default

Destroys the registry without owning registered RuntimeTexture objects.

TextureHandleRegistry() [2/3]

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

delete

Copy construction is disabled because the registry contains synchronization state.

References TextureHandleRegistry().

Here is the call graph for this function:

TextureHandleRegistry() [3/3]

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

delete

Move construction is disabled because handles refer to stable registry IDs.

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.

getIdentityForHandle()

TextureIdentityKey Engine::Assets::Textures::TextureHandleRegistry::getIdentityForHandle ( TextureHandle handle ) const

nodiscard

Gets the path/type identity associated with a handle.

Parameters

handle

Texture handle to query.

Returns

Identity key, or an empty key for an invalid handle.

getOrCreateHandle() [1/2]

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 99 of file TextureHandleRegistry.h.

References getOrCreateHandle().

Referenced by getOrCreateHandle().

Here is the call graph for this function:

Here is the caller graph for this function:

getOrCreateHandle() [2/2]

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

nodiscard

Gets or creates an untyped handle for a texture path and semantic type.

Parameters

path	Path to the texture file.
type	Semantic texture usage.

Returns

Texture handle for the path/type identity.

getOrCreateHandleImpl()

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

private

Internal implementation of getOrCreateHandle.

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

isResident()

bool Engine::Assets::Textures::TextureHandleRegistry::isResident ( TextureHandle handle ) const

nodiscard

True if the handle currently has a resident RuntimeTexture.

onTextureLoaded() [1/3]

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

Marks a path as resident when it resolves to one registered texture type.

Parameters

path	Path to the loaded texture.
texture	Loaded runtime texture pointer.
descriptorIndex	Descriptor slot assigned to the texture.

onTextureLoaded() [2/3]

void Engine::Assets::Textures::TextureHandleRegistry::onTextureLoaded	(	const std::filesystem::path &	path,
		TextureType	type,
		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
type	Texture usage type associated with the loaded path.
texture	Pointer to the loaded Texture object
descriptorIndex	The descriptor index assigned to this texture

onTextureLoaded() [3/3]

void Engine::Assets::Textures::TextureHandleRegistry::onTextureLoaded	(	const TextureIdentityKey &	identity,
		RuntimeTexture *	texture,
		uint32_t	descriptorIndex )

Marks a registered texture identity as resident.

Parameters

identity	Registered path/type identity.
texture	Loaded runtime texture pointer.
descriptorIndex	Descriptor slot assigned to the texture.

onTextureUnloaded() [1/2]

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

onTextureUnloaded() [2/2]

void Engine::Assets::Textures::TextureHandleRegistry::onTextureUnloaded	(	const std::filesystem::path &	path,
		TextureType	type )

Marks a registered path/type identity as not resident.

Parameters

path	Path to the unloaded texture.
type	Semantic texture usage.

operator=() [1/2]

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

delete

Copy assignment is disabled because registry entries must remain stable.

References TextureHandleRegistry().

Here is the call graph for this function:

operator=() [2/2]

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

delete

Move assignment is disabled because handles refer to stable registry IDs.

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

Stable descriptor slot if allocated, 0xFFFFFFFF if no slot has been reserved

resolveDescriptorSlot()

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

nodiscard

Resolve a handle to its stable descriptor slot.

This is descriptor-slot ownership, not image residency. The returned slot can contain a fallback descriptor until the real texture becomes resident.

resolveTexture()

RuntimeTexture * Engine::Assets::Textures::TextureHandleRegistry::resolveTexture ( TextureHandle handle ) const

nodiscard

Resolves a resident handle to its runtime Vulkan texture.

Returns

The resident texture, or nullptr while loading or for an invalid handle.

setDescriptorSlot()

void Engine::Assets::Textures::TextureHandleRegistry::setDescriptorSlot	(	TextureHandle	handle,
		uint32_t	descriptorIndex )

Assign a stable descriptor slot to a handle before the image is resident.

Member Data Documentation

entries_

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

private

Definition at line 263 of file TextureHandleRegistry.h.

identityToHandleId_

std::unordered_map<TextureIdentityKey, uint32_t, TextureIdentityKeyHash> Engine::Assets::Textures::TextureHandleRegistry::identityToHandleId_

private

Definition at line 264 of file TextureHandleRegistry.h.

mutex_

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

mutableprivate

Definition at line 266 of file TextureHandleRegistry.h.

pathToHandleIds_

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

private

Definition at line 265 of file TextureHandleRegistry.h.

---

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

• /workspace/magerbeton/gl3-vulkan/code/Engine/include/Engine/Texture/TextureHandleRegistry.h