Panda3D
 All Classes Functions Variables Enumerations
audioSound.h
00001 // Filename: audioSound.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 __AUDIOSOUND_H__
00017 #define __AUDIOSOUND_H__
00018 
00019 #include "config_audio.h"
00020 #include "typedReferenceCount.h"
00021 #include "pointerTo.h"
00022 #include "filterProperties.h"
00023 
00024 class AudioManager;
00025 
00026 class EXPCL_PANDA_AUDIO AudioSound : public TypedReferenceCount {
00027 PUBLISHED:
00028   virtual ~AudioSound();
00029 
00030   // For best compatibility, set the loop_count,
00031   // volume, and balance, prior to calling play().  You may
00032   // set them while they're playing, but it's implementation
00033   // specific whether you get the results.
00034   // - Calling play() a second time on the same sound before it is
00035   //   finished will start the sound again (creating a skipping or
00036   //   stuttering effect).
00037   virtual void play() = 0;
00038   virtual void stop() = 0;
00039           
00040   // loop: false = play once; true = play forever.
00041   // inits to false.
00042   virtual void set_loop(bool loop=true) = 0;
00043   virtual bool get_loop() const = 0;
00044           
00045   // loop_count: 0 = forever; 1 = play once; n = play n times.
00046   // inits to 1.
00047   virtual void set_loop_count(unsigned long loop_count=1) = 0;
00048   virtual unsigned long get_loop_count() const = 0;
00049           
00050   // Control time position within the sound.
00051   // This is similar (in concept) to the seek position within
00052   // a file.
00053   // time in seconds: 0 = beginning; length() = end.
00054   // inits to 0.0.
00055   // - The current time position will not change while the sound is
00056   //   playing; you must call play() again to effect the change.  To
00057   //   play the same sound from a time offset a second time,
00058   //   explicitly set the time position again.  When looping, the
00059   //   second and later loops will start from the beginning of the
00060   //   sound.
00061   // - If a sound is playing, calling get_time() repeatedly will
00062   //   return different results over time.  e.g.:
00063   //   PN_stdfloat percent_complete = s.get_time() / s.length();
00064   virtual void set_time(PN_stdfloat start_time=0.0) = 0;
00065   virtual PN_stdfloat get_time() const = 0;
00066           
00067   // 0 = minimum; 1.0 = maximum.
00068   // inits to 1.0.
00069   virtual void set_volume(PN_stdfloat volume=1.0) = 0;
00070   virtual PN_stdfloat get_volume() const = 0;
00071           
00072   // -1.0 is hard left
00073   // 0.0 is centered
00074   // 1.0 is hard right
00075   // inits to 0.0.
00076   virtual void set_balance(PN_stdfloat balance_right=0.0) = 0;
00077   virtual PN_stdfloat get_balance() const = 0;
00078           
00079   // play_rate is any positive PN_stdfloat value.
00080   // inits to 1.0.
00081   virtual void set_play_rate(PN_stdfloat play_rate=1.0f) = 0;
00082   virtual PN_stdfloat get_play_rate() const = 0;
00083 
00084   // inits to manager's state.
00085   virtual void set_active(bool flag=true) = 0;
00086   virtual bool get_active() const = 0;
00087 
00088   // Set (or clear) the event that will be thrown when the sound
00089   // finishes playing.  To clear the event, pass an empty string.
00090   virtual void set_finished_event(const string& event) = 0;
00091   virtual const string& get_finished_event() const = 0;
00092           
00093   // There is no set_name(), this is intentional.
00094   virtual const string& get_name() const = 0;
00095           
00096   // return: playing time in seconds.
00097   virtual PN_stdfloat length() const = 0;
00098 
00099   // Controls the position of this sound's emitter.
00100   // px, py and pz are the emitter's position.
00101   // vx, vy and vz are the emitter's velocity in UNITS PER SECOND (default: meters).
00102   virtual void set_3d_attributes(PN_stdfloat px, PN_stdfloat py, PN_stdfloat pz,
00103                                  PN_stdfloat vx, PN_stdfloat vy, PN_stdfloat vz);
00104   virtual void get_3d_attributes(PN_stdfloat *px, PN_stdfloat *py, PN_stdfloat *pz,
00105                                  PN_stdfloat *vx, PN_stdfloat *vy, PN_stdfloat *vz);
00106 
00107 
00108   // Controls the distance (in units) that this sound begins to fall off.
00109   // Also affects the rate it falls off.
00110   // Default is 1.0
00111   // Closer/Faster, <1.0
00112   // Farther/Slower, >1.0
00113   virtual void set_3d_min_distance(PN_stdfloat dist);
00114   virtual PN_stdfloat get_3d_min_distance() const;
00115 
00116   // Controls the maximum distance (in units) that this sound stops falling off.
00117   // The sound does not stop at that point, it just doesn't get any quieter.
00118   // You should rarely need to adjust this.
00119   // Default is 1000000000.0
00120   virtual void set_3d_max_distance(PN_stdfloat dist);
00121   virtual PN_stdfloat get_3d_max_distance() const;
00122 
00123   // *_speaker_mix and *_speaker_level(s) serve the same purpose.
00124   // *_speaker_mix is for use with FMOD.
00125   // *_speaker_level(s) is for use with Miles.
00126   // Both interfaces exist because of a significant difference in the
00127   // two APIs.  Hopefully the difference can be reconciled into a single
00128   // interface at some point.
00129   virtual PN_stdfloat get_speaker_mix(int speaker);
00130   virtual void set_speaker_mix(PN_stdfloat frontleft, PN_stdfloat frontright, PN_stdfloat center, PN_stdfloat sub, PN_stdfloat backleft, PN_stdfloat backright, PN_stdfloat sideleft, PN_stdfloat  sideright);
00131 
00132   virtual PN_stdfloat get_speaker_level(int index);
00133   virtual void set_speaker_levels(PN_stdfloat level1, PN_stdfloat level2=-1.0f, PN_stdfloat level3=-1.0f, PN_stdfloat level4=-1.0f, PN_stdfloat level5=-1.0f, PN_stdfloat level6=-1.0f, PN_stdfloat level7=-1.0f, PN_stdfloat level8=-1.0f, PN_stdfloat level9=-1.0f);
00134 
00135   virtual int get_priority();
00136   virtual void set_priority(int priority);
00137 
00138   virtual bool configure_filters(FilterProperties *config);
00139 
00140   enum SoundStatus { BAD, READY, PLAYING };
00141   virtual SoundStatus status() const = 0;
00142 
00143   virtual void output(ostream &out) const;
00144   virtual void write(ostream &out) const;
00145 
00146 protected:
00147   AudioSound();
00148 
00149   friend class AudioManager;
00150 
00151 public:
00152   static TypeHandle get_class_type() {
00153     return _type_handle;
00154   }
00155   static void init_type() {
00156     TypedReferenceCount::init_type();
00157     register_type(_type_handle, "AudioSound",
00158                   TypedReferenceCount::get_class_type());
00159   }
00160   virtual TypeHandle get_type() const {
00161     return get_class_type();
00162   }
00163   virtual TypeHandle force_init_type() {init_type(); return get_class_type();}
00164 
00165 private:
00166   static TypeHandle _type_handle;
00167 };
00168 
00169 inline ostream &
00170 operator << (ostream &out, const AudioSound &sound) {
00171   sound.output(out);
00172   return out;
00173 }
00174 
00175 #include "audioSound.I"
00176 
00177 EXPCL_PANDA_AUDIO ostream &
00178 operator << (ostream &out, AudioSound::SoundStatus status);
00179 
00180 #endif /* __AUDIOSOUND_H__ */
 All Classes Functions Variables Enumerations