The Developer’s Cry

 Yet another blog by a hobbyist programmer

OpenAL - sounds good!

For getting sound to work on the iPhone, I needed to acquaint myself with the OpenAL sound system. OpenAL is also particularly interesting because it is a 3D sound system. You set the position of a sound source, and OpenAL will take care of getting the volume just right, as well as the “position” of the sound where you are perceiving it to be coming from, when you hear it played on your surround set. It can also do cool things like the doppler effect. While I do not need 3D sound and just have started using OpenAL, it would certainly be cool to get some simple stereo sound effects in my game. This is something that SDL_mixer can not do.

OpenAL tutorials and ALUT

There are some nice tutorials on the web, and they all use ALUT. It turns out that ALUT had some (simple to resolve!) bugs in it, and some guys decided to mark it as deprecated. When standard C code gets marked as deprecated, gcc won’t compile it anymore. So, now all those nice online tutorials don’t work anymore. ALUT had two functions that were really convenient: alutInit() and alutLoadWAVFile(). Writing my own WAV loader took some time, but I managed, and initializing OpenAL properly takes some magic sequence, but read below about how that works.

Ubuntu Linux suxxors

First a sidestep from writing code; getting your system to work, and be able to produce sound at all. My favorite development platform is still Linux. For some reason, Ubuntu decided to break sound in version 8.10 (Intrepid) and I’ve been hassling with it for days to get some audio output out of my programs. At it turns out, Ubuntu Intrepid mixes asound (ALSA), esnd, and PulseAudio, with an apparent preference for PulseAudio, except that it’s not properly integrated or set up or whatever, it just doesn’t work in all cases. That’s right, one program seems to work, while others don’t. The solution: I removed all PulseAudio packages from my system, and installed their ALSA counterparts. (In fact, I compiled the mpd music player daemon by hand, because Ubuntu’s version tried to use PulseAudio anyway). After taking these drastic measures, my sound programs produced audio output, hurray!!

Initializing OpenAL

As said, we are going to have to do without ALUT. OpenAL needs to be initialized by creating a “context” and selecting the audio device, otherwise you will get nothing but errors. In some tutorials, I found that you may select “DirectSound3D” as a device, but that obviously only works on Windows. I have no clue what devices are available on Linux, MacOS X, or whatever other platform you may think of. Luckily, there is a way to get the default device.
I’ll share The Code with you:

#include "al.h"
#include "alc.h"

int init_openal(void) {
ALCcontext *context;
ALCdevice *device;
const ALCchar *default_device;

    default_device = alcGetString(NULL,
    ALC_DEFAULT_DEVICE_SPECIFIER);

    printf("using default device: %s\n", default_device);

    if ((device = alcOpenDevice(default_device)) == NULL) {
        fprintf(stderr, "failed to open sound device\n");
        return -1;
    }
    context = alcCreateContext(device, NULL);
    alcMakeCurrentContext(context);
    alcProcessContext(context);

    /* you may use alcGetError() at this point to see if everything is still OK */

    atexit(atexit_openal);

    /* allocate buffers and sources here using alGenBuffers() and alGenSources() */
    /* ... */

    alGetError(); /* clear any AL errors beforehand */
    return 0;
}

First a remark about the includes. Including the files "al.h" and "alc.h" is much more portable than using <AL/al.h> and <AL/alc.h>, and it saves you from resorting to "#ifdef PLATFORM_SO_AND_SO" constructs.
Using the default device may not always be the best choice. There should be an option in the program to let the user decide on what device to use.
Note the atexit() call; OpenAL will complain loudly when you exit the program without having cleaned up properly. It has a right to complain too; you’ve allocated some valuable hardware resources and it may be well possible that the operating system is not exactly babysitting this hardware, meaning that when you exit the program without releasing the allocated hardware buffers, they will remain as marked ‘in use’ until the computer is rebooted (!). A good atexit() handler frees the allocated resources and closes the sound device. 

/*
    OpenAL is very picky about leaving allocated buffers etc. behind
*/
void atexit_openal(void) {
ALCcontext *context;
ALCdevice *device;

    stop_openal_all();    /* stop all sound from playing */

    alDeleteSources(NUM_SOUNDS, snd_sources);
    alDeleteBuffers(NUM_SOUNDS, snd_buffers);

    context = alcGetCurrentContext();
    device = alcGetContextsDevice(context);

    alcMakeContextCurrent(NULL);
    alcDestroyContext(context);
    alcCloseDevice(device);
}

Mind the order in which to call OpenAL in the atexit handler, always first stop the sound, delete the sound sources, and then delete the buffers. Then move on to the context, and finally close the device. If you don’t do it in this order, the sound system will not be properly de-initialized.

Loading .WAV files

Loading WAV sound files is easy, although there is one big gotcha to it: it is a binary format, stored in little endian format. The intel x86 line of processors are all little endian, so no problem there. However, I like to write portable code, so this is a bit of fun. I have the pleasure of having access to a big endian machine, so I could test my WAVE loader code there, too. I came up with a very simple test too see if a machine is big or little endian:

#include <stdint.h>

int is_big_endian(void) {
    unsigned char test[4] = { 0x12, 0x34, 0x56, 0x78 };

    return *((uint32_t *)test) == 0x12345678;
}

The is_little_endian() function is left as an exercise to the reader.

Back to the WAVE loader, what I do is simply read the whole file into memory and then map a struct that represents the WAV header over it. Then I do the integer fixups (read as little endian values), and then perform some basic checks on whether this really was a good WAV file. For a music player, you should do these checks before loading the music data, but for my game code, I was happy with simply loading the file all at once.

You can find good information about the structure of a WAV file header on the web. Note how a WAVE loader is really a RIFF loader, and in my case, also a PCM sound loader.
There is a gotcha when blindly pouring the WAV header information into a struct, which is alignment. The compiler may mess around with the size of your struct … use pragma pack to instruct the compiler to refrain from doing that:

#pragma pack(1)
typedef struct {
    uint32_t Chunk_ID;
    uint32_t ChunkSize;
    ...
    uint16_t AudioFormat;
    ...
} WAV_header_t;
#pragma pack()

I’ve noticed that there are quite a few WAV files out there that have little mistakes in the headers, in particular the final field data_size (or subchunk2_size), which represents the length of the music data, is often wrong. The correct value is file size minus header size, and note that you can now ‘repair’ the WAV file.
Now that we’ve succeeded in loading the .WAV file, feed this data into alBufferData() and we’re ready to make some noise.

Closing remarks

In this blog entry I’ve shown how you can survive without ALUT. Although SDL_mixer happily handles .mp3s and many other formats, it doesn’t give you the stereo and 3D sound that OpenAL does. For OpenAL, you will need to write your own sample loader. Painful as it seems, it is really just a good exercise in handling data formats.
In the devmaster OpenAL tutorials they show how to stream Ogg Vorbis files through OpenAL. Be sure to read all their tutorials, they’re pretty straightforward once you’ve gotten through lesson 1. Also note how they rely on ALUT … forget about ALUT. Use OpenAL, it sounds good.