The central class for managing all types derived from xiiResource. More...

#include <ResourceManager.h>

Public Member Functions
template<typename ResourceType>
XII_FORCE_INLINE ResourceType *	GetResource (xiiStringView sResourceID, bool bIsReloadable)

template<typename ResourceType>
XII_FORCE_INLINE xiiTypedResourceHandle< ResourceType >	LoadResource (xiiStringView sResourceID)

Static Public Member Functions
Events
static const xiiEvent< const xiiResourceEvent &, xiiMutex > &	GetResourceEvents ()

static const xiiEvent< const xiiResourceManagerEvent &, xiiMutex > &	GetManagerEvents ()
	Events for the resource manager that affect broader things.

static void	BroadcastExistsEvent ()
	Goes through all existing resources and broadcasts the 'Exists' event.

Loading and creating resources
template<typename ResourceType>
static xiiTypedResourceHandle< ResourceType >	LoadResource (xiiStringView sResourceID)
	Returns a handle to the requested resource. sResourceID must uniquely identify the resource, different spellings / casing will result in different resources.

template<typename ResourceType>
static xiiTypedResourceHandle< ResourceType >	LoadResource (xiiStringView sResourceID, xiiTypedResourceHandle< ResourceType > hLoadingFallback)
	Same as LoadResource(), but additionally allows to set a priority on the resource and a custom fallback resource for this instance.

static xiiTypelessResourceHandle	LoadResourceByType (const xiiRTTI *pResourceType, xiiStringView sResourceID)
	Same as LoadResource(), but instead of a template argument, the resource type to use is given as xiiRTTI info. Returns a typeless handle due to the missing template argument.

static bool	IsAnyLoadingInProgress ()
	Checks whether any resource loading is in progress.

static xiiString	GenerateUniqueResourceID (xiiStringView sResourceIDPrefix)
	Generates a unique resource ID with the given prefix.

template<typename ResourceType, typename DescriptorType>
static xiiTypedResourceHandle< ResourceType >	CreateResource (xiiStringView sResourceID, DescriptorType &&descriptor, xiiStringView sResourceDescription=nullptr)
	Creates a resource from a descriptor.

template<typename ResourceType, typename DescriptorType>
static xiiTypedResourceHandle< ResourceType >	GetOrCreateResource (xiiStringView sResourceID, DescriptorType &&descriptor, xiiStringView sResourceDescription=nullptr)
	Returns a handle to the resource with the given ID if it exists or creates it from a descriptor.

template<typename ResourceType>
static xiiTypedResourceHandle< ResourceType >	GetExistingResource (xiiStringView sResourceID)
	Returns a handle to the resource with the given ID. If the resource does not exist, the handle is invalid.

static xiiTypelessResourceHandle	GetExistingResourceByType (const xiiRTTI *pResourceType, xiiStringView sResourceID)
	Same as GetExistingResourceByType() but allows to specify the resource type as a xiiRTTI.

template<typename ResourceType>
static xiiTypedResourceHandle< ResourceType >	GetExistingResourceOrCreateAsync (xiiStringView sResourceID, xiiUniquePtr< xiiResourceTypeLoader > &&pLoader, xiiTypedResourceHandle< ResourceType > hLoadingFallback={})

static xiiTypelessResourceHandle	GetExistingResourceOrCreateAsync (const xiiRTTI *pResourceType, xiiStringView sResourceID, xiiUniquePtr< xiiResourceTypeLoader > &&pLoader)

static void	PreloadResource (const xiiTypelessResourceHandle &hResource)
	Triggers loading of the given resource. tShouldBeAvailableIn specifies how long the resource is not yet needed, thus allowing other resources to be loaded first. This is only a hint and there are no guarantees when the resource is available.

static void	ForceLoadResourceNow (const xiiTypelessResourceHandle &hResource)
	Similar to locking a resource with 'BlockTillLoaded' acquire mode, but can be done with a typeless handle and does not return a result.

static xiiResourceState	GetLoadingState (const xiiTypelessResourceHandle &hResource)
	Returns the current loading state of the given resource.

Reloading resources
static xiiUInt32	ReloadAllResources (bool bForce)
	Goes through all resources and makes sure they are reloaded, if they have changed. If bForce is true, all resources are updated, even if there is no indication that they have changed.

template<typename ResourceType>
static xiiUInt32	ReloadResourcesOfType (bool bForce)
	Goes through all resources of the given type and makes sure they are reloaded, if they have changed. If bForce is true, resources are updated, even if there is no indication that they have changed.

static xiiUInt32	ReloadResourcesOfType (const xiiRTTI *pType, bool bForce)
	Goes through all resources of the given type and makes sure they are reloaded, if they have changed. If bForce is true, resources are updated, even if there is no indication that they have changed.

template<typename ResourceType>
static bool	ReloadResource (const xiiTypedResourceHandle< ResourceType > &hResource, bool bForce)
	Reloads only the one specific resource. If bForce is true, it is updated, even if there is no indication that it has changed.

static bool	ReloadResource (const xiiRTTI *pType, const xiiTypelessResourceHandle &hResource, bool bForce)
	Reloads only the one specific resource. If bForce is true, it is updated, even if there is no indication that it has changed.

static void	UpdateResourceWithCustomLoader (const xiiTypelessResourceHandle &hResource, xiiUniquePtr< xiiResourceTypeLoader > &&pLoader)
	Calls ReloadResource() on the given resource, but makes sure that the reload happens with the given custom loader.

static void	RestoreResource (const xiiTypelessResourceHandle &hResource)
	Removes the 'PreventFileReload' flag and forces a reload on the resource.

Acquiring resources
template<typename ResourceType>
static ResourceType *	BeginAcquireResource (const xiiTypedResourceHandle< ResourceType > &hResource, xiiResourceAcquireMode mode, const xiiTypedResourceHandle< ResourceType > &hLoadingFallback=xiiTypedResourceHandle< ResourceType >(), xiiResourceAcquireResult *out_pAcquireResult=nullptr)
	Acquires a resource pointer from a handle. Prefer to use xiiResourceLock, which wraps BeginAcquireResource / EndAcquireResource.

static xiiResource *	BeginAcquireResourcePointer (const xiiRTTI *pType, const xiiTypelessResourceHandle &hResource)
	Same as BeginAcquireResource but only for the base resource pointer.

template<typename ResourceType>
static void	EndAcquireResource (ResourceType *pResource)
	Needs to be called in concert with BeginAcquireResource() after accessing a resource has been finished. Prefer to use xiiResourceLock instead.

static void	EndAcquireResourcePointer (xiiResource *pResource)
	Same as EndAcquireResource but without the template parameter. See also BeginAcquireResourcePointer.

static void	ForceNoFallbackAcquisition (xiiUInt32 uiNumFrames=0xFFFFFFFFU)
	Forces the resource manager to treat xiiResourceAcquireMode::AllowLoadingFallback as xiiResourceAcquireMode::BlockTillLoaded on BeginAcquireResource.

static xiiUInt32	GetForceNoFallbackAcquisition ()
	If the returned number is greater 0 the resource manager treats xiiResourceAcquireMode::AllowLoadingFallback as xiiResourceAcquireMode::BlockTillLoaded on BeginAcquireResource.

template<typename ResourceType>
static xiiLockedObject< xiiMutex, xiiDynamicArray< xiiResource * > >	GetAllResourcesOfType ()
	Retrieves an array of pointers to resources of the indicated type which are loaded at the moment. Destroy the returned object as soon as possible as it holds the entire resource manager locked.

Miscellaneous
static xiiMutex &	GetMutex ()
	Returns the resource manager mutex. Allows to lock the manager on a thread when multiple operations need to be done in sequence.

static void	PerFrameUpdate ()
	Must be called once per frame for some bookkeeping.

static void	EngineAboutToShutdown ()
	Makes sure that no further resource loading will take place.

static void	ResetAllResources ()
	Calls xiiResource::ResetResource() on all resources.

static void	SetResourceLowResData (const xiiTypelessResourceHandle &hResource, xiiStreamReader *pStream)
	Calls xiiResource::UpdateContent() to fill the resource with 'low resolution' data.

Type specific loaders
static void	SetDefaultResourceLoader (xiiResourceTypeLoader *pDefaultLoader)
	Sets the resource loader to use when no type specific resource loader is available.

static xiiResourceTypeLoader *	GetDefaultResourceLoader ()
	Returns the resource loader to use when no type specific resource loader is available.

template<typename ResourceType>
static void	SetResourceTypeLoader (xiiResourceTypeLoader *pCreator)
	Sets the resource loader to use for the given resource type.

Named resources
static void	RegisterNamedResource (xiiStringView sLookupName, xiiStringView sRedirectionResource)
	Registers a 'named' resource. When a resource is looked up using sLookupName, the lookup will be redirected to sRedirectionResource.

static void	UnregisterNamedResource (xiiStringView sLookupName)
	Removes a previously registered name from the redirection table.

Asset system interaction
static void	RegisterResourceForAssetType (xiiStringView sAssetTypeName, const xiiRTTI *pResourceType)
	Registers which resource type to use to load an asset with the given type name.

static const xiiRTTI *	FindResourceForAssetType (xiiStringView sAssetTypeName)
	Returns the resource type that was registered to handle the given asset type for loading. nullptr if no resource type was registered for this asset type.

Export mode
static void	EnableExportMode (bool bEnable)
	Enables export mode. In this mode the resource manager will assert when it actually tries to load a resource. This can be useful when exporting resource handles but the actual resource content is not needed.

static bool	IsExportModeEnabled ()
	Returns whether export mode is active.

template<typename ResourceType>
static xiiTypedResourceHandle< ResourceType >	GetResourceHandleForExport (xiiStringView sResourceID)
	Creates a resource handle for the given resource ID. This method can only be used if export mode is enabled. Internally it will create a resource but does not load the content. This way it can be ensured that the resource handle is always only the size of a pointer.

Resource Type Overrides
static void	RegisterResourceOverrideType (const xiiRTTI *pDerivedTypeToUse, xiiDelegate< bool(const xiiStringBuilder &)> overrideDecider)
	Registers a resource type to be used instead of any of it's base classes, when loading specific data.

static void	UnregisterResourceOverrideType (const xiiRTTI *pDerivedTypeToUse)
	Unregisters pDerivedTypeToUse as an override resource.

Friends
class	xiiResourceManagerState

class	xiiResource

class	xiiResourceManagerWorkerDataLoad

class	xiiResourceManagerWorkerUpdateContent

class	xiiResourceHandleReadContext

Resource Fallbacks
using	ResourceCleanupCB = xiiDelegate<void()>

template<typename RESOURCE_TYPE>
static void	SetResourceTypeLoadingFallback (const xiiTypedResourceHandle< RESOURCE_TYPE > &hResource)
	Specifies which resource to use as a loading fallback for the given type, while a resource is not yet loaded.

template<typename RESOURCE_TYPE>
static const xiiTypedResourceHandle< RESOURCE_TYPE > &	GetResourceTypeLoadingFallback ()

template<typename RESOURCE_TYPE>
static void	SetResourceTypeMissingFallback (const xiiTypedResourceHandle< RESOURCE_TYPE > &hResource)
	Specifies which resource to use as a missing fallback for the given type, when a resource cannot be loaded.

template<typename RESOURCE_TYPE>
static const xiiTypedResourceHandle< RESOURCE_TYPE > &	GetResourceTypeMissingFallback ()

static void	AddResourceCleanupCallback (ResourceCleanupCB cb)
	[internal] Used by xiiResource to register a cleanup function to be called at resource manager shutdown.

static void	ClearResourceCleanupCallback (ResourceCleanupCB cb)

static void	ExecuteAllResourceCleanupCallbacks ()
	This will clear ALL resources that were registered as 'missing' or 'loading' fallback resources. This is called early during system shutdown to clean up resources.

Unloading resources
static xiiUInt32	FreeAllUnusedResources ()
	Deallocates all resources whose refcount has reached 0. Returns the number of deleted resources.

static xiiUInt32	FreeUnusedResources (xiiTime timeout, xiiTime lastAcquireThreshold)
	Deallocates resources whose refcount has reached 0. Returns the number of deleted resources.

static void	SetAutoFreeUnused (xiiTime timeout, xiiTime lastAcquireThreshold)
	If timeout is not zero, FreeUnusedResources() is called once every frame with the given parameters.

template<typename ResourceType>
static void	SetIncrementalUnloadForResourceType (bool bActive)
	If set to 'false' resources of the given type will not be incrementally unloaded in the background, when they are not referenced anymore.

template<typename TypeBeingUpdated, typename TypeItWantsToAcquire>
static void	AllowResourceTypeAcquireDuringUpdateContent ()

static void	AllowResourceTypeAcquireDuringUpdateContent (const xiiRTTI pTypeBeingUpdated, const xiiRTTI pTypeItWantsToAcquire)

static bool	IsResourceTypeAcquireDuringUpdateContentAllowed (const xiiRTTI pTypeBeingUpdated, const xiiRTTI pTypeItWantsToAcquire)

Resource Priorities
template<typename RESOURCE_TYPE>
static void	SetResourceTypeDefaultPriority (xiiResourcePriority priority)
	Specifies which resource to use as a loading fallback for the given type, while a resource is not yet loaded.

Detailed Description

The central class for managing all types derived from xiiResource.

Member Function Documentation

◆ BeginAcquireResource()

template<typename ResourceType>

ResourceType * xiiResourceManager::BeginAcquireResource	(	const xiiTypedResourceHandle< ResourceType > &	hResource,
		xiiResourceAcquireMode	mode,
		const xiiTypedResourceHandle< ResourceType > &	hLoadingFallback = xiiTypedResourceHandle<ResourceType>(),
		xiiResourceAcquireResult *	out_pAcquireResult = nullptr )

static

Acquires a resource pointer from a handle. Prefer to use xiiResourceLock, which wraps BeginAcquireResource / EndAcquireResource.

Parameters

hResource	The resource to acquire
mode	The desired way to acquire the resource. See xiiResourceAcquireMode for details.
hLoadingFallback	A custom fallback resource that should be returned if hResource is not yet available. Allows to use domain specific knowledge to get a better fallback.
Priority	Allows to adjust the priority of the resource. This will affect how fast the resource is loaded, in case it is not yet available.
out_AcquireResult	Returns how successful the acquisition was. See xiiResourceAcquireResult for details.

◆ BroadcastExistsEvent()

void xiiResourceManager::BroadcastExistsEvent ( )

static

Goes through all existing resources and broadcasts the 'Exists' event.

Used to announce all currently existing resources to interested event listeners (ie tools).

◆ ClearResourceCleanupCallback()

void xiiResourceManager::ClearResourceCleanupCallback ( ResourceCleanupCB cb )

static

See also: AddResourceCleanupCallback()

◆ CreateResource()

template<typename ResourceType, typename DescriptorType>

xiiTypedResourceHandle< ResourceType > xiiResourceManager::CreateResource	(	xiiStringView	sResourceID,
		DescriptorType &&	descriptor,
		xiiStringView	sResourceDescription = nullptr )

static

Creates a resource from a descriptor.

Parameters

sResourceID	The unique ID by which the resource is identified. E.g. in GetExistingResource()
descriptor	A type specific descriptor that holds all the information to create the resource.
sResourceDescription	An optional description that might help during debugging. Often a human readable name or path is stored here, to make it easier to identify this resource.

◆ GenerateUniqueResourceID()

xiiString xiiResourceManager::GenerateUniqueResourceID ( xiiStringView sResourceIDPrefix )

static

Generates a unique resource ID with the given prefix.

Provide a prefix that is preferably not used anywhere else (i.e., closely related to your code). If the prefix is not also used to manually generate resource IDs, this function is guaranteed to return a unique resource ID.

◆ GetExistingResource()

template<typename ResourceType>

xiiTypedResourceHandle< ResourceType > xiiResourceManager::GetExistingResource ( xiiStringView sResourceID )

static

Returns a handle to the resource with the given ID. If the resource does not exist, the handle is invalid.

Use this if a resource needs to be created procedurally (with CreateResource()), but might already have been created. If the returned handle is invalid, then just go through the resource creation step.

◆ GetOrCreateResource()

template<typename ResourceType, typename DescriptorType>

xiiTypedResourceHandle< ResourceType > xiiResourceManager::GetOrCreateResource	(	xiiStringView	sResourceID,
		DescriptorType &&	descriptor,
		xiiStringView	sResourceDescription = nullptr )

static

Returns a handle to the resource with the given ID if it exists or creates it from a descriptor.

Parameters

sResourceID	The unique ID by which the resource is identified. E.g. in GetExistingResource()
descriptor	A type specific descriptor that holds all the information to create the resource.
sResourceDescription	An optional description that might help during debugging. Often a human readable name or path is stored here, to make it easier to identify this resource.

◆ GetResourceEvents()

const xiiEvent< const xiiResourceEvent &, xiiMutex > & xiiResourceManager::GetResourceEvents ( )

static

Events on individual resources. Subscribe to this to get a notification for events happening on any resource. If you are only interested in events for a specific resource, subscribe on directly on that instance.

◆ GetResourceTypeLoadingFallback()

template<typename RESOURCE_TYPE>

static const xiiTypedResourceHandle< RESOURCE_TYPE > & xiiResourceManager::GetResourceTypeLoadingFallback ( )

inlinestatic

See also: SetResourceTypeLoadingFallback()

◆ GetResourceTypeMissingFallback()

template<typename RESOURCE_TYPE>

static const xiiTypedResourceHandle< RESOURCE_TYPE > & xiiResourceManager::GetResourceTypeMissingFallback ( )

inlinestatic

See also: SetResourceTypeMissingFallback()

◆ LoadResource() [1/2]

template<typename ResourceType>

static xiiTypedResourceHandle< ResourceType > xiiResourceManager::LoadResource ( xiiStringView sResourceID )

static

Returns a handle to the requested resource. sResourceID must uniquely identify the resource, different spellings / casing will result in different resources.

After the call to this function the resource definitely exists in memory. Upon access through BeginAcquireResource / xiiResourceLock the resource will be loaded. If it is not possible to load the resource it will change to a 'missing' state. If the code accessing the resource cannot handle that case, the application will 'terminate' (that means crash).

◆ LoadResource() [2/2]

template<typename ResourceType>

xiiTypedResourceHandle< ResourceType > xiiResourceManager::LoadResource	(	xiiStringView	sResourceID,
		xiiTypedResourceHandle< ResourceType >	hLoadingFallback )

static

Same as LoadResource(), but additionally allows to set a priority on the resource and a custom fallback resource for this instance.

Pass in xiiResourcePriority::Unchanged, if you only want to specify a custom fallback resource. If a resource priority is specified, the target resource will get that priority. If a valid fallback resource is specified, the resource will store that as its instance specific fallback resource. This will be used when trying to acquire the resource later.

◆ RegisterNamedResource()

void xiiResourceManager::RegisterNamedResource	(	xiiStringView	sLookupName,
		xiiStringView	sRedirectionResource )

static

Registers a 'named' resource. When a resource is looked up using sLookupName, the lookup will be redirected to sRedirectionResource.

This can be used to register a resource under an easier to use name. For example one can register "MenuBackground" as the name for "{ E50DCC85-D375-4999-9CFE-42F1377FAC85 }". If the lookup name already exists, it will be overwritten.

◆ RegisterResourceOverrideType()

xiiResourceManager::RegisterResourceOverrideType	(	const xiiRTTI *	pDerivedTypeToUse,
		xiiDelegate< bool(const xiiStringBuilder &)>	overrideDecider )

static

Registers a resource type to be used instead of any of it's base classes, when loading specific data.

When resource B is derived from A it can be registered to be instantiated when loading data, even if the code specifies to use a resource of type A. Whenever LoadResource<A>() is executed, the registered callback OverrideDecider is run to figure out whether B should be instantiated instead. If OverrideDecider returns true, B is used.

OverrideDecider is given the resource ID after it has been resolved by the xiiFileSystem. So it has to be able to make its decision from the file path, name or extension. The override is registered for all base classes of pDerivedTypeToUse, in case the derivation hierarchy is longer.

Without calling this at startup, a derived resource type has to be manually requested in code.

◆ ResetAllResources()

void xiiResourceManager::ResetAllResources ( )

static

Calls xiiResource::ResetResource() on all resources.

This is mostly for usage in tools to reset resource whose state can be modified at runtime, to reset them to their original state.

◆ RestoreResource()

void xiiResourceManager::RestoreResource ( const xiiTypelessResourceHandle & hResource )

static

Removes the 'PreventFileReload' flag and forces a reload on the resource.

See also: UpdateResourceWithCustomLoader()

◆ SetResourceLowResData()

void xiiResourceManager::SetResourceLowResData	(	const xiiTypelessResourceHandle &	hResource,
		xiiStreamReader *	pStream )

static

Calls xiiResource::UpdateContent() to fill the resource with 'low resolution' data.

This will early out, if the resource has gotten low-res data before. The resource itself may ignore the data, if it has already gotten low/high res data before.

The typical use case is, that some other piece of code stores a low-res version of a resource to be able to get a resource into a usable state. For instance, a material may store low resolution texture data for every texture that it references. Then when 'loading' the textures, it can pass this low-res data to the textures, such that rendering can give decent results right away. If the textures have already been loaded before, or some other material already had low-res data, the call exits quickly.

◆ SetResourceTypeLoader()

template<typename ResourceType>

xiiResourceManager::SetResourceTypeLoader< xiiConfigFileResource > ( xiiResourceTypeLoader * pCreator )

static

Sets the resource loader to use for the given resource type.

Note: This is bound to one specific type. Derived types do not inherit the type loader.

◆ SetResourceTypeMissingFallback()

template<typename RESOURCE_TYPE>

xiiResourceManager::SetResourceTypeMissingFallback< xiiConfigFileResource > ( const xiiTypedResourceHandle< RESOURCE_TYPE > & hResource )

inlinestatic

Specifies which resource to use as a missing fallback for the given type, when a resource cannot be loaded.

Note: If no missing fallback is specified, trying to load a resource that does not exist will assert at runtime.

◆ UnregisterResourceOverrideType()

void xiiResourceManager::UnregisterResourceOverrideType ( const xiiRTTI * pDerivedTypeToUse )

static

Unregisters pDerivedTypeToUse as an override resource.

See also: RegisterResourceOverrideType()

◆ UpdateResourceWithCustomLoader()

void xiiResourceManager::UpdateResourceWithCustomLoader	(	const xiiTypelessResourceHandle &	hResource,
		xiiUniquePtr< xiiResourceTypeLoader > &&	pLoader )

static

Calls ReloadResource() on the given resource, but makes sure that the reload happens with the given custom loader.

Use this e.g. with a xiiResourceLoaderFromMemory to replace an existing resource with new data that was created on-the-fly. Using this function will set the 'PreventFileReload' flag on the resource and thus prevent further reload actions.

See also: RestoreResource()

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

/home/runner/work/XII/XII/Source/Engine/Core/ResourceManager/ResourceManager.h
/home/runner/work/XII/XII/Source/Engine/Core/ResourceManager/Implementation/ResourceLoading.cpp
/home/runner/work/XII/XII/Source/Engine/Core/ResourceManager/Implementation/ResourceManager.cpp
/home/runner/work/XII/XII/Source/Engine/Core/ResourceManager/Implementation/ResourceManager_inl.h
/home/runner/work/XII/XII/Source/Engine/GraphicsCore/Decals/Implementation/DecalAtlasResource.cpp
/home/runner/work/XII/XII/Source/Engine/GraphicsCore/Decals/Implementation/DecalResource.cpp
/home/runner/work/XII/XII/Source/Engine/GraphicsCore/Textures/Implementation/TextureLoader.cpp
/home/runner/work/XII/XII/Source/Engine/Utilities/Resources/ConfigFileResource.cpp
/home/runner/work/XII/XII/Source/EnginePlugins/VisualScriptPlugin/Resources/Implementation/VisualScriptClassResource.cpp

Public Member Functions

Static Public Member Functions

Friends

Resource Fallbacks

Unloading resources

Resource Priorities

Detailed Description

Member Function Documentation

◆ BeginAcquireResource()

◆ BroadcastExistsEvent()

◆ ClearResourceCleanupCallback()

◆ CreateResource()

◆ GenerateUniqueResourceID()

◆ GetExistingResource()

◆ GetOrCreateResource()

◆ GetResourceEvents()

◆ GetResourceTypeLoadingFallback()

◆ GetResourceTypeMissingFallback()

◆ LoadResource() [1/2]

◆ LoadResource() [2/2]

◆ RegisterNamedResource()

◆ RegisterResourceOverrideType()

◆ ResetAllResources()

◆ RestoreResource()

◆ SetResourceLowResData()

◆ SetResourceTypeLoader()

◆ SetResourceTypeMissingFallback()

◆ UnregisterResourceOverrideType()

◆ UpdateResourceWithCustomLoader()