COMP 557 - Fall 2009 - Assignment 0
Getting Started with OpenGL in Java

This is not a real assignment, but instead is intended as means to help you get set up for doing the assignments and the beginning of term OpenGL tutorials. 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 a very old 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. If you have multiple versions of java installed, you'll also 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 1.6 (see Window->Preferences, Java, Compiler). If you are familiar with Eclipse, you can probably skip the rest of this section.

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. 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 when you're browsing the 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).  We will use the previous version to avoid profiles, and also because builds of the libraries are available for a large variety of platforms at jogl.dev.java.net. Go to the release build page JSR-231 1.1.1a and download the appropriate files for your platform. For instance, if on windows, download

  • jogl-1.1.1a-windows-i586.zip
  • jogl-1.1.1a-src.zip (to have access to javadoc in Eclipse)
  • jogl-1.1.1a-docs.zip (if you prefer reading javadoc in your browser)

To make your life more pleasant in Eclipse, you want to attach the source code to the jar for the javadoc. First add the jar to your build path, then open up Reference Libraries in your project, right click on the jar to set properties, go to source code attachment, and tell it where to find the zip file. Note that the .dll (or .so) that comes with the jar must be in your path. You can do this by opening the reference libraries in your project, right clicking to select properties, choose Native Library and enter the location of the .dll or .so file.  You can also do this by adding the folder containing the shared library to your path.

To complete most assignments you will likely need to use the vecmath jar for working with matrices, points, and vectors. The vecmath package is available as part of JAVA3D, but instead of installing the full Java3D, you can download just the vecmath.jar locally. The source code (i.e., the javadoc) is in the jar, so if it isn't automatically attached, you'll want to repeat the process above and attach the jar as source. You might also want to browse the vecmath javadoc online.

You may find the following links useful for documentation on OpenGL: The OpenGL Programming Guide (The Red Book) online version (or at Amazon), Jumping into JOGL, JOGL: A Beginner's Guide and Tutorial. Another popular resource is nehe.gamedev.net (see the NeHeGL JOGL link on the bottom right).

WebCT and Submitting Assignments

You do not need to submit anything for assignment zero.  However, if you are new to WebCT, you may wish to test the submission process, and as such there is a test assignment called A0 on WebCT.  Note that you should always check that the system has correctly received your uploaded files by downloading your submission and verifying its contents! You can always "take back your work" before the deadline and resubmit.  Once the deadline has passed, you'll not be able to do this.  Late  assignment submissions are permitted, but can only be made if you have not previously submitted an assignment.  If ever you have problems submitting your work, contact the instructor or one of the TAs.