Add some more descriptive comments

[simgear.git] / simgear / sound / sound.hxx

diff --git a/simgear/sound/sound.hxx b/simgear/sound/sound.hxx
index cd0c96ed9ef6630ee8e29f72648e8ef8fca9868e..48888b0a1597c8a513f32d86f8abc8566434628a 100644 (file)
--- a/simgear/sound/sound.hxx
+++ b/simgear/sound/sound.hxx
@@ -20,6 +20,12 @@
 //
 // $Id$
 
+/** 
+ * \file sound.hxx 
+ * Provides a class to manage a single sound event including things
+ * like looping, volume and pitch changes.
+ */
+
 #ifndef _SG_SOUND_HXX
 #define _SG_SOUND_HXX 1
 
@@ -38,19 +44,71 @@ static const double MAX_TRANSIT_TIME = 0.1; // 100 ms.
 /**
  * Class for handling one sound event.
  *
+ * This class handles everything for a particular sound event, by
+ * scanning an a pre-loaded property tree structure for sound
+ * settings, setting up its internal states, and managing sound
+ * playback whenever such an event happens.
  */
-class Sound
+class SGSound
 {
 
 public:
 
-  Sound();
-  virtual ~Sound();
-
-  virtual void init (SGPropertyNode *, SGPropertyNode *, SoundMgr *,
+  SGSound();
+  virtual ~SGSound();
+
+  /**
+   * Initialize the sound event.
+   *
+   * Prior to initialization of the sound event the propgrams property root
+   * has to be defined, the sound configuration XML tree has to be loaded 
+   * and a sound manager class has to be defined.
+   *
+   * A sound configuration file would look like this:
+   *  <fx>
+   *   <event_name>
+   *    <name/> Define the name of the event. For refference only.
+   *    <mode/> Either:
+   *              looped: play this sound looped.
+   *              in-transit: play looped while the event is happening.
+   *              once: play this sound once.
+   *    <path/> The relative path to the audio file.
+   *    <property/> Take action if this property becomes true.
+   *    <condition/> Take action if this condition becomes true.
+   *    <volume> or <pitch> Define volume or pitch settings.
+   *     <property/> Take the value of this property as a refference for the
+   *                 result.
+   *     <internal/> Either:
+   *                   dt_start: the time elapsed since this sound is playing.
+   *                   dt_stop: the time elapsed since this sound has stopped.
+   *     <offset/> Add this value to the result.
+   *     <factor/> Multiply the result by this factor.
+   *     <min/> Make sure the value is never less than this value.
+   *     <max/> Make sure the value is never larger than this value.
+   *    </volume> or </pitch>
+   *   </event_name>
+   *
+   *   <event_name>
+   *   </event_name>
+   *  </fx>
+   *
+   * @param root The root node of the programs property tree.
+   * @param child A pointer to the location of the current event as defined
+   * in the configuration file.
+   * @param sndmgr A pointer to a pre-initialized sound manager class.
+   * @param path The path where the audio files remain.
+   */
+  virtual void init (SGPropertyNode *, SGPropertyNode *, SGSoundMgr *,
                      const string &);
+
+  /**
+   * Check wheter an event has happened and if action has to be taken.
+   */
   virtual void update (double dt);
 
+  /**
+   * Stop taking action on the pre-defined events.
+   */
   void stop();
 
 protected:
@@ -59,7 +117,7 @@ protected:
   enum { ONCE=0, LOOPED, IN_TRANSIT };
   enum { LEVEL=0, INVERTED, FLIPFLOP };
 
-  // Sound properties
+  // SGSound properties
   typedef struct {
         SGPropertyNode * prop;
         double (*fn)(double);
@@ -73,10 +131,10 @@ protected:
 
 private:
 
-  SoundMgr * _mgr;
-  SimpleSound * _sample;
+  SGSoundMgr * _mgr;
+  SGSimpleSound * _sample;
 
-  FGCondition * _condition;
+  SGCondition * _condition;
   SGPropertyNode * _property;
 
   bool _active;