GNU Info

(openal.info)alc

---

Next: alut Prev: al Up: API

---

Enter node , (file) or (file)node

OpenAL Device and Context management functions
==============================================

   You can't do anything really good in OpenAL without opening at least
one device and creating at least one context.  One context must be made
current before any al calls can be made, or else bad mojo will ensue.

`ALCdevice *alcOpenDevice( const ALubyte *deviceSpecifier );'
     `alcOpenDevice' opens a rendering backend, using `deviceSpecifier'
     to determine the type of device and any special options.
     `deviceSpecifier' is an implementation dependant string.

     In the Loki implementation, this string is an `ALRC' token string,
     in the form:

                  '( ( symbol1 value1 ) ( symbol2 value2 ) )

     Each symbol is bound to the associated value, overriding any
     previously set value.  Important symbols include:

    `devices'
          `devices' is a list of tokens (either strings or unquoted
          symbols) that OpenAL checks for in order to determine the
          sequence and types of devices that should be used to render
          audio to.

          The list of available devices at the time of this writing is:
          native              operating system native
          sdl                 Simple DirectMedia Layer
                              backend
          arts                aRTs backend
          esd                 esound daemon backend
          alsa                ALSA backend
          waveout             WAVE file output
          null                no output

          A device string in this context would look like:

                       '( ( devices '( native esd null ) ) )

          which would tell `alcOpenDevice' to first attempt `native'
          audio, failing that try to use the `esd' backend, and failing
          that to fall back on the `null' backend, in which processing
          is done as normal but no output is provided.

    `sampling-rate'
          `sampling-rate' is an `ALRC_INTEGER' that specifier the
          external sampling rate to set the backend to, if possible.
          Common values include 11025, 22050, and 44100.

          A sampling-rate example might look like:

                       '( ( sample-rate 22050 ) )

          This does not alter the internal mixing rate ( the frequency
          which the library mixes different streams at ).  To alter the
          interal mixing rate, all contexts created must specify the
          context creation flag `ALC_FREQUENCY'.

`void *alcCreateContext( ALCdevice *device, ALint* attrlist )'
     Create a context, returning a unique identifier for the context,
     or NULL on error.  The context is associated with the passed
     device and uses it to do its rendering.

     `attrlist' is usually `NULL', but you can pass it an integer array
     terminated by `ALC_INVALID' in alc enum / integer pairs.

          	int attrlist[] = { ALC_SYNC, AL_TRUE,
          			   ALC_SOURCES, 100,
          			   ALC_FREQUENCY, 44100,
          			   ALC_INVALID };
          	ALCdevice *dev = alcOpenDevice( NULL );
          
          	void *context = alcCreateContext( dev, attrlist );

     Valid context creation flags include:

    `ALC_FREQUENCY'
          `ALC_FREQUENCY' sets the internal mixing rate of the context.
          It does not alter the mixing rate of the external device.

    `ALC_SYNC'
          Boolean representing whether the context should depend on the
          use of `alcUpdateContext' to perform it's mixing or launch a
          seperate thread.

    `ALC_BUFFERSIZE'
          Size of the mixing buffer, in bytes.

    `ALC_SOURCES'
          Number of sources to preallocate.

    `ALC_BUFFERS'
          Number of buffers to preallocate.

`ALCenum alcMakeContextCurrent( ALvoid *alcHandle )'
     `alcMakeContextCurrent' sets the current context, which is what al
     calls (in general) either alter or query.  Several contexts can be
     mixed simultaneously.

`void *alcProcessContext( ALvoid *alcHandle )'
     For synchronous operation (where the context specified by alcHandle
     was created using the `ALC_SYNC' context creation flag), this
     commits all the changes needed and writes the result to the audio
     backend.

     In asynchronous operation, this almost always is a NOP.  The single
     exception that `alcProcessContext' will unpause a paused
     asynchronous context.

`void *alcPauseContext( ALvoid *alcHandle )'
     For currently unpaused asynchronous contexts, this call pauses the
     context and prevents any of its sources from being processed.
     Sources associated with this context do not have their position
     updated, and no mixing occurs.

     For paused asynchronous context, or synchronous contexts, this is a
     legal NOP.

`ALCenum alcDestroyContext( ALvoid *alcHandle )'
     Destroy the context associated with `alcHandle', freeing all
     associated objects and sources.

`ALCenum alcGetError( ALvoid );'
     Get the last `alc' error set.

`const ALubyte *alcGetErrorString(ALenum param);'
     Get the string representation of the last `alc' error set.