Panda3D
fmodAudioSound.h
1 // Filename: fmodAudioSound.h
2 // Created by: cort (January 22, 2003)
3 // Prior system by: cary
4 // Rewrite [for new Version of FMOD-EX] by: Stan Rosenbaum "Staque" - Spring 2006
5 //
6 //
7 ////////////////////////////////////////////////////////////////////
8 //
9 // PANDA 3D SOFTWARE
10 // Copyright (c) Carnegie Mellon University. All rights reserved.
11 //
12 // All use of this software is subject to the terms of the revised BSD
13 // license. You should have received a copy of this license along
14 // with this source code in a file named "LICENSE."
15 //
16 ////////////////////////////////////////////////////////////////////
17 //
18 //
19 //
20 ////////////////////////////////////////////////////////////////////
21 //
22 // [FIRST READ FmodAudioManager for an Introduction if you haven't
23 // already].
24 //
25 // Hello, all future Panda audio code people! This is my errata
26 // documentation to Help any future programmer maintain FMOD and PANDA.
27 //
28 // Well, if you reading this you probably want to know how PANDA deals
29 // with sounds directly using FMOD-EX. Well I am going to tell you.
30 //
31 // The first thing, you as the programmer have to understand,
32 // especially if you never have done sound programming before, is how
33 // the FMOD-EX API works.
34 //
35 // With FMOD-EX the guys at Firelight, adopted a model of managing
36 // sounds with FMOD similar to how a Sound Designer creates sound in a
37 // sound studio using SOUNDS and CHANNELS. Although this may seem
38 // strange at first, if you are not familiar with sound programming,
39 // there is a very good metaphor you are probably already familiar with
40 // to explain how FMOD-EX works.
41 //
42 // Think of you standard GUI API. Usually a GUI API is made up of two
43 // things: Windows and Widgets. These correspond to CHANNELS and
44 // SOUNDS, where a Channel is a Window and a Sound is Widget. Sounds
45 // are played within channels, and channels don't exist unless they
46 // have something to display.
47 //
48 // Now why am I explaining all of this? When PANDA was created they set
49 // up the basic audio classes to handle only the idea of a SOUND. The
50 // idea of a Channel really wasn't prevalent as in more modern Audio
51 // APIs. With this rewrite of PANDA to use the FMOD-EX API, the PANDA
52 // FmodAudioSound Class, now has to handle two different parts of the
53 // FMOD-EX API in order to play a sound.
54 //
55 // SOUND: The object the handles the audio data in form of WAV, AIF,
56 // OGG, MID, IT, MP3, etc... And CHANNEL: The object that actually
57 // plays the sound and manipulates it in real time.
58 //
59 // Ultimately this isn't a problem expect for a couple situations when
60 // you go to play a sound, which I will explain in more detail in that
61 // part of the code. All that you have to know right now is that
62 // Channels in FMOD do not exist unless they are playing a sound. And
63 // in the PANDA FmodAudioSound API class there is only ONE dedicated
64 // channel per sound. Otherwise there is really nothing to worry
65 // about.
66 //
67 ////////////////////////////////////////////////////////////////////
68 
69 #ifndef __FMOD_AUDIO_SOUND_H__
70 #define __FMOD_AUDIO_SOUND_H__
71 
72 #include <pandabase.h>
73 
74 #include "audioSound.h"
75 #include "reMutex.h"
76 #include "fmodAudioManager.h"
77 
78 #include <fmod.hpp>
79 #include <fmod_errors.h>
80 
81 class EXPCL_FMOD_AUDIO FmodAudioSound : public AudioSound {
82  public:
83 
84  FmodAudioSound(AudioManager *manager, Filename fn, bool positional );
85  ~FmodAudioSound();
86 
87  // For best compatibility, set the loop_count, start_time,
88  // volume, and balance, prior to calling play(). You may
89  // set them while they're playing, but it's implementation
90  // specific whether you get the results.
91  void play();
92  void stop();
93 
94  // loop: false = play once; true = play forever.
95  // inits to false.
96  void set_loop(bool loop=true);
97  bool get_loop() const;
98 
99  // loop_count: 0 = forever; 1 = play once; n = play n times.
100  // inits to 1.
101  void set_loop_count(unsigned long loop_count=1);
102  unsigned long get_loop_count() const;
103 
104  // 0 = beginning; length() = end.
105  // inits to 0.0.
106  void set_time(PN_stdfloat start_time=0.0);
107  PN_stdfloat get_time() const;
108 
109  // 0 = minimum; 1.0 = maximum.
110  // inits to 1.0.
111  void set_volume(PN_stdfloat volume=1.0);
112  PN_stdfloat get_volume() const;
113 
114  // -1.0 is hard left
115  // 0.0 is centered
116  // 1.0 is hard right
117  // inits to 0.0.
118  void set_balance(PN_stdfloat balance_right=0.0);
119  PN_stdfloat get_balance() const;
120 
121  // play_rate is any positive float value.
122  // inits to 1.0.
123  void set_play_rate(PN_stdfloat play_rate=1.0f);
124  PN_stdfloat get_play_rate() const;
125 
126  const string &get_name() const;
127 
128  // return: playing time in seconds.
129  PN_stdfloat length() const;
130 
131  // Controls the position of this sound's emitter.
132  // pos is a pointer to an xyz triplet of the emitter's position.
133  // vel is a pointer to an xyz triplet of the emitter's velocity.
134  void set_3d_attributes(PN_stdfloat px, PN_stdfloat py, PN_stdfloat pz, PN_stdfloat vx, PN_stdfloat vy, PN_stdfloat vz);
135  void get_3d_attributes(PN_stdfloat *px, PN_stdfloat *py, PN_stdfloat *pz, PN_stdfloat *vx, PN_stdfloat *vy, PN_stdfloat *vz);
136 
137  void set_3d_min_distance(PN_stdfloat dist);
138  PN_stdfloat get_3d_min_distance() const;
139 
140  void set_3d_max_distance(PN_stdfloat dist);
141  PN_stdfloat get_3d_max_distance() const;
142 
143  AudioSound::SoundStatus status() const;
144 
145  virtual PN_stdfloat get_speaker_mix(AudioManager::SpeakerId speaker);
146  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);
147 
148  void set_active(bool active=true);
149  bool get_active() const;
150 
151  void finished();
152  void set_finished_event(const string& event);
153  const string& get_finished_event() const;
154 
155  private:
156  PT(FmodAudioManager) _manager;
157  FMOD::Sound *_sound;
158  FMOD::Channel *_channel;
159 
160  Filename _file_name;
161 
162  float _volume;
163  float _balance;
164  float _playrate;
165  int _priority;
166  float _mix[AudioManager::SPK_COUNT];
167 
168  float _sampleFrequency;
169  mutable float _length; //in seconds.
170 
171  FMOD_SPEAKERMODE _speakermode;
172 
173  FMOD_VECTOR _location;
174  FMOD_VECTOR _velocity;
175 
176  PN_stdfloat _min_dist;
177  PN_stdfloat _max_dist;
178 
179  void start_playing();
180  void set_volume_on_channel();
181  void set_balance_on_channel();
182  void set_play_rate_on_channel();
183  void set_speaker_mix_on_channel();
184  void set_3d_attributes_on_channel();
185  // void add_dsp_on_channel();
186  void set_speaker_mix_or_balance_on_channel();
187 
188  virtual int get_priority();
189  virtual void set_priority(int priority);
190 
191  bool _active;
192  bool _paused;
193  PN_stdfloat _start_time;
194 
195  string _finished_event;
196 
197  // This reference-counting pointer is set to this while the sound is
198  // playing, and cleared when we get an indication that the sound has
199  // stopped. This prevents a sound from destructing while it is
200  // playing. We use a PT instead of managing the reference counts by
201  // hand to help guard against accidental reference count leaks or
202  // other mismanagement.
203  PT(FmodAudioSound) _self_ref;
204 
205  static FMOD_RESULT F_CALLBACK
206  sound_end_callback(FMOD_CHANNEL * channel,
207  FMOD_CHANNEL_CALLBACKTYPE type,
208  void *commanddata1,
209  void *commanddata2);
210 
211  static FMOD_RESULT F_CALLBACK
212  open_callback(const char *name, int unicode, unsigned int *file_size,
213  void **handle, void **user_data);
214 
215  static FMOD_RESULT F_CALLBACK
216  close_callback(void *handle, void *user_data);
217 
218  static FMOD_RESULT F_CALLBACK
219  read_callback(void *handle, void *buffer, unsigned int size_bytes,
220  unsigned int *bytes_read, void *user_data);
221 
222  static FMOD_RESULT F_CALLBACK
223  seek_callback(void *handle, unsigned int pos, void *user_data);
224 
225 
226  ////////////////////////////////////////////////////////////
227  //These are needed for Panda's Pointer System. DO NOT ERASE!
228  ////////////////////////////////////////////////////////////
229 
230  public:
231  static TypeHandle get_class_type() {
232  return _type_handle;
233  }
234  static void init_type() {
235  AudioSound::init_type();
236  register_type(_type_handle, "FmodAudioSound", AudioSound::get_class_type());
237  }
238  virtual TypeHandle get_type() const {
239  return get_class_type();
240  }
241  virtual TypeHandle force_init_type() {
242  init_type();
243  return get_class_type();
244  }
245 
246  private:
247  static TypeHandle _type_handle;
248 
249  ////////////////////////////////////////////////////////////
250  //DONE
251  ////////////////////////////////////////////////////////////
252 };
253 
254 #include "fmodAudioSound.I"
255 
256 #endif /* __FMOD_AUDIO_SOUND_H__ */
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)
For use only with FMOD.
Definition: audioSound.cxx:89
The name of a file, such as a texture file or an Egg file.
Definition: filename.h:44
virtual PN_stdfloat get_speaker_mix(int speaker)
For use only with FMOD.
Definition: audioSound.cxx:78
TypeHandle is the identifier used to differentiate C++ class types.
Definition: typeHandle.h:85