Getting up and running with JOGL JOGL is Sun's open sourced OpenGL binding for Java. It is actively supported by many developers with Sun's newly established Java Gaming Group. With JOGL it is possible to finally be able to create (API supported) OpenGL games in Java. The only credible competing API is the LWJGL (Lightweight Java Game Library) which strives to be the Java gaming equivalent of DirectX.

Both libraries utilize a hefty amount of native code, but where LWJGL seeks to be a complete gaming solution - the Sun APIs (JOGL, JOAL, and JInput) allow you to mix and match what you need to create your solution. In addition, JOGL integrates cleanly with AWT and Swing components whereas LWJGL creates its own native window - defying any attempts to integrate it with a Java application.

This article deals specifically with getting JOGL installed on your machine and getting it to render a single cheesy triangle. As you will shortly discover, this takes little effort (unless you are unfamiliar with the OpenGL APIs). The first step required is to obtain the binaries that you will need in order to compile and run your applications. These pre-compiled binaries can be obtained from the project website file sharing area Project Files. Download the binaries for your platform (currently there are binaries available for OSX (Panther DP or greater), Linux, Solaris, and Windows. This pretty much covers all of the major platforms so I doubt you'll find yourself trying to compile the library yourself.

Now that you have the binaries you will note that you hava a .jar file and a JNI library (.dll, .so, .jnilib). You will need to install the jogl.jar file in the classpath of your build environment in order to be able to compile an application with JOGL. Since many people these days are using IDEs like Eclipse, JBuilder, and IntelliJ - it is fairly straightforward to add the .jar file to your build. Follow the instructions for your specific build environment.

Next comes the slightly trickier part, the installation of the native library. You won't need this in order to compile your application, but you will need it in order to run your application. Java developers usually don't find themselves installing native libraries (for obvious reasons) so it usually escapes us as to how its done. Java loads native libraries from the directories listed in the java.library.path environment variable. Best to just print this out and put the native library into one of these directories. One of these directories is likely to be the extension (ext) directory of the JRE for your IDE. Unless you only want to run the application from inside the IDE, don't install it here.

You can confirm this by creating a test program that does System.loadLibrary("jogl");. If the application throws an UnsatisfiedLinkException, the JRE running your application cannot find the native library. This isn't too likely if you've installed it in one of the directories listed in java.library.path, but just in case - try again

Now that you have JOGL installed, you want to feed cool L33t geometry to your video card and have it do cool stuff. Well at the moment I want to feed myself so I tell you about that. Coming up next - actually understanding the API enough to be able to get something on the screen!

Note here that I am creating a frame and giving that frame a size. Since at the moment I don't plan to have any extra stuff in that frame other than the rendered component this is fine and I won't worry about a layoutmanager.

The next thing you need is a warm piece of GLCanvas to draw on. Since you cannot directly instantiate GLCanvas (which is good OO design) you must obtain it from the factory that creates them. This is GLDrawableFactory. We will tell this factory that we want it to create and return to us a GLCanvas with a default set of capabilities.

The capabilities that you want a GLCanvas to have are specified in GLCapabilities. So if you want something with specific buffers, bitdepths, etc, you would create a GLCapabilities() object that has those capabilities and pass that into the factory as so:

There is a lot of stuff you can do with GLCapabilities but I'm not going to cover that here - explore and experiment.

Now that you have your GLCanvas done you need to add it to the Frame so that people will be able to see it.

1

testFrame.add( canvas );

So now you have a GLCanvas on a Frame and when that frame comes up it will do.... nothing The reason it won't do anything is because of the architecture of JOGL. JOGL will emit a series of events that will tell you what's going on with the framework so that you can listen for those events and do the right thing. JOGL refers to this as a GLEventListener. The GLEventListener contains the methods that we're most interested in: init(), display(), reshape(), and displayChanged().

When the GLCanvas (which is a GLDrawable) is rendered for the first time, init(GLDrawable) is called. In this method you would do the same thing you would do in an init call to your old OpenGL engines. Set up any initial settings and get yourself ready to draw. If you aren't following the JOGL architecture properly, you may be able to hack some drawing into this method but DO NOT do this. You will make your life harder later. Load textures, geometry, etc here, but don't start trying to render anything in this method.

When a GLDrawable is told to render, this method is called. Note that this is a good way to decouple the rendering interface from any sort of frame rate limiter or timing system. Anyways, THIS is the method where you want to do your drawing.

There has been some question as to whether or not one should reacquire gl in the display method. I have as of yet found it unnecessary to do this and I'm not sure why its recommended as the GLDrawable should not be destroyed at any point during rendering and as such should be cacheable as should GL and GLU.

The next method of interest is reshape(). Just like with GLUT, reshape is called when your context changes shape. Its useful to make camera adjustments and the like when this occurs in this method. Since I currently don't support these operations this method is undefined:

So now you have the code for what I refer to at the TestRenderer, but you can call it whatever you want so long as it implements GLEventListener.

Now that you have a GLEventListener lo and behold you application renders... nothing still The reason is again in the JOGL architecture. Recall that the display method needs to be called before anything gets drawn to the screen. Well - you don't have anything calling display(). You COULD throw in a while loop that spun forever calling display(), but there is really a better way. JOGL includes the concept of an Animator. This animator basically holds the tempo of when display gets called. Personally I think RenderLoop might have been a better name, but hey you can extend it and call it whatever you want right

To make a long story short you need to add an Animator so that display is getting called. For this tutorial I will use the one provided for by JOGL, though one that handles frame rates properly is likely going to make a LOT more sense for anything running in a Window. No sense having JOGL running in a window yet taking up so much CPU that nothing else can really run either. The last chunk of code that you need is

There you have it. Go ahead and compile/run and you will have one cheesy triangle. The world is now yours to control because if you can draw one triangle, you can draw millions of triangles in 3D space with textures and stuff and have a real game. At this point you might want to take a look at some OpenGL resources as it won't matter whether or not you're coding in C++ or Java as OpenGL is OpenGL and it will be simple to tell what needs to be syntactically changed to work with JOGL (or LWJGL for that matter).