# 3D graphics programming in Java: Part 2, Advanced Java 3D

Java 3D has the potential to allow Java programmers of all sorts to include vibrant 3D content in their applets and applications. This is fact, but not certainty, as Sun faces heavy competition from other technologies, especially OpenGL. Beyond the basics that every 3D API must provide, what does Java 3D have going for it?

Last month we began our exploration of Java 3D with static content and small scenes. This month we'll conclude our introduction by delving into loaders for larger scene graphs and giving our worlds behaviors and interactivity. We'll also discuss the interplay between Java 3D and VRML, review the performance characteristics of Java 3D, and set the stage for next month's look at Java OpenGL bindings.

## Java 3D transforms and placement

I received several reader questions about the placement of the 3D objects in last month's examples. One reader in particular asked why, when he modified the transform so the cube's z coordinate was positive, he could no longer see the cube. Let's reexamine the example code from last month's Example 3 to learn more about how things are situated in three dimensional space using Java 3D.

The critical line of code from this example is:

```
myTransform3D.setTranslation(new Vector3f(-0.5f,-0.5f,-2.3f));
```

The arguments in the `Vector3D` constructor are x, y, and z coordinates. The cube is placed by this transform at x = -0.5; y = -0.5; and z = -2.3 (in floating point values, hence the "f" suffixes).

It's critical to note that your viewing location can change. This is determined by the location of the associated `ViewPlatform`, which, in turn, is situated in the 3D world using the `TransformGroup` above it (actually, using a `Transform3D` node to transform the `TransformGroup` above it).

Also note that in Example 3, we don't move the `ViewPlatform`; we construct all of the view branch using the default constructors, which use an identity `Transform3D` node (more on identity later) in the `TransformGroup` above `ViewPlatform`. Thus, the `ViewPlatform` is located at x = 0.0; y = 0.0; and z = 0.0, the origin of the 3D coordinate system.

And finally, it's important to note that the coordinate system is aligned with your view into it. With the default view branch, the +x axis runs from left to right across the screen and the +y axis runs from bottom to top, which means, using the right-hand rule, that the +z axis runs out of the screen towards you. By default, your view into the world is looking in the -z direction.

Because you're "sitting" at the origin (the view platform is located at 0.0, 0.0, 0.0) looking in the negative-z direction, anything in the positive-z section of the 3D world is behind you and you can't see it. Don't you just love 3D! (See Resources for more information on `Transform3D`.)

## Exploring the com.sun.j3d class archives

Now, let's return to the issue of the contents of Sun's private jar files. Last month I briefly mentioned that Sun's Java 3D implementation installs both standard Java 3D classes (as specified in the Java 3D API specification) and nonstandard (Sun implementation-specific) classes. These classes are made available in one of several jar archives placed within the new Java 2 platform (formerly known as Java 1.2) extensions directory (see last month's column for more information on this). We discussed the standard classes and jars in sufficient detail last month, but we still have some ground to cover on the Sun-specific ones.

As a reminder, Sun's archives include:

• `j3daudio.jar`, which archives the `com.sun.j3d.audio` packages, described last month
• `j3dutils.jar`, which encapsulates a variety of Sun utility classes in 16 total packages and subpackages underneath `com.sun.j3d` (more details in a moment)
• `j3dutilscontrib.jar`, which archives useful utilities contributed by others to Sun's efforts (again, more details in a moment)

When you explode the `j3dutils.jar` archive, you see the following subpackages of `com.sun.j3d`:

• `audioengines`
• `audioengines.javasound`
• `loaders`
• `loaders.lw3d`
• `loaders.objectfile`
• `utils`
• `utils.applet`
• `utils.audio`
• `utils.behaviors`
• `utils.behaviors.interpolators`
• `utils.behaviors.mouse`
• `utils.behaviors.picking`
• `utils.geometry`
• `utils.image`
• `utils.internal`
• `utils.universe`

Likewise, exploding `j3dutilscontrib.jar` reveals these additional `com.sun.j3d` subpackages:

• `loaders`
• `loaders.vrmlfile`
• `utils`
• `utils.behaviors`
• `utils.behaviors.keyboard`
• `utils.font3d`
• `utils.trackers`

Now that you know the basic layout of Sun's utility class archives, you can delve into them more deeply if you need any of the functionality they provide. For instance, if you're looking to capture mouse events to control interpolated behaviors, you need to load in LightWave 3D content. And if you're interested in 3D font support, you should review `com.sun.j3d.utils.behaviors.mouse`, `com.sun.j3d.utils.behaviors.interpolators`, `com.sun.j3d.loaders.lw3d`, and `com.sun.j3d.utils.font3d` more closely.

Please note that while some documentation is provided for these packages in the general Java 3D documentation from Sun, the quality of documentation varies from package to package and from class to class. I recommend that you monitor the java3d-interest mailing list for information on the particular utility classes you need to use.

## Behaviors and interpolators

Interactivity results from being able to program an object to react to certain stimuli. In Java 3D, these behaviors are scheduled when the view platform crosses the stimulus bounds, a region of space defined by the programmer. Bounds assign a spatial scope to objects. There are bounds for both sounds and behaviors in Java 3D.

The advantage of requiring bounds for objects is that the runtime can safely disregard (not render) things that are out of bounds. If you build behaviors into your Java 3D applications, you will be required to set bounds in order to have the Java 3D runtime scheduler prepare your behaviors for execution. The scene graph includes a set of nodes for setting up and scheduling behaviors and bounds. In addition, several of the utilities described above help you to more easily deal with interactivity, including the aptly named "behaviors" subpackages.

Behaviors can be keyed to any number of Java events or user interactions. When a user hovers near a certain object, for instance, you can cause the object to move, change color, or otherwise exhibit behavior. (In this case, the stimuli would be the user's presence inside of a specified bounds, or region, of space.)

Many behaviors can be controlled using interpolators, objects that accept a range of values to provide a time-varying behavior. You can build your own interpolators if you like, but Java 3D's built-in interpolators and Sun's utilities should suffice for most of your needs. In this month's Example 4, we modify last month's Example 3 to make the word JavaWorld rotate.

```
001   /**
002    * constructContentBranch() is where we specify the 3D graphics
003    * content to be rendered.  We return the content branch group
004    * for use with our SimpleUniverse.  We have added a RotationInterpolator
005    * to Example03 so that in this case, our "JavaWorld" text rotates
006    * about the origin.  We have also removed the scaling and static
007    * rotation from the text, and the scaling from our ColorCube.
008   **/
009   private BranchGroup constructContentBranch() {
010     Font myFont = new Font("TimesRoman",Font.PLAIN,10);
011     Font3D myFont3D = new Font3D(myFont,new FontExtrusion());
012     Text3D myText3D = new Text3D(myFont3D, "JavaWorld");
013     Shape3D myShape3D = new Shape3D(myText3D, new Appearance());
014     Shape3D myCube = new ColorCube();
015
016     BranchGroup contentBranchGroup = new BranchGroup();
017     Transform3D myTransform3D = new Transform3D();
018     TransformGroup contentTransformGroup = new TransformGroup(myTransform3D);
020
021     Alpha myAlpha = new Alpha();
023     myAlpha.setLoopCount(-1);
024     RotationInterpolator myRotater =
025                       new RotationInterpolator(myAlpha,contentTransformGroup);
026     myRotater.setAxisOfRotation(myTransform3D);
027     myRotater.setMinimumAngle(0.0f);
028     myRotater.setMaximumAngle((float)(Math.PI*2.0));
029     BoundingSphere myBounds = new BoundingSphere();
030     myRotater.setSchedulingBounds(myBounds);
031     contentTransformGroup.setCapability(TransformGroup.ALLOW_TRANSFORM_WRITE);
033
035
036     myTransform3D.setTranslation(new Vector3f(-0.5f,-0.5f,-2.3f));
037     TransformGroup cubeTransformGroup = new TransformGroup(myTransform3D);
040
041     return(contentBranchGroup);
042   }
```

By default, behaviors have no scheduling bounds and are never scheduled. You must set scheduling bounds yourself to execute behaviors in Java 3D. It's also important to remember that even with nondefault bounds specified, your behaviors may not be executed if the view platform isn't within the bounded region. This is, of course, by design, but it can make for frustrating debugging experiences if you're not careful.

For instance, modifying only the z coordinate of our view platform location from

```
myViewTransform.setTranslation(new Vector3f(2.0f,0.0f,11.0f));
```

in Example 4 to

```
myViewTransform.setTranslation(new Vector3f(2.0f,0.0f,12.0f));
```

in Example 5, we no longer see the word JavaWorld rotating. Keep this in mind as you develop more complicated and interactive worlds.

## Reusing the world's 3D content

If you were limited to using only content you could manually code into your Java 3D applications, you would either limit yourself to small scene graphs with a few nodes, or relinquish any hope of sleeping ever again. Writing Java 3D code to create complex 3D worlds from scratch is certainly nontrivial. Realizing that such limits aren't good for the success of Java 3D (not to mention your sanity), Sun has made it easy to import from standard 3D file formats into Java 3D using loaders.

Put simply, a loader knows how to read content from a standard 3D file format -- say, for instance, Wavefront's Object file format (OBJ) -- then construct a Java 3D scene from it. There are a variety of loaders available on the Web, including several provided by Sun within the Java 3D release itself. All of them are documented at the Java 3D Loaders archive (see Resources). As of this writing, 17 publicly known Java 3D file loaders are currently available, supporting such common formats as AutoCAD's Drawing Interchange File (DXF), LightWave's Scene Format (LWS) and Object Format (LWO), 3D-Studio's 3DS, and application-specific formats like the Protein Data Bank's PDB.

The world is full of free or commercial archives of 3D content. So, given that loaders and content exist, how do you use them?

## Our first loader: Wavefront OBJ content using ObjectFile

Sun has included support for Wavefront's OBJ and LightWave's LightWave 3D file formats built into its implementation of Java 3D. Both formats are fairly prevalent in the modeling and animation community, and both are well specified and understood (again, please refer to the Loaders Archive URL for more information on these formats). I picked the OBJ format to provide a simple example of how to use a loader.

Wavefront OBJ is supported by Sun's `com.sun.j3d.utils.loaders.objectfile` package. The main class we will use to load and parse the content is `ObjectFile`, which encapsulates an OBJ file and provides methods to load its content into Java 3D. In the simplest case, we can load in OBJ content with a few lines of code in a modified `constructContentBranch()` method, as illustrated in Example 6:

Related:
Page 1
Page 1 of 3
``` ```