//
// $Id$
+/**
+ * \file soundmgr.hxx
+ * Provides a sound manager class to keep track of
+ * multiple sounds and manage playing them with different effects and
+ * timings.
+ */
#ifndef _SG_SOUNDMGR_HXX
#define _SG_SOUNDMGR_HXX 1
SG_USING_STD(string);
-// manages everything we need to know for an individual sound sample
-class SimpleSound {
+/**
+ * manages everything we need to know for an individual sound sample
+ */
+class SGSimpleSound {
private:
public:
- SimpleSound( const char *path, const char *file = NULL );
- SimpleSound( unsigned char *buffer, int len );
- ~SimpleSound();
+ SGSimpleSound( const char *path, const char *file = NULL );
+ SGSimpleSound( unsigned char *buffer, int len );
+ ~SGSimpleSound();
+ /**
+ * Start playing this sample.
+ *
+ * @param sched A pointer to the appropriate scheduler.
+ * @param looped Define wether the sound should be played in a loop.
+ */
void play( slScheduler *sched, bool looped );
- void stop( slScheduler *sched, bool quick = true );
+ /**
+ * Stop playing this sample.
+ *
+ * @param sched A pointer to the appropriate scheduler.
+ */
+ void stop( slScheduler *sched );
+
+ /**
+ * Play this sample once.
+ * @see #play
+ */
inline void play_once( slScheduler *sched ) { play( sched, false); }
+
+ /**
+ * Play this sample looped.
+ * @see #play
+ */
inline void play_looped( slScheduler *sched ) { play( sched, true); }
+
+ /**
+ * Test if a sample is curretnly playing.
+ * @return true if is is playing, false otherwise.
+ */
inline bool is_playing( ) {
return ( sample->getPlayCount() > 0 );
}
+ /**
+ * Get the current pitch setting of this sample.
+ */
inline double get_pitch() const { return pitch; }
+
+ /**
+ * Set the pitch of this sample.
+ */
inline void set_pitch( double p ) {
pitch = p;
pitch_envelope->setStep( 0, 0.01, pitch );
}
+
+ /**
+ * Get the current volume setting of this sample.
+ */
inline double get_volume() const { return volume; }
+
+ /**
+ * Set the volume of this sample.
+ */
inline void set_volume( double v ) {
volume = v;
volume_envelope->setStep( 0, 0.01, volume );
}
+ /**
+ * Get a refference to the raw sample.
+ */
inline slSample *get_sample() { return sample; }
+
+ /**
+ * Get the pitch envelope setting of this sample.
+ */
inline slEnvelope *get_pitch_envelope() { return pitch_envelope; }
+
+ /**
+ * Get the volume envelope setting of this sample.
+ */
inline slEnvelope *get_volume_envelope() { return volume_envelope; }
};
typedef sample_map::iterator sample_map_iterator;
typedef sample_map::const_iterator const_sample_map_iterator;
-
-typedef map < string, SimpleSound * > sound_map;
+typedef map < string, SGSimpleSound * > sound_map;
typedef sound_map::iterator sound_map_iterator;
typedef sound_map::const_iterator const_sound_map_iterator;
-class SoundMgr
+/**
+ * Manage a collection of SGSimpleSound instances
+ */
+class SGSoundMgr
{
slScheduler *audio_sched;
public:
- SoundMgr();
- ~SoundMgr();
+ SGSoundMgr();
+ ~SGSoundMgr();
/**
void resume ();
- // is audio working?
+ /**
+ * is audio working?
+ */
inline bool is_working() const { return !audio_sched->notWorking(); }
- // reinitialize the sound manager
+ /**
+ * reinitialize the sound manager
+ */
inline void reinit() { init(); }
- // add a sound effect, return true if successful
- bool add( SimpleSound *sound, const string& refname);
+ /**
+ * add a sound effect, return true if successful
+ */
+ bool add( SGSimpleSound *sound, const string& refname);
- // add a sound file, return the sample if successful, else return NULL
- SimpleSound *add( const string& refname,
+ /**
+ * Add a sound file to the sound manager.
+ *
+ * The advantage of using this function over the previous one is that
+ * it doesn't load a sample if it already is in memory, but instead it
+ * uses the already loaded sample data.
+ *
+ * @param refname A refference name to make a distincion between samples.
+ * @param path The path or full filename of the sample to load.
+ * @param file An optional filename which will be appended to the path.
+ * @return An instance of the sound for further manipulation.
+ */
+ SGSimpleSound *add( const string& refname,
const char *path, const char *file = NULL );
- // remove a sound effect, return true if successful
+ /**
+ * remove a sound effect, return true if successful
+ */
bool remove( const string& refname );
- // return true of the specified sound exists in the sound manager system
+ /**
+ * return true of the specified sound exists in the sound manager system
+ */
bool exists( const string& refname );
- // return a pointer to the SimpleSound if the specified sound
- // exists in the sound manager system, otherwise return NULL
- SimpleSound *find( const string& refname );
+ /**
+ * return a pointer to the SGSimpleSound if the specified sound
+ * exists in the sound manager system, otherwise return NULL
+ */
+ SGSimpleSound *find( const string& refname );
- // tell the scheduler to play the indexed sample in a continuous
- // loop
+ /**
+ * tell the scheduler to play the indexed sample in a continuous
+ * loop
+ */
bool play_looped( const string& refname );
- // tell the scheduler to play the indexed sample once
+ /**
+ * tell the scheduler to play the indexed sample once
+ */
bool play_once( const string& refname );
- // return true of the specified sound is currently being played
+ /**
+ * return true of the specified sound is currently being played
+ */
bool is_playing( const string& refname );
- // immediate stop playing the sound
+ /**
+ * immediate stop playing the sound
+ */
bool stop( const string& refname );
- // return the audio scheduler
+ /**
+ * return the audio scheduler
+ */
inline slScheduler *get_scheduler( ) { return audio_sched; };
};
projects / simgear.git / blobdiff