Organizing the Scene Graph Through BranchGroups

To repeat, in Listing 11.1 we instantiate two separate BranchGroup objects and add them to the Locale object; one to represent the content subgraph and the other to represent the view subgraph. You are urged to get used to this structure because it is always present.

In the vast majority of cases, there is only one Locale. (Occasionally, there are more than one.) In all cases, there is one and only one VirtualUniverse. Thus, “the trunk of the tree” of a Java 3D scene graph is fundamentally the same for every program.

From this discussion, you can see that the top operating level for the developer is at the BranchGroup level. You will be well served in understanding and thinking of the Java 3D program in this way. To gain insight into any Java 3D example, the programmer should find and chart the BranchGroups. This approach will permit the programmer to “see the forest from the trees” in any application.

The BranchGroup has additional properties that separate it from the other subclasses of Group. First, BranchGroups are the only objects that can be detached from a live scene. Also, a BranchGroup is the only object that can be compiled.

When writing Java 3D programs, we will always want to create at least one scene graph and one view graph. Keep this in mind as we continue our discussion.

We will now discuss in detail the substructures of these two important branches:

Content graph

View graph

The Content Graph

The majority of the work in developing a Java 3D application typically occurs in creating the content graph. To create the content graph, the programmer will write a method that returns a BranchGroup. The BranchGroup returned from this method is then added to a Locale object.

After the BranchGroup is added to the Locale object, it is considered “live” and will go into a kind of continuous render mode. This is called “retained mode” versus the alternative “immediate mode.”

The purpose of the content or scene BranchGroup is to glue together the scene elements and those operations performed on them.

The building of a content graph is illustrated with the following simple example.

Imagine that we want to develop a 3D scene with a single object in the center. In this case, our method to return a BranchGroup will be trivial. Because the content is so simple, most of the work will actually be in setting up the program outside of creating the content subgraph. You should note that this is the opposite of the usual case. In BasicReceipeJ3D, in Listing 11.2, we add a simple box to the content subgraph as seen in Figure 11.2.

Regardless, the structure of the program isn't too difficult. In the application's constructor, we create an instance of VirtualUniverse and Locale. After this is done, we are free to call our custom method for creating the content BranchGroup and add that BranchGroup to the Locale. Part 2 of the code from our BasicRecipeJ3D.java example is shown in Listing 11.2.

Listing 11.2 BasicRecipeJ3D.java Part 2 of 4

public void BasicRecipeJ3D()
. . .

BranchGroup scene = createScene();
locale.addBranchGraph(scene);

. . .
}

The method to create our content subgraph is

public BranchGroup createScene() {

  // Create the root of the branch graph; this will be returned
  BranchGroup objRoot = new BranchGroup();

  //Create an appearance object to apply to the geometry

  Appearance app = new Appearance();
  Color3f red = new Color3f(1.f, 0.f, 0.f);
  Color3f black = new Color3f(0.f, 0.f, 0.f);
  Color3f white = new Color3f(1.f, 1.f, 1.f);

  app.setMaterial(new Material(red, black, red, white, 100.0f));

  //Create some geometry
  Box box = new Box(1.f,1.f,1.f, app);

  // Create a simple shape leaf node, add it to the scene graph.
 objRoot.addChild(box)
  return objRoot;
}

Building the content graph is the focus of this chapter, and we will explore the range of options throughout. For now, it is enough to realize that there are a large number of ways in which we can enhance our content subgraph. One thing that we can do in our createScene() method is import prebuilt objects (detailed later in this chapter and in Chapter 12) from other software packages, such as 3D Studio or VRML 2.0 and most recently X3D (so called VRML on steroids). We can also use this method to add lights, specify animation behaviors, and place textures on objects in the scene.

If the objects within the environment are complex at all, we will want to create external classes to load them. For example, we develop a variety of geometric primitives in the section “Making Simple Geometry with the Java 3D Utilities.” Objects from these classes are instantiated and added to the scene graph in the createScene() method.

BasicRecipeJ3D is used throughout the rest of this chapter as a way to quickly view content. You will be asked to comment and uncomment sections of the createScene() method. As we develop classes and then build applications around those classes, we will largely abandon BasicRecipeJ3D. However, it is recommended that the programmer keep the class handy for future applications because it is a quick way to view classes and test code. I recommend that the reader and developer write a demo frame class as an exercise in order to become familiar with the interaction of Java 3D and Java.

The key information to take away from this discussion is that if we plan to create a 3D world, we will need a content subgraph to add to the Locale object. You can do this by writing a method similar to the previous createScene() method and use it to return a BranchGroup that is added to the scene graph. Later, you will see that BranchGroups can contain other Group objects that further allow the programmer to organize the scene graph in an intelligent manner.

With this elementary concept in hand, we move on to the second major branch of the scene graph, the view graph.

The View Graph

Now that we have a way to bring content into our scene graph, we need a way to control how the content is viewed. For now, we will leave aside the technical details of the Java 3D viewing model in order to continue with our basic recipe for creating a Java 3D program; however, moving beyond a rudimentary understanding of Java 3D will require an in-depth knowledge of the view model (provided in Chapter 13).

The view graph, like the content graph, is contained in a BranchGroup object. Therefore, we will need to add the elements of our view graph to a BranchGroup and add the BranchGroup to the same (usually) Locale to which we added our content subgraph.

Remember that the BranchGroup represents major branches in our scene graph tree. In most cases, the view graph is considerably simpler than the content graph; however, this need not always be the case. It is possible to add geometry and other objects to the view graph just as in the scene graph. For now, we will focus on the common elements that form the view graph.

The key element that we will add to the view BranchGroup is a ViewPlatform object. For the sake of the immediate discussion, you can consider the ViewPlatform as a type of camera mounted on a platform but, as will be discussed in Chapter 12, this is a gross oversimplification of the ViewPlatform's role. Indeed, the sophistication of the ViewPlatform is one of the major aspects of Java 3D that separates it from other 3D APIs. Advanced use of the Java 3D view model is discussed in Chapter 13.

Listing 11.3 illustrates the creation of our view graph.

Listing 11.3 BasicRecipeJ3D.java Part 3 of 4

. . .
BranchGroup viewgraph = createView();
locale.addBranchGraph(viewgraph);. . .

public BranchGroup createView() {
  //Create the root of the view graph to return
  BranchGroup viewRoot = new BranchGroup();

  //Create the ViewPlatform object
  ViewPlatform vp = new ViewPlatform();

  //Add the ViewPlatform object to the BranchGroup and return
  viewRoot.add(vp);
  return viewRoot;
}

In Listing 11.3, several objects that are part of the view model are instantiated. Specifically, these objects are PhysicalBody and PhysicalEnvironment. We defer coverage of these objects until Chapter 13 and encourage you to continue without worrying about the details. The important point here is that there is a separate BranchGroup for the view graph and that the view graph contains a ViewPlatform object that can be manipulated by the application.

At this point, you shouldn't be discouraged by the rather unsophisticated results of this program. Much more attractive geometry and materials will be used later. The purpose of this first program is to show the programming paradigm in the simplest possible fashion.