The Java(TM) 3D API Specification

529 Pages·1997·1.31 MB·English

by  Henry Sowizral

Java 3D™ API
Specification
Version 1.1 Alpha 01, February 27, 1998
JavaSoft
A Sun Microsystems, Inc. Business
901 San Antonio Road
Palo Alto, CA 94303 USA
415 960-1300 fax [phone]
© 1997, 1998 Sun Microsystems, Inc.
901 San Antonio Road, Palo Alto, California 94303 U.S.A.
All rights reserved.
RESTRICTED RIGHTS LEGEND: Use, duplication, or disclosure by the United States
Government is subject to the restrictions set forth in DFARS 252.227-7013 (c)(1)(ii) and
FAR 52.227-19.
The release described in this document may be protected by one or more U.S. patents, for-
eign patents, or pending applications.
Sun Microsystems, Inc. (SUN) hereby grants to you a fully paid, nonexclusive, nontrans-
ferable, perpetual, worldwide limited license (without the right to sublicense) under
SUN’s intellectual property rights that are essential to practice this specification. This
license allows and is limited to the creation and distribution of clean-room implementa-
tions of this specification that (i) are complete implementations of this specification, (ii)
pass all test suites relating to this specification that are available from SUN, (iii) do not
derive from SUN source code or binary materials, and (iv) do not include any SUN binary
materials without an appropriate and separate license from SUN.
Java, JavaScript, and Java 3D are trademarks of Sun Microsystems, Inc. Sun, Sun Micro-
systems, the Sun logo, Java and HotJava are trademarks or registered trademarks of Sun
Microsystems, Inc. UNIX® is a registered trademark in the United States and other coun-
tries, exclusively licensed through X/Open Company, Ltd. All other product names men-
tioned herein are the trademarks of their respective owners.
THIS PUBLICATION IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY
KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
PURPOSE, OR NON-INFRINGEMENT.
THIS PUBLICATION COULD INCLUDE TECHNICAL INACCURACIES OR TYPO-
GRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFOR-
MATION 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 THE PRO-
GRAM(S) DESCRIBED IN THIS PUBLICATION AT ANY TIME.
Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv
1 Introduction to Java 3D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.1 Goals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1
1.2 Programming Paradigm. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2
1.2.1 The Scene Graph Programming Model . . . . . . . . . . . . . . .2
1.2.2 Rendering Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2
1.2.3 Extensibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3
1.3 High Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4
1.3.1 Layered Implementation. . . . . . . . . . . . . . . . . . . . . . . . . . .4
1.3.2 Target Hardware Platforms . . . . . . . . . . . . . . . . . . . . . . . .4
1.4 Support for Building Applications and Applets . . . . . . . . . . . . . . . . . . .5
1.4.1 Browsers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5
1.4.2 Games. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5
1.5 Overview of Java3D Object Hierarchy. . . . . . . . . . . . . . . . . . . . . . . . . .6
1.6 Structuring the Java3D Program. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7
1.6.1 Java3D Application Scene Graph . . . . . . . . . . . . . . . . . . .7
1.6.2 Recipe for a Java3D Program . . . . . . . . . . . . . . . . . . . . . .8
1.6.3 HelloUniverse: A Sample Java3D Program . . . . . . . . . . .9
2 Scene Graph Basics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
2.1 Scene Graph Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15
2.1.1 Spatial Separation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15
2.1.2 State Inheritance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16
2.1.3 Rendering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17
2.2 Scene Graph Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17
2.2.1 Node Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19
2.2.2 NodeComponent Objects . . . . . . . . . . . . . . . . . . . . . . . . .23
2.3 Scene Graph Superstructure Objects. . . . . . . . . . . . . . . . . . . . . . . . . . .24
2.3.1 VirtualUniverse Object. . . . . . . . . . . . . . . . . . . . . . . . . . .24
2.3.2 Locale Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24
2.4 Scene Graph Viewing Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25
2.4.1 Canvas3D Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25
2.4.2 Screen3D Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25
2.4.3 View Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25
2.4.4 PhysicalBody Object . . . . . . . . . . . . . . . . . . . . . . . . . . . .26
2.4.5 PhysicalEnvironment Object . . . . . . . . . . . . . . . . . . . . . .26
Version 1.1 Alpha 01, February 27, 1998 iii
CONTENTS
3 Scene Graph Superstructure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
3.1 The Virtual Universe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
3.2 Establishing a Scene. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
3.3 Loading a Virtual Universe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
3.4 Coordinate Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
3.5 High-resolution Coordinates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
3.5.1 Java3D High-resolution Coordinates. . . . . . . . . . . . . . . 29
3.5.2 Java3D Virtual World Coordinates . . . . . . . . . . . . . . . . 30
3.5.3 Details of High-resolution Coordinates. . . . . . . . . . . . . . 30
3.6 API for Superstructure Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
3.6.1 VirtualUniverse Object . . . . . . . . . . . . . . . . . . . . . . . . . . 32
3.6.2 Locale Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
3.6.3 HiResCoord Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
4 Group Node Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
4.1 Group Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
4.2 BranchGroup Node. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
4.3 TransformGroup Node. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
4.4 OrderedGroup Node. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
4.5 DecalGroup Node. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
4.6 Switch Node. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
4.7 SharedGroup Node. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
5 Leaf Node Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
5.1 Leaf Node. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
5.2 Shape3D Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
5.3 BoundingLeaf Node. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
5.4 Background Node. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
5.5 Clip Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
5.6 Fog Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
5.6.1 ExponentialFog Node . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
5.6.2 LinearFog Node. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
5.7 Light Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
5.7.1 AmbientLight Node. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
5.7.2 DirectionalLight Node. . . . . . . . . . . . . . . . . . . . . . . . . . . 64
5.7.3 PointLight Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
5.7.4 SpotLight Node. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
5.8 Sound Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
5.8.1 BackgroundSound Node . . . . . . . . . . . . . . . . . . . . . . . . . 74
5.8.2 PointSound Node. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
5.8.3 ConeSound Node. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
5.9 Soundscape Node. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
5.10 ViewPlatform Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
5.11 Behavior Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
5.12 Morph Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
5.13 Link Node. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
iv Java 3D API Specification
6 Reusing Scene Graphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
6.1 Sharing Subgraphs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .93
6.1.1 SharedGroup Node. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .93
6.1.2 Link Leaf Node. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .95
6.2 Cloning Subgraphs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .96
6.2.1 References to Node Component Objects . . . . . . . . . . . . .97
6.2.2 References to Other Scene Graph Nodes. . . . . . . . . . . . .98
6.2.3 Dangling References. . . . . . . . . . . . . . . . . . . . . . . . . . . .101
6.2.4 Subclassing Nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . .102
6.2.5 NodeReferenceTable Object. . . . . . . . . . . . . . . . . . . . . .103
6.2.6 Example User Behavior Node . . . . . . . . . . . . . . . . . . . .103
7 Node Component Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
7.1 Node Component Objects: Attributes . . . . . . . . . . . . . . . . . . . . . . . . .107
7.1.1 Appearance Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . .107
7.1.2 ColoringAttributes Object . . . . . . . . . . . . . . . . . . . . . . .111
7.1.3 LineAttributes Object. . . . . . . . . . . . . . . . . . . . . . . . . . .112
7.1.4 PointAttributes Object . . . . . . . . . . . . . . . . . . . . . . . . . .114
7.1.5 PolygonAttributes Object. . . . . . . . . . . . . . . . . . . . . . . .115
7.1.6 RenderingAttributes Object . . . . . . . . . . . . . . . . . . . . . .117
7.1.7 TextureAttributes Object . . . . . . . . . . . . . . . . . . . . . . . .119
7.1.8 TransparencyAttributes Object. . . . . . . . . . . . . . . . . . . .120
7.1.9 Material Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .122
7.1.10 Texture Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .124
7.1.11 Texture2D Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .128
7.1.12 Texture3D Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .128
7.1.13 TexCoordGeneration Object. . . . . . . . . . . . . . . . . . . . . .129
7.1.14 MediaContainer Object. . . . . . . . . . . . . . . . . . . . . . . . . .132
7.1.15 AuralAttributes Object. . . . . . . . . . . . . . . . . . . . . . . . . .133
7.1.16 ImageComponent Object . . . . . . . . . . . . . . . . . . . . . . . .139
7.1.17 ImageComponent2D Object. . . . . . . . . . . . . . . . . . . . . .141
7.1.18 ImageComponent3D Object. . . . . . . . . . . . . . . . . . . . . .142
7.1.19 DepthComponent Object . . . . . . . . . . . . . . . . . . . . . . . .143
7.1.20 DepthComponentFloat Object . . . . . . . . . . . . . . . . . . . .143
7.1.21 DepthComponentInt Object . . . . . . . . . . . . . . . . . . . . . .144
7.1.22 DepthComponentNative Object. . . . . . . . . . . . . . . . . . .144
7.1.23 Bounds Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .145
7.1.24 BoundingBox Object . . . . . . . . . . . . . . . . . . . . . . . . . . .146
7.1.25 BoundingSphere Object . . . . . . . . . . . . . . . . . . . . . . . . .148
7.1.26 BoundingPolytope Object. . . . . . . . . . . . . . . . . . . . . . . .150
7.1.27 Transform3D Object. . . . . . . . . . . . . . . . . . . . . . . . . . . .152
7.2 Node Component Objects: Geometry . . . . . . . . . . . . . . . . . . . . . . . . .164
7.2.1 GeometryArray Object. . . . . . . . . . . . . . . . . . . . . . . . . .164
7.2.2 PointArray Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .171
7.2.3 LineArray Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .171
7.2.4 TriangleArray Object . . . . . . . . . . . . . . . . . . . . . . . . . . .172
7.2.5 QuadArray Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .172
7.2.6 GeometryStripArray Object. . . . . . . . . . . . . . . . . . . . . .172
Version 1.1 Alpha 01, February 27, 1998 v
CONTENTS
7.2.7 LineStripArray Object. . . . . . . . . . . . . . . . . . . . . . . . . . 173
7.2.8 TriangleStripArray Object. . . . . . . . . . . . . . . . . . . . . . . 173
7.2.9 TriangleFanArray Object . . . . . . . . . . . . . . . . . . . . . . . 174
7.2.10 IndexedGeometryArray Object. . . . . . . . . . . . . . . . . . . 174
7.2.11 IndexedPointArray Object. . . . . . . . . . . . . . . . . . . . . . . 177
7.2.12 IndexedLineArray Object . . . . . . . . . . . . . . . . . . . . . . . 177
7.2.13 IndexedTriangleArray Object . . . . . . . . . . . . . . . . . . . . 178
7.2.14 IndexedQuadArray Object . . . . . . . . . . . . . . . . . . . . . . 178
7.2.15 IndexedGeometryStripArray Object. . . . . . . . . . . . . . . 179
7.2.16 IndexedLineStripArray Object . . . . . . . . . . . . . . . . . . . 179
7.2.17 IndexedTriangleStripArray Object . . . . . . . . . . . . . . . . 180
7.2.18 IndexedTriangleFanArray Object . . . . . . . . . . . . . . . . . 181
7.2.19 CompressedGeometry Object . . . . . . . . . . . . . . . . . . . . 181
7.2.20 CompressedGeometryHeader Object . . . . . . . . . . . . . . 182
7.2.21 Raster Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
7.2.22 Font3D Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
7.2.23 FontExtrusion Object . . . . . . . . . . . . . . . . . . . . . . . . . . 188
7.2.24 Text3D Geometry Object . . . . . . . . . . . . . . . . . . . . . . . 189
7.3 Math Component Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
7.3.1 Tuple Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
7.3.2 Matrix Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
8 View Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
8.1 Why a New Model? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
8.1.1 The Physical Environment Influences the View. . . . . . 196
8.2 Separation of Physical and Virtual. . . . . . . . . . . . . . . . . . . . . . . . . . . 197
8.2.1 The Virtual World. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
8.2.2 The Physical World. . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
8.3 The Objects That Define the View. . . . . . . . . . . . . . . . . . . . . . . . . . . 198
8.4 ViewPlatform: A Place in the Virtual World. . . . . . . . . . . . . . . . . . . 199
8.4.1 Moving Through the Virtual World . . . . . . . . . . . . . . . 200
8.4.2 Dropping In on a Favorite Place . . . . . . . . . . . . . . . . . . 201
8.4.3 View Attach Policy. . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
8.4.4 Associating Geometry with a ViewPlatform. . . . . . . . . 203
8.5 Generating a View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
8.5.1 Composing Model and Viewing Transformations . . . . 203
8.5.2 Multiple Locales . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
8.6 A Minimal Environment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
8.7 The View Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
8.7.1 Projection Policy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
8.7.2 Clip Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
8.7.3 Projection and Clip Parameters. . . . . . . . . . . . . . . . . . . 211
8.7.4 Frame Start Time, Duration, and Number. . . . . . . . . . . 212
8.7.5 View Traversal and Behavior Scheduling. . . . . . . . . . . 213
8.7.6 Scene Antialiasing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
8.7.7 Depth Buffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
8.8 The Screen3D Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
8.9 The Canvas3D Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
vi Java 3D API Specification
8.9.1 Window System–Provided Parameters . . . . . . . . . . . . .215
8.9.2 Other Canvas3D Parameters. . . . . . . . . . . . . . . . . . . . . .216
8.10 The PhysicalBody Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .216
8.11 The PhysicalEnvironment Object . . . . . . . . . . . . . . . . . . . . . . . . . . . .217
9 Behaviors and Interpolators . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
9.1 Behavior Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .219
9.1.1 Code Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .220
9.1.2 WakeupCondition Object. . . . . . . . . . . . . . . . . . . . . . . .221
9.1.3 WakeupCriterion Object. . . . . . . . . . . . . . . . . . . . . . . . .221
9.1.4 Composing WakeupCriterion Objects . . . . . . . . . . . . . .222
9.2 Composing Behaviors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .222
9.3 Scheduling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .222
9.4 How Java3D Performs Execution Culling . . . . . . . . . . . . . . . . . . . . .223
9.5 The Behavior API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .224
9.5.1 The Behavior Node. . . . . . . . . . . . . . . . . . . . . . . . . . . . .224
9.5.2 WakeupCondition Object. . . . . . . . . . . . . . . . . . . . . . . .226
9.5.3 The WakeupCriterion Objects . . . . . . . . . . . . . . . . . . . .226
9.6 Interpolator Behaviors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .236
9.6.1 Mapping Time to Alpha. . . . . . . . . . . . . . . . . . . . . . . . .237
9.6.2 Acceleration of Alpha. . . . . . . . . . . . . . . . . . . . . . . . . . .241
9.6.3 The Alpha Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .242
9.6.4 The Interpolator Base Class . . . . . . . . . . . . . . . . . . . . . .246
9.6.5 PositionInterpolator Object. . . . . . . . . . . . . . . . . . . . . . .247
9.6.6 RotationInterpolator Object . . . . . . . . . . . . . . . . . . . . . .248
9.6.7 ColorInterpolator Object. . . . . . . . . . . . . . . . . . . . . . . . .250
9.6.8 ScaleInterpolator Object. . . . . . . . . . . . . . . . . . . . . . . . .251
9.6.9 SwitchValueInterpolator Object. . . . . . . . . . . . . . . . . . .252
9.6.10 TransparencyInterpolator Object . . . . . . . . . . . . . . . . . .253
9.6.11 PositionPathInterpolator Object. . . . . . . . . . . . . . . . . . .254
9.6.12 RotPosPathInterpolator Object. . . . . . . . . . . . . . . . . . . .256
9.6.13 RotPosScalePathInterpolator Object . . . . . . . . . . . . . . .257
9.6.14 RotationPathInterpolator Object. . . . . . . . . . . . . . . . . . .259
9.7 Level-of-Detail Behaviors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .260
9.7.1 LOD Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .260
9.7.2 DistanceLOD Object . . . . . . . . . . . . . . . . . . . . . . . . . . .261
9.8 Billboard Behavior. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .262
10 Input Devices and Picking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
10.1 InputDevice Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .265
10.1.1 The Abstract Interface . . . . . . . . . . . . . . . . . . . . . . . . . .266
10.1.2 Instantiating and Registering a New Device . . . . . . . . .267
10.2 Sensors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .267
10.2.1 Using and Assigning Sensors. . . . . . . . . . . . . . . . . . . . .268
10.2.2 Behind the (Sensor) Scenes . . . . . . . . . . . . . . . . . . . . . .268
10.2.3 The Sensor Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . .268
10.2.4 The SensorRead Object . . . . . . . . . . . . . . . . . . . . . . . . .271
10.3 Picking. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .272
Version 1.1 Alpha 01, February 27, 1998 vii
CONTENTS
10.3.1 SceneGraphPath Object. . . . . . . . . . . . . . . . . . . . . . . . . 273
10.3.2 BranchGroup Node and Locale Node Pick Methods . . 275
10.3.3 PickShape Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
10.3.4 PickPoint Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
10.3.5 PickRay Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
10.3.6 PickSegment Object . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
11 Audio Devices. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
11.1 AudioDevice Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
11.1.1 Initialization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
11.1.2 Audio Playback. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
11.1.3 Device-Driver-Specific Data. . . . . . . . . . . . . . . . . . . . . 282
11.2 Instantiating and Registering a New Device . . . . . . . . . . . . . . . . . . . 282
11.3 AudioMixerDevice Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
12 Execution and Rendering Model . . . . . . . . . . . . . . . . . . . . . . . . . 285
12.1 Three Major Rendering Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
12.1.1 Immediate Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
12.1.2 Retained Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286
12.1.3 Compiled-retained Mode. . . . . . . . . . . . . . . . . . . . . . . . 286
12.2 Instantiating the Render Loop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
12.2.1 An Application-level Perspective . . . . . . . . . . . . . . . . . 287
12.2.2 Retained and Compiled-retained Rendering Modes. . . 287
13 Immediate-Mode Rendering. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
13.1 Two Styles of Immediate-Mode Rendering. . . . . . . . . . . . . . . . . . . . 289
13.1.1 Pure Immediate-Mode Rendering. . . . . . . . . . . . . . . . . 289
13.1.2 Mixed-Mode Rendering . . . . . . . . . . . . . . . . . . . . . . . . 291
13.2 Canvas3D Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
13.3 API for Immediate Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
13.3.1 GraphicsContext3D. . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
A Math Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
A.1 Tuple Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
A.1.1 Tuple2f Class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
A.1.2 Tuple3b Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
A.1.3 Tuple3d Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
A.1.4 Tuple3f Class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
A.1.5 Tuple4b Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
A.1.6 Tuple4d Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
A.1.7 Tuple4f Class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
A.1.8 AxisAngle4d Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
A.1.9 AxisAngle4f Class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
A.1.10 GVector Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
A.2 Matrix Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
A.2.1 Matrix3f Class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346
A.2.2 Matrix3d Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
viii Java 3D API Specification
A.2.3 Matrix4f Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .359
A.2.4 Matrix4d Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .367
A.2.5 GMatrix Class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .376
B 3D Geometry Compression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
B.1 Compression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .381
B.2 Decompression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .382
B.3 Appendix Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .382
B.4 Generalized Triangle Strip. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .382
B.5 Generalized Triangle Mesh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .383
B.6 Position Representation and Quantization. . . . . . . . . . . . . . . . . . . . . .386
B.7 Color Representation and Quantization. . . . . . . . . . . . . . . . . . . . . . . .387
B.8 Normal Representation and Quantization . . . . . . . . . . . . . . . . . . . . . .388
B.8.1 Normals as Indices . . . . . . . . . . . . . . . . . . . . . . . . . . . . .389
B.8.2 Normal Encoding Parameterization . . . . . . . . . . . . . . . .390
B.9 Modified Huffman Encoding. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .392
B.10 Geometry Compression Commands . . . . . . . . . . . . . . . . . . . . . . . . . .393
B.11 Bit Layout of Geometry Decompression Commands . . . . . . . . . . . . .395
B.12 Geometry Decompression Command Bit Details . . . . . . . . . . . . . . . .395
B.12.1 NOP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .395
B.12.2 setState . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .395
B.12.3 setTable. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .397
B.12.4 meshBufferReference. . . . . . . . . . . . . . . . . . . . . . . . . . .398
B.12.5 Position Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . .399
B.12.6 Color Subcommand . . . . . . . . . . . . . . . . . . . . . . . . . . . .399
B.12.7 Normal Subcommand. . . . . . . . . . . . . . . . . . . . . . . . . . .400
B.12.8 vertex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .402
B.12.9 normal. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .403
B.12.10 color . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .403
B.13 Semantics of Geometry Decompression Commands . . . . . . . . . . . . .403
B.13.1 Header and Body to Variable-Length Command. . . . . .404
B.13.2 Variable-Length Command to Command . . . . . . . . . . .405
B.13.3 Delta Position to Position. . . . . . . . . . . . . . . . . . . . . . . .405
B.13.4 Delta Color to Color. . . . . . . . . . . . . . . . . . . . . . . . . . . .406
B.13.5 Encoded Delta Normal to Encoded Normal. . . . . . . . . .406
B.13.6 Encoded Normal to Rectilinear Normal. . . . . . . . . . . . .406
B.14 Semantics of Vertices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .407
B.14.1 Command to Vertex . . . . . . . . . . . . . . . . . . . . . . . . . . . .407
B.14.2 Vertex to Intermediate Triangle. . . . . . . . . . . . . . . . . . .408
B.14.3 Intermediate Triangle to Final Triangle . . . . . . . . . . . . .409
B.15 Outline of Geometry Process. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .410
B.15.1 Compressing Geometry Data . . . . . . . . . . . . . . . . . . . . .410
B.15.2 Convert to Generalized Mesh Format . . . . . . . . . . . . . .410
B.15.3 Position. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .410
B.15.4 Normals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .411
B.15.5 Colors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .412
B.15.6 Collect Delta Code Statistics . . . . . . . . . . . . . . . . . . . . .412
B.15.7 Position Delta Code Statistics. . . . . . . . . . . . . . . . . . . . .412
Version 1.1 Alpha 01, February 27, 1998 ix