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  * \param time The time after which playback should stop, -1 for infinity.
 169  * \return Whether the handle is valid.
 170  */
 171 extern int AUD_setLoop(AUD_Channel* handle, int loops, float time);
 172
 173 /**
 174  * Rectifies a sound.
 175  * \param sound The sound to rectify.
 176  * \return A handle of the rectified sound.
 177  */
 178 extern AUD_Sound* AUD_rectifySound(AUD_Sound* sound);
 179
 180 /**
 181  * Unloads a sound of any type.
 182  * \param sound The handle of the sound.
 183  */
 184 extern void AUD_unload(AUD_Sound* sound);
 185
 186 /**
 187  * Plays back a sound file.
 188  * \param sound The handle of the sound file.
 189  * \param keep When keep is true the sound source will not be deleted but set to
 190  *             paused when its end has been reached.
 191  * \return A handle to the played back sound.
 192  */
 193 extern AUD_Channel* AUD_play(AUD_Sound* sound, int keep);
 194
 195 /**
 196  * Pauses a played back sound.
 197  * \param handle The handle to the sound.
 198  * \return Whether the handle has been playing or not.
 199  */
 200 extern int AUD_pause(AUD_Channel* handle);
 201
 202 /**
 203  * Resumes a paused sound.
 204  * \param handle The handle to the sound.
 205  * \return Whether the handle has been paused or not.
 206  */
 207 extern int AUD_resume(AUD_Channel* handle);
 208
 209 /**
 210  * Stops a playing or paused sound.
 211  * \param handle The handle to the sound.
 212  * \return Whether the handle has been valid or not.
 213  */
 214 extern int AUD_stop(AUD_Channel* handle);
 215
 216 /**
 217  * Sets the end behaviour of a playing or paused sound.
 218  * \param handle The handle to the sound.
 219  * \param keep When keep is true the sound source will not be deleted but set to
 220  *             paused when its end has been reached.
 221  * \return Whether the handle has been valid or not.
 222  */
 223 extern int AUD_setKeep(AUD_Channel* handle, int keep);
 224
 225 /**
 226  * Seeks a playing or paused sound.
 227  * \param handle The handle to the sound.
 228  * \param seekTo From where the sound file should be played back in seconds.
 229  * \return Whether the handle has been valid or not.
 230  */
 231 extern int AUD_seek(AUD_Channel* handle, float seekTo);
 232
 233 /**
 234  * Retrieves the playback position of a handle.
 235  * \param handle The handle to the sound.
 236  * \return The current playback position in seconds or 0.0 if the handle is
 237  *         invalid.
 238  */
 239 extern float AUD_getPosition(AUD_Channel* handle);
 240
 241 /**
 242  * Returns the status of a playing, paused or stopped sound.
 243  * \param handle The handle to the sound.
 244  * \return The status of the sound behind the handle.
 245  */
 246 extern AUD_Status AUD_getStatus(AUD_Channel* handle);
 247
 248 /**
 249  * Sets the listener location.
 250  * \param location The new location.
 251  */
 252 extern int AUD_setListenerLocation(const float* location);
 253
 254 /**
 255  * Sets the listener velocity.
 256  * \param velocity The new velocity.
 257  */
 258 extern int AUD_setListenerVelocity(const float* velocity);
 259
 260 /**
 261  * Sets the listener orientation.
 262  * \param orientation The new orientation as quaternion.
 263  */
 264 extern int AUD_setListenerOrientation(const float* orientation);
 265
 266 /**
 267  * Sets the speed of sound.
 268  * This value is needed for doppler effect calculation.
 269  * \param speed The new speed of sound.
 270  */
 271 extern int AUD_setSpeedOfSound(float speed);
 272
 273 /**
 274  * Sets the doppler factor.
 275  * This value is a scaling factor for the velocity vectors of sources and
 276  * listener which is used while calculating the doppler effect.
 277  * \param factor The new doppler factor.
 278  */
 279 extern int AUD_setDopplerFactor(float factor);
 280
 281 /**
 282  * Sets the distance model.
 283  * \param model distance model.
 284  */
 285 extern int AUD_setDistanceModel(AUD_DistanceModel model);
 286
 287 /**
 288  * Sets the location of a source.
 289  * \param handle The handle of the source.
 290  * \param location The new location.
 291  * \return Whether the action succeeded.
 292  */
 293 extern int AUD_setSourceLocation(AUD_Channel* handle, const float* location);
 294
 295 /**
 296  * Sets the velocity of a source.
 297  * \param handle The handle of the source.
 298  * \param velocity The new velocity.
 299  * \return Whether the action succeeded.
 300  */
 301 extern int AUD_setSourceVelocity(AUD_Channel* handle, const float* velocity);
 302
 303 /**
 304  * Sets the orientation of a source.
 305  * \param handle The handle of the source.
 306  * \param orientation The new orientation as quaternion.
 307  * \return Whether the action succeeded.
 308  */
 309 extern int AUD_setSourceOrientation(AUD_Channel* handle, const float* orientation);
 310
 311 /**
 312  * Sets whether the source location, velocity and orientation are relative
 313  * to the listener.
 314  * \param handle The handle of the source.
 315  * \param relative Whether the source is relative.
 316  * \return Whether the action succeeded.
 317  */
 318 extern int AUD_setRelative(AUD_Channel* handle, int relative);
 319
 320 /**
 321  * Sets the maximum volume of a source.
 322  * \param handle The handle of the source.
 323  * \param volume The new maximum volume.
 324  * \return Whether the action succeeded.
 325  */
 326 extern int AUD_setVolumeMaximum(AUD_Channel* handle, float volume);
 327
 328 /**
 329  * Sets the minimum volume of a source.
 330  * \param handle The handle of the source.
 331  * \param volume The new minimum volume.
 332  * \return Whether the action succeeded.
 333  */
 334 extern int AUD_setVolumeMinimum(AUD_Channel* handle, float volume);
 335
 336 /**
 337  * Sets the maximum distance of a source.
 338  * If a source is further away from the reader than this distance, the
 339  * volume will automatically be set to 0.
 340  * \param handle The handle of the source.
 341  * \param distance The new maximum distance.
 342  * \return Whether the action succeeded.
 343  */
 344 extern int AUD_setDistanceMaximum(AUD_Channel* handle, float distance);
 345
 346 /**
 347  * Sets the reference distance of a source.
 348  * \param handle The handle of the source.
 349  * \param distance The new reference distance.
 350  * \return Whether the action succeeded.
 351  */
 352 extern int AUD_setDistanceReference(AUD_Channel* handle, float distance);
 353
 354 /**
 355  * Sets the attenuation of a source.
 356  * This value is used for distance calculation.
 357  * \param handle The handle of the source.
 358  * \param factor The new attenuation.
 359  * \return Whether the action succeeded.
 360  */
 361 extern int AUD_setAttenuation(AUD_Channel* handle, float factor);
 362
 363 /**
 364  * Sets the outer angle of the cone of a source.
 365  * \param handle The handle of the source.
 366  * \param angle The new outer angle of the cone.
 367  * \return Whether the action succeeded.
 368  */
 369 extern int AUD_setConeAngleOuter(AUD_Channel* handle, float angle);
 370
 371 /**
 372  * Sets the inner angle of the cone of a source.
 373  * \param handle The handle of the source.
 374  * \param angle The new inner angle of the cone.
 375  * \return Whether the action succeeded.
 376  */
 377 extern int AUD_setConeAngleInner(AUD_Channel* handle, float angle);
 378
 379 /**
 380  * Sets the outer volume of the cone of a source.
 381  * The volume between inner and outer angle is interpolated between inner
 382  * volume and this value.
 383  * \param handle The handle of the source.
 384  * \param volume The new outer volume of the cone.
 385  * \return Whether the action succeeded.
 386  */
 387 extern int AUD_setConeVolumeOuter(AUD_Channel* handle, float volume);
 388
 389 /**
 390  * Sets the volume of a played back sound.
 391  * \param handle The handle to the sound.
 392  * \param volume The new volume, must be between 0.0 and 1.0.
 393  * \return Whether the action succeeded.
 394  */
 395 extern int AUD_setSoundVolume(AUD_Channel* handle, float volume);
 396
 397 /**
 398  * Sets the pitch of a played back sound.
 399  * \param handle The handle to the sound.
 400  * \param pitch The new pitch.
 401  * \return Whether the action succeeded.
 402  */
 403 extern int AUD_setSoundPitch(AUD_Channel* handle, float pitch);
 404
 405 /**
 406  * Opens a read device, with which audio data can be read.
 407  * \param specs The specification of the audio data.
 408  * \return A device handle.
 409  */
 410 extern AUD_Device* AUD_openReadDevice(AUD_DeviceSpecs specs);
 411
 412 /**
 413  * Sets the main volume of a device.
 414  * \param device The device.
 415  * \param volume The new volume, must be between 0.0 and 1.0.
 416  * \return Whether the action succeeded.
 417  */
 418 extern int AUD_setDeviceVolume(AUD_Device* device, float volume);
 419
 420 /**
 421  * Plays back a sound file through a read device.
 422  * \param device The read device.
 423  * \param sound The handle of the sound file.
 424  * \param seek The position where the sound should be seeked to.
 425  * \return A handle to the played back sound.
 426  */
 427 extern AUD_Channel* AUD_playDevice(AUD_Device* device, AUD_Sound* sound, float seek);
 428
 429 /**
 430  * Sets the volume of a played back sound of a read device.
 431  * \param device The read device.
 432  * \param handle The handle to the sound.
 433  * \param volume The new volume, must be between 0.0 and 1.0.
 434  * \return Whether the action succeeded.
 435  */
 436 extern int AUD_setDeviceSoundVolume(AUD_Device* device,
 437                                                                         AUD_Channel* handle,
 438                                                                         float volume);
 439
 440 /**
 441  * Reads the next samples into the supplied buffer.
 442  * \param device The read device.
 443  * \param buffer The target buffer.
 444  * \param length The length in samples to be filled.
 445  * \return True if the reading succeeded, false if there are no sounds
 446  *         played back currently, in that case the buffer is filled with
 447  *         silence.
 448  */
 449 extern int AUD_readDevice(AUD_Device* device, data_t* buffer, int length);
 450
 451 /**
 452  * Closes a read device.
 453  * \param device The read device.
 454  */
 455 extern void AUD_closeReadDevice(AUD_Device* device);
 456
 457 /**
 458  * Reads a sound file into a newly created float buffer.
 459  * The sound is therefore bandpassed, rectified and resampled.
 460  */
 461 extern float* AUD_readSoundBuffer(const char* filename, float low, float high,
 462                                                                   float attack, float release, float threshold,
 463                                                                   int accumulate, int additive, int square,
 464                                                                   float sthreshold, int samplerate,
 465                                                                   int* length);
 466
 467 extern AUD_Sound* AUD_createSequencer(void* data, AUD_volumeFunction volume);
 468
 469 extern void AUD_destroySequencer(AUD_Sound* sequencer);
 470
 471 extern AUD_SequencerEntry* AUD_addSequencer(AUD_Sound** sequencer, AUD_Sound* sound,
 472                                                                                 float begin, float end, float skip, void* data);
 473
 474 extern void AUD_removeSequencer(AUD_Sound* sequencer, AUD_SequencerEntry* entry);
 475
 476 extern void AUD_moveSequencer(AUD_Sound* sequencer, AUD_SequencerEntry* entry,
 477                                                   float begin, float end, float skip);
 478
 479 extern void AUD_muteSequencer(AUD_Sound* sequencer, AUD_SequencerEntry* entry,
 480                                                   char mute);
 481
 482 extern int AUD_readSound(AUD_Sound* sound, sample_t* buffer, int length);
 483
 484 extern void AUD_startPlayback();
 485
 486 extern void AUD_stopPlayback();
 487
 488 extern void AUD_seekSequencer(AUD_Channel* handle, float time);
 489
 490 extern float AUD_getSequencerPosition(AUD_Channel* handle);
 491
 492 #ifdef WITH_JACK
 493 extern void AUD_setSyncCallback(AUD_syncFunction function, void* data);
 494 #endif
 495
 496 extern int AUD_doesPlayback();
 497
 498 #ifdef __cplusplus
 499 }
 500 #endif
 501
 502 #endif //AUD_CAPI