Resource manager. More...

#include <kanzi/core.ui/resource/resource_manager.hpp>

Classes
class	AcquireTask
	Load task for a group of resources. More...

struct	KzuResourceManagerProtocolHandlerObject_internal
	Protocol handler structure. More...

struct	LoadTask

struct	LookupResultPointer

Public Types
enum	MemoryStrategy { KeepInMemory, OptimizeMemory }
	Resource manager memory strategy. More...

enum	LookupResultVariantIndices { PointerVariantIndex, LoadTaskVariantIndex }

typedef shared_ptr< LoadTask >	LoadTaskSharedPtr

typedef vector< LoadTaskSharedPtr >	ResourceContainer

typedef kzsException(*	ProtocolHandler) (ResourceManager resourceManager, string_view resourceURL, string_view protocol, string_view hostname, unsigned port, string_view path, void userData, ResourceSharedPtr &out_resource, LoadTaskSharedPtr &out_loadTask)
	Protocol handler function type definition. More...

typedef function< void(ResourceManager , string_view resourceURL, string_view protocol, string_view hostname, unsigned port, string_view path, void userData, Resource *resource)>	ProtocolResourceReloadFunction

typedef vector< pair< string, KzuBinaryDirectory * > >	DirectoryContainer

typedef unordered_map< string, KzuResourceManagerProtocolHandlerObject_internal >	ProtocolMap

typedef variant< LookupResultPointer, LoadTaskSharedPtr >	LookupResult

typedef unordered_map< string, LookupResult >	LookupMap

typedef unordered_set< string >	UrlContainer

typedef function< void()>	AsyncAcquireFinishedCallback

typedef shared_ptr< AcquireTask >	AcquireTaskSharedPtr

Public Member Functions
	ResourceManager (KzcMemoryManager *memoryManager)
	Constructor. More...

	~ResourceManager ()
	Destructor. More...

void	initializeLoaderThreads (size_t threadCount)
	Initializes additional resource loader threads for resource manager, which process the resource loading in parallel. More...

void	uninitializeLoaderThreads ()
	Uninitalizes loader threads from resource manager. More...

void	addDirectory (KzuBinaryDirectory *directory)
	Adds a binary directory to the resource manager to be used with the kzb protocol. More...

KzuBinaryDirectory *	mergeDirectory (KzuBinaryDirectory *directory)
	Merges a binary directory to the binary directory with the same name that already exists in the resource manager. More...

void	removeDirectory (KzuBinaryDirectory *directory)
	Removes binary directory from the resource manager. More...

void	addKzbFile (string_view fileName)
	Open a KZB file from disk and add it to the list of files. More...

void	addKzbFile (unique_ptr< KzbFile > kzbFile)
	Add a KzbFile to the list of files. More...

void	addKzbFile (ConstByteSpan data)
	Add a memory block as a kzb file. More...

unique_ptr< ReadOnlyMemoryFile >	openFile (string_view url, KzbFile **kzbFile)

KzuBinaryDirectory *	getDirectory (string_view name) const
	Gets the binary directory with the given name from the resource manager. More...

KzuBinaryDirectory *	addDirectoryFromFile (string_view fileName)
	Adds a binary directory from file to the resource manager to be used with the kzb protocol. More...

KzuBinaryDirectory *	mergeDirectoryFromFile (string_view fileName)
	Loads a binary directory from a file and merges it to the binary directory with the same name that already exists in the resource manager. More...

DirectoryContainer::const_iterator	beginDirectories () const
	Returns iterator to beginning of binary directories. More...

DirectoryContainer::const_iterator	endDirectories () const
	Returns iterator to end of binary directories. More...

void	invalidateAllGPUResources ()
	Tells the resource manager to invalidate all GPU resource states back to undeployed state without actually undeploying. More...

void	getMemoryUsage (size_t out_resourceCount, size_t out_cpuMemoryUsage, size_t *out_gpuMemoryUsage) const
	Queries information about memory usage. More...

Domain *	getDomain () const
	Gets UI domain from resource manager. More...

void	registerProtocolHandler (kzString protocol, ProtocolHandler handler, ProtocolResourceReloadFunction reloadFunction, void *userData)
	Registers the given protocol handler for loading resources specified with the given resource URL protocol (scheme name). More...

void	unregisterProtocolHandler (kzString protocol)
	Unregisters the protocol handler with the given resource URL protocol (scheme name). More...

bool	supportsProtocolHandler (kzString protocol) const
	Checks if the given resource URL protocol (scheme name) is registered as a protocol handler for the resource manager. More...

ResourceSharedPtr	acquireResource (string_view url)
	Acquires a resource associated with the given url. More...

ResourceSharedPtr	tryAcquireResource (string_view url)
	Behaves like acquireResource but doesn't throw exceptions. More...

template<typename Type >
shared_ptr< Type >	tryAcquireResource (string_view url)

template<typename Type >
shared_ptr< Type >	acquireResource (string_view url)
	Acquires a resource associated with the given url and casts the resource to given type. More...

void	registerResource (string_view url, ResourceSharedPtr resource)
	Associates the given URL with the resource so that the next acquireResource with the URL will return the resource. More...

void	registerLoadTask (string_view url, LoadTaskSharedPtr loadTask)
	Associates the given URL with the resource so that the next acquireResource with the URL complete the task and return the result. More...

void	unregisterResource (string_view url)
	Removes the association of the given URL to a resource or a load task. More...

ResourceSharedPtr	acquireLoadedResource (string_view url) const
	Acquires a resource associated with the given url. If no resource is associated with the url, returns nullptr. More...

KzcImage *	loadImage (string_view url) const
	Loads an image from the given url. More...

KzcSpline *	loadSpline (string_view url) const
	Loads a spline from the given url. More...

string	getResourceURL (const Resource &resource) const
	Tries to find a url for a given resource. Returns empty string if the resource doesn't have a registered url. More...

void	setDefaultMemoryStrategy (MemoryStrategy resourceReleaseStrategy)
	Sets default memory strategy. More...

MemoryStrategy	getDefaultMemoryStrategy () const
	Gets default memory strategy. More...

void	purge ()
	Deletes unreferenced resources. More...

void	update ()
	Processes resource manager load and deployment queues to progress the background tasks. More...

bool	processDeploymentQueueItem ()
	Processes asynchronous loading tasks by deploying a single loaded GPU resource. More...

bool	hasDeploymentTasks () const
	Tell if deployment queue is empty. More...

AcquireTaskSharedPtr	acquireResourcesAsync (const UrlContainer &urls, AsyncAcquireFinishedCallback callback)
	Creates a background task that loads and deploys all resources from a set of URLs. More...

void	wait (AcquireTask &acquireTask)
	Blocks until async acquire task has finished and calls the callback of the task (unless it has been called already). More...

void	deployGPUResources ()
	Deploys all GPU resources that are present in gpuDeploymentQueue. For internal use of the framework only. More...

void	setDomain (Domain *domain)
	Helper function for setting project to resource manager. More...

KzcMemoryManager *	getMemoryManager () const

KzuBinaryFileInfo *	getBinaryFileInfo (string_view url) const
	Gets binary file info corresponding to a file from the given url. More...

KzbFile *	getKzbFile (string_view hostname, size_t index=0) const
	Get KZB file construct corresponding to given name. More...

void	reloadFromUrl (Resource *resource)
	Reload texture from URL. More...

Static Public Member Functions
static kzString	getResourcePathFromURL (kzString resourceURL)
	Gets resource path from resource URL. More...

static kzString	getRelativePathFromAbsolutePath (kzString absolutePath)
	Gets relative path from absolute path (relative to screen). More...

Friends
class	Resource

class	GPUResource

Detailed Description

Resource manager.

Stores resources and manages resource load tasks.

Member Typedef Documentation

typedef shared_ptr<LoadTask> kanzi::ResourceManager::LoadTaskSharedPtr

typedef vector<LoadTaskSharedPtr> kanzi::ResourceManager::ResourceContainer

typedef kzsException(* kanzi::ResourceManager::ProtocolHandler) (ResourceManager *resourceManager, string_view resourceURL, string_view protocol, string_view hostname, unsigned port, string_view path, void *userData, ResourceSharedPtr &out_resource, LoadTaskSharedPtr &out_loadTask)

Protocol handler function type definition.

Parameters

resourceURL	The full URL of the resource in the form of protocol://hostname[:port]/path.
protocol	Extracted protocol part of the resource URL.
hostname	Extracted hostname part of the resource URL.
port	Extracted port part of the resource URL. This is 0 if the port is omitted from the URL.
path	Extracted path part of the resource URL.
userData	The userData object passed as parameter for kzuResourceManagerRegisterProtocolHandler().
out_resource	The loaded resource.

Returns: Can return KZU_EXCEPTION_FILE_NOT_FOUND if the resource cannot be loaded.

typedef function<void(ResourceManager*, string_view resourceURL, string_view protocol, string_view hostname, unsigned port, string_view path, void* userData, Resource* resource)> kanzi::ResourceManager::ProtocolResourceReloadFunction

typedef vector<pair<string, KzuBinaryDirectory*> > kanzi::ResourceManager::DirectoryContainer

typedef unordered_map<string, KzuResourceManagerProtocolHandlerObject_internal> kanzi::ResourceManager::ProtocolMap

typedef variant<LookupResultPointer, LoadTaskSharedPtr> kanzi::ResourceManager::LookupResult

typedef unordered_map<string, LookupResult> kanzi::ResourceManager::LookupMap

typedef unordered_set<string> kanzi::ResourceManager::UrlContainer

typedef function<void()> kanzi::ResourceManager::AsyncAcquireFinishedCallback

typedef shared_ptr<AcquireTask> kanzi::ResourceManager::AcquireTaskSharedPtr

Member Enumeration Documentation

enum kanzi::ResourceManager::MemoryStrategy

Resource manager memory strategy.

Enumerator
KeepInMemory	With this setting, when a resource is no longer referenced, resource manager keeps it in memory until purge() is called.
OptimizeMemory	With this setting, when a resource is no longer referenced, resource manager deletes it and frees the (CPU and GPU) memory used by the resource. */.

enum kanzi::ResourceManager::LookupResultVariantIndices

Enumerator
PointerVariantIndex
LoadTaskVariantIndex

Constructor & Destructor Documentation

kanzi::ResourceManager::ResourceManager ( KzcMemoryManager * memoryManager )

explicit

Constructor.

Parameters

memoryManager	Memory manager to use.
renderer	Renderer to use.

kanzi::ResourceManager::~ResourceManager ( )

Destructor.

Member Function Documentation

void kanzi::ResourceManager::initializeLoaderThreads ( size_t threadCount )

Initializes additional resource loader threads for resource manager, which process the resource loading in parallel.

The initialization should be executed only once, after the resource manager has been created.

Parameters

threadCount	Number of loader threads. If 0, parallel loading is disabled.
loaderMemoryManagerSize	Memory manager size for resource loading, required to hold the allocated resource data. No effect if threadCount is 0.

void kanzi::ResourceManager::uninitializeLoaderThreads ( )

Uninitalizes loader threads from resource manager.

This function should be possible to be called at any time.

void kanzi::ResourceManager::addDirectory ( KzuBinaryDirectory * directory )

Adds a binary directory to the resource manager to be used with the kzb protocol.

This transfers the ownership of the binary directory to the resource manager.

Parameters

directory The binary directory you want to add.

KzuBinaryDirectory* kanzi::ResourceManager::mergeDirectory ( KzuBinaryDirectory * directory )

Merges a binary directory to the binary directory with the same name that already exists in the resource manager.

If there is no binary directory with the same name, the effect is the same as addDirectory. If a directory with the same name already exists, the passed directory is merged to the existing directory, and the passed directory is destroyed. The files in provided binary directory take precedence over the files with the same name in the existing directory.

Parameters

directory The binary directory you want to merge.

Returns: A pointer to the merged directory.

void kanzi::ResourceManager::removeDirectory ( KzuBinaryDirectory * directory )

Removes binary directory from the resource manager.

Parameters

directory The binary directory you want to remove.

void kanzi::ResourceManager::addKzbFile ( string_view fileName )

Open a KZB file from disk and add it to the list of files.

If file cannot be opened or is not a KZB file, an error will be thrown.

Parameters

fileName File name to open.

void kanzi::ResourceManager::addKzbFile ( unique_ptr< KzbFile > kzbFile )

Add a KzbFile to the list of files.

Parameters

kzbFile File to add.

void kanzi::ResourceManager::addKzbFile ( ConstByteSpan data )

Add a memory block as a kzb file.

This function will internally create a kzb file reading the memory block.

Parameters

data	Data to add.

unique_ptr<ReadOnlyMemoryFile> kanzi::ResourceManager::openFile	(	string_view	url,
		KzbFile **	kzbFile
	)

KzuBinaryDirectory* kanzi::ResourceManager::getDirectory ( string_view name ) const

Gets the binary directory with the given name from the resource manager.

Returns: nullptr if a directory is not found.

KzuBinaryDirectory* kanzi::ResourceManager::addDirectoryFromFile ( string_view fileName )

Adds a binary directory from file to the resource manager to be used with the kzb protocol.

The resource manager keeps the ownership of the binary directory.

Parameters

fileName Path to a binary file. Note that the filename may be different from the directory name stored in the binary: for example the file "Programmer_tutorial.kzb" contains a directory named "programmer_tutorial".

Returns: A pointer that is set to point to the binary directory of the loaded binary.

KzuBinaryDirectory* kanzi::ResourceManager::mergeDirectoryFromFile ( string_view fileName )

Loads a binary directory from a file and merges it to the binary directory with the same name that already exists in the resource manager.

For documentation of the merge process refer to mergeDirectory().

Parameters

fileName The name of the .kzb file to load binary directory from.

Returns: A pointer to the merged directory if successful, nullptr otherwise.

DirectoryContainer::const_iterator kanzi::ResourceManager::beginDirectories ( ) const

inline

Returns iterator to beginning of binary directories.

DirectoryContainer::const_iterator kanzi::ResourceManager::endDirectories ( ) const

inline

Returns iterator to end of binary directories.

void kanzi::ResourceManager::invalidateAllGPUResources ( )

Tells the resource manager to invalidate all GPU resource states back to undeployed state without actually undeploying.

This is needed e.g. when the GL context is recreated.

void kanzi::ResourceManager::getMemoryUsage	(	size_t *	out_resourceCount,
		size_t *	out_cpuMemoryUsage,
		size_t *	out_gpuMemoryUsage
	)		const

Queries information about memory usage.

Domain* kanzi::ResourceManager::getDomain ( ) const

Gets UI domain from resource manager.

void kanzi::ResourceManager::registerProtocolHandler	(	kzString	protocol,
		ProtocolHandler	handler,
		ProtocolResourceReloadFunction	reloadFunction,
		void *	userData
	)

Registers the given protocol handler for loading resources specified with the given resource URL protocol (scheme name).

void kanzi::ResourceManager::unregisterProtocolHandler ( kzString protocol )

Unregisters the protocol handler with the given resource URL protocol (scheme name).

bool kanzi::ResourceManager::supportsProtocolHandler ( kzString protocol ) const

Checks if the given resource URL protocol (scheme name) is registered as a protocol handler for the resource manager.

ResourceSharedPtr kanzi::ResourceManager::acquireResource ( string_view url )

Acquires a resource associated with the given url.

If no resource is associated with the url, tries to load the resource from the location specified by the url. The url specifies the location with a protocol and a protocol specific path.

The supported protocols are:

kzb protocol for loading resources from .kzb files. For example, "kzb://programmer_tutorial/Prefabs/Widget Item Prefab". If the given url is not found from the added binary directories, an exception is thrown.
file protocol for loading resources from external files. For example, "file://./Icon.png".

Parameters

url	Url of the resource.

Returns: Shared pointer to the resource.

ResourceSharedPtr kanzi::ResourceManager::tryAcquireResource ( string_view url )

Behaves like acquireResource but doesn't throw exceptions.

See also: acquireResource

Parameters

url	Url of the resource.

Returns: Shared pointer to the resource, or nullptr if resource is not found.

template<typename Type >

shared_ptr<Type> kanzi::ResourceManager::tryAcquireResource ( string_view url )

inline

template<typename Type >

shared_ptr<Type> kanzi::ResourceManager::acquireResource ( string_view url )

inline

Acquires a resource associated with the given url and casts the resource to given type.

If the cast fails, throws an exception.

Parameters

url	Url of the resource.

Returns: Shared pointer to the resource.

void kanzi::ResourceManager::registerResource	(	string_view	url,
		ResourceSharedPtr	resource
	)

Associates the given URL with the resource so that the next acquireResource with the URL will return the resource.

void kanzi::ResourceManager::registerLoadTask	(	string_view	url,
		LoadTaskSharedPtr	loadTask
	)

Associates the given URL with the resource so that the next acquireResource with the URL complete the task and return the result.

void kanzi::ResourceManager::unregisterResource ( string_view url )

Removes the association of the given URL to a resource or a load task.

ResourceSharedPtr kanzi::ResourceManager::acquireLoadedResource ( string_view url ) const

Acquires a resource associated with the given url. If no resource is associated with the url, returns nullptr.

KzcImage* kanzi::ResourceManager::loadImage ( string_view url ) const

Loads an image from the given url.

KzcSpline* kanzi::ResourceManager::loadSpline ( string_view url ) const

Loads a spline from the given url.

string kanzi::ResourceManager::getResourceURL ( const Resource & resource ) const

Tries to find a url for a given resource. Returns empty string if the resource doesn't have a registered url.

static kzString kanzi::ResourceManager::getResourcePathFromURL ( kzString resourceURL )

static

Gets resource path from resource URL.

Returns KZ_NULL if the URL is malformed.

static kzString kanzi::ResourceManager::getRelativePathFromAbsolutePath ( kzString absolutePath )

static

Gets relative path from absolute path (relative to screen).

void kanzi::ResourceManager::setDefaultMemoryStrategy ( MemoryStrategy resourceReleaseStrategy )

Sets default memory strategy.

MemoryStrategy kanzi::ResourceManager::getDefaultMemoryStrategy ( ) const

Gets default memory strategy.

void kanzi::ResourceManager::purge ( )

Deletes unreferenced resources.

void kanzi::ResourceManager::update ( )

Processes resource manager load and deployment queues to progress the background tasks.

Called by the framework once per frame.

bool kanzi::ResourceManager::processDeploymentQueueItem ( )

Processes asynchronous loading tasks by deploying a single loaded GPU resource.

This function does not do anything if there are no active asynchronous loading tasks with loaded resources. Framework calls this function once every frame. Call this function periodically to ensure that asynchronous loading tasks are completed.

Returns: False if there is no asynchronously loaded resources in the deployment queue.

bool kanzi::ResourceManager::hasDeploymentTasks ( ) const

Tell if deployment queue is empty.

Returns: True if empty, false if not.

AcquireTaskSharedPtr kanzi::ResourceManager::acquireResourcesAsync	(	const UrlContainer &	urls,
		AsyncAcquireFinishedCallback	callback
	)

Creates a background task that loads and deploys all resources from a set of URLs.

After all resources are loaded and deployed, calls the provided callback.

Parameters

urls	Set of URLs for resources that will be loaded.
callback	Callback function that will be called when all of the specified resource URLs have been loaded.

Returns: Handle to the async load task. The handle can be passed to wait to wait for the completion of the load.

void kanzi::ResourceManager::wait ( AcquireTask & acquireTask )

Blocks until async acquire task has finished and calls the callback of the task (unless it has been called already).

Parameters

acquireTask Acquire task created by acquireResourcesAsync.

void kanzi::ResourceManager::deployGPUResources ( )

Deploys all GPU resources that are present in gpuDeploymentQueue. For internal use of the framework only.

void kanzi::ResourceManager::setDomain ( Domain * domain )

Helper function for setting project to resource manager.

KzcMemoryManager* kanzi::ResourceManager::getMemoryManager ( ) const

KzuBinaryFileInfo* kanzi::ResourceManager::getBinaryFileInfo ( string_view url ) const

Gets binary file info corresponding to a file from the given url.

Parameters

url	URL to fetch.

Returns: Binary file info found or 0.

KzbFile* kanzi::ResourceManager::getKzbFile	(	string_view	hostname,
		size_t	index = `0`
	)		const

Get KZB file construct corresponding to given name.

Parameters

hostname	Hostname part of the file.
index	Index of the file for the given hostname, typically 0.

Returns: KZB file found or 0.

void kanzi::ResourceManager::reloadFromUrl ( Resource * resource )

Reload texture from URL.

Friends And Related Function Documentation

friend class Resource

friend

friend class GPUResource

friend

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

kanzi/core.ui/resource/resource_manager.hpp

Classes

Public Types

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation