Main and Miscellanious - ALURE

# Main and Miscellanious

Summary

Main and Miscellanious |
Functions |
alureGetVersion | Stores the major and minor version of the library.
alureGetErrorString | Returns a string describing the last error encountered.
alureGetDeviceNames | Gets an array of device name strings from OpenAL.
alureFreeDeviceNames | Frees the device name array returned from alureGetDeviceNames.
alureInitDevice | Opens the named device, creates a context with the given attributes, and sets that context as current.
alureShutdownDevice | Destroys the current context and closes its associated device.
alureGetSampleFormat | Retrieves an OpenAL format for the given sample format.
alureInstallDecodeCallbacks | Installs callbacks to enable ALURE to handle more file types.
alureSleep | Rests the calling thread for the given number of seconds.
alureGetProcAddress | Returns a pointer for the named ALURE function.

### Functions

### alureGetVersion

> ALURE_API void ALURE_APIENTRY alureGetVersion( | ALuint | * | major,
> | ALuint | * | minor | )

Stores the major and minor version of the library. If either major or minor are NULL, that value is not provided.

### alureGetErrorString

> ALURE_API const ALchar* ALURE_APIENTRY alureGetErrorString( | void | )

Returns a string describing the last error encountered.

### alureGetDeviceNames

> ALURE_API const ALCchar** ALURE_APIENTRY alureGetDeviceNames( | ALCboolean |  | all,
> | ALCsizei | * | count | )

Gets an array of device name strings from OpenAL. This encapsulates AL_ENUMERATE_ALL_EXT (if supported and ‘all’ is true) and standard enumeration, with ‘count’ being set to the number of returned device names.

#### Returns

An array of device name strings, or NULL on error.

#### See Also

alureFreeDeviceNames

### alureFreeDeviceNames

> ALURE_API ALvoid ALURE_APIENTRY alureFreeDeviceNames( | const | ALCchar | ** | names | )

Frees the device name array returned from alureGetDeviceNames.

#### See Also

alureGetDeviceNames

### alureInitDevice

> ALURE_API ALboolean ALURE_APIENTRY alureInitDevice( | const | ALCchar | * | name,
> | const | ALCint | * | attribs | )

Opens the named device, creates a context with the given attributes, and sets that context as current. The name and attribute list would be the same as what’s passed to alcOpenDevice and alcCreateContext respectively.

#### Returns

AL_FALSE on error.

#### See Also

alureShutdownDevice

### alureShutdownDevice

> ALURE_API ALboolean ALURE_APIENTRY alureShutdownDevice( | void | )

Destroys the current context and closes its associated device.

#### Returns

AL_FALSE on error.

#### See Also

alureInitDevice

### alureGetSampleFormat

> ALURE_API ALenum ALURE_APIENTRY alureGetSampleFormat( | ALuint | channels,
> | ALuint | bits,
> | ALuint | floatbits | )

Retrieves an OpenAL format for the given sample format. If bits is non-0, floatbits must be 0, and if floatbits is non-0, bits must be 0. The application should not rely on any particular format enum being returned as it is dependant on the available extensions. The returned format will be valid for the current context. Requires an active context.

#### Returns

An OpenAL format enum for the given sample format, or AL_NONE if one can’t be found.

### alureInstallDecodeCallbacks

> ALURE_API ALboolean ALURE_APIENTRY alureInstallDecodeCallbacks(
> | ALint |  | index,
> | void | * | (*open_file)(const ALchar *filename),
> | void | * | (*open_memory)(const ALubyte *data, ALuint length),
> | ALboolean |  | (*get_format)(void *instance, ALenum *format, ALuint *samplerate, ALuint *blocksize),
> | ALuint |  | (*decode)(void *instance, ALubyte *data, ALuint bytes),
> | ALboolean |  | (*rewind)(void *instance),
> | void |  | (*close)(void *instance)
> )

Installs callbacks to enable ALURE to handle more file types. The index is the order that each given set of callbacks will be tried, starting at the most negative number (INT_MIN) and going up. Negative indices will be tried before the built-in decoders, and positive indices will be tried after. Installing callbacks onto the same index multiple times will remove the previous callbacks, and removing old callbacks won’t affect any opened files using them (they’ll continue to use the old functions until properly closed, although newly opened files will use the new ones). Passing NULL for all callbacks is a valid way to remove an installed set, otherwise certain callbacks must be specified. Callbacks that are not specified will assume failure.

#### Parameters

open_file | This callback is expected to open the named file and prepare it for decoding. If the callbacks cannot decode the file, NULL should be returned to indicate failure. Upon success, a non-NULL handle must be returned, which will be used as a unique identifier for the decoder instance. This callback is required if open_memory is not specified.
open_memory | This callback behaves the same as open_file, except it takes a memory segment for input instead of a filename. The given memory will remain valid while the instance is open. This callback is required if open_file is not specified.
get_format | This callback is used to retrieve the format of the decoded data for the given instance. It is the responsibility of the function to make sure the returned format is valid for the current AL context (eg. don’t return AL_FORMAT_QUAD16 if the AL_EXT_MCFORMATS extension isn’t available). Returning 0 for samplerate or blocksize, or returning AL_NONE for format, will cause a failure. Returning AL_FALSE indicates failure. This callback is required.
decode | This callback is called to get more decoded data. Up to the specified amount of bytes should be written to the data pointer. The number of bytes written should be a multiple of the block size, otherwise an OpenAL error may occur during buffering. The function should return the number of bytes written. This callback is required.
rewind | This callback is for rewinding the instance so that the next decode calls for it will get audio data from the start of the sound file. If the stream fails to rewind, AL_FALSE should be returned.
close | This callback is called at the end of processing for a particular instance. The handle will not be used further and any associated data may be deleted.

#### Returns

AL_FALSE on error.

### alureSleep

> ALURE_API ALboolean ALURE_APIENTRY alureSleep( | ALfloat | duration | )

Rests the calling thread for the given number of seconds.

#### Returns

AL_FALSE on error.

### alureGetProcAddress

> ALURE_API void* ALURE_APIENTRY alureGetProcAddress( | const | ALchar | * | funcname | )

Returns a pointer for the named ALURE function.

#### Returns

NULL on error.

Version Added: 1.1

> ALURE_API void ALURE_APIENTRY alureGetVersion( | ALuint | * | major,
> | ALuint | * | minor | )

Stores the major and minor version of the library.

> ALURE_API const ALchar* ALURE_APIENTRY alureGetErrorString( | void | )

Returns a string describing the last error encountered.

> ALURE_API const ALCchar** ALURE_APIENTRY alureGetDeviceNames( | ALCboolean |  | all,
> | ALCsizei | * | count | )

Gets an array of device name strings from OpenAL.

> ALURE_API ALvoid ALURE_APIENTRY alureFreeDeviceNames( | const | ALCchar | ** | names | )

Frees the device name array returned from alureGetDeviceNames.

> ALURE_API ALboolean ALURE_APIENTRY alureInitDevice( | const | ALCchar | * | name,
> | const | ALCint | * | attribs | )

Opens the named device, creates a context with the given attributes, and sets that context as current.

> ALURE_API ALboolean ALURE_APIENTRY alureShutdownDevice( | void | )

Destroys the current context and closes its associated device.

> ALURE_API ALenum ALURE_APIENTRY alureGetSampleFormat( | ALuint | channels,
> | ALuint | bits,
> | ALuint | floatbits | )

Retrieves an OpenAL format for the given sample format.

> ALURE_API ALboolean ALURE_APIENTRY alureInstallDecodeCallbacks(
> | ALint |  | index,
> | void | * | (*open_file)(const ALchar *filename),
> | void | * | (*open_memory)(const ALubyte *data, ALuint length),
> | ALboolean |  | (*get_format)(void *instance, ALenum *format, ALuint *samplerate, ALuint *blocksize),
> | ALuint |  | (*decode)(void *instance, ALubyte *data, ALuint bytes),
> | ALboolean |  | (*rewind)(void *instance),
> | void |  | (*close)(void *instance)
> )

Installs callbacks to enable ALURE to handle more file types.

> ALURE_API ALboolean ALURE_APIENTRY alureSleep( | ALfloat | duration | )

Rests the calling thread for the given number of seconds.

> ALURE_API void* ALURE_APIENTRY alureGetProcAddress( | const | ALchar | * | funcname | )

Returns a pointer for the named ALURE function.
Close