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  // Turn the manager on or off. If you play a sound while the manager is
110  // inactive, it won't start. If you deactivate the manager while sounds are
111  // playing, they'll stop. If you activate the manager while looping sounds
112  // are playing (those that have a loop_count of zero), they will start
113  // playing from the beginning of their loop. Defaults to true.
114  virtual void set_active(bool flag) = 0;
115  virtual bool get_active() const = 0;
116 
117  // This controls the number of sounds that you allow at once. This is more
118  // of a user choice -- it avoids talk over and the creation of a cacophony.
119  // It can also be used to help performance. 0 == unlimited. 1 == mutually
120  // exclusive (one sound at a time). Which is an example of: n == allow n
121  // sounds to be playing at the same time.
122  virtual void set_concurrent_sound_limit(unsigned int limit = 0) = 0;
123  virtual unsigned int get_concurrent_sound_limit() const = 0;
124 
125  // This is likely to be a utility function for the concurrent_sound_limit
126  // options. It is exposed as an API, because it's reasonable that it may be
127  // useful to be here. It reduces the number of concurrently playing sounds
128  // to count by some implementation specific means. If the number of sounds
129  // currently playing is at or below count then there is no effect.
130  virtual void reduce_sounds_playing_to(unsigned int count) = 0;
131 
132  // Stop playback on all sounds managed by this manager. This is effectively
133  // the same as reduce_sounds_playing_to(0), but this call may be for
134  // efficient on some implementations.
135  virtual void stop_all_sounds() = 0;
136 
137  // This should be called every frame. Failure to call could cause problems.
138  virtual void update();
139 
140  // This controls the "set of ears" that listens to 3D spacialized sound px,
141  // py, pz are position coordinates. vx, vy, vz are a velocity vector in
142  // UNITS PER SECOND (default: meters). fx, fy and fz are the respective
143  // components of a unit forward-vector ux, uy and uz are the respective
144  // components of a unit up-vector
145  virtual void audio_3d_set_listener_attributes(PN_stdfloat px, PN_stdfloat py, PN_stdfloat pz,
146  PN_stdfloat vx, PN_stdfloat vy, PN_stdfloat vz,
147  PN_stdfloat fx, PN_stdfloat fy, PN_stdfloat fz,
148  PN_stdfloat ux, PN_stdfloat uy, PN_stdfloat uz);
149  virtual void audio_3d_get_listener_attributes(PN_stdfloat *px, PN_stdfloat *py, PN_stdfloat *pz,
150  PN_stdfloat *vx, PN_stdfloat *vy, PN_stdfloat *vz,
151  PN_stdfloat *fx, PN_stdfloat *fy, PN_stdfloat *fz,
152  PN_stdfloat *ux, PN_stdfloat *uy, PN_stdfloat *uz);
153 
154  // Control the "relative scale that sets the distance factor" units for 3D
155  // spacialized audio. This is a float in units-per-meter. Default value is
156  // 1.0, which means that Panda units are understood as meters; for e.g.
157  // feet, set 3.28. This factor is applied only to Fmod and OpenAL at the
158  // moment.
159  virtual void audio_3d_set_distance_factor(PN_stdfloat factor);
160  virtual PN_stdfloat audio_3d_get_distance_factor() const;
161 
162  // Control the presence of the Doppler effect. Default is 1.0 Exaggerated
163  // Doppler, use >1.0 Diminshed Doppler, use <1.0
164  virtual void audio_3d_set_doppler_factor(PN_stdfloat factor);
165  virtual PN_stdfloat audio_3d_get_doppler_factor() const;
166 
167  // Exaggerate or diminish the effect of distance on sound. Default is 1.0
168  // Valid range is 0 to 10 Faster drop off, use >1.0 Slower drop off, use
169  // <1.0
170  virtual void audio_3d_set_drop_off_factor(PN_stdfloat factor);
171  virtual PN_stdfloat audio_3d_get_drop_off_factor() const;
172 
173  static Filename get_dls_pathname();
174  MAKE_PROPERTY(dls_pathname, get_dls_pathname);
175 
176  virtual void output(std::ostream &out) const;
177  virtual void write(std::ostream &out) const;
178 
179  // set_speaker_configuration is a Miles only method.
180  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);
181 
182 public:
183  static void register_AudioManager_creator(Create_AudioManager_proc* proc);
184 
185 protected:
186  friend class AudioSound;
187 
188  // Avoid adding data members (instance variables) to this mostly abstract
189  // base class. This allows implementors of various sound systems the best
190  // flexibility.
191 
192  static Create_AudioManager_proc* _create_AudioManager;
193  AtomicAdjust::Pointer _null_sound;
194 
195  AudioManager();
196 
197 public:
198  static TypeHandle get_class_type() {
199  return _type_handle;
200  }
201  static void init_type() {
202  TypedReferenceCount::init_type();
203  register_type(_type_handle, "AudioManager",
204  TypedReferenceCount::get_class_type());
205  }
206  virtual TypeHandle get_type() const {
207  return get_class_type();
208  }
209  virtual TypeHandle force_init_type() {init_type(); return get_class_type();}
210 
211 private:
212  static TypeHandle _type_handle;
213 };
214 
215 inline std::ostream &
216 operator << (std::ostream &out, const AudioManager &mgr) {
217  mgr.output(out);
218  return out;
219 }
220 
221 #include "audioManager.I"
222 
223 #endif /* __AUDIO_MANAGER_H__ */
PANDA 3D SOFTWARE Copyright (c) Carnegie Mellon University.
PANDA 3D SOFTWARE Copyright (c) Carnegie Mellon University.
PANDA 3D SOFTWARE Copyright (c) Carnegie Mellon University.
The name of a file, such as a texture file or an Egg file.
Definition: filename.h:39
Stores a configuration for a set of audio DSP filters.
A MovieAudio is actually any source that provides a sequence of audio samples.
Definition: movieAudio.h:44
TypeHandle is the identifier used to differentiate C++ class types.
Definition: typeHandle.h:81
A base class for things which need to inherit from both TypedObject and from ReferenceCount.
PANDA 3D SOFTWARE Copyright (c) Carnegie Mellon University.
PANDA 3D SOFTWARE Copyright (c) Carnegie Mellon University.
PANDA 3D SOFTWARE Copyright (c) Carnegie Mellon University.
PANDA 3D SOFTWARE Copyright (c) Carnegie Mellon University.
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