Reformat alc/h and al.h, and redo the comments

2 files changed, 574 insertions, 666 deletions

diff --git a/include/AL/al.h b/include/AL/al.h
index 5b0f9dfd..9e10485c 100644
--- a/include/AL/al.h
+++ b/include/AL/al.h
@@ -22,22 +22,18 @@ extern "C" {
 #endif
 
 
-/*
- * The OPENAL, ALAPI, ALAPIENTRY, AL_INVALID, AL_ILLEGAL_ENUM, and
- * AL_ILLEGAL_COMMAND macros are deprecated, but are included for
- * applications porting code from AL 1.0
- */
+/** Deprecated macro. */
 #define OPENAL
-#define ALAPI AL_API
-#define ALAPIENTRY AL_APIENTRY
-#define AL_INVALID                                (-1)
-#define AL_ILLEGAL_ENUM                           AL_INVALID_ENUM
-#define AL_ILLEGAL_COMMAND                        AL_INVALID_OPERATION
+#define ALAPI                                    AL_API
+#define ALAPIENTRY                               AL_APIENTRY
+#define AL_INVALID                               (-1)
+#define AL_ILLEGAL_ENUM                          AL_INVALID_ENUM
+#define AL_ILLEGAL_COMMAND                       AL_INVALID_OPERATION
 
+/** Supported AL version. */
 #define AL_VERSION_1_0
 #define AL_VERSION_1_1
 
-
 /** 8-bit boolean */
 typedef char ALboolean;
 
@@ -80,632 +76,580 @@ typedef void ALvoid;
 
 /* Enumerant values begin at column 50. No tabs. */
 
-/* "no distance model" or "no buffer" */
-#define AL_NONE                                   0
+/** "no distance model" or "no buffer" */
+#define AL_NONE                                  0
 
-/* Boolean False. */
-#define AL_FALSE                                  0
+/** Boolean False. */
+#define AL_FALSE                                 0
 
 /** Boolean True. */
-#define AL_TRUE                                   1
-
-/** Indicate Source has relative coordinates. */
-#define AL_SOURCE_RELATIVE                        0x202
-
+#define AL_TRUE                                  1
 
 
 /**
- * Directional source, inner cone angle, in degrees.
- * Range:    [0-360] 
- * Default:  360
+ * Relative source.
+ * Type:    ALboolean
+ * Range:   [AL_TRUE, AL_FALSE]
+ * Default: AL_FALSE
+ *
+ * Specifies if the Source has relative coordinates.
  */
-#define AL_CONE_INNER_ANGLE                       0x1001
+#define AL_SOURCE_RELATIVE                       0x202
 
-/**
- * Directional source, outer cone angle, in degrees.
- * Range:    [0-360] 
- * Default:  360
- */
-#define AL_CONE_OUTER_ANGLE                       0x1002
 
 /**
- * Specify the pitch to be applied at source.
- * Range:   [0.5-2.0]
- * Default: 1.0
- */
-#define AL_PITCH                                  0x1003
-  
-/** 
- * Specify the current location in three dimensional space.
- * OpenAL, like OpenGL, uses a right handed coordinate system,
- *  where in a frontal default view X (thumb) points right, 
- *  Y points up (index finger), and Z points towards the
- *  viewer/camera (middle finger). 
- * To switch from a left handed coordinate system, flip the
- *  sign on the Z coordinate.
- * Listener position is always in the world coordinate system.
- */ 
-#define AL_POSITION                               0x1004
-  
-/** Specify the current direction. */
-#define AL_DIRECTION                              0x1005
-  
-/** Specify the current velocity in three dimensional space. */
-#define AL_VELOCITY                               0x1006
-
-/**
- * Indicate whether source is looping.
- * Type: ALboolean?
- * Range:   [AL_TRUE, AL_FALSE]
- * Default: FALSE.
+ * Inner cone angle, in degrees.
+ * Type:    ALint, ALfloat
+ * Range:   [0 - 360]
+ * Default: 360
+ *
+ * The angle covered by the inner cone, where the source will not attenuate.
  */
-#define AL_LOOPING                                0x1007
+#define AL_CONE_INNER_ANGLE                      0x1001
 
 /**
- * Indicate the buffer to provide sound samples. 
- * Type: ALuint.
- * Range: any valid Buffer id.
- */
-#define AL_BUFFER                                 0x1009
-  
-/**
- * Indicate the gain (volume amplification) applied. 
- * Type:   ALfloat.
- * Range:  ]0.0-  ]
- * A value of 1.0 means un-attenuated/unchanged.
- * Each division by 2 equals an attenuation of -6dB.
- * Each multiplicaton with 2 equals an amplification of +6dB.
- * A value of 0.0 is meaningless with respect to a logarithmic
- *  scale; it is interpreted as zero volume - the channel
- *  is effectively disabled.
- */
-#define AL_GAIN                                   0x100A
-
-/*
- * Indicate minimum source attenuation
- * Type: ALfloat
- * Range:  [0.0 - 1.0]
+ * Outer cone angle, in degrees.
+ * Range:   [0 - 360]
+ * Default: 360
  *
- * Logarthmic
+ * The angle covered by the outer cone, where the source will be fully
+ * attenuated.
  */
-#define AL_MIN_GAIN                               0x100D
+#define AL_CONE_OUTER_ANGLE                      0x1002
 
 /**
- * Indicate maximum source attenuation
- * Type: ALfloat
- * Range:  [0.0 - 1.0]
+ * Source pitch.
+ * Type:    ALfloat
+ * Range:   [0.5 - 2.0]
+ * Default: 1.0
  *
- * Logarthmic
+ * A multiplier for the frequency (sample rate) of the source's buffer.
  */
-#define AL_MAX_GAIN                               0x100E
+#define AL_PITCH                                 0x1003
 
 /**
- * Indicate listener orientation.
+ * Source or listener position.
+ * Type:    ALfloat[3], ALint[3]
+ * Default: {0, 0, 0}
  *
- * at/up 
+ * The source or listener location in three dimensional space.
+ *
+ * OpenAL, like OpenGL, uses a right handed coordinate system, where in a
+ * frontal default view X (thumb) points right, Y points up (index finger), and
+ * Z points towards the viewer/camera (middle finger).
+ *
+ * To switch from a left handed coordinate system, flip the sign on the Z
+ * coordinate.
  */
-#define AL_ORIENTATION                            0x100F
+#define AL_POSITION                              0x1004
 
 /**
- * Source state information.
+ * Source direction.
+ * Type:    ALfloat[3], ALint[3]
+ * Default: {0, 0, 0}
+ *
+ * Specifies the current direction in local space.
+ * A zero-length vector specifies an omni-directional source (cone is ignored).
  */
-#define AL_SOURCE_STATE                           0x1010
-#define AL_INITIAL                                0x1011
-#define AL_PLAYING                                0x1012
-#define AL_PAUSED                                 0x1013
-#define AL_STOPPED                                0x1014
+#define AL_DIRECTION                             0x1005
 
 /**
- * Buffer Queue params
+ * Source or listener velocity.
+ * Type:    ALfloat[3], ALint[3]
+ * Default: {0, 0, 0}
+ *
+ * Specifies the current velocity in local space.
  */
-#define AL_BUFFERS_QUEUED                         0x1015
-#define AL_BUFFERS_PROCESSED                      0x1016
+#define AL_VELOCITY                              0x1006
 
 /**
- * Source buffer position information
- */
-#define AL_SEC_OFFSET                             0x1024
-#define AL_SAMPLE_OFFSET                          0x1025
-#define AL_BYTE_OFFSET                            0x1026
-
-/*
- * Source type (Static, Streaming or undetermined)
- * Source is Static if a Buffer has been attached using AL_BUFFER
- * Source is Streaming if one or more Buffers have been attached using alSourceQueueBuffers
- * Source is undetermined when it has the NULL buffer attached
+ * Source looping.
+ * Type:    ALboolean
+ * Range:   [AL_TRUE, AL_FALSE]
+ * Default: AL_FALSE
+ *
+ * Specifies whether source is looping.
  */
-#define AL_SOURCE_TYPE                            0x1027
-#define AL_STATIC                                 0x1028
-#define AL_STREAMING                              0x1029
-#define AL_UNDETERMINED                           0x1030
-
-/** Sound samples: format specifier. */
-#define AL_FORMAT_MONO8                           0x1100
-#define AL_FORMAT_MONO16                          0x1101
-#define AL_FORMAT_STEREO8                         0x1102
-#define AL_FORMAT_STEREO16                        0x1103
+#define AL_LOOPING                               0x1007
 
 /**
- * source specific reference distance
- * Type: ALfloat
- * Range:  0.0 - +inf
+ * Source buffer.
+ * Type:  ALuint
+ * Range: any valid Buffer.
  *
- * At 0.0, no distance attenuation occurs.  Default is
- * 1.0.
+ * Specifies the buffer to provide sound samples.
  */
-#define AL_REFERENCE_DISTANCE                     0x1020
+#define AL_BUFFER                                0x1009
 
 /**
- * source specific rolloff factor
- * Type: ALfloat
- * Range:  0.0 - +inf
+ * Source or listener gain.
+ * Type:  ALfloat
+ * Range: [0.0 - ]
  *
+ * A value of 1.0 means unattenuated. Each division by 2 equals an attenuation
+ * of about -6dB. Each multiplicaton by 2 equals an amplification of about
+ * +6dB.
+ *
+ * A value of 0.0 is meaningless with respect to a logarithmic scale; it is
+ * silent.
  */
-#define AL_ROLLOFF_FACTOR                         0x1021
+#define AL_GAIN                                  0x100A
 
 /**
- * Directional source, outer cone gain.
+ * Minimum source gain.
+ * Type:  ALfloat
+ * Range: [0.0 - 1.0]
  *
- * Default:  0.0
- * Range:    [0.0 - 1.0]
- * Logarithmic
+ * The minimum gain allowed for a source, after distance and cone attenation is
+ * applied (if applicable).
  */
-#define AL_CONE_OUTER_GAIN                        0x1022
+#define AL_MIN_GAIN                              0x100D
 
 /**
- * Indicate distance above which sources are not
- * attenuated using the inverse clamped distance model.
+ * Maximum source gain.
+ * Type:  ALfloat
+ * Range: [0.0 - 1.0]
  *
- * Default: +inf
- * Type: ALfloat
- * Range:  0.0 - +inf
+ * The maximum gain allowed for a source, after distance and cone attenation is
+ * applied (if applicable).
  */
-#define AL_MAX_DISTANCE                           0x1023
-
-/** 
- * Sound samples: frequency, in units of Hertz [Hz].
- * This is the number of samples per second. Half of the
- *  sample frequency marks the maximum significant
- *  frequency component.
- */
-#define AL_FREQUENCY                              0x2001
-#define AL_BITS                                   0x2002
-#define AL_CHANNELS                               0x2003
-#define AL_SIZE                                   0x2004
+#define AL_MAX_GAIN                              0x100E
 
 /**
- * Buffer state.
+ * Listener orientation.
+ * Type: ALfloat[6]
+ * Default: {0.0, 0.0, -1.0, 0.0, 1.0, 0.0}
  *
- * Not supported for public use (yet).
- */
-#define AL_UNUSED                                 0x2010
-#define AL_PENDING                                0x2011
-#define AL_PROCESSED                              0x2012
-
-
-/** Errors: No Error. */
-#define AL_NO_ERROR                               0
-
-/** 
- * Invalid Name paramater passed to AL call.
- */
-#define AL_INVALID_NAME                           0xA001
-
-/** 
- * Invalid parameter passed to AL call.
- */
-#define AL_INVALID_ENUM                           0xA002
-
-/** 
- * Invalid enum parameter value.
- */
-#define AL_INVALID_VALUE                          0xA003
-
-/** 
- * Illegal call.
+ * Effectively two three dimensional vectors. The first vector is the front (or
+ * "at") and the second is the top (or "up").
+ *
+ * Both vectors are in local space.
  */
-#define AL_INVALID_OPERATION                      0xA004
+#define AL_ORIENTATION                           0x100F
 
-  
 /**
- * No mojo.
+ * Source state (query only).
+ * Type:  ALint
+ * Range: [AL_INITIAL, AL_PLAYING, AL_PAUSED, AL_STOPPED]
  */
-#define AL_OUT_OF_MEMORY                          0xA005
+#define AL_SOURCE_STATE                          0x1010
 
-
-/** Context strings: Vendor Name. */
-#define AL_VENDOR                                 0xB001
-#define AL_VERSION                                0xB002
-#define AL_RENDERER                               0xB003
-#define AL_EXTENSIONS                             0xB004
-
-/** Global tweakage. */
+/** Source state value. */
+#define AL_INITIAL                               0x1011
+#define AL_PLAYING                               0x1012
+#define AL_PAUSED                                0x1013
+#define AL_STOPPED                               0x1014
 
 /**
- * Doppler scale.  Default 1.0
+ * Source Buffer Queue size (query only).
+ * Type: ALint
+ *
+ * The number of buffers queued using alSourceQueueBuffers, minus the buffers
+ * removed with alSourceUnqueueBuffers.
  */
-#define AL_DOPPLER_FACTOR                         0xC000
+#define AL_BUFFERS_QUEUED                        0x1015
 
 /**
- * Tweaks speed of propagation.
+ * Source Buffer Queue processed count (query only).
+ * Type: ALint
+ *
+ * The number of queued buffers that have been fully processed, and can be
+ * removed with alSourceUnqueueBuffers.
+ *
+ * Looping sources will never fully process buffers because they will be set to
+ * play again for when the source loops.
  */
-#define AL_DOPPLER_VELOCITY                       0xC001
+#define AL_BUFFERS_PROCESSED                     0x1016
 
 /**
- * Speed of Sound in units per second
+ * Source reference distance.
+ * Type:    ALfloat
+ * Range:   [0.0 - ]
+ * Default: 1.0
+ *
+ * The distance in units that no attenuation occurs.
+ *
+ * At 0.0, no distance attenuation ever occurs.
  */
-#define AL_SPEED_OF_SOUND                         0xC003
+#define AL_REFERENCE_DISTANCE                    0x1020
 
 /**
- * Distance models
+ * Source rolloff factor.
+ * Type:    ALfloat
+ * Range:   [0.0 - ]
+ * Default: 1.0
  *
- * used in conjunction with DistanceModel
+ * Multiplier to exaggerate or diminish distance attenuation.
  *
- * implicit: NONE, which disances distance attenuation.
- */
-#define AL_DISTANCE_MODEL                         0xD000
-#define AL_INVERSE_DISTANCE                       0xD001
-#define AL_INVERSE_DISTANCE_CLAMPED               0xD002
-#define AL_LINEAR_DISTANCE                        0xD003
-#define AL_LINEAR_DISTANCE_CLAMPED                0xD004
-#define AL_EXPONENT_DISTANCE                      0xD005
-#define AL_EXPONENT_DISTANCE_CLAMPED              0xD006
-
-/*
- * Renderer State management
+ * At 0.0, no distance attenuation ever occurs.
  */
-AL_API void AL_APIENTRY alEnable( ALenum capability );
+#define AL_ROLLOFF_FACTOR                        0x1021
 
-AL_API void AL_APIENTRY alDisable( ALenum capability ); 
-
-AL_API ALboolean AL_APIENTRY alIsEnabled( ALenum capability ); 
-
-
-/*
- * State retrieval
- */
-AL_API const ALchar* AL_APIENTRY alGetString( ALenum param );
-
-AL_API void AL_APIENTRY alGetBooleanv( ALenum param, ALboolean* data );
-
-AL_API void AL_APIENTRY alGetIntegerv( ALenum param, ALint* data );
-
-AL_API void AL_APIENTRY alGetFloatv( ALenum param, ALfloat* data );
-
-AL_API void AL_APIENTRY alGetDoublev( ALenum param, ALdouble* data );
-
-AL_API ALboolean AL_APIENTRY alGetBoolean( ALenum param );
-
-AL_API ALint AL_APIENTRY alGetInteger( ALenum param );
-
-AL_API ALfloat AL_APIENTRY alGetFloat( ALenum param );
-
-AL_API ALdouble AL_APIENTRY alGetDouble( ALenum param );
-
-
-/*
- * Error support.
- * Obtain the most recent error generated in the AL state machine.
+/**
+ * Outer cone gain.
+ * Type:    ALfloat
+ * Range:   [0.0 - 1.0]
+ * Default: 0.0
+ *
+ * The gain attenuation applied when the listener is outside of the source's
+ * outer cone.
  */
-AL_API ALenum AL_APIENTRY alGetError( void );
+#define AL_CONE_OUTER_GAIN                       0x1022
 
-
-/* 
- * Extension support.
- * Query for the presence of an extension, and obtain any appropriate
- * function pointers and enum values.
+/**
+ * Source maximum distance.
+ * Type:    ALfloat
+ * Range:   [0.0 - ]
+ * Default: +inf
+ *
+ * The distance above which the source is not attenuated any further with a
+ * clamped distance model, or where attenuation reaches 0.0 gain for linear
+ * distance models.
  */
-AL_API ALboolean AL_APIENTRY alIsExtensionPresent( const ALchar* extname );
-
-AL_API void* AL_APIENTRY alGetProcAddress( const ALchar* fname );
+#define AL_MAX_DISTANCE                          0x1023
 
-AL_API ALenum AL_APIENTRY alGetEnumValue( const ALchar* ename );
+/** Source buffer position, in seconds */
+#define AL_SEC_OFFSET                            0x1024
+/** Source buffer position, in sample frames */
+#define AL_SAMPLE_OFFSET                         0x1025
+/** Source buffer position, in bytes */
+#define AL_BYTE_OFFSET                           0x1026
 
-
-/*
- * LISTENER
- * Listener represents the location and orientation of the
- * 'user' in 3D-space.
+/**
+ * Source type (query only).
+ * Type:  ALint
+ * Range: [AL_STATIC, AL_STREAMING, AL_UNDETERMINED]
  *
- * Properties include: -
+ * A Source is Static if a Buffer has been attached using AL_BUFFER.
  *
- * Gain         AL_GAIN         ALfloat
- * Position     AL_POSITION     ALfloat[3]
- * Velocity     AL_VELOCITY     ALfloat[3]
- * Orientation  AL_ORIENTATION  ALfloat[6] (Forward then Up vectors)
-*/
-
-/*
- * Set Listener parameters
- */
-AL_API void AL_APIENTRY alListenerf( ALenum param, ALfloat value );
-
-AL_API void AL_APIENTRY alListener3f( ALenum param, ALfloat value1, ALfloat value2, ALfloat value3 );
-
-AL_API void AL_APIENTRY alListenerfv( ALenum param, const ALfloat* values ); 
-
-AL_API void AL_APIENTRY alListeneri( ALenum param, ALint value );
-
-AL_API void AL_APIENTRY alListener3i( ALenum param, ALint value1, ALint value2, ALint value3 );
-
-AL_API void AL_APIENTRY alListeneriv( ALenum param, const ALint* values );
-
-/*
- * Get Listener parameters
- */
-AL_API void AL_APIENTRY alGetListenerf( ALenum param, ALfloat* value );
-
-AL_API void AL_APIENTRY alGetListener3f( ALenum param, ALfloat *value1, ALfloat *value2, ALfloat *value3 );
-
-AL_API void AL_APIENTRY alGetListenerfv( ALenum param, ALfloat* values );
-
-AL_API void AL_APIENTRY alGetListeneri( ALenum param, ALint* value );
-
-AL_API void AL_APIENTRY alGetListener3i( ALenum param, ALint *value1, ALint *value2, ALint *value3 );
-
-AL_API void AL_APIENTRY alGetListeneriv( ALenum param, ALint* values );
-
+ * A Source is Streaming if one or more Buffers have been attached using
+ * alSourceQueueBuffers.
+ *
+ * A Source is Undetermined when it has the NULL buffer attached.
+ */
+#define AL_SOURCE_TYPE                           0x1027
+
+/** Source type value. */
+#define AL_STATIC                                0x1028
+#define AL_STREAMING                             0x1029
+#define AL_UNDETERMINED                          0x1030
+
+/** Buffer format specifier. */
+#define AL_FORMAT_MONO8                          0x1100
+#define AL_FORMAT_MONO16                         0x1101
+#define AL_FORMAT_STEREO8                        0x1102
+#define AL_FORMAT_STEREO16                       0x1103
+
+/** Buffer frequency (query only). */
+#define AL_FREQUENCY                             0x2001
+/** Buffer bits per sample (query only). */
+#define AL_BITS                                  0x2002
+/** Buffer channel count (query only). */
+#define AL_CHANNELS                              0x2003
+/** Buffer data size (query only). */
+#define AL_SIZE                                  0x2004
 
 /**
- * SOURCE
- * Sources represent individual sound objects in 3D-space.
- * Sources take the PCM data provided in the specified Buffer,
- * apply Source-specific modifications, and then
- * submit them to be mixed according to spatial arrangement etc.
- * 
- * Properties include: -
- *
- * Gain                              AL_GAIN                 ALfloat
- * Min Gain                          AL_MIN_GAIN             ALfloat
- * Max Gain                          AL_MAX_GAIN             ALfloat
- * Position                          AL_POSITION             ALfloat[3]
- * Velocity                          AL_VELOCITY             ALfloat[3]
- * Direction                         AL_DIRECTION            ALfloat[3]
- * Head Relative Mode                AL_SOURCE_RELATIVE      ALint (AL_TRUE or AL_FALSE)
- * Reference Distance                AL_REFERENCE_DISTANCE   ALfloat
- * Max Distance                      AL_MAX_DISTANCE         ALfloat
- * RollOff Factor                    AL_ROLLOFF_FACTOR       ALfloat
- * Inner Angle                       AL_CONE_INNER_ANGLE     ALint or ALfloat
- * Outer Angle                       AL_CONE_OUTER_ANGLE     ALint or ALfloat
- * Cone Outer Gain                   AL_CONE_OUTER_GAIN      ALint or ALfloat
- * Pitch                             AL_PITCH                ALfloat
- * Looping                           AL_LOOPING              ALint (AL_TRUE or AL_FALSE)
- * MS Offset                         AL_MSEC_OFFSET          ALint or ALfloat
- * Byte Offset                       AL_BYTE_OFFSET          ALint or ALfloat
- * Sample Offset                     AL_SAMPLE_OFFSET        ALint or ALfloat
- * Attached Buffer                   AL_BUFFER               ALint
- * State (Query only)                AL_SOURCE_STATE         ALint
- * Buffers Queued (Query only)       AL_BUFFERS_QUEUED       ALint
- * Buffers Processed (Query only)    AL_BUFFERS_PROCESSED    ALint
- */
-
-/* Create Source objects */
-AL_API void AL_APIENTRY alGenSources( ALsizei n, ALuint* sources ); 
-
-/* Delete Source objects */
-AL_API void AL_APIENTRY alDeleteSources( ALsizei n, const ALuint* sources );
-
-/* Verify a handle is a valid Source */ 
-AL_API ALboolean AL_APIENTRY alIsSource( ALuint sid ); 
-
-/*
- * Set Source parameters
+ * Buffer state.
+ *
+ * Not for public use.
  */
-AL_API void AL_APIENTRY alSourcef( ALuint sid, ALenum param, ALfloat value ); 
-
-AL_API void AL_APIENTRY alSource3f( ALuint sid, ALenum param, ALfloat value1, ALfloat value2, ALfloat value3 );
+#define AL_UNUSED                                0x2010
+#define AL_PENDING                               0x2011
+#define AL_PROCESSED                             0x2012
 
-AL_API void AL_APIENTRY alSourcefv( ALuint sid, ALenum param, const ALfloat* values ); 
 
-AL_API void AL_APIENTRY alSourcei( ALuint sid, ALenum param, ALint value ); 
+/** No error. */
+#define AL_NO_ERROR                              0
 
-AL_API void AL_APIENTRY alSource3i( ALuint sid, ALenum param, ALint value1, ALint value2, ALint value3 );
+/** Invalid name paramater passed to AL call. */
+#define AL_INVALID_NAME                          0xA001
 
-AL_API void AL_APIENTRY alSourceiv( ALuint sid, ALenum param, const ALint* values );
+/** Invalid enum parameter passed to AL call. */
+#define AL_INVALID_ENUM                          0xA002
 
-/*
- * Get Source parameters
- */
-AL_API void AL_APIENTRY alGetSourcef( ALuint sid, ALenum param, ALfloat* value );
+/** Invalid value parameter passed to AL call. */
+#define AL_INVALID_VALUE                         0xA003
 
-AL_API void AL_APIENTRY alGetSource3f( ALuint sid, ALenum param, ALfloat* value1, ALfloat* value2, ALfloat* value3);
+/** Illegal AL call. */
+#define AL_INVALID_OPERATION                     0xA004
 
-AL_API void AL_APIENTRY alGetSourcefv( ALuint sid, ALenum param, ALfloat* values );
+/** Not enough memory. */
+#define AL_OUT_OF_MEMORY                         0xA005
 
-AL_API void AL_APIENTRY alGetSourcei( ALuint sid,  ALenum param, ALint* value );
 
-AL_API void AL_APIENTRY alGetSource3i( ALuint sid, ALenum param, ALint* value1, ALint* value2, ALint* value3);
+/** Context string: Vendor ID. */
+#define AL_VENDOR                                0xB001
+/** Context string: Version. */
+#define AL_VERSION                               0xB002
+/** Context string: Renderer ID. */
+#define AL_RENDERER                              0xB003
+/** Context string: Space-separated extension list. */
+#define AL_EXTENSIONS                            0xB004
 
-AL_API void AL_APIENTRY alGetSourceiv( ALuint sid,  ALenum param, ALint* values );
 
-
-/*
- * Source vector based playback calls
+/**
+ * Doppler scale.
+ * Type:    ALfloat
+ * Range:   [0.0 - ]
+ * Default: 1.0
+ *
+ * Scale for source and listener velocities.
  */
+#define AL_DOPPLER_FACTOR                        0xC000
+AL_API void AL_APIENTRY alDopplerFactor(ALfloat value);
 
-/* Play, replay, or resume (if paused) a list of Sources */
-AL_API void AL_APIENTRY alSourcePlayv( ALsizei ns, const ALuint *sids );
-
-/* Stop a list of Sources */
-AL_API void AL_APIENTRY alSourceStopv( ALsizei ns, const ALuint *sids );
-
-/* Rewind a list of Sources */
-AL_API void AL_APIENTRY alSourceRewindv( ALsizei ns, const ALuint *sids );
-
-/* Pause a list of Sources */
-AL_API void AL_APIENTRY alSourcePausev( ALsizei ns, const ALuint *sids );
-
-/*
- * Source based playback calls
+/**
+ * Doppler velocity (deprecated).
+ *
+ * A multiplier applied to the Speed of Sound.
  */
+#define AL_DOPPLER_VELOCITY                      0xC001
+AL_API void AL_APIENTRY alDopplerVelocity(ALfloat value);
 
-/* Play, replay, or resume a Source */
-AL_API void AL_APIENTRY alSourcePlay( ALuint sid );
-
-/* Stop a Source */
-AL_API void AL_APIENTRY alSourceStop( ALuint sid );
-
-/* Rewind a Source (set playback postiton to beginning) */
-AL_API void AL_APIENTRY alSourceRewind( ALuint sid );
-
-/* Pause a Source */
-AL_API void AL_APIENTRY alSourcePause( ALuint sid );
-
-/*
- * Source Queuing 
+/**
+ * Speed of Sound, in units per second.
+ * Type:    ALfloat
+ * Range:   [0.0001 - ]
+ * Default: 343.3
+ *
+ * The speed at which sound waves are assumed to travel, when calculating the
+ * doppler effect.
  */
-AL_API void AL_APIENTRY alSourceQueueBuffers( ALuint sid, ALsizei numEntries, const ALuint *bids );
-
-AL_API void AL_APIENTRY alSourceUnqueueBuffers( ALuint sid, ALsizei numEntries, ALuint *bids );
-
+#define AL_SPEED_OF_SOUND                        0xC003
+AL_API void AL_APIENTRY alSpeedOfSound(ALfloat value);
 
 /**
- * BUFFER
- * Buffer objects are storage space for sample data.
- * Buffers are referred to by Sources. One Buffer can be used
- * by multiple Sources.
+ * Distance attenuation model.
+ * Type:    ALint
+ * Range:   [AL_NONE, AL_INVERSE_DISTANCE, AL_INVERSE_DISTANCE_CLAMPED,
+ *           AL_LINEAR_DISTANCE, AL_LINEAR_DISTANCE_CLAMPED,
+ *           AL_EXPONENT_DISTANCE, AL_EXPONENT_DISTANCE_CLAMPED]
+ * Default: AL_INVERSE_DISTANCE_CLAMPED
  *
- * Properties include: -
+ * The model by which sources attenuate with distance.
  *
- * Frequency (Query only)    AL_FREQUENCY      ALint
- * Size (Query only)         AL_SIZE           ALint
- * Bits (Query only)         AL_BITS           ALint
- * Channels (Query only)     AL_CHANNELS       ALint
- */
-
-/* Create Buffer objects */
-AL_API void AL_APIENTRY alGenBuffers( ALsizei n, ALuint* buffers );
-
-/* Delete Buffer objects */
-AL_API void AL_APIENTRY alDeleteBuffers( ALsizei n, const ALuint* buffers );
-
-/* Verify a handle is a valid Buffer */
-AL_API ALboolean AL_APIENTRY alIsBuffer( ALuint bid );
-
-/* Specify the data to be copied into a buffer */
-AL_API void AL_APIENTRY alBufferData( ALuint bid, ALenum format, const ALvoid* data, ALsizei size, ALsizei freq );
-
-/*
- * Set Buffer parameters
- */
-AL_API void AL_APIENTRY alBufferf( ALuint bid, ALenum param, ALfloat value );
-
-AL_API void AL_APIENTRY alBuffer3f( ALuint bid, ALenum param, ALfloat value1, ALfloat value2, ALfloat value3 );
-
-AL_API void AL_APIENTRY alBufferfv( ALuint bid, ALenum param, const ALfloat* values );
-
-AL_API void AL_APIENTRY alBufferi( ALuint bid, ALenum param, ALint value );
-
-AL_API void AL_APIENTRY alBuffer3i( ALuint bid, ALenum param, ALint value1, ALint value2, ALint value3 );
-
-AL_API void AL_APIENTRY alBufferiv( ALuint bid, ALenum param, const ALint* values );
-
-/*
- * Get Buffer parameters
- */
-AL_API void AL_APIENTRY alGetBufferf( ALuint bid, ALenum param, ALfloat* value );
-
-AL_API void AL_APIENTRY alGetBuffer3f( ALuint bid, ALenum param, ALfloat* value1, ALfloat* value2, ALfloat* value3);
-
-AL_API void AL_APIENTRY alGetBufferfv( ALuint bid, ALenum param, ALfloat* values );
-
-AL_API void AL_APIENTRY alGetBufferi( ALuint bid, ALenum param, ALint* value );
-
-AL_API void AL_APIENTRY alGetBuffer3i( ALuint bid, ALenum param, ALint* value1, ALint* value2, ALint* value3);
-
-AL_API void AL_APIENTRY alGetBufferiv( ALuint bid, ALenum param, ALint* values );
-
+ * None     - No distance attenuation.
+ * Inverse  - Doubling the distance halves the source gain.
+ * Linear   - Linear gain scaling between the reference and max distances.
+ * Exponent - Exponential gain dropoff.
+ *
+ * Clamped variations work like the non-clamped counterparts, except the
+ * distance calculated is clamped between the reference and max distances.
+ */
+#define AL_DISTANCE_MODEL                        0xD000
+AL_API void AL_APIENTRY alDistanceModel(ALenum distanceModel);
+
+/** Distance model value. */
+#define AL_INVERSE_DISTANCE                      0xD001
+#define AL_INVERSE_DISTANCE_CLAMPED              0xD002
+#define AL_LINEAR_DISTANCE                       0xD003
+#define AL_LINEAR_DISTANCE_CLAMPED               0xD004
+#define AL_EXPONENT_DISTANCE                     0xD005
+#define AL_EXPONENT_DISTANCE_CLAMPED             0xD006
+
+/** Renderer State management. */
+AL_API void AL_APIENTRY alEnable(ALenum capability);
+AL_API void AL_APIENTRY alDisable(ALenum capability);
+AL_API ALboolean AL_APIENTRY alIsEnabled(ALenum capability);
+
+/** State retrieval. */
+AL_API const ALchar* AL_APIENTRY alGetString(ALenum param);
+AL_API void AL_APIENTRY alGetBooleanv(ALenum param, ALboolean *values);
+AL_API void AL_APIENTRY alGetIntegerv(ALenum param, ALint *values);
+AL_API void AL_APIENTRY alGetFloatv(ALenum param, ALfloat *values);
+AL_API void AL_APIENTRY alGetDoublev(ALenum param, ALdouble *values);
+AL_API ALboolean AL_APIENTRY alGetBoolean(ALenum param);
+AL_API ALint AL_APIENTRY alGetInteger(ALenum param);
+AL_API ALfloat AL_APIENTRY alGetFloat(ALenum param);
+AL_API ALdouble AL_APIENTRY alGetDouble(ALenum param);
 
-/*
- * Global Parameters
+/**
+ * Error retrieval.
+ *
+ * Obtain the first error generated in the AL context since the last check.
  */
-AL_API void AL_APIENTRY alDopplerFactor( ALfloat value );
-
-AL_API void AL_APIENTRY alDopplerVelocity( ALfloat value );
-
-AL_API void AL_APIENTRY alSpeedOfSound( ALfloat value );
-
-AL_API void AL_APIENTRY alDistanceModel( ALenum distanceModel );
+AL_API ALenum AL_APIENTRY alGetError(void);
 
-/*
- * Pointer-to-function types, useful for dynamically getting AL entry points.
- */
-typedef void           (AL_APIENTRY *LPALENABLE)( ALenum capability );
-typedef void           (AL_APIENTRY *LPALDISABLE)( ALenum capability ); 
-typedef ALboolean      (AL_APIENTRY *LPALISENABLED)( ALenum capability ); 
-typedef const ALchar*  (AL_APIENTRY *LPALGETSTRING)( ALenum param );
-typedef void           (AL_APIENTRY *LPALGETBOOLEANV)( ALenum param, ALboolean* data );
-typedef void           (AL_APIENTRY *LPALGETINTEGERV)( ALenum param, ALint* data );
-typedef void           (AL_APIENTRY *LPALGETFLOATV)( ALenum param, ALfloat* data );
-typedef void           (AL_APIENTRY *LPALGETDOUBLEV)( ALenum param, ALdouble* data );
-typedef ALboolean      (AL_APIENTRY *LPALGETBOOLEAN)( ALenum param );
-typedef ALint          (AL_APIENTRY *LPALGETINTEGER)( ALenum param );
-typedef ALfloat        (AL_APIENTRY *LPALGETFLOAT)( ALenum param );
-typedef ALdouble       (AL_APIENTRY *LPALGETDOUBLE)( ALenum param );
-typedef ALenum         (AL_APIENTRY *LPALGETERROR)( void );
-typedef ALboolean      (AL_APIENTRY *LPALISEXTENSIONPRESENT)(const ALchar* extname );
-typedef void*          (AL_APIENTRY *LPALGETPROCADDRESS)( const ALchar* fname );
-typedef ALenum         (AL_APIENTRY *LPALGETENUMVALUE)( const ALchar* ename );
-typedef void           (AL_APIENTRY *LPALLISTENERF)( ALenum param, ALfloat value );
-typedef void           (AL_APIENTRY *LPALLISTENER3F)( ALenum param, ALfloat value1, ALfloat value2, ALfloat value3 );
-typedef void           (AL_APIENTRY *LPALLISTENERFV)( ALenum param, const ALfloat* values );
-typedef void           (AL_APIENTRY *LPALLISTENERI)( ALenum param, ALint value );
-typedef void           (AL_APIENTRY *LPALLISTENER3I)( ALenum param, ALint value1, ALint value2, ALint value3 );
-typedef void           (AL_APIENTRY *LPALLISTENERIV)( ALenum param, const ALint* values );
-typedef void           (AL_APIENTRY *LPALGETLISTENERF)( ALenum param, ALfloat* value );
-typedef void           (AL_APIENTRY *LPALGETLISTENER3F)( ALenum param, ALfloat *value1, ALfloat *value2, ALfloat *value3 );
-typedef void           (AL_APIENTRY *LPALGETLISTENERFV)( ALenum param, ALfloat* values );
-typedef void           (AL_APIENTRY *LPALGETLISTENERI)( ALenum param, ALint* value );
-typedef void           (AL_APIENTRY *LPALGETLISTENER3I)( ALenum param, ALint *value1, ALint *value2, ALint *value3 );
-typedef void           (AL_APIENTRY *LPALGETLISTENERIV)( ALenum param, ALint* values );
-typedef void           (AL_APIENTRY *LPALGENSOURCES)( ALsizei n, ALuint* sources ); 
-typedef void           (AL_APIENTRY *LPALDELETESOURCES)( ALsizei n, const ALuint* sources );
-typedef ALboolean      (AL_APIENTRY *LPALISSOURCE)( ALuint sid ); 
-typedef void           (AL_APIENTRY *LPALSOURCEF)( ALuint sid, ALenum param, ALfloat value); 
-typedef void           (AL_APIENTRY *LPALSOURCE3F)( ALuint sid, ALenum param, ALfloat value1, ALfloat value2, ALfloat value3 );
-typedef void           (AL_APIENTRY *LPALSOURCEFV)( ALuint sid, ALenum param, const ALfloat* values );
-typedef void           (AL_APIENTRY *LPALSOURCEI)( ALuint sid, ALenum param, ALint value); 
-typedef void           (AL_APIENTRY *LPALSOURCE3I)( ALuint sid, ALenum param, ALint value1, ALint value2, ALint value3 );
-typedef void           (AL_APIENTRY *LPALSOURCEIV)( ALuint sid, ALenum param, const ALint* values );
-typedef void           (AL_APIENTRY *LPALGETSOURCEF)( ALuint sid, ALenum param, ALfloat* value );
-typedef void           (AL_APIENTRY *LPALGETSOURCE3F)( ALuint sid, ALenum param, ALfloat* value1, ALfloat* value2, ALfloat* value3);
-typedef void           (AL_APIENTRY *LPALGETSOURCEFV)( ALuint sid, ALenum param, ALfloat* values );
-typedef void           (AL_APIENTRY *LPALGETSOURCEI)( ALuint sid, ALenum param, ALint* value );
-typedef void           (AL_APIENTRY *LPALGETSOURCE3I)( ALuint sid, ALenum param, ALint* value1, ALint* value2, ALint* value3);
-typedef void           (AL_APIENTRY *LPALGETSOURCEIV)( ALuint sid, ALenum param, ALint* values );
-typedef void           (AL_APIENTRY *LPALSOURCEPLAYV)( ALsizei ns, const ALuint *sids );
-typedef void           (AL_APIENTRY *LPALSOURCESTOPV)( ALsizei ns, const ALuint *sids );
-typedef void           (AL_APIENTRY *LPALSOURCEREWINDV)( ALsizei ns, const ALuint *sids );
-typedef void           (AL_APIENTRY *LPALSOURCEPAUSEV)( ALsizei ns, const ALuint *sids );
-typedef void           (AL_APIENTRY *LPALSOURCEPLAY)( ALuint sid );
-typedef void           (AL_APIENTRY *LPALSOURCESTOP)( ALuint sid );
-typedef void           (AL_APIENTRY *LPALSOURCEREWIND)( ALuint sid );
-typedef void           (AL_APIENTRY *LPALSOURCEPAUSE)( ALuint sid );
-typedef void           (AL_APIENTRY *LPALSOURCEQUEUEBUFFERS)(ALuint sid, ALsizei numEntries, const ALuint *bids );
-typedef void           (AL_APIENTRY *LPALSOURCEUNQUEUEBUFFERS)(ALuint sid, ALsizei numEntries, ALuint *bids );
-typedef void           (AL_APIENTRY *LPALGENBUFFERS)( ALsizei n, ALuint* buffers );
-typedef void           (AL_APIENTRY *LPALDELETEBUFFERS)( ALsizei n, const ALuint* buffers );
-typedef ALboolean      (AL_APIENTRY *LPALISBUFFER)( ALuint bid );
-typedef void           (AL_APIENTRY *LPALBUFFERDATA)( ALuint bid, ALenum format, const ALvoid* data, ALsizei size, ALsizei freq );
-typedef void           (AL_APIENTRY *LPALBUFFERF)( ALuint bid, ALenum param, ALfloat value);
-typedef void           (AL_APIENTRY *LPALBUFFER3F)( ALuint bid, ALenum param, ALfloat value1, ALfloat value2, ALfloat value3 );
-typedef void           (AL_APIENTRY *LPALBUFFERFV)( ALuint bid, ALenum param, const ALfloat* values );
-typedef void           (AL_APIENTRY *LPALBUFFERI)( ALuint bid, ALenum param, ALint value);
-typedef void           (AL_APIENTRY *LPALBUFFER3I)( ALuint bid, ALenum param, ALint value1, ALint value2, ALint value3 );
-typedef void           (AL_APIENTRY *LPALBUFFERIV)( ALuint bid, ALenum param, const ALint* values );
-typedef void           (AL_APIENTRY *LPALGETBUFFERF)( ALuint bid, ALenum param, ALfloat* value );
-typedef void           (AL_APIENTRY *LPALGETBUFFER3F)( ALuint bid, ALenum param, ALfloat* value1, ALfloat* value2, ALfloat* value3);
-typedef void           (AL_APIENTRY *LPALGETBUFFERFV)( ALuint bid, ALenum param, ALfloat* values );
-typedef void           (AL_APIENTRY *LPALGETBUFFERI)( ALuint bid, ALenum param, ALint* value );
-typedef void           (AL_APIENTRY *LPALGETBUFFER3I)( ALuint bid, ALenum param, ALint* value1, ALint* value2, ALint* value3);
-typedef void           (AL_APIENTRY *LPALGETBUFFERIV)( ALuint bid, ALenum param, ALint* values );
-typedef void           (AL_APIENTRY *LPALDOPPLERFACTOR)( ALfloat value );
-typedef void           (AL_APIENTRY *LPALDOPPLERVELOCITY)( ALfloat value );
-typedef void           (AL_APIENTRY *LPALSPEEDOFSOUND)( ALfloat value );
-typedef void           (AL_APIENTRY *LPALDISTANCEMODEL)( ALenum distanceModel );
+/**
+ * Extension support.
+ *
+ * Query for the presence of an extension, and obtain any appropriate function
+ * pointers and enum values.
+ */
+AL_API ALboolean AL_APIENTRY alIsExtensionPresent(const ALchar *extname);
+AL_API void* AL_APIENTRY alGetProcAddress(const ALchar *fname);
+AL_API ALenum AL_APIENTRY alGetEnumValue(const ALchar *ename);
+
+
+/** Set Listener parameters */
+AL_API void AL_APIENTRY alListenerf(ALenum param, ALfloat value);
+AL_API void AL_APIENTRY alListener3f(ALenum param, ALfloat value1, ALfloat value2, ALfloat value3);
+AL_API void AL_APIENTRY alListenerfv(ALenum param, const ALfloat *values);
+AL_API void AL_APIENTRY alListeneri(ALenum param, ALint value);
+AL_API void AL_APIENTRY alListener3i(ALenum param, ALint value1, ALint value2, ALint value3);
+AL_API void AL_APIENTRY alListeneriv(ALenum param, const ALint *values);
+
+/** Get Listener parameters */
+AL_API void AL_APIENTRY alGetListenerf(ALenum param, ALfloat *value);
+AL_API void AL_APIENTRY alGetListener3f(ALenum param, ALfloat *value1, ALfloat *value2, ALfloat *value3);
+AL_API void AL_APIENTRY alGetListenerfv(ALenum param, ALfloat *values);
+AL_API void AL_APIENTRY alGetListeneri(ALenum param, ALint *value);
+AL_API void AL_APIENTRY alGetListener3i(ALenum param, ALint *value1, ALint *value2, ALint *value3);
+AL_API void AL_APIENTRY alGetListeneriv(ALenum param, ALint *values);
+
+
+/** Create Source objects. */
+AL_API void AL_APIENTRY alGenSources(ALsizei n, ALuint *sources);
+/** Delete Source objects. */
+AL_API void AL_APIENTRY alDeleteSources(ALsizei n, const ALuint *sources);
+/** Verify a handle is a valid Source. */
+AL_API ALboolean AL_APIENTRY alIsSource(ALuint source);
+
+/** Set Source parameters. */
+AL_API void AL_APIENTRY alSourcef(ALuint source, ALenum param, ALfloat value);
+AL_API void AL_APIENTRY alSource3f(ALuint source, ALenum param, ALfloat value1, ALfloat value2, ALfloat value3);
+AL_API void AL_APIENTRY alSourcefv(ALuint source, ALenum param, const ALfloat *values);
+AL_API void AL_APIENTRY alSourcei(ALuint source, ALenum param, ALint value);
+AL_API void AL_APIENTRY alSource3i(ALuint source, ALenum param, ALint value1, ALint value2, ALint value3);
+AL_API void AL_APIENTRY alSourceiv(ALuint source, ALenum param, const ALint *values);
+
+/** Get Source parameters. */
+AL_API void AL_APIENTRY alGetSourcef(ALuint source, ALenum param, ALfloat *value);
+AL_API void AL_APIENTRY alGetSource3f(ALuint source, ALenum param, ALfloat *value1, ALfloat *value2, ALfloat *value3);
+AL_API void AL_APIENTRY alGetSourcefv(ALuint source, ALenum param, ALfloat *values);
+AL_API void AL_APIENTRY alGetSourcei(ALuint source,  ALenum param, ALint *value);
+AL_API void AL_APIENTRY alGetSource3i(ALuint source, ALenum param, ALint *value1, ALint *value2, ALint *value3);
+AL_API void AL_APIENTRY alGetSourceiv(ALuint source,  ALenum param, ALint *values);
+
+
+/** Play, replay, or resume (if paused) a list of Sources */
+AL_API void AL_APIENTRY alSourcePlayv(ALsizei n, const ALuint *sources);
+/** Stop a list of Sources */
+AL_API void AL_APIENTRY alSourceStopv(ALsizei n, const ALuint *sources);
+/** Rewind a list of Sources */
+AL_API void AL_APIENTRY alSourceRewindv(ALsizei n, const ALuint *sources);
+/** Pause a list of Sources */
+AL_API void AL_APIENTRY alSourcePausev(ALsizei n, const ALuint *sources);
+
+/** Play, replay, or resume a Source */
+AL_API void AL_APIENTRY alSourcePlay(ALuint source);
+/** Stop a Source */
+AL_API void AL_APIENTRY alSourceStop(ALuint source);
+/** Rewind a Source (set playback postiton to beginning) */
+AL_API void AL_APIENTRY alSourceRewind(ALuint source);
+/** Pause a Source */
+AL_API void AL_APIENTRY alSourcePause(ALuint source);
+
+/** Queue buffers onto a source */
+AL_API void AL_APIENTRY alSourceQueueBuffers(ALuint source, ALsizei nb, const ALuint *buffers);
+/** Unqueue processed buffers from a source */
+AL_API void AL_APIENTRY alSourceUnqueueBuffers(ALuint source, ALsizei nb, ALuint *buffers);
+
+
+/** Create Buffer objects */
+AL_API void AL_APIENTRY alGenBuffers(ALsizei n, ALuint *buffers);
+/** Delete Buffer objects */
+AL_API void AL_APIENTRY alDeleteBuffers(ALsizei n, const ALuint *buffers);
+/** Verify a handle is a valid Buffer */
+AL_API ALboolean AL_APIENTRY alIsBuffer(ALuint buffer);
+
+/** Specifies the data to be copied into a buffer */
+AL_API void AL_APIENTRY alBufferData(ALuint buffer, ALenum format, const ALvoid *data, ALsizei size, ALsizei freq);
+
+/** Set Buffer parameters, */
+AL_API void AL_APIENTRY alBufferf(ALuint buffer, ALenum param, ALfloat value);
+AL_API void AL_APIENTRY alBuffer3f(ALuint buffer, ALenum param, ALfloat value1, ALfloat value2, ALfloat value3);
+AL_API void AL_APIENTRY alBufferfv(ALuint buffer, ALenum param, const ALfloat *values);
+AL_API void AL_APIENTRY alBufferi(ALuint buffer, ALenum param, ALint value);
+AL_API void AL_APIENTRY alBuffer3i(ALuint buffer, ALenum param, ALint value1, ALint value2, ALint value3);
+AL_API void AL_APIENTRY alBufferiv(ALuint buffer, ALenum param, const ALint *values);
+
+/** Get Buffer parameters. */
+AL_API void AL_APIENTRY alGetBufferf(ALuint buffer, ALenum param, ALfloat *value);
+AL_API void AL_APIENTRY alGetBuffer3f(ALuint buffer, ALenum param, ALfloat *value1, ALfloat *value2, ALfloat *value3);
+AL_API void AL_APIENTRY alGetBufferfv(ALuint buffer, ALenum param, ALfloat *values);
+AL_API void AL_APIENTRY alGetBufferi(ALuint buffer, ALenum param, ALint *value);
+AL_API void AL_APIENTRY alGetBuffer3i(ALuint buffer, ALenum param, ALint *value1, ALint *value2, ALint *value3);
+AL_API void AL_APIENTRY alGetBufferiv(ALuint buffer, ALenum param, ALint *values);
+
+/** Pointer-to-function type, useful for dynamically getting AL entry points. */
+typedef void          (AL_APIENTRY *LPALENABLE)(ALenum capability);
+typedef void          (AL_APIENTRY *LPALDISABLE)(ALenum capability);
+typedef ALboolean     (AL_APIENTRY *LPALISENABLED)(ALenum capability);
+typedef const ALchar* (AL_APIENTRY *LPALGETSTRING)(ALenum param);
+typedef void          (AL_APIENTRY *LPALGETBOOLEANV)(ALenum param, ALboolean *values);
+typedef void          (AL_APIENTRY *LPALGETINTEGERV)(ALenum param, ALint *values);
+typedef void          (AL_APIENTRY *LPALGETFLOATV)(ALenum param, ALfloat *values);
+typedef void          (AL_APIENTRY *LPALGETDOUBLEV)(ALenum param, ALdouble *values);
+typedef ALboolean     (AL_APIENTRY *LPALGETBOOLEAN)(ALenum param);
+typedef ALint         (AL_APIENTRY *LPALGETINTEGER)(ALenum param);
+typedef ALfloat       (AL_APIENTRY *LPALGETFLOAT)(ALenum param);
+typedef ALdouble      (AL_APIENTRY *LPALGETDOUBLE)(ALenum param);
+typedef ALenum        (AL_APIENTRY *LPALGETERROR)(void);
+typedef ALboolean     (AL_APIENTRY *LPALISEXTENSIONPRESENT)(const ALchar *extname);
+typedef void*         (AL_APIENTRY *LPALGETPROCADDRESS)(const ALchar *fname);
+typedef ALenum        (AL_APIENTRY *LPALGETENUMVALUE)(const ALchar *ename);
+typedef void          (AL_APIENTRY *LPALLISTENERF)(ALenum param, ALfloat value);
+typedef void          (AL_APIENTRY *LPALLISTENER3F)(ALenum param, ALfloat value1, ALfloat value2, ALfloat value3);
+typedef void          (AL_APIENTRY *LPALLISTENERFV)(ALenum param, const ALfloat *values);
+typedef void          (AL_APIENTRY *LPALLISTENERI)(ALenum param, ALint value);
+typedef void          (AL_APIENTRY *LPALLISTENER3I)(ALenum param, ALint value1, ALint value2, ALint value3);
+typedef void          (AL_APIENTRY *LPALLISTENERIV)(ALenum param, const ALint *values);
+typedef void          (AL_APIENTRY *LPALGETLISTENERF)(ALenum param, ALfloat *value);
+typedef void          (AL_APIENTRY *LPALGETLISTENER3F)(ALenum param, ALfloat *value1, ALfloat *value2, ALfloat *value3);
+typedef void          (AL_APIENTRY *LPALGETLISTENERFV)(ALenum param, ALfloat *values);
+typedef void          (AL_APIENTRY *LPALGETLISTENERI)(ALenum param, ALint *value);
+typedef void          (AL_APIENTRY *LPALGETLISTENER3I)(ALenum param, ALint *value1, ALint *value2, ALint *value3);
+typedef void          (AL_APIENTRY *LPALGETLISTENERIV)(ALenum param, ALint *values);
+typedef void          (AL_APIENTRY *LPALGENSOURCES)(ALsizei n, ALuint *sources);
+typedef void          (AL_APIENTRY *LPALDELETESOURCES)(ALsizei n, const ALuint *sources);
+typedef ALboolean     (AL_APIENTRY *LPALISSOURCE)(ALuint source);
+typedef void          (AL_APIENTRY *LPALSOURCEF)(ALuint source, ALenum param, ALfloat value);
+typedef void          (AL_APIENTRY *LPALSOURCE3F)(ALuint source, ALenum param, ALfloat value1, ALfloat value2, ALfloat value3);
+typedef void          (AL_APIENTRY *LPALSOURCEFV)(ALuint source, ALenum param, const ALfloat *values);
+typedef void          (AL_APIENTRY *LPALSOURCEI)(ALuint source, ALenum param, ALint value);
+typedef void          (AL_APIENTRY *LPALSOURCE3I)(ALuint source, ALenum param, ALint value1, ALint value2, ALint value3);
+typedef void          (AL_APIENTRY *LPALSOURCEIV)(ALuint source, ALenum param, const ALint *values);
+typedef void          (AL_APIENTRY *LPALGETSOURCEF)(ALuint source, ALenum param, ALfloat *value);
+typedef void          (AL_APIENTRY *LPALGETSOURCE3F)(ALuint source, ALenum param, ALfloat *value1, ALfloat *value2, ALfloat *value3);
+typedef void          (AL_APIENTRY *LPALGETSOURCEFV)(ALuint source, ALenum param, ALfloat *values);
+typedef void          (AL_APIENTRY *LPALGETSOURCEI)(ALuint source, ALenum param, ALint *value);
+typedef void          (AL_APIENTRY *LPALGETSOURCE3I)(ALuint source, ALenum param, ALint *value1, ALint *value2, ALint *value3);
+typedef void          (AL_APIENTRY *LPALGETSOURCEIV)(ALuint source, ALenum param, ALint *values);
+typedef void          (AL_APIENTRY *LPALSOURCEPLAYV)(ALsizei n, const ALuint *sources);
+typedef void          (AL_APIENTRY *LPALSOURCESTOPV)(ALsizei n, const ALuint *sources);
+typedef void          (AL_APIENTRY *LPALSOURCEREWINDV)(ALsizei n, const ALuint *sources);
+typedef void          (AL_APIENTRY *LPALSOURCEPAUSEV)(ALsizei n, const ALuint *sources);
+typedef void          (AL_APIENTRY *LPALSOURCEPLAY)(ALuint source);
+typedef void          (AL_APIENTRY *LPALSOURCESTOP)(ALuint source);
+typedef void          (AL_APIENTRY *LPALSOURCEREWIND)(ALuint source);
+typedef void          (AL_APIENTRY *LPALSOURCEPAUSE)(ALuint source);
+typedef void          (AL_APIENTRY *LPALSOURCEQUEUEBUFFERS)(ALuint source, ALsizei nb, const ALuint *buffers);
+typedef void          (AL_APIENTRY *LPALSOURCEUNQUEUEBUFFERS)(ALuint source, ALsizei nb, ALuint *buffers);
+typedef void          (AL_APIENTRY *LPALGENBUFFERS)(ALsizei n, ALuint *buffers);
+typedef void          (AL_APIENTRY *LPALDELETEBUFFERS)(ALsizei n, const ALuint *buffers);
+typedef ALboolean     (AL_APIENTRY *LPALISBUFFER)(ALuint buffer);
+typedef void          (AL_APIENTRY *LPALBUFFERDATA)(ALuint buffer, ALenum format, const ALvoid *data, ALsizei size, ALsizei freq);
+typedef void          (AL_APIENTRY *LPALBUFFERF)(ALuint buffer, ALenum param, ALfloat value);
+typedef void          (AL_APIENTRY *LPALBUFFER3F)(ALuint buffer, ALenum param, ALfloat value1, ALfloat value2, ALfloat value3);
+typedef void          (AL_APIENTRY *LPALBUFFERFV)(ALuint buffer, ALenum param, const ALfloat *values);
+typedef void          (AL_APIENTRY *LPALBUFFERI)(ALuint buffer, ALenum param, ALint value);
+typedef void          (AL_APIENTRY *LPALBUFFER3I)(ALuint buffer, ALenum param, ALint value1, ALint value2, ALint value3);
+typedef void          (AL_APIENTRY *LPALBUFFERIV)(ALuint buffer, ALenum param, const ALint *values);
+typedef void          (AL_APIENTRY *LPALGETBUFFERF)(ALuint buffer, ALenum param, ALfloat *value);
+typedef void          (AL_APIENTRY *LPALGETBUFFER3F)(ALuint buffer, ALenum param, ALfloat *value1, ALfloat *value2, ALfloat *value3);
+typedef void          (AL_APIENTRY *LPALGETBUFFERFV)(ALuint buffer, ALenum param, ALfloat *values);
+typedef void          (AL_APIENTRY *LPALGETBUFFERI)(ALuint buffer, ALenum param, ALint *value);
+typedef void          (AL_APIENTRY *LPALGETBUFFER3I)(ALuint buffer, ALenum param, ALint *value1, ALint *value2, ALint *value3);
+typedef void          (AL_APIENTRY *LPALGETBUFFERIV)(ALuint buffer, ALenum param, ALint *values);
+typedef void          (AL_APIENTRY *LPALDOPPLERFACTOR)(ALfloat value);
+typedef void          (AL_APIENTRY *LPALDOPPLERVELOCITY)(ALfloat value);
+typedef void          (AL_APIENTRY *LPALSPEEDOFSOUND)(ALfloat value);
+typedef void          (AL_APIENTRY *LPALDISTANCEMODEL)(ALenum distanceModel);
 
 #if defined(__cplusplus)
-}  /* extern "C" */
+}  / *extern "C" */
 #endif
 
 #endif /* AL_AL_H */
diff --git a/include/AL/alc.h b/include/AL/alc.h
index 9590896f..e7a512ce 100644
--- a/include/AL/alc.h
+++ b/include/AL/alc.h
@@ -22,21 +22,19 @@ extern "C" {
 #endif
 
 
-/*
- * The ALCAPI, ALCAPIENTRY, and ALC_INVALID macros are deprecated, but are
- * included for applications porting code from AL 1.0
- */
-#define ALCAPI ALC_API
-#define ALCAPIENTRY ALC_APIENTRY
-#define ALC_INVALID 0
-
+/** Deprecated macro. */
+#define ALCAPI                                   ALC_API
+#define ALCAPIENTRY                              ALC_APIENTRY
+#define ALC_INVALID                              0
 
-#define ALC_VERSION_0_1         1
+/** Supported ALC version? */
+#define ALC_VERSION_0_1                          1
 
+/** Opaque device handle */
 typedef struct ALCdevice_struct ALCdevice;
+/** Opaque context handle */
 typedef struct ALCcontext_struct ALCcontext;
 
-
 /** 8-bit boolean */
 typedef char ALCboolean;
 
@@ -79,192 +77,158 @@ typedef void ALCvoid;
 
 /* Enumerant values begin at column 50. No tabs. */
 
-/* Boolean False. */
+/** Boolean False. */
 #define ALC_FALSE                                0
 
-/* Boolean True. */
+/** Boolean True. */
 #define ALC_TRUE                                 1
 
-/**
- * followed by <int> Hz
- */
+/** Context attribute: <int> Hz. */
 #define ALC_FREQUENCY                            0x1007
 
-/**
- * followed by <int> Hz
- */
+/** Context attribute: <int> Hz. */
 #define ALC_REFRESH                              0x1008
 
-/**
- * followed by AL_TRUE, AL_FALSE
- */
+/** Context attribute: AL_TRUE or AL_FALSE. */
 #define ALC_SYNC                                 0x1009
 
-/**
- * followed by <int> Num of requested Mono (3D) Sources
- */
+/** Context attribute: <int> requested Mono (3D) Sources. */
 #define ALC_MONO_SOURCES                         0x1010
 
-/**
- * followed by <int> Num of requested Stereo Sources
- */
+/** Context attribute: <int> requested Stereo Sources. */
 #define ALC_STEREO_SOURCES                       0x1011
 
-/**
- * errors
- */
-
-/**
- * No error
- */
+/** No error. */
 #define ALC_NO_ERROR                             0
 
-/**
- * No device
- */
+/** Invalid device handle. */
 #define ALC_INVALID_DEVICE                       0xA001
 
-/**
- * invalid context ID
- */
+/** Invalid context handle. */
 #define ALC_INVALID_CONTEXT                      0xA002
 
-/**
- * bad enum
- */
+/** Invalid enum parameter passed to an ALC call. */
 #define ALC_INVALID_ENUM                         0xA003
 
-/**
- * bad value
- */
+/** Invalid value parameter passed to an ALC call. */
 #define ALC_INVALID_VALUE                        0xA004
 
-/**
- * Out of memory.
- */
+/** Out of memory. */
 #define ALC_OUT_OF_MEMORY                        0xA005
 
 
+/** String for the default device specifier. */
+#define ALC_DEFAULT_DEVICE_SPECIFIER             0x1004
 /**
- * The Specifier string for default device
+ * String for the given device's specifier.
+ *
+ * If device handle is NULL, it is instead a null-char separated list of
+ * strings of known device specifiers (list ends with an empty string).
  */
-#define ALC_DEFAULT_DEVICE_SPECIFIER             0x1004
 #define ALC_DEVICE_SPECIFIER                     0x1005
+/** String for space-separated list of ALC extensions. */
 #define ALC_EXTENSIONS                           0x1006
 
+/** Runtime ALC version. */
 #define ALC_MAJOR_VERSION                        0x1000
 #define ALC_MINOR_VERSION                        0x1001
 
+/** Context attribute list properties. */
 #define ALC_ATTRIBUTES_SIZE                      0x1002
 #define ALC_ALL_ATTRIBUTES                       0x1003
 
 
+/** Capture extension */
+#define ALC_EXT_CAPTURE 1
 /**
- * Capture extension
+ * String for the given capture device's specifier.
+ *
+ * If device handle is NULL, it is instead a null-char separated list of
+ * strings of known capture device specifiers (list ends with an empty string).
  */
-#define ALC_EXT_CAPTURE 1
 #define ALC_CAPTURE_DEVICE_SPECIFIER             0x310
+/** String for the default capture device specifier. */
 #define ALC_CAPTURE_DEFAULT_DEVICE_SPECIFIER     0x311
+/** Number of sample frames available for capture. */
 #define ALC_CAPTURE_SAMPLES                      0x312
 
 
-/**
- * ALC_ENUMERATE_ALL_EXT enums
- */
+/** Enumerate All extension */
 #define ALC_ENUMERATE_ALL_EXT 1
+/** String for the default extended device specifier. */
 #define ALC_DEFAULT_ALL_DEVICES_SPECIFIER        0x1012
-#define ALC_ALL_DEVICES_SPECIFIER                0x1013
-
-
-/*
- * Context Management
+/**
+ * String for the given extended device's specifier.
+ *
+ * If device handle is NULL, it is instead a null-char separated list of
+ * strings of known extended device specifiers (list ends with an empty string).
  */
-ALC_API ALCcontext *    ALC_APIENTRY alcCreateContext( ALCdevice *device, const ALCint* attrlist );
-
-ALC_API ALCboolean      ALC_APIENTRY alcMakeContextCurrent( ALCcontext *context );
-
-ALC_API void            ALC_APIENTRY alcProcessContext( ALCcontext *context );
-
-ALC_API void            ALC_APIENTRY alcSuspendContext( ALCcontext *context );
-
-ALC_API void            ALC_APIENTRY alcDestroyContext( ALCcontext *context );
-
-ALC_API ALCcontext *    ALC_APIENTRY alcGetCurrentContext( void );
-
-ALC_API ALCdevice*      ALC_APIENTRY alcGetContextsDevice( ALCcontext *context );
+#define ALC_ALL_DEVICES_SPECIFIER                0x1013
 
 
-/*
- * Device Management
- */
-ALC_API ALCdevice *     ALC_APIENTRY alcOpenDevice( const ALCchar *devicename );
+/** Context management. */
+ALC_API ALCcontext* ALC_APIENTRY alcCreateContext(ALCdevice *device, const ALCint* attrlist);
+ALC_API ALCboolean  ALC_APIENTRY alcMakeContextCurrent(ALCcontext *context);
+ALC_API void        ALC_APIENTRY alcProcessContext(ALCcontext *context);
+ALC_API void        ALC_APIENTRY alcSuspendContext(ALCcontext *context);
+ALC_API void        ALC_APIENTRY alcDestroyContext(ALCcontext *context);
+ALC_API ALCcontext* ALC_APIENTRY alcGetCurrentContext(void);
+ALC_API ALCdevice*  ALC_APIENTRY alcGetContextsDevice(ALCcontext *context);
 
-ALC_API ALCboolean      ALC_APIENTRY alcCloseDevice( ALCdevice *device );
+/** Device management. */
+ALC_API ALCdevice* ALC_APIENTRY alcOpenDevice(const ALCchar *devicename);
+ALC_API ALCboolean ALC_APIENTRY alcCloseDevice(ALCdevice *device);
 
 
-/*
+/**
  * Error support.
- * Obtain the most recent Context error
+ *
+ * Obtain the most recent Device error.
  */
-ALC_API ALCenum         ALC_APIENTRY alcGetError( ALCdevice *device );
-
+ALC_API ALCenum ALC_APIENTRY alcGetError(ALCdevice *device);
 
-/* 
+/**
  * Extension support.
+ *
  * Query for the presence of an extension, and obtain any appropriate
  * function pointers and enum values.
  */
-ALC_API ALCboolean      ALC_APIENTRY alcIsExtensionPresent( ALCdevice *device, const ALCchar *extname );
-
-ALC_API void  *         ALC_APIENTRY alcGetProcAddress( ALCdevice *device, const ALCchar *funcname );
-
-ALC_API ALCenum         ALC_APIENTRY alcGetEnumValue( ALCdevice *device, const ALCchar *enumname );
-
-
-/*
- * Query functions
- */
-ALC_API const ALCchar * ALC_APIENTRY alcGetString( ALCdevice *device, ALCenum param );
-
-ALC_API void            ALC_APIENTRY alcGetIntegerv( ALCdevice *device, ALCenum param, ALCsizei size, ALCint *data );
-
-
-/*
- * Capture functions
- */
-ALC_API ALCdevice*      ALC_APIENTRY alcCaptureOpenDevice( const ALCchar *devicename, ALCuint frequency, ALCenum format, ALCsizei buffersize );
-
-ALC_API ALCboolean      ALC_APIENTRY alcCaptureCloseDevice( ALCdevice *device );
-
-ALC_API void            ALC_APIENTRY alcCaptureStart( ALCdevice *device );
-
-ALC_API void            ALC_APIENTRY alcCaptureStop( ALCdevice *device );
-
-ALC_API void            ALC_APIENTRY alcCaptureSamples( ALCdevice *device, ALCvoid *buffer, ALCsizei samples );
-
-/*
- * Pointer-to-function types, useful for dynamically getting ALC entry points.
- */
-typedef ALCcontext *   (ALC_APIENTRY *LPALCCREATECONTEXT) (ALCdevice *device, const ALCint *attrlist);
-typedef ALCboolean     (ALC_APIENTRY *LPALCMAKECONTEXTCURRENT)( ALCcontext *context );
-typedef void           (ALC_APIENTRY *LPALCPROCESSCONTEXT)( ALCcontext *context );
-typedef void           (ALC_APIENTRY *LPALCSUSPENDCONTEXT)( ALCcontext *context );
-typedef void           (ALC_APIENTRY *LPALCDESTROYCONTEXT)( ALCcontext *context );
-typedef ALCcontext *   (ALC_APIENTRY *LPALCGETCURRENTCONTEXT)( void );
-typedef ALCdevice *    (ALC_APIENTRY *LPALCGETCONTEXTSDEVICE)( ALCcontext *context );
-typedef ALCdevice *    (ALC_APIENTRY *LPALCOPENDEVICE)( const ALCchar *devicename );
-typedef ALCboolean     (ALC_APIENTRY *LPALCCLOSEDEVICE)( ALCdevice *device );
-typedef ALCenum        (ALC_APIENTRY *LPALCGETERROR)( ALCdevice *device );
-typedef ALCboolean     (ALC_APIENTRY *LPALCISEXTENSIONPRESENT)( ALCdevice *device, const ALCchar *extname );
-typedef void *         (ALC_APIENTRY *LPALCGETPROCADDRESS)(ALCdevice *device, const ALCchar *funcname );
-typedef ALCenum        (ALC_APIENTRY *LPALCGETENUMVALUE)(ALCdevice *device, const ALCchar *enumname );
-typedef const ALCchar* (ALC_APIENTRY *LPALCGETSTRING)( ALCdevice *device, ALCenum param );
-typedef void           (ALC_APIENTRY *LPALCGETINTEGERV)( ALCdevice *device, ALCenum param, ALCsizei size, ALCint *dest );
-typedef ALCdevice *    (ALC_APIENTRY *LPALCCAPTUREOPENDEVICE)( const ALCchar *devicename, ALCuint frequency, ALCenum format, ALCsizei buffersize );
-typedef ALCboolean     (ALC_APIENTRY *LPALCCAPTURECLOSEDEVICE)( ALCdevice *device );
-typedef void           (ALC_APIENTRY *LPALCCAPTURESTART)( ALCdevice *device );
-typedef void           (ALC_APIENTRY *LPALCCAPTURESTOP)( ALCdevice *device );
-typedef void           (ALC_APIENTRY *LPALCCAPTURESAMPLES)( ALCdevice *device, ALCvoid *buffer, ALCsizei samples );
+ALC_API ALCboolean ALC_APIENTRY alcIsExtensionPresent(ALCdevice *device, const ALCchar *extname);
+ALC_API void*      ALC_APIENTRY alcGetProcAddress(ALCdevice *device, const ALCchar *funcname);
+ALC_API ALCenum    ALC_APIENTRY alcGetEnumValue(ALCdevice *device, const ALCchar *enumname);
+
+/** Query function. */
+ALC_API const ALCchar* ALC_APIENTRY alcGetString(ALCdevice *device, ALCenum param);
+ALC_API void           ALC_APIENTRY alcGetIntegerv(ALCdevice *device, ALCenum param, ALCsizei size, ALCint *values);
+
+/** Capture function. */
+ALC_API ALCdevice* ALC_APIENTRY alcCaptureOpenDevice(const ALCchar *devicename, ALCuint frequency, ALCenum format, ALCsizei buffersize);
+ALC_API ALCboolean ALC_APIENTRY alcCaptureCloseDevice(ALCdevice *device);
+ALC_API void       ALC_APIENTRY alcCaptureStart(ALCdevice *device);
+ALC_API void       ALC_APIENTRY alcCaptureStop(ALCdevice *device);
+ALC_API void       ALC_APIENTRY alcCaptureSamples(ALCdevice *device, ALCvoid *buffer, ALCsizei samples);
+
+/** Pointer-to-function type, useful for dynamically getting ALC entry points. */
+typedef ALCcontext*    (ALC_APIENTRY *LPALCCREATECONTEXT)(ALCdevice *device, const ALCint *attrlist);
+typedef ALCboolean     (ALC_APIENTRY *LPALCMAKECONTEXTCURRENT)(ALCcontext *context);
+typedef void           (ALC_APIENTRY *LPALCPROCESSCONTEXT)(ALCcontext *context);
+typedef void           (ALC_APIENTRY *LPALCSUSPENDCONTEXT)(ALCcontext *context);
+typedef void           (ALC_APIENTRY *LPALCDESTROYCONTEXT)(ALCcontext *context);
+typedef ALCcontext*    (ALC_APIENTRY *LPALCGETCURRENTCONTEXT)(void);
+typedef ALCdevice*     (ALC_APIENTRY *LPALCGETCONTEXTSDEVICE)(ALCcontext *context);
+typedef ALCdevice*     (ALC_APIENTRY *LPALCOPENDEVICE)(const ALCchar *devicename);
+typedef ALCboolean     (ALC_APIENTRY *LPALCCLOSEDEVICE)(ALCdevice *device);
+typedef ALCenum        (ALC_APIENTRY *LPALCGETERROR)(ALCdevice *device);
+typedef ALCboolean     (ALC_APIENTRY *LPALCISEXTENSIONPRESENT)(ALCdevice *device, const ALCchar *extname);
+typedef void*          (ALC_APIENTRY *LPALCGETPROCADDRESS)(ALCdevice *device, const ALCchar *funcname);
+typedef ALCenum        (ALC_APIENTRY *LPALCGETENUMVALUE)(ALCdevice *device, const ALCchar *enumname);
+typedef const ALCchar* (ALC_APIENTRY *LPALCGETSTRING)(ALCdevice *device, ALCenum param);
+typedef void           (ALC_APIENTRY *LPALCGETINTEGERV)(ALCdevice *device, ALCenum param, ALCsizei size, ALCint *values);
+typedef ALCdevice*     (ALC_APIENTRY *LPALCCAPTUREOPENDEVICE)(const ALCchar *devicename, ALCuint frequency, ALCenum format, ALCsizei buffersize);
+typedef ALCboolean     (ALC_APIENTRY *LPALCCAPTURECLOSEDEVICE)(ALCdevice *device);
+typedef void           (ALC_APIENTRY *LPALCCAPTURESTART)(ALCdevice *device);
+typedef void           (ALC_APIENTRY *LPALCCAPTURESTOP)(ALCdevice *device);
+typedef void           (ALC_APIENTRY *LPALCCAPTURESAMPLES)(ALCdevice *device, ALCvoid *buffer, ALCsizei samples);
 
 #if defined(__cplusplus)
 }