Kanzi  3.9.4
Kanzi Engine API
kanzi::ResourceManager Class Reference

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< AcquireTaskAcquireTaskSharedPtr
 AcquireTask shared pointer type. More...
 
typedef function< void()> AsyncAcquireFinishedCallback
 Callback function type for acquire tasks. More...
 
typedef vector< LoadTaskSharedPtrFinishingQueueContainer
 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< KzbFileKzbFilePtr
 Type for a smart pointer to a KZB file. More...
 
typedef shared_ptr< LoadTaskLoadTaskSharedPtr
 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...
 
DomaingetDomain () const
 Returns the domain. More...
 
FinishingQueuegetFinishingQueue ()
 Gets the finishing queue for asynchronous loading tasks. More...
 
KzbFilegetKzbFile (string_view hostname, size_t index=0) const
 Get the kzb file construct corresponding to the given name. More...
 
const LibJPEGParametersgetLibJPEGParameters () const
 Gets the parameters that Kanzi passes to libjpeg. More...
 
const LibPNGParametersgetLibPNGParameters () 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...
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:

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

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
resourceManagerThe resource manager.
resourceURLThe full URL of the resource in the form of protocol://hostname[:port]/path.
protocolExtracted protocol part of the resource URL.
hostnameExtracted hostname part of the resource URL.
portExtracted port part of the resource URL. This is 0 if the port is omitted from the URL.
pathExtracted path part of the resource URL.
out_resourceThe loaded resource, or nullptr.
out_loadTaskA 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
nameThread 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"
uriURI of the loading task.

◆ FinishingQueueContainer

Container type for the finishing queue. Used internally.

◆ AsyncAcquireFinishedCallback

Callback function type for acquire tasks.

◆ AcquireTaskSharedPtr

AcquireTask shared pointer type.

◆ KzbFilePtr

Type for a smart pointer to a KZB file.

◆ KzbFileDictionary

Type for the KZB file container.

◆ ResourceContainer

Alias for a container of resources.

Member Enumeration Documentation

◆ 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
threadCountThe number of loader threads. If 0, parallel loading is disabled.
maxPendingResourcesThe 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
threadIndexIndex 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
maxPendingResourcesThe 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
fileNameThe 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
kzbFileFile to add.
enforceColorspaceGenerate 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
dataData to add. The memory area must be readable as long as the resource manager is alive.
enforceColorspaceGenerate 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
urlURL of the resource.
[out]kzbFileIf 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_resourceCountThe total number of resources.
out_cpuMemoryUsageEstimate for the total amount of bytes of CPU memory that the resources use.
out_gpuMemoryUsageEstimate 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
protocolThe protocol name. For example, "http".
handlerThe 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.
reloadFunctionThe 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
protocolThe 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
urlURL 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
urlURL 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
urlURL 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
urlURL 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
urlURL of the resource.
resourceThe 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
urlURL of the resource.
loadTaskA 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
urlURL 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
urlURL 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
resourceThe 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
resourceReleaseStrategyThe 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
callbackCallback 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
threadNameThread name to pass to a callback.
urlURL 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
urlsSet of URLs for resources that you want to load.
callbackCallback 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
acquireTaskAcquire 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
hostnameHostname of the kzb file.
indexIndex 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
resourceThe 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
loadTaskThe load task requesting the dependencies.
urlsContainer 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
parameterslibjpeg 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
parameterslibpng 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: