-
Notifications
You must be signed in to change notification settings - Fork 513
Programmer's Guide
OpenAL is a cross-platform three-dimensional audio API. The API’s primary purpose is to allow an application to position audio sources in a three-dimensional space around a listener, producing reasonable spatialization of the sources for the audio system (headphones, 2.1 speaker output, 5.1 speaker output, etc.) Through extensions, Creative Labs has also enhanced OpenAL with EAX and other capabilities. OpenAL is appropriate for many audio applications, but was designed to be most appropriate for gaming audio.
This reference guide is most appropriate for a programmer. Experience with C or C++ is not required to learn the concepts in OpenAL, but will make understanding the OpenAL source as well as sample code easier. Since there are several sample applications included with the OpenAL SDKs as well as with the source distribution, it is recommended that interested programmers take advantage of those resources.
The two most important resources for additional information on OpenAL are the websites at www.openal.org and http://developer.creative.com. The main OpenAL site hosts the specification, the open source implementations, and sample code. The Creative developer site has a section dedicated to OpenAL with SDKs showing how to use OpenAL as well as various extensions.
Use of OpenAL revolves around the use of three fundamental objects – Buffers, Sources, and a Listener. A buffer can be filled with audio data, and can then be attached to a source. The source can then be positioned and played. How the source is heard is determined by its position and orientation relative to the Listener object (there is only one Listener). Creating a number of sources and buffers and a single listener and then updating the positions and orientations of the sources and listener dynamically can present a convincing 3D audio world.
Here is a diagram showing the fundamental OpenAL objects and their relationships to the context and device objects:
When initializing OpenAL, at least one device has to be opened. Within that device, at least one context will be created. Within that context, one listener object is implied, and a multitude of source objects can be created. Each source can have one or more buffers objects attached to it. Buffer objects are not part of a specific context – they are shared among all contexts on one device.
The function call to open a device, alcOpenDevice, takes a
string as input. The string should contain either the name of a valid OpenAL
rendering device, or NULL
to request the default device.
On PC Systems, a number of different OpenAL renderering devices may co-exist. For example a “native” renderer specific to the user’s high-end soundcard, and a host-based software fallback renderer. On platforms where multiple renderers can be present, an OpenAL application may require the ability to identify the different devices available, in order to give the end-user a choice of device. OpenAL’s Enumeration extension makes this possible.
The Enumeration extension allows the programmer to retrieve a string listing the
names of available devices. It can also provide the name of the default device.
Use alcGetString with the device property set to NULL
, and
the enum property set to ALC_DEVICE_SPECIFIER
to get the list of available
devices. To get the default device name, pass in NULL
and
ALC_DEFAULT_DEVICE_SPECIFIER
.
The Enumeration extension also works with capture devices – the equivalent
values are ALC_CAPTURE_DEVICE_SPECIFIER
and
ALC_CAPTURE_DEFAULT_DEVICE_SPECIFIER
.
The programmer can find out more about the capabilities of each device by querying to see which extensions it supports using alcIsExtensionPresent and alIsExtensionPresent.
As described above, the first step to initializing OpenAL is to open a device. Once that is successfully done, then a context is opened on that device. Now the fundamental OpenAL objects can be managed – the listener, various sources, and various buffers.
To generate a set of buffers for use, use alGetError to reset the error state, call alGenBuffers to generate the number of buffers desired, and then use alGetError again to detect if an error was generated.
Fill the buffers with PCM data using alBufferData.
To generate a set of sources for use, use alGetError to reset the error state, call alGenSources to generate the number of sources desired, and then use alGetError again to detect if an error was generated.
Buffers are attached to sources using alSourcei.
Once a buffer has been attached to a source, the source can play the buffer using alSourcePlay.
Source and Listener properties can be updated dynamically using property set and get calls such as alGetListenerfv, alListener3f, alSourcei, and alGetSource3f.
Example:
// Initialization
Device = alcOpenDevice(NULL); // select the "preferred device"
if (Device) {
Context=alcCreateContext(Device,NULL);
alcMakeContextCurrent(Context);
}
// Check for EAX 2.0 support
g_bEAX = alIsExtensionPresent("EAX2.0");
// Generate Buffers
alGetError(); // clear error code
alGenBuffers(NUM_BUFFERS, g_Buffers);
if ((error = alGetError()) != AL_NO_ERROR)
{
DisplayALError("alGenBuffers :", error);
return;
}
/ Load test.wav
loadWAVFile("test.wav",&format,&data,&size,&freq,&loop);
if ((error = alGetError()) != AL_NO_ERROR)
{
DisplayALError("alutLoadWAVFile test.wav : ", error);
alDeleteBuffers(NUM_BUFFERS, g_Buffers);
return;
}
// Copy test.wav data into AL Buffer 0
alBufferData(g_Buffers[0],format,data,size,freq);
if ((error = alGetError()) != AL_NO_ERROR)
{
DisplayALError("alBufferData buffer 0 : ", error);
alDeleteBuffers(NUM_BUFFERS, g_Buffers);
return;
}
// Unload test.wav
unloadWAV(format,data,size,freq);
if ((error = alGetError()) != AL_NO_ERROR)
{
DisplayALError("alutUnloadWAV : ", error);
alDeleteBuffers(NUM_BUFFERS, g_Buffers);
return;
}
// Generate Sources
alGenSources(1,source);
if ((error = alGetError()) != AL_NO_ERROR)
{
DisplayALError("alGenSources 1 : ", error);
return;
}
// Attach buffer 0 to source
alSourcei(source[0], AL_BUFFER, g_Buffers[0]);
if ((error = alGetError()) != AL_NO_ERROR)
{
DisplayALError("alSourcei AL_BUFFER 0 : ", error);
}
// Exit
Context=alcGetCurrentContext();
Device=alcGetContextsDevice(Context);
alcMakeContextCurrent(NULL);
alcDestroyContext(Context);
alcCloseDevice(Device);
For every context, there is automatically one Listener object. The
alListener[f, 3f, fv, i]
and alGetListener[f, 3f, fv, i]
families of
functions can be used to set or retrieve the following listener properties:
Property | Data Type | Description |
---|---|---|
AL_GAIN |
f , fv
|
Master gain. Value should be positive |
AL_POSITION |
fv , 3f , iv , 3i
|
X, Y, Z position |
AL_VELOCITY |
fv , 3f , iv , 3i
|
Velocity vector |
AL_ORIENTATION |
fv , iv
|
Orientation expressed as “at” and “up” vectors |
Example:
ALfloat listenerPos[]={0.0,0.0,0.0};
ALfloat listenerVel[]={0.0,0.0,0.0};
ALfloat listenerOri[]={0.0,0.0,-1.0, 0.0,1.0,0.0};
// Position ...
alListenerfv(AL_POSITION,listenerPos);
if ((error = alGetError()) != AL_NO_ERROR)
{
DisplayALError("alListenerfv POSITION : ", error);
return;
}
// Velocity ...
alListenerfv(AL_VELOCITY,listenerVel);
if ((error = alGetError()) != AL_NO_ERROR)
{
DisplayALError("alListenerfv VELOCITY : ", error);
return;
}
// Orientation ...
alListenerfv(AL_ORIENTATION,listenerOri);
if ((error = alGetError()) != AL_NO_ERROR)
{
DisplayALError("alListenerfv ORIENTATION : ", error);
return;
}
Each buffer generated by alGenBuffers has properties which can
be retrieved. The alGetBuffer[f, i]
functions can be used to retrieve the
following buffer properties:
Property | Data Type | Description |
---|---|---|
AL_FREQUENCY |
i , iv
|
Frequency of buffer in Hz |
AL_BITS |
i , iv
|
Bit depth of buffer |
AL_CHANNELS |
i , iv
|
Number of channels in buffer. > 1 is valid, but buffer won’t be positioned when played |
AL_SIZE |
i , iv
|
Size of buffer in bytes |
AL_DATA |
i , iv
|
Original location where data was copied from generally useless, as was probably freed after buffer creation |
Example:
// Retrieve Buffer Frequency
alBufferi(g_Buffers[0], AL_FREQUENCY, iFreq);
Each source generated by alGenSources has properties which can
be set or retrieved. The alSource[f, 3f, fv, i]
and
alGetSource[f, 3f, fv, i]
families of functions can be used to set or retrieve
the following source properties:
Property | Data Type | Description |
---|---|---|
AL_PITCH |
f , fv
|
Pitch multiplier. Always positive |
AL_GAIN |
f , fv
|
Source gain. Value should be positive |
AL_MAX_DISTANCE |
f , fv , i , iv
|
Used with the Inverse Clamped Distance Model to set the distance where there will no longer be any attenuation of the source |
AL_ROLLOFF_FACTOR |
f , fv , i , iv
|
The rolloff rate for the source. Default is 1.0 |
AL_REFERENCE_DISTANCE |
f , fv , i , iv
|
The distance under which the volume for the source would normally drop by half (before being influenced by rolloff factor or AL_MAX_DISTANCE ) |
AL_MIN_GAIN |
f , fv
|
The minimum gain for this source |
AL_MAX_GAIN |
f , fv
|
The maximum gain for this source |
AL_CONE_OUTER_GAIN |
f , fv
|
The gain when outside the oriented cone |
AL_CONE_INNER_ANGLE |
f , fv , i , iv
|
The gain when inside the oriented cone |
AL_CONE_OUTER_ANGLE |
f , fv , i , iv
|
Outer angle of the sound cone, in degrees. Default is 360 |
AL_POSITION |
fv , 3f
|
X, Y, Z position |
AL_VELOCITY |
fv , 3f
|
Velocity vector |
AL_DIRECTION |
fv , 3f , iv , 3i
|
Direction vector |
AL_SOURCE_RELATIVE |
i , iv
|
Determines if the positions are relative to the listener. Default is AL_FALSE
|
AL_SOURCE_TYPE |
i , iv
|
The source type – AL_UNDETERMINED , AL_STATIC , or AL_STREAMING
|
AL_LOOPING |
i , iv
|
Turns looping on (AL_TRUE ) or off (AL_FALSE ) |
AL_BUFFER |
i , iv
|
The ID of the attached buffer |
AL_SOURCE_STATE |
i , iv
|
The state of the source (AL_STOPPED , AL_PLAYING , …) |
AL_BUFFERS_QUEUED * |
i , iv
|
The number of buffers queued on this source |
AL_BUFFERS_PROCESSED |
i , iv
|
The number of buffers in the queue that have been processed |
AL_SEC_OFFSET |
f , fv , i , iv
|
The playback position, expressed in seconds |
AL_SAMPLE_OFFSET |
f , fv , i , iv
|
The playback position, expressed in samples |
AL_BYTE_OFFSET |
f , fv , i , iv
|
The playback position, expressed in bytes |
* Read Only (alGetSourcei)
Example:
alGetError(); // clear error state
alSourcef(source[0],AL_PITCH,1.0f);
if ((error = alGetError()) != AL_NO_ERROR)
DisplayALError("alSourcef 0 AL_PITCH : \n", error);
alGetError(); // clear error state
alSourcef(source[0],AL_GAIN,1.0f);
if ((error = alGetError()) != AL_NO_ERROR)
DisplayALError("alSourcef 0 AL_GAIN : \n", error);
alGetError(); // clear error state
alSourcefv(source[0],AL_POSITION,source0Pos);
if ((error = alGetError()) != AL_NO_ERROR)
DisplayALError("alSourcefv 0 AL_POSITION : \n", error);
alGetError(); // clear error state
alSourcefv(source[0],AL_VELOCITY,source0Vel);
if ((error = alGetError()) != AL_NO_ERROR)
DisplayALError("alSourcefv 0 AL_VELOCITY : \n", error);
alGetError(); // clear error state
alSourcei(source[0],AL_LOOPING,AL_FALSE);
if ((error = alGetError()) != AL_NO_ERROR)
DisplayALError("alSourcei 0 AL_LOOPING true: \n", error);
To continuously stream audio from a source without interruption, buffer queuing is required. To use buffer queuing, the buffers and sources are generated in the normal way, but alSourcei is not used to attach the buffers to the source. Instead, the functions alSourceQueueBuffers and alSourceUnqueueBuffers are used. The program can attach a buffer or a set of buffers to a source using alSourceQueueBuffers, and then call alSourcePlay on that source. While the source is playing, alSourceUnqueueBuffers can be called to remove buffers which have already played. Those buffers can then be filled with new data or discarded. New or refilled buffers can then be attached to the playing source using alSourceQueueBuffers. As long as there is always a new buffer to play in the queue, the source will continue to play.
Although some 1.0 implementations of OpenAL may not enforce the following restrictions on queuing, it is recommended to observe the following additional rules, which do universally apply to 1.1 implementations:
-
A source that will be used for streaming should not have its first buffer attached using alSourcei – always use alSourceQueueBuffers to attach buffers to streaming sources. Any source can have all buffers detached from it using
alSourcei(..., AL_BUFFER, 0)
, and can then be used for either streaming or non-streaming buffers depending on how data is then attached to the source (with alSourcei or with alSourceQueueBuffers). -
All buffers attached to a source using alSourceQueueBuffers should have the same audio format.
The Doppler effect depends on the velocities of source and listener relative to the medium, and the propagation speed of sound in that medium. The application might want to emphasize or deemphasize the Doppler effect as physically accurate calculation might not give the desired results. The amount of frequency shift (pitch change) is proportional to the speed of listener and source along their line of sight.
The Doppler effect as implemented by OpenAL is described by the formula below. Effects of the medium (air, water) moving with respect to listener and source are ignored.
- SS:
AL_SPEED_OF_SOUND
= speed of sound (default value 343.3) - DF:
AL_DOPPLER_FACTOR
= Doppler factor (default 1.0) - vls: Listener velocity scalar (scalar, projected on source-to-listener vector)
- vss: Source velocity scalar (scalar, projected on source-to-listener vector)
- f: Frequency of sample
- f': Effective Doppler shifted frequency
- SL: Source tt listener vector
- SV: Source velocity vector
- LV: Listener velocity vector
Graphic representation of vls and vss:
3D Mathematical representation of vls and vss:
There are two API calls global to the current context that provide control of
the speed of sound and Doppler factor. AL_DOPPLER_FACTOR
is a simple scaling
of source and listener velocities to exaggerate or deemphasize the Doppler
(pitch) shift resulting from the calculation.
void alDopplerFactor(ALfloat dopplerFactor);
A negative value will result in an AL_INVALID_VALUE
error, the command is then
ignored. The default value is 1. The current setting can be queried using
alGetFloat{v}
and AL_DOPPLER_FACTOR
.
AL_SPEED_OF_SOUND
allows the application to change the reference (propagation)
speed used in the Doppler calculation. The source and listener velocities
should be expressed in the same units as the speed of sound.
void alSpeedOfSound(ALfloat speed);
A negative or zero value will result in an AL_INVALID_VALUE
error, and the
command is ignored. The default value is 343.3 (appropriate for velocity units
of meters and air as the propagation medium). The current setting can be queried
using alGetFloat{v}
and AL_SPEED_OF_SOUND
.
Distance and velocity units are completely independent of one another (so you could use different units for each if desired). If an OpenAL application doesn't want to use Doppler effects, then leaving all velocities at zero will achieve that result.
The error state of OpenAL can be retrieved at any time using alGetError. alGetError clears the error state of OpenAL when it is called, so it is common for an OpenAL application to call alGetError at the beginning of a critical operation to clear the error state, perform the critical operation, and then use alGetError again to test whether or not an error occurred.
Error Codes:
Error Code | Description |
---|---|
AL_NO_ERROR | there is not currently an error |
AL_INVALID_NAME | a bad name (ID) was passed to an OpenAL function |
AL_INVALID_ENUM | an invalid enum value was passed to an OpenAL function |
AL_INVALID_VALUE | an invalid value was passed to an OpenAL function |
AL_INVALID_OPERATION | the requested operation is not valid |
AL_OUT_OF_MEMORY | the requested operation resulted in OpenAL running out of memory |
Example:
alGetError(); // Clear Error Code
// Generate Buffers
alGenBuffers(NUM_BUFFERS, g_Buffers);
if ((error = alGetError()) != AL_NO_ERROR)
{
DisplayALError("alGenBuffers :", error);
exit(-1);
}
OpenAL has an extension mechanism that can be used by OpenAL vendors to add new features to the API. Creative Labs have added a number of extensions including EAX, X-RAM, Multi Channel Buffer playback, and most recently an Effect Extension (EFX). To determine if an extension is available the application can use either alIsExtensionPresent or alcIsExtensionPresent depending on the type of extension. The Appendices contain more details about some of Creative’s extensions to OpenAL.
Property | Data Type | Description |
---|---|---|
AL_FREQUENCY |
i , iv
|
Frequency of buffer in Hz |
AL_BITS |
i , iv
|
Bit depth of buffer |
AL_CHANNELS |
i , iv
|
Number of channels in buffer. > 1 is valid, but buffer won’t be positioned when played |
AL_SIZE |
i , iv
|
Size of buffer in bytes |
AL_DATA |
i , iv
|
Original location where data was copied from generally useless, as was probably freed after buffer creation |
- alGenBuffers
- alDeleteBuffers
- alIsBuffer
- alBufferData
- alBufferf
- alBuffer3f
- alBufferfv
- alBufferi
- alBuffer3i
- alBufferiv
- alGetBufferf
- alGetBuffer3f
- alGetBufferfv
- alGetBufferi
- alGetBuffer3i
- alGetBufferiv
This function generates one or more buffers, which contain audio data (see
alBufferData). References to buffers are ALuint
values,
which are used wherever a buffer reference is needed (in calls such as
alDeleteBuffers, alSourcei,
alSourceQueueBuffers, and
alSourceUnqueueBuffers).
void alGenBuffers(
ALsizei n,
ALuint *buffers
);
- n - The number of buffers to be generated
- buffers - Pointer to an array of ALuint values which will store the names of the new buffers
State | Description |
---|---|
AL_INVALID_VALUE | The buffer array isn't large enough to hold the number of buffers requested. |
AL_OUT_OF_MEMORY | There is not enough memory available to generate all the buffers requested. |
OpenAL 1.0 or higher
If the requested number of buffers cannot be created, an error will be generated
which can be detected with alGetError. If an error occurs, no
buffers will be generated. If n
equals zero, alGenBuffers
does nothing and does not return an error.
This function deletes one or more buffers, freeing the resources used by the buffer. Buffers which are attached to a source can not be deleted. See alSourcei and alSourceUnqueueBuffers for information on how to detach a buffer from a source.
void alDeleteBuffers(
ALsizei n,
ALuint *buffers
);
- n - The number of buffers to be deleted
- buffers - Pointer to an array of buffer names identifying the buffers to be deleted
State | Description |
---|---|
AL_INVALID_OPERATION | The buffer is still in use and can not be deleted. |
AL_INVALID_NAME | A buffer name is invalid. |
AL_INVALID_VALUE | The requested number of buffers can not be deleted. |
OpenAL 1.0 or higher
If the requested number of buffers cannot be deleted, an error will be generated
which can be detected with alGetError. If an error occurs, no
buffers will be deleted. If n
equals zero,
alDeleteBuffers does nothing and will not return an error.
This function tests if a buffer name is valid, returning AL_TRUE
if valid,
AL_FALSE
if not.
ALboolean alIsBuffer(
ALuint buffer
);
- buffer - A buffer name to be tested for validity
None
OpenAL 1.0 or higher
The NULL
buffer is always valid (see alSourcei for information on how the NULL buffer is
used).
This function fills a buffer with audio data. All the pre-defined formats are PCM data, but this function may be used by extensions to load other data types as well.
void alBufferData(
ALuint buffer,
ALenum format,
const ALvoid *data,
ALsizei size,
ALsizei freq
);
- buffer - Buffer name to be filled with data
- format - Format type from among the following:
AL_FORMAT_MONO8
AL_FORMAT_MONO16
AL_FORMAT_STEREO8
AL_FORMAT_STEREO16
- data - Pointer to the audio data
- size - The size of the data in bytes
- freq - The frequency of the audio data
State | Description |
---|---|
AL_OUT_OF_MEMORY | There is not enough memory available to create this buffer. |
AL_INVALID_VALUE | The size parameter is not valid for the format specified, the buffer is in use, or the data is a NULL pointer. |
AL_INVALID_ENUM | The specified format does not exist. |
OpenAL 1.0 or higher
8-bit PCM data is expressed as an unsigned value over the range 0 to 255, 128 being an audio output level of zero. 16-bit PCM data is expressed as a signed value over the range -32768 to 32767, 0 being an audio output level of zero. Stereo data is expressed in interleaved format, left channel first. Buffers containing more than one channel of data will be played without 3D spatialization.
This function sets a floating point property of a buffer.
void alBufferf(
ALuint buffer,
ALenum param,
ALfloat value
);
- buffer - Buffer name whose attribute is being retrieved
- param - The name of the attribute to be set
- value - The
ALfloat
value to be set
State | Description |
---|---|
AL_INVALID_ENUM | The specified parameter is not valid. |
AL_INVALID_NAME | The specified buffer doesn't have parameters (the NULL buffer), or doesn't exist. |
OpenAL 1.1 or higher
There are no relevant buffer properties defined in OpenAL 1.1 which can be affected by this call, but this function may be used by OpenAL extensions.
alBuffer3f, alBufferfv, alGetBufferf, alGetBuffer3f, alGetBufferfv
This function sets a floating point property of a buffer.
void alBuffer3f(
ALuint buffer,
ALenum param,
ALfloat v1,
ALfloat v2,
ALfloat v3
);
- buffer - Buffer name whose attribute is being retrieved
- param - The name of the attribute to be set
- v1, v2, v3 - The
ALfloat
values to be set
State | Description |
---|---|
AL_INVALID_ENUM | The specified parameter is not valid. |
AL_INVALID_NAME | The specified buffer doesn't have parameters (the NULL buffer), or doesn't exist. |
OpenAL 1.1 or higher
There are no relevant buffer properties defined in OpenAL 1.1 which can be affected by this call, but this function may be used by OpenAL extensions.
alBufferf, alBufferfv, alGetBufferf, alGetBuffer3f, alGetBufferfv
This function sets a floating point property of a buffer.
void alBuffer3f(
ALuint buffer,
ALenum param,
ALfloat* value
);
- buffer - Buffer name whose attribute is being retrieved
- param - The name of the attribute to be set
- values - A pointer to the
ALfloat
values to be set
State | Description |
---|---|
AL_INVALID_ENUM | The specified parameter is not valid. |
AL_INVALID_NAME | The specified buffer doesn't have parameters (the NULL buffer), or doesn't exist. |
OpenAL 1.1 or higher
There are no relevant buffer properties defined in OpenAL 1.1 which can be affected by this call, but this function may be used by OpenAL extensions.
alBufferf, alBuffer3f, alGetBufferf, alGetBuffer3f, alGetBufferfv
This function sets an integer property of a buffer.
void alBufferi(
ALuint buffer,
ALenum param,
ALint value
);
- buffer - Buffer name whose attribute is being retrieved
- param - The name of the attribute to be set
- values - The
ALint
value to be set
State | Description |
---|---|
AL_INVALID_ENUM | The specified parameter is not valid. |
AL_INVALID_NAME | The specified buffer doesn't have parameters (the NULL buffer), or doesn't exist. |
OpenAL 1.1 or higher
There are no relevant buffer properties defined in OpenAL 1.1 which can be affected by this call, but this function may be used by OpenAL extensions.
alBuffer3i, alBufferiv, alGetBufferi, alGetBuffer3i, alGetBufferiv
This function sets an integer property of a buffer.
void alBuffer3i(
ALuint buffer,
ALenum param,
ALint v1,
ALint v2,
ALint v3,
);
- buffer - Buffer name whose attribute is being retrieved
- param - The name of the attribute to be set
- v1, v2, v3 - The
ALint
values to be set
State | Description |
---|---|
AL_INVALID_ENUM | The specified parameter is not valid. |
AL_INVALID_NAME | The specified buffer doesn't have parameters (the NULL buffer), or doesn't exist. |
OpenAL 1.1 or higher
There are no relevant buffer properties defined in OpenAL 1.1 which can be affected by this call, but this function may be used by OpenAL extensions.
alBufferi, alBufferiv, alGetBufferi, alGetBuffer3i, alGetBufferiv
This function sets an integer property of a buffer.
void alBufferiv(
ALuint buffer,
ALenum param,
ALint* values
);
- buffer - Buffer name whose attribute is being retrieved
- param - The name of the attribute to be set
- values - A pointer to the
ALint
values to be set
State | Description |
---|---|
AL_INVALID_ENUM | The specified parameter is not valid. |
AL_INVALID_NAME | The specified buffer doesn't have parameters (the NULL buffer), or doesn't exist. |
OpenAL 1.1 or higher
There are no relevant buffer properties defined in OpenAL 1.1 which can be affected by this call, but this function may be used by OpenAL extensions.
alBufferi, alBuffer3i, alGetBufferi, alGetBuffer3i, alGetBufferiv
This function retrieves a floating point property of a buffer.
void alGetBufferf(
ALuint buffer,
ALenum pname,
ALfloat* value
);
- buffer - Buffer name whose attribute is being retrieved
- param - The name of the attribute to be retrieved
- value - A pointer to an
ALfloat
to hold the retrieved data
State | Description |
---|---|
AL_INVALID_ENUM | The specified parameter is not valid. |
AL_INVALID_NAME | The specified buffer doesn't have parameters (the NULL buffer), or doesn't exist. |
AL_INVALID_VALUE | The specified value pointer is not valid. |
OpenAL 1.0 or higher
There are no relevant buffer properties defined in OpenAL 1.1 which can be affected by this call, but this function may be used by OpenAL extensions.
alBufferf, alBuffer3f, alBufferfv, alGetBuffer3f, alGetBufferfv
This function retrieves a floating point property of a buffer.
void alGetBuffer3f(
ALuint buffer,
ALenum pname,
ALfloat* v1,
ALfloat* v2,
ALfloat* v3
);
- buffer - Buffer name whose attribute is being retrieved
- param - The name of the attribute to be retrieved
- v1, v2, v3 - Pointers to
ALfloat
values to hold the retrieved data
State | Description |
---|---|
AL_INVALID_ENUM | The specified parameter is not valid. |
AL_INVALID_NAME | The specified buffer doesn't have parameters (the NULL buffer), or doesn't exist. |
AL_INVALID_VALUE | The specified value pointer is not valid. |
OpenAL 1.1 or higher
There are no relevant buffer properties defined in OpenAL 1.1 which can be affected by this call, but this function may be used by OpenAL extensions.
alBufferf, alBuffer3f, alBufferfv, alGetBufferf, alGetBufferfv
This function retrieves a floating point property of a buffer.
void alGetBufferfv(
ALuint buffer,
ALenum pname,
ALfloat* values
);
- buffer - Buffer name whose attribute is being retrieved
- param - The name of the attribute to be retrieved
- values - Pointer to an
ALfloat
vector to hold the retrieved data
State | Description |
---|---|
AL_INVALID_ENUM | The specified parameter is not valid. |
AL_INVALID_NAME | The specified buffer doesn't have parameters (the NULL buffer), or doesn't exist. |
AL_INVALID_VALUE | The specified value pointer is not valid. |
OpenAL 1.1 or higher
There are no relevant buffer properties defined in OpenAL 1.1 which can be affected by this call, but this function may be used by OpenAL extensions.
alBufferf, alBuffer3f, alBufferfv, alGetBufferf, alGetBuffer3f
This function retrieves an integer property of a buffer.
void alGetBufferi(
ALuint buffer,
ALenum pname,
ALint* value
);
- buffer - Buffer name whose attribute is being retrieved
- param - The name of the attribute to be retrieved:
AL_FREQUENCY
AL_BITS
AL_CHANNELS
AL_SIZE
AL_DATA
- value - Pointer to an
ALint
to hold the retrieved data
State | Description |
---|---|
AL_INVALID_ENUM | The specified parameter is not valid. |
AL_INVALID_NAME | The specified buffer doesn't have parameters (the NULL buffer), or doesn't exist. |
AL_INVALID_VALUE | The specified value pointer is not valid. |
OpenAL 1.0 or higher
None
alBufferi, alBuffer3i, alBufferiv, alGetBuffer3i, alGetBufferiv
This function retrieves an integer property of a buffer.
void alGetBuffer3i(
ALuint buffer,
ALenum pname,
ALint* v1,
ALint* v2,
ALint* v3
);
- buffer - Buffer name whose attribute is being retrieved
- param - The name of the attribute to be retrieved
- v1, v2, v3 - Pointer to
ALint
values to hold the retrieved data
State | Description |
---|---|
AL_INVALID_ENUM | The specified parameter is not valid. |
AL_INVALID_NAME | The specified buffer doesn't have parameters (the NULL buffer), or doesn't exist. |
AL_INVALID_VALUE | The specified value pointer is not valid. |
OpenAL 1.1 or higher
There are no relevant buffer properties defined in OpenAL 1.1 which can be retrieved by this call, but this function may be used by OpenAL extensions.
alBufferi, alBuffer3i, alBufferiv, alGetBufferi, alGetBufferiv
This function retrieves an integer property of a buffer.
void alGetBufferiv(
ALuint buffer,
ALenum pname,
ALint* values
);
- buffer - Buffer name whose attribute is being retrieved
- param - The name of the attribute to be retrieved:
AL_FREQUENCY
AL_BITS
AL_CHANNELS
AL_SIZE
AL_DATA
- values - Pointer to an
ALint
vector to hold the retrieved data
State | Description |
---|---|
AL_INVALID_ENUM | The specified parameter is not valid. |
AL_INVALID_NAME | The specified buffer doesn't have parameters (the NULL buffer), or doesn't exist. |
AL_INVALID_VALUE | The specified value pointer is not valid. |
OpenAL 1.1 or higher
None
alBufferi, alBuffer3i, alBufferiv, alGetBufferi, alGetBuffer3i
Property | Data Type | Description |
---|---|---|
AL_PITCH |
f , fv
|
Pitch multiplier. Always positive |
AL_GAIN |
f , fv
|
Source gain. Value should be positive |
AL_MAX_DISTANCE |
f , fv , i , iv
|
Used with the Inverse Clamped Distance Model to set the distance where there will no longer be any attenuation of the source |
AL_ROLLOFF_FACTOR |
f , fv , i , iv
|
The rolloff rate for the source. Default is 1.0 |
AL_REFERENCE_DISTANCE |
f , fv , i , iv
|
The distance under which the volume for the source would normally drop by half (before being influenced by rolloff factor or AL_MAX_DISTANCE ) |
AL_MIN_GAIN |
f , fv
|
The minimum gain for this source |
AL_MAX_GAIN |
f , fv
|
The maximum gain for this source |
AL_CONE_OUTER_GAIN |
f , fv
|
The gain when outside the oriented cone |
AL_CONE_INNER_ANGLE |
f , fv , i , iv
|
The gain when inside the oriented cone |
AL_CONE_OUTER_ANGLE |
f , fv , i , iv
|
Outer angle of the sound cone, in degrees. Default is 360 |
AL_POSITION |
fv , 3f
|
X, Y, Z position |
AL_VELOCITY |
fv , 3f
|
Velocity vector |
AL_DIRECTION |
fv , 3f , iv , 3i
|
Direction vector |
AL_SOURCE_RELATIVE |
i , iv
|
Determines if the positions are relative to the listener. Default is AL_FALSE
|
AL_SOURCE_TYPE |
i , iv
|
The source type: AL_UNDETERMINED , AL_STATIC or AL_STREAMING
|
AL_LOOPING |
i , iv
|
Turns looping on (AL_TRUE ) or off (AL_FALSE ) |
AL_BUFFER |
i , iv
|
The ID of the attached buffer |
AL_SOURCE_STATE |
i , iv
|
The state of the source: AL_STOPPED , AL_PLAYING , ... |
AL_BUFFERS_QUEUED |
i , iv
|
The number of buffers queued on this source |
AL_BUFFERS_PROCESSED |
i , iv
|
The number of buffers in the queue that have been processed |
AL_SEC_OFFSET |
f , fv , i , iv
|
The playback position, expressed in seconds |
AL_SAMPLE_OFFSET |
f , fv , i , iv
|
The playback position, expressed in samples |
AL_BYTE_OFFSET |
f , fv , i , iv
|
The playback position, expressed in bytes |
- alGenSources
- alDeleteSources
- alIsSource
- alSourcef
- alSource3f
- alSourcefv
- alSourcei
- alSource3i
- alSourceiv
- alGetSourcef
- alGetSource3f
- alGetSourcefv
- alGetSourcei
- alGetSource3i
- alGetSourceiv
- alSourcePlay
- alSourcePlayv
- alSourcePause
- alSourcePausev
- alSourceStop
- alSourceStopv
- alSourceRewind
- alSourceRewindv
- alSourceQueueBuffers
- alSourceUnqueueBuffers
This function generates one or more sources. References to sources are
ALuint
values, which are used wherever a source reference is needed (in calls
such as alDeleteSources and alSourcei).
void alGenSources(
ALsizei n,
ALuint *sources
);
- n - The number of sources to be generated
- sources - Pointer to an array of
ALuint
vlaues which will store the names of the new sources
State | Description |
---|---|
AL_OUT_OF_MEMORY | There is not enough memory to generate all the requested sources. |
AL_INVALID_VALUE | There are not enough non-memory resources to create all the requested sources, or the array pointer is not valid. |
AL_INVALID_OPERATION | There is no context to create sources in. |
OpenAL 1.0 or higher
If the requested number of sources cannot be created, an error will be generated
which can be detected with alGetError. If an error occurs, no
sources will be generated. If n
equals zero, alGenSources
does nothing and does not return an error.
This function deletes one or more sources.
void alDeleteSources(
ALsizei n,
ALuint *sources
);
- n - The number of sources to be deleted
- sources - Pointer to an array of source names identifying the sources to be deleted
State | Description |
---|---|
AL_INVALID_NAME | At least one specified source is not valid, or an attempt is being made to delete more sources than exist. |
AL_INVALID_OPERATION | There is no current context. |
OpenAL 1.0 or higher
If the requested number of sources cannot be deleted, an error will be generated
which can be detected with alGetError. If an error occurs, no
sources will be deleted. If n
equals zero,
alDeleteSources does nothing and will not return an error.
A playing source can be deleted – the source will be stopped and then deleted.
This function tests if a source name is valid, returning AL_TRUE
if valid and
AL_FALSE
if not.
boolean alIsSource(
ALuint source
);
- source - A source name to be tested for validity
State | Description |
---|---|
AL_INVALID_OPERATION | There is no current context. |
OpenAL 1.0 or higher
None
This function sets an integer property of a source.
void alSourcef(
ALuint source,
ALenum param,
ALfloat value
);
- source - Source name whose attribute is being set
- param - The name of the attribute to set:
AL_PITCH
AL_GAIN
AL_MIN_GAIN
AL_MAX_GAIN
AL_MAX_DISTANCE
AL_ROLLOFF_FACTOR
AL_CONE_OUTER_GAIN
AL_CONE_INNER_ANGLE
AL_CONE_OUTER_ANGLE
AL_REFERENCE_DISTANCE
- value - The value to set the attribute to
State | Description |
---|---|
AL_INVALID_VALUE | The value given is out of range. |
AL_INVALID_ENUM | The specified parameter is not valid. |
AL_INVALID_NAME | The specified source name is not valid. |
AL_INVALID_OPERATION | There is no current context. |
OpenAL 1.0 or higher
None
alSource3f, alSourcefv, alGetSourcef, alGetSource3f, alGetSourcefv
This function sets a source property requiring three floating point values.
void alSource3f(
ALuint source,
ALenum param,
ALfloat v1,
ALfloat v2,
ALfloat v3
);
- source - Source name whose attribute is being set
- param - The name of the attribute to set:
AL_POSITION
AL_VELOCITY
AL_DIRECTION
- v1, v2, v3 - The three
ALfloat
values to set the attribute to
State | Description |
---|---|
AL_INVALID_VALUE | The value given is out of range. |
AL_INVALID_ENUM | The specified parameter is not valid. |
AL_INVALID_NAME | The specified source name is not valid. |
AL_INVALID_OPERATION | There is no current context. |
OpenAL 1.0 or higher
This function is an alternative to alSourcefv.
alSourcef, alSourcefv, alGetSourcef, alGetSource3f, alGetSourcefv
This function sets a floating point-vector property of a source.
void alSourcefv(
ALuint source,
ALenum param,
ALfloat* values
);
- source - Source name whose attribute is being set
- param - The name of the attribute to set:
AL_POSITION
AL_VELOCITY
AL_DIRECTION
- values - A pointer to the vector to set the attribute to
State | Description |
---|---|
AL_INVALID_VALUE | The value given is out of range. |
AL_INVALID_ENUM | The specified parameter is not valid. |
AL_INVALID_NAME | The specified source name is not valid. |
AL_INVALID_OPERATION | There is no current context. |
OpenAL 1.0 or higher
This function is an alternative to alSource3f.
alSourcef, alSource3f, alGetSourcef, alGetSource3f, alGetSourcefv
This function sets an integer property of a source.
void alSourcei(
ALuint source,
ALenum param,
ALint value
);
- source - Source name whose attribute is being set
- param - The name of the attribute to set:
AL_SOURCE_RELATIVE
AL_CONE_INNER_ANGLE
AL_CONE_OUTER_ANGLE
AL_LOOPING
AL_BUFFER
AL_SOURCE_STATE
- value - The value to set the attribute to
State | Description |
---|---|
AL_INVALID_VALUE | The value given is out of range. |
AL_INVALID_ENUM | The specified parameter is not valid. |
AL_INVALID_NAME | The specified source name is not valid. |
AL_INVALID_OPERATION | There is no current context. |
OpenAL 1.0 or higher
The buffer name zero is reserved as a “NULL Buffer" and is accepted by
alSourcei(…, AL_BUFFER, …)
as a valid buffer of zero length. The NULL
Buffer is extremely useful for detaching buffers from a source which were
attached using this call or with alSourceQueueBuffers.
alSource3i, alSourceiv, alGetSourcei, alGetSource3i, alGetSourceiv
This function sets a source property requiring three integer values.
void alSource3i(
ALuint source,
ALenum param,
ALint v1,
ALint v2,
ALint v3
);
- source - Source name whose attribute is being set
- param - The name of the attribute to set:
AL_POSITION
AL_VELOCITY
AL_DIRECTION
- v1, v2, v3 - The three
ALint
values to set the attribute to
State | Description |
---|---|
AL_INVALID_VALUE | The value given is out of range. |
AL_INVALID_ENUM | The specified parameter is not valid. |
AL_INVALID_NAME | The specified source name is not valid. |
AL_INVALID_OPERATION | There is no current context. |
OpenAL 1.1 or higher
None
alSourcei, alSourceiv, alGetSourcei, alGetSource3i, alGetSourceiv
This function sets an integer-vector property of a source.
void alSourceiv(
ALuint source,
ALenum param,
ALint* values
);
- source - Source name whose attribute is being set
- param - The name of the attribute to set:
AL_POSITION
AL_VELOCITY
AL_DIRECTION
- values - A pointer to the vector to set the attribute to
State | Description |
---|---|
AL_INVALID_VALUE | The value given is out of range. |
AL_INVALID_ENUM | The specified parameter is not valid. |
AL_INVALID_NAME | The specified source name is not valid. |
AL_INVALID_OPERATION | There is no current context. |
OpenAL 1.1 or higher
None
alSourcei, alSource3i, alGetSourcei, alGetSource3i, alGetSourceiv
This function sets an integer property of a source.
void alGetSourcei(
ALuint source,
ALenum param,
ALint* value
);
- source - Source name whose attribute is being retrieved
- param - The name of the attribute to retrieve:
AL_SOURCE_RELATIVE
AL_BUFFER
AL_SOURCE_STATE
AL_BUFFERS_QUEUED
AL_BUFFERS_PROCESSED
- values - A pointer to the integer value being retrieved
State | Description |
---|---|
AL_INVALID_VALUE | The value pointer given is not valid. |
AL_INVALID_ENUM | The specified parameter is not valid. |
AL_INVALID_NAME | The specified source name is not valid. |
AL_INVALID_OPERATION | There is no current context. |
OpenAL 1.0 or higher
None
alSourcei, alSource3i, alSourceiv, alGetSource3i, alGetSourceiv
This function retrieves three integer values representing a property of a source.
void alGetSource3i(
ALuint source,
ALenum param,
ALint* v1,
ALint* v2,
ALint* v3
);
- source - Source name whose attribute is being retrieved
- param - The name of the attribute to retrieve:
AL_POSITION
AL_VELOCITY
AL_DIRECTION
- values - Pointer to the values to retrieve
State | Description |
---|---|
AL_INVALID_VALUE | The value pointer given is not valid. |
AL_INVALID_ENUM | The specified parameter is not valid. |
AL_INVALID_NAME | The specified source name is not valid. |
AL_INVALID_OPERATION | There is no current context. |
OpenAL 1.1 or higher
None
alSourcei, alSource3i, alSourceiv, alGetSourcei, alGetSourceiv
This function retrieves an integer property of a source.
void alGetSourceiv(
ALuint source,
ALenum param,
ALint* values
);
- source - Source name whose attribute is being retrieved
- param - The name of the attribute to retrieve:
AL_POSITION
AL_VELOCITY
AL_DIRECTION
- values - Pointer to the vector to retrieve
State | Description |
---|---|
AL_INVALID_VALUE | The value pointer given is not valid. |
AL_INVALID_ENUM | The specified parameter is not valid. |
AL_INVALID_NAME | The specified source name is not valid. |
AL_INVALID_OPERATION | There is no current context. |
OpenAL 1.0 or higher
None
alSourcei, alSource3i, alSourceiv, alGetSourcei, alGetSource3i
This function plays a source.
void alSourcePlay(
ALuint source
);
- source - The name of the source to be played
State | Description |
---|---|
AL_INVALID_NAME | The specified source name is not valid. |
AL_INVALID_OPERATION | There is no current context. |
OpenAL 1.0 or higher
The playing source will have its state changed to AL_PLAYING
. When called on a
source which is already playing, the source will restart at the beginning. When
the attached buffer(s) are done playing, the source will progress to the
AL_STOPPED
state.
alSourcePlayv, alSourcePause, alSourcePausev, alSourceRewind, alSourceRewindv, alSourceStop, alsourcestopv
This function plays a set of sources.
void alSourcePlayv(
ALsizei n,
ALuint *sources
);
- n - The number of sources to be played
- source - A pointer to an array of sources to be played
State | Description |
---|---|
AL_INVALID_VALUE | The value pointer given is not valid. |
AL_INVALID_NAME | The specified source name is not valid. |
AL_INVALID_OPERATION | There is no current context. |
OpenAL 1.0 or higher
The playing sources will have their state changed to AL_PLAYING
. When called
on a source which is already playing, the source will restart at the beginning.
When the attached buffer(s) are done playing, the source will progress to the
AL_STOPPED
state.
alSourcePlay, alSourcePause, alSourcePausev, alSourceRewind, alSourceRewindv, alSourceStop, alsourcestopv
This function pauses a source.
void alSourcePause(
ALuint source
);
- source - The name of the source to be paused
State | Description |
---|---|
AL_INVALID_NAME | The specified source name is not valid. |
AL_INVALID_OPERATION | There is no current context. |
OpenAL 1.0 or higher
The paused source will have its state changed to AL_PAUSED
.
alSourcePlay, alSourcePlayv, alSourcePausev, alSourceRewind, alSourceRewindv, alSourceStop, alsourcestopv
This function pauses a set of sources.
void alSourcePausev(
ALsizei n,
ALuint *sources
);
- n - The number of sources to be paused
- source - A pointer to an array of sources to be paused
State | Description |
---|---|
AL_INVALID_VALUE | The value pointer given is not valid. |
AL_INVALID_NAME | The specified source name is not valid. |
AL_INVALID_OPERATION | There is no current context. |
OpenAL 1.0 or higher
The paused sources will have their state changed to AL_PAUSED
.
alSourcePlay, alSourcePlayv, alSourcePause, alSourceRewind, alSourceRewindv, alSourceStop, alsourcestopv
This function stops a source.
void alSourceStop(
ALuint source
);
- source - The name of the source to be stopped
State | Description |
---|---|
AL_INVALID_NAME | The specified source name is not valid. |
AL_INVALID_OPERATION | There is no current context. |
OpenAL 1.0 or higher
The paused source will have its state changed to AL_STOPPED
.
alSourcePlay, alSourcePlayv, alSourcePause, alSourcePausev, alSourceRewind, alSourceRewindv, alsourcestopv
This function stops a set of sources.
void alSourceStopv(
ALsizei n,
ALuint *sources
);
- n - The number of sources to stop
- source - A pointer to an array of sources to be stopped
State | Description |
---|---|
AL_INVALID_VALUE | The value pointer given is not valid. |
AL_INVALID_NAME | The specified source name is not valid. |
AL_INVALID_OPERATION | There is no current context. |
OpenAL 1.0 or higher
The paused sources will have their state changed to AL_STOPPED
.
alSourcePlay, alSourcePlayv, alSourcePause, alSourceRewind, alSourceRewindv, alSourceStop, alsourcestop
This function stops the source and sets its state to AL_INITIAL
.
void alSourceRewind(
ALuint source
);
- source - The name of the source to be rewound
State | Description |
---|---|
AL_INVALID_NAME | The specified source name is not valid. |
AL_INVALID_OPERATION | There is no current context. |
OpenAL 1.0 or higher
None
alSourcePlay, alSourcePlayv, alSourcePause, alSourcePausev, alSourceRewindv, alsourcestop, alsourcestopv
his function stops a set of sources and sets all their states to AL_INITIAL
.
void alSourceRewindv(
ALsizei n,
ALuint *sources
);
- n - The number of sources to be rewound
- source - A pointer to an array of sources to be rewound
State | Description |
---|---|
AL_INVALID_VALUE | The value pointer given is not valid. |
AL_INVALID_NAME | The specified source name is not valid. |
AL_INVALID_OPERATION | There is no current context. |
OpenAL 1.0 or higher
None
alSourcePlay, alSourcePlayv, alSourcePause, alSourcePausev, alSourceRewind, alSourceStop, alsourcestop
This function queues a set of buffers on a source. All buffers attached to a
source will be played in sequence, and the number of processed buffers can be
detected using an alSourcei call to retrieve
AL_BUFFERS_PROCESSED
.
void alSourceQueueBuffers(
ALuint source,
ALsizei n,
ALuint* buffers
);
- source - The name of the source to queue buffers onto
- n - The number of buffers to be queued
- buffers - A pointer to an array of buffer names to be queued
State | Description |
---|---|
AL_INVALID_NAME | At least one specified buffer name is not valid, or the specified source name is not valid. |
AL_INVALID_OPERATION | There is no current context, an attempt was made to add a new buffer which is not the same format as the buffers already in the queue, or the source already has a static buffer attached. |
OpenAL 1.0 or higher
When first created, a source will be of type AL_UNDETERMINED
. A successful
alSourceQueueBuffers call will change the source type
to AL_STREAMING
.
This function unqueues a set of buffers attached to a source. The number of
processed buffers can be detected using an alSourcei call to
retrieve AL_BUFFERS_PROCESSED
, which is the maximum number of buffers that can
be unqueued using this call.
void alSourceUnqueueBuffers(
ALuint source,
ALsizei n,
ALuint* buffers
);
- source - The name of the source to unqueue buffers from
- n - The number of buffers to be unqueued
- buffers - A pointer to an array of buffer names that were removed
State | Description |
---|---|
AL_INVALID_VALUE | At least one buffer can not be unqueued because it has not been processed yet. |
AL_INVALID_NAME | The specified source name is not valid. |
AL_INVALID_OPERATION | There is no current context. |
OpenAL 1.0 or higher
The unqueue operation will only take place if all n buffers can be removed from the queue.
Property | Data Type | Description |
---|---|---|
AL_GAIN |
f , fv
|
Master gain. Value should be positive |
AL_POSITION |
fv , 3f , iv , 3i
|
X, Y, Z position |
AL_VELOCITY |
fv , 3f , iv , 3i
|
Velocity vector |
AL_ORIENTATION |
fv , fv
|
Orientation expressed as "at" and "up" vectors |
- alListenerf
- alListener3f
- alListenerfv
- alListeneri
- alListener3i
- alListeneriv
- alGetListenerf
- alGetListener3f
- alGetListenerfv
- alGetListeneri
- alGetListener3i
- alGetListeneriv
This function sets a floating point property for the listener.
void alListenerf(
ALenum param,
ALfloat value
);
- param - The name of the attribute to be set:
AL_GAIN
- value - The ALfloat value to set the attribute to
State | Description |
---|---|
AL_INVALID_VALUE | The value given is not valid. |
AL_INVALID_ENUM | The specified parameter is not valid. |
AL_INVALID_OPERATION | There is no current context. |
OpenAL 1.0 or higher
None
alListener3f, alListenerfv, alGetListenerf, alGetListener3f, alGetListenerfv
This function sets a floating point property for the listener.
void alListener3f(
ALenum param,
ALfloat v1,
ALfloat v2,
ALfloat v3
);
- param - The name of the attribute to be set:
AL_POSITION
AL_VELOCITY
- v1, v2, v3 - The value to set the attribute to
State | Description |
---|---|
AL_INVALID_VALUE | The value given is not valid. |
AL_INVALID_ENUM | The specified parameter is not valid. |
AL_INVALID_OPERATION | There is no current context. |
OpenAL 1.0 or higher
None
alListenerf, alListenerfv, alGetListenerf, alGetListener3f, alGetListenerfv
This function sets a floating point-vector property for the listener.
void alListenerfv(
ALenum param,
ALfloat* values
);
- param - The name of the attribute to be set:
AL_POSITION
AL_VELOCITY
AL_ORIENTATION
- values - Pointer to floating point-vector values
State | Description |
---|---|
AL_INVALID_VALUE | The value given is not valid. |
AL_INVALID_ENUM | The specified parameter is not valid. |
AL_INVALID_OPERATION | There is no current context. |
OpenAL 1.0 or higher
None
alListenerf, alListener3f, alGetListenerf, alGetListener3f, alGetListenerfv
This function sets an integer property for the listener.
void alListeneri(
ALenum param,
ALint value
);
- param - The name of the attribute to be set
- value - The integer value to set the attribute to
State | Description |
---|---|
AL_INVALID_VALUE | The value given is not valid. |
AL_INVALID_ENUM | The specified parameter is not valid. |
AL_INVALID_OPERATION | There is no current context. |
OpenAL 1.0 or higher
There are no integer listener attributes defined for OpenAL 1.1, but this function may be used by an extension.
alListener3i, alListeneriv, alGetListeneri, alGetListener3i, alGetListeneriv
This function sets an integer property for the listener.
void alListener3i(
ALenum param,
ALint v1,
ALint v2,
ALint v3
);
- param - The name of the attribute to be set:
AL_POSITION
AL_VELOCITY
- v1, v2, v3 - The integer values to set the attribute to
State | Description |
---|---|
AL_INVALID_VALUE | The value given is not valid. |
AL_INVALID_ENUM | The specified parameter is not valid. |
AL_INVALID_OPERATION | There is no current context. |
OpenAL 1.1 or higher
None
alListeneri, alListeneriv, alGetListeneri, alGetListener3i, alGetListeneriv
This function sets an integer property for the listener.
void alListeneriv(
ALenum param,
ALint* values
);
- param - The name of the attribute to be set:
AL_POSITION
AL_VELOCITY
AL_ORIENTATION
- values - Pointer to the integer values to set the attribute to
State | Description |
---|---|
AL_INVALID_VALUE | The value given is not valid. |
AL_INVALID_ENUM | The specified parameter is not valid. |
AL_INVALID_OPERATION | There is no current context. |
OpenAL 1.1 or higher
None
alListeneri, alListener3i, alGetListeneri, alGetListener3i, alGetListeneriv
This function retrieves a floating point property of the listener.
void alGetListenerf(
ALenum param,
ALfloat* value
);
- param - The name of the attribute to be retrieved:
AL_GAIN
- values - Pointer to the floating-point value being retrieved
State | Description |
---|---|
AL_INVALID_VALUE | The value given is not valid. |
AL_INVALID_ENUM | The specified parameter is not valid. |
AL_INVALID_OPERATION | There is no current context. |
OpenAL 1.0 or higher
None
alListenerf, alListener3f, alListenerfv, alGetListener3f, alGetListenerfv
This function retrieves a set of three floating point values from a property of the listener.
void alGetListener3f(
ALenum param,
ALfloat* v1,
ALfloat* v2,
ALfloat* v3
);
- param - The name of the attribute to be retrieved:
AL_POSITION
AL_VELOCITY
- v1, v2, v3 - Pointers to the three floating point being retrieved
State | Description |
---|---|
AL_INVALID_VALUE | The value given is not valid. |
AL_INVALID_ENUM | The specified parameter is not valid. |
AL_INVALID_OPERATION | There is no current context. |
OpenAL 1.0 or higher
None
alListenerf, alListener3f, alListenerfv, alGetListenerf, alGetListenerfv
This function retrieves a floating point-vector property of the listener.
void alGetListenerfv(
ALenum param,
ALfloat* values
);
- param - The name of the attribute to be retrieved:
AL_POSITION
AL_VELOCITY
AL_ORIENTATION
- values - Pointers to the three floating point being retrieved
State | Description |
---|---|
AL_INVALID_VALUE | The value given is not valid. |
AL_INVALID_ENUM | The specified parameter is not valid. |
AL_INVALID_OPERATION | There is no current context. |
OpenAL 1.0 or higher
None
alListenerf, alListener3f, alListenerfv, alGetListenerf, alGetListener3f
This function retrieves an integer property of the listener.
void alGetListeneri(
ALenum param,
ALint* value
);
- param - The name of the attribute to be retrieved:
- values - Pointer to the integer value being retrieved
State | Description |
---|---|
AL_INVALID_VALUE | The value given is not valid. |
AL_INVALID_ENUM | The specified parameter is not valid. |
AL_INVALID_OPERATION | There is no current context. |
OpenAL 1.0 or higher
There are no integer listener attributes defined for OpenAL 1.1, but this function may be used by an extension.
alListeneri, alListener3i, alListeneriv, alGetListener3i, alGetListeneriv
This function retrieves an integer property of the listener.
void alGetListener3i(
ALenum param,
ALint* v1,
ALint* v2,
ALint* v3
);
- param - The name of the attribute to be retrieved:
AL_POSITION
AL_VELOCITY
- v1, v2, v3 - Pointers to the integer values being retrieved
State | Description |
---|---|
AL_INVALID_VALUE | The value given is not valid. |
AL_INVALID_ENUM | The specified parameter is not valid. |
AL_INVALID_OPERATION | There is no current context. |
OpenAL 1.1 or higher
None
alListeneri, alListener3i, alListeneriv, alGetListeneri, alGetListeneriv
This function retrieves an integer property of the listener.
void alGetListeneriv(
ALenum param,
ALint* values
);
- param - The name of the attribute to be retrieved:
AL_POSITION
AL_VELOCITY
AL_ORIENTATION
- values - Pointers to the integer values being retrieved
State | Description |
---|---|
AL_INVALID_VALUE | The value given is not valid. |
AL_INVALID_ENUM | The specified parameter is not valid. |
AL_INVALID_OPERATION | There is no current context. |
OpenAL 1.1 or higher
None
alListeneri, alListener3i, alListeneriv, alGetListeneri, alGetListener3i