Use the resource manager to access and use resources in kzb files. More...

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

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

class	FinishingQueue
	Collection of resource loading tasks that have been already been loaded by a loader thread and are waiting to be finished by the main thread. More...

struct	LoadTask
	Use this base class to implement load tasks to load new resources. More...

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

typedef unordered_set< string >	UrlContainer
	Container type for URL set. More...

typedef shared_ptr< LoadTask >	LoadTaskSharedPtr
	LoadTask shared pointer type. More...

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)
	Type definition for the protocol handler of the load function. More...

typedef function< void(ResourceManager , string_view resourceURL, string_view protocol, string_view hostname, unsigned port, string_view path, void userData, Resource *resource)>	ProtocolResourceReloadFunction
	Type definition for the protocol handler of the reload function. More...

typedef vector< pair< string, KzuBinaryDirectory * > >	DirectoryContainer
	Type for the directory container. More...

typedef vector< LoadTaskSharedPtr >	FinishingQueueContainer
	Container type for the finishing queue. Used internally. More...

typedef function< void()>	AsyncAcquireFinishedCallback
	Callback function type for acquire tasks. More...

typedef shared_ptr< AcquireTask >	AcquireTaskSharedPtr
	AcquireTask shared pointer type. More...

typedef unique_ptr< KzbFile >	KzbFilePtr
	Type for a smart pointer to a KZB file. More...

typedef map< string, vector< KzbFilePtr > >	KzbFileDictionary
	Type for the KZB file container. More...

typedef vector< ResourceSharedPtr >	ResourceContainer
	Alias for a container of resources. More...

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

	~ResourceManager ()
	Destructor. More...

void	initializeLoaderThreads (size_t threadCount, size_t maxPendingResources)
	Initializes the additional resource loader threads for the resource manager. More...

void	waitForAcquireTasks ()
	Kanzi internally uses this function when application is about to lose GL context, to wait for all existing acquire tasks to finish. More...

void	uninitializeLoaderThreads ()
	Stops and removes the loader threads. After the call, all loading happens in the main thread. More...

ThreadNativeHandleType	getLoaderThreadHandle (size_t threadIndex)
	Gets the native handle of a loader thread. More...

size_t	getLoaderThreadCount () const
	Gets the number of loader threads of the resource manager. More...

void	setMaxPendingResources (size_t maxPendingResources)
	You can use this function to change the maximum number of resources that can be processed by the loading threads at the same time. 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 with another binary directory that has the same name and that already exists in the resource manager: More...

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

void	addKzbFile (string_view fileName)
	Opens a kzb file from the file system and adds it to the list of files. More...

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

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

unique_ptr< ReadOnlyMemoryFile >	openFile (string_view url, KzbFile **kzbFile)
	Opens a handle to a resource file inside a kzb file. More...

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 a kzb file to the resource manager, which you can then use with the kzb protocol. More...

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

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

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

void	invalidateAllGPUResources ()
	Kanzi internally uses this function to set all the GPU resources to undeployed state when an application loses and recreates the GL context after a pause-resume event. More...

void	getMemoryUsage (size_t out_resourceCount, size_t out_cpuMemoryUsage, size_t *out_gpuMemoryUsage) const
	Calculates the memory usage summary for all resources. More...

size_t	getAcquireTaskCount () const
	Returns the number of acquire tasks that have been started with a call to acquireResourcesAsync and have not yet been completed. More...

size_t	getLoadQueueSize () const
	Returns the number of resource load tasks in the load queue. More...

Domain *	getDomain () const
	Returns the domain. More...

void	registerProtocolHandler (kzString protocol, ProtocolHandler handler, ProtocolResourceReloadFunction reloadFunction, void *userData)
	Registers a 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 whether 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)
	Acquires a resource associated with the given URL, like acquireResource, but does not throw exceptions. More...

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

template<typename Type >
shared_ptr< Type >	acquireResource (string_view url)
	Acquires a resource associated with the given URL and casts the resource to the 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 returns 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 completes the load task and returns 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. More...

BitmapImageUniquePtr	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 the given resource. More...

void	setDefaultMemoryStrategy (MemoryStrategy resourceReleaseStrategy)
	Sets the memory release strategy for new resources. More...

MemoryStrategy	getDefaultMemoryStrategy () const
	Gets the memory release strategy. More...

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

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

FinishingQueue &	getFinishingQueue ()
	Gets the finishing queue for asynchronous loading 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 the execution until the async acquire task finishes and calls the callback of the task (unless it has been called already). More...

void	deployGPUResources ()
	Kanzi internally uses this function to reload all GPU resources that have been invalidated by the pause-resume event. More...

void	setDomain (Domain *domain)
	Kanzi internally uses this function to set the domain of the resource manager when it creates a resource manager. More...

KzcMemoryManager *	getMemoryManager () const
	Returns the memory manager. More...

KzuBinaryFileInfo *	getBinaryFileInfo (string_view url) const
	Gets the kzb file information for a file from the given URL. More...

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

void	reloadFromUrl (Resource *resource)
	Kanzi internally uses this function to reload a resource from a kzb file. More...

KzbFileDictionary::const_iterator	beginKzbFiles () const
	Returns the iterator to the beginning of loaded KZB files. More...

KzbFileDictionary::const_iterator	endKzbFiles () const
	Returns the iterator to the end of loaded KZB files. More...

void	enqueueDependencies (LoadTaskSharedPtr loadTask, UrlContainer urls)
	Enqueue resource dependencies of a load task for asynchronous loading. More...

ResourceContainer	getAllLoadedResources () const
	Get a container of all existing resources. More...

Static Public Member Functions
static kzString	getResourcePathFromURL (kzString resourceURL)
	Kanzi internally uses this function to convert a resource URL to a resource path by dropping the protocol and project name from the path. More...

static kzString	getRelativePathFromAbsolutePath (kzString absolutePath)
	Kanzi internally uses this function to convert an absolute path to a node to a relative path by removing the screen name part of the path. More...

Friends
class	FinishingQueue

class	Resource

class	GPUResource

class	PreviewPatcher

Detailed Description

Use the resource manager to access and use resources in kzb files.

The resource manager maintains kzb files and provides mechanisms to load resources from kzb files.

To access resources in a kzb file, use the kzb URL of the resource that you want to access. For example, the URL string "kzb://programmer_tutorial/Prefabs/Widget Item Prefab" refers to the resource called "Widget Item Prefab" inside the folder "Prefabs" in the kzb file of the "programmer_tutorial" project.

Acquiring resources from kzb

When you acquire a URL for the first time, the resource manager loads the resource and caches it. The next time you use the same URL, Kanzi does not load the resource again, but returns the previously loaded resource instead.

To acquire a single resource, use acquireResource:

        // Set the location of the texture that you want to acquire inside the kzb file.
        string_view url = "kzb://project/Textures/texture";
        // Acquire the texture. Kanzi loads the texture from the kzb file and deploys it
        // to the GPU. You can immediately use the returned texture.
        // If the function cannot find the texture, it throws an exception.
        TextureSharedPtr texture = resourceManager->acquireResource<Texture>(url);

Releasing resources

Kanzi manages the lifetime of resources with shared pointers, but to cache resources, the resource manager maintains a shared pointer to each acquired resource. This means that Kanzi does not automatically release the memory used by resources, even if you are not using those resources.

To destroy resources and release the memory used up by those resources, use purge:

        // For example, get the Image node that uses a texture.
        Image2DSharedPtr image = lookupSomeImage2D();
        // Before you can release a resource, you must first stop using that resource.
        // For example, set the Image node texture to nullptr so that that node does not use the texture anymore.
        image->setImage(TextureSharedPtr());
        // Release all the resources that are no longer in use. This way you free the memory
        // that the texture you released used.
        resourceManager->purge();

Acquiring resources asynchronously

The resource manager uses worker threads to load multiple resources simultaneously and in the background, while the application is running. You can use Application::onConfigure to specify the number of loader threads. With loader threads you can load textures, meshes, and shaders. Kanzi uses the main thread to load all other types of resources.

You can decrease the loading time of resources by first collecting the URLs of all resources and loading multiple resources simultaneously. Kanzi does this automatically for the startup screen. If you are instantiating prefabs using the API, you can use collectResourceUrls to collect the URLs and acquireResourcesAsync to acquire the resources:

        // When you have a prefab template and you want to load its resources before using the prefab.
        string_view prefabUrl = "kzb://project/Textures/texture";
        PrefabTemplateSharedPtr prefabTemplate = resourceManager->acquireResource<PrefabTemplate>(prefabUrl);
        // First, collect the URLs of resources used by the prefab that Kanzi must load...
        ResourceManager::UrlContainer urls;
        collectResourceUrls(*prefabTemplate, urls);
        // ...then start the asynchronous loading. Kanzi calls the onAsyncLoadFinished callback when it loads all of the URLs.
        ResourceManager::AcquireTaskSharedPtr acquireTask = resourceManager->acquireResourcesAsync(urls, bind(&ResourceManagerSnippets::onAsyncLoadFinished, this));

If you need the results immediately, you can use wait:

// Block execution until the acquire task finishes.

resourceManager->wait(*acquireTask);

See also: collectResourceUrls, loadPrefabAsync

Managing kzb files

At application startup, Kanzi opens the kzb files that you specify in the application.cfg or in the configuration file specified by the Application::onConfigure. With the resource manager you can use addKzbFile to open additional kzb files at runtime:

// Open a kzb file from the working directory.

resourceManager->addKzbFile("project.kzb");

Acquiring resources from the file system

Besides loading resources from kzb files, you can load resources from the file system. The resource manager supports the loading of these resource types from the file system:

Texture from png, jpg, and jpeg files
KzuFont from ttf files
BinaryResource from js files

Kanzi determines the type of the resource it creates from the file extension, not from the file contents. You have to ensure that the files use correct extensions.

To load resources from the file system, use the file:// protocol:

        // Set the location of an image file. Use "." as the project name to refer to the current working directory.
        string_view url = "file://./image.png";
        // Acquire the texture. Kanzi loads the texture from the kzb file and deploys it
        // to the GPU. You can immediately use the returned texture.
        // If the function cannot find the texture, it throws an exception.
        TextureSharedPtr texture = resourceManager->acquireResource<Texture>(url);

Member Typedef Documentation

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

Container type for URL set.

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

LoadTask shared pointer type.

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)

Type definition for the protocol handler of the load function.

The load function takes a resource URL and creates either a new resource or a load task that creates a new resource.

Parameters

resourceManager	The resource manager.
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 extra protocol specific data object that was stored when the protocol handler was registered.
out_resource	The loaded resource, or nullptr.
out_loadTask	A load task for the resource, or nullptr.

Returns: Success or exception.

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

Type definition for the protocol handler of the reload function.

The reload function takes a resource URL and an existing resource, and reloads the resource.

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

Type for the directory container.

Deprecated:: Part of the legacy kzb loading.

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

Container type for the finishing queue. Used internally.

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

Callback function type for acquire tasks.

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

AcquireTask shared pointer type.

typedef unique_ptr<KzbFile> kanzi::ResourceManager::KzbFilePtr

Type for a smart pointer to a KZB file.

typedef map<string, vector<KzbFilePtr> > kanzi::ResourceManager::KzbFileDictionary

Type for the KZB file container.

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

Alias for a container of resources.

Member Enumeration Documentation

enum kanzi::ResourceManager::MemoryStrategy

Resource manager memory strategy.

Enumerator
KeepInMemory	When a resource is no longer referenced, the resource manager keeps the resource in memory until you call purge().
OptimizeMemory	When a resource is no longer referenced, the resource manager deletes the resource and frees the (CPU and GPU) memory used by the resource.

Constructor & Destructor Documentation

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

explicit

Constructor.

Parameters

memoryManager Memory manager to use.

kanzi::ResourceManager::~ResourceManager ( )

Destructor.

Member Function Documentation

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

Initializes the additional resource loader threads for the resource manager.

Do not call this function, because Kanzi automatically calls it.

Parameters

threadCount	The number of loader threads. If 0, parallel loading is disabled.
maxPendingResources	The maximum number of resources that can be processed by the loading threads at the same time. If set to 0, behaves as if set to threadCount + 1.

void kanzi::ResourceManager::waitForAcquireTasks ( )

Kanzi internally uses this function when application is about to lose GL context, to wait for all existing acquire tasks to finish.

void kanzi::ResourceManager::uninitializeLoaderThreads ( )

Stops and removes the loader threads. After the call, all loading happens in the main thread.

ThreadNativeHandleType kanzi::ResourceManager::getLoaderThreadHandle ( size_t threadIndex )

Gets the native handle of a loader thread.

You can use the native handle of a thread to set the priority of that thread, or to assign that thread to a dedicated CPU core:

        // You can set the application loader thread count by using ApplicationProperties::loadingThreadCount. 
        // To get the native handle of the first loader thread, pass to the function threadIndex 0.
        size_t threadIndex = 0;
        ThreadNativeHandleType handle = resourceManager->getLoaderThreadHandle(threadIndex);
        // You can use the retrieved thread native handle to set priority, or assign it to a dedicated CPU core.
#if defined(_WIN32)
        SetThreadPriority(static_cast<HANDLE>(handle), THREAD_PRIORITY_ABOVE_NORMAL);
#else
        sched_param sch;
        int policy;
        pthread_getschedparam(static_cast<pthread_t>(handle), &policy, &sch);
        sch.sched_priority = 99;
        pthread_setschedparam(static_cast<pthread_t>(handle), policy, &sch);
#endif

Resource manager creates all its loader threads during application startup and does not add or delete loader threads during the rest of application runtime, except during shutdown. An appropriate place to adjust loader thread settings is in the Application::onStartup() overloaded function. Kanzi calls this function after the ResourceManager created its loader threads and before Kanzi starts using loader threads for loading assets from kzb files.

Parameters

threadIndex Index of the loader thread.

Returns: Returns the native handle of the thread at threadIndex. If threadIndex is out of bounds, throws an out_of_range exception.

size_t kanzi::ResourceManager::getLoaderThreadCount ( ) const

Gets the number of loader threads of the resource manager.

Returns: The number of loader threads. If parallel loading is disabled, the function returns 0.

void kanzi::ResourceManager::setMaxPendingResources ( size_t maxPendingResources )

You can use this function to change the maximum number of resources that can be processed by the loading threads at the same time.

Parameters

maxPendingResources The maximum number of resources that can be processed by the loading threads at the same time. If set to 0, behaves as if set to threadCount + 1.

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.

Deprecated:: Part of the legacy kzb loading. Use addKzbFile instead.

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

Merges a binary directory with another binary directory that has the same name and that already exists in the resource manager:

If a directory with the same name already exists, this function merges the directory you pass to the existing directory and destroys the directory you passed. The files in the binary directory you pass take precedence over the files with the same name in the existing directory.
If a binary directory with the same name does not exist, the result is the same as when you use addDirectory.
Parameters

directory The binary directory you want to merge.

Returns
A pointer to the merged directory.

Deprecated:
Part of the legacy kzb loading. Use addKzbFile instead.

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

Removes a binary directory from the resource manager.

Parameters

directory The binary directory you want to remove.

Deprecated:: Part of the legacy kzb loading.

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

Opens a kzb file from the file system and adds it to the list of files.

If this function cannot open the file you pass to it or that file is not a kzb file, the function throws an exception.

Parameters

fileName The name of the file to open.

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

Adds a kzb file to the list of files.

Parameters

kzbFile File to add.

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

Adds a memory block as a kzb file.

This function internally creates a kzb file by reading the memory block.

Parameters

data	Data to add. The memory area must be readable as long as the resource manager is alive.

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

Opens a handle to a resource file inside a kzb file.

You can use this handle to read data directly from the kzb file.

Parameters

	url	URL of the resource.
[out]	kzbFile	If the function finds the resource file, returns a pointer to the kzb file.

Returns: Handle that points to the data inside the kzb file.

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

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

Returns: nullptr if the function cannot find the directory.

Deprecated:: Part of the legacy kzb loading. Use getKzbFile instead.

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

Adds a binary directory from a kzb file to the resource manager, which you can then use with the kzb protocol.

The resource manager keeps the ownership of the binary directory.

Parameters

fileName Path to the kzb file. Note that the filename can be different from the directory name stored in the kzb file. For example, file Programmer_tutorial.kzb can contain a directory named programmer_tutorial.

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

Deprecated:: Part of the legacy kzb loading. Use addKzbFile instead.

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

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

See also: For details about the merge process, see mergeDirectory().

Parameters

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

Returns: If successful, a pointer to the merged directory, otherwise nullptr.

Deprecated:: Part of the legacy kzb loading. Use addKzbFile instead.

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

inline

Returns the iterator to the beginning of binary directories.

Deprecated:: Part of the legacy kzb loading. Use beginKzbFiles instead.

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

inline

Returns the iterator to the end of binary directories.

Deprecated:: Part of the legacy kzb loading. Use endKzbFiles instead.

void kanzi::ResourceManager::invalidateAllGPUResources ( )

Kanzi internally uses this function to set all the GPU resources to undeployed state when an application loses and recreates the GL context after a pause-resume event.

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

Calculates the memory usage summary for all resources.

Parameters

out_resourceCount	The total number of resources.
out_cpuMemoryUsage	Estimate for the total amount of bytes of CPU memory that the resources use.
out_gpuMemoryUsage	Estimate for the total amount of bytes of GPU memory that the resources use.

size_t kanzi::ResourceManager::getAcquireTaskCount ( ) const

Returns the number of acquire tasks that have been started with a call to acquireResourcesAsync and have not yet been completed.

Each acquire task can load multiple resources.

Returns: The number of acquire tasks.

size_t kanzi::ResourceManager::getLoadQueueSize ( ) const

Returns the number of resource load tasks in the load queue.

This includes the load tasks that are waiting to be loaded and load tasks that are currently being loaded. This does not include the load tasks that are in the finishing queue.

Returns: The number of load tasks in load queue.

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

Returns the domain.

Returns: The domain.

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

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

Parameters

protocol	The protocol name. For example, "http".
handler	The protocol loader function. Kanzi calls this function when you use a URL with the given protocol, and Kanzi does not find an existing resource with that URL. This loader function creates a resource. reloadFunction The protocol reloader function. Kanzi calls this function to recreate an existing resource. Kanzi uses this function only for GPU resources when an application loses GL context in a pause-resume event.
userData	Extra data that you want to pass to the handler functions.

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 whether the given resource URL protocol (scheme name) is registered as a protocol handler for the resource manager.

Parameters

protocol The protocol to check.

Returns: True if the protocol is registered, otherwise False.

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. If you already earlier acquired the resource at the given URL, this function returns a shared pointer to the already acquired resource.

The supported protocols are:

kzb protocol for loading resources from kzb files. For example, "kzb://programmer_tutorial/Prefabs/Widget Item Prefab". If the function cannot find the given URL in the added binary directories, the function throws an exception.
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 )

Acquires a resource associated with the given URL, like acquireResource, but does not throw exceptions.

See also: acquireResource

Parameters

url	URL of the resource.

Returns: Shared pointer to the resource. If the resource does not exist, nullptr.

template<typename Type >

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

inline

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

If the type cast fails, the function returns nullptr.

See also: acquireResource

Parameters

url	URL of the resource.

Returns: Shared pointer to the resource. If the resource does not exist, or has different type, nullptr.

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 the given type.

If the resource does not exist or the type cast fails, the function throws an exception.

See also: acquireResource

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 returns the resource.

You can use this function to provide a URL to a resource that you created using the API.

Parameters

url	URL of the resource.
resource	The registered 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 completes the load task and returns the result.

Parameters

url	URL of the resource.
loadTask	A load task that creates the resource at the given URL.

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

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

You can use this function to force Kanzi to recreate a resource the next time you use this URL.

Parameters

url	URL of the resource.

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

Acquires a resource associated with the given URL.

If no resource is associated with the URL, does not try to load the resource.

Parameters

url	URL of the resource.

Returns: The resource that was loaded with the given URL. If no resource was loaded with the given URL, nullptr.

BitmapImageUniquePtr kanzi::ResourceManager::loadImage ( string_view url ) const

Loads an image from the given URL.

Deprecated:: Part of the legacy kzb loading.

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

Loads a spline from the given URL.

Deprecated:: Part of the legacy kzb loading.

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

Tries to find a URL for the given resource.

This function loops over all resources, so it can take a long time to complete.

Parameters

resource The resource.

Returns: The resource URL. If the resource does not have a registered URL, an empty string.

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

static

Kanzi internally uses this function to convert a resource URL to a resource path by dropping the protocol and project name from the path.

For example, converts the URL "kzb://programmer_tutorial/Textures/bgr" to "Textures/bgr".

Parameters

resourceURL A resource URL.

Returns: The resource URL without protocol and project name.

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

static

Kanzi internally uses this function to convert an absolute path to a node to a relative path by removing the screen name part of the path.

For example, converts the path "Screen/RootPage/Viewport 2D" to "RootPage/Viewport 2D".

Parameters

absolutePath Absolute path to a node in the tree.

Returns: Relative path to the node from the Screen node.

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

Sets the memory release strategy for new resources.

Parameters

resourceReleaseStrategy The new memory strategy.

MemoryStrategy kanzi::ResourceManager::getDefaultMemoryStrategy ( ) const

Gets the memory release strategy.

Returns: The current memory strategy.

void kanzi::ResourceManager::purge ( )

Deletes unreferenced resources.

You can use this function to free memory. Destroys all resources that are referenced only by the resource manager.

void kanzi::ResourceManager::update ( )

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

Kanzi calls this function once every frame.

FinishingQueue& kanzi::ResourceManager::getFinishingQueue ( )

inline

Gets the finishing queue for asynchronous loading tasks.

You can use this to control the deployment strategy of the resources.

Returns: The finishing queue.

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. Kanzi 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, otherwise False.

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 Kanzi loads and deploys all resources, the function calls the callback you provide.

Parameters

urls	Set of URLs for resources that you want to load.
callback	Callback function that this function calls when Kanzi loads all specified resources.

Returns: Handle to the async load task. You can pass the handle to wait to wait for the completion of the load.

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

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

Parameters

acquireTask Acquire task created by acquireResourcesAsync.

void kanzi::ResourceManager::deployGPUResources ( )

Kanzi internally uses this function to reload all GPU resources that have been invalidated by the pause-resume event.

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

Kanzi internally uses this function to set the domain of the resource manager when it creates a resource manager.

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

Returns the memory manager.

Returns: The memory manager.

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

Gets the kzb file information for a file from the given URL.

Parameters

url	URL of the binary file.

Returns: Binary file information, or nullptr if URL does not point to any file.

Deprecated:: Part of the legacy kzb loading. Use openFile instead.

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

Get the kzb file construct corresponding to the given name.

Parameters

hostname	Hostname of the kzb file.
index	Index of the file for the given hostname, typically 0. Can be set to higher than 0 when a single hostname has multiple kzb files.

Returns: The kzb file, or nullptr if no matching kzb file is found.

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

Kanzi internally uses this function to reload a resource from a kzb file.

Parameters

resource The reloaded resource.

KzbFileDictionary::const_iterator kanzi::ResourceManager::beginKzbFiles ( ) const

inline

Returns the iterator to the beginning of loaded KZB files.

Returns: A const iterator to the beginning of KZB dictionary.

KzbFileDictionary::const_iterator kanzi::ResourceManager::endKzbFiles ( ) const

inline

Returns the iterator to the end of loaded KZB files.

Returns: A const iterator to the end of KZB dictionary.

void kanzi::ResourceManager::enqueueDependencies	(	LoadTaskSharedPtr	loadTask,
		UrlContainer	urls
	)

Enqueue resource dependencies of a load task for asynchronous loading.

Meant to be called by LoadTask::enqueueDependencies. When you call this function it informs the main thread about the dependencies of a load task, which then triggers the asynchronous loading of these dependencies.

Parameters

loadTask	The load task requesting the dependencies.
urls	Container of dependency URLs.

ResourceContainer kanzi::ResourceManager::getAllLoadedResources ( ) const

Get a container of all existing resources.

Returns: A container of shared_ptrs to all existing resources.

Friends And Related Function Documentation

friend class FinishingQueue

friend

friend class Resource

friend

friend class GPUResource

friend

friend class PreviewPatcher

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

Acquiring resources from kzb

Releasing resources

Acquiring resources asynchronously

Managing kzb files

Acquiring resources from the file system

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation