1 // sample_group.hxx -- Manage a group of samples relative to a base position
3 // Written for the new SoundSystem by Erik Hofman, October 2009
5 // Copyright (C) 2009 Erik Hofman <erik@ehofman.com>
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.
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.
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.
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.
29 #ifndef _SG_SAMPLE_GROUP_OPENAL_HXX
30 #define _SG_SAMPLE_GROUP_OPENAL_HXX 1
33 # error This library requires C++
36 #if defined(__APPLE__)
37 # include <OpenAL/al.h>
38 #elif defined(OPENALSDK)
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>
54 #include "sample_openal.hxx"
55 #include "sample_queue.hxx"
60 typedef map < string, SGSharedPtr<SGSoundSample> > sample_map;
61 typedef sample_map::iterator sample_map_iterator;
62 typedef sample_map::const_iterator const_sample_map_iterator;
66 class SGSampleGroup : public SGReferenced
71 * Empty constructor for class encapsulation.
72 * Note: The sample group should still be activated before use
78 * Register this sample group at the sound manager using refname
79 * Note: The sample group should still be activated before use
80 * @param smgr Pointer to a pre-initialized sound manager class
81 * @param refname Name of this group for reference purposes.
83 SGSampleGroup ( SGSoundMgr *smgr, const string &refname );
88 virtual ~SGSampleGroup ();
91 * Set the status of this sample group to active.
93 inline void activate() { _active = true; }
97 * Call this function periodically to update the OpenAL state of all
98 * samples associated with this class. None op the configuration changes
99 * take place without a call to this function.
101 virtual void update (double dt);
104 * Register an audio sample to this group.
105 * @param sound Pointer to a pre-initialized audio sample
106 * @param refname Name of this audio sample for reference purposes
107 * @return return true if successful
109 bool add( SGSharedPtr<SGSoundSample> sound, const string& refname );
112 * Remove an audio sample from this group.
113 * @param refname Reference name of the audio sample to remove
114 * @return return true if successful
116 bool remove( const string& refname );
119 * Test if a specified audio sample is registered at this sample group
120 * @param refname Reference name of the audio sample to test for
121 * @return true if the specified audio sample exists
123 bool exists( const string& refname );
126 * Find a specified audio sample in this sample group
127 * @param refname Reference name of the audio sample to find
128 * @return A pointer to the SGSoundSample
130 SGSoundSample *find( const string& refname );
133 * Stop all playing samples and set the source id to invalid.
138 * Request to stop playing all audio samples until further notice.
143 * Request to resume playing all audio samples.
148 * Request to start playing the referred audio sample.
149 * @param refname Reference name of the audio sample to start playing
150 * @param looping Define if the sound should loop continuously
151 * @return true if the audio sample exsists and is scheduled for playing
153 bool play( const string& refname, bool looping );
156 * Request to start playing the referred audio sample looping.
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
160 inline bool play_looped( const string& refname ) {
161 return play( refname, true );
165 * Request to start playing the referred audio sample once.
166 * @param refname Reference name of the audio sample to start playing
167 * @return true if the audio sample exists and is scheduled for playing
169 inline bool play_once( const string& refname ) {
170 return play( refname, false );
174 * Test if a referenced sample is playing or not.
175 * @param refname Reference name of the audio sample to test for
176 * @return True of the specified sound is currently playing
178 bool is_playing( const string& refname );
181 * Request to stop playing the referred audio sample.
182 * @param refname Reference name of the audio sample to stop
183 * @return true if the audio sample exists and is scheduled to stop
185 bool stop( const string& refname );
188 * Set the master volume for this sample group.
189 * @param vol Volume (must be between 0.0 and 1.0)
191 void set_volume( float vol );
194 * Set the velocity vector of this sample group.
195 * This is in the local frame coordinate system; x=north, y=east, z=down
196 * @param vel Velocity vector
198 void set_velocity( const SGVec3d& vel ) {
199 _velocity = vel; _changed = true;
203 * Set the position of this sample group.
204 * This is in the same coordinate system as OpenGL; y=up, z=back, x=right.
205 * @param pos Base position
207 void set_position_geod( const SGGeod& pos ) {
208 _base_pos = pos; _changed = true;
212 * Set the orientation of this sample group.
213 * @param ori Quaternation containing the orientation information
215 void set_orientation( const SGQuatd& ori ) {
216 _orientation = ori; _changed = true;
220 * Tie this sample group to the listener position, orientation and velocity
222 void tie_to_listener() { _tied_to_listener = true; }
233 bool _tied_to_listener;
237 SGQuatd _orientation;
240 std::vector< SGSharedPtr<SGSoundSample> > _removed_samples;
242 bool testForALError(string s);
243 bool testForError(void *p, string s);
245 void update_pos_and_orientation();
246 void update_sample_config( SGSoundSample *sound );
249 #endif // _SG_SAMPLE_GROUP_OPENAL_HXX