Panda3D
 All Classes Functions Variables Enumerations
fmodAudioManager.h
00001 // Filename: fmodAudioManager.h
00002 // Created by:  cort (January 22, 2003)
00003 // Extended by: ben  (October 22, 2003)
00004 // Prior system by: cary
00005 // Rewrite [for new Version of FMOD-EX] by: Stan Rosenbaum "Staque" - Spring 2006
00006 //
00007 //
00008 ////////////////////////////////////////////////////////////////////
00009 //
00010 // PANDA 3D SOFTWARE
00011 // Copyright (c) Carnegie Mellon University.  All rights reserved.
00012 //
00013 // All use of this software is subject to the terms of the revised BSD
00014 // license.  You should have received a copy of this license along
00015 // with this source code in a file named "LICENSE."
00016 //
00017 ////////////////////////////////////////////////////////////////////
00018 
00019 
00020 ////////////////////////////////////////////////////////////////////
00021 //
00022 //Hello, all future Panda audio code people! This is my errata
00023 //documentation to help any future programmer maintain FMOD and PANDA.
00024 //
00025 //This documentation more then that is needed, but I wanted to go all
00026 //out, with the documentation. Because I was a totally newbie at
00027 //programming [especially with C/C++] this semester I want to make
00028 //sure future code maintainers have that insight I did not when
00029 //starting on the PANDA project here at the ETC/CMU.
00030 //
00031 //As of Spring 2006, Panda's FMOD audio support has been pretty much
00032 //completely rewritten. This has been done so PANDA can use FMOD-EX
00033 //[or AKA FMOD 4] and some of its new features.
00034 //
00035 //First, the FMOD-EX API itself has been completely rewritten compared
00036 //to previous versions. FMOD now handles any type of audio files, wave
00037 //audio [WAV, AIF, MP3, OGG, etc...] or musical file [MID, TRACKERS]
00038 //as the same type of an object. The API has also been structured more
00039 //like a sound studio, with 'sounds' and 'channels'. This will be
00040 //covered more in the FmodAudioSound.h/.cxx sources.
00041 //
00042 //Second, FMOD now offers virtually unlimited sounds to be played at
00043 //once via their virtual channels system. Actually the theoretical
00044 //limit is around 4000, but that is still a lot. What you need to know
00045 //about this, is that even thought you might only hear 32 sound being
00046 //played at once, FMOD will keep playing any additional sounds, and
00047 //swap those on virtual channels in and out with those on real
00048 //channels depending on priority, or distance [if you are dealing with
00049 //3D audio].
00050 //
00051 //Third, FMOD's DSP support has been added. So you can now add GLOBAL
00052 //or SOUND specific DSP effects. Right not you can only use FMOD's
00053 //built in DSP effects.  But adding support for FMOD's support of VST
00054 //effects shouldn't be that hard.
00055 //
00056 //As for the FmodManager itself, it is pretty straight forward, I
00057 //hope. As a manager class, it will create the FMOD system with the
00058 //"_system" variable which is an instance of FMOD::SYSTEM. (Actually,
00059 //we create only one global _system variable now, and share it with
00060 //all outstanding FmodManager objects--this appears to be the way FMOD
00061 //wants to work.)  The FmodManager class is also the one responsible
00062 //for creation of Sounds, DSP, and maintaining the GLOBAL DSP chains
00063 //[The GLOBAL DSP chain is the DSP Chain which affects ALL the
00064 //sounds].
00065 //
00066 //Any way that is it for an intro, lets move on to looking at the rest
00067 //of the code.
00068 //
00069 ////////////////////////////////////////////////////////////////////
00070 
00071 
00072 #ifndef __FMOD_AUDIO_MANAGER_H__
00073 #define __FMOD_AUDIO_MANAGER_H__
00074 
00075 //First the includes.
00076 #include "pandabase.h"
00077 #include "pset.h"
00078 
00079 #ifdef HAVE_FMODEX //[
00080 
00081 #include "audioManager.h"
00082 
00083 //The Includes needed for FMOD
00084 #include <fmod.hpp>
00085 #include <fmod_errors.h>
00086 
00087 class FmodAudioSound;
00088 
00089 extern void fmod_audio_errcheck(const char *context, FMOD_RESULT n);
00090 
00091 class EXPCL_FMOD_AUDIO FmodAudioManager : public AudioManager {
00092   friend class FmodAudioSound;
00093 
00094  public:
00095 
00096   //Constructor and Destructor
00097   FmodAudioManager();
00098   virtual ~FmodAudioManager();
00099 
00100   virtual bool is_valid();
00101           
00102   virtual PT(AudioSound) get_sound(const string&, bool positional = false, int mode=SM_heuristic);
00103   virtual PT(AudioSound) get_sound(MovieAudio *,  bool positional = false, int mode=SM_heuristic);
00104     
00105   virtual int getSpeakerSetup();
00106   virtual void setSpeakerSetup(SpeakerModeCategory cat);
00107 
00108   virtual void set_volume(PN_stdfloat);
00109   virtual PN_stdfloat get_volume() const;
00110           
00111   virtual void set_active(bool);
00112   virtual bool get_active() const;
00113 
00114   virtual void stop_all_sounds();
00115 
00116   virtual void update();
00117   
00118   // This controls the "set of ears" that listens to 3D spacialized sound
00119   // px, py, pz are position coordinates. Can be 0.0f to ignore.
00120   // vx, vy, vz are a velocity vector in UNITS PER SECOND (default: meters).
00121   // fx, fy and fz are the respective components of a unit forward-vector
00122   // ux, uy and uz are the respective components of a unit up-vector
00123   // These changes will NOT be invoked until audio_3d_update() is called.
00124   virtual void audio_3d_set_listener_attributes(PN_stdfloat px, PN_stdfloat py, PN_stdfloat pz,
00125                                                 PN_stdfloat vx, PN_stdfloat xy, PN_stdfloat xz, 
00126                                                 PN_stdfloat fx, PN_stdfloat fy, PN_stdfloat fz,
00127                                                 PN_stdfloat ux, PN_stdfloat uy, PN_stdfloat uz);
00128 
00129   // REMOVE THIS ONE
00130   virtual void audio_3d_get_listener_attributes(PN_stdfloat *px, PN_stdfloat *py, PN_stdfloat *pz,
00131                                                 PN_stdfloat *vx, PN_stdfloat *vy, PN_stdfloat *vz,
00132                                                 PN_stdfloat *fx, PN_stdfloat *fy, PN_stdfloat *fz,
00133                                                 PN_stdfloat *ux, PN_stdfloat *uy, PN_stdfloat *uz);
00134           
00135   // Control the "relative distance factor" for 3D spacialized audio. Default is 1.0
00136   // Fmod uses meters internally, so give a float in Units-per meter
00137   // Don't know what Miles uses.
00138   virtual void audio_3d_set_distance_factor(PN_stdfloat factor);
00139   virtual PN_stdfloat audio_3d_get_distance_factor() const;
00140 
00141   // Control the presence of the Doppler effect. Default is 1.0
00142   // Exaggerated Doppler, use >1.0
00143   // Diminshed Doppler, use <1.0
00144   virtual void audio_3d_set_doppler_factor(PN_stdfloat factor);
00145   virtual PN_stdfloat audio_3d_get_doppler_factor() const;
00146 
00147   // Exaggerate or diminish the effect of distance on sound. Default is 1.0
00148   // Faster drop off, use >1.0
00149   // Slower drop off, use <1.0
00150   virtual void audio_3d_set_drop_off_factor(PN_stdfloat factor);
00151   virtual PN_stdfloat audio_3d_get_drop_off_factor() const;
00152 
00153   //THESE ARE NOT USED ANYMORE.
00154   //THEY ARE ONLY HERE BECAUSE THEY are still needed by Miles.
00155   //THESE are stubs in FMOD-EX version
00156   ////////////////////////////////////////////////////////////////////
00157   virtual void set_concurrent_sound_limit(unsigned int limit = 0);
00158   virtual unsigned int get_concurrent_sound_limit() const;
00159   virtual void reduce_sounds_playing_to(unsigned int count);
00160   virtual void uncache_sound(const string&);
00161   virtual void clear_cache();
00162   virtual void set_cache_limit(unsigned int count);
00163   virtual unsigned int get_cache_limit() const;
00164   ////////////////////////////////////////////////////////////////////
00165 
00166 private:
00167   FMOD::DSP *make_dsp(const FilterProperties::FilterConfig &conf);
00168   void update_dsp_chain(FMOD::DSP *head, FilterProperties *config);
00169   virtual bool configure_filters(FilterProperties *config);
00170   
00171  private:
00172   // This global lock protects all access to FMod library interfaces.
00173   static ReMutex _lock;
00174 
00175   static FMOD::System *_system;
00176   static pset<FmodAudioManager *> _all_managers;
00177 
00178   static bool _system_is_valid;
00179 
00180   static PN_stdfloat _distance_factor;
00181   static PN_stdfloat _doppler_factor;
00182   static PN_stdfloat _drop_off_factor;
00183 
00184   FMOD::ChannelGroup *_channelgroup;
00185 
00186   FMOD_VECTOR _position;
00187   FMOD_VECTOR _velocity;
00188   FMOD_VECTOR _forward;
00189   FMOD_VECTOR _up;
00190 
00191   // DLS info for MIDI files
00192   string _dlsname;
00193   FMOD_CREATESOUNDEXINFO _midi_info;
00194   
00195   bool _is_valid;
00196   bool _active;
00197   
00198   // The set of all sounds.  Needed only to implement stop_all_sounds.
00199   typedef pset<FmodAudioSound *> SoundSet;
00200   SoundSet _all_sounds;
00201 
00202   ////////////////////////////////////////////////////////////
00203   //These are needed for Panda's Pointer System. DO NOT ERASE!
00204   ////////////////////////////////////////////////////////////
00205 
00206  public:
00207   static TypeHandle get_class_type() {
00208     return _type_handle;
00209   }
00210   static void init_type() {
00211     AudioManager::init_type();
00212     register_type(_type_handle, "FmodAudioManager", AudioManager::get_class_type());
00213   }
00214   virtual TypeHandle get_type() const {
00215     return get_class_type();
00216   }
00217   virtual TypeHandle force_init_type() {
00218     init_type(); 
00219     return get_class_type();
00220   }
00221 
00222  private:
00223   static TypeHandle _type_handle;
00224 
00225   ////////////////////////////////////////////////////////////
00226   //DONE
00227   ////////////////////////////////////////////////////////////
00228 
00229 };
00230 
00231 EXPCL_FMOD_AUDIO AudioManager *Create_FmodAudioManager();
00232 
00233 
00234 #endif //]
00235 
00236 #endif /* __FMOD_AUDIO_MANAGER_H__ */
 All Classes Functions Variables Enumerations