Resource cache subsystem. Loads resources on demand and stores them for later access. More...

#include <Urho3D/Resource/ResourceCache.h>

Inheritance diagram for Urho3D::ResourceCache:
[legend]
Collaboration diagram for Urho3D::ResourceCache:
[legend]

Public Member Functions

 ResourceCache (Context *context)
 Construct.
 
 ~ResourceCache () override
 Destruct. Free all resources.
 
bool AddResourceDir (const String &pathName, unsigned priority=PRIORITY_LAST)
 Add a resource load directory. Optional priority parameter which will control search order.
 
bool AddPackageFile (PackageFile *package, unsigned priority=PRIORITY_LAST)
 Add a package file for loading resources from. Optional priority parameter which will control search order.
 
bool AddPackageFile (const String &fileName, unsigned priority=PRIORITY_LAST)
 Add a package file for loading resources from by name. Optional priority parameter which will control search order.
 
bool AddManualResource (Resource *resource)
 Add a manually created resource. Must be uniquely named within its type.
 
void RemoveResourceDir (const String &pathName)
 Remove a resource load directory.
 
void RemovePackageFile (PackageFile *package, bool releaseResources=true, bool forceRelease=false)
 Remove a package file. Optionally release the resources loaded from it.
 
void RemovePackageFile (const String &fileName, bool releaseResources=true, bool forceRelease=false)
 Remove a package file by name. Optionally release the resources loaded from it.
 
void ReleaseResource (StringHash type, const String &name, bool force=false)
 Release a resource by name.
 
void ReleaseResources (StringHash type, bool force=false)
 Release all resources of a specific type.
 
void ReleaseResources (StringHash type, const String &partialName, bool force=false)
 Release resources of a specific type and partial name.
 
void ReleaseResources (const String &partialName, bool force=false)
 Release resources of all types by partial name.
 
void ReleaseAllResources (bool force=false)
 Release all resources. When called with the force flag false, releases all currently unused resources.
 
bool ReloadResource (Resource *resource)
 Reload a resource. Return true on success. The resource will not be removed from the cache in case of failure.
 
void ReloadResourceWithDependencies (const String &fileName)
 Reload a resource based on filename. Causes also reload of dependent resources if necessary.
 
void SetMemoryBudget (StringHash type, unsigned long long budget)
 
void SetAutoReloadResources (bool enable)
 
void SetReturnFailedResources (bool enable)
 
void SetSearchPackagesFirst (bool value)
 
void SetFinishBackgroundResourcesMs (int ms)
 
void AddResourceRouter (ResourceRouter *router, bool addAsFirst=false)
 Add a resource router object. By default there is none, so the routing process is skipped.
 
void RemoveResourceRouter (ResourceRouter *router)
 Remove a resource router object.
 
SharedPtr< FileGetFile (const String &name, bool sendEventOnFailure=true)
 Open and return a file from the resource load paths or from inside a package file. If not found, use a fallback search with absolute path. Return null if fails. Can be called from outside the main thread.
 
ResourceGetResource (StringHash type, const String &name, bool sendEventOnFailure=true)
 Return a resource by type and name. Load if not loaded yet. Return null if not found or if fails, unless SetReturnFailedResources(true) has been called. Can be called only from the main thread.
 
SharedPtr< ResourceGetTempResource (StringHash type, const String &name, bool sendEventOnFailure=true)
 Load a resource without storing it in the resource cache. Return null if not found or if fails. Can be called from outside the main thread if the resource itself is safe to load completely (it does not possess for example GPU data).
 
bool BackgroundLoadResource (StringHash type, const String &name, bool sendEventOnFailure=true, Resource *caller=nullptr)
 Background load a resource. An event will be sent when complete. Return true if successfully stored to the load queue, false if eg. already exists. Can be called from outside the main thread.
 
unsigned GetNumBackgroundLoadResources () const
 
void GetResources (PODVector< Resource * > &result, StringHash type) const
 Return all loaded resources of a specific type.
 
ResourceGetExistingResource (StringHash type, const String &name)
 Return an already loaded resource of specific type & name, or null if not found. Will not load if does not exist.
 
const HashMap< StringHash, ResourceGroup > & GetAllResources () const
 Return all loaded resources.
 
const Vector< String > & GetResourceDirs () const
 
const Vector< SharedPtr< PackageFile > > & GetPackageFiles () const
 
template<class T >
T * GetResource (const String &name, bool sendEventOnFailure=true)
 Template version of returning a resource by name.
 
template<class T >
T * GetExistingResource (const String &name)
 Template version of returning an existing resource by name.
 
template<class T >
SharedPtr< T > GetTempResource (const String &name, bool sendEventOnFailure=true)
 Template version of loading a resource without storing it to the cache.
 
template<class T >
void ReleaseResource (const String &name, bool force=false)
 Template version of releasing a resource by name.
 
template<class T >
bool BackgroundLoadResource (const String &name, bool sendEventOnFailure=true, Resource *caller=nullptr)
 Template version of queueing a resource background load.
 
template<class T >
void GetResources (PODVector< T * > &result) const
 Template version of returning loaded resources of a specific type.
 
bool Exists (const String &name) const
 Return whether a file exists in the resource directories or package files. Does not check manually added in-memory resources.
 
unsigned long long GetMemoryBudget (StringHash type) const
 
unsigned long long GetMemoryUse (StringHash type) const
 
unsigned long long GetTotalMemoryUse () const
 
String GetResourceFileName (const String &name) const
 Return full absolute file name of resource if possible, or empty if not found.
 
bool GetAutoReloadResources () const
 
bool GetReturnFailedResources () const
 
bool GetSearchPackagesFirst () const
 
int GetFinishBackgroundResourcesMs () const
 
ResourceRouterGetResourceRouter (unsigned index) const
 Return a resource router by index.
 
String GetPreferredResourceDir (const String &path) const
 Return either the path itself or its parent, based on which of them has recognized resource subdirectories.
 
String SanitateResourceName (const String &name) const
 Remove unsupported constructs from the resource name to prevent ambiguity, and normalize absolute filename to resource path relative if possible.
 
String SanitateResourceDirName (const String &name) const
 Remove unnecessary constructs from a resource directory name and ensure it to be an absolute path.
 
void StoreResourceDependency (Resource *resource, const String &dependency)
 Store a dependency for a resource. If a dependency file changes, the resource will be reloaded.
 
void ResetDependencies (Resource *resource)
 Reset dependencies for a resource.
 
String PrintMemoryUsage () const
 Returns a formatted string containing the memory actively used.
 
- Public Member Functions inherited from Urho3D::Object
 Object (Context *context)
 Construct.
 
 ~Object () override
 Destruct. Clean up self from event sender & receiver structures.
 
virtual StringHash GetType () const =0
 
virtual const StringGetTypeName () const =0
 
virtual const TypeInfoGetTypeInfo () const =0
 Return type info.
 
virtual void OnEvent (Object *sender, StringHash eventType, VariantMap &eventData)
 Handle event.
 
bool IsInstanceOf (StringHash type) const
 Check current instance is type of specified type.
 
bool IsInstanceOf (const TypeInfo *typeInfo) const
 Check current instance is type of specified type.
 
template<typename T >
bool IsInstanceOf () const
 Check current instance is type of specified class.
 
template<typename T >
T * Cast ()
 Cast the object to specified most derived class.
 
template<typename T >
const T * Cast () const
 Cast the object to specified most derived class.
 
void SubscribeToEvent (StringHash eventType, EventHandler *handler)
 Subscribe to an event that can be sent by any sender.
 
void SubscribeToEvent (Object *sender, StringHash eventType, EventHandler *handler)
 Subscribe to a specific sender's event.
 
void SubscribeToEvent (StringHash eventType, const std::function< void(StringHash, VariantMap &)> &function, void *userData=nullptr)
 Subscribe to an event that can be sent by any sender.
 
void SubscribeToEvent (Object *sender, StringHash eventType, const std::function< void(StringHash, VariantMap &)> &function, void *userData=nullptr)
 Subscribe to a specific sender's event.
 
void UnsubscribeFromEvent (StringHash eventType)
 Unsubscribe from an event.
 
void UnsubscribeFromEvent (Object *sender, StringHash eventType)
 Unsubscribe from a specific sender's event.
 
void UnsubscribeFromEvents (Object *sender)
 Unsubscribe from a specific sender's events.
 
void UnsubscribeFromAllEvents ()
 Unsubscribe from all events.
 
void UnsubscribeFromAllEventsExcept (const PODVector< StringHash > &exceptions, bool onlyUserData)
 Unsubscribe from all events except those listed, and optionally only those with userdata (script registered events).
 
void SendEvent (StringHash eventType)
 Send event to all subscribers.
 
void SendEvent (StringHash eventType, VariantMap &eventData)
 Send event with parameters to all subscribers.
 
VariantMapGetEventDataMap () const
 Return a preallocated map for event data. Used for optimization to avoid constant re-allocation of event data maps.
 
template<typename... Args>
void SendEvent (StringHash eventType, Args... args)
 Send event with variadic parameter pairs to all subscribers. The parameter pairs is a list of paramID and paramValue separated by comma, one pair after another.
 
ContextGetContext () const
 Return execution context.
 
const VariantGetGlobalVar (StringHash key) const
 
const VariantMapGetGlobalVars () const
 
void SetGlobalVar (StringHash key, const Variant &value)
 
ObjectGetSubsystem (StringHash type) const
 Return subsystem by type.
 
ObjectGetEventSender () const
 Return active event sender. Null outside event handling.
 
EventHandlerGetEventHandler () const
 Return active event handler. Null outside event handling.
 
bool HasSubscribedToEvent (StringHash eventType) const
 Return whether has subscribed to an event without specific sender.
 
bool HasSubscribedToEvent (Object *sender, StringHash eventType) const
 Return whether has subscribed to a specific sender's event.
 
bool HasEventHandlers () const
 Return whether has subscribed to any event.
 
template<class T >
T * GetSubsystem () const
 Template version of returning a subsystem.
 
const StringGetCategory () const
 
void SetBlockEvents (bool block)
 Block object from sending and receiving events.
 
bool GetBlockEvents () const
 Return sending and receiving events blocking status.
 
- Public Member Functions inherited from Urho3D::RefCounted
 RefCounted ()
 Construct. Allocate the reference count structure and set an initial self weak reference.
 
virtual ~RefCounted ()
 Destruct. Mark as expired and also delete the reference count structure if no outside weak references exist.
 
 RefCounted (const RefCounted &rhs)=delete
 Prevent copy construction.
 
RefCountedoperator= (const RefCounted &rhs)=delete
 Prevent assignment.
 
void AddRef ()
 Increment reference count. Can also be called outside of a SharedPtr for traditional reference counting.
 
void ReleaseRef ()
 Decrement reference count and delete self if no more references. Can also be called outside of a SharedPtr for traditional reference counting.
 
int Refs () const
 
int WeakRefs () const
 
RefCountRefCountPtr ()
 Return pointer to the reference count structure.
 

Private Member Functions

 URHO3D_OBJECT (ResourceCache, Object)
 
const SharedPtr< Resource > & FindResource (StringHash type, StringHash nameHash)
 Find a resource.
 
const SharedPtr< Resource > & FindResource (StringHash nameHash)
 Find a resource by name only. Searches all type groups.
 
void ReleasePackageResources (PackageFile *package, bool force=false)
 Release resources loaded from a package file.
 
void UpdateResourceGroup (StringHash type)
 Update a resource group. Recalculate memory use and release resources if over memory budget.
 
void HandleBeginFrame (StringHash eventType, VariantMap &eventData)
 Handle begin frame event. Automatic resource reloads and the finalization of background loaded resources are processed here.
 
FileSearchResourceDirs (const String &name)
 Search FileSystem for file.
 
FileSearchPackages (const String &name)
 Search resource packages for file.
 

Private Attributes

Mutex resourceMutex_
 Mutex for thread-safe access to the resource directories, resource packages and resource dependencies.
 
HashMap< StringHash, ResourceGroupresourceGroups_
 Resources by type.
 
Vector< StringresourceDirs_
 Resource load directories.
 
Vector< SharedPtr< FileWatcher > > fileWatchers_
 File watchers for resource directories, if automatic reloading enabled.
 
Vector< SharedPtr< PackageFile > > packages_
 Package files.
 
HashMap< StringHash, HashSet< StringHash > > dependentResources_
 Dependent resources. Only used with automatic reload to eg. trigger reload of a cube texture when any of its faces change.
 
SharedPtr< BackgroundLoaderbackgroundLoader_
 Resource background loader.
 
Vector< SharedPtr< ResourceRouter > > resourceRouters_
 Resource routers.
 
bool autoReloadResources_
 Automatic resource reloading flag.
 
bool returnFailedResources_
 Return failed resources flag.
 
bool searchPackagesFirst_
 Search priority flag.
 
bool isRouting_
 Resource routing flag to prevent endless recursion.
 
int finishBackgroundResourcesMs_
 How many milliseconds maximum per frame to spend on finishing background loaded resources.
 

Additional Inherited Members

- Static Public Member Functions inherited from Urho3D::Object
static const TypeInfoGetTypeInfoStatic ()
 Return type info static.
 
- Protected Attributes inherited from Urho3D::Object
Contextcontext_
 Execution context.
 

Detailed Description

Resource cache subsystem. Loads resources on demand and stores them for later access.

Member Function Documentation

◆ GetAutoReloadResources()

bool Urho3D::ResourceCache::GetAutoReloadResources ( ) const
inline

Return whether automatic resource reloading is enabled.

◆ GetFinishBackgroundResourcesMs()

int Urho3D::ResourceCache::GetFinishBackgroundResourcesMs ( ) const
inline

Return how many milliseconds maximum to spend on finishing background loaded resources.

◆ GetMemoryBudget()

unsigned long long Urho3D::ResourceCache::GetMemoryBudget ( StringHash  type) const

Return memory budget for a resource type.

◆ GetMemoryUse()

unsigned long long Urho3D::ResourceCache::GetMemoryUse ( StringHash  type) const

Return total memory use for a resource type.

◆ GetNumBackgroundLoadResources()

unsigned Urho3D::ResourceCache::GetNumBackgroundLoadResources ( ) const

Return number of pending background-loaded resources.

◆ GetPackageFiles()

const Vector<SharedPtr<PackageFile> >& Urho3D::ResourceCache::GetPackageFiles ( ) const
inline

Return added package files.

◆ GetResourceDirs()

const Vector<String>& Urho3D::ResourceCache::GetResourceDirs ( ) const
inline

Return added resource load directories.

◆ GetReturnFailedResources()

bool Urho3D::ResourceCache::GetReturnFailedResources ( ) const
inline

Return whether resources that failed to load are returned.

◆ GetSearchPackagesFirst()

bool Urho3D::ResourceCache::GetSearchPackagesFirst ( ) const
inline

Return whether when getting resources should check package files or directories first.

◆ GetTotalMemoryUse()

unsigned long long Urho3D::ResourceCache::GetTotalMemoryUse ( ) const

Return total memory use for all resources.

Here is the caller graph for this function:

◆ SetAutoReloadResources()

void Urho3D::ResourceCache::SetAutoReloadResources ( bool  enable)

Enable or disable automatic reloading of resources as files are modified. Default false.

Here is the call graph for this function:

◆ SetFinishBackgroundResourcesMs()

void Urho3D::ResourceCache::SetFinishBackgroundResourcesMs ( int  ms)
inline

Set how many milliseconds maximum per frame to spend on finishing background loaded resources.

Here is the call graph for this function:

◆ SetMemoryBudget()

void Urho3D::ResourceCache::SetMemoryBudget ( StringHash  type,
unsigned long long  budget 
)

Set memory budget for a specific resource type, default 0 is unlimited.

◆ SetReturnFailedResources()

void Urho3D::ResourceCache::SetReturnFailedResources ( bool  enable)
inline

Enable or disable returning resources that failed to load. Default false. This may be useful in editing to not lose resource ref attributes.

◆ SetSearchPackagesFirst()

void Urho3D::ResourceCache::SetSearchPackagesFirst ( bool  value)
inline

Define whether when getting resources should check package files or directories first. True for packages, false for directories.


The documentation for this class was generated from the following files:
  • Source/Urho3D/Resource/ResourceCache.h
  • Source/Urho3D/Resource/ResourceCache.cpp