migrated NDOF code from soc-2010-merwin, SpaceNavigator now works on Mac blender
[blender-staging.git] / intern / audaspace / intern / AUD_C-API.h
1 /*
2  * $Id$
3  *
4  * ***** BEGIN GPL LICENSE BLOCK *****
5  *
6  * Copyright 2009-2011 Jörg Hermann Müller
7  *
8  * This file is part of AudaSpace.
9  *
10  * Audaspace is free software; you can redistribute it and/or modify
11  * it under the terms of the GNU General Public License as published by
12  * the Free Software Foundation; either version 2 of the License, or
13  * (at your option) any later version.
14  *
15  * AudaSpace is distributed in the hope that it will be useful,
16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
18  * GNU General Public License for more details.
19  *
20  * You should have received a copy of the GNU General Public License
21  * along with Audaspace; if not, write to the Free Software Foundation,
22  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
23  *
24  * ***** END GPL LICENSE BLOCK *****
25  */
26
27 /** \file AUD_C-API.h
28  *  \ingroup audaspace
29  */
30  
31 #ifndef AUD_CAPI
32 #define AUD_CAPI
33
34 #ifdef __cplusplus
35 extern "C" {
36 #endif
37
38 #include "AUD_Space.h"
39
40 typedef enum
41 {
42         AUD_NULL_DEVICE = 0,
43         AUD_SDL_DEVICE,
44         AUD_OPENAL_DEVICE,
45         AUD_JACK_DEVICE
46 } AUD_DeviceType;
47
48 typedef struct
49 {
50         AUD_Specs specs;
51         float length;
52 } AUD_SoundInfo;
53
54 #ifndef AUD_CAPI_IMPLEMENTATION
55         typedef void AUD_Sound;
56         typedef void AUD_Channel;
57         typedef void AUD_Device;
58         typedef void AUD_SequencerEntry;
59         typedef float (*AUD_volumeFunction)(void*, void*, float);
60         typedef void (*AUD_syncFunction)(void*, int, float);
61 #endif
62
63 /**
64  * Initializes FFMPEG if it is enabled.
65  */
66 extern void AUD_initOnce(void);
67
68 /**
69  * Initializes an audio device.
70  * \param device The device type that should be used.
71  * \param specs The audio specification to be used.
72  * \param buffersize The buffersize for the device.
73  * \return Whether the device has been initialized.
74  */
75 extern int AUD_init(AUD_DeviceType device, AUD_DeviceSpecs specs, int buffersize);
76
77 /**
78  * Unitinitializes an audio device.
79  */
80 extern void AUD_exit(void);
81
82 /**
83  * Locks the playback device.
84  */
85 extern void AUD_lock(void);
86
87 /**
88  * Unlocks the device.
89  */
90 extern void AUD_unlock(void);
91
92 /**
93  * Returns information about a sound.
94  * \param sound The sound to get the info about.
95  * \return The AUD_SoundInfo structure with filled in data.
96  */
97 extern AUD_SoundInfo AUD_getInfo(AUD_Sound* sound);
98
99 /**
100  * Loads a sound file.
101  * \param filename The filename of the sound file.
102  * \return A handle of the sound file.
103  */
104 extern AUD_Sound* AUD_load(const char* filename);
105
106 /**
107  * Loads a sound file.
108  * \param buffer The buffer which contains the sound file.
109  * \param size The size of the buffer.
110  * \return A handle of the sound file.
111  */
112 extern AUD_Sound* AUD_loadBuffer(unsigned char* buffer, int size);
113
114 /**
115  * Buffers a sound.
116  * \param sound The sound to buffer.
117  * \return A handle of the sound buffer.
118  */
119 extern AUD_Sound* AUD_bufferSound(AUD_Sound* sound);
120
121 /**
122  * Delays a sound.
123  * \param sound The sound to dealy.
124  * \param delay The delay in seconds.
125  * \return A handle of the delayed sound.
126  */
127 extern AUD_Sound* AUD_delaySound(AUD_Sound* sound, float delay);
128
129 /**
130  * Limits a sound.
131  * \param sound The sound to limit.
132  * \param start The start time in seconds.
133  * \param end The stop time in seconds.
134  * \return A handle of the limited sound.
135  */
136 extern AUD_Sound* AUD_limitSound(AUD_Sound* sound, float start, float end);
137
138 /**
139  * Ping pongs a sound.
140  * \param sound The sound to ping pong.
141  * \return A handle of the ping pong sound.
142  */
143 extern AUD_Sound* AUD_pingpongSound(AUD_Sound* sound);
144
145 /**
146  * Loops a sound.
147  * \param sound The sound to loop.
148  * \return A handle of the looped sound.
149  */
150 extern AUD_Sound* AUD_loopSound(AUD_Sound* sound);
151
152 /**
153  * Sets a remaining loop count of a looping sound that currently plays.
154  * \param handle The playback handle.
155  * \param loops The count of remaining loops, -1 for infinity.
156  * \return Whether the handle is valid.
157  */
158 extern int AUD_setLoop(AUD_Channel* handle, int loops);
159
160 /**
161  * Rectifies a sound.
162  * \param sound The sound to rectify.
163  * \return A handle of the rectified sound.
164  */
165 extern AUD_Sound* AUD_rectifySound(AUD_Sound* sound);
166
167 /**
168  * Unloads a sound of any type.
169  * \param sound The handle of the sound.
170  */
171 extern void AUD_unload(AUD_Sound* sound);
172
173 /**
174  * Plays back a sound file.
175  * \param sound The handle of the sound file.
176  * \param keep When keep is true the sound source will not be deleted but set to
177  *             paused when its end has been reached.
178  * \return A handle to the played back sound.
179  */
180 extern AUD_Channel* AUD_play(AUD_Sound* sound, int keep);
181
182 /**
183  * Pauses a played back sound.
184  * \param handle The handle to the sound.
185  * \return Whether the handle has been playing or not.
186  */
187 extern int AUD_pause(AUD_Channel* handle);
188
189 /**
190  * Resumes a paused sound.
191  * \param handle The handle to the sound.
192  * \return Whether the handle has been paused or not.
193  */
194 extern int AUD_resume(AUD_Channel* handle);
195
196 /**
197  * Stops a playing or paused sound.
198  * \param handle The handle to the sound.
199  * \return Whether the handle has been valid or not.
200  */
201 extern int AUD_stop(AUD_Channel* handle);
202
203 /**
204  * Sets the end behaviour of a playing or paused sound.
205  * \param handle The handle to the sound.
206  * \param keep When keep is true the sound source will not be deleted but set to
207  *             paused when its end has been reached.
208  * \return Whether the handle has been valid or not.
209  */
210 extern int AUD_setKeep(AUD_Channel* handle, int keep);
211
212 /**
213  * Seeks a playing or paused sound.
214  * \param handle The handle to the sound.
215  * \param seekTo From where the sound file should be played back in seconds.
216  * \return Whether the handle has been valid or not.
217  */
218 extern int AUD_seek(AUD_Channel* handle, float seekTo);
219
220 /**
221  * Retrieves the playback position of a handle.
222  * \param handle The handle to the sound.
223  * \return The current playback position in seconds or 0.0 if the handle is
224  *         invalid.
225  */
226 extern float AUD_getPosition(AUD_Channel* handle);
227
228 /**
229  * Returns the status of a playing, paused or stopped sound.
230  * \param handle The handle to the sound.
231  * \return The status of the sound behind the handle.
232  */
233 extern AUD_Status AUD_getStatus(AUD_Channel* handle);
234
235 /**
236  * Sets the listener location.
237  * \param location The new location.
238  */
239 extern int AUD_setListenerLocation(const float* location);
240
241 /**
242  * Sets the listener velocity.
243  * \param velocity The new velocity.
244  */
245 extern int AUD_setListenerVelocity(const float* velocity);
246
247 /**
248  * Sets the listener orientation.
249  * \param orientation The new orientation as quaternion.
250  */
251 extern int AUD_setListenerOrientation(const float* orientation);
252
253 /**
254  * Sets the speed of sound.
255  * This value is needed for doppler effect calculation.
256  * \param speed The new speed of sound.
257  */
258 extern int AUD_setSpeedOfSound(float speed);
259
260 /**
261  * Sets the doppler factor.
262  * This value is a scaling factor for the velocity vectors of sources and
263  * listener which is used while calculating the doppler effect.
264  * \param factor The new doppler factor.
265  */
266 extern int AUD_setDopplerFactor(float factor);
267
268 /**
269  * Sets the distance model.
270  * \param model distance model.
271  */
272 extern int AUD_setDistanceModel(AUD_DistanceModel model);
273
274 /**
275  * Sets the location of a source.
276  * \param handle The handle of the source.
277  * \param location The new location.
278  * \return Whether the action succeeded.
279  */
280 extern int AUD_setSourceLocation(AUD_Channel* handle, const float* location);
281
282 /**
283  * Sets the velocity of a source.
284  * \param handle The handle of the source.
285  * \param velocity The new velocity.
286  * \return Whether the action succeeded.
287  */
288 extern int AUD_setSourceVelocity(AUD_Channel* handle, const float* velocity);
289
290 /**
291  * Sets the orientation of a source.
292  * \param handle The handle of the source.
293  * \param orientation The new orientation as quaternion.
294  * \return Whether the action succeeded.
295  */
296 extern int AUD_setSourceOrientation(AUD_Channel* handle, const float* orientation);
297
298 /**
299  * Sets whether the source location, velocity and orientation are relative
300  * to the listener.
301  * \param handle The handle of the source.
302  * \param relative Whether the source is relative.
303  * \return Whether the action succeeded.
304  */
305 extern int AUD_setRelative(AUD_Channel* handle, int relative);
306
307 /**
308  * Sets the maximum volume of a source.
309  * \param handle The handle of the source.
310  * \param volume The new maximum volume.
311  * \return Whether the action succeeded.
312  */
313 extern int AUD_setVolumeMaximum(AUD_Channel* handle, float volume);
314
315 /**
316  * Sets the minimum volume of a source.
317  * \param handle The handle of the source.
318  * \param volume The new minimum volume.
319  * \return Whether the action succeeded.
320  */
321 extern int AUD_setVolumeMinimum(AUD_Channel* handle, float volume);
322
323 /**
324  * Sets the maximum distance of a source.
325  * If a source is further away from the reader than this distance, the
326  * volume will automatically be set to 0.
327  * \param handle The handle of the source.
328  * \param distance The new maximum distance.
329  * \return Whether the action succeeded.
330  */
331 extern int AUD_setDistanceMaximum(AUD_Channel* handle, float distance);
332
333 /**
334  * Sets the reference distance of a source.
335  * \param handle The handle of the source.
336  * \param distance The new reference distance.
337  * \return Whether the action succeeded.
338  */
339 extern int AUD_setDistanceReference(AUD_Channel* handle, float distance);
340
341 /**
342  * Sets the attenuation of a source.
343  * This value is used for distance calculation.
344  * \param handle The handle of the source.
345  * \param factor The new attenuation.
346  * \return Whether the action succeeded.
347  */
348 extern int AUD_setAttenuation(AUD_Channel* handle, float factor);
349
350 /**
351  * Sets the outer angle of the cone of a source.
352  * \param handle The handle of the source.
353  * \param angle The new outer angle of the cone.
354  * \return Whether the action succeeded.
355  */
356 extern int AUD_setConeAngleOuter(AUD_Channel* handle, float angle);
357
358 /**
359  * Sets the inner angle of the cone of a source.
360  * \param handle The handle of the source.
361  * \param angle The new inner angle of the cone.
362  * \return Whether the action succeeded.
363  */
364 extern int AUD_setConeAngleInner(AUD_Channel* handle, float angle);
365
366 /**
367  * Sets the outer volume of the cone of a source.
368  * The volume between inner and outer angle is interpolated between inner
369  * volume and this value.
370  * \param handle The handle of the source.
371  * \param volume The new outer volume of the cone.
372  * \return Whether the action succeeded.
373  */
374 extern int AUD_setConeVolumeOuter(AUD_Channel* handle, float volume);
375
376 /**
377  * Sets the volume of a played back sound.
378  * \param handle The handle to the sound.
379  * \param volume The new volume, must be between 0.0 and 1.0.
380  * \return Whether the action succeeded.
381  */
382 extern int AUD_setSoundVolume(AUD_Channel* handle, float volume);
383
384 /**
385  * Sets the pitch of a played back sound.
386  * \param handle The handle to the sound.
387  * \param pitch The new pitch.
388  * \return Whether the action succeeded.
389  */
390 extern int AUD_setSoundPitch(AUD_Channel* handle, float pitch);
391
392 /**
393  * Opens a read device, with which audio data can be read.
394  * \param specs The specification of the audio data.
395  * \return A device handle.
396  */
397 extern AUD_Device* AUD_openReadDevice(AUD_DeviceSpecs specs);
398
399 /**
400  * Sets the main volume of a device.
401  * \param device The device.
402  * \param volume The new volume, must be between 0.0 and 1.0.
403  * \return Whether the action succeeded.
404  */
405 extern int AUD_setDeviceVolume(AUD_Device* device, float volume);
406
407 /**
408  * Plays back a sound file through a read device.
409  * \param device The read device.
410  * \param sound The handle of the sound file.
411  * \param seek The position where the sound should be seeked to.
412  * \return A handle to the played back sound.
413  */
414 extern AUD_Channel* AUD_playDevice(AUD_Device* device, AUD_Sound* sound, float seek);
415
416 /**
417  * Sets the volume of a played back sound of a read device.
418  * \param device The read device.
419  * \param handle The handle to the sound.
420  * \param volume The new volume, must be between 0.0 and 1.0.
421  * \return Whether the action succeeded.
422  */
423 extern int AUD_setDeviceSoundVolume(AUD_Device* device,
424                                                                         AUD_Channel* handle,
425                                                                         float volume);
426
427 /**
428  * Reads the next samples into the supplied buffer.
429  * \param device The read device.
430  * \param buffer The target buffer.
431  * \param length The length in samples to be filled.
432  * \return True if the reading succeeded, false if there are no sounds
433  *         played back currently, in that case the buffer is filled with
434  *         silence.
435  */
436 extern int AUD_readDevice(AUD_Device* device, data_t* buffer, int length);
437
438 /**
439  * Closes a read device.
440  * \param device The read device.
441  */
442 extern void AUD_closeReadDevice(AUD_Device* device);
443
444 /**
445  * Reads a sound file into a newly created float buffer.
446  * The sound is therefore bandpassed, rectified and resampled.
447  */
448 extern float* AUD_readSoundBuffer(const char* filename, float low, float high,
449                                                                   float attack, float release, float threshold,
450                                                                   int accumulate, int additive, int square,
451                                                                   float sthreshold, int samplerate,
452                                                                   int* length);
453
454 /**
455  * Pauses a playing sound after a specific amount of time.
456  * \param handle The handle to the sound.
457  * \param time The time in seconds.
458  * \return The silence handle.
459  */
460 extern AUD_Channel* AUD_pauseAfter(AUD_Channel* handle, float seconds);
461
462 extern AUD_Sound* AUD_createSequencer(int muted, void* data, AUD_volumeFunction volume);
463
464 extern void AUD_destroySequencer(AUD_Sound* sequencer);
465
466 extern void AUD_setSequencerMuted(AUD_Sound* sequencer, int muted);
467
468 extern AUD_SequencerEntry* AUD_addSequencer(AUD_Sound** sequencer, AUD_Sound* sound,
469                                                                                 float begin, float end, float skip, void* data);
470
471 extern void AUD_removeSequencer(AUD_Sound* sequencer, AUD_SequencerEntry* entry);
472
473 extern void AUD_moveSequencer(AUD_Sound* sequencer, AUD_SequencerEntry* entry,
474                                                   float begin, float end, float skip);
475
476 extern void AUD_muteSequencer(AUD_Sound* sequencer, AUD_SequencerEntry* entry,
477                                                   char mute);
478
479 extern int AUD_readSound(AUD_Sound* sound, sample_t* buffer, int length);
480
481 extern void AUD_startPlayback(void);
482
483 extern void AUD_stopPlayback(void);
484
485 extern void AUD_seekSequencer(AUD_Channel* handle, float time);
486
487 extern float AUD_getSequencerPosition(AUD_Channel* handle);
488
489 #ifdef WITH_JACK
490 extern void AUD_setSyncCallback(AUD_syncFunction function, void* data);
491 #endif
492
493 extern int AUD_doesPlayback(void);
494
495 #ifdef __cplusplus
496 }
497 #endif
498
499 #endif //AUD_CAPI