ce1791886de5be548343d41aef55c3dd3c5cf90e
[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 #endif
56
57 /**
58  * Initializes an audio device.
59  * \param device The device type that should be used.
60  * \param specs The audio specification to be used.
61  * \param buffersize The buffersize for the device.
62  * \return Whether the device has been initialized.
63  */
64 extern int AUD_init(AUD_DeviceType device, AUD_DeviceSpecs specs, int buffersize);
65
66 /**
67  * Returns a integer list with available sound devices. The last one is always
68  * AUD_NULL_DEVICE.
69  */
70 extern int* AUD_enumDevices();
71
72 /**
73  * Unitinitializes an audio device.
74  */
75 extern void AUD_exit();
76
77 /**
78  * Locks the playback device.
79  */
80 extern void AUD_lock();
81
82 /**
83  * Unlocks the device.
84  */
85 extern void AUD_unlock();
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  * \param time The time after which playback should stop, -1 for infinity.
152  * \return Whether the handle is valid.
153  */
154 extern int AUD_setLoop(AUD_Handle* handle, int loops, float time);
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_Handle* 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_Handle* 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_Handle* 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_Handle* 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_Handle* 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_Handle* 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_Handle* 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_Handle* handle);
230
231 /**
232  * Plays a 3D sound.
233  * \param sound The handle of the sound file.
234  * \param keep When keep is true the sound source will not be deleted but set to
235  *             paused when its end has been reached.
236  * \return A handle to the played back sound.
237  * \note The factory must provide a mono (single channel) source and the device
238  *       must support 3D audio, otherwise the sound is played back normally.
239  */
240 extern AUD_Handle* AUD_play3D(AUD_Sound* sound, int keep);
241
242 /**
243  * Updates the listener 3D data.
244  * \param data The 3D data.
245  * \return Whether the action succeeded.
246  */
247 extern int AUD_updateListener(AUD_3DData* data);
248
249 /**
250  * Sets a 3D device setting.
251  * \param setting The setting type.
252  * \param value The new setting value.
253  * \return Whether the action succeeded.
254  */
255 extern int AUD_set3DSetting(AUD_3DSetting setting, float value);
256
257 /**
258  * Retrieves a 3D device setting.
259  * \param setting The setting type.
260  * \return The setting value.
261  */
262 extern float AUD_get3DSetting(AUD_3DSetting setting);
263
264 /**
265  * Updates a listeners 3D data.
266  * \param handle The source handle.
267  * \param data The 3D data.
268  * \return Whether the action succeeded.
269  */
270 extern int AUD_update3DSource(AUD_Handle* handle, AUD_3DData* data);
271
272 /**
273  * Sets a 3D source setting.
274  * \param handle The source handle.
275  * \param setting The setting type.
276  * \param value The new setting value.
277  * \return Whether the action succeeded.
278  */
279 extern int AUD_set3DSourceSetting(AUD_Handle* handle,
280                                                                   AUD_3DSourceSetting setting, float value);
281
282 /**
283  * Retrieves a 3D source setting.
284  * \param handle The source handle.
285  * \param setting The setting type.
286  * \return The setting value.
287  */
288 extern float AUD_get3DSourceSetting(AUD_Handle* handle,
289                                                                         AUD_3DSourceSetting setting);
290
291 /**
292  * Sets the volume of a played back sound.
293  * \param handle The handle to the sound.
294  * \param volume The new volume, must be between 0.0 and 1.0.
295  * \return Whether the action succeeded.
296  */
297 extern int AUD_setSoundVolume(AUD_Handle* handle, float volume);
298
299 /**
300  * Sets the pitch of a played back sound.
301  * \param handle The handle to the sound.
302  * \param pitch The new pitch.
303  * \return Whether the action succeeded.
304  */
305 extern int AUD_setSoundPitch(AUD_Handle* handle, float pitch);
306
307 /**
308  * Opens a read device, with which audio data can be read.
309  * \param specs The specification of the audio data.
310  * \return A device handle.
311  */
312 extern AUD_Device* AUD_openReadDevice(AUD_DeviceSpecs specs);
313
314 /**
315  * Sets the main volume of a device.
316  * \param device The device.
317  * \param volume The new volume, must be between 0.0 and 1.0.
318  * \return Whether the action succeeded.
319  */
320 extern int AUD_setDeviceVolume(AUD_Device* device, float volume);
321
322 /**
323  * Plays back a sound file through a read device.
324  * \param device The read device.
325  * \param sound The handle of the sound file.
326  * \param seek The position where the sound should be seeked to.
327  * \return A handle to the played back sound.
328  */
329 extern AUD_Handle* AUD_playDevice(AUD_Device* device, AUD_Sound* sound, float seek);
330
331 /**
332  * Sets the volume of a played back sound of a read device.
333  * \param device The read device.
334  * \param handle The handle to the sound.
335  * \param volume The new volume, must be between 0.0 and 1.0.
336  * \return Whether the action succeeded.
337  */
338 extern int AUD_setDeviceSoundVolume(AUD_Device* device,
339                                                                         AUD_Handle* handle,
340                                                                         float volume);
341
342 /**
343  * Reads the next samples into the supplied buffer.
344  * \param device The read device.
345  * \param buffer The target buffer.
346  * \param length The length in samples to be filled.
347  * \return True if the reading succeeded, false if there are no sounds
348  *         played back currently, in that case the buffer is filled with
349  *         silence.
350  */
351 extern int AUD_readDevice(AUD_Device* device, data_t* buffer, int length);
352
353 /**
354  * Closes a read device.
355  * \param device The read device.
356  */
357 extern void AUD_closeReadDevice(AUD_Device* device);
358
359 /**
360  * Reads a sound file into a newly created float buffer.
361  * The sound is therefore bandpassed, rectified and resampled.
362  */
363 extern float* AUD_readSoundBuffer(const char* filename, float low, float high,
364                                                                   float attack, float release, float threshold,
365                                                                   int accumulate, int additive, int square,
366                                                                   float sthreshold, int samplerate,
367                                                                   int* length);
368
369 extern AUD_Sound* AUD_createSequencer(void* data, AUD_volumeFunction volume);
370
371 extern void AUD_destroySequencer(AUD_Sound* sequencer);
372
373 extern AUD_SequencerEntry* AUD_addSequencer(AUD_Sound** sequencer, AUD_Sound* sound,
374                                                                                 float begin, float end, float skip, void* data);
375
376 extern void AUD_removeSequencer(AUD_Sound* sequencer, AUD_SequencerEntry* entry);
377
378 extern void AUD_moveSequencer(AUD_Sound* sequencer, AUD_SequencerEntry* entry,
379                                                   float begin, float end, float skip);
380
381 extern void AUD_muteSequencer(AUD_Sound* sequencer, AUD_SequencerEntry* entry,
382                                                   char mute);
383
384 extern int AUD_readSound(AUD_Sound* sound, sample_t* buffer, int length);
385
386 #ifdef __cplusplus
387 }
388 #endif
389
390 #endif //AUD_CAPI