Using NVIDIA Nsight with Java/JOGL

As advertised, the Nsight graphics debugger requires Visual Studio C++. However, it turns out to work perfectly fine with Java/JOGL. You can still examine your shaders at runtime - such as seeing the current contents of your shader's uniform variables - and you can even see the C calls being made by your JOGL-wrapped program.

Nsight is only available if you have an NVIDIA graphics card. It won't work with an Intel or AMD graphics card.

Setting up Nsight for JOGL is surprisingly easy! Here are the steps:

1. If you haven't already done so, install Visual Studio, such as Visual Studio 2017 Community. Be sure to include the C++ core compiler. (Note: VS install is notoriously slow!). VS 2017 Community is available here.

2. Install NVIDIA Nsight, the Visual Studio Edition. This should be quick and easy -- much easier than installing VS. The CUDA elements aren't necessary (unless you want them for other reasons). Nsight is available here.

3. Run Visual Studio, and make sure the Nsight menu appears at the top on the menu bar.

4. Under the File menu, choose "New Project". A large selection box appears. On the left pane, click on "Visual C++" (so that it highlights), then in the center box, choose "Windows Console Application". Then in the lower right, click "OK". After a few seconds, a short C++ program main should appear.

   NOTE -- we are NOT going to enter our Java source code into Visual Studio. Instead, we are going to run our already-compiled Java/JOGL program as an "external application", as shown in the following remaining steps:

5. In the right pane (called "Solution Explorer"), the second line immediately under "Solution 'Console Application'" should show the name of the project, which is probably something like "ConsoleApplication1". Right click on that project name - a large menu should appear. Near the bottom is "Nsight User Properties". Click on that, as shown here:

   

6. The "Launch Action" pane should appear. There are THREE thing that need to be changed on this pane.
   First, click the button to select "Launch external program:"
   The box to the right of that probably contains something like "$(LocalDebuggerCommand)"
   Change that entry to instead contain the path to the Java SDK executable. On my Windows machine, that is:
   

   C:\Program Files\Java\jdk1.8.0_101\bin\java.exe

   Second, further down on the same pane, under "Launch Options", there is a line that says "Command line arguments:". In the box to the right of that, replace whatever is there with the command line arguments needed to run your Java/JOGL application. Each argument must be in its own set of quotations!! For example, if you usually run your program with a command such as:
   

   java -Dsun.java2d.d3d=false code.Code

   then the entry in the argument box would need to be:
   

   "-Dsun.java2d.d3d=false" "code.Code"

   Note the sets of double quotes around EACH parameter, separately!

   Third, further down on the same pane is a line that says "Working directory:". In the box to the right of that, replace whatever is there with the path to the directory from which you would execute the command to run your program (i.e., the call to "java" shown immediately above). For example, something like:
   

   C:\Users\gordonvs\Documents\myGraphicsPrograms\2_4_cubes

   Note the box to the right of "Connection name:" probably says "localhost". Don't change that, leave that entry as it is.

   Here is an example screenshot showing all three changes:

   

7. Click "OK" in the lower right. The NVIDIA Nsight User Settings box should close.

8. Under the File menu, save the project.

9. Under the "Nsight" menu (along the top menu bar), choose "Start Graphics Debugging", as shown here:

   

10. A window will pop up asking if you want to "connect without security?". Click on "Connect unsecurely". This should cause your external Java/JOGL graphics program to execute. You should see both a terminal window, and your running program, appear. Nsight may superimpose some information over your running program. Here is an example:

    

11. Once your program is running, navigate in your program to whatever area you wish to examine, then from the Nsight menu, select "Pause and Capture Frame", as shown here:

    

12. The Frame debugger screen should appear, along with the HUD toolbar and scrubber. Your program will likely freeze at this point. In the center of the debugger screen is a left bar with buttons for each shader stage. For example, you can highlight "VS" for "vertex shader", and in the larger center box to its right, you can scroll down and look at the contents of the uniform variables (presuming you have "API inspector" selected above it). Here is an example:

    

13. Another interesting window that appears is one that looks similar to your running program. This window has a timeline along the bottom, which allows you to click and see the sequence of items drawn on the frame. Here is an example - note the cursor has been clicked on the left area of the timeline, and it shows those items that have been drawn up to that point:

    

Let me know if my instructions (above) are missing any steps, or if there are any corrections needed, or if they would benefit from any other helpful hints.