3D Audio GSoC:
[blender.git] / intern / audaspace / intern / AUD_C-API.h
index c3439f89ade990a0b0eab5b6e7a7151be10e9828..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
@@ -50,8 +59,16 @@ typedef struct
        typedef void AUD_Sound;
        typedef void AUD_Handle;
        typedef void AUD_Device;
+       typedef void AUD_SEntry;
+       typedef float (*AUD_volumeFunction)(void*, void*, float);
+       typedef void (*AUD_syncFunction)(void*, int, float);
 #endif
 
+/**
+ * Initializes FFMPEG if it is enabled.
+ */
+extern void AUD_initOnce(void);
+
 /**
  * Initializes an audio device.
  * \param device The device type that should be used.
@@ -61,26 +78,20 @@ typedef struct
  */
 extern int AUD_init(AUD_DeviceType device, AUD_DeviceSpecs specs, int buffersize);
 
-/**
- * Returns a integer list with available sound devices. The last one is always
- * AUD_NULL_DEVICE.
- */
-extern int* AUD_enumDevices();
-
 /**
  * Unitinitializes an audio device.
  */
-extern void AUD_exit();
+extern void AUD_exit(void);
 
 /**
  * Locks the playback device.
  */
-extern void AUD_lock();
+extern void AUD_lock(void);
 
 /**
  * Unlocks the device.
  */
-extern void AUD_unlock();
+extern void AUD_unlock(void);
 
 /**
  * Returns information about a sound.
@@ -143,11 +154,12 @@ extern AUD_Sound* AUD_pingpongSound(AUD_Sound* sound);
 extern AUD_Sound* AUD_loopSound(AUD_Sound* sound);
 
 /**
- * Stops a looping sound when the current playback finishes.
+ * Sets a remaining loop count of a looping sound that currently plays.
  * \param handle The playback handle.
+ * \param loops The count of remaining loops, -1 for infinity.
  * \return Whether the handle is valid.
  */
-extern int AUD_stopLoop(AUD_Handle* handle);
+extern int AUD_setLoop(AUD_Handle* handle, int loops);
 
 /**
  * Rectifies a sound.
@@ -211,6 +223,7 @@ extern int AUD_seek(AUD_Handle* handle, float seekTo);
 
 /**
  * Retrieves the playback position of a handle.
+ * \param handle The handle to the sound.
  * \return The current playback position in seconds or 0.0 if the handle is
  *         invalid.
  */
@@ -224,64 +237,145 @@ extern float AUD_getPosition(AUD_Handle* handle);
 extern AUD_Status AUD_getStatus(AUD_Handle* handle);
 
 /**
- * Plays a 3D sound.
- * \param sound The handle of the sound file.
- * \param keep When keep is true the sound source will not be deleted but set to
- *             paused when its end has been reached.
- * \return A handle to the played back sound.
- * \note The factory must provide a mono (single channel) source and the device
- *       must support 3D audio, otherwise the sound is played back normally.
+ * Sets the listener location.
+ * \param location The new location.
+ */
+extern int AUD_setListenerLocation(const float* location);
+
+/**
+ * Sets the listener velocity.
+ * \param velocity The new velocity.
+ */
+extern int AUD_setListenerVelocity(const float* velocity);
+
+/**
+ * Sets the listener orientation.
+ * \param orientation The new orientation as quaternion.
+ */
+extern int AUD_setListenerOrientation(const float* orientation);
+
+/**
+ * Sets the speed of sound.
+ * This value is needed for doppler effect calculation.
+ * \param speed The new speed of sound.
+ */
+extern int AUD_setSpeedOfSound(float speed);
+
+/**
+ * Sets the doppler factor.
+ * This value is a scaling factor for the velocity vectors of sources and
+ * listener which is used while calculating the doppler effect.
+ * \param factor The new doppler factor.
  */
-extern AUD_Handle* AUD_play3D(AUD_Sound* sound, int keep);
+extern int AUD_setDopplerFactor(float factor);
 
 /**
- * Updates the listener 3D data.
- * \param data The 3D data.
+ * Sets the distance model.
+ * \param model distance model.
+ */
+extern int AUD_setDistanceModel(AUD_DistanceModel model);
+
+/**
+ * Sets the location of a source.
+ * \param handle The handle of the source.
+ * \param location The new location.
  * \return Whether the action succeeded.
  */
-extern int AUD_updateListener(AUD_3DData* data);
+extern int AUD_setSourceLocation(AUD_Handle* handle, const float* location);
 
 /**
- * Sets a 3D device setting.
- * \param setting The setting type.
- * \param value The new setting value.
+ * Sets the velocity of a source.
+ * \param handle The handle of the source.
+ * \param velocity The new velocity.
  * \return Whether the action succeeded.
  */
-extern int AUD_set3DSetting(AUD_3DSetting setting, float value);
+extern int AUD_setSourceVelocity(AUD_Handle* handle, const float* velocity);
 
 /**
- * Retrieves a 3D device setting.
- * \param setting The setting type.
- * \return The setting value.
+ * Sets the orientation of a source.
+ * \param handle The handle of the source.
+ * \param orientation The new orientation as quaternion.
+ * \return Whether the action succeeded.
  */
-extern float AUD_get3DSetting(AUD_3DSetting setting);
+extern int AUD_setSourceOrientation(AUD_Handle* handle, const float* orientation);
 
 /**
- * Updates a listeners 3D data.
- * \param handle The source handle.
- * \param data The 3D data.
+ * Sets whether the source location, velocity and orientation are relative
+ * to the listener.
+ * \param handle The handle of the source.
+ * \param relative Whether the source is relative.
  * \return Whether the action succeeded.
  */
-extern int AUD_update3DSource(AUD_Handle* handle, AUD_3DData* data);
+extern int AUD_setRelative(AUD_Handle* handle, int relative);
 
 /**
- * Sets a 3D source setting.
- * \param handle The source handle.
- * \param setting The setting type.
- * \param value The new setting value.
+ * Sets the maximum volume of a source.
+ * \param handle The handle of the source.
+ * \param volume The new maximum volume.
  * \return Whether the action succeeded.
  */
-extern int AUD_set3DSourceSetting(AUD_Handle* handle,
-                                                                 AUD_3DSourceSetting setting, float value);
+extern int AUD_setVolumeMaximum(AUD_Handle* handle, float volume);
 
 /**
- * Retrieves a 3D source setting.
- * \param handle The source handle.
- * \param setting The setting type.
- * \return The setting value.
+ * Sets the minimum volume of a source.
+ * \param handle The handle of the source.
+ * \param volume The new minimum volume.
+ * \return Whether the action succeeded.
+ */
+extern int AUD_setVolumeMinimum(AUD_Handle* handle, float volume);
+
+/**
+ * Sets the maximum distance of a source.
+ * If a source is further away from the reader than this distance, the
+ * volume will automatically be set to 0.
+ * \param handle The handle of the source.
+ * \param distance The new maximum distance.
+ * \return Whether the action succeeded.
+ */
+extern int AUD_setDistanceMaximum(AUD_Handle* handle, float distance);
+
+/**
+ * Sets the reference distance of a source.
+ * \param handle The handle of the source.
+ * \param distance The new reference distance.
+ * \return Whether the action succeeded.
+ */
+extern int AUD_setDistanceReference(AUD_Handle* handle, float distance);
+
+/**
+ * Sets the attenuation of a source.
+ * This value is used for distance calculation.
+ * \param handle The handle of the source.
+ * \param factor The new attenuation.
+ * \return Whether the action succeeded.
+ */
+extern int AUD_setAttenuation(AUD_Handle* handle, float factor);
+
+/**
+ * Sets the outer angle of the cone of a source.
+ * \param handle The handle of the source.
+ * \param angle The new outer angle of the cone.
+ * \return Whether the action succeeded.
+ */
+extern int AUD_setConeAngleOuter(AUD_Handle* handle, float angle);
+
+/**
+ * Sets the inner angle of the cone of a source.
+ * \param handle The handle of the source.
+ * \param angle The new inner angle of the cone.
+ * \return Whether the action succeeded.
  */
-extern float AUD_get3DSourceSetting(AUD_Handle* handle,
-                                                                       AUD_3DSourceSetting setting);
+extern int AUD_setConeAngleInner(AUD_Handle* handle, float angle);
+
+/**
+ * Sets the outer volume of the cone of a source.
+ * The volume between inner and outer angle is interpolated between inner
+ * volume and this value.
+ * \param handle The handle of the source.
+ * \param volume The new outer volume of the cone.
+ * \return Whether the action succeeded.
+ */
+extern int AUD_setConeVolumeOuter(AUD_Handle* handle, float volume);
 
 /**
  * Sets the volume of a played back sound.
@@ -318,20 +412,10 @@ extern int AUD_setDeviceVolume(AUD_Device* device, float volume);
  * Plays back a sound file through a read device.
  * \param device The read device.
  * \param sound The handle of the sound file.
+ * \param seek The position where the sound should be seeked to.
  * \return A handle to the played back sound.
  */
-extern AUD_Handle* AUD_playDevice(AUD_Device* device, AUD_Sound* sound);
-
-/**
- * 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_Handle* handle,
-                                                                       float volume);
+extern AUD_Handle* AUD_playDevice(AUD_Device* device, AUD_Sound* sound, float seek);
 
 /**
  * Reads the next samples into the supplied buffer.
@@ -357,9 +441,91 @@ 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);
 
+/**
+ * Pauses a playing sound after a specific amount of time.
+ * \param handle The handle to the sound.
+ * \param time The time in seconds.
+ * \return The silence handle.
+ */
+extern AUD_Handle* AUD_pauseAfter(AUD_Handle* handle, float seconds);
+
+extern AUD_Sound* AUD_createSequencer(float fps, int muted);
+
+extern void AUD_destroySequencer(AUD_Sound* sequencer);
+
+extern void AUD_setSequencerMuted(AUD_Sound* sequencer, int muted);
+
+extern void AUD_setSequencerFPS(AUD_Sound* sequencer, float fps);
+
+extern AUD_SEntry* AUD_addSequence(AUD_Sound* sequencer, AUD_Sound* sound,
+                                                                  float begin, float end, float skip);
+
+extern void AUD_removeSequence(AUD_Sound* sequencer, AUD_SEntry* entry);
+
+extern void AUD_moveSequence(AUD_SEntry* entry, float begin, float end, float skip);
+
+extern void AUD_muteSequence(AUD_SEntry* entry, char mute);
+
+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_setSequencerSpecs(AUD_Sound* sequencer, AUD_Specs specs);
+
+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);
+#endif
+
+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