]> git.mxchange.org Git - simgear.git/blobdiff - simgear/sound/sample_group.hxx
Add Update the World Magnetic Model to 2015.0
[simgear.git] / simgear / sound / sample_group.hxx
index 3e277014f0c39b93cde67d35d163bbd8e189f8c5..f87cb1dc10d6ee0a64084a668fd5244f0e164c9b 100644 (file)
@@ -1,45 +1,33 @@
-// soundmgr.hxx -- Sound effect management class
+///@file
+/// Manage a group of samples relative to a base position
+///
+/// Sample groups contain all sounds related to one specific object and
+/// have to be added to the sound manager, otherwise they won't get processed.
 //
-// Sampel Group handler initially written by Erik Hofman
+// Written for the new SoundSystem by Erik Hofman, October 2009
 //
-// Copyright (C) 2009  Erik Hofman - <erik@ehofman.com>
+// Copyright (C) 2009 Erik Hofman <erik@ehofman.com>
 //
-// This program is free software; you can redistribute it and/or
-// modify it under the terms of the GNU General Public License as
-// published by the Free Software Foundation; either version 2 of the
-// License, or (at your option) any later version.
+// This library is free software; you can redistribute it and/or
+// modify it under the terms of the GNU Library General Public
+// License as published by the Free Software Foundation; either
+// version 2 of the License, or (at your option) any later version.
 //
-// This program is distributed in the hope that it will be useful, but
-// WITHOUT ANY WARRANTY; without even the implied warranty of
+// This library is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-// General Public License for more details.
+// Library General Public License for more details.
 //
-// You should have received a copy of the GNU General Public License
-// along with this program; if not, write to the Free Software Foundation,
-// Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
-//
-// $Id$
-
-/**
- * \file sample_group.hxx
- * sample groups contain all sounds related to one specific object and
- * have to be added to the sound manager, otherwise they won't get processed.
- */
+// You should have received a copy of the GNU Library General Public
+// License along with this library; if not, write to the Free Software
+// Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301, USA.
 
 #ifndef _SG_SAMPLE_GROUP_OPENAL_HXX
 #define _SG_SAMPLE_GROUP_OPENAL_HXX 1
 
-#ifndef __cplusplus
-# error This library requires C++
-#endif
-
-#if defined(__APPLE__)
-# include <OpenAL/al.h>
-#else
-# include <AL/al.h>
-#endif
 
 #include <string>
+#include <vector>
 #include <map>
 
 #include <simgear/compiler.h>
 #include <simgear/structure/exception.hxx>
 
 #include "sample_openal.hxx"
+#include "sample_queue.hxx"
 
-using std::map;
-using std::string;
 
-typedef map < string, SGSharedPtr<SGSoundSample> > sample_map;
+typedef std::map < std::string, SGSharedPtr<SGSoundSample> > sample_map;
 typedef sample_map::iterator sample_map_iterator;
 typedef sample_map::const_iterator const_sample_map_iterator;
 
@@ -62,118 +49,187 @@ class SGSoundMgr;
 class SGSampleGroup : public SGReferenced
 {
 public:
+
+    /**
+     * Empty constructor for class encapsulation.
+     * Note: The sample group should still be activated before use
+     */
     SGSampleGroup ();
-    SGSampleGroup ( SGSoundMgr *smgr, const string &refname );
-    ~SGSampleGroup ();
 
+    /**
+     * Constructor
+     * Register this sample group at the sound manager using refname
+     * Note: The sample group should still be activated before use
+     * @param smgr Pointer to a pre-initialized sound manager class
+     * @param refname Name of this group for reference purposes.
+     */
+    SGSampleGroup ( SGSoundMgr *smgr, const std::string &refname );
+
+    /**
+     * Destructor
+     */
+    virtual ~SGSampleGroup ();
+
+    /**
+     * Set the status of this sample group to active.
+     */
+    inline void activate() { _active = true; }
+
+    /**
+     * Update function.
+     * Call this function periodically to update the OpenAL state of all
+     * samples associated with this class. None op the configuration changes
+     * take place without a call to this function.
+     */
     virtual void update (double dt);
 
     /**
-     * add a sound effect, return true if successful
+     * Register an audio sample to this group.
+     * @param sound Pointer to a pre-initialized audio sample
+     * @param refname Name of this audio sample for reference purposes
+     * @return return true if successful
+     */
+    bool add( SGSharedPtr<SGSoundSample> sound, const std::string& refname );
+
+    /**
+     * Remove an audio sample from this group.
+     * @param refname Reference name of the audio sample to remove
+     * @return return true if successful
      */
-    bool add( SGSoundSample *sound, const string& refname );
+    bool remove( const std::string& refname );
 
     /**
-     * remove a sound effect, return true if successful
+     * Test if a specified audio sample is registered at this sample group
+     * @param refname Reference name of the audio sample to test for
+     * @return true if the specified audio sample exists
      */
-    bool remove( const string& refname );
+    bool exists( const std::string& refname );
 
     /**
-     * return true of the specified sound exists in the sound manager system
+     * Find a specified audio sample in this sample group
+     * @param refname Reference name of the audio sample to find
+     * @return A pointer to the SGSoundSample
      */
-    bool exists( const string& refname );
+    SGSoundSample *find( const std::string& refname );
 
     /**
-     * return a pointer to the SGSoundSample if the specified sound
-     * exists in the sound manager system, otherwise return NULL
+     * Stop all playing samples and set the source id to invalid.
      */
-    SGSoundSample *find( const string& refname );
+    void stop();
 
     /**
-     * request to stop playing all associated samples until further notice
+     * Request to stop playing all audio samples until further notice.
      */
     void suspend();
 
     /**
-     * request to resume playing all associated samples
+     * Request to resume playing all audio samples.
      */
     void resume();
 
-
     /**
-     * request to start playing the associated samples
+     * Request to start playing the referred audio sample.
+     * @param refname Reference name of the audio sample to start playing
+     * @param looping Define if the sound should loop continuously
+     * @return true if the audio sample exsists and is scheduled for playing
      */
-    bool play( const string& refname, bool looping );
+    bool play( const std::string& refname, bool looping = false );
     
     /**
-     * tell the scheduler to play the indexed sample in a continuous
-     * loop
+     * Request to start playing the referred audio sample looping.
+     * @param refname Reference name of the audio sample to start playing
+     * @return true if the audio sample exsists and is scheduled for playing
      */
-    inline bool play_looped( const string& refname ) {
+    inline bool play_looped( const std::string& refname ) {
         return play( refname, true );
     }
 
     /**
-     * tell the scheduler to play the indexed sample once
+     * Request to start playing the referred audio sample once.
+     * @param refname Reference name of the audio sample to start playing
+     * @return true if the audio sample exists and is scheduled for playing
      */
-    inline bool play_once( const string& refname ) {
+    inline bool play_once( const std::string& refname ) {
         return play( refname, false );
     }
 
     /**
-     * return true of the specified sound is currently being played
+     * Test if a referenced sample is playing or not.
+     * @param refname Reference name of the audio sample to test for
+     * @return True of the specified sound is currently playing
      */
-    bool is_playing( const string& refname );
+    bool is_playing( const std::string& refname );
 
     /**
-     * request to stop playing the associated samples
+     * Request to stop playing the referred audio sample.
+     * @param refname Reference name of the audio sample to stop
+     * @return true if the audio sample exists and is scheduled to stop
      */
-    bool stop( const string& refname );
+    bool stop( const std::string& refname );
 
     /**
-     * set overall volume for the application.
-     * @param must be between 0.0 and 1.0
+     * Set the master volume for this sample group.
+     * @param vol Volume (must be between 0.0 and 1.0)
      */
     void set_volume( float vol );
 
     /**
-     * set the positions of all managed sound sources
+     * Set the velocity vector of this sample group.
+     * This is in the local frame coordinate system; x=north, y=east, z=down
+     * @param vel Velocity vector 
      */
-    void set_position( SGVec3d pos );
+    void set_velocity( const SGVec3d& vel ) {
+       _velocity = vel; _changed = true;
+    }
 
     /**
-     * set the velocities of all managed sound sources
+     * Set the position of this sample group.
+     * This is in the same coordinate system as OpenGL; y=up, z=back, x=right.
+     * @param pos Base position
      */
-    void set_velocity( SGVec3f vel );
+    void set_position_geod( const SGGeod& pos ) {
+        _base_pos = pos; _changed = true;
+    }
 
     /**
-     * set the orientation of all managed sound sources
+     * Set the orientation of this sample group.
+     * @param ori Quaternation containing the orientation information
      */
-    void set_orientation( SGVec3f ori );
+    void set_orientation( const SGQuatd& ori ) {
+        _orientation = ori; _changed = true;
+    }
 
     /**
-     * load the data of the sound sample
+     * Tie this sample group to the listener position, orientation and velocity
      */
-    void load_file(SGSoundSample *sound);
+    void tie_to_listener() { _tied_to_listener = true; }
 
 protected:
     SGSoundMgr *_smgr;
+    std::string _refname;
     bool _active;
 
 private:
+    void cleanup_removed_samples();
+    void start_playing_sample(SGSoundSample *sample);
+    void check_playing_sample(SGSoundSample *sample);
+  
     bool _changed;
-    bool _position_changed;
-
+    bool _pause;
     float _volume;
+    bool _tied_to_listener;
 
-    SGVec3d _position;
-    SGVec3f _orientation;
+    SGVec3d _velocity;
+    SGGeod _base_pos;
+    SGQuatd _orientation;
 
     sample_map _samples;
+    std::vector< SGSharedPtr<SGSoundSample> > _removed_samples;
 
-    bool testForALError(string s);
-    bool testForError(void *p, string s);
+    bool testForALError(std::string s);
+    bool testForError(void *p, std::string s);
 
+    void update_pos_and_orientation();
     void update_sample_config( SGSoundSample *sound );
 };