LWJGL 3 - Function postfixes

[spasi]

Hi all,

Historically, LWJGL has always stripped unnecessary postfixes from native functions. For example, the native function:

void glUniformMatrix4fv (GLint location, GLsizei count, GLboolean transpose, const GLfloat *value)

has the 'fv' postfix. It's there because C doesn't support function overloading and we'd like to overload the last argument (value) with different types. In this case, it's an array (pointer) to floats and 'fv' means "float vector" or "array of floats". This native function is mapped to the following two Java methods (in both LWJGL 2.x and 3):

void glUniformMatrix4f(int location, int count, boolean transpose, ByteBuffer value)
void glUniformMatrix4(int location, boolean transpose, FloatBuffer value)

Since Java does support function overloading, we don't need the postfixes. A NIO buffer automatically means "arrays of values" and a FloatBuffer in the second case means "array of floats". So, this is nice from a Java perspective, so why does this poll exist? A couple of reasons:

- New users or users experienced in the native API are often confused. They try to compile some code that uses the original function names and cannot understand why compilation fails. This can be a bad first experience with LWJGL, which is critical for adoption of the library. They would have to go through the FAQ to figure it out and we all know no one reads documentation.
- Modern IDEs. Is there anyone that manually types OpenGL functions? And if you do, are a couple of extra characters really a problem?

The drawbacks would be:

- Extra work when porting LWJGL 2.x code to 3.
- No overloading obviously, changing the argument type means also changing the function name.

[Kai]

Hello Spasi,

I am all in favor of the suffixes!

Usually, my approach to typing a GL function, I don't know yet the version or specifics of, is like the following:
- Google the name of it without the gl prefix and any suffix
- this usually leads to the sdk site on OpenGL.org or khronos
- See what that function really does and what the parameter and return type means
- See in which version it was introduced
- go to the IDE and static import that class
- write the function without suffix and have a look at the auto-suggestions

And this is where suffixes would come in handy, because it is at times difficult to differentiate between the overloads that are artificially introduced by LWJGL because of conveniences, and the suffixed function "overloads" of the GL API itself.

So, I would appreciate those official GL API suffixes.

[Cornix]

I dont see why we cant have both. The methods without the postfix would simply call the methods with the postfix and both worlds would be happy, those who like to switch out parameters as needed without needing to change the method name, and those who like to be precise with what function they call.
But if we have to choose one or the other I would be for keeping the postfix as its closer to the native API.

[spasi]

I dont see why we cant have both.

This is technically possible, but has two negatives:

- Increased JAR size. (minor)
- Massive, improperly sorted, auto-complete lists in your IDE. This will be quite confusing imho. (major)

[Neoptolemus]

I agree that going the way of suffixes and sacrificing the overloaded methods is a pretty minor inconvenience really, compared to the portential inconvenience of people coming from the C library and finding that the methods have different naming conventions.

Also don't forget that the majority of tutorials out there are written in C++, so it would bring LWJGL more in line with the vast range of tutorials out there.

As far as the move from LWJGL 2.x to 3.x goes, there will already be some rework due to the deprecation of the maths library and the Display static methods, so an extra few function names (which would be easy to find and fix using any half decent IDE) is hardly a massive inconvenience.

Overall I'd say go for it and make the LWJGL GL methods reflect the C library more precisely, as the inconveniences to existing LWJGL users would be less than the convenience for new users.

[spasi]

What about the single value versions LWJGL generates? Strip or keep? For example:

void glGetIntegerv(int pname, IntBuffer params)
int glGetIntegerv(int pname) // keep

vs

void glGetIntegerv(int pname, IntBuffer params)
int glGetInteger(int pname) // strip

I think I'm in favor of the second option. The single value versions are non-standard anyway and we don't break existing code that much.

[iamcreasy]

Hello I am new here, and I am just starting with LWJGL 3.

I am in favor of postfixes(single character and multi character) resembling native functions, the only reason is because the vast amount of already existing documentations out there. You can ask anyone(or google) who knows opengl and they will know what exactly you are asking - wheres if those are removed, I 'somehow' need to figure out the original name is, and as a beginner I don't know how long it's going to take - and depending on the user it could take somewhere between 5 minute to 5 days.