# OpenAL Tutoral
Basic sound using OpenAL
Author: Brian Matzon

# 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.