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 the load tasks that load new resources. More...

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

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

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

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

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

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

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

using	NewLoadingTaskCallback = function< void(string_view, string_view)>
	Type definition for callback on thread task assignment. More...

using	ProtocolHandler = function< kzsException(ResourceManager *resourceManager, string_view resourceURL, string_view protocol, string_view hostname, unsigned port, string_view path, ResourceSharedPtr &out_resource, LoadTaskSharedPtr &out_loadTask)>
	Type definition for the protocol handler of the load function. More...

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

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

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

Public Member Functions
ResourceSharedPtr	acquireLoadedResource (string_view url) const
	Acquires a resource associated with the given URL. More...

ResourceSharedPtr	acquireResource (string_view url)
	Acquires a resource associated with the given URL. 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...

AcquireTaskSharedPtr	acquireResourcesAsync (const UrlContainer &urls, AsyncAcquireFinishedCallback callback)
	Creates a background task that loads and deploys all resources from a set of URLs. 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, bool enforceColorspace=true)
	Adds a kzb file to the list of files. More...

void	addKzbFile (ConstByteSpan data, bool enforceColorspace=true)
	Adds a memory block as a kzb file. More...

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

void	deployGPUResources ()
	Kanzi internally uses this function to reload all GPU resources that have been invalidated by the pause-resume event. 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 async loading. 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...

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

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

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

FinishingQueue &	getFinishingQueue ()
	Gets the finishing queue for asynchronous loading tasks. More...

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

const LibJPEGParameters &	getLibJPEGParameters () const
	Gets the parameters that Kanzi passes to libjpeg. More...

const LibPNGParameters &	getLibPNGParameters () const
	Gets the parameters that Kanzi passes to libpng. More...

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

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

size_t	getLoadQueueSize () const
	Returns the number of resource load tasks in the load queue. 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...

string	getResourceURL (const Resource &resource) const
	Tries to find a URL for the given resource. More...

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

void	initializeLoaderThreads (size_t threadCount, size_t maxPendingResources)
	Initializes the additional resource loader threads for the resource manager. 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	onNewLoadingTask (string_view threadName, string_view url) const
	Notify about task assignment. More...

ReadOnlyMemoryFilePtr	openFile (string_view url, KzbFile **kzbFile)
	Opens a handle to a resource file inside a kzb file. More...

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

void	purge ()
	Deletes unreferenced resources. 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	registerProtocolHandler (kzString protocol, ProtocolHandler handler, ProtocolResourceReloadFunction reloadFunction)
	Registers a protocol handler for loading resources specified with the given resource URL protocol (scheme name). 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	reloadFromUrl (Resource *resource)
	Kanzi internally uses this function to reload a resource from a kzb file. More...

	ResourceManager ()
	Constructor. More...

void	setDefaultMemoryStrategy (MemoryStrategy resourceReleaseStrategy)
	Sets the memory release strategy for new resources. 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...

void	setLibJPEGParameters (const LibJPEGParameters &parameters)
	Sets the parameters that Kanzi passes to libjpeg when loading files. More...

void	setLibPNGParameters (const LibPNGParameters &parameters)
	Sets the parameters that Kanzi passes to libpng when loading files. 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	setOnNewLoadingTask (NewLoadingTaskCallback callback)
	When a thread is assigned a task, the callback specified with `callback` is called with the URI of the task. 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	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...

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

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

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

void	update ()
	Processes resource manager load and deployment queues to progress the background tasks. 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	waitForAcquireTasks ()
	Kanzi internally uses this function when application is about to lose GL context, to wait for all existing acquire tasks to finish. More...

	~ResourceManager ()
	Destructor. More...

Friends
class	FinishingQueue

class	GPUResource

class	NewPreviewPatcher

class	PreviewPatcher

class	Resource

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
Font 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

◆ UrlContainer

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

Container type for URL set.

◆ LoadTaskSharedPtr

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

LoadTask shared pointer type.

◆ ProtocolHandler

using kanzi::ResourceManager::ProtocolHandler = function<kzsException(ResourceManager* resourceManager, string_view resourceURL, string_view protocol, string_view hostname, unsigned port, string_view path, 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.
out_resource	The loaded resource, or nullptr.
out_loadTask	A load task for the resource, or nullptr.

Returns: Success or exception.

◆ ProtocolResourceReloadFunction

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

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.

◆ NewLoadingTaskCallback

using kanzi::ResourceManager::NewLoadingTaskCallback = function<void(string_view , string_view )>

Type definition for callback on thread task assignment.

Parameters

name	Thread name to pass to callback. Loading threads have names like `RLT` d, where `d` is the index of the loading thread. If the task is done in the main thread, the thread name is `"RLT Main"`
uri	URI of the loading task.

◆ FinishingQueueContainer

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

Container type for the finishing queue. Used internally.

◆ AsyncAcquireFinishedCallback

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

Callback function type for acquire tasks.

◆ AcquireTaskSharedPtr

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

AcquireTask shared pointer type.

◆ KzbFilePtr

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

Type for a smart pointer to a KZB file.

◆ KzbFileDictionary

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

Type for the KZB file container.

◆ ResourceContainer

using kanzi::ResourceManager::ResourceContainer = vector<ResourceSharedPtr>

Alias for a container of resources.

Member Enumeration Documentation

◆ MemoryStrategy

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

◆ ResourceManager()

kanzi::ResourceManager::ResourceManager ( )

explicit

Constructor.

◆ ~ResourceManager()

kanzi::ResourceManager::~ResourceManager ( )

Destructor.

Member Function Documentation

◆ initializeLoaderThreads()

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.

◆ waitForAcquireTasks()

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.

◆ uninitializeLoaderThreads()

void kanzi::ResourceManager::uninitializeLoaderThreads ( )

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

◆ getLoaderThreadHandle()

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:

        // Kanzi passes the loader thread count to an application 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.

Since: Kanzi 3.7.0

◆ getLoaderThreadCount()

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.

Since: Kanzi 3.7.0

◆ setMaxPendingResources()

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.

◆ addKzbFile() [1/3]

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.

◆ addKzbFile() [2/3]

void kanzi::ResourceManager::addKzbFile	(	unique_ptr< KzbFile >	kzbFile,
		bool	enforceColorspace = `true`
	)

Adds a kzb file to the list of files.

Parameters

kzbFile	File to add.
enforceColorspace	Generate a warning if the colorspace does not match the domain.

◆ addKzbFile() [3/3]

void kanzi::ResourceManager::addKzbFile	(	ConstByteSpan	data,
		bool	enforceColorspace = `true`
	)

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.
enforceColorspace	Generate a warning if the colorspace does not match the domain.

◆ openFile()

ReadOnlyMemoryFilePtr 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.

◆ invalidateAllGPUResources()

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.

◆ getMemoryUsage()

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.

◆ getAcquireTaskCount()

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.

◆ getLoadQueueSize()

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.

◆ getDomain()

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

Returns the domain.

Returns: The domain.

◆ registerProtocolHandler()

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

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.

◆ unregisterProtocolHandler()

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

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

◆ supportsProtocolHandler()

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.

◆ acquireResource() [1/2]

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.

◆ tryAcquireResource() [1/2]

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.

◆ tryAcquireResource() [2/2]

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.

◆ acquireResource() [2/2]

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.

◆ registerResource()

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.

◆ registerLoadTask()

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.

◆ unregisterResource()

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.

◆ acquireLoadedResource()

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.

◆ getResourceURL()

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.

◆ setDefaultMemoryStrategy()

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

Sets the memory release strategy for new resources.

Parameters

resourceReleaseStrategy The new memory strategy.

◆ getDefaultMemoryStrategy()

MemoryStrategy kanzi::ResourceManager::getDefaultMemoryStrategy ( ) const

Gets the memory release strategy.

Returns: The current memory strategy.

◆ purge()

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.

◆ update()

void kanzi::ResourceManager::update ( )

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

Kanzi calls this function once every frame.

◆ setOnNewLoadingTask()

void kanzi::ResourceManager::setOnNewLoadingTask ( NewLoadingTaskCallback callback )

inline

When a thread is assigned a task, the callback specified with callback is called with the URI of the task.

Preferred location to call this is in onConfigure().

Parameters

callback Callback to run when a thread is assigned work.

◆ onNewLoadingTask()

void kanzi::ResourceManager::onNewLoadingTask	(	string_view	threadName,
		string_view	url
	)		const

inline

Notify about task assignment.

See also: setLoadingThreadTaskNotification().

Parameters

threadName	Thread name to pass to a callback.
url	URL to pass to a callback.

◆ getFinishingQueue()

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.

◆ processDeploymentQueueItem()

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.

◆ hasDeploymentTasks()

bool kanzi::ResourceManager::hasDeploymentTasks ( ) const

Tell if deployment queue is empty.

Returns: True if empty, otherwise False.

◆ acquireResourcesAsync()

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.

◆ wait()

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.

◆ deployGPUResources()

void kanzi::ResourceManager::deployGPUResources ( )

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

◆ setDomain()

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.

◆ getKzbFile()

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.

◆ reloadFromUrl()

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

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

Parameters

resource The reloaded resource.

◆ beginKzbFiles()

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.

◆ endKzbFiles()

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.

◆ enqueueDependencies()

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

Enqueue resource dependencies of a load task for async loading.

Meant to be called by LoadTask::enqueueDependencies. Informs the main thread of the dependencies of a load task, which can then trigger their async loading.

Parameters

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

◆ getAllLoadedResources()

ResourceContainer kanzi::ResourceManager::getAllLoadedResources ( ) const

Get a container of all existing resources.

Returns: A container of shared_ptrs to all existing resources.

◆ setLibJPEGParameters()

void kanzi::ResourceManager::setLibJPEGParameters ( const LibJPEGParameters & parameters )

inline

Sets the parameters that Kanzi passes to libjpeg when loading files.

Parameters

parameters libjpeg parameters.

Since: Kanzi 3.9.3

◆ getLibJPEGParameters()

const LibJPEGParameters& kanzi::ResourceManager::getLibJPEGParameters ( ) const

inline

Gets the parameters that Kanzi passes to libjpeg.

Returns: libjpeg parameters.

Since: Kanzi 3.9.3

◆ setLibPNGParameters()

void kanzi::ResourceManager::setLibPNGParameters ( const LibPNGParameters & parameters )

inline

Sets the parameters that Kanzi passes to libpng when loading files.

Parameters

parameters libpng parameters.

Since: Kanzi 3.9.3

◆ getLibPNGParameters()

const LibPNGParameters& kanzi::ResourceManager::getLibPNGParameters ( ) const

inline

Gets the parameters that Kanzi passes to libpng.

Returns: libpng parameters.

Since: Kanzi 3.9.3

Friends And Related Function Documentation

◆ FinishingQueue

friend class FinishingQueue

friend

◆ Resource

friend class Resource

friend

◆ GPUResource

friend class GPUResource

friend

◆ PreviewPatcher

friend class PreviewPatcher

friend

◆ NewPreviewPatcher

friend class NewPreviewPatcher

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

Friends

Detailed Description

Acquiring resources from kzb

Releasing resources

Acquiring resources asynchronously

Managing kzb files

Acquiring resources from the file system

Member Typedef Documentation

◆ UrlContainer

◆ LoadTaskSharedPtr

◆ ProtocolHandler

◆ ProtocolResourceReloadFunction

◆ NewLoadingTaskCallback

◆ FinishingQueueContainer

◆ AsyncAcquireFinishedCallback

◆ AcquireTaskSharedPtr

◆ KzbFilePtr

◆ KzbFileDictionary

◆ ResourceContainer

Member Enumeration Documentation

◆ MemoryStrategy

Constructor & Destructor Documentation

◆ ResourceManager()

◆ ~ResourceManager()

Member Function Documentation

◆ initializeLoaderThreads()

◆ waitForAcquireTasks()

◆ uninitializeLoaderThreads()

◆ getLoaderThreadHandle()

◆ getLoaderThreadCount()

◆ setMaxPendingResources()

◆ addKzbFile() [1/3]

◆ addKzbFile() [2/3]

◆ addKzbFile() [3/3]

◆ openFile()

◆ invalidateAllGPUResources()

◆ getMemoryUsage()

◆ getAcquireTaskCount()

◆ getLoadQueueSize()

◆ getDomain()

◆ registerProtocolHandler()

◆ unregisterProtocolHandler()

◆ supportsProtocolHandler()

◆ acquireResource() [1/2]

◆ tryAcquireResource() [1/2]

◆ tryAcquireResource() [2/2]

◆ acquireResource() [2/2]

◆ registerResource()

◆ registerLoadTask()

◆ unregisterResource()

◆ acquireLoadedResource()

◆ getResourceURL()

◆ setDefaultMemoryStrategy()

◆ getDefaultMemoryStrategy()

◆ purge()

◆ update()

◆ setOnNewLoadingTask()

◆ onNewLoadingTask()

◆ getFinishingQueue()

◆ processDeploymentQueueItem()

◆ hasDeploymentTasks()

◆ acquireResourcesAsync()

◆ wait()

◆ deployGPUResources()

◆ setDomain()

◆ getKzbFile()

◆ reloadFromUrl()

◆ beginKzbFiles()

◆ endKzbFiles()

◆ enqueueDependencies()

◆ getAllLoadedResources()

◆ setLibJPEGParameters()

◆ getLibJPEGParameters()

◆ setLibPNGParameters()

◆ getLibPNGParameters()

Friends And Related Function Documentation

◆ FinishingQueue