intern/audaspace/intern/AUD_C-API.h

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