ezEngine  Milestone 7
ezResourceBase Class Referenceabstract

The case class for all resources. More...

#include <ResourceBase.h>

Inheritance diagram for ezResourceBase:

Classes

struct  MemoryUsage
 

Public Member Functions

const ezStringGetResourceID () 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.
 
void SetResourceDescription (const char *szDescription)
 The resource description allows to store an additional string that might be more descriptive during debugging, than the unique ID.
 
const ezStringGetResourceDescription () const
 The resource description allows to store an additional string that might be more descriptive during debugging, than the unique ID.
 
ezResourceState GetLoadingState () const
 Returns the current state in which this resource is in.
 
ezUInt8 GetNumQualityLevelsDiscardable () const
 Returns the current maximum quality level that the resource could have. More...
 
ezUInt8 GetNumQualityLevelsLoadable () const
 Returns how many quality levels the resource may additionally load.
 
void SetPriority (ezResourcePriority priority)
 Sets the current priority of this resource. More...
 
ezResourcePriority GetPriority () const
 Returns the currently user-specified priority of this resource. More...
 
void SetDueDate (ezTime date=ezTime::Seconds(60.0 *60.0 *24.0 *365.0 *1000.0))
 Specifies the time (usually in the future) at which this resource is needed and should be fully loaded. More...
 
virtual ezTime GetLoadingDeadline (ezTime tNow) const
 Returns the deadline (tNow + x) at which this resource is required to be loaded. More...
 
const ezBitflags
< ezResourceFlags > & 
GetBaseResourceFlags () const
 Returns the basic flags for the resource type. Mostly used the resource manager.
 
const MemoryUsageGetMemoryUsage () const
 Returns the information about the current memory usage of the resource.
 
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.
 
ezInt32 GetReferenceCount () const
 Returns the reference count of this resource.
 
const ezTimestampGetLoadedFileModificationTime () const
 Returns the modification date of the file from which this resource was loaded. More...
 
- Public Member Functions inherited from ezReflectedClass
EZ_FORCE_INLINE 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_FORCE_INLINE bool IsInstanceOf () const
 Returns whether the type of this instance is of the given type or derived from it.
 
virtual void Serialize (ezArchiveWriter &stream) const
 This function is called to serialize the instance. More...
 
virtual void Deserialize (ezArchiveReader &stream)
 This function is called to deserialize the instance. More...
 
virtual void OnDeserialized ()
 This function is called after all objects are deserialized and thus all references to other objects are valid. More...
 

Protected Types

enum  DoUpdate { OnMainThread, OnAnyThread }
 
enum  Unload { AllQualityLevels, OneQualityLevel }
 

Protected Member Functions

 ezResourceBase (DoUpdate ResourceUpdateThread, ezUInt8 uiQualityLevelsLoadable)
 Default constructor.
 
virtual ~ezResourceBase ()
 virtual destructor.
 
MemoryUsageModifyMemoryUsage ()
 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...
 

Private Member Functions

 EZ_ADD_DYNAMIC_REFLECTION (ezResourceBase)
 
void SetUniqueID (const char *szUniqueID, bool bIsReloadable)
 Called by ezResourceManager shortly after resource creation.
 
void CallUnloadData (Unload WhatToUnload)
 
virtual ezResourceLoadDesc UnloadData (Unload WhatToUnload)=0
 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.
 
void CallUpdateContent (ezStreamReaderBase *Stream)
 
virtual ezResourceLoadDesc UpdateContent (ezStreamReaderBase *Stream)=0
 Called whenever more data for the resource is available. The resource must read the stream to update it's data.
 
virtual ezResourceTypeLoaderGetDefaultResourceTypeLoader () const
 Returns the resource type loader that should be used for this type of resource, unless it has been overridden on the ezResourceManager. More...
 
virtual void UpdateMemoryUsage (MemoryUsage &out_NewMemoryUsage)=0
 This function must be overridden by all resource types. More...
 

Private Attributes

volatile ezResourceState m_LoadingState
 
ezUInt8 m_uiQualityLevelsDiscardable
 
ezUInt8 m_uiQualityLevelsLoadable
 
ezBitflags< ezResourceFlagsm_Flags
 
ezResourcePriority m_Priority
 
ezAtomicInteger32 m_iReferenceCount
 
ezAtomicInteger32 m_iLockCount
 
ezString m_UniqueID
 
ezString m_sResourceDescription
 
MemoryUsage m_MemoryUsage
 
ezTime m_LastAcquire
 
ezTime m_DueDate
 
ezTimestamp m_LoadedFileModificationTime
 

Friends

class ezResourceManager
 
class ezResourceManagerWorker
 
class ezResourceManagerWorkerGPU
 
template<typename ResourceType >
class ezResourceHandle
 
template<typename SELF , typename SELF_DESCRIPTOR >
class ezResource
 
EZ_CORE_DLL void IncreaseResourceRefCount (ezResourceBase *pResource)
 
EZ_CORE_DLL void DecreaseResourceRefCount (ezResourceBase *pResource)
 

Additional Inherited Members

- Static Public Member Functions inherited from ezNoBase
static const ezRTTIGetStaticRTTI ()
 

Detailed Description

The case class for all resources.

Note
Never derive directly from ezResourceBase, but derive from ezResource instead.

Member Function Documentation

ezResourceTypeLoader * ezResourceBase::GetDefaultResourceTypeLoader ( ) const
privatevirtual

Returns the resource type loader that should be used for this type of resource, unless it has been overridden on the ezResourceManager.

By default, this redirects to ezResourceManager::GetDefaultResourceLoader. So there is one global default loader, that can be set on the resource manager. Overriding this function will then allow to use a different resource loader on a specific type. Additionally, one can override the resource loader from the outside, by setting it via ezResourceManager::SetResourceTypeLoader. That last method always takes precedence and allows to modify the behavior without modifying the code for the resource. But in the default case, the resource defines which loader is used.

Reimplemented in ezShaderPermutationResource.

const ezTimestamp& ezResourceBase::GetLoadedFileModificationTime ( ) const
inline

Returns the modification date of the file from which this resource was loaded.

The date may be invalid, if it cannot be retrieved or the resource was created and not loaded.

ezTime ezResourceBase::GetLoadingDeadline ( ezTime  tNow) const
virtual

Returns the deadline (tNow + x) at which this resource is required to be loaded.

This represents the final priority that is used by the resource manager to determine which resource to load next.

Note
It is fully valid to return a time in the past.
Although it is possible to override this function, it is advised not to do so. The default algorithm is tweaked well enough already, it should not be necessary to modify it.
ezUInt8 ezResourceBase::GetNumQualityLevelsDiscardable ( ) const
inline

Returns the current maximum quality level that the resource could have.

This is used to scale the amount data used. Once a resource is in the 'Loaded' state, it can still have different quality levels. E.g. a texture can be fully used with n mipmap levels, but there might be more that could be loaded. On the other hand a resource could have a higher 'loaded quality level' then the 'max quality level', if the user just changed settings and reduced the maximum quality level that should be used. In this case the resource manager will instruct the resource to unload some of its data soon.

The quality level is a purely logical concept that can be handled very different by different resource types. E.g. a texture resource could theoretically use one quality level per available mipmap level. However, since the resource should generally be able to load and unload each quality level separately, it might make more sense for a texture resource, to use one quality level for everything up to 64*64, and then one quality level for each mipmap above that, which would result in 5 quality levels for a 1024*1024 texture.

Most resource will have zero or one quality levels (which is the same) as they are either loaded or not.

ezResourcePriority ezResourceBase::GetPriority ( ) const
inline

Returns the currently user-specified priority of this resource.

See Also
SetPriority
void ezResourceBase::SetDueDate ( ezTime  date = ezTime::Seconds(60.0 * 60.0 * 24.0 * 365.0 * 1000.0))

Specifies the time (usually in the future) at which this resource is needed and should be fully loaded.

This is another way in which the loading priority of the resource can be influenced by the runtime. By specifying a 'due date' or 'deadline', the resource manager is instructed to make sure that this resource gets loaded in due time. The closer that the due date is, the higher the priority for loading this resource becomes.

Calling this function without parameters 'resets' the due date to a date into the far future, which practically disables it.

The due date is an absolute deadline, whereas the priority is a relative value compared to other resources. Both can be combined. The due date always take precedence when it approaches, however as long as it is further away, priority has the most influence.

See Also
SetPriority
void ezResourceBase::SetIsReloadable ( bool  bIsReloadable)
inlineprotected

Call this to specify whether a resource is reloadable.

By default all created resources are flagged as not reloadable. All resources loaded from file are automatically flagged as reloadable.

void ezResourceBase::SetPriority ( ezResourcePriority  priority)

Sets the current priority of this resource.

This is one way for the engine to specify how important this resource is, in relation to others. The runtime can use any arbitrary scheme to compute the priority for resources, e.g. it could use distance to the camera, on screen size, or random chance. However, it should be consistent with the priority computation of other resources, to prevent preferring or penalizing other resources too much.

Also make sure to always update the priority of resources when it becomes unimportant. If a resource is set to high priority and then never changed back, it will be kept loaded longer than others.

The due date is an absolute deadline, whereas the priority is a relative value compared to other resources. Both can be combined. The due date always take precedence when it approaches, however as long as it is further away, priority has the most influence.

See Also
SetDueDate
virtual void ezResourceBase::UpdateMemoryUsage ( MemoryUsage out_NewMemoryUsage)
privatepure virtual

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.

Implemented in ezMeshBufferResource, ezMaterialResource, ezConstantBufferResource, ezTextureResource, ezMeshResource, ezShaderPermutationResource, and ezShaderResource.


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