Blogged by buffi

I haven’t been able to find a single line of online documenting how the effects extension for OpenAL on OS X should be used, so I thought I’d write a short summary here since I had a bunch of issues getting started with it.

First of all, if you are going to develop ANYTHING using OpenAL and Cocoa, download the following example from Apple.

OpenALExample

This is pretty much the only thing to get you started, and it includes most of the OpenAL functionalities that you’ll want to use. I made the mistake of trying to find docs for the effects extension instead of just looking through this source, and failed miserably. Lacking docs, I took a look at the header which contains some information about enabling reverb and other effects. Unfortunately, some of the inline documentation in this code is currently incorrect.

The row stating

 #define ALC_ASA_REVERB_ON 'rvon' // type ALboolean.

should say

 #define ALC_ASA_REVERB_ON 'rvon' // type UInt32.

Trying to use an ALboolean when enabling the reverb wont work (it expects UInt32). I filed a bug report for this, so hopefully it’ll be fixed eventually.

The header also references several methods which doesn’t seem to exist, so instead do the following to enable reverb/occlusion/obstruction.

I should mention that the following code assumes you already have OpenAL working and are just missing the effects.

Step 1
Include the effects header

#import <OpenAL/MacOSX_OALExtensions.h>

Step 2
Paste these functions from OpenALExample into your source file (or in a header which you’ll #import)

OSStatus  alcASASetSourceProc(const ALuint property, ALuint source, ALvoid *data, ALuint dataSize)
{
    OSStatus    err = noErr;
    static  alcASASetSourceProcPtr  proc = NULL;

    if (proc == NULL) {
        proc = (alcASASetSourceProcPtr) alcGetProcAddress(NULL, (const ALCchar*) "alcASASetSource");
    }   

    if (proc)
        err = proc(property, source, data, dataSize);
    return (err);
}

OSStatus  alcASASetListenerProc(const ALuint property, ALvoid *data, ALuint dataSize)
{
    OSStatus    err = noErr;
    static  alcASASetListenerProcPtr    proc = NULL;

    if (proc == NULL) {
        proc = (alcASASetListenerProcPtr) alcGetProcAddress(NULL, "alcASASetListener");
    }   

    if (proc)
        err = proc(property, data, dataSize);
    return (err);
}

Step 3 (for reverb)
The function calls below will enable reverb for a source (with id sourceId).

UInt32 reverbOn = 1;
alcASASetListenerProc(alcGetEnumValue(NULL,
    "ALC_ASA_REVERB_ON"), &reverbOn, sizeof(reverbOn));

ALfloat level = 1.0; // How much reverb you want for your source.
alcASASetSourceProc(alcGetEnumValue(NULL,
    "ALC_ASA_REVERB_SEND_LEVEL"), sourceId, &level, sizeof(level));

// Theres a bunch of predefined room types in MacOSX_OALExtensions.h
ALint roomType = ALC_ASA_REVERB_ROOM_TYPE_SmallRoom;
alcASASetListenerProc(alcGetEnumValue(NULL,
    "ALC_ASA_REVERB_ROOM_TYPE"), &roomType, sizeof(roomType));

Occlusion and obstructions work exactly the same, but using other constants from MacOSX_OALExtensions.h (have a look inside OpenALExample if you don’t understand which one to use).

I’m not sure anyone will see this and have any use of it, but I know seeing a quick summary like this would have saved me some time so here it is…

buffi Cocoa, Programming & scripting Cocoa, Core Audio, OpenAL