updates to openalbridge (modified api and simplified some sections)
authorkoda
Mon, 19 Apr 2010 15:30:11 +0000 (2010-04-19)
changeset 3360 717b4e46e855
parent 3359 d17b9f6adae5
child 3361 cfc6cd502f85
updates to openalbridge (modified api and simplified some sections)
misc/openalbridge/globals.h
misc/openalbridge/loaders.c
misc/openalbridge/openalbridge.c
misc/openalbridge/openalbridge.h
--- a/misc/openalbridge/globals.h	Mon Apr 19 13:31:08 2010 +0000
+++ b/misc/openalbridge/globals.h	Mon Apr 19 15:30:11 2010 +0000
@@ -140,11 +140,6 @@
 #define WAV_FILE_FORMAT 0x52494646
 #define WAV_HEADER_SUBCHUNK2ID 0x64617461
     
-    
-    /*other defines*/
-#define FADE_IN  0
-#define FADE_OUT 1
-    
     char *prog;
     
 #ifdef __CPLUSPLUS
--- a/misc/openalbridge/loaders.c	Mon Apr 19 13:31:08 2010 +0000
+++ b/misc/openalbridge/loaders.c	Mon Apr 19 15:30:11 2010 +0000
@@ -154,7 +154,7 @@
         /*ogg handle*/
         FILE *oggFile;
         /*stream handle*/
-        OggVorbis_File  oggStream; 
+        OggVorbis_File oggStream; 
         /*some formatting data*/
         vorbis_info *vorbisInfo; 
         /*length of the decoded data*/
@@ -173,7 +173,7 @@
             errno = EINVAL;
             err_ret("(%s) ERROR - ov_fopen() failed with %X", prog, result);
             ov_clear(&oggStream);
-            return AL_FALSE;
+            return -1;
         }
         
         /*load OGG header and determine the decoded data size*/
@@ -209,7 +209,7 @@
                 errno = EILSEQ;
                 err_ret("(%s) ERROR - wrong OGG header [channel %d]", prog, vorbisInfo->channels);
                 ov_clear(&oggStream);
-                return AL_FALSE;
+                return -1;
             }
         }
         
@@ -231,19 +231,19 @@
                     errno = EILSEQ;
                     err_ret("(%s) ERROR - End of file from OGG stream", prog);
                     ov_clear(&oggStream);
-                    return AL_FALSE;
+                    return -1;
                 }
             }
         }
         
         /*set the last fields*/
         *bitsize = size;
-        *freq    = vorbisInfo->rate;
+        *freq = vorbisInfo->rate;
         
-        /*cleaning time*/
+        /*cleaning time (ov_clear also closes file handler)*/
         ov_clear(&oggStream);
-        
-        return AL_TRUE;
+
+        return 0;
     }
     
 #ifdef __CPLUSPLUS
--- a/misc/openalbridge/openalbridge.c	Mon Apr 19 13:31:08 2010 +0000
+++ b/misc/openalbridge/openalbridge.c	Mon Apr 19 15:30:11 2010 +0000
@@ -34,8 +34,74 @@
     ALuint globalindex, globalsize, increment;
     
     ALboolean openalReady = AL_FALSE;
-    
-    ALboolean openal_close (void) {
+    ALfloat old_gain;
+
+    ALboolean openal_init(ALboolean usehardware, int memorysize) {	
+        /*Initialize an OpenAL contex and allocate memory space for data and buffers*/
+        ALCcontext *context;
+        ALCdevice *device;
+        const ALCchar *default_device;
+        
+        prog = "OpenAL subsystem";
+
+	// set the memory dimentsion and the increment width when reallocating
+        if (memorysize <= 0)
+            globalsize = 50;
+        else
+            globalsize = memorysize;
+        increment = globalsize;
+        
+	// reuse old context but keep the new value for increment
+        if (openalReady == AL_TRUE) {
+            err_msg("(%s) WARN - already initialized", prog);
+            return AL_FALSE;
+        }
+        
+        if (usehardware == AL_TRUE)
+            device = alcOpenDevice(NULL);
+        else
+            device = alcOpenDevice("Generic Software");
+        
+        err_msg("(%s) INFO - Output device: %s", prog, alcGetString(device, ALC_DEVICE_SPECIFIER));
+        
+	if (device == NULL) {
+            errno = ENODEV;                
+            err_ret("(%s) WARN - failed to open sound device", prog);
+            return AL_FALSE;
+        }
+	
+        context = alcCreateContext(device, NULL);
+        alcMakeContextCurrent(context);
+        alcProcessContext(context);
+        
+        if (AlGetError("(%s) WARN - Failed to create a new contex") != AL_TRUE)
+            return AL_FALSE;
+        
+        // allocate memory space for buffers and sources
+        Buffers = (ALuint*) Malloc(sizeof(ALuint)*globalsize);
+        Sources = (ALuint*) Malloc(sizeof(ALuint)*globalsize);
+        
+        // set the listener gain, position (on xyz axes), velocity (one value for each axe) and orientation
+	// Position, Velocity and Orientation of the listener
+        ALfloat ListenerPos[] = {0.0, 0.0, 0.0};
+        ALfloat ListenerVel[] = {0.0, 0.0, 0.0};
+        ALfloat ListenerOri[] = {0.0, 0.0, -1.0,  0.0, 1.0, 0.0};
+
+        alListenerf (AL_GAIN,        1.0f       );
+        alListenerfv(AL_POSITION,    ListenerPos);
+        alListenerfv(AL_VELOCITY,    ListenerVel);
+        alListenerfv(AL_ORIENTATION, ListenerOri);
+        
+        if (AlGetError("(%s) WARN - Failed to set Listener properties") != AL_TRUE)
+            return AL_FALSE;
+        
+        openalReady = AL_TRUE;
+        
+        alGetError();  // clear any AL errors beforehand
+        return AL_TRUE;
+    }
+
+    void openal_close (void) {
         /*Stop all sounds, deallocate all memory and close OpenAL */
         ALCcontext *context;
         ALCdevice  *device;
@@ -43,7 +109,7 @@
         if (openalReady == AL_FALSE) {
             errno = EPERM;
             err_ret("(%s) WARN - OpenAL not initialized", prog);
-            return AL_FALSE;
+            return;
         }
         
         alSourceStopv	(globalsize, Sources);
@@ -62,7 +128,7 @@
         
         openalReady = AL_FALSE;
         
-        err_msg("(%s) INFO - OpenAL closed", prog);
+        err_msg("(%s) INFO - closed", prog);
         
         return AL_TRUE;
     }
@@ -71,74 +137,8 @@
         return openalReady;
     }
     
-    ALboolean openal_init(char* programname, ALboolean usehardware, uint32_t memorysize) {	
-        /*Initialize an OpenAL contex and allocate memory space for data and buffers*/
-        ALCcontext *context;
-        ALCdevice *device;
-        const ALCchar *default_device;
-        
-        prog = programname;
-        
-        /*Position of the listener*/
-        ALfloat ListenerPos[] = { 0.0, 0.0, 0.0 };
-        /*Velocity of the listener*/
-        ALfloat ListenerVel[] = { 0.0, 0.0, 0.0 };
-        /*Orientation of the listener. (first 3 elements are "at", second 3 are "up")*/
-        ALfloat ListenerOri[] = { 0.0, 0.0, -1.0,  0.0, 1.0, 0.0 };
-        
-        if (openalReady == AL_TRUE) {
-            errno = EPERM;                
-            err_ret("(%s) WARN - OpenAL already initialized", prog);
-            return AL_FALSE;
-        }
-        
-        if (usehardware == AL_TRUE) {
-            default_device = alcGetString(NULL, ALC_DEFAULT_DEVICE_SPECIFIER);
-            device = alcOpenDevice(default_device);
-        } else
-            device = alcOpenDevice("Generic Software");
-        
-        if (device == NULL) {
-            errno = ENODEV;                
-            err_ret("(%s) WARN - Failed to open sound device", prog);
-            return AL_FALSE;
-        }
-        err_msg("(%s) INFO - Output device: %s", prog, alcGetString(device, ALC_DEVICE_SPECIFIER));
-        
-        context = alcCreateContext(device, NULL);
-        alcMakeContextCurrent(context);
-        alcProcessContext(context);
-        
-        if (AlGetError("(%s) WARN - Failed to create a new contex") != AL_TRUE)
-            return AL_FALSE;
-        
-        /*allocate memory space for buffers and sources*/
-        if (memorysize == 0)
-            globalsize = 50;
-        else
-            globalsize = memorysize;
-        increment  = globalsize;
-        
-        Buffers = (ALuint*) Malloc(sizeof(ALuint)*globalsize);
-        Sources = (ALuint*) Malloc(sizeof(ALuint)*globalsize);
-        
-        /*set the listener gain, position (on xyz axes), velocity (one value for each axe) and orientation*/
-        alListenerf (AL_GAIN,        1.0f       );
-        alListenerfv(AL_POSITION,    ListenerPos);
-        alListenerfv(AL_VELOCITY,    ListenerVel);
-        alListenerfv(AL_ORIENTATION, ListenerOri);
-        
-        if (AlGetError("(%s) WARN - Failed to set Listener properties") != AL_TRUE)
-            return AL_FALSE;
-        
-        openalReady = AL_TRUE;
-        
-        alGetError();  /* clear any AL errors beforehand */
-        return AL_TRUE;
-    }
     
-    
-    ALboolean helper_realloc (void) {
+    void helper_realloc (void) {
         /*expands allocated memory when loading more sound files than expected*/
         int oldsize = globalsize;
         globalsize += increment;
@@ -148,11 +148,11 @@
         Buffers = (ALuint*) Realloc(Buffers, sizeof(ALuint)*globalsize);
         Sources = (ALuint*) Realloc(Sources, sizeof(ALuint)*globalsize);
         
-        return AL_TRUE;
+        return;
     }
     
     
-    ALint openal_loadfile (const char *filename){
+    int openal_loadfile (const char *filename){
         /*Open a file, load into memory and allocate the Source buffer for playing*/
         ALfloat SourcePos[] = { 0.0, 0.0, 0.0 }; /*Position of the source sound*/
         ALfloat SourceVel[] = { 0.0, 0.0, 0.0 }; /*Velocity of the source sound*/
@@ -164,9 +164,8 @@
         FILE *fp;
         
         if (openalReady == AL_FALSE) {
-            errno = EPERM;                
-            err_ret("(%s) WARN - OpenAL not initialized", prog);
-            return AL_FALSE;
+            err_msg("(%s) WARN - not initialized", prog);
+            return -1;
         }
         
         /*when the buffers are all used, we can expand memory to accept new files*/
@@ -177,28 +176,27 @@
         fp = Fopen (filename, "rb");
         
         if (fp == NULL)
-            return -1;
+            return -2;
         
         error = fread (&fileformat, sizeof(uint32_t), 1, fp);
         fclose (fp);
         
         if (error < 0) {
-            errno = EIO;
-            err_ret("(%s) ERROR - File %s is too short", prog, filename);
-            return -2;
+            err_msg("(%s) ERROR - File %s is too short", prog, filename);
+            return -3;
         }
         
         /*prepare the buffer to receive data*/
         alGenBuffers(1, &Buffers[globalindex]);
         
         if (AlGetError("(%s) ERROR - Failed to allocate memory for buffers") != AL_TRUE)
-            return -3;
+            return -4;
         
         /*prepare the source to emit sound*/
         alGenSources(1, &Sources[globalindex]);
         
         if (AlGetError("(%s) ERROR - Failed to allocate memory for sources") != AL_TRUE)
-            return -4;
+            return -5;
         
         
         switch (ENDIAN_BIG_32(fileformat)) {
@@ -209,9 +207,8 @@
                 error = load_wavpcm (filename, &format, &data, &bitsize, &freq);
                 break;
             default:
-                errno = EINVAL;
-                err_ret ("(%s) ERROR - File format (%08X) not supported", prog, ENDIAN_BIG_32(fileformat));
-                return -5;
+                err_msg ("(%s) ERROR - File format (%08X) not supported", prog, ENDIAN_BIG_32(fileformat));
+                return -6;
                 break;
         }
         
@@ -241,105 +238,84 @@
     }
     
     
-    ALboolean openal_toggleloop (uint32_t index){
-        /*Set or unset looping mode*/
-        ALint loop;
-        
-        if (openalReady == AL_FALSE) {
-            errno = EPERM;                
-            err_ret("(%s) WARN - OpenAL not initialized", prog);
-            return AL_FALSE;
-        }
-        
-        if (index >= globalsize) {
-            errno = EINVAL;
-            err_ret("(%s) ERROR - Index out of bounds (got %d, max %d)", prog, index, globalindex);
-            return AL_FALSE;
-        }
-        
-        alGetSourcei (Sources[index], AL_LOOPING, &loop);
-        alSourcei (Sources[index], AL_LOOPING, !((uint8_t) loop) & 0x00000001);
-        if (AlGetError("(%s) ERROR - Failed to get or set loop property") != AL_TRUE)
-            return AL_FALSE;
-        
-        alGetError();  /* clear any AL errors beforehand */
-        
-        return AL_TRUE;
+    void openal_playsound (uint32_t index) {
+        openal_playsound_loop (index, 0);
+    }
+    
+    
+    void openal_pausesound (uint32_t index) {
+        if (openalReady == AL_TRUE && index < globalsize)
+            alSourcePause(Sources[index]);
     }
     
     
-    ALboolean openal_setvolume (uint32_t index, uint8_t percentage) {
-        if (openalReady == AL_FALSE) {
-            errno = EPERM;                
-            err_ret("(%s) WARN - OpenAL not initialized", prog);
-            return AL_FALSE;
-        }
+    void openal_stopsound (uint32_t index) {
+        openal_stopsound_free(index, 0);
+    }
+    
+
+    void openal_freesound (uint32_t index){
+       if (openalReady == AL_TRUE && index < globalsize)
+            alSourceStop(Sources[index]);
+           // STUB
+    }
+
+
+    void openal_playsound_loop (unsigned int index, char loops) {
+	if (openalReady == AL_TRUE && index < globalsize) {
+            alSourcePlay(Sources[index]);
+	    if (loops != 0)
+                openal_toggleloop(index);
+	}
+    }
+
+    void openal_stopsound_free    (unsigned int index, char freesource) {
+        if (openalReady == AL_TRUE && index < globalsize) {
+            alSourceStop(Sources[index]);
+	    if (freesource != 0)
+	        openal_freesound(index);
+	}
+    }
+
+    void openal_toggleloop (uint32_t index) {
+        ALint loop;
         
-        /*Set volume for sound number index*/
-        if (index >= globalsize) {
-            errno = EINVAL;
-            err_ret("(%s) ERROR - Index out of bounds (got %d, max %d)", prog, index, globalindex);
-            return AL_FALSE;
-        }
-        
-        if (percentage > 100)
-            percentage = 100;
-        alSourcef (Sources[index], AL_GAIN, (float) percentage/100.0f);
-        if (AlGetError2("(%s) ERROR -  Failed to set volume for sound %d\n", index) != AL_TRUE)
-            return AL_FALSE;
-        
-        alGetError();  /* clear any AL errors beforehand */
-        
-        return AL_TRUE;
+        if (openalReady == AL_TRUE && index < globalsize) {
+            alGetSourcei (Sources[index], AL_LOOPING, &loop);
+            alSourcei (Sources[index], AL_LOOPING, !((uint8_t) loop) & 0x00000001);
+	}
+
+    }
+    
+
+    void openal_setvolume (uint32_t index, float gain) {
+        if (openalReady == AL_TRUE && index < globalsize)
+            alSourcef (Sources[index], AL_GAIN, gain);
     }
     
     
-    ALboolean openal_setglobalvolume (uint8_t percentage) {
-        if (openalReady == AL_FALSE) {
-            errno = EPERM;                
-            err_ret("(%s) WARN - OpenAL not initialized", prog);
-            return AL_FALSE;
-        }
-        
-        /*Set volume for all sounds*/		
-        if (percentage > 100)
-            percentage = 100;
-        alListenerf (AL_GAIN, (float) percentage/100.0f);
-        if (AlGetError("(%s) ERROR -  Failed to set global volume") != AL_TRUE)
-            return AL_FALSE;
-        
-        alGetError();  /* clear any AL errors beforehand */
-        
-        return AL_TRUE;
+    void openal_setglobalvolume (float gain) {
+        if (openalReady == AL_TRUE)
+            alListenerf (AL_GAIN, gain);
+    }
+    
+    void openal_togglemute () {
+        ALfloat gain;
+
+        if (openalReady == AL_TRUE) {
+            alGetListenerf (AL_GAIN, &gain);
+            if (gain > 0) {
+		old_gain = gain; 
+                gain = 0;
+	    } else 
+                gain = old_gain;
+    
+	    alListenerf (AL_GAIN, gain);
+	}
     }
     
     
-    ALboolean openal_togglemute () {
-        /*Mute or unmute sound*/
-        ALfloat mute;
-        
-        if (openalReady == AL_FALSE) {
-            errno = EPERM;                
-            err_ret("(%s) WARN - OpenAL not initialized", prog);
-            return AL_FALSE;
-        }
-        
-        alGetListenerf (AL_GAIN, &mute);
-        if (mute > 0) 
-            mute = 0;
-        else
-            mute = 1.0;
-        alListenerf (AL_GAIN, mute);
-        if (AlGetError("(%s) ERROR -  Failed to set mute property") != AL_TRUE)
-            return AL_FALSE;
-        
-        alGetError();  /* clear any AL errors beforehand */
-        
-        return AL_TRUE;
-    }
-    
-    
-    ALboolean openal_fade (uint32_t index, uint16_t quantity, ALboolean direction) {
+    void openal_fade (uint32_t index, uint16_t quantity, char direction) {
         /*Fade in or out by calling a helper thread*/
 #ifndef _WIN32
         pthread_t thread;
@@ -349,176 +325,51 @@
 #endif
         fade_t *fade;
         
-        if (openalReady == AL_FALSE) {
-            errno = EPERM;                
-            err_ret("(%s) WARN - OpenAL not initialized", prog);
-            return AL_FALSE;
-        }
+        if (openalReady == AL_TRUE && index < globalsize) {
         
-        fade = (fade_t*) Malloc(sizeof(fade_t));
-        fade->index = index;
-        fade->quantity = quantity;
+            fade = (fade_t*) Malloc(sizeof(fade_t));
+            fade->index = index;
+            fade->quantity = quantity;
         
-        if (index >= globalsize) {
-            errno = EINVAL;
-            err_ret("(%s) ERROR - Index out of bounds (got %d, max %d)", prog, index, globalindex);
-            return AL_FALSE;
-        }
-        
-        switch (direction) {
-            case FADE_IN:
+            if (direction > 0) {
 #ifndef _WIN32
                 pthread_create(&thread, NULL, helper_fadein, (void*) fade);
 #else
                 Thread = _beginthread(&helper_fadein, 0, (void*) fade);
 #endif
-                break;
-            case FADE_OUT:
+            } else {
 #ifndef _WIN32
                 pthread_create(&thread, NULL, helper_fadeout, (void*) fade);
 #else
                 Thread = _beginthread(&helper_fadeout, 0, (void*) fade);
 #endif	
-                break;
-            default:
-                errno = EINVAL;
-                err_ret("(%s) ERROR - Unknown direction for fading", prog, index, globalindex);
-                free(fade);
-                return AL_FALSE;
-                break;
-        }
+            }
         
 #ifndef _WIN32
-        pthread_detach(thread);
+            pthread_detach(thread);
 #endif
-        
-        alGetError();  /* clear any AL errors beforehand */
-        
-        return AL_TRUE;
-    }
-    
-    
-    ALboolean openal_fadeout (uint32_t index, uint16_t quantity) {
-        /*wrapper for fadeout*/
-        return openal_fade(index, quantity, FADE_OUT);
-    }
-    
-    
-    ALboolean openal_fadein (uint32_t index, uint16_t quantity) {
-        /*wrapper for fadein*/
-        return openal_fade(index, quantity, FADE_IN);
-    }
-    
-    
-    ALboolean openal_setposition (uint32_t index, float x, float y, float z) {
-        if (openalReady == AL_FALSE) {
-            errno = EPERM;                
-            err_ret("(%s) WARN - OpenAL not initialized", prog);
-            return AL_FALSE;
-        }
-        
-        if (index >= globalsize) {
-            errno = EINVAL;
-            err_ret("(%s) ERROR - Index out of bounds (got %d, max %d)", prog, index, globalindex);
-            return AL_FALSE;
-        }
-        
-        alSource3f(Sources[index], AL_POSITION, x, y, z);
-        if (AlGetError2("(%s) ERROR - Failed to set position for sound %d)", index) != AL_TRUE)
-            return AL_FALSE;
-        
-        return AL_TRUE;
+	}
     }
     
     
-    ALboolean openal_playsound (uint32_t index){
-        if (openalReady == AL_FALSE) {
-            errno = EPERM;                
-            err_ret("(%s) WARN - OpenAL not initialized", prog);
-            return AL_FALSE;
-        }
-        
-        /*Play sound number index*/
-        if (index >= globalsize) {
-            errno = EINVAL;
-            err_ret("(%s) ERROR - Index out of bounds (got %d, max %d)", prog, index, globalindex);
-            return AL_FALSE;
-        }
-        alSourcePlay(Sources[index]);
-        if (AlGetError2("(%s) ERROR - Failed to play sound %d)", index) != AL_TRUE)
-            return AL_FALSE;
-        
-        alGetError();  /* clear any AL errors beforehand */
-        
-        return AL_TRUE;
-    }
-    
-    
-    ALboolean openal_pausesound(uint32_t index){
-        if (openalReady == AL_FALSE) {
-            errno = EPERM;                
-            err_ret("(%s) WARN - OpenAL not initialized", prog);
-            return AL_FALSE;
-        }
-        
-        /*Pause sound number index*/
-        if (index >= globalsize) {
-            errno = EINVAL;
-            err_ret("(%s) ERROR - Index out of bounds (got %d, max %d)", prog, index, globalindex);
-            return AL_FALSE;
-        }
-        alSourcePause(Sources[index]);
-        if (AlGetError2("(%s) ERROR - Failed to pause sound %d)", index) != AL_TRUE)
-            return AL_FALSE;
-        
-        return AL_TRUE;
+    void openal_fadeout (uint32_t index, uint16_t quantity) {
+        openal_fade(index, quantity, AL_FADE_OUT);
     }
     
     
-    ALboolean openal_stopsound(uint32_t index){
-        if (openalReady == AL_FALSE) {
-            errno = EPERM;                
-            err_ret("(%s) WARN - OpenAL not initialized", prog);
-            return AL_FALSE;
-        }
-        
-        /*Stop sound number index*/
-        if (index >= globalsize) {
-            errno = EINVAL;
-            err_ret("(%s) ERROR - Index out of bounds (got %d, max %d)", prog, index, globalindex);
-            return AL_FALSE;
-        }
-        alSourceStop(Sources[index]);
-        if (AlGetError2("(%s) ERROR - Failed to stop sound %d)", index) != AL_TRUE)
-            return AL_FALSE;
-        
-        alGetError();  /* clear any AL errors beforehand */
-        
-        return AL_TRUE;
+    void openal_fadein (uint32_t index, uint16_t quantity) {
+        openal_fade(index, quantity, AL_FADE_IN);
     }
     
     
-    ALboolean openal_freesound(uint32_t index){
-        if (openalReady == AL_FALSE) {
-            errno = EPERM;                
-            err_ret("(%s) WARN - OpenAL not initialized", prog);
-            return AL_FALSE;
-        }
-        
-        /*Stop sound number index*/
-        if (index >= globalsize) {
-            errno = EINVAL;
-            err_ret("(%s) ERROR - Index out of bounds (got %d, max %d)", prog, index, globalindex);
-            return AL_FALSE;
-        }
-        globalindex--;
-        // most likely should do other stuff
-        
-        alGetError();  /* clear any AL errors beforehand */
-        
-        return AL_TRUE;
+    void openal_setposition (uint32_t index, float x, float y, float z) {
+        if (openalReady == AL_TRUE && index < globalsize) 
+            alSource3f(Sources[index], AL_POSITION, x, y, z);;
     }
     
+    
+
+    
 #ifdef __CPLUSPLUS
 }
 #endif
--- a/misc/openalbridge/openalbridge.h	Mon Apr 19 13:31:08 2010 +0000
+++ b/misc/openalbridge/openalbridge.h	Mon Apr 19 15:30:11 2010 +0000
@@ -24,23 +24,52 @@
 extern "C" {
 #endif 
     
-    char   openal_init              (char* programname, char usehardware, unsigned int memorysize);
-    char   openal_close             (void);
-    char   openal_ready             (void);
-    int    openal_loadfile          (const char *filename);
-    char   openal_toggleloop        (unsigned int index);
-    char   openal_setposition       (unsigned int index, float x, float y, float z);
-    char   openal_setvolume         (unsigned int index, unsigned char percentage);
-    char   openal_setglobalvolume   (unsigned char percentage);
-    char   openal_togglemute        (void);
-    char   openal_fadeout           (unsigned int index, unsigned short int quantity);
-    char   openal_fadein            (unsigned int index, unsigned short int quantity);
-    char   openal_fade              (unsigned int index, unsigned short int quantity, char direction);
-    char   openal_playsound         (unsigned int index);	
-    char   openal_pausesound        (unsigned int index);
-    char   openal_stopsound         (unsigned int index);
-    char   openal_freesound         (unsigned int index);
-    
+    // init audio context and allocate memory
+    char openal_init              (char usehardware, int memorysize);
+
+    // close audio subsytem and free memory
+    void openal_close             (void);
+
+    // check if openal_init has been called
+    char openal_ready             (void);
+
+    // load an audio file into memory and map it to abuffer
+    int  openal_loadfile          (const char *filename);
+
+    // play, pause, stop a single sound source
+    void openal_playsound         (unsigned int index);	
+    void openal_pausesound        (unsigned int index);
+    void openal_stopsound         (unsigned int index);
+
+    // play a sound and set whether it should loop or not (0/1)
+    void openal_playsound_loop    (unsigned int index, char loops);
+
+    // stop a sound and free the associated buffer
+    void openal_stopsound_free    (unsigned int index, char freesource);
+
+    void openal_freesound         (unsigned int index);
+
+    // set or unset the looping property for a sound source
+    void openal_toggleloop        (unsigned int index);
+
+    // set position and volume of a sound source
+    void openal_setposition       (unsigned int index, float x, float y, float z);
+    void openal_setvolume         (unsigned int index, float gain);
+
+    // set volume for all sounds (gain interval is [0-1])
+    void openal_setglobalvolume   (float gain);
+
+    // mute or unmute all sounds    
+    void openal_togglemute        (void);
+
+    // fade effect, 
+    void openal_fadeout           (unsigned int index, unsigned short int quantity);
+    void openal_fadein            (unsigned int index, unsigned short int quantity);
+    void openal_fade              (unsigned int index, unsigned short int quantity, char direction);
+
+#define AL_FADE_IN 1
+#define AL_FADE_OUT -1
+
 #ifdef __CPLUSPLUS
 }
 #endif