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