general tips on how to debug lwjgl projects

[sc]

I've been playing with LWJGL for a couple of weeks now, and I've noticed how easy it is to make mistakes + how difficult it is to figure out what went wrong.

So, I would like to ask you (the more experienced devs) how you go about debugging your projects.
For instance, I have a scene with 3 red cubes that works as it should.
I then tried adding some diffuse light, and now the cubes are black. There's no errors. How would you go about fixing this (in general) ?

I think it might be useful for other starters as well, to have a bunch of tips collected here, all in 1 place ...

[spasi]

When you say no errors, do you mean no Java exceptions or no OpenGL errors? I.e. are you checking for OpenGL errors or use a debug context with a debug callback registered?

One simple solution to LWJGL debugging is the LWJGLX/debug agent. It will report most common/obvious bugs.

If the above doesn't help, then you're having a classic "my screen is black" OpenGL situation. I'm afraid this is not at all LWJGL specific and you'd have the same problem in any programming language or OpenGL binding library. It's up to you to go through the OpenGL state to figure out what goes wrong. It could be a wrong matrix transformation or wrong normals on the model, etc. There are some free and commercial OpenGL debugging solutions out there that might help, but I personally haven't used one.

[sc]

No errors in this case means : the project was running fine before I added the diffuse light, and I saw 3 colored cubes on the screen.
After adding the light, the project is still running, and I see my blue background color + some black cubes.

Possible problems that I can come up with (with my limited experience) : light is on the backside of the cubes and I see only 'shadow', OR, something when wrong during the calculations for the light (matrix stuff).
Trying out a different light position and getting the same result, discards the first option.

So ... how do I figure out what I did wrong ?
When you're just writing Java or any other language, you always get help from the ide/compiler and if you don't understand the error msg, you can google it. This is a bit ... different.

The things you mentioned :
* checking for OpenGL errors
* use a debug context with a debug callback registered

... could you please tell me a bit more ? I'm not really sure what you mean.

* LWJGLX/debug agent : I knew about its existence, and I have read the documentation ... but I'm still unsure what exactly it is used for. Is it only to detect errors that you can't see otherwise (because of the app crash) ? And am I right in thinking this is something extra to add to a project (not a replacement for the regular LWJGL jars) ?
I'll try it out, if I can figure out how to set it up in my maven project. 

* go through the OpenGL state to figure out what goes wrong : do you mean 'go over the code line by line' and try to see what's wrong ?
* free and commercial OpenGL debugging solutions : yes, I've installed RenderDoc. I managed to get it running ... but I'm unsure what to do with it next. The documentation talks about setting breakpoints in the shaders, but that doesn't work. Maybe I set it up wrong, or maybe it's only possible for Direct3D ... I don't know.

Waw. This sure is an adventure. 
And thank you for helping !

[spasi]

The LWJGLX/debug agent enables all (debug-level) LWJGL checks, as well as other automated error checking like OpenGL's debug context. It also instruments methods in LWJGL bindings to do additional state validation. There's no reason to not use it when you have trouble, it can immediately eliminate a wide range of issues that you may have.

If you'd like to setup an OpenGL debug context, it's very simple:

// before window creation
glfwWindowHint(GLFW_OPENGL_DEBUG_CONTEXT, GLFW_TRUE);
// after GL.createCapabilities()
debugProc = GLUtil.setupDebugMessageCallback();

With the above, it's like calling glGetError after every single OpenGL function call, plus you may get additional warnings (e.g. for performance).

It's a massive waste of time trying to figure out how your matrices or light positions are wrong, when you're simply getting an OpenGL error somewhere, screwing things up. If there are no errors, then you can proceed with examining your program line-by-line or using something like RenderDoc.

[vesa1995]

...

One simple solution to LWJGL debugging is the LWJGLX/debug agent. It will report most common/obvious bugs.

...

I added this agent, but I am not sure if it works, because I don't see any output in console? Can you tell me if there should be any output when you run app or any other way to check if agent is working?

[KaiHH]

You probably added it as a program argument (argument passed to the `String[] args` array of the `main` method) instead of as a JVM/VM argument.
Depending on how you run your Java application (cmd line, Eclipse, IntelliJ IDEA, NetBeans, ...) there are various ways to effectively specify a JVM/VM argument when the `java`/`javaw` launcher is invoked.
Research the documentation for your particular IDE (if you use any) on how to specify a JVM/VM argument as opposed to a program argument when launching your application.
On the command line you would do it like: `java -javaagent:<path-to-the-agent-jar> -jar yourApp.jar <any-program-arguments>`

[vesa1995]

You probably added it as a program argument (argument passed to the `String[] args` array of the `main` method) instead of as a JVM/VM argument.
Depending on how you run your Java application (cmd line, Eclipse, IntelliJ IDEA, NetBeans, ...) there are various ways to effectively specify a JVM/VM argument when the `java`/`javaw` launcher is invoked.
Research the documentation for your particular IDE (if you use any) on how to specify a JVM/VM argument as opposed to a program argument when launching your application.
On the command line you would do it like: `java -javaagent:<path-to-the-agent-jar> -jar yourApp.jar <any-program-arguments>`

thank you, I was using program arguments in IntelliJ, you need to click more options and then you get VM arguemnts................. damn