LWJGL3 Starter Kit

[TheOnlySilverClaw]

Goal

The boilerplate code that is written in most LWJGL3-applications should be put in a separate repository, so new users have a base to start with. They could pull the repository, import the code into their favorite tool, run it and see a simple example, like a triangle. Or even a textured cube that can be rotated.

Motivation

First of all, I know, LWJGL3 is supposed to be lightweight and low-level and all, and people can try to find a higher level framework/engine. But some people, like me, would actually love to use it, while not being experts in OpenGL right from the start. With the help of some tutorials and hours of trying around, I finally managed to get a quad on the screen, but I do not see why everyone has to go through that frustrating process. One mistake, like picking the wrong one out of a few dozen GL_SOMETHING constants or methods can cost hours of debugging, because there is no exception thrown and all you can see is a blank screen.

Also, I know it helps to understand the basics, but I usually learn much better from reading code. So, why not just give new users some working code to start with? If they do not like it, let them change it. If they do not need the training wheels, let them use the bare bones LWJGL3 as usual. This suggestion is meant for the noobs like me, who are willing to learn, but would like to see some progress before going through 20 pages of tutorial, creating a window, writing a shader, creating a program, creating a mesh, etc.

How to do it?

Technically, most of the suggested things already exist in the demo suite, SilverTigers's tutorials, the glorious lwjglbook and a lot of other places. So, maybe pick the best and most used parts, arrange them to work as a minimal "cube in the void" scene, put those into an official repository and ensure that it's still working as intended after every update. I would volunteer to do it, but as mentioned, I'm still a beginner myself.

[httpdigest]

I think your post touches two things, which I'd like to address separately.

1. Project scaffolding/setup
   This can certainly be done for different IDEs and build systems and be put into a GitHub repository.
   Like you mentioned, the lwjgl3-demos repository does this with Maven, but people may use Gradle or wish to have a readily usable IntelliJ, Eclipse or NetBeans project.
   Providing this should not be a problem.
2. Simple examples/demos
   It is hard to know in advance what people would like to learn about OpenGL to make a sufficiently simple demo that addresses this aspect. Like you mentioned, the lwjgl3-demos tries to contain single-file demos addressing various aspects. And I promise you that these demos will always be kept in sync with the most recent LWJGL version. Maybe you could tell what you'd have liked to be in there?

Another aspect which I read between the lines is: Learning OpenGL.
Yes, learning OpenGL is hard. It is a very complex industry standard API that takes years to learn and alot of practice/experimenting. I think that, as much as all the nice tutorials/books/videos/... try to ease this learning process, the amount that has to be learnt is still the same and it is indeed hard.

Regarding what demo to pick: With the complexity and versatility of OpenGL comes the fact that different people want to learn different things, based on what they want to achieve or already know.

In my opinion, the only point that can be addressed successfully is providing scaffolding/setup, so that people at least don't have to fight with their IDEs anymore. :)

[TheOnlySilverClaw]

It is hard to know in advance what people would like to learn about OpenGL to make a sufficiently simple demo that addresses this aspect. Like you mentioned, the lwjgl3-demos tries to contain single-file demos addressing various aspects. And I promise you that these demos will always be kept in sync with the most recent LWJGL version. Maybe you could tell what you'd have liked to be in there?

I know what you mean and I fully agree, there will be no "one fits all solution", but I think that's not necessary. JMonkeyEngine used a colored cube as the initial setup and i think that's a good place to start. It should just bring people to the point where they can try around with stuff, like change the cube colors, make two cubes, rotate one of them, etc. That's how I would have wanted to start learning, instead of spending the first few hours going through crash reports and looking at empty screens. And from that point on, I would be much more eager to experiment knowing that I could always start with a fresh copy when I would mess everything up.

I would love to know what other people would consider a good starting setup, but for me it would basically be what I would have after working through the first half of the lwjglwook:

Basic classes for

• Window
• ShaderProgram(, Shader)
• Mesh
• Camera
  and some very basic shaders, maybe one for color and for 2dtexture.

Aaaand yeah, optionally package the whole thing with a good build script. I did not find the setup that complicated, but adding the native dependencies might help some people. Also, I would not mind putting a dependency on JOML into the Starter Kit, since that's probably the first thing I install anyway. ;)

[httpdigest]

I'd like to also throw JOML's demo repository in here. It contains some "camera" demos, such as the FirstPersonCameraDemo where you can walk around or the ShaderExample with a rotating cube.

[SilverTiger]

Another thing to consider would be the OpenGL version.
Some people may want boilercode for Legacy OpenGL like 1.5 or 2.1 and others do just want core OpenGL 3.2+ or 4.5. This could be done by creating different branches.

But I like the idea and it shouldn't be too complex to create some boilercode with some basic classes and a default vertex and fragment shader.

[httpdigest]

I agree. Also in order to fully implement #100 the way I envision it, we would need some small start project packed alongside the packaged modules/dependencies to get people going.
Again I'd like to refer to how Spring Initializr does it, which provides a working (very small) demo program which can be started right away. That demo program however does not depend on the actually selected modules/dependencies.
We could do better and provide a starter example for a few of the most frequently used module combinations, such as OpenGL + GLFW + stb.

[TheOnlySilverClaw]

The JOML stuff looks neat, such a shame I did not find that earlier...

I was assuming LWJGL3 was not really intended to be used with Legacy OpenGL anyway. I would at least not make the Starter Kit support using Legacy stuff. But maybe that's just my impression.
And yes, having something like and Initializr for LWJGL3 would be pretty great.

Looking at the labels...I would love to contribute, I'm just not really sure how. I suspect with my current knowledge about most of the stuff involved, I would break more than help. :/

[JuKu]

@TheOnlySilverClaw Maybe this project can be interesting for you:
https://github.com/JuKu/java-2drenderer-prototyp

In Release 0.0.4 pre-alpha you have an working triangle example.
Link to release: https://github.com/JuKu/java-2drenderer-prototyp/releases

[TheOnlySilverClaw]

@JuKu I skimmed over it and I'm not entirely sure what it is supposed to be. Looks like a small game engine?
Anyway, I already played around with 2D shapes. It's the 3D projection and all where things got tricky. I will continue to play around with LWJGL after my bachelor's thesis again, maybe if I figure something out, I'll contribute an Example for rendering a simple cube.
I think the most important thing would be to make it minimalistic, but also extensible, so when someone starts using LWJGL, they can start by changing the color, size, rotation, etc. of the cube and when they got the hang of it, throw that away and start tinkering.

[JuKu]

@TheOnlySilverClaw It should be an little game engine prototype, but its Work in Progress.
But you can use release 0.0.4 pre-alpha for an working example with an little abstraction.

What do you want?
More abstraction to draw polygons / meshs easier, so also people without OpenGL skills can use LWJGL?

[httpdigest]

In my opinion, the goal should not be to provide people with whole render or game engines. Neither should the goal be to teach people OpenGL/OpenAL/Vulkan/.... There are better resources for this.
In my opinion, the most important thing a starter kit should offer is to show the design decisions and concepts of LWJGL 3:

• direct NIO buffers as out-parameters
• memory management with BufferUtils/MemoryStack/MemoryUtil
• how to use structs
• callbacks

We should focus on getting people to understand the design decisions made by LWJGL 3 so that they can feel comfortable using the various libraries without being surprised by unknown constructs/concepts.

[TheOnlySilverClaw]

What do you want?
More abstraction to draw polygons / meshs easier, so also people without OpenGL skills can use LWJGL?

I think it should be as little as possible, but show what Kai mentioned.
When you use JMonkeyEngine, you usually start looking at this.
Just a blue cube. The starter kind could show how cube coordinates are put into a buffer, sent through a simple shader and maybe have a callback to move the screen around.
I don't even know what structs are in LWJGL, but maybe that can be worked into that, too?

[JuKu]

@TheOnlySilverClaw But as @httpdigest said, LWJGL isnt an game engine.
There are some differents.

jMonkeyEngine ist an 3D game engine, based on LWJGL and other tools. There are many abstraction, so you dont need to use OpenGL anymore, only for extensions.
LWJGL ist also an Gaming Library, but its goal isnt to add more abstraction to OpenGL.
Its gool is to give all the tools together in one library, so that Java Developer can use this tools, like the OpenGL pipeline with all its native calls very easy.
So i dont know if its an good idea to build an example for an game engine, for what LWJGL isnt builded.

If you want to know, how you can draw an triangle (an rectangle is only 2x triangle), take a look of this classes on my project:
GPUTriangle.java: https://github.com/JuKu/java-2drenderer-prototyp/blob/master/prototyp-game-engine/src/main/java/com/jukusoft/renderer2d/prototyp/engine/mesh/data/GPUTriangle.java
Triangle: https://github.com/JuKu/java-2drenderer-prototyp/blob/master/prototyp-game-engine/src/main/java/com/jukusoft/renderer2d/prototyp/engine/mesh/data/Triangle.java

In my project i have added more abstraction, so class Triangle holds data of triangle (coordinates of all 3 edges and color) and class GPUTriangle contains the specific OpenGL calls for this, so i want to add support for other graphic pipelines without changing your program code.
So the prototyp can maybe support DirectX, Vulkan and also OpenGL.
But its an higher abstraction level than LWJGL.

[TheOnlySilverClaw]

For the second or third time... I know how to create a triangle. I also know that LWJGL is not a game engine. I'm just saying it would make sense to have a clean example to show how the work-flow for rendering something would be and rendering a cube would be a good starting point for a lot of users. That assumption might be biased, but it's usually one of the examples all OpenGL tutorials go through, too.

From my experience, OpenGL is intimidating, because you spend a lot of time going through boilerplate code before see any visible result and you cannot use System.out.println or anything inside of shaders to figure out why it does not work. Giving a good starting point would probably help a lot of users.
And yes, I know there are also other backends like Vulkan, but is anyone actually using that to start with graphics programming? Honest question, I know I'm not the expert here.

[Spasi]

We never got around to implementing this request, but many years have passed and there are plenty of resources available now for people getting started with LWJGL3. Even the projects mentioned in the original post (lwjgl3-demos and lwjglbook) are still active and rich with content.