Panda3D
fmodAudioManager.h
1 // Filename: fmodAudioManager.h
2 // Created by: cort (January 22, 2003)
3 // Extended by: ben (October 22, 2003)
4 // Prior system by: cary
5 // Rewrite [for new Version of FMOD-EX] by: Stan Rosenbaum "Staque" - Spring 2006
6 //
7 //
8 ////////////////////////////////////////////////////////////////////
9 //
10 // PANDA 3D SOFTWARE
11 // Copyright (c) Carnegie Mellon University. All rights reserved.
12 //
13 // All use of this software is subject to the terms of the revised BSD
14 // license. You should have received a copy of this license along
15 // with this source code in a file named "LICENSE."
16 //
17 ////////////////////////////////////////////////////////////////////
18 
19 
20 ////////////////////////////////////////////////////////////////////
21 //
22 //Hello, all future Panda audio code people! This is my errata
23 //documentation to help any future programmer maintain FMOD and PANDA.
24 //
25 //This documentation more then that is needed, but I wanted to go all
26 //out, with the documentation. Because I was a totally newbie at
27 //programming [especially with C/C++] this semester I want to make
28 //sure future code maintainers have that insight I did not when
29 //starting on the PANDA project here at the ETC/CMU.
30 //
31 //As of Spring 2006, Panda's FMOD audio support has been pretty much
32 //completely rewritten. This has been done so PANDA can use FMOD-EX
33 //[or AKA FMOD 4] and some of its new features.
34 //
35 //First, the FMOD-EX API itself has been completely rewritten compared
36 //to previous versions. FMOD now handles any type of audio files, wave
37 //audio [WAV, AIF, MP3, OGG, etc...] or musical file [MID, TRACKERS]
38 //as the same type of an object. The API has also been structured more
39 //like a sound studio, with 'sounds' and 'channels'. This will be
40 //covered more in the FmodAudioSound.h/.cxx sources.
41 //
42 //Second, FMOD now offers virtually unlimited sounds to be played at
43 //once via their virtual channels system. Actually the theoretical
44 //limit is around 4000, but that is still a lot. What you need to know
45 //about this, is that even thought you might only hear 32 sound being
46 //played at once, FMOD will keep playing any additional sounds, and
47 //swap those on virtual channels in and out with those on real
48 //channels depending on priority, or distance [if you are dealing with
49 //3D audio].
50 //
51 //Third, FMOD's DSP support has been added. So you can now add GLOBAL
52 //or SOUND specific DSP effects. Right not you can only use FMOD's
53 //built in DSP effects. But adding support for FMOD's support of VST
54 //effects shouldn't be that hard.
55 //
56 //As for the FmodManager itself, it is pretty straight forward, I
57 //hope. As a manager class, it will create the FMOD system with the
58 //"_system" variable which is an instance of FMOD::SYSTEM. (Actually,
59 //we create only one global _system variable now, and share it with
60 //all outstanding FmodManager objects--this appears to be the way FMOD
61 //wants to work.) The FmodManager class is also the one responsible
62 //for creation of Sounds, DSP, and maintaining the GLOBAL DSP chains
63 //[The GLOBAL DSP chain is the DSP Chain which affects ALL the
64 //sounds].
65 //
66 //Any way that is it for an intro, lets move on to looking at the rest
67 //of the code.
68 //
69 ////////////////////////////////////////////////////////////////////
70 
71 
72 #ifndef __FMOD_AUDIO_MANAGER_H__
73 #define __FMOD_AUDIO_MANAGER_H__
74 
75 //First the includes.
76 #include "pandabase.h"
77 #include "pset.h"
78 
79 #include "audioManager.h"
80 
81 //The Includes needed for FMOD
82 #include <fmod.hpp>
83 #include <fmod_errors.h>
84 
85 class FmodAudioSound;
86 
87 extern void fmod_audio_errcheck(const char *context, FMOD_RESULT n);
88 
89 class EXPCL_FMOD_AUDIO FmodAudioManager : public AudioManager {
90  friend class FmodAudioSound;
91 
92  public:
93 
94  //Constructor and Destructor
96  virtual ~FmodAudioManager();
97 
98  virtual bool is_valid();
99 
100  virtual PT(AudioSound) get_sound(const string&, bool positional = false, int mode=SM_heuristic);
101  virtual PT(AudioSound) get_sound(MovieAudio *, bool positional = false, int mode=SM_heuristic);
102 
103  virtual int getSpeakerSetup();
104  virtual void setSpeakerSetup(SpeakerModeCategory cat);
105 
106  virtual void set_volume(PN_stdfloat);
107  virtual PN_stdfloat get_volume() const;
108 
109  virtual void set_wavwriter(bool);
110 
111  virtual void set_active(bool);
112  virtual bool get_active() const;
113 
114  virtual void stop_all_sounds();
115 
116  virtual void update();
117 
118  // This controls the "set of ears" that listens to 3D spacialized sound
119  // px, py, pz are position coordinates. Can be 0.0f to ignore.
120  // vx, vy, vz are a velocity vector in UNITS PER SECOND (default: meters).
121  // fx, fy and fz are the respective components of a unit forward-vector
122  // ux, uy and uz are the respective components of a unit up-vector
123  // These changes will NOT be invoked until audio_3d_update() is called.
124  virtual void audio_3d_set_listener_attributes(PN_stdfloat px, PN_stdfloat py, PN_stdfloat pz,
125  PN_stdfloat vx, PN_stdfloat xy, PN_stdfloat xz,
126  PN_stdfloat fx, PN_stdfloat fy, PN_stdfloat fz,
127  PN_stdfloat ux, PN_stdfloat uy, PN_stdfloat uz);
128 
129  // REMOVE THIS ONE
130  virtual void audio_3d_get_listener_attributes(PN_stdfloat *px, PN_stdfloat *py, PN_stdfloat *pz,
131  PN_stdfloat *vx, PN_stdfloat *vy, PN_stdfloat *vz,
132  PN_stdfloat *fx, PN_stdfloat *fy, PN_stdfloat *fz,
133  PN_stdfloat *ux, PN_stdfloat *uy, PN_stdfloat *uz);
134 
135  // Control the "relative distance factor" for 3D spacialized audio. Default is 1.0
136  // Fmod uses meters internally, so give a float in Units-per meter
137  // Don't know what Miles uses.
138  virtual void audio_3d_set_distance_factor(PN_stdfloat factor);
139  virtual PN_stdfloat audio_3d_get_distance_factor() const;
140 
141  // Control the presence of the Doppler effect. Default is 1.0
142  // Exaggerated Doppler, use >1.0
143  // Diminshed Doppler, use <1.0
144  virtual void audio_3d_set_doppler_factor(PN_stdfloat factor);
145  virtual PN_stdfloat audio_3d_get_doppler_factor() const;
146 
147  // Exaggerate or diminish the effect of distance on sound. Default is 1.0
148  // Faster drop off, use >1.0
149  // Slower drop off, use <1.0
150  virtual void audio_3d_set_drop_off_factor(PN_stdfloat factor);
151  virtual PN_stdfloat audio_3d_get_drop_off_factor() const;
152 
153  //THESE ARE NOT USED ANYMORE.
154  //THEY ARE ONLY HERE BECAUSE THEY are still needed by Miles.
155  //THESE are stubs in FMOD-EX version
156  ////////////////////////////////////////////////////////////////////
157  virtual void set_concurrent_sound_limit(unsigned int limit = 0);
158  virtual unsigned int get_concurrent_sound_limit() const;
159  virtual void reduce_sounds_playing_to(unsigned int count);
160  virtual void uncache_sound(const string&);
161  virtual void clear_cache();
162  virtual void set_cache_limit(unsigned int count);
163  virtual unsigned int get_cache_limit() const;
164  ////////////////////////////////////////////////////////////////////
165 
166 private:
167  FMOD::DSP *make_dsp(const FilterProperties::FilterConfig &conf);
168  void update_dsp_chain(FMOD::DSP *head, FilterProperties *config);
169  virtual bool configure_filters(FilterProperties *config);
170 
171  private:
172  // This global lock protects all access to FMod library interfaces.
173  static ReMutex _lock;
174 
175  static FMOD::System *_system;
176  static pset<FmodAudioManager *> _all_managers;
177 
178  static bool _system_is_valid;
179 
180  static PN_stdfloat _distance_factor;
181  static PN_stdfloat _doppler_factor;
182  static PN_stdfloat _drop_off_factor;
183 
184  FMOD::ChannelGroup *_channelgroup;
185 
186  FMOD_VECTOR _position;
187  FMOD_VECTOR _velocity;
188  FMOD_VECTOR _forward;
189  FMOD_VECTOR _up;
190 
191  // DLS info for MIDI files
192  string _dlsname;
193  FMOD_CREATESOUNDEXINFO _midi_info;
194 
195  bool _is_valid;
196  bool _active;
197 
198  // The set of all sounds. Needed only to implement stop_all_sounds.
200  SoundSet _all_sounds;
201 
202  FMOD_OUTPUTTYPE _saved_outputtype;
203 
204  ////////////////////////////////////////////////////////////
205  //These are needed for Panda's Pointer System. DO NOT ERASE!
206  ////////////////////////////////////////////////////////////
207 
208  public:
209  static TypeHandle get_class_type() {
210  return _type_handle;
211  }
212  static void init_type() {
213  AudioManager::init_type();
214  register_type(_type_handle, "FmodAudioManager", AudioManager::get_class_type());
215  }
216  virtual TypeHandle get_type() const {
217  return get_class_type();
218  }
219  virtual TypeHandle force_init_type() {
220  init_type();
221  return get_class_type();
222  }
223 
224  private:
225  static TypeHandle _type_handle;
226 
227  ////////////////////////////////////////////////////////////
228  //DONE
229  ////////////////////////////////////////////////////////////
230 
231 };
232 
233 EXPCL_FMOD_AUDIO AudioManager *Create_FmodAudioManager();
234 
235 
236 #endif /* __FMOD_AUDIO_MANAGER_H__ */
virtual bool configure_filters(FilterProperties *config)
Configures the global DSP filter chain.
void set_volume(PN_stdfloat volume=1.0)
0.0 to 1.0 scale of volume converted to Fmod&#39;s internal 0.0 to 255.0 scale.
Stores a configuration for a set of audio DSP filters.
bool get_active() const
Returns whether the sound has been marked "active".
virtual void update()
Must be called every frame.
void set_active(bool active=true)
Sets whether the sound is marked "active".
This is our own Panda specialization on the default STL set.
Definition: pset.h:52
TypeHandle is the identifier used to differentiate C++ class types.
Definition: typeHandle.h:85
A MovieAudio is actually any source that provides a sequence of audio samples.
Definition: movieAudio.h:48
A reentrant mutex.
Definition: reMutex.h:36
PN_stdfloat get_volume() const
Gets the current volume of a sound.