Programming 3D Sound With OpenAL in Windows
by Dan Ricart

As the capabilities of sound cards and sound APIs have increased over the years, 3D sound has played an increasingly important role in games. Creating an immersive experience for the gamer goes beyond nice looking graphics. Done correctly, ambient sound and music can take games to a whole new level. To achieve this effect, different sound programming APIs have been developed such as Microsoft's DirectSound and DirectSound3D, Aureal's A3D and Creative Labs EAX. More recently, Loki Entertainment and Creative Labs have developed OpenAL. They have done this in an effort to create a more standard, cross-platform API to allow developers to add sound to any title. This article explains the basics of OpenAL and how to get started adding 3D sound to your project.

OpenAL is basically an audio library that contains functions for playing back sounds and music in a game environment. It allows a programmer to load whatever sounds they like and control certain characteristics such as position, velocity, direction and angles for cones that determine how the sound is traveling. All sounds are positioned relative to the listener which represents the current place in the game universe where the user is. The closer the listener gets to a sound, the louder it gets. OpenAL can also be used for the playback of music. OpenAL can make use of streaming to continuously play music back in the background. OpenAL also supports the use of DirectSound3D and EAX in Windows. There are functions contained in the library that allow the use of these APIs without much extra programming.

The main advantage of OpenAL over DirectSound and EAX is that OpenAL is designed to be a cross platform API. It is possible to download Windows, Mac and Linux binaries of it so it can be used on many Operating Systems. DirectSound and DirectSound3D were designed only for Windows and EAX is basically an extension of DirectSound3D. For those wishing to create an application for multiple Operating Systems, OpenAL might be the way to go. This tutorial is designed to show you how to get basic functionality out of OpenAL in Windows. The code shown here is from the demo application that you can download which contains the complete example. OpenGL is used for the rendering so the demo shows some similarities between OpenGL and OpenAL.

Getting Started

The first thing to do is to obtain the OpenAL SDK. This can be obtained from Creative Labs developer site at developer.creative.com. Once the SDK is set up you can begin using its functions. You will first need to initialize OpenAL at the start of your game or application. For my application I am going to use the basic method of setting it up for DirectSound3D but it is also possible to make use of EAX by checking for its availability. The initialization code looks like this:

ALCcontext *Context;
ALCdevice *Device;

Device = alcOpenDevice((ALubyte*)"DirectSound3D");
if (Device == NULL)
{
  exit(-1);
}

//Create context(s)
Context=alcCreateContext(Device,NULL);

//Set active context
alcMakeContextCurrent(Context);

// Clear Error Code
alGetError();

Loading Sounds

Once OpenAL has been initialized you can start filling buffers with sounds. The first step is to fill a buffer with sound using the alutLoadWAVFile function. Once you have filled the buffer you need to attach it to a source. This source can then be used to play back the sound. The code for loading a sound looks like this:

char* alBuffer; //data for the buffer
ALenum alFormatBuffer; //for the buffer format
ALsizei alFreqBuffer; //for the frequency of the buffer
long alBufferLen; //the bit depth
ALboolean alLoop; //looped
unsigned int alSource; //buffer source
unsigned int alSampleSet;

//load the wave file
alutLoadWAVFile("test.wav",&alFormatBuffer, (void **) &alBuffer,(unsigned int *)&alBufferLen, &alFreqBuffer, &loop);

//create 1 source
alGenSources(1, &alSource);

//create 1 buffer
alGenBuffers(1, &alSampleSet);

//put the data into our sampleset buffer
alBufferData(alSampleSet, alFormatBuffer, alBuffer, alBufferLen, alFreqBuffer);

//assign the buffer to this source
alSourcei(alSource, AL_BUFFER, alSampleSet);

//release the data
alutUnloadWAV(alFormatBuffer, alBuffer, alBufferLen, alFreqBuffer);

The first step here was to load the file "test.wav". The data is read in and stored in alBuffer. Next a source and a buffer are created. Then the buffer is filled with data from alBuffer. Next the buffer is assigned to the source and the wave data is released.

Setting Source Properties

Once you have a sound source set up you will need to set some of its properties. To do this you use the alSource command. This function works similar to functions in OpenGL where different versions of the function exist such as alSourcei, alSourcef, alSource3f, and so on. The properties you are setting determine which function you use. Setting something like pitch for example just needs one floating point parameter so alSourcef is used. The first parameter passed to the function is that of the source you are modifying. The second parameter corresponds to what property you are changing. The rest of the parameters are the actual settings for this property. Here is an example of setting position and velocity for a sound source:

//set source position
alSource3f(alSource,AL_POSITION, xposition, yposition, zposition);

//set source velocity
alSource3f(alSource,AL_VELOCITY, xvelocity, yvelocity, zvelocity);

Here alSource is our sound source and AL_POSITION and AL_VELOCITY signal that we want to change the position and velocity parameters. The rest correspond to floating point numbers with preset values.

Using a Listener

The use of a listener in 3D sound is important so that you have a reference point from which to hear sounds. The closer a listener is to a sound source's position, the louder the sound will get provided there are no obstacles. OpenAL already has a listener object set up so all you need to do is modify its properties as needed. The most important properties of the listener are the position and orientation of the listener. These properties are generally updated once for every loop in a game. The position indicates where the listener currently is while the orientation is where the listener is facing. For example, if a listener is facing west and a sound is coming from the north, the sound will appear to come from the right. However if the user orientation changes and turns to face the north, the sound will now appear to come from straight ahead.

Modifying a listener's properties works similarly to the way you change a sound source's properties. The function alListener is used and has variations depending on the property you are modifying. For example, to set the listener position you can call alListener3f and specify 3 separate floating point numbers or you could call alListenerfv and pass an array of floating point numbers. The parameters for the position are simply the x, y and z values for the listener in the game world. The orientation property however takes 6 parameters. The first 3 are for the vector that corresponds to what the user of listener is currently looking at. The next 3 are for the vector leading straight up from where the listener is facing. Here is an example of setting the listener position and orientation:

float listenerx, listenery, listenerz;
float vec[6];

listenerx=10.0f;
listenery=0.0f;
listenerz=5.0f;

vec[0] = fvecx; //forward vector x value
vec[1] = fvecy; //forward vector y value
vec[2] = fvecz; //forward vector z value
vec[3] = uvecx; //up vector x value
vec[4] = uvecy; //up vector y value
vec[5] = uvecz; //up vector z value

//set current listener position
alListener3f(AL_POSITION, listenerx, listenery, listenerz);

//set current listener orientation
alListenerfv(AL_ORIENTATION, vec);

In the first function call, 3 separate floating point numbers were passed for the x, y and z of the listener's position. For the second call, an array called vec is passed. This array is comprised of the six values for the two vectors dealing with the listener's orientation.

Playing Sounds

Once your sounds are loaded and you have set your listener properties you can then play your sounds. To do this you call the function alSourcePlay. This function takes a single parameter which is the source you want to play. To stop a sound you call the function alSourceStop which also takes the name of the source you want to stop. If you want your sound effect to loop such as if you have a sound of running water, you can set the looping property of the sound to true before playing the sound. Here is some sample code:

//tell the sound to loop continuously
alSourcei(alSource,AL_LOOPING,AL_TRUE);

//play the sound
alSourcePlay(alSource);

To stop the sound:

alSourceStop(alSource);

Cleaning Up

Once you are finished with your program you need to free up your sources and buffers and shut down OpenAL. The commands are relatively simple. Here is how to delete your sources and buffers:

//delete our source
alDeleteSources(1,&alSource);

//delete our buffer
alDeleteBuffers(1,&alSampleSet);

Here the first parameter for each is the number of buffers or sources to be deleted and the second is the buffer or source to be deleted. The last step is to close out OpenAL itself. This is done as follows:

//Get active context
Context=alcGetCurrentContext();

//Get device for active context
Device=alcGetContextsDevice(Context);

//Disable context
alcMakeContextCurrent(NULL);

//Release context(s)
alcDestroyContext(Context);

//Close device
alcCloseDevice(Device);

That's about it for playing basic sounds in OpenAL. The basic steps are to first initialize OpenAL, then load in whatever sounds you need, set the properties of the sounds and listener and then play the sounds. There is a lot more you can do with OpenAL but this was just written to describe some of the basics. The source code that comes along with this demonstrates the use of all of this in an OpenGL demo. In the demo, you control the listener and its position is set to your current position every loop. If you have any questions or comments, e-mail me at ricart3@tcnj.edu.

Download the source code for this article here.

Discuss this article in the forums

Date this article was posted to GameDev.net: 7/2/2003
(Note that this date does not necessarily correspond to the date the article was written)

See Also:
General
Sweet Snippets