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