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