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