Panda3D

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