diff --git a/docs/guide/buffer.md b/docs/guide/buffer.md new file mode 100644 index 0000000000..7aeaf4ecf2 --- /dev/null +++ b/docs/guide/buffer.md @@ -0,0 +1,620 @@ +## Buffer Functions +### Properties + +| Property | Data Type | Description | +| ------------ | --------- | ----------- | +| AL_FREQUENCY | `i`, `iv` | Frequency of buffer in Hz | +| AL_BITS | `i`, `iv` | Bit depth of buffer | +| AL_CHANNELS | `i`, `iv` | Number of channels in buffer. > 1 is valid, but buffer won’t be positioned when played | +| AL_SIZE | `i`, `iv` | Size of buffer in bytes | +| AL_DATA | `i`, `iv` | Original location where data was copied from generally useless, as was probably freed after buffer creation | + +### Functions +* [alGenBuffers](#algenbuffers) +* [alDeleteBuffers](#aldeletebuffers) +* [alIsBuffer](#alisbuffer) +* [alBufferData](#albufferdata) +* [alBufferf](#albufferf) +* [alBuffer3f](#albuffer3f) +* [alBufferfv](#albufferfv) +* [alBufferi](#albufferi) +* [alBuffer3i](#albuffer3i) +* [alBufferiv](#albufferiv) +* [alGetBufferf](#algetbufferf) +* [alGetBuffer3f](#algetbuffer3f) +* [alGetBufferfv](#algetbufferfv) +* [alGetBufferi](#algetbufferi) +* [alGetBuffer3i](#algetbuffer3i) +* [alGetBufferiv](#algetbufferiv) + +#### alGenBuffers +##### Description +This function generates one or more buffers, which contain audio data (see +[alBufferData](#albufferdata)). References to buffers are `ALuint` values, +which are used wherever a buffer reference is needed (in calls such as +[alDeleteBuffers](#aldeletebuffers), [alSourcei](source.md#alsourcei), +[alSourceQueueBuffers](source.md#alsourcequeuebuffers), and +[alSourceUnqueueBuffers](source.md#alsourceunqueuebuffers)). + +```cpp +void alGenBuffers( + ALsizei n, + ALuint *buffers +); +``` + +##### Parameters +* n - The number of buffers to be generated +* buffers - Pointer to an array of ALuint values which will store the names of + the new buffers + +##### Possible Error States +| State | Description | +| ---------------- | ----------- | +| AL_INVALID_VALUE | The buffer array isn't large enough to hold the number of buffers requested. | +| AL_OUT_OF_MEMORY | There is not enough memory available to generate all the buffers requested. | + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +If the requested number of buffers cannot be created, an error will be generated +which can be detected with [alGetError](error.md#algeterror). If an error +occurs, no buffers will be generated. If `n` equals zero, +[alGenBuffers](#algenbuffers) does nothing and does not return an error. + +##### See Also +[alDeleteBuffers](#aldeletebuffers), [alIsBuffer](#alisbuffer) + +#### alDeleteBuffers +##### Description +This function deletes one or more buffers, freeing the resources used by the +buffer. Buffers which are attached to a source can not be deleted. See +[alSourcei](source.md#alsourcei) and +[alSourceUnqueueBuffers](source.md#alsourceunqueuebuffers) for information on +how to detach a buffer from a source. + +```cpp +void alDeleteBuffers( + ALsizei n, + ALuint *buffers +); +``` + +##### Parameters +* n - The number of buffers to be deleted +* buffers - Pointer to an array of buffer names identifying the buffers to be + deleted + +##### Possible Error States +| State | Description | +| -------------------- | ----------- | +| AL_INVALID_OPERATION | The buffer is still in use and can not be deleted. | +| AL_INVALID_NAME | A buffer name is invalid. | +| AL_INVALID_VALUE | The requested number of buffers can not be deleted. | + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +If the requested number of buffers cannot be deleted, an error will be generated +which can be detected with [alGetError](error.md#algeterror). If an error +occurs, no buffers will be deleted. If `n` equals zero, +[alDeleteBuffers](#alDeleteBuffers) does nothing and will not return an error. + +##### See Also +[alGenBuffers](#alGenBuffers), [alIsBuffer](#alIsBuffer) + +#### alIsBuffer +##### Description +This function tests if a buffer name is valid, returning `AL_TRUE` if valid, +`AL_FALSE` if not. + +```cpp +ALboolean alIsBuffer( + ALuint buffer +); +``` + +##### Parameters +* buffer - A buffer name to be tested for validity + +##### Possible Error States +None + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +The `NULL` buffer is always valid (see [alSourcei](source.md#alsourcei) for +information on how the NULL `buffer` is used). + +##### See Also +[alGenBuffers](#alGenBuffers), [alDeleteBuffers](#aldeletebuffers) + +#### alBufferData +##### Description +This function fills a buffer with audio data. All the pre-defined formats are +PCM data, but this function may be used by extensions to load other data types +as well. + +```cpp +void alBufferData( + ALuint buffer, + ALenum format, + const ALvoid *data, + ALsizei size, + ALsizei freq +); +``` + +##### Parameters +* buffer - Buffer name to be filled with data +* format - Format type from among the following: + + `AL_FORMAT_MONO8` + + `AL_FORMAT_MONO16` + + `AL_FORMAT_STEREO8` + + `AL_FORMAT_STEREO16` +* data - Pointer to the audio data +* size - The size of the data in bytes +* freq - The frequency of the audio data + +##### Possible Error States +| State | Description | +| ---------------- | ----------- | +| AL_OUT_OF_MEMORY | There is not enough memory available to create this buffer. | +| AL_INVALID_VALUE | The size parameter is not valid for the format specified, the buffer is in use, or the data is a `NULL` pointer. | +| AL_INVALID_ENUM | The specified format does not exist. | + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +8-bit PCM data is expressed as an unsigned value over the range 0 to 255, 128 +being an audio output level of zero. 16-bit PCM data is expressed as a signed +value over the range -32768 to 32767, 0 being an audio output level of zero. +Stereo data is expressed in interleaved format, left channel first. Buffers +containing more than one channel of data will be played without 3D +spatialization. + +#### alBufferf +##### Description +This function sets a floating point property of a buffer. + +```cpp +void alBufferf( + ALuint buffer, + ALenum param, + ALfloat value +); +``` + +##### Parameters +* buffer - Buffer name whose attribute is being retrieved +* param - The name of the attribute to be set +* value - The `ALfloat` value to be set + +##### Possible Error States +| State | Description | +| --------------- | ----------- | +| AL_INVALID_ENUM | The specified parameter is not valid. | +| AL_INVALID_NAME | The specified buffer doesn't have parameters (the `NULL` buffer), or doesn't exist. | + +##### Version Requirements +OpenAL 1.1 or higher + +##### Remarks +There are no relevant buffer properties defined in OpenAL 1.1 which can be +affected by this call, but this function may be used by OpenAL extensions. + +##### See Also +[alBuffer3f](#alBuffer3f), [alBufferfv](#alBufferfv), +[alGetBufferf](#alGetBufferf), [alGetBuffer3f](#alGetBuffer3f), +[alGetBufferfv](#alGetBufferfv) + +#### alBuffer3f +##### Description +This function sets a floating point property of a buffer. + +```cpp +void alBuffer3f( + ALuint buffer, + ALenum param, + ALfloat v1, + ALfloat v2, + ALfloat v3 +); +``` + +##### Parameters +* buffer - Buffer name whose attribute is being retrieved +* param - The name of the attribute to be set +* v1, v2, v3 - The `ALfloat` values to be set + +##### Possible Error States +| State | Description | +| --------------- | ----------- | +| AL_INVALID_ENUM | The specified parameter is not valid. | +| AL_INVALID_NAME | The specified buffer doesn't have parameters (the `NULL` buffer), or doesn't exist. | + +##### Version Requirements +OpenAL 1.1 or higher + +##### Remarks +There are no relevant buffer properties defined in OpenAL 1.1 which can be +affected by this call, but this function may be used by OpenAL extensions. + +##### See Also +[alBufferf](#alBufferf), [alBufferfv](#alBufferfv), +[alGetBufferf](#alGetBufferf), [alGetBuffer3f](#alGetBuffer3f), +[alGetBufferfv](#alGetBufferfv) + +#### alBufferfv +##### Description +This function sets a floating point property of a buffer. + +```cpp +void alBuffer3f( + ALuint buffer, + ALenum param, + ALfloat* value +); +``` + +##### Parameters +* buffer - Buffer name whose attribute is being retrieved +* param - The name of the attribute to be set +* values - A pointer to the `ALfloat` values to be set + +##### Possible Error States +| State | Description | +| --------------- | ----------- | +| AL_INVALID_ENUM | The specified parameter is not valid. | +| AL_INVALID_NAME | The specified buffer doesn't have parameters (the `NULL` buffer), or doesn't exist. | + +##### Version Requirements +OpenAL 1.1 or higher + +##### Remarks +There are no relevant buffer properties defined in OpenAL 1.1 which can be +affected by this call, but this function may be used by OpenAL extensions. + +##### See Also +[alBufferf](#alBufferf), [alBuffer3f](#alBuffer3f), +[alGetBufferf](#alGetBufferf), [alGetBuffer3f](#alGetBuffer3f), +[alGetBufferfv](#alGetBufferfv) + +#### alBufferi +##### Description +This function sets an integer property of a buffer. + +```cpp +void alBufferi( + ALuint buffer, + ALenum param, + ALint value +); +``` + +##### Parameters +* buffer - Buffer name whose attribute is being retrieved +* param - The name of the attribute to be set +* values - The `ALint` value to be set + +##### Possible Error States +| State | Description | +| --------------- | ----------- | +| AL_INVALID_ENUM | The specified parameter is not valid. | +| AL_INVALID_NAME | The specified buffer doesn't have parameters (the `NULL` buffer), or doesn't exist. | + +##### Version Requirements +OpenAL 1.1 or higher + +##### Remarks +There are no relevant buffer properties defined in OpenAL 1.1 which can be +affected by this call, but this function may be used by OpenAL extensions. + +##### See Also +[alBuffer3i](#alBuffer3i), [alBufferiv](#alBufferiv), +[alGetBufferi](#alGetBufferf), [alGetBuffer3i](#alGetBuffer3i), +[alGetBufferiv](#alGetBufferiv) + +#### alBuffer3i +##### Description +This function sets an integer property of a buffer. + +```cpp +void alBuffer3i( + ALuint buffer, + ALenum param, + ALint v1, + ALint v2, + ALint v3, +); +``` + +##### Parameters +* buffer - Buffer name whose attribute is being retrieved +* param - The name of the attribute to be set +* v1, v2, v3 - The `ALint` values to be set + +##### Possible Error States +| State | Description | +| --------------- | ----------- | +| AL_INVALID_ENUM | The specified parameter is not valid. | +| AL_INVALID_NAME | The specified buffer doesn't have parameters (the `NULL` buffer), or doesn't exist. | + +##### Version Requirements +OpenAL 1.1 or higher + +##### Remarks +There are no relevant buffer properties defined in OpenAL 1.1 which can be +affected by this call, but this function may be used by OpenAL extensions. + +##### See Also +[alBufferi](#alBufferi), [alBufferiv](#alBufferiv), +[alGetBufferi](#alGetBufferf), [alGetBuffer3i](#alGetBuffer3i), +[alGetBufferiv](#alGetBufferiv) + +#### alBufferiv +##### Description +This function sets an integer property of a buffer. + +```cpp +void alBufferiv( + ALuint buffer, + ALenum param, + ALint* values +); +``` + +##### Parameters +* buffer - Buffer name whose attribute is being retrieved +* param - The name of the attribute to be set +* values - A pointer to the `ALint` values to be set + +##### Possible Error States +| State | Description | +| --------------- | ----------- | +| AL_INVALID_ENUM | The specified parameter is not valid. | +| AL_INVALID_NAME | The specified buffer doesn't have parameters (the `NULL` buffer), or doesn't exist. | + +##### Version Requirements +OpenAL 1.1 or higher + +##### Remarks +There are no relevant buffer properties defined in OpenAL 1.1 which can be +affected by this call, but this function may be used by OpenAL extensions. + +##### See Also +[alBufferi](#alBufferi), [alBuffer3i](#alBuffer3i), +[alGetBufferi](#alGetBufferf), [alGetBuffer3i](#alGetBuffer3i), +[alGetBufferiv](#alGetBufferiv) + +#### alGetBufferf +##### Description +This function retrieves a floating point property of a buffer. + +```cpp +void alGetBufferf( + ALuint buffer, + ALenum pname, + ALfloat* value +); +``` + +##### Parameters +* buffer - Buffer name whose attribute is being retrieved +* param - The name of the attribute to be retrieved +* value - A pointer to an `ALfloat` to hold the retrieved data + +##### Possible Error States +| State | Description | +| ---------------- | ----------- | +| AL_INVALID_ENUM | The specified parameter is not valid. | +| AL_INVALID_NAME | The specified buffer doesn't have parameters (the `NULL` buffer), or doesn't exist. | +| AL_INVALID_VALUE | The specified value pointer is not valid. | + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +There are no relevant buffer properties defined in OpenAL 1.1 which can be +affected by this call, but this function may be used by OpenAL extensions. + +##### See Also +[alBufferf](#alBufferf), [alBuffer3f](#alBuffer3f), +[alBufferfv](#alBufferfv), [alGetBuffer3f](#alGetBuffer3f), +[alGetBufferfv](#alGetBufferfv) + +#### alGetBuffer3f +##### Description +This function retrieves a floating point property of a buffer. + +```cpp +void alGetBuffer3f( + ALuint buffer, + ALenum pname, + ALfloat* v1, + ALfloat* v2, + ALfloat* v3 +); +``` + +##### Parameters +* buffer - Buffer name whose attribute is being retrieved +* param - The name of the attribute to be retrieved +* v1, v2, v3 - Pointers to `ALfloat` values to hold the retrieved data + +##### Possible Error States +| State | Description | +| ---------------- | ----------- | +| AL_INVALID_ENUM | The specified parameter is not valid. | +| AL_INVALID_NAME | The specified buffer doesn't have parameters (the `NULL` buffer), or doesn't exist. | +| AL_INVALID_VALUE | The specified value pointer is not valid. | + +##### Version Requirements +OpenAL 1.1 or higher + +##### Remarks +There are no relevant buffer properties defined in OpenAL 1.1 which can be +affected by this call, but this function may be used by OpenAL extensions. + +##### See Also +[alBufferf](#alBufferf), [alBuffer3f](#alBuffer3f), +[alBufferfv](#alBufferfv), [alGetBufferf](#alGetBufferf), +[alGetBufferfv](#alGetBufferfv) + +#### alGetBufferfv +##### Description +This function retrieves a floating point property of a buffer. + +```cpp +void alGetBufferfv( + ALuint buffer, + ALenum pname, + ALfloat* values +); +``` + +##### Parameters +* buffer - Buffer name whose attribute is being retrieved +* param - The name of the attribute to be retrieved +* values - Pointer to an `ALfloat` vector to hold the retrieved data + +##### Possible Error States +| State | Description | +| ---------------- | ----------- | +| AL_INVALID_ENUM | The specified parameter is not valid. | +| AL_INVALID_NAME | The specified buffer doesn't have parameters (the `NULL` buffer), or doesn't exist. | +| AL_INVALID_VALUE | The specified value pointer is not valid. | + +##### Version Requirements +OpenAL 1.1 or higher + +##### Remarks +There are no relevant buffer properties defined in OpenAL 1.1 which can be +affected by this call, but this function may be used by OpenAL extensions. + +##### See Also +[alBufferf](#alBufferf), [alBuffer3f](#alBuffer3f), +[alBufferfv](#alBufferfv), [alGetBufferf](#alGetBufferf), +[alGetBuffer3f](#alGetBuffer3f) + +#### alGetBufferi +##### Description +This function retrieves an integer property of a buffer. + +```cpp +void alGetBufferi( + ALuint buffer, + ALenum pname, + ALint* value +); +``` + +##### Parameters +* buffer - Buffer name whose attribute is being retrieved +* param - The name of the attribute to be retrieved: + + `AL_FREQUENCY` + + `AL_BITS` + + `AL_CHANNELS` + + `AL_SIZE` + + `AL_DATA` +* value - Pointer to an `ALint` to hold the retrieved data + +##### Possible Error States +| State | Description | +| ---------------- | ----------- | +| AL_INVALID_ENUM | The specified parameter is not valid. | +| AL_INVALID_NAME | The specified buffer doesn't have parameters (the `NULL` buffer), or doesn't exist. | +| AL_INVALID_VALUE | The specified value pointer is not valid. | + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +None + +##### See Also +[alBufferi](#alBufferi), [alBuffer3i](#alBuffer3i), +[alBufferiv](#alBufferiv), [alGetBuffer3i](#alGetBuffer3i), +[alGetBufferiv](#alGetBufferiv) + +#### alGetBuffer3i +##### Description +This function retrieves an integer property of a buffer. + +```cpp +void alGetBuffer3i( + ALuint buffer, + ALenum pname, + ALint* v1, + ALint* v2, + ALint* v3 +); +``` + +##### Parameters +* buffer - Buffer name whose attribute is being retrieved +* param - The name of the attribute to be retrieved +* v1, v2, v3 - Pointer to `ALint` values to hold the retrieved data + +##### Possible Error States +| State | Description | +| ---------------- | ----------- | +| AL_INVALID_ENUM | The specified parameter is not valid. | +| AL_INVALID_NAME | The specified buffer doesn't have parameters (the `NULL` buffer), or doesn't exist. | +| AL_INVALID_VALUE | The specified value pointer is not valid. | + +##### Version Requirements +OpenAL 1.1 or higher + +##### Remarks +There are no relevant buffer properties defined in OpenAL 1.1 which can be +retrieved by this call, but this function may be used by OpenAL extensions. + +##### See Also +[alBufferi](#alBufferi), [alBuffer3i](#alBuffer3i), +[alBufferiv](#alBufferiv), [alGetBufferi](#alGetBufferi), +[alGetBufferiv](#alGetBufferiv) + +#### alGetBufferiv +##### Description +This function retrieves an integer property of a buffer. + +```cpp +void alGetBufferiv( + ALuint buffer, + ALenum pname, + ALint* values +); +``` + +##### Parameters +* buffer - Buffer name whose attribute is being retrieved +* param - The name of the attribute to be retrieved: + + `AL_FREQUENCY` + + `AL_BITS` + + `AL_CHANNELS` + + `AL_SIZE` + + `AL_DATA` +* values - Pointer to an `ALint` vector to hold the retrieved data + +##### Possible Error States +| State | Description | +| ---------------- | ----------- | +| AL_INVALID_ENUM | The specified parameter is not valid. | +| AL_INVALID_NAME | The specified buffer doesn't have parameters (the `NULL` buffer), or doesn't exist. | +| AL_INVALID_VALUE | The specified value pointer is not valid. | + +##### Version Requirements +OpenAL 1.1 or higher + +##### Remarks +None + +##### See Also +[alBufferi](#alBufferi), [alBuffer3i](#alBuffer3i), +[alBufferiv](#alBufferiv), [alGetBufferi](#alGetBufferi), +[alGetBuffer3i](#alGetBuffer3i) diff --git a/docs/guide/context-capture.md b/docs/guide/context-capture.md new file mode 100644 index 0000000000..8e12138a68 --- /dev/null +++ b/docs/guide/context-capture.md @@ -0,0 +1,162 @@ +## Context Capture Functions +### Functions +* [alcCaptureOpenDevice](#alccaptureopendevice) +* [alcCaptureCloseDevice](#alccaptureclosedevice) +* [alcCaptureStart](#alccapturestart) +* [alcCaptureStop](#alccapturestop) +* [alcCaptureSamples](#alccapturesamples) + +#### alcCaptureOpenDevice +##### Description +This function opens a capture device by name. + +```cpp +ALCdevice* alcCaptureOpenDevice( + const ALCchar* devicename, + ALCuint frequency, + ALCenum format, + ALCsizei buffersize +); +``` + +##### Parameters +* devicename - A pointer to a device name string +* frequency - The frequency that the data should be captured at +* format - The requested capture buffer format +* buffersize - The size of the capture buffer + +##### Possible Error States +| State | Description | +| ----------------- | ----------- | +| ALC_INVALID_VALUE | One of the parameters has an invalid value. | +| ALC_OUT_OF_MEMORY | The specified device is invalid, or can not capture audio. | + +##### Version Requirements +OpenAL 1.1 or higher + +##### Remarks +Returns the capture device pointer, or `NULL` on failure. + +##### See Also +[alcCaptureCloseDevice](#alcCaptureCloseDevice) + +#### alcCaptureCloseDevice +##### Description +This function closes the specified capture device. + +```cpp +ALCboolean alcCaptureCloseDevice( + ALCdevice* device +); +``` + +##### Parameters +* device - A pointer to a capture device + +##### Possible Error States +| State | Description | +| ------------------ | ----------- | +| ALC_INVALID_DEVICE | The specified device is not a valid capture device. | + +##### Version Requirements +OpenAL 1.1 or higher + +##### Remarks +Returns `ALC_TRUE` if the close operation was successful, `ALC_FALSE` on +failure. + +##### See Also +[alcCaptureOpenDevice](#alccaptureopendevice) + +#### alcCaptureStart +##### Description +This function begins a capture operation. + +```cpp +void alcCaptureStart( + ALCdevice *device +); +``` + +##### Parameters +* device - A pointer to a capture device + +##### Possible Error States +| State | Description | +| ------------------ | ----------- | +| ALC_INVALID_DEVICE | The specified device is not a valid capture device. | + +##### Version Requirements +OpenAL 1.1 or higher + +##### Remarks +[alcCaptureStart](#alccapturestart) will begin recording to an internal ring +buffer of the size specified when opening the capture device. The application +can then retrieve the number of samples currently available using the +`ALC_CAPTURE_SAMPLES` token with +[alcGetIntegerv](context-state.md#alcgetintegerv). When the application +determines that enough samples are available for processing, then it can obtain +them with a call to [alcCaptureSamples](#alccapturesamples). + +##### See Also +[alcCaptureStop](#alccapturestop), [alcCaptureSamples](#alccapturesamples) + +#### alcCaptureStop +##### Description +This function stops a capture operation. + +```cpp +void alcCaptureStop( + ALCdevice *device +); +``` + +##### Parameters +* device - A pointer to a capture device + +##### Possible Error States +| State | Description | +| ------------------ | ----------- | +| ALC_INVALID_DEVICE | The specified device is not a valid capture device. | + +##### Version Requirements +OpenAL 1.1 or higher + +##### Remarks +None + +##### See Also +[alcCaptureStart](#alccapturestart), [alcCaptureSamples](#alccapturesamples) + +#### alcCaptureSamples +##### Description +This function completes a capture operation, and does not block. + +```cpp +void alcCaptureSamples( + ALCdevice* device, + ALCvoid* buffer, + ALCsizei samples +); +``` + +##### Parameters +* device - A pointer to a capture device +* buffer - A pointer to a data buffer, which must be large enough to accommodate + samples number of samples +* samples - The number of samples to be retrieved + +##### Possible Error States +| State | Description | +| ------------------ | ----------- | +| ALC_INVALID_VALUE | The specified number of samples is larger than the number of available samples. | +| ALC_INVALID_DEVICE | The specified device is not a valid capture device. | + +##### Version Requirements +OpenAL 1.1 or higher + +##### Remarks +None + +##### See Also +[alcCaptureStart](#alccapturestart), [alcCaptureStop](#alccapturestop) diff --git a/docs/guide/context-device.md b/docs/guide/context-device.md new file mode 100644 index 0000000000..7d15f73bfb --- /dev/null +++ b/docs/guide/context-device.md @@ -0,0 +1,57 @@ +## Context Device Functions +### Functions +* [alcOpenDevice](#alcopendevice) +* [alcCloseDevice](#alcclosedevice) + +#### alcOpenDevice +##### Description +This function opens a device by name. + +```cpp +ALCdevice* alcOpenDevice( + const ALCchar* devicename +); +``` + +##### Parameters +* devicename - A null-terminated string describing a device + +##### Possible Error States +The return value will be `NULL` if there is an error. + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +Returns a pointer to the opened device. Will return `NULL` if a device can not be opened. + +##### See Also +[alcCloseDevice](#alcclosedevice) + +#### alcCloseDevice +##### Description +This function closes an opened device. + +```cpp +ALCboolean alcCloseDevice( + ALCdevice* device +); +``` + +##### Parameters +* device - A pointer to an opened device + +##### Possible Error States +| State | Description | +| ------------------ | ----------- | +| ALC_INVALID_DEVICE | The specified device name doesn't exist. | + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +`ALC_TRUE` will be returned on success or `ALC_FALSE` on failure. Closing a +device will fail if the device contains any contexts or buffers. + +##### See Also +[alcOpenDevice](#alcopendevice) diff --git a/docs/guide/context-error.md b/docs/guide/context-error.md new file mode 100644 index 0000000000..b891ca09bf --- /dev/null +++ b/docs/guide/context-error.md @@ -0,0 +1,33 @@ +## Context Error Functions +### Error Codes +| Error Code | Description | +| ------------------- | ----------- | +| ALC_NO_ERROR | There is not currently an error | +| ALC_INVALID_DEVICE | A bad device was passed to an OpenAL function | +| ALC_INVALID_CONTEXT | A bad context was passed to an OpenAL function | +| ALC_INVALID_ENUM | An unknown enum value was passed to an OpenAL function | +| ALC_INVALID_VALUE | An invalid value was passed to an OpenAL function | +| ALC_OUT_OF_MEMORY | The requested operation resulted in OpenAL running out of memory | + +### Functions +* [alcGetError](#alcgeterror) + +#### alcGetError +##### Description +This function retrieves the current context error state. + +```cpp +ALCenum alcGetError(ALCdevice *device); +``` + +##### Parameters +* device - A pointer to the device to retrieve the error state from + +##### Possible Error States +None + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +None diff --git a/docs/guide/context-extension.md b/docs/guide/context-extension.md new file mode 100644 index 0000000000..053e5c3a28 --- /dev/null +++ b/docs/guide/context-extension.md @@ -0,0 +1,96 @@ +## Context Extension Functions +### Functions +* [alcIsExtensionPresent](#alcisextensionpresent) +* [alcGetProcAddress](#alcgetprocaddress) +* [alcGetEnumValue](#alcgetenumvalue) + +#### alcIsExtensionPresent +##### Description +This function queries if a specified context extension is available. + +```cpp +ALCboolean alcIsExtensionPresent( + ALCdevice *device, + const ALCchar *extName +); +``` + +##### Parameters +* device - A pointer to the device to be queried for an extension +* extName - A null-terminated string describing the extension + +##### Possible Error States +| State | Description | +| ----------------- | ----------- | +| ALC_INVALID_VALUE | The string pointer is not valid. | + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +Returns `ALC_TRUE` if the extension is available, `ALC_FALSE` if the extension +is not available. + +##### See Also +[alcGetProcAddress](#alcgetprocaddress), [alcGetEnumValue](#alcgetenumvalue) + +#### alcGetProcAddress +##### Description +This function retrieves the address of a specified context extension function. + +```cpp +void* alcGetProcAddress( + ALCdevice* device, + const ALCchar* funcName +); +``` + +##### Parameters +* device - A pointer to the device to be queried for the function +* funcName - a null-terminated string describing the function + +##### Possible Error States +| State | Description | +| ----------------- | ----------- | +| ALC_INVALID_VALUE | The string pointer is not valid. | + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +Returns the address of the function, or `NULL` if it is not found. + +##### See Also +[alcIsExtensionPresent](#alcisextensionpresent), +[alcGetEnumValue](#alcgetenumvalue) + +#### alcGetEnumValue +##### Description +This function retrieves the enum value for a specified enumeration name. + +```cpp +ALCenum alcGetEnumValue( + ALCdevice* device, + const ALCchar* enumName +); +``` + +##### Parameters +* device - A pointer to the device to be queried +* enumName - A null terminated string describing the enum value + +##### Possible Error States +| State | Description | +| ----------------- | ----------- | +| ALC_INVALID_VALUE | The string pointer is not valid. | + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +Returns the enum value described by the enumName string. This is most often +used for querying an enum value for an ALC extension. + +##### See Also +[alcIsExtensionPresent](#alcisextensionpresent), +[alcGetProcAddress](#alcgetprocaddress) diff --git a/docs/guide/context-management.md b/docs/guide/context-management.md new file mode 100644 index 0000000000..743b8e1f47 --- /dev/null +++ b/docs/guide/context-management.md @@ -0,0 +1,231 @@ +## Context Management Functions +### Properties +| Property | Data Type | Description | +| ------------------ | --------- | ----------- | +| ALC_FREQUENCY | `i` | Output frequency | +| ALC_MONO_SOURCES | `i` | Requested number of mono sources | +| ALC_STEREO_SOURCES | `i` | Requested number of stereo sources | +| ALC_REFRESH | `i` | Update rate of context processing | +| ALC_SYNC | `i` | Flag indicating a synchronous context | + +### Functions +* [alcCreateContext](#alccreatecontext) +* [alcMakeContextCurrent](#alcmakecontextcurrent) +* [alcProcessContext](#alcprocesscontext) +* [alcSuspendContext](#alcsuspendcontext) +* [alcDestroyContext](#alcdestroycontext) +* [alcGetCurrentContext](#alcgetcurrentcontext) +* [alcGetContextsDevice](#alcgetcontextsdevice) + +#### alcCreateContext +##### Description +This function creates a context using a specified device. + +```cpp +ALCcontext* alcCreateContext( + ALCdevice* device, + ALCint* attrlist +); +``` + +##### Parameters +* device - A pointer to a device +* attrlist - A pointer to a set of attributes: + + `ALC_FREQUENCY` + + `ALC_MONO_SOURCES` + + `ALC_REFRESH` + + `ALC_STEREO_SOURCES` + + `ALC_SYNC` + +##### Possible Error States +| State | Description | +| ------------------ | ----------- | +| ALC_INVALID_VALUE | An additional context can not be created for this device. | +| ALC_INVALID_DEVICE | The specified device is not a valid output device. | + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +Returns a pointer to the new context (`NULL` on failure). + +The attribute list can be `NULL`, or a zero terminated list of integer pairs +composed of valid ALC attribute tokens and requested values. + +##### See Also +[alcDestroyContext](#alcdestroycontext), +[alcMakeContextCurrent](#alcmakecontextcurrent) + +#### alcMakeContextCurrent +##### Description +This function makes a specified context the current context. + +```cpp +ALCboolean alcMakeContextCurrent( + ALCcontext *context +); +``` + +##### Parameters +* context - A pointer to the new context + +##### Possible Error States +| State | Description | +| ------------------- | ----------- | +| ALC_INVALID_CONTEXT | The specified context is invalid. | + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +Returns `ALC_TRUE` on success, or `ALC_FALSE` on failure. + +##### See Also +[alcCreateContext](#alccreatecontext), +[alcDestroyContext](#alcdestroycontext) + +#### alcProcessContext +##### Description +This function tells a context to begin processing. + +```cpp +void alcProcessContext( + ALCcontext *context +); +``` + +##### Parameters +* context - A pointer to the context + +##### Possible Error States +| State | Description | +| ------------------- | ----------- | +| ALC_INVALID_CONTEXT | The specified context is invalid. | + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +When a context is suspended, changes in OpenAL state will be accepted but will +not be processed. [alcSuspendContext](#alcsuspendcontext) can be used to +suspend a context, and then all the OpenAL state changes can be applied at once, +followed by a call to [alcProcessContext](#alcProcessContext) to apply all the +state changes immediately. In some cases, this procedure may be more efficient +than application of properties in a non-suspended state. In some +implementations, process and suspend calls are each a NOP. + +##### See Also +[alcSuspendContext](#alcsuspendcontext) + +#### alcSuspendContext +##### Description +This function suspends processing on a specified context. + +```cpp +void alcSuspendContext( + ALCcontext *context +); +``` + +##### Parameters +* context - A pointer to the context to be suspended + +##### Possible Error States +| State | Description | +| ------------------- | ----------- | +| ALC_INVALID_CONTEXT | The specified context is invalid. | + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +When a context is suspended, changes in OpenAL state will be accepted but will +not be processed. A typical use of [alcSuspendContext](#alcsuspendcontext) +would be to suspend a context, apply all the OpenAL state changes at once, and +then call [alcProcessContext](#alcprocesscontext) to apply all the state changes +at once. In some cases, this procedure may be more efficient than application +of properties in a non-suspended state. In some implementations, process and +suspend calls are each a NOP. + +##### See Also +[alcProcessContext](#alcprocesscontext) + +#### alcDestroyContext +##### Description +This function destroys a context. + +```cpp +void alcDestroyContext( + ALCcontext *context +); +``` + +##### Parameters +* context - A pointer to the context + +##### Possible Error States +| State | Description | +| ------------------- | ----------- | +| ALC_INVALID_CONTEXT | The specified context is invalid. | + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +A context which is not current can be destroyed at any time (all sources within +that context will also be deleted). +[alcMakeContextCurrent](#alcmakecontextcurrent) should be used to make sure the +context to be destroyed is not current (`NULL` is valid for +[alcMakeContextCurrent](#alcmakecontextcurrent)). + +##### See Also +[alcCreateContext](#alccreatecontext), +[alcMakeContextCurrent](#alcmakecontextcurrent) + +#### alcGetCurrentContext +##### Description +This function retrieves the current context. + +```cpp +ALCcontext* alcGetCurrentContext(ALCvoid); +``` + +##### Parameters +None + +##### Possible Error States +None + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +Returns a pointer to the current context. + +##### See Also +[alcGetContextsDevice](#alcgetcontextsdevice) + +#### alcGetContextsDevice +##### Description +This function retrieves a context's device pointer. + +```cpp +ALCdevice* alcGetContextsDevice(ALCcontext *context); +``` + +##### Parameters +* context - A pointer to a context + +##### Possible Error States +| State | Description | +| ------------------- | ----------- | +| ALC_INVALID_CONTEXT | The specified context is invalid. | + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +Returns a pointer to the specified context's device. + +##### See Also +[alcGetCurrentContext](#alcgetcurrentcontext) diff --git a/docs/guide/context-state.md b/docs/guide/context-state.md new file mode 100644 index 0000000000..73a0e50594 --- /dev/null +++ b/docs/guide/context-state.md @@ -0,0 +1,90 @@ +## Context State Functions +### Functions +* [alcGetString](#alcgetstring) +* [alcGetIntegerv](#alcgetintegerv) + +#### alcGetString +##### Description +This function returns pointers to strings related to the context. + +```cpp +const ALCchar * alcGetString( + ALCdevice *device, + ALenum param +); +``` + +##### Parameters +* device - A pointer to the device to be queried +* param - An attribute to be retrieved: + + `ALC_DEFAULT_DEVICE_SPECIFIER` + + `ALC_CAPTURE_DEFAULT_DEVICE_SPECIFIER` + + `ALC_DEVICE_SPECIFIER` + + `ALC_CAPTURE_DEVICE_SPECIFIER` + + `ALC_EXTENSIONS` + +##### Possible Error States +| State | Description | +| ---------------- | ----------- | +| ALC_INVALID_ENUM | The specified parameter is not valid. | + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +`ALC_DEFAULT_DEVICE_SPECIFIER` will return the name of the default output +device. + +`ALC_CAPTURE_DEFAULT_DEVICE_SPECIFIER` will return the name of the default +capture device. + +`ALC_DEVICE_SPECIFIER` will return the name of the specified output device if a +pointer is supplied, or will return a list of all available devices if a `NULL` +device pointer is supplied. A list is a pointer to a series of strings +separated by `NULL` characters, with the list terminated by two `NULL` +characters. See Enumeration Extension for more details. + +`ALC_CAPTURE_DEVICE_SPECIFIER` will return the name of the specified capture +device if a pointer is supplied, or will return a list of all available devices +if a `NULL` device pointer is supplied. + +`ALC_EXTENSIONS` returns a list of available context extensions, with each +extension separated by a space and the list terminated by a `NULL` character. + +#### alcGetIntegerv +##### Description +This function returns integers related to the context. + +```cpp +void alcGetIntegerv( + ALCdevice* device, + ALCenum param, + ALCsizei size, + ALCint* data +); +``` + +##### Parameters +* device - A pointer to the device to be queried +* param - An attribute to be retrieved: + + `ALC_MAJOR_VERSION` + + `ALC_MINOR_VERSION` + + `ALC_ATTRIBUTES_SIZE` + + `ALC_ALL_ATTRIBUTES` +* size - The size of the destination buffer provided +* data - A pointer to the data to be returned + +##### Possible Error States +| State | Description | +| ------------------- | ----------- | +| ALC_INVALID_VALUE | The specified data pointer or size is not valid. | +| ALC_INVALID_ENUM | The specified parameter is not valid. | +| ALC_INVALID_DEVICE | The specified device is not valid. | +| ALC_INVALID_CONTEXT | The specified context is not valid. | + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +The versions returned refer to the specification version that the implementation +meets. diff --git a/docs/guide/error.md b/docs/guide/error.md new file mode 100644 index 0000000000..cf30727fdc --- /dev/null +++ b/docs/guide/error.md @@ -0,0 +1,39 @@ +## Error Functions +### Error Codes +| Error Code | Description | +| -------------------- | ----------- | +| AL_NO_ERROR | There is not currently an error | +| AL_INVALID_NAME | A bad name (ID) was passed to an OpenAL function | +| AL_INVALID_ENUM | An invalid enum value was passed to an OpenAL function | +| AL_INVALID_VALUE | An invalid value was passed to an OpenAL function | +| AL_INVALID_OPERATION | The requested operation is not valid | +| AL_OUT_OF_MEMORY | The requested operation resulted in OpenAL running out of memory | + +### Functions +* [alGetError](#algeterror) + +#### alGetError +##### Description +This function returns the current error state and then clears the error state. + +```cpp +ALenum alGetError(ALvoid); +``` + +##### Parameters +None + +##### Possible Error States +None + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +Returns an `Alenum` representing the error state. When an OpenAL error occurs, +the error state is set and will not be changed until the error state is +retrieved using [alGetError](#algeterror). Whenever [alGetError](#algeterror) +is called, the error state is cleared and the last state (the current state when +the call was made) is returned. To isolate error detection to a specific +portion of code, [alGetError](#algeterror) should be called before the isolated +section to clear the current error state. diff --git a/docs/guide/extension.md b/docs/guide/extension.md new file mode 100644 index 0000000000..6bd3f89306 --- /dev/null +++ b/docs/guide/extension.md @@ -0,0 +1,87 @@ +## Extension Functions +### Functions +* [alIsExtensionPresent](#alisextensionpresent) +* [alGetProcAddress](#algetprocaddress) +* [alGetEnumValue](#algetenumvalue) + +#### alIsExtensionPresent +##### Description +This function tests if a specific extension is available for the OpenAL driver. + +```cpp +ALboolean alIsExtensionPresent( + const ALchar *extname +); +``` + +##### Parameters +* extname - A null-terminated string describing the desired extension + +##### Possible Error States +| State | Description | +| ---------------- | ----------- | +| AL_INVALID_VALUE | The specified extension string is not a valid pointer. | + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +Returns `AL_TRUE` if the extension is available, `AL_FALSE` if the extension is not +available. + +##### See Also +[alGetProcAddress](#algetprocaddress), [alGetEnumValue](#algetenumvalue) + +#### alGetProcAddress +##### Description +This function returns the address of an OpenAL extension function. + +```cpp +void* alGetProcAddress( + const ALchar *fname +); +``` + +##### Parameters +* fname - A null-terminated string containing the function name + +##### Possible Error States +None + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +The return value is a pointer to the specified function. The return value will +be `NULL` if the function is not found. + +##### See Also +[alIsExtensionPresent](#alisextensionpresent), [alGetEnumValue](#algetenumvalue) + +#### alGetEnumValue +##### Description +This function returns the enumeration value of an OpenAL enum described by a +string. + +```cpp +ALenum alGetEnumValue( + const ALchar *ename +); +``` + +##### Parameters +* ename - A null-terminated string describing an OpenAL enum + +##### Possible Error States +None + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +Returns the actual `ALenum` described by a string. Returns `NULL` if the string +doesn’t describe a valid OpenAL enum. + +##### See Also +[alIsExtensionPresent](#alisextensionpresent), +[alGetProcAddress](#algetprocaddress) diff --git a/docs/guide/extensions/enumeration.md b/docs/guide/extensions/enumeration.md new file mode 100644 index 0000000000..67f06eb468 --- /dev/null +++ b/docs/guide/extensions/enumeration.md @@ -0,0 +1,118 @@ +## Enumeration Extension +The Enumeration Extension enables the application developer to retrieve a list +of device strings identifying the different OpenAL rendering and capture devices +present on the user’s PC. The OpenAL router takes care of querying the user’s +system to find valid device implementations. Any of the strings returned by the enumeration extension can be used to create a device during +initialization via [alcOpenDevice](../context-device.md#alcopendevice). This +extension is critical if you want to enable the user to select at run-time which +device should be used to render your OpenAL audio. + +Naturally device enumeration is a very platform-specific topic. The mechanism +might not be implemented on platforms such as games consoles with fixed +capabilities, where multiple rendering devices are unnecessary. + +Note that on PC the standard Enumeration Extension will not identify every +potential OpenAL output path. It will not return all the possible outputs in +situations where the user has more than one audio device installed, or under +Windows Vista where the audio system specifies different “endpoints” for sound +such as Speakers, S/PDIF, etc... If you require complete control over the +choice of output path, use the “Enumerate All” extension. + +For full details on making use of the different devices you might come across on +the Windows PC platform, see the accompanying OpenAL Deployment Guide (PC +Windows). + +### Detecting the Enumeration Extension +To check whether the OpenAL libraries expose the Enumeration extension, use the +OpenAL function call +[alcIsExtensionPresent](../context-extension.md#alcisextensionpresent) and the +name `"ALC_ENUMERATION_EXT"`. +```cpp +if (alcIsExtensionPresent(NULL, “ALC_ENUMERATION_EXT") == AL_TRUE) { + // Enumeration Extension Found +} +``` + +### Retrieving device names +If the extension is found, the developer can retrieve a string containing +`NULL`-separated device name strings (the list is terminated with two +consecutive `NULL` characters), and a string containing the name of the default +device. + +To retrieve the string listing all the devices present, the developer should use +the OpenAL function call [alcGetString](../context-state.md#alcgetstring) with +the name `"ALC_DEVICE_SPECIFIER"`. + +To retrieve the string containing the name of the default device, the developer +should use the OpenAL function call +[alcGetString](../context-state.md#alcgetstring) with the name +`"ALC_DEFAULT_DEVICE_SPECIFIER"`. + +```cpp +const ALCchar* devices; +const ALCchar* defaultDeviceName; + +// Pass in NULL device handle to get list of devices +devices = alcGetString(NULL, ALC_DEVICE_SPECIFIER); +// devices contains the device names, separated by NULL and terminated by two +// consecutive NULLs. + +defaultDeviceName = alcGetString(NULL, ALC_DEFAULT_DEVICE_SPECIFIER); +// defaultDeviceName contains the name of the default device +``` + +### Parsing the device string +It is trivial to parse the device string and retrieve the names of the +individual devices. Ideally these will be presented to the user in the +application configuration GUI, to enable the user to select the desired device +at initialization time. + +### Checking the current device name +The developer can check to see the name of the device that was actually opened +using the function call [alcGetString](../context-state.md#alcgetstring) with a +pointer to an open device and the name `"ALC_DEVICE_SPECIFIER"`. + +```cpp +ALCdevice* pMyDevice; +const ALCchar* actualDeviceName; + +// Open the default device +pMyDevice=alcOpenDevice(NULL); + +// Pass in valid device pointer to get the name of the open device + +actualDeviceName = alcGetString(pMyDevice, ALC_DEVICE_SPECIFIER); +// actualDeviceName contains the name of the open device +``` + +### Enumeration Names +#### ALC_ENUMERATION_EXT +Use with [alcIsExtensionPresent](../context-extension.md#alcisextensionpresent) +to detect if the enumeration extension is available. + +#### ALC_DEVICE_SPECIFIER +Use with [alcGetString](../context-state.md#alcgetstring) and a NULL device +pointer to retrieve a string containing the available device names, separated +with `NULL` characters and terminated by two consecutive `NULL` characters. + +Use with [alcGetString](../context-state.md#alcgetstring) and a pointer to a +previously-opened device to ascertain the device’s name. + +#### ALC_CAPTURE_DEVICE_SPECIFIER +Use with [alcGetString](../context-state.md#alcgetstring) and a `NULL` device +pointer to retrieve a string containing the available capture device names, +separated with `NULL` characters and terminated by two consecutive `NULL` +characters. + +Use with [alcGetString](../context-state.md#alcgetstring) and a pointer to a +previously-opened capture device to ascertain the device’s name. + +#### ALC_DEFAULT_DEVICE_SPECIFIER +Use with [alcGetString](../context-state.md#alcgetstring) with a NULL Device +identifier to retrieve a `NULL`-terminated string containing the name of the +default device. + +#### ALC_CAPTURE_DEFAULT_DEVICE_SPECIFIER +Use with [alcGetString](../context-state.md#alcgetstring) with a `NULL` Device +identifier to retrieve a `NULL`-terminated string containing the name of the +default capture device. diff --git a/docs/guide/images/figure-doppler-graphic.png b/docs/guide/images/figure-doppler-graphic.png new file mode 100644 index 0000000000..8792abbbe0 Binary files /dev/null and b/docs/guide/images/figure-doppler-graphic.png differ diff --git a/docs/guide/images/figure-exponential-distance.JPG b/docs/guide/images/figure-exponential-distance.JPG new file mode 100644 index 0000000000..894f02c933 Binary files /dev/null and b/docs/guide/images/figure-exponential-distance.JPG differ diff --git a/docs/guide/images/figure-inverse-distance.JPG b/docs/guide/images/figure-inverse-distance.JPG new file mode 100644 index 0000000000..bdfb77d366 Binary files /dev/null and b/docs/guide/images/figure-inverse-distance.JPG differ diff --git a/docs/guide/images/figure-linear-distance.JPG b/docs/guide/images/figure-linear-distance.JPG new file mode 100644 index 0000000000..df6060dd67 Binary files /dev/null and b/docs/guide/images/figure-linear-distance.JPG differ diff --git a/docs/guide/images/figure-object-relationships.png b/docs/guide/images/figure-object-relationships.png new file mode 100644 index 0000000000..4ad43b6437 Binary files /dev/null and b/docs/guide/images/figure-object-relationships.png differ diff --git a/docs/guide/introduction.md b/docs/guide/introduction.md new file mode 100644 index 0000000000..8222600d93 --- /dev/null +++ b/docs/guide/introduction.md @@ -0,0 +1,500 @@ +# OpenAL Programmer's Guide - Versions 1.0 and 1.1 + +## Table of Contents +* [About this Document](#about-this-document) + + [Introduction](#introduction) + + [Intended Audience](#intended-audience) + + [Other OpenAL Resources](#other-openal-resources) +* [Introduction to OpenAL](#introduction-to-openal) + + [Objects](#objects) + + [Device Enumeration](#device-enumeration) + + [Initializing/Exiting](#initializing-exiting) + + [Listener properties](#listener-properties) + + [Buffer Properties](#buffer-properties) + + [Source Properties](#source-properties) + + [Queuing Buffers on a Source](#queuing-buffers-on-a-source) + + [Doppler Shift](#doppler-shift) + + [Error Handling](#error-handling) + + [Extensions](#extensions) +* [Buffer Functions](buffer.md#buffer-functions) + + [Properties](buffer.md#properties) + + [Functions](buffer.md#functions) +* [Source Functions](source.md#source-functions) + + [Properties](source.md#properties) + + [Functions](source.md#functions) +* [Listener Functions](listener.md#listener-functions) + + [Properties](listener.md#properties) + + [Functions](listener.md#functions) +* [State Functions](state.md#state-functions) + + [Properties](state.md#properties) + + [Functions](state.md#functions) +* [Error Functions](error.md#error-functions) + + [Error Codes](error.md#error-codes) + + [Functions](error.md#functions) +* [Extension Functions](extension.md#extension-functions) + + [Functions](extension.md#functions) +* [Context Management Functions](context-management.md#context-management-functions) + + [Properties](context-management.md#properties) + + [Functions](context-management.md#functions) +* [Context Error Functions](context-error.md#context-error-functions) + + [Error Codes](context-error.md#error-codes) + + [Functions](context-error.md#functions) +* [Context Device Functions](context-device.md#context-device-functions) + + [Functions](context-device.md#functions) +* [Context Extension Functions](context-extension.md#context-extension-functions) + + [Functions](context-extension.md#functions) +* [Context State Functions](context-state.md#context-state-functions) + + [Functions](context-state.md#functions) +* [Context Capture Functions](context-capture.md#context-capture-functions) + + [Functions](context-capture.md#functions) +* [Standard Extensions to OpenAL](extensions/) + + [Enumeration Extension](extensions/enumeration.md) + +## About this Document +### Introduction +OpenAL is a cross-platform three-dimensional audio API. The API’s primary +purpose is to allow an application to position audio sources in a +three-dimensional space around a listener, producing reasonable spatialization +of the sources for the audio system (headphones, 2.1 speaker output, 5.1 speaker +output, etc.) Through extensions, Creative Labs has also enhanced OpenAL with +EAX and other capabilities. OpenAL is appropriate for many audio applications, +but was designed to be most appropriate for gaming audio. + +### Intended Audience +This reference guide is most appropriate for a programmer. Experience with C or +C++ is not required to learn the concepts in OpenAL, but will make understanding +the OpenAL source as well as sample code easier. Since there are several sample +applications included with the OpenAL SDKs as well as with the source +distribution, it is recommended that interested programmers take advantage of +those resources. + +### Other OpenAL Resources +The two most important resources for additional information on OpenAL are the +websites at www.openal.org and http://developer.creative.com. The main OpenAL +site hosts the specification, the open source implementations, and sample code. +The Creative developer site has a section dedicated to OpenAL with SDKs showing +how to use OpenAL as well as various extensions. + +## Introduction to OpenAL +Use of OpenAL revolves around the use of three fundamental objects – Buffers, +Sources, and a Listener. A buffer can be filled with audio data, and can then be +attached to a source. The source can then be positioned and played. How the +source is heard is determined by its position and orientation relative to the +Listener object (there is only one Listener). Creating a number of sources and +buffers and a single listener and then updating the positions and orientations +of the sources and listener dynamically can present a convincing 3D audio world. + +### Objects +Here is a diagram showing the fundamental OpenAL objects and their relationships +to the context and device objects: + +![object relationships](images/figure-object-relationships.png "Object Relationships") + +When initializing OpenAL, at least one device has to be opened. Within that +device, at least one context will be created. Within that context, one listener +object is implied, and a multitude of source objects can be created. Each +source can have one or more buffers objects attached to it. Buffer objects are +not part of a specific context – they are shared among all contexts on one +device. + +### Device Enumeration +The function call to open a device, [alcOpenDevice](context-device.md#alcopendevice), takes a +string as input. The string should contain either the name of a valid OpenAL +rendering device, or `NULL` to request the default device. + +On PC Systems, a number of different OpenAL renderering devices may co-exist. +For example a “native” renderer specific to the user’s high-end soundcard, and a +host-based software fallback renderer. On platforms where multiple renderers +can be present, an OpenAL application may require the ability to identify the +different devices available, in order to give the end-user a choice of device. +OpenAL’s [Enumeration extension](extensions/enumeration.md) makes this possible. + +The Enumeration extension allows the programmer to retrieve a string listing the +names of available devices. It can also provide the name of the default device. +Use [alcGetString](context-state.md#alcgetstring) with the device property set +to `NULL`, and the enum property set to `ALC_DEVICE_SPECIFIER` to get the list +of available devices. To get the default device name, pass in `NULL` and +`ALC_DEFAULT_DEVICE_SPECIFIER`. + +The Enumeration extension also works with capture devices – the equivalent +values are `ALC_CAPTURE_DEVICE_SPECIFIER` and +`ALC_CAPTURE_DEFAULT_DEVICE_SPECIFIER`. + +The programmer can find out more about the capabilities of each device by +querying to see which extensions it supports using +[alcIsExtensionPresent](context-extension.md#alcisextensionpresent) and +[alIsExtensionPresent](extension.md#alIsextensionpresent). + +### Initializing/Exiting +As described above, the first step to initializing OpenAL is to open a device. +Once that is successfully done, then a context is opened on that device. Now +the fundamental OpenAL objects can be managed – the listener, various sources, +and various buffers. + +To generate a set of buffers for use, use [alGetError](error.md#algeterror) to +reset the error state, call [alGenBuffers](buffer.md#algenbuffers) to generate +the number of buffers desired, and then use [alGetError](error.md#algeterror) +again to detect if an error was generated. + +Fill the buffers with PCM data using [alBufferData](buffer.md#albufferdata). + +To generate a set of sources for use, use [alGetError](error.md#algeterror) to +reset the error state, call [alGenSources](source.md#algensources) to generate +the number of sources desired, and then use [alGetError](error.md#algeterror) +again to detect if an error was generated. + +Buffers are attached to sources using [alSourcei](source.md#alsourcei). + +Once a buffer has been attached to a source, the source can play the buffer +using [alSourcePlay](source.md#alsourceplay). + +Source and Listener properties can be updated dynamically using property set and +get calls such as [alGetListenerfv](listener.md#algetlistenerfv), +[alListener3f](listener.md#allistener3f), [alSourcei](source.md#alsourcei), and +[alGetSource3f](source.md#algetsource3f). + +Example: + +```cpp +// Initialization +Device = alcOpenDevice(NULL); // select the "preferred device" + +if (Device) { + Context=alcCreateContext(Device,NULL); + alcMakeContextCurrent(Context); +} + +// Check for EAX 2.0 support +g_bEAX = alIsExtensionPresent("EAX2.0"); + +// Generate Buffers +alGetError(); // clear error code + +alGenBuffers(NUM_BUFFERS, g_Buffers); +if ((error = alGetError()) != AL_NO_ERROR) +{ + DisplayALError("alGenBuffers :", error); + return; +} + +/ Load test.wav +loadWAVFile("test.wav",&format,&data,&size,&freq,&loop); +if ((error = alGetError()) != AL_NO_ERROR) +{ + DisplayALError("alutLoadWAVFile test.wav : ", error); + alDeleteBuffers(NUM_BUFFERS, g_Buffers); + return; +} + +// Copy test.wav data into AL Buffer 0 +alBufferData(g_Buffers[0],format,data,size,freq); +if ((error = alGetError()) != AL_NO_ERROR) +{ + DisplayALError("alBufferData buffer 0 : ", error); + alDeleteBuffers(NUM_BUFFERS, g_Buffers); + return; +} + +// Unload test.wav +unloadWAV(format,data,size,freq); +if ((error = alGetError()) != AL_NO_ERROR) +{ + DisplayALError("alutUnloadWAV : ", error); + alDeleteBuffers(NUM_BUFFERS, g_Buffers); + return; +} + +// Generate Sources +alGenSources(1,source); +if ((error = alGetError()) != AL_NO_ERROR) +{ + DisplayALError("alGenSources 1 : ", error); + return; +} + +// Attach buffer 0 to source +alSourcei(source[0], AL_BUFFER, g_Buffers[0]); +if ((error = alGetError()) != AL_NO_ERROR) +{ + DisplayALError("alSourcei AL_BUFFER 0 : ", error); +} + +// Exit +Context=alcGetCurrentContext(); +Device=alcGetContextsDevice(Context); +alcMakeContextCurrent(NULL); +alcDestroyContext(Context); +alcCloseDevice(Device); +``` + +### Listener properties +For every context, there is automatically one Listener object. The +`alListener[f, 3f, fv, i]` and `alGetListener[f, 3f, fv, i]` families of +functions can be used to set or retrieve the following listener properties: + +| Property | Data Type | Description | +| ---------------- | ---------------------- | ---------------------------------------------- | +| `AL_GAIN` | `f`, `fv` | Master gain. Value should be positive | +| `AL_POSITION` | `fv`, `3f`, `iv`, `3i` | X, Y, Z position | +| `AL_VELOCITY` | `fv`, `3f`, `iv`, `3i` | Velocity vector | +| `AL_ORIENTATION` | `fv`, `iv` | Orientation expressed as “at” and “up” vectors | + +Example: + +```cpp +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}; + +// Position ... +alListenerfv(AL_POSITION,listenerPos); +if ((error = alGetError()) != AL_NO_ERROR) +{ + DisplayALError("alListenerfv POSITION : ", error); + return; +} + +// Velocity ... +alListenerfv(AL_VELOCITY,listenerVel); +if ((error = alGetError()) != AL_NO_ERROR) +{ + DisplayALError("alListenerfv VELOCITY : ", error); + return; +} + +// Orientation ... +alListenerfv(AL_ORIENTATION,listenerOri); +if ((error = alGetError()) != AL_NO_ERROR) +{ + DisplayALError("alListenerfv ORIENTATION : ", error); + return; +} +``` + +### Buffer Properties +Each buffer generated by [alGenBuffers](buffer.md#algenbuffers) has properties which can +be retrieved. The `alGetBuffer[f, i]` functions can be used to retrieve the +following buffer properties: + +| Property | Data Type | Description | +| -------------- | --------- | ----------- | +| `AL_FREQUENCY` | `i`, `iv` | Frequency of buffer in Hz | +| `AL_BITS` | `i`, `iv` | Bit depth of buffer | +| `AL_CHANNELS` | `i`, `iv` | Number of channels in buffer. > 1 is valid, but buffer won’t be positioned when played | +| `AL_SIZE` | `i`, `iv` | Size of buffer in bytes | +| `AL_DATA` | `i`, `iv` | Original location where data was copied from generally useless, as was probably freed after buffer creation | + +Example: + +```cpp +// Retrieve Buffer Frequency +alBufferi(g_Buffers[0], AL_FREQUENCY, iFreq); +``` + +### Source Properties +Each source generated by [alGenSources](source.md#algensources) has properties which can +be set or retrieved. The `alSource[f, 3f, fv, i]` and +`alGetSource[f, 3f, fv, i]` families of functions can be used to set or retrieve +the following source properties: + +| Property | Data Type | Description | +| ----------------------- | ---------------------- | ----------- | +| `AL_PITCH` | `f`, `fv` | Pitch multiplier. Always positive | +| `AL_GAIN` | `f`, `fv` | Source gain. Value should be positive | +| `AL_MAX_DISTANCE` | `f`, `fv`, `i`, `iv` | Used with the Inverse Clamped Distance Model to set the distance where there will no longer be any attenuation of the source | +| `AL_ROLLOFF_FACTOR` | `f`, `fv`, `i`, `iv` | The rolloff rate for the source. Default is 1.0 | +| `AL_REFERENCE_DISTANCE` | `f`, `fv`, `i`, `iv` | The distance under which the volume for the source would normally drop by half (before being influenced by rolloff factor or `AL_MAX_DISTANCE`) | +| `AL_MIN_GAIN` | `f`, `fv` | The minimum gain for this source | +| `AL_MAX_GAIN` | `f`, `fv` | The maximum gain for this source | +| `AL_CONE_OUTER_GAIN` | `f`, `fv` | The gain when outside the oriented cone | +| `AL_CONE_INNER_ANGLE` | `f`, `fv`, `i`, `iv` | The gain when inside the oriented cone | +| `AL_CONE_OUTER_ANGLE` | `f`, `fv`, `i`, `iv` | Outer angle of the sound cone, in degrees. Default is 360 | +| `AL_POSITION` | `fv`, `3f` | X, Y, Z position | +| `AL_VELOCITY` | `fv`, `3f` | Velocity vector | +| `AL_DIRECTION` | `fv`, `3f`, `iv`, `3i` | Direction vector | +| `AL_SOURCE_RELATIVE` | `i`, `iv` | Determines if the positions are relative to the listener. Default is `AL_FALSE` | +| `AL_SOURCE_TYPE` | `i`, `iv` | The source type – `AL_UNDETERMINED`, `AL_STATIC`, or `AL_STREAMING` | +| `AL_LOOPING` | `i`, `iv` | Turns looping on (`AL_TRUE`) or off (`AL_FALSE`) | +| `AL_BUFFER` | `i`, `iv` | The ID of the attached buffer | +| `AL_SOURCE_STATE` | `i`, `iv` | The state of the source (`AL_STOPPED`, `AL_PLAYING`, …) | +| `AL_BUFFERS_QUEUED`* | `i`, `iv` | The number of buffers queued on this source | +| `AL_BUFFERS_PROCESSED` | `i`, `iv` | The number of buffers in the queue that have been processed | +| `AL_SEC_OFFSET` | `f`, `fv`, `i`, `iv` | The playback position, expressed in seconds | +| `AL_SAMPLE_OFFSET` | `f`, `fv`, `i`, `iv` | The playback position, expressed in samples | +| `AL_BYTE_OFFSET` | `f`, `fv`, `i`, `iv` | The playback position, expressed in bytes | + +*\* Read Only (alGetSourcei)* + +Example: + +```cpp +alGetError(); // clear error state +alSourcef(source[0],AL_PITCH,1.0f); +if ((error = alGetError()) != AL_NO_ERROR) + DisplayALError("alSourcef 0 AL_PITCH : \n", error); + +alGetError(); // clear error state +alSourcef(source[0],AL_GAIN,1.0f); +if ((error = alGetError()) != AL_NO_ERROR) + DisplayALError("alSourcef 0 AL_GAIN : \n", error); + +alGetError(); // clear error state +alSourcefv(source[0],AL_POSITION,source0Pos); +if ((error = alGetError()) != AL_NO_ERROR) + DisplayALError("alSourcefv 0 AL_POSITION : \n", error); + + alGetError(); // clear error state +alSourcefv(source[0],AL_VELOCITY,source0Vel); +if ((error = alGetError()) != AL_NO_ERROR) + DisplayALError("alSourcefv 0 AL_VELOCITY : \n", error); + +alGetError(); // clear error state +alSourcei(source[0],AL_LOOPING,AL_FALSE); +if ((error = alGetError()) != AL_NO_ERROR) + DisplayALError("alSourcei 0 AL_LOOPING true: \n", error); +``` + +### Queuing Buffers on a Source +To continuously stream audio from a source without interruption, buffer queuing +is required. To use buffer queuing, the buffers and sources are generated in +the normal way, but [alSourcei](source.md#alsourcei) is not used to attach the +buffers to the source. Instead, the functions +[alSourceQueueBuffers](source.md#alsourcequeuebuffers) and +[alSourceUnqueueBuffers](source.md#alsourceunqueuebuffers) are used. The +program can attach a buffer or a set of buffers to a source using +[alSourceQueueBuffers](source.md#alsourcequeuebuffers), and then call +[alSourcePlay](source.md#alsourceplay) on that source. While the source is +playing, [alSourceUnqueueBuffers](source.md#alsourceunqueuebuffers) can be +called to remove buffers which have already played. Those buffers can then be +filled with new data or discarded. New or refilled buffers can then be attached +to the playing source using +[alSourceQueueBuffers](source.md#alsourcequeuebuffers). As long as there is +always a new buffer to play in the queue, the source will continue to play. + +Although some 1.0 implementations of OpenAL may not enforce the following +restrictions on queuing, it is recommended to observe the following additional +rules, which do universally apply to 1.1 implementations: + +1) A source that will be used for streaming should not have its first buffer +attached using [alSourcei](source.md#alsourcei) – always use +[alSourceQueueBuffers](source.md#alsourcequeuebuffers) to attach buffers to +streaming sources. Any source can have all buffers detached from it using +`alSourcei(..., AL_BUFFER, 0)`, and can then be used for either streaming or +non-streaming buffers depending on how data is then attached to the source (with +[alSourcei](source.md#alsourcei) or with +[alSourceQueueBuffers](source.md#alsourcequeuebuffers)). + +2) All buffers attached to a source using +[alSourceQueueBuffers](source.md#alsourcequeuebuffers) should have the same +audio format. + +### Doppler Shift +The Doppler effect depends on the velocities of source and listener relative to +the medium, and the propagation speed of sound in that medium. The application +might want to emphasize or deemphasize the Doppler effect as physically accurate +calculation might not give the desired results. The amount of frequency shift +(pitch change) is proportional to the speed of listener and source along their +line of sight. + +The Doppler effect as implemented by OpenAL is described by the formula below. +Effects of the medium (air, water) moving with respect to listener and source +are ignored. + +* SS: `AL_SPEED_OF_SOUND` = speed of sound (default value 343.3) +* DF: `AL_DOPPLER_FACTOR` = Doppler factor (default 1.0) +* vls: Listener velocity scalar (scalar, projected on source-to-listener vector) +* vss: Source velocity scalar (scalar, projected on source-to-listener vector) +* f: Frequency of sample +* f': Effective Doppler shifted frequency +* SL: Source tt listener vector +* SV: Source velocity vector +* LV: Listener velocity vector + +Graphic representation of vls and vss: +![Doppler Graphic](images/figure-doppler-graphic.png "Doppler Graphic") + +3D Mathematical representation of vls and vss: +![](https://latex.codecogs.com/gif.latex?\left&space;|&space;v&space;\right&space;|&space;=&space;$\sqrt{v.x&space;\times&space;v.x&space;+&space;v.y&space;\times&space;v.y&space;+&space;v.z&space;\times&space;v.z}) + +![](https://latex.codecogs.com/gif.latex?v1&space;\bullet&space;v2&space;=&space;v1.x&space;\times&space;v2.x&space;+&space;v1.y&space;\times&space;v2.y&space;+&space;v1.z&space;\times&space;v2.z) + +![](https://latex.codecogs.com/gif.latex?vls&space;=&space;\min(\frac{SL&space;\bullet&space;LV}{\left&space;|&space;SL&space;\right&space;|},&space;\frac{SS}{DF})) + +![](https://latex.codecogs.com/gif.latex?vss&space;=&space;\min(\frac{SL&space;\bullet&space;SV}{\left&space;|&space;SL&space;\right&space;|},&space;\frac{SS}{DF})) + +![](https://latex.codecogs.com/gif.latex?{f}'&space;=&space;f&space;\times&space;\frac{SS&space;-&space;DF&space;\times&space;vls}{SS&space;-&space;DF&space;\times&space;vss}) + +There are two API calls global to the current context that provide control of +the speed of sound and Doppler factor. `AL_DOPPLER_FACTOR` is a simple scaling +of source and listener velocities to exaggerate or deemphasize the Doppler +(pitch) shift resulting from the calculation. + +```cpp +void alDopplerFactor(ALfloat dopplerFactor); +``` + +A negative value will result in an `AL_INVALID_VALUE` error, the command is then +ignored. The default value is 1. The current setting can be queried using +`alGetFloat{v}` and `AL_DOPPLER_FACTOR`. + +`AL_SPEED_OF_SOUND` allows the application to change the reference (propagation) +speed used in the Doppler calculation. The source and listener velocities +should be expressed in the same units as the speed of sound. + +```cpp +void alSpeedOfSound(ALfloat speed); +``` + +A negative or zero value will result in an `AL_INVALID_VALUE` error, and the +command is ignored. The default value is 343.3 (appropriate for velocity units +of meters and air as the propagation medium). The current setting can be queried +using `alGetFloat{v}` and `AL_SPEED_OF_SOUND`. + +Distance and velocity units are completely independent of one another (so you +could use different units for each if desired). If an OpenAL application +doesn't want to use Doppler effects, then leaving all velocities at zero will +achieve that result. + +### Error Handling +The error state of OpenAL can be retrieved at any time using +[alGetError](error.md#algeterror). [alGetError](error.md#algeterror) clears the +error state of OpenAL when it is called, so it is common for an OpenAL +application to call [alGetError](error.md#algeterror) at the beginning of a +critical operation to clear the error state, perform the critical operation, and +then use [alGetError](error.md#algeterror) again to test whether or not an error +occurred. + +Error Codes: + +| Error Code | Description | +| -------------------- | ----------- | +| AL_NO_ERROR | there is not currently an error | +| AL_INVALID_NAME | a bad name (ID) was passed to an OpenAL function | +| AL_INVALID_ENUM | an invalid enum value was passed to an OpenAL function | +| AL_INVALID_VALUE | an invalid value was passed to an OpenAL function | +| AL_INVALID_OPERATION | the requested operation is not valid | +| AL_OUT_OF_MEMORY | the requested operation resulted in OpenAL running out of memory | + +Example: + +```cpp +alGetError(); // Clear Error Code + +// Generate Buffers +alGenBuffers(NUM_BUFFERS, g_Buffers); +if ((error = alGetError()) != AL_NO_ERROR) +{ + DisplayALError("alGenBuffers :", error); + exit(-1); +} +``` + +### Extensions +OpenAL has an extension mechanism that can be used by OpenAL vendors to add new +features to the API. Creative Labs have added a number of extensions including +EAX, X-RAM, Multi Channel Buffer playback, and most recently an Effect Extension +(EFX). To determine if an extension is available the application can use either +[alIsExtensionPresent](extension.md#alisextensionpresent) or +[alcIsExtensionPresent](context-extension.md#alcisextensionpresent) depending on +the type of extension. The Appendices contain more details about some of +Creative’s extensions to OpenAL. diff --git a/docs/guide/listener.md b/docs/guide/listener.md new file mode 100644 index 0000000000..50ae078d37 --- /dev/null +++ b/docs/guide/listener.md @@ -0,0 +1,451 @@ +## Listener Functions +### Properties +| Property | Data Type | Description | +| -------------- | ---------------------- | ----------- | +| AL_GAIN | `f`, `fv` | Master gain. Value should be positive | +| AL_POSITION | `fv`, `3f`, `iv`, `3i` | X, Y, Z position | +| AL_VELOCITY | `fv`, `3f`, `iv`, `3i` | Velocity vector | +| AL_ORIENTATION | `fv`, `fv` | Orientation expressed as "at" and "up" vectors | + +### Functions +* [alListenerf](#allistenerf) +* [alListener3f](#allistenerf) +* [alListenerfv](#allistenerfv) +* [alListeneri](#allisteneri) +* [alListener3i](#allistener3i) +* [alListeneriv](#allisteneriv) +* [alGetListenerf](#algetlistenerf) +* [alGetListener3f](#algetlistener3f) +* [alGetListenerfv](#algetlistenerfv) +* [alGetListeneri](#algetlisteneri) +* [alGetListener3i](#algetlistener3i) +* [alGetListeneriv](#algetlisteneriv) + +#### alListenerf +##### Description +This function sets a floating point property for the listener. + +```cpp +void alListenerf( + ALenum param, + ALfloat value +); +``` + +##### Parameters +* param - The name of the attribute to be set: + + `AL_GAIN` +* value - The ALfloat value to set the attribute to + +##### Possible Error States +| State | Description | +| -------------------- | ----------- | +| AL_INVALID_VALUE | The value given is not valid. | +| AL_INVALID_ENUM | The specified parameter is not valid. | +| AL_INVALID_OPERATION | There is no current context. | + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +None + +##### See Also +[alListener3f](#allistener3f), [alListenerfv](#allistenerfv), +[alGetListenerf](#algetlistenerf), [alGetListener3f](#algetlistener3f), +[alGetListenerfv](#algetlistenerfv) + +#### alListener3f +##### Description +This function sets a floating point property for the listener. + +```cpp +void alListener3f( + ALenum param, + ALfloat v1, + ALfloat v2, + ALfloat v3 +); +``` + +##### Parameters +* param - The name of the attribute to be set: + + `AL_POSITION` + + `AL_VELOCITY` +* v1, v2, v3 - The value to set the attribute to + +##### Possible Error States +| State | Description | +| -------------------- | ----------- | +| AL_INVALID_VALUE | The value given is not valid. | +| AL_INVALID_ENUM | The specified parameter is not valid. | +| AL_INVALID_OPERATION | There is no current context. | + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +None + +##### See Also +[alListenerf](#allistenerf), [alListenerfv](#allistenerfv), +[alGetListenerf](#algetlistenerf), [alGetListener3f](#algetlistener3f), +[alGetListenerfv](#algetlistenerfv) + +#### alListenerfv +##### Description +This function sets a floating point-vector property for the listener. + +```cpp +void alListenerfv( + ALenum param, + ALfloat* values +); +``` + +##### Parameters +* param - The name of the attribute to be set: + + `AL_POSITION` + + `AL_VELOCITY` + + `AL_ORIENTATION` +* values - Pointer to floating point-vector values + +##### Possible Error States +| State | Description | +| -------------------- | ----------- | +| AL_INVALID_VALUE | The value given is not valid. | +| AL_INVALID_ENUM | The specified parameter is not valid. | +| AL_INVALID_OPERATION | There is no current context. | + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +None + +##### See Also +[alListenerf](#allistenerf), [alListener3f](#allistenerf), +[alGetListenerf](#algetlistenerf), [alGetListener3f](#algetlistener3f), +[alGetListenerfv](#algetlistenerfv) + +#### alListeneri +##### Description +This function sets an integer property for the listener. + +```cpp +void alListeneri( + ALenum param, + ALint value +); +``` + +##### Parameters +* param - The name of the attribute to be set +* value - The integer value to set the attribute to + +##### Possible Error States +| State | Description | +| -------------------- | ----------- | +| AL_INVALID_VALUE | The value given is not valid. | +| AL_INVALID_ENUM | The specified parameter is not valid. | +| AL_INVALID_OPERATION | There is no current context. | + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +There are no integer listener attributes defined for OpenAL 1.1, but this +function may be used by an extension. + +##### See Also +[alListener3i](#allistener3i), [alListeneriv](#allisteneriv), +[alGetListeneri](#algetlisteneri), [alGetListener3i](#algetlistener3i), +[alGetListeneriv](#algetlisteneriv) + +#### alListener3i +##### Description +This function sets an integer property for the listener. + +```cpp +void alListener3i( + ALenum param, + ALint v1, + ALint v2, + ALint v3 +); +``` + +##### Parameters +* param - The name of the attribute to be set: + + `AL_POSITION` + + `AL_VELOCITY` +* v1, v2, v3 - The integer values to set the attribute to + +##### Possible Error States +| State | Description | +| -------------------- | ----------- | +| AL_INVALID_VALUE | The value given is not valid. | +| AL_INVALID_ENUM | The specified parameter is not valid. | +| AL_INVALID_OPERATION | There is no current context. | + +##### Version Requirements +OpenAL 1.1 or higher + +##### Remarks +None + +##### See Also +[alListeneri](#allisteneri), [alListeneriv](#allisteneriv), +[alGetListeneri](#algetlisteneri), [alGetListener3i](#algetlistener3i), +[alGetListeneriv](#algetlisteneriv) + +#### alListeneriv +##### Description +This function sets an integer property for the listener. + +```cpp +void alListeneriv( + ALenum param, + ALint* values +); +``` + +##### Parameters +* param - The name of the attribute to be set: + + `AL_POSITION` + + `AL_VELOCITY` + + `AL_ORIENTATION` +* values - Pointer to the integer values to set the attribute to + +##### Possible Error States +| State | Description | +| -------------------- | ----------- | +| AL_INVALID_VALUE | The value given is not valid. | +| AL_INVALID_ENUM | The specified parameter is not valid. | +| AL_INVALID_OPERATION | There is no current context. | + +##### Version Requirements +OpenAL 1.1 or higher + +##### Remarks +None + +##### See Also +[alListeneri](#allisteneri), [alListener3i](#allisteneri), +[alGetListeneri](#algetlisteneri), [alGetListener3i](#algetlistener3i), +[alGetListeneriv](#algetlisteneriv) + +#### alGetListenerf +##### Description +This function retrieves a floating point property of the listener. + +```cpp +void alGetListenerf( + ALenum param, + ALfloat* value +); +``` + +##### Parameters +* param - The name of the attribute to be retrieved: + + `AL_GAIN` +* values - Pointer to the floating-point value being retrieved + +##### Possible Error States +| State | Description | +| -------------------- | ----------- | +| AL_INVALID_VALUE | The value given is not valid. | +| AL_INVALID_ENUM | The specified parameter is not valid. | +| AL_INVALID_OPERATION | There is no current context. | + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +None + +##### See Also +[alListenerf](#allistenerf), [alListener3f](#allistenerf), +[alListenerfv](#allistenerfv), [alGetListener3f](#algetlistener3f), +[alGetListenerfv](#algetlistenerfv) + +#### alGetListener3f +##### Description +This function retrieves a set of three floating point values from a property of +the listener. + +```cpp +void alGetListener3f( + ALenum param, + ALfloat* v1, + ALfloat* v2, + ALfloat* v3 +); +``` + +##### Parameters +* param - The name of the attribute to be retrieved: + + `AL_POSITION` + + `AL_VELOCITY` +* v1, v2, v3 - Pointers to the three floating point being retrieved + +##### Possible Error States +| State | Description | +| -------------------- | ----------- | +| AL_INVALID_VALUE | The value given is not valid. | +| AL_INVALID_ENUM | The specified parameter is not valid. | +| AL_INVALID_OPERATION | There is no current context. | + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +None + +##### See Also +[alListenerf](#allistenerf), [alListener3f](#allistenerf), +[alListenerfv](#allistenerfv), [alGetListenerf](#algetlistenerf), +[alGetListenerfv](#algetlistenerfv) + +#### alGetListenerfv +##### Description +This function retrieves a floating point-vector property of the listener. + +```cpp +void alGetListenerfv( + ALenum param, + ALfloat* values +); +``` + +##### Parameters +* param - The name of the attribute to be retrieved: + + `AL_POSITION` + + `AL_VELOCITY` + + `AL_ORIENTATION` +* values - Pointers to the three floating point being retrieved + +##### Possible Error States +| State | Description | +| -------------------- | ----------- | +| AL_INVALID_VALUE | The value given is not valid. | +| AL_INVALID_ENUM | The specified parameter is not valid. | +| AL_INVALID_OPERATION | There is no current context. | + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +None + +##### See Also +[alListenerf](#allistenerf), [alListener3f](#allistenerf), +[alListenerfv](#allistenerfv), [alGetListenerf](#algetlistenerf), +[alGetListener3f](#algetlistener3f) + +#### alGetListeneri +##### Description +This function retrieves an integer property of the listener. + +```cpp +void alGetListeneri( + ALenum param, + ALint* value +); +``` + +##### Parameters +* param - The name of the attribute to be retrieved: +* values - Pointer to the integer value being retrieved + +##### Possible Error States +| State | Description | +| -------------------- | ----------- | +| AL_INVALID_VALUE | The value given is not valid. | +| AL_INVALID_ENUM | The specified parameter is not valid. | +| AL_INVALID_OPERATION | There is no current context. | + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +There are no integer listener attributes defined for OpenAL 1.1, but this +function may be used by an extension. + +##### See Also +[alListeneri](#allisteneri), [alListener3i](#allisteneri), +[alListeneriv](#allisteneriv), [alGetListener3i](#algetlistener3i), +[alGetListeneriv](#algetlisteneriv) + +#### alGetListener3i +##### Description +This function retrieves an integer property of the listener. + +```cpp +void alGetListener3i( + ALenum param, + ALint* v1, + ALint* v2, + ALint* v3 +); +``` + +##### Parameters +* param - The name of the attribute to be retrieved: + + `AL_POSITION` + + `AL_VELOCITY` +* v1, v2, v3 - Pointers to the integer values being retrieved + +##### Possible Error States +| State | Description | +| -------------------- | ----------- | +| AL_INVALID_VALUE | The value given is not valid. | +| AL_INVALID_ENUM | The specified parameter is not valid. | +| AL_INVALID_OPERATION | There is no current context. | + +##### Version Requirements +OpenAL 1.1 or higher + +##### Remarks +None + +##### See Also +[alListeneri](#allisteneri), [alListener3i](#allisteneri), +[alListeneriv](#allisteneriv), [alGetListeneri](#algetlisteneri), +[alGetListeneriv](#algetlisteneriv) + +#### alGetListeneriv +##### Description +This function retrieves an integer property of the listener. + +```cpp +void alGetListeneriv( + ALenum param, + ALint* values +); +``` + +##### Parameters +* param - The name of the attribute to be retrieved: + + `AL_POSITION` + + `AL_VELOCITY` + + `AL_ORIENTATION` +* values - Pointers to the integer values being retrieved + +##### Possible Error States +| State | Description | +| -------------------- | ----------- | +| AL_INVALID_VALUE | The value given is not valid. | +| AL_INVALID_ENUM | The specified parameter is not valid. | +| AL_INVALID_OPERATION | There is no current context. | + +##### Version Requirements +OpenAL 1.1 or higher + +##### Remarks +None + +##### See Also +[alListeneri](#allisteneri), [alListener3i](#allisteneri), +[alListeneriv](#allisteneriv), [alGetListeneri](#algetlisteneri), +[alGetListener3i](#algetlistener3i) diff --git a/docs/guide/source.md b/docs/guide/source.md new file mode 100644 index 0000000000..b981b7dbf7 --- /dev/null +++ b/docs/guide/source.md @@ -0,0 +1,867 @@ +## Source Functions +### Properties +| Property | Data Type | Description | +| --------------------- | ---------------------- | ----------- | +| AL_PITCH | `f`, `fv` | Pitch multiplier. Always positive | +| AL_GAIN | `f`, `fv` | Source gain. Value should be positive | +| AL_MAX_DISTANCE | `f`, `fv`, `i`, `iv` | Used with the Inverse Clamped Distance Model to set the distance where there will no longer be any attenuation of the source | +| AL_ROLLOFF_FACTOR | `f`, `fv`, `i`, `iv` | The rolloff rate for the source. Default is 1.0 | +| AL_REFERENCE_DISTANCE | `f`, `fv`, `i`, `iv` | The distance under which the volume for the source would normally drop by half (before being influenced by rolloff factor or `AL_MAX_DISTANCE`) | +| AL_MIN_GAIN | `f`, `fv` | The minimum gain for this source | +| AL_MAX_GAIN | `f`, `fv` | The maximum gain for this source | +| AL_CONE_OUTER_GAIN | `f`, `fv` | The gain when outside the oriented cone | +| AL_CONE_INNER_ANGLE | `f`, `fv`, `i`, `iv` | The gain when inside the oriented cone | +| AL_CONE_OUTER_ANGLE | `f`, `fv`, `i`, `iv` | Outer angle of the sound cone, in degrees. Default is 360 | +| AL_POSITION | `fv`, `3f` | X, Y, Z position | +| AL_VELOCITY | `fv`, `3f` | Velocity vector | +| AL_DIRECTION | `fv`, `3f`, `iv`, `3i` | Direction vector | +| AL_SOURCE_RELATIVE | `i`, `iv` | Determines if the positions are relative to the listener. Default is `AL_FALSE` | +| AL_SOURCE_TYPE | `i`, `iv` | The source type: `AL_UNDETERMINED`, `AL_STATIC` or `AL_STREAMING` | +| AL_LOOPING | `i`, `iv` | Turns looping on (`AL_TRUE`) or off (`AL_FALSE`) | +| AL_BUFFER | `i`, `iv` | The ID of the attached buffer | +| AL_SOURCE_STATE | `i`, `iv` | The state of the source: `AL_STOPPED`, `AL_PLAYING`, ... | +| AL_BUFFERS_QUEUED | `i`, `iv` | The number of buffers queued on this source | +| AL_BUFFERS_PROCESSED | `i`, `iv` | The number of buffers in the queue that have been processed | +| AL_SEC_OFFSET | `f`, `fv`, `i`, `iv` | The playback position, expressed in seconds | +| AL_SAMPLE_OFFSET | `f`, `fv`, `i`, `iv` | The playback position, expressed in samples | +| AL_BYTE_OFFSET | `f`, `fv`, `i`, `iv` | The playback position, expressed in bytes | + +### Functions +* [alGenSources](#algensources) +* [alDeleteSources](#aldeletesources) +* [alIsSource](#alissource) +* [alSourcef](#alsourcef) +* [alSource3f](#alsource3f) +* [alSourcefv](#alsourcefv) +* [alSourcei](#alsourcei) +* [alSource3i](#alsource3i) +* [alSourceiv](#alsourceiv) +* [alGetSourcef](#algetsourcef) +* [alGetSource3f](#algetsource3f) +* [alGetSourcefv](#algetsourcefv) +* [alGetSourcei](#algetsourcei) +* [alGetSource3i](#algetsource3i) +* [alGetSourceiv](#algetsourceiv) +* [alSourcePlay](#alsourceplay) +* [alSourcePlayv](#alsourceplayv) +* [alSourcePause](#alsourcepause) +* [alSourcePausev](#alsourcepausev) +* [alSourceStop](#alsourcestop) +* [alSourceStopv](#alsourcestopv) +* [alSourceRewind](#alsourcerewind) +* [alSourceRewindv](#alsourcerewindv) +* [alSourceQueueBuffers](#alsourcequeuebuffers) +* [alSourceUnqueueBuffers](#alsourceunqueuebuffers) + +#### alGenSources +##### Description +This function generates one or more sources. References to sources are +`ALuint` values, which are used wherever a source reference is needed (in calls +such as [alDeleteSources](#aldeletesources) and [alSourcei](#alsourcei)). + +```cpp +void alGenSources( + ALsizei n, + ALuint *sources +); +``` + +##### Parameters +* n - The number of sources to be generated +* sources - Pointer to an array of `ALuint` vlaues which will store the names of + the new sources + +##### Possible Error States +| State | Description | +| -------------------- | ----------- | +| AL_OUT_OF_MEMORY | There is not enough memory to generate all the requested sources. | +| AL_INVALID_VALUE | There are not enough non-memory resources to create all the requested sources, or the array pointer is not valid. | +| AL_INVALID_OPERATION | There is no context to create sources in. | + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +If the requested number of sources cannot be created, an error will be generated +which can be detected with [alGetError](error.md#algeterror). If an error +occurs, no sources will be generated. If `n` equals zero, +[alGenSources](#algensources) does nothing and does not return an error. + +##### See Also +[alDeleteSources](#aldeletesources), [alIsSource](#alissource) + +#### alDeleteSources +##### Description +This function deletes one or more sources. + +```cpp +void alDeleteSources( + ALsizei n, + ALuint *sources +); +``` + +##### Parameters +* n - The number of sources to be deleted +* sources - Pointer to an array of source names identifying the sources to be + deleted + +##### Possible Error States +| State | Description | +| -------------------- | ----------- | +| AL_INVALID_NAME | At least one specified source is not valid, or an attempt is being made to delete more sources than exist. | +| AL_INVALID_OPERATION | There is no current context. | + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +If the requested number of sources cannot be deleted, an error will be generated +which can be detected with [alGetError](error.md#algeterror). If an error +occurs, no sources will be deleted. If `n` equals zero, +[alDeleteSources](#aldeletesources) does nothing and will not return an error. + +A playing source can be deleted – the source will be stopped and then deleted. + +##### See Also +[alGenSources](#algensources), [alIsSource](#alissource) + +#### alIsSource +##### Description +This function tests if a source name is valid, returning `AL_TRUE` if valid and +`AL_FALSE` if not. + +```cpp +boolean alIsSource( + ALuint source +); +``` + +##### Parameters +* source - A source name to be tested for validity + +##### Possible Error States +| State | Description | +| -------------------- | ----------- | +| AL_INVALID_OPERATION | There is no current context. | + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +None + +##### See Also +[alGenSources](#algensources), [alDeleteSources](#aldeletesources) + +#### alSourcei +##### Description +This function sets an integer property of a source. + +```cpp +void alSourcef( + ALuint source, + ALenum param, + ALfloat value +); +``` + +##### Parameters +* source - Source name whose attribute is being set +* param - The name of the attribute to set: + + `AL_PITCH` + + `AL_GAIN` + + `AL_MIN_GAIN` + + `AL_MAX_GAIN` + + `AL_MAX_DISTANCE` + + `AL_ROLLOFF_FACTOR` + + `AL_CONE_OUTER_GAIN` + + `AL_CONE_INNER_ANGLE` + + `AL_CONE_OUTER_ANGLE` + + `AL_REFERENCE_DISTANCE` +* value - The value to set the attribute to + +##### Possible Error States +| State | Description | +| -------------------- | ----------- | +| AL_INVALID_VALUE | The value given is out of range. | +| AL_INVALID_ENUM | The specified parameter is not valid. | +| AL_INVALID_NAME | The specified source name is not valid. | +| AL_INVALID_OPERATION | There is no current context. | + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +None + +##### See Also +[alSource3f](#alsource3f), [alSourcefv](#alSourcefv), +[alGetSourcef](#algetsourcef), [alGetSource3f](#algetsource3f), +[alGetSourcefv](#algetsourcefv) + +#### alSource3f +##### Description +This function sets a source property requiring three floating point values. + +```cpp +void alSource3f( + ALuint source, + ALenum param, + ALfloat v1, + ALfloat v2, + ALfloat v3 +); +``` + +##### Parameters +* source - Source name whose attribute is being set +* param - The name of the attribute to set: + + `AL_POSITION` + + `AL_VELOCITY` + + `AL_DIRECTION` +* v1, v2, v3 - The three `ALfloat` values to set the attribute to + +##### Possible Error States +| State | Description | +| -------------------- | ----------- | +| AL_INVALID_VALUE | The value given is out of range. | +| AL_INVALID_ENUM | The specified parameter is not valid. | +| AL_INVALID_NAME | The specified source name is not valid. | +| AL_INVALID_OPERATION | There is no current context. | + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +This function is an alternative to [alSourcefv](3alsourcefv). + +##### See Also +[alSourcef](#alsourcef), [alSourcefv](#alSourcefv), +[alGetSourcef](#algetsourcef), [alGetSource3f](#algetsource3f), +[alGetSourcefv](#algetsourcefv) + +#### alSourcefv +##### Description +This function sets a floating point-vector property of a source. + +```cpp +void alSourcefv( + ALuint source, + ALenum param, + ALfloat* values +); +``` + +##### Parameters +* source - Source name whose attribute is being set +* param - The name of the attribute to set: + + `AL_POSITION` + + `AL_VELOCITY` + + `AL_DIRECTION` +* values - A pointer to the vector to set the attribute to + +##### Possible Error States +| State | Description | +| -------------------- | ----------- | +| AL_INVALID_VALUE | The value given is out of range. | +| AL_INVALID_ENUM | The specified parameter is not valid. | +| AL_INVALID_NAME | The specified source name is not valid. | +| AL_INVALID_OPERATION | There is no current context. | + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +This function is an alternative to [alSource3f](#alsource3f). + +##### See Also +[alSourcef](#alsourcef), [alSource3f](#alSource3f), +[alGetSourcef](#algetsourcef), [alGetSource3f](#algetsource3f), +[alGetSourcefv](#algetsourcefv) + +#### alSourcei +##### Description +This function sets an integer property of a source. + +```cpp +void alSourcei( + ALuint source, + ALenum param, + ALint value +); +``` + +##### Parameters +* source - Source name whose attribute is being set +* param - The name of the attribute to set: + + `AL_SOURCE_RELATIVE` + + `AL_CONE_INNER_ANGLE` + + `AL_CONE_OUTER_ANGLE` + + `AL_LOOPING` + + `AL_BUFFER` + + `AL_SOURCE_STATE` +* value - The value to set the attribute to + +##### Possible Error States +| State | Description | +| -------------------- | ----------- | +| AL_INVALID_VALUE | The value given is out of range. | +| AL_INVALID_ENUM | The specified parameter is not valid. | +| AL_INVALID_NAME | The specified source name is not valid. | +| AL_INVALID_OPERATION | There is no current context. | + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +The buffer name zero is reserved as a “NULL Buffer" and is accepted by +`alSourcei(…, AL_BUFFER, …)` as a valid buffer of zero length. The `NULL` +Buffer is extremely useful for detaching buffers from a source which were +attached using this call or with [alSourceQueueBuffers](#alsourcequeuebuffers). + +##### See Also +[alSource3i](#alsource3i), [alSourceiv](#alSourceiv), +[alGetSourcei](#algetsourcei), [alGetSource3i](#algetsource3i), +[alGetSourceiv](#algetsourceiv) + +#### alSource3i +##### Description +This function sets a source property requiring three integer values. + +```cpp +void alSource3i( + ALuint source, + ALenum param, + ALint v1, + ALint v2, + ALint v3 +); +``` + +##### Parameters +* source - Source name whose attribute is being set +* param - The name of the attribute to set: + + `AL_POSITION` + + `AL_VELOCITY` + + `AL_DIRECTION` +* v1, v2, v3 - The three `ALint` values to set the attribute to + +##### Possible Error States +| State | Description | +| -------------------- | ----------- | +| AL_INVALID_VALUE | The value given is out of range. | +| AL_INVALID_ENUM | The specified parameter is not valid. | +| AL_INVALID_NAME | The specified source name is not valid. | +| AL_INVALID_OPERATION | There is no current context. | + +##### Version Requirements +OpenAL 1.1 or higher + +##### Remarks +None + +##### See Also +[alSourcei](#alsourcei), [alSourceiv](#alSourceiv), +[alGetSourcei](#algetsourcei), [alGetSource3i](#algetsource3i), +[alGetSourceiv](#algetsourceiv) + +#### alSourceiv +##### Description +This function sets an integer-vector property of a source. + +```cpp +void alSourceiv( + ALuint source, + ALenum param, + ALint* values +); +``` + +##### Parameters +* source - Source name whose attribute is being set +* param - The name of the attribute to set: + + `AL_POSITION` + + `AL_VELOCITY` + + `AL_DIRECTION` +* values - A pointer to the vector to set the attribute to + +##### Possible Error States +| State | Description | +| -------------------- | ----------- | +| AL_INVALID_VALUE | The value given is out of range. | +| AL_INVALID_ENUM | The specified parameter is not valid. | +| AL_INVALID_NAME | The specified source name is not valid. | +| AL_INVALID_OPERATION | There is no current context. | + +##### Version Requirements +OpenAL 1.1 or higher + +##### Remarks +None + +##### See Also +[alSourcei](#alsourcei), [alSource3i](#alSource3i), +[alGetSourcei](#algetsourcei), [alGetSource3i](#algetsource3i), +[alGetSourceiv](#algetsourceiv) + +#### alGetSourcei +##### Description +This function sets an integer property of a source. + +```cpp +void alGetSourcei( + ALuint source, + ALenum param, + ALint* value +); +``` + +##### Parameters +* source - Source name whose attribute is being retrieved +* param - The name of the attribute to retrieve: + + `AL_SOURCE_RELATIVE` + + `AL_BUFFER` + + `AL_SOURCE_STATE` + + `AL_BUFFERS_QUEUED` + + `AL_BUFFERS_PROCESSED` +* values - A pointer to the integer value being retrieved + +##### Possible Error States +| State | Description | +| -------------------- | ----------- | +| AL_INVALID_VALUE | The value pointer given is not valid. | +| AL_INVALID_ENUM | The specified parameter is not valid. | +| AL_INVALID_NAME | The specified source name is not valid. | +| AL_INVALID_OPERATION | There is no current context. | + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +None + +##### See Also +[alSourcei](#alsourcei), [alSource3i](#alSource3i), +[alSourceiv](#algetsourceiv), [alGetSource3i](#algetsource3i), +[alGetSourceiv](#algetsourceiv) + +#### alGetSource3i +##### Description +This function retrieves three integer values representing a property of a source. + +```cpp +void alGetSource3i( + ALuint source, + ALenum param, + ALint* v1, + ALint* v2, + ALint* v3 +); +``` + +##### Parameters +* source - Source name whose attribute is being retrieved +* param - The name of the attribute to retrieve: + + `AL_POSITION` + + `AL_VELOCITY` + + `AL_DIRECTION` +* values - Pointer to the values to retrieve + +##### Possible Error States +| State | Description | +| -------------------- | ----------- | +| AL_INVALID_VALUE | The value pointer given is not valid. | +| AL_INVALID_ENUM | The specified parameter is not valid. | +| AL_INVALID_NAME | The specified source name is not valid. | +| AL_INVALID_OPERATION | There is no current context. | + +##### Version Requirements +OpenAL 1.1 or higher + +##### Remarks +None + +##### See Also +[alSourcei](#alsourcei), [alSource3i](#alSource3i), +[alSourceiv](#algetsourceiv), [alGetSourcei](#algetsourcei), +[alGetSourceiv](#algetsourceiv) + +#### alGetSourceiv +##### Description +This function retrieves an integer property of a source. + +```cpp +void alGetSourceiv( + ALuint source, + ALenum param, + ALint* values +); +``` + +##### Parameters +* source - Source name whose attribute is being retrieved +* param - The name of the attribute to retrieve: + + `AL_POSITION` + + `AL_VELOCITY` + + `AL_DIRECTION` +* values - Pointer to the vector to retrieve + +##### Possible Error States +| State | Description | +| -------------------- | ----------- | +| AL_INVALID_VALUE | The value pointer given is not valid. | +| AL_INVALID_ENUM | The specified parameter is not valid. | +| AL_INVALID_NAME | The specified source name is not valid. | +| AL_INVALID_OPERATION | There is no current context. | + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +None + +##### See Also +[alSourcei](#alsourcei), [alSource3i](#alSource3i), +[alSourceiv](#algetsourceiv), [alGetSourcei](#algetsourcei), +[alGetSource3i](#algetsource3i) + +#### alSourcePlay +##### Description +This function plays a source. + +```cpp +void alSourcePlay( + ALuint source +); +``` + +##### Parameters +* source - The name of the source to be played + +##### Possible Error States +| State | Description | +| -------------------- | ----------- | +| AL_INVALID_NAME | The specified source name is not valid. | +| AL_INVALID_OPERATION | There is no current context. | + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +The playing source will have its state changed to `AL_PLAYING`. When called on a +source which is already playing, the source will restart at the beginning. When +the attached buffer(s) are done playing, the source will progress to the +`AL_STOPPED` state. + +##### See Also +[alSourcePlayv](#alsourceplayv), [alSourcePause](#alsourcepause), +[alSourcePausev](#alsourcepausev), [alSourceRewind](#alsourcerewind), +[alSourceRewindv](#alsourcerewindv), [alSourceStop](#alsourcestop), +[alsourcestopv](#alsourcestopv) + +#### alSourcePlayv +##### Description +This function plays a set of sources. + +```cpp +void alSourcePlayv( + ALsizei n, + ALuint *sources +); +``` + +##### Parameters +* n - The number of sources to be played +* source - A pointer to an array of sources to be played + +##### Possible Error States +| State | Description | +| -------------------- | ----------- | +| AL_INVALID_VALUE | The value pointer given is not valid. | +| AL_INVALID_NAME | The specified source name is not valid. | +| AL_INVALID_OPERATION | There is no current context. | + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +The playing sources will have their state changed to `AL_PLAYING`. When called +on a source which is already playing, the source will restart at the beginning. +When the attached buffer(s) are done playing, the source will progress to the +`AL_STOPPED` state. + +##### See Also +[alSourcePlay](#alsourceplay), [alSourcePause](#alsourcepause), +[alSourcePausev](#alsourcepausev), [alSourceRewind](#alsourcerewind), +[alSourceRewindv](#alsourcerewindv), [alSourceStop](#alsourcestop), +[alsourcestopv](#alsourcestopv) + +#### alSourcePause +##### Description +This function pauses a source. + +```cpp +void alSourcePause( + ALuint source +); +``` + +##### Parameters +* source - The name of the source to be paused + +##### Possible Error States +| State | Description | +| -------------------- | ----------- | +| AL_INVALID_NAME | The specified source name is not valid. | +| AL_INVALID_OPERATION | There is no current context. | + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +The paused source will have its state changed to `AL_PAUSED`. + +##### See Also +[alSourcePlay](#alsourceplay), [alSourcePlayv](#alsourceplayv), +[alSourcePausev](#alsourcepausev), [alSourceRewind](#alsourcerewind), +[alSourceRewindv](#alsourcerewindv), [alSourceStop](#alsourcestop), +[alsourcestopv](#alsourcestopv) + +#### alSourcePausev +##### Description +This function pauses a set of sources. + +```cpp +void alSourcePausev( + ALsizei n, + ALuint *sources +); +``` + +##### Parameters +* n - The number of sources to be paused +* source - A pointer to an array of sources to be paused + +##### Possible Error States +| State | Description | +| -------------------- | ----------- | +| AL_INVALID_VALUE | The value pointer given is not valid. | +| AL_INVALID_NAME | The specified source name is not valid. | +| AL_INVALID_OPERATION | There is no current context. | + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +The paused sources will have their state changed to `AL_PAUSED`. + +##### See Also +[alSourcePlay](#alsourceplay), [alSourcePlayv](#alsourceplayv), +[alSourcePause](#alsourcepause), [alSourceRewind](#alsourcerewind), +[alSourceRewindv](#alsourcerewindv), [alSourceStop](#alsourcestop), +[alsourcestopv](#alsourcestopv) + +#### alSourceStop +##### Description +This function stops a source. + +```cpp +void alSourceStop( + ALuint source +); +``` + +##### Parameters +* source - The name of the source to be stopped + +##### Possible Error States +| State | Description | +| -------------------- | ----------- | +| AL_INVALID_NAME | The specified source name is not valid. | +| AL_INVALID_OPERATION | There is no current context. | + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +The paused source will have its state changed to `AL_STOPPED`. + +##### See Also +[alSourcePlay](#alsourceplay), [alSourcePlayv](#alsourceplayv), +[alSourcePause](#alsourcepause), [alSourcePausev](#alsourcepausev), +[alSourceRewind](#alsourcerewind), [alSourceRewindv](#alsourcerewindv), +[alsourcestopv](#alsourcestopv) + +#### alSourceStopv +##### Description +This function stops a set of sources. + +```cpp +void alSourceStopv( + ALsizei n, + ALuint *sources +); +``` + +##### Parameters +* n - The number of sources to stop +* source - A pointer to an array of sources to be stopped + +##### Possible Error States +| State | Description | +| -------------------- | ----------- | +| AL_INVALID_VALUE | The value pointer given is not valid. | +| AL_INVALID_NAME | The specified source name is not valid. | +| AL_INVALID_OPERATION | There is no current context. | + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +The paused sources will have their state changed to `AL_STOPPED`. + +##### See Also +[alSourcePlay](#alsourceplay), [alSourcePlayv](#alsourceplayv), +[alSourcePause](#alsourcepause), [alSourceRewind](#alsourcerewind), +[alSourceRewindv](#alsourcerewindv), [alSourceStop](#alsourcestop), +[alsourcestop](#alsourcestop) + +#### alSourceRewind +##### Description +This function stops the source and sets its state to `AL_INITIAL`. + +```cpp +void alSourceRewind( + ALuint source +); +``` + +##### Parameters +* source - The name of the source to be rewound + +##### Possible Error States +| State | Description | +| -------------------- | ----------- | +| AL_INVALID_NAME | The specified source name is not valid. | +| AL_INVALID_OPERATION | There is no current context. | + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +None + +##### See Also +[alSourcePlay](#alsourceplay), [alSourcePlayv](#alsourceplayv), +[alSourcePause](#alsourcepause), [alSourcePausev](#alsourcepausev), +[alSourceRewindv](#alsourcerewindv), [alsourcestop](#alsourcestop), +[alsourcestopv](#alsourcestopv) + +#### alSourceRewindv +##### Description +his function stops a set of sources and sets all their states to `AL_INITIAL`. + +```cpp +void alSourceRewindv( + ALsizei n, + ALuint *sources +); +``` + +##### Parameters +* n - The number of sources to be rewound +* source - A pointer to an array of sources to be rewound + +##### Possible Error States +| State | Description | +| -------------------- | ----------- | +| AL_INVALID_VALUE | The value pointer given is not valid. | +| AL_INVALID_NAME | The specified source name is not valid. | +| AL_INVALID_OPERATION | There is no current context. | + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +None + +##### See Also +[alSourcePlay](#alsourceplay), [alSourcePlayv](#alsourceplayv), +[alSourcePause](#alsourcepause), [alSourcePausev](#alsourcepausev), +[alSourceRewind](#alsourcerewind), [alSourceStop](#alsourcestop), +[alsourcestop](#alsourcestop) + +#### alSourceQueueBuffers +##### Description +This function queues a set of buffers on a source. All buffers attached to a +source will be played in sequence, and the number of processed buffers can be +detected using an [alSourcei](#alsourcei) call to retrieve +`AL_BUFFERS_PROCESSED`. + +```cpp +void alSourceQueueBuffers( + ALuint source, + ALsizei n, + ALuint* buffers +); +``` + +##### Parameters +* source - The name of the source to queue buffers onto +* n - The number of buffers to be queued +* buffers - A pointer to an array of buffer names to be queued + +##### Possible Error States +| State | Description | +| -------------------- | ----------- | +| AL_INVALID_NAME | At least one specified buffer name is not valid, or the specified source name is not valid. | +| AL_INVALID_OPERATION | There is no current context, an attempt was made to add a new buffer which is not the same format as the buffers already in the queue, or the source already has a static buffer attached. | + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +When first created, a source will be of type `AL_UNDETERMINED`. A successful +[alSourceQueueBuffers](#alsourcequeuebuffers) call will change the source type +to `AL_STREAMING`. + +##### See Also +[alSourceUnqueueBuffers](#alsourceunqueuebuffers) + +#### alSourceUnqueueBuffers +##### Description +This function unqueues a set of buffers attached to a source. The number of +processed buffers can be detected using an [alSourcei](#alsourcei) call to +retrieve `AL_BUFFERS_PROCESSED`, which is the maximum number of buffers that can +be unqueued using this call. + +```cpp +void alSourceUnqueueBuffers( + ALuint source, + ALsizei n, + ALuint* buffers +); +``` + +##### Parameters +* source - The name of the source to unqueue buffers from +* n - The number of buffers to be unqueued +* buffers - A pointer to an array of buffer names that were removed + +##### Possible Error States +| State | Description | +| -------------------- | ----------- | +| AL_INVALID_VALUE | At least one buffer can not be unqueued because it has not been processed yet. | +| AL_INVALID_NAME | The specified source name is not valid. | +| AL_INVALID_OPERATION | There is no current context. | + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +The unqueue operation will only take place if all n buffers can be removed from +the queue. + +##### See Also +[alSourceQueueBuffers](#alsourcequeuebuffers) diff --git a/docs/guide/state.md b/docs/guide/state.md new file mode 100644 index 0000000000..9f358a64c0 --- /dev/null +++ b/docs/guide/state.md @@ -0,0 +1,569 @@ +## State Functions +### Properties +| Property | Data Type | Description | +| ----------------- | --------- | ----------- | +| AL_DOPPLER_FACTOR | `f` | Global Doppler factor | +| AL_SPEED_OF_SOUND | `f` | Speed of sound in units per second | +| AL_DISTANCE_MODEL | `f` | Distance model enumeration value | + +### Functions +* [alEnable](#alenable) +* [alDisable](#aldisable) +* [alIsEnabled](#alisenabled) +* [alGetBoolean](#algetboolean) +* [alGetDouble](#algetdouble) +* [alGetFloat](#algetfloat) +* [alGetInteger](#algetinteger) +* [alGetBooleanv](#algetbooleanv) +* [alGetDoublev](#algetdoublev) +* [alGetFloatv](#algetfloatv) +* [alGetIntegerv](#algetintegerv) +* [alGetString](#algetstring) +* [alDistanceModel](#aldistancemodel) +* [alDopplerFactor](#aldopplerfactor) +* [alSpeedOfSound](#alspeedofsound) + +#### alEnable +##### Description +This function enables a feature of the OpenAL driver. + +```cpp +void alEnable( + ALenum capability +); +``` + +##### Parameters +* capability - the name of a capability to enable + +##### Possible Error States +| State | Description | +| -------------------- | ----------- | +| AL_INVALID_ENUM | The specified capability is not valid. | +| AL_INVALID_OPERATION | There is no current context. | + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +There are no capabilities defined in OpenAL 1.1 to be used with this function, +but it may be used by an extension. + +##### See Also +[alDisable](#aldisable), [alIsEnabled](#alisenabled) + +#### alDisable +##### Description +This function disables a feature of the OpenAL driver. + +```cpp +void alDisable( + ALenum capability +); +``` + +##### Parameters +* capability - the name of a capability to distable + +##### Possible Error States +| State | Description | +| -------------------- | ----------- | +| AL_INVALID_ENUM | The specified capability is not valid. | +| AL_INVALID_OPERATION | There is no current context. | + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +There are no capabilities defined in OpenAL 1.1 to be used with this function, +but it may be used by an extension. + +##### See Also +[alEnable](#alenabled), [alIsEnabled](#alisenabled) + +#### alIsEnabled +##### Description +This function returns a boolean indicating if a specific feature is enabled in +the OpenAL driver. + +```cpp +ALboolean alIsEnabled( + ALenum capability +); +``` + +##### Parameters +* capability - the name of a capability to check + +##### Possible Error States +| State | Description | +| -------------------- | ----------- | +| AL_INVALID_ENUM | The specified capability is not valid. | +| AL_INVALID_OPERATION | There is no current context. | + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +Returns `AL_TRUE` if the capability is enabled, `AL_FALSE` if the capability is +disabled. There are no capabilities defined in OpenAL 1.1 to be used with this +function, but it may be used by an extension. + +##### See Also +[alEnable](#alenabled), [alDisable](#aldisable) + +#### alGetBoolean +##### Description +This function returns a boolean OpenAL state. + +```cpp +ALboolean alGetBoolean( + ALenum param +); +``` + +##### Parameters +* param - the state to be queried: + + `AL_DOPPLER_FACTOR` + + `AL_SPEED_OF_SOUND` + + `AL_DISTANCE_MODEL` + +##### Possible Error States +| State | Description | +| -------------------- | ----------- | +| AL_INVALID_ENUM | The specified parameter is not valid. | +| AL_INVALID_OPERATION | There is no current context. | + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +The boolean state described by `param` will be returned. + +##### See Also +[alGetBooleanv](#algetbooleanv), [alGetDouble](#algetdouble), +[alGetDoublev](#algetdoublev), [alGetFloat](#algetfloat), +[alGetFloatv](#algetfloatv), [alGetInteger](#algetinteger), +[alGetIntegerv](#algetintegerv) + +#### alGetDouble +##### Description +This function returns a double precision floating point OpenAL state. + +```cpp +ALdouble alGetDouble( + ALenum param +); +``` + +##### Parameters +* param - the state to be queried: + + `AL_DOPPLER_FACTOR` + + `AL_SPEED_OF_SOUND` + + `AL_DISTANCE_MODEL` + +##### Possible Error States +| State | Description | +| -------------------- | ----------- | +| AL_INVALID_ENUM | The specified parameter is not valid. | +| AL_INVALID_OPERATION | There is no current context. | + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +The double value described by `param` will be returned. + +##### See Also +[alGetBoolean](#algetboolean), [alGetBooleanv](#algetbooleanv), +[alGetDoublev](#algetdoublev), [alGetFloat](#algetfloat), +[alGetFloatv](#algetfloatv), [alGetInteger](#algetinteger), +[alGetIntegerv](#algetintegerv) + +#### alGetFloat +##### Description +This function returns a floating point OpenAL state. + +```cpp +ALfloat alGetFloat( + ALenum param +); +``` + +##### Parameters +* param - the state to be queried: + + `AL_DOPPLER_FACTOR` + + `AL_SPEED_OF_SOUND` + + `AL_DISTANCE_MODEL` + +##### Possible Error States +| State | Description | +| -------------------- | ----------- | +| AL_INVALID_ENUM | The specified parameter is not valid. | +| AL_INVALID_OPERATION | There is no current context. | + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +The floating point state described by `param` will be returned. + +##### See Also +[alGetBoolean](#algetboolean), [alGetBooleanv](#algetbooleanv), +[alGetDouble](#algetdouble), [alGetDoublev](#algetdoublev), +[alGetFloatv](#algetfloatv), [alGetInteger](#algetinteger), +[alGetIntegerv](#algetintegerv) + +#### alGetInteger +##### Description +This function returns an integer OpenAL state. + +```cpp +ALint alGetInteger( + ALenum param +); +``` + +##### Parameters +* param - the state to be queried: + + `AL_DOPPLER_FACTOR` + + `AL_SPEED_OF_SOUND` + + `AL_DISTANCE_MODEL` + +##### Possible Error States +| State | Description | +| -------------------- | ----------- | +| AL_INVALID_ENUM | The specified parameter is not valid. | +| AL_INVALID_OPERATION | There is no current context. | + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +The integer state described by `param` will be returned. + +##### See Also +[alGetBoolean](#algetboolean), [alGetBooleanv](#algetbooleanv), +[alGetDouble](#algetdouble), [alGetDoublev](#algetdoublev), +[alGetFloat](#algetfloat), [alGetFloatv](#algetfloatv), +[alGetIntegerv](#algetintegerv) + +#### alGetBooleanv +##### Description +This function returns an integer OpenAL state. + +```cpp +void alGetBooleanv( + ALenum param, + ALboolean* data +); +``` + +##### Parameters +* param - the state to be queried: + + `AL_DOPPLER_FACTOR` + + `AL_SPEED_OF_SOUND` + + `AL_DISTANCE_MODEL` +* data - A pointer to the location where the state will be stored + +##### Possible Error States +| State | Description | +| -------------------- | ----------- | +| AL_INVALID_ENUM | The specified parameter is not valid. | +| AL_INVALID_VALUE | The specified data pointer is not valid. | +| AL_INVALID_OPERATION | There is no current context. | + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +None + +##### See Also +[alGetBoolean](#algetboolean), [alGetDouble](#algetdouble), +[alGetDoublev](#algetdoublev), [alGetFloat](#algetfloat), +[alGetFloatv](#algetfloatv), [alGetInteger](#algetinteger), +[alGetIntegerv](#algetintegerv) + +#### alGetDoublev +##### Description +This function retrieves a double precision floating point OpenAL state. + +```cpp +void alGetDoublev( + ALenum param, + ALdouble* data +); +``` + +##### Parameters +* param - the state to be queried: + + `AL_DOPPLER_FACTOR` + + `AL_SPEED_OF_SOUND` + + `AL_DISTANCE_MODEL` +* data - A pointer to the location where the state will be stored + +##### Possible Error States +| State | Description | +| -------------------- | ----------- | +| AL_INVALID_ENUM | The specified parameter is not valid. | +| AL_INVALID_VALUE | The specified data pointer is not valid. | +| AL_INVALID_OPERATION | There is no current context. | + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +None + +##### See Also +[alGetBoolean](#algetboolean), [alGetBooleanv](#algetbooleanv), +[alGetDouble](#algetdouble), [alGetFloat](#algetfloat), +[alGetFloatv](#algetfloatv), [alGetInteger](#algetinteger), +[alGetIntegerv](#algetintegerv) + +#### alGetFloatv +##### Description +This function retrieves a floating point OpenAL state. + +```cpp +void alGetFloatv( + ALenum param, + ALfloat* data +); +``` + +##### Parameters +* param - the state to be queried: + + `AL_DOPPLER_FACTOR` + + `AL_SPEED_OF_SOUND` + + `AL_DISTANCE_MODEL` +* data - A pointer to the location where the state will be stored + +##### Possible Error States +| State | Description | +| -------------------- | ----------- | +| AL_INVALID_ENUM | The specified parameter is not valid. | +| AL_INVALID_VALUE | The specified data pointer is not valid. | +| AL_INVALID_OPERATION | There is no current context. | + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +None + +##### See Also +[alGetBoolean](#algetboolean), [alGetBooleanv](#algetbooleanv), +[alGetDouble](#algetdouble), [alGetDoublev](#algetdoublev), +[alGetFloat](#algetfloat), [alGetInteger](#algetinteger), +[alGetIntegerv](#algetintegerv) + +#### alGetIntegerv +##### Description +This function retrieves an integer OpenAL state. + +```cpp +void alGetIntegerv( + ALenum param, + ALint* data +); +``` + +##### Parameters +* param - the state to be queried: + + `AL_DOPPLER_FACTOR` + + `AL_SPEED_OF_SOUND` + + `AL_DISTANCE_MODEL` +* data - A pointer to the location where the state will be stored + +##### Possible Error States +| State | Description | +| -------------------- | ----------- | +| AL_INVALID_ENUM | The specified parameter is not valid. | +| AL_INVALID_VALUE | The specified data pointer is not valid. | +| AL_INVALID_OPERATION | There is no current context. | + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +None + +##### See Also +[alGetBoolean](#algetboolean), [alGetBooleanv](#algetbooleanv), +[alGetDouble](#algetdouble), [alGetDoublev](#algetdoublev), +[alGetFloat](#algetfloat), [alGetFloatv](#algetfloatv), +[alGetInteger](#algetinteger) + +#### alGetString +##### Description +This function retrieves an OpenAL string property. + +```cpp +const ALchar* alGetString( + ALenum param +); +``` + +##### Parameters +* param - the state to be queried: + + `AL_VENDOR` + + `AL_VERSION` + + `AL_RENDERER` + + `AL_EXTENSIONS` + +##### Possible Error States +| State | Description | +| -------------------- | ----------- | +| AL_INVALID_ENUM | The specified parameter is not valid. | + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +Returns a pointer to a null-terminated string. + +#### alDistanceModel +##### Description +This function selects the OpenAL distance model – `AL_INVERSE_DISTANCE`, +`AL_INVERSE_DISTANCE_CLAMPED`, `AL_LINEAR_DISTANCE`, +`AL_LINEAR_DISTANCE_CLAMPED`, `AL_EXPONENT_DISTANCE`, +`AL_EXPONENT_DISTANCE_CLAMPED`, or `AL_NONE`. + +The `AL_INVERSE_DISTANCE` model works according to the following formula: +```cpp +gain = AL_REFERENCE_DISTANCE / (AL_REFERENCE_DISTANCE + + AL_ROLLOFF_FACTOR * (distance - AL_REFERENCE_DISTANCE)); +``` + +The `AL_INVERSE_DISTANCE_CLAMPED` model works according to the following +formula: +```cpp +distance = max(distance, AL_REFERENCE_DISTANCE); +distance = min(distance, AL_MAX_DISTANCE); +gain = AL_REFERENCE_DISTANCE / (AL_REFERENCE_DISTANCE + + AL_ROLLOFF_FACTOR * (distance - AL_REFERENCE_DISTANCE)); +``` + +Here is a graph showing the inverse distance curve: +![Inverse Distance Curve](images/figure-inverse-distance.jpg) + +The `AL_LINEAR_DISTANCE` model works according to the following formula: +```cpp +distance = min(distance, AL_MAX_DISTANCE); // Avoid negative gain +gain = (1 - AL_ROLLOFF_FACTOR * (distance - + AL_REFERENCE_DISTANCE) / + (AL_MAX_DISTANCE - AL_REFERENCE_DISTANCE)); +``` + +The `AL_LINEAR_DISTANCE_CLAMPED` model works according to the following formula: +```cpp +distance = max(distance, AL_REFERENCE_DISTANCE); +distance = min(distance, AL_MAX_DISTANCE); +gain = (1 - AL_ROLLOFF_FACTOR * (distance - + AL_REFERENCE_DISTANCE) / + (AL_MAX_DISTANCE - AL_REFERENCE_DISTANCE)); +``` + +Here is a graph showing the linear distance curve: +![Inverse Distance Curve](images/figure-linear-distance.jpg) + +The `AL_EXPONENT_DISTANCE` model works according to the following forumula: +```cpp +gain = pow(distance / AL_REFERENCE_DISTANCE, -AL_ROLLOFF_FACTOR); +``` + +The `AL_EXPONENT_DISTANCE_CLAMPED` model works according to the following +forumla: +```cpp +distance = max(distance, AL_REFERENCE_DISTANCE); +distance = min(distance, AL_MAX_DISTANCE); +gain = pow(distance / AL_REFERENCE_DISTANCE, -AL_ROLLOFF_FACTOR); +``` + +Here is a graph showing the exponential distance curve: +![Inverse Distance Curve](images/figure-exponential-distance.jpg) + +The `AL_NONE` distance model works according to the following formula: +```cpp +gain = 1; +``` + +```cpp +void alDistanceModel( + ALenum value +); +``` + +##### Parameters +* value - The distance model to be set: + + `AL_INVERSE_DISTANCE` + + `AL_INVERSE_DISTANCE_CLAMPED` + + `AL_LINEAR_DISTANCE` + + `AL_LINEAR_DISTANCE_CLAMPED` + + `AL_EXPONENT_DISTANCE` + + `AL_EXPONENT_DISTANCE_CLAMPED` + + `AL_NONE` + +##### Possible Error States +| State | Description | +| -------------------- | ----------- | +| AL_INVALID_VALUE | The specified distance model is not valid. | +| AL_INVALID_OPERATION | There is no current context. | + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +The default distance model in OpenAL is `AL_INVERSE_DISTANCE_CLAMPED`. + +#### alDopplerFactor +##### Description +This function selects the OpenAL Doppler factor value. + +```cpp +void alDopplerFactor( + ALfloat value +); +``` + +##### Parameters +* value - The Doppler scale value to set + +##### Possible Error States +| State | Description | +| -------------------- | ----------- | +| AL_INVALID_VALUE | The specified distance model is not valid. | +| AL_INVALID_OPERATION | There is no current context. | + +##### Version Requirements +OpenAL 1.0 or higher + +##### Remarks +The default Doppler factor value is 1.0. + +#### alSpeedOfSound +##### Description +This function selects the speed of sound for use in Doppler calculations. + +```cpp +void alSpeedOfSound( + ALfloat value +); +``` + +##### Parameters +* value - The speed of sound value to set + +##### Possible Error States +| State | Description | +| -------------------- | ----------- | +| AL_INVALID_VALUE | The specified distance model is not valid. | +| AL_INVALID_OPERATION | There is no current context. | + +##### Version Requirements +OpenAL 1.1 or higher + +##### Remarks +The default speed of sound value is 343.3.