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