Panda3D

audioManager.h

00001 // Filename: audioManager.h
00002 // Created by:  skyler (June 6, 2001)
00003 // Prior system by: cary
00004 //
00005 ////////////////////////////////////////////////////////////////////
00006 //
00007 // PANDA 3D SOFTWARE
00008 // Copyright (c) Carnegie Mellon University.  All rights reserved.
00009 //
00010 // All use of this software is subject to the terms of the revised BSD
00011 // license.  You should have received a copy of this license along
00012 // with this source code in a file named "LICENSE."
00013 //
00014 ////////////////////////////////////////////////////////////////////
00015 
00016 #ifndef __AUDIO_MANAGER_H__
00017 #define __AUDIO_MANAGER_H__
00018 
00019 #include "config_audio.h"
00020 #include "audioSound.h"
00021 #include "luse.h"
00022 #include "filterProperties.h"
00023 #include "movieAudio.h"
00024 #include "atomicAdjust.h"
00025 
00026 typedef AudioManager *Create_AudioManager_proc();
00027 
00028 
00029 class EXPCL_PANDA_AUDIO AudioManager : public TypedReferenceCount {
00030 PUBLISHED:
00031 
00032   enum SpeakerModeCategory {
00033     // These enumerants line up one-to-one
00034     // with the FMOD SPEAKERMODE enumerants.
00035     SPEAKERMODE_raw, 
00036     SPEAKERMODE_mono, 
00037     SPEAKERMODE_stereo, 
00038     SPEAKERMODE_quad, 
00039     SPEAKERMODE_surround, 
00040     SPEAKERMODE_5point1, 
00041     SPEAKERMODE_7point1, 
00042     SPEAKERMODE_prologic, 
00043     SPEAKERMODE_max,
00044     SPEAKERMODE_COUNT
00045   };
00046   
00047 
00048   enum SpeakerId {
00049     SPK_none,
00050     SPK_frontleft,
00051     SPK_frontright,
00052     SPK_center,
00053     SPK_sub,
00054     SPK_backleft,
00055     SPK_backright,
00056     SPK_sideleft,
00057     SPK_sideright,
00058     SPK_COUNT,
00059   };
00060 
00061   enum StreamMode {
00062     SM_heuristic,
00063     SM_sample,
00064     SM_stream,
00065   };
00066   
00067   virtual int getSpeakerSetup();
00068   virtual void setSpeakerSetup(SpeakerModeCategory cat);
00069   virtual bool configure_filters(FilterProperties *config);
00070   
00071   // Create an AudioManager for each category of sounds you have.
00072   // E.g.
00073   //   MySoundEffects = create_AudioManager::AudioManager();
00074   //   MyMusicManager = create_AudioManager::AudioManager();
00075   //   ...
00076   //   my_sound = MySoundEffects.get_sound("neatSfx.mp3");
00077   //   my_music = MyMusicManager.get_sound("introTheme.mid");
00078 
00079   static PT(AudioManager) create_AudioManager();
00080   virtual ~AudioManager();
00081 
00082   virtual void shutdown();
00083   
00084   // If you're interested in knowing whether this audio manager
00085   // is valid, here's the call to do it.  It is not necessary
00086   // to check whether the audio manager is valid before making other
00087   // calls.  You are free to use an invalid sound manager, you
00088   // may get silent sounds from it though.  The sound manager and
00089   // the sounds it creates should not crash the application even
00090   // when the objects are not valid.
00091   virtual bool is_valid() = 0;
00092   
00093   // Get a sound:
00094   virtual PT(AudioSound) get_sound(const string& file_name, bool positional = false, int mode=SM_heuristic) = 0;
00095   virtual PT(AudioSound) get_sound(MovieAudio *source, bool positional = false, int mode=SM_heuristic) = 0;
00096 
00097   PT(AudioSound) get_null_sound();
00098 
00099   // Tell the AudioManager there is no need to keep this one cached.
00100   // This doesn't break any connection between AudioSounds that have
00101   // already given by get_sound() from this manager.  It's
00102   // only affecting whether the AudioManager keeps a copy of the sound
00103   // in its pool/cache.
00104   virtual void uncache_sound(const string& file_name) = 0;
00105   virtual void clear_cache() = 0;
00106   virtual void set_cache_limit(unsigned int count) = 0;
00107   virtual unsigned int get_cache_limit() const = 0;
00108 
00109   // Control volume:
00110   // FYI:
00111   //   If you start a sound with the volume off and turn the volume 
00112   //   up later, you'll hear the sound playing at that late point.
00113   // 0 = minimum; 1.0 = maximum.
00114   // inits to 1.0.
00115   virtual void set_volume(PN_stdfloat volume) = 0;
00116   virtual PN_stdfloat get_volume() const = 0;
00117   
00118   // Turn the manager on or off.
00119   // If you play a sound while the manager is inactive, it won't start.
00120   // If you deactivate the manager while sounds are playing, they'll
00121   // stop.
00122   // If you activate the manager while looping sounds are playing
00123   // (those that have a loop_count of zero),
00124   // they will start playing from the beginning of their loop.
00125   // inits to true.
00126   virtual void set_active(bool flag) = 0;
00127   virtual bool get_active() const = 0;
00128   
00129   // This controls the number of sounds that you allow at once.  This
00130   // is more of a user choice -- it avoids talk over and the creation
00131   // of a cacophony.
00132   // It can also be used to help performance.
00133   // 0 == unlimited.
00134   // 1 == mutually exclusive (one sound at a time).  Which is an example of:
00135   // n == allow n sounds to be playing at the same time.
00136   virtual void set_concurrent_sound_limit(unsigned int limit = 0) = 0;
00137   virtual unsigned int get_concurrent_sound_limit() const = 0;
00138   
00139   // This is likely to be a utility function for the concurrent_sound_limit
00140   // options.  It is exposed as an API, because it's reasonable that it
00141   // may be useful to be here.  It reduces the number of concurrently
00142   // playing sounds to count by some implementation specific means.
00143   // If the number of sounds currently playing is at or below count then
00144   // there is no effect.
00145   virtual void reduce_sounds_playing_to(unsigned int count) = 0;
00146 
00147   // Stop playback on all sounds managed by this manager.
00148   // This is effectively the same as reduce_sounds_playing_to(0), but
00149   // this call may be for efficient on some implementations.
00150   virtual void stop_all_sounds() = 0;
00151 
00152   // This should be called every frame.  Failure to call could
00153   // cause problems.
00154   virtual void update();
00155 
00156   // This controls the "set of ears" that listens to 3D spacialized sound
00157   // px, py, pz are position coordinates. 
00158   // vx, vy, vz are a velocity vector in UNITS PER SECOND (default: meters). 
00159   // fx, fy and fz are the respective components of a unit forward-vector
00160   // ux, uy and uz are the respective components of a unit up-vector
00161   virtual void audio_3d_set_listener_attributes(PN_stdfloat px, PN_stdfloat py, PN_stdfloat pz,
00162                                                 PN_stdfloat vx, PN_stdfloat vy, PN_stdfloat vz,
00163                                                 PN_stdfloat fx, PN_stdfloat fy, PN_stdfloat fz,
00164                                                 PN_stdfloat ux, PN_stdfloat uy, PN_stdfloat uz);
00165   virtual void audio_3d_get_listener_attributes(PN_stdfloat *px, PN_stdfloat *py, PN_stdfloat *pz,
00166                                                 PN_stdfloat *vx, PN_stdfloat *vy, PN_stdfloat *vz,
00167                                                 PN_stdfloat *fx, PN_stdfloat *fy, PN_stdfloat *fz,
00168                                                 PN_stdfloat *ux, PN_stdfloat *uy, PN_stdfloat *uz);
00169  
00170   // Control the "relative scale that sets the distance factor" units for 3D spacialized audio. Default is 1.0
00171   // Fmod uses meters internally, so give a float in Units-per meter
00172   // Don't know what Miles uses.
00173   // Default is 1.0 which is adjust in panda to be feet.
00174   virtual void audio_3d_set_distance_factor(PN_stdfloat factor);
00175   virtual PN_stdfloat audio_3d_get_distance_factor() const;
00176 
00177   // Control the presence of the Doppler effect. Default is 1.0
00178   // Exaggerated Doppler, use >1.0
00179   // Diminshed Doppler, use <1.0
00180   virtual void audio_3d_set_doppler_factor(PN_stdfloat factor);
00181   virtual PN_stdfloat audio_3d_get_doppler_factor() const;
00182 
00183   // Exaggerate or diminish the effect of distance on sound. Default is 1.0
00184   // Valid range is 0 to 10
00185   // Faster drop off, use >1.0
00186   // Slower drop off, use <1.0
00187   virtual void audio_3d_set_drop_off_factor(PN_stdfloat factor);
00188   virtual PN_stdfloat audio_3d_get_drop_off_factor() const;
00189 
00190   static Filename get_dls_pathname();
00191 
00192   virtual void output(ostream &out) const;
00193   virtual void write(ostream &out) const;
00194 
00195   // set_speaker_configuration is a Miles only method.
00196   virtual void set_speaker_configuration(LVecBase3 *speaker1, LVecBase3 *speaker2=NULL, LVecBase3 *speaker3=NULL, LVecBase3 *speaker4=NULL, LVecBase3 *speaker5=NULL, LVecBase3 *speaker6=NULL, LVecBase3 *speaker7=NULL, LVecBase3 *speaker8=NULL, LVecBase3 *speaker9=NULL);
00197 
00198 public:
00199   static void register_AudioManager_creator(Create_AudioManager_proc* proc);
00200 
00201 protected:
00202   friend class AudioSound;
00203   
00204   // Avoid adding data members (instance variables) to this mostly abstract
00205   // base class.  This allows implementors of various sound systems the
00206   // best flexibility.
00207   
00208   static Create_AudioManager_proc* _create_AudioManager;
00209   AtomicAdjust::Pointer _null_sound;
00210 
00211   AudioManager();
00212 
00213 public:
00214   static TypeHandle get_class_type() {
00215     return _type_handle;
00216   }
00217   static void init_type() {
00218     TypedReferenceCount::init_type();
00219     register_type(_type_handle, "AudioManager",
00220                   TypedReferenceCount::get_class_type());
00221   }
00222   virtual TypeHandle get_type() const {
00223     return get_class_type();
00224   }
00225   virtual TypeHandle force_init_type() {init_type(); return get_class_type();}
00226 
00227 private:
00228   static TypeHandle _type_handle;
00229 };
00230 
00231 inline ostream &
00232 operator << (ostream &out, const AudioManager &mgr) {
00233   mgr.output(out);
00234   return out;
00235 }
00236 
00237 #include "audioManager.I"
00238 
00239 #endif /* __AUDIO_MANAGER_H__ */
 All Classes Functions Variables Enumerations