Dependencies/OpenAL/include/AL/al.h

   1 #ifndef __al_h_
   2 #define __al_h_
   3
   4 /**
   5  * OpenAL cross platform audio library
   6  * Copyright (C) 1999-2000 by authors.
   7  * This library is free software; you can redistribute it and/or
   8  *  modify it under the terms of the GNU Library General Public
   9  *  License as published by the Free Software Foundation; either
  10  *  version 2 of the License, or (at your option) any later version.
  11  *
  12  * This library is distributed in the hope that it will be useful,
  13  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15  *  Library General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Library General Public
  18  *  License along with this library; if not, write to the
  19  *  Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  20  *  Boston, MA  02111-1307, USA.
  21  * Or go to http://www.gnu.org/copyleft/lgpl.html
  22  */
  23 #include "altypes.h"
  24
  25 #ifdef __cplusplus
  26 extern "C" {
  27 #endif
  28
  29 #ifdef _WIN32
  30 #define ALAPI       __declspec(dllexport)
  31 #define ALAPIENTRY  __cdecl
  32 #define AL_CALLBACK
  33 #else /* _WIN32 */
  34
  35 #ifdef TARGET_OS_MAC
  36 #if TARGET_OS_MAC
  37 #pragma export on
  38 #endif /* TARGET_OS_MAC */
  39 #endif /* TARGET_OS_MAC */
  40
  41 #ifndef ALAPI
  42 #define ALAPI
  43 #endif
  44
  45 #ifndef ALAPIENTRY
  46 #define ALAPIENTRY
  47 #endif
  48
  49 #ifndef CALLBACK
  50 #define AL_CALLBACK
  51 #endif
  52
  53 #endif /* _WIN32 */
  54
  55 #ifndef AL_NO_PROTOTYPES
  56
  57 /**
  58  * OpenAL Maintenance Functions
  59  * State Management and Query.
  60  * Error Handling.
  61  * Extension Support.
  62  */
  63
  64
  65 /** Renderer State management. */
  66 ALAPI void ALAPIENTRY alEnable( ALenum capability );
  67
  68 ALAPI void ALAPIENTRY alDisable( ALenum capability );
  69
  70 ALAPI ALboolean ALAPIENTRY alIsEnabled( ALenum capability );
  71
  72 /** Application preferences for driver performance choices. */
  73 ALAPI void ALAPIENTRY alHint( ALenum target, ALenum mode );
  74
  75 /** State retrieval. */
  76 ALAPI void ALAPIENTRY alGetBooleanv( ALenum param, ALboolean* data );
  77
  78 /** State retrieval. */
  79 ALAPI void ALAPIENTRY alGetIntegerv( ALenum param, ALint* data );
  80
  81 /** State retrieval. */
  82 ALAPI void ALAPIENTRY alGetFloatv( ALenum param, ALfloat* data );
  83
  84 /** State retrieval. */
  85 ALAPI void ALAPIENTRY alGetDoublev( ALenum param, ALdouble* data );
  86
  87 /** State retrieval. */
  88 ALAPI const ALubyte* ALAPIENTRY alGetString( ALenum param );
  89
  90
  91 /** State retrieval.through return value ( for compatibility ) */
  92 ALAPI ALboolean ALAPIENTRY alGetBoolean( ALenum param );
  93 ALAPI ALint ALAPIENTRY alGetInteger( ALenum param );
  94 ALAPI ALfloat ALAPIENTRY alGetFloat( ALenum param );
  95 ALAPI ALdouble ALAPIENTRY alGetDouble( ALenum param );
  96
  97 /**
  98  * Error support.
  99  * Obtain the most recent error generated in the AL state machine.
 100  */
 101 ALAPI ALenum ALAPIENTRY alGetError( ALvoid );
 102
 103 /**
 104  * Extension support.
 105  * Obtain the address of a function (usually an extension)
 106  *  with the name fname. All addresses are context-independent.
 107  */
 108 ALAPI ALboolean ALAPIENTRY alIsExtensionPresent( const ALubyte* fname );
 109
 110
 111 /**
 112  * Extension support.
 113  * Obtain the address of a function (usually an extension)
 114  *  with the name fname. All addresses are context-independent.
 115  */
 116 ALAPI void* ALAPIENTRY alGetProcAddress( const ALubyte* fname );
 117
 118
 119 /**
 120  * Extension support.
 121  * Obtain the integer value of an enumeration (usually an extension) with the name ename.
 122  */
 123 ALAPI ALenum ALAPIENTRY alGetEnumValue( const ALubyte* ename );
 124
 125
 126
 127
 128
 129
 130 /**
 131  * LISTENER
 132  * Listener is the sample position for a given context.
 133  * The multi-channel (usually stereo) output stream generated
 134  *  by the mixer is parametrized by this Listener object:
 135  *  its position and velocity relative to Sources, within
 136  *  occluder and reflector geometry.
 137  */
 138
 139
 140
 141 /**
 142  *
 143  * Listener Gain:  default 1.0f.
 144  */
 145 ALAPI void ALAPIENTRY alListenerf( ALenum pname, ALfloat param );
 146
 147 ALAPI void ALAPIENTRY alListeneri( ALenum pname, ALint param );
 148
 149 /**
 150  *
 151  * Listener Position:        ALfloat[3]
 152  * Listener Velocity:        ALfloat[3]
 153  */
 154 ALAPI void ALAPIENTRY alListener3f( ALenum pname,
 155                                     ALfloat f1, ALfloat f2, ALfloat f3 );
 156
 157 /**
 158  *
 159  * Listener Position:        ALfloat[3]
 160  * Listener Velocity:        ALfloat[3]
 161  * Listener Orientation:     ALfloat[6]  (forward and up vector).
 162  */
 163 ALAPI void ALAPIENTRY alListenerfv( ALenum pname, ALfloat* param );
 164
 165 /*
 166  * Retrieve listener information.
 167  */
 168 ALAPI void ALAPIENTRY alGetListeneri( ALenum pname, ALint* value );
 169 ALAPI void ALAPIENTRY alGetListenerf( ALenum pname, ALfloat* value );
 170
 171 ALAPI void ALAPIENTRY alGetListeneriv( ALenum pname, ALint* value );
 172 ALAPI void ALAPIENTRY alGetListenerfv( ALenum pname, ALfloat* values );
 173
 174 ALAPI void ALAPIENTRY alGetListener3f( ALenum pname,
 175                                        ALfloat *f1, ALfloat *f2, ALfloat *f3 );
 176
 177 /**
 178  * SOURCE
 179  * Source objects are by default localized. Sources
 180  *  take the PCM data provided in the specified Buffer,
 181  *  apply Source-specific modifications, and then
 182  *  submit them to be mixed according to spatial
 183  *  arrangement etc.
 184  */
 185
 186
 187
 188 /** Create Source objects. */
 189 ALAPI void ALAPIENTRY alGenSources( ALsizei n, ALuint* sources );
 190
 191 /** Delete Source objects. */
 192 ALAPI void ALAPIENTRY alDeleteSources( ALsizei n, ALuint* sources );
 193
 194 /** Verify a handle is a valid Source. */
 195 ALAPI ALboolean ALAPIENTRY alIsSource( ALuint sid );
 196
 197
 198 /** Set an integer parameter for a Source object. */
 199 ALAPI void ALAPIENTRY alSourcei( ALuint sid, ALenum param, ALint value );
 200 ALAPI void ALAPIENTRY alSourcef( ALuint sid, ALenum param, ALfloat value );
 201 ALAPI void ALAPIENTRY alSource3f( ALuint sid, ALenum param,
 202                                   ALfloat f1, ALfloat f2, ALfloat f3 );
 203 ALAPI void ALAPIENTRY alSourcefv( ALuint sid, ALenum param, ALfloat* values );
 204
 205 /** Get an integer parameter for a Source object. */
 206 ALAPI void ALAPIENTRY alGetSourcei( ALuint sid,  ALenum pname, ALint* value );
 207 ALAPI void ALAPIENTRY alGetSourceiv( ALuint sid,  ALenum pname, ALint* values );
 208 ALAPI void ALAPIENTRY alGetSourcef( ALuint sid, ALenum pname, ALfloat* value );
 209 ALAPI void ALAPIENTRY alGetSourcefv( ALuint sid, ALenum pname, ALfloat* values );
 210
 211 /* deprecated, included for Win compatibility */
 212 ALAPI void ALAPIENTRY alGetSource3f( ALuint sid, ALenum pname, ALfloat* value1,
 213                                      ALfloat* value2, ALfloat* value3);
 214
 215 ALAPI void ALAPIENTRY alSourcePlayv( ALsizei ns, ALuint *ids );
 216 ALAPI void ALAPIENTRY alSourceStopv( ALsizei ns, ALuint *ids );
 217 ALAPI void ALAPIENTRY alSourceRewindv( ALsizei ns, ALuint *ids );
 218 ALAPI void ALAPIENTRY alSourcePausev( ALsizei ns, ALuint *ids );
 219
 220 /** Activate a source, start replay. */
 221 ALAPI void ALAPIENTRY alSourcePlay( ALuint sid );
 222
 223 /**
 224  * Pause a source,
 225  *  temporarily remove it from the mixer list.
 226  */
 227 ALAPI void ALAPIENTRY alSourcePause( ALuint sid );
 228
 229 /**
 230  * Rewind a source,
 231  *  set the source to play at the beginning.
 232  */
 233 ALAPI void ALAPIENTRY alSourceRewind( ALuint sid );
 234
 235 /**
 236  * Stop a source,
 237  *  temporarily remove it from the mixer list,
 238  *  and reset its internal state to pre-Play.
 239  * To remove a Source completely, it has to be
 240  *  deleted following Stop, or before Play.
 241  */
 242 ALAPI void ALAPIENTRY alSourceStop( ALuint sid );
 243
 244 /**
 245  * BUFFER
 246  * Buffer objects are storage space for sample data.
 247  * Buffers are referred to by Sources. There can be more than
 248  *  one Source using the same Buffer data. If Buffers have
 249  *  to be duplicated on a per-Source basis, the driver has to
 250  *  take care of allocation, copying, and deallocation as well
 251  *  as propagating buffer data changes.
 252  */
 253
 254
 255
 256
 257 /** Buffer object generation. */
 258 ALAPI void ALAPIENTRY alGenBuffers( ALsizei n, ALuint* buffers );
 259
 260 ALAPI void ALAPIENTRY alDeleteBuffers( ALsizei n, ALuint* buffers );
 261
 262
 263 ALAPI ALboolean ALAPIENTRY alIsBuffer( ALuint buffer );
 264
 265 /**
 266  * Specify the data to be filled into a buffer.
 267  */
 268 ALAPI void ALAPIENTRY alBufferData( ALuint   buffer,
 269                    ALenum   format,
 270                    ALvoid*    data,
 271                    ALsizei  size,
 272                    ALsizei  freq );
 273
 274 ALAPI void ALAPIENTRY alGetBufferi( ALuint buffer, ALenum param, ALint*   value );
 275 ALAPI void ALAPIENTRY alGetBufferf( ALuint buffer, ALenum param, ALfloat* value );
 276 ALAPI void ALAPIENTRY alGetBufferiv( ALuint buffer, ALenum param, ALint *v);
 277 ALAPI void ALAPIENTRY alGetBufferfv( ALuint buffer, ALenum param, ALfloat *v);
 278
 279
 280
 281 /**
 282  * Frequency Domain Filters are band filters.
 283  *  Attenuation in Media (distance based)
 284  *  Reflection Material
 285  *  Occlusion Material (separating surface)
 286  *
 287  * Temporal Domain Filters:
 288  *  Early Reflections
 289  *  Late Reverb
 290  *
 291  */
 292
 293
 294
 295
 296 /**
 297  * EXTENSION: IASIG Level 2 Environment.
 298  * Environment object generation.
 299  * This is an EXTension that describes the Environment/Reverb
 300  *  properties according to IASIG Level 2 specifications.
 301  */
 302
 303
 304
 305
 306
 307 /**
 308  * Allocate n environment ids and store them in the array environs.
 309  * Returns the number of environments actually allocated.
 310  */
 311 ALAPI ALsizei ALAPIENTRY alGenEnvironmentIASIG( ALsizei n, ALuint* environs );
 312
 313 ALAPI void ALAPIENTRY alDeleteEnvironmentIASIG( ALsizei n, ALuint* environs );
 314
 315 ALAPI ALboolean ALAPIENTRY alIsEnvironmentIASIG( ALuint environ );
 316
 317 ALAPI void ALAPIENTRY alEnvironmentiIASIG( ALuint eid, ALenum param, ALint value );
 318
 319 ALAPI void ALAPIENTRY alEnvironmentfIASIG( ALuint eid, ALenum param, ALfloat value );
 320
 321
 322
 323 /**
 324  * Queue stuff
 325  */
 326 ALAPI void ALAPIENTRY alSourceQueueBuffers( ALuint sid, ALsizei numEntries, ALuint *bids );
 327 ALAPI void ALAPIENTRY alSourceUnqueueBuffers( ALuint sid, ALsizei numEntries, ALuint *bids );
 328 ALAPI void ALAPIENTRY alQueuei( ALuint sid, ALenum param, ALint value );
 329
 330 /**
 331  * Knobs and dials
 332  */
 333 ALAPI void ALAPIENTRY alDopplerFactor( ALfloat value );
 334 ALAPI void ALAPIENTRY alDopplerVelocity( ALfloat value );
 335 ALAPI void ALAPIENTRY alDistanceModel( ALenum distanceModel );
 336
 337 #else /* AL_NO_PROTOTYPES */
 338
 339
 340 /** OpenAL Maintenance Functions */
 341
 342       void                         (*alEnable)( ALenum capability );
 343       void                         (*alDisable)( ALenum capability );
 344       ALboolean                    (*alIsEnabled)( ALenum capability );
 345       void                           (*alHint)( ALenum target, ALenum mode );
 346       ALboolean                    (*alGetBoolean)( ALenum param );
 347       ALint                        (*alGetInteger)( ALenum param );
 348       ALfloat                      (*alGetFloat)( ALenum param );
 349       ALdouble                     (*alGetDouble)( ALenum param );
 350       void                         (*alGetBooleanv)( ALenum param,
 351                                                       ALboolean* data );
 352       void                         (*alGetIntegerv)( ALenum param,
 353                                                       ALint* data );
 354       void                         (*alGetFloatv)( ALenum param,
 355                                                       ALfloat* data );
 356       void                         (*alGetDoublev)( ALenum param,
 357                                                       ALdouble* data );
 358       const ALubyte*               (*GetString)( ALenum param );
 359       ALenum                       (*alGetError)( ALvoid );
 360
 361       /**
 362        * Extension support.
 363        * Query existance of extension
 364        */
 365       ALboolean                (*alIsExtensionPresent)(const ALubyte* fname );
 366
 367       /**
 368        * Extension support.
 369        * Obtain the address of a function (usually an extension)
 370        *  with the name fname. All addresses are context-independent.
 371        */
 372       void*                (*alGetProcAddress)( const ALubyte* fname );
 373
 374
 375       /**
 376        * Extension support.
 377        * Obtain the integer value of an enumeration (usually an extension) with the name ename.
 378        */
 379       ALenum                (*alGetEnumValue)( const ALubyte* ename );
 380
 381 /**
 382  * LISTENER
 383  * Listener is the sample position for a given context.
 384  * The multi-channel (usually stereo) output stream generated
 385  *  by the mixer is parametrized by this Listener object:
 386  *  its position and velocity relative to Sources, within
 387  *  occluder and reflector geometry.
 388  */
 389       /**
 390        *
 391        * Listener Gain:  default 1.0f.
 392        */
 393       void                (*alListenerf)( ALenum pname, ALfloat param );
 394
 395       /**
 396        *
 397        * Listener Position:        ALfloat[3]
 398        * Listener Velocity:        ALfloat[3]
 399        * Listener Orientation:     ALfloat[6]  (forward and up vector).
 400        */
 401       void                (*alListenerfv)( ALenum pname, ALfloat* param );
 402
 403       /*
 404        * Retrieve listener information.
 405        */
 406       void              (*alGetListeneri)( ALenum pname, ALint* value );
 407       void              (*alGetListenerf)( ALenum pname, ALfloat* value );
 408
 409       void              (*alGetListeneriv)( ALenum pname, ALint* values );
 410       void              (*alGetListenerfv)( ALenum pname, ALfloat* values );
 411
 412 /**
 413  * SOURCE
 414  * Source objects are by default localized. Sources
 415  *  take the PCM data provided in the specified Buffer,
 416  *  apply Source-specific modifications, and then
 417  *  submit them to be mixed according to spatial
 418  *  arrangement etc.
 419  */
 420
 421       /** Create Source objects. */
 422       void                (*alGenSources)( ALsizei n, ALuint* sources );
 423
 424       /** Delete Source objects. */
 425       void                (*alDeleteSources)( ALsizei n, ALuint* sources );
 426
 427       /** Verify a handle is a valid Source. */
 428       ALboolean        (*alIsSource)( ALuint sid );
 429
 430       /** Set an integer parameter for a Source object. */
 431       void                (*alSourcei)( ALuint sid, ALenum param, ALint value);
 432
 433       /** Set a float parameter for a Source object. */
 434       void                (*alSourcef)( ALuint sid, ALenum param, ALfloat value);
 435
 436       /** Set a 3 float parameter for a Source object. */
 437       void                (*alSource3f)( ALuint sid, ALenum param,
 438                                   ALfloat f1, ALfloat f2, ALfloat f3 );
 439
 440       /** Set a float vector parameter for a Source object. */
 441       void                (*alSourcefv)( ALuint sid, ALenum param,
 442                               ALfloat* values );
 443
 444       /** Get an integer scalar parameter for a Source object. */
 445       void                (*alGetSourcei)( ALuint sid,
 446                               ALenum pname, ALint* value );
 447
 448       /** Get an integer parameter for a Source object. */
 449       void                (*alGetSourceiv)( ALuint sid,
 450                               ALenum pname, ALint* values );
 451
 452       /** Get a float scalar parameter for a Source object. */
 453       void                (*alGetSourcef)( ALuint sid,
 454                               ALenum pname, ALfloat* value );
 455
 456       /** Get three float scalar parameter for a Source object. */
 457       void                (*alGetSource3f)( ALuint sid, ALenum pname,
 458                                             ALfloat* value1,
 459                                             ALfloat* value2,
 460                                             ALfloat* value3);
 461
 462       /** Get a float vector parameter for a Source object. */
 463       void                (*alGetSourcefv)( ALuint sid,
 464                               ALenum pname, ALfloat* values );
 465
 466
 467       /** Activate a source, start replay. */
 468       void                (*alSourcePlay)( ALuint sid );
 469
 470       /**
 471        * Pause a source,
 472        *  temporarily remove it from the mixer list.
 473        */
 474       void                (*alSourcePause)( ALuint sid );
 475
 476       /**
 477        * Stop a source,
 478        *  temporarily remove it from the mixer list,
 479        *  and reset its internal state to pre-Play.
 480        * To remove a Source completely, it has to be
 481        *  deleted following Stop, or before Play.
 482        */
 483       void                (*alSourceStop)( ALuint sid );
 484
 485       /**
 486        * Rewind a souce.  Stopped paused and playing sources,
 487        * resets the offset into the PCM data and sets state to
 488        * AL_INITIAL.
 489        */
 490       void                (*alSourceRewind)( ALuint sid );
 491
 492       /**
 493        * vector forms of those functions we all love
 494        */
 495       void                (*alSourcePlayv)( ALsizei ns, ALuint *ids );
 496       void                (*alSourceStopv)( ALsizei ns, ALuint *ids );
 497       void                (*alSourceRewindv)( ALsizei ns, ALuint *ids );
 498       void                (*alSourcePausev)( ALsizei ns, ALuint *ids );
 499
 500 /**
 501  * BUFFER
 502  * Buffer objects are storage space for sample data.
 503  * Buffers are referred to by Sources. There can be more than
 504  *  one Source using the same Buffer data. If Buffers have
 505  *  to be duplicated on a per-Source basis, the driver has to
 506  *  take care of allocation, copying, and deallocation as well
 507  *  as propagating buffer data changes.
 508  */
 509
 510       /** Buffer object generation. */
 511       void                (*alGenBuffers)( ALsizei n, ALuint* buffers );
 512       void                (*alDeleteBuffers)( ALsizei n, ALuint* buffers );
 513       ALboolean           (*alIsBuffer)( ALuint buffer );
 514
 515       /**
 516        * Specify the data to be filled into a buffer.
 517        */
 518       void                (*alBufferData)( ALuint   buffer,
 519                                         ALenum   format,
 520                                         ALvoid*    data,
 521                                         ALsizei  size,
 522                                         ALsizei  freq );
 523
 524       void                (*alGetBufferi)( ALuint buffer,
 525                                       ALenum param, ALint*   value );
 526       void                (*alGetBufferf)( ALuint buffer,
 527                                       ALenum param, ALfloat* value );
 528       void                (*alGetBufferiv)( ALuint buffer,
 529                                       ALenum param, ALint*   value );
 530       void                (*alGetBufferfv)( ALuint buffer,
 531                                       ALenum param, ALfloat* value );
 532
 533 /**
 534  * EXTENSION: IASIG Level 2 Environment.
 535  * Environment object generation.
 536  * This is an EXTension that describes the Environment/Reverb
 537  *  properties according to IASIG Level 2 specifications.
 538  */
 539       /**
 540        * Allocate n environment ids and store them in the array environs.
 541        * Returns the number of environments actually allocated.
 542        */
 543       ALsizei                (*alGenEnvironmentIASIG)( ALsizei n, ALuint* environs );
 544       void                (*alDeleteEnvironmentIASIG)(ALsizei n,
 545                                               ALuint* environs);
 546       ALboolean                (*alIsEnvironmentIASIG)( ALuint environ );
 547       void                (*alEnvironmentiIASIG)( ALuint eid,
 548                                       ALenum param, ALint value );
 549       void                (*alEnvironmentfIASIG)( ALuint eid,
 550                                       ALenum param, ALuint value );
 551       /**
 552        * Queue stuff
 553        */
 554       void              (*alQueuei)(ALuint sid, ALenum param, ALint value );
 555       void              (*alSourceUnqueueBuffers)(ALuint sid, ALsizei numEntries, ALuint *bids );
 556       void              (*alSourceQueueBuffers)(ALuint sid, ALsizei numEntries, ALuint *bids );
 557
 558       void              (*alDopplerFactor)( ALfloat value );
 559       void              (*alDopplerVelocity)( ALfloat value );
 560       void              (*alDistanceModel)( ALenum distanceModel );
 561
 562 /**
 563  * Frequency Domain Filters are band filters.
 564  *  Attenuation in Media (distance based)
 565  *  Reflection Material
 566  *  Occlusion Material (separating surface)
 567  *
 568  * Temporal Domain Filters:
 569  *  Early Reflections
 570  *  Late Reverb
 571  *
 572  */
 573
 574 #endif /* AL_NO_PROTOTYPES */
 575
 576 #ifdef TARGET_OS_MAC
 577 #if TARGET_OS_MAC
 578 #pragma export off
 579 #endif /* TARGET_OS_MAC */
 580 #endif /* TARGET_OS_MAC */
 581
 582
 583 #ifdef __cplusplus
 584 }  /* extern "C" */
 585 #endif
 586
 587 #endif /* __al_h_ */