This is Info file openal.info, produced by Makeinfo version 1.68 from
the input file openal.texi.

START-INFO-DIR-ENTRY
* OpenAL: (openal).         The Programmer's Guide to 3d Positional Audio
END-INFO-DIR-ENTRY


File: openal.info,  Node: Top,  Next: Introduction,  Up: (dir)

OpenAL
******

   This document describes the OpenAL API, design goals and Loki's
OpenAL implementation.

* Menu:

* Introduction::         What is OpenAL and what is it good for?
* FAQ::                  Frequency Asked Questions, with answers
* Goals::                Basic design decisions, requirements, scope, etc.
* API::                  The OpenAL API
* Loki Implementation::  Loki's own OpenAL implementation: today and tomorrow.
* Example::              An example of a program using the OpenAL API.
* Tutorial::             A gentle introduction to Loki's AL

* Function Index::
* Variable Index::
* Concept Index::


File: openal.info,  Node: Introduction,  Next: FAQ,  Prev: Top,  Up: Top

Introduction
************

   The idea behind OpenAL is a 3d positional spatialized sound library
analogous to OpenGL: instead of micromanaging each aspect of sound
playback and effect, the application writer may limit themselves to
placing the sounds in the scene and letting the native OpenAL
implementation determine the correct amount of pitch alteration, gain
attenuation, phase shift, etc, required to render the sounds correctly.

   That's the goal, anyway.


File: openal.info,  Node: FAQ,  Next: Goals,  Prev: Introduction,  Up: Top

   Here are some of the most Frequently Asked Questions, and their
answers.

* Menu:

* How do I enable ESD?::
* Why doesn't this POS work with my Vortex card?::
* How can I set the size of my world?::


File: openal.info,  Node: How do I enable ESD?,  Up: FAQ

   Configure openal with `configure --enable-esd'.  make, then install.
Then, place the following in your `~/.openalrc' file:


     	(define devices '(esd))


File: openal.info,  Node: Why doesn't this POS work with my Vortex card?,  Up: FAQ

   Dollars-to-donuts your driver doesn't implemented the select call
properly.  You can see messages from `native_blitbuffer' complaining
about select timeouts when this is a problem.

   If you suffer from an unimplemented select call in your driver, put
the following in your `~/.openalrc' file:


     	(define native-use-select #f)

   This will tell `OpenAL' that it shouldn't rely on select for
information about when to write to a file descriptor.


File: openal.info,  Node: How can I set the size of my world?,  Up: FAQ

   You don't need to.  Use the source attributes `AL_ROLLOFF_FACTOR' and
`AL_REFERENCE_DISTANCE' to correctly model your position data.


File: openal.info,  Node: Goals,  Next: API,  Prev: FAQ,  Up: Top

Goals
*****

   To provide a cross-platform spatialized audio library.


File: openal.info,  Node: API,  Next: Loki Implementation,  Prev: Goals,  Up: Top

The OpenAL API
**************

   This is the OpenAL API.  Sort of.

* Menu:

OpenAL Sections:

* Basic Concepts::                  Stuff defined
* types::                           Integral types
* al::                              High level stuff
* alc::                             Device and Context management
* alut::                            Utility functions, etc
* alkludge::                        Kludgey, Deprecated stuff
* Errors::                          What goes wrong and where


File: openal.info,  Node: Basic Concepts,  Next: types,  Up: API

   al calls, either implicitly or explicitly, act upon opaque objects
of the kind `Buffers', `Sources', `Contexts', or `Listeners'.  Of these
types, the generation and deletion of `Buffers', `Sources', and
`Contexts' are explicit and must be handled by the application.

   To give a brief overview:

`Buffers'
     `Buffers' contain PCM audio data, and the parameters associated
     with the data (length, frequency, sample width etc).  `Buffers'
     cannot be played, a `Source' must be associated with them, and the
     `Source' is then played.

     `Buffers' are created with a call to `alGenBuffers', which creates
     a set of buffer ids and binds them to buffers.  The buffer id is
     the only mechanism by which an application may refer to a buffer.
     After its useful lifetime is over, buffer ids should be deleted
     via the call `alDeleteBuffers'.

`Sources'
     `Sources' are independent objects, which, when played, make sound.
     `Sources' need to be associated with a `Buffer' before they can be
     played.

     `Sources' are created with a call to `alGenSources', which creates
     a set of source ids and binds them to sources.  The source id is
     the only mechanism by which an application may refer to a source.
     After its useful lifetime is over, source ids should be deleted
     via the call `alDeleteSources'.

`Devices'
     A `Device' is a binding to the audio rendered backend used by the
     library.  This may be an actual hardware device, a software mixing
     server, or other abstraction.

     At least one device must be created for the generation of contexts.

`Contexts'
     A `Context' abstracts the audio device from the rest of the library
     (and the application).  You generally only need one.  Calling most
     al functions before creating a context via `alcCreateContext' will
     result in either an error or a segfault.

     When you're about to quit, call `alcDestroyContext' to destroy the
     context and don't make any other al calls.


File: openal.info,  Node: types,  Next: al,  Prev: Basic Concepts,  Up: API

OpenAL types
============

`ALboolean'
     OpenAL bool type.

`ALbyte'
     OpenAL 8bit signed byte.

`ALubyte'
     OpenAL 8bit unsigned byte.

`ALshort'
     OpenAL 16bit signed short integer type.

`ALushort'
     OpenAL 16bit unsigned short integer type.

`ALuint'
     OpenAL 32bit unsigned integer type.

`ALint'
     OpenAL 32bit signed integer type.

`ALfloat'
     OpenAL 32bit floating point type.

`ALdouble'
     OpenAL 64bit double point type.

`ALsizei'
     OpenAL 32bit type.

`ALbitfield'
     OpenAL bitfield.

`ALclampf'
     Openal clamped float value.

`ALclampd'
     Openal clamped double value.


File: openal.info,  Node: al,  Next: alc,  Prev: types,  Up: API

OpenAL main functions
=====================

   Here are the al functions, grouped according to object they affect.

`Listener functions'
     Listener is the sample position for a given context.  The
     multi-channel (usually stereo) output stream generated by the
     mixer is parametrized by this Listener object: its position and
     velocity relative to Sources, within occluder and reflector
     geometry.

    `void alListenerf( ALenum pname, ALfloat param )'
          Set the parameter using a float argument for the listener of
          the current context for the token specified by pname.

          If pname specifies an attribute not of type `ALfloat', a
          conversion is first performed.  If pname does not specify a
          valid listener attribute, `AL_INVALID_VALUE' is set and no
          further operation is commited.

    `void alListenerfv( ALenum pname, ALfloat *param )'
          Set the parameter using a float vector for the listener of
          the current context for the token specified by pname.

          If pname specifies an attribute not of type `ALfloat', a
          conversion is first performed.  If pname does not specify a
          valid listener attribute, `AL_INVALID_VALUE' is set and no
          further operation is commited.

    `void alGetListeneriv( ALenum pname,  ALint *value )'
          Get the parameter using an integer vector for the listener of
          the current context for the token specified by pname.

          If pname specifies an attribute not of type `ALint', a
          conversion is first performed.  If pname does not specify a
          valid listener attribute, `AL_INVALID_VALUE' is set and no
          further operation is commited.

    `void alGetListenerfv( ALenum pname, ALfloat *values )'
          Get the parameter using an float vector for the listener of
          the current context for the token specified by pname.

          If pname specifies an attribute not of type `ALint', a
          conversion is first performed.  If pname does not specify a
          valid listener attribute, `AL_INVALID_VALUE' is set and no
          further operation is commited.

`Source functions'
     Source objects are by default localized. Sources take the PCM data
     provided in the specified Buffer, apply Source-specific
     modifications, and then submit them to be mixed according to
     spatial arrangement etc.

    `void alGenSources( ALsizei n, ALuint* sources )'
          Create n source object names, and populate sources[0..n-1]
          with these names.  If n == 0, a legal NOP occurs.  If n < 0,
          `AL_INVALID_VALUE' is set and `alGenSources' returns, taking
          no further action.  If resources are not currently available
          sufficient to cover the request, `AL_OUT_OF_MEMORY' is set.
          No partial allocation occurs.

    `void alDeleteSources( ALsizei n, ALuint* sources )'
          Delete n source object names, named in sources[0..n-1].

          If n == 0, a legal NOP occurs.  If n < 0, `AL_INVALID_VALUE'
          is set and `alGenSources' returns, taking no further action.
          If any member of sources[0..n-1] is not a currently valid
          source name, `AL_INVALID_NAME' is set and no deletion occurs.
          If any member of sources[0..n-1] names a source that has a
          state other than `AL_INITIAL' or `AL_STOPPED',
          `AL_ILLEGAL_COMMAND' is set and no deletion occurs.

    `ALboolean alIsSource( ALuint sid )'
          Returns `AL_TRUE' if sid is a valid source name, `AL_FALSE'
          otherwise.

    `void alSourcei( ALuint sid, ALenum param, ALint value )'
          Set an parameter using an integer argument for a source
          object.

          If pname specifies an attribute not of type `ALint', a
          conversion is first performed.  If pname does not specify a
          valid source attribute, `AL_ILLEGAL_ENUM' is set and no
          operation is commited.  If value does not specify a valid
          value for the attribute, `AL_INVALID_VALUE' is set an no
          operation is commited.

    `void alSourcef( ALuint sid, ALenum param, ALfloat value )'
          Set an parameter using a float argument for a source object.

          If pname specifies an attribute not of type `ALfloat', a
          conversion is first performed.  If pname does not specify a
          valid source attribute, `AL_ILLEGAL_ENUM' is set and no
          operation is commited.  If value does not specify a valid
          value for the attribute, `AL_INVALID_VALUE' is set an no
          operation is commited.

    `void alSourcefv( ALuint sid, ALenum param, ALfloat* values )'
          Get a parameter using a float vector from a source object.
          If values is `NULL', a legal NOP occurs.

          If pname specifies an attribute not of type `ALfloat', a
          conversion is first performed.  If pname does not specify a
          valid source attribute, `AL_ILLEGAL_ENUM' is set and no
          further operation is commited.  If value does not specify a
          valid value for the attribute, `AL_INVALID_VALUE' is set an
          no operation is commited.

    `void alGetSourceiv( ALuint sid,  ALenum pname, ALint* value )'
          Get a parameter using an integer vector from a source object.
          If values is `NULL', a legal NOP occurs.

          If pname specifies an attribute not of type `ALfloat', a
          conversion is first performed.  If pname does not specify a
          valid source attribute, `AL_ILLEGAL_ENUM' is set and no
          further operation is commited.

    `void alGetSourcefv( ALuint sid, ALenum pname, ALfloat* values )'
          Get a parameter using a float vector from a source object.
          If values is `NULL', a legal NOP occurs.

          If pname specifies an attribute not of type `ALfloat', a
          conversion is first performed.  If pname does not specify a
          valid source attribute, `AL_ILLEGAL_ENUM' is set and no
          further operation is commited.

    `void alSourcePlay( ALuint sid )'
          Activate a source, start replay.  If sid is not a valid
          source name, `AL_INVALID_NAME' is set and no action occurs.
          If the source specified by sid is in the state `AL_PLAYING',
          this call is a legal NOP.

    `void alSourceStop( ALuint sid )'
          Change a source's state from `AL_PLAYING' to `AL_STOPPED'.  If
          sid is not a valid source name, `AL_INVALID_NAME' is set and
          no action occurs.  If the source is not in the state
          `AL_PLAYING', this call is a legal NOP.

    `void alSourcePause( ALuint sid )'
          Change a source's state from `AL_PLAYING' to `AL_PAUSED'.  If
          sid is not a valid source name, `AL_INVALID_NAME' is set and
          no action occurs.  If the source is not in the state
          `AL_PLAYING', this call is a legal NOP.

    `void alSourceRewind( ALuint sid )'
          Change a source's state to `AL_INITIAL'.  Sources which have
          the state `AL_PLAYING' or `AL_PAUSED' will be taken to
          `AL_STOPPED' first.  The source's position in its associated
          buffer will be set to 0.  If sid is not a valid source name,
          `AL_INVALID_NAME' is set and no action occurs.

    `void alSourcePlayv( ALuint ns, ALuint *ids )'
          Perform alSourcePlay on ids[0..ns-1].

          If any member of ids[0..ns-1] is not a valid source,
          `AL_INVALID_NAME' is set and no action takes place.  If ns ==
          0, a legal NOP occurs.  If ns < 0, `AL_INVALID_VALUE' is set
          and `alSourcePlayv' returns, taking no action.

    `void alSourceStopv( ALuint ns, ALuint *ids )'
          Perform alSourceStop on ids[0..ns-1].

          If any member of ids[0..ns-1] is not a valid source,
          `AL_INVALID_NAME' is set and no action takes place.  If ns ==
          0, a legal NOP occurs.  If ns < 0, `AL_INVALID_VALUE' is set
          and `alSourcePlayv' returns, taking no action.

    `void alSourcePausev( ALuint ns, ALuint *ids )'
          Perform alSourcePause on ids[0..ns-1].

          If any member of ids[0..ns-1] is not a valid source,
          `AL_INVALID_NAME' is set and no action takes place.  If ns ==
          0, a legal NOP occurs.  If ns < 0, `AL_INVALID_VALUE' is set
          and `alSourcePlayv' returns, taking no action.

    `void alSourceRewindv( ALuint ns, ALuint *ids )'
          Perform alSourceRewind on ids[0..ns-1].

          If any member of ids[0..ns-1] is not a valid source,
          `AL_INVALID_NAME' is set and no action takes place.  If ns ==
          0, a legal NOP occurs.  If ns < 0, `AL_INVALID_VALUE' is set
          and `alSourcePlayv' returns, taking no action.

`Buffers'
     Buffer objects are storage space for sample data.  Buffers are
     referred to by Sources. There can be more than one Source using
     the same Buffer data. If Buffers have to be duplicated on a
     per-Source basis, the driver has to take care of allocation,
     copying, and deallocation as well as propagating buffer data
     changes.

    `void alGenBuffers( ALsizei n, ALuint *samples )'
          Create n buffer object names, and populate samples with these
          names.  If n == 0, a legal NOP occurs.  If n < 0,
          `AL_INVALID_VALUE' is set and `alGenBuffers' returns, taking
          no further action.  If resources are not currently available
          sufficient to cover the request, `AL_OUT_OF_MEMORY' is set.
          No partial allocation occurs.

    `void alDeleteBuffers( ALsizei n, ALuint *samples )'
          Delete n buffer object names, named in samples[0 - n-1].  If
          n == 0, a legal NOP occurs.  If n < 0, `AL_INVALID_VALUE' is
          set and `alGenBuffers' returns, taking no further action.  If
          any member of samples[0..n-1] is not a currently valid buffer
          name, `AL_INVALID_NAME' is set and no deletion occurs.

          If any member of samples[0..n-1] is associated with a
          currently playing or paused source, the buffer in question is
          flagged and deletion occurs when all sources the buffer is
          associated with move to `AL_STOPPED'.  This is a deviation
          from the canonical spec and this feature should not be relied
          upon to deliver the same results in the future.

    `ALboolean alIsBuffer( ALuint buffer )'
          Returns `AL_TRUE' if bid is a valid buffer name, `AL_FALSE'
          otherwise.

    `void alBufferData( ALuint id, ALenum format, ALvoid *data, ALsizei size, ALsizei freq )'
          Specify the data to be filled into the buffer associated with
          id.

    `ALsizei alBufferAppendData( ALuint buffer, ALenum format, ALvoid *data, ALsizei size, ALsizei freq )'
          Specify data to be filled into a looping buffer.  This takes
          the current position at the time of the call, and returns the
          number of samples written.

    `void alGetBufferi( ALuint buffer, ALenum param, ALint *value )'
          Query Buffer integer attribute.

    `void alGetBufferf( ALuint buffer, ALenum param, ALfloat* value )'
          Query Buffer float attribute.

`Extension Support'
     Extension support.

    `ALboolean alIsExtensionPresent( const ALubyte* fname )'
          Obtain the address of a function (usually an extension) with
          the name fname. All addresses are context-independent.

    `void *alGetProcAddress( const ALubyte* fname )'
          Obtain the address of a function (usually an extension) with
          the name fname. All addresses are context-independent.

    `ALenum alGetEnumValue( const ALubyte* ename )'
          Obtain the integer value of an enumeration (usually an
          extension) with the name ename.

`Misc'
     Misc functions that don't act directly upon an object and don't fit
     well anywhere else.

     OpenAL Maintenance Functions State Management and Query.

    `void alEnable( ALenum capability )'
          Renderer State management.

    `void alDisable( ALenum capability )'
          Renderer State management.

    `ALboolean alIsEnabled( ALenum capability )'
          Returns `AL_TRUE' if capability is enabled, `AL_FALSE'
          otherwise.

    `void alHint( ALenum target, ALenum mode )'
          Application preferences for driver performance choices.

    `void alGetBooleanv( ALenum param, ALboolean* data )'
          State retrieval.

    `void alGetIntegerv( ALenum param, ALint* data )'
          State retrieval.

    `void alGetFloatv( ALenum param, ALfloat* data )'
          State retrieval.

    `void alGetDoublev( ALenum param, ALdouble* data )'
          State retrieval.

    `const ALubyte *alGetString( ALenum param )'
          Returns a const ALubyte *, NUL terminated string
          representation of param.  If param is not a valid enum,
          `AL_ILLEGAL_ENUM' is set.


File: openal.info,  Node: alc,  Next: alut,  Prev: al,  Up: API

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.


File: openal.info,  Node: alut,  Next: alkludge,  Prev: alc,  Up: API

OpenAL utility functions
========================

   Description of OpenAL utility functions goes here.


File: openal.info,  Node: alkludge,  Next: Errors,  Prev: alut,  Up: API

OpenAL kludgey functions
========================

   `alkludge.h' is a repository for stuff that need to either be
discarded, rewritten, or thought out.  You should not rely on functions
in `alkludge.h', although it is unlikely that functions will be removed
from it without some form of equivalent functionality being introduced
in the regular library.


File: openal.info,  Node: Errors,  Prev: alkludge,  Up: API

   There are two types of errors in OpenAL: `alc' errors and `al'
errors.  `al' errors are context specific and one deep.  Only the first
occurring error will be recorded, subsequent errors will not be
recorded.  Errors may be retrieved via the `alGetError' call, after
which the error in the current context will be set to `AL_NO_ERROR',
and subsequent errors will again alter the context's error state.

   `alc' errors are not context specific, and may be retrieved via the
`alcGetError' call.  After a call to `alcGetError', the context-global
error variable is set to `ALC_NO_ERROR'.


File: openal.info,  Node: Loki Implementation,  Next: Example,  Prev: API,  Up: Top

Loki's high-quality implementation of the OpenAL API
****************************************************

   While we may be a bit biased, we are partial to the Loki OpenAL
implementation.  Loki's implementation is currently an all-software
library with support for multiple filters, configuration, and extension
support via plugins.

* Menu:


* Installation::                    How do compile and install.
* Filters::                         What effects are available?
* Configuration::                   How can I configure the library?
* Extensions::                      How can I use extensions?


File: openal.info,  Node: Installation,  Next: Filters,  Prev: Loki Implementation,  Up: Loki Implementation

   If you retrieve the library via cvs, be sure to run the autogen.sh
script provided.  It will build configure and config.h.in.

   After that, run configure with the options you want.  Run configure
-help for available options.


File: openal.info,  Node: Filters,  Next: Configuration,  Prev: Installation,  Up: Loki Implementation

Loki Openal Filters
*******************


File: openal.info,  Node: Configuration,  Next: Extensions,  Prev: Filters,  Up: Loki Implementation

The openal configuration file
*****************************

   Users can give openal hints as to optimal defaults for various
parameters via the openal configuration file.  The openal configuration
file should be placed in either `/etc' or in one's home directory,
being named `openalrc' in the first location or `.openalrc' in the
second location.

   The configuration language is meant to be lisp-like.  This does not
mean that it supports lisp constructs, only that it looks something like
lisp.  This hideous language is referred to within the openal sources as
`ALRC' (for openAL Resource Configuration language).

* Menu:

* Primitives::                      ALRC primitive functions.
* Variables::                       What you can define or set.
* Types::                           Sort of stuff you define or set.
* Evaluation::                      Don't try this at home.


File: openal.info,  Node: Primitives,  Next: Variables,  Up: Configuration

   `ALRC' supports a very small number of primitives required to give
the user a very small amount of control over OpenAL.  Generally, the
user can specific default values for things like listener position,
source parameters, etc.

   Primitives are responsible for evaluation their own arguments, unlike
expressions or functions.  Therefore, an argument passed to a primitive
may never be evaluated.

   The primitives are:

`and'
          ( and predicate-1 predicate-2 ... )

     Performs a logical `and' on parameters, using short circuit
     evaluation.  Evaluates to true if none of the parameters evaluate
     to false.

`or'
          ( or predicate-1 predicate-2 ... )

     Performs a logical `or' on parameters, stopping at the first true
     evaluation.  Evaluates to true if any of the parameters evaluate to
     true.

`define'
          (define identifier value)

     `define' evaluates `value', and if `identifier' is not already in
     the symbol table, creates a new symbol named `identifier' with the
     evaluated `value'.  If `identifier' is already defined, define
     sets it to the the evaluated `value'.

`load-extension'
          ( load-extension "/absolute/pathname/plugin.so" )

     `load-extension' informs openal of the presence of a plugin which
     conforms to the extension format described in *Note Making your
     own::.


File: openal.info,  Node: Variables,  Next: Types,  Prev: Primitives,  Up: Configuration

   By setting certain `variables', a user can change the behavior of
OpenAL without resorting to wholesale recompilations.  Loki's OpenAL
implementation respects on certain variables and checks for them.
Usually, the values are used to set default values (such as the default
gain for a source (usually 1.0).

* Menu:

* Source variables::                      Variables that affect sources
* Context variables::                     Variables that affect contexts
* Listener variables::                    Variables that affect listeners


File: openal.info,  Node: Source variables,  Next: Context variables,  Prev: Variables,  Up: Variables

   There are some, but I haven't listed them here.


File: openal.info,  Node: Context variables,  Next: Listener variables,  Prev: Source variables,  Up: Variables

`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               Standard OSS (/dev/dsp) backend    
                          on linux.                          
     sdl                  Simple DirectMedia Layer backend.  
     arts                 aRTs backend                       
     esd                  esound daemon backend.             
     alsa                 ALSA backend.                      
     waveout              WAVE file output.                  



     ...please note that this does not mean that the backends work
     without fail, but that support either is included or is planned.

     A typical invocation look like:

          ( define devices '(sdl native) )

     ...which indicates to OpenAL that it should try to render audio to
     the SDL backend (if available), and failing that to try the native
     audio method for the platform in question, which usually means
     using the OSS drivers and `/dev/dsp'.  If each device specified in
     `devices' fails, then the default behavior (`native') is tried.
     If that fails, OpenAL will return a `NULL' context.


File: openal.info,  Node: Listener variables,  Prev: Context variables,  Up: Variables


File: openal.info,  Node: Types,  Next: Evaluation,  Prev: Variables,  Up: Configuration

   Symbol values have associated type information.  Users should be
acquainted with the following types in ALRC:

   * ALRC_INVALID

     This is the type of a value that is either false or for some reason
     invalid.  No evaluation or assignment should be attempted with this
     type.

   * ALRC_LIST

     This type contains other types.  If not quoted, it is evaluated as
     an expression with the first item specifying the function name,
     which is probably not what you want.

          '( 0.0 0.0 0.0 )          ; list which is not an expression
          ( define blah 'blah ) 	; list which is an expression

   * ALRC_SYMBOL

     Things which, when evaluated, are not themselves.

   * ALRC_INTEGER

     Integer numbers.

   * ALRC_FLOAT

     Floating point numbers.

   * ALRC_STRING

     A series of characters enclosed by '"'.


File: openal.info,  Node: Evaluation,  Prev: Types,  Up: Configuration


File: openal.info,  Node: Extensions,  Prev: Configuration,  Up: Loki Implementation

How to extend Loki's OpenAL
***************************

   Loki's OpenAL implementation include some functions which are
specific to the implementation.  These functions all have the suffix
`_LOKI' to distinguish them.

   In order to use these extensions, the application will need to query
their existence via `IsExtensionPresent', and then use `GetProcAddress'
to resolve the address of the extension.  The result of
`GetProcAddress' will need to be cast to the appropriate function type.

* Menu:

* Loki specific tokens::
* Built in::
* Making your own::


File: openal.info,  Node: Loki specific tokens,  Next: Built in,  Up: Extensions

     Some of the Loki specific functionality is expressed in terms of
     Loki specific enumerate tokens passed to otherwise standard calls.

`AL_FORMAT_WAVE_EXT'
     `AL_FORMAT_WAVE_EXT' is used in calls accepting format arguments.
     It specifies that the data parameter used in the call is an entire
     wave file, including header, and that the call should set the
     frequency, bit depth, and channel information using the header in
     the file itself.

`AL_BYTE_LOKI'
     `AL_BYTE_LOKI' is used as a getter to `alGetSourcei', and reports
     a source's position, in bytes, into the buffer, or -1 in the case
     of a non playing source.  There are no guarentees about the
     internal representation of data so the value returned using this
     token may not correspond with the equivilant offset in the user
     supplied data.

`AL_SOURCE_LOOPING_LOKI'
     `AL_SOURCE_LOOPING_LOKI' is used as a setter/getter to
     `al{Get}Sourcei', and sets/gets the infinite loop flag on a source.


File: openal.info,  Node: Built in,  Next: Making your own,  Prev: Loki specific tokens,  Up: Extensions

   Here's a list of extensions which are built into the Loki OpenAL
implementation.  The prefix is included in this section for clarify.

`void alAttenuationScale_LOKI(ALfloat param)'
     `alAttenuationScale_LOKI' scales the units of the simulation.
     Without a call to this function, it is very likely that your
     application will not sound correct.

     The default scaling factor in Loki's OpenAL is such that a listener
     placed at the origin will hear sounds attenuated until that point
     that the sounds are `ALMAXDISTANCE' units away.  `ALMAXDISTANCE' is
     an arbitrary constant defined when including `AL/alkludge.h'.

     It is almost assured that the default scaling factor will be
     incorrect for most applications.  That is why this call is so
     important.  Usage will generally follow:

                  /* create context, load data, and define some value radius
                   * to be the radius of your world simulation.
                   */
          
                  setScale = (void (*)(ALfloat ))
                                  alGetProcAddress("alAttenuationScale_LOKI");
                  if(setScale != NULL) {
                          setScale(radius / ALMAXDISTANCE);
                  }

     It is highly recommended you explicitly use this function, and do
     not assume that the default units will be useful to you.

`ALfloat alcGetAudioChannel_LOKI(ALuint channel)'
     `alcGetAudioChannel_LOKI' takes in a channel enumeration from the
     set `AL_CHAN_MAIN_LOKI', `AL_CHAN_PCM_LOKI', and
     `AL_CHAN_CD_LOKI', and returns a normalized ALfloat, corresponding
     to the volume associated with the channel on whatever backend the
     library is using.

`void alcSetAudioChannel_LOKI(ALuint channel, ALfloat volume)'
     `alcSetAudioChannel_LOKI' takes a channel specification from the
     set `AL_CHAN_MAIN_LOKI', `AL_CHAN_PCM_LOKI', and `AL_CHAN_CD_LOKI'
     and a normalized volume, and sets the hardware channel associated
     with the channel argument to the volume (the volume mapped to the
     settings appropriate for the backend, that is).

`void alMute_LOKI(ALvoid)'
     `alMute_LOKI' returns nothing and takes no argument.  After a call
     to `alMute_LOKI', the implementation ceased all audio output, while
     still updating state (so sources still play, you just can't hear
     them).  The audio setting is preserved so that a subsequent call to
     `alUnMute_LOKI' will restore the volume to its value prior to the
     `alMute_LOKI' call.

     This isn't really useful, as you can do the same with by just
     querying and setting the listener gain.

`void alUnMute_LOKI(ALvoid)'
     `alUnMute_LOKI' performs the inverse operation of `alMute_LOKI'.
     alUnMute_LOKI restores the volume of the simulation to that which
     is was before calling `alMute_LOKI'.

`void alReverbScale_LOKI(ALuint sid, ALfloat param)'
     `alReverbScale_LOKI' allows you to set a normalized value param,
     which represents the gain that is used when reverberating.  Don't
     use it.  It will be removed as soon as the IASIG extension is
     completed.

`void alReverbDelay_LOKI(ALuint sid, ALfloat param)'
     `alReverbScale_LOKI' allows you to set the delay associated with a
     reverberating source.  Don't use this.  It will be removed as soon
     as the IASIG extension is completed.

`ALboolean alBufferPitchHack_LOKI(ALuint bid, ALfloat pitch)'
     Don't use this.  You don't want it.

`void alBombOnError_LOKI(void)'
     `alBombOnError_LOKI', when called, will cause the implementation to
     abort on error, instead of just setting the per-context error and
     continuing.  This is useful only for debugging.  alc errors are not
     handled.

`void alBufferi_LOKI( ALuint bid, ALenum param, ALint value )'
     `alBufferi_LOKI' can be used to set a buffer's attributes.  Not
     recommended unless you know what you're doing.  Usually, you can
     use this to enable a "multichannel" buffer.

`void alBufferDataWithCallback_LOKI( ALuint bid, ALint (*callback)(ALuint sid, ALuint bid, ALshort *data, ALenum format, ALuint samples))'
     `alBufferDataWithCallback_LOKI' can be used to specify that the
     buffer `bid' should, instead of using a static chunk of data
     specified by `alBufferData', call the callback `callback' to fill
     a chunk of data as needed.

     The parameters for `callback' are as such:

          	`ALuint sid'
          	The source id that this request is associated with.  Since many
          	sources may share the same buffer, this sid allows the application
          	to keep track of offsets and other state associated with each
          	source instance.
          
          	`ALuint bid'
          	The buffer id that the callback is associated with.
          
          	`ALshort *data'
          	The memory area that the callback should populate
          
          	`ALenum format'
          	The format the the output data should be in.
          
          	`ALuint samples'
          	The number of *samples* required.


File: openal.info,  Node: Making your own,  Prev: Built in,  Up: Extensions

   It is possible to extend the functionality of Loki's implementation
of OpenAL via plugins (combined with some configuration mojo).

   "Plugins" are actually just shared libraries which contain, as an
available symbol, a table which contains function name/address pairs.
Code necessary for library initialization and exit should be placed in
_init, _fini as described in dlopen(3).

   The table containing the function name/address pairs should
correspond to the following format:

     struct {
             ALubyte *name;
             void *addr;
     } alExtension_03282000 [] = {
         { "alutLoadGIF", (void *) alutLoadGIF },
         { NULL, NULL }
     };

   Right now, the end `{ NULL, NULL }' pair is needed, and the table
needs to be named `alExtension_03282000'.  This format is likely to
change in the future, in order to avoid a badly written plugin from
crashing each application linked against openal.

   In order to take advantage of the extension, openal will have to be
informed of its location via the configuration file *Note
Configuration::.

   To avoid potential compatibility problems with initialization code,
Loki's OpenAL implementation checks for the presence of the functions
`alExtInit_03282000' and `alExtFini_03282000'.  These functions are
executed at dlopen and dlclose time, respectively.

* Menu:

* Includes and typedefs::
* Basics::
* Getting symbol information::
* Adding Filters::


File: openal.info,  Node: Includes and typedefs,  Next: Basics,  Up: Making your own

Includes and typedefs
=====================


File: openal.info,  Node: Basics,  Next: Getting symbol information,  Prev: Includes and typedefs,  Up: Making your own

Basics
======


File: openal.info,  Node: Getting symbol information,  Next: Adding Filters,  Prev: Basics,  Up: Making your own

Getting Symbol Information
==========================


File: openal.info,  Node: Adding Filters,  Prev: Getting symbol information,  Up: Making your own

Adding Filters
==============


File: openal.info,  Node: Example,  Prev: Loki Implementation,  Up: Top

OpenAL examples
***************

   Here are some examples.

* Menu:

* Trivial::                         A trivial example
* Error Handling::                  Some basic error handling
* Context Management::              Context management
* Panning::                         An example of left/right panning
* Positional::                      Positional attenuation example
* Doppler::                         How to use velocity
* Streaming::                       How to use streaming sound
* Reverb::                          How to use reverb


File: openal.info,  Node: Trivial,  Next: Error Handling,  Up: Example

Trivial Example
===============


     #include <AL/al.h>
     #include <AL/alc.h>
     #include <AL/alext.h>
     #include <AL/alkludge.h>
     #include <AL/alut.h>
     
     #include <time.h>
     #include <stdio.h>
     #include <stdlib.h>
     #include <sys/time.h>
     #include <sys/types.h>
     #include <unistd.h>
     #include <sys/stat.h>
     
     #define FILE "sample.wav"
     
     static void init(void);
     
     static ALuint moving_source = 0;
     
     static time_t start;
     static void *data = (void *) 0xDEADBEEF;
     
     static void *context_id;
     
     static void init( void ) {
             FILE *fh;
             ALfloat zeroes[] = { 0.0f, 0.0f,  0.0f };
             ALfloat back[]   = { 0.0f, 0.0f, -1.0f, 0.0f, 1.0f, 0.0f };
             ALfloat front[]  = { 0.0f, 0.0f,  1.0f, 0.0f, 1.0f, 0.0f };
             ALuint stereo;
             ALsizei size;
             ALsizei bits;
             ALsizei freq;
             ALsizei format;
             int filelen;
     	struct stat buf;
     
     	if( stat( FILE, &buf ) < 0 ) {
     		/* file does not exist */
                     fprintf( stderr, "Couldn't access %s\n", FILE );
     		exit(1);
     	}
     
             fh = fopen("sample.wav", "rb");
             if(fh == NULL) {
                     fprintf( stderr, "Couldn't open %s\n", FILE );
                     exit(1);
             }
     
     	filelen = buf.st_size;
     
             data = malloc( filelen );
     
             alListenerfv( AL_POSITION, zeroes );
             alListenerfv( AL_ORIENTATION, front );
     
             alGenBuffers( 1, &stereo);
     
             if( fread( data, filelen, 1, fh) != 1 ) {
     		fprintf( stderr, "Couldn't read %s\n", FILE );
     
     		free( data );
     
     		exit(1);
     	}
     
             fclose( fh );
     
             alBufferData( stereo, data, AL_FORMAT_WAVE_EXT, filelen, 0 );
     
     	free( data );
     
             alGenSources(1, &moving_source);
     
             alSource3f( moving_source, AL_POSITION, 0.0, 0.0, 4.0 );
             alSourcefv( moving_source, AL_VELOCITY, zeroes );
             alSourcei(  moving_source, AL_BUFFER, stereo );
             alSourcei(  moving_source, AL_LOOPING, AL_FALSE);
     
             return;
     }
     
     int main( int argc, char* argv[] ) {
     	ALCdevice *dev;
             int attrlist[] = { ALC_FREQUENCY, 22050,
                                 ALC_INVALID };
             time_t shouldend;
             ALint state = AL_INITIAL;
     
     	/* open device */
     	dev = alcOpenDevice( NULL );
     	if( dev == NULL ) {
     		return 1;
     	}
     
             /* create context. */
             context_id = alcCreateContext( dev, attrlist );
             if( context_id == NULL ) {
     		alcCloseDevice( dev );
     
                     return 1;
             }
     
     	alcMakeContextCurrent( context_id );
     
             /*
              * Setup LOKI extensions
              */
             fixup_function_pointers();
     
             init( );
     
             alSourcePlay( moving_source );
             do {
             	/* sleep for a bit */
             	micro_sleep( 500000 );
     
                     shouldend = time(NULL);
                     if((shouldend - start) > 10) {
                             /* After 10 seconds, we end */
                             alSourceStop( moving_source );
                     }
     
                     alSourcei( moving_source, AL_SOURCE_STATE, &state );
             } while(state != AL_STOPPED);
     
             cleanup();
     
             alcDestroyContext( context_id );
     	alcCloseDevice( dev );
     
             return 0;
     }


File: openal.info,  Node: Error Handling,  Next: Context Management,  Prev: Trivial,  Up: Example

Error Handling
==============

   Error Handling goes here.


File: openal.info,  Node: Context Management,  Next: Panning,  Prev: Error Handling,  Up: Example

Context Management
==================

   Context Management goes here.


File: openal.info,  Node: Panning,  Next: Positional,  Prev: Context Management,  Up: Example

Panning
=======

   Panning example goes here.


File: openal.info,  Node: Positional,  Next: Doppler,  Prev: Panning,  Up: Example

Positional
==========

   Positional example goes here.


File: openal.info,  Node: Doppler,  Next: Streaming,  Prev: Positional,  Up: Example

Doppler
=======

   Doppler example goes here.


File: openal.info,  Node: Reverb,  Prev: Streaming,  Up: Example

Reverb
======

     #include <AL/al.h>
     #include <AL/alc.h>
     #include <AL/alkludge.h>
     #include <AL/alut.h>
     
     #include <time.h>
     #include <stdio.h>
     #include <unistd.h>
     
     static void init( void );
     
     static ALuint reverb_sid = 0;
     
     static void *wave = NULL;
     
     static void init( void ) {
     	ALfloat zeroes[] = { 0.0f, 0.0f,  0.0f };
     	ALfloat back[]   = { 0.0f, 0.0f, -1.0f, 0.0f, 1.0f, 0.0f };
     	ALfloat front[]  = { 0.0f, 0.0f,  1.0f, 0.0f, 1.0f, 0.0f };
     	ALuint boom;
     	ALsizei size;
     	ALsizei bits;
     	ALsizei freq;
     	ALsizei format;
     
     	alListenerfv(AL_POSITION, zeroes );
     	alListenerfv(AL_VELOCITY, zeroes );
     	alListenerfv(AL_ORIENTATION, front );
     
             alGenBuffers( 1, &boom );
     
     	alutLoadWAV( "l2.wav", &wave, &format, &size, &bits, &freq);
     
     	alBufferData( boom, format, wave, size, freq );
     	free(wave); /* openal makes a local copy of wave data */
     
     	alGenSources( 1, &reverb_sid);
     
     	alSource3f(reverb_sid, AL_POSITION, 2.0, 0.0, 4.0);
     	alSourcefv(reverb_sid, AL_VELOCITY, zeroes);
     	alSourcefv(reverb_sid, AL_ORIENTATION, back);
     	alSourcei (reverb_sid, AL_BUFFER, boom);
     
     	alReverbScale(reverb_sid, 0.6);
     	alReverbDelay(reverb_sid, 0.3);
     
     	alAttenuationScale(0.3);
     }
     
     int main(int argc, char *argv[]) {
     	alutInit( &argc, argv );
     
     	init( );
     
     	alSourcePlay(reverb_sid);
     	sleep(10);
     
     	alutExit();
     
     	return 0;
     }


File: openal.info,  Node: Streaming,  Next: Reverb,  Prev: Doppler,  Up: Example

Streaming
=========

   Support for streaming sounds rises from the API specification
surrounding `alBufferAppendData'.  Streaming sources are understood to
be sources whose `AL_BUFFER' parameter is a streaming buffer.  A
streaming buffer is a buffer created by a call to
`alGenStreamingBuffer', and can only be fed data using
`alBufferAppendData'.

   Streaming sources have restrictions associated with them, and for the
time being require special creation procedures.  Further specifications
may remove some of these restrictions, but until further notice
streaming sources will always be synchronized, and some of the filters
may not apply to them.

     insert code example


File: openal.info,  Node: Tutorial,  Up: Top

* Menu:

* Definitions::


File: openal.info,  Node: Definitions,  Up: Tutorial

   Foo!


File: openal.info,  Node: Function Index,  Next: Variable Index,  Up: Top

Function Index
**************

* Menu:

* alAttenuationScale_LOKI:               Built in.
* alBombOnError_LOKI:                    Built in.
* alBufferAppendData <1>:                al.
* alBufferAppendData:                    Streaming.
* alBufferData:                          al.
* alBufferDataWithCallback:              Built in.
* alBufferi_LOKI:                        Built in.
* alBufferPitchHack_LOKI:                Built in.
* alcCreateContext:                      alc.
* alcDestroyContext:                     alc.
* alcGetAudioChannel:                    Built in.
* alcGetError:                           alc.
* alcGetErrorString:                     alc.
* alcMakeContextCurrent:                 alc.
* alcOpenDevice:                         alc.
* alcPauseContext:                       alc.
* alcProcessContext:                     alc.
* alcSetAudioChannel:                    Built in.
* alDeleteBuffers:                       al.
* alDeleteSources:                       al.
* alDisable:                             al.
* alEnable:                              al.
* alGenBuffers:                          al.
* alGenSources:                          al.
* alGenStreamingBuffer:                  Streaming.
* alGetBooleanv:                         al.
* alGetBufferf:                          al.
* alGetBufferi:                          al.
* alGetDoublev:                          al.
* alGetEnumValue:                        al.
* alGetError:                            Errors.
* alGetFloatv:                           al.
* alGetIntegerv:                         al.
* alGetListenerfv:                       al.
* alGetListeneriv:                       al.
* alGetProcAddress <1>:                  al.
* alGetProcAddress:                      Extensions.
* alGetSourcefv:                         al.
* alGetSourcei:                          al.
* alGetString:                           al.
* alHint:                                al.
* alIsBuffer:                            al.
* alIsEnabled:                           al.
* alIsExtensionPresent <1>:              Extensions.
* alIsExtensionPresent:                  al.
* alIsSource:                            al.
* alListenerf:                           al.
* alListenerfv:                          al.
* alMute_LOKI:                           Built in.
* alReverbDelay_LOKI:                    Built in.
* alReverbScale_LOKI:                    Built in.
* alSourcef:                             al.
* alSourcefv:                            al.
* alSourcei:                             al.
* alSourcePause:                         al.
* alSourcePausev:                        al.
* alSourcePlay:                          al.
* alSourcePlayv:                         al.
* alSourceRewind:                        al.
* alSourceRewindv:                       al.
* alSourceStop:                          al.
* alSourceStopv:                         al.
* alUnMute_LOKI:                         Built in.


File: openal.info,  Node: Variable Index,  Next: Concept Index,  Prev: Function Index,  Up: Top

Variable Index
**************

* Menu:

* AL_BYTE_LOKI:                          Loki specific tokens.
* AL_FORMAT_WAVE_EXT:                    Loki specific tokens.
* AL_SOURCE_LOOPING_LOKI:                Loki specific tokens.
* ALC_BUFFERS:                           alc.
* ALC_BUFFERSIZE:                        alc.
* ALC_FREQUENCY:                         alc.
* ALC_SOURCES:                           alc.
* ALC_SYNC:                              alc.
* ALMAXDISTANCE:                         Built in.
* devices:                               alc.
* sampling-rate:                         alc.


File: openal.info,  Node: Concept Index,  Prev: Variable Index,  Up: Top

Concept Index
*************

* Menu:

* _LOKI:                                 Built in.
* ALRC:                                  Configuration.
* and:                                   Primitives.
* API:                                   API.
* Buffers:                               Basic Concepts.
* config file:                           Configuration.
* configuration file:                    Configuration.
* Context variables:                     Context variables.
* Contexts:                              Basic Concepts.
* define:                                Primitives.
* Devices:                               Basic Concepts.
* error:                                 Built in.
* Errors:                                Errors.
* extensions:                            Making your own.
* Extensions:                            Extensions.
* Installation:                          Installation.
* internal mixing rate:                  alc.
* Listener variables:                    Listener variables.
* load-extension:                        Primitives.
* or:                                    Primitives.
* plugins:                               Making your own.
* primitive:                             Primitives.
* Source variables:                      Source variables.
* Sources <1>:                           al.
* Sources:                               Basic Concepts.
* Streaming:                             Streaming.
* Streaming buffer:                      Streaming.
* Streaming source:                      Streaming.
* units:                                 Built in.
* world units:                           Built in.



Tag Table:
Node: Top214
Node: Introduction908
Node: FAQ1451
Node: How do I enable ESD?1732
Node: Why doesn't this POS work with my Vortex card?1951
Node: How can I set the size of my world?2493
Node: Goals2705
Node: API2846
Node: Basic Concepts3431
Node: types5518
Node: al6218
Node: alc19222
Node: alut24542
Node: alkludge24721
Node: Errors25153
Node: Loki Implementation25806
Node: Installation26499
Node: Filters26842
Node: Configuration26989
Node: Primitives27980
Node: Variables29428
Node: Source variables30059
Node: Context variables30217
Node: Listener variables31679
Node: Types31769
Node: Evaluation32713
Node: Extensions32787
Node: Loki specific tokens33437
Node: Built in34530
Node: Making your own39721
Node: Includes and typedefs41231
Node: Basics41364
Node: Getting symbol information41502
Node: Adding Filters41673
Node: Example41805
Node: Trivial42431
Node: Error Handling46228
Node: Context Management46390
Node: Panning46564
Node: Positional46709
Node: Doppler46852
Node: Reverb46988
Node: Streaming48653
Node: Tutorial49417
Node: Definitions49491
Node: Function Index49556
Node: Variable Index52617
Node: Concept Index53319

End Tag Table
