3D Audio GSoC:
[blender.git] / intern / audaspace / intern / AUD_C-API.h
index 71b5ca82430e41007d543be2b7173f27f005864c..abcbd21507487832ed7b7780d119f7d39e587f40 100644 (file)
@@ -1,31 +1,40 @@
 /*
  * $Id$
  *
- * ***** BEGIN LGPL LICENSE BLOCK *****
+ * ***** BEGIN GPL LICENSE BLOCK *****
  *
- * Copyright 2009 Jörg Hermann Müller
+ * Copyright 2009-2011 Jörg Hermann Müller
  *
  * This file is part of AudaSpace.
  *
- * AudaSpace is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Lesser General Public License as published by
- * the Free Software Foundation, either version 3 of the License, or
+ * Audaspace is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
  * (at your option) any later version.
  *
  * AudaSpace is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU Lesser General Public License for more details.
+ * GNU General Public License for more details.
  *
- * You should have received a copy of the GNU Lesser General Public License
- * along with AudaSpace.  If not, see <http://www.gnu.org/licenses/>.
+ * You should have received a copy of the GNU General Public License
+ * along with Audaspace; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  *
- * ***** END LGPL LICENSE BLOCK *****
+ * ***** END GPL LICENSE BLOCK *****
  */
 
+/** \file AUD_C-API.h
+ *  \ingroup audaspace
+ */
 #ifndef AUD_CAPI
 #define AUD_CAPI
 
+#ifdef WITH_PYTHON
+#include "Python.h"
+#endif
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -48,9 +57,9 @@ typedef struct
 
 #ifndef AUD_CAPI_IMPLEMENTATION
        typedef void AUD_Sound;
-       typedef void AUD_Channel;
+       typedef void AUD_Handle;
        typedef void AUD_Device;
-       typedef void AUD_SequencerEntry;
+       typedef void AUD_SEntry;
        typedef float (*AUD_volumeFunction)(void*, void*, float);
        typedef void (*AUD_syncFunction)(void*, int, float);
 #endif
@@ -150,7 +159,7 @@ extern AUD_Sound* AUD_loopSound(AUD_Sound* sound);
  * \param loops The count of remaining loops, -1 for infinity.
  * \return Whether the handle is valid.
  */
-extern int AUD_setLoop(AUD_Channel* handle, int loops);
+extern int AUD_setLoop(AUD_Handle* handle, int loops);
 
 /**
  * Rectifies a sound.
@@ -172,28 +181,28 @@ extern void AUD_unload(AUD_Sound* sound);
  *             paused when its end has been reached.
  * \return A handle to the played back sound.
  */
-extern AUD_Channel* AUD_play(AUD_Sound* sound, int keep);
+extern AUD_Handle* AUD_play(AUD_Sound* sound, int keep);
 
 /**
  * Pauses a played back sound.
  * \param handle The handle to the sound.
  * \return Whether the handle has been playing or not.
  */
-extern int AUD_pause(AUD_Channel* handle);
+extern int AUD_pause(AUD_Handle* handle);
 
 /**
  * Resumes a paused sound.
  * \param handle The handle to the sound.
  * \return Whether the handle has been paused or not.
  */
-extern int AUD_resume(AUD_Channel* handle);
+extern int AUD_resume(AUD_Handle* handle);
 
 /**
  * Stops a playing or paused sound.
  * \param handle The handle to the sound.
  * \return Whether the handle has been valid or not.
  */
-extern int AUD_stop(AUD_Channel* handle);
+extern int AUD_stop(AUD_Handle* handle);
 
 /**
  * Sets the end behaviour of a playing or paused sound.
@@ -202,7 +211,7 @@ extern int AUD_stop(AUD_Channel* handle);
  *             paused when its end has been reached.
  * \return Whether the handle has been valid or not.
  */
-extern int AUD_setKeep(AUD_Channel* handle, int keep);
+extern int AUD_setKeep(AUD_Handle* handle, int keep);
 
 /**
  * Seeks a playing or paused sound.
@@ -210,7 +219,7 @@ extern int AUD_setKeep(AUD_Channel* handle, int keep);
  * \param seekTo From where the sound file should be played back in seconds.
  * \return Whether the handle has been valid or not.
  */
-extern int AUD_seek(AUD_Channel* handle, float seekTo);
+extern int AUD_seek(AUD_Handle* handle, float seekTo);
 
 /**
  * Retrieves the playback position of a handle.
@@ -218,14 +227,14 @@ extern int AUD_seek(AUD_Channel* handle, float seekTo);
  * \return The current playback position in seconds or 0.0 if the handle is
  *         invalid.
  */
-extern float AUD_getPosition(AUD_Channel* handle);
+extern float AUD_getPosition(AUD_Handle* handle);
 
 /**
  * Returns the status of a playing, paused or stopped sound.
  * \param handle The handle to the sound.
  * \return The status of the sound behind the handle.
  */
-extern AUD_Status AUD_getStatus(AUD_Channel* handle);
+extern AUD_Status AUD_getStatus(AUD_Handle* handle);
 
 /**
  * Sets the listener location.
@@ -272,7 +281,7 @@ extern int AUD_setDistanceModel(AUD_DistanceModel model);
  * \param location The new location.
  * \return Whether the action succeeded.
  */
-extern int AUD_setSourceLocation(AUD_Channel* handle, const float* location);
+extern int AUD_setSourceLocation(AUD_Handle* handle, const float* location);
 
 /**
  * Sets the velocity of a source.
@@ -280,7 +289,7 @@ extern int AUD_setSourceLocation(AUD_Channel* handle, const float* location);
  * \param velocity The new velocity.
  * \return Whether the action succeeded.
  */
-extern int AUD_setSourceVelocity(AUD_Channel* handle, const float* velocity);
+extern int AUD_setSourceVelocity(AUD_Handle* handle, const float* velocity);
 
 /**
  * Sets the orientation of a source.
@@ -288,7 +297,7 @@ extern int AUD_setSourceVelocity(AUD_Channel* handle, const float* velocity);
  * \param orientation The new orientation as quaternion.
  * \return Whether the action succeeded.
  */
-extern int AUD_setSourceOrientation(AUD_Channel* handle, const float* orientation);
+extern int AUD_setSourceOrientation(AUD_Handle* handle, const float* orientation);
 
 /**
  * Sets whether the source location, velocity and orientation are relative
@@ -297,7 +306,7 @@ extern int AUD_setSourceOrientation(AUD_Channel* handle, const float* orientatio
  * \param relative Whether the source is relative.
  * \return Whether the action succeeded.
  */
-extern int AUD_setRelative(AUD_Channel* handle, int relative);
+extern int AUD_setRelative(AUD_Handle* handle, int relative);
 
 /**
  * Sets the maximum volume of a source.
@@ -305,7 +314,7 @@ extern int AUD_setRelative(AUD_Channel* handle, int relative);
  * \param volume The new maximum volume.
  * \return Whether the action succeeded.
  */
-extern int AUD_setVolumeMaximum(AUD_Channel* handle, float volume);
+extern int AUD_setVolumeMaximum(AUD_Handle* handle, float volume);
 
 /**
  * Sets the minimum volume of a source.
@@ -313,7 +322,7 @@ extern int AUD_setVolumeMaximum(AUD_Channel* handle, float volume);
  * \param volume The new minimum volume.
  * \return Whether the action succeeded.
  */
-extern int AUD_setVolumeMinimum(AUD_Channel* handle, float volume);
+extern int AUD_setVolumeMinimum(AUD_Handle* handle, float volume);
 
 /**
  * Sets the maximum distance of a source.
@@ -323,7 +332,7 @@ extern int AUD_setVolumeMinimum(AUD_Channel* handle, float volume);
  * \param distance The new maximum distance.
  * \return Whether the action succeeded.
  */
-extern int AUD_setDistanceMaximum(AUD_Channel* handle, float distance);
+extern int AUD_setDistanceMaximum(AUD_Handle* handle, float distance);
 
 /**
  * Sets the reference distance of a source.
@@ -331,7 +340,7 @@ extern int AUD_setDistanceMaximum(AUD_Channel* handle, float distance);
  * \param distance The new reference distance.
  * \return Whether the action succeeded.
  */
-extern int AUD_setDistanceReference(AUD_Channel* handle, float distance);
+extern int AUD_setDistanceReference(AUD_Handle* handle, float distance);
 
 /**
  * Sets the attenuation of a source.
@@ -340,7 +349,7 @@ extern int AUD_setDistanceReference(AUD_Channel* handle, float distance);
  * \param factor The new attenuation.
  * \return Whether the action succeeded.
  */
-extern int AUD_setAttenuation(AUD_Channel* handle, float factor);
+extern int AUD_setAttenuation(AUD_Handle* handle, float factor);
 
 /**
  * Sets the outer angle of the cone of a source.
@@ -348,7 +357,7 @@ extern int AUD_setAttenuation(AUD_Channel* handle, float factor);
  * \param angle The new outer angle of the cone.
  * \return Whether the action succeeded.
  */
-extern int AUD_setConeAngleOuter(AUD_Channel* handle, float angle);
+extern int AUD_setConeAngleOuter(AUD_Handle* handle, float angle);
 
 /**
  * Sets the inner angle of the cone of a source.
@@ -356,7 +365,7 @@ extern int AUD_setConeAngleOuter(AUD_Channel* handle, float angle);
  * \param angle The new inner angle of the cone.
  * \return Whether the action succeeded.
  */
-extern int AUD_setConeAngleInner(AUD_Channel* handle, float angle);
+extern int AUD_setConeAngleInner(AUD_Handle* handle, float angle);
 
 /**
  * Sets the outer volume of the cone of a source.
@@ -366,7 +375,7 @@ extern int AUD_setConeAngleInner(AUD_Channel* handle, float angle);
  * \param volume The new outer volume of the cone.
  * \return Whether the action succeeded.
  */
-extern int AUD_setConeVolumeOuter(AUD_Channel* handle, float volume);
+extern int AUD_setConeVolumeOuter(AUD_Handle* handle, float volume);
 
 /**
  * Sets the volume of a played back sound.
@@ -374,7 +383,7 @@ extern int AUD_setConeVolumeOuter(AUD_Channel* handle, float volume);
  * \param volume The new volume, must be between 0.0 and 1.0.
  * \return Whether the action succeeded.
  */
-extern int AUD_setSoundVolume(AUD_Channel* handle, float volume);
+extern int AUD_setSoundVolume(AUD_Handle* handle, float volume);
 
 /**
  * Sets the pitch of a played back sound.
@@ -382,7 +391,7 @@ extern int AUD_setSoundVolume(AUD_Channel* handle, float volume);
  * \param pitch The new pitch.
  * \return Whether the action succeeded.
  */
-extern int AUD_setSoundPitch(AUD_Channel* handle, float pitch);
+extern int AUD_setSoundPitch(AUD_Handle* handle, float pitch);
 
 /**
  * Opens a read device, with which audio data can be read.
@@ -406,18 +415,7 @@ extern int AUD_setDeviceVolume(AUD_Device* device, float volume);
  * \param seek The position where the sound should be seeked to.
  * \return A handle to the played back sound.
  */
-extern AUD_Channel* AUD_playDevice(AUD_Device* device, AUD_Sound* sound, float seek);
-
-/**
- * Sets the volume of a played back sound of a read device.
- * \param device The read device.
- * \param handle The handle to the sound.
- * \param volume The new volume, must be between 0.0 and 1.0.
- * \return Whether the action succeeded.
- */
-extern int AUD_setDeviceSoundVolume(AUD_Device* device,
-                                                                       AUD_Channel* handle,
-                                                                       float volume);
+extern AUD_Handle* AUD_playDevice(AUD_Device* device, AUD_Sound* sound, float seek);
 
 /**
  * Reads the next samples into the supplied buffer.
@@ -443,7 +441,7 @@ extern void AUD_closeReadDevice(AUD_Device* device);
 extern float* AUD_readSoundBuffer(const char* filename, float low, float high,
                                                                  float attack, float release, float threshold,
                                                                  int accumulate, int additive, int square,
-                                                                 float sthreshold, int samplerate,
+                                                                 float sthreshold, double samplerate,
                                                                  int* length);
 
 /**
@@ -452,32 +450,51 @@ extern float* AUD_readSoundBuffer(const char* filename, float low, float high,
  * \param time The time in seconds.
  * \return The silence handle.
  */
-extern AUD_Channel* AUD_pauseAfter(AUD_Channel* handle, float seconds);
+extern AUD_Handle* AUD_pauseAfter(AUD_Handle* handle, float seconds);
 
-extern AUD_Sound* AUD_createSequencer(void* data, AUD_volumeFunction volume);
+extern AUD_Sound* AUD_createSequencer(float fps, int muted);
 
 extern void AUD_destroySequencer(AUD_Sound* sequencer);
 
-extern AUD_SequencerEntry* AUD_addSequencer(AUD_Sound** sequencer, AUD_Sound* sound,
-                                                                               float begin, float end, float skip, void* data);
+extern void AUD_setSequencerMuted(AUD_Sound* sequencer, int muted);
 
-extern void AUD_removeSequencer(AUD_Sound* sequencer, AUD_SequencerEntry* entry);
+extern void AUD_setSequencerFPS(AUD_Sound* sequencer, float fps);
 
-extern void AUD_moveSequencer(AUD_Sound* sequencer, AUD_SequencerEntry* entry,
-                                                 float begin, float end, float skip);
+extern AUD_SEntry* AUD_addSequence(AUD_Sound* sequencer, AUD_Sound* sound,
+                                                                  float begin, float end, float skip);
 
-extern void AUD_muteSequencer(AUD_Sound* sequencer, AUD_SequencerEntry* entry,
-                                                 char mute);
+extern void AUD_removeSequence(AUD_Sound* sequencer, AUD_SEntry* entry);
 
-extern int AUD_readSound(AUD_Sound* sound, sample_t* buffer, int length);
+extern void AUD_moveSequence(AUD_SEntry* entry, float begin, float end, float skip);
 
-extern void AUD_startPlayback(void);
+extern void AUD_muteSequence(AUD_SEntry* entry, char mute);
 
-extern void AUD_stopPlayback(void);
+extern void AUD_setRelativeSequence(AUD_SEntry* entry, char relative);
+
+extern void AUD_updateSequenceSound(AUD_SEntry* entry, AUD_Sound* sound);
+
+extern void AUD_setSequenceAnimData(AUD_SEntry* entry, AUD_AnimateablePropertyType type, int frame, float* data, char animated);
+
+extern void AUD_setSequencerAnimData(AUD_Sound* sequencer, AUD_AnimateablePropertyType type, int frame, float* data, char animated);
+
+extern void AUD_updateSequenceData(AUD_SEntry* entry, float volume_max, float volume_min,
+                                                                  float distance_max, float distance_reference, float attenuation,
+                                                                  float cone_angle_outer, float cone_angle_inner, float cone_volume_outer);
+
+extern void AUD_updateSequencerData(AUD_Sound* sequencer, float speed_of_sound,
+                                                                       float factor, AUD_DistanceModel model);
+
+extern void AUD_setSequencerDeviceSpecs(AUD_Sound* sequencer);
 
-extern void AUD_seekSequencer(AUD_Channel* handle, float time);
+extern void AUD_setSequencerSpecs(AUD_Sound* sequencer, AUD_Specs specs);
 
-extern float AUD_getSequencerPosition(AUD_Channel* handle);
+extern void AUD_seekSequencer(AUD_Handle* handle, float time);
+
+extern float AUD_getSequencerPosition(AUD_Handle* handle);
+
+extern void AUD_startPlayback(void);
+
+extern void AUD_stopPlayback(void);
 
 #ifdef WITH_JACK
 extern void AUD_setSyncCallback(AUD_syncFunction function, void* data);
@@ -485,6 +502,30 @@ extern void AUD_setSyncCallback(AUD_syncFunction function, void* data);
 
 extern int AUD_doesPlayback(void);
 
+extern int AUD_readSound(AUD_Sound* sound, sample_t* buffer, int length);
+
+extern AUD_Sound* AUD_copy(AUD_Sound* sound);
+
+extern void AUD_freeHandle(AUD_Handle* channel);
+
+extern void* AUD_createSet(void);
+
+extern void AUD_destroySet(void* set);
+
+extern char AUD_removeSet(void* set, void* entry);
+
+extern void AUD_addSet(void* set, void* entry);
+
+extern void* AUD_getSet(void* set);
+
+extern const char* AUD_mixdown(AUD_Sound* sound, unsigned int start, unsigned int length, unsigned int buffersize, const char* filename, AUD_DeviceSpecs specs, AUD_Container format, AUD_Codec codec, unsigned int bitrate);
+
+#ifdef WITH_PYTHON
+extern PyObject* AUD_getPythonFactory(AUD_Sound* sound);
+
+extern AUD_Sound* AUD_getPythonSound(PyObject* sound);
+#endif
+
 #ifdef __cplusplus
 }
 #endif