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