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.