JOGL Tutorial 1 - Environment Setup

Date: March 5, 2011

Downloads & Installation

To begin, you need to get the tools that enable you to program in Java and utilize OpenGL. There are three main downloads you will need for these tutorials:

1. JDK (Java Development Kit)

This is the set of programs and libraries that allow you to write Java code. You can download the JDK from here.

By downloading the JDK you also get a JRE (Java Runtime Environment), which is the collection of libraries required to actually run Java programs. At the time of writing, I am using JDK 6 Update 21 (Java 1.6.0_21) for Linux 64-bit. Follow the installation instructions provided to get the JDK set up for your platform.

2. JOGL (Java Bindings for OpenGL)

JOGL provides access to the OpenGL graphics API, enabling hardware-accelerated graphics with Java. JOGL is currently maintained by JogAmp. You can download the most recent signed release of JOGL from here (more info on build versions). You will want to get the file in the format "jogl-2.0-b<version>-<date>-<platform>.7z". The platform indicates amd64 for 64-bit architectures and i586 for 32-bit architectures.

For example (as of March 5, 2011), the most recent files by platform are:

Linux 64-bit: jogl-2.0-b23-20110303-linux-amd64.7z

Linux 32-bit: jogl-2.0-b23-20110303-linux-i586.7z

Windows 64-bit: jogl-2.0-b23-20110303-windows-amd64.7z

Windows 32-bit: jogl-2.0-b23-20110303-windows-i586.7z

Mac OS X: jogl-2.0-b23-20110303-macosx-universal.7z

The libraries used to be in .zip files, but are now in 7-zip format. You may need to download a utility to extract these files.

Note: Do not be confused by "amd64" if you have a 64-bit Intel processor, as it refers to the instruction set and not the manufacturer of your CPU.

You can extract these files to your JDK / JRE installation, but I don't recommend it for portability reasons. It's important to remember that these files are needed by any computer that wants to run a JOGL application. I typically create a lib directory somewhere in my home and extract all my libraries there. For instance, "/home/justin/lib/jogl-2.0" in Linux or 'C:\lib\jogl-2.0" in Windows. There are two important directories for writing applications:

jar/ - contains all of the Java bytecode (.class files) for JOGL grouped into .JAR files.

lib/ - contains the native libraries (.so for Linux / OS X, .dll for Windows) for your platform.

3. Eclipse IDE

An integrated development environment (IDE) allows you to more efficiently write Java programs. This isn't strictly necessary, and you may choose to use another IDE, but this guide will focus on Eclipse. Download the Eclipse IDE for Java Developers here.

After you download Eclipse, you do not need to install it. Simply open the directory you extracted the files to and run eclipse.

Setup Eclipse

At this point, you're ready to configure Eclipse to make Java applications that utilize the JOGL library. There are a few ways to do this, but I'm going to recommend the one that is most convenient if you decide to create multiple Java projects inside Eclipse. Start Eclipse by navigating to the directory you extracted it and starting "eclipse" (Linux) or "eclipse.exe" (Windows).

Eclipse will ask you to select a Workspace, which is the directory that contains your projects as well as your preferences and settings for Eclipse. Enter a directory you can remember and it will create it for you.

Creating Project Source Folder

First we create a project that will contain the source code for each program. This project will go into your workspace directory.

Click "File > New > Java Project"
In the "Project name" field, enter "Tutorials" (or something else if you prefer) and leave the other options alone unless you want to change the JRE being used.
Click "Finish"
You should see "Package Explorer" on the left side of Eclipse, which contains the Tutorials project. You can expand it by clicking the button to the left of the project folder.

Creating JOGL User Library

To use JOGL, it's necessary for your project to reference it. The JOGL library consists of a number of JAR files and native libraries, but it's preferable to refer to this collection as a whole rather than each file separately. To do this, create a "user library" that lists all of the required files.

In the top Eclipse menu bar, click "Window > Preferences"
The left side of the preferences frame should show a list of options. Make sure you have "Java > Build Path > User Libraries" selected.
Click "New..." and type a name for your library, such as "jogl-2.0". Leave the "System library (added to the boot class path)" checkbox unchecked and click "OK".

Back in the "User Libraries" panel, you should see your library appear. Click "Add JARs..." and navigate to the location where you extracted your JOGL library.
Open the jar/ directory, which contains all the various JAR files and native libraries for JOGL. Select the following JARs: gluegen-rt.jar, jogl.all.jar, nativewindow.all.jar, newt.all.jar
Click OK to add these four JARs to your user library. You should see them listed under "jogl-2.0" now.

Expand each JAR by clicking the button to its left. This should show you four properties for each JAR:

Source attachment is where you would link the JAR with the source code (.java files) corresponding to its .class files. This would let you view the source code of the library inside the IDE when looking through classes from the library.
Javadoc location refers to the HTML Javadoc files that provide programmers with information about the methods, classes, interfaces, and other elements of code inside the JAR. If you download the Javadoc for JOGL, you can see the documentation inside Eclipse.
Native library location indicates where platform specific libraries are located. Native libraries may be needed by the code inside a JAR files to work.
Access rules allow you to restrict usage of some code in a JAR file, which we don't care about here.

For now, you only need to be concerned with the native library location for each JAR in the jogl-2.0 user library. For each JAR:

Click "Native library location" and then "Edit..." on the right.
Select "External Folder..." and navigate to the lib/ directory. The path you enter should be the directory containing .so or .dll files.
Click "OK".

Linking JOGL with Project

You're done setting up the JOGL user library, and you should only have to do this once unless you download a newer version of JOGL at some point. Now you simply have to tell your project to use your JOGL user library.

In the package explorer, right click the project folder and select "Properties" at the bottom of the drop-down list.
On the left side of the properties frame, select "Java Build Path" and click the "Libraries" tab at the top.
Click "Add Library...", select "User Library" and click "Next", then put a check mark next to JOGL-2.0 and click "Finish". You should see JOGL-2.0 in the "Libraries" list now, so click "OK" to exit properties.
In the Package Explorer, you'll also see the library is now referenced by the JOGL-Tutorials project. Now you can use the code inside the JOGL library in any Java source code belonging to this project.

Comments