From chris.kcat at gmail.com  Fri Oct 13 21:10:23 2017
From: chris.kcat at gmail.com (Chris Robinson)
Date: Fri, 13 Oct 2017 18:10:23 -0700
Subject: [openal] Alure updates
Message-ID: <5972abe5-99a1-beb9-fb0a-83dec6d7db5e@gmail.com>

I've been working quite a bit recently on the Alure2 API, which is a 
complete rewrite of the old Alure1 API. I'm looking for feedback -- any 
way it can be improved, anything that's unclear, any glaring omissions, 
as well as any bugs if you try to use it, so that I can start 
considering a release.

https://github.com/kcat/alure

For those unaware, Alure is a library that sits on top of OpenAL and 
provides utility functions to implement common features (e.g. audio file 
reading/decoding) and make common tasks easier (e.g. automatically 
handle the buffer queue for source streaming). The original Alure was 
modeled extremely closely on ALUT, which itself merely added functions 
to help load files into OpenAL buffers. With Alure, I took that idea, 
cleaned up the legacy cruft that had built onto the API, and added more 
features onto it that many applications would find useful.

Ultimately though, I was never happy with the additions. They did what 
they were supposed to do, but I felt a few early design decisions 
created ugliness and baggage in the API. And because I wanted to 
maintain ABI compatibility, I couldn't fix them without breaking it. So 
if I was going to break ABI, I might as well redo everything and rename 
the library (alure2) so it can sit along side the original.

The biggest change from Alure1 is that Alure2 is now a C++ API, where 
Alure1 used C++ internally but exposed a C API. Specifically, it 
requires C++11. It should be possible to make a C wrapper (it uses pImpl 
and virtual class member functions to keep implementation details 
hidden), but I'll worry about that once the C++ API is settled.

The second biggest change is that it manages OpenAL for you, rather than 
the app still using OpenAL calls with OpenAL objects and only using 
Alure as-needed. So rather than an ALCdevice* or ALCcontext*, you deal 
with alure::Device and alure::Context. And rather than integer IDs for 
sources, buffers, etc, you have type-safe alure::Source and 
alure::Buffer objects, all of which providing appropriate member functions.

Because of that object management, it's also able to maintain a buffer 
cache so you can retrieve the same buffer multiple times by name without 
loading it multiple times (until you uncache it, then getting it again 
will reload it), and sources can be prioritized. The latter point means 
you can create as many alure::Source objects as you want and specify how 
important each one is, but an OpenAL source ID is only taken when it 
needs to play. When a Source plays and no more OpenAL sources are 
available, it'll preempt the lowest-priority Source if it's lower- or 
equal-priority to the Source trying to play, and take its internal 
source ID.

There's quite a bit more available, but that's a good overview of the 
big things. A number of examples are available showing it in action:

https://github.com/kcat/alure/tree/master/examples

And the header documents most of the public API:

https://github.com/kcat/alure/blob/master/include/AL/alure2.h

If there's any questions, feel free to ask. I still have things I want 
and need to work on, but it's at a point where feedback would be helpful.

Thanks for looking!