Added another three effects that you can use with the Sound to F-Curve modifier,...
[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_Handle;
52         typedef void AUD_Device;
53 #endif
54
55 /**
56  * Initializes an audio device.
57  * \param device The device type that should be used.
58  * \param specs The audio specification to be used.
59  * \param buffersize The buffersize for the device.
60  * \return Whether the device has been initialized.
61  */
62 extern int AUD_init(AUD_DeviceType device, AUD_DeviceSpecs specs, int buffersize);
63
64 /**
65  * Returns a integer list with available sound devices. The last one is always
66  * AUD_NULL_DEVICE.
67  */
68 extern int* AUD_enumDevices();
69
70 /**
71  * Unitinitializes an audio device.
72  */
73 extern void AUD_exit();
74
75 /**
76  * Locks the playback device.
77  */
78 extern void AUD_lock();
79
80 /**
81  * Unlocks the device.
82  */
83 extern void AUD_unlock();
84
85 /**
86  * Returns information about a sound.
87  * \param sound The sound to get the info about.
88  * \return The AUD_SoundInfo structure with filled in data.
89  */
90 extern AUD_SoundInfo AUD_getInfo(AUD_Sound* sound);
91
92 /**
93  * Loads a sound file.
94  * \param filename The filename of the sound file.
95  * \return A handle of the sound file.
96  */
97 extern AUD_Sound* AUD_load(const char* filename);
98
99 /**
100  * Loads a sound file.
101  * \param buffer The buffer which contains the sound file.
102  * \param size The size of the buffer.
103  * \return A handle of the sound file.
104  */
105 extern AUD_Sound* AUD_loadBuffer(unsigned char* buffer, int size);
106
107 /**
108  * Buffers a sound.
109  * \param sound The sound to buffer.
110  * \return A handle of the sound buffer.
111  */
112 extern AUD_Sound* AUD_bufferSound(AUD_Sound* sound);
113
114 /**
115  * Delays a sound.
116  * \param sound The sound to dealy.
117  * \param delay The delay in seconds.
118  * \return A handle of the delayed sound.
119  */
120 extern AUD_Sound* AUD_delaySound(AUD_Sound* sound, float delay);
121
122 /**
123  * Limits a sound.
124  * \param sound The sound to limit.
125  * \param start The start time in seconds.
126  * \param end The stop time in seconds.
127  * \return A handle of the limited sound.
128  */
129 extern AUD_Sound* AUD_limitSound(AUD_Sound* sound, float start, float end);
130
131 /**
132  * Ping pongs a sound.
133  * \param sound The sound to ping pong.
134  * \return A handle of the ping pong sound.
135  */
136 extern AUD_Sound* AUD_pingpongSound(AUD_Sound* sound);
137
138 /**
139  * Loops a sound.
140  * \param sound The sound to loop.
141  * \return A handle of the looped sound.
142  */
143 extern AUD_Sound* AUD_loopSound(AUD_Sound* sound);
144
145 /**
146  * Stops a looping sound when the current playback finishes.
147  * \param handle The playback handle.
148  * \return Whether the handle is valid.
149  */
150 extern int AUD_stopLoop(AUD_Handle* handle);
151
152 /**
153  * Rectifies a sound.
154  * \param sound The sound to rectify.
155  * \return A handle of the rectified sound.
156  */
157 extern AUD_Sound* AUD_rectifySound(AUD_Sound* sound);
158
159 /**
160  * Unloads a sound of any type.
161  * \param sound The handle of the sound.
162  */
163 extern void AUD_unload(AUD_Sound* sound);
164
165 /**
166  * Plays back a sound file.
167  * \param sound The handle of the sound file.
168  * \param keep When keep is true the sound source will not be deleted but set to
169  *             paused when its end has been reached.
170  * \return A handle to the played back sound.
171  */
172 extern AUD_Handle* AUD_play(AUD_Sound* sound, int keep);
173
174 /**
175  * Pauses a played back sound.
176  * \param handle The handle to the sound.
177  * \return Whether the handle has been playing or not.
178  */
179 extern int AUD_pause(AUD_Handle* handle);
180
181 /**
182  * Resumes a paused sound.
183  * \param handle The handle to the sound.
184  * \return Whether the handle has been paused or not.
185  */
186 extern int AUD_resume(AUD_Handle* handle);
187
188 /**
189  * Stops a playing or paused sound.
190  * \param handle The handle to the sound.
191  * \return Whether the handle has been valid or not.
192  */
193 extern int AUD_stop(AUD_Handle* handle);
194
195 /**
196  * Sets the end behaviour of a playing or paused sound.
197  * \param handle The handle to the sound.
198  * \param keep When keep is true the sound source will not be deleted but set to
199  *             paused when its end has been reached.
200  * \return Whether the handle has been valid or not.
201  */
202 extern int AUD_setKeep(AUD_Handle* handle, int keep);
203
204 /**
205  * Seeks a playing or paused sound.
206  * \param handle The handle to the sound.
207  * \param seekTo From where the sound file should be played back in seconds.
208  * \return Whether the handle has been valid or not.
209  */
210 extern int AUD_seek(AUD_Handle* handle, float seekTo);
211
212 /**
213  * Retrieves the playback position of a handle.
214  * \return The current playback position in seconds or 0.0 if the handle is
215  *         invalid.
216  */
217 extern float AUD_getPosition(AUD_Handle* handle);
218
219 /**
220  * Returns the status of a playing, paused or stopped sound.
221  * \param handle The handle to the sound.
222  * \return The status of the sound behind the handle.
223  */
224 extern AUD_Status AUD_getStatus(AUD_Handle* handle);
225
226 /**
227  * Plays a 3D sound.
228  * \param sound The handle of the sound file.
229  * \param keep When keep is true the sound source will not be deleted but set to
230  *             paused when its end has been reached.
231  * \return A handle to the played back sound.
232  * \note The factory must provide a mono (single channel) source and the device
233  *       must support 3D audio, otherwise the sound is played back normally.
234  */
235 extern AUD_Handle* AUD_play3D(AUD_Sound* sound, int keep);
236
237 /**
238  * Updates the listener 3D data.
239  * \param data The 3D data.
240  * \return Whether the action succeeded.
241  */
242 extern int AUD_updateListener(AUD_3DData* data);
243
244 /**
245  * Sets a 3D device setting.
246  * \param setting The setting type.
247  * \param value The new setting value.
248  * \return Whether the action succeeded.
249  */
250 extern int AUD_set3DSetting(AUD_3DSetting setting, float value);
251
252 /**
253  * Retrieves a 3D device setting.
254  * \param setting The setting type.
255  * \return The setting value.
256  */
257 extern float AUD_get3DSetting(AUD_3DSetting setting);
258
259 /**
260  * Updates a listeners 3D data.
261  * \param handle The source handle.
262  * \param data The 3D data.
263  * \return Whether the action succeeded.
264  */
265 extern int AUD_update3DSource(AUD_Handle* handle, AUD_3DData* data);
266
267 /**
268  * Sets a 3D source setting.
269  * \param handle The source handle.
270  * \param setting The setting type.
271  * \param value The new setting value.
272  * \return Whether the action succeeded.
273  */
274 extern int AUD_set3DSourceSetting(AUD_Handle* handle,
275                                                                   AUD_3DSourceSetting setting, float value);
276
277 /**
278  * Retrieves a 3D source setting.
279  * \param handle The source handle.
280  * \param setting The setting type.
281  * \return The setting value.
282  */
283 extern float AUD_get3DSourceSetting(AUD_Handle* handle,
284                                                                         AUD_3DSourceSetting setting);
285
286 /**
287  * Sets the volume of a played back sound.
288  * \param handle The handle to the sound.
289  * \param volume The new volume, must be between 0.0 and 1.0.
290  * \return Whether the action succeeded.
291  */
292 extern int AUD_setSoundVolume(AUD_Handle* handle, float volume);
293
294 /**
295  * Sets the pitch of a played back sound.
296  * \param handle The handle to the sound.
297  * \param pitch The new pitch.
298  * \return Whether the action succeeded.
299  */
300 extern int AUD_setSoundPitch(AUD_Handle* handle, float pitch);
301
302 /**
303  * Opens a read device, with which audio data can be read.
304  * \param specs The specification of the audio data.
305  * \return A device handle.
306  */
307 extern AUD_Device* AUD_openReadDevice(AUD_DeviceSpecs specs);
308
309 /**
310  * Sets the main volume of a device.
311  * \param device The device.
312  * \param volume The new volume, must be between 0.0 and 1.0.
313  * \return Whether the action succeeded.
314  */
315 extern int AUD_setDeviceVolume(AUD_Device* device, float volume);
316
317 /**
318  * Plays back a sound file through a read device.
319  * \param device The read device.
320  * \param sound The handle of the sound file.
321  * \return A handle to the played back sound.
322  */
323 extern AUD_Handle* AUD_playDevice(AUD_Device* device, AUD_Sound* sound);
324
325 /**
326  * Sets the volume of a played back sound of a read device.
327  * \param device The read device.
328  * \param handle The handle to the sound.
329  * \param volume The new volume, must be between 0.0 and 1.0.
330  * \return Whether the action succeeded.
331  */
332 extern int AUD_setDeviceSoundVolume(AUD_Device* device,
333                                                                         AUD_Handle* handle,
334                                                                         float volume);
335
336 /**
337  * Reads the next samples into the supplied buffer.
338  * \param device The read device.
339  * \param buffer The target buffer.
340  * \param length The length in samples to be filled.
341  * \return True if the reading succeeded, false if there are no sounds
342  *         played back currently, in that case the buffer is filled with
343  *         silence.
344  */
345 extern int AUD_readDevice(AUD_Device* device, data_t* buffer, int length);
346
347 /**
348  * Closes a read device.
349  * \param device The read device.
350  */
351 extern void AUD_closeReadDevice(AUD_Device* device);
352
353 /**
354  * Reads a sound file into a newly created float buffer.
355  * The sound is therefore bandpassed, rectified and resampled.
356  */
357 extern float* AUD_readSoundBuffer(const char* filename, float low, float high,
358                                                                   float attack, float release, float threshold,
359                                                                   int accumulate, int additive, int square,
360                                                                   float sthreshold, int samplerate,
361                                                                   int* length);
362
363 #ifdef __cplusplus
364 }
365 #endif
366
367 #endif //AUD_CAPI