Tutorial Java3D Capitulo 1 - Iniciando, Notas de estudo de Análise de Sistemas de Engenharia

Baixe Tutorial Java3D Capitulo 1 - Iniciando e outras Notas de estudo em PDF para Análise de Sistemas de Engenharia, somente na Docsity!

tutorial v1.5 (Java 3D API v1.1.2)

Getting Started with

the Java 3D

API

Chapter 1

Dennis J Bouvier

K Computing

Getting Started with Java 3D

© 1999 Sun Microsystems, Inc. 2550 Garcia Avenue, Mountain View, California 94043-1100 U.S.A

All Rights Reserved.

The information contained in this document is subject to change without notice.

SUN MICROSYSTEMS PROVIDES THIS MATERIAL "AS IS" AND MAKES NO WARRANTY OF ANY KIND, EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. SUN MICROSYSTEMS SHALL NOT BE LIABLE FOR ERRORS CONTAINED HEREIN OR FOR INCIDENTAL OR CONSEQUENTIAL DAMAGES (INCLUDING LOST PROFITS IN CONNECTION WITH THE FURNISHING, PERFORMANCE OR USE OF THIS MATERIAL, WHETHER BASED ON WARRANTY, CONTRACT, OR OTHER LEGAL THEORY).

THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY MADE TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THE PUBLICATION. SUN MICROSYSTEMS, INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR PROGRAM(S) DESCRIBED IN THIS PUBLICATION AT ANY TIME.

Some states do not allow the exclusion of implied warranties or the limitations or exclusion of liability for incidental or consequential damages, so the above limitations and exclusion may not apply to you. This warranty gives you specific legal rights, and you also may have other rights which vary from state to state.

Permission to use, copy, modify, and distribute this documentation for NON-COMMERCIAL purposes and without fee is hereby granted provided that this copyright notice appears in all copies.

This documentation was prepared for Sun Microsystems by K Computing (530 Showers Drive, Suite 7-225, Mountain View, CA 94040, 770-982-7881, www.kcomputing.com). For further information about course development or course delivery, please contact either Sun Microsystems or K Computing.

Java, JavaScript, Java 3D, HotJava, Sun, Sun Microsystems, and the Sun logo are trademarks or registered trademarks of Sun Microsystems, Inc. All other product names mentioned herein are the trademarks of their respective owners.

Getting Started with Java 3D

The Java 3D Tutorial 1-ii

Getting Started with Java 3D

The Java 3D Tutorial 1-iii

Code Fragments

Code Fragment 1-1 Class HelloJava3Da..............................................................................................1- Code Fragment 1-2 Method createSceneGraph for Class HelloJava3Da ...............................................1- Code Fragment 1-3 Main() Method of HelloJava3Da Invokes MainFrame............................................1- Code Fragment 1-4 Import Statements for HelloJava3Da.java..............................................................1- Code Fragment 1-5 One Rotation in the Content Branch Graph............................................................1- Code Fragment 1-6 Two Rotation Transformations in HelloJava3Db ...................................................1- Code Fragment 1-7 createSceneGraph method with RotationInterpolator Behavior...............................1- Code Fragment 1-8 Content Branch for Rotated Spinning ColorCube of HelloJava3Dd........................1-

1

Getting Started

T(dx, dy, dz) =

1 0 0 dx 0 1 0 dy 0 0 1 dz 0 0 0 1

Chapter Objectives

After reading this chapter, you will:

• Be able to explain in general terms what Java 3D is
• Be able to describe the basic structure of Java 3D programs
• Recognize many classes from the Java 3D API
• Be able to write some simple animated Java 3D programs

he Java 3D API is an interface for writing programs to display and interact with three-dimensional graphics. Java 3D is a standard extension to the Java 2 JDK. The API provides a collection of high-level constructs for creating and manipulating 3D geometry and structures for rendering that geometry. Java 3D provides the functions for creation of imagery, visualizations, animations, and interactive 3D graphics application programs.

1.1 What is the Java 3D API?

The Java 3D API is a hierarchy of Java classes which serve as the interface to a sophisticated three- dimensional graphics rendering and sound rendering system. The programmer works with high-level constructs for creating and manipulating 3D geometric objects. These geometric objects reside in a virtual universe, which is then rendered. The API is designed with the flexibility to create precise virtual universes of a wide variety of sizes, from astronomical to subatomic.

Despite all this functionality, the API is still straightforward to use. The details of rendering are handled automatically. By taking advantage of Java threads, the Java 3D renderer is capable of rendering in parallel. The renderer can also automatically optimize for improved rendering performance.

A Java 3D program creates instances of Java 3D objects and places them into a scene graph data structure. The scene graph is an arrangement of 3D objects in a tree structure that completely specifies the content of a virtual universe, and how it is to be rendered.

C H A P T E R

T

Java 3D programs can be written to run as stand alone applications, as applets in browsers which have been extended to support Java 3D, or both^1.

(^1) Browser support for Java 3D is available through the Java Plugin, which can be downloaded from java.sun.com.

All of the example programs in this tutorial are written as applications.

1.2 The Java 3D API

Every Java 3D program is at least partially assembled from objects from the Java 3D class hierarchy. This collection of objects describes a virtual universe , which is to be rendered. The API defines over 100 classes presented in the javax.media.j3d package. These classes are commonly referred to as the Java 3D core classes.

There are hundreds of fields and methods in the classes of the Java 3D API. However, a simple virtual universe that includes animation can be built with only a few classes. This chapter describes a minimal set of objects and their interactions to render a simple virtual universe.

This chapter includes the development of one simple but complete Java 3D program called HelloJava3D, which displays a rotating cube. The example program is developed incrementally, and presented in multiple versions, to demonstrate each part of the Java 3D programming process. All of the programs used in this tutorial are available electronically. See the "Getting This Tutorial" section in the Preface for more information.

In addition to the Java 3D core package, other packages are used in writing Java 3D programs. One such package is the com.sun.j3d.utils package that is commonly referred to as the Java 3D utility classes. The core class package includes only the lowest-level classes necessary in Java 3D programming. The utility classes are convenient and powerful additions to the core.

The utility classes fall into four major categories: content loaders, scene graph construction aids, geometry classes, and convenience utilities. Future functionality, such as nurbs, likely would be added as utility classes, not in the Java 3D core package. Some utility classes may be moved to the core package in future versions of the Java 3D API.

Using utility classes significantly reduces the number of lines of code in a Java 3D program. In addition to the Java 3D core and utility class packages, every Java 3D program uses classes from the java.awt package and javax.vecmath package. The java.awt package defines the Abstract Windowing Toolkit (AWT). AWT classes create a window to display the rendering. The javax.vecmath package defines vector math classes for points, vectors, matrices, and other mathematical objects.

In the rest of the text, the term visual object is used to refer to an ‘object in the scene graph’ (e.g., a cube or a sphere). The term object is used only to refer to an instance of a class. The term content is used to refer to visual objects in a scene graph as a whole.

1.3 Building a Scene Graph

A Java 3D virtual universe is created from a scene graph. A scene graph is created using instances of Java 3D classes. The scene graph is assembled from objects to define the geometry, sound, lights, location, orientation, and appearance of visual and audio objects.

VirtualUniverse

Locale

Group

Leaf

NodeComponent

other objects

parent-child link

reference

Nodes and NodeComponents (objects) Arcs (object relationships)

Figure 1-1 Symbols Representing Objects in Scene Graphs

Each of the symbols shown on the left-hand side of Figure 1-1 represents a single object when used in a scene graph. The first two symbols represent objects of specific classes: VirtualUniverse and Locale. The next three symbols on the left represent objects of the Group, Leaf, and NodeComponent classes. These three symbols are often annotated to indicate the subclass of the specific object. The last symbol on the left is used to represent any other class of object.

The solid arrow symbol represents a parent-child relationship between two objects. The dashed arrow is a reference to another object. Referenced objects can be shared among different branches of a scene graph. An example of a simple scene graph is shown in Figure 1-2.

BranchGroup Nodes

VirtualUniverse

BG

TG TransformGroup Node

View Platform

BG

Appearance Geometry

S

Locale

View Canvas3D Screen3D

Physical Body Physical Environment

Shape3D node

Node Components

Figure 1-2 First Scene Graph Example

It is possible to create an illegal scene graph. An example illegal scene graph is shown in Figure 1-3. The scene graph depicted in Figure 1-3 is illegal because it violates the properties for a DAG. The problem lies only with the two TransformGroup objects having the same Shape3D leaf object as children. Remember a Leaf object may have only one parent. In other words, there can only be one path from a Locale object to a leaf (or one path from a leaf to a Locale).

You may think the structure shown in Figure 1-3 defines three visual objects in a virtual universe. It appears as though the scene graph defines two visual objects through re-use of the visual (Shape3D) object on the right-hand side of the figure. Conceptually, each of the TransformGroup objects parenting the shared instance of Shape3D could place an image of the visual object in different locations. However, it is an illegal scene graph since the parent-child arcs do not form a tree. In this example, the result is that the Shape3D object has more than one parent.

The discussion of the tree and DAG structures are correct. However, the Java 3D runtime system reports the mistake in terms of child-parent relationships. One result of the tree structure limitation is that each Shape3D object is restricted to one parent. For the example scene graph of Figure 1-3, a 'multiple parent' exception is reported at runtime. Figure 1-4, with one parent for each Shape3D object, shows one possible fix for this scene graph.

Each scene graph has a single VirtualUniverse. The VirtualUniverse object has a list of Locale objects. A Locale object provides a reference point in the virtual universe. Think of a Locale object as being a landmark used to determine the location of visual objects in the virtual universe.

It is technically possible for a Java 3D program to have more than one VirtualUniverse object, thus defining more than one virtual universe. However, there is no inherent way to communicate among virtual universes. Further, a scene graph object can not exist in multiple virtual universes simultaneously. It is highly recommended to use one and only one instance of VirtualUniverse in each Java 3D program.

While a VirtualUniverse object may reference many Locale objects, most Java 3D programs have only one Locale object. Each Locale object may serve as the root of multiple subgraphs of the scene graph. Refer to Figure 1-2 for an example scene graph and note the two subgraph branches from the Locale object in the figure.

A BranchGroup object is the root of a subgraph, or branch graph. There are two different categories of scene subgraph: the view branch graph and the content branch graph. The content branch graph specifies the contents of the virtual universe - geometry, appearance, behavior, location, sound, and lights. The view branch graph specifies the viewing parameters such as the viewing location and direction. Together, the two branches specify much of the work the renderer has to do.

1.3.1 High Level Java 3D API Class Hierarchy

An overview of the first three levels of the Java 3D API hierarchy appears in Figure 1-5. The VirtualUniverse, Locale, Group, and Leaf classes appear in this portion of the hierarchy. Other than the VirtualUniverse and Locale objects, the rest of a scene graph is composed of SceneGraphObject objects. SceneGraphObject is the superclass for nearly every Core and Utility Java 3D class.

SceneGraphObject has two subclasses: Node and NodeComponent. The subclasses of Node provide most of the objects in the scene graph. A Node object is either a Group node or a Leaf node object. Group and Leaf are superclasses to a number of subclasses. Here is a quick look at the Node class, its two subclasses, and the NodeComponent class. After this background material is covered, the construction of Java 3D programs is explained.

Node Class

The Node class is an abstract superclass of Group and Leaf classes. The Node class defines some important common methods for its subclasses. Information on specific methods is presented in later sections after more background material is covered. The subclasses of Node compose scene graphs.

Group Class

The Group class is the superclass used in specifying the location and orientation of visual objects in the virtual universe. Two of the subclasses of Group are BranchGroup and TransformGroup. In the graphical representation of the scene graph, the Group symbols (circles) are often annotated with BG for BranchGroups, TG for TransformGroups, etc. Figure 1-2 shows an example of this.

Leaf Class

The Leaf class is the superclass used in specifying the shape, sound, and behavior of visual objects in the virtual universe. Some of the subclasses of Leaf are Shape3D, Light, Behavior, and Sound. These objects can have no children but may reference NodeComponents.

NodeComponent Class

The NodeComponent class is the superclass used in specifying the geometry, appearance, texture, and material properties of a Shape3D (Leaf) node. NodeComponents are not part of the scene graph, but are referenced by it. A NodeComponent may be referenced by more than one Shape3D object.

VirtualUniverse

Locale

View

PhysicalBody

PhysicalUniverse

Canvas3D (extends awt.canvas)

ScreenGraphObject

Node

Group

Leaf

NodeComponent

Transform3D

Screen3D

javax.media.j3d

Alpha

Figure 1-5 An Overview of the Java 3D API Class Hierarchy

1.4 Recipe for Writing Java 3D Programs

The subclasses of SceneGraphObject are the building blocks that are assembled into scene graphs. The basic outline of Java 3D program development consists of seven steps (collectively referred to as a recipe here and in The Java 3D API Specification) presented in Figure 1-6. This recipe can be used to assemble many useful Java 3D programs.

BranchGroup

VirtualUniverse

BG

TG TransformGroup

View Platform

BG

Appearance Geometry

S

Locale

View Canvas3D Screen3D

Physical Body Physical Environment

Figure 1-7 A SimpleUniverse Object Provides a Minimal Virtual Universe, Indicated by the Dashed Line.

Using a SimpleUniverse object makes the basic recipe even easier. Figure 1-8 presents the simple recipe, which is the basic recipe modified to use a SimpleUniverse object. Steps 2, 3, and 4 of the basic recipe are replaced by step 2 of the simple recipe.

1. Create a Canvas3D Object
2. Create a SimpleUniverse object which references the earlier Canvas3D object a. Customize the SimpleUniverse object
3. Construct content branch
4. Compile content branch graph
5. Insert content branch graph into the Locale of the SimpleUniverse

Figure 1-8 Simple Recipe for Writing Java 3D Programs using SimpleUniverse.

The gray box on the next page is the first instance of a reference block in this tutorial. A reference block lists constructors, methods, or fields of a class. Reference blocks are designed to allow the tutorial reader to learn basic Java 3D API programming without having another reference at hand. The reference blocks in this tutorial do not cover every constructor or method of a class. For that matter, there are many Java 3D API classes without reference block in this tutorial. Therefore, this tutorial document does not replace The Java 3D API Specification. However, for the constructors, methods, or fields listed; the reference blocks in this tutorial typically give more detailed information than The Java 3D API Specification.

SimpleUniverse Constructors

Package: com.sun.j3d.utils.universe

This class sets up a minimal user environment to quickly and easily get a Java 3D program up and running. This utility class creates all the necessary objects for a view branch graph. Specifically, this class creates Locale, VirtualUniverse, ViewingPlatform, and Viewer objects (all with their default values). The objects have the appropriate relationships to form the view branch graph.

SimpleUniverse provides all functionality necessary for many basic Java 3D applications. Viewer and ViewingPlatform are convenience utility classes. These classes use the View and ViewPlatform core classes.

SimpleUniverse() Constructs a simple virtual universe.

SimpleUniverse(Canvas3D canvas3D) Construct as simple universe with a reference to the named Canvas3D object.

The SimpleUniverse object creates a complete view branch graph for a virtual universe. The view branch graph includes an image plate. An image plate is the conceptual rectangle where the content is projected to form the rendered image. The Canvas3D object, which provides an image in a window on your computer display, can be thought of as the image plate.

Figure 1-9, shows the relationship between the image plate, the eye position, and the virtual universe. The eye position is behind the image plate. The visual objects in front of the image plate are rendered to the image plate. Rendering can be thought of as projecting the visual objects to the image plate. This idea is illustrated with the four projectors in the image (dashed lines).

image plate

projectors

eye position

visual object

Figure 1-9 Conceptual Drawing of Image Plate and Eye Position in a Virtual Universe.

By default, the image plate is centered at the origin in the SimpleUniverse. The default orientation is to look down the z-axis. From this position, the x-axis is a horizontal line through the image plate, with positive values to the right. The y-axis is a vertical line through the center of the image plate, with positive values up. Consequently, the point (0,0,0) is in the center of the image plate.

BranchGroup objects can be compiled. Compiling a BranchGroup converts the BranchGroup object and all of its ancestors to a more efficient form for the renderer. Compiling BranchGroup objects is recommended as the last step before making it live. It is best to only compile the BranchGroup objects inserted into Locales. Compilation is further discussed in sections 1.8 and 1.8.1.

BranchGroup compile() Method

void compile() Compiles the source BranchGroup associated with this object by creating and caching a compiled scene graph.

Concepts of compiled and live are implemented in the SceneGraphObject class. The two methods of the SceneGraphObject class that relate to these concepts are shown in the SceneGraphObject methods reference box below.

SceneGraphObject Methods (partial list)

SceneGraphObject is the superclass of nearly every class used to create a scene graph including Group, Leaf, and NodeComponent. The SceneGraphObject provides a number of common methods and fields for its subclasses; two of which are presented here. The methods of SceneGraphObject associated with “compile” are covered in Section 1.8 Performance Basics.

boolean isCompiled() Returns a flag indicating whether the node is part of a scene graph that has been compiled.

boolean isLive() Returns a flag indicating whether the node is part of a live scene graph.

Note there is no “start the renderer” step in either the basic or simple recipes. The Java 3D renderer starts running in an infinite loop when a branch graph containing an instance of View becomes live in a virtual universe. Once started, the Java 3D renderer conceptually performs the operations shown in Figure 1-10.

while(true) { Process input If (request to exit) break Perform Behaviors Traverse the scene graph and render visual objects } Cleanup and exit

Figure 1-10 Conceptual Renderer Process

The previous sections explained the construction of a simple virtual universe without a content branch graph. Creating the content branch graph is the subject of the next few sections. Creating content is discussed through the presentation of example programs.

1.6 Simple Recipe Example: HelloJava3Da

The typical Java 3D program begins by defining a new class to extend the Applet class. In the HelloJava3Da.java example found in the examples/HelloJava3D directory, HelloJava3Da is a class defined to extend the Applet class. Java 3D programs could be written as applications, but using Applet class gives an easy way to produce a windowed application.

The main class of a Java 3D program typically defines a method to construct the content branch graph. In the HelloJava3Da example such a method is defined and it is called createSceneGraph().

All steps of the simple recipe are implemented in the constructor of the HelloJava3Da class. Step 1, create a Canvas3D object, is completed on line 4. Step 2, create a SimpleUniverse object, is done on line 11. Step 2a, customize the SimpleUniverse object, is accomplished on line 15. Step 3, construct content branch, is accomplished by a call to the createSceneGraph() method. Step 4, compile content branch graph, is done on line 8. Finally, step 5, insert content branch graph into the Locale of the SimpleUniverse, is completed on line 16.

1. public class HelloJava3Da extends Applet {
2. public HelloJava3Da() {
3. setLayout(new BorderLayout());
4. Canvas3D canvas3D = new Canvas3D(null);
5. add("Center", canvas3D);
7. BranchGroup scene = createSceneGraph();
8. scene.compile();
10. // SimpleUniverse is a Convenience Utility class
11. SimpleUniverse simpleU = new SimpleUniverse(canvas3D);
13. // This moves the ViewPlatform back a bit so the
14. // objects in the scene can be viewed.
15. simpleU.getViewingPlatform().setNominalViewingTransform();
17. simpleU.addBranchGraph(scene);
18. } // end of HelloJava3Da (constructor)

Code Fragment 1-1 Class HelloJava3Da

Step 3 of the simple recipe is to create the content branch graph. A content branch graph is created in Code Fragment 1-2. It is probably the simplest content branch graph possible. The content branch created in Code Fragment 1-2 contains one static graphical object, a ColorCube. The ColorCube is located at the origin of the virtual world coordinate system. With the given location and orientation of the viewing direction and the cube, the cube appears as a rectangle when rendered. The image is shown after all of the code for the program is presented, in Figure 1-12.

1. public BranchGroup createSceneGraph() {
2. // Create the root of the branch graph
3. BranchGroup objRoot = new BranchGroup();
5. // Create a simple shape leaf node, add it to the scene graph.
6. // ColorCube is a Convenience Utility class
7. objRoot.addChild(new ColorCube(0.4));
9. return objRoot;
10. } // end of createSceneGraph method of HelloJava3Da 11.} // end of class HelloJava3Da

Code Fragment 1-2 Method createSceneGraph for Class HelloJava3Da

The class HelloJava3Da is derived from Applet but the program is runnable as an application with the use of the MainFrame class. The Applet class is used as a base class to make it easy to write a Java 3D program that runs in a window. MainFrame provides an AWT frame (window) for an applet allowing the