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