OpenAL Tutorial
(by Brian Matzon <brian@matzon.dk>)
1.0 OpenAL Basics
Before embarking on our little OpenAL adventure, some tools are needed.
1.0.1 Ingredients
Head on over to Creatives site
and snag a copy of the OpenAL specification along with a copy of the Programmers
reference.
If you haven't already done so, get a copy of the OpenAL runtime environment
too (and install it).
1.1 OpenAL theory
Uhm... I'm not going to write this... In all honesty reading the specification
would be a good thing before continuing - but it isn't required...
1.2 Basic setup
Lets start out by creating a skeleton class for some very basic sound. We'll
start of by creating the required OpenAL object
import
org.lwjgl.openal.AL;
public class PlayTest {
/** OpenAL instance */
protected AL al;
/**
* Creates an instance of PlayTest
*/
public PlayTest() {
try {
al = new AL();
al.create();
} catch (Exception e) {
e.printStackTrace();
}
}
}
1.3 Buffer and Source creation
Now that we have created the AL instance, we need to create
two things to actually get some sound. We need to create a buffer to hold
sound data, and a source that is to play the sound data.
Lets start of by creating one source, and one buffer:
//create one IntBuffer as buffer and one as source
//createIntBuffer is a utility method which allocates a direct ByteBuffer in native order
IntBuffer buffers = createIntBuffer(1);
IntBuffer sources = createIntBuffer(1);
//generate buffers and sources
al.genBuffers(1, Sys.getDirectBufferAddress(buffers));
al.genSources(1, Sys.getDirectBufferAddress(sources));
There, all set for actually loading some sound data into the buffer.
1.4 Loading sound data and setting up a buffer
Now that we have a buffer, we need to load some sound data into this buffer.
This is done using the al.bufferData method. In our example we will
"cheat" a bit, by using the WaveData class to load
a wave file, and copy this into the buffer:
//load wave data
WaveData wavefile = WaveData.create("mywavefile.wav");
//copy to buffer
al.bufferData(buffers.get(0), wavefile.format, Sys.getDirectBufferAddress(wavefile.data), wavefile.data.capacity(), wavefile.samplerate);
//unload file again
wavefile.dispose();
Having loaded the data, we pass it to bufferData. Once the buffer
has been filled with sound data, we unload it from the system using wavefile.dispose().
Don't worry about deleting it this soon - the sound data has been copied
to the buffer.
1.5 Associating sources and buffers
To associate a source to a buffer we set the integer BUFFER attribute on
the source, and assign it a value of the buffer to play:
//set up source input
al.sourcei(sources.get(0), AL.BUFFER, buffers.get(0));
1.6 Setting source properties
Having set up the source, it is time to set some attributes on the source
- there are many that can be set, but in this example we only set the looping
attribute to true by doing the following:
//loop source
al.sourcei(sources.get(0), AL.LOOPING, AL.TRUE);
1.7 Sound...
There, ready to play the sound, do this using the sourcePlay method
of the AL class. to stop and pause use sourcePause and
sourceStop respectively, and supply the source to affect:
//play source 0
al.sourcePlay(sources.get(0));
//wait 5 secs
try {
System.out.println("Waiting 5 seconds for sound to complete");
Thread.sleep(5000);
} catch (InterruptedException inte) {
}
//stop source 0
al.sourceStop(sources.get(0));
1.8 Cleaning up
Having had loads of fun playing a sound (!), it is now time to do some
house chores. We need to clean up what we have created, this amounts to:
- deleting source and buffer
- destroying AL
as is shown here:
//delete buffers and sources
al.deleteSources(1, Sys.getDirectBufferAddress(sources));
al.deleteBuffers(1, Sys.getDirectBufferAddress(buffers));
//shutdown
al.destroy();
There, all set. Now you should be able to play some basic sound!
This tutorial is rather short, and the above examples feature no error checking.
For the complete source code, look at the classes in the
org.lwjgl.test.openal package.