Javadoc change request for more clarity [glDrawElements]

[darkyellow]

Hi

To prevent others making the same mistake id did, I am going to request some clarity to be added the javadoc for glDrawElements

glDrawElements
public static void glDrawElements(int mode,
                                  int count,
                                  int type,
                                  long indices)
Reference Page

Constructs a sequence of geometric primitives by successively transferring elements for count vertices to the GL. The ith element transferred by DrawElements will be taken from element indices[i] (if no element array buffer is bound), or from the element whose index is stored in the currently bound element array buffer at offset indices + i. I have posted the java doc for the function in question below.
Parameters:
mode - the kind of primitives being constructed. One of:
POINTS	LINE_STRIP	LINE_LOOP	LINES	POLYGON	TRIANGLE_STRIP	TRIANGLE_FAN
TRIANGLES	QUAD_STRIP	QUADS	LINES_ADJACENCY	LINE_STRIP_ADJACENCY	TRIANGLES_ADJACENCY	TRIANGLE_STRIP_ADJACENCY
PATCHES
count - the number of vertices to transfer to the GL
type - indicates the type of index values in indices. One of:
UNSIGNED_BYTE	UNSIGNED_SHORT	UNSIGNED_INT
indices - the index values

]

The confusion here is the long indicies value.

Firstly, it is not the index values. The index values are stored in the ELEMENT ARRAY_BUFFER as there is no way to pass one in this call.

Secondly the indicies value is the offset in to the ELEMENT_ARRAY_BUFFER, but this is the byte offset and not the offset of the number of elements in the array. I'll explain more with the below example

ELEMENT_ARRAY_BUFFER = {0,1,2,3,4,5}

Lets say I want to draw use the first three to draw a triangle

GL11.glDrawElements(GL11.GL_TRIANGLES,3,GL11.GL_UNSIGNED_SHORT,0)

This works fine, now lets say I want to draw the second triangle (using indexes 3,4,5), I would need to do this

GL11.glDrawElements(GL11.GL_TRIANGLES,3,GL11.GL_UNSIGNED_SHORT,6)

Note even though I wanted the 3rd element I had to put a 6 here because everyone of the 3 elements is a short which is 2 bytes long.

[Kai]

LWJGL's binding of the OpenGL's glDrawElements function, and in particular this overload, is as direct as possible.
It directly reflects the underlying native OpenGL function with its parameters.

The problem is that OpenGL functions are horribly overloaded.
In the case of glDrawElements, the 'indices' parameter is being interpreted differently depending on the value of the GL_ELEMENT_ARRAY_BUFFER binding.
If it is 0 (i.e. no element array buffer is bound) then the 'indices' parameter is actually the client-side native memory address of the indices array, which you could provide yourself if you wanted to.

When the GL_ELEMENT_ARRAY_BUFFER binding is not 0 (i.e. an element array buffer is bound), then it is the offset in basic machine units into the server-side buffer object.

The problem in the documentation in the part:

...or from the element whose index is stored in the currently bound element array buffer at offset indices + i.

may now be that the documentation does not state the actual unit of the offset value. You assumed that it was the element index (regardless of the underlying primitive/word size) and that was the confusion. But the documentation does not say that.
Instead, the documentation should do as most OpenGL documentations do, by mentioning "basic machine unit" as the unit.

[darkyellow]

You are spot on in what i was trying to say. But basic machine unit is not a helpful term in my mind, byte array offset is better