diff options
Diffstat (limited to 'intern/audaspace/AUD_C-API.h')
| -rw-r--r-- | intern/audaspace/AUD_C-API.h | 330 |
1 files changed, 330 insertions, 0 deletions
diff --git a/intern/audaspace/AUD_C-API.h b/intern/audaspace/AUD_C-API.h new file mode 100644 index 00000000000..1ee4b33e9fe --- /dev/null +++ b/intern/audaspace/AUD_C-API.h @@ -0,0 +1,330 @@ +/* + * $Id$ + * + * ***** BEGIN LGPL LICENSE BLOCK ***** + * + * Copyright 2009 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 + * (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. + * + * You should have received a copy of the GNU Lesser General Public License + * along with AudaSpace. If not, see <http://www.gnu.org/licenses/>. + * + * ***** END LGPL LICENSE BLOCK ***** + */ + +#ifndef AUD_CAPI +#define AUD_CAPI + +#ifdef __cplusplus +extern "C" { +#endif + +#include "intern/AUD_Space.h" + +typedef enum +{ + AUD_NULL_DEVICE = 0, + AUD_SDL_DEVICE, + AUD_OPENAL_DEVICE +} AUD_DeviceType; + +typedef struct +{ + AUD_Specs specs; + float length; +} AUD_SoundInfo; + +#ifndef AUD_CAPI_IMPLEMENTATION + typedef void AUD_Sound; + typedef void AUD_Handle; + typedef void AUD_Device; +#endif + +/** + * Initializes an audio device. + * \param device The device type that should be used. + * \param specs The audio specification to be used. + * \param buffersize The buffersize for the device. + * \return Whether the device has been initialized. + */ +extern int AUD_init(AUD_DeviceType device, AUD_Specs 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(); + +/** + * Locks the playback device. + */ +extern void AUD_lock(); + +/** + * Unlocks the device. + */ +extern void AUD_unlock(); + +/** + * Returns information about a sound. + * \param sound The sound to get the info about. + * \return The AUD_SoundInfo structure with filled in data. + */ +extern AUD_SoundInfo AUD_getInfo(AUD_Sound* sound); + +/** + * Loads a sound file. + * \param filename The filename of the sound file. + * \return A handle of the sound file. + */ +extern AUD_Sound* AUD_load(const char* filename); + +/** + * Loads a sound file. + * \param buffer The buffer which contains the sound file. + * \param size The size of the buffer. + * \return A handle of the sound file. + */ +extern AUD_Sound* AUD_loadBuffer(unsigned char* buffer, int size); + +/** + * Buffers a sound. + * \param sound The sound to buffer. + * \return A handle of the sound buffer. + */ +extern AUD_Sound* AUD_bufferSound(AUD_Sound* sound); + +/** + * Delays a sound. + * \param sound The sound to dealy. + * \param delay The delay in seconds. + * \return A handle of the delayed sound. + */ +extern AUD_Sound* AUD_delaySound(AUD_Sound* sound, float delay); + +/** + * Limits a sound. + * \param sound The sound to limit. + * \param start The start time in seconds. + * \param end The stop time in seconds. + * \return A handle of the limited sound. + */ +extern AUD_Sound* AUD_limitSound(AUD_Sound* sound, float start, float end); + +/** + * Ping pongs a sound. + * \param sound The sound to ping pong. + * \return A handle of the ping pong sound. + */ +extern AUD_Sound* AUD_pingpongSound(AUD_Sound* sound); + +/** + * Loops a sound. + * \param sound The sound to loop. + * \return A handle of the looped sound. + */ +extern AUD_Sound* AUD_loopSound(AUD_Sound* sound); + +/** + * Stops a looping sound when the current playback finishes. + * \param handle The playback handle. + * \return Whether the handle is valid. + */ +extern int AUD_stopLoop(AUD_Handle* handle); + +/** + * Unloads a sound of any type. + * \param sound The handle of the sound. + */ +extern void AUD_unload(AUD_Sound* sound); + +/** + * Plays back a sound file. + * \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. + */ +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_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_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_Handle* handle); + +/** + * Sets the end behaviour of a playing or paused sound. + * \param handle The handle to the sound. + * \param keep When keep is true the sound source will not be deleted but set to + * paused when its end has been reached. + * \return Whether the handle has been valid or not. + */ +extern int AUD_setKeep(AUD_Handle* handle, int keep); + +/** + * Seeks a playing or paused sound. + * \param handle The handle to the sound. + * \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_Handle* handle, float seekTo); + +/** + * Retrieves the playback position of a handle. + * \return The current playback position in seconds or 0.0 if the handle is + * invalid. + */ +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_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. + */ +extern AUD_Handle* AUD_play3D(AUD_Sound* sound, int keep); + +/** + * Updates the listener 3D data. + * \param data The 3D data. + * \return Whether the action succeeded. + */ +extern int AUD_updateListener(AUD_3DData* data); + +/** + * Sets a 3D device setting. + * \param setting The setting type. + * \param value The new setting value. + * \return Whether the action succeeded. + */ +extern int AUD_set3DSetting(AUD_3DSetting setting, float value); + +/** + * Retrieves a 3D device setting. + * \param setting The setting type. + * \return The setting value. + */ +extern float AUD_get3DSetting(AUD_3DSetting setting); + +/** + * Updates a listeners 3D data. + * \param handle The source handle. + * \param data The 3D data. + * \return Whether the action succeeded. + */ +extern int AUD_update3DSource(AUD_Handle* handle, AUD_3DData* data); + +/** + * Sets a 3D source setting. + * \param handle The source handle. + * \param setting The setting type. + * \param value The new setting value. + * \return Whether the action succeeded. + */ +extern int AUD_set3DSourceSetting(AUD_Handle* handle, + AUD_3DSourceSetting setting, float value); + +/** + * Retrieves a 3D source setting. + * \param handle The source handle. + * \param setting The setting type. + * \return The setting value. + */ +extern float AUD_get3DSourceSetting(AUD_Handle* handle, + AUD_3DSourceSetting setting); + +/** + * Sets the volume of a played back sound. + * \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_setSoundVolume(AUD_Handle* handle, float volume); + +/** + * Sets the pitch of a played back sound. + * \param handle The handle to the sound. + * \param pitch The new pitch. + * \return Whether the action succeeded. + */ +extern int AUD_setSoundPitch(AUD_Handle* handle, float pitch); + +/** + * Opens a read device, with which audio data can be read. + * \param specs The specification of the audio data. + * \return A device handle. + */ +extern AUD_Device* AUD_openReadDevice(AUD_Specs specs); + +/** + * Plays back a sound file through a read device. + * \param device The read device. + * \param sound The handle of the sound file. + * \return Whether the sound could be played back. + */ +extern int AUD_playDevice(AUD_Device* device, AUD_Sound* sound); + +/** + * Reads the next samples into the supplied buffer. + * \param device The read device. + * \param buffer The target buffer. + * \param length The length in samples to be filled. + * \return True if the reading succeeded, false if there are no sounds + * played back currently, in that case the buffer is filled with + * silence. + */ +extern int AUD_readDevice(AUD_Device* device, sample_t* buffer, int length); + +/** + * Closes a read device. + * \param device The read device. + */ +extern void AUD_closeReadDevice(AUD_Device* device); + +#ifdef __cplusplus +} +#endif + +#endif //AUD_CAPI |