Resource manager. More...

#include "kzu_resource_common.h"
#include <system/debug/kzs_error.h>
#include <system/kzs_types.h>
#include <system/kzs_header.h>

Data Structures
struct	KzuResourceManagerLoadCallbackData
	Structure for passing required resource manager objects to core layer when needed. More...

Typedefs
typedef kzsException(*	KzuResourceManagerProtocolHandler )(struct KzuResourceManager resourceManager, kzString resourceURL, kzString protocol, kzString hostname, kzUint port, kzString path, void userData, struct KzuResource **out_resource)
	Protocol handler function type definition. More...

Enumerations
enum	KzuResourceManagerMemoryStrategy { KZU_RESOURCE_MANAGER_MEMORY_STRATEGY_KEEP_IN_MEMORY, KZU_RESOURCE_MANAGER_MEMORY_STRATEGY_OPTIMIZE_MEMORY }
	Resource manager memory strategy. More...

Functions
kzsError	kzuResourceManagerCreate (const struct KzcMemoryManager memoryManager, struct KzcRenderer renderer, struct KzuResourceManager **out_resourceManager)
	Creates a resource manager. More...

kzsError	kzuResourceManagerDelete (struct KzuResourceManager *resourceManager)
	Deletes a resource manager. More...

kzsError	kzuResourceManagerInitializeLoaderThreads (struct KzuResourceManager *resourceManager, kzUint threadCount, kzUint loaderMemoryManagerSize, kzUint maxPendingResources)
	Initializes additional resource loader threads for resource manager, which process the resource loading in parallel. More...

kzsError	kzuResourceManagerUninitializeLoaderThreads (struct KzuResourceManager *resourceManager)
	Uninitalizes loader threads from resource manager. More...

kzsError	kzuResourceManagerAddDirectory (const struct KzuResourceManager resourceManager, const struct KzuBinaryDirectory directory)
	Adds binary directory to resource manager. More...

kzsError	kzuResourceManagerRemoveDirectory (const struct KzuResourceManager resourceManager, const struct KzuBinaryDirectory directory)
	Removes binary directory to resource manager. More...

struct KzuBinaryDirectory *	kzuResourceManagerGetDirectory (const struct KzuResourceManager *resourceManager, kzString name)
	Gets the binary directory with the given name from resource manager. More...

struct KzcHashMap *	kzuResourceManagerGetDirectories (const struct KzuResourceManager *resourceManager)
	Gets all directories from binary loader. More...

kzsError	kzuResourceManagerLoadAllResources (struct KzuResourceManager *resourceManager)
	Tells the resource manager to load all resources from queue. More...

kzsError	kzuResourceManagerDeployAllGPUResources (const struct KzuResourceManager *resourceManager)
	Tells the resource manager to deploy all GPU resources from queue. More...

kzsError	kzuResourceManagerUndeployAllGPUResources (struct KzuResourceManager *resourceManager)
	Tells the resource manager to undeploy all GPU resources. More...

kzsError	kzuResourceManagerInvalidateAllGPUResources (struct KzuResourceManager *resourceManager)
	Tells the resource manager to invalidate all GPU resource states back to undeployed state without actually undeploying. More...

kzsError	kzuResourceManagerGetMemoryUsage (const struct KzuResourceManager resourceManager, const KzuResourceType resourceType, kzUint out_resourceCount, kzUint out_cpuMemoryUsage, kzUint out_gpuMemoryUsage)
	Queries information about memory usage. More...

void	kzuResourceManagerSetKeepGPUResourcesInCPUMemory (struct KzuResourceManager *resourceManager, kzBool keepGPUResourcesInCPUMemory)
	Controls resource CPU memory usage. More...

struct KzcRenderer *	kzuResourceManagerGetRenderer (const struct KzuResourceManager *resourceManager)
	Gets the renderer of the resource manager. More...

struct KzuUIDomain *	kzuResourceManagerGetUIDomain (const struct KzuResourceManager *resourceManager)
	Gets UI domain from resource manager. More...

kzsError	kzuResourceManagerRegisterProtocolHandler (const struct KzuResourceManager resourceManager, kzString protocol, KzuResourceManagerProtocolHandler handler, void userData)
	Registers the given protocol handler for loading resources specified with the given resource URL protocol (scheme name). More...

kzsError	kzuResourceManagerUnregisterProtocolHandler (const struct KzuResourceManager *resourceManager, kzString protocol)
	Unregisters the protocol handler with the given resource URL protocol (scheme name). More...

kzBool	kzuResourceManagerSupportsProtocolHandler (const struct KzuResourceManager *resourceManager, kzString protocol)
	Checks if the given resource URL protocol (scheme name) is registered as a protocol handler for the resource manager. More...

kzsException	kzuResourceManagerAcquireResource (struct KzuResourceManager resourceManager, kzString url, struct KzuResource *out_resource)
	Acquires resource from resource manager based on given URL. More...

kzsError	kzuResourceManagerAddResource (const struct KzuResourceManager resourceManager, kzString url, struct KzuResource resource)
	Adds the resource with the given URL to resource manager. More...

kzsError	kzuResourceManagerRemoveResource (const struct KzuResourceManager *resourceManager, kzString url)
	Removes a resource with the given URL from resource manager. More...

struct KzuResource *	kzuResourceManagerGetResource (const struct KzuResourceManager *resourceManager, kzString url)

kzString	kzuResourceManagerGetResourceURL (const struct KzuResourceManager resourceManager, const struct KzuResource resource)

kzString	kzuResourceManagerGetResourcePathFromURL (kzString resourceURL)
	Gets resource path from resource URL. More...

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

kzsError	kzuResourceManagerGetResourceTypeForKZBURL (const struct KzuResourceManager resourceManager, kzString url, KzuResourceType out_resourceType)
	Gets the resource type of a URL pointing to .KZB file. More...

void	kzuResourceManagerSetDefaultMemoryStrategy (struct KzuResourceManager *resourceManager, enum KzuResourceManagerMemoryStrategy resourceReleaseStrategy)
	Sets default memory strategy. More...

enum KzuResourceManagerMemoryStrategy	kzuResourceManagerGetDefaultMemoryStrategy (const struct KzuResourceManager *resourceManager)
	Gets default memory strategy. More...

kzsError	kzuResourceManagerPurge (struct KzuResourceManager *resourceManager)
	Deletes unreferenced resources. More...

kzsError	kzuResourceManagerUpdate (struct KzuResourceManager *resourceManager)
	Processes resource manager load and deployment queues. More...

kzsError	kzuResourceManagerPreloadResources (struct KzuResourceManager resourceManager, const struct KzcDynamicArray preloadURLs, kzsError(loadedCallback)(void userData), void *userData)
	Creates a background task that loads and deploys all resources from a set of URLs. More...

Detailed Description

Resource manager.

Typedef Documentation

typedef kzsException(* KzuResourceManagerProtocolHandler)(struct KzuResourceManager *resourceManager, kzString resourceURL, kzString protocol, kzString hostname, kzUint port, kzString path, void *userData, struct KzuResource **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().

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

Enumeration Type Documentation

enum KzuResourceManagerMemoryStrategy

Resource manager memory strategy.

Enumerator
KZU_RESOURCE_MANAGER_MEMORY_STRATEGY_KEEP_IN_MEMORY	With this setting, when a resource is no longer referenced, resource manager keeps it in memory until kzuResourceManagerPurge() is called.
KZU_RESOURCE_MANAGER_MEMORY_STRATEGY_OPTIMIZE_MEMORY	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.

Function Documentation

kzsError kzuResourceManagerCreate	(	const struct KzcMemoryManager *	memoryManager,
		struct KzcRenderer *	renderer,
		struct KzuResourceManager **	out_resourceManager
	)

Creates a resource manager.

kzsError kzuResourceManagerDelete ( struct KzuResourceManager * resourceManager)

Deletes a resource manager.

kzsError kzuResourceManagerInitializeLoaderThreads	(	struct KzuResourceManager *	resourceManager,
		kzUint	threadCount,
		kzUint	loaderMemoryManagerSize,
		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	Number of loader threads. If 0, parallel loading is disabled.
loaderMemoryManagerSize	Memory manager size for resource loading, required to hold the allocated resource data. No effect if threadCount is 0.
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.

kzsError kzuResourceManagerUninitializeLoaderThreads ( struct KzuResourceManager * resourceManager)

Uninitalizes loader threads from resource manager.

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

kzsError kzuResourceManagerAddDirectory	(	const struct KzuResourceManager *	resourceManager,
		const struct KzuBinaryDirectory *	directory
	)

Adds binary directory to resource manager.

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

kzsError kzuResourceManagerRemoveDirectory	(	const struct KzuResourceManager *	resourceManager,
		const struct KzuBinaryDirectory *	directory
	)

Removes binary directory to resource manager.

struct KzuBinaryDirectory* kzuResourceManagerGetDirectory	(	const struct KzuResourceManager *	resourceManager,
		kzString	name
	)

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

Returns: KZ_NULL if a directory is not found.

struct KzcHashMap* kzuResourceManagerGetDirectories ( const struct KzuResourceManager * resourceManager)

Gets all directories from binary loader.

Returns: A hash map where keys are binary directory names (kzString) and values are the directories (struct KzuBinaryDirectory*).

kzsError kzuResourceManagerLoadAllResources ( struct KzuResourceManager * resourceManager)

Tells the resource manager to load all resources from queue.

Waits until load queue is empty, including the loader threads.

kzsError kzuResourceManagerDeployAllGPUResources ( const struct KzuResourceManager * resourceManager)

Tells the resource manager to deploy all GPU resources from queue.

kzsError kzuResourceManagerUndeployAllGPUResources ( struct KzuResourceManager * resourceManager)

Tells the resource manager to undeploy all GPU resources.

kzsError kzuResourceManagerInvalidateAllGPUResources ( struct KzuResourceManager * resourceManager)

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.

kzsError kzuResourceManagerGetMemoryUsage	(	const struct KzuResourceManager *	resourceManager,
		const KzuResourceType	resourceType,
		kzUint *	out_resourceCount,
		kzUint *	out_cpuMemoryUsage,
		kzUint *	out_gpuMemoryUsage
	)

Queries information about memory usage.

The information is returned for every type covered by given resourceType parameter. Passing KZU_RESOURCE_TYPE_RESOURCE as the type will return information about all resources. Passing KZU_RESOURCE_TYPE_GPU_RESOURCE as the type will return information about all GPU resources. Passing the RESOURCE_TYPE of any specific resource such as mesh will return information only about such resources.

void kzuResourceManagerSetKeepGPUResourcesInCPUMemory	(	struct KzuResourceManager *	resourceManager,
		kzBool	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.

struct KzcRenderer* kzuResourceManagerGetRenderer ( const struct KzuResourceManager * resourceManager)

Gets the renderer of the resource manager.

struct KzuUIDomain* kzuResourceManagerGetUIDomain ( const struct KzuResourceManager * resourceManager)

Gets UI domain from resource manager.

kzsError kzuResourceManagerRegisterProtocolHandler	(	const struct KzuResourceManager *	resourceManager,
		kzString	protocol,
		KzuResourceManagerProtocolHandler	handler,
		void *	userData
	)

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

kzsError kzuResourceManagerUnregisterProtocolHandler	(	const struct KzuResourceManager *	resourceManager,
		kzString	protocol
	)

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

kzBool kzuResourceManagerSupportsProtocolHandler	(	const struct KzuResourceManager *	resourceManager,
		kzString	protocol
	)

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

kzsException kzuResourceManagerAcquireResource	(	struct KzuResourceManager *	resourceManager,
		kzString	url,
		struct KzuResource **	out_resource
	)

Acquires resource from resource manager based on given URL.

If resource is already loaded, increases the reference count and returns the loaded resource. This function first queries from the Localization manager for a localized version of the resource URL.

Parameters

out_resource Output resource or KZ_NULL. Can be KZ_NULL.

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

kzsError kzuResourceManagerAddResource	(	const struct KzuResourceManager *	resourceManager,
		kzString	url,
		struct KzuResource *	resource
	)

Adds the resource with the given URL to resource manager.

kzsError kzuResourceManagerRemoveResource	(	const struct KzuResourceManager *	resourceManager,
		kzString	url
	)

Removes a resource with the given URL from resource manager.

struct KzuResource* kzuResourceManagerGetResource	(	const struct KzuResourceManager *	resourceManager,
		kzString	url
	)

Returns: Resource with given url from resource manager storage. KZ_NULL if none exists.

kzString kzuResourceManagerGetResourceURL	(	const struct KzuResourceManager *	resourceManager,
		const struct KzuResource *	resource
	)

Returns: Resource URL from resource manager, KZ_NULL if not found.

kzString kzuResourceManagerGetResourcePathFromURL ( kzString resourceURL)

Gets resource path from resource URL.

Returns KZ_NULL if the URL is malformed.

kzString kzuResourceManagerGetRelativePathFromAbsolutePath ( kzString absolutePath)

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

kzsError kzuResourceManagerGetResourceTypeForKZBURL	(	const struct KzuResourceManager *	resourceManager,
		kzString	url,
		KzuResourceType *	out_resourceType
	)

Gets the resource type of a URL pointing to .KZB file.

Returns KZ_NULL if the URL does not point to a .KZB resource file.

void kzuResourceManagerSetDefaultMemoryStrategy	(	struct KzuResourceManager *	resourceManager,
		enum KzuResourceManagerMemoryStrategy	resourceReleaseStrategy
	)

Sets default memory strategy.

enum KzuResourceManagerMemoryStrategy kzuResourceManagerGetDefaultMemoryStrategy ( const struct KzuResourceManager * resourceManager)

Gets default memory strategy.

kzsError kzuResourceManagerPurge ( struct KzuResourceManager * resourceManager)

Deletes unreferenced resources.

kzsError kzuResourceManagerUpdate ( struct KzuResourceManager * resourceManager)

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.

kzsError kzuResourceManagerPreloadResources	(	struct KzuResourceManager *	resourceManager,
		const struct KzcDynamicArray *	preloadURLs,
		kzsError()(void userData)	loadedCallback,
		void *	userData
	)

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.

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation