simgear/sound/sample_group.hxx

   1 // sample_group.hxx -- Manage a group of samples relative to a base position
   2 //
   3 // Written for the new SoundSystem by Erik Hofman, October 2009
   4 //
   5 // Copyright (C) 2009 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 Foundation,
  19 // Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
  20 //
  21 // $Id$
  22
  23 /**
  24  * \file sample_group.hxx
  25  * sample groups contain all sounds related to one specific object and
  26  * have to be added to the sound manager, otherwise they won't get processed.
  27  */
  28
  29 #ifndef _SG_SAMPLE_GROUP_OPENAL_HXX
  30 #define _SG_SAMPLE_GROUP_OPENAL_HXX 1
  31
  32 #ifndef __cplusplus
  33 # error This library requires C++
  34 #endif
  35
  36 #if defined(__APPLE__)
  37 # include <OpenAL/al.h>
  38 #else
  39 # include <AL/al.h>
  40 #endif
  41
  42 #include <string>
  43 #include <map>
  44
  45 #include <simgear/compiler.h>
  46 #include <simgear/math/SGMath.hxx>
  47 #include <simgear/structure/SGReferenced.hxx>
  48 #include <simgear/structure/SGSharedPtr.hxx>
  49 #include <simgear/structure/exception.hxx>
  50
  51 #include "sample_openal.hxx"
  52
  53 using std::map;
  54 using std::string;
  55
  56 typedef map < string, SGSharedPtr<SGSoundSample> > sample_map;
  57 typedef sample_map::iterator sample_map_iterator;
  58 typedef sample_map::const_iterator const_sample_map_iterator;
  59
  60 class SGSoundMgr;
  61
  62 class SGSampleGroup : public SGReferenced
  63 {
  64 public:
  65
  66     /**
  67      * Empty constructor for class encapsulation.
  68      * Note: The sample group should still be activated before use
  69      */
  70     SGSampleGroup ();
  71
  72     /**
  73      * Constructor
  74      * Register this sample group at the sound manager using refname
  75      * Note: The sample group should still be activated before use
  76      * @param smgr Pointer to a pre-initialized sound manager class
  77      * @param refname Name of this group for reference purposes.
  78      */
  79     SGSampleGroup ( SGSoundMgr *smgr, const string &refname );
  80
  81     /**
  82      * Destructor
  83      */
  84     ~SGSampleGroup ();
  85
  86     /**
  87      * Set the status of this sample group to active.
  88      */
  89     inline void activate() { _active = true; }
  90
  91     /**
  92      * Update function.
  93      * Call this function periodically to update the OpenAL state of all
  94      * samples associated with this class. None op the configuration changes
  95      * take place without a call to this function.
  96      */
  97     virtual void update (double dt);
  98
  99     /**
 100      * Register an audio sample to this group.
 101      * @param sound Pointer to a pre-initialized audio sample
 102      * @param refname Name of this audio sample for reference purposes
 103      * @return return true if successful
 104      */
 105     bool add( SGSoundSample *sound, const string& refname );
 106
 107     /**
 108      * Remove an audio sample from this group.
 109      * @param refname Reference name of the audio sample to remove
 110      * @return return true if successful
 111      */
 112     bool remove( const string& refname );
 113
 114     /**
 115      * Test if a specified audio sample is registered at this sample group
 116      * @param refname Reference name of the audio sample to test for
 117      * @return true if the specified audio sample exists
 118      */
 119     bool exists( const string& refname );
 120
 121     /**
 122      * Find a specified audio sample in this sample group
 123      * @param refname Reference name of the audio sample to find
 124      * @return A pointer to the SGSoundSample
 125      */
 126     SGSoundSample *find( const string& refname );
 127
 128     /**
 129      * Request to stop playing all audio samples until further notice.
 130      */
 131     void suspend();
 132
 133     /**
 134      * Request to resume playing all audio samples.
 135      */
 136     void resume();
 137
 138     /**
 139      * Request to start playing the refered audio sample.
 140      * @param refname Reference name of the audio sample to start playing
 141      * @param looping Define if the sound should loop continuously
 142      * @return true if the audio sample exsists and is scheduled for playing
 143      */
 144     bool play( const string& refname, bool looping );
 145
 146     /**
 147      * Request to start playing the refered audio sample looping.
 148      * @param refname Reference name of the audio sample to start playing
 149      * @return true if the audio sample exsists and is scheduled for playing
 150      */
 151     inline bool play_looped( const string& refname ) {
 152         return play( refname, true );
 153     }
 154
 155     /**
 156      * Request to start playing the refered audio sample once.
 157      * @param refname Reference name of the audio sample to start playing
 158      * @return true if the audio sample exsists and is scheduled for playing
 159      */
 160     inline bool play_once( const string& refname ) {
 161         return play( refname, false );
 162     }
 163
 164     /**
 165      * Test if a referenced sample is playing or not.
 166      * @param refname Reference name of the audio sample to test for
 167      * @return True of the specified sound is currently playing
 168      */
 169     bool is_playing( const string& refname );
 170
 171     /**
 172      * Request to stop playing the refered audio sample.
 173      * @param refname Reference name of the audio sample to stop
 174      * @return true if the audio sample exsists and is scheduled to stop
 175      */
 176     bool stop( const string& refname );
 177
 178     /**
 179      * Set the master volume for this sample group.
 180      * @param vol Volume (must be between 0.0 and 1.0)
 181      */
 182     void set_volume( float vol );
 183
 184     /**
 185      * Set the velocity vector of this sample group.
 186      * This is in the same coordinate system as OpenGL; y=up, z=back, x=right.
 187      * @param vel Velocity vector
 188      */
 189     void set_velocity( const SGVec3d& vel );
 190
 191     /**
 192      * Set the position of this sample group.
 193      * This is in the same coordinate system as OpenGL; y=up, z=back, x=right.
 194      * @param pos Base position
 195      */
 196     void set_position( const SGGeod& pos );
 197
 198     /**
 199      * Set the orientation of this sample group.
 200      * @param ori Quaternation containing the orientation information
 201      */
 202     void set_orientation( const SGQuatd& ori );
 203
 204     /**
 205      * Tie this sample group to the listener position, orientation and velocity
 206      */
 207     void tie_to_listener() { _tied_to_listener = true; }
 208
 209 protected:
 210     SGSoundMgr *_smgr;
 211     string _refname;
 212     bool _active;
 213
 214 private:
 215     float _volume;
 216     bool _tied_to_listener;
 217
 218     SGVec3d _velocity;
 219     SGQuatd _orientation;
 220     SGGeod _position;
 221
 222     sample_map _samples;
 223
 224     bool testForALError(string s);
 225     bool testForError(void *p, string s);
 226
 227     void update_sample_config( SGSoundSample *sound );
 228 };
 229
 230 #endif // _SG_SAMPLE_GROUP_OPENAL_HXX
 231