Open source Java projects: Java Binding for OpenGL (JOGL)

A low-level Java API for 3D graphics

1 2 3 4 5 6 7 8 9 Page 2
Page 2 of 9

When compiling JOGL source code, you must make jogl.jar available to the compiler. When running JOGL applications, you must make jogl.jar and gluegen-rt.jar available to the application launcher. Furthermore, you need to tell the launcher where to find the native libraries. Accomplish these tasks via the -cp and -Djava.library.path options, respectively:

javac -cp "c:\jogl\jogl.jar" x.java

java -cp "c:\jogl\jogl.jar;c:\jogl\gluegen-rt.jar;." -Djava.library.path="c:\jogl" x

DirectDraw and Windows Vista

According to the Java SE 6 Release Notes, you don't need to specify -Dsun.java2d.noddraw=true on a Vista platform because "the use of DirectDraw for hardware acceleration is currently disabled by default because of incompatibilities with Vista's Desktop Window Manager."

These command lines reveal that jogl.jar is located in the \jogl directory on my C: drive. (I chose to copy lib's files to this location for convenience.) Furthermore, the second command line identifies this directory as the location of JOGL's native libraries. Finally, the command lines specify x as a placeholder for the Java file that contains the application's entry point.

If you're working on a Windows platform and discover program crashes, flickering, and other problems, chances are that OpenGL and the Java2D DirectDraw rendering pipeline are conflicting in some way. To correct this problem, specify the -Dsun.java2d.noddraw=true option in the java command line. This option disables the DirectDraw pipeline.

If you cannot use DirectDraw with OpenGL, you should enable the Java2D OpenGL rendering pipeline so that you still get hardware acceleration while working with JOGL's GLJPanel class (I discuss this class later). You can enable the OpenGL pipeline by specifying the -Dsun.java2d.opengl=true option in the aforementioned java command line.

Verify that the Java2D OpenGL rendering pipeline is active

According to Java 5's New Features in Java2D technology documentation, certain platform-specific minimum requirements must be met before the Java2D OpenGL rendering pipeline will be activated. To determine whether these requirements have been met for your platform, and that this pipeline is active (via a message that's output to the console), specify -Dsun.java2d.noddraw=True instead of -Dsun.java2d.noddraw=true. To find out what rendering operations have been accelerated, specify -Dsun.java2d.trace=log.

A gallery of demos

A variety of demonstration programs, located in the jogl-demos.zip archive, have been created to demonstrate JOGL. Furthermore, jogl-demos-src.zip contains their source code, along with documentation on running these demos. You can download both archives from the same location as the JOGL release build archive.

The jogl-demos.zip archive contains jogl-demos.jar, jogl-demos-util.jar, and jogl-demos-data.jar. You'll need to add jogl-demos.jar and possibly add the other two JAR files to your classpath before running a demo. For example, the command line below (divided across two lines for readability) requires only the first JAR file to run the gears demo on a Windows platform:

java -cp "c:\jogl\jogl.jar;c:\jogl\gluegen-rt.jar;c:\jogldemos\jogl-demos.jar" 
     -Djava.library.path="c:\jogl" demos.gears.Gears

This command line assumes that c:\jogl contains JOGL's jogl.jar and gluegen-rt.jar JAR files, and native libraries. Furthermore, it assumes that the three JAR files for the demos are located in c:\jogldemos. Once you've invoked the command, you should observe the 3D scene that's shown in Figure 1.

This classic OpenGL demo, converted to JOGL, features three turning interconnected gears.
Figure 1. This classic OpenGL demo, converted to JOGL, features three turning interconnected gears

Additionally, the gears demo outputs some information about the platform's OpenGL implementation to the command window. For example, it outputs the following (reformatted) information about my platform's implementation:

INIT GL IS: com.sun.opengl.impl.GLImpl
Chosen GLCapabilities: GLCapabilities [DoubleBuffered: true, Stereo: false, HardwareAccelerated: true, 
                       DepthBits: 24, StencilBits: 0, Red: 8, Green: 8, Blue: 8, Alpha: 0, Red Accum: 16, 
                       Green Accum: 16, Blue Accum: 16, Alpha Accum: 16, Multisample: false ]
GL_VENDOR: NVIDIA Corporation
GL_RENDERER: GeForce 6100/PCI/SSE2/3DNOW!
GL_VERSION: 2.1.2

Most demos have certain hardware and software requirements. For example, the procedural texture physics demo requires pbuffer (pixel buffer) support, along with the ARB_vertex_program and ARB_fragment_program OpenGL extensions. Assuming that your platform meets these requirements, the following command line (divided across three lines for readability) runs this demo:

java -cp "c:\jogl\jogl.jar;c:\jogl\gluegen-rt.jar;c:\jogldemos\jogl-demos.jar;
          c:\jogldemos\jogl-demos-util.jar;c:\jogldemos\jogl-demos-data.jar" 
     -Djava.library.path="c:\jogl" demos.proceduralTexturePhysics.ProceduralTexturePhysics

This command line includes jogl-demos-util.jar and jogl-demos-data.jar in the classpath because they're required by the demo. After invoking the command, you should observe the 3D scene that's shown in Figure 2 -- try clicking the scene (to give it focus) and repeatedly pressing the period key to increase the frequency of the water droplets.

This physics-based water simulation is run in its entirety on the graphics card via vertex programs, fragment programs, and pbuffers.
Figure 2. This physics-based water simulation is run in its entirety on the graphics card via vertex programs, fragment programs, and pbuffers.

By the way, the java.net-hosted JOGL Demos project site lets you test drive the demos located in jogl-demos.jar and additional site-specific demos via Java Web Start.

1 2 3 4 5 6 7 8 9 Page 2
Page 2 of 9