X-Git-Url: https://git.mxchange.org/?a=blobdiff_plain;f=simgear%2Fsound%2Fsoundmgr.hxx;h=852fdc027bcd83e2f5797d91278cda4e5a0868f0;hb=a1a596b02a3433a7821c418c6e09e76f7bf927b0;hp=9f1d1e955b88a4ae983e7c752e93e992970399dd;hpb=ef5fb7a98e898453bcda17545097dc3826a338eb;p=simgear.git

diff --git a/simgear/sound/soundmgr.hxx b/simgear/sound/soundmgr.hxx
index 9f1d1e95..852fdc02 100644
--- a/simgear/sound/soundmgr.hxx
+++ b/simgear/sound/soundmgr.hxx
@@ -23,6 +23,12 @@
 //
 // $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
@@ -44,7 +50,9 @@ SG_USING_STD(map);
 SG_USING_STD(string);
 
 
-// manages everything we need to know for an individual sound sample
+/**
+ * manages everything we need to know for an individual sound sample
+ */
 class SGSimpleSound {
 
 private:
@@ -61,28 +69,80 @@ public:
     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; }
 };
 
@@ -101,6 +161,9 @@ typedef sound_map::iterator sound_map_iterator;
 typedef sound_map::const_iterator const_sound_map_iterator;
 
 
+/**
+ * Manage a collection of SGSimpleSound instances
+ */
 class SGSoundMgr
 {
 
@@ -154,43 +217,76 @@ public:
     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
+    /**
+     * 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
+    /**
+     * 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 SGSimpleSound if the specified sound
-    // exists in the sound manager system, otherwise return NULL
-    SGSimpleSound *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; };
 };