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