3D Graphics Programming in Java, Part I

Author: by Bill Day

In order to build a true Java platform, Sun realized early on that it needed to fill out the API picture beyond the limited functionality available in the Java 1.0 core platform. Sun has grown the core a great deal with the Java 1.1 and Java 2/JDK 1.2 releases, but there are still some pieces missing from the Java puzzle.

Sun and its partners developed the Java Media and Communication APIs to provide the missing multimedia programming pieces. Two of the biggest pieces, 2D and 3D graphics, are targeted with the Java 2D and 3D APIs, respectively. Java 3D has been released as an Extension API, providing 3D graphics support for the newly released Java 2/JDK 1.2 platform.

Java 3D is meant to give Java developers the ability to write applets and applications that provide three dimensional, interactive content to users. Sun has some heavy competition from other 3D graphics technologies in this arena, and Java 3D has an uphill battle ahead of it if it is to defeat the incumbent graphics standard, OpenGL.

I will introduce Java 3D and Java-OpenGL in three articles over the month. I will also demonstrate using VRML in Java 3D with VRML97 content loaders and the Java 3D VRML97 browser. I will follow the Java 3D and VRML articles with one on using Java-to-OpenGL bindings.

Pros and Cons of Java 3D

This issue we begin our tour of 3D graphics APIs for Java by exploring Java 3D. We'll start by discussing some of the API's major strengths and weaknesses.

Selling points for Java 3D:

Java 3D has a lot of pros, but what about the cons? They include:

Installing Java 3D

Now that we understand the major features and constraints of Java 3D, let's get ready to try out some example code.

Java 3D is available for Win32 and Solaris. The more mature of Sun's Java 3D implementations is built on top of OpenGL. An alpha-quality Direct3D implementation is also available for Win32. All require Java 2/JDK 1.2. Sun released the final Java 3D implementation shortly after it released JDK 1.2, so that the released Java 3D requires the released Java 2/JDK 1.2 or future releases to execute.

A slightly confusing aside: Sun released Java 3D 1.0 alpha implementations, which corresponded to the Java 3D 1.0 API, but it never released anything beyond alpha for the 1.0 API. Sun then modified the API, releasing the modified version as the Java 3D 1.1 API. This version was followed with releases of what it called 1.1 beta implementations, two total. Sun then released a final Java 1.1 API and implementation shortly after the final release of the Java 2/JDK 1.2 platform. Hopefully, the API has stabilized and won't be revved, but let the buyer beware.

Because we will be covering Java OpenGL bindings in a future article, I have decided to economize and use the OpenGL version of Java 3D in these installation instructions too. If you install the OpenGL version to use with these Java 3D examples, you will have the rendering libraries you need for the Java-OpenGL examples to come later.

The software components you need to use Java 3D are:

Optionally, you may also want to download the Java 3D documentation and example code. Both are available from the same link as the Java 3D runtime.

Please note that you are no longer required to set the CLASSPATH environment variables in order for your Java or Appletviewer executables to find extension libraries. With Java 2/JDK 1.2, Sun finally created a standard extension directory. This directory is located at /jre/lib/ext/ within your JDK installation directory. For instance, on my system, JDK 1.2 is installed at:

C:\jdk1.2\

and the standard extension directory is at:

C:\jdk1.2\jre\lib\ext\

All extension libraries should place their jar archives into this extensions directory at install-time, and all standard JDK tools know to search here for needed class files.

For Sun's Java 3D, these archives include both public (documented in the Java 3D API specification) and private (Sun implementation-specific) classes. Public class archives include:

Private archives include:

Constructing the view branch of the scene

As I noted earlier, one of the biggest strengths of the scene graph graphics model is that it allows inexperienced graphics programmers to add 3D to their applications. Traditionally, 3D programmers have had to specify where and how individual lines or other graphics primitives are to be drawn. Using a scene graph, however, the programmer simply creates a tree-like structure containing nodes that represent objects to be rendered as well as rendering instructions (such as where the viewpoint displayed to the monitor is located, physical geometry of the 3D world the programmer is creating, and relative distances between things).

In Java 3D, there are two major portions, or branches, to this tree: the view branch and the content branch. The content branch contains nodes describing the actual objects you want to render, including how to draw them, how to color them, textures to place on the primitives, how the objects are arranged in space, and how the objects should behave interactively. The view branch contains everything else, but in practice this branch is actually quite small compared to the content branch. View branches will often contain only a few nodes, while content branches may contain thousands for complicated 3D worlds.

Example 1 (please refer to Resources for the URL of the complete example code archive) provides a simple example for creating a Java 3D scene graph. We see how to use the heavyweight Canvas3D component within a Frame container, how to create the view branch of the graph, and how to attach a View to it. The content branch portion is left empty, so that we render an empty universe.

001 //Comment out the following package statement to compile separately.
002 package com.javaworld.media.j3d;
003
004 import java.awt.*;
005 import java.awt.event.*;
006 import javax.media.j3d.*;
007
008 public class Example01 extends Frame {
009 /**
010 * Instantiates an Example01 object.
011 **/
012 public static void main(String args[]) {
013 new Example01();
014 }
015
016 /**
017 * The Example01 constructor sets the frame's size, adds the
018 * visual components, and then makes them visible to the user.
019 *
020 * We place a Canvas3D object into the Frame so that Java 3D
021 * has the heavyweight component it needs to render 3D
022 * graphics into. We then call methods to construct the
023 * View and Content branches of our scene graph.
024 **/
025 public Example01() {
026 //Title our frame and set its size.
027 super("Java 3D Example01");
028 setSize(400,300);
029
030 //Here is our first Java 3D-specific code. We add a
031 //Canvas3D to our Frame so that we can render our 3D
032 //graphics. Java 3D requires a heavyweight component
033 //Canvas3D into which to render.
034 Canvas3D myCanvas3D = new Canvas3D(null);
035 add("Center",myCanvas3D);
036
037 //Turn on the visibility of our frame.
038 setVisible(true);
039
040 //We want to be sure we properly dispose of resources
041 //this frame is using when the window is closed. We use
042 //an anonymous inner class adapter for this.
043 addWindowListener(new WindowAdapter()
044 {public void windowClosing(WindowEvent e)
045 {dispose(); System.exit(0);}
046 }
047 );
048
049 //Now that we have our Frame and Canvas3D, we are ready
050 //to start building our scene graph. We need to construct
051 //both a view branch and a content branch. In order to
052 //actually use our view branch, we also need to construct
053 //a View and connect it to our view branch's ViewPlatform.
054 View myView = constructView(myCanvas3D);
055 Locale myLocale = constructViewBranch(myView);
056 constructContentBranch(myLocale);
057 }
058
059 /**
060 * constructView() takes a Canvas3D reference and constructs
061 * a View to display in that Canvas3D. It uses the default
062 * PhysicalBody and PhysicalEnvironment (both required to be
063 * set or else the 3D runtime will throw exceptions). The
064 * returned View is used by constructViewBranch() to attach
065 * the scene graph's ViewPlatform to a Canvas3D for rendering.
066 *
067 * @see constructViewBranch(View)
068 **/
069 private View constructView(Canvas3D myCanvas3D) {
070 View myView = new View();
071 myView.addCanvas3D(myCanvas3D);
072 myView.setPhysicalBody(new PhysicalBody());
073 myView.setPhysicalEnvironment(new PhysicalEnvironment());
074 return(myView);
075 }
076
077
078 /**
079 * constructViewBranch() takes as input a View which we
080 * attached to our Canvas3D in constructView(). It constructs
081 * a default view branch for the scene graph, attaches
082 * the View to the ViewPlatform, and returns a reference to
083 * our Locale for use by constructContentBranch()
084 * in creating content for our scene graph.
085 *
086 * @see constructView(Canvas3D)
087 * @see constructContentBranch(Locale)
088 **/
089 private Locale constructViewBranch(View myView) {
090
091 //First, we create the necessary coordinate systems
092 //(VirtualUniverse, Locale), container nodes
093 //(BranchGroup, TransformGroup), and platform which
094 //determines our viewing position and direction (ViewPlatform).
095 VirtualUniverse myUniverse = new VirtualUniverse();
096 Locale myLocale = new Locale(myUniverse);
097 BranchGroup myBranchGroup = new BranchGroup();
098 TransformGroup myTransformGroup = new TransformGroup();
099 ViewPlatform myViewPlatform = new ViewPlatform();
100
101 //Next, we insert the platform into the transform group,
102 //the transform group into the branch group, and the branch
103 //group into the locale's branch graph portion of the
104 //scene graph.
105 myTransformGroup.addChild(myViewPlatform);
106 myBranchGroup.addChild(myTransformGroup);
107 myLocale.addBranchGraph(myBranchGroup);
108
109 //Finally, we attach our view to the view platform and we
110 //return a reference to our new universe. We are ready to
111 //render 3D content!
112 myView.attachViewPlatform(myViewPlatform);
113 return(myLocale);
114 }
115
116 /**
117 * constructContentBranch() is where we specify the 3D graphics
118 * content to be rendered into the Locale referenced
119 * in the passed parameter. Nothing is currently specified, so we
120 * render an empty universe.
121 *
122 * @see constructViewBranch(View)
123 **/
124 private void constructContentBranch(Locale myLocale) {
125 //Insert content to be rendered here.
126 }
127 }

Placing Content Into The Java 3D Scene Graph

Now, let's provide some content to be rendered. We'll start with static content: In our next installment, we'll add interactivity.

One interesting thing to note about Java 3D is that it does not provide primitives like spheres or cubes. The designers of the API chose to instead provide robust support for things like GeometryArrays, so that developers could build up graphics primitives while allowing the Java 3D runtime to optimize as much as possible for speed. The astute observer will note that the primitives provided in Java 3D closely map to those provided in OpenGL, no surprise considering the layering of Java 3D on top of OpenGL.

One result of this design decision is that you will either have to spend a lot of time creating primitives over and over again, or you will need to use a primitive library built for Java 3D.

For Example 2 (see Resources for code archive), we sidestep the issue by rendering a three dimensional text string. Java 3D builds on top of the new text support provided in Java 2D (please refer to the listing of my JavaWorld columns in the Resources for more information on Java 2D and text).

Using the 3D text support, our updated constructViewBranch() method is:

Our universe is empty no more!

Using Sun Utility Classes to Make Your Code Simpler

You may have looked at all of the set-up code in our first two examples above and wondered, Why do we have to make so many redundant method calls each time we use Java 3D? The answer is, we don't if we're willing to use Sun utility classes (or write our own).

Sun has provided a large number of utility classes to take some of the burden off of the developer. Assuming you can put up with the portability restrictions mentioned previously, these utilities can take care of simple view branch construction for you. They also provide a library of primitive shapes that you can use directly, rather than constructing objects from the smallest fragments each time.

Example 3 (see Resources for code) illustrates the use of SimpleUniverse and ColorCube utilities. Please refer to the complete source code listing for the import statements and additional information on these utilities.

We're Just Dipping Our Toes In…

A vast amount of capability, and seeming complexity, lurks beneath the calm surface of the Java 3D sea.This article has shown you how to dip your toes in and go for a short swim.

Next week we will continue our exploration of Java 3D. I will discuss loading VRML and other 3D content into Java 3D. I'll also discuss some of the general performance issues at work under the covers in Sun's Java 3D implementation. In the installment after that, I'll compare and contrast Java OpenGL bindings with Java 3D.

Resources

Bill Day is a software engineer at Silicon Graphics Computer Systems and an ACM Distinguished Lecturer. Bill writes the monthly technical column Media Programming for JavaWorld magazine and is currently authoring a book entitled Java Media Players for O'Reilly & Associates.