Getting Started with the Java 3D™ API Chapter 1 Dennis J Bouvier K Computing tutorial v1.5 (Java 3D API v1.1.2) 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 Table of Contents Chapter 1: Getting Started......................................................................................................................................1-1 1.1 What is Java 3D ........................................................................................................................1-1 1.2 The Java 3D API.......................................................................................................................1-2 1.3 Building a Scene Graph .............................................................................................................1-2 1.3.1 High Level Java 3D API Class Hierarchy...........................................................................1-7 1.4 Recipe for Writing Java 3D Programs........................................................................................1-8 1.4.1 A Simple Recipe for Writing Java 3D Programs .................................................................1-9 1.5 Some Java 3D Terminology .....................................................................................................1-12 1.6 Simple Recipe Example: HelloJava3Da....................................................................................1-13 1.6.1 Java 3D Classes Used in HelloJava3Da............................................................................1-16 1.7 Rotating the Cube....................................................................................................................1-19 1.7.1 Combination of Transformations Example: HelloJava3Db ................................................1-20 1.8 Capabilities and Performance...................................................................................................1-22 1.8.1 Compiling Contents..........................................................................................................1-23 1.8.2 Capabilities......................................................................................................................1-24 1.9 Adding Animation Behavior.....................................................................................................1-25 1.9.1 Specifying Animation Behavior ........................................................................................1-26 1.9.2 Time Varying Functions: Mapping a Behavior to Time.....................................................1-27 1.9.3 Scheduling Region ...........................................................................................................1-27 1.9.4 Behavior Example: HelloJava3Dc ....................................................................................1-28 1.9.5 Transformation and Behavior Combination Example: HelloJava3Dd.................................1-30 1.10 Chapter Summary....................................................................................................................1-33 1.11 Self Test..................................................................................................................................1-33 The Java 3D Tutorial 1-i Getting Started with Java 3D Figures Figure 1-1 Symbols Representing Objects in Scene Graphs....................................................................1-4 Figure 1-2 First Scene Graph Example ..................................................................................................1-5 Figure 1-3 Example of an Illegal Scene Graph (not a DAG)...................................................................1-6 Figure 1-4 Fix for Illegal Scene Graph of Figure 1-3..............................................................................1-6 Figure 1-5 An Overview of the Java 3D API Class Hierarchy ................................................................1-8 Figure 1-6 Recipe for Writing Java 3D Programs .................................................................................1-9 Figure 1-7 A SimpleUniverse Object Provides a Minimal Virtual Universe...........................................1-10 Figure 1-8 Simple Recipe for Writing Java 3D Programs.....................................................................1-10 Figure 1-9 Conceptual Drawing of Image Plate and Eye Position in a Virtual Universe.........................1-11 Figure 1-10 Conceptual Renderer Process............................................................................................1-13 Figure 1-11 Scene Graph for HelloJava3Da Example ..........................................................................1-16 Figure 1-12 Image Produced by HelloJava3Da ....................................................................................1-16 Figure 1-13 Scene Graph for Content Branch Graph Created in Code Fragment 1-5.............................1-20 Figure 1-14 Scene Graph for HelloJava3Db Example ..........................................................................1-22 Figure 1-15 Image of the Rotated ColorCube Rendered by HelloJava3Db ............................................1-22 Figure 1-16 Conceptual Example of the Result of Compiling a Scene Graph ........................................1-23 Figure 1-17 Recipe for Adding Behaviors to a Java 3D Visual Objects.................................................1-26 Figure 1-18 Scene Graph for HelloJava3Dc Example ..........................................................................1-30 Figure 1-19 An Image of the ColorCube in Rotation as Rendered by HelloJava3Dc..............................1-30 Figure 1-20 Scene Graph for HelloJava3Dd Example ..........................................................................1-32 Figure 1-21 An Image of the ColorCube in Rotation as Rendered by HelloJava3Dd..............................1-32 The Java 3D Tutorial 1-ii Getting Started with Java 3D Code Fragments Code Fragment 1-1 Class HelloJava3Da..............................................................................................1-14 Code Fragment 1-2 Method createSceneGraph for Class HelloJava3Da ...............................................1-14 Code Fragment 1-3 Main() Method of HelloJava3Da Invokes MainFrame............................................1-15 Code Fragment 1-4 Import Statements for HelloJava3Da.java..............................................................1-15 Code Fragment 1-5 One Rotation in the Content Branch Graph............................................................1-20 Code Fragment 1-6 Two Rotation Transformations in HelloJava3Db ...................................................1-21 Code Fragment 1-7 createSceneGraph method with RotationInterpolator Behavior...............................1-29 Code Fragment 1-8 Content Branch for Rotated Spinning ColorCube of HelloJava3Dd........................1-31 The Java 3D Tutorial 1-iii Getting Started with Java 3D Reference Blocks SimpleUniverse Constructors ..............................................................................................................1-11 ViewingPlatform setNominalViewingTransform() Method ..................................................1-12 SimpleUniverse Methods (partial list)..................................................................................................1-12 BranchGroup compile() Method....................................................................................................1-13 SceneGraphObject Methods