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:

• It provides a high-level, object-oriented view of 3D graphics. Java 3D accomplishes this in part by using a scene graph-based 3D graphics model. (We'll discuss this concept in more detail momentarily.) This approach is intended to help programmers without much graphics or multimedia programming experience use 3D in their applications. In stark contrast to lower-level, procedural 3D APIs like OpenGL, which are designed to optimize for the best possible speed and give programmers the greatest possible control over the rendering process, Java 3D is meant to be straightforward enough for every programmer to learn.
• If you don't need low-level access to rendering operations, Java 3D may be an option. Rendering access is limited to requests via attributes and capability bits, similar in form and function to Java 2D's rendering hints. (See Resources for links to my previous JavaWorld series on Java 2D, which included discussion and examples of 2D's rendering hints).
• Java 3D is optimized for speed where possible. The runtime uses rendering capability bits to optimize the scene graph for the fastest possible renders. This approach makes Java 3D more applicable to interactive graphics environments (games, simulations, low-latency situations) than to offline, high-quality graphics applications (like render farms).
• A large and growing number of 3D loaders are available to import content into the Java 3D runtime. Sun and the VRML Consortium (recently renamed the Web 3D Consortium) have made a Java 3D VRML97 file loader and browser freely available with code. The next installment in this series will explore Java 3D loaders in more detail.
• Java 3D requires vector math capabilities not available elsewhere in the Java platform. These math operations are currently located in the javax.vecmath package and may be moved into the core platform in the future.
• Java 3D supports a number of exotic devices (wands, data gloves, and headsets, for example). The com.sun.j3d.utils.trackers package included with Sun's implementation provides classes for Fakespace, Logitech, and Polhemus devices. These devices are not widely used outside the game and simulation development arenas, so information on them is rather sparse. Consequently, I will not discuss them in much greater detail in this series. However, if you are interested in finding out more about Java 3D device support, please refer to Sun's Java 3D sites and the Java 3D mailing list archive (both available from the main Sun Java 3D URLs included in the Resources below).

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

• Java 3D is a standard extension API. Java platform licensees are given the option to implement the API if they like, but they're not required to implement it. Java 3D's positioning as a standard extension runs the risk of reducing the portability of Java 3D code across platforms -- most vendors have to struggle to keep up with changes and additions to the core platform alone.
• Java 3D has severe availability constraints. These are the result of Java 3D's status as an extension API. The only major vendor currently providing a Java 3D implementation is Sun, with its implementations for Solaris and Win32. Compared to OpenGL, which is available for every flavor of Unix, Windows, and many other operating systems, the cross-platform portability of Java 3D code looks questionable.
• Along with software availability problems come documentation deficits. Sun is making a valiant effort to provide developer training and support for Java 3D, but it is still falling short compared to the rest of the industry's efforts in documenting OpenGL and its use. The OpenGL Consortium's Web site is far deeper and broader than anything Sun has managed to put together for Java 3D so far. This is not a minor point: the relative complexity of 3D graphics APIs make good documentation a necessity.
• Java 3D hides rendering-pipeline details from the developer. Because Java 3D is a high-level API, it intentionally hides details of the rendering pipeline from the developer, which makes it unsuitable for a significant number of problems where such details are important. Game developers, in particular, often use low-level access to the graphics system and may find it difficult handing over the reigns to the Java 3D runtime.
• Java 3D components are heavyweight. That is, they have a native (non-Java) peer that actually does the rendering. This can complicate your GUI development if you use Java Swing and its all-Java, or lightweight, components. There are some special workarounds, but in general, lightweight and heavyweight components don't mix well in the same container objects and windows. More information on lightweight-heavyweight component problems is available from the Resources at the end of this article.

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:

• Java 3D runtime, Be sure to choose the OpenGL version of Java 3D for your platform (I'm using Win32). The released Win32 Java 3D for development (select JDK option) is version 1.1, in java3d1_1-win32-opengl-jdk.exe, and weighs in at 3.2MB.
• OpenGL 1.1, bundled with Windows NT 4.0 and Windows 95 OSR 2. If you have the OSR 1 release of Windows 95, though, you can download OpenGL support. The latest Windows 95-OpenGL 1.1 implementation is available from Microsoft as opengl95.exe, and is approximately 0.5 MB.
• JDK 1.2, available from Sun. Note that JDK 1.2 corresponds directly to the Java 2 platform. (Sun renamed Java 1.2 to Java 2 at the last minute before release, in a brilliant displaying of marketing and licensing prowess.) Note also that Java 3D requires the 1.2 platform, and Sun has stated on the java3d-interest mailing list that it has no interest in decoupling the API and trying to make it available with previous platform releases.

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:

• j3dcore.jar -- Contains class files for the public Java 3D package javax.media.j3d.
• vecmath.jar -- Contains classes for javax.vecmath.

Private archives include:

• j3daudio.jar -- Archives the com.sun.j3d.audio classes, which build support for spatialized audio on top of a custom copy of the Java portion of the Java Sound, Headspace-based audio engine, debuting in Java 2.
• j3dutils.jar -- Encapsulates a variety of Sun utility classes in 16 total packages and subpackages underneath com.sun.j3d. I will dig deeper into these packages in the next installment of our Java 3D discussion.

  Please note that in theory you may instantiate and call methods on any of the classes provided in nonstandard packages like com.sun, but caveat emptor: There is no guarantee they will be available on the platform your code executes on. In current practice, Java 3D is only available from Sun, so a lot of developers do, in fact, use classes within Sun's private archives. You should be aware of the potential portability trade-off entailed in choosing to do so.

  There's no magic in how the public and private Java 3D classes interface with system resources, either. Sun installs native libraries in J3D.dll and j3daudio.dll under the /jre/bin/ directory. The Java 3D classes use native methods to call these DLLs and interface with the Win32 platform and OpenGL rendering library. (Similar libraries exist for Solaris implementations.)

  One final note on installation: The OpenGL rendering pipeline is designed to take advantage of OpenGL acceleration hardware to speed up your graphics applications. For the purposes of this column, though, you should be able to experiment with the examples without any special hardware. (In fact, I'm developing all the examples on a Pentium 150MHz MMX laptop with no OpenGL acceleration hardware.) If you're interested in acceleration cards, you should refer to the OpenGL website or the Java 3D mailing list (see Resources) for more information. I plan to include a little more information in the future installments on Java 3D and Java-OpenGL, too.