SoundDataCache Class Reference

SoundDataCache is the data-keeper of SoundSystemManager. More...

#include <data.h>

Public Member Functions
bool	GetSoundData (const char *name, csRef< iSndSysData > &sndData)
	Fetches a sound data from the cache and loads it from the VFS if necessary. More...
bool	Initialize (iObjectRegistry *objectReg)
	Initializes CS iSndSysLoader and look for the VFS. More...
bool	LoadSoundLib (const char *fileName, iObjectRegistry *objectReg)
	Reads information contained in the given sound library XML file. More...
	SoundDataCache ()
	Constructor. More...
void	UnloadSoundFile (const char *name)
	Forces the cache to unload and delete the data of the given sound from the memory, no matter if it's still in use or not. More...
void	UnloadSoundLib ()
	Unloads everything LoadSoundLib created and clean the cache. More...
void	Update ()
	Checks the reference counting to sounds to determine if they are still in use or not. More...
	~SoundDataCache ()
	Deconstructor. More...

Detailed Description

SoundDataCache is the data-keeper of SoundSystemManager.

It loads and unloads all sound files and provides a simple caching mechanism.

Birth: After the object creation, it should be called the method Initialize in order to aquire references to the virtual file system and the CS sound loader. If a sound library is present it should be loaded with LoadSoundLib.

Usage: Sounds can be retrieved with GetSoundData. The provided iSndSysData should always be used with a csRef since the reference counting is checked to determine if the sound is still in use or not. Referencing the sound data with a normal pointer could cause the application to crash by ending up with pointing to an object that the cache has destroyed.

Cache: The data is cached and unloaded when it is not referenced anymore and the time given in the configuration option "PlaneShift.Sound.DataCacheTime" has elapsed. One can force the cache to unload a sound with UnloadSoundFile if it is known that the sound won't be used again.

Death: It is not necessary to call UnloadSoundLib. The destructor takes care of it too.

Definition at line 102 of file data.h.

Constructor & Destructor Documentation

SoundDataCache::SoundDataCache

(

)

Constructor.

Initialization is done via Initialize because it's not guaranteed that it's successful.

SoundDataCache::~SoundDataCache

(

)

Deconstructor.

Unloads everything and destroys all SoundFile objects.

Member Function Documentation

bool SoundDataCache::GetSoundData	(	const char *	name,
		csRef< iSndSysData > &	sndData
	)

Fetches a sound data from the cache and loads it from the VFS if necessary.

If the sound is not in the sound library then it considers the parameter "name" as a path in the VFS and it tries to load the data from there.

Attention

always use the provided iSndSysData with a csRef since the reference counting is used to determine if the sound is still in use or not. Referencing the sound data with a normal pointer could cause the application to crash by ending up with pointing to an object that the cache has destroyed.

Parameters

name	the name of the sound to fetch (or its path if it is not in the library.
sndData	object that will contain the sound data at the end.

Returns

true on success, false if the sound data couldn't be retrieved.

bool SoundDataCache::Initialize

(

iObjectRegistry *

objectReg

)

Initializes CS iSndSysLoader and look for the VFS.

Parameters

objectReg

iObjectRegistry to get references to iVFS and iSndSysLoader.

Returns

true on success, false otherwise.

bool SoundDataCache::LoadSoundLib	(	const char *	fileName,
		iObjectRegistry *	objectReg
	)

Reads information contained in the given sound library XML file.

Parameters

fileName	the path to the XML sound library file.
objectReg	ps iObjectRegistry because we need iDocumentSystem.

Returns

true on success, false otherwise.

void SoundDataCache::UnloadSoundFile

(

const char *

name

)

Forces the cache to unload and delete the data of the given sound from the memory, no matter if it's still in use or not.

Parameters

namethe

name of the sound to unload.

void SoundDataCache::UnloadSoundLib

(

)

Unloads everything LoadSoundLib created and clean the cache.

void SoundDataCache::Update

(

)

Checks the reference counting to sounds to determine if they are still in use or not.

Unloads the sound data that has not been used for the time specified in the configuration option "PlaneShift.Sound.DataCacheTime".

---

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

• plugins/common/soundmanager/data.h