simgear/sound/sound.hxx

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