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