Getting Started with OpenGL in Java

This page provide information useful for getting your workspace ready to work on computer graphics and computer animation assignments. The lab machines already have the necessary software installed, but if you are using your own machine then you may need to install some software.

Java and Eclipse Software

If you are not already using Sun/Oracle Java, or have an older installation, then download and install the latest Java SE JDK (careful not to select the JRE). Note that you may already have "other" Java versions installed on your machine (for instance, Microsoft or GNU Java), but avoid using these as they will very likely lead to problems.

I also strongly recommend using Eclipse as a development environment. If you need to install it, then I suggest downloading the Eclipse IDE for Java Developers because it is slightly smaller. If you have multiple versions of java installed, you will want to make sure that you are using the appropriate JDK (see Window->Preferences, Java, Installed JREs) and have the compiler compliance level is set to at least 1.6 (see Window->Preferences, Java, Compiler).

Using Eclipse

Eclipse uses a workspace to organize your projects. When you start eclipse for the first time, it will make you a workspace in some default location (probably your home directory), but you can switch workspaces with the file menu, and open any folder you want for your workspace. One nice way to organize this would be to create a workspaceComp557 folder in your home directory, then tell eclipse to open that workspace.

Once your workspace is open, add a new java project, give it a name, such as A0, A1, etc. The defaults for the project when you click next are probably fine, e.g., default JRE, separate folders for source and class files. Once it is created, you will see a src folder for the source files and bin for the class files. Note that you may eventually create additional folders for data.

Lastly a few tips on using eclipse to help you browse provided code. If you let your mouse hover over an identifier, variable or method, a window will pop up telling you what it is, and providing you with the javadoc. If you hold ctrl and click on an identifier, it will take you to its definition (e.g., the implementation of a method). This is a great way to explore code rapidly! Note the yellow forward and back buttons on the tool bar are useful for going back to where you were after control clicking an identifier.

Provided Code

Download the provided code and dump it into a new java project. Note that the code lives in the comp557.a0 package. Please do not change the package name for any of your assignments. This example code contains a minimal example framework with which you can try out the OpenGL API, and may be of use during the tutorials.

You'll want to put the provided code (see below) in src folder of your new project, and there are lots of ways to do this. Most importantly, you need the directory structure to match the package structure! An easy way is to copy the directory provided in the zip file and paste it into the src directory. Since everything lives in the package comp557 you need this folder (i.e., you can't just copy and paste the a0 folder into src). If you copy files into your project on the file system side, you'll need to tell Eclipse to refresh its view of the project (right click on the project and select refresh). This summarizes the steps for "dumping the source code into a project". You'll have lots of errors at this point, but they all go away when you attach the jars as specified in the assignment.

Libraries

The provided code uses JOGL for OpenGL bindings. JOGL has been around for many years and has changed over the years to keep up to date with the evolving OpenGL specification. The latest version involves "profiles" to allow for applications to be developed for different versions of OpenGL and different hardware (e.g., OpenGL ES 2.0, as you would use for an Android or iOS device). Grab the latest release version from jogamp.org. In version 2.0 of JOGL, installation has become slightly simpler with respect to the native libraries. See local installation information, and download the 7zip file. Unzip the archive somewhere convenient. You will want to include jogl-all.jar and gluegen-rt.jar in your build path, and likewise attach the provided source code for your own convenience (e.g., jogl-src.zip). Because you will need to do this for each assignment, you will want to set this up as a user library.

You may find the following links useful for documentation on OpenGL:

JOGL User Library

You will be using several jars in each assignment, and to save time in setting up dependancies it will be useful to create a user defined library that groups together the necessary jars. Create a user library called JOGL2 and add to it jogl.all.jar and jlugen-rt.jar. You will want to set the source code attachment and native library location. As we will also be regularly using vecmath.jar and mintools.jar you can add these too once they are provided.

Right click on your project, select settings, and choose Java Build Path, and click on the Libraries tab. When you click Add Library, select User Library and click next, choose User Libraries, and click New. Give it the name JOGL2. Now add the jars to your library, set the source path, and if necessary native library paths. Once finished, you can select the user library you created for inclusion.

JOGL2.0 Idiosyncrasies

As mentioned previously, different profiles are available, e.g., GL2, GL3. You will notice in the provided code that we are pretty much exclusively using GL2.

OpenGL functions that have parameters that take pointers or arrays as argiments in C are mapped to Java an a way that facilitates code porting, but may look mysterious at first. For instance, a glVertex call that accepts an array of doubles, in JOGL, has the method signature glVertex3dv(double[] v, int v_offset). We typically provide 0 for the offset. Alternatively we can use native IO buffers.

DebugGL is your friend! It will call glGetError for you and throw exceptions. Notice how the provided code sets the GL2 to be a DebugGL2.