Linux DevCenter    
 Published on Linux DevCenter (http://www.linuxdevcenter.com/)
 See this if you're having trouble printing code examples


OpenAL Development: The Programmer's View

by Dave Phillips
10/13/2000

Related Articles:

OpenAL Explained

What Is This 3D Audio Business?

OpenAL Applications: The User's View


Previous Features

More from the Linux DevCenter

The OpenAL project employs the two mainstays of all successful open source projects: a very active mailing list and a CVS source code repository. Loki Entertainment sponsors the CVS site and its own OpenAL newsgroup, while the OpenAL web site provides contact and sign-up information for the mailing list. Occasional development snapshots of code sources are available from the OpenAL web site, but to stay current, you should download and build the sources from the CVS site. If you've never downloaded from a CVS source code repository, have no fear; the site includes complete instructions for retrieving the files you need.

Developers will be especially interested in the XLDEMO example program included with the OpenAL source package. It provides a simple demonstration of the basic use of the library, with particular emphasis on the relationship between OpenGL graphics and OpenAL audio. Of course, to do anything with the OpenAL API, you need to retrieve, build, and install the library source code.

Enter your home directory, fire up your Internet connection, and log on to Loki's CVS site. Follow the instructions given there to download from the repository. If all goes well, you should have a new directory containing the source code for builds of the OpenAL library for Windows, the Mac OS, Linux, and BeOS. Enter it, read the text files, and move into the directory for your platform of choice.

Note: The following instructions apply only to the Linux build of the OpenAL library. Please see the documentation in your platform's directory for instructions specific to your system.

From your $HOME/openal/linux directory, run ./autogen.sh to generate the configure script, then run ./configure --help for a list of configuration options. The list is extensive, but it is recommended that you start with only the --enable-debug and --enable-optimization options. Most of the other options are either debug or audio library flags (the kernel sound drivers, OSS/Linux, ALSA, ESD, and WAV output are all supported, but in varying degrees of completeness). Now run ./configure --enable-debug --enable-optimization. If no errors are reported, run make and (as root) make install. You should now have the libopenal.so shared library in /usr/local/lib, and you should also have a new /usr/local/include/AL headers directory. The configuration is not complicated, and the sources compiled cleanly with the default libraries on my Red Hat 6.1 system.

After installing the library, move into the openal/demos/XLDEMO/ directory. Read the README file for general instructions for building the demo on your platform (Windows, Linux, or Mac; sorry, no demo for BeOS yet).

To build the Linux version of the demo, enter openal/demos/XLDEMO/linux and read the Makefile to find what dependencies must be resolved. As well as having libopenal installed, you'll need the OpenGL or the Mesa libraries and include files. You'll also need the GLUT library and headers. All other required libraries and headers should be included with any mainstream Linux distribution.

If your system meets the requirements, the demo should build quickly. Before running it, copy the *.mdl, *.wav, and *.pcm files from openal/demos/XLDEMO/COMMON into the Linux demo directory. Make sure your sound system is turned on, then start an X session and open an xterm window. Move to the directory where you built the demo and type in ./xldemo. The scene in Figure 1 should appear.

Screen shot of xldemo.

Figure 1: The xldemo opening scene.

Your starting position is the camera or viewer's position in the OpenGL 3D visual field. You are also the listener in OpenAL's 3D audio field, so where the camera goes, so goes the listener. All other objects (visual and audio) are rendered relative to your position. In Figure 1, the object at the center is a beacon that emits a radar beep following the arc of the broadcast beam. The objects seen at the far left and in the back are vehicles that traverse the area enclosed by the walls. The viewer moves around the space by using the arrow keys and the 'z' and 'x' keys. Note the dynamic activity of each object's sounds as you approach, follow, and leave them. The proximity effects are very striking.

The code that creates these effects can be found in the openal/demos/XLDEMO/COMMON and openal/demos/XLDEMO/linux directories. An audiovisual environment object (AVEnvironment in xlmain.cpp) is created in the main loop. The AVEnvironment object is constantly updated with the current position of the viewer and the other objects moving around the virtual world. The OpenGL display updates and the OpenAL audio updates use the same type of mechanisms to create a seamless integration of the movement of the sound and graphics. On the next page we'll take a closer look at how that works....

An example: coding an object for movement and sound, part 1

Before delving into some source code, let's take a quick look at the basic services provided by the OpenAL programming interface. The API describes a collection of library services including listener and sound source orientation, a sample data specification, and an I3DL2-compliant reverberation environment description (I3DL2 is the IASIG 3D audio Level 2 specification). Loki's implementation of the API includes resource configuration scripting and functional extensibility via plugins.

All actions performed by the library work upon objects known as Buffers, Sources, Context, and Listeners. Buffers hold the actual audio data and its format characteristics (such as sample rate and length). However, a Buffer can not be played directly: it must be bound to a Source (a Source can be played), and multiple Sources can simultaneously share access to a single Buffer. At least one Context object must be created before calling any library functions: Context handles the actual audio device interface for the library, and thus for the application as well.

Incidentally, supported audio devices for Linux currently include OSS/Free (/dev/dsp), ESD (the Enlightened Sound Daemon), ALSA (the Advanced Linux Sound Architecture), SDL (the Simple DirectMedia Layer), aRts (a realtime sound synthesis environment), and WAV file output.

Each object includes attributes for the dynamic modification of a sound's perceived location and movement within a changing environment. The Listener object is the sample position within a given Context, receiving and interpreting data from multichannel audio streams generated by Sources. Its parameter list includes these attributes:

The Source object contains these attributes:

As might be expected, the Buffer object includes the variables describing the sample data:

Now that we've met our objects, let's see how they're employed in a real code example on the next page.

An example: coding an object for movement and sound, part 2

The xldemo program illustrates the basic use of OpenAL. A scene is created that includes two stationary objects (houses), two moving objects with fixed paths (a car and a van), and one freely moving object (the listener, i.e., you). The Linux version of the xldemo program is built from the Linux-specific sources in openal/demos/XLDEMO/linux and the shared sources in the openal/demos/XLDEMO/COMMON directory. Let's take a closer look into those sources to watch OpenAL at work.

Note: Code comments preceded by "tsao" are by Joseph I. Valenzuela. The author is especially indebted to Mr. Valenzuela for his assistance with this section.

In the Linux directory, xlmain.cpp sets up OpenGL/OpenAL and starts the main program loop. Looking into the code, we first see some standard includes (such as stdlib.h and sys/time.h) declared along with these files:

#include "GL/glut.h"  
  // sets up OpenGL 
#include "../COMMON/common.h"
  // defines the AVEnvironment class
#include "../COMMON/audioenv.h"
  // defines the audio environment class

The AVEnvironment class includes items such as window height and width, camera/listener angles and positions, and the named objects in the virtual environment (Sky, Ground, CarList, etc). It also references functions such as PlaceCamera and ChangeView (both found in xlmain.cpp). The audio environment class contains functions for loading and playing sound files, starting and stopping playback, and managing the positions of Sources and Listener.

Both common.h and audioenv.h include xlheader.h, which in turn calls the OpenAL headers -- view this section of code here.

Now let's look at audioenv.cpp in the openal/demos/XLDEMO/COMMON directory. View that code here.

These code fragments include most of the OpenAL calls used in the xldemo program. As you can see, quite a lot gets done by not a lot of code. The OpenAL API functions take care of the gritty details, freeing the programmer from considerable tedious calculations. Furthermore, both OpenGL and OpenAL share the same mechanisms for determining the camera/listener position, velocity, angle, etc., all of which get updated simultaneously for visuals and audio, but I leave that investigation to the motivated reader. More examples of interesting OpenAL code can be found in the sources to the Chromium BSU game and the excellent tutorial by Fotis Hadginikos.

Dave Phillips maintains the Linux Music & Sound Applications Web site and has been a performing musician for more than 30 years.


Discuss this article in the O'Reilly Network Linux Forum.

Return to the Linux DevCenter.

 

Copyright © 2009 O'Reilly Media, Inc.