JOAL API inconsistent with OpenAL?

Java Sound & OpenAL
#1

Hi,
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)

and

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).

Worse, both 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?

Thx.

#2

Sorry for the confusion and for the lack of javadoc. It is rooted in the fact that the Java programming language does not have pointers, so stylistic constructs have to be adopted.

We documented the mappings from C to Java in the JSR-231 overview documentation which you can find here. I’ve just filed JOAL Issue 14 to track improving the javadoc.

We’re on the verge of releasing new versions of JOAL and JOGL which allow both to be used in applets as well as via Java Web Start. This massively simplifies deployment of Java applications using OpenGL and OpenAL and I think is an exciting development. I hope you’ll agree and will consider using JOAL in your course.

Please also take a look at the joal-demos source code which shows how to use the APIs, and post if you have more questions or comments.

#3

As Ken pointed-out, Java lacks pointers like C/C++, so when you use the array method instead of the buffer one, you have to specify from where in the array you begin (whereas a Buffer object has a variable to where it begins). So if you wanted to start from the beginning of the array, you just have 0 as the 3rd parameter. And as for buffers, remember to rewind() them beforehand.

In essence, both alGenBuffers(…) methods are exactly the same, both as interfaces to the C function alGenBuffers(ALsizei n,ALuint *buffers):

IntBuffer buffer = IntBuffer.allocate(1);
al.alGenBuffers(1, buffer);
int bufferID = buffer.get();

is the same as

int[] buffer = new int[1];
al.alGenBuffers(1, buffer, 0);
int bufferID = buffer[0];

The JOGL API does the same thing where there are methods that can accept either a Buffer, or an array & offset.