Yagl::SfxDevice Class Reference

#include <sfxdevice.h>

Inheritance diagram for Yagl::SfxDevice:

List of all members.

Public Member Functions
bool	initialize ()
	initializes the sfxdevice
void	deinitialize ()
	deinitializes the sfxdevice
void	getListenerPosition (float *x, float *y, float *z)
	returns the listeners position
void	setListenerPosition (float x, float y, float z)
	sets the listeners position
void	getListenerVelocity (float *x, float *y, float *z)
	returns the listeners velocity
void	setListenerVelocity (float x, float y, float z)
	sets the listeners velocity
void	getListenerOrientation (float *x_at, float *y_at, float *z_at, float *x_up, float *y_up, float *z_up)
	returns the listeners orientation
void	setListenerOrientation (float x_at, float y_at, float z_at, float x_up, float y_up, float z_up)
	sets the listeners orientation
bool	createSoundBufferFromFile (const char *filename, unsigned int *buffer_handle)
	creates a soundbuffer from a file
bool	doesSoundBufferExist (unsigned int buffer_handle)
	checks wheter a soundbuffer with the given handle exists
void	destroySoundBuffer (unsigned int buffer_handle)
	destroys the given soundbuffer
void	destroyAllSoundBuffers ()
	destroys all soundbuffers currently in use
bool	playSoundBuffer (unsigned int buffer_handle, bool relative=true, float *position=0, float *velocity=0, float pitch=1.0f, float gain=1.0f, float roll_off=0.0)
	plays the given soundbuffer with the specified attributes
SoundSource *	createSoundSource (unsigned int buffer_handle)
	creates a new soundsource and associates the given buffer to it
void	destroySoundSource (SoundSource *source)
	this will destroy a soundsource
void	destroyAllSoundSources ()
	destroys all soundsources
SoundStream *	createSoundStream (const char *filename)
	creates a soundstream from a file
void	destroySoundStream (SoundStream *stream)
	destroys the given soundstream
void	destroyAllSoundStreams ()
	destroys all soundstreams
Static Public Member Functions
static SfxDevice &	getInstance ()
	returns a reference to the SfxDevice singleton
Protected Member Functions
	SfxDevice ()
	Constructor.
	SfxDevice (const SfxDevice &device)
	copy constructor
virtual	~SfxDevice ()
	Destructor.
bool	initializeDevice ()
	internal, initializes the audiodevice
void	deinitializeDevice ()
	internal, deinitializes the audiodevice
bool	initializeChannels ()
	internal, initializes and enumerates all hardware audiochannels
void	deinitializeChannels ()
	internal, stops all playing channels and releases them
bool	acquireChannel (unsigned int &channel)
	internal, tries to acquire an unused audiochannel
void	releaseChannel (unsigned int channel)
	internal, releases a channel and stops it if it was playing
void	destroyAllTemporarySources ()
	internal, destroys all temporary soundsources
void	updateTemporarySources ()
	internal, updates all temporary soundsources
void *	run ()
	internal, updates all temporary soundsources and soundstreams
void	updateSources ()
	internal, updates all soundsources
void	updateStreams ()
	internal, updates all soundstreams
Protected Attributes
bool	initialized_
	is the device initialized?
Channel *	channels_
	list of all hardware audio channels
unsigned int	num_channels_
	number of channels
Yagl::Mutex	channels_lock_
	mutex to lock the channels
float	listener_position_ [3]
	listener position
float	listener_velocity_ [3]
	listener velocity ( for doppler effect )
float	listener_orientation_ [6]
	listener orientation, first 3 floats are direction vector, last 3 floats up vector
std::list< unsigned int >	buffers_
	list of all buffers currently in use
Yagl::Mutex	buffers_lock_
	mutex to lock the buffers
std::list< SoundSource * >	sources_
	list of all soundsources currently in use
Yagl::Mutex	sources_lock_
	mutex to lock the sources
std::list< SoundSource * >	temporary_sources_
	list of all temporary soundsources currently in use
Yagl::Mutex	temporary_sources_lock_
	mutex to lock temporary soundsources
std::list< SoundStream * >	streams_
	list of all streams currently in use
Yagl::Mutex	streams_lock_
	mutex to lock all soundsources
Static Protected Attributes
static Yagl::SfxDevice	instance_
	singleton instance of the SfxDevice
Friends
class	Yagl::SoundSource
class	Yagl::SoundStream

---

Detailed Description

class SfxDevice

This class represents the hardware audio device. it offers methods to create soundbuffers that hold pcm audiodata, create soundsources that can use soundbuffers as audiodata sources and create soundstreams that use files as audiodata sources. the sfxdevice is a singleton due to the nature of an audiodevice. The SfxDevice Singleton keeps track of all created SoundBuffers, SoundSources and SoundStreams and guarantees that given proper program termination everything will be cleaned up and will not leave any memory leaks or wasted resources. the SfxDevice also has a feature called the Listener which represents the listener in 3D space. this listener has a position, a velocity ( to calculate the doppler effect ) and an orientation ( direction vector and up vector to form a coordinate system similar to a camera in 3d gfx applications ). you can manipulate the listeners attributes via a couple of methods provided by the SfxDevice. OpenAl has a Source ( == channel ) system that is limited to the resources the hardware offers. a source is really a channel of your audio device, the number of channels is limited and variies per hardware. the lower limit seems to be 16 channels however this is just an empirical value so make sure you use the getNumFreeChannels and getNumChannels methods of the SfxDevice. SoundSources and SoundStreams need at one channel to be able to play the associated SoundBuffer/File. The SfxDevice keeps track of channel usage and tries to free any unused channels as soon as possible. SoundSources acquire a channel within their play method. if the soundsource is done playing the SoundBuffer associated with it the used channel is released and free to be used by other SoundSources and SoundStreams. You don't have to worry about that as this is all done in the background for you. if there's no free channel when you call the play method of a SoundSource the sound just doesn't get played. SoundStreams acquire a channel when you set the file to be streamed from with the setStreamedFile method ( also used in createSoundStream ). a channel will be permanently assigned to a soundstream until the soundstream gets destroyed. it is therefor good practice to create 2 - 3 SoundStreams that you can use for playing background music and long audiodata in general. SoundBuffers are what you should use for small samples like explosions and the like. the number of possible SoundBuffers is not limited you can create as many as you want as long as they fit into your ram. On creation of a soundbuffer via the createSoundBufferFromFile method you'll receive a handle to that buffer on success that you can use with SoundSources. you can assign one SoundBuffer to multiple sources. There's also a decoder system working in the background. currently there's two decoders available, the ogg decoder and the sample decoder ( for wav, snd etc. files ). you don't have to care about the format of your audiodata as long as a proper decoder is registered.

---

Constructor & Destructor Documentation

Yagl::SfxDevice::SfxDevice (   )  [protected]

Constructor. sets up internal members like listener attributes etc. hidden due to SfxDevice being a singleton, it will also register the standard decoders( ogg, wav )

virtual Yagl::SfxDevice::~SfxDevice (   )  [protected, virtual]

Destructor. this will destroy all undestroyed SoundBuffers, SoundSources temporary SoundSources and SoundStreams. it will also release all the acquired hardware

---

Member Function Documentation

bool Yagl::SfxDevice::acquireChannel (  unsigned int &  channel  )  [protected]

internal, tries to acquire an unused audiochannel this will go through the list of audiochannels and try to find a free audiochannel. Parameters: channel  variable where the handle to the channel gets stored to Returns: true on success ( channel is valid ), false on failure

bool Yagl::SfxDevice::createSoundBufferFromFile (  const char *  filename, unsigned int *  buffer_handle )

creates a soundbuffer from a file this will try to create a soundbuffer from the specified file. the method will try to find a proper decoder and then read in and convert the file to pcm audiodata. soundbuffers are intended to hold only small samples like explosion noise or gunshots. you can however load a fullblown soundfile but this is not recommended. for example ogg has a 1:10 compression ratio that would mean a 4mb ogg would be 40mb in ram. it would also take a bit long to decode to ram due the the nature of this method. the method retunrs a handle to the created soundbuffer which can then be used by multiple soundsources Parameters: filename  the file the soundbuffer should be created from buffer_handle  adress of a variable the handle gets stored to on success Returns: true on success ( buffer_handle valid ), false on failure

SoundSource* Yagl::SfxDevice::createSoundSource (  unsigned int  buffer_handle  )

creates a new soundsource and associates the given buffer to it this will create a new soundsource and associate the given buffer to it. a call to play of that soundsource will then try to play the associated buffer at the with the given attributes of the soundsource. you can create multiple soundsources and associate them to the same buffer. Parameters: buffer_handle  the buffer to be associated with the soundsource Returns: a pointer to a SoundSource on success, 0 on failure

SoundStream* Yagl::SfxDevice::createSoundStream (  const char *  filename  )

creates a soundstream from a file this creates a soundstream from the given file. the method will acquire a soundchannel for the stream and assign it to the stream permanently until the stream is destroyed. it will also try to find a decoder it can decode the given file. Parameters: filename  file to be used by the stream Returns: a pointer to a SoundStream on success, 0 on failure

void Yagl::SfxDevice::deinitialize (   )

deinitializes the sfxdevice this will destroy all soundbuffers, temporary soundsources, soundsources and soundstreams currently in use and release the audiohardware ( device and channels )

void Yagl::SfxDevice::deinitializeChannels (   )  [protected]

internal, stops all playing channels and releases them this stops all audiochannels that are playing and releases them

void Yagl::SfxDevice::deinitializeDevice (   )  [protected]

internal, deinitializes the audiodevice this deinitializes the audiodevice

void Yagl::SfxDevice::destroyAllSoundBuffers (   )

destroys all soundbuffers currently in use this will destroy all soundbuffers currently in use

void Yagl::SfxDevice::destroyAllSoundSources (   )

destroys all soundsources this will destroy all soundsources created by createSoundSource. it will release all the channels used by the soundsources too.

void Yagl::SfxDevice::destroyAllSoundStreams (   )

destroys all soundstreams this will destroy all soundstreams currently in use. all the channels associated with the streams will be released.

void Yagl::SfxDevice::destroyAllTemporarySources (   )  [protected]

internal, destroys all temporary soundsources this destroys all temporary soundsources that were created with SfxDevice::playSoundBuffer(). it will also free the channels associated with the sources.

void Yagl::SfxDevice::destroySoundBuffer (  unsigned int  buffer_handle  )

destroys the given soundbuffer this method will destroy the given soundbuffer if it exists. it will therefor free the allocated memory of that soundbuffer. be carefull with this method if there's a soundsource that uses this soundbuffer it might cause a crash FIXME: keep track of what soundsources use what buffer and stop the soundsource on deletion of a soundbuffer Parameters: buffer_handle  the buffer to be destroyed

void Yagl::SfxDevice::destroySoundSource (  SoundSource *  source  )

this will destroy a soundsource this will destroy the given soundsource and free any resources of it ( e.g. channel ) Parameters: source  pointer to the source being destroyed

void Yagl::SfxDevice::destroySoundStream (  SoundStream *  stream  )

destroys the given soundstream this will destroy a given soundstream. it will stop the streaming and release the channel assigned to the soundstream

bool Yagl::SfxDevice::doesSoundBufferExist (  unsigned int  buffer_handle  )

checks wheter a soundbuffer with the given handle exists this method will check wheter a soundbuffer with the provided buffer handle exists Parameters: buffer_handle  the handle of the buffer in question Returns: true if the buffer exists, false in the other case

static SfxDevice& Yagl::SfxDevice::getInstance (   )  [static]

returns a reference to the SfxDevice singleton this returns a reference to the SfxDevice singleton.

void Yagl::SfxDevice::getListenerOrientation (  float *  x_at, float *  y_at, float *  z_at, float *  x_up, float *  y_up, float *  z_up )

returns the listeners orientation this will return the listeners orientation. the up vector given via x_up, y_up, z_up should be prependicular to the direction vector Parameters: x_at  x direction of listener y_at  y direction of listener z_at  z direction of listener x_up  x up vector component of listener y_up  y up vector component of listener z_up  z up vector component of listener

void Yagl::SfxDevice::getListenerPosition (  float *  x, float *  y, float *  z )

returns the listeners position this will return the listeners position Parameters: x  x coordinate of listener y  y coordinate of listener z  z coordinate of listener

void Yagl::SfxDevice::getListenerVelocity (  float *  x, float *  y, float *  z )

returns the listeners velocity this will return the listeners velocity Parameters: x  x velocity of listener y  y velocity of listener z  z velocity of listener

bool Yagl::SfxDevice::initialize (   )

initializes the sfxdevice this will acquire the audiohardware ( device and channels ) Returns: true on success, false on failure

bool Yagl::SfxDevice::initializeChannels (   )  [protected]

internal, initializes and enumerates all hardware audiochannels this will initialize and enumerate all hardware audiochannels available. all audiochannels are owned and dynamicall managed by the SfxDevice so that any unused channels are free to be used by other SoundSources and SoundStreams. Returns: true on success, false on failure

bool Yagl::SfxDevice::initializeDevice (   )  [protected]

internal, initializes the audiodevice this initializes the hardware audio device Returns: true on success, false on error

bool Yagl::SfxDevice::playSoundBuffer (  unsigned int  buffer_handle, bool  relative = true, float *  position = 0, float *  velocity = 0, float  pitch = 1.0f, float  gain = 1.0f, float  roll_off = 0.0 )

plays the given soundbuffer with the specified attributes this is the quick and dirty fire and forget method to play a soundbuffer at a given position with a the given velocity, gain, pitch and rolloff if no channel could be acquired cause all channels are currently in use the soundbuffer won't be played. if you want teh buffer to be played at the same position as the listener is just provide the bufferhandle. any movement of the listener will not influence the volume of the played soundbuffer. this is equal to simply playing a sample. you can however provide addtional attributes that should be taken into account after calling this method you don'T have any influence on those attributes anymore. Parameters: buffer_handle  the buffer to be played relative  should this be played relative to the listener ( position wise ) position  a pointer to a 3 element big array of floats that represents the position where the sound should be played at ( either relative to the listeners position or in absolute world space ) velocity  a pointer to a 3 element big array of floats representing the velocity of the soundsource used to calculate the doppler effect pitch  the pitch, should be between 0.0 ( played very slow ) 1.0 ( played at normal frequency ) or higher if you want to play it at higher frequency gain  the gain should be between 0.0 ( mute ) and 1.0 ( full volume ) roll_off  indicates how much the distance to the listener should be taken into account. 0.0 if the distance should not play a role ( sound is played at full volume no matter the position ) 1.0 to take the distance into account as in nature

void Yagl::SfxDevice::releaseChannel (  unsigned int  channel  )  [protected]

internal, releases a channel and stops it if it was playing this releases the given channel if it is a valid one and stops the channel if it is playing. Parameters: channel  the channel to be released

void* Yagl::SfxDevice::run (   )  [protected, virtual]

internal, updates all temporary soundsources and soundstreams this is the thread method that is running in the background during the complete lifetime of the sfxdevice. it checks all temporary soundsources' status ( see SfxDevice::updateTemporarySoundSources ) and guarantes that all soundstreams are being feed with new data. it also releases any unused channels if a non temporary soundsource has finished playing thus giving other soundsources the possibility to play. Reimplemented from Yagl::Thread.

void Yagl::SfxDevice::setListenerOrientation (  float  x_at, float  y_at, float  z_at, float  x_up, float  y_up, float  z_up )

sets the listeners orientation this will sets the listeners orientation. Parameters: x_at  x direction of listener y_at  y direction of listener z_at  z direction of listener x_up  x up vector component of listener y_up  y up vector component of listener z_up  z up vector component of listener

void Yagl::SfxDevice::setListenerPosition (  float  x, float  y, float  z )

sets the listeners position this will set the listeners position Parameters: x  x coordinate of listener y  y coordinate of listener z  z coordinate of listener

void Yagl::SfxDevice::setListenerVelocity (  float  x, float  y, float  z )

sets the listeners velocity this will set the listeners velocity Parameters: x  x velocity of listener y  y velocity of listener z  z velocity of listener

void Yagl::SfxDevice::updateSources (   )  [protected]

internal, updates all soundsources this checks all soundsources created via SfxDevice::createSoundSource. if a source is found that has a channel assigned but is stopped it will release the channel giving other soundsources the possibility to play their sound this method is used within the update thread of the SfxDevice

void Yagl::SfxDevice::updateStreams (   )  [protected]

internal, updates all soundstreams this method updates all streams created via SfxDevice::createSoundStream. it calls the updateStream method of each stream in the streams_ list so they keep playing the stream or close it if the streams is finished. this method is used in the update thread of the SfxDevice

void Yagl::SfxDevice::updateTemporarySources (   )  [protected]

internal, updates all temporary soundsources this will check all temporary soundsources' status. if a temporary soundsource is not playing anymore it is destroyed and the associated channel is released this method gets called from within the update thread of the SfxDevice.

---

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

• D:/projects/gamelib/inc/audiolib/sfxdevice.h

---