intern/audaspace/intern/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 "AUD_Space.h"
  34
  35 typedef enum
  36 {
  37         AUD_NULL_DEVICE = 0,
  38         AUD_SDL_DEVICE,
  39         AUD_OPENAL_DEVICE,
  40         AUD_JACK_DEVICE
  41 } AUD_DeviceType;
  42
  43 typedef struct
  44 {
  45         AUD_Specs specs;
  46         float length;
  47 } AUD_SoundInfo;
  48
  49 #ifndef AUD_CAPI_IMPLEMENTATION
  50         typedef void AUD_Sound;
  51         typedef void AUD_Handle;
  52         typedef void AUD_Device;
  53         typedef void AUD_SequencerEntry;
  54         typedef float (*AUD_volumeFunction)(void*, void*, float);
  55         typedef void (*AUD_syncFunction)(void*, int, float);
  56 #endif
  57
  58 /**
  59  * Initializes FFMPEG if it is enabled.
  60  */
  61 extern void AUD_initOnce();
  62
  63 /**
  64  * Initializes an audio device.
  65  * \param device The device type that should be used.
  66  * \param specs The audio specification to be used.
  67  * \param buffersize The buffersize for the device.
  68  * \return Whether the device has been initialized.
  69  */
  70 extern int AUD_init(AUD_DeviceType device, AUD_DeviceSpecs specs, int buffersize);
  71
  72 /**
  73  * Returns a integer list with available sound devices. The last one is always
  74  * AUD_NULL_DEVICE.
  75  */
  76 extern int* AUD_enumDevices();
  77
  78 /**
  79  * Unitinitializes an audio device.
  80  */
  81 extern void AUD_exit();
  82
  83 /**
  84  * Locks the playback device.
  85  */
  86 extern void AUD_lock();
  87
  88 /**
  89  * Unlocks the device.
  90  */
  91 extern void AUD_unlock();
  92
  93 /**
  94  * Returns information about a sound.
  95  * \param sound The sound to get the info about.
  96  * \return The AUD_SoundInfo structure with filled in data.
  97  */
  98 extern AUD_SoundInfo AUD_getInfo(AUD_Sound* sound);
  99
 100 /**
 101  * Loads a sound file.
 102  * \param filename The filename of the sound file.
 103  * \return A handle of the sound file.
 104  */
 105 extern AUD_Sound* AUD_load(const char* filename);
 106
 107 /**
 108  * Loads a sound file.
 109  * \param buffer The buffer which contains the sound file.
 110  * \param size The size of the buffer.
 111  * \return A handle of the sound file.
 112  */
 113 extern AUD_Sound* AUD_loadBuffer(unsigned char* buffer, int size);
 114
 115 /**
 116  * Buffers a sound.
 117  * \param sound The sound to buffer.
 118  * \return A handle of the sound buffer.
 119  */
 120 extern AUD_Sound* AUD_bufferSound(AUD_Sound* sound);
 121
 122 /**
 123  * Delays a sound.
 124  * \param sound The sound to dealy.
 125  * \param delay The delay in seconds.
 126  * \return A handle of the delayed sound.
 127  */
 128 extern AUD_Sound* AUD_delaySound(AUD_Sound* sound, float delay);
 129
 130 /**
 131  * Limits a sound.
 132  * \param sound The sound to limit.
 133  * \param start The start time in seconds.
 134  * \param end The stop time in seconds.
 135  * \return A handle of the limited sound.
 136  */
 137 extern AUD_Sound* AUD_limitSound(AUD_Sound* sound, float start, float end);
 138
 139 /**
 140  * Ping pongs a sound.
 141  * \param sound The sound to ping pong.
 142  * \return A handle of the ping pong sound.
 143  */
 144 extern AUD_Sound* AUD_pingpongSound(AUD_Sound* sound);
 145
 146 /**
 147  * Loops a sound.
 148  * \param sound The sound to loop.
 149  * \return A handle of the looped sound.
 150  */
 151 extern AUD_Sound* AUD_loopSound(AUD_Sound* sound);
 152
 153 /**
 154  * Sets a remaining loop count of a looping sound that currently plays.
 155  * \param handle The playback handle.
 156  * \param loops The count of remaining loops, -1 for infinity.
 157  * \param time The time after which playback should stop, -1 for infinity.
 158  * \return Whether the handle is valid.
 159  */
 160 extern int AUD_setLoop(AUD_Handle* handle, int loops, float time);
 161
 162 /**
 163  * Rectifies a sound.
 164  * \param sound The sound to rectify.
 165  * \return A handle of the rectified sound.
 166  */
 167 extern AUD_Sound* AUD_rectifySound(AUD_Sound* sound);
 168
 169 /**
 170  * Unloads a sound of any type.
 171  * \param sound The handle of the sound.
 172  */
 173 extern void AUD_unload(AUD_Sound* sound);
 174
 175 /**
 176  * Plays back a sound file.
 177  * \param sound The handle of the sound file.
 178  * \param keep When keep is true the sound source will not be deleted but set to
 179  *             paused when its end has been reached.
 180  * \return A handle to the played back sound.
 181  */
 182 extern AUD_Handle* AUD_play(AUD_Sound* sound, int keep);
 183
 184 /**
 185  * Pauses a played back sound.
 186  * \param handle The handle to the sound.
 187  * \return Whether the handle has been playing or not.
 188  */
 189 extern int AUD_pause(AUD_Handle* handle);
 190
 191 /**
 192  * Resumes a paused sound.
 193  * \param handle The handle to the sound.
 194  * \return Whether the handle has been paused or not.
 195  */
 196 extern int AUD_resume(AUD_Handle* handle);
 197
 198 /**
 199  * Stops a playing or paused sound.
 200  * \param handle The handle to the sound.
 201  * \return Whether the handle has been valid or not.
 202  */
 203 extern int AUD_stop(AUD_Handle* handle);
 204
 205 /**
 206  * Sets the end behaviour of a playing or paused sound.
 207  * \param handle The handle to the sound.
 208  * \param keep When keep is true the sound source will not be deleted but set to
 209  *             paused when its end has been reached.
 210  * \return Whether the handle has been valid or not.
 211  */
 212 extern int AUD_setKeep(AUD_Handle* handle, int keep);
 213
 214 /**
 215  * Seeks a playing or paused sound.
 216  * \param handle The handle to the sound.
 217  * \param seekTo From where the sound file should be played back in seconds.
 218  * \return Whether the handle has been valid or not.
 219  */
 220 extern int AUD_seek(AUD_Handle* handle, float seekTo);
 221
 222 /**
 223  * Retrieves the playback position of a handle.
 224  * \param handle The handle to the sound.
 225  * \return The current playback position in seconds or 0.0 if the handle is
 226  *         invalid.
 227  */
 228 extern float AUD_getPosition(AUD_Handle* handle);
 229
 230 /**
 231  * Returns the status of a playing, paused or stopped sound.
 232  * \param handle The handle to the sound.
 233  * \return The status of the sound behind the handle.
 234  */
 235 extern AUD_Status AUD_getStatus(AUD_Handle* handle);
 236
 237 /**
 238  * Plays a 3D sound.
 239  * \param sound The handle of the sound file.
 240  * \param keep When keep is true the sound source will not be deleted but set to
 241  *             paused when its end has been reached.
 242  * \return A handle to the played back sound.
 243  * \note The factory must provide a mono (single channel) source and the device
 244  *       must support 3D audio, otherwise the sound is played back normally.
 245  */
 246 extern AUD_Handle* AUD_play3D(AUD_Sound* sound, int keep);
 247
 248 /**
 249  * Updates the listener 3D data.
 250  * \param data The 3D data.
 251  * \return Whether the action succeeded.
 252  */
 253 extern int AUD_updateListener(AUD_3DData* data);
 254
 255 /**
 256  * Sets a 3D device setting.
 257  * \param setting The setting type.
 258  * \param value The new setting value.
 259  * \return Whether the action succeeded.
 260  */
 261 extern int AUD_set3DSetting(AUD_3DSetting setting, float value);
 262
 263 /**
 264  * Retrieves a 3D device setting.
 265  * \param setting The setting type.
 266  * \return The setting value.
 267  */
 268 extern float AUD_get3DSetting(AUD_3DSetting setting);
 269
 270 /**
 271  * Updates a listeners 3D data.
 272  * \param handle The source handle.
 273  * \param data The 3D data.
 274  * \return Whether the action succeeded.
 275  */
 276 extern int AUD_update3DSource(AUD_Handle* handle, AUD_3DData* data);
 277
 278 /**
 279  * Sets a 3D source setting.
 280  * \param handle The source handle.
 281  * \param setting The setting type.
 282  * \param value The new setting value.
 283  * \return Whether the action succeeded.
 284  */
 285 extern int AUD_set3DSourceSetting(AUD_Handle* handle,
 286                                                                   AUD_3DSourceSetting setting, float value);
 287
 288 /**
 289  * Retrieves a 3D source setting.
 290  * \param handle The source handle.
 291  * \param setting The setting type.
 292  * \return The setting value.
 293  */
 294 extern float AUD_get3DSourceSetting(AUD_Handle* handle,
 295                                                                         AUD_3DSourceSetting setting);
 296
 297 /**
 298  * Sets the volume of a played back sound.
 299  * \param handle The handle to the sound.
 300  * \param volume The new volume, must be between 0.0 and 1.0.
 301  * \return Whether the action succeeded.
 302  */
 303 extern int AUD_setSoundVolume(AUD_Handle* handle, float volume);
 304
 305 /**
 306  * Sets the pitch of a played back sound.
 307  * \param handle The handle to the sound.
 308  * \param pitch The new pitch.
 309  * \return Whether the action succeeded.
 310  */
 311 extern int AUD_setSoundPitch(AUD_Handle* handle, float pitch);
 312
 313 /**
 314  * Opens a read device, with which audio data can be read.
 315  * \param specs The specification of the audio data.
 316  * \return A device handle.
 317  */
 318 extern AUD_Device* AUD_openReadDevice(AUD_DeviceSpecs specs);
 319
 320 /**
 321  * Sets the main volume of a device.
 322  * \param device The device.
 323  * \param volume The new volume, must be between 0.0 and 1.0.
 324  * \return Whether the action succeeded.
 325  */
 326 extern int AUD_setDeviceVolume(AUD_Device* device, float volume);
 327
 328 /**
 329  * Plays back a sound file through a read device.
 330  * \param device The read device.
 331  * \param sound The handle of the sound file.
 332  * \param seek The position where the sound should be seeked to.
 333  * \return A handle to the played back sound.
 334  */
 335 extern AUD_Handle* AUD_playDevice(AUD_Device* device, AUD_Sound* sound, float seek);
 336
 337 /**
 338  * Sets the volume of a played back sound of a read device.
 339  * \param device The read device.
 340  * \param handle The handle to the sound.
 341  * \param volume The new volume, must be between 0.0 and 1.0.
 342  * \return Whether the action succeeded.
 343  */
 344 extern int AUD_setDeviceSoundVolume(AUD_Device* device,
 345                                                                         AUD_Handle* handle,
 346                                                                         float volume);
 347
 348 /**
 349  * Reads the next samples into the supplied buffer.
 350  * \param device The read device.
 351  * \param buffer The target buffer.
 352  * \param length The length in samples to be filled.
 353  * \return True if the reading succeeded, false if there are no sounds
 354  *         played back currently, in that case the buffer is filled with
 355  *         silence.
 356  */
 357 extern int AUD_readDevice(AUD_Device* device, data_t* buffer, int length);
 358
 359 /**
 360  * Closes a read device.
 361  * \param device The read device.
 362  */
 363 extern void AUD_closeReadDevice(AUD_Device* device);
 364
 365 /**
 366  * Reads a sound file into a newly created float buffer.
 367  * The sound is therefore bandpassed, rectified and resampled.
 368  */
 369 extern float* AUD_readSoundBuffer(const char* filename, float low, float high,
 370                                                                   float attack, float release, float threshold,
 371                                                                   int accumulate, int additive, int square,
 372                                                                   float sthreshold, int samplerate,
 373                                                                   int* length);
 374
 375 extern AUD_Sound* AUD_createSequencer(void* data, AUD_volumeFunction volume);
 376
 377 extern void AUD_destroySequencer(AUD_Sound* sequencer);
 378
 379 extern AUD_SequencerEntry* AUD_addSequencer(AUD_Sound** sequencer, AUD_Sound* sound,
 380                                                                                 float begin, float end, float skip, void* data);
 381
 382 extern void AUD_removeSequencer(AUD_Sound* sequencer, AUD_SequencerEntry* entry);
 383
 384 extern void AUD_moveSequencer(AUD_Sound* sequencer, AUD_SequencerEntry* entry,
 385                                                   float begin, float end, float skip);
 386
 387 extern void AUD_muteSequencer(AUD_Sound* sequencer, AUD_SequencerEntry* entry,
 388                                                   char mute);
 389
 390 extern int AUD_readSound(AUD_Sound* sound, sample_t* buffer, int length);
 391
 392 extern void AUD_startPlayback();
 393
 394 extern void AUD_stopPlayback();
 395
 396 extern void AUD_seekSequencer(AUD_Handle* handle, float time);
 397
 398 extern float AUD_getSequencerPosition(AUD_Handle* handle);
 399
 400 #ifdef WITH_JACK
 401 extern void AUD_setSyncCallback(AUD_syncFunction function, void* data);
 402 #endif
 403
 404 extern int AUD_doesPlayback();
 405
 406 #ifdef __cplusplus
 407 }
 408 #endif
 409
 410 #endif //AUD_CAPI