LWJGL 3 - API Freeze (request for feedback)

[arcnor]

+1 on Java convention here (also, hi )

[Kai]

I have but one additional request: Can we please make the auto-generated classes not final?
The reason is that one can then extend those classes and provide additional and/or cross-cutting concerns to certain methods of those classes by extending the classes and hiding specific methods.
And since the methods are all static anyway, making the class final will also not have any performance benefit (the methods are linked against statically at the callsite and everything is known about the method invocation at compiletime).
When extending a GLxx class and hiding some methods, the client/user can then just swap the static import from GLxx to `MyGLxx` and the Java compiler would use the "nearest" hidden method version and everything would still compile.
When the GLxx class is final, one can of course still build a MyGLxx but would then be forced to fully selectively import the corresponding methods and cannot use static import anymore, because of ambiguous methods when importing both GLxx and MyGLxx.

[spasi]

Nightly build 3.0.0b #42 is up. Changes:

- GLFW structs have been renamed.
- Struct and binding classes are now not final. Binding classes now include a default constructor, which enables "static extension" as per Kai's request, but it should never be called (throws immediately).
- Added bindings to xxhash.

[kappa]

Just a tiny nitpick, the 'Configuration' class name seems pretty long , could something smaller like 'Config' work better?

Another possible simplification/idea, the Sys class is now a lot slimmer in LWJGL3 (compared to LWJGL2), rather than have users access another class for configurations, could the enum variables not just be inside Sys? e.g. Sys.LIBRARY_PATH.set("libs");

[spasi]

Yes, it could be done. The reason I added a new class and put it in the system package is that I wasn't really sure of the design. I also consider most of the settings "advanced", they won't be of interest to most users. Finally, remember that I have reserved the system package for breaking changes, everything* in there is subject to change between releases.

* except MemoryUtil, which I consider extremely useful and will try to keep stable.

[kappa]

Only reason I mentioned the Sys class was it might be nice to have a single point of getting and setting all LWJGL library related information.

However good point about keeping the system package breakable, another variation could be:

import static org.lwjgl.system.Configuration.*;
...

Sys.set(LIBRARY_PATH, "libs");

and

String libPath = Sys.get(LIBRARY_PATH);

With Config/Configuration then just being a data storage class which could change when needed.

[Kai]

I would keep the Configuration class with a fixed API, and let it act as a facade for all the configuration aspects, where most of that functionality may or may not be implemented by the Sys class, which may of course change.

[spasi]

Sorry for the delayed response, had a very busy couple of days.

import static org.lwjgl.system.Configuration.*;
...

Sys.set(LIBRARY_PATH, "libs");

and

String libPath = Sys.get(LIBRARY_PATH);

With Config/Configuration then just being a data storage class which could change when needed.

I see two separate issues with the current solution:

- Configuration is a big name to type and looks ugly I guess.
- The user needs to go into org.lwjgl.system to discover it.

The above fixes the first, but not the second. Also, in the presence of a Configuration static import, why not do:

import static org.lwjgl.system.Configuration.*;
...

LIBRARY_PATH.set("libs");

and

String libPath = LIBRARY_PATH.get();

Why involve Sys?

I would keep the Configuration class with a fixed API, and let it act as a facade for all the configuration aspects, where most of that functionality may or may not be implemented by the Sys class, which may of course change.

Could you give a code example please? I'm not sure I understand what you mean exactly.

[Kai]

I would keep the Configuration class with a fixed API, and let it act as a facade for all the configuration aspects, where most of that functionality may or may not be implemented by the Sys class, which may of course change.

Could you give a code example please? I'm not sure I understand what you mean exactly.

Sure. What I meant was just that having a Configuration class (and I personally would call it Configuration instead of Config, I don't like abbreviations) with a stable API is a good thing, whereas the functionality provided by that Configuration class could as well be implemented by means of the Sys class, to avoid code duplication or something like that.
So we would have a small class Configuration, which could have various methods to configure things, but the actual doing of that configuration in the background inside LWJGL can be implemented by Sys.
By "facade" I just meant exactly this: The Configuration class can provide an interface whereas its functionality can be spread over many other internal classes (such as Sys) by means of delegation, but the user would not need to know.

[abcdef]

This isn't really feedback on changes to be made but feedback on the changes being made.

I'm still on the previous stable build, I have read many threads about some of the core changes being made and classes that have been changed / moved / removed etc. Lots of good change, but tracking all the changes is difficult. What would be good, once the API freeze occurs, is to either have a summary of all the changes made or having the getting started page demonstrate everything (it might be large if it had everything so maybe there needs to be a simple and extended example)

Just an idea, I have lost track of all the changes so it would be good to see everything in one place explained.

[Kai]

Did you look at the demo package in the LWJGL3 repository? Those cover every aspect of the API (GLFW, registering the GL context in LWJGL, registering callbacks for GLFW, OpenGL, OpenCL, OpenAL, ...).
I also try my very best to keep the lwjgl3-demos repository up to date with the very latest changes in LWJGL3.
However, those latter demos only make more use of OpenGL functions. They do not make use of new aspects of LWJGL that aren't already shown in the demos package of LWJGL3.

[abcdef]

I have seen them yes, I used them when I first migrated over to LWJGL3. It would be just useful to see a summary of all the changes listed out in one place.

[spasi]

Hi all,

It's been a bit over two weeks that I moved to a new home and I'm still on mobile internet, they haven't transferred my VDSL connection yet. Oh the joys of living in Greece...

Anyway, I used this time to work on some implementation details and settle some long-pending issues that were compromising the library's robustness. Especially worth mentioning is the fix for starting GLFW without -XstartOnFirstThread on OS X, we get an informative exception now. It was really unfortunate that most users' first experience with LWJGL was a nasty JVM crash.

On Configuration, I'm still not convinced it should be taken out of org.lwjgl.system. This is something we can do in a post 3.0 release, when the design and implementation details have settled.

On the other hand, I've been thinking about kappa's point that the Sys class doesn't do anything useful. I don't like its name, Sys, when there's also an org.lwjgl.system package. I also don't like LWJGLUtil as a name. This is what I think should be done:

- Combine the Sys and LWJGLUtil classes.
- The new class should have a new, nicer name. I haven't thought of anything, need suggestions please.
- Move some of LWJGLUtil's functionality that's only used internally (log, getClassTokens) into the org.lwjgl.system package somewhere.

What do you think?

[spasi]

It would be just useful to see a summary of all the changes listed out in one place.

Hey abcdef,

I'll try to post some details in a blog post when 3.0b is released. The site will also be updated with a page that lists all releases and associated release notes. The release notes will probably also be reflected on Github. I haven't bothered with anything like that so far because the library has been going through extensive changes.

[Kai]

Just one note about the Sys class. It mostly seems to be used for build-version querying.
I would move that functionality to a Configure/Configuration/Config class, in the style of GNU Autotools/Autoconf config.h also storing version and defines for detected features. That's the best I can come up with regarding lending a known concept/name from somewhere else people could be comfortable/familiar with.