[Openal-devel] AL headers

[Sven Panne]

Am Samstag, 3. September 2005 23:40 schrieb Garin Hiebert:
> > OpenAL gives new users a feeling of general roughness at the edges and
> > lack of polish.
>
> OK -- polish away...
>
> If in the process of "polishing," the headers stop working with
> Creative's 1.1 implementation (the Windows implementation in CVS) and
> the Creative implementation is the one matching the published spec,
> then I'll bitch about it at that time. [...]

OK, I'll try to summarise the cosmetic problems I still see with al.h and 
alc.h:

Namespace hygiene: al.h should only #define things with an "AL" prefix and 
declare C entities with an "al" prefix, same for ALC, of course. And using 
only entities which are mentioned in the spec would be desirable, too. The 
only exceptions should be the typedefs for the API entry points, which seem 
to have different naming conventions on WinDoze. We get this almost right, 
with 2 glitches: al.h #defines "OPENAL". Why? I propose to simply remove 
this. The other glitch is the definition of the ALCdevice and ALCcontext 
types, as these introduce additional names outside of those from the spec. 
What's even worse, these are *implementation-dependent*, nothing really nice 
for reference headers... :-P Always using

   typedef void ALCdevice;
   typedef void ALCcontext;

looks much better, both types can only appear as opaque pointers in user code. 
(Which is a wart in the spec, IMHO, using an e.g. ALCuint handle would be 
more consistent with AL). Another option might be to always use opaque 
structs

   typedef struct _ALCdevice ALCdevice;
   typedef struct _ALCcontext ALCcontext;

which would be a little bit more type-safe and follow the usual practice of 
using an initial underscore for internal entities. Both ways should be rather 
easy to implement, and I don't really care much about which of those 
alternatives are chosen. But let's at least remove the ugly platform-specific 
#ifdef for this part!

And the other problem I still see is of the use of the variable definitions we 
already talked about.

Can we get a quick reply from Creative/Apple about the two issues mentioned 
above? From an implementation point of view they are trivial and I can change 
the Linux codebase accordingly to whatever we decide.

Apart from that, I'm quite happy now with al.h and alc.h, and I promise that I 
won't cause Garin any more heart attacks... (at least not for the headers ;-)

Cheers,
   S.