Recipe for Writing a Java 3D Application

We are now going to describe the basic paradigm for writing a Java 3D application. To repeat, most of the programming effort goes into creating one or more BranchGroups for holding content. BranchGroups are the fundamental organizational structure to use when building the scene graph and are a mandatory element of all Java 3D programs.

Required Ingredients

All Java 3D programs have a basic set of ingredients that must be present in order to do anything. The classes for these objects are listed in Table 11.2.

Canvas3D—a Place to Draw 3D Scenes

Even though it isn't absolutely mandatory that a Java 3D application has a rendering area on the screen, the cases in which an application doesn't are extremely rare.

The Canvas3D class provides a Component on which the 3D scene is rendered. Because Canvas3D is an extension of Canvas, it can be added to containers just like the Graphics2D object we used in Chapter 3, “Graphics Programming with the Java 2D API.” It is therefore present in practically all Java 3D applications.

A Canvas3D object can be used for both onscreen and offscreen rendering. Onscreen and offscreen Canvas3Ds behave somewhat differently from each other. Onscreen Canvas3Ds are rendered automatically and continuously if they are attached to an active View object. This isn't true of offscreen Canvas3Ds, which are only rendered after a call to the renderOffScreenBuffer() method. A second difference is that onscreen Canvas3Ds can be either single- or double-buffered, whereas offscreen Canvas3Ds are only single-buffered. Finally, offscreen Canvas3Ds are only available as monoscopic entities. (Monoscopic and stereoscopic viewing are covered in Chapter 13, “The Java 3D View Model.”)

First Programming Example

Listing 11.1, BasicRecipeJ3D.java, demonstrates the structure of a program that contains the elements listed in Table 11.2 as well as an instantiation of the Canvas3D object.

The first three of the components in Table 11.2 will be covered in more detail later. For now, we will focus on the critical fourth element in Table 11.2, the BranchGroup.

Two fundamental parts of the scene graph are contained in BranchGroups: the content subgraph and the view subgraph. These two objects are instantiated and added to the Locale object in the last four lines of Listing 11.1.

Listing 11.1 BasicRecipeJ3D.java Part 1 of 4

public BasicRecipeJ3D() {
   setLayout(new BorderLayout());

   GraphicsConfigTemplate3D g3d = new GraphicsConfigTemplate3D();
   GraphicsConfiguration gc =
      GraphicsEnvironment.getLocalGraphicsEnvironment(). getDefaultScreenDevice().
getBestConfiguration(g3d);

   Canvas3D c = new Canvas3D(gc);
   add("Center", c);
   universe = new VirtualUniverse();
   locale = new Locale(universe);

   BranchGroup scene = createSceneGraph();
   BranchGroup view = createViewGraph();

   locale.add(scene);
   locale.add(view);
}
public static void main(String[] args) {
    new MainFrame(new VoxelModeler(), 256, 256);
 }
}

In addition to the creating of the view and content subgraphs, there are several important aspects of the previous code to examine. First is the creation of the Canvas3D object, c. Notice that the Canvas3D constructor requires a GraphicsConfiguration object. The GraphicsConfiguration is an object of general use in Java and encapsulates information about the graphics and printer devices on a particular platform. More information about the GraphicsEnvironment, GraphicsDevice, and GraphicsConfiguration objects is provided in Chapter 2, “Imaging and Graphics on the Java Platform.” To get a GraphicsConfiguration object for 3D operations, we must also use the GraphicsTemplate3D class to create an additional object that is used for setting 3D graphics defaults.

Also, note the somewhat unusual call to the MainFrame class. MainFrame is a utility class that extends the Applet class and is provided in

com.sunj3d.utils.applet.MainFrame;

The purpose of the MainFrame class is to allow the class (in the preceding case, our BasicRecipeJ3D class) to be run as either a standalone application or as an applet.

Finally, we add the scene and view subgraphs to the scene graph superstructure object Locale.