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