KzuResource is the base class for all resource objects in the Engine. More...

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

Macros
#define	KZU_RESOURCE_PROFILING_MESH_KZB
	Profiling tag for mesh. More...

#define	KZU_RESOURCE_PROFILING_MESH_DEPLOY
	Profiling tag for mesh deploy. More...

#define	KZU_RESOURCE_PROFILING_TEXTURE_2D_KZB
	Profiling tag for 2d texture. More...

#define	KZU_RESOURCE_PROFILING_TEXTURE_2D_DEPLOY
	Profiling tag for 2d texture deploy. More...

#define	KZU_RESOURCE_PROFILING_TEXTURE_CUBE_KZB
	Profiling tag for cubemap texture. More...

#define	KZU_RESOURCE_PROFILING_TEXTURE_CUBE_DEPLOY
	Profiling tag for cubemap texture deploy. More...

#define	KZU_RESOURCE_PROFILING_TEXTURE_RENDER_TARGET_2D_KZB
	Profiling tag for 2d render target texture. More...

#define	KZU_RESOURCE_PROFILING_TEXTURE_RENDER_TARGET_2D_DEPLOY
	Profiling tag for 2d render target texture deploy. More...

#define	KZU_RESOURCE_PROFILING_TEXTURE_RENDER_TARGET_CUBE_KZB
	Profiling tag for cubemap render target texture. More...

#define	KZU_RESOURCE_PROFILING_TEXTURE_RENDER_TARGET_CUBE_DEPLOY
	Profiling tag for cubemap render target texture deploy. More...

#define	KZU_RESOURCE_PROFILING_SHADER_KZB
	Profiling tag for shader. More...

#define	KZU_RESOURCE_PROFILING_SHADER_DEPLOY
	Profiling tag for shader deploy. More...

#define	KZU_RESOURCE_PROFILING_MATERIAL_KZB
	Profiling tag for material. More...

#define	KZU_RESOURCE_PROFILING_STYLE_KZB
	Profiling tag for style. More...

#define	KZU_RESOURCE_PROFILING_STATE_MANAGER_KZB
	Profiling tag for state manager. More...

#define	KZU_RESOURCE_PROFILING_TIMELINE_SEQUENCE_KZB
	Profiling tag for timeline sequence. More...

#define	KZU_RESOURCE_PROFILING_ANIMATION_CLIP_KZB
	Profiling tag for animation clip. More...

#define	KZU_RESOURCE_PROFILING_ANIMATION_KZB
	Profiling tag for animation. More...

#define	KZU_RESOURCE_PROFILING_COMPOSER_KZB
	Profiling tag for composer. More...

#define	KZU_RESOURCE_PROFILING_OBJECT_NODE_KZB
	Profiling tag for object node. More...

#define	KZU_RESOURCE_PROFILING_PREFAB_TEMPLATE_KZB
	Profiling tag for prefab template. More...

#define	KZU_RESOURCE_PROFILING_PREFAB_TEMPLATE_NODE_KZB
	Profiling tag for prefab template. More...

#define	KZU_RESOURCE_PROFILING_GENERIC_FILE_KZB
	Profiling tag for prefab template. More...

#define	KZU_RESOURCE_PROFILING_TRAJECTORY_KZB
	Profiling tag for trajectory. More...

#define	KZU_RESOURCE_PROFILING_OBJECT_SOURCE_KZB
	Profiling tag for object source. More...

#define	KZU_RESOURCE_PROFILING_FONT_KZB
	Profiling tag for font. More...

#define	KZU_RESOURCE_PROFILING_TEXT_KZB
	Profiling tag for text. More...

Enumerations
enum	KzuResourceLoadingStrategy { KZU_RESOURCE_LOADING_STRATEGY_DEFAULT, KZU_RESOURCE_LOADING_STRATEGY_MANUAL, KZU_RESOURCE_LOADING_STRATEGY_OPTIMIZE_SPEED, KZU_RESOURCE_LOADING_STRATEGY_OPTIMIZE_MEMORY, KZU_RESOURCE_LOADING_STRATEGY_ON_DEMAND }
	Resource loading strategy specifies when the resource is loaded and unloaded. More...

Functions
kzsError	kzuResourceCreateKZBLoader (const struct KzcMemoryManager memoryManager, const struct KzuBinaryDirectory binaryDirectory, kzString path, struct KzuResourceLoader **out_resourceLoader)
	Creates the resource loader that loads the resource from the project file (.KZB) using the given path. More...

kzsError	kzuResourceDelete (struct KzuResource *resource)
	Deletes the resource. More...

kzBool	kzuResourceTypeIsTypeOf (const KzuResourceType resourceType, const KzuResourceType baseResourceType)
	Checks whether the resourceType, or one of its base types, is of the given base resource type. More...

kzBool	kzuResourceIsTypeOf (const struct KzuResource *resource, const KzuResourceType resourceType)
	Checks whether the resource, or one of its base types, is of the given resource type. More...

KzuResourceType	kzuResourceGetType (const struct KzuResource *resource)
	Returns the type of the resource. More...

kzString	kzuResourceTypeGetName (KzuResourceType resourceType)
	Returns the resource type name as a string. More...

kzString	kzuResourceGetName (const struct KzuResource *resource)
	Returns the name of the resource as a string. More...

struct KzuResourceManager *	kzuResourceGetResourceManager (const struct KzuResource *resource)
	Returns the resource manager that was used for creating the resource. More...

kzsError	kzuResourceLoad (struct KzuResource *resource)
	Loads the resource if the resource is not loaded. More...

kzsError	kzuResourceUnload (struct KzuResource *resource)
	Unloads the resource if the resource is loaded. More...

kzBool	kzuResourceIsLoaded (const struct KzuResource *resource)
	Checks whether the resource is loaded. More...

enum KzuResourceLoadingStrategy	kzuResourceGetLoadingStrategy (const struct KzuResource *resource)
	Returns the loading strategy of the resource. More...

void	kzuResourceSetLoadingStrategy (struct KzuResource *resource, enum KzuResourceLoadingStrategy loadingStrategy)
	Sets the loading strategy of the resource. More...

kzUint	kzuResourceGetCPUMemoryUsage (const struct KzuResource *resource)
	Returns the amount of memory used by the resource. More...

kzsError	kzuResourceAcquire (struct KzuResource *resource)
	Acquires an existing resource, increasing the reference count by one. More...

kzsError	kzuResourceRelease (struct KzuResource *resource)
	Decreases the reference count of a resource by one, effectively releases the resource when the reference count reaches zero. More...

kzsError	kzuResourceLoad_private (struct KzuResource resource, const struct KzuResourceLoaderThreadContext threadContext)
	Private function for kzuResourceLoad() with specified thread context. More...

kzsError	kzuResourceFinishLoading_private (struct KzuResource resource, const struct KzuResourceLoaderThreadContext threadContext)
	Private function for finishing the loading of the resource. More...

Variables
const KzuResourceType	KZU_RESOURCE_TYPE_RESOURCE
	Base resource type identifier for all resources. More...

Detailed Description

KzuResource is the base class for all resource objects in the Engine.

The main functionality is to provide:

Functionality for loading and unloading data
Runtime type information (RTTI) of resources

Loading and unloading of resource data is controlled by a KzuResourceManager, which uses KzuResourceLoadingStrategy of the resource to determine when the data should be loaded or unloaded.

User can derive this class using the API provided by kzu_resource_base.h.

Example: The following example uses RTTI to check if a resource is a texture resource and queries texture specific information if it is.
if (kzuResourceIsTypeOf(resource, KZU_RESOURCE_TYPE_TEXTURE))

{

struct KzuTexture* texture = kzuTextureFromResource(resource);

kzString name = kzuResourceGetName(resource);

kzUint width = kzuTextureGetWidth(texture);

kzUint height = kzuTextureGetHeight(texture);

kzcLogDebug("Resource %s is a texture of size %i * %i", name, width, height);

}

Example: The following example logs how much memory a resource currently consumes.
kzString name = kzuResourceGetName(resource);

KzuResourceType type = kzuResourceGetType(resource);

kzString typeName = kzuResourceTypeGetName(type);

kzUint memoryUsage = kzuResourceGetCPUMemoryUsage(resource);

kzcLogDebug("Resource %s of type %s uses %i bytes of RAM", name, typeName, memoryUsage);

See Also: kzu_resource_manager.h; kzu_gpu_resource.h

Macro Definition Documentation

#define KZU_RESOURCE_PROFILING_MESH_KZB

Profiling tag for mesh.

#define KZU_RESOURCE_PROFILING_MESH_DEPLOY

Profiling tag for mesh deploy.

#define KZU_RESOURCE_PROFILING_TEXTURE_2D_KZB

Profiling tag for 2d texture.

#define KZU_RESOURCE_PROFILING_TEXTURE_2D_DEPLOY

Profiling tag for 2d texture deploy.

#define KZU_RESOURCE_PROFILING_TEXTURE_CUBE_KZB

Profiling tag for cubemap texture.

#define KZU_RESOURCE_PROFILING_TEXTURE_CUBE_DEPLOY

Profiling tag for cubemap texture deploy.

#define KZU_RESOURCE_PROFILING_TEXTURE_RENDER_TARGET_2D_KZB

Profiling tag for 2d render target texture.

#define KZU_RESOURCE_PROFILING_TEXTURE_RENDER_TARGET_2D_DEPLOY

Profiling tag for 2d render target texture deploy.

#define KZU_RESOURCE_PROFILING_TEXTURE_RENDER_TARGET_CUBE_KZB

Profiling tag for cubemap render target texture.

#define KZU_RESOURCE_PROFILING_TEXTURE_RENDER_TARGET_CUBE_DEPLOY

Profiling tag for cubemap render target texture deploy.

#define KZU_RESOURCE_PROFILING_SHADER_KZB

Profiling tag for shader.

#define KZU_RESOURCE_PROFILING_SHADER_DEPLOY

Profiling tag for shader deploy.

#define KZU_RESOURCE_PROFILING_MATERIAL_KZB

Profiling tag for material.

#define KZU_RESOURCE_PROFILING_STYLE_KZB

Profiling tag for style.

#define KZU_RESOURCE_PROFILING_STATE_MANAGER_KZB

Profiling tag for state manager.

#define KZU_RESOURCE_PROFILING_TIMELINE_SEQUENCE_KZB

Profiling tag for timeline sequence.

#define KZU_RESOURCE_PROFILING_ANIMATION_CLIP_KZB

Profiling tag for animation clip.

#define KZU_RESOURCE_PROFILING_ANIMATION_KZB

Profiling tag for animation.

#define KZU_RESOURCE_PROFILING_COMPOSER_KZB

Profiling tag for composer.

#define KZU_RESOURCE_PROFILING_OBJECT_NODE_KZB

Profiling tag for object node.

#define KZU_RESOURCE_PROFILING_PREFAB_TEMPLATE_KZB

Profiling tag for prefab template.

#define KZU_RESOURCE_PROFILING_PREFAB_TEMPLATE_NODE_KZB

Profiling tag for prefab template.

#define KZU_RESOURCE_PROFILING_GENERIC_FILE_KZB

Profiling tag for prefab template.

#define KZU_RESOURCE_PROFILING_TRAJECTORY_KZB

Profiling tag for trajectory.

#define KZU_RESOURCE_PROFILING_OBJECT_SOURCE_KZB

Profiling tag for object source.

#define KZU_RESOURCE_PROFILING_FONT_KZB

Profiling tag for font.

#define KZU_RESOURCE_PROFILING_TEXT_KZB

Profiling tag for text.

Enumeration Type Documentation

enum KzuResourceLoadingStrategy

Resource loading strategy specifies when the resource is loaded and unloaded.

Enumerator
KZU_RESOURCE_LOADING_STRATEGY_DEFAULT	When using the default strategy the engine loads the resource before it is needed. The loading strategy depends on the platform and Kanzi application, but the engine optimizes the loading strategy.
KZU_RESOURCE_LOADING_STRATEGY_MANUAL	When using the manual loading strategy you must load and unload the resource manually by calling the kzuResourceLoad and kzuResourceUnload functions. This is the only loading strategy that you can control completely.
KZU_RESOURCE_LOADING_STRATEGY_OPTIMIZE_SPEED	When using the optimize speed strategy the engine keeps the resource in RAM. When the application needs the resource, the engine can deploy the resource from RAM to GPU as fast as possible. The engine releases the resource from RAM only when the resource is not accessible anymore. This strategy guarantees that the engine does not unload the resource during runtime.
KZU_RESOURCE_LOADING_STRATEGY_OPTIMIZE_MEMORY	When using the optimize memory loading strategy the engine unloads the resource as soon as possible. The engine releases the GPU resources from RAM after deploying the resources.
KZU_RESOURCE_LOADING_STRATEGY_ON_DEMAND	When using the on demand strategy the engine loads the resource when it is needed and releases it when it is not needed anymore. On demand loading strategy differs from the optimize loading strategy in that it does not load the resource before it is needed. This strategy is not yet supported.

Function Documentation

kzsError kzuResourceCreateKZBLoader	(	const struct KzcMemoryManager *	memoryManager,
		const struct KzuBinaryDirectory *	binaryDirectory,
		kzString	path,
		struct KzuResourceLoader **	out_resourceLoader
	)

Creates the resource loader that loads the resource from the project file (.KZB) using the given path.

Parameters

memoryManager	Memory manager to allocate memory for resource loader.
binaryDirectory	Binary directory containing resource to load.
path	Path of the resource inside a .KZB virtual file system.
out_resourceLoader	The created resource loader.

kzsError kzuResourceDelete ( struct KzuResource * resource)

Deletes the resource.

The reference count of the resource must be zero or an assert may fail.

If the resource is a GPU resource and it has been deployed, it will be undeployed.

If the resource has been loaded, it will be unloaded.

Frees any remaining data owned by the resource by calling a virtual destructor.

After calling this function, the pointer to the resource becomes invalid and must not be used anymore.

Parameters

resource The resource that will be deleted.

Returns: KZS_SUCCESS on success.

kzBool kzuResourceTypeIsTypeOf	(	const KzuResourceType	resourceType,
		const KzuResourceType	baseResourceType
	)

Checks whether the resourceType, or one of its base types, is of the given base resource type.

Parameters

resourceType	The resource type to check.
baseResourceType	Resource type to check against.

Returns: Returns KZ_TRUE if the resource type or one of its parent types is of the given base resource type, otherwise returns KZ_FALSE.

kzBool kzuResourceIsTypeOf	(	const struct KzuResource *	resource,
		const KzuResourceType	resourceType
	)

Checks whether the resource, or one of its base types, is of the given resource type.

Parameters

resource	The resource whose type to check.
resourceType	Resource type to check against.

Returns: Returns KZ_TRUE if the resource or one of its parent types is of the given resource type, otherwise returns KZ_FALSE.

KzuResourceType kzuResourceGetType ( const struct KzuResource * resource)

Returns the type of the resource.

Parameters

resource The resource.

Returns: Type of the resource specified on creation time.

kzString kzuResourceTypeGetName ( KzuResourceType resourceType)

Returns the resource type name as a string.

This function is meant for debugging.

Parameters

resourceType The resource type.

Returns: Name of the resource type as a string.

kzString kzuResourceGetName ( const struct KzuResource * resource)

Returns the name of the resource as a string.

Parameters

resource The resource.

Returns: Name of the resource.

struct KzuResourceManager* kzuResourceGetResourceManager ( const struct KzuResource * resource)

Returns the resource manager that was used for creating the resource.

Parameters

resource The resource.

Returns: The resource manager specified on creation time.

kzsError kzuResourceLoad ( struct KzuResource * resource)

Loads the resource if the resource is not loaded.

Depending on the deployment strategy this may also deploy the resource if it is a GPU resource.

Parameters

resource The resource to load.

Returns: KZS_SUCCESS on successful loading or if the resource is already loaded.

kzsError kzuResourceUnload ( struct KzuResource * resource)

Unloads the resource if the resource is loaded.

Ignores the loading strategy.

Parameters

resource The resource to unload.

Returns: KZS_SUCCESS on successful unloading or if the resource is not loaded.

kzBool kzuResourceIsLoaded ( const struct KzuResource * resource)

Checks whether the resource is loaded.

Parameters

resource The resource.

Returns: Returns KZ_TRUE if the resource is loaded, otherwise returns KZ_FALSE.

enum KzuResourceLoadingStrategy kzuResourceGetLoadingStrategy ( const struct KzuResource * resource)

Returns the loading strategy of the resource.

Parameters

resource The resource which loading strategy is returned.

Returns: Returns previously set loading strategy or KZU_RESOURCE_LOADING_STRATEGY_DEFAULT if it's not set.

void kzuResourceSetLoadingStrategy	(	struct KzuResource *	resource,
		enum KzuResourceLoadingStrategy	loadingStrategy
	)

Sets the loading strategy of the resource.

Parameters

resource	The resource which loading strategy is set.
loadingStrategy	The loading strategy to use. See KzuResourceLoadingStrategy.

kzUint kzuResourceGetCPUMemoryUsage ( const struct KzuResource * resource)

Returns the amount of memory used by the resource.

Parameters

resource The resource.

Returns: The amount of memory used by the resource in bytes or zero.

kzsError kzuResourceAcquire ( struct KzuResource * resource)

Acquires an existing resource, increasing the reference count by one.

kzsError kzuResourceRelease ( struct KzuResource * resource)

Decreases the reference count of a resource by one, effectively releases the resource when the reference count reaches zero.

Note that the memory allocated for the resource may or may not be freed when the count reaches zero, depending on the resource manager's settings.

Parameters

resource The resource which reference count to decrease.

kzsError kzuResourceLoad_private	(	struct KzuResource *	resource,
		const struct KzuResourceLoaderThreadContext *	threadContext
	)

Private function for kzuResourceLoad() with specified thread context.

kzsError kzuResourceFinishLoading_private	(	struct KzuResource *	resource,
		const struct KzuResourceLoaderThreadContext *	threadContext
	)

Private function for finishing the loading of the resource.

Variable Documentation

const KzuResourceType KZU_RESOURCE_TYPE_RESOURCE

Base resource type identifier for all resources.

All resource types inherit from this resource type. This implies that kzuResourceIsTypeOf(resource, KZU_RESOURCE_TYPE_RESOURCE) always returns KZ_TRUE.

Macros

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

Enumeration Type Documentation

Function Documentation

If the resource is a GPU resource and it has been deployed, it will be undeployed.

If the resource has been loaded, it will be unloaded.

Frees any remaining data owned by the resource by calling a virtual destructor.

Variable Documentation