cl-openal

About
-----

cl-openal is a series of semi-lispy public domain bindings to the OpenAL API. It includes direct
CFFI bindings, as well as varying levels of lispy wrappings around AL, ALC, and ALUT.

The translation from the C bindings to lispy bindings is pretty straightforward, and follows
cl-opengl's example, in spirit.

Loading
-------

cl-openal depends on CFFI to load. It's split into three separate systems: cl-openal for the basic
OpenAL bindings, cl-alc for ALC, and cl-alut for ALUT. If you need anything from ALC or ALUT, you'll
have to specifically load them.

In order to use cl-openal and cl-alc, you'll need to have OpenAL installed on your system, or
available as a shared library/.dll. Additionally, an implementation of ALUT needs to be available in
order to use cl-alut (such as freealut).

cl-openal should run on all major platforms, including Linux, the BSDs, OSX, and Windows. It should
be usable by any Common Lisp implementation supported by CFFI.

Error handling
--------------

**BREAKING CHANGE NOTICE:** The new error handling API represents a breaking change. It introduces
`*PROPAGATE-ERRORS*` with the default value of `T`, which means that OpenAL operations which would
previously fail silently will now signal `AL-ERROR` in case of an error. This is a better default,
but will break well-written code using the old API that expects to do its own error checking using
`GET-ERROR`. To restore the old behaviour, set `*PROPAGATE-ERRORS*` to `NIL**.

**NOTE:** `AL:GET-ERROR`/`AL:CLEAR-ERROR` are distinct from `ALUT:GET-ERROR`/`ALUT:CLEAR-ERROR`,
because the error handling in ALUT differs from error handling in OpenAL/ALC. Similarly, the
condition reported for OpenAL/ALC errors is `AL-ERROR`, whereas for ALUT it's `ALUT-ERROR`. In
previous versions, these symbols were accidentally merged. Code relying on the old behaviour will
need to be updated (or converted to use automatic error checking, see below).

By default, cl-openal will call `alGetError()`/`alutGetError` after every C operation and signal any
errors via the `AL-ERROR`/`ALUT-ERROR` conditions. The specific error code be retrieved via
`(AL:ERRCODE CONDITION)`.

Previous versions of cl-openal did not have any provision for automatic error detection, and only
provided `GET-ERROR` as a very thin wrapper around `alGetError()`. This not only requires user code to
do its own error check after every operation, which is tedious and error-prone, but makes some
operations inherently unsafe, as certain wrappers perform foreign memory accesses immediately after
calling the underlying OpenAL functions, without any opportunity for the user to check for errors
and abort. This means memory corruption is highly likely in those instances. This issue has been
fixed, and even if `*PROPAGATE-ERRORS*` is `NIL`, all wrappers exported by packages `AL`, `ALC` and
`ALUT` will now abort if any underlying C operations signals an error. In this case, the wrapper
function will return `NIL`.

If for some reason you need to use one of the low-level bindings in the `%AL` or `%ALC` packages,
the macro `AL:DEFUN-AL` should be use instead of regular `DEFUN`. It automates clearing the error
state at the beginning of the function, and the checking at the end, and exposes a local macro
called `CHECKPOINT`, which should be inserted after every low-level operation, if it's not the last
operation in the function definition. It will also ensure that `*PROPAGATE-ERRORS*` is respected.

If you need to interact with the low-level bindings in `%ALUT`, a similar macro called `DEFUN-ALUT`
is provided. It also automates error clearing and handling, but because the ALUT error reporting is
different, it's simpler to use: there's no need to call `(CHECKPOINT)`, all CFFI calls are checked
automatically.

Thread safety
-------------

Unfortunately, the OpenAL specification is incomplete when it comes to thread safety. Although
OpenAL contexts are specified to be thread safe, and a single OpenAL operation is atomic, the
specification does not specify enough details to allow safe sharing of contexts between multiple
threads. In particular, error handling through `alGetError()` is inherently not thread-safe, and if
multiple threads perform operations on a single context simultaneously, they will have no way to
tell whose operation caused the error being reported.

cl-openal on its part is also not thread-safe in its error handling. If `*PROPAGATE-ERRORS*` is
`NIL`, the mechanism uses the value of a special variable to store and report errors. Because
special variable bindings are not visible across threads, retrieving the last error *will* break if
done from multiple threads.

For these reasons, **multiple threads should never access a single OpenAL context at the same
time. Doing so is inherently unsafe and cannot be done without introducing race conditions.**

Support
-------

If you have any questions, you may contact me at <kzm@sykosomatic.org>. Patches or similar
always welcome!

Extra Notes
-----------

The OpenAL Programming Guide says that buffers can not be destroyed while they are queued. Sources,
on the other hand, can be destroyed while buffers are queued on them.

For this reason it's probably a good idea to do:

    (with-buffers ...
      (with-sources ...
        (queueing code)))

instead of

    (with-sources ...
      (with-buffers ...
        (queueing code)))

Same goes for WITH-SOURCES which you want to wrap in WITH-CONTEXT.


cl-openal

Upstream URL

Author

Maintainer

License

cl-alc

Version:

License:

Authors:

Maintainers:

Dependencies:

cl-alut

Version:

License:

Authors:

Maintainers:

Dependencies:

cl-openal

Version:

License:

Authors:

Maintainers:

Dependencies:

cl-openal-examples

Dependencies:

Dependencies (2)

Dependents (1)