simgear/sound/sample_group.hxx

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