Yagl::SoundStream Class Reference

#include <soundstream.h>

List of all members.

Public Member Functions
bool	setStreamedFile (const Yagl::String filename)
	sets the streamed file of the soundstream
void	setRelativeToListener (bool value)
	set wheter the soundstream is positioned relative to listener or not
void	setVelocity (float x, float y, float z)
	sets the velocity of the soundstream
void	setPosition (float x, float y, float z)
	sets the position of the soundstream
void	setGain (float gain)
	sets the gain of the soundstream
void	setPitch (float pitch)
	sets the pitch of the soundstream
void	setRollOff (float rolloff)
	sets the rolloff of the soundstream
bool	isRelativeToListener ()
	returns wheter the soundstream is positioned relative to listener or not
void	getVelocity (float *x, float *y, float *z)
	returns velocity of soundstream
void	getPosition (float *x, float *y, float *z)
	returns position of soundstream
float	getGain ()
	returns the gain of the soundstream
float	getPitch ()
	returns the pitch of the soundstream
float	getRollOff ()
	returns the rolloff of the soundstream
void	play ()
	plays the soundstream
void	playLooped ()
	plays the soundstream
void	pause ()
	pauses the soundstream
void	stop ()
	stops the soundstream
bool	isPlaying ()
	returns wheter the soundstream is playing
bool	isPaused ()
	returns wheter the soundstream is paused
bool	isStopped ()
	returns wheter the soundstream is stopped
Protected Member Functions
	SoundStream ()
	internal, constructor
	SoundStream (const SoundStream &stream)
	internal copy constructor
	~SoundStream ()
	internal, destructor
bool	acquireChannel ()
	internal, acquires a channel from the SfxDevice
void	releaseChannel ()
	internal, releases the channel assigned to the stream
void	updateStream ()
	internal, updates the stream
bool	streamToBuffer (unsigned int buffer)
	internal, streams the next chunk to the given buffer
void	unqueueBuffers ()
	internal, unqueues all unprocessed buffers from the channel
Protected Attributes
unsigned int	buffers_ [2]
	handle to the used buffers
unsigned int	channel_
	handle to the assigned channel
bool	has_valid_channel_
	indicates wheter the soundstream has a valid channel
SOUNDSTREAM_STATUS	state_
	state of the stream, can be PLAYING, PAUSED or STOPPED
Decoder *	decoder_
	pointer to the decoder in use.
Mutex	stream_lock_
	mutex to lock the stream
float	position_ [3]
	position of the soundstream ( either relative to listener or given in worldspace depending on relative_ )
float	velocity_ [3]
	velocity of the soundstream
float	gain_
	gain of the soundstream ( should be between 0.0 and 1.0 )
float	pitch_
	pitch of the soundstream ( should be > 0.0, 1.0 for normal frequency )
float	rolloff_
	defines how much the distance to the listener of the stream is taken into account when calculating the final volume of the played sound ( 0.0 for distance having no effect on volu,me, 1.0 for distance having the same effect as in nature )
bool	relative_
	is the position given relative to the listener's position?
Friends
class	Yagl::SfxDevice

---

Detailed Description

class SoundStream

a soundstream is similar to a soundsource, except that it works with files being streamed instead of soundbuffers. a valid soundstream has a permanent channel assigned to it no matter what's its state. the channel will only be released if the soundstream is destroyed other than that all rules applying to soundsources applay to soundstreams given that a stream always streams from a certain file in a certain format it owns a decoder that is responsible for feeding the stream. no special care has to be taken if you want to stream from a specific file as long as a proper decoder is registered.

---

Constructor & Destructor Documentation

Yagl::SoundStream::~SoundStream (   )  [protected]

internal, destructor this will stop the stream if it plays, delete the decoder associated to it, and release the channel assigned to it

---

Member Function Documentation

bool Yagl::SoundStream::acquireChannel (   )  [protected]

internal, acquires a channel from the SfxDevice this method tries to acquire a channel from the SfxDevice Returns: true on success ( channel_ holds channle handle, has_valid_channel_ == true ), false on failure ( channel_ is undefined, has_valid_channel_ == false )

float Yagl::SoundStream::getGain (   )

returns the gain of the soundstream this returns the gain of the soundstream Returns: gain of soundstream

float Yagl::SoundStream::getPitch (   )

returns the pitch of the soundstream this returns the pitch of the soundstream Returns: pitch of soundstream

void Yagl::SoundStream::getPosition (  float *  x, float *  y, float *  z )

returns position of soundstream this will return the position of the soundstream Parameters: x  pointer to where the x component of the position should be stored to y  pointer to where the y component of the position should be stored to z  pointer to where the z component of the position should be stored to

float Yagl::SoundStream::getRollOff (   )

returns the rolloff of the soundstream this returns the rolloff of the soundstream Returns: rolloff of soundstream

void Yagl::SoundStream::getVelocity (  float *  x, float *  y, float *  z )

returns velocity of soundstream this will return the velocity of the soundstream Parameters: x  pointer to where the x component of the velocity should be stored to y  pointer to where the y component of the velocity should be stored to z  pointer to where the z component of the velocity should be stored to

bool Yagl::SoundStream::isPaused (   )

returns wheter the soundstream is paused returns wheter the soundstream is paused Returns: true if it's paused, false if not

bool Yagl::SoundStream::isPlaying (   )

returns wheter the soundstream is playing returns wheter the soundstream is playing Returns: true if it's playing, false if not

bool Yagl::SoundStream::isRelativeToListener (   )

returns wheter the soundstream is positioned relative to listener or not this returns wheter the soundstream is positioned relative to the listener or not Returns: true if relative, false otherwise

bool Yagl::SoundStream::isStopped (   )

returns wheter the soundstream is stopped returns wheter the soundstream is stopped Returns: true if it's stopped, false if not

void Yagl::SoundStream::pause (   )

pauses the soundstream this will pause the soundstream if it was playing. any calls to set and get methods still work. in case the soundstream was in STOPPED state this method has no effect.

void Yagl::SoundStream::play (   )

plays the soundstream this will try to acquire a channel from the SfxDevice and play the associated soundbuffer with the given attributes of the soundstream ( positio, velocity, gain, pitch, rolloff ). in case no channel could be acquired the method has no effect

void Yagl::SoundStream::playLooped (   )

plays the soundstream this will try to acquire a channel from the SfxDevice and play the associated soundbuffer with the given attributes of the soundstream ( positio, velocity, gain, pitch, rolloff ). the soundbuffer will be played looped from start to end. in case no channel could be acquired the method has no effect.

void Yagl::SoundStream::releaseChannel (   )  [protected]

internal, releases the channel assigned to the stream this will release the channel assigned to the stream

void Yagl::SoundStream::setGain (  float  gain  )

sets the gain of the soundstream this sets the gain of the soundstream. 0.0 is mute 1.0 is full volume Parameters: gain  gain of the soundstream

void Yagl::SoundStream::setPitch (  float  pitch  )

sets the pitch of the soundstream this sets the pitch of the soundstream. should be > 0.0, 1.0 is normal frequency Parameters: pitch  pitch of the soundstream

void Yagl::SoundStream::setPosition (  float  x, float  y, float  z )

sets the position of the soundstream this sets the position of the soundstream either relative to the listener or in world space depending on relative_ Parameters: x  x component of position y  y component of position z  z component of position

void Yagl::SoundStream::setRelativeToListener (  bool  value  )

set wheter the soundstream is positioned relative to listener or not this methods sets wheter the soundstream's position is relative to the listener or not. Parameters: value  true if it should be relative, false otherwise

void Yagl::SoundStream::setRollOff (  float  rolloff  )

sets the rolloff of the soundstream this sets the rolloff of the soundstream. the rolloff defines how much the distance to the listener should be taken into account when calculating the final volume of the soundstream. 0.0 means it is not taken into account, 1.0 means it's taken into account as in nature Parameters: rolloff  rolloff the soundstream

bool Yagl::SoundStream::setStreamedFile (  const Yagl::String  filename  )

sets the streamed file of the soundstream this method will try to open the specified file and use it as the streams source. it will stop the stream if it was playing and delete the decoder. it will then try to get a decoder for the specified file, the state_ is set to STOPPED Parameters: filename  the file to be streamed from Returns: true on success, false on failure

void Yagl::SoundStream::setVelocity (  float  x, float  y, float  z )

sets the velocity of the soundstream this sets the velocity of the soundstream used to calcualte the doppler effect Parameters: x  x component of velocity y  y component of velocity z  z component of velocity

void Yagl::SoundStream::stop (   )

stops the soundstream this will stop the soundstream if it is playing it will also release the acquired channel in that case. in case the soundstream was in STOPPED state this method has no effect.

bool Yagl::SoundStream::streamToBuffer (  unsigned int  buffer  )  [protected]

internal, streams the next chunk to the given buffer this will try to stream the next chunk to the given buffer. if a failure or an eof occurs then the soundstream will stop playing the decoder wil be deleted, the channel will be released and the state_ will be set to STOPPED Parameters: buffer  handle of the buffer that should receive the new chunk Returns: true if a chunk was successfully decoded, false on eof or when a failure occured

void Yagl::SoundStream::unqueueBuffers (   )  [protected]

internal, unqueues all unprocessed buffers from the channel this will unqueue all unprocessed buffers from the channel. needed when the channel stops playing before eof is reached.

void Yagl::SoundStream::updateStream (   )  [protected]

internal, updates the stream this method is responsible for feeding the stream via the decoder. if there was an error during streaming it will put the stream to a STOPPED state, realese the channel and delete the decoder. if the stream has reached an eof it will do the same. in every other case it will feed the stream with the newly decoded chunks from the file so that it keeps playing. this method is called from within SfxDevice::updateStreams in the update thread.

---

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

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

---