Class ResourceRegistry¶

Defined in File resource_registry.h

Class Documentation¶

class ResourceRegistry¶

Central manager for asynchronous resource loading and lifetime management.

The ResourceRegistry is the core of the resource system. It provides the primary API for loading resources (textures, meshes, materials, etc.) with asynchronous job system integration.

Architecture:

The registry is a Module that depends on:

ReferenceManager: Tracks reference counts for future unloading support
ResourceDatabase: Provides filesystem abstraction and metadata
SchedulerModule: Job system for async loading
SystemOrchestrator: ECS integration

Internal State:

The registry maintains three key data structures:

resources: DenseMap of loaded resources (StringId → Reference<Resource>)
pending_resources: DenseSet of resources currently loading
errored_resources: DenseSet of resources that failed to load

All access to these structures is protected by a SpinLock for thread safety.

Loading Flow:

User calls load<T>(resource_id) → returns ResourceReference<T> immediately
Registry checks if resource exists/is pending → early return if so
Registry dispatches load_resource() coroutine to job system
Coroutine queries database for metadata → creates source → loads via loader
Resource moves from pending_resources to resources
ResourceReference lazily discovers loaded resource when queried

Resource Identity:

Resources are identified by StringId (hash of the resource path):

resource_id: The StringId used for lookups (e.g., STRING_ID(“textures/albedo.png”))
resource_handle: Internal handle (currently same as resource_id)

Current Limitations:

No unloading: Resources stay loaded forever (TODO at line 77)
No streaming: Large resources must fit in memory
No hot-reload: Changes require restart

Usage Example (Async):

// Request async load (returns immediately)
auto texture_ref = registry.load<TextureResource>(STRING_ID("textures/albedo.png"));

// Poll each frame until ready
if (texture_ref.is_valid()) {
    auto& texture = texture_ref.get();
    renderer.bind_texture(texture);
}

Usage Example (Immediate):

// Block until loaded (for startup resources)
auto mesh_ref = registry.immediate_load<MeshResource>(STRING_ID("models/character.gltf"));
// mesh_ref.is_valid() is guaranteed true here (or Error if failed)

See also

ResourceReference for the handle API

See also

ResourceDatabase for metadata and file access

See also

LoaderFactory for loader selection

See also

ReferenceManager for reference counting

Public Functions

ResourceRegistry(const Project &project, ecs::Registry &ecs_registry, jobs::Scheduler &scheduler, ResourceDatabase &database, ReferenceManager &reference_manager, const renderer::vulkan::VulkanContext &context)¶

Constructor.

Parameters:

ecs_registry –
scheduler –
database –
reference_manager –
context – Vulkan context for resource creation

~ResourceRegistry() noexcept¶

template<ResourceConcept T> inline ResourceReference<T> load(StringId resource_id)¶

Request an asynchronous load for a resource based on its unique id and returns a reference. The returned reference is invalid until the resource is loaded, once its loaded it can be accessed through the ResourceReference api

Note

Resources cannot have an invalid state but a reference can have one, make sure to test it before using the underlying resource.

Note

the resource id is different from the resource handle, while both are unique per resource.

Template Parameters:: T – The underlying requested resource type
Parameters:: resource_id – The resource id
Returns:: A reference to the resource

template<ResourceConcept T> inline ResourceReference<T> immediate_load(StringId resource_id)¶

Request an immediate load of a resource based on its unique id and returns a reference to it.

Template Parameters:: T – The underlying requested resource type
Parameters:: resource_id – The resource id
Returns:: A reference to the resource

template<ResourceConcept T> inline ResourceReference<T> get(const StringId resource_id)¶

Get a reference to an existing resource of type T, but does not attempt to create it if not loaded. If the resource does not exist, returns a null reference.

Template Parameters:: T – The underlying requested resource type
Parameters:: resource_id – The resource id
Returns:: A reference to the resource, if exists

template<ResourceConcept T, typename ...Args> inline Reference<T> allocate(const StringId id, Args&&... args)¶

Allocated a resource of type T in the registry, returns a pointer to it (not a ResourceReference) Resources allocated this way are considered loaded and can be used straight away

Template Parameters:

T – The type of the resource

Parameters:

id – A handle to the resource
args – The constructor arguments for the resource

Returns:

A pointer to the resource

Job<Reference<Resource>> load_direct(const SourceMetadata &meta, const resources::ResourceSource &source)¶

Directly loads a resource from a source (through the corresponding loader)

Parameters:

meta – The source metadata
source – A type erased source

Returns:

A pointer to the created resource

void wait_all(std::span<Job<>> jobs) const¶

template<typename T> inline auto list_all_resources_of_type()¶

inline ecs::Registry &get_ecs_registry() const¶

Protected Functions

std::expected<Reference<Resource>, ResourceState> get_resource(const StringId &id)¶

Gets a pointer to the resource from a handle, if the resource is invalid, returns the invalid state instead

Parameters:: id – The handle to the resource
Returns:: A resource pointer if valid, the invalid state as a ResourceState enum otherwise

void create_resource(const StringId &resource_id, ResourceType type)¶

Creates a new resource asynchronously in the registry and returns a handle to it. If the resource exists already (either in pending or loaded), returns the existing handle

Parameters:

resource_id – The resource id.
type – The type of the resource.

Returns:

A handle to the resource

void create_resource_immediate(const StringId &resource_id, ResourceType type)¶

Much like the create_resource this function creates a resource and returns a hanlde, but blocks until the resource creation is done. If the resource exists already (either in pending or loaded), returns the existing handle

Parameters:

resource_id – The resource id.
type – The type of the resource.

Returns:

A handle to the resource

Job<Reference<Resource>> load_resource(StringId handle)¶