JOGL-Specific Features

JOGL is the shortened name for the Java bindings to OpenGL developed and maintained by Sun Microsystems’ Java Game Technology Group and distributed on the Web at their main Java game development site. Whereas JOGL serves to provide clean, object-oriented access to standard OpenGL features, it also adds additional features beyond standard OpenGL. The JOGL team took the best ideas from several other previous Java OpenGL wrapper projects, such as GL4Java, while keeping it fast, clean, and easy to use.

JOGL is intended to be a community-development process. Developers and users can get involved through existing forums and mailing lists the java.net Web site on game development. Everyone is encouraged to post, and the participants on those sites are eager to hear about impressions and suggestions for its development.

JOGL is integrated with Java’s Abstract Window Toolkit and Swing widget sets. JOGL provides access to the latest OpenGL 1.4 with vendor extensions. JOGL also provides popular features introduced by previous Java bindings, including a composable pipeline model that can provide simpler debugging for JOGL applications than the analogous C OpenGL program. The GL class provides a minimal and easy-to-use API designed to handle many of the issues associated with multithreaded OpenGL applications. JOGL uses the most recent Java Platform features and, therefore, supports only J2SE 1.4 and later. Several complex and leading-edge OpenGL demonstrations have been successfully ported from C/C++ to JOGL. Finally, the JOGL binding is written almost completely in the Java programming language. The native code is autogenerated during the build process by a tool called GlueGen, which is also publicly available.
Integration with AWT

Java’s Abstract Window Toolkit, or AWT, is the set of standard Java APIs for GUI building and is part of the larger group of APIs called the Java Foundation Classes (JFC), included with the standard Java distributions. The vast majority of Java applications that use a graphic interface use the display classes from the JFC. Because JOGL is also a display technology, it was built to be integrated with AWT and compatible with AWT components.
The main display class in JOGL is an interface called GLDrawable. JOGL provides two implementations of this interface, GLCanvas and GLJPanel.
GLCanvas is a heavyweight AWT component, and GLJPanel is a lightweight Swing component, both of which provide OpenGL rendering support. The class inheritance structure for GLCanvas and GLJPanel follows, showing their relationship to AWT:net.java.games.jogl
Class GLCanvas

java.lang.Object

+—java.awt.Component

+—java.awt.Canvas

+—net.java.games.jogl.GLCanvas
net.java.games.jogl
Class GLJPanel
java.lang.Object

+—java.awt.Component

+—java.awt.Container

+—javax.swing.JComponent

+—javax.swing.JPanel

+—net.java.games.jogl.GLJPanel
Because GLCanvas and GLJPanel inherit from AWT and Swing components, respectively, they can be added to standard AWT and Swing applications and used directly there. This ability makes for nice integration options with existing as well as new AWT/Swing applications, gaming or otherwise.
Neither GLCanvas nor GLJPanel can be instantiated directly; the class GLDrawableFactory is used to create them. The GLDrawableFactory creates the canvas or panel based on default or user-defined GLCapabilities, which configure things such as the display area’s color depth, Z-depth, and other frame bufferer settings. See the API docs for more information.
Supports OpenGL 1.4
JOGL is completely up-to-date and supports the latest OpenGL 1.4 release. This is important for JOGL to be considered a leading-edge technology, and it will need to follow closely future OpenGL releases. OpenGL is a fairly large (and growing) API, and although designed to be as simple as possible, it is still fairly complex by most standards. Keeping the Java wrappers current would be a tedious task if it were done by hand as it was done in the past with other Java OpenGL bindings. One way this process is improved with JOGL is the use of a new tool, GlueGen.
GlueGen
GlueGen is an automatic tool for creating JNI wrappers from regular C code to become part of Java APIs.
JOGL is completely automatically generated from the OpenGL C header files. When a new GL version or function is released, GlueGen can reprocess the C source, and the new JOGL will instantly have access to the new functions.
GlueGen parses C header files using a full GNU C grammar and builds a memory mapping of all typedefs, enums, structs, pointers, function pointers, and other C structures. It then builds a parallel mapping of Java methods and structures to the C equivalents and writes all the Java code and JNI code necessary to link the two. In fact, it’s powerful enough to allow you to call C functions that use C structs as parameters or return values and builds Java-side accessor classes that wrap NIO buffers. This gives you fast, completely safe access to native data.
It cleanly handles all the platform-dependent complexities involved with determining whether or not a GL function is supported at runtime. This process takes into account the GL versions of the server and client and the extensions that are exposed on the client and server. At this writing, GlueGen is also used to build Java bindings for NVidia’s Cg language for JOGL. This is currently experimental, but it shows the power of GlueGen and the forward thinking of the JOGL team.

Vendor Extensions Exposed
All public OpenGL 1.4 vendor extensions are exposed directly in the GL interface. This does not mean that they are all implemented on any given system and will most likely need to be queried with the isExtensionAvailable() and isFunctionAvailable() GL methods, similar to regular C OpenGL. On many platforms, most functionality is still only OpenGL 1.1, so, in theory, any routines first exposed in OpenGL 1.2, 1.3, and 1.4 as well as vendor extensions should all be queried. Still, should an application call an unavailable or unsupported OpenGL function on the existing hardware, JOGL will gracefully throw a runtime GLException.
Designed for NIO
JOGL uses NIO’s ByteBuffers for many data access and manipulation operations. Rendering APIs such as OpenGL access much data and need it as fast as possible. Copying large arrays of floats between Java and the underlining system memory is prohibitively slow for a cutting-edge rendering system. Therefore, JOGL uses direct ByteBuffers for data wrappers where the Java and JNI OpenGL-side need to share data.

Composable Pipelines and DebugGL
JOGL has what is called composable pipelines. Composable pipelines are alternate render objects that can provide debugging and error-checking options in OpenGL. The DebugGL object can be swapped for the standard GL object at will, and DebugGL will do automatic error-checking “under the hood” to catch GL error conditions in application commands. This tool is valuable for debugging, as will be shown in the easy use of this in the main example.
Open Source

Finally, although not really an API feature, the designers choose to author the JOGL implementation as open source. As with any open-source project, one of the greatest benefits is that the developer always has the option to dig into the binding and make changes if needed. This flexibility is extremely helpful when a particular feature is not yet available in the current release build, or the implementation is buggy, or the interface disagrees with another possible design. During the course of writing this book, we built our own custom build of JOGL to allow access to features that were planned for future JOGL releases but not yet implemented in the public releases. This was of great help, allowing us to make progress on our projects independently of the current public release. When the following public release supported those features that we had added in our custom builds, we easily switched back to the standard public