2.5 Audio:
[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_Handle;
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 an audio device.
60  * \param device The device type that should be used.
61  * \param specs The audio specification to be used.
62  * \param buffersize The buffersize for the device.
63  * \return Whether the device has been initialized.
64  */
65 extern int AUD_init(AUD_DeviceType device, AUD_DeviceSpecs specs, int buffersize);
66
67 /**
68  * Returns a integer list with available sound devices. The last one is always
69  * AUD_NULL_DEVICE.
70  */
71 extern int* AUD_enumDevices();
72
73 /**
74  * Unitinitializes an audio device.
75  */
76 extern void AUD_exit();
77
78 /**
79  * Locks the playback device.
80  */
81 extern void AUD_lock();
82
83 /**
84  * Unlocks the device.
85  */
86 extern void AUD_unlock();
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  * \param time The time after which playback should stop, -1 for infinity.
153  * \return Whether the handle is valid.
154  */
155 extern int AUD_setLoop(AUD_Handle* handle, int loops, float time);
156
157 /**
158  * Rectifies a sound.
159  * \param sound The sound to rectify.
160  * \return A handle of the rectified sound.
161  */
162 extern AUD_Sound* AUD_rectifySound(AUD_Sound* sound);
163
164 /**
165  * Unloads a sound of any type.
166  * \param sound The handle of the sound.
167  */
168 extern void AUD_unload(AUD_Sound* sound);
169
170 /**
171  * Plays back a sound file.
172  * \param sound The handle of the sound file.
173  * \param keep When keep is true the sound source will not be deleted but set to
174  *             paused when its end has been reached.
175  * \return A handle to the played back sound.
176  */
177 extern AUD_Handle* AUD_play(AUD_Sound* sound, int keep);
178
179 /**
180  * Pauses a played back sound.
181  * \param handle The handle to the sound.
182  * \return Whether the handle has been playing or not.
183  */
184 extern int AUD_pause(AUD_Handle* handle);
185
186 /**
187  * Resumes a paused sound.
188  * \param handle The handle to the sound.
189  * \return Whether the handle has been paused or not.
190  */
191 extern int AUD_resume(AUD_Handle* handle);
192
193 /**
194  * Stops a playing or paused sound.
195  * \param handle The handle to the sound.
196  * \return Whether the handle has been valid or not.
197  */
198 extern int AUD_stop(AUD_Handle* handle);
199
200 /**
201  * Sets the end behaviour of a playing or paused sound.
202  * \param handle The handle to the sound.
203  * \param keep When keep is true the sound source will not be deleted but set to
204  *             paused when its end has been reached.
205  * \return Whether the handle has been valid or not.
206  */
207 extern int AUD_setKeep(AUD_Handle* handle, int keep);
208
209 /**
210  * Seeks a playing or paused sound.
211  * \param handle The handle to the sound.
212  * \param seekTo From where the sound file should be played back in seconds.
213  * \return Whether the handle has been valid or not.
214  */
215 extern int AUD_seek(AUD_Handle* handle, float seekTo);
216
217 /**
218  * Retrieves the playback position of a handle.
219  * \param handle The handle to the sound.
220  * \return The current playback position in seconds or 0.0 if the handle is
221  *         invalid.
222  */
223 extern float AUD_getPosition(AUD_Handle* handle);
224
225 /**
226  * Returns the status of a playing, paused or stopped sound.
227  * \param handle The handle to the sound.
228  * \return The status of the sound behind the handle.
229  */
230 extern AUD_Status AUD_getStatus(AUD_Handle* handle);
231
232 /**
233  * Plays a 3D sound.
234  * \param sound The handle of the sound file.
235  * \param keep When keep is true the sound source will not be deleted but set to
236  *             paused when its end has been reached.
237  * \return A handle to the played back sound.
238  * \note The factory must provide a mono (single channel) source and the device
239  *       must support 3D audio, otherwise the sound is played back normally.
240  */
241 extern AUD_Handle* AUD_play3D(AUD_Sound* sound, int keep);
242
243 /**
244  * Updates the listener 3D data.
245  * \param data The 3D data.
246  * \return Whether the action succeeded.
247  */
248 extern int AUD_updateListener(AUD_3DData* data);
249
250 /**
251  * Sets a 3D device setting.
252  * \param setting The setting type.
253  * \param value The new setting value.
254  * \return Whether the action succeeded.
255  */
256 extern int AUD_set3DSetting(AUD_3DSetting setting, float value);
257
258 /**
259  * Retrieves a 3D device setting.
260  * \param setting The setting type.
261  * \return The setting value.
262  */
263 extern float AUD_get3DSetting(AUD_3DSetting setting);
264
265 /**
266  * Updates a listeners 3D data.
267  * \param handle The source handle.
268  * \param data The 3D data.
269  * \return Whether the action succeeded.
270  */
271 extern int AUD_update3DSource(AUD_Handle* handle, AUD_3DData* data);
272
273 /**
274  * Sets a 3D source setting.
275  * \param handle The source handle.
276  * \param setting The setting type.
277  * \param value The new setting value.
278  * \return Whether the action succeeded.
279  */
280 extern int AUD_set3DSourceSetting(AUD_Handle* handle,
281                                                                   AUD_3DSourceSetting setting, float value);
282
283 /**
284  * Retrieves a 3D source setting.
285  * \param handle The source handle.
286  * \param setting The setting type.
287  * \return The setting value.
288  */
289 extern float AUD_get3DSourceSetting(AUD_Handle* handle,
290                                                                         AUD_3DSourceSetting setting);
291
292 /**
293  * Sets the volume of a played back sound.
294  * \param handle The handle to the sound.
295  * \param volume The new volume, must be between 0.0 and 1.0.
296  * \return Whether the action succeeded.
297  */
298 extern int AUD_setSoundVolume(AUD_Handle* handle, float volume);
299
300 /**
301  * Sets the pitch of a played back sound.
302  * \param handle The handle to the sound.
303  * \param pitch The new pitch.
304  * \return Whether the action succeeded.
305  */
306 extern int AUD_setSoundPitch(AUD_Handle* handle, float pitch);
307
308 /**
309  * Opens a read device, with which audio data can be read.
310  * \param specs The specification of the audio data.
311  * \return A device handle.
312  */
313 extern AUD_Device* AUD_openReadDevice(AUD_DeviceSpecs specs);
314
315 /**
316  * Sets the main volume of a device.
317  * \param device The device.
318  * \param volume The new volume, must be between 0.0 and 1.0.
319  * \return Whether the action succeeded.
320  */
321 extern int AUD_setDeviceVolume(AUD_Device* device, float volume);
322
323 /**
324  * Plays back a sound file through a read device.
325  * \param device The read device.
326  * \param sound The handle of the sound file.
327  * \param seek The position where the sound should be seeked to.
328  * \return A handle to the played back sound.
329  */
330 extern AUD_Handle* AUD_playDevice(AUD_Device* device, AUD_Sound* sound, float seek);
331
332 /**
333  * Sets the volume of a played back sound of a read device.
334  * \param device The read device.
335  * \param handle The handle to the sound.
336  * \param volume The new volume, must be between 0.0 and 1.0.
337  * \return Whether the action succeeded.
338  */
339 extern int AUD_setDeviceSoundVolume(AUD_Device* device,
340                                                                         AUD_Handle* handle,
341                                                                         float volume);
342
343 /**
344  * Reads the next samples into the supplied buffer.
345  * \param device The read device.
346  * \param buffer The target buffer.
347  * \param length The length in samples to be filled.
348  * \return True if the reading succeeded, false if there are no sounds
349  *         played back currently, in that case the buffer is filled with
350  *         silence.
351  */
352 extern int AUD_readDevice(AUD_Device* device, data_t* buffer, int length);
353
354 /**
355  * Closes a read device.
356  * \param device The read device.
357  */
358 extern void AUD_closeReadDevice(AUD_Device* device);
359
360 /**
361  * Reads a sound file into a newly created float buffer.
362  * The sound is therefore bandpassed, rectified and resampled.
363  */
364 extern float* AUD_readSoundBuffer(const char* filename, float low, float high,
365                                                                   float attack, float release, float threshold,
366                                                                   int accumulate, int additive, int square,
367                                                                   float sthreshold, int samplerate,
368                                                                   int* length);
369
370 extern AUD_Sound* AUD_createSequencer(void* data, AUD_volumeFunction volume);
371
372 extern void AUD_destroySequencer(AUD_Sound* sequencer);
373
374 extern AUD_SequencerEntry* AUD_addSequencer(AUD_Sound** sequencer, AUD_Sound* sound,
375                                                                                 float begin, float end, float skip, void* data);
376
377 extern void AUD_removeSequencer(AUD_Sound* sequencer, AUD_SequencerEntry* entry);
378
379 extern void AUD_moveSequencer(AUD_Sound* sequencer, AUD_SequencerEntry* entry,
380                                                   float begin, float end, float skip);
381
382 extern void AUD_muteSequencer(AUD_Sound* sequencer, AUD_SequencerEntry* entry,
383                                                   char mute);
384
385 extern int AUD_readSound(AUD_Sound* sound, sample_t* buffer, int length);
386
387 extern void AUD_startPlayback();
388
389 extern void AUD_stopPlayback();
390
391 extern void AUD_seekSequencer(AUD_Handle* handle, float time);
392
393 extern float AUD_getSequencerPosition(AUD_Handle* handle);
394
395 extern void AUD_setSyncCallback(AUD_syncFunction function, void* data);
396
397 extern int AUD_doesPlayback();
398
399 #ifdef __cplusplus
400 }
401 #endif
402
403 #endif //AUD_CAPI