Manages the entire library's resources, including keys, creatables, age info and page info. More...

#include <plResManager.h>

Public Member Functions
	plResManager (PlasmaVer pv=PlasmaVer::pvUnknown)
virtual	~plResManager ()
void	setVer (PlasmaVer pv, bool force=false)
PlasmaVer	getVer ()
plKey	readKey (hsStream *S)
plKey	readKeyNotify (hsStream *S, const plKeyData::AfterLoadCallback &callback)
plKey	readUoid (hsStream *S)
void	writeKey (hsStream *S, plKey key)
void	writeKey (hsStream S, hsKeyedObject ko)
void	writeUoid (hsStream *S, plKey key)
void	writeUoid (hsStream S, hsKeyedObject ko)
plKey	prcParseKey (const pfPrcTag *tag)
plKey	prcParseKeyNotify (const pfPrcTag *tag, const plKeyData::AfterLoadCallback &callback)
class hsKeyedObject *	getObject (plKey key)
unsigned int	countKeys (const plLocation &loc)
plPageInfo *	ReadPage (const char *filename, bool stub=false)
plPageInfo *	ReadPagePrc (const pfPrcTag *root)
void	WritePage (const char filename, plPageInfo page)
void	WritePagePrc (pfPrcHelper prc, plPageInfo page)
plPageInfo *	FindPage (const plLocation &loc)
void	UnloadPage (const plLocation &loc)
plAgeInfo *	ReadAge (const char *filename, bool readPages)
plAgeInfo *	ReadAgePrc (const pfPrcTag *root)
void	WriteAge (const char filename, plAgeInfo age)
void	WriteAgePrc (pfPrcHelper prc, plAgeInfo age)
plAgeInfo *	FindAge (const plString &name)
void	UnloadAge (const plString &name)
class plCreatable *	ReadCreatable (hsStream *S, bool canStub=false, int stubLen=0)
void	WriteCreatable (hsStream S, class plCreatable pCre)
class plCreatable *	prcParseCreatable (const pfPrcTag *tag)
class plSceneNode *	getSceneNode (const plLocation &loc)
std::vector< plLocation >	getLocations ()
std::vector< short >	getTypes (const plLocation &loc, bool checkKeys=false)
std::vector< plKey >	getKeys (const plLocation &loc, short type, bool checkKeys=false)
std::vector< plKey >	getKeys (short type, bool checkKeys=false)
plKey	AddKey (plKey key)
void	MoveKey (plKey key, const plLocation &to)
void	AddObject (const plLocation &loc, hsKeyedObject *obj)
void	AddPage (plPageInfo *page)
void	AddAge (plAgeInfo *age)
void	DelObject (plKey obj)
void	DelPage (const plLocation &loc)
void	DelAge (const plString &name)
void	ChangeLocation (plLocation from, plLocation to)
ProgressCallback	SetProgressFunc (ProgressCallback newFunc)
PageUnloadCallback	SetPageUnloadFunc (PageUnloadCallback newFunc)
void	lock ()
void	unlock ()

Protected Attributes
PlasmaVer	fPlasmaVer
plKeyCollector	keys
std::vector< plPageInfo * >	pages
std::vector< plAgeInfo * >	ages
ProgressCallback	progressFunc
PageUnloadCallback	pageUnloadFunc
unsigned int	totalKeys
unsigned int	readKeys
bool	mustStub

Detailed Description

Manages the entire library's resources, including keys, creatables, age info and page info.

You will need to create at least one ResManager if you plan to use any creatables or keys in your application. You can also use it to handle PRC data and store Age or PRP information. Most of the top-level file-based operations you'll do will start from here.

Constructor & Destructor Documentation

plResManager::plResManager ( PlasmaVer pv = PlasmaVer::pvUnknown )

Constructs a ResManager.

If the version is left unspecified, it will be determined automatically when you call either ReadPage() or ReadAge()

See Also: setVer(), getVer()

virtual plResManager::~plResManager ( )

virtual

Destroy the ResManager.

This will delete all keys, Creatables, Ages and Pages that are registered with the ResManager.

Member Function Documentation

void plResManager::AddAge ( plAgeInfo * age )

Manually register a plAgeInfo with the ResManager.

Note: You should only use this for NEW ages created by the application, never for ages read from files or PRC tags.

plKey plResManager::AddKey ( plKey key )

Manually register a plKey with the ResManager.

Note: You should do this if you are creating a NEW hsKeyedObject (after initializing the key with hsKeyedObject::init() ). You should NOT use this for keys or KeyedObjects that are loaded into the ResManager through other sources, like parsing from a file or PRC tag.

Unlike AddObject(), this function WILL check to see if the key is already registered, and returns a copy of the registered key instead of the new one, if it is found in the ResManager.

Returns: a copy of the key stored in the ResManager

See Also: hsKeyedObject::init(), MoveKey(), AddObject()

void plResManager::AddObject	(	const plLocation &	loc,
		hsKeyedObject *	obj
	)

Manually register an hsKeyedObject with the ResManager.

Like AddKey, this registers the object and its key into the ResManager, but this function also changes the location of the associated plKey to match the location we're adding it to. However, unlike AddKey(), this function performs no check to see whether the key is already loaded. You should only use this function for NEW hsKeyedObjects and never for ones that are already loaded from a file or PRC tag.

See Also: AddKey(), MoveKey(), hsKeyedObject::init()

void plResManager::AddPage ( plPageInfo * page )

Manually register a plPageInfo with the ResManager.

Note: You should only use this for NEW pages created by the application, never for pages read from files or PRC tags.

void plResManager::ChangeLocation	(	plLocation	from,
		plLocation	to
	)

This function can completely change a location identifier for all loaded data. Any plKeys or plPageInfos that are registered whose location matches from will be updated to the location to, and when the files are written back to disk, they will be stored with the new location info.

unsigned int plResManager::countKeys ( const plLocation & loc )

Returns the total number of keys registered for the specified plLocation

void plResManager::DelAge ( const plString & name )

Removes the age specified by filename from the ResManager, and frees any memory associated with it. Unlike UnloadAge(), this function does NOT remove any pages referenced by the age, nor any objects referenced by those pages.

void plResManager::DelObject ( plKey obj )

Removes the plKey and its associated hsKeyedObject from the ResManager, and frees the memory associated with both. This will allow you to delete an object from a page.

void plResManager::DelPage ( const plLocation & loc )

Removes the page specified by loc from the ResManager, and frees any memory associated with it. Unlike UnloadPage(), this function does NOT remove any keys or objects referenced by the page.

See Also: UnloadPage()

plAgeInfo* plResManager::FindAge ( const plString & name )

Finds a registered age info structure by name.

Parameters

name	The filename of the age to be found

Returns: the age info structure, or NULL if it can't be found

See Also: FindPage()

plPageInfo* plResManager::FindPage ( const plLocation & loc )

Find a registered page whose location is specified by loc.

Returns: the plPageInfo describing the page, or NULL if it is not found.

See Also: FindAge()

std::vector<plKey> plResManager::getKeys	(	const plLocation &	loc,
		short	type,
		bool	checkKeys = `false`
	)

Return an array of all the plKeys of the specified Creatable Class for the specified location.

Parameters

checkKeys if set to true, the ResManager will clean out any invalid keys while building the type list.

std::vector<plKey> plResManager::getKeys	(	short	type,
		bool	checkKeys = `false`
	)

Return an array of all the plKeys of the specified Creatable Class for all locations.

Parameters

checkKeys if set to true, the ResManager will clean out any invalid keys while building the type list.

std::vector<plLocation> plResManager::getLocations ( )

Return an array of all page locations registered by the ResManager. Note that this might include locations that are not currently loaded, since it's possible to load keys for external pages.

class hsKeyedObject* plResManager::getObject ( plKey key )

Find and return the object referenced by key, or NULL if the key either doesn't exist or isn't loaded. This uses the ResManager's internal list of keys, unlike plKeyData::getObj() which just returns the key's internal object pointer.

See Also: plKeyData::getObj()

class plSceneNode* plResManager::getSceneNode ( const plLocation & loc )

Finds the plSceneNode associated with the page at loc. If there is more than one Scene Node in the page, returns only the first one.

Returns: a plSceneNode for the page, or NULL if one wasn't found

std::vector<short> plResManager::getTypes	(	const plLocation &	loc,
		bool	checkKeys = `false`
	)

Return an array of all of the Creatable Class types that have one or more keys loaded into the ResManager for this location.

Parameters

checkKeys if set to true, the ResManager will clean out any invalid keys while building the type list.

PlasmaVer plResManager::getVer ( )

Return the version of data files this ResManager expects to deal with. Used for reading or writing data to files only.

See Also: setVer()

void plResManager::lock ( )

Lock access to the ResManager in multithreaded apps

void plResManager::MoveKey	(	plKey	key,
		const plLocation &	to
	)

Change a plKey's location to the one specified. This is probably a good idea to call after importing a key or KeyedObject from a file or PRC data, to ensure the key and object get put into the correct place. Since plKeys share a single datum, any objects in any pages that hold reference to this key will also use the updated location.

See Also: AddKey(), AddObject()

class plCreatable* plResManager::prcParseCreatable ( const pfPrcTag * tag )

Parse a plCreatable contained in the PRC tag.

Returns: a parsed plCreatable, or NULL if parsing failed.

See Also: ReadCreatable(), WriteCreatable(), plCreatable::prcParse(), plCreatable::prcWrite()

plKey plResManager::prcParseKey ( const pfPrcTag * tag )

Parse the PRC tag as a plKey and register it with the ResManager

plKey plResManager::prcParseKeyNotify	(	const pfPrcTag *	tag,
		const plKeyData::AfterLoadCallback &	callback
	)

Parse the PRC tag as a plKey, register it with the ResManager and add callback

Parameters

callback Callback to be called after object referenced by this key is parsed

plAgeInfo* plResManager::ReadAge	(	const char *	filename,
		bool	readPages
	)

Read an AGE file and register it with the ResManager.

Parameters

readPages Specifies whether to also load and register all of the pages referenced by the AGE file.

Returns: a pointer to the plAgeInfo describing the AGE file.

See Also: ReadAgePrc(), ReadPage(), ReadPagePrc()

plAgeInfo* plResManager::ReadAgePrc ( const pfPrcTag * root )

Read age file data from a PRC block and register it with the ResManager.

Returns: a pointer to the plAgeInfo describing the age.

See Also: ReadAge(), ReadPage(), ReadPagePrc()

class plCreatable* plResManager::ReadCreatable	(	hsStream *	S,
		bool	canStub = `false`,
		int	stubLen = `0`
	)

Read a plCreatable from the stream. This should be converted to a compatible subclass in order to make use of its members.

Parameters

canStub	Specifies whether an unsupported ClassIndex can be made into a plCreatableStub without disrupting the stream.
stubLen	Specifies the size of the plCreatable for stubs This only makes sense if canStub is true, and it MUST be specified if canStub is true.

Returns: The plCreatable object.

See Also: WriteCreatable(), prcParseCreatable()

plKey plResManager::readKey ( hsStream * S )

Read a plKey and register it with the ResManager

plKey plResManager::readKeyNotify	(	hsStream *	S,
		const plKeyData::AfterLoadCallback &	callback
	)

Read a plKey, register it with the ResManager and add callback

Parameters

callback Callback to be called after object referenced by this key is loaded

plPageInfo* plResManager::ReadPage	(	const char *	filename,
		bool	stub = `false`
	)

Read a Page (PRP File) and register it with the ResManager.

Returns: a pointer to the plPageInfo describing the page.

See Also: ReadPageRaw(), ReadPagePrc(), ReadAge(), ReadAgePrc()

plPageInfo* plResManager::ReadPagePrc ( const pfPrcTag * root )

Parse a page from a PRC data source, and register it with the ResManager.

Returns: a pointer to the plPageInfo describing the page.

See Also: ReadPage(), ReadPageRaw(), ReadAge(), ReadAgePrc()

plKey plResManager::readUoid ( hsStream * S )

Read a raw plKey from a stream (no "exists" bool for Uru streams)

PageUnloadCallback plResManager::SetPageUnloadFunc ( PageUnloadCallback newFunc )

ProgressCallback plResManager::SetProgressFunc ( ProgressCallback newFunc )

This function is currently unsupported.

void plResManager::setVer	(	PlasmaVer	pv,
		bool	force = `false`
	)

Set the version of data files this ResManager expects to deal with. This is used when reading or writing data to files, but doesn't have any affect on data already loaded.

Parameters

force Change the version even if one is already set

See Also: getVer()

void plResManager::UnloadAge ( const plString & name )

Unload an age info structure by name. Frees all memory associated with the age, and also unloads all pages that are described by this age info.

See Also: UnloadPage(), DelAge()

void plResManager::UnloadPage ( const plLocation & loc )

Unloads and frees memory for all registered data for the page whose location is specified by loc.

See Also: UnloadAge(), DelPage()

void plResManager::unlock ( )

Unlock access to the ResManager in multithreaded apps

void plResManager::WriteAge	(	const char *	filename,
		plAgeInfo *	age
	)

Create/overwrite an age file for the specified age info structure

See Also: WriteAgePrc(), WritePage(), WritePagePrc()

void plResManager::WriteAgePrc	(	pfPrcHelper *	prc,
		plAgeInfo *	age
	)

Write a PRC chunk for the specified age info structure

See Also: WriteAge(), WritePage, WritePagePrc()

void plResManager::WriteCreatable	(	hsStream *	S,
		class plCreatable *	pCre
	)

Writes a plCreatable to the stream.

See Also: ReadCreatable(), prcParseCreatable()

void plResManager::writeKey	(	hsStream *	S,
		plKey	key
	)

Write a plKey to a stream

void plResManager::writeKey	(	hsStream *	S,
		hsKeyedObject *	ko
	)

Write the plKey that describes the specified hsKeyedObject to a stream

void plResManager::WritePage	(	const char *	filename,
		plPageInfo *	page
	)

Write the specified page to a PRP file

See Also: WritePagePrc(), WriteAge(), WriteAgePrc()

void plResManager::WritePagePrc	(	pfPrcHelper *	prc,
		plPageInfo *	page
	)

Write the specified page to a PRC document

See Also: WritePage(), WriteAge(), WriteAgePrc()

void plResManager::writeUoid	(	hsStream *	S,
		plKey	key
	)

Write a raw plKey to a stream (no "exists" bool for Uru streams)

void plResManager::writeUoid	(	hsStream *	S,
		hsKeyedObject *	ko
	)

Write the raw plKey that describes the hsKeyedObject to a stream

Member Data Documentation

std::vector<plAgeInfo*> plResManager::ages

protected

PlasmaVer plResManager::fPlasmaVer

protected

plKeyCollector plResManager::keys

protected

bool plResManager::mustStub

protected

std::vector<plPageInfo*> plResManager::pages

protected

PageUnloadCallback plResManager::pageUnloadFunc

protected

ProgressCallback plResManager::progressFunc

protected

unsigned int plResManager::readKeys

protected

unsigned int plResManager::totalKeys

protected

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

core/ResManager/plResManager.h

Public Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation