removing files that should not be in blender2.5, added (by mistake?) r19226
[blender-staging.git] / intern / SoundSystem / SND_IAudioDevice.h
1 /**
2  * $Id$
3  *
4  * ***** BEGIN GPL LICENSE BLOCK *****
5  *
6  * This program is free software; you can redistribute it and/or
7  * modify it under the terms of the GNU General Public License
8  * as published by the Free Software Foundation; either version 2
9  * of the License, or (at your option) any later version.
10  *
11  * This program is distributed in the hope that it will be useful,
12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14  * GNU General Public License for more details.
15  *
16  * You should have received a copy of the GNU General Public License
17  * along with this program; if not, write to the Free Software Foundation,
18  * Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
19  *
20  * The Original Code is Copyright (C) 2001-2002 by NaN Holding BV.
21  * All rights reserved.
22  *
23  * The Original Code is: all of this file.
24  *
25  * Contributor(s): none yet.
26  *
27  * ***** END GPL LICENSE BLOCK *****
28  */
29 #ifndef SND_IAUDIODEVICE
30 #define SND_IAUDIODEVICE
31
32 #include "SND_SoundObject.h"
33 #include "SND_CDObject.h"
34 #include "SND_WaveCache.h"
35 #include "SND_WaveSlot.h"
36 #include "MT_Matrix3x3.h"
37
38 class SND_IAudioDevice
39 {
40 public:
41
42         /**
43          * constructor
44          */
45         SND_IAudioDevice() {};
46
47         /**
48          * destructor
49          */
50         virtual ~SND_IAudioDevice() {};
51
52         /**
53          * check to see if initialization was successfull
54          *
55          * @return indication of succes
56          */
57         virtual bool IsInitialized()=0;
58
59         /**
60          * get the wavecache (which does sample (un)loading)
61          *
62          * @return pointer to the wavecache
63          */
64         virtual SND_WaveCache* GetWaveCache() const =0;
65
66         /**
67          * loads a sample into the device
68          *
69          * @param samplename    the name of the sample
70          * @param memlocation   pointer where the sample is stored
71          * @param size                  size of the sample in memory
72          *
73          * @return pointer to the slot with sample data
74          */
75         virtual SND_WaveSlot* LoadSample(const STR_String& samplename,
76                                                                          void* memlocation,
77                                                                          int size)=0;
78
79         /**
80          * remove a sample from the wavecache
81          *
82          * @param filename      pointer to filename
83          */
84 //      virtual void RemoveSample(const char* filename)=0;
85         
86         /**
87          * remove all samples from the wavecache
88          */
89         virtual void RemoveAllSamples()=0;
90
91         /**
92          * get a new id from the device
93          *
94          * @param pObject       pointer to soundobject
95          *
96          * @return indication of success
97          */
98         virtual bool GetNewId(SND_SoundObject* pObject)=0;
99         
100         /**
101          * clear an id
102          *
103          * @param pObject       pointer to soundobject
104          */
105         virtual void ClearId(SND_SoundObject* pObject)=0;
106         
107         /**
108          * initialize the listener
109          */
110         virtual void InitListener()=0;
111         
112         /**
113          * set the value of the propagation speed relative to which the 
114          * source velocities are interpreted.
115          * f' = DOPPLER_FACTOR * f * (DOPPLER_VELOCITY - Vl) / (DOPPLER_VELOCITY + Vo)
116          * f:  frequency in sample (soundobject)
117      * f': effective Doppler shifted frequency
118          * Vl: velocity listener
119          * Vo: velocity soundobject
120          *
121          * @param dopplervelocity       scaling factor for doppler effect
122          */
123         virtual void SetDopplerVelocity(MT_Scalar dopplervelocity) const =0;
124         
125         /**
126          * set a scaling to exaggerate or deemphasize the Doppler (pitch) 
127          * shift resulting from the calculation.
128          * f' = DOPPLER_FACTOR * f * (DOPPLER_VELOCITY - Listener_velocity )/(DOPPLER_VELOCITY + object_velocity )
129          *
130          * @param dopplerfactor scaling factor for doppler effect
131          */
132         virtual void SetDopplerFactor(MT_Scalar dopplerfactor) const =0;
133         
134         /**
135          * set the roll-off factor
136          *
137          * @param rollofffactor a global volume scaling factor
138          */
139         virtual void SetListenerRollOffFactor(MT_Scalar rollofffactor) const =0;
140
141         /**
142          * make the context the current one
143          */
144         virtual void MakeCurrent() const =0;
145
146         /**
147          * update the device
148          */
149         virtual void NextFrame() const =0;
150
151         /**
152          * set the volume of the listener.
153          *
154          * @param gain  the mastergain
155          */
156         virtual void SetListenerGain(float gain) const =0;
157
158         /**
159          * connect the buffer with the source
160          *
161          * @param id            the id of the object
162          * @param buffer        the buffer the sample is stored in
163          */
164         virtual void SetObjectBuffer(int id, unsigned int buffer)=0; 
165
166         /**
167          * pause playback of the cd
168          * @param id    the id of the object
169          *
170          * @return the state the object is in
171          */
172         virtual int GetPlayState(int id) =0;
173
174         /**
175          * play a sound belonging to an object.
176          *
177          * @param id    the id of the object
178          */
179         virtual void PlayObject(int id) =0;
180         
181         /**
182          * stop a sound belonging to an object.
183          *
184          * @param id    the id of the object
185          */
186         virtual void StopObject(int id) const =0;
187         
188         /**
189          * stop all sounds.
190          */
191         virtual void StopAllObjects()=0;
192         
193         /**
194          * pause the sound belonging to an object.
195          *
196          * @param id    the id of the object
197          */
198         virtual void PauseObject(int id) const =0;
199
200         /**
201          * set the sound to looping or non-looping.
202          *
203          * @param id    the id of the object
204          * @param loopmode      type of looping (no loop, normal, bidirectional)
205          */
206         virtual void SetObjectLoop(int id, unsigned int loopmode) const =0;
207         
208         /**
209          * set the looppoints of a sound
210          *
211          * @param id    the id of the object
212          * @param loopstart     the startpoint of the loop (in samples)
213          * @param loopend       the endpoint of the loop (in samples)
214          */
215         virtual void SetObjectLoopPoints(int id, unsigned int loopstart, unsigned int loopend) const =0;
216
217         /**
218          * set the pitch of the sound.
219          *
220          * @param id    the id of the object
221          * @param pitch the pitch
222          */
223         virtual void SetObjectPitch(int id, MT_Scalar pitch) const =0;
224         
225         /**
226          * set the gain of the sound.
227          *
228          * @param id    the id of the object
229          * @param gain  the gain
230          */
231         virtual void SetObjectGain(int id, MT_Scalar gain) const =0;
232         
233         /**
234          * ROLLOFF_FACTOR is per-Source parameter the application can use to increase or decrease
235          * the range of a source by decreasing or increasing the attenuation, respectively. The 
236          * default value is 1. The implementation is free to optimize for a ROLLOFF_FACTOR value 
237          * of 0, which indicates that the application does not wish any distance attenuation on 
238          * the respective Source. 
239          *
240          * @param id            the id of the object
241          * @param rolloff       a per-source volume scaling factor
242          */
243         virtual void SetObjectRollOffFactor(int id, MT_Scalar rolloff) const =0;
244
245         /**
246          * min_gain indicates the minimal gain which is always guaranteed for this sound
247          *
248          * @param id            the id of the object
249          * @param mingain       the minimum gain of the object
250          */
251         virtual void SetObjectMinGain(int id, MT_Scalar mingain) const =0;
252
253         /**
254          * max_gain indicates the maximal gain which is always guaranteed for this sound
255          *
256          * @param id            the id of the object
257          * @param maxgain       the maximum gain of the object
258          */
259         virtual void SetObjectMaxGain(int id, MT_Scalar maxgain) const =0;
260         /**
261          * set the distance at which the Listener will experience gain.
262      * G_dB = GAIN - 20*log10(1 + ROLLOFF_FACTOR*(dist-REFERENCE_DISTANCE)/REFERENCE_DISTANCE );
263          *
264          * @param id                            the id of the object
265          * @param referencedistance     the distance at which the listener will start hearing
266          */
267         virtual void SetObjectReferenceDistance(int id, MT_Scalar referencedistance) const =0;
268
269         /**
270          * set the position, velocity and orientation of a sound.
271          *
272          * @param id                    the id of the object
273          * @param position              the position of the object
274          * @param velocity              the velocity of the object
275          * @param orientation   the orientation of the object
276          * @param lisposition   the position of the listener
277          * @param rollofffactor the rollofffactor of the object
278          */
279         virtual void SetObjectTransform(int id,
280                                                                         const MT_Vector3& position,
281                                                                         const MT_Vector3& velocity,
282                                                                         const MT_Matrix3x3& orientation,        
283                                                                         const MT_Vector3& lisposition,
284                                                                         const MT_Scalar& rollofffactor) const =0;
285
286         /**
287          * make a sound 2D
288          *
289          * @param id    the id of the object
290          */
291         virtual void ObjectIs2D(int id) const =0;
292
293         /**
294          * tell the device we want cd suppport
295          */
296         virtual void UseCD() const =0;
297         
298         /**
299          * start playback of the cd
300          *
301          * @param track the tracknumber to start playback from
302          */
303         virtual void PlayCD(int track) const =0;
304
305         /**
306          * pause playback of the cd (true == pause, false == resume)
307          */
308         virtual void PauseCD(bool pause) const =0;
309
310         /**
311          * stop playback of the cd
312          */
313         virtual void StopCD() const =0;
314
315         /**
316          * set the playbackmode of the cd
317          * SND_CD_ALL           play all tracks
318          * SND_CD_TRACK         play one track
319          * SND_CD_TRACKLOOP     play one track looped
320          * SND_CD_RANDOM        play all tracks in random order
321          *
322          * @param playmode      playmode
323          */
324         virtual void SetCDPlaymode(int playmode) const =0;
325         
326         /**
327          * set the volume playback of the cd
328          *
329          * @param gain  the gain
330          */
331         virtual void SetCDGain(MT_Scalar gain) const =0;
332
333         virtual void StartUsingDSP() =0;
334         virtual float* GetSpectrum() =0;
335         virtual void StopUsingDSP() =0;
336
337 protected:
338
339         virtual void RevokeSoundObject(SND_SoundObject* pObject)=0;
340 };
341
342 #endif //SND_IAUDIODEVICE
343