3.2 Java-Call to OpenGL

The java program should act like a native program. Java programs should use the native OpenGL library on the specific platform. The java program must load the wrapper library, which will load the OpenGL library. Like the OpenGL library, the wrapper library is platform depended and will be load in runtime, a so called dynamic library. The platform independed java OpenGL application needs the platform depended wrapper library and all librarys the wrapper library needs, e.g.: the OpenGL library etc. . To run a java OpenGL application, the user must have the OpenGL library installed and must install the wrapper library - that's all. The java OpenGL applications have the performance like an native OpenGL application. The only reason for a performance less than the native one are the costs for the java procedures (to modify data etc.). The passing through of data from java to OpenGL and vice versa needs no special converting features, thus the passing does not consume much time.

3.2.1 JNI to OpenGL

3.2.1.1 Data Type Mappings

Because java should pass it´s data without any time consuming convertion, we need a data type mapping style, where the OpenGL data types[2] fits in the java types and vice versa. The first and important criteria for a type match is the size of bytes. The secound and convinient criteria is to find aequivalent types in java, where less or no data converting must be done by the wrapper library and the java OpenGL programmer himself. Except for the marked OpenGL types we found a fine type matching which fullfill our needs. All unsigned types must match in a byte-size java aequivalent, so a special java-casting must be done by the java OpenGL programmer. Because java programmer uses arrays, we generate the GL4Java function for all Java-Array-Types, to achieve compatibility with the GLvoid * (see below).

OpenGL Data Types Mapping to Java Types.

Data Type C-Type JNI-Type Java-Type OpenGL Type

8-bit integer unsigned char jboolean boolean GLboolean

8-bit integer signed char jbyte byte GLbyte

8-bit unsigned integer unsigned char jbyte^a byte^a GLubyte,

16-bit integer short jshort short GLshort

16-bit unsigned integer unsigned short jshort^a short^a GLushort

32-bit integer int or long jint int GLint, GLsizei

32-bit unsigned integer unsigned int or jint^a int^a GLuint,

unsigned int GLenum, GLbitfield

32-bit floating-point float jfloat float GLfloat, GLclampf

64-bit floating-point double jdouble double GLdouble, GLclampd

32-bit integer void * jbyteArray^b byte[]^b GLvoid *

jshortArray^b short[]^b GLvoid *

jintArray^b int[]^b GLvoid *

jfloatArray^b float[]^b GLvoid *

jdoubleArray^b double[]^b GLvoid *

jbooleanArray^b boolean[]^b GLvoid *

jlongArray^b long[]^b GLvoid *

3.2.1.2 JNI Generation

The wrapper library which is called by the java application is specified by the Java Native Interface (JNI)[5]. All native functions, which should be called by the java application must be declared as a native function in a java class. E.g.:

public native void glClear ( int mask ) ;

The JNI compiler creates a header file for the C programming language, e.g. foo.h. This header file can be copied as an template to the C definition file, e.g. foo.c. This definition file can modified to add the needed function bodies. The function bodies, the functions, only has to call its C function out of the OpenGL library with a standard data type convertion.

In the begining we wrote some of the OpenGL wrapper functions by ourself, but later we learned that we can not guarante that all functions are wrapped and that all functions were almost bug free.

To simplify the writing of the apropiate wrapper functions, we created a C-Header-File to Java-Native-Declarations plus C-Wrapper-Functions generator. We named this generator C2J.

Details see chapter 5.2 on page .

Footnotes

... jbyte^a

No Java matching for unsigned, using extra conversion

... jbyteArray^b

No Java matching for pointers, using any arrays