I'm trying to understand why it appears that the JOAL API does not seem to match the OpenAL API (in the same way, for example, that one expects the JOGL API to match the OpenGL API). I freely admit this could be due to my misunderstanding something, or looking at the wrong version, or something else (in which case I'd appreciate a gentle correction), but here's an example of what I'm talking about.
The OpenAL 1.1 Programmers Giude (http://developer.creative.com/articles/article.asp?cat=1&sbcat=31&top=38&aid=51&file=OpenAL_Programmers_Guide.pdf
) updated December 2006 specifies (page 15) just one form of alGenBuffers():
void alGenBuffers(ALsizei n,ALuint *buffers);
The JOAL 1.1b03 API (Sep 5, 2006; the latest, as far as I know) specifies two
forms of method alGenBuffers():
alGenBuffers(int n, IntBuffer buffers)
alGenBuffers(int n, int buffers, int buffers_offset)
On it's face, this would seem to at least indicate that JOAL is not precisely just an interface directly into OpenAL, but rather that someone has decided to "do it better" (?).
Further, there is no
documentation in the JOAL API JavaDoc explaining what the second form of alGenBuffers() does (i.e., what that third parameter represents (yes, I could guess a bit from the parameter name, but that's pretty weak documentation if that's the intent, and anyway every guess I make leaves me with at least a couple of questions).
methods contain the same
comment as to what they do:
Entry point (through function pointer) to C language function:
void alGenBuffers(ALsizei n, ALuint * buffers);
leaving even more confusion (and fewer clues) as to how the JOAL API actually works.
I've used alGenBuffers() as an example; there are many other routines with the same ambiguities.
I am teaching classes in game design and am trying to make the argument that JOAL is a solid alternative to other choices. However, things like this, which make it difficult for me
to figure things out and therefore darn near impossible for my students, make it difficult to continue considering JOAL as a viable alternative. Can someone help -- either in pointing out my error(s), providing the missing explanation of what the API really intends to say/do, or (best case) improve the API so that it is either consistent with OpenAL or else has JavaDoc that clearly explains the differences?