Audaspace:
[blender-staging.git] / intern / audaspace / intern / AUD_C-API.h
1 /*
2  * ***** BEGIN GPL LICENSE BLOCK *****
3  *
4  * Copyright 2009-2011 Jörg Hermann Müller
5  *
6  * This file is part of AudaSpace.
7  *
8  * Audaspace is free software; you can redistribute it and/or modify
9  * it under the terms of the GNU General Public License as published by
10  * the Free Software Foundation; either version 2 of the License, or
11  * (at your option) any later version.
12  *
13  * AudaSpace is distributed in the hope that it will be useful,
14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
16  * GNU General Public License for more details.
17  *
18  * You should have received a copy of the GNU General Public License
19  * along with Audaspace; if not, write to the Free Software Foundation,
20  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
21  *
22  * ***** END GPL LICENSE BLOCK *****
23  */
24
25 /** \file AUD_C-API.h
26  *  \ingroup audaspace
27  */
28  
29 #ifndef __AUD_C_API_H__
30 #define __AUD_C_API_H__
31
32 #ifdef __cplusplus
33 extern "C" {
34 #endif
35
36 #include "AUD_Space.h"
37
38 /// Supported output devices.
39 typedef enum
40 {
41         AUD_NULL_DEVICE = 0,
42         AUD_SDL_DEVICE,
43         AUD_OPENAL_DEVICE,
44         AUD_JACK_DEVICE
45 } AUD_DeviceType;
46
47 /// Sound information structure.
48 typedef struct
49 {
50         AUD_Specs specs;
51         float length;
52 } AUD_SoundInfo;
53
54 #ifndef AUD_CAPI_IMPLEMENTATION
55         typedef void AUD_Sound;
56         typedef void AUD_Handle;
57         typedef void AUD_Device;
58         typedef void AUD_SEntry;
59         typedef float (*AUD_volumeFunction)(void *, void *, float);
60         typedef void (*AUD_syncFunction)(void *, int, float);
61 #endif
62
63 /**
64  * Initializes FFMPEG if it is enabled.
65  */
66 extern void AUD_initOnce(void);
67
68 /**
69  * Initializes an audio device.
70  * \param device The device type that should be used.
71  * \param specs The audio specification to be used.
72  * \param buffersize The buffersize for the device.
73  * \return Whether the device has been initialized.
74  */
75 extern int AUD_init(AUD_DeviceType device, AUD_DeviceSpecs specs, int buffersize);
76
77 /**
78  * Unitinitializes an audio device.
79  */
80 extern void AUD_exit(void);
81
82 /**
83  * Locks the playback device.
84  */
85 extern void AUD_lock(void);
86
87 /**
88  * Unlocks the device.
89  */
90 extern void AUD_unlock(void);
91
92 /**
93  * Returns information about a sound.
94  * \param sound The sound to get the info about.
95  * \return The AUD_SoundInfo structure with filled in data.
96  */
97 extern AUD_SoundInfo AUD_getInfo(AUD_Sound *sound);
98
99 /**
100  * Loads a sound file.
101  * \param filename The filename of the sound file.
102  * \return A handle of the sound file.
103  */
104 extern AUD_Sound *AUD_load(const char *filename);
105
106 /**
107  * Loads a sound file.
108  * \param buffer The buffer which contains the sound file.
109  * \param size The size of the buffer.
110  * \return A handle of the sound file.
111  */
112 extern AUD_Sound *AUD_loadBuffer(unsigned char *buffer, int size);
113
114 /**
115  * Buffers a sound.
116  * \param sound The sound to buffer.
117  * \return A handle of the sound buffer.
118  */
119 extern AUD_Sound *AUD_bufferSound(AUD_Sound *sound);
120
121 /**
122  * Rechannels the sound to be mono.
123  * \param sound The sound to rechannel.
124  * \return The mono sound.
125  */
126 extern AUD_Sound *AUD_monoSound(AUD_Sound *sound);
127
128 /**
129  * Delays a sound.
130  * \param sound The sound to dealy.
131  * \param delay The delay in seconds.
132  * \return A handle of the delayed sound.
133  */
134 extern AUD_Sound *AUD_delaySound(AUD_Sound *sound, float delay);
135
136 /**
137  * Limits a sound.
138  * \param sound The sound to limit.
139  * \param start The start time in seconds.
140  * \param end The stop time in seconds.
141  * \return A handle of the limited sound.
142  */
143 extern AUD_Sound *AUD_limitSound(AUD_Sound *sound, float start, float end);
144
145 /**
146  * Ping pongs a sound.
147  * \param sound The sound to ping pong.
148  * \return A handle of the ping pong sound.
149  */
150 extern AUD_Sound *AUD_pingpongSound(AUD_Sound *sound);
151
152 /**
153  * Loops a sound.
154  * \param sound The sound to loop.
155  * \return A handle of the looped sound.
156  */
157 extern AUD_Sound *AUD_loopSound(AUD_Sound *sound);
158
159 /**
160  * Sets a remaining loop count of a looping sound that currently plays.
161  * \param handle The playback handle.
162  * \param loops The count of remaining loops, -1 for infinity.
163  * \return Whether the handle is valid.
164  */
165 extern int AUD_setLoop(AUD_Handle *handle, int loops);
166
167 /**
168  * Rectifies a sound.
169  * \param sound The sound to rectify.
170  * \return A handle of the rectified sound.
171  */
172 extern AUD_Sound *AUD_rectifySound(AUD_Sound *sound);
173
174 /**
175  * Unloads a sound of any type.
176  * \param sound The handle of the sound.
177  */
178 extern void AUD_unload(AUD_Sound *sound);
179
180 /**
181  * Plays back a sound file.
182  * \param sound The handle of the sound file.
183  * \param keep When keep is true the sound source will not be deleted but set to
184  *             paused when its end has been reached.
185  * \return A handle to the played back sound.
186  */
187 extern AUD_Handle *AUD_play(AUD_Sound *sound, int keep);
188
189 /**
190  * Pauses a played back sound.
191  * \param handle The handle to the sound.
192  * \return Whether the handle has been playing or not.
193  */
194 extern int AUD_pause(AUD_Handle *handle);
195
196 /**
197  * Resumes a paused sound.
198  * \param handle The handle to the sound.
199  * \return Whether the handle has been paused or not.
200  */
201 extern int AUD_resume(AUD_Handle *handle);
202
203 /**
204  * Stops a playing or paused sound.
205  * \param handle The handle to the sound.
206  * \return Whether the handle has been valid or not.
207  */
208 extern int AUD_stop(AUD_Handle *handle);
209
210 /**
211  * Sets the end behaviour of a playing or paused sound.
212  * \param handle The handle to the sound.
213  * \param keep When keep is true the sound source will not be deleted but set to
214  *             paused when its end has been reached.
215  * \return Whether the handle has been valid or not.
216  */
217 extern int AUD_setKeep(AUD_Handle *handle, int keep);
218
219 /**
220  * Seeks a playing or paused sound.
221  * \param handle The handle to the sound.
222  * \param seekTo From where the sound file should be played back in seconds.
223  * \return Whether the handle has been valid or not.
224  */
225 extern int AUD_seek(AUD_Handle *handle, float seekTo);
226
227 /**
228  * Retrieves the playback position of a handle.
229  * \param handle The handle to the sound.
230  * \return The current playback position in seconds or 0.0 if the handle is
231  *         invalid.
232  */
233 extern float AUD_getPosition(AUD_Handle *handle);
234
235 /**
236  * Returns the status of a playing, paused or stopped sound.
237  * \param handle The handle to the sound.
238  * \return The status of the sound behind the handle.
239  */
240 extern AUD_Status AUD_getStatus(AUD_Handle *handle);
241
242 /**
243  * Sets the listener location.
244  * \param location The new location.
245  */
246 extern int AUD_setListenerLocation(const float location[3]);
247
248 /**
249  * Sets the listener velocity.
250  * \param velocity The new velocity.
251  */
252 extern int AUD_setListenerVelocity(const float velocity[3]);
253
254 /**
255  * Sets the listener orientation.
256  * \param orientation The new orientation as quaternion.
257  */
258 extern int AUD_setListenerOrientation(const float orientation[4]);
259
260 /**
261  * Sets the speed of sound.
262  * This value is needed for doppler effect calculation.
263  * \param speed The new speed of sound.
264  */
265 extern int AUD_setSpeedOfSound(float speed);
266
267 /**
268  * Sets the doppler factor.
269  * This value is a scaling factor for the velocity vectors of sources and
270  * listener which is used while calculating the doppler effect.
271  * \param factor The new doppler factor.
272  */
273 extern int AUD_setDopplerFactor(float factor);
274
275 /**
276  * Sets the distance model.
277  * \param model distance model.
278  */
279 extern int AUD_setDistanceModel(AUD_DistanceModel model);
280
281 /**
282  * Sets the location of a source.
283  * \param handle The handle of the source.
284  * \param location The new location.
285  * \return Whether the action succeeded.
286  */
287 extern int AUD_setSourceLocation(AUD_Handle *handle, const float location[3]);
288
289 /**
290  * Sets the velocity of a source.
291  * \param handle The handle of the source.
292  * \param velocity The new velocity.
293  * \return Whether the action succeeded.
294  */
295 extern int AUD_setSourceVelocity(AUD_Handle *handle, const float velocity[3]);
296
297 /**
298  * Sets the orientation of a source.
299  * \param handle The handle of the source.
300  * \param orientation The new orientation as quaternion.
301  * \return Whether the action succeeded.
302  */
303 extern int AUD_setSourceOrientation(AUD_Handle *handle, const float orientation[4]);
304
305 /**
306  * Sets whether the source location, velocity and orientation are relative
307  * to the listener.
308  * \param handle The handle of the source.
309  * \param relative Whether the source is relative.
310  * \return Whether the action succeeded.
311  */
312 extern int AUD_setRelative(AUD_Handle *handle, int relative);
313
314 /**
315  * Sets the maximum volume of a source.
316  * \param handle The handle of the source.
317  * \param volume The new maximum volume.
318  * \return Whether the action succeeded.
319  */
320 extern int AUD_setVolumeMaximum(AUD_Handle *handle, float volume);
321
322 /**
323  * Sets the minimum volume of a source.
324  * \param handle The handle of the source.
325  * \param volume The new minimum volume.
326  * \return Whether the action succeeded.
327  */
328 extern int AUD_setVolumeMinimum(AUD_Handle *handle, float volume);
329
330 /**
331  * Sets the maximum distance of a source.
332  * If a source is further away from the reader than this distance, the
333  * volume will automatically be set to 0.
334  * \param handle The handle of the source.
335  * \param distance The new maximum distance.
336  * \return Whether the action succeeded.
337  */
338 extern int AUD_setDistanceMaximum(AUD_Handle *handle, float distance);
339
340 /**
341  * Sets the reference distance of a source.
342  * \param handle The handle of the source.
343  * \param distance The new reference distance.
344  * \return Whether the action succeeded.
345  */
346 extern int AUD_setDistanceReference(AUD_Handle *handle, float distance);
347
348 /**
349  * Sets the attenuation of a source.
350  * This value is used for distance calculation.
351  * \param handle The handle of the source.
352  * \param factor The new attenuation.
353  * \return Whether the action succeeded.
354  */
355 extern int AUD_setAttenuation(AUD_Handle *handle, float factor);
356
357 /**
358  * Sets the outer angle of the cone of a source.
359  * \param handle The handle of the source.
360  * \param angle The new outer angle of the cone.
361  * \return Whether the action succeeded.
362  */
363 extern int AUD_setConeAngleOuter(AUD_Handle *handle, float angle);
364
365 /**
366  * Sets the inner angle of the cone of a source.
367  * \param handle The handle of the source.
368  * \param angle The new inner angle of the cone.
369  * \return Whether the action succeeded.
370  */
371 extern int AUD_setConeAngleInner(AUD_Handle *handle, float angle);
372
373 /**
374  * Sets the outer volume of the cone of a source.
375  * The volume between inner and outer angle is interpolated between inner
376  * volume and this value.
377  * \param handle The handle of the source.
378  * \param volume The new outer volume of the cone.
379  * \return Whether the action succeeded.
380  */
381 extern int AUD_setConeVolumeOuter(AUD_Handle *handle, float volume);
382
383 /**
384  * Sets the volume of a played back sound.
385  * \param handle The handle to the sound.
386  * \param volume The new volume, must be between 0.0 and 1.0.
387  * \return Whether the action succeeded.
388  */
389 extern int AUD_setSoundVolume(AUD_Handle *handle, float volume);
390
391 /**
392  * Sets the pitch of a played back sound.
393  * \param handle The handle to the sound.
394  * \param pitch The new pitch.
395  * \return Whether the action succeeded.
396  */
397 extern int AUD_setSoundPitch(AUD_Handle *handle, float pitch);
398
399 /**
400  * Opens a read device, with which audio data can be read.
401  * \param specs The specification of the audio data.
402  * \return A device handle.
403  */
404 extern AUD_Device *AUD_openReadDevice(AUD_DeviceSpecs specs);
405
406 /**
407  * Sets the main volume of a device.
408  * \param device The device.
409  * \param volume The new volume, must be between 0.0 and 1.0.
410  * \return Whether the action succeeded.
411  */
412 extern int AUD_setDeviceVolume(AUD_Device *device, float volume);
413
414 /**
415  * Plays back a sound file through a read device.
416  * \param device The read device.
417  * \param sound The handle of the sound file.
418  * \param seek The position where the sound should be seeked to.
419  * \return A handle to the played back sound.
420  */
421 extern AUD_Handle *AUD_playDevice(AUD_Device *device, AUD_Sound *sound, float seek);
422
423 /**
424  * Reads the next samples into the supplied buffer.
425  * \param device The read device.
426  * \param buffer The target buffer.
427  * \param length The length in samples to be filled.
428  * \return True if the reading succeeded, false if there are no sounds
429  *         played back currently, in that case the buffer is filled with
430  *         silence.
431  */
432 extern int AUD_readDevice(AUD_Device *device, data_t *buffer, int length);
433
434 /**
435  * Closes a read device.
436  * \param device The read device.
437  */
438 extern void AUD_closeReadDevice(AUD_Device *device);
439
440 /**
441  * Reads a sound file into a newly created float buffer.
442  * The sound is therefore bandpassed, rectified and resampled.
443  */
444 extern float *AUD_readSoundBuffer(const char *filename, float low, float high,
445                                   float attack, float release, float threshold,
446                                   int accumulate, int additive, int square,
447                                   float sthreshold, double samplerate,
448                                   int *length);
449
450 /**
451  * Pauses a playing sound after a specific amount of time.
452  * \param handle The handle to the sound.
453  * \param seconds The time in seconds.
454  * \return The silence handle.
455  */
456 extern AUD_Handle *AUD_pauseAfter(AUD_Handle *handle, float seconds);
457
458 /**
459  * Creates a new sequenced sound scene.
460  * \param fps The FPS of the scene.
461  * \param muted Whether the scene is muted.
462  * \return The new sound scene.
463  */
464 extern AUD_Sound *AUD_createSequencer(float fps, int muted);
465
466 /**
467  * Deletes a sound scene.
468  * \param sequencer The sound scene.
469  */
470 extern void AUD_destroySequencer(AUD_Sound *sequencer);
471
472 /**
473  * Sets the muting state of the scene.
474  * \param sequencer The sound scene.
475  * \param muted Whether the scene is muted.
476  */
477 extern void AUD_setSequencerMuted(AUD_Sound *sequencer, int muted);
478
479 /**
480  * Sets the scene's FPS.
481  * \param sequencer The sound scene.
482  * \param fps The new FPS.
483  */
484 extern void AUD_setSequencerFPS(AUD_Sound *sequencer, float fps);
485
486 /**
487  * Adds a new entry to the scene.
488  * \param sequencer The sound scene.
489  * \param sound The sound this entry should play.
490  * \param begin The start time.
491  * \param end The end time or a negative value if determined by the sound.
492  * \param skip How much seconds should be skipped at the beginning.
493  * \return The entry added.
494  */
495 extern AUD_SEntry *AUD_addSequence(AUD_Sound *sequencer, AUD_Sound *sound,
496                                    float begin, float end, float skip);
497
498 /**
499  * Removes an entry from the scene.
500  * \param sequencer The sound scene.
501  * \param entry The entry to remove.
502  */
503 extern void AUD_removeSequence(AUD_Sound *sequencer, AUD_SEntry *entry);
504
505 /**
506  * Moves the entry.
507  * \param entry The sequenced entry.
508  * \param begin The new start time.
509  * \param end The new end time or a negative value if unknown.
510  * \param skip How many seconds to skip at the beginning.
511  */
512 extern void AUD_moveSequence(AUD_SEntry *entry, float begin, float end, float skip);
513
514 /**
515  * Sets the muting state of the entry.
516  * \param entry The sequenced entry.
517  * \param mute Whether the entry should be muted or not.
518  */
519 extern void AUD_muteSequence(AUD_SEntry *entry, char mute);
520
521 /**
522  * Sets whether the entrie's location, velocity and orientation are relative
523  * to the listener.
524  * \param entry The sequenced entry.
525  * \param relative Whether the source is relative.
526  * \return Whether the action succeeded.
527  */
528 extern void AUD_setRelativeSequence(AUD_SEntry *entry, char relative);
529
530 /**
531  * Sets the sound of the entry.
532  * \param entry The sequenced entry.
533  * \param sound The new sound.
534  */
535 extern void AUD_updateSequenceSound(AUD_SEntry *entry, AUD_Sound *sound);
536
537 /**
538  * Writes animation data to a sequenced entry.
539  * \param entry The sequenced entry.
540  * \param type The type of animation data.
541  * \param frame The frame this data is for.
542  * \param data The data to write.
543  * \param animated Whether the attribute is animated.
544  */
545 extern void AUD_setSequenceAnimData(AUD_SEntry *entry, AUD_AnimateablePropertyType type, int frame, float *data, char animated);
546
547 /**
548  * Writes animation data to a sequenced entry.
549  * \param sequencer The sound scene.
550  * \param type The type of animation data.
551  * \param frame The frame this data is for.
552  * \param data The data to write.
553  * \param animated Whether the attribute is animated.
554  */
555 extern void AUD_setSequencerAnimData(AUD_Sound *sequencer, AUD_AnimateablePropertyType type, int frame, float *data, char animated);
556
557 /**
558  * Updates all non-animated parameters of the entry.
559  * \param entry The sequenced entry.
560  * \param volume_max The maximum volume.
561  * \param volume_min The minimum volume.
562  * \param distance_max The maximum distance.
563  * \param distance_reference The reference distance.
564  * \param attenuation The attenuation.
565  * \param cone_angle_outer The outer cone opening angle.
566  * \param cone_angle_inner The inner cone opening angle.
567  * \param cone_volume_outer The volume outside the outer cone.
568  */
569 extern void AUD_updateSequenceData(AUD_SEntry *entry, float volume_max, float volume_min,
570                                    float distance_max, float distance_reference, float attenuation,
571                                    float cone_angle_outer, float cone_angle_inner, float cone_volume_outer);
572
573 /**
574  * Updates all non-animated parameters of the entry.
575  * \param sequencer The sound scene.
576  * \param speed_of_sound The speed of sound for doppler calculation.
577  * \param factor The doppler factor to control the effect's strength.
578  * \param model The distance model for distance calculation.
579  */
580 extern void AUD_updateSequencerData(AUD_Sound *sequencer, float speed_of_sound,
581                                     float factor, AUD_DistanceModel model);
582
583 /**
584  * Sets the audio output specification of the sound scene to the specs of the
585  * current playback device.
586  * \param sequencer The sound scene.
587  */
588 extern void AUD_setSequencerDeviceSpecs(AUD_Sound *sequencer);
589
590 /**
591  * Sets the audio output specification of the sound scene.
592  * \param sequencer The sound scene.
593  * \param specs The new specification.
594  */
595 extern void AUD_setSequencerSpecs(AUD_Sound *sequencer, AUD_Specs specs);
596
597 /**
598  * Seeks sequenced sound scene playback.
599  * \param handle Playback handle.
600  * \param time Time in seconds to seek to.
601  */
602 extern void AUD_seekSequencer(AUD_Handle *handle, float time);
603
604 /**
605  * Returns the current sound scene playback time.
606  * \param handle Playback handle.
607  * \return The playback time in seconds.
608  */
609 extern float AUD_getSequencerPosition(AUD_Handle *handle);
610
611 /**
612  * Starts the playback of jack transport if possible.
613  */
614 extern void AUD_startPlayback(void);
615
616 /**
617  * Stops the playback of jack transport if possible.
618  */
619 extern void AUD_stopPlayback(void);
620
621 #ifdef WITH_JACK
622 /**
623  * Sets the sync callback for jack transport.
624  * \param function The callback function.
625  * \param data The data parameter for the callback.
626  */
627 extern void AUD_setSyncCallback(AUD_syncFunction function, void *data);
628 #endif
629
630 /**
631  * Returns whether jack transport is currently playing.
632  * \return Whether jack transport is currently playing.
633  */
634 extern int AUD_doesPlayback(void);
635
636 /**
637  * Reads a sound into a buffer for drawing at a specific sampling rate.
638  * \param sound The sound to read.
639  * \param buffer The buffer to write to. Must have a size of 3*4*length.
640  * \param length How many samples to read from the sound.
641  * \param samples_per_second How many samples to read per second of the sound.
642  * \return How many samples really have been read. Always <= length.
643  */
644 extern int AUD_readSound(AUD_Sound *sound, sample_t *buffer, int length, int samples_per_second);
645
646 /**
647  * Copies a sound.
648  * \param sound Sound to copy.
649  * \return Copied sound.
650  */
651 extern AUD_Sound *AUD_copy(AUD_Sound *sound);
652
653 /**
654  * Frees a handle.
655  * \param channel Handle to free.
656  */
657 extern void AUD_freeHandle(AUD_Handle *channel);
658
659 /**
660  * Creates a new set.
661  * \return The new set.
662  */
663 extern void *AUD_createSet(void);
664
665 /**
666  * Deletes a set.
667  * \param set The set to delete.
668  */
669 extern void AUD_destroySet(void *set);
670
671 /**
672  * Removes an entry from a set.
673  * \param set The set work on.
674  * \param entry The entry to remove.
675  * \return Whether the entry was in the set or not.
676  */
677 extern char AUD_removeSet(void *set, void *entry);
678
679 /**
680  * Adds a new entry to a set.
681  * \param set The set work on.
682  * \param entry The entry to add.
683  */
684 extern void AUD_addSet(void *set, void *entry);
685
686 /**
687  * Removes one entry from a set and returns it.
688  * \param set The set work on.
689  * \return The entry or NULL if the set is empty.
690  */
691 extern void *AUD_getSet(void *set);
692
693 /**
694  * Mixes a sound down into a file.
695  * \param sound The sound scene to mix down.
696  * \param start The start frame.
697  * \param length The count of frames to write.
698  * \param buffersize How many samples should be written at once.
699  * \param filename The file to write to.
700  * \param specs The file's audio specification.
701  * \param format The file's container format.
702  * \param codec The codec used for encoding the audio data.
703  * \param bitrate The bitrate for encoding.
704  * \return An error message or NULL in case of success.
705  */
706 extern const char *AUD_mixdown(AUD_Sound *sound, unsigned int start, unsigned int length,
707                                unsigned int buffersize, const char *filename,
708                                AUD_DeviceSpecs specs, AUD_Container format,
709                                AUD_Codec codec, unsigned int bitrate);
710
711 /**
712  * Mixes a sound down into multiple files.
713  * \param sound The sound scene to mix down.
714  * \param start The start frame.
715  * \param length The count of frames to write.
716  * \param buffersize How many samples should be written at once.
717  * \param filename The file to write to, the channel number and an underscore are added at the beginning.
718  * \param specs The file's audio specification.
719  * \param format The file's container format.
720  * \param codec The codec used for encoding the audio data.
721  * \param bitrate The bitrate for encoding.
722  * \return An error message or NULL in case of success.
723  */
724 extern const char *AUD_mixdown_per_channel(AUD_Sound *sound, unsigned int start, unsigned int length,
725                                            unsigned int buffersize, const char *filename,
726                                            AUD_DeviceSpecs specs, AUD_Container format,
727                                            AUD_Codec codec, unsigned int bitrate);
728
729 /**
730  * Opens a read device and prepares it for mixdown of the sound scene.
731  * \param specs Output audio specifications.
732  * \param sequencer The sound scene to mix down.
733  * \param volume The overall mixdown volume.
734  * \param start The start time of the mixdown in the sound scene.
735  * \return The read device for the mixdown.
736  */
737 extern AUD_Device *AUD_openMixdownDevice(AUD_DeviceSpecs specs, AUD_Sound *sequencer, float volume, float start);
738
739 #ifdef WITH_PYTHON
740 /**
741  * Retrieves the python factory of a sound.
742  * \param sound The sound factory.
743  * \return The python factory.
744  */
745 extern void *AUD_getPythonFactory(AUD_Sound *sound);
746
747 /**
748  * Retrieves the sound factory of a python factory.
749  * \param sound The python factory.
750  * \return The sound factory.
751  */
752 extern AUD_Sound *AUD_getPythonSound(void *sound);
753 #endif
754
755 #ifdef __cplusplus
756 }
757
758 #include <boost/shared_ptr.hpp>
759 class AUD_IDevice;
760 class AUD_I3DDevice;
761
762 /**
763  * Returns the current playback device.
764  * \return The playback device.
765  */
766 boost::shared_ptr<AUD_IDevice> AUD_getDevice();
767
768 /**
769  * Returns the current playback 3D device.
770  * \return The playback 3D device.
771  */
772 AUD_I3DDevice *AUD_get3DDevice();
773 #endif
774
775 #endif //__AUD_C_API_H__