simgear/sound/xmlsound.hxx

   1 ///@file
   2 /// Sound class implementation
   3 ///
   4 /// Provides a class to manage a single sound event including things like
   5 /// looping, volume and pitch changes.
   6 //
   7 // Started by Erik Hofman, February 2002
   8 //
   9 // Copyright (C) 2002  Erik Hofman - erik@ehofman.com
  10 //
  11 // This library is free software; you can redistribute it and/or
  12 // modify it under the terms of the GNU Library General Public
  13 // License as published by the Free Software Foundation; either
  14 // version 2 of the License, or (at your option) any later version.
  15 //
  16 // This library is distributed in the hope that it will be useful,
  17 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  18 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  19 // Library General Public License for more details.
  20 //
  21 // You should have received a copy of the GNU Library General Public
  22 // License along with this library; if not, write to the Free Software
  23 // Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301, USA.
  24
  25 #ifndef _SG_SOUND_HXX
  26 #define _SG_SOUND_HXX 1
  27
  28
  29 #include <vector>
  30 #include <string>
  31
  32 #include <simgear/compiler.h>
  33
  34 #include <simgear/props/propsfwd.hxx>
  35 #include <simgear/structure/SGSharedPtr.hxx>
  36
  37 // forward decls
  38 class SGSampleGroup;
  39 class SGSoundSample;
  40 class SGCondition;
  41 class SGPath;
  42
  43 static const double MAX_TRANSIT_TIME = 0.1;     // 100 ms.
  44
  45
  46 /**
  47  * Class for handling one sound event.
  48  *
  49  * This class handles everything for a particular sound event, by
  50  * scanning an a pre-loaded property tree structure for sound
  51  * settings, setting up its internal states, and managing sound
  52  * playback whenever such an event happens.
  53  */
  54 class SGXmlSound
  55 {
  56
  57 public:
  58
  59   SGXmlSound();
  60   virtual ~SGXmlSound();
  61
  62   /**
  63    * Initialize the sound event.
  64    *
  65    * Prior to initialization of the sound event the program's property root
  66    * has to be defined, the sound configuration XML tree has to be loaded
  67    * and a sound manager class has to be defined.
  68    *
  69    * A sound configuration file would look like this:
  70    * @code{xml}
  71    *  <fx>
  72    *   <event_name>
  73    *    <name/> Define the name of the event. For reference only.
  74    *    <mode/> Either:
  75    *              looped: play this sound looped.
  76    *              in-transit: play looped while the event is happening.
  77    *              once: play this sound once.
  78    *    <path/> The relative path to the audio file.
  79    *    <property/> Take action if this property becomes true.
  80    *    <condition/> Take action if this condition becomes true.
  81    *    <delay-sec/> Time after which the sound should be played.
  82    *    <volume> or <pitch> Define volume or pitch settings.
  83    *     <property/> Take the value of this property as a reference for the
  84    *                 result.
  85    *     <internal/> Either:
  86    *                   dt_start: the time elapsed since this sound is playing.
  87    *                   dt_stop: the time elapsed since this sound has stopped.
  88    *     <offset/> Add this value to the result.
  89    *     <factor/> Multiply the result by this factor.
  90    *     <min/> Make sure the value is never less than this value.
  91    *     <max/> Make sure the value is never larger than this value.
  92    *    </volume> or </pitch>
  93    *   </event_name>
  94    *
  95    *   <event_name>
  96    *   </event_name>
  97    *  </fx>
  98    * @endcode
  99    *
 100    * @param root        The root node of the programs property tree.
 101    * @param child       A pointer to the location of the current event as
 102    *                    defined in the configuration file.
 103    * @param sgrp        A pointer to a pre-initialized sample group class.
 104    * @param avionics    A pointer to the pre-initialized avionics sample group.
 105    * @param path        The path where the audio files remain.
 106    */
 107   virtual void init( SGPropertyNode *root,
 108                      SGPropertyNode *child,
 109                      SGSampleGroup *sgrp,
 110                      SGSampleGroup *avionics,
 111                      const SGPath& path );
 112
 113   /**
 114    * Check whether an event has happened and if action has to be taken.
 115    */
 116   virtual void update (double dt);
 117
 118   /**
 119    * Stop taking action on the pre-defined events.
 120    */
 121   void stop();
 122
 123 protected:
 124
 125   enum { MAXPROP=5 };
 126   enum { ONCE=0, LOOPED, IN_TRANSIT };
 127   enum { LEVEL=0, INVERTED, FLIPFLOP };
 128
 129   // SGXmlSound properties
 130   typedef struct {
 131         SGPropertyNode_ptr prop;
 132         double (*fn)(double);
 133         double *intern;
 134         double factor;
 135         double offset;
 136         double min;
 137         double max;
 138         bool subtract;
 139   } _snd_prop;
 140
 141 private:
 142
 143   SGSampleGroup * _sgrp;
 144   SGSharedPtr<SGSoundSample> _sample;
 145
 146   SGSharedPtr<SGCondition> _condition;
 147   SGPropertyNode_ptr _property;
 148
 149   bool _active;
 150   std::string _name;
 151   int _mode;
 152   double _prev_value;
 153   double _dt_play;
 154   double _dt_stop;
 155   double _delay;        // time after which the sound should be started (default: 0)
 156   double _stopping;     // time after the sound should have stopped.
 157                         // This is useful for lost packets in in-transit mode.
 158   bool _initialized;
 159
 160   std::vector<_snd_prop> _volume;
 161   std::vector<_snd_prop> _pitch;
 162 };
 163
 164 #endif // _SG_SOUND_HXX