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