OpenAL Tutorial 1 - Single Static Source

From LWJGL
Revision as of 02:20, 8 December 2010 by JediTofu (Talk | contribs)

Jump to: navigation, search

Appendix A: Full Working Source Code


Welcome to the exciting world of OpenAL! OpenAL is still in a stage of growth, and even though there is an ever larger following to the API it still hasn't reached it's full potential. One of the big reasons for this is that there is still not yet hardware acceleration built in for specific cards. However, Creative Labs is a major contributor to the OpenAL project and also happens to be one of the largest soundcard manufacturers. So there is a promise of hardware accelerated features in the near future. OpenAL's only other major contributor, Loki, has gone the way of the dinosaur. So the future of OpenAL on Linux platforms is uncertain. You can still obtain the Linux binaries on some more obscure websites.


OpenAL has also not been seen in many major commercial products, which may have also hurt it's growth. As far as I know the only pc game to use OpenAL has been Metal Gear 2 (although recently I've discovered that Unreal 2 does as well). The popular modeling program, Blender3D, was also known to use OpenAL for all it's audio playback. Aside from these however the only other OpenAL uses have been in the sdk examples and a few obscure tutorials on the internet.


But lets face it, OpenAL has a lot of potential. There are many other audio libraries that claim to work with the hardware on a lower level (and this may be true), but the designers of OpenAL did several things in it's design which make it a superior API. First of all they emulated the OpenGL API which is one of the best ever designed. The API style is flexible, so different coding methods and hardware implementations will take advantage of this. People who have had a lot of experience with OpenGL will be able to pick up OpenAL quite fast. OpenAL also has the advantage of creating 3D surround sound which a lot of other API's cannot boast. On top of all of that it also has the ability to extend itself into EAX and AC3 flawlessly. To my knowledge no other audio library has that capability.


If you still haven't found a reason here to use OpenAL then here's another. It's just cool. It's a nice looking API and will integrate well into your code. You will be able to do many cool sound effects with it. But before we do that we have to learn the basics.


So let's get coding!


import java.io.IOException;
import java.nio.FloatBuffer;
import java.nio.IntBuffer;

import org.lwjgl.BufferUtils;
import org.lwjgl.LWJGLException;
import org.lwjgl.openal.AL;
import org.lwjgl.openal.AL10;
import org.lwjgl.util.WaveData;

public class Lesson1 {
  /** Buffers hold sound data. */
  IntBuffer buffer = BufferUtils.createIntBuffer(1);

  /** Sources are points emitting sound. */
  IntBuffer source = BufferUtils.createIntBuffer(1);


Those familiar with OpenGL know that it uses "texture objects" (or "texture names") to handle textures used by a program. OpenAL does a similar thing with audio samples. There are essentially 3 kinds of objects in OpenAL. A buffer which stores all the information about how a sound should be played and the sound data itself, and a source which is a point in space that emits a sound. It's important to understand that a source is not itself an audio sample. A source only plays back sound data from a buffer bound to it. The source is also given special properties like position and velocity.


The third object which I have not mentioned yet is the listener. There is only one listener which represents where 'you' are, the user. The listener properties along with the source properties determine how the audio sample will be heard. For example their relative positions will determine the intensity of the sound.


  /** Position of the source sound. */
  FloatBuffer sourcePos = BufferUtils.createFloatBuffer(3).put(new float[] { 0.0f, 0.0f, 0.0f });

  /** Velocity of the source sound. */
  FloatBuffer sourceVel = BufferUtils.createFloatBuffer(3).put(new float[] { 0.0f, 0.0f, 0.0f });

  /** Position of the listener. */
  FloatBuffer listenerPos = BufferUtils.createFloatBuffer(3).put(new float[] { 0.0f, 0.0f, 0.0f });

  /** Velocity of the listener. */
  FloatBuffer listenerVel = BufferUtils.createFloatBuffer(3).put(new float[] { 0.0f, 0.0f, 0.0f });

  /** Orientation of the listener. (first 3 elements are "at", second 3 are "up") */
  FloatBuffer listenerOri =
      BufferUtils.createFloatBuffer(6).put(new float[] { 0.0f, 0.0f, -1.0f,  0.0f, 1.0f, 0.0f });


In the above code we specify the position and velocity of the source and listener objects. These NIO Buffers are vector based Cartesian coordinates.


Note: LWJGL uses the position, limit and capacity properties of NIO buffers to determine where to index the data and how many elements to get/set. It is therefore crucial that these limits are set correctly. In the above case we would have to flip each of the buffers so their position and limit is set correctly. A newly created buffer will have its position set to 0 and its limit to its capacity.


  /**
   * boolean LoadALData()
   *
   *  This function will load our sample data from the disk using the Alut
   *  utility and send the data into OpenAL as a buffer. A source is then
   *  also created to play that buffer.
   */
  int loadALData() {


Here we will create a function that loads all of our sound data from a file.


Note: The original tutorial uses ALUT to load wave data. ALUT is not available in the LWJGL binding, due to license issues. You may use the WaveData class to load sound files instead.


    // Load wav data into a buffer.
    AL10.alGenBuffers(buffer);

    if(AL10.alGetError() != AL10.AL_NO_ERROR)
      return AL10.AL_FALSE;

    WaveData waveFile = WaveData.create("FancyPants.wav");
    AL10.alBufferData(buffer.get(0), waveFile.format, waveFile.data, waveFile.samplerate);
    waveFile.dispose();


The function 'alGenBuffers' will create the buffer objects and store them in the variable we passed it. It's important to do an error check to make sure everything went smoothly. There may be a case in which OpenAL could not generate a buffer object due to a lack of memory. In this case it would set the error bit.


The WaveData class is very helpful here. It opens up the file for us and gives us all the information we need to create the buffer. And after we have attached all this data to the buffer it will help use dispose of the data. It all works in a clean and efficient manner.


    // Bind the buffer with the source.
    AL10.alGenSources(source);

    if (AL10.alGetError() != AL10.AL_NO_ERROR)
      return AL10.AL_FALSE;

    AL10.alSourcei(source.get(0), AL10.AL_BUFFER,   buffer.get(0) );
    AL10.alSourcef(source.get(0), AL10.AL_PITCH,    1.0f          );
    AL10.alSourcef(source.get(0), AL10.AL_GAIN,     1.0f          );
    AL10.alSource (source.get(0), AL10.AL_POSITION, sourcePos     );
    AL10.alSource (source.get(0), AL10.AL_VELOCITY, sourceVel     );


We generate a source object in the same manner we generated the buffer object. Then we define the source properties that it will use when it's in playback. The most important of these properties is the buffer it should use. This tells the source which audio sample to playback. In this case we only have one so we bind it. We also tell the source it's position and velocity which we defined earlier.


One more thing on 'alGenBuffers' and 'alGenSources'. In some example code I have seen these functions will return an integer value for the number of buffers/sources created. I suppose this was meant as an error checking feature that was left out in a later version. If you see this done in other code don't use it yourself. If you want to do this check, use 'alGetError' instead (like we have done above).


    // Do another error check and return.
    if (AL10.alGetError() == AL10.AL_NO_ERROR)
      return AL10.AL_TRUE;

    return AL10.AL_FALSE;


To end the function we just do one more check to make sure all is well, then we return success.


  /**
   * void setListenerValues()
   *
   *  We already defined certain values for the Listener, but we need
   *  to tell OpenAL to use that data. This function does just that.
   */
  void setListenerValues() {
    AL10.alListener(AL10.AL_POSITION,    listenerPos);
    AL10.alListener(AL10.AL_VELOCITY,    listenerVel);
    AL10.alListener(AL10.AL_ORIENTATION, listenerOri);
  }


We created this function to update the listener properties.


  /**
   * void killALData()
   *
   *  We have allocated memory for our buffers and sources which needs
   *  to be returned to the system. This function frees that memory.
   */
  void killALData() {
    AL10.alDeleteSources(source);
    AL10.alDeleteBuffers(buffer);
  }


This will be our shutdown procedure. It is necessary to call this to release all the memory and audio devices that our program may be using.


  public static void main(String[] args) {
    new Lesson1().execute();
  }


This is our main entry point. We just create our Lesson1 instance and call the execute method.


  public void execute() {
    // Initialize OpenAL and clear the error bit.
    try{
    AL.create();
    } catch (LWJGLException le) {
    le.printStackTrace();
      return;
    }
    AL10.alGetError();


The function 'AL.create()' will setup everything that OpenAL needs to do for us. Basically 'AL.create()' creates a single OpenAL context through Alc and sets it to current. On the Windows platform it initializes DirectSound. We also do an initial call to the error function to clear it. Every time we call 'alGetError' it will reset itself to 'AL_NO_ERROR'.


    // Load the wav data.
    if(loadALData() == AL10.AL_FALSE) {
      System.out.println("Error loading data.");
      return;
    }

    setListenerValues();

We will check to see if the wav files loaded correctly. If not we must exit the program. Then we update the listener values.


    // Loop.
    char c = ' ';
    while(c != 'q') {
      try {
      c = (char) System.in.read();
      } catch (IOException ioe) {
      c = 'q';
      }

      switch(c) {
        // Pressing 'p' will begin playing the sample.
        case 'p': AL10.alSourcePlay(source.get(0)); break;

        // Pressing 's' will stop the sample from playing.
        case's': AL10.alSourceStop(source.get(0)); break;

        // Pressing 'h' will pause the sample.
        case 'h': AL10.alSourcePause(source.get(0)); break;
      };
    }
    killALData();
  }
}


This is the interesting part of the tutorial. It's a very basic loop that lets us control the playback of the audio sample. Pressing 'p' will replay the sample, pressing 's' will stop the sample, and pressing 'h' will pause the sample. Pressing 'q' will exit the program. When done, we kill all data loaded into buffers and delete any source objects created.


Well there it is. Your first delve into OpenAL. I hope it was made simple enough for you. It may have been a little too simple for the 1337 h4X0r, but we all got to start somewhere. Things will get more advanced as we go along.


Download source code and resources for this lesson here.



Credit

Author: Jesse Maurais

From: DevMaster.net

Modified to LWJGL: Brian Matzon



Appendix A: Full Working Source Code

Back to Top

import java.io.FileNotFoundException;
import java.io.IOException;
import java.nio.FloatBuffer;
import java.nio.IntBuffer;

import org.lwjgl.BufferUtils;
import org.lwjgl.LWJGLException;
import org.lwjgl.openal.AL;
import org.lwjgl.openal.AL10;
import org.lwjgl.util.WaveData;

public class Lesson1 {
  /** Buffers hold sound data. */
  IntBuffer buffer = BufferUtils.createIntBuffer(1);

  /** Sources are points emitting sound. */
  IntBuffer source = BufferUtils.createIntBuffer(1);

  /** Position of the source sound. */
  FloatBuffer sourcePos = (FloatBuffer)BufferUtils.createFloatBuffer(3).put(new float[] { 0.0f, 0.0f, 0.0f }).rewind();

  /** Velocity of the source sound. */
  FloatBuffer sourceVel = (FloatBuffer)BufferUtils.createFloatBuffer(3).put(new float[] { 0.0f, 0.0f, 0.0f }).rewind();

  /** Position of the listener. */
  FloatBuffer listenerPos = (FloatBuffer)BufferUtils.createFloatBuffer(3).put(new float[] { 0.0f, 0.0f, 0.0f }).rewind();

  /** Velocity of the listener. */
  FloatBuffer listenerVel = (FloatBuffer)BufferUtils.createFloatBuffer(3).put(new float[] { 0.0f, 0.0f, 0.0f }).rewind();

  /** Orientation of the listener. (first 3 elements are "at", second 3 are "up") */
  FloatBuffer listenerOri = (FloatBuffer)BufferUtils.createFloatBuffer(6).put(new float[] { 0.0f, 0.0f, -1.0f,  0.0f, 1.0f, 0.0f }).rewind();

  /**
  * boolean LoadALData()
  *
  *  This function will load our sample data from the disk using the Alut
  *  utility and send the data into OpenAL as a buffer. A source is then
  *  also created to play that buffer.
  */
  int loadALData() {
    // Load wav data into a buffer.
    AL10.alGenBuffers(buffer);

    if(AL10.alGetError() != AL10.AL_NO_ERROR)
      return AL10.AL_FALSE;

    //Loads the wave file from your file system
    /*java.io.FileInputStream fin = null;
    try {
      fin = new java.io.FileInputStream("FancyPants.wav");
    } catch (java.io.FileNotFoundException ex) {
      ex.printStackTrace();
      return AL10.AL_FALSE;
    }
    WaveData waveFile = WaveData.create(fin);
    try {
      fin.close();
    } catch (java.io.IOException ex) {
    }*/

    //Loads the wave file from this class's package in your classpath
    WaveData waveFile = WaveData.create("FancyPants.wav");

    AL10.alBufferData(buffer.get(0), waveFile.format, waveFile.data, waveFile.samplerate);
    waveFile.dispose();

    // Bind the buffer with the source.
    AL10.alGenSources(source);

    if (AL10.alGetError() != AL10.AL_NO_ERROR)
      return AL10.AL_FALSE;

    AL10.alSourcei(source.get(0), AL10.AL_BUFFER,   buffer.get(0) );
    AL10.alSourcef(source.get(0), AL10.AL_PITCH,    1.0f          );
    AL10.alSourcef(source.get(0), AL10.AL_GAIN,     1.0f          );
    AL10.alSource (source.get(0), AL10.AL_POSITION, sourcePos     );
    AL10.alSource (source.get(0), AL10.AL_VELOCITY, sourceVel     );

    // Do another error check and return.
    if (AL10.alGetError() == AL10.AL_NO_ERROR)
      return AL10.AL_TRUE;

    return AL10.AL_FALSE;
  }

  /**
   * void setListenerValues()
   *
   *  We already defined certain values for the Listener, but we need
   *  to tell OpenAL to use that data. This function does just that.
   */
  void setListenerValues() {
    AL10.alListener(AL10.AL_POSITION,    listenerPos);
    AL10.alListener(AL10.AL_VELOCITY,    listenerVel);
    AL10.alListener(AL10.AL_ORIENTATION, listenerOri);
  }

  /**
   * void killALData()
   *
   *  We have allocated memory for our buffers and sources which needs
   *  to be returned to the system. This function frees that memory.
   */
  void killALData() {
    AL10.alDeleteSources(source);
    AL10.alDeleteBuffers(buffer);
  }

  public static void main(String[] args) {
    new Lesson1().execute();
  }

  public void execute() {
    // Initialize OpenAL and clear the error bit.
    try{
      AL.create();
    } catch (LWJGLException le) {
      le.printStackTrace();
      return;
    }
    AL10.alGetError();

    // Load the wav data.
    if(loadALData() == AL10.AL_FALSE) {
      System.out.println("Error loading data.");
      return;
    }

    setListenerValues();

    // Loop.
    System.out.println("OpenAL Tutorial 1 - Single Static Source");
    System.out.println("[Menu]");
    System.out.println("p - Play the sample.");
    System.out.println("s - Stop the sample.");
    System.out.println("h - Pause the sample.");
    System.out.println("q - Quit the program.");
    char c = ' ';
    while(c != 'q') {
      try {
        System.out.print("Input: ");
        System.out.flush();
        c = (char) System.in.read();
        System.in.read(); //Read new line
      } catch (IOException ioe) {
        c = 'q';
      }

      switch(c) {
        // Pressing 'p' will begin playing the sample.
        case 'p': AL10.alSourcePlay(source.get(0)); break;

        // Pressing 's' will stop the sample from playing.
        case's': AL10.alSourceStop(source.get(0)); break;

        // Pressing 'h' will pause the sample.
        case 'h': AL10.alSourcePause(source.get(0)); break;
      };
    }
    killALData();
  }
}

Back to Top