An (Unofficial) OpenGL* Port for Java Prerelease Version 0.1 Jan 19, 1996 Author: Leo Chan lchan@cgl.uwaterloo.ca MetaMedia Project Computer Graphics Lab University of Waterloo http://www.meta.cgl.uwaterloo.ca * OpenGL(R) is a registered trademark of Silicon Graphics Inc. This is NOT yet an official port. Introduction ============ This is a straight port of most of the OpenGL C functions to Java, and allows OpenGL programs to be ported to or written in Java. This library can be used (including commercial use) without charge and the source code is available for use or modification without charge. The author offers no guarantee of support or functionality. Comments, bug reports and bug fixes are welcome. Please use the above address to contact the author. We are calling it "OpenGL" since we intend it to be a one-to-one mapping of the full functionality of OpenGL, and thus satisfy the requirements for calling something "OpenGL". We will contact the OpenGL ARB about certifying the naming conventions we use. NOTE: This version represents a prerelease of work in progress. This is *not* a beta release; we don't claim that it is meant to be complete or official (yet). Several OpenGL functions still need to be ported, and certain methods have yet to be tested. The missing functions are: glGenLists, glInitNames, glIsList, glMap1, glMap2, glNewList, glPixelMapfv, glPixelMapiv, glPixelMapsv, glPixelStore, glPixelTransfer, glPixelZoom, glPolygonStipple, glReadPixels, glSelectBuffer, glTexImage1D, glTexImage2D glTexParameter, See "Use of Mesa" below. Disclaimer ========== We don't actually think OpenGL is a very good interface in an OO context, or in the multi-platform context that Java is meant to be used in. This port was done for compatibility and porting reasons, and to get something working quickly. We're now in the process of building a public-domain OO graphics library on top of the OpenGL class, but without any specific bonds to the use of OpenGL as a rendering engine. Using the OpenGLwidget ====================== Naming Conventions ------------------ Each OpenGL function is mapped to a method in the OpenGLwidget class. Java's polymorphism has been used so that the same method name can be used with different arguments. For example, if you instantiate an OpenGLwidget object called "w", then OpenGL C functions OpenGLwidget Java method glLightf(GLenum,GLenum,GLfloat) --> w.light(int,int,float) glLightfv(GLenum,GLenum,GLfloat *) --> w.light(int,int,float[]) glLighti(GLenum,GLenum,int) --> w.light(int,int,int) glLightiv(GLenum,GLenum,int *) --> w.light(int,int,int[]) We drop the initial "gl" since such a naming convention is not needed; the object reference creates the necessary name scope. We also convert the initial uppercase letter to lowercase. Any internal capitalization is kept, i.e. w.lightModel(). Finally, we drop any suffixes which previously indicated the argument type expected in C, in this case 'f', 'fv', 'i' and 'iv'. These suffixes are not needed in java to differentiate between functions which accept different types. We have put the OpenGLwidget class in a package called OpenGL. OpenGL Context -------------- The widget creates and maintains an OpenGL context, and acts as any other AWT widget. Well, actually, it WILL once we get the right window handle out of the AWT... right now we are forced to create our own external window. If you create more than one widget, each will have its own context. Configuration Options --------------------- We have not completed any support for configuration of the OpenGLwidget yet. For example, the size of the widget is 500x500, hard-coded in the OpenGL/OpenGLwidget.java file (under the private variables width and height). Configuration support is work in progress... Widget Methods -------------- Additional widget methods include: w.swap() Swaps the front and back buffers This is mapped internally to the appropriate native windowing system calls. Right now we only support X, though. w.use() Makes w's graphics context the current context for the OpenGL rendering Use of Java Arrays ------------------ In some OpenGLwidget methods, such as get(), Java arrays are used by the native C functions. The length field of the Java arrays are checked in Java before the native C functions are called to ensure that sufficient space to complete the operation has been allocated in the Java array. Use of Mesa ----------- A GNU subset of OpenGL which is implemented completely in software is available for various platforms. It is called "Mesa" and can be obtained from ftp:iris.ssec.wisc.edu/pub/Mesa Mesa was used in the development of version 0.1, since we didn't have a version of OpenGL for the Sun at the time but could only use the JDK there. However, Mesa is not an official or complete implementation of OpenGL, so... We plan to test the system against a full implementation of OpenGL in the near future, on our Onyx and/or on a Sun with a third-party commercial OpenGL implementation. How To Install ============== Makefile -------- Note: the supplied Makefile was only tested on a Sun SPARCstation running Solaris. For those who are not using UNIX, or even worse, Windows, good luck... You will need to change several variables in the Makefile to specify the location of your javac and javah compiler, the JDK, etc. These variables are near the top of the make file between two large comment blocks. There is a second Makefile in the CNativeCode subdirectory which you will also need to customize in a similar manner to specify the location of the OpenGL (or Mesa in the supplied Makefile) libraries, the X libraries and the location of java (for header files). With these two files correctly modified, go to the directory with the file 'testOGLWidget.java' in it and type 'make testOGLWidget.class' If all goes well, a file called 'libOpenGL4java.so' should be created in the current directory. This is the shared library that java will load when you use the OpenGLwidget. Be sure that the current directory is in you $LD_LIBRARY_PATH environment variable, or java will not be able to find the library. You should be able to type 'java testOGLWidget' and see three cylinders rendered in green.