Panda3D
 All Classes Functions Variables Enumerations
audioSound.h
1 // Filename: audioSound.h
2 // Created by: skyler (June 6, 2001)
3 // Prior system by: cary
4 //
5 ////////////////////////////////////////////////////////////////////
6 //
7 // PANDA 3D SOFTWARE
8 // Copyright (c) Carnegie Mellon University. All rights reserved.
9 //
10 // All use of this software is subject to the terms of the revised BSD
11 // license. You should have received a copy of this license along
12 // with this source code in a file named "LICENSE."
13 //
14 ////////////////////////////////////////////////////////////////////
15 
16 #ifndef __AUDIOSOUND_H__
17 #define __AUDIOSOUND_H__
18 
19 #include "config_audio.h"
20 #include "typedReferenceCount.h"
21 #include "pointerTo.h"
22 #include "filterProperties.h"
23 
24 class AudioManager;
25 
26 class EXPCL_PANDA_AUDIO AudioSound : public TypedReferenceCount {
27 PUBLISHED:
28  virtual ~AudioSound();
29 
30  // For best compatibility, set the loop_count,
31  // volume, and balance, prior to calling play(). You may
32  // set them while they're playing, but it's implementation
33  // specific whether you get the results.
34  // - Calling play() a second time on the same sound before it is
35  // finished will start the sound again (creating a skipping or
36  // stuttering effect).
37  virtual void play() = 0;
38  virtual void stop() = 0;
39 
40  // loop: false = play once; true = play forever.
41  // inits to false.
42  virtual void set_loop(bool loop=true) = 0;
43  virtual bool get_loop() const = 0;
44 
45  // loop_count: 0 = forever; 1 = play once; n = play n times.
46  // inits to 1.
47  virtual void set_loop_count(unsigned long loop_count=1) = 0;
48  virtual unsigned long get_loop_count() const = 0;
49 
50  // Control time position within the sound.
51  // This is similar (in concept) to the seek position within
52  // a file.
53  // time in seconds: 0 = beginning; length() = end.
54  // inits to 0.0.
55  // - The current time position will not change while the sound is
56  // playing; you must call play() again to effect the change. To
57  // play the same sound from a time offset a second time,
58  // explicitly set the time position again. When looping, the
59  // second and later loops will start from the beginning of the
60  // sound.
61  // - If a sound is playing, calling get_time() repeatedly will
62  // return different results over time. e.g.:
63  // PN_stdfloat percent_complete = s.get_time() / s.length();
64  virtual void set_time(PN_stdfloat start_time=0.0) = 0;
65  virtual PN_stdfloat get_time() const = 0;
66 
67  // 0 = minimum; 1.0 = maximum.
68  // inits to 1.0.
69  virtual void set_volume(PN_stdfloat volume=1.0) = 0;
70  virtual PN_stdfloat get_volume() const = 0;
71 
72  // -1.0 is hard left
73  // 0.0 is centered
74  // 1.0 is hard right
75  // inits to 0.0.
76  virtual void set_balance(PN_stdfloat balance_right=0.0) = 0;
77  virtual PN_stdfloat get_balance() const = 0;
78 
79  // play_rate is any positive PN_stdfloat value.
80  // inits to 1.0.
81  virtual void set_play_rate(PN_stdfloat play_rate=1.0f) = 0;
82  virtual PN_stdfloat get_play_rate() const = 0;
83 
84  // inits to manager's state.
85  virtual void set_active(bool flag=true) = 0;
86  virtual bool get_active() const = 0;
87 
88  // Set (or clear) the event that will be thrown when the sound
89  // finishes playing. To clear the event, pass an empty string.
90  virtual void set_finished_event(const string& event) = 0;
91  virtual const string& get_finished_event() const = 0;
92 
93  // There is no set_name(), this is intentional.
94  virtual const string& get_name() const = 0;
95 
96  // return: playing time in seconds.
97  virtual PN_stdfloat length() const = 0;
98 
99  // Controls the position of this sound's emitter.
100  // px, py and pz are the emitter's position.
101  // vx, vy and vz are the emitter's velocity in UNITS PER SECOND (default: meters).
102  virtual void set_3d_attributes(PN_stdfloat px, PN_stdfloat py, PN_stdfloat pz,
103  PN_stdfloat vx, PN_stdfloat vy, PN_stdfloat vz);
104  virtual void get_3d_attributes(PN_stdfloat *px, PN_stdfloat *py, PN_stdfloat *pz,
105  PN_stdfloat *vx, PN_stdfloat *vy, PN_stdfloat *vz);
106 
107 
108  // Controls the distance (in units) that this sound begins to fall off.
109  // Also affects the rate it falls off.
110  // Default is 1.0
111  // Closer/Faster, <1.0
112  // Farther/Slower, >1.0
113  virtual void set_3d_min_distance(PN_stdfloat dist);
114  virtual PN_stdfloat get_3d_min_distance() const;
115 
116  // Controls the maximum distance (in units) that this sound stops falling off.
117  // The sound does not stop at that point, it just doesn't get any quieter.
118  // You should rarely need to adjust this.
119  // Default is 1000000000.0
120  virtual void set_3d_max_distance(PN_stdfloat dist);
121  virtual PN_stdfloat get_3d_max_distance() const;
122 
123  // *_speaker_mix and *_speaker_level(s) serve the same purpose.
124  // *_speaker_mix is for use with FMOD.
125  // *_speaker_level(s) is for use with Miles.
126  // Both interfaces exist because of a significant difference in the
127  // two APIs. Hopefully the difference can be reconciled into a single
128  // interface at some point.
129  virtual PN_stdfloat get_speaker_mix(int speaker);
130  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);
131 
132  virtual PN_stdfloat get_speaker_level(int index);
133  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);
134 
135  virtual int get_priority();
136  virtual void set_priority(int priority);
137 
138  virtual bool configure_filters(FilterProperties *config);
139 
140  enum SoundStatus { BAD, READY, PLAYING };
141  virtual SoundStatus status() const = 0;
142 
143  virtual void output(ostream &out) const;
144  virtual void write(ostream &out) const;
145 
146 protected:
147  AudioSound();
148 
149  friend class AudioManager;
150 
151 public:
152  static TypeHandle get_class_type() {
153  return _type_handle;
154  }
155  static void init_type() {
156  TypedReferenceCount::init_type();
157  register_type(_type_handle, "AudioSound",
158  TypedReferenceCount::get_class_type());
159  }
160  virtual TypeHandle get_type() const {
161  return get_class_type();
162  }
163  virtual TypeHandle force_init_type() {init_type(); return get_class_type();}
164 
165 private:
166  static TypeHandle _type_handle;
167 };
168 
169 inline ostream &
170 operator << (ostream &out, const AudioSound &sound) {
171  sound.output(out);
172  return out;
173 }
174 
175 #include "audioSound.I"
176 
177 EXPCL_PANDA_AUDIO ostream &
178 operator << (ostream &out, AudioSound::SoundStatus status);
179 
180 #endif /* __AUDIOSOUND_H__ */
A base class for things which need to inherit from both TypedObject and from ReferenceCount.
Stores a configuration for a set of audio DSP filters.
TypeHandle is the identifier used to differentiate C++ class types.
Definition: typeHandle.h:85