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:

Public Member Functions
	ResourceCache (Context *context)
	Construct.
	~ResourceCache () override
	Destruct. Free all resources.
bool	AddManualResource (Resource *resource)
	Add a manually created resource. Must be uniquely named within its type.
void	ReleaseResource (StringHash type, const ea::string &name, bool force=false)
	Release a resource by name.
void	ReleaseResource (const ea::string &resourceName, 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 ea::string &partialName, bool force=false)
	Release resources of a specific type and partial name.
void	ReleaseResources (const ea::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 (const ea::string_view resourceName)
	Reload a resource. Return true on success. The resource will not be removed from the cache in case of failure.
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 ea::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	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.
AbstractFilePtr	GetFile (const ea::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 ea::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 ea::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 ea::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 (ea::vector< Resource * > &result, StringHash type) const
	Return all loaded resources of a specific type.
Resource *	GetExistingResource (StringHash type, const ea::string &name)
	Return an already loaded resource of specific type & name, or null if not found. Will not load if does not exist. Specifying zero type will search all types.
const ea::unordered_map< StringHash, ResourceGroup > &	GetAllResources () const
	Return all loaded resources.
template<class T >
T *	GetResource (const ea::string &name, bool sendEventOnFailure=true)
	Template version of returning a resource by name.
template<class T >
T *	GetExistingResource (const ea::string &name)
	Template version of returning an existing resource by name.
template<class T >
SharedPtr< T >	GetTempResource (const ea::string &name, bool sendEventOnFailure=true)
	Template version of loading a resource without storing it to the cache.
template<class T >
void	ReleaseResource (const ea::string &resourceName, bool force=false)
	Template version of releasing a resource by name.
template<class T >
bool	BackgroundLoadResource (const ea::string &name, bool sendEventOnFailure=true, Resource *caller=nullptr)
	Template version of queueing a resource background load.
template<class T >
void	GetResources (ea::vector< T * > &result) const
	Template version of returning loaded resources of a specific type.
bool	Exists (const ea::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
ea::string	GetResourceFileName (const ea::string &name) const
	Return full absolute file name of resource if possible, or empty if not found.
bool	GetReturnFailedResources () const
bool	GetSearchPackagesFirst () const
int	GetFinishBackgroundResourcesMs () const
ResourceRouter *	GetResourceRouter (unsigned index) const
	Return a resource router by index.
ea::string	SanitateResourceName (const ea::string &name) const
	Remove unsupported constructs from the resource name to prevent ambiguity, and normalize absolute filename to resource path relative if possible.
void	StoreResourceDependency (Resource *resource, const ea::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.
ea::string	PrintMemoryUsage () const
	Returns a formatted string containing the memory actively used.
void	Scan (ea::vector< ea::string > &result, const ea::string &pathName, const ea::string &filter, ScanFlags flags) const
	Scan for specified files.
ea::string	PrintResources (const ea::string &typeName=EMPTY_STRING) const
	Returns a formatted string containing the currently loaded resources with optional type name filter.
void	IgnoreResourceReload (const ea::string &name)
	When resource auto-reloading is enabled ignore reloading resource once.
void	IgnoreResourceReload (const Resource *resource)
	When resource auto-reloading is enabled ignore reloading resource once.
void	RouteResourceName (FileIdentifier &name) const
	Pass name through resource routers and return final resource name.
void	Clear ()
	Clear all resources from resource cache.
FileIdentifier	GetCanonicalIdentifier (const FileIdentifier &name) const
	Return canonical resource identifier without resource routing.
FileIdentifier	GetResolvedIdentifier (const FileIdentifier &name) const
	Return canonical resource identifier with resource routing applied.
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 ea::string &	GetTypeName () const =0
virtual const TypeInfo *	GetTypeInfo () const =0
	Return type info.
virtual bool	IsInstanceOf (StringHash type) const =0
	Check whether current instance implements specified type.
virtual void	OnEvent (Object *sender, StringHash eventType, VariantMap &eventData)
	Handle event.
virtual void	SerializeInBlock (Archive &archive)
	Serialize content from/to archive. May throw ArchiveException.
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	SubscribeToEventManual (StringHash eventType, EventHandler *handler)
	Subscribe to an event that can be sent by any sender.
void	SubscribeToEventManual (Object *sender, StringHash eventType, EventHandler *handler)
	Subscribe to a specific sender's event.
template<class T >
void	SubscribeToEvent (StringHash eventType, T handler)
	Subscribe to an event that can be sent by any sender.
template<class T >
void	SubscribeToEvent (Object *sender, StringHash eventType, T handler)
	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 ea::vector< StringHash > &exceptions)
	Unsubscribe from all events except those listed.
void	UnsubscribeFromAllEventsExcept (const ea::vector< Object * > &exceptions)
	Unsubscribe from all events except those with listed senders.
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, const Args &... args)
	Send event with variadic parameter pairs to all subscribers. The parameters are (paramID, paramValue) pairs.
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 ea::string &	GetCategory () const
void	SendEvent (StringHash eventType, const VariantMap &eventData)
	Send event with parameters to all subscribers.
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.
int	AddRef ()
int	ReleaseRef ()
int	Refs () const
int	WeakRefs () const
RefCount *	RefCountPtr () const
	Return pointer to the reference count structure.
bool	HasScriptObject () const
	Return true if script runtime object wrapping this native object exists.
bool	IsScriptStrongRef () const
	Return true if script reference is strong.

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. The finalization of background loaded resources are processed here.
void	HandleFileChanged (StringHash eventType, VariantMap &eventData)
	Handle file changed to reload resource.
void	HandleReflectionRemoved (ObjectReflection *reflection)
	Handle object reflection removed.

Private Attributes
Mutex	resourceMutex_
	Mutex for thread-safe access to the resource directories, resource packages and resource dependencies.
ea::unordered_map< StringHash, ResourceGroup >	resourceGroups_
	Resources by type.
ea::unordered_map< StringHash, ea::hash_set< 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.
ea::vector< SharedPtr< ResourceRouter > >	resourceRouters_
	Resource routers.
bool	returnFailedResources_
	Return failed resources flag.
bool	searchPackagesFirst_
	Search priority flag.
int	finishBackgroundResourcesMs_
	How many milliseconds maximum per frame to spend on finishing background loaded resources.
ea::vector< ea::string >	ignoreResourceAutoReload_
	List of resources that will not be auto-reloaded if reloading event triggers.

Additional Inherited Members
Static Public Member Functions inherited from Urho3D::Object
static const TypeInfo *	GetTypeInfoStatic ()
	Return type info static.
Static Public Attributes inherited from Urho3D::Object
static constexpr ea::array< StringHash, 0 >	TypeHierarchy {}
Protected Attributes inherited from Urho3D::Object
WeakPtr< Context >	context_
	Execution context.

Detailed Description

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

Member Function Documentation

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.

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.

SetFinishBackgroundResourcesMs()

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

inline

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

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:

• Urho3D/Resource/ResourceCache.h
• Urho3D/Resource/ResourceCache.cpp