YAJOGLB has moved to berlios.de, and the new home page is at yajoglb.berlios.de.
This is the home page for YAJOGLB (Yet Another Java OpenGL Binding), my contribution to the world of Java OpenGL bindings. YAJOGLB allows you to use Silicon Graphics's OpenGL 3D graphics library from within Java programs under Microsoft Windows or Linux.
You need to have OpenGL installed on your Windows or Linux machine before you can use YAJOGLB. If your video card does not support OpenGL directly, several years ago SGI released software implementation for Windows. You can find SGI's OpenGL 1.1 for Windows 95 and Windows NT 4.0 at http://www.berkelium.com/OpenGL/sgi-opengl.html. Because it is a software based OpenGL implementation it will run on slowly, but on any Windows machine.
There is an OpenGL clone named Mesa that you can use under Linux. It is available at http://www.mesa3d.org. I've written some Linux notes that you should read before using the binding under Linux.
Once OpenGL is installed on your machine, you also need to have Java on your machine. You can find instructions for installing the Java developer's kit at http://java.sun.com
The Makefiles use a provided python script that, along with gcc, generates the dependencies for the C files. If you don't want to install python on your Linux machine you could replace the script with a touch command. Of course, make won't know when to recompile your files if you do that. There is more information on building the distribution in the building section of the technical overview.
For the most part, when the individual OpenGL methods are no different from their counterparts in the C API they have been left undocumented. I've found the documentation at http://www.opengl.org/developers/documentation/man_pages/hardcopy/GL/html/ to be very helpful. There is also a technical overview in the documentation directory, and some test documentation that includes sample images.
The last thing you need to download is the 0.4 YAJOGLB distribution, which is a tarred and bzip2ed copy of the package.
Once you have unpacked the distribution, you should have a directory with the following subdirectories:
CNativeCode - the source code for the native libraries used by the binding to use OpenGL. The distribution includes the Windows DLL (which needs to be in your PATH environment variable for the binding to work) is located in the directory CNativeCode/YAJOGLB/Debug. Under Linux you can build the dynamic library with make.
doc - contains documentation on the bindings, which includes this document and a technical overview.
test - contains sample code used to test the Java bindings, along with some test documentation.
sun - contains a class that allows the bindings to access the native peer component's drawing surface. These are no longer used, and are included if you can not use the JAWT extension that Sun added to Java in JDK 1.3. However, I am no longer testing them.
There are some differences between how the OpenGL API is expressed in C and how I choose to implement it in Java. The first and most obvious difference is that none of the library functions are stand-alone functions. Because Java does not allow pure functions the OpenGL functions are all members of the GL class. This class serves as a placeholder for the OpenGL functions. Also, each OpenGL.Canvas maintains a window that can be used only for OpenGL rendering. There is an OpenGL.Context class that serves as the "OpenGL Context" that is implicitly used by every OpenGL function.
The second difference is that the "gl" prefixes have been removed (the "glu" prefix has not, because it would have created some conflicts) from functions and constants. So, for example, glNormal3f is normal, and GL_QUADS is just QUADS. The prefix seemed redundant given that all function calls have to be made through a GL object anyway.
The argument specifications ("2d", "3f","4sv") at the end of most OpenGL functions have been removed. Java's method overloading is used to distinguish between glVertex3f(1.0, 2.0, 1.0) and glVertex2f(1.0, 2.0).
Here is an example of the C code that is needed to draw a box with lighting (taken from Microsoft's excellent introduction to OpenGL):
glBegin(GL_QUADS);
glNormal3f( 0.0F, 0.0F, 1.0F);
glVertex3f( 0.5F, 0.5F, 0.5F); glVertex3f(-0.5F, 0.5F, 0.5F);
glVertex3f(-0.5F,-0.5F, 0.5F); glVertex3f( 0.5F,-0.5F, 0.5F);
...
glEnd();
Here is what the same code looks like in YAJOGLB, with gl being a GL object.
gl.begin(QUADS);
gl.normal( 0.0F, 0.0F, 1.0F);
gl.vertex( 0.5F, 0.5F, 0.5F); gl.vertex(-0.5F, 0.5F, 0.5F);
gl.vertex(-0.5F,-0.5F, 0.5F); gl.vertex( 0.5F,-0.5F, 0.5F);
...
gl.end();
Other changes had to be made for the GLUT routines that require "objects" as parameters. In C, some GLU functions take a pointer to some structure that must be manually allocated and deallocated. I decided that this wouldn't do for programming in Java, so I implemented a series of Java objects for each GLU structures. So, the bindings include the GLUNurbs, GLUQuadric, and GLUTriangulator class. Here is an example of what drawing a sphere looks like in C:
GLUquadricObj *quadric = gluNewQuadric();
gluQuadricDrawStyle(quadric, GLU_FILL);
gluQuadricNormals(quadric, GLU_SMOOTH);
gluSphere(quadric, sphereRadius, 15, 10);
gluDeleteQuadric(quadric);
Here is what it looks like in Java:
GLUQuadric sphere = new GLUQuadric();
sphere.gluQuadricDrawStyle(GLU_FILL);
sphere.gluQuadricNormals(GLU_SMOOTH);
sphere.gluSphere(sphereRadius, 15, 10);
Notice that you don't have to deallocate the quadric object, and that instead of being passed as a parameter to the GLU functions, the GLU functions hang off the object.
Instead of giving the various GLU objects callbacks you override methods on the appropriate class. Instead of supplying an error function for your NURBS object, extend GLUNurbs and override the error method. It will be called whenever the error callback would be.
The binding has been tested with JDK 1.3 with an NVIDIA TNT2 under Windows 2000 and GNU/Linux. Please let me know if you get it to work under any other configurations. Previous versions worked just fine under Windows 98 and Windows NT; I'd be surprised if I had managed to break support for those operating systems.
There are a host of other OpenGL bindings available. Some of the ones that I know about are (I've kept projects with broken links):
Magician A nice but now defunct commercial binding.
An Unoffical Port of Java to OpenGL Leo Chan's OpenGL binding --- the grand daddy of most Java OpenGL bindings. YAJOGLB is one of the few that is not based on Leo Chan's work.
JavaGL A somewhat older OpenGL binding. From the documentation it looks like not all of the OpenGL calls are supported, and that it hasn't changed in about a year.
JavaOpenGL Jack Palevich's OpenGL binding, based on the "Unoffical Port of Java to OpenGL", this is a binding that works with Windows.
Jogl A nice set of bindings for that are being used for Adam King's Java3D implementation.
GL4Java A Thesis describing an OpenGL Java binding for X-Windows.
Tree A Java interface for Mesa, which means that it should work for OpenGL as well.
I'd like to thank my friends Jay Bauer and Dwight Divine for their help with the package; Jay for letting me test it on his machine and Dwight for correcting some mistakes in my documentation. My previous employer, BALR, was also of considerable assistance. Lastly, I wouldn't have been able to write the binding without being able to take a look at some open source software. Jogl showed me how to access an AWT's peer instance to obtain native windows information (since replaced by JAWT), and Mesa (a 3D graphics library with an API similar to OpenGL's) matrix modification routines made their way into the GeometryViewer used in the test package.
If you use this package, or have any questions about it, please drop me a line at razeh@yahoo.com.