#include <kanzi/resource/resource_manager.hpp>

Classes
struct	KzuResourceManagerProtocolHandlerObject_internal
	Protocol handler structure. More...

struct	LoadCallbackData
	Structure for passing required resource manager objects to core layer when needed. More...

Public Types
enum	MemoryStrategy { KeepInMemory, OptimizeMemory }
	Resource manager memory strategy. 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)
	Protocol handler function type definition. More...

typedef unordered_map< string, KzuBinaryDirectory * >	DirectoryMap

typedef unordered_map< string, KzuResourceManagerProtocolHandlerObject_internal >	ProtocolMap

typedef unordered_map< string, ResourceWeakPtr >	LookupMap

typedef unordered_map< string, ResourceSharedPtr >	KeepInMemoryLookupMap

typedef vector< string >	PreloadUrlContainer

typedef function< void()>	PreloadFinishedCallback

Public Member Functions
void	initializeLoaderThreads (kzUint threadCount, kzUint maxPendingResources)
	Initializes additional resource loader threads for resource manager, which process the resource loading in parallel. More...

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

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

void	removeDirectory (KzuBinaryDirectory *directory)
	Removes binary directory from the resource manager. 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 file to the resource manager to be used with the kzb protocol. More...

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

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

void	undeployAllGPUResources ()
	Tells the resource manager to undeploy all GPU resources. More...

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

bool	areAllGPUResourcesSupported ()

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

void	setKeepGPUResourcesInCPUMemory (bool keepGPUResourcesInCPUMemory)
	Controls resource CPU memory usage. More...

Renderer *	getRenderer () const
	Gets the renderer of the resource manager. More...

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

CompositionManager *	getCompositionManager () const
	Get composition manager. More...

void	setCompositionManager (CompositionManagerSharedPtr compositionManager)
	Set composition manager. More...

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

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

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

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

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

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

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

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

void	unregisterResource (string_view url)
	Associates the association of the given URL. More...

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

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

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

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

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

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

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

void	update ()
	Processes resource manager load and deployment queues. More...

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

void	preloadResources (const PreloadUrlContainer &preloadURLs, PreloadFinishedCallback callback)
	Creates a background task that loads and deploys all resources from a set of URLs. More...

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

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

KzcMemoryManager *	getMemoryManager () const

BrushResourceSharedPtr	getNullBrush ()

void	addResource (Resource *resource)
	Adds a resource to resource manager. More...

void	removeResource (Resource *resource)
	Removes a resource from resource manager. More...

void	removeGPUResource (GPUResource *resource)
	Removes a gpu resource from resource manager. More...

void	enqueueResourceFinishLoading (Resource resource, const KzuResourceLoaderThreadContext threadContext)
	Notifies the resource manager that a resource loading has been processed and it can be placed to the queue for finishing the loading in the main thread. More...

void	resourceLoaded (Resource *resource, bool forcePrioritizeResource)
	Notifies the resource manager that a resource has been fully loaded. More...

void	resourceUnloaded (Resource *resource)
	Notifies the resource manager that a resource has been unloaded. More...

void	gpuResourceDeployed (GPUResource *gpuResource)
	Notifies the resource manager that a GPU resource has been deployed. More...

void	gpuResourceUndeployed (const GPUResource *gpuResource) const
	Notifies the resource manager that a GPU resource has been undeployed. More...

void	gpuResourceCommonDataFreed (const GPUResource *gpuResource) const
	Notifies the resource manager that the common data of a GPU resource has been freed. More...

void	gpuResourceInvalidated (GPUResource *gpuResource)
	Notifies the resource manager that a GPU resource has been invalidated. More...

const KzuResourceLoaderThreadContext *	getMainThreadContext () const
	Gets the resource loader thread context for the main thread. More...

void	update_private (bool preloading)
	Processes resource manager load and deployment queues. More...

void	interceptResourceLoading (Resource *resource)
	Tries to stop resource loading as soon as possible. More...

void	prioritizeResource (Resource *resource)
	Marks the resource as prioritized. More...

void	deployIfQueued (Resource *resource)
	Deploys the resource if it is a GPU resource and it has been enqueued for deployment (not for progressive deployment). More...

void	updatePendingResourceCount (kzInt amount)
	Increments or decrements the number of pending resources in the resource manager. More...

Static Public Member Functions
static ResourceManager *	create (KzcMemoryManager memoryManager, Renderer renderer)
	Creates a resource manager. More...

static void	destroy (ResourceManager *resourceManager)
	Deletes a resource manager. More...

static kzString	getResourcePathFromURL (kzString resourceURL)
	Gets resource path from resource URL. More...

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

Protected Member Functions
	ResourceManager (KzcMemoryManager memoryManager, Renderer renderer)
	Constructor. More...

	~ResourceManager ()
	Destructor. More...

Friends
class	Resource

class	GPUResource

Member Typedef Documentation

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)

Protocol handler function type definition.

Parameters

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

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

typedef unordered_map<string, KzuBinaryDirectory*> kanzi::ResourceManager::DirectoryMap

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

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

typedef unordered_map<string, ResourceSharedPtr> kanzi::ResourceManager::KeepInMemoryLookupMap

typedef vector<string> kanzi::ResourceManager::PreloadUrlContainer

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

Member Enumeration Documentation

enum kanzi::ResourceManager::MemoryStrategy

Resource manager memory strategy.

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

Constructor & Destructor Documentation

kanzi::ResourceManager::ResourceManager	(	KzcMemoryManager *	memoryManager,
		Renderer *	renderer
	)

explicitprotected

Constructor.

Parameters

memoryManager	Memory manager to use.
renderer	Renderer to use.

kanzi::ResourceManager::~ResourceManager ( )

protected

Destructor.

Member Function Documentation

static ResourceManager* kanzi::ResourceManager::create	(	KzcMemoryManager *	memoryManager,
		Renderer *	renderer
	)

static

Creates a resource manager.

static void kanzi::ResourceManager::destroy ( ResourceManager * resourceManager )

static

Deletes a resource manager.

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

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

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

Parameters

threadCount	The number of loader threads. If set to 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::uninitializeLoaderThreads ( )

Uninitalizes loader threads from resource manager.

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

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

Adds a binary directory to the resource manager to be used with the kzb protocol. This transfers the ownership of the binary directory to the resource manager.

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

Removes binary directory from the resource manager.

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

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

Returns: nullptr if a directory is not found.

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

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

The resource manager keeps the ownership of the binary directory.

Parameters

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

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

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

inline

Returns iterator to beginning of binary directories.

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

inline

Returns iterator to end of binary directories.

void kanzi::ResourceManager::undeployAllGPUResources ( )

Tells the resource manager to undeploy all GPU resources.

void kanzi::ResourceManager::invalidateAllGPUResources ( )

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

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

bool kanzi::ResourceManager::areAllGPUResourcesSupported ( )

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

Queries information about memory usage.

void kanzi::ResourceManager::setKeepGPUResourcesInCPUMemory ( bool keepGPUResourcesInCPUMemory )

Controls resource CPU memory usage.

Normally when GPU resources are deployed, they are optionally unloaded from CPU memory depending on their loading strategy. If this flag is set, the loading strategy is ignored and the resource is always kept in CPU memory after deployment.

Renderer* kanzi::ResourceManager::getRenderer ( ) const

Gets the renderer of the resource manager.

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

Gets UI domain from resource manager.

CompositionManager* kanzi::ResourceManager::getCompositionManager ( ) const

inline

Get composition manager.

Returns: Reference to composition manager.

void kanzi::ResourceManager::setCompositionManager ( CompositionManagerSharedPtr compositionManager )

inline

Set composition manager.

Will take ownership of composition manager passed.

Parameters

compositionManager New composition manager.

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

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

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

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

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

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

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

Acquires a resource associated with the given url.

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

The supported protocols are:

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

Parameters

url	Url of the resource.

Returns: Shared pointer to the resource.

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

Behaves like acquireResource but doesn't throw exceptions.

See also: acquireResource

Parameters

url	Url of the resource.

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

template<typename Type >

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

inline

template<typename Type >

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

inline

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

If the cast fails, throws an exception.

Parameters

url	Url of the resource.

Returns: Shared pointer to the resource.

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

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

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

Associates the association of the given URL.

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

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

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

Loads an image from the given url.

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

Loads a spline from the given url.

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

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

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

static

Gets resource path from resource URL.

Returns KZ_NULL if the URL is malformed.

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

static

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

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

Sets default memory strategy.

MemoryStrategy kanzi::ResourceManager::getDefaultMemoryStrategy ( ) const

Gets default memory strategy.

void kanzi::ResourceManager::purge ( )

Deletes unreferenced resources.

void kanzi::ResourceManager::update ( )

Processes resource manager load and deployment queues.

This function ensures that all immediately needed resources are loaded and deployed.

bool kanzi::ResourceManager::processDeploymentQueueItem ( )

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

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

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

void kanzi::ResourceManager::preloadResources	(	const PreloadUrlContainer &	preloadURLs,
		PreloadFinishedCallback	callback
	)

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

After all resources are loaded and deployed, calls the provided callback. The callback happens always in the main thread.

void kanzi::ResourceManager::deployGPUResources ( )

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

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

Helper function for setting project to resource manager.

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

BrushResourceSharedPtr kanzi::ResourceManager::getNullBrush ( )

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

Adds a resource to resource manager.

Resources themselves are responsible for adding them, so this function is not public.

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

Removes a resource from resource manager.

Resources themselves are responsible for removing them, so this function is not public.

void kanzi::ResourceManager::removeGPUResource ( GPUResource * resource )

Removes a gpu resource from resource manager.

Resources themselves are responsible for removing them, so this function is not public.

void kanzi::ResourceManager::enqueueResourceFinishLoading	(	Resource *	resource,
		const KzuResourceLoaderThreadContext *	threadContext
	)

Notifies the resource manager that a resource loading has been processed and it can be placed to the queue for finishing the loading in the main thread.

void kanzi::ResourceManager::resourceLoaded	(	Resource *	resource,
		bool	forcePrioritizeResource
	)

Notifies the resource manager that a resource has been fully loaded.

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

Notifies the resource manager that a resource has been unloaded.

void kanzi::ResourceManager::gpuResourceDeployed ( GPUResource * gpuResource )

Notifies the resource manager that a GPU resource has been deployed.

void kanzi::ResourceManager::gpuResourceUndeployed ( const GPUResource * gpuResource ) const

Notifies the resource manager that a GPU resource has been undeployed.

void kanzi::ResourceManager::gpuResourceCommonDataFreed ( const GPUResource * gpuResource ) const

Notifies the resource manager that the common data of a GPU resource has been freed.

void kanzi::ResourceManager::gpuResourceInvalidated ( GPUResource * gpuResource )

Notifies the resource manager that a GPU resource has been invalidated.

const KzuResourceLoaderThreadContext* kanzi::ResourceManager::getMainThreadContext ( ) const

Gets the resource loader thread context for the main thread.

void kanzi::ResourceManager::update_private ( bool preloading )

Processes resource manager load and deployment queues.

This function ensures that all immediately needed resources are loaded and deployed. Resources marked for preloading will be deployed progressively if preloading is KZ_TRUE.

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

Tries to stop resource loading as soon as possible.

If the loading has already started in a loader thread, waits until the resource is loaded.

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

Marks the resource as prioritized.

Prioritized resources will be loaded and deployed on the next call to kzuResourceManagerUpdate().

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

Deploys the resource if it is a GPU resource and it has been enqueued for deployment (not for progressive deployment).

void kanzi::ResourceManager::updatePendingResourceCount ( kzInt amount )

Increments or decrements the number of pending resources in the resource manager.

This function acquires the required lock.

Parameters

resourceManager	The resource manager object holding the counter for pending resources.
amount	If amount == 1, the pending resource count is incremented. If amount == -1, the pending resource count is decremented. Other values are invalid.

Friends And Related Function Documentation

friend class Resource

friend

friend class GPUResource

friend

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

kanzi/resource/resource_manager.hpp

Classes

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Friends

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation