LWJGL Forum

Please login or register.

Login with username, password and session length

Author Topic: Javadoc change request for more clarity [glDrawElements]  (Read 230 times)

darkyellow

  • Newbie
  • *
  • Offline Offline
  • Posts: 15

Hi

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

Code: [Select]
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

Code: [Select]
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

Code: [Select]
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.

Logged

Kai

  • Nerdus Imperius
  • *****
  • Offline Offline
  • Posts: 900
Re: Javadoc change request for more clarity [glDrawElements]
« Reply #1 on: April 12, 2017, 16:09:36 »

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:
Quote
...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.
Logged

darkyellow

  • Newbie
  • *
  • Offline Offline
  • Posts: 15
Re: Javadoc change request for more clarity [glDrawElements]
« Reply #2 on: April 13, 2017, 16:21:44 »

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
Logged