ezEngine  Milestone 9
ezResourceManager Class Reference

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

#include <ResourceManager.h>

Static Public Member Functions

Loading and creating resources
template<typename ResourceType >
static ezTypedResourceHandle< ResourceType > LoadResource (const char *szResourceID)
 Returns a handle to the requested resource. szResourceID must uniquely identify the resource, different spellings / casing will result in different resources. More...
 
template<typename ResourceType >
static ezTypedResourceHandle< ResourceType > LoadResource (const char *szResourceID, ezResourcePriority Priority, ezTypedResourceHandle< ResourceType > hLoadingFallback)
 Same as LoadResource(), but additionally allows to set a priority on the resource and a custom fallback resource for this instance. More...
 
static ezTypelessResourceHandle LoadResourceByType (const ezRTTI *pResourceType, const char *szResourceID)
 Same as LoadResource(), but instead of a template argument, the resource type to use is given as ezRTTI info. Returns a typeless handle due to the missing template argument.
 
static ezString GenerateUniqueResourceID (const char *szResourceIDPrefix)
 Generates a unique resource ID with the given prefix. More...
 
template<typename ResourceType , typename DescriptorType >
static ezTypedResourceHandle< ResourceType > CreateResource (const char *szResourceID, DescriptorType &&descriptor, const char *szResourceDescription=nullptr)
 Creates a resource from a descriptor. More...
 
template<typename ResourceType >
static ezTypedResourceHandle< ResourceType > GetExistingResource (const char *szResourceID)
 Returns a handle to the resource with the given ID. If the resource does not exist, the handle is invalid. More...
 
static void PreloadResource (const ezTypelessResourceHandle &hResource, ezTime tShouldBeAvailableIn)
 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 bool FinishLoadingOfResources ()
 Makes sure all resources that are currently in the preload queue, are finished loading. More...
 
Reloading resources
static ezUInt32 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 ezUInt32 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 ezUInt32 ReloadResourcesOfType (const ezRTTI *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 ezTypedResourceHandle< 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 void UpdateResourceWithCustomLoader (const ezTypelessResourceHandle &hResource, ezUniquePtr< ezResourceTypeLoader > &&loader)
 Calls ReloadResource() on the given resource, but makes sure that the reload happens with the given custom loader. More...
 
template<typename ResourceType >
static void RestoreResource (const ezTypedResourceHandle< ResourceType > &hResource)
 Removes the 'PreventFileReload' flag and forces a reload on the resource. More...
 
Acquiring resources
template<typename ResourceType >
static ResourceType * BeginAcquireResource (const ezTypedResourceHandle< ResourceType > &hResource, ezResourceAcquireMode mode, const ezTypedResourceHandle< ResourceType > &hLoadingFallback=ezTypedResourceHandle< ResourceType >(), ezResourcePriority Priority=ezResourcePriority::Unchanged, ezResourceAcquireResult *out_AcquireResult=nullptr)
 Acquires a resource pointer from a handle. Prefer to use ezResourceLock, which wraps BeginAcquireResource / EndAcquireResource. More...
 
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 ezResourceLock instead.
 
Unloading resources
static ezUInt32 FreeUnusedResources (bool bFreeAllUnused)
 Deallocates all resources whose refcount has reached 0. Returns the number of deleted resources. More...
 
Miscellaneous
static ezMutexGetMutex ()
 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 ezResource::ResetResource() on all resources. More...
 
static void SetResourceLowResData (const ezTypelessResourceHandle &hResource, ezStreamReader *pStream)
 Calls ezResource::UpdateContent() to fill the resource with 'low resolution' data. More...
 
Type specific loaders
static void SetDefaultResourceLoader (ezResourceTypeLoader *pDefaultLoader)
 Sets the resource loader to use when no type specific resource loader is available.
 
static ezResourceTypeLoaderGetDefaultResourceLoader ()
 Returns the resource loader to use when no type specific resource loader is available.
 
template<typename ResourceType >
static void SetResourceTypeLoader (ezResourceTypeLoader *pCreator)
 Sets the resource loader to use for the given resource type. More...
 
Named resources
static void RegisterNamedResource (const char *szLookupName, const char *szRedirectionResource)
 Registers a 'named' resource. When a resource is looked up using szLookupName, the lookup will be redirected to szRedirectionResource. More...
 
static void UnregisterNamedResource (const char *szLookupName)
 Removes a previously registered name from the redirection table.
 
Asset system interaction
static void RegisterResourceForAssetType (const char *szAssetTypeName, const ezRTTI *pResourceType)
 Registers which resource type to use to load an asset with the given type name.
 
static const ezRTTIFindResourceForAssetType (const char *szAssetTypeName)
 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 ()
 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.
 
template<typename ResourceType >
static ezTypedResourceHandle< ResourceType > GetResourceHandleForExport (const char *szResourceID)
 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 ezRTTI *pDerivedTypeToUse, ezDelegate< bool(const ezStringBuilder &)> OverrideDecider)
 Registers a resource type to be used instead of any of it's base classes, when loading specific data. More...
 
static void UnregisterResourceOverrideType (const ezRTTI *pDerivedTypeToUse)
 Unregisters pDerivedTypeToUse as an override resource. More...
 

Friends

class ezResource
 
class ezResourceManagerWorkerDiskRead
 
class ezResourceManagerWorkerMainThread
 
class ezResourceHandleReadContext
 

Events

static ezEvent< const ezResourceEvent & > s_ResourceEvents
 
static ezEvent< const ezResourceManagerEvent & > s_ManagerEvents
 Events for the resource manager that affect broader things.
 
static void BroadcastExistsEvent ()
 Goes through all existing resources and broadcasts the 'Exists' event. More...
 

Resource Fallbacks

using ResourceCleanupCB = ezDelegate< void()>
 
template<typename RESOURCE_TYPE >
static void SetResourceTypeLoadingFallback (const ezTypedResourceHandle< 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 ezTypedResourceHandle< RESOURCE_TYPE > & GetResourceTypeLoadingFallback ()
 
template<typename RESOURCE_TYPE >
static void SetResourceTypeMissingFallback (const ezTypedResourceHandle< RESOURCE_TYPE > &hResource)
 Specifies which resource to use as a missing fallback for the given type, when a resource cannot be loaded. More...
 
template<typename RESOURCE_TYPE >
static const ezTypedResourceHandle< RESOURCE_TYPE > & GetResourceTypeMissingFallback ()
 
static void AddResourceCleanupCallback (ResourceCleanupCB cb)
 [internal] Used by ezResource 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.
 

Detailed Description

The central class for managing all types derived from ezResource.

Member Function Documentation

◆ BeginAcquireResource()

template<typename ResourceType >
ResourceType * ezResourceManager::BeginAcquireResource ( const ezTypedResourceHandle< ResourceType > &  hResource,
ezResourceAcquireMode  mode,
const ezTypedResourceHandle< ResourceType > &  hLoadingFallback = ezTypedResourceHandle<ResourceType>(),
ezResourcePriority  Priority = ezResourcePriority::Unchanged,
ezResourceAcquireResult *  out_AcquireResult = nullptr 
)
static

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

Parameters
hResourceThe resource to acquire
modeThe desired way to acquire the resource. See ezResourceAcquireMode for details.
hLoadingFallbackA custom fallback resource that should be returned if hResource is not yet available. Allows to use domain specific knowledge to get a better fallback.
PriorityAllows to adjust the priority of the resource. This will affect how fast the resource is loaded, in case it is not yet available.
out_AcquireResultReturns how successful the acquisition was. See ezResourceAcquireResult for details.

◆ BroadcastExistsEvent()

void ezResourceManager::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 ezResourceManager::ClearResourceCleanupCallback ( ResourceCleanupCB  cb)
static

◆ CreateResource()

template<typename ResourceType , typename DescriptorType >
ezTypedResourceHandle< ResourceType > ezResourceManager::CreateResource ( const char *  szResourceID,
DescriptorType &&  descriptor,
const char *  szResourceDescription = nullptr 
)
static

Creates a resource from a descriptor.

Parameters
szResourceIDThe unique ID by which the resource is identified. E.g. in GetExistingResource()
descriptorA type specific descriptor that holds all the information to create the resource.
szResourceDescriptionAn 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.

◆ FinishLoadingOfResources()

bool ezResourceManager::FinishLoadingOfResources ( )
static

Makes sure all resources that are currently in the preload queue, are finished loading.

Returns whether any resources were waited for.

Note
This will only wait for the preload queue to be empty at this point in time. It does not mean that all resources are fully loaded (all levels-of-detail). Once you render a frame, more resources might end up in the preload queue again. So if one wants to make a full detail screenshot and have all resources loaded with all details, one must render multiple frames and only make a screenshot once no resources where waited for anymore.

◆ FreeUnusedResources()

ezUInt32 ezResourceManager::FreeUnusedResources ( bool  bFreeAllUnused)
static

Deallocates all resources whose refcount has reached 0. Returns the number of deleted resources.

If bFreeAllUnused is false, the function only iterates once over the known resources. This may miss resources that are unreferenced after another resource was unloaded. If bFreeAllUnused is true, it will repeat the step as long as it finds resources that can be deallocated.

◆ GenerateUniqueResourceID()

ezString ezResourceManager::GenerateUniqueResourceID ( const char *  szResourceIDPrefix)
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 >
ezTypedResourceHandle< ResourceType > ezResourceManager::GetExistingResource ( const char *  szResourceID)
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.

◆ GetResourceTypeLoadingFallback()

template<typename RESOURCE_TYPE >
static const ezTypedResourceHandle<RESOURCE_TYPE>& ezResourceManager::GetResourceTypeLoadingFallback ( )
inlinestatic

◆ GetResourceTypeMissingFallback()

template<typename RESOURCE_TYPE >
static const ezTypedResourceHandle<RESOURCE_TYPE>& ezResourceManager::GetResourceTypeMissingFallback ( )
inlinestatic

◆ LoadResource() [1/2]

template<typename ResourceType >
ezTypedResourceHandle< ResourceType > ezResourceManager::LoadResource ( const char *  szResourceID)
static

Returns a handle to the requested resource. szResourceID 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 / ezResourceLock 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 >
ezTypedResourceHandle< ResourceType > ezResourceManager::LoadResource ( const char *  szResourceID,
ezResourcePriority  Priority,
ezTypedResourceHandle< 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 ezResourcePriority::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 ezResourceManager::RegisterNamedResource ( const char *  szLookupName,
const char *  szRedirectionResource 
)
static

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

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()

void ezResourceManager::RegisterResourceOverrideType ( const ezRTTI pDerivedTypeToUse,
ezDelegate< bool(const ezStringBuilder &)>  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 ezFileSystem. 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 ezResourceManager::ResetAllResources ( )
static

Calls ezResource::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()

template<typename ResourceType >
void ezResourceManager::RestoreResource ( const ezTypedResourceHandle< ResourceType > &  hResource)
static

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

See also
UpdateResourceWithCustomLoader()

◆ SetResourceLowResData()

void ezResourceManager::SetResourceLowResData ( const ezTypelessResourceHandle hResource,
ezStreamReader pStream 
)
static

Calls ezResource::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 >
ezResourceManager::SetResourceTypeLoader< ezRenderToTexture2DResource > ( ezResourceTypeLoader 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 >
ezResourceManager::SetResourceTypeMissingFallback< ezProceduralPlacementResource > ( const ezTypedResourceHandle< 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 ezResourceManager::UnregisterResourceOverrideType ( const ezRTTI pDerivedTypeToUse)
static

Unregisters pDerivedTypeToUse as an override resource.

See also
RegisterResourceOverrideType()

◆ UpdateResourceWithCustomLoader()

void ezResourceManager::UpdateResourceWithCustomLoader ( const ezTypelessResourceHandle hResource,
ezUniquePtr< ezResourceTypeLoader > &&  loader 
)
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 ezResourceLoaderFromMemory 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()

Member Data Documentation

◆ s_ResourceEvents

ezEvent< const ezResourceEvent & > ezResourceManager::s_ResourceEvents
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.


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