Running Java 3D

1. Requirements and getting Java 3D installed and running
2. How do I get Java 3D to automatically install under JDK 1.3?
3. Can't find javax.media.j3d.*, com.sun.j3d.utils or javax.vecmath
4. Exceptions
5. The "no J3D in shared library path" error
6. Strange rendering results
7. Why does my screen flicker?
8. Out of memory problems
9. How do I get Java 3D in fullscreen mode?
10. Where can I get the source to javax.media.j3d or other parts of Java3D?
11. How do I get Java3D to run with IBM's JVM on Linux?
12. Why doesn't Canva3D work with JDK1.4?
13. Why doesn't Java3D work with JDK1.5 beta (Tiger)?

Return to the main FAQ page for more questions and answers.

1. Requirements and getting Java 3D installed and running

j3d.org maintains a simple installation guide that will be of use to newcomers to Java 3D.

First, download Java 3D from the java.sun.com or one of the other sites listed in our downloads page.

You must be running Java 2 for Java 3D to work correctly.

For windows, you should be running the Java 2 Windows 95/98/NT Production release - JDK 1.2 or later. For Solaris, you should run the Java 2 Solaris Production Implementation - JDK 1.2 or later.

You also need OpenGL support on your system to run Java 3D. Alternatively, Windows users can use DirectX, so long as you have Direct3D 8.0a or later. If you are using Windows95/NT or Windows NT, you can get the OpenGL libraries from ftp://ftp.microsoft.com/softlib/mslfiles/opengl95.exe. It will not run using Win32s. Implementations for OpenGL and Direct3D are available.

If you are using Solaris, you can download the files from http://www.sun.com/solaris/opengl. You must use OpenGL 1.1.1 with patch 106022-03 or later.

Most importantly, follow all the instructions included in the Java3D download to set everything up. Once you've done all of that, try compiling and running some of the examples included in the archive.

Other platforms will vary their requirements, but generally follow the same needs as here.

2. How do I get Java 3D to automatically install under JDK 1.3?

Paul Pantera from Sun has provided us with a very detailed explanation of how to set up your system for this. You can find it in the Quick Fix section of j3d.org.

3. Can't find javax.media.j3d.*, com.sun.j3d.utils or javax.vecmath

Normally you will only find these errors when running under Java Plugin. There is a known bug with Java Plugin with JDK 1.2 and 1.2.1 that causes the JAR files to be not found and causes the above exceptions

To fix this, you need to copy the JAR files from $jre.home/lib/ext to $jre.home/lib. Now your application will find the classes. Note that this effects anything installed as a standard extension, not just Java 3D.

From JDK 1.2.2 and later revisions, this is fixed.

If this still does not fix your problems and you are running on a Windows box. then look at your PATH setting. You have one of two options. Java installs java.exe and javaw.exe in your windows/system directory. These are completely useless as they don't find anything. You can either delete these completely or change your path to point to the JDK install directory before the windows system directory (not recommended because you might accidently prevent something else from running in the system area).

Finally, check to make sure your code is using the Java Plugin. If the applet is referenced with APPLET tags, then you will not be able to run Java 3D. It must be run through the HtmlConverter program supplied by Sun.

If all this fails you don't have Java 3D installed correctly or at all!

4. Exceptions

If you think you've set everything up correctly, but are still having problems, check the list of exceptions stack traces we've compiled to see the likely cause and its solution.

5. The "no J3D in shared library path" error

Java3D should automatically install itself in the correct places so that it will always find the classes. Unfortunately, sometimes this doesn't work because something else might be screwed up - such as OpenGL.

When installing J3D make sure that you give it the correct path for the JRE home. If you do not, then the system is unlikely to find the correct classes in your classpath. To check, look in the directory $JAVA_HOME/jre/lib/ext. In there you should find the following JAR files:

j3daudio.jar
j3dcore.jar
j3dutils.jar
vecmath.jar

If you are missing any of these, you may generate the error message.

For solaris users, David Thompson (davidt@chaos.lanl.gov) has posted the following hint:

It turns out that though the Creator software was properly installed, the OpenGL software was not. To check for the proper installation of the graphics packages on Solaris, see the web page: http://www.sun.com/software/graphics/OpenGL/Developer/verify_install.html#Verif-OGL

If you see nothing is returned by the check of openGL, you need to go through the install proceedure. Go to the web page: http://www.sun.com/software/graphics/OpenGL/1.1.2/dload_mailer.cgi

and download and install openGL. (See instructions on the web page) Next, restart your window server. (This can be done by logging out and then back in.) Then try to run the examples again and see if they work.

Another useful page, if there is a problem, is: http://www.sun.com/software/graphics/OpenGL/Developer/FAQ-1.1.2.html

6. Strange rendering results

If you're running under Solaris, check to be sure you're running OpenGL 1.1.1 with patch level 106022-03 or later. Java 3D requires OpenGL 1.1.1 under Solaris, and the patch corrects a rendering bug in vertex arrays, which is something Java 3D utilitizes.

If you're running under Windows, be sure that your display is set to at least 64K colors (more if possible).

7. Why does my screen flicker?

Effects Java 3D 1.2 only. Earlier versions do not have this problem.

In some JDK/Graphics card combination you will get a frame buffer without double buffer support. This is because the GraphicsConfigTemplate returned is not compatible with Canvas3D if we initialze Canvas3D in the explicit fashion (see below). The best way of overcoming this is to create the Canvas3D with the null parameter. Kelvin Chung from Sun's Java3D team supplies the following hint:

canvas = new Canvas3D(
  GraphicsEnvironment.getLocalGraphicsEnvironment().
    getDefaultScreenDevice().getDefaultConfiguration());

Or if you still want to do this yourself

   GraphicsConfigTemplate3D template = new GraphicsConfigTemplate3D();
   cfg = GraphicsEnvironment.getLocalGraphicsEnvironment().
       getDefaultScreenDevice().getBestConfiguration(template);
   canvas = new Canvas3D(cfg);

8. Out of memory problems

If you get an error message about your Java 3D program (or any Java program for that matter). The Java virtual machine allocates a certain amount of memory to use, and it's much less than people typically have on their systems. To increase this limit, use the -Xmx option when you run the program. For example, the following command will allow a maximum of 64 meg of space to be used by the JVM:

                java -Xmx64m program

9. How do I get Java 3D in fullscreen mode?

There are two ways of accomplishing this. The first is to use JDK 1.4 or later. These have API calls for creating fullscreen windows directly. If you need to use an earlier version of the JDK, then follow these instructions:

For DirectX 8.1, you can set the Java property, j3d.fullscreen to one of the following values:

• REQUIRED - fullscreen mode is required. Abort program if full screen mode cannot be initiated.
• PREFERRED - fullscreen mode is preferred. Try to initiate fullscreen mode but if that fails, use a regular window instead.
• UNNECESSARY - fullscreen is not necessary for this application.

For instance, to run the HelloUniverse example program in fullscreen mode if it is available, the following command would be used:

	java -Dj3d.fullscreen=PREFERRED HelloUniverse

For OpenGL, there is a workaround to make J3D look like it is operating in fullscreen by subclassing java.awt.Window. Essentially you create a new window instance that is exactly the same size as the current screen size. Window does not have all the borders that you normally get with Frame and Dialog.

  Toolkit tk = Toolkit.getDefaultToolkit();
  Dimension d = tk.getScreenSize();
  Frame f = new Frame();
  Window w = new Window(f);
  w.setSize(d);
  Canvas3D canvas = new Canvas3D();
  w.add(canvas);
  w.setVisible(true);

10. Where can I get the source to javax.media.j3d or other parts of Java3D?

As part of the java.net project site. Be aware of the licensing. The core APIs are not distributed under an Open Source license. The utility packages are available under a BSD-style license.

11. How do I get Java3D to run with IBM's JVM on Linux?

Java3D looks specifically for a library called libjawt.so which is not part of the IBM JVM or associated libraries. In order to make J3D work, you need to create a symbolic link to the IBM equivalent libawt.so. To do this, find the directory that has the libraries installed in it (typically IBMJava2-13/jre/bin), and type the command:

    ln -s libawt.so libjawt.so

If you are running IBM's release of JDK 1.4.2, it broke something in a different way to this fix. There is a missing or changed function call that is now causing Java3D to not run any more. We don't know of any fix for this currently other than using the Blackdown JVM rather than IBM's.

12. Why doesn't Canva3D work with JDK1.4?

There are some fundamental internal changes that to the way that the JDK describes window handles. They are not compatible and so Java3D will crash on startup. If you want to use JDK 1.4 with Java3D, you will need to use either Java3D 1.3 or 1.2.1_04 or later. 1.2.1_03 and earlier will crash your application.

13. Why doesn't Java3D work with JDK1.5 beta (Tiger)?

There was a bug in JDK 1.5 Beta 1 that meant the DLLs could not be found without explicitly setting the LD_LIBRARY_PATH environment variable (see Sun BugId : 4976297 - JAWT apps on Linux now have to set LD_LIBRARY_PATH to point to libmawt.so). This bug has apparently been fixed with beta 2.