Discussion
of the API is done via the openal-devel
mailing list.
This
is the OpenAL Utility Toolkit (ALUT)
Reference Manual.
Some
previous versions of ALUT were released under the BSD license - others under
LGPL. This version will be released exclusively under LGPL.
At
the time of the first writing of this document (August 2005), ALUT was a set of
undocumented semi-portable functions that were mixed up in the OpenAL library
distribution. The intent had always been that ALUT would be a cleanly separated
library that would be portable between systems. It was hoped that it would be
well suited to producing succinct demo programs and to help new developers to
get started with OpenAL. It was to do this by removing the annoying details of
getting an audio application started - allowing developers to learn OpenAL
without distractions such as loading sound samples from disk.
In
order to move from this initial implementation to a clean API that would meet
the original goals of ALUT, it was necessary to break from the past and make a
clean start. The original version(s) were unnumbered - so we will arbitarily
label all previous versions as 0.x.x and start this cleaned up version at
release 1.0.0 to reflect changed API and implementations.
There
are no formal guarantees of reverse compatibility with the various versions of
ALUT prior to 1.0.0. Having said that, some effort has been
made to at least allow these programs to continue to run if they are recompiled
against ALUT 1.0.0 or later.
The
old Linux implementation of OpenAL poses a special compatibility problem: ALUT
0.x.x was not a physically separate library on this platform,
it was actually part of libopenal itself. This is bad for at least two reasons:
It was handled differently on other platforms and much more seriously it locked
together OpenAL and ALUT releases. So a deliberate decision was made to break
binary compatibility in this respect and cleanly split the libraries into an
OpenAL (i.e. AL and ALC) part and an ALUT one.
If
you have a program which needs such an old, deprecated "combined
OpenAL/ALUT" and you are not able to recompile it for some reason (e.g. it
is available in binary format only), then temporarily setting the environment
variable LD_PRELOAD to the full path of your installed
ALUT dynamic library can help. If this really works depends on the platform,
but e.g. Linux, FreeBSD, NetBSD, Solaris etc. support
this mechanism. On Mac OS X there is a similar environment variable called DYLD_INSERT_LIBRARIES, but this
has not been tested yet.
Let's assume that your ALUT dynamic library
is at the usual location /usr/lib/libalut.so and you have an old
program called myOldProg, then the following commandline in
Bash syntax does the trick:
LD_PRELOAD="/usr/lib/libalut.so" myOldProgNote that setting LD_PRELOAD globally
might not be a good idea, because in that case the new ALUT would be loaded
before every dynamically linked
executable.
If
you are already familiar with OpenGL and its utility toolkit GLUT, then you
should feel very familiar with ALUT. Wherever GLUT has 'GL', ALUT has '
Here is the traditional first program for any
language or library, but this time it is actually saying 'Hello, world!' instead of printing it:
#include <stdlib.h>#include <AL/alut.h> int
main (int argc, char **argv)
{ ALuint helloBuffer, helloSource; alutInit (&argc, argv); helloBuffer = alutCreateBufferHelloWorld (); alGenSources (1, &helloSource); alSourcei (helloSource, AL_BUFFER, helloBuffer); alSourcePlay (helloSource); alutSleep (1); alutExit (); return EXIT_SUCCESS;}Note that there error checks are missing in
the program above to keep it simple.
All
ALUT programs should contain:
#include <AL/alut.h>The
ALUT header includes <AL/al.h> and <AL/alc.h> for you so
you don't need to include them again - although it does not hurt to do so. ALUT
reserves the "ALUT_" prefix for preprocessor macros, so you
should never define such a macro in your own program. Furthermore, you should
not rely on any macro starting with "ALUT_" not
mentioned in this specification.
If
you are using the freealut implementation of ALUT, which is available via the OpenAL homepage, you can find out the
necessary compilation flags by using one of the following commands:
pkg-config --cflags freealut
freealut-config --cflags
To
find out the necessary flags for linking, use one of the following commands:
pkg-config --libs freealut
freealut-config --libs
On Windows, link with alut.dll and openal32.dll.
ALUT
reserves the "alut" prefix for globally visible functions
and variables, so you should never define such a function or variable in your
own program. Furthermore, you should not rely on any such function or variable
not mentioned in this specification.
ALUT's
error handling and reporting is a little bit different from the one used in
OpenAL and OpenGL: All functions which can fail report success/failure via a
return value, where AL_FALSE / AL_NONE / NULL mean
failure. alutGetError can be used to find
out what exactly went wrong.
It
is guaranteed that if a function fails, no data pointed to by pointer arguments
has been changed.
alutGetError - return and clear
the current error state
ALenum alutGetError (void);Any
ALUT routine that fails will return AL_FALSE / AL_NONE / NULL and set the
global error state. If a subsequent error occurs while there is still an error
recorded internally, the second error will simply be ignored. Calling alutGetError will reset
the error code to ALUT_ERROR_NO_ERROR. Note that the
error state is not cleared by
other successful ALUT calls.
alutGetError returns the
contents of the global error state, which can be one of the following values:
ALUT_ERROR_NO_ERROR
No ALUT error found.
ALUT_ERROR_OUT_OF_MEMORY
ALUT ran out of memory.
ALUT_ERROR_INVALID_ENUM
ALUT was given an invalid enumeration
token.
ALUT_ERROR_INVALID_VALUE
ALUT was given an invalid value.
ALUT_ERROR_INVALID_OPERATION
The operation is invalid in the current
ALUT state.
ALUT_ERROR_NO_CURRENT_CONTEXT
There is no current
ALUT_ERROR_AL_ERROR_ON_ENTRY
There was already an
ALUT_ERROR_ALC_ERROR_ON_ENTRY
There was already an ALC error on entry
to an ALUT function.
ALUT_ERROR_OPEN_DEVICE
There was an error opening the ALC
device.
ALUT_ERROR_CLOSE_DEVICE
There was an error closing the ALC
device.
ALUT_ERROR_CREATE_CONTEXT
There was an error creating an ALC
context.
ALUT_ERROR_MAKE_CONTEXT_CURRENT
Could not change the
current ALC context.
ALUT_ERROR_DESTROY_CONTEXT
There was an error destroying the ALC
context.
ALUT_ERROR_GEN_BUFFERS
There was an error generating an
ALUT_ERROR_BUFFER_DATA
There was an error passing buffer data
to
ALUT_ERROR_IO_ERROR
I/O error, consult errno for more
details.
ALUT_ERROR_UNSUPPORTED_FILE_TYPE
Unsupported file type.
ALUT_ERROR_UNSUPPORTED_FILE_SUBTYPE
Unsupported mode
within an otherwise usable file type.
ALUT_ERROR_CORRUPT_OR_TRUNCATED_DATA
The sound data was corrupt or
truncated.
alutGetError can be called in
any ALUT state and will never fail.
alutGetErrorString - return an error
message string given an error code
const char *alutGetErrorString (ALenum error);
alutGetErrorString can be used to
convert an error code into a human-readable description. The precise text of
these descriptions may vary from implementation to implementation and should
not be relied upon by the application.
alutGetErrorString returns a pointer
to an immutable zero-terminated string corresponding to the given error code.
alutGetErrorString can be called in
any ALUT state and will never fail. An unknown error code is not considered an
error and a generic description will be returned in that case.
A typical ALUT program might look like this:
static void
reportError (void)
{ fprintf (stderr, "ALUT error: %s\n", alutGetErrorString (alutGetError ())); exit (EXIT_FAILURE);} int
main (int argc, char **argv)
{ if (!alutInit (&argc, argv)) { reportError (); } /* ...play audio for a while... */ if (!alutExit ()) { reportError (); } return EXIT_SUCCESS;}ALUT
starts in an uninitialized
state. alutInit and alutInitWithoutContext put ALUT
into the initialized state.
Those functions must only be called when the state is uninitialized. alutExit puts ALUT
back from an initialized state
to an uninitialized one.
The
following functions must only be called in an initialized state and with a current context: alutExit, alutCreateBufferFromFile, alutCreateBufferFromFileImage, alutLoadMemoryFromFile, alutLoadMemoryFromFileImage, alutGetMIMETypes, alutCreateBufferHelloWorld, alutCreateBufferWaveform. All these
functions check for AL/ALC errors on entry and immediately return ALUT_ERROR_AL_ERROR_ON_ENTRY or ALUT_ERROR_ALC_ERROR_ON_ENTRY if there
was one. Note that as a consequence of these checks the AL/ALC error states for
the current context/device are cleared after calling any of these functions.
alutSleep can be called in
every state.
The
following functions never fail and can be called in any state: alutGetError, alutGetErrorString, alutGetMajorVersion, alutGetMinorVersion.
alutInit - initialize the
ALUT library and create a default current context
ALboolean alutInit (int *argcp, char **argv);alutInit initializes the
ALUT internals and creates an OpenAL context on the default device and makes it
the current OpenAL context. If you want something more
complex than that (e.g. running on a non-default device or opening multiple
contexts on multiple devices), you can use alutInitWithoutContext instead.
alutInit examines the
commandline arguments passed to it and remove those it recognizes. It is
acceptable to pass two NULL pointers in
settings where no useful information can be obtained from argc and argv.
alutInit returns AL_TRUE on success
or AL_FALSE on failure.
ALUT_ERROR_INVALID_VALUE
One of the arguments was NULL, but not
the other one.
ALUT_ERROR_INVALID_OPERATION
ALUT has already been initialized.
ALUT_ERROR_OPEN_DEVICE
There was an error opening the default
ALC device.
ALUT_ERROR_CREATE_CONTEXT
There was an error creating an ALC
context.
ALUT_ERROR_MAKE_CONTEXT_CURRENT
Could not change the
current ALC context.
If you pass alutInit the argc
and argv from your main program, it will examine your command-line options and
use (and remove) those options that it recognises:
int
main (int argc, char **argv)
{ alutInit (&argc, argv); ...}Precisely which (if any) command-line options
are accepted and what they control is implementation and operating system
dependent. Note that some implementations will use argv[0]
in debug and error messages - but this is not guaranteed by the API because it
is operating-system dependent. On some OS's, alutInit may use
initial settings from other sources such as 'registry' data, '.alutrc' files or
shell variables. Please consult the README.xxx file for your OS if you need
further details.
alutInitWithoutContext - initialize the
ALUT library
ALboolean alutInitWithoutContext (int *argcp, char **argv);alutInitWithoutContext initializes the
ALUT internals. It does not create any OpenAL context or device, so this has to
be done via the usual ALC calls. alutInitWithoutContext examines
the commandline arguments passed to it and remove those it recognizes. It is
acceptable to pass two NULL pointers in
settings where no useful information can be obtained from argc and argv.
alutInitWithoutContext returns AL_TRUE on success
or AL_FALSE on failure.
ALUT_ERROR_INVALID_VALUE
One of the arguments was NULL, but not
the other one.
ALUT_ERROR_INVALID_OPERATION
ALUT has already been initialized.
alutExit - shutdown the ALUT
library
ALboolean alutExit (void);When
the application has finished playing audio, it should shut down ALUT using aluExit. This
closes any OpenAL device/context that ALUT may have created in alutInit (but not
any that the application created using ALC). After calling alutExit, you may
subsequently call alutInit or alutInitWithoutContext again. Note
that under well-behaved operating systems, it should be acceptable to simply
exit from your program without bothering to call alutExit, relying on
the OS to clean up after you. However, it is dangerous to rely on this behavior
if portable operation is expected.
alutExit returns AL_TRUE on success
or AL_FALSE on failure.
ALUT_ERROR_INVALID_OPERATION
ALUT has not been initialised.
ALUT_ERROR_NO_CURRENT_CONTEXT
There is no current
ALUT_ERROR_AL_ERROR_ON_ENTRY
There was already an
ALUT_ERROR_ALC_ERROR_ON_ENTRY
There was already an ALC error on entry
to alutExit.
ALUT_ERROR_CLOSE_DEVICE
There was an error closing the ALC
device created by alutInit.
ALUT_ERROR_MAKE_CONTEXT_CURRENT
Could not release
the current ALC context.
ALUT_ERROR_DESTROY_CONTEXT
There was an error destroying the ALC
context created by alutInit.
ALUT
attempts to simplify the business of getting a simple application running by
providing loaders for a range of file formats. Rather than enumerate a list of
formats that will likely grow with time, the loaders are generic and try to do
their best either by using OpenAL extensions if possible or by converting the
sound data into standard OpenAL formats.
In
order to simplify initial startup and to keep test program distributions clean,
ALUT provides built-in sounds, too, that do not require disk I/O because they
are built into the ALUT library. These functions may be used to write compact
ALUT test/example applications with no external file dependancies whatsoever.
When sending short application programs to either the ALUT or OpenAL developers
as a part of bug reporting, one should endeavor to use these functions instead
of loading ones own sound files.
There
are eight (= 4 * 2) different loaders, corresponding to the sources and
destinations of the sound data. The possible sources are:
The
possible destinations are:
alutCreateBufferFromFile - load a sound file
into an OpenAL buffer
ALuint alutCreateBufferFromFile (const char *filename);alutCreateBufferFromFile tries to guess the
sound data format by looking at the filename and/or the file contents and loads
the sound data into an OpenAL buffer.
On
success, alutCreateBufferFromFile returns a handle to
an OpenAL buffer containing the loaded sound. It returns AL_NONE on failure.
ALUT_ERROR_OUT_OF_MEMORY
ALUT ran out of memory.
ALUT_ERROR_INVALID_OPERATION
ALUT has not been initialised.
ALUT_ERROR_NO_CURRENT_CONTEXT
There is no current
ALUT_ERROR_AL_ERROR_ON_ENTRY
There was already an
ALUT_ERROR_ALC_ERROR_ON_ENTRY
There was already an ALC error on entry
to alutCreateBufferFromFile.
ALUT_ERROR_GEN_BUFFERS
There was an error generating an
ALUT_ERROR_BUFFER_DATA
There was an error passing buffer data
to
ALUT_ERROR_IO_ERROR
I/O error, consult errno for more
details.
ALUT_ERROR_UNSUPPORTED_FILE_TYPE
Unsupported file type.
ALUT_ERROR_UNSUPPORTED_FILE_SUBTYPE
Unsupported mode
within an otherwise usable file type.
ALUT_ERROR_CORRUPT_OR_TRUNCATED_DATA
The sound data was corrupt or
truncated.
alutCreateBufferFromFileImage - load
in-memory sound data into an OpenAL buffer
ALuint alutCreateBufferFromFileImage (const ALvoid *data, ALsizei length);alutCreateBufferFromFileImage tries to
guess the sound data format by looking at the contents of the memory region
given as parameters and loads the sound data into an OpenAL buffer.
On
success, alutCreateBufferFromFileImage returns a handle to
an OpenAL buffer containing the loaded sound. It returns AL_NONE on failure.
ALUT_ERROR_OUT_OF_MEMORY
ALUT ran out of memory.
ALUT_ERROR_INVALID_OPERATION
ALUT has not been initialised.
ALUT_ERROR_NO_CURRENT_CONTEXT
There is no current
ALUT_ERROR_AL_ERROR_ON_ENTRY
There was already an
ALUT_ERROR_ALC_ERROR_ON_ENTRY
There was already an ALC error on entry
to alutCreateBufferFromFileImage.
ALUT_ERROR_GEN_BUFFERS
There was an error generating an
ALUT_ERROR_BUFFER_DATA
There was an error passing buffer data
to
ALUT_ERROR_UNSUPPORTED_FILE_TYPE
Unsupported file type.
ALUT_ERROR_UNSUPPORTED_FILE_SUBTYPE
Unsupported mode
within an otherwise usable file type.
ALUT_ERROR_CORRUPT_OR_TRUNCATED_DATA
The sound data was corrupt or truncated.
alutCreateBufferHelloWorld - create a
buffer with a 'Hello, world!' sound
ALuint alutCreateBufferHelloWorld (void);alutCreateBufferHelloWorld returns a
handle to an OpenAL buffer containing the sound of someone saying 'Hello,
world!'.
On
success, alutCreateBufferHelloWorld returns a handle to
an OpenAL buffer containing a 'Hello, world!' sound. It returns AL_NONE on failure.
ALUT_ERROR_OUT_OF_MEMORY
ALUT ran out of memory.
ALUT_ERROR_INVALID_OPERATION
ALUT has not been initialised.
ALUT_ERROR_NO_CURRENT_CONTEXT
There is no current
ALUT_ERROR_AL_ERROR_ON_ENTRY
There was already an
ALUT_ERROR_ALC_ERROR_ON_ENTRY
There was already an ALC error on entry
to alutCreateBufferHelloWorld.
ALUT_ERROR_GEN_BUFFERS
There was an error generating an
ALUT_ERROR_BUFFER_DATA
There was an error passing buffer data
to
alutCreateBufferWaveform - create a buffer
with a synthesized waveform sound
ALuint alutCreateBufferWaveform (ALenum waveshape, ALfloat frequency, ALfloat phase, ALfloat duration);alutCreateBufferWaveform returns a handle to
an OpenAL buffer containing a snippet of audio with the specified waveshape at
the specified frequency (in Hertz), phase (in degrees: -180 to +180) and
duration (in seconds). Allowed waveforms are:
The
duration will always be rounded up to an exact number of cycles of the sound to
avoid a click if you loop the sample. The frequency and phase arguments are
ignored for ALUT_WHITENOISE.
On
success, alutCreateBufferWaveform returns a handle to
an OpenAL buffer containing the synthesized waveform. It returns AL_NONE on failure.
ALUT_ERROR_OUT_OF_MEMORY
ALUT ran out of memory.
ALUT_ERROR_INVALID_ENUM
An invalid waveform token was given to alutCreateBufferWaveform.
ALUT_ERROR_INVALID_VALUE
The frequency was not positive or the
duration was negative.
ALUT_ERROR_INVALID_OPERATION
ALUT has not been initialised.
ALUT_ERROR_NO_CURRENT_CONTEXT
There is no current
ALUT_ERROR_AL_ERROR_ON_ENTRY
There was already an
ALUT_ERROR_ALC_ERROR_ON_ENTRY
There was already an ALC error on entry
to alutCreateBufferWaveform.
ALUT_ERROR_GEN_BUFFERS
There was an error generating an
ALUT_ERROR_BUFFER_DATA
There was an error passing buffer data
to
alutLoadMemoryFromFile - load a sound file
into OpenAL-like data
ALvoid *alutLoadMemoryFromFile (const char *filename, ALenum *format, ALsizei *size, ALfloat *frequency);alutLoadMemoryFromFile tries to guess the
sound data format by looking at the filename and/or the file contents and loads
the sound data into a newly malloced buffer, possibly
converting it in the process. The format is guaranteed to be a standard OpenAL
format afterwards.
On
success, alutLoadMemoryFromFile returns a pointer
to a newly allocated memory area containing the sound data, which can be freed if not
needed anymore. It returns NULL on failure. If any
of the format, size or frequency parameters are non-NULL, the
respective information about the sound will be passed back.
ALUT_ERROR_OUT_OF_MEMORY
ALUT ran out of memory.
ALUT_ERROR_INVALID_OPERATION
ALUT has not been initialised.
ALUT_ERROR_NO_CURRENT_CONTEXT
There is no current
ALUT_ERROR_AL_ERROR_ON_ENTRY
There was already an
ALUT_ERROR_ALC_ERROR_ON_ENTRY
There was already an ALC error on entry
to alutLoadMemoryFromFile.
ALUT_ERROR_IO_ERROR
I/O error, consult errno for more
details.
ALUT_ERROR_UNSUPPORTED_FILE_TYPE
Unsupported file type.
ALUT_ERROR_UNSUPPORTED_FILE_SUBTYPE
Unsupported mode
within an otherwise usable file type.
ALUT_ERROR_CORRUPT_OR_TRUNCATED_DATA
The sound data was corrupt or
truncated.
alutLoadMemoryFromFileImage - convert
in-memory sound data into OpenAL-like data
ALvoid *alutLoadMemoryFromFileImage (const ALvoid *data, ALsizei length, ALenum *format, ALsizei *size, ALfloat *frequency);alutLoadMemoryFromFileImage tries to
guess the sound data format by looking at the contents of the memory region
given as the first two arguments and loads the sound data into a newly malloced buffer,
possibly converting it in the process. The format is guaranteed to be a
standard OpenAL format afterwards.
On
success, alutLoadMemoryFromFileImage returns a pointer
to a newly allocated memory area containing the sound data, which can be freed if not
needed anymore. It returns NULL on failure. If any
of the format, size or frequency parameters are non-NULL, the
respective information about the sound will be passed back.
ALUT_ERROR_OUT_OF_MEMORY
ALUT ran out of memory.
ALUT_ERROR_INVALID_OPERATION
ALUT has not been initialised.
ALUT_ERROR_NO_CURRENT_CONTEXT
There is no current
ALUT_ERROR_AL_ERROR_ON_ENTRY
There was already an
ALUT_ERROR_ALC_ERROR_ON_ENTRY
There was already an ALC error on entry
to alutLoadMemoryFromFileImage.
ALUT_ERROR_UNSUPPORTED_FILE_TYPE
Unsupported file type.
ALUT_ERROR_UNSUPPORTED_FILE_SUBTYPE
Unsupported mode
within an otherwise usable file type.
ALUT_ERROR_CORRUPT_OR_TRUNCATED_DATA
The sound data was corrupt or
truncated.
alutLoadMemoryHelloWorld - load a 'Hello,
world!' sound into OpenAL-like data
ALvoid *alutLoadMemoryHelloWorld (ALenum *format, ALsizei *size, ALfloat *frequency); alutLoadMemoryHelloWorld loads the sound of
someone saying 'Hello, world!' into a newly malloced buffer.
The sound data is guaranteed to be in a standard OpenAL format, with a sample
frequency chosen by the ALUT implementation.
On
success, alutLoadMemoryHelloWorld returns a pointer
to a newly allocated memory area containing the sound data, which can be freed if not
needed anymore. It returns NULL on failure. If any
of the format, size or frequency parameters are non-NULL, the
respective information about the sound will be passed back.
ALUT_ERROR_OUT_OF_MEMORY
ALUT ran out of memory.
ALUT_ERROR_INVALID_OPERATION
ALUT has not been initialised.
ALUT_ERROR_NO_CURRENT_CONTEXT
There is no current
ALUT_ERROR_AL_ERROR_ON_ENTRY
There was already an
ALUT_ERROR_ALC_ERROR_ON_ENTRY
There was already an ALC error on entry
to alutLoadMemoryHelloWorld.
alutLoadMemoryWaveform - load a
synthesized waveform sound into OpenAL-like data
ALvoid *alutLoadMemoryWaveform (ALenum waveshape, ALfloat frequency, ALfloat phase, ALfloat duration, ALenum *format, ALsizei *size, ALfloat *sampleFrequency);alutLoadMemoryWaveform loads a snippet of
audio with the specified waveshape at the specified frequency (in Hertz), phase
(in degrees: -180 to +180) and duration (in seconds) into a newly malloced buffer.
The sound data is guaranteed to be in a standard OpenAL format, with a sample
frequency chosen by the ALUT implementation. Allowed waveforms are:
The
duration will always be rounded up to an exact number of cycles of the sound to
avoid a click if you loop the sample. The frequency and phase arguments are
ignored for ALUT_WHITENOISE.
On
success, alutLoadMemoryWaveform returns a pointer
to a newly allocated memory area containing the sound data, which can be freed if not
needed anymore. It returns NULL on failure. If any
of the format, size or sample frequency parameters are non-NULL, the
respective information about the sound will be passed back.
ALUT_ERROR_OUT_OF_MEMORY
ALUT ran out of memory.
ALUT_ERROR_INVALID_ENUM
An invalid waveform token was given to alutLoadMemoryWaveform.
ALUT_ERROR_INVALID_VALUE
The frequency was not positive or the
duration was negative.
ALUT_ERROR_INVALID_OPERATION
ALUT has not been initialised.
ALUT_ERROR_NO_CURRENT_CONTEXT
There is no current
ALUT_ERROR_AL_ERROR_ON_ENTRY
There was already an
ALUT_ERROR_ALC_ERROR_ON_ENTRY
There was already an ALC error on entry
to alutLoadMemoryWaveform.
alutGetMIMETypes - get list support
supported audio MIME types
const char *alutGetMIMETypes (ALenum loader);
alutGetMIMETypes returns a
comma-separated list of supported MIME types for the given loader type, e.g.
something like "audio/basic,audio/mpeg,audio/x-wav".
Allowed loader types are:
ALUT_LOADER_BUFFER
For the loaders returning sound data in
an OpenAL buffer, e.g. alutCreateBufferFromFile and alutCreateBufferFromFileImage
ALUT_LOADER_MEMORY
For the loaders returning sound data in
a newly allocated memory region, e.g. alutLoadMemoryFromFile and alutLoadMemoryFromFileImage
It
is possible that ALUT_LOADER_MEMORY loaders will be
unable to support some file types that ALUT_LOADER_BUFFER loaders can
support (although the reverse is never the case). Furthermore, it is possible
that for some file types (notably audio/x-wav) the support may be only for a
few sub-formats. For example, an implementation may advertise that audio/x-wav
is supported when in fact it only supports uncompressed (i.e. PCM) WAV files
and not any of the compressed subformats. In this event, the various ALUT
loaders may return an error and set ALUT_ERROR_UNSUPPORTED_FILE_SUBTYPE rather than
ALUT_ERROR_UNSUPPORTED_FILE_TYPE which would indicate that no files of
this type are allowed.
On
success, alutGetMIMETypes returns a
zero-terminated string which contains a comma-separated list of supported MIME
types. It returns NULL on failure.
ALUT_ERROR_INVALID_ENUM
alutGetMIMETypes was given
an invalid loader token.
ALUT_ERROR_INVALID_OPERATION
ALUT has not been initialised.
ALUT_ERROR_NO_CURRENT_CONTEXT
There is no current
ALUT_ERROR_AL_ERROR_ON_ENTRY
There was already an
ALUT_ERROR_ALC_ERROR_ON_ENTRY
There was already an ALC error on entry
to alutGetMIMETypes.
For
backwards-compatibility with ALUT 0.x.x, ALUT still offers the three deprecated
functions below. Note that on MacOS 0.x.x version, the 'loop' parameter
is omitted from both loader functions.
void alutLoadWAVFile (ALbyte *filename,
ALenum *format, void **data, ALsizei *size, ALsizei *frequency, ALboolean *loop); void alutLoadWAVMemory (ALbyte *buffer,
ALenum *format, void **data, ALsizei *size, ALsizei *frequency, ALboolean *loop); void alutUnloadWAV (ALenum format ALvoid *data, ALsizei size, ALsizei frequency);
ALUT
version numbers consist of a major version number, a minor version number, and
a patchlevel. The former two numbers will match the major/minor version number
of the corresponding ALUT specification document and can be accessed at compile
time as well as runtime. The patchlevel is not programmatically available and
it is incremented only when fixing bugs without any API changes.
alutGetMajorVersion - return the major
ALUT version number
ALint alutGetMajorVersion (void);alutGetMajorVersion returns the major
version number of the ALUT in use, which will match the major version number of
the corresponding ALUT specification document.
alutGetMajorVersion returns the major
version number of the ALUT in use.
alutGetMajorVersion can be called in
any ALUT state and will never fail.
alutGetMinorVersion - return the minor
ALUT version number
ALint alutGetMinorVersion (void);alutGetMinorVersion returns the minor
version number of the ALUT in use, which will match the minor version number of
the corresponding ALUT specification document.
alutGetMinorVersion returns the minor
version number of the ALUT in use.
alutGetMinorVersion can be called in
any ALUT state and will never fail.
#define ALUT_API_MAJOR_VERSION 1 #define ALUT_API_MINOR_VERSION 1Version
1.0.0 introduced the above preprocessor symbols, whose values will be
incremented appropriately in future revisions of ALUT. In version 1.1.0, alutLoadMemoryHelloWorld and alutLoadMemoryWaveform have been
added to the ALUT API.
Applications can verify at runtime that they
have been compiled and linked with the matching header file and library file as
follows:
#ifdef ALUT_API_MAJOR_VERSIONif (alutGetMajorVersion () != ALUT_API_MAJOR_VERSION ||
alutGetMinorVersion () != ALUT_API_MINOR_VERSION) /* Oh-oh! The ALUT header and the ALUT library are different revisions... */#else /* Oh-oh! We're linking against an ALUT 0.x.x header file... */#endifHaving
a general utility function like the following in an audio-related toolkit might
seem strange at first, but sleeping is a common task in a lot of audio demos
and it can't be done portably without cluttering the source code with #ifdefs.
alutSleep - sleep for a given
number of seconds
ALboolean alutSleep (ALfloat duration);alutSleep will delay the
execution of the current thread for at least the given amount of seconds. It
will only return earlier if a signal has been delivered to the thread, but this
does not count as an error. Note that sleeping for zero seconds will give other
runnable threads a chance to run.
alutSleep returns AL_TRUE on success
or AL_FALSE on failure. Note that current implementations will
always succeed if the duration is non-negative, but this might change in the
future.
ALUT_ERROR_INVALID_VALUE
alutSleep was given a
negative duration.