Base class for managed asset entity in ParaEngine. More...

#include <AssetEntity.h>

Inheritance diagram for ParaEngine::AssetEntity:

Public Types
enum	AssetState { ASSET_STATE_NORMAL, ASSET_STATE_LOCAL, ASSET_STATE_REMOTE, ASSET_STATE_CACHE, ASSET_STATE_SYNC_START, ASSET_STATE_SYNC_SUCCEED, ASSET_STATE_SYNC_FAIL, ASSET_STATE_FAILED_TO_LOAD }
	the asset state. More...

enum	AssetType { base =0, texture, mesh, multianimation, spritevertex, font, sound, mdx, parax, database, effectfile, dllplugin, datagrid, cadMesh, image }
	each asset type has a unique asset type number

Public Types inherited from ParaEngine::IAttributeFields
typedef ParaEngine::weak_ptr< IObject, IAttributeFields >	WeakPtr_type

Public Types inherited from ParaEngine::IObject
typedef ParaEngine::weak_ptr< IObject >	WeakPtr_type

Public Member Functions
	AssetEntity (const AssetKey &key)

	ATTRIBUTE_DEFINE_CLASS (AssetEntity)

virtual int	InstallFields (CAttributeClass *pClass, bool bOverride)
	this class should be implemented if one wants to add new attribute. More...

	ATTRIBUTE_METHOD1 (AssetEntity, GetLocalFileName_s, const char **)

	ATTRIBUTE_METHOD1 (AssetEntity, SetLocalFileName_s, const char *)

	ATTRIBUTE_METHOD1 (AssetEntity, GetRemoteAssetURL_s, const char **)

	ATTRIBUTE_METHOD1 (AssetEntity, IsValid_s, bool *)

	ATTRIBUTE_METHOD1 (AssetEntity, IsLoaded_s, bool *)

	ATTRIBUTE_METHOD1 (AssetEntity, IsLocked_s, bool *)

	ATTRIBUTE_METHOD1 (AssetEntity, IsInitialized_s, bool *)

	ATTRIBUTE_METHOD1 (AssetEntity, GetState_s, int *)

	ATTRIBUTE_METHOD1 (AssetEntity, SetState_s, int)

virtual AssetType	GetType ()

virtual const std::string &	GetIdentifier ()

virtual bool	AutoSync (bool bForceSync=false, bool bLazyLoading=true)
	call this function to automatically sync with the remote server according to current asset state More...

virtual void	Refresh (const char *sFilename=NULL, bool bLazyLoad=false)
	refresh the asset from local disk. More...

virtual const string &	GetLocalFileName ()
	the actual local file name. More...

virtual void	SetLocalFileName (const char *sFileName)

virtual string	GetRemoteAssetURL ()
	get the remote server url of this asset. More...

virtual CParameterBlock *	GetParamBlock (bool bCreateIfNotExist=false)
	get effect parameter block with this object. More...

bool	IsValid ()
	whether this is a valid resource object. More...

bool	IsInitialized ()
	whether initialized. More...

virtual bool	IsLoaded ()
	most assets are loaded asynchronously. More...

virtual int	Release ()
	call this function to safely release this asset. More...

AssetKey &	GetKey ()
	return the key object. More...

AssetState	GetState ()
	return the asset state. More...

void	SetState (AssetState state)
	set the asset state. More...

virtual IAttributeFields *	GetAttributeObject ()
	get the attribute object of this asset. More...

virtual HRESULT	InitDeviceObjects ()

virtual HRESULT	RestoreDeviceObjects ()

virtual HRESULT	InvalidateDeviceObjects ()

virtual HRESULT	DeleteDeviceObjects ()

virtual HRESULT	RendererRecreated ()
	callback of listening the event that renderer was recreated on Android/WP8 all opengl related id has already become invalid at this time, no need to release them, just recreate them all in this function.

virtual void	Cleanup ()
	Clean up additional resources. More...

void	LoadAsset ()
	load asset. More...

void	UnloadAsset ()
	unload asset. More...

void	GarbageCollectMe ()
	if its reference count is zero, unload this asset object. More...

bool	IsLocked ()
	whether this is a locked resource resource. More...

virtual bool	Lock (int nMethod=0)
	Lock the object. More...

virtual void	UnLock ()
	UnLock the object.

virtual bool	GetBoundingBox (Vector3 pMin, Vector3 pMax)
	Get AABB bounding box of the asset object. More...

Public Member Functions inherited from ParaEngine::IAttributeFields
virtual int	GetAttributeClassID ()
	attribute class ID should be identical, unless one knows how overriding rules work. More...

virtual const char *	GetAttributeClassName ()
	a static string, describing the attribute class object's name

virtual const char *	GetAttributeClassDescription ()
	a static string, describing the attribute class object

virtual int	GetChildAttributeColumnCount ()
	we support multi-dimensional child object. More...

virtual int	GetChildAttributeObjectCount (int nColumnIndex=0)
	get the number of child objects (row count) in the given column. More...

virtual IAttributeFields *	GetChildAttributeObject (int nRowIndex, int nColumnIndex=0)

virtual IAttributeFields *	GetChildAttributeObject (const std::string &sName)
	get attribute by child object. More...

	ATTRIBUTE_METHOD1 (IAttributeFields, GetName_s, const char **)

	ATTRIBUTE_METHOD1 (IAttributeFields, SetName_s, const char *)

	ATTRIBUTE_METHOD (IAttributeFields, PrintObject_s)

	ATTRIBUTE_METHOD (IAttributeFields, AddRef_s)

	ATTRIBUTE_METHOD1 (IAttributeFields, GetRefCount_s, int *)

	ATTRIBUTE_METHOD1 (IAttributeFields, SetTime_s, int)

	ATTRIBUTE_METHOD1 (IAttributeFields, GetTime_s, int *)

	ATTRIBUTE_METHOD (IAttributeFields, Release_s)

virtual void	SetIdentifier (const std::string &sID)

virtual bool	IsModified ()
	whether some of the fields are modified.It is up to the implementation class to provide this functionality if necessary. More...

virtual void	SetModified (bool bModified)
	set whether any field has been modified. More...

virtual bool	ValidateFields ()
	validate all fields and return true if validation passed. More...

virtual string	GetValidationMessage ()
	get the recent validation message due to the most recent call to ValidateFields()

virtual bool	ResetField (int nFieldID)
	Reset the field to its initial or default value. More...

virtual bool	InvokeEditor (int nFieldID, const std::string &sParameters)
	Invoke an (external) editor for a given field. More...

virtual bool	AddChildAttributeObject (IAttributeFields *pChild, int nRowIndex=-1, int nColumnIndex=0)
	add child object. More...

virtual void *	QueryObjectByName (const std::string &sObjectType)
	convert to object of a given type. More...

virtual void *	QueryObject (int nObjectType)
	convert to object of a given type. More...

virtual int	GetTime ()
	get the current local time in case it is animated in milli seconds frames. More...

virtual void	SetTime (int nTime)

virtual CDynamicAttributeField *	GetDynamicField (const std::string &sName)
	Get a dynamic field with a given name. More...

virtual CDynamicAttributeField *	GetDynamicField (int nIndex)
	Get a dynamic field with a given index. More...

virtual const char *	GetDynamicFieldNameByIndex (int nIndex)
	get field name by index

virtual int	GetDynamicFieldCount ()
	how many dynamic field this object currently have. More...

virtual int	SetDynamicField (const std::string &sName, const CVariable &value)
	set a dynamic field with a given name. More...

virtual int	AddDynamicField (const std::string &sName, ATTRIBUTE_FIELDTYPE dwType)
	add dynamic field and return field index

virtual void	RemoveAllDynamicFields ()
	remove all dynamic fields

virtual int	SaveDynamicFieldsToString (std::string &output)
	save only text dynamic fields to fieldname = value text strings. More...

virtual int	LoadDynamicFieldsFromString (const std::string &input)
	load only text dynamic fields from string More...

CAttributeClass *	GetAttributeClass ()
	get the main attribute class object. More...

void	PrintObject ()
	print the content of this object to a text file at temp/doc/[ClassName].txt. More...

Public Member Functions inherited from ParaEngine::IObject
virtual void	Clone (IObject *obj) const
	Clone the object's contains to a pointer. More...

virtual IObject *	Clone () const
	Clone the object's contains and return a pointer to the newly created object. More...

virtual bool	Equals (const IObject *obj) const
	Compare the object with another object. More...

virtual const IType *	GetType () const

virtual std::string	ToString () const

WeakPtr_type &	GetWeakReference ()
	get weak reference object. More...

virtual int	ProcessObjectEvent (const ObjectEvent &event)
	this function is only used to backward compatibility of ParaObject:AddEvent() function. More...

Public Member Functions inherited from ParaEngine::CRefCounted
void	addref () const
	add reference count of the object. More...

bool	delref () const
	decrease reference count of the object. More...

int	GetRefCount () const
	get the reference count

CRefCounted *	AddToAutoReleasePool ()
	addref and releases the ownership sometime soon automatically (usually at the end of the current frame). More...

Static Public Member Functions
static const string &	GetAssetServerUrl ()
	get the asset server url. More...

static void	SetAssetServerUrl (const char *pStr)
	set the asset server url. More...

Static Public Member Functions inherited from ParaEngine::IAttributeFields
static HRESULT	GetAttributeClassID_s (IAttributeFields cls, int p1)

static HRESULT	GetAttributeClassName_s (IAttributeFields cls, const char *p1)

static bool	OpenWithDefaultEditor (const char *sFilename, bool bWaitOnReturn=false)
	Open a given file with the default registered editor in the game engine. More...

Public Attributes
AssetKey	m_key
	this is the unique key object. More...

bool	m_bIsInitialized
	whether this entity is initialized;Entity is by default lazily initialized

bool	m_bIsValid
	whether this is a valid resource object. More...

Additional Inherited Members
Protected Member Functions inherited from ParaEngine::IAttributeFields
virtual CAttributeClass *	CreateAttributeClass ()
	initialize fields

virtual CDynamicAttributesSet *	GetDynamicAttributes (bool bCreateIfNotExist=false)

Protected Attributes inherited from ParaEngine::IObject
WeakPtr_type	m_weak_reference

Protected Attributes inherited from ParaEngine::CRefCounted
int	m_refcount

Detailed Description

Base class for managed asset entity in ParaEngine.

We allow each entity to have one name shortcut of string type, so that the entity can be easily referenced in script files through this name. we allow each asset to be associated with only one name, if multiple names are assigned to the the name entity, the latest assigned names will override previous names. This could be limitation. and will be removed in later version. However, in the game engine runtime, scene node stores asset entity as pointer to them. Entity is by default lazily initialized, unless they are called to be initialized.

Member Enumeration Documentation

§ AssetState

enum ParaEngine::AssetEntity::AssetState

the asset state.

an asset may be local or remote. if remote, it may take time for the asset to sync with the server. if an asset does not exist, we will try to fetch it via the central file server.

Enumerator
ASSET_STATE_NORMAL	asset is always created in normal state.
ASSET_STATE_LOCAL	the asset is local, which means that we have found a local disk version of the file. we always try to find in local disk first
ASSET_STATE_REMOTE	the asset is always remote. usually the asset key string begins with http://
ASSET_STATE_CACHE	asset is from the local cache. we have found the asset in disk cache, this means that we have sync it before. if file is not local, we will try to find in cache.
ASSET_STATE_SYNC_START	if file can not be found in local disk or in local cache, we will put it in sync start state, and make a url request to fetch from the server. During the fetching period, the asset is in this state, and we usually use a dummy placeholder for display.
ASSET_STATE_SYNC_SUCCEED	if a remote file is downloaded to cache and loaded. it will be put to sync succeed state. This is the same as cache state.
ASSET_STATE_SYNC_FAIL	if a remote file can not be downloaded. We will put it in sync fail state. This will prevent us from checking with the remote server again.
ASSET_STATE_FAILED_TO_LOAD	the file is not found or failed to load

Member Function Documentation

§ AutoSync()

bool AssetEntity::AutoSync	(	bool	bForceSync = `false`,
		bool	bLazyLoading = `true`
	)

virtual

call this function to automatically sync with the remote server according to current asset state

Parameters

bForceSync	if true, cache version is ignored. default to false.
bLazyLoading	default to true. if true, it will immediately refresh texture when data is available. otherwise, we will wait until the next round.

Returns: : whether a cache version is found. if not, a remote request is made.

HTTP texture file name is first hashed (one directional and uniquely) to an encoded file name string.

we will first check if the file exist, if so we will use it. if not, we will check if the file is being downloaded (in the downloading map), if so, ignore it. if not, we will begin a file URL request and add the request url to downloading map.

Once, download is completed, we will remove the url from the downloading map. if download is succeeded, we will reload the asset.

§ Cleanup()

virtual void ParaEngine::AssetEntity::Cleanup ( )

inlinevirtual

Clean up additional resources.

this function will only be called before the destructor function.

Reimplemented in ParaEngine::MeshEntity, ParaEngine::CadModel, ParaEngine::SequenceEntity, ParaEngine::ParaVertexBufferPool, ParaEngine::DatabaseEntity, ParaEngine::ParaXEntity, and ParaEngine::SpriteFontEntityOpenGL.

§ GarbageCollectMe()

void ParaEngine::AssetEntity::GarbageCollectMe ( )

inline

if its reference count is zero, unload this asset object.

any reference holder of this object can call this function to free its resources, if they believe that it will not be needed for quite some time in future.

§ GetAssetServerUrl()

const string & AssetEntity::GetAssetServerUrl ( )

static

get the asset server url.

In case we can not find an up-to-date asset, we will try to update from the server. if "", asset server will be disabled.

§ GetAttributeObject()

IAttributeFields * AssetEntity::GetAttributeObject ( )

virtual

get the attribute object of this asset.

Reimplemented in ParaEngine::MeshEntity, and ParaEngine::ParaXEntity.

§ GetBoundingBox()

virtual bool ParaEngine::AssetEntity::GetBoundingBox	(	Vector3 *	pMin,
		Vector3 *	pMax
	)

inlinevirtual

Get AABB bounding box of the asset object.

if the asset contains an OOB, it will return true.

Reimplemented in ParaEngine::MeshEntity, and ParaEngine::ParaXEntity.

§ GetKey()

AssetKey& ParaEngine::AssetEntity::GetKey ( )

inline

return the key object.

§ GetLocalFileName()

const string & AssetEntity::GetLocalFileName ( )

virtual

the actual local file name.

it could be the same as the asset key name or a dummy texture name, or a local cache texture name in all conditions, this is either empty or a local disk file name. This function is overridden for asset that support remote sync. For local asset, this is the same as the key string.

§ GetParamBlock()

virtual CParameterBlock* ParaEngine::AssetEntity::GetParamBlock ( bool bCreateIfNotExist = false )

inlinevirtual

get effect parameter block with this object.

Parameters

bCreateIfNotExist

Reimplemented in ParaEngine::CEffectFileDirectX, ParaEngine::CadModel, and ParaEngine::MeshEntity.

§ GetRemoteAssetURL()

string AssetEntity::GetRemoteAssetURL ( )

virtual

get the remote server url of this asset.

this is computed by concatenating asset server url and asset key

§ GetState()

AssetState ParaEngine::AssetEntity::GetState ( )

inline

return the asset state.

§ InstallFields()

int AssetEntity::InstallFields	(	CAttributeClass *	pClass,
		bool	bOverride
	)

virtual

this class should be implemented if one wants to add new attribute.

This function is always called internally.

Reimplemented from ParaEngine::IAttributeFields.

Reimplemented in ParaEngine::CBufferPicking, ParaEngine::ParaVertexBufferPool, and ParaEngine::ParaXEntity.

§ IsInitialized()

bool AssetEntity::IsInitialized ( )

whether initialized.

§ IsLoaded()

bool AssetEntity::IsLoaded ( )

virtual

most assets are loaded asynchronously.

This allows us to check if an asset is loaded. For example, we can LoadAsset() for a number of assets that need preloading. and then use a timer to check if they are initialized and remove from the uninitialized list.

Reimplemented in ParaEngine::TextureEntity, ParaEngine::CadModel, ParaEngine::MeshEntity, ParaEngine::TextureEntityDirectX, and ParaEngine::ParaXEntity.

§ IsLocked()

bool ParaEngine::AssetEntity::IsLocked ( )

inline

whether this is a locked resource resource.

A resource is locked because we are loading it from disk to memory or we are downloading it or we are composing it.

§ IsValid()

bool ParaEngine::AssetEntity::IsValid ( )

inline

whether this is a valid resource object.

An invalid object may result from a non-exist resource file.

§ LoadAsset()

void ParaEngine::AssetEntity::LoadAsset ( )

inline

load asset.

this function will only load the asset if it has not been initialized. since ParaEngine uses lazy loading, it is highly advised that user calls this function as often as possible to ensure that the asset is active; otherwise, they may get invalid resource pointers. Some derived class will call this function automatically, during resource pointer retrieval function. E.g. During each frame render routine, call this function if the asset is used.

§ Lock()

bool AssetEntity::Lock ( int nMethod = 0 )

virtual

Lock the object.

Once an object is locked, it can not be initialized, or reinitialized.

Parameters

nMethod how we are going to lock the asset. if 0(default), the asset should use place holder when used during the lock session.

Returns: true if the asset is not previously locked.

§ Refresh()

void AssetEntity::Refresh	(	const char *	sFilename = `NULL`,
		bool	bLazyLoad = `false`
	)

virtual

refresh the asset from local disk.

Call this function to refresh the asset if the asset file has been modified since last load. When we finished synchronizing with the remote server, we will also call this function to refresh from file.

Parameters

sFilename	the new local file name to use. if NULL, the GetAssetFileName method will be used. calling this function will always causes the asset to reload from local disk file.
bLazyLoad	default to false. if false, asset is only loaded when needed.

Reimplemented in ParaEngine::TextureEntity, ParaEngine::CadModel, ParaEngine::ParaXEntity, and ParaEngine::MeshEntity.

§ Release()

int AssetEntity::Release ( )

virtual

call this function to safely release this asset.

If there is no further reference to this object, it will actually delete itself (with "delete this"). So never keep a pointer to this class after you have released it. A macro like SAFE_RELEASE() is advised to be used.

Reimplemented from ParaEngine::CRefCounted.

§ SetAssetServerUrl()

void AssetEntity::SetAssetServerUrl ( const char * pStr )

static

set the asset server url.

In case we can not find an up-to-date asset, we will try to update from the server.

Parameters

pStr	such as "http://assets.paraengine.com/"; if this is "", asset server will be disabled.

§ SetState()

void ParaEngine::AssetEntity::SetState ( AssetState state )

inline

set the asset state.

This is usually called automatically when asset is synced with the server.

§ UnloadAsset()

void ParaEngine::AssetEntity::UnloadAsset ( )

inline

unload asset.

Normally this function is called automatically by resource manager. So never call this function manually, unless you really mean it.

Member Data Documentation

§ m_bIsValid

bool ParaEngine::AssetEntity::m_bIsValid

whether this is a valid resource object.

§ m_key

AssetKey ParaEngine::AssetEntity::m_key

this is the unique key object.

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

Client/trunk/ParaEngineClient/Core/AssetEntity.h
Client/trunk/ParaEngineClient/Core/AssetEntity.cpp

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

§ AssetState

Member Function Documentation

§ AutoSync()

§ Cleanup()

§ GarbageCollectMe()

§ GetAssetServerUrl()

§ GetAttributeObject()

§ GetBoundingBox()

§ GetKey()

§ GetLocalFileName()

§ GetParamBlock()

§ GetRemoteAssetURL()

§ GetState()

§ InstallFields()

§ IsInitialized()

§ IsLoaded()

§ IsLocked()

§ IsValid()

§ LoadAsset()

§ Lock()

§ Refresh()

§ Release()

§ SetAssetServerUrl()

§ SetState()

§ UnloadAsset()

Member Data Documentation

§ m_bIsValid

§ m_key