Panda3D

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