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 WITH_PYTHON
  30 #include "Python.h"
  31 #endif
  32
  33 #ifdef __cplusplus
  34 extern "C" {
  35 #endif
  36
  37 #include "AUD_Space.h"
  38
  39 typedef enum
  40 {
  41         AUD_NULL_DEVICE = 0,
  42         AUD_SDL_DEVICE,
  43         AUD_OPENAL_DEVICE,
  44         AUD_JACK_DEVICE
  45 } AUD_DeviceType;
  46
  47 typedef struct
  48 {
  49         AUD_Specs specs;
  50         float length;
  51 } AUD_SoundInfo;
  52
  53 #ifndef AUD_CAPI_IMPLEMENTATION
  54         typedef void AUD_Sound;
  55         typedef void AUD_Channel;
  56         typedef void AUD_Device;
  57         typedef void AUD_SequencerEntry;
  58         typedef float (*AUD_volumeFunction)(void*, void*, float);
  59         typedef void (*AUD_syncFunction)(void*, int, float);
  60 #endif
  61
  62 /**
  63  * Initializes FFMPEG if it is enabled.
  64  */
  65 extern void AUD_initOnce();
  66
  67 /**
  68  * Initializes an audio device.
  69  * \param device The device type that should be used.
  70  * \param specs The audio specification to be used.
  71  * \param buffersize The buffersize for the device.
  72  * \return Whether the device has been initialized.
  73  */
  74 extern int AUD_init(AUD_DeviceType device, AUD_DeviceSpecs specs, int buffersize);
  75
  76 /**
  77  * Returns a integer list with available sound devices. The last one is always
  78  * AUD_NULL_DEVICE.
  79  */
  80 extern int* AUD_enumDevices();
  81
  82 /**
  83  * Unitinitializes an audio device.
  84  */
  85 extern void AUD_exit();
  86
  87 #ifdef WITH_PYTHON
  88 /**
  89  * Initalizes the Python module.
  90  */
  91 extern PyObject* AUD_initPython();
  92 #endif
  93
  94 /**
  95  * Locks the playback device.
  96  */
  97 extern void AUD_lock();
  98
  99 /**
 100  * Unlocks the device.
 101  */
 102 extern void AUD_unlock();
 103
 104 /**
 105  * Returns information about a sound.
 106  * \param sound The sound to get the info about.
 107  * \return The AUD_SoundInfo structure with filled in data.
 108  */
 109 extern AUD_SoundInfo AUD_getInfo(AUD_Sound* sound);
 110
 111 /**
 112  * Loads a sound file.
 113  * \param filename The filename of the sound file.
 114  * \return A handle of the sound file.
 115  */
 116 extern AUD_Sound* AUD_load(const char* filename);
 117
 118 /**
 119  * Loads a sound file.
 120  * \param buffer The buffer which contains the sound file.
 121  * \param size The size of the buffer.
 122  * \return A handle of the sound file.
 123  */
 124 extern AUD_Sound* AUD_loadBuffer(unsigned char* buffer, int size);
 125
 126 /**
 127  * Buffers a sound.
 128  * \param sound The sound to buffer.
 129  * \return A handle of the sound buffer.
 130  */
 131 extern AUD_Sound* AUD_bufferSound(AUD_Sound* sound);
 132
 133 /**
 134  * Delays a sound.
 135  * \param sound The sound to dealy.
 136  * \param delay The delay in seconds.
 137  * \return A handle of the delayed sound.
 138  */
 139 extern AUD_Sound* AUD_delaySound(AUD_Sound* sound, float delay);
 140
 141 /**
 142  * Limits a sound.
 143  * \param sound The sound to limit.
 144  * \param start The start time in seconds.
 145  * \param end The stop time in seconds.
 146  * \return A handle of the limited sound.
 147  */
 148 extern AUD_Sound* AUD_limitSound(AUD_Sound* sound, float start, float end);
 149
 150 /**
 151  * Ping pongs a sound.
 152  * \param sound The sound to ping pong.
 153  * \return A handle of the ping pong sound.
 154  */
 155 extern AUD_Sound* AUD_pingpongSound(AUD_Sound* sound);
 156
 157 /**
 158  * Loops a sound.
 159  * \param sound The sound to loop.
 160  * \return A handle of the looped sound.
 161  */
 162 extern AUD_Sound* AUD_loopSound(AUD_Sound* sound);
 163
 164 /**
 165  * Sets a remaining loop count of a looping sound that currently plays.
 166  * \param handle The playback handle.
 167  * \param loops The count of remaining loops, -1 for infinity.
 168  * \return Whether the handle is valid.
 169  */
 170 extern int AUD_setLoop(AUD_Channel* handle, int loops);
 171
 172 /**
 173  * Rectifies a sound.
 174  * \param sound The sound to rectify.
 175  * \return A handle of the rectified sound.
 176  */
 177 extern AUD_Sound* AUD_rectifySound(AUD_Sound* sound);
 178
 179 /**
 180  * Unloads a sound of any type.
 181  * \param sound The handle of the sound.
 182  */
 183 extern void AUD_unload(AUD_Sound* sound);
 184
 185 /**
 186  * Plays back a sound file.
 187  * \param sound The handle of the sound file.
 188  * \param keep When keep is true the sound source will not be deleted but set to
 189  *             paused when its end has been reached.
 190  * \return A handle to the played back sound.
 191  */
 192 extern AUD_Channel* AUD_play(AUD_Sound* sound, int keep);
 193
 194 /**
 195  * Pauses a played back sound.
 196  * \param handle The handle to the sound.
 197  * \return Whether the handle has been playing or not.
 198  */
 199 extern int AUD_pause(AUD_Channel* handle);
 200
 201 /**
 202  * Resumes a paused sound.
 203  * \param handle The handle to the sound.
 204  * \return Whether the handle has been paused or not.
 205  */
 206 extern int AUD_resume(AUD_Channel* handle);
 207
 208 /**
 209  * Stops a playing or paused sound.
 210  * \param handle The handle to the sound.
 211  * \return Whether the handle has been valid or not.
 212  */
 213 extern int AUD_stop(AUD_Channel* handle);
 214
 215 /**
 216  * Sets the end behaviour of a playing or paused sound.
 217  * \param handle The handle to the sound.
 218  * \param keep When keep is true the sound source will not be deleted but set to
 219  *             paused when its end has been reached.
 220  * \return Whether the handle has been valid or not.
 221  */
 222 extern int AUD_setKeep(AUD_Channel* handle, int keep);
 223
 224 /**
 225  * Seeks a playing or paused sound.
 226  * \param handle The handle to the sound.
 227  * \param seekTo From where the sound file should be played back in seconds.
 228  * \return Whether the handle has been valid or not.
 229  */
 230 extern int AUD_seek(AUD_Channel* handle, float seekTo);
 231
 232 /**
 233  * Retrieves the playback position of a handle.
 234  * \param handle The handle to the sound.
 235  * \return The current playback position in seconds or 0.0 if the handle is
 236  *         invalid.
 237  */
 238 extern float AUD_getPosition(AUD_Channel* handle);
 239
 240 /**
 241  * Returns the status of a playing, paused or stopped sound.
 242  * \param handle The handle to the sound.
 243  * \return The status of the sound behind the handle.
 244  */
 245 extern AUD_Status AUD_getStatus(AUD_Channel* handle);
 246
 247 /**
 248  * Sets the listener location.
 249  * \param location The new location.
 250  */
 251 extern int AUD_setListenerLocation(const float* location);
 252
 253 /**
 254  * Sets the listener velocity.
 255  * \param velocity The new velocity.
 256  */
 257 extern int AUD_setListenerVelocity(const float* velocity);
 258
 259 /**
 260  * Sets the listener orientation.
 261  * \param orientation The new orientation as quaternion.
 262  */
 263 extern int AUD_setListenerOrientation(const float* orientation);
 264
 265 /**
 266  * Sets the speed of sound.
 267  * This value is needed for doppler effect calculation.
 268  * \param speed The new speed of sound.
 269  */
 270 extern int AUD_setSpeedOfSound(float speed);
 271
 272 /**
 273  * Sets the doppler factor.
 274  * This value is a scaling factor for the velocity vectors of sources and
 275  * listener which is used while calculating the doppler effect.
 276  * \param factor The new doppler factor.
 277  */
 278 extern int AUD_setDopplerFactor(float factor);
 279
 280 /**
 281  * Sets the distance model.
 282  * \param model distance model.
 283  */
 284 extern int AUD_setDistanceModel(AUD_DistanceModel model);
 285
 286 /**
 287  * Sets the location of a source.
 288  * \param handle The handle of the source.
 289  * \param location The new location.
 290  * \return Whether the action succeeded.
 291  */
 292 extern int AUD_setSourceLocation(AUD_Channel* handle, const float* location);
 293
 294 /**
 295  * Sets the velocity of a source.
 296  * \param handle The handle of the source.
 297  * \param velocity The new velocity.
 298  * \return Whether the action succeeded.
 299  */
 300 extern int AUD_setSourceVelocity(AUD_Channel* handle, const float* velocity);
 301
 302 /**
 303  * Sets the orientation of a source.
 304  * \param handle The handle of the source.
 305  * \param orientation The new orientation as quaternion.
 306  * \return Whether the action succeeded.
 307  */
 308 extern int AUD_setSourceOrientation(AUD_Channel* handle, const float* orientation);
 309
 310 /**
 311  * Sets whether the source location, velocity and orientation are relative
 312  * to the listener.
 313  * \param handle The handle of the source.
 314  * \param relative Whether the source is relative.
 315  * \return Whether the action succeeded.
 316  */
 317 extern int AUD_setRelative(AUD_Channel* handle, int relative);
 318
 319 /**
 320  * Sets the maximum volume of a source.
 321  * \param handle The handle of the source.
 322  * \param volume The new maximum volume.
 323  * \return Whether the action succeeded.
 324  */
 325 extern int AUD_setVolumeMaximum(AUD_Channel* handle, float volume);
 326
 327 /**
 328  * Sets the minimum volume of a source.
 329  * \param handle The handle of the source.
 330  * \param volume The new minimum volume.
 331  * \return Whether the action succeeded.
 332  */
 333 extern int AUD_setVolumeMinimum(AUD_Channel* handle, float volume);
 334
 335 /**
 336  * Sets the maximum distance of a source.
 337  * If a source is further away from the reader than this distance, the
 338  * volume will automatically be set to 0.
 339  * \param handle The handle of the source.
 340  * \param distance The new maximum distance.
 341  * \return Whether the action succeeded.
 342  */
 343 extern int AUD_setDistanceMaximum(AUD_Channel* handle, float distance);
 344
 345 /**
 346  * Sets the reference distance of a source.
 347  * \param handle The handle of the source.
 348  * \param distance The new reference distance.
 349  * \return Whether the action succeeded.
 350  */
 351 extern int AUD_setDistanceReference(AUD_Channel* handle, float distance);
 352
 353 /**
 354  * Sets the attenuation of a source.
 355  * This value is used for distance calculation.
 356  * \param handle The handle of the source.
 357  * \param factor The new attenuation.
 358  * \return Whether the action succeeded.
 359  */
 360 extern int AUD_setAttenuation(AUD_Channel* handle, float factor);
 361
 362 /**
 363  * Sets the outer angle of the cone of a source.
 364  * \param handle The handle of the source.
 365  * \param angle The new outer angle of the cone.
 366  * \return Whether the action succeeded.
 367  */
 368 extern int AUD_setConeAngleOuter(AUD_Channel* handle, float angle);
 369
 370 /**
 371  * Sets the inner angle of the cone of a source.
 372  * \param handle The handle of the source.
 373  * \param angle The new inner angle of the cone.
 374  * \return Whether the action succeeded.
 375  */
 376 extern int AUD_setConeAngleInner(AUD_Channel* handle, float angle);
 377
 378 /**
 379  * Sets the outer volume of the cone of a source.
 380  * The volume between inner and outer angle is interpolated between inner
 381  * volume and this value.
 382  * \param handle The handle of the source.
 383  * \param volume The new outer volume of the cone.
 384  * \return Whether the action succeeded.
 385  */
 386 extern int AUD_setConeVolumeOuter(AUD_Channel* handle, float volume);
 387
 388 /**
 389  * Sets the volume of a played back sound.
 390  * \param handle The handle to the sound.
 391  * \param volume The new volume, must be between 0.0 and 1.0.
 392  * \return Whether the action succeeded.
 393  */
 394 extern int AUD_setSoundVolume(AUD_Channel* handle, float volume);
 395
 396 /**
 397  * Sets the pitch of a played back sound.
 398  * \param handle The handle to the sound.
 399  * \param pitch The new pitch.
 400  * \return Whether the action succeeded.
 401  */
 402 extern int AUD_setSoundPitch(AUD_Channel* handle, float pitch);
 403
 404 /**
 405  * Opens a read device, with which audio data can be read.
 406  * \param specs The specification of the audio data.
 407  * \return A device handle.
 408  */
 409 extern AUD_Device* AUD_openReadDevice(AUD_DeviceSpecs specs);
 410
 411 /**
 412  * Sets the main volume of a device.
 413  * \param device The device.
 414  * \param volume The new volume, must be between 0.0 and 1.0.
 415  * \return Whether the action succeeded.
 416  */
 417 extern int AUD_setDeviceVolume(AUD_Device* device, float volume);
 418
 419 /**
 420  * Plays back a sound file through a read device.
 421  * \param device The read device.
 422  * \param sound The handle of the sound file.
 423  * \param seek The position where the sound should be seeked to.
 424  * \return A handle to the played back sound.
 425  */
 426 extern AUD_Channel* AUD_playDevice(AUD_Device* device, AUD_Sound* sound, float seek);
 427
 428 /**
 429  * Sets the volume of a played back sound of a read device.
 430  * \param device The read device.
 431  * \param handle The handle to the sound.
 432  * \param volume The new volume, must be between 0.0 and 1.0.
 433  * \return Whether the action succeeded.
 434  */
 435 extern int AUD_setDeviceSoundVolume(AUD_Device* device,
 436                                                                         AUD_Channel* handle,
 437                                                                         float volume);
 438
 439 /**
 440  * Reads the next samples into the supplied buffer.
 441  * \param device The read device.
 442  * \param buffer The target buffer.
 443  * \param length The length in samples to be filled.
 444  * \return True if the reading succeeded, false if there are no sounds
 445  *         played back currently, in that case the buffer is filled with
 446  *         silence.
 447  */
 448 extern int AUD_readDevice(AUD_Device* device, data_t* buffer, int length);
 449
 450 /**
 451  * Closes a read device.
 452  * \param device The read device.
 453  */
 454 extern void AUD_closeReadDevice(AUD_Device* device);
 455
 456 /**
 457  * Reads a sound file into a newly created float buffer.
 458  * The sound is therefore bandpassed, rectified and resampled.
 459  */
 460 extern float* AUD_readSoundBuffer(const char* filename, float low, float high,
 461                                                                   float attack, float release, float threshold,
 462                                                                   int accumulate, int additive, int square,
 463                                                                   float sthreshold, int samplerate,
 464                                                                   int* length);
 465
 466 extern AUD_Sound* AUD_createSequencer(void* data, AUD_volumeFunction volume);
 467
 468 extern void AUD_destroySequencer(AUD_Sound* sequencer);
 469
 470 extern AUD_SequencerEntry* AUD_addSequencer(AUD_Sound** sequencer, AUD_Sound* sound,
 471                                                                                 float begin, float end, float skip, void* data);
 472
 473 extern void AUD_removeSequencer(AUD_Sound* sequencer, AUD_SequencerEntry* entry);
 474
 475 extern void AUD_moveSequencer(AUD_Sound* sequencer, AUD_SequencerEntry* entry,
 476                                                   float begin, float end, float skip);
 477
 478 extern void AUD_muteSequencer(AUD_Sound* sequencer, AUD_SequencerEntry* entry,
 479                                                   char mute);
 480
 481 extern int AUD_readSound(AUD_Sound* sound, sample_t* buffer, int length);
 482
 483 extern void AUD_startPlayback();
 484
 485 extern void AUD_stopPlayback();
 486
 487 extern void AUD_seekSequencer(AUD_Channel* handle, float time);
 488
 489 extern float AUD_getSequencerPosition(AUD_Channel* handle);
 490
 491 #ifdef WITH_JACK
 492 extern void AUD_setSyncCallback(AUD_syncFunction function, void* data);
 493 #endif
 494
 495 extern int AUD_doesPlayback();
 496
 497 #ifdef __cplusplus
 498 }
 499 #endif
 500
 501 #endif //AUD_CAPI