Hello JOGL

Introducing Java Bindings for OpenGL

For some years now, a programmer that wanted to create a graphics-intensive program that could be sold to users of different operating systems had one choice—OpenGL. The GL stands for graphics library. OpenGL is a registered trademark of SGI. OpenGL manifests itself as a cross platform C programming API. In reality though, it is a hardware-independent specification for a programming interface.

OpenGL is for making graphics. It is fast. Most of the time, it is hardware accelerated. It seems that OpenGL can do anything visually that you would want to do.

Unfortunately, OpenGL is written for C. Let's face it, C is not the most popular language for programming complex applications. One of the biggest drawbacks to OpenGL is that you can't make it do anything without a window to put your graphics in, but OpenGL doesn't provide a means for you to create windows. This makes OpenGL hard to learn for beginners.

Luckily, GLUT (OpenGL Utility Toolkit) was introduced and made dealing with windows, buttons, and events generated by users easier. Still, learning OpenGL in C or even C++ can be painful for new programmers or programmers that want to use true object-oriented programming.

Then came JOGL

Java is possibly the most popular true object-oriented programming language. There have been many attempts to marry OpenGL with Java, but the first one that made everyone stand up and take notice was Java Bindings for OpenGL, or JOGL. The reason for this is that this effort is supported by Sun Microsystems (the creators of Java) and SGI (the creators of OpenGL).

Nowadays, JOGL is developed by the game technology group at Sun. It started out life as Jungle developed by Ken Russel and Chris Kline. Russell is a Sun employee working on the HotSpot Virtual Machine with many years of 3D experience. Kline works for Irrational Games and also is very experienced with 3D graphics.

I am personally grateful for their efforts and the efforts of all those who are working on JOGL. There have been several attempts at providing access to OpenGL through a friendly Java API—among these have been Java 3D, OpenGL for Java Technology (gl4java), and Lightweight Java Game Library (LWJGL). JOGL is the first that I felt comfortable with.

JOGL is the Sun supported set of Java class bindings for OpenGL. Wow! That was a mouthful.

OpenGL is used to display 3D models. It is powerful, fast, and perhaps the greatest thing to happen to Java since Swing was introduced. Using OpenGL through JOGL, you will be able to make cool games or model situations that could be too expensive to create. Thick tomes have been written describing OpenGL. They will be useful once you know your way around, but not yet. You need to learn how this all applies to the Java APIs that expose OpenGL to you. You also need some basic introductions to net.java.games.jogl.* and perhaps some refreshers on math.


If you want to use JOGL, you will need to get jogl.jar and its accompanying native code. I dream of the day it is standard with the Java installation, but for now that is just a well placed dream.

The first trick is finding the binaries for your OS and extracting them. I found them at https://games-binaries.dev.java.net/build/index.html. Every OS is different, but there are two parts to installing. The jogl.jar must be placed in the system classpath, and the binary library must be placed wherever libraries go in your OS. If you're lucky, you will have an installer to do it for you. If you don't have an installer and don't know where to look for information on placing everything on your computer, you can start with the links I've provided in Resources. Our first code example will be written specifically to test whether you've installed everything correctly, so you don't need to stress about testing your installation until then.

Javadocs for JOGL

The Javadocs may be obtained at the same location as the binary distribution of JOGL. The Javadocs will be named something similar to jogl-1.0-usrdoc.tar.

If you browse the net.java.games.jogl package, you'll quickly notice that some of the classes are huge. GL is a perfect example of this. Don't be put off by this. You'll find out quickly that you're able to do some pretty sophisticated work even with just a small amount of JOGL knowledge. The classes you might want to glance at now are:

  • GLDrawable
  • GLCanvas
  • GLJPanel
  • GLCapabilities
  • GLDrawableFactory

These will be your basic interface into the world of graphics. If you remember, earlier I mentioned that one of the greatest drawbacks for beginners learning OpenGL is the lack of a windowing system standard. GLUT helps a long way in that regard for our C counterparts, but we have Swing and the AWT (Abstract Window Toolkit). It's very likely you have already used AWT or Swing, so you are not going to feel like you are learning everything from scratch. This is a good thing. After a very brief introduction to getting a component for JOGL up on the screen, we won't need much work to have you running pretty cool and hip apps!

GlueGen ... almost as cool as JOGL?

As you should be aware, OpenGL is written for C programmers. This means that for Java to take advantage of it, there has to be some native interface. This means JNI (Java Native Interface), which isn't fun or pretty, must be written to make this connection. OpenGL is pretty big. Writing all those connections takes time. To make things just a little more difficult, there are plenty of vendor-specific features and OpenGL keeps improving, which means there are changes to keep up with. In short, it has been pretty hard for the "anyone" trying to keep up with OpenGL to write a Java to native interface that is all encompassing.

Enter the JOGL folks. They decided to take advantage of the C header files and write some code that would do all the JNI work for them. They called it GlueGen. GlueGen parses the C header files and then magically creates the needed Java and JNI code necessary to connect to those native libraries. This means that updates to OpenGL can be added quickly to JOGL.

Hello World!

I'm a firm believer in tradition, so of course we will start with a "Hello World." This Hello World will examine our installation and tell us whether all or part is installed correctly. Remember there are two parts to the JOGL installation. There is the Java library in a jar file and the native code in another library.

Here is our program:


import net.java.games.jogl.*;

public class HelloWorld { public static void main (String args[]) { try { System.loadLibrary("jogl"); System.out.println( "Hello World! (The native libraries are installed.)" ); GLCapabilities caps = new GLCapabilities(); System.out.println( "Hello JOGL! (The jar appears to be available.)" ); } catch (Exception e) { System.out.println(e); } } }

First, this program tests to see if the native and Java libraries are installed correctly. JOGL is installed properly only when the jogl.jar and the native library, named something like libjogl.jnilib or jogl.dll, are both installed. If the native library is not accessible, this program will throw a java.lang.UnsatisfiedLinkError exception. If the JAR is not installed in the classpath, then the program will not even compile. The javac compiler will say something similar to "package net.java.games.jogl does not exist." When this class compiles and runs without exceptions, you are ready to continue learning JOGL.

A good template

Let's move on to a couple of classes that you may find useful to use as a template while messing around with JOGL. I've used them as templates more than once. Feel free to use them however you like.

This template is made up of two classes. The first is SimpleJoglApp shown below, and the second is SimpleGLEventListener shown after a brief description. You will need to type both in to compile the template. The main app:


import java.awt.*; import java.awt.event.*; import javax.swing.*; import net.java.games.jogl.*;

/** * This is a basic JOGL app. Feel free to * reuse this code or modify it. */ public class SimpleJoglApp extends JFrame { public static void main(String[] args) { final SimpleJoglApp app = new SimpleJoglApp();

// show what we've done SwingUtilities.invokeLater ( new Runnable() { public void run() { app.setVisible(true); } } ); }

public SimpleJoglApp() { //set the JFrame title super("Simple JOGL Application");

//kill the process when the JFrame is closed setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);

//only three JOGL lines of code ... and here they are GLCapabilities glcaps = new GLCapabilities(); GLCanvas glcanvas = GLDrawableFactory.getFactory().createGLCanvas(glcaps); glcanvas.addGLEventListener(new SimpleGLEventListener());

//add the GLCanvas just like we would any Component getContentPane().add(glcanvas, BorderLayout.CENTER); setSize(500, 300);

//center the JFrame on the screen centerWindow(this); }

public void centerWindow(Component frame) { Dimension screenSize = Toolkit.getDefaultToolkit().getScreenSize(); Dimension frameSize = frame.getSize();

if (frameSize.width > screenSize.width ) frameSize.width = screenSize.width; if (frameSize.height > screenSize.height) frameSize.height = screenSize.height;

frame.setLocation ( (screenSize.width - frameSize.width ) >> 1, (screenSize.height - frameSize.height) >> 1 ); } }

That is it. Let's focus on the three lines of JOGL-specific code in this first class. To start:

 GLCapabilities glcaps = new GLCapabilities();

This determines what OpenGL/graphics features are available to our JOGL libraries and the JVM.


 GLCanvas glcanvas =

We cannot create GLCanvases or GLJPanels. We need to have them created for us by a GLDrawableFactory. So, we retrieve a GLDrawableFactory using GLDrawableFactory's static method, getFactory().

Now we have a GLDrawableFactory, so we use its createGLCanvas() method to create a GLCanvas to draw on. We could have used the createGLJPanel() method instead if we had wanted a Swing component instead of an AWT component.

Notice that we passed in the GLCapabilities object we created earlier. This allows the GLDrawable we're having created to be created properly.

Finally, we are ready to add a GLEventListener to the GLCanvas:

 glcanvas.addGLEventListener(new SimpleGLEventListener());

Our implementation of GLEventListener is SimpleGLEventListener. It will take care of any drawing that needs to be done when it receives a call from the GLDrawable and our one and only GLCanvas. As you will see, I decided not to draw anything in this program. Now for the GLEventListener:


import java.awt.*; import java.awt.event.*; import net.java.games.jogl.*;

/** * For our purposes only two of the * GLEventListeners matter. Those would * be init() and display(). */ public class SimpleGLEventListener implements GLEventListener {

/** * Take care of initialization here. */ public void init(GLDrawable drawable) {


/** * Take care of drawing here. */ public void display(GLDrawable drawable) {


/** * Called when the GLDrawable (GLCanvas * or GLJPanel) has changed in size. We * won't need this, but you may eventually * need it -- just not yet. */ public void reshape( GLDrawable drawable, int x, int y, int width, int height ) {}

/** * If the display depth is changed while the * program is running this method is called. * Nowadays this doesn't happen much, unless * a programmer has his program do it. */ public void displayChanged( GLDrawable drawable, boolean modeChanged, boolean deviceChanged ) {} }

That is the heart of the JOGL work we will do. Notice the UML graphic below. SimpleJoglApp is a JFrame. It contains our GLDrawable, which is actually a GLCanvas, but don't tell him that. We add the SimpleGLEventListener, which implements GLEventListener to the GLCanvas so the GLCanvas knows we care if he wants any OpenGL work done. GLDrawables can talk your ear off, so you'll want to make sure your GLEventListener is optimized…for real.

This app may look a bit scrambled depending on your OS. This is to be expected because you are just displaying random bits of memory at this point. So congratulations on your new-found graphics talents.

You're ready for the real thing

After you've familiarized yourself with the previous example, make a pretty picture.

Here is your next app. Make sure you type this and all examples in. Debugging and messing around with them will serve to quickly teach you how they work.

1 2 Page 1
Page 1 of 2