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 #elif defined(OPENALSDK)
  39 # include <al.h>
  40 #else
  41 # include <AL/al.h>
  42 #endif
  43
  44 #include <string>
  45 #include <vector>
  46 #include <map>
  47
  48 #include <simgear/compiler.h>
  49 #include <simgear/math/SGMath.hxx>
  50 #include <simgear/structure/SGReferenced.hxx>
  51 #include <simgear/structure/SGSharedPtr.hxx>
  52 #include <simgear/structure/exception.hxx>
  53
  54 #include "sample_openal.hxx"
  55
  56 using std::map;
  57 using std::string;
  58
  59 typedef map < string, SGSharedPtr<SGSoundSample> > sample_map;
  60 typedef sample_map::iterator sample_map_iterator;
  61 typedef sample_map::const_iterator const_sample_map_iterator;
  62
  63 class SGSoundMgr;
  64
  65 class SGSampleGroup : public SGReferenced
  66 {
  67 public:
  68
  69     /**
  70      * Empty constructor for class encapsulation.
  71      * Note: The sample group should still be activated before use
  72      */
  73     SGSampleGroup ();
  74
  75     /**
  76      * Constructor
  77      * Register this sample group at the sound manager using refname
  78      * Note: The sample group should still be activated before use
  79      * @param smgr Pointer to a pre-initialized sound manager class
  80      * @param refname Name of this group for reference purposes.
  81      */
  82     SGSampleGroup ( SGSoundMgr *smgr, const string &refname );
  83
  84     /**
  85      * Destructor
  86      */
  87     ~SGSampleGroup ();
  88
  89     /**
  90      * Set the status of this sample group to active.
  91      */
  92     inline void activate() { _active = true; }
  93
  94     /**
  95      * Update function.
  96      * Call this function periodically to update the OpenAL state of all
  97      * samples associated with this class. None op the configuration changes
  98      * take place without a call to this function.
  99      */
 100     virtual void update (double dt);
 101
 102     /**
 103      * Register an audio sample to this group.
 104      * @param sound Pointer to a pre-initialized audio sample
 105      * @param refname Name of this audio sample for reference purposes
 106      * @return return true if successful
 107      */
 108     bool add( SGSharedPtr<SGSoundSample> sound, const string& refname );
 109
 110     /**
 111      * Remove an audio sample from this group.
 112      * @param refname Reference name of the audio sample to remove
 113      * @return return true if successful
 114      */
 115     bool remove( const string& refname );
 116
 117     /**
 118      * Test if a specified audio sample is registered at this sample group
 119      * @param refname Reference name of the audio sample to test for
 120      * @return true if the specified audio sample exists
 121      */
 122     bool exists( const string& refname );
 123
 124     /**
 125      * Find a specified audio sample in this sample group
 126      * @param refname Reference name of the audio sample to find
 127      * @return A pointer to the SGSoundSample
 128      */
 129     SGSoundSample *find( const string& refname );
 130
 131     /**
 132      * Stop all playing samples and set the source id to invalid.
 133      */
 134     void stop();
 135
 136     /**
 137      * Request to stop playing all audio samples until further notice.
 138      */
 139     void suspend();
 140
 141     /**
 142      * Request to resume playing all audio samples.
 143      */
 144     void resume();
 145
 146     /**
 147      * Request to start playing the refered audio sample.
 148      * @param refname Reference name of the audio sample to start playing
 149      * @param looping Define if the sound should loop continuously
 150      * @return true if the audio sample exsists and is scheduled for playing
 151      */
 152     bool play( const string& refname, bool looping );
 153
 154     /**
 155      * Request to start playing the refered audio sample looping.
 156      * @param refname Reference name of the audio sample to start playing
 157      * @return true if the audio sample exsists and is scheduled for playing
 158      */
 159     inline bool play_looped( const string& refname ) {
 160         return play( refname, true );
 161     }
 162
 163     /**
 164      * Request to start playing the refered audio sample once.
 165      * @param refname Reference name of the audio sample to start playing
 166      * @return true if the audio sample exsists and is scheduled for playing
 167      */
 168     inline bool play_once( const string& refname ) {
 169         return play( refname, false );
 170     }
 171
 172     /**
 173      * Test if a referenced sample is playing or not.
 174      * @param refname Reference name of the audio sample to test for
 175      * @return True of the specified sound is currently playing
 176      */
 177     bool is_playing( const string& refname );
 178
 179     /**
 180      * Request to stop playing the refered audio sample.
 181      * @param refname Reference name of the audio sample to stop
 182      * @return true if the audio sample exsists and is scheduled to stop
 183      */
 184     bool stop( const string& refname );
 185
 186     /**
 187      * Set the master volume for this sample group.
 188      * @param vol Volume (must be between 0.0 and 1.0)
 189      */
 190     void set_volume( float vol );
 191
 192     /**
 193      * Set the velocity vector of this sample group.
 194      * This is in the local frame coordinate system; x=north, y=east, z=down
 195      * @param vel Velocity vector
 196      */
 197     void set_velocity( const SGVec3d& vel ) {
 198        _velocity = vel; _changed = true;
 199     }
 200
 201     /**
 202      * Set the position of this sample group.
 203      * This is in the same coordinate system as OpenGL; y=up, z=back, x=right.
 204      * @param pos Base position
 205      */
 206     void set_position_geod( const SGGeod& pos ) {
 207         _base_pos = pos; _changed = true;
 208     }
 209
 210     /**
 211      * Set the orientation of this sample group.
 212      * @param ori Quaternation containing the orientation information
 213      */
 214     void set_orientation( const SGQuatd& ori ) {
 215         _orientation = ori; _changed = true;
 216     }
 217
 218     /**
 219      * Tie this sample group to the listener position, orientation and velocity
 220      */
 221     void tie_to_listener() { _tied_to_listener = true; }
 222
 223 protected:
 224     SGSoundMgr *_smgr;
 225     string _refname;
 226     bool _active;
 227
 228 private:
 229     bool _changed;
 230     bool _pause;
 231     float _volume;
 232     bool _tied_to_listener;
 233
 234     SGVec3d _velocity;
 235     SGGeod _base_pos;
 236     SGQuatd _orientation;
 237
 238     sample_map _samples;
 239     std::vector< SGSharedPtr<SGSoundSample> > _removed_samples;
 240
 241     bool testForALError(string s);
 242     bool testForError(void *p, string s);
 243
 244     void update_pos_and_orientation();
 245     void update_sample_config( SGSoundSample *sound );
 246 };
 247
 248 #endif // _SG_SAMPLE_GROUP_OPENAL_HXX
 249