How to: Getting started with JOGL

gregorypierce · July 12, 2003, 2:39pm

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!

gregorypierce · July 12, 2003, 3:15pm

Okay, no food that doesn’t require cooking so I will press forward and cover as much as I can until I pass out from starvation

You will build your JOGL application much the same as you build any other AWT application (for now):


            Frame testFrame = new Frame("TestFrame");
            testFrame.setSize( 512, 384 );

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.


            GLCanvas canvas = GLDrawableFactory.getFactory().createGLCanvas( new GLCapabilities() );

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:


            GLCapabilities glCaps = new GLCapabilities();
            glCaps.setRedBits(8);
            glCaps.setBlueBits(8);
            glCaps.setGreenBits(8);
            glCaps.setAlphaBits(8);
            
            GLCanvas canvas = GLDrawableFactory.getFactory().createGLCanvas( glCaps );

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.


            testFrame.add( canvas );

So now you have a GLCanvas on a Frame and when that frame comes up it will do… nothing ;D 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.


    public void init(GLDrawable drawable)
    {
        this.gl = drawable.getGL();
        this.glDrawable = drawable;

        drawable.setGL( new DebugGL(drawable.getGL() ));

        System.out.println("Init GL is " + gl.getClass().getName());
    }

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.


    public void display(GLDrawable drawable)
    {
        gl.glClear(GL.GL_COLOR_BUFFER_BIT | GL.GL_DEPTH_BUFFER_BIT );
        gl.glLoadIdentity();

        gl.glColor3f(1.0f, 0.0f, 0.0f );

        gl.glBegin( GL.GL_TRIANGLES );
            gl.glVertex3f( 0.0f, 0.0f, 0.0f );
            gl.glVertex3f( 1.0f, 0.0f, 0.0f );
            gl.glVertex3f( 1.0f, 1.0f, 0.0f );
        gl.glEnd();
    }

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:


    public void reshape(GLDrawable drawable, int x, int y, int width, int height)
    {
    }

The same can be said of display changed. If the device or display mode changes, JOGL will let you know so you can handle your rendering accordingly.


    public void displayChanged(GLDrawable drawable, boolean modeChanged, boolean deviceChanged)
    {
    }

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 ;D 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


            final Animator animator = new Animator(canvas);
            testFrame.addWindowListener(new WindowAdapter() {
                public void windowClosing(WindowEvent e) {
                  animator.stop();
                  System.exit(0);
                }
              });
            testFrame.show();
            animator.start();

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).

gregorypierce · July 12, 2003, 3:27pm

Test.java


import net.java.games.jogl.*;

import java.awt.*;
import java.awt.event.WindowAdapter;
import java.awt.event.WindowEvent;

public class Test
{
    public static void main( String[] args )
    {
        try
        {
            Frame testFrame = new Frame("TestFrame");
            testFrame.setSize( 512, 384 );

            GLCapabilities glCaps = new GLCapabilities();
            glCaps.setRedBits(8);
            glCaps.setBlueBits(8);
            glCaps.setGreenBits(8);
            glCaps.setAlphaBits(8);

            GLCanvas canvas = GLDrawableFactory.getFactory().createGLCanvas( glCaps );

            testFrame.add( canvas );

            canvas.addGLEventListener(new TestRenderer());

            final Animator animator = new Animator( canvas);
            testFrame.addWindowListener(new WindowAdapter() {
                public void windowClosing(WindowEvent e) {
                  animator.stop();
                  System.exit(0);
                }
              });
            testFrame.show();
            animator.start();
        }
        catch( Exception e )
        {
            e.printStackTrace();
        }
    }
}

TestRenderer.java


import net.java.games.jogl.GLEventListener;
import net.java.games.jogl.GL;
import net.java.games.jogl.GLDrawable;
import net.java.games.jogl.DebugGL;


public class TestRenderer implements GLEventListener
{
    private GL              gl;
    private GLDrawable      glDrawable;

    public void init(GLDrawable drawable)
    {
        this.gl = drawable.getGL();
        this.glDrawable = drawable;

        drawable.setGL( new DebugGL(drawable.getGL() ));

        System.out.println("Init GL is " + gl.getClass().getName());
    }

    public void display(GLDrawable drawable)
    {
        gl.glClear(GL.GL_COLOR_BUFFER_BIT | GL.GL_DEPTH_BUFFER_BIT );
        gl.glLoadIdentity();

        gl.glColor3f(1.0f, 0.0f, 0.0f );

        gl.glBegin( GL.GL_TRIANGLES );
            gl.glVertex3f( 0.0f, 0.0f, 0.0f );
            gl.glVertex3f( 1.0f, 0.0f, 0.0f );
            gl.glVertex3f( 1.0f, 1.0f, 0.0f );
        gl.glEnd();
    }

    public void reshape(GLDrawable drawable, int x, int y, int width, int height)
    {
    }

    public void displayChanged(GLDrawable drawable, boolean modeChanged, boolean deviceChanged)
    {
    }

}

DavidYazel · July 12, 2003, 6:47pm

Thank you, that was a nice introduction!

swpalmer · July 13, 2003, 12:28am

Yes, thanks! That was excellent. Perhaps it should be placed in the Wiki so that when this thread is long lost this info is still easy to find.

system · July 13, 2003, 4:43am

A very nice introduction. Simple and robust; so it should be with Java all day.

kbr · July 14, 2003, 9:26am

Thanks for writing this introduction. Do you have it in HTML form? Let’s check it in under the doc/ subdirectory of the jogl project.

gregorypierce · July 14, 2003, 3:07pm

Not yet, but I’ll convert it into an HTML form and email it to you. I’m going to continue on by adding some stuff on getting a textured triangle since there is some VERY understandable weirdness and confusion about loading textures and doing some basic input (not using JInput until I get finished with learning Cocoa to handle input for OSX).

Markus_Persson · July 23, 2003, 5:25pm

Has anyone gotten this to run on linux?

I was trying to figure out why Wurm was having trouble on linux, so got rid of everything but the example here and uploaded it.
The Guy™ who’s running linux (I’m not) gets this:

net.java.games.jogl.GLException: Error making context current at net.java.games.jogl.impl.x11.X11GLContext.makeCurrent(X11GLContext.java:141) at net.java.games.jogl.impl.x11.X11OnscreenGLContext.makeCurrent(X11OnscreenGLContext.java:111) at net.java.games.jogl.impl.GLContext.invokeGL(GLContext.java:162) at net.java.games.jogl.GLCanvas.displayImpl(GLCanvas.java:196) at net.java.games.jogl.GLCanvas.display(GLCanvas.java:91) at net.java.games.jogl.Animator$1.run(Animator.java:104) at java.lang.Thread.run(Thread.java:536)

gregorypierce · July 23, 2003, 7:06pm

I’ll fire up RedHat 9 tonight and see what i can find in terms of running general applications. I haven’t had any problems with Linux in the past so it would be surprising to find something now.

nlmueng · July 23, 2003, 8:37pm

You need to change the GLCapabilities part. If you just switch it to say new GLCapabilities() instead of creating a defined one it works fine. I think it has something to do with being 32 bit.

Nathan

AndersDahlberg · July 23, 2003, 8:49pm

I’m “the guy™” ;D

Strange thing is, the jogl demos works fine (i.e. gears)!

AndersDahlberg · July 23, 2003, 8:55pm


You need to change the GLCapabilities part.  If you just switch it to say new GLCapabilities() instead of creating a defined one it works fine.  I think it has something to do with being 32 bit.

That actually makes sense, that it tries to switch bpp. That was my first thought

http://www.java-gaming.org/cgi-bin/JGNetForums/YaBB.cgi?board=Announcements;action=display;message=10;thread=1058284789

Maybe that’s not the problem though?

And if it is - could the error message include some more information (i.e. “couldn’t switch to 32bpp”?)

gregorypierce · July 23, 2003, 11:03pm

I am able to on RedHat 9 using the latest NVidia drivers on a GeForce 4200 able to get that GLCapabilities() to work. Not sure why yours wouldn’t. You should have enough video memory for that to work unless you’re requesting an incredibly large GLContext, or potentially something that’s non-square’d, though that’s rarely an issue these days.

nlmueng · July 23, 2003, 11:37pm

it fails on my box too if I leave it that way. When I just did it like new GLCapabilities() it works.

I only have the 810 onboard video in the box.

nathan

Markus_Persson · July 24, 2003, 11:10am

[quote]I’m “the guy™” ;D
[/quote]
Actually, you’re not. The other Guy™ I talked about in the wurm thread started getting the same error as you did…

Anyway, I’ll try this. Thanks, all. =D

AndersDahlberg · July 24, 2003, 11:34am

sob I’m not the guy™ sob :-[

Well, I guess I’ll get over it some day in the distant future ;D

Markus_Persson · July 24, 2003, 11:35am

You can be The Man™, if you want to. ;D

Now go test if wurm works for you.

AndersDahlberg · July 24, 2003, 1:08pm

muahahaha :)


Java Web Start 1.4.2 Konsol, startades Thu Jul 24 17:04:59 CEST 2003
Java 2 Runtime Environment: Version 1.4.2 av Sun Microsystems Inc.
Loggar till filen: /home/anders/log.txt
net.java.games.jogl.GLException: Error making context current
        at net.java.games.jogl.impl.x11.X11GLContext.makeCurrent(X11GLContext.java:141)
        at net.java.games.jogl.impl.x11.X11OnscreenGLContext.makeCurrent(X11OnscreenGLContext.java:111)
        at net.java.games.jogl.impl.GLContext.invokeGL(GLContext.java:162)
        at net.java.games.jogl.GLCanvas.displayImpl(GLCanvas.java:196)
        at net.java.games.jogl.GLCanvas.display(GLCanvas.java:91)
        at com.wurmonline.client.WurmClient$4.run(WurmClient.java:565)
        at java.awt.event.InvocationEvent.dispatch(Unknown Source)
        at java.awt.EventQueue.dispatchEvent(Unknown Source)
        at java.awt.EventDispatchThread.pumpOneEventForHierarchy(Unknown Source)        at java.awt.EventDispatchThread.pumpEventsForHierarchy(Unknown Source)
        at java.awt.EventDispatchThread.pumpEvents(Unknown Source)
        at java.awt.EventDispatchThread.pumpEvents(Unknown Source)
        at java.awt.EventDispatchThread.run(Unknown Source)

Markus_Persson · July 24, 2003, 1:14pm

So now it works for the Guy™, but not the Man™.

Excuse me, I’ll go kill myself now…