ParaAsset namespace contains a list of HAPI functions to manage resources(asset) used in game world composing, such as 3d models, textures, animations, sound, etc. More...

#include <ParaScriptingCommon.h>

Static Public Member Functions
static bool	OpenArchive (const char *strFileName)
	open the archive file(zip or pkg file) for further resource file searching. More...

static bool	GeneratePkgFile (const char srcZip, const char destPkg)
	Generate a pkg file which is equivalent to the specified zip file. More...

static bool	GeneratePkgFile_ (const char srcZip, const char destPkg, int nVersion)
	Generate a pkg file which is equivalent to the specified zip file. More...

static bool	OpenArchive2 (const char *strFileName, bool bUseRelativePath)
	open the archive file(zip or pkg file) for further resource file searching. More...

static bool	OpenArchiveEx (const char strFileName, const char sRootDir)
	add archive to manager More...

static void	CloseArchive (const string &path)
	close an archive. More...

static const char *	GetAssetServerUrl ()
	when an asset is not found, we will try to find it via this url. More...

static void	SetAssetServerUrl (const char *path)
	when an asset is not found, we will try to find it via this url. More...

static void	GarbageCollect ()
	Garbage Collect all assets according to reference count. More...

static void	Unload (const char *assettype)
	Unload an asset by its type name. More...

static void	UnloadAll ()
	unload all assets. More...

static void	UnloadDatabase ()
	unload all databases. More...

static void	Init ()
	initialize all objects that have not been created yet NOTE: always call this function at least once when finished creating a batch of assets assets created using any of the functions in this namespace can not be used until this function is called. More...

static ParaAssetObject	LoadEffectFile (const char strAssetName, const char strFilePath)
	Load effect file from a text or compiled HLSL file. More...

static ParaAssetObject	GetEffectFile (const char *strAssetName)
	load an effect file by its name. More...

static ParaAssetObject	LoadParaX (const char strAssetName, const char strFilePath)
	Load ParaX model asset, ParaX model file contains mesh, skeletal animation, etc. More...

static ParaAssetObject	LoadDatabase (const char strAssetName, const char strFilePath)
	Load Database asset. More...

static ParaAssetObject	LoadStaticMesh (const char strAssetName, const char strFilePath)
	Load a X file based static mesh object. More...

static ParaAssetObject	LoadPickingBuffer (const char *strAssetName)
	get or load picking buffer

static ParaAssetObject	LoadTexture (const char strAssetName, const char strFilePath, int nSurfaceType)

static ParaAssetObject	LoadRenderTarget (const char *strAssetName, int width, int height)

static ParaAssetObject	LoadSpriteFrame (const char *strAssetName, int nFrames, int nRow, int nCol)
	A sprite object must be created from Sprite frame and a texture. More...

static ParaAssetObject	LoadFont (const char strAssetName, const char FontName, int nFontSize)
	load a system font, such as arial, times new man, etc. More...

static ParaAssetObject	LoadImageFont (const char strAssetName, const char TextureName, int nSize, int nTxtColumns)
	load an image based font, not tested.

static ParaAssetObject	LoadSound (const char strAssetName, const char strFilePath, bool bInit)
	load a sound or music. More...

static void	AddFontName (const string &sLocalName, const string &sTypeFaceName)
	give an alias name to a given font name. More...

static int	GetBoneAnimProviderIDByName (const char *sName)
	Get provider id by name. More...

static const char *	GetBoneAnimProviderFileNameByID (int nAnimID)
	get the file name of a given animID. More...

static int	CreateBoneAnimProvider (int nAnimID, const char name, const char filename, bool bOverwrite)
	Create an animation provider from file. More...

static bool	DeleteBoneAnimProvider (int nAnimID)
	delete a provider by ID. More...

static int	PrintToFile (const char *strFileName, DWORD dwSelection)
	print all asset file to a given file. More...

static bool	Refresh (const char *filename)
	refresh asset if it is already loaded. More...

Detailed Description

ParaAsset namespace contains a list of HAPI functions to manage resources(asset) used in game world composing, such as 3d models, textures, animations, sound, etc.

Resources are used to create scene objects. assets of the same type must have different names. Assets must be initialized before they can be used, and this should be manually done in scripts by calling Init().

Member Function Documentation

§ AddFontName()

void ParaAsset::AddFontName	(	const string &	sLocalName,
		const string &	sTypeFaceName
	)

static

give an alias name to a given font name.

The most common use of this function is to replace the "System" font with a custom game font installed at "fonts/" folder.

Parameters

sLocalName	a local file name like "System", "Default"
sTypeFaceName	the real type face name to use when creating the font. please note that, the engine will search for the file "fonts/[sTypeFaceName].ttf", if this file exists, it will use that it, instead of the system installed font if any. Note: game custom font files under "fonts/" must be named by their true font name (i.e. type face name), otherwise they will not be loaded properly.

§ CloseArchive()

void ParaAsset::CloseArchive ( const string & path )

static

close an archive.

When done with an archive, one should always close it. Too many opened archives will compromise the IO performances.

§ CreateBoneAnimProvider()

int ParaAsset::CreateBoneAnimProvider	(	int	nAnimID,
		const char *	name,
		const char *	filename,
		bool	bOverwrite
	)

static

Create an animation provider from file.

Parameters

nAnimID	-1 if one wants it to be automatically assigned. otherwise one can manually specify one. Please note, if there is already a provider with the same ID, the old one is automatically released and replaced with the new one.
name	optional key. Allowing user to query by a user friendly name. This can be NULL.
filename	from which file the animation data is loaded. It can be a ParaX animation file or BVH file.
bOverwrite	whether to overwrite existing with the same nAnimID or name

Returns: : return the nAnimID, in case nAnim is set to -1. -1 is returned, if failed.

§ DeleteBoneAnimProvider()

bool ParaAsset::DeleteBoneAnimProvider ( int nAnimID )

static

delete a provider by ID.

Returns: : return true if succeed.

§ GarbageCollect()

void ParaAsset::GarbageCollect ( )

static

Garbage Collect all assets according to reference count.

If the reference count is not maintained well by the user, this function is not effective as UnloadAll().

See also: UnloadAll().

§ GeneratePkgFile()

bool ParaAsset::GeneratePkgFile	(	const char *	srcZip,
		const char *	destPkg
	)

static

Generate a pkg file which is equivalent to the specified zip file.

This function can only be called, when a zip file can be successfully loaded.

Parameters

srcZip	the zip file name from which to generate.
destPkg	: destination file. if nil, it just rename the srcZip

Returns: true if successful. It will overwrite existing file. Output file is at the save directory and filename but with pkg file extension.

§ GeneratePkgFile_()

bool ParaAsset::GeneratePkgFile_	(	const char *	srcZip,
		const char *	destPkg,
		int	nVersion
	)

static

Generate a pkg file which is equivalent to the specified zip file.

This function can only be called, when a zip file can be successfully loaded.

Parameters

srcZip	the zip file name from which to generate.
destPkg	: destination file. if nil, it just rename the srcZip
nVersion	the pkg file version number. version 2 is recommended.

Returns: true if successful. It will overwrite existing file. Output file is at the save directory and filename but with pkg file extension.

§ GetAssetServerUrl()

const char * ParaAsset::GetAssetServerUrl ( )

static

when an asset is not found, we will try to find it via this url.

e.g. if asset is "model/test.dds", and asset url is "http://asset.paraengine.com/", then we will fetch the asset via "http://asset.paraengine.com/model/test.dds" if the asset path is "", asset server will be disabled.

§ GetBoneAnimProviderFileNameByID()

const char * ParaAsset::GetBoneAnimProviderFileNameByID ( int nAnimID )

static

get the file name of a given animID.

It may return NULL, if animID is invalid or is an internal animation id.

§ GetBoneAnimProviderIDByName()

int ParaAsset::GetBoneAnimProviderIDByName ( const char * sName )

static

Get provider id by name.

Name is used when creating the provider instance. It is usually the same as the file path from which animation data is loaded. return -1 if not found

§ GetEffectFile()

ParaScripting::ParaAssetObject ParaAsset::GetEffectFile ( const char * strAssetName )

static

load an effect file by its name.

it will return an invalid effect if the effect is not found.

§ Init()

void ParaAsset::Init ( void )

static

initialize all objects that have not been created yet NOTE: always call this function at least once when finished creating a batch of assets assets created using any of the functions in this namespace can not be used until this function is called.

you can call "init" as many times as you like. Asset Manager guaranteed that if a object is valid, it will not be reinitialied

we needs to call RestoreDeviceObjects() to initialize device dependence object like the local mesh in the Mesh entity.

§ LoadDatabase()

ParaScripting::ParaAssetObject ParaAsset::LoadDatabase	(	const char *	strAssetName,
		const char *	strFilePath
	)

static

Load Database asset.

it must be sqlite database at the moment.

§ LoadEffectFile()

ParaScripting::ParaAssetObject ParaAsset::LoadEffectFile	(	const char *	strAssetName,
		const char *	strFilePath
	)

static

Load effect file from a text or compiled HLSL file.

It will return the old effect if effect is already loaded before.

§ LoadFont()

ParaAssetObject ParaAsset::LoadFont	(	const char *	strAssetName,
		const char *	FontName,
		int	nFontSize
	)

static

load a system font, such as arial, times new man, etc.

Parameters

nFontSize in pixels

§ LoadParaX()

ParaAssetObject ParaAsset::LoadParaX	(	const char *	strAssetName,
		const char *	strFilePath
	)

static

Load ParaX model asset, ParaX model file contains mesh, skeletal animation, etc.

Currently ParaX and mdx file format is supported, please refer to ParaX file document for creating ParaX file based multianimation asset.

§ LoadSound()

ParaAssetObject ParaAsset::LoadSound	(	const char *	strAssetName,
		const char *	strFilePath,
		bool	bInit
	)

static

load a sound or music.

The sound is not initialized until it is played for the first time.

Parameters

bInit whether to initialize the file

§ LoadSpriteFrame()

ParaAssetObject ParaAsset::LoadSpriteFrame	(	const char *	strAssetName,
		int	nFrames,
		int	nRow,
		int	nCol
	)

static

A sprite object must be created from Sprite frame and a texture.

This is to create the sprite frame, which tells the engine how the sprite is loaded in the texture.

Parameters

nFrames	how many frames the sprite has
nRow	number of rows in the texture
nCol	number of columns in the texture

§ LoadStaticMesh()

ParaAssetObject ParaAsset::LoadStaticMesh	(	const char *	strAssetName,
		const char *	strFilePath
	)

static

Load a X file based static mesh object.

If any side of the mesh's bounding box is longer than 50 meters(units) and that the triangle count is over 1500, Octree will be used to sort its triangle lists, otherwise no culling optimization will be used when rendering the mesh. Static mesh is suitable for rendering small repeated object such as stones, trees, or large object such as level mesh. another usage is that it can be used as physical data to be fed to the physics engine, in which case simple and convex geometry should be used as much as possible.

§ LoadTexture()

ParaAssetObject ParaAsset::LoadTexture	(	const char *	strAssetName,
		const char *	strFilePath,
		int	nSurfaceType
	)

static

Note: : we treat png file as DXT3 by default. if the texture filename ends with "_32bits.png", we will load with D3DFMT_A8R8G8B8 instead of DXT3. If one wants to ensure high resolution texture, use TGA format instead. All dds textures are loaded with full mipmapping default.

Parameters

strAssetName
strFilePath	if the file name ends with _a{0-9}{0-9}{0-9}.xxx, it will be regarded as a texture sequence. and the nSurfaceType will be ignored and forced to TextureSequence
nSurfaceType	enum _SurfaceType { / render target, call SetTextureInfo() to specify size. if SetTextureInfo() / is never called, the back buffer size is used. RenderTarget = 0, / normal managed texture, with all mip-mapping level created StaticTexture = 1, / a group of textures, such as xxx_a001.jpg, ..., xxx_a009.jpg TextureSequence = 2, / texture in memory SysMemoryTexture, / BLP textures BlpTexture, / detailed terrain texture TerrainHighResTexture, / cube texture for environment mapping, etc. CubeTexture, }

Returns

§ OpenArchive()

bool ParaAsset::OpenArchive ( const char * strFileName )

static

open the archive file(zip or pkg file) for further resource file searching.

If any file can not be located on the disk file system, it will go on searching for it in the archive file. files in the archive file will be relative to the ParaEngine SDK root directory.

Parameters

strFileName the package file path name

§ OpenArchive2()

bool ParaAsset::OpenArchive2	(	const char *	strFileName,
		bool	bUseRelativePath
	)

static

open the archive file(zip or pkg file) for further resource file searching.

If any file can not be located on the disk file system, it will go on searching for it in the archive file.

Parameters

strFileName	the package file path name
bUseRelativePath	if this is true, files in the archive file will be relative to the parent directory of archive path.

§ OpenArchiveEx()

bool ParaAsset::OpenArchiveEx	(	const char *	strFileName,
		const char *	sRootDir
	)

static

add archive to manager

Parameters

strFileName	path of the zip or pkg file.
sRootDir	files in the archive will be regarded as relative to this this root directory. If this is "", there is no root directory set. such as "model/", "script/", characters after the last slash is always stripped off.

§ PrintToFile()

int ParaAsset::PrintToFile	(	const char *	strFileName,
		DWORD	dwSelection
	)

static

print all asset file to a given file.

Each asset is on a single line, in the following format: [AssetFileName]

Parameters

strFileName	to which file the result is written to. if NULL or "", it is "temp/assets.txt"
dwSelection	bitwise on which assets to export, 1 is for texture, 2 is for Mesh, 4 is for ParaXEntity. Default to 0xffffffff

Returns: : the number of results printed are returned.

§ Refresh()

bool ParaAsset::Refresh ( const char * filename )

static

refresh asset if it is already loaded.

it will search for all refreshable asset type, such as textures and mesh, etc. if found, it will call the Refresh() method on the asset entity and return true, or return false.

§ SetAssetServerUrl()

void ParaAsset::SetAssetServerUrl ( const char * path )

static

when an asset is not found, we will try to find it via this url.

e.g. if asset is "model/test.dds", and asset url is "http://asset.paraengine.com/", then we will fetch the asset via "http://asset.paraengine.com/model/test.dds" if the asset path is "", asset server will be disabled.

Parameters

path:if the asset path is "", asset server will be disabled.

§ Unload()

void ParaAsset::Unload ( const char * assettype )

static

Unload an asset by its type name.

once an unloaded asset is used again, its device resource will be reinitialized.

Parameters

strAssetName

value and meaning are listed below

"*": Unload all assets.

See also

UnloadAll()

"ParaX": Unload all ParaX models
"StaticMesh": Unload all StaticMesh models
"Texture": Unload all Texture
"Sound": Unload all Sound
"Font": Unload all Font TODO: currently only "*" is supported.

§ UnloadAll()

void ParaAsset::UnloadAll ( )

static

unload all assets.

once an unloaded asset is used again, its device resource will be reinitialized.

See also: Unload()

§ UnloadDatabase()

void ParaAsset::UnloadDatabase ( )

static

unload all databases.

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

Client/trunk/ParaEngineClient/ParaScriptBindings/ParaScriptingCommon.h
Client/trunk/ParaEngineClient/ParaScriptBindings/ParaScriptingCommon.cpp

Static Public Member Functions

Detailed Description

Member Function Documentation

§ AddFontName()

§ CloseArchive()

§ CreateBoneAnimProvider()

§ DeleteBoneAnimProvider()

§ GarbageCollect()

§ GeneratePkgFile()

§ GeneratePkgFile_()

§ GetAssetServerUrl()

§ GetBoneAnimProviderFileNameByID()

§ GetBoneAnimProviderIDByName()

§ GetEffectFile()

§ Init()

§ LoadDatabase()

§ LoadEffectFile()

§ LoadFont()

§ LoadParaX()

§ LoadSound()

§ LoadSpriteFrame()

§ LoadStaticMesh()

§ LoadTexture()

§ OpenArchive()

§ OpenArchive2()

§ OpenArchiveEx()

§ PrintToFile()

§ Refresh()

§ SetAssetServerUrl()

§ Unload()

§ UnloadAll()

§ UnloadDatabase()