Jausoft - Sven Goethel Software Development

OpenGL^TMfor Java^TM Frequently Asked Questions (F.A.Q)

Table Of Contents (TOC)

GL4JAVA general questions :
What is GL4JAVA ?
Who makes GL4JAVA ?
How can I learn using GL4JAVA ?
Do I have to pay in order to use GL4JAVA ?
How can I help ?
Where can I download and install the beast ?
What kinda GL4JAVA applications and applets currently exist ?
What should I read before you reply with RTFM ? Whom should I ask ?

JAVA related questions :
But isn't Java slow ?
What platforms does GL4JAVA run on ?
How does GL4JAVA compare to Java3D ?

GL4JAVA technical questions :
I'm trying to use gl4java on my OS using Java2. I can't succeed having it working !
My Canvas renders 1 frame, then stops, what's wrong ?
GLAnimCanvas vs GLJPanel, which should I choose ?
GLJPanel/GLAnimCanvas subclass model vs GLEventListener model, which should I choose ?
Extensions - Does GL4JAVA support extensions ? How do I load them ?
Tesselation - Does GL4JAVA support tesselation ? How do I use it ?
Offscreen - How Do I Use Offscreen Rendering with GL4JAVA ?
Fullscreen - How Do I Use Fullscreen with GL4JAVA ? Bump Mapping - How Do I Use Bump Mapping with GL4JAVA ?
General questions :
Trademarks

What is GL4JAVA ?

GL4JAVA is an abbreviation of OpenGL^TM for Java^TM,
read the trademarks section ;-)

GL4JAVA is an OpenGL binding for Java.
The GL4JAVA API maps native c++ OpenGL functions to the Java language and provides fast access to 3D accelerators from Java.

GL4Java maps the complete OpenGL 1.3 and GLU 1.2 API and implements window handle functions (native and java), while using the Java-Native-Interface (JNI) of Java or the JDirect-Interface of MS-JVM. Win32, X-Window, Mac.

GL4JAVA has been developed under Open Source Model since 1997 and has become over the years a serious and stable API.
Though, the library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY nor obligation of user support.

Have a look at the Overview !

Who makes GL4JAVA ?

GL4JAVA is mainly developed by Sven Gothel from Jausoft but many people have helped/contributed to the development of the project :

Aetius,

Jean-Yves BRUD,

Ron Cemer (www.3dstockcharts.com),

Leo Chan,

Alban Cousinié,

DESYS (www.desys.com),

E3Futura & TeatreSoft,

Lee Elson (NASA),

Max Gilead,

Adam King,

Atilla Kolac,

Pontus Lidman (Mathcore),

Eloi Maduell,

Moises Ferrer Ramirez

Tommy Reilly,

Odell Reynolds (NASA),

Kenneth B. Russell (SUN Microsystems),

Ervin Vervaet,

Leung Yau Wai,

Gerard Ziemski,

...

The companies are only listed here, if the support and help is done by them officially.
But if the individuals had to do the whole within ther spare time only,
no company information is provided here !!

Others we missed to list up here, please email the maintainers.

Please check out the Thanxs Page also !

How can I learn using GL4JAVA ?

Have a look at the GL4Java Documents !

If you are completely new to OpenGL, you can check out NeHe's OpenGL Tutorials. It is a good starting point to get a taste of OpenGL. Several NeHe's tutorials have been ported to GL4JAVA and can be found here (most of them are also included within the demo package)

Then if you're seriously considering learning OpenGL, we advise you to buy the OpenGL Programming Guide, wich is also commonly refered as the "OpenGL RedBook".
You can find several digital copies of it online, but we don't know if they are authorized by the authors. If you want to check them out, search fo "OpenGL Redbook" in a search engine.
Notice the book has more than 600 pages, so it's REALLY worst buying it if you don't want to burn your eyes on the screen ! :)

Then the next and mandatory step (before you ask a basic or stupid question to Sven which will reply by a RTFM !) is to read the docs and learn the demos provided with GL4JAVA wich can be found here,

Do I have to pay in order to use GL4JAVA ?

No. The GL4JAVA library is free software. You can redistribute it and/or modify it under the terms of the GNU Library General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

Of course, Sven Gothel spends a lot of time developping GL4JAVA and a generous donnation to Jausoft would help him continue supporting the development of GL4JAVA.

How can I help ?

Well, GL4JAVA is OpenSource'd LGPL licensed and lives from your support !
So, anything you missing within GL4JAVA may be a good thing to add and maintain.
Just ask the mailinglist Usergroup Mailinglist !

Where can I download and install the beast ?

Well, you can use the last release: GL4Java Homepage
Press the download/installation button, which leads you to the specific page !
There you will find all links for automatic and manual installation,
and the directories from which you can download the sources, demo's, docs and binaries:

latest source, docs, demos

latest binaries

Take your time, don't hurry ;-) !

Here you can find instructions for the manual installation,
and a checklist for the automatic installation via the installer !

If you wan't to check out the very latest GL4JAVA on the edge development release,
please go to GL4JAVA @ SOURCEFORGE !

What kinda GL4JAVA applications and applets currently exist ?

Applications

Demos

and just search the web for GL4JAVA ;-)

What should I read before you reply with RTFM ? Whom should I ask ?
(RTFM = Unix abbreviation for `Read The Fucking Manual')

Read the Overview !
and there you will find the JavaDoc GL4JAVA API and other stuff.

Download or browse the latest source, docs and demos via CVS GL4JAVA @ SOURCEFORGE
and read the README files, the docs and the demos !

You can also browser them from here: latest release,
download them from here: latest source, docs, demos,
but this source might be outdated, since this is not the development release !

Just ask the mailinglist Usergroup Mailinglist!

But isn't Java slow ?

No. Check out the demos !

Java has been arround for more than 6 years now and the speed of execution of the language has been improved dramaticaly. The latest implementation of Java 2.0 (JDK 1.4) is running especially fast. Since programing with GL4JAVA relies mostly on hardware acceleration, the speed of execution of the Java language doesn't matter much unless you use huge and unoptimized algorithms.

It is heard that using Java as an Applet in a browser reduces the performance considerably though, because the display often goes thrue the browser's window API rather than directly to your Operating System display API. This is especially true with Netscape 6.0 wich cuts down the Java performance by a factor of 2 (using the java plugin !) compared to the AppletViewer.

There are several papers about optimizing the speed of Java on the Internet :

Tuning JavaTM I/O Performance on java.sun.com
Thirteen Great Ways to Increase Java Performance on java.sun.com
Dirty Java: Optimizing Pure Java on Gamasutra

What platforms does GL4JAVA run on ?

GL4JAVA runs on GNU/Linux, Win32, Mac OS 9.x, Mac OS X and any Unix/X11/OpenGL.

We do support precompiled native binaries It should run on any Unix/X11/OpenGL machine, but we sometimes don't have precompiled binaries for those.
E.g. we had it run also on Solaris, Irix and AIX. But since nobody does create binaries and maintains
those machines, we cannot provide you with precompiled native libraries.

How does GL4JAVA compare to Java3D ?

GL4JAVA is an OpenGL binding and provides nothing else than access to OpenGL/GLU commands.
GUI managment and toolkits like GLUT, texture managment, etc. are also provided.
For the near future hopefully we can support a higher level scenegraph (SG) API like VRML or 3DS.

Java3D is a multipurpose closed source scene graph API relying on DirectX and OpenGL.
Java3D provides parsers for loading objects, functions to manipulate scene objects, such as texturing, morphing and so on... Because of Java3D's multipurpose nature, it contains many functionalities and thus contains an important amount of code, wich many parts of it remain unused because they aren't in the field of your purpose. This makes the API heavy and long to load. But then the display speed performs reasonnably. On the other hand Java 3D is much easier to use because it is a high level API. For example if you want to do a morph in Java3D, you create a morph node, load your geometry targets inside it, and set the morph amount between the targets.

Using plain OpenGL for a 3D morphing, you have to go thru every vertex of your geometry and compute their x,y,z position yourself. Using plain OpenGL you have to code your own file parser and display your object, polygon per polygon, all this with your little hands ! This is an important work and it takes time. More, OpenGL is very specific and thus it's quite hard to learn, often requiring a good knowledge of math. But in the end you have coded only what you needed and your program is very small and fully optimized (this requires you use OpenGL intelligently, though).

So if you need to have your project coded very quickly, if performance is not a top priority criteria and if you feel desesparate when doing math, use an avaiable well functional SCENEGRAPH environment, e.g. Java3D. If performance is critical (such as for games), if you have plenty of time, and you feel your shoulders are strong enough to face the big and malicious OpenGL monster, use plain OpenGL !

CONCLUSION:
If you don't want to do plain OpenGL use a SCENEGRAPH environment!
If there is none yet avaiable for GL4JAVA,
create some, make it avaiable under the terms of the LGPL !
GL4JAVA is OpenSource and lives from your support and contributions.
GL4JAVA provides you with it's source code and adding functionality is welcome.
Look at the benefits !

Does GL4JAVA support extensions ? How do I load them ?

Yes, GL4JAVA supports numerous extensions. In order to list wich extensions are supported, just do a
>java gl4java.GLContext -info
OR press the gl4java button on a demo, e.g. gears.

The extensions and the regular OpenGL 1.3 functions are dynamically loaded, so you don't have to worry about loading them. They are here, and you just have to use them !

You can query, if the function exists, while calling e.g.:
boolean t = GLContext.gljTextGLProc("VertexArrayRangeNV", true /* verbose */);
that's it !
Then you can savely call VertexArrayRangeNV(), this works for all supported OpenGL methods !
If you call the GL4Java wrapper method for an unimplemented OpenGL function, nothing will happen - it is safe !

Check out the NVidia Demo !

Does GL4JAVA support tesselation ? How do I use it ?

Since GL4Java 2.2.0, tesselation is supported !

Please look in the sources and/or javadoc
of:

	gl4java.GLUTFunc

There exist also many demos:

demos/MiscDemos/tess / (source)

demos/MiscDemos/tessdemo / (source)

demos/MiscDemos/tesswind / (source)

DETAILS

The native callback manager of GL4Java seeks the
callback function with:

callback method-type (the "which" argument of the Callback function)

the current gl-context

Because the callback manager functions do not know the
tessellator/nurbs/quadratics id,
only ONE callback-method for one gl-context and "which"-method
is supported !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!


Jean-Yves BRUD asked:

> What is the meaning of parameter signature ?
> If my callback method name is myVertexCallBack (for a GLU_TESS_VERTEX
> callback),
> what is the value of the signature parameter ?

public void  gluTessCallback(     long tobj, int which,
			          Object methodClassInstance, 
			          String methodName, 
				  String signature,
				  int voidArrayLen1,
				  int voidArrayLen2,
				  int voidArrayLen3,
				  int voidArrayLen4,
				  int voidArrayLen5
				  );


Example (tessdemo.java line 337):
	glu.gluTessCallback ( tobj, GLU_TESS_VERTEX, gl,
			      "glVertex2fv", "([F)V",
			      2, 0, 0, 0, 0);

The signature "([F)V" is the original java style signature of the
argument-list, your callback method takes (here: glVertex2fv) !

	void glVertex2fv( const GLfloat v[2] ) 

	(...) := within the brackets are function arguments signature part
	[F    := float array
	V     := void - 
                 the signature part after the brackets 
		 means the return value

Read SUN's Java Documentation for Java-Callback methods:
         http://java.sun.com/docs/books/tutorial/native1.1/implementing/method.html

Here you can find the mapping of function arguments to its corresponding
string signature representation !

Jean-Yves BRUD asked:

>
> What is the meaning of the 5 parameters: voidArrayLen1, voidArrayLen2,
> voidArrayLen3,
> voidArrayLen4, voidArrayLen5, and what value do I need to put ?
>

public void  gluTessCallback(     long tobj, int which,
			          Object methodClassInstance, 
			          String methodName, 
				  String signature,
				  int voidArrayLen1,
				  int voidArrayLen2,
				  int voidArrayLen3,
				  int voidArrayLen4,
				  int voidArrayLen5
				  );

The maximum number of arrays within the argumentlist of 
a GLU Callback function for Tesselation is 5 !

So, the arguments voidArrayLen[1-5] refines the expected
size of the arrays, 
which are passed into and from the java callback funtion.

	OpenGL-Machine <-> GL4Java-Callback-Handler <-> Java-Callback-Method

E.g. (tessdemo.java):
         glu.gluTessCallback ( tobj, GLU_TESS_COMBINE, this,
                                "combine_callback", "([D[D[F[F)V",
                                2, 0, 0, 2, 0);

        public void combine_callback( double coords[/*3*/],
                               double vertex_data[/*4xn(=0)*/],
                               float weight[/*4*/], float[/*m(=2)*/] data )
        {
           data[0] = (float) coords[0];
           data[1] = (float) coords[1];
        }

You can see, we do use the arrays "data" and "coords" with a size of 2 !
You are not allowed to use nonsense sizes, because this can hurt your
application with a segementation fault !
(Well the GL4Java Callback functions checks
 the array sizes to OpenGL's maximum, .. but be kind of ..)

The OpenGL machine calls GL4Java's callback function,
which dispatches the call (incl. data) to your java callback function !

How Do I Use Offscreen Rendering with GL4JAVA ?

You can just use it, the way GLJPanel use it for swing integration !

Since 2.8, I have added a gl4java.awt.GLOffScreenDrawable !

Here is a little offscreen PNG gl-image renderer, using gl4java.awt.GLOffScreenDrawable:

demos/MiscDemos/gearsOffScreen2Tga.java (source)

demos/MiscDemos/gearsOffScreenDrawImage.html / (source)

How Do I Use Fullscreen with GL4JAVA ?

Well, for the pre JDK 1.4 aera, i only can recommend the stupid way
of increasing the window size to screen size like in the
demos/RonsDemos/FullScreenGears.java demo !

For the JDK 1.4 machines, we just can use the standard JDK 1.4
fullscreen mode like this:

demos/MiscDemos/gearsFullScreen.java (source)

How Do I Use Bump Mapping with GL4JAVA ?

I do not know ? ;-)

Somebody should fill this .. please !

I'm trying to use gl4java on my OS using Java2. I can't succeed having it working !

First of all, we do use the follwing names here:

	JAVA_HOME

JAVA_HOME refers to the directory where the runtime software is installed (which is the top-level directory of the JRE or the jre directory in the Java 2 SDK).
Here are some examples of you JAVA_HOME locations:

WIN32 JDK:	C:\jdk1.3.1\jre
WIN32 JRE:	C:\Program Files\JavaSoft\JRE\1.3.1
UNIX  JDK:	/usr/lib/jdk1.3.1/jre

	DIRECTORY SEPERATOR /

/ is our directory seperator. so if you are unlucky and using win32 ;-), you have to use the backslash \, otherwise on any unix flavor, you are fine with the straight slash.

For the Window's world, I have learned on my win98se machine,
that you better use the JRE as your default Java2 JRE,
for the Java2 plugin within your browsers.

Don't ask me why, but i never ever got the gl4java applets to run
if using the JDK directory in the Java2 Plugin setup.

Well, the good thing is, using the JRE Path, is the default ;-)

First check that you have all the .jar files in the correct locations :

JAVA_HOME/lib/ext/gl4java.jar
JAVA_HOME/lib/ext/gl4java-glutfonts.jar
JAVA_HOME/lib/ext/gl4java-glffonts.jar
JAVA_HOME/lib/ext/png.jar

Then make sure you have installed the gl4java native dynamic libraries in the right directories :

the following 5 native dynamic libraries are required:

	WINDOWS:
	========
	JAVA_HOME/bin/GL4JavaGljMSJDirect.dll
	JAVA_HOME/bin/GL4JavaJauGljJNI.dll
	JAVA_HOME/bin/GL4JavaJauGljJNI12.dll
	JAVA_HOME/bin/GL4JavaJauGljJNI13.dll
	JAVA_HOME/bin/GL4JavaJauGljJNI14.dll

	UNIX X86:
	========
	JAVA_HOME/lib/i386/GL4JavaGljMSJDirect.so
	JAVA_HOME/lib/i386/GL4JavaJauGljJNI.so
	JAVA_HOME/lib/i386/GL4JavaJauGljJNI12.so
	JAVA_HOME/lib/i386/GL4JavaJauGljJNI13.so
	JAVA_HOME/lib/i386/GL4JavaJauGljJNI14.so

	UNIX PPC:
	========
	JAVA_HOME/lib/ppc/GL4JavaGljMSJDirect.so
	JAVA_HOME/lib/ppc/GL4JavaJauGljJNI.so
	JAVA_HOME/lib/ppc/GL4JavaJauGljJNI12.so
	JAVA_HOME/lib/ppc/GL4JavaJauGljJNI13.so
	JAVA_HOME/lib/ppc/GL4JavaJauGljJNI14.so

Some JDK ore JRE's have different locations, e.g. IBM's JDK for Linux, they do use e.g.:

	JAVA_HOME/bin

for the dynamic libraries !

You just can search for the libraries, which directory is our destination:

libjava.so (unix)

java.dll (win32)

Then you may want to install the native libraries
to you system's default library path also.
Here are several possible default locations.

	WINDOWS VARIANTS:
	=================
	C:/WIN98/SYSTEM 
	C:/WIN95/SYSTEM 
	C:/WINNT/SYSTEM32 

	UNIX FLAVORS
	============
	/usr/lib

Be sure, that if you do have installed GL4Java in any of the described directories,
install the same version on all such locations.

Because of Java2 PrivilegedAction's restriction,
you should have installed the libraries under the above JAVA_HOME directory,
to being able to use GL4Java for Java Applet's!

Finally check out the java.policy files located in :

	JAVA_HOME/lib/security/java.policy

You should have (by default) :

grant codeBase "file:${java.home}/lib/ext/*" {
	permission java.security.AllPermission;
};

The following issue might be obsolete regarding the GL4Java 2.8 release !
Some have problems using standalone GL4JAVA applications,
because they wouldn't fint jawt.dll and wouldn't load gl4java dependent dlls.
In this case you have 2 choices:

Make sure you have your PATH variable set correctly (don't forget to replace "\jdk1.x\" by your own jdk directory): PATH = your_path_variables;c:\jdk1.x\jre\bin;C:\jdk1.x\bin

just start the java application from c:\jdk1.x\jre\bin\java

You should be up and running now ! That is what I call a seamless installation ! ;)

My Canvas renders 1 frame, then stops, what's wrong ?

Ensure you have managed the GL Context correctly.

If using the old override model (derivation from GLCanvas or GLAnimCanvas),
you have to make the gl context current first, then use gl and last but not least free it !

Here is how you should use gl4java during display :

public void display(){

	// Ensure GL Context is initialised correctly
	if (!glj.gljMakeCurrent())return;

	// YOUR CUSTOM CODE goes here

	// swap the buffers IF double buffering is enabled
	glj.gljSwap();

	// just check if some opengl errors occured
        glj.gljCheckGL();

	// free the GL Context. This function MUST be called
	// in last position in you display function.
        glj.gljFree();

}

If using the new gl listener model, you do not have to take care about this,
cause the listener holder (GLCanvas or GLAnimCanvas) itself takes care about this

GLAnimCanvas vs GLJPanel, which should I choose ?

The GLJPanel implementation currently renders to an off-screen buffer and copies the pixels to the lightweight component. This leads to slowdowns over GLAnimCanvas because the rendering is not hardware-accelerated and because of the copying overhead.

It is possible that the implementation could be changed to walk the lightweight component hierarchy to find the bounds of the GLJPanel within its parent heavyweight component and clip the OpenGL rendering region to fit (if the GLJPanel itself isn't overlapped by another lightweight component), which should speed it up significantly, though this kind of code is tricky to write.

But you can use heavyweight components within a swing layout also : these are hardware accelerated but they keep their heavyweight restrictions (no overlapping...)
have a look at GL4Java/demos/testTextPPM1.java, where swing/awt is mixed ..

GLJPanel/GLAnimCanvas subclass model vs GLEventListener model, which should I choose ?

The subclass model is the old mechanism which was used with GL4JAVA untill now.
It consists in designing a class inherited from GLAnimCanvas or GLJPanel and overload its init() and display() methods to put your custom code.

It's recommended to use the new GLEventListener model, even if you're a beginner.

The listener model allows you to switch easyly between different GLEventListener's init()/display()/etc.. methods without having to destroy your canvas and create a new one.

With the new model, you have to implement an GLEventListener, which is your selfmade application specific renderer.
Then you just can attach your GLEventListener ( gearRenderer (source) ) to any GLDrawable, e.g.:

gearRenderer attached at an offscreen GLDrawable (source)

gearRenderer attached at an direct GLDrawable (source)

The GLEventListener is the newly implemented listener mechanism which avoids subclassing.
It offers higher performance, especially for GLAnimCanvas, because in certain circumstances OpenGL context
switches can be avoided. (The details of this are hidden from the programmer.)

To use this new mechanism as shown in the gears demo (source):

  - Create a gl4java.GLCapabilities object indicating the use of
    RGBA mode, etc.
  - Pass this capabilities object to gl4java.drawable.GLDrawableFactory.getFactory().
  - Call addGLEventListener on the resulting GLDrawable to set up your listener, which should implement at least init() and display().

For highest performance animations:

  - Call GLDrawableFactory.createGLAnimCanvas()
  - Call setUseRepaint(false), setUseFpsSleep(false), and setUseYield(false) on the resulting GLAnimCanvas

In one of the NVidia demos ported to Java, adding the optimized context handling increased the speed of the demo by 20%. Performance gain is not obvious in every case though, it depends on where the bottleneck is in your application.

Another simple exemple of using the listener model can be found in the demos :

demos/MiscDemos/TriangleRotate.java (source)

OpenGL^TMfor Java^TM / Trademarks

Linux is a trademark of Linus Torvald
OpenGL is a registered trademark of SGI.
Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems,Inc. in the United States and other countries.
Solaris is trademark of Sun Microsystems,Inc.
Windows and Windows NT are registered trademarks of Microsoft Corporation.
IRIX is a registerd trademark of SGI in the United States and other countries.
Mac is a registered trademark of Apple Computer, Inc.
Netscape is a trademark of Netscape Communications Corp.
The names of products and corporations are trademarks or registered trademarks of respective corporation.

GL4Java was the former project name of OpenGL^TM for Java^TM

GL4Java has no relationship with the Java trademark registered by Sun Microsystems, Inc.

This FAQ is maintained by Alban Cousinié and Sven Goethel.
Last Updated on 10th November 2001