Urho3D::ResourceCache Class Reference

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

#include <Urho3D/Resource/ResourceCache.h>

Inheritance diagram for Urho3D::ResourceCache:

Collaboration diagram for Urho3D::ResourceCache:

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< File >	GetFile (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.
Resource *	GetResource (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< Resource >	GetTempResource (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.
Resource *	GetExistingResource (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
ResourceRouter *	GetResourceRouter (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 String &	GetTypeName () const =0
virtual const TypeInfo *	GetTypeInfo () 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.
VariantMap &	GetEventDataMap () 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.
Context *	GetContext () const
	Return execution context.
const Variant &	GetGlobalVar (StringHash key) const
const VariantMap &	GetGlobalVars () const
void	SetGlobalVar (StringHash key, const Variant &value)
Object *	GetSubsystem (StringHash type) const
	Return subsystem by type.
Object *	GetEventSender () const
	Return active event sender. Null outside event handling.
EventHandler *	GetEventHandler () 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 String &	GetCategory () 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.
RefCounted &	operator= (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
RefCount *	RefCountPtr ()
	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.
File *	SearchResourceDirs (const String &name)
	Search FileSystem for file.
File *	SearchPackages (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, ResourceGroup >	resourceGroups_
	Resources by type.
Vector< String >	resourceDirs_
	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< BackgroundLoader >	backgroundLoader_
	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 TypeInfo *	GetTypeInfoStatic ()
	Return type info static.
Protected Attributes inherited from Urho3D::Object
Context *	context_
	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