Panda3D
audioManager.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 audioManager.h
10  * @author skyler
11  * @date 2001-06-06
12  * Prior system by: cary
13  */
14 
15 #ifndef __AUDIO_MANAGER_H__
16 #define __AUDIO_MANAGER_H__
17 
18 #include "config_audio.h"
19 #include "audioSound.h"
20 #include "luse.h"
21 #include "filterProperties.h"
22 #include "movieAudio.h"
23 #include "atomicAdjust.h"
24 
25 typedef AudioManager *Create_AudioManager_proc();
26 
27 
28 class EXPCL_PANDA_AUDIO AudioManager : public TypedReferenceCount {
29 PUBLISHED:
30 
31  enum SpeakerModeCategory {
32  // These enumerants line up one-to-one with the FMOD SPEAKERMODE
33  // enumerants.
34  SPEAKERMODE_raw,
35  SPEAKERMODE_mono,
36  SPEAKERMODE_stereo,
37  SPEAKERMODE_quad,
38  SPEAKERMODE_surround,
39  SPEAKERMODE_5point1,
40  SPEAKERMODE_7point1,
41  SPEAKERMODE_max,
42  SPEAKERMODE_COUNT
43  };
44 
45 
46  enum SpeakerId {
47  SPK_none,
48  SPK_frontleft,
49  SPK_frontright,
50  SPK_center,
51  SPK_sub,
52  SPK_backleft,
53  SPK_backright,
54  SPK_sideleft,
55  SPK_sideright,
56  SPK_COUNT,
57  };
58 
59  enum StreamMode {
60  SM_heuristic,
61  SM_sample,
62  SM_stream,
63  };
64 
65  virtual int get_speaker_setup();
66  virtual void set_speaker_setup(SpeakerModeCategory cat);
67  virtual bool configure_filters(FilterProperties *config);
68 
69  // Create an AudioManager for each category of sounds you have. E.g.
70  // MySoundEffects = create_AudioManager::AudioManager(); MyMusicManager =
71  // create_AudioManager::AudioManager(); ... my_sound =
72  // MySoundEffects.get_sound("neatSfx.mp3"); my_music =
73  // MyMusicManager.get_sound("introTheme.mid");
74 
75  static PT(AudioManager) create_AudioManager();
76  virtual ~AudioManager();
77 
78  virtual void shutdown();
79 
80  // If you're interested in knowing whether this audio manager is valid,
81  // here's the call to do it. It is not necessary to check whether the audio
82  // manager is valid before making other calls. You are free to use an
83  // invalid sound manager, you may get silent sounds from it though. The
84  // sound manager and the sounds it creates should not crash the application
85  // even when the objects are not valid.
86  virtual bool is_valid() = 0;
87 
88  // Get a sound:
89  virtual PT(AudioSound) get_sound(const Filename &file_name, bool positional = false, int mode=SM_heuristic) = 0;
90  virtual PT(AudioSound) get_sound(MovieAudio *source, bool positional = false, int mode=SM_heuristic) = 0;
91 
92  PT(AudioSound) get_null_sound();
93 
94  // Tell the AudioManager there is no need to keep this one cached. This
95  // doesn't break any connection between AudioSounds that have already given
96  // by get_sound() from this manager. It's only affecting whether the
97  // AudioManager keeps a copy of the sound in its poolcache.
98  virtual void uncache_sound(const Filename &file_name) = 0;
99  virtual void clear_cache() = 0;
100  virtual void set_cache_limit(unsigned int count) = 0;
101  virtual unsigned int get_cache_limit() const = 0;
102 
103  // Control volume: FYI: If you start a sound with the volume off and turn
104  // the volume up later, you'll hear the sound playing at that late point. 0
105  // = minimum; 1.0 = maximum. inits to 1.0.
106  virtual void set_volume(PN_stdfloat volume) = 0;
107  virtual PN_stdfloat get_volume() const = 0;
108 
109 /*
110  * Turn the manager on or off. If you play a sound while the manager is
111  * inactive, it won't start. If you deactivate the manager while sounds are
112  * playing, they'll stop. If you activate the manager while looping sounds
113  * are playing (those that have a loop_count of zero), they will start playing
114  * from the beginning of their loop. inits to true.
115  */
116  virtual void set_active(bool flag) = 0;
117  virtual bool get_active() const = 0;
118 
119  // This controls the number of sounds that you allow at once. This is more
120  // of a user choice -- it avoids talk over and the creation of a cacophony.
121  // It can also be used to help performance. 0 == unlimited. 1 == mutually
122  // exclusive (one sound at a time). Which is an example of: n == allow n
123  // sounds to be playing at the same time.
124  virtual void set_concurrent_sound_limit(unsigned int limit = 0) = 0;
125  virtual unsigned int get_concurrent_sound_limit() const = 0;
126 
127  // This is likely to be a utility function for the concurrent_sound_limit
128  // options. It is exposed as an API, because it's reasonable that it may be
129  // useful to be here. It reduces the number of concurrently playing sounds
130  // to count by some implementation specific means. If the number of sounds
131  // currently playing is at or below count then there is no effect.
132  virtual void reduce_sounds_playing_to(unsigned int count) = 0;
133 
134  // Stop playback on all sounds managed by this manager. This is effectively
135  // the same as reduce_sounds_playing_to(0), but this call may be for
136  // efficient on some implementations.
137  virtual void stop_all_sounds() = 0;
138 
139  // This should be called every frame. Failure to call could cause problems.
140  virtual void update();
141 
142  // This controls the "set of ears" that listens to 3D spacialized sound px,
143  // py, pz are position coordinates. vx, vy, vz are a velocity vector in
144  // UNITS PER SECOND (default: meters). fx, fy and fz are the respective
145  // components of a unit forward-vector ux, uy and uz are the respective
146  // components of a unit up-vector
147  virtual void audio_3d_set_listener_attributes(PN_stdfloat px, PN_stdfloat py, PN_stdfloat pz,
148  PN_stdfloat vx, PN_stdfloat vy, PN_stdfloat vz,
149  PN_stdfloat fx, PN_stdfloat fy, PN_stdfloat fz,
150  PN_stdfloat ux, PN_stdfloat uy, PN_stdfloat uz);
151  virtual void audio_3d_get_listener_attributes(PN_stdfloat *px, PN_stdfloat *py, PN_stdfloat *pz,
152  PN_stdfloat *vx, PN_stdfloat *vy, PN_stdfloat *vz,
153  PN_stdfloat *fx, PN_stdfloat *fy, PN_stdfloat *fz,
154  PN_stdfloat *ux, PN_stdfloat *uy, PN_stdfloat *uz);
155 
156  // Control the "relative scale that sets the distance factor" units for 3D
157  // spacialized audio. This is a float in units-per-meter. Default value is
158  // 1.0, which means that Panda units are understood as meters; for e.g.
159  // feet, set 3.28. This factor is applied only to Fmod and OpenAL at the
160  // moment.
161  virtual void audio_3d_set_distance_factor(PN_stdfloat factor);
162  virtual PN_stdfloat audio_3d_get_distance_factor() const;
163 
164  // Control the presence of the Doppler effect. Default is 1.0 Exaggerated
165  // Doppler, use >1.0 Diminshed Doppler, use <1.0
166  virtual void audio_3d_set_doppler_factor(PN_stdfloat factor);
167  virtual PN_stdfloat audio_3d_get_doppler_factor() const;
168 
169  // Exaggerate or diminish the effect of distance on sound. Default is 1.0
170  // Valid range is 0 to 10 Faster drop off, use >1.0 Slower drop off, use
171  // <1.0
172  virtual void audio_3d_set_drop_off_factor(PN_stdfloat factor);
173  virtual PN_stdfloat audio_3d_get_drop_off_factor() const;
174 
175  static Filename get_dls_pathname();
176  MAKE_PROPERTY(dls_pathname, get_dls_pathname);
177 
178  virtual void output(std::ostream &out) const;
179  virtual void write(std::ostream &out) const;
180 
181  // set_speaker_configuration is a Miles only method.
182  virtual void set_speaker_configuration(LVecBase3 *speaker1, LVecBase3 *speaker2=nullptr, LVecBase3 *speaker3=nullptr, LVecBase3 *speaker4=nullptr, LVecBase3 *speaker5=nullptr, LVecBase3 *speaker6=nullptr, LVecBase3 *speaker7=nullptr, LVecBase3 *speaker8=nullptr, LVecBase3 *speaker9=nullptr);
183 
184 public:
185  static void register_AudioManager_creator(Create_AudioManager_proc* proc);
186 
187 protected:
188  friend class AudioSound;
189 
190  // Avoid adding data members (instance variables) to this mostly abstract
191  // base class. This allows implementors of various sound systems the best
192  // flexibility.
193 
194  static Create_AudioManager_proc* _create_AudioManager;
195  AtomicAdjust::Pointer _null_sound;
196 
197  AudioManager();
198 
199 public:
200  static TypeHandle get_class_type() {
201  return _type_handle;
202  }
203  static void init_type() {
204  TypedReferenceCount::init_type();
205  register_type(_type_handle, "AudioManager",
206  TypedReferenceCount::get_class_type());
207  }
208  virtual TypeHandle get_type() const {
209  return get_class_type();
210  }
211  virtual TypeHandle force_init_type() {init_type(); return get_class_type();}
212 
213 private:
214  static TypeHandle _type_handle;
215 };
216 
217 inline std::ostream &
218 operator << (std::ostream &out, const AudioManager &mgr) {
219  mgr.output(out);
220  return out;
221 }
222 
223 #include "audioManager.I"
224 
225 #endif /* __AUDIO_MANAGER_H__ */
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.h
PANDA 3D SOFTWARE Copyright (c) Carnegie Mellon University.
TypedReferenceCount
A base class for things which need to inherit from both TypedObject and from ReferenceCount.
Definition: typedReferenceCount.h:31
TypeHandle
TypeHandle is the identifier used to differentiate C++ class types.
Definition: typeHandle.h:81
luse.h
PANDA 3D SOFTWARE Copyright (c) Carnegie Mellon University.
atomicAdjust.h
PANDA 3D SOFTWARE Copyright (c) Carnegie Mellon University.
movieAudio.h
PANDA 3D SOFTWARE Copyright (c) Carnegie Mellon University.
audioManager.I
PANDA 3D SOFTWARE Copyright (c) Carnegie Mellon University.
config_audio.h
PANDA 3D SOFTWARE Copyright (c) Carnegie Mellon University.
MovieAudio
A MovieAudio is actually any source that provides a sequence of audio samples.
Definition: movieAudio.h:44
AudioSound
Definition: audioSound.h:25
FilterProperties
Stores a configuration for a set of audio DSP filters.
Definition: filterProperties.h:24
AudioManager
Definition: audioManager.h:28
audioSound.h
PANDA 3D SOFTWARE Copyright (c) Carnegie Mellon University.
Filename
The name of a file, such as a texture file or an Egg file.
Definition: filename.h:39