An ezCollectionResource is used to tell the engine about resources that it should preload in the background. More...

#include <CollectionResource.h>

Inheritance diagram for ezCollectionResource:

[legend]

Public Member Functions
void	RegisterNames ()
	Registers the named resources in the collection with the ezResourceManager, such that they can be loaded by those names. More...

void	UnregisterNames ()
	Removes the registered names from the ezResourceManager. More...

bool	PreloadResources (ezUInt32 uiNumResourcesToPreload=ezMath::MaxValue< ezUInt32 >())
	Puts up to the given number of resources for which a resource type could be found into the preload queue of the ezResourceManager. More...

bool	IsLoadingFinished (float *out_pProgress=nullptr) const
	Returns true if all resources added for preloading via PreloadResources have finished loading. if `out_progress` is defined: More...

const ezCollectionResourceDescriptor &	GetDescriptor () const
	Returns the resource descriptor for this resource.

ezArrayPtr< const ezTypelessResourceHandle >	GetPreloadedResources () const
	Returns the current list of resources that have already been added to the preload list. See PreloadResources().

Public Member Functions inherited from ezResource
EZ_ALWAYS_INLINE ezStringView	GetResourceID () const
	Returns the unique ID that identifies this resource. On a file resource this might be a path. Can also be a GUID or any other scheme that uniquely identifies the resource.

EZ_ALWAYS_INLINE ezUInt64	GetResourceIDHash () const
	Returns the hash of the unique ID.

void	SetResourceDescription (ezStringView sDescription)
	The resource description allows to store an additional string that might be more descriptive during debugging, than the unique ID.

const ezString &	GetResourceDescription () const
	The resource description allows to store an additional string that might be more descriptive during debugging, than the unique ID.

const ezString &	GetResourceIdOrDescription () const
	The returns the resource description, if available, otherwise the resource ID. More...

EZ_ALWAYS_INLINE ezResourceState	GetLoadingState () const
	Returns the current state in which this resource is in.

EZ_ALWAYS_INLINE ezUInt8	GetNumQualityLevelsDiscardable () const
	Returns the current maximum quality level that the resource could have. More...

EZ_ALWAYS_INLINE ezUInt8	GetNumQualityLevelsLoadable () const
	Returns how many quality levels the resource may additionally load.

float	GetLoadingPriority (ezTime now) const
	Returns the priority that is used by the resource manager to determine which resource to load next.

ezResourcePriority	GetPriority () const
	Returns the current resource priority.

void	SetPriority (ezResourcePriority priority)
	Changes the current resource priority.

const EZ_ALWAYS_INLINE ezBitflags< ezResourceFlags > &	GetBaseResourceFlags () const
	Returns the basic flags for the resource type. Mostly used the resource manager.

const EZ_ALWAYS_INLINE MemoryUsage &	GetMemoryUsage () const
	Returns the information about the current memory usage of the resource.

EZ_ALWAYS_INLINE ezTime	GetLastAcquireTime () const
	Returns the time at which the resource was (tried to be) acquired last. If a resource is acquired using ezResourceAcquireMode::PointerOnly, this does not update the last acquired time, since the resource is not acquired for full use.

EZ_ALWAYS_INLINE ezInt32	GetReferenceCount () const
	Returns the reference count of this resource.

const EZ_ALWAYS_INLINE ezTimestamp &	GetLoadedFileModificationTime () const
	Returns the modification date of the file from which this resource was loaded. More...

EZ_ALWAYS_INLINE ezUInt32	GetCurrentResourceChangeCounter () const
	Returns the current value of the resource change counter. Can be used to detect whether the resource has changed since using it last time. More...

EZ_ALWAYS_INLINE void	IncResourceChangeCounter ()
	Allows to manually increase the resource change counter to signal that dependent code might need to update.

virtual void	ResetResource ()
	If the resource has modifications from the original state, it should reset itself to that state now (or force a reload on itself).

void	PrintHandleStackTraces ()
	Prints the stack-traces for all handles that currently reference this resource. More...

Public Member Functions inherited from ezReflectedClass
virtual const ezRTTI *	GetDynamicRTTI () const

bool	IsInstanceOf (const ezRTTI *pType) const
	Returns whether the type of this instance is of the given type or derived from it.

template<typename T >
EZ_ALWAYS_INLINE bool	IsInstanceOf () const
	Returns whether the type of this instance is of the given type or derived from it.

Private Member Functions
virtual ezResourceLoadDesc	UnloadData (Unload WhatToUnload) override
	Requests the resource to unload another quality level. If bFullUnload is true, the resource should unload all data, because it is going to be deleted afterwards.

virtual ezResourceLoadDesc	UpdateContent (ezStreamReader *Stream) override
	Called whenever more data for the resource is available. The resource must read the stream to update it's data. More...

virtual void	UpdateMemoryUsage (MemoryUsage &out_NewMemoryUsage) override
	This function must be overridden by all resource types. More...

Additional Inherited Members
Public Types inherited from ezResource
enum	DoUpdate { OnMainThread, OnAnyThread, DoUpdate::OnGraphicsResourceThreads }

Static Public Member Functions inherited from ezNoBase
static const ezRTTI *	GetStaticRTTI ()

Public Attributes inherited from ezResource
ezEvent< const ezResourceEvent &, ezMutex >	m_ResourceEvents

Static Public Attributes inherited from ezResource
static DoUpdate	UpdateGraphicsResource = ezResource::DoUpdate::OnAnyThread

Protected Types inherited from ezResource
enum	Unload { AllQualityLevels, OneQualityLevel }

Protected Member Functions inherited from ezResource
	ezResource (DoUpdate ResourceUpdateThread, ezUInt8 uiQualityLevelsLoadable)
	Default constructor.

virtual	~ezResource ()
	virtual destructor.

MemoryUsage &	ModifyMemoryUsage ()
	Non-const version for resources that want to write this variable directly.

void	SetIsReloadable (bool bIsReloadable)
	Call this to specify whether a resource is reloadable. More...

void	SetHasLoadingFallback (bool bHasLoadingFallback)
	Used internally by the code injection macros.

Detailed Description

An ezCollectionResource is used to tell the engine about resources that it should preload in the background.

Collection resources can be used to improve the user experience by ensuring data is already (more likely) available when it is needed. For instance when a player walks into a longer corridor, a collection resource can be triggered to preload the data that will be needed when he reaches the door at the end of the corridor. In scenes this can be achieved using an ezCollectionComponent.

Collection resources can also be used to query how much percent of the references resources are already loaded, which enables building progress bars or allowing functionality only after all necessary data is available.

Finally, collections can also be used to register resources with a nice name, such that it can be referenced in code by that name. This is useful if you want to reference some asset in code with a readable resource ID, and may want to change which resource is referenced at a later time. For example the nice name "Avatar" could point to some dummy mesh at the beginning of the project, and be updated to point to something else later, without the need to change the code.

Note: Once ezCollectionResource::PreloadResources() has been triggered, the resource will hold a handle to all referenced resources, meaning those resources cannot get unloaded anymore. Make sure to discard the collection resource if the data it references should get freed up.

Member Function Documentation

◆ IsLoadingFinished()

bool ezCollectionResource::IsLoadingFinished ( float * out_pProgress = nullptr ) const

Returns true if all resources added for preloading via PreloadResources have finished loading. if out_progress is defined:

Assigns a value between 0.0 and 1.0 representing how many of the collection's resources are in a loaded state at the moment.
Always assigns 1.0 if all resources are in a loaded state.
Always assigns 1.0 if the collection contains no resources, or PreloadResources() was not triggered previously. Note: the progress can reach at maximum the fraction of resources that have been queued for preloading via PreloadResources. The progress will only reach 1.0 if all resources of this collection have been queued via PreloadResources and finished loading.

◆ PreloadResources()

bool ezCollectionResource::PreloadResources ( ezUInt32 uiNumResourcesToPreload = ezMath::MaxValue<ezUInt32>() )

Puts up to the given number of resources for which a resource type could be found into the preload queue of the ezResourceManager.

This has to be called manually. It will return false if no more resources can be queued for preloading. This can be used as a workflow where PreloadResources and IsLoadingFinished are called repeadedly in tandem, so only a smaller fraction of resources gets queued and waited for, to allow simple resource load-balancing.

◆ RegisterNames()

void ezCollectionResource::RegisterNames ( )

Registers the named resources in the collection with the ezResourceManager, such that they can be loaded by those names.

Note: This has to be called MANUALLY on collection resources, they do NOT do this automatically when loaded. Since resources are streamed, there is no guaranteed point in time when those names would be registered, which would introduce timing issues, where sometimes the name is registered when it is used and sometimes not. By calling this manually, the point in time where this is done is fixed and guaranteed.

Calling this twice has no effect.

◆ UnregisterNames()

void ezCollectionResource::UnregisterNames ( )

Removes the registered names from the ezResourceManager.

Calling this twice has no effect.

◆ UpdateContent()

ezResourceLoadDesc ezCollectionResource::UpdateContent ( ezStreamReader * pStream )

overrideprivatevirtual

Called whenever more data for the resource is available. The resource must read the stream to update it's data.

pStream may be nullptr in case the resource data could not be found.

Implements ezResource.

◆ UpdateMemoryUsage()

void ezCollectionResource::UpdateMemoryUsage ( MemoryUsage & out_NewMemoryUsage )

overrideprivatevirtual

This function must be overridden by all resource types.

It has to compute the memory used by this resource. It is called by the resource manager whenever the resource's data has been loaded or unloaded.

Implements ezResource.

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

/home/runner/work/ezEngine/ezEngine/Code/Engine/Core/Collection/CollectionResource.h
/home/runner/work/ezEngine/ezEngine/Code/Engine/Core/Collection/Implementation/CollectionResource.cpp

Public Member Functions

Private Member Functions

Additional Inherited Members