The Java 3D™

API Specification

Version 1.2, March 2000

JavaSoft
A Sun Microsystems, Inc. Business
901 San Antonio Road
Palo Alto, CA 94303 USA
415 960-1300 fax 415 969-9131
 1997, 1998, 1999, 2000 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

Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii

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 Java 3D Object Hierarchy. . . . . . . . . . . . . . . . . . . . . . . . . .6
1.6 Structuring the Java 3D Program. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6
1.6.1 Java 3D Application Scene Graph . . . . . . . . . . . . . . . . . . .6
1.6.2 Recipe for a Java 3D Program . . . . . . . . . . . . . . . . . . . . . .8
1.6.3 HelloUniverse: A Sample Java 3D Program . . . . . . . . . . .9

2 Java 3D Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
2.1 Basic Scene Graph Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11
2.1.1 Constructing a Simple Scene Graph. . . . . . . . . . . . . . . . .12
2.1.2 A Place For Scene Graphs . . . . . . . . . . . . . . . . . . . . . . . .12
2.1.3 SimpleUniverse Utility . . . . . . . . . . . . . . . . . . . . . . . . . . .15
2.1.4 Processing a Scene Graph. . . . . . . . . . . . . . . . . . . . . . . . .15
2.2 Features of Java 3D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16
2.2.1 Bounds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16
2.2.2 Nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17
2.2.3 Live and/or Compiled. . . . . . . . . . . . . . . . . . . . . . . . . . . .17

3 Scene Graph Basics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

3.1 Scene Graph Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19
3.1.1 Spatial Separation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19

Version 1.2, March 2000 iii

 CONTENTS

3.1.2 State Inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

3.1.3 Rendering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
3.2 Scene Graph Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
3.2.1 Node Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
3.2.2 NodeComponent Objects . . . . . . . . . . . . . . . . . . . . . . . . 26
3.3 Scene Graph Superstructure Objects . . . . . . . . . . . . . . . . . . . . . . . . . . 27
3.3.1 VirtualUniverse Object . . . . . . . . . . . . . . . . . . . . . . . . . . 27
3.3.2 Locale Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
3.4 Scene Graph Viewing Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
3.4.1 Canvas3D Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
3.4.2 Screen3D Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
3.4.3 View Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
3.4.4 PhysicalBody Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
3.4.5 PhysicalEnvironment Object. . . . . . . . . . . . . . . . . . . . . . 28

4 Scene Graph Superstructure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

4.1 The Virtual Universe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
4.2 Establishing a Scene . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
4.3 Loading a Virtual Universe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
4.4 Coordinate Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
4.5 High-resolution Coordinates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
4.5.1 Java 3D High-resolution Coordinates . . . . . . . . . . . . . . . 33
4.5.2 Java 3D Virtual World Coordinates . . . . . . . . . . . . . . . . 34
4.5.3 Details of High-resolution Coordinates. . . . . . . . . . . . . . 34
4.6 API for Superstructure Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
4.6.1 VirtualUniverse Object . . . . . . . . . . . . . . . . . . . . . . . . . . 36
4.6.2 Locale Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
4.6.3 HiResCoord Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

5 Group Node Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

5.1 Group Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
5.2 BranchGroup Node. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
5.3 TransformGroup Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
5.4 OrderedGroup Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
5.5 DecalGroup Node. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
5.6 Switch Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
5.7 SharedGroup Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

6 Leaf Node Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

6.1 Leaf Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
6.2 Shape3D Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
6.2.1 OrientedShape3D Node. . . . . . . . . . . . . . . . . . . . . . . . . . 55
6.3 BoundingLeaf Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
6.4 Background Node. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
6.5 Clip Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
6.6 ModelClip Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
6.7 Fog Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
6.7.1 ExponentialFog Node . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

iv The Java 3D API Specification

 6.7.2 LinearFog Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .69
6.8 Light Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .71
6.8.1 AmbientLight Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . .73
6.8.2 DirectionalLight Node . . . . . . . . . . . . . . . . . . . . . . . . . . .73
6.8.3 PointLight Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .74
6.8.4 SpotLight Node. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .76
6.9 Sound Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .77
6.9.1 BackgroundSound Node. . . . . . . . . . . . . . . . . . . . . . . . . .83
6.9.2 PointSound Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .84
6.9.3 ConeSound Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .88
6.10 Soundscape Node. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .95
6.11 ViewPlatform Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .97
6.12 Behavior Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .99
6.13 Morph Node. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .99
6.14 Link Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .102
6.15 AlternateAppearance Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .102

7 Reusing Scene Graphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

7.1 Sharing Subgraphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .105
7.1.1 SharedGroup Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . .105
7.1.2 Link Leaf Node. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .107
7.2 Cloning Subgraphs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .108
7.2.1 References to Node Component Objects . . . . . . . . . . . .109
7.2.2 References to Other Scene Graph Nodes . . . . . . . . . . . .110
7.2.3 Dangling References. . . . . . . . . . . . . . . . . . . . . . . . . . . .112
7.2.4 Subclassing Nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . .113
7.2.5 NodeReferenceTable Object. . . . . . . . . . . . . . . . . . . . . .114
7.2.6 Example User Behavior Node . . . . . . . . . . . . . . . . . . . .115

8 Node Component Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119

8.1 Node Component Objects: Attributes . . . . . . . . . . . . . . . . . . . . . . . . .119
8.1.1 Alpha Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .119
8.1.2 Appearance Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . .119
8.1.3 ColoringAttributes Object . . . . . . . . . . . . . . . . . . . . . . .123
8.1.4 LineAttributes Object . . . . . . . . . . . . . . . . . . . . . . . . . . .125
8.1.5 PointAttributes Object . . . . . . . . . . . . . . . . . . . . . . . . . .127
8.1.6 PolygonAttributes Object . . . . . . . . . . . . . . . . . . . . . . . .128
8.1.7 RenderingAttributes Object . . . . . . . . . . . . . . . . . . . . . .130
8.1.8 TextureAttributes Object . . . . . . . . . . . . . . . . . . . . . . . .133
8.1.9 TransparencyAttributes Object. . . . . . . . . . . . . . . . . . . .136
8.1.10 Material Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .138
8.1.11 Texture Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .140
8.1.12 Texture2D Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .145
8.1.13 Texture3D Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .145
8.1.14 TexCoordGeneration Object. . . . . . . . . . . . . . . . . . . . . .146
8.1.15 TextureUnitState Object . . . . . . . . . . . . . . . . . . . . . . . . .149
8.1.16 MediaContainer Object. . . . . . . . . . . . . . . . . . . . . . . . . .151
8.1.17 AuralAttributes Object . . . . . . . . . . . . . . . . . . . . . . . . . .152

Version 1.2, March 2000 v

 CONTENTS

8.1.18 ImageComponent Object. . . . . . . . . . . . . . . . . . . . . . . . 159

8.1.19 ImageComponent2D Object . . . . . . . . . . . . . . . . . . . . . 162
8.1.20 ImageComponent3D Object . . . . . . . . . . . . . . . . . . . . . 164
8.1.21 DepthComponent Object. . . . . . . . . . . . . . . . . . . . . . . . 166
8.1.22 DepthComponentFloat Object. . . . . . . . . . . . . . . . . . . . 167
8.1.23 DepthComponentInt Object . . . . . . . . . . . . . . . . . . . . . 167
8.1.24 DepthComponentNative Object . . . . . . . . . . . . . . . . . . 168
8.1.25 Bounds Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
8.1.26 BoundingBox Object. . . . . . . . . . . . . . . . . . . . . . . . . . . 170
8.1.27 BoundingSphere Object . . . . . . . . . . . . . . . . . . . . . . . . 172
8.1.28 BoundingPolytope Object . . . . . . . . . . . . . . . . . . . . . . . 174
8.1.29 Transform3D Object . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
8.2 Node Component Objects: Geometry . . . . . . . . . . . . . . . . . . . . . . . . 190
8.2.1 GeometryArray Object . . . . . . . . . . . . . . . . . . . . . . . . . 191
8.2.2 GeometryUpdater Interface. . . . . . . . . . . . . . . . . . . . . . 206
8.2.3 PointArray Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
8.2.4 LineArray Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
8.2.5 TriangleArray Object . . . . . . . . . . . . . . . . . . . . . . . . . . 207
8.2.6 QuadArray Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
8.2.7 GeometryStripArray Object . . . . . . . . . . . . . . . . . . . . . 208
8.2.8 LineStripArray Object. . . . . . . . . . . . . . . . . . . . . . . . . . 209
8.2.9 TriangleStripArray Object. . . . . . . . . . . . . . . . . . . . . . . 210
8.2.10 TriangleFanArray Object . . . . . . . . . . . . . . . . . . . . . . . 210
8.2.11 IndexedGeometryArray Object . . . . . . . . . . . . . . . . . . . 211
8.2.12 IndexedPointArray Object. . . . . . . . . . . . . . . . . . . . . . . 214
8.2.13 IndexedLineArray Object . . . . . . . . . . . . . . . . . . . . . . . 214
8.2.14 IndexedTriangleArray Object . . . . . . . . . . . . . . . . . . . . 215
8.2.15 IndexedQuadArray Object . . . . . . . . . . . . . . . . . . . . . . 215
8.2.16 IndexedGeometryStripArray Object . . . . . . . . . . . . . . . 216
8.2.17 IndexedLineStripArray Object . . . . . . . . . . . . . . . . . . . 217
8.2.18 IndexedTriangleStripArray Object . . . . . . . . . . . . . . . . 218
8.2.19 IndexedTriangleFanArray Object . . . . . . . . . . . . . . . . . 218
8.2.20 CompressedGeometry Object . . . . . . . . . . . . . . . . . . . . 219
8.2.21 CompressedGeometryHeader Object . . . . . . . . . . . . . . 222
8.2.22 Raster Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
8.2.23 Font3D Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
8.2.24 FontExtrusion Object . . . . . . . . . . . . . . . . . . . . . . . . . . 227
8.2.25 Text3D Geometry Object . . . . . . . . . . . . . . . . . . . . . . . 228
8.3 Math Component Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
8.3.1 Tuple Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
8.3.2 Matrix Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234

9 View Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235

9.1 Why a New Model? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
9.1.1 The Physical Environment Influences the View . . . . . . 236
9.2 Separation of Physical and Virtual . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
9.2.1 The Virtual World . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
9.2.2 The Physical World . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237

vi The Java 3D API Specification

 9.3 The Objects That Define the View . . . . . . . . . . . . . . . . . . . . . . . . . . .238
9.4 ViewPlatform: A Place in the Virtual World . . . . . . . . . . . . . . . . . . .239
9.4.1 Moving Through the Virtual World . . . . . . . . . . . . . . . .240
9.4.2 Dropping In on a Favorite Place. . . . . . . . . . . . . . . . . . .241
9.4.3 View Attach Policy. . . . . . . . . . . . . . . . . . . . . . . . . . . . .242
9.4.4 Associating Geometry with a ViewPlatform . . . . . . . . .243
9.5 Generating a View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .243
9.5.1 Composing Model and Viewing Transformations . . . . .243
9.5.2 Multiple Locales . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .245
9.6 A Minimal Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .246
9.7 The View Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .246
9.7.1 Projection Policy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .249
9.7.2 Clip Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .251
9.7.3 Projection and Clip Parameters . . . . . . . . . . . . . . . . . . .251
9.7.4 Frame Start Time, Duration, and Number . . . . . . . . . . .253
9.7.5 View Traversal and Behavior Scheduling . . . . . . . . . . .254
9.7.6 Scene Antialiasing . . . . . . . . . . . . . . . . . . . . . . . . . . . . .255
9.7.7 Depth Buffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .255
9.8 The Screen3D Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .256
9.8.1 Off-screen Rendering . . . . . . . . . . . . . . . . . . . . . . . . . . .257
9.9 The Canvas3D Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .257
9.9.1 Window System–Provided Parameters . . . . . . . . . . . . .259
9.9.2 Off-screen Rendering . . . . . . . . . . . . . . . . . . . . . . . . . . .259
9.9.3 Other Canvas3D Parameters. . . . . . . . . . . . . . . . . . . . . .260
9.9.4 GraphicsConfigTemplate3D Object . . . . . . . . . . . . . . . .263
9.10 The PhysicalBody Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .264
9.11 The PhysicalEnvironment Object . . . . . . . . . . . . . . . . . . . . . . . . . . . .265

10 Behaviors and Interpolators . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267

10.1 Behavior Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .267
10.1.1 Code Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .268
10.1.2 WakeupCondition Object . . . . . . . . . . . . . . . . . . . . . . . .269
10.1.3 WakeupCriterion Object. . . . . . . . . . . . . . . . . . . . . . . . .269
10.1.4 Composing WakeupCriterion Objects . . . . . . . . . . . . . .270
10.2 Composing Behaviors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .270
10.3 Scheduling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .270
10.4 How Java 3D Performs Execution Culling . . . . . . . . . . . . . . . . . . . . .271
10.5 The Behavior API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .272
10.5.1 The Behavior Node. . . . . . . . . . . . . . . . . . . . . . . . . . . . .272
10.5.2 WakeupCondition Object . . . . . . . . . . . . . . . . . . . . . . . .274
10.5.3 The WakeupCriterion Objects . . . . . . . . . . . . . . . . . . . .274
10.6 Interpolator Behaviors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .285
10.6.1 Mapping Time to Alpha . . . . . . . . . . . . . . . . . . . . . . . . .285
10.6.2 Acceleration of Alpha. . . . . . . . . . . . . . . . . . . . . . . . . . .289
10.6.3 The Alpha Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .289
10.6.4 The Interpolator Base Class . . . . . . . . . . . . . . . . . . . . . .294
10.6.5 PositionInterpolator Object. . . . . . . . . . . . . . . . . . . . . . .295
10.6.6 RotationInterpolator Object . . . . . . . . . . . . . . . . . . . . . .296

Version 1.2, March 2000 vii

 CONTENTS

10.6.7 ColorInterpolator Object . . . . . . . . . . . . . . . . . . . . . . . . 298

10.6.8 ScaleInterpolator Object . . . . . . . . . . . . . . . . . . . . . . . . 299
10.6.9 SwitchValueInterpolator Object . . . . . . . . . . . . . . . . . . 300
10.6.10 TransparencyInterpolator Object. . . . . . . . . . . . . . . . . . 301
10.6.11 PathInterpolator Object . . . . . . . . . . . . . . . . . . . . . . . . . 302
10.6.12 PositionPathInterpolator Object . . . . . . . . . . . . . . . . . . 303
10.6.13 RotPosPathInterpolator Object . . . . . . . . . . . . . . . . . . . 305
10.6.14 RotPosScalePathInterpolator Object . . . . . . . . . . . . . . . 307
10.6.15 RotationPathInterpolator Object . . . . . . . . . . . . . . . . . . 308
10.7 Level-of-Detail Behaviors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
10.7.1 LOD Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
10.7.2 DistanceLOD Object . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
10.8 Billboard Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312

11 Input Devices and Picking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315

11.1 InputDevice Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
11.1.1 The Abstract Interface . . . . . . . . . . . . . . . . . . . . . . . . . . 316
11.1.2 Instantiating and Registering a New Device . . . . . . . . . 317
11.2 Sensors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
11.2.1 Using and Assigning Sensors . . . . . . . . . . . . . . . . . . . . 318
11.2.2 Behind the (Sensor) Scenes. . . . . . . . . . . . . . . . . . . . . . 318
11.2.3 The Sensor Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
11.2.4 The SensorRead Object . . . . . . . . . . . . . . . . . . . . . . . . . 322
11.3 Picking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
11.3.1 SceneGraphPath Object. . . . . . . . . . . . . . . . . . . . . . . . . 324
11.3.2 BranchGroup Node and Locale Node Pick Methods . . 327
11.3.3 PickShape Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
11.3.4 PickBounds Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
11.3.5 PickPoint Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
11.3.6 PickRay Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
11.3.7 PickSegment Object . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
11.3.8 PickCone Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
11.3.9 PickConeRay Object . . . . . . . . . . . . . . . . . . . . . . . . . . . 331
11.3.10 PickConeSegment Object . . . . . . . . . . . . . . . . . . . . . . . 331
11.3.11 PickCylinder Object . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
11.3.12 PickCylinderRay Object . . . . . . . . . . . . . . . . . . . . . . . . 332
11.3.13 PickCylinderSegment Object . . . . . . . . . . . . . . . . . . . . 333

12 Audio Devices. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335

12.1 AudioDevice Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
12.1.1 Initialization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
12.1.2 Audio Playback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336
12.1.3 Device-Driver-Specific Data. . . . . . . . . . . . . . . . . . . . . 338
12.2 AudioDevice3D Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
12.3 Instantiating and Registering a New Device . . . . . . . . . . . . . . . . . . . 344

13 Execution and Rendering Model . . . . . . . . . . . . . . . . . . . . . . . . . 345

13.1 Three Major Rendering Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345

viii The Java 3D API Specification

 13.1.1 Immediate Mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .345
13.1.2 Retained Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .346
13.1.3 Compiled-retained Mode . . . . . . . . . . . . . . . . . . . . . . . .346
13.2 Instantiating the Render Loop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .347
13.2.1 An Application-level Perspective. . . . . . . . . . . . . . . . . .347
13.2.2 Retained and Compiled-retained Rendering Modes. . . .347

14 Immediate-Mode Rendering . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349

14.1 Two Styles of Immediate-Mode Rendering . . . . . . . . . . . . . . . . . . . .349
14.1.1 Pure Immediate-Mode Rendering . . . . . . . . . . . . . . . . .349
14.1.2 Mixed-Mode Rendering . . . . . . . . . . . . . . . . . . . . . . . . .351
14.2 Canvas3D Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .352
14.3 API for Immediate Mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .354
14.3.1 GraphicsContext3D . . . . . . . . . . . . . . . . . . . . . . . . . . . .354
14.3.2 J3DGraphics2D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .360

A Math Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363

A.1 Tuple Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .363
A.1.1 Tuple2d Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .363
A.1.2 Tuple2f Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .369
A.1.3 Tuple3b Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .375
A.1.4 Tuple3d Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .377
A.1.5 Tuple3f Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .383
A.1.6 Tuple3i Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .390
A.1.7 Tuple4b Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .393
A.1.8 Tuple4d Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .396
A.1.9 Tuple4f Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .404
A.1.10 Tuple4i Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .412
A.1.11 AxisAngle4d Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . .415
A.1.12 AxisAngle4f Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . .417
A.1.13 GVector Class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .419
A.2 Matrix Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .423
A.2.1 Matrix3f Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .424
A.2.2 Matrix3d Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .430
A.2.3 Matrix4f Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .437
A.2.4 Matrix4d Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .445
A.2.5 GMatrix Class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .453

B 3D Geometry Compression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459

B.1 Compression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .460
B.2 Decompression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .460
B.3 Appendix Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .460
B.4 Generalized Triangle Strip. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .461
B.5 Generalized Triangle Mesh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .463
B.6 Position Representation and Quantization. . . . . . . . . . . . . . . . . . . . . .465
B.7 Color Representation and Quantization. . . . . . . . . . . . . . . . . . . . . . . .466
B.8 Normal Representation and Quantization . . . . . . . . . . . . . . . . . . . . . .467
B.8.1 Normals as Indices . . . . . . . . . . . . . . . . . . . . . . . . . . . . .468

Version 1.2, March 2000 ix

 CONTENTS

B.8.2 Normal Encoding Parameterization . . . . . . . . . . . . . . . 469

B.8.3 Special Warping Rules for Delta Normals . . . . . . . . . . 471
B.9 Modified Huffman Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 473
B.10 Compressed Geometry Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . 475
B.11 Bit Layout of Compressed Geometry Instructions. . . . . . . . . . . . . . . 475
B.12 Compressed Geometry Instruction Bit Details. . . . . . . . . . . . . . . . . . 476
B.12.1 nop Instruction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 476
B.12.2 setState Instruction . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477
B.12.3 setTable Instruction . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479
B.12.4 mbr (meshBufferReference) Instruction . . . . . . . . . . . . 480
B.12.5 Position Sub-instruction . . . . . . . . . . . . . . . . . . . . . . . . 482
B.12.6 Color Sub-instruction . . . . . . . . . . . . . . . . . . . . . . . . . . 483
B.12.7 Normal Sub-instruction . . . . . . . . . . . . . . . . . . . . . . . . . 484
B.12.8 vertex Instruction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488
B.12.9 setNormal Instruction . . . . . . . . . . . . . . . . . . . . . . . . . . 489
B.12.10 setColor Instruction . . . . . . . . . . . . . . . . . . . . . . . . . . . . 489
B.13 Semantics of Compressed Geometry Instructions . . . . . . . . . . . . . . . 490
B.13.1 Header and Body to Variable-Length Instruction . . . . . 490
B.13.2 Variable-Length Instruction to Instruction . . . . . . . . . . 491
B.13.3 Delta Position to Position . . . . . . . . . . . . . . . . . . . . . . . 492
B.13.4 Delta Color to Color . . . . . . . . . . . . . . . . . . . . . . . . . . . 492
B.13.5 Encoded Delta Normal to Encoded Normal . . . . . . . . . 492
B.13.6 Encoded Normal to Rectilinear Normal . . . . . . . . . . . . 493
B.14 Semantics of Vertices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493
B.14.1 Instruction to Vertex . . . . . . . . . . . . . . . . . . . . . . . . . . . 493
B.14.2 Vertex to Intermediate Triangle . . . . . . . . . . . . . . . . . . 494
B.14.3 Intermediate Triangle to Final Triangle . . . . . . . . . . . . 495
B.15 Outline of Geometry Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 496
B.15.1 Compressing Geometry Data . . . . . . . . . . . . . . . . . . . . 496
B.15.2 Convert to Generalized Mesh Format . . . . . . . . . . . . . . 496
B.15.3 Position . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 496
B.15.4 Normals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497
B.15.5 Colors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498
B.15.6 Collect Delta Code Statistics. . . . . . . . . . . . . . . . . . . . . 499
B.15.7 Position Delta Code Statistics . . . . . . . . . . . . . . . . . . . . 499
B.15.8 Color Delta Code Statistics . . . . . . . . . . . . . . . . . . . . . . 499
B.15.9 Normal Delta Code Statistics . . . . . . . . . . . . . . . . . . . . 499
B.15.10 Assign Huffman Tags . . . . . . . . . . . . . . . . . . . . . . . . . . 501
B.15.11 Assemble the Pieces into a Bit Stream . . . . . . . . . . . . . 501
B.16 Compressed Geometry Assembly Syntax . . . . . . . . . . . . . . . . . . . . . 501
B.17 Compressed Geometry Instruction Verifier . . . . . . . . . . . . . . . . . . . . 504

C View Model Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 509

C.1 An Overview of the Java 3D View Model . . . . . . . . . . . . . . . . . . . . . 509
C.2 Physical Environments and Their Effects . . . . . . . . . . . . . . . . . . . . . 510
C.2.1 A Head-mounted Example . . . . . . . . . . . . . . . . . . . . . . 510
C.2.2 A Room-mounted Example. . . . . . . . . . . . . . . . . . . . . . 510
C.2.3 Impact of Head Position and Orientation on the
Camera. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 510

x The Java 3D API Specification

 C.3 The Coordinate Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .511
C.3.1 Room-mounted Coordinate Systems . . . . . . . . . . . . . . .511
C.3.2 Head-mounted Coordinate Systems . . . . . . . . . . . . . . . .513
C.4 The ViewPlatform Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .514
C.5 The View Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .514
C.5.1 View Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .515
C.5.2 Screen Scale Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . .516
C.5.3 Window Eyepoint Policy . . . . . . . . . . . . . . . . . . . . . . . .516
C.5.4 Monoscopic View Policy . . . . . . . . . . . . . . . . . . . . . . . .517
C.5.5 Visibility Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .518
C.5.6 Coexistence Centering Enable . . . . . . . . . . . . . . . . . . . .519
C.5.7 Eyepoint in Coexistence . . . . . . . . . . . . . . . . . . . . . . . . .519
C.5.8 Sensors and Their Location in the Virtual World. . . . . .519
C.6 The Screen3D Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .520
C.6.1 Screen3D Calibration Parameters. . . . . . . . . . . . . . . . . .521
C.6.2 Accessing and Changing Head Tracker Coordinates . . .522
C.7 The Canvas3D Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .522
C.7.1 Scene Antialiasing . . . . . . . . . . . . . . . . . . . . . . . . . . . . .523
C.7.2 Accessing and Modifying an Eye’s Image Plate
Position . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .523
C.7.3 Canvas Width and Height. . . . . . . . . . . . . . . . . . . . . . . .524
C.7.4 Monoscopic View Policy . . . . . . . . . . . . . . . . . . . . . . . .524
C.8 The PhysicalBody Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .525
C.9 The PhysicalEnvironment Object . . . . . . . . . . . . . . . . . . . . . . . . . . . .527
C.10 Viewing in Head-tracked Environments . . . . . . . . . . . . . . . . . . . . . . .529
C.10.1 A Room-mounted Display with Head Tracking. . . . . . .530
C.10.2 A Head-mounted Display with Head Tracking . . . . . . .530
C.11 Compatibility Mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .530
C.11.1 Overview of the Camera-based View Model . . . . . . . . .531
C.11.2 Using the Camera-based View Model . . . . . . . . . . . . . .532

D Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 537
D.1 BadTransformException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .537
D.2 CapabilityNotSetException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .538
D.3 DanglingReferenceException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .538
D.4 IllegalRenderingStateException . . . . . . . . . . . . . . . . . . . . . . . . . . . . .539
D.5 IllegalSharingException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .539
D.6 MismatchedSizeException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .540
D.7 MultipleParentException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .540
D.8 RestrictedAccessException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .540
D.9 SceneGraphCycleException . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .541
D.10 SingularMatrixException. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .541
D.11 SoundException. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .542

E Equations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 543
E.1 Fog Equations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .543
E.2 Lighting Equations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .544
E.3 Sound Equations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .546

Version 1.2, March 2000 xi

 CONTENTS

E.3.1 Headphone Playback Equations . . . . . . . . . . . . . . . . . . 546

E.3.2 Speaker Playback Equations . . . . . . . . . . . . . . . . . . . . . 554
E.4 Texture Mapping Equations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 556
E.4.1 Texture Lookup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 556
E.4.2 Texture Application. . . . . . . . . . . . . . . . . . . . . . . . . . . . 558

F The Utility Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 561

F.1 The Utility Packages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 561
F.2 Package Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 562
F.3 audioengines Package. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 563
F.4 audioengines.javasound Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . 563
F.5 loaders Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 564
F.5.1 Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 564
F.5.2 Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 564
F.5.3 Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 564
F.6 loaders.lw3d Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 565
F.7 loaders.objectfile Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 565
F.8 utils.applet Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 566
F.9 utils.behaviors.interpolators Package . . . . . . . . . . . . . . . . . . . . . . . . . 566
F.10 utils.behaviors.keyboard Package . . . . . . . . . . . . . . . . . . . . . . . . . . . 567
F.11 utils.behaviors.mouse Package. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 567
F.11.1 Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 568
F.11.2 Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 568
F.12 utils.compression Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 568
F.13 utils.geometry Package. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 569
F.14 utils.image Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 571
F.15 utils.picking Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 571
F.16 utils.picking.behaviors Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 572
F.16.1 Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 572
F.16.2 Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 573
F.17 utils.universe Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 573

G CD-ROM Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 575

G.1 What’s on the CD-ROM. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 575
G.2 Installing the Software on Windows 95/98/NT Systems . . . . . . . . . . 576
G.2.1 Requirements for Windows Systems . . . . . . . . . . . . . . 576
G.2.2 Installing the Java 2 SDK on Windows Systems . . . . . 576
G.2.3 Installing the Java 3D API on Windows Systems. . . . . 577
G.2.4 Installing the Javadocs on Windows Systems. . . . . . . . 578
G.3 Installing the Software on Solaris Systems . . . . . . . . . . . . . . . . . . . . 578
G.3.1 Requirements for Solaris Systems. . . . . . . . . . . . . . . . . 578
G.3.2 Installing Sun OpenGL 1.2 for Solaris . . . . . . . . . . . . . 579
G.3.3 Installing Patches on Solaris . . . . . . . . . . . . . . . . . . . . . 579
G.3.4 Installing the Java 2 SDK on Solaris Systems . . . . . . . 580
G.3.5 Installing the Java 3D API on Solaris Systems . . . . . . . 581
G.3.6 Installing the Javadocs on Solaris Systems . . . . . . . . . . 582
G.4 Accessing the Documentation from the CD-ROM . . . . . . . . . . . . . . 582

xii The Java 3D API Specification

H The Example Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 585
H.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .585
H.2 Running the Example Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . .585
H.2.1 Running within a Browser . . . . . . . . . . . . . . . . . . . . . . .586
H.2.2 Running within Appletviewer . . . . . . . . . . . . . . . . . . . .587
H.3 Program Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .587
H.3.1 AWT_Interaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .588
H.3.2 AlternateAppearance . . . . . . . . . . . . . . . . . . . . . . . . . . .589
H.3.3 Appearance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .589
H.3.4 AppearanceMixed. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .592
H.3.5 Background. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .593
H.3.6 Billboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .594
H.3.7 ConicWorld . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .594
H.3.8 FourByFour . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .594
H.3.9 GearTest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .595
H.3.10 GeometryByReference . . . . . . . . . . . . . . . . . . . . . . . . . .595
H.3.11 GeometryCompression . . . . . . . . . . . . . . . . . . . . . . . . . .595
H.3.12 HelloUniverse. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .596
H.3.13 LOD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .596
H.3.14 Lightwave . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .596
H.3.15 ModelClip. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .597
H.3.16 Morphing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .597
H.3.17 ObjLoad . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .597
H.3.18 OffScreenCanvas3D . . . . . . . . . . . . . . . . . . . . . . . . . . . .598
H.3.19 OrientedShape3D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .599
H.3.20 PackageInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .599
H.3.21 PickTest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .599
H.3.22 PickText3D. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .600
H.3.23 PlatformGeometry . . . . . . . . . . . . . . . . . . . . . . . . . . . . .601
H.3.24 PureImmediate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .601
H.3.25 ReadRaster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .603
H.3.26 Sound . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .603
H.3.27 SphereMotion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .603
H.3.28 SplineAnim. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .603
H.3.29 Text2D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .604
H.3.30 Text3D . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .604
H.3.31 TextureByReference. . . . . . . . . . . . . . . . . . . . . . . . . . . .604
H.3.32 TextureTest. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .605
H.3.33 TickTockCollision . . . . . . . . . . . . . . . . . . . . . . . . . . . . .605
H.3.34 TickTockPicking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .605
H.3.35 VirtualInputDevice . . . . . . . . . . . . . . . . . . . . . . . . . . . . .605

Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 607

Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 611

Version 1.2, March 2000 xiii

 Figures

Figure 1-1 Java 3D Object Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7

Figure 1-2 Application Scene Graph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7
Figure 2-1 A Simple Scene Graph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13
Figure 2-2 Content Branch, View Branch, and Superstructure . . . . . . . . . . . . . . . . . .14
Figure 3-1 A Java 3D Scene Graph Is a DAG (Directed Acyclic Graph) . . . . . . . . . .20
Figure 3-2 Viewing a Scene Graph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .29
Figure 4-1 The Virtual Universe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .32
Figure 5-1 Group Node Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41
Figure 5-2 Altering the Scene Graph at Run Time . . . . . . . . . . . . . . . . . . . . . . . . . . .45
Figure 6-1 Leaf Node Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .52
Figure 6-2 PointSound Distance Gain Attenuation . . . . . . . . . . . . . . . . . . . . . . . . . . .87
Figure 6-3 ConeSound . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .89
Figure 6-4 ConeSound with a Single Distance Gain Attenuation Array . . . . . . . . . . .93
Figure 6-5 ConeSound with Two Distance Gain Attenuation Arrays . . . . . . . . . . . . .93
Figure 6-6 Multiple Soundscape Application Regions . . . . . . . . . . . . . . . . . . . . . . . .96
Figure 7-1 Sharing a Subgraph. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .106
Figure 7-2 Referenced and Duplicated NodeComponent Objects . . . . . . . . . . . . . . .110
Figure 7-3 References to Other Scene Graph Nodes . . . . . . . . . . . . . . . . . . . . . . . . .111
Figure 7-4 Updated Subgraph after updateNodeReferences Call . . . . . . . . . . . .111
Figure 7-5 Dangling Reference: Bold Nodes Are Being Cloned. . . . . . . . . . . . . . . .113
Figure 8-1 Attribute Component Object Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . .120
Figure 8-2 Sound Reverberation Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .153
Figure 8-3 Geometry Component Object Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . .190
Figure 8-4 Various Text Alignments and Paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . .231
Figure 9-1 View Object, Its Component Objects, and Their Interconnection . . . . . .238
Figure 9-2 A Portion of a Scene Graph Containing a ViewPlatform Object. . . . . . .240
Figure 9-3 A Simple Scene Graph with View Control . . . . . . . . . . . . . . . . . . . . . . .241
Figure 9-4 Object and ViewPlatform Transformations . . . . . . . . . . . . . . . . . . . . . . .244
Figure 10-1 An Interpolator’s Generic Time-to-Alpha Mapping Sequence . . . . . . . .286
Figure 10-2 An Interpolator Set to a Loop Count of 1 with Mode Flags Set to Enable Only
the Alpha-Increasing and Alpha-at-1 Portion of the Waveform . . . . . . .286

Version 1.2, March 2000 xv

 FIGURES

Figure 10-3 An Interpolator Set to a Loop Count of 1 with Mode Flags Set to Enable Only
the Alpha-Decreasing and Alpha-at-0 Portion of the Waveform . . . . . . 287
Figure 10-4 An Interpolator Set to a Loop Count of 1 with Mode Flags Set to Enable All
Portions of the Waveform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
Figure 10-5 An Interpolator Set to Loop Infinitely and Mode Flags Set to Enable Only the
Alpha-Increasing and Alpha-at-1 Portion of the Waveform . . . . . . . . . . 288
Figure 10-6 An Interpolator Set to Loop Infinitely and Mode Flags Set to Enable Only the
Alpha-Decreasing and Alpha-at-0 Portion of the Waveform . . . . . . . . . 288
Figure 10-7 An Interpolator Set to Loop Infinitely and Mode Flags Set to Enable All
Portions of the Waveform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
Figure 10-8 How an Alpha-Increasing Waveform Changes with Various Values of
increasingAlphaRampDuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
Figure 14-1 Minimal Immediate-Mode Structure. . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
Figure A-1 Math Object Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364
Figure B-1 A Generalized Triangle Strip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462
Figure B-2 A Generalized Triangle Strip . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463
Figure B-3 Encoding of the Six Sextants of Each Octant of a Sphere . . . . . . . . . . . 470
Figure B-4 Sextant Coordinates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471
Figure B-5 Sextant Neighbors and Their Relationships . . . . . . . . . . . . . . . . . . . . . . 472
Figure B-6 Bit Layout of Compressed Geometry Instructions . . . . . . . . . . . . . . . . . 478
Figure C-1 Display Rigidly Attached to the Tracker Base . . . . . . . . . . . . . . . . . . . . 512
Figure C-2 Display Rigidly Attached to the Head Tracker (Sensor). . . . . . . . . . . . . 514
Figure C-3 A Portion of a Scene Graph Containing a Single Screen3D Object . . . . 520
Figure C-4 A Single-Screen Display Environment . . . . . . . . . . . . . . . . . . . . . . . . . . 520
Figure C-5 A Portion of a Scene Graph Containing Three Screen3D Objects . . . . . 521
Figure C-6 A Three-Screen Display Environment . . . . . . . . . . . . . . . . . . . . . . . . . . 521
Figure C-7 The Camera-based View Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 532
Figure C-8 A Perspective Viewing Frustum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534
Figure C-9 Perspective View Model Arguments. . . . . . . . . . . . . . . . . . . . . . . . . . . . 534
Figure C-10 Orthographic View Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 535
Figure E-1 Signal to Only One Ear Is Direct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 547
Figure E-2 Signals to Both Ears Are Indirect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 548
Figure E-3 ConeSound with a Single Distance Gain Attenuation Array . . . . . . . . . 550
Figure E-4 ConeSound with Two Distance Attenuation Arrays . . . . . . . . . . . . . . . . 550

xvi The Java 3D API Specification

 Preface

T HIS document describes the Java 3D™ API, version 1.2, and presents some
details on the implementation of the API. This specification is not intended as a
programmer’s guide.
This specification is written for 3D graphics application programmers. We assume
that the reader has at least a rudimentary understanding of computer graphics. This
includes familiarity with the essentials of computer graphics algorithms as well as
familiarity with basic graphics hardware and associated terminology.

Related Documentation
This specification is intended to be used in conjunction with the browser-accessi-
ble, javadoc-generated API reference.

Style Conventions
The following style conventions are used in this specification:
• Lucida type is used to represent computer code and the names of files and
directories.
• Bold Lucida type is used for Java 3D API declarations.
• Bold type is used to represent variables.
• Italic type is used for emphasis and for equations.

Programming Conventions
Java 3D uses the following programming conventions:
• The default coordinate system is right-handed, with +Y being up, +X
horizontal to the right, and +Z directed toward the viewer.

Version 1.2, March 2000 xvii

 PREFACE

• All angles or rotational representations are in radians.

• All distances are expressed in units or fractions of meters.

Acknowledgments
We gratefully acknowledge Warren Dale for writing the Sound API portion of this
specification and Daniel Petersen for writing the scene graph sharing portion of the
specification. We especially acknowledge Bruce Bartlett for his invaluable assis-
tance with the editing, formatting, and indexing of the specification. Without
Bruce’s considerable help, this book would not have been possible.
We also thank the many individuals and companies that provided comments and
suggestions. They have improved the Java 3D API.
Henry Sowizral
Kevin Rushforth
Michael Deering
Sun Microsystems, Inc.
April 2000

xviii The Java 3D API Specification

 C H A P T E R 1
Introduction to Java 3D

T HE Java 3D API is an application programming interface used for writing

three-dimensional graphics applications and applets. It gives developers high-
level constructs for creating and manipulating 3D geometry and for constructing
the structures used in rendering that geometry. Application developers can
describe very large virtual worlds using these constructs, which provide Java 3D
with enough information to render these worlds efficiently.
Java 3D delivers Java’s “write once, run anywhere” benefit to developers of 3D
graphics applications. Java 3D is part of the JavaMedia suite of APIs, making it
available on a wide range of platforms. It also integrates well with the Internet
because applications and applets written using the Java 3D API have access to
the entire set of Java classes.
The Java 3D API draws its ideas from existing graphics APIs and from new tech-
nologies. Java 3D’s low-level graphics constructs synthesize the best ideas found
in low-level APIs such as Direct3D, OpenGL, QuickDraw3D, and XGL. Simi-
larly, its higher-level constructs synthesize the best ideas found in several scene
graph–based systems. Java 3D introduces some concepts not commonly consid-
ered part of the graphics environment, such as 3D spatial sound. Java 3D’s sound
capabilities help to provide a more immersive experience for the user.

1.1 Goals
Java 3D was designed with several goals in mind. Chief among them is high per-
formance. Several design decisions were made so that Java 3D implementations
can deliver the highest level of performance to application users. In particular,
when trade-offs were made, the alternative that benefited runtime execution was
chosen.
Other important Java 3D goals are to
Version 1.2, March 2000 1
1.2 Programming Paradigm INTRODUCTION TO JAVA 3D

• Provide a rich set of features for creating interesting 3D worlds, tempered

by the need to avoid nonessential or obscure features. Features that could
be layered on top of Java 3D were not included.
• Provide a high-level object-oriented programming paradigm that enables
developers to deploy sophisticated applications and applets rapidly.
• Provide support for runtime loaders. This allows Java 3D to accommodate
a wide variety of file formats, such as vendor-specific CAD formats, inter-
change formats, and VRML97.

1.2 Programming Paradigm

Java 3D is an object-oriented API. Applications construct individual graphics
elements as separate objects and connect them together into a treelike structure
called a scene graph. The application manipulates these objects using their pre-
defined accessor, mutator, and node-linking methods.

1.2.1 The Scene Graph Programming Model

Java 3D’s scene graph–based programming model provides a simple and flexible
mechanism for representing and rendering scenes. The scene graph contains a
complete description of the entire scene, or virtual universe. This includes the
geometric data, the attribute information, and the viewing information needed to
render the scene from a particular point of view. Chapter 3, “Scene Graph
Basics,” provides more information on the Java 3D scene graph programming
model.
The Java 3D API improves on previous graphics APIs by eliminating many of
the bookkeeping and programming chores that those APIs impose. Java 3D
allows the programmer to think about geometric objects rather than about trian-
gles—about the scene and its composition rather than about how to write the ren-
dering code for efficiently displaying the scene.

1.2.2 Rendering Modes

Java 3D includes three different rendering modes: immediate mode, retained
mode, and compiled-retained mode (see Chapter 13, “Execution and Rendering
Model”). Each successive rendering mode allows Java 3D more freedom in opti-
mizing an application’s execution. Most Java 3D applications will want to take
advantage of the convenience and performance benefits that the retained and
compiled-retained modes provide.

2 The Java 3D API Specification

INTRODUCTION TO JAVA 3D Extensibility 1.2.3

1.2.2.1 Immediate Mode

Immediate mode leaves little room for global optimization at the scene graph
level. Even so, Java 3D has raised the level of abstraction and accelerates imme-
diate mode rendering on a per-object basis. An application must provide a
Java 3D draw method with a complete set of points, lines, or triangles, which are
then rendered by the high-speed Java 3D renderer. Of course, the application can
build these lists of points, lines, or triangles in any manner it chooses.

1.2.2.2 Retained Mode

Retained mode requires an application to construct a scene graph and specify
which elements of that scene graph may change during rendering. The scene
graph describes the objects in the virtual universe, the arrangement of those
objects, and how the application animates those objects.

1.2.2.3 Compiled-Retained Mode

Compiled-retained mode, like retained mode, requires the application to con-
struct a scene graph and specify which elements of the scene graph may change
during rendering. Additionally, the application can compile some or all of the
subgraphs that make up a complete scene graph. Java 3D compiles these graphs
into an internal format. The compiled representation of the scene graph may bear
little resemblance to the original tree structure provided by the application, how-
ever, it is functionally equivalent. Compiled-retained mode provides the highest
performance.

1.2.3 Extensibility
Most Java 3D classes expose only accessor and mutator methods. Those methods
operate only on that object’s internal state, making it meaningless for an applica-
tion to override them. Therefore, Java 3D does not provide the capability to over-
ride the behavior of Java 3D attributes. To make Java 3D work correctly,
applications must call “super.setXxxxx” for any attribute state set method that
is overridden.
Applications can extend Java 3D’s classes and add their own methods. However,
they may not override Java 3D’s scene graph traversal semantics because the
nodes do not contain explicit traversal and draw methods. Java 3D’s renderer
retains those semantics internally.
Java 3D does provide hooks for mixing Java 3D–controlled scene graph render-
ing and user-controlled rendering using Java 3D’s immediate mode constructs

Version 1.2, March 2000 3

1.3 High Performance INTRODUCTION TO JAVA 3D

(see Section 14.1.2, “Mixed-Mode Rendering”). Alternatively, the application

can stop Java 3D’s renderer and do all its drawing in immediate mode (see
Section 14.1.1, “Pure Immediate-Mode Rendering”).
Behaviors require applications to extend the Behavior object and to override its
methods with user-written Java code. These extended objects should contain ref-
erences to those scene graph objects that they will manipulate at run time.
Chapter 10, “Behaviors and Interpolators,” describes Java 3D’s behavior model.

1.3 High Performance

Java 3D’s programming model allows the Java 3D API to do the mundane tasks,
such as scene graph traversal, managing attribute state changes, and so forth,
thereby simplifying the application’s job. Java 3D does this without sacrificing
performance. At first glance, it might appear that this approach would create
more work for the API, however, it actually has the opposite effect. Java 3D’s
higher level of abstraction not only changes the amount but, more important, also
the kind of work the API must perform. Java 3D does not need to impose the
same type of constraints as do APIs with a lower level of abstraction, thus allow-
ing Java 3D to introduce optimizations not possible with these lower-level APIs.
Additionally, leaving the details of rendering to Java 3D allows it to tune the ren-
dering to the underlying hardware. For example, relaxing the strict rendering
order imposed by other APIs allows parallel traversal as well as parallel render-
ing. Knowing which portions of the scene graph cannot be modified at run time
allows Java 3D to flatten the tree, pretransform geometry, or represent the geom-
etry in a native hardware format without the need to keep the original data.

1.3.1 Layered Implementation

Besides optimizations at the scene graph level, one of the more important factors
that determines the performance of Java 3D is the time it takes to render the vis-
ible geometry. Java 3D implementations are layered to take advantage of the
native, low-level API that is available on a given system. In particular, Java 3D
implementations that use Direct3D and OpenGL are available. This means that
Java 3D rendering will be accelerated across the same wide range of systems that
are supported by these lower-level APIs.

1.3.2 Target Hardware Platforms

Java 3D is aimed at a wide range of 3D-capable hardware and software plat-
forms, from low-cost PC game cards and software renderers at the low end,
4 The Java 3D API Specification
INTRODUCTION TO JAVA 3D Games 1.4.2

through midrange workstations, all the way up to very high-performance special-

ized 3D image generators.
Java 3D implementations are expected to provide useful rendering rates on most
modern PCs, especially those with 3D graphics accelerator cards. On midrange
workstations, Java 3D is expected to provide applications with nearly full-speed
hardware performance.
Finally, Java 3D is designed to scale as the underlying hardware platforms
increase in speed over time. Tomorrow’s 3D PC game accelerators will support
more complex virtual worlds than high-priced workstations of a few years ago.
Java 3D is prepared to meet this increase in hardware performance.

1.4 Support for Building Applications and Applets

Java 3D neither anticipates nor directly supports every possible 3D need. Instead
it provides support for adding those features through Java code.
Objects defined using a computer-aided design (CAD) system or an animation
system may be included in a Java 3D-based application. Most such modeling
packages have an external format (sometimes proprietary). Designers can export
geometry designed using an external modeler to a file. Java 3D can use that geo-
metric information, but only if an application provides a means for reading and
translating the modeler’s file format into Java 3D primitives.
Similarly, VRML loaders will parse and translate VRML files and generate the
appropriate Java 3D objects and Java code necessary to support the file’s con-
tents.

1.4.1 Browsers
Today’s Internet browsers support 3D content by passing such data to plug-in 3D
viewers that render into their own window. It is anticipated that, over time, the
display of 3D content will become integrated into the main browser display. In
fact, some of today’s 3D browsers display 2D content as 2D objects within a 3D
world.

1.4.2 Games
Developers of 3D game software have typically attempted to wring out every last
ounce of performance from the hardware. Historically they have been quite will-
ing to use hardware-specific, nonportable optimizations to get the best perfor-

Version 1.2, March 2000 5

1.5 Overview of Java 3D Object Hierarchy INTRODUCTION TO JAVA 3D

mance possible. As such, in the past, game developers have tended to program
below the level of easy-to-use software such as Java 3D. However, the trend in
3D games today is to leverage general-purpose 3D hardware accelerators and to
use fewer “tricks” in rendering.
So, while Java 3D was not explicitly designed to match the game developer’s
every expectation, Java 3D’s sophisticated implementation techniques should
provide more than enough performance to support many game applications. One
might argue that applications written using a general API like Java 3D may have
a slight performance penalty over those employing special, nonportable tech-
niques. However, other factors such as portability, time to market, and develop-
ment cost must be weighed against absolute peak performance.

1.5 Overview of Java 3D Object Hierarchy

Java 3D defines several basic classes that are used to construct and manipulate a
scene graph and to control viewing and rendering. Figure 1-1 shows the overall
object hierarchy used by Java 3D. Subsequent chapters provide more detail for
specific portions of the hierarchy.

1.6 Structuring the Java 3D Program

This section illustrates how a developer might structure a Java 3D application.
The simple application in this example creates a scene graph that draws an object
in the middle of a window and rotates the object about its center point.

1.6.1 Java 3D Application Scene Graph

The scene graph for the sample application is shown in Figure 1-2.
The scene graph consists of superstructure components—a VirtualUniverse
object and a Locale object—and a set of branch graphs. Each branch graph is a
subgraph that is rooted by a BranchGroup node that is attached to the superstruc-
ture. For more information, see Chapter 3, “Scene Graph Basics.”
A VirtualUniverse object defines a named universe. Java 3D permits the creation
of more than one universe, though the vast majority of applications will use just
one. The VirtualUniverse object provides a grounding for scene graphs. All
Java 3D scene graphs must connect to a VirtualUniverse object to be displayed.
For more information, see Chapter 4, “Scene Graph Superstructure.”

6 The Java 3D API Specification

INTRODUCTION TO JAVA 3D Java 3D Application Scene Graph 1.6.1

javax.media.j3d
VirtualUniverse
Locale
View
PhysicalBody
PhysicalEnvironment
Screen3D
Canvas3D (extends awt.Canvas)
SceneGraphObject
Node
Group
Leaf
NodeComponent
Various component objects
Transform3D
javax.vecmath
Matrix classes
Tuple classes

Figure 1-1 Java 3D Object Hierarchy

VirtualUniverse Object

Locale Object

BG BG BranchGroup Nodes

Behavior Node B T TransformGroup Nodes T

User Code Shape3D Node

and Data S VP View
ViewPlatform Object
Other Objects
Appearance Geometry

Figure 1-2 Application Scene Graph

Below the VirtualUniverse object is a Locale object. The Locale object defines
the origin, in high-resolution coordinates, of its attached branch graphs. A virtual

Version 1.2, March 2000 7

1.6.2 Recipe for a Java 3D Program INTRODUCTION TO JAVA 3D

universe may contain as many Locales as needed. In this example, a single

Locale object is defined with its origin at (0.0, 0.0, 0.0).
The scene graph itself starts with the BranchGroup nodes (see Section 5.2,
“BranchGroup Node”). A BranchGroup serves as the root of a subgraph, called a
branch graph, of the scene graph. Only BranchGroup objects can attach to
Locale objects.
In this example there are two branch graphs and, thus, two BranchGroup nodes.
Attached to the left BranchGroup are two subgraphs. One subgraph consists of a
user-extended Behavior leaf node. The Behavior node contains Java code for
manipulating the transformation matrix associated with the object’s geometry.
The other subgraph in this BranchGroup consists of a TransformGroup node that
specifies the position (relative to the Locale), orientation, and scale of the geo-
metric objects in the virtual universe. A single child, a Shape3D leaf node, refers
to two component objects: a Geometry object and an Appearance object. The
Geometry object describes the geometric shape of a 3D object (a cube in our
simple example). The Appearance object describes the appearance of the geome-
try (color, texture, material reflection characteristics, and so forth).
The right BranchGroup has a single subgraph that consists of a TransformGroup
node and a ViewPlatform leaf node. The TransformGroup specifies the position
(relative to the Locale), orientation, and scale of the ViewPlatform. This trans-
formed ViewPlatform object defines the end user’s view within the virtual uni-
verse.
Finally, the ViewPlatform is referenced by a View object that specifies all of the
parameters needed to render the scene from the point of view of the ViewPlat-
form. Also referenced by the View object are other objects that contain informa-
tion, such as the drawing canvas into which Java 3D renders, the screen that
contains the canvas, and information about the physical environment.

1.6.2 Recipe for a Java 3D Program

The following steps are taken by the example program to create the scene graph
elements and link them together. Java 3D will then render the scene graph and
display the graphics in a window on the screen:
1. Create a Canvas3D object and add it to the Applet panel.
2. Create a BranchGroup as the root of the scene branch graph.
3. Construct a Shape3D node with a TransformGroup node above it.
4. Attach a RotationInterpolator behavior to the TransformGroup.

8 The Java 3D API Specification

INTRODUCTION TO JAVA 3D HelloUniverse: A Sample Java 3D Program 1.6.3

5. Call the simple universe utility function to do the following:

a. Establish a virtual universe with a single high-resolution Locale (see
Chapter 3, “Scene Graph Basics”).
b. Create the PhysicalBody, PhysicalEnvironment, View, and ViewPlat-
form objects.
c. Create a BranchGroup as the root of the view platform branch graph.
d. Insert the view platform branch graph into the Locale.
6. Insert the scene branch graph into the simple universe’s Locale.
The Java 3D renderer then starts running in an infinite loop. The renderer con-
ceptually performs the following operations:

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

1.6.3 HelloUniverse: A Sample Java 3D Program

Here are code fragments from a simple program, HelloUniverse.java, that cre-
ates a cube and a RotationInterpolator behavior object that rotates the cube at a
constant rate of π/2 radians per second.

1.6.3.1 HelloUniverse Class

The HelloUniverse class, on the next page, creates the branch graph that includes
the cube and the RotationInterpolator behavior. It then adds this branch graph to
the Locale object generated by the SimpleUniverse utility.

Version 1.2, March 2000 9

1.6.3 HelloUniverse: A Sample Java 3D Program INTRODUCTION TO JAVA 3D

public class HelloUniverse extends Applet {

public BranchGroup createSceneGraph() {
// Create the root of the branch graph
BranchGroup objRoot = new BranchGroup();

// Create the TransformGroup node and initialize it to the

// identity. Enable the TRANSFORM_WRITE capability so that
// our behavior code can modify it at run time. Add it to
// the root of the subgraph.
TransformGroup objTrans = new TransformGroup();
objTrans.setCapability(
TransformGroup.ALLOW_TRANSFORM_WRITE);
objRoot.addChild(objTrans);

// Create a simple Shape3D node; add it to the scene graph.

objTrans.addChild(new ColorCube(0.4));

// Create a new Behavior object that will perform the

// desired operation on the specified transform and add
// it into the scene graph.
Transform3D yAxis = new Transform3D();
Alpha rotationAlpha = new Alpha(-1, 4000);
RotationInterpolator rotator = new RotationInterpolator(
rotationAlpha, objTrans, yAxis,
0.0f, (float) Math.PI*2.0f);
BoundingSphere bounds =
new BoundingSphere(new Point3d(0.0,0.0,0.0), 100.0);
rotator.setSchedulingBounds(bounds);
objRoot.addChild(rotator);

// Have Java 3D perform optimizations on this scene graph.

objRoot.compile();

return objRoot;
}

public HelloUniverse() {
<construct canvas3d, set layout of applet, create canvas>

// Create the scene; attach it to the virtual universe

BranchGroup scene = createSceneGraph();
SimpleUniverse u = new SimpleUniverse(canvas3d);
u.getViewingPlatform().setNominalViewingTransform();
u.addBranchGraph(scene);
}
}

10 The Java 3D API Specification

 C H A P T E R 2
Java 3D Concepts

A specification serves to precisely define objects, methods, and their actions. It

is not the best way to learn an API. Describing how to use an API belongs in a tuto-
rial or programmer’s reference manual—and that is well beyond the scope of this
book. However, a short introduction to the main concepts in Java 3D can provide
the context for understanding the detailed, but isolated, specification found in the
remainder of this book.
This chapter introduces Java 3D concepts and illustrates them with some simple
program fragments. Appendix H, “The Example Programs” describes the exam-
ples included with the CD-ROM and highlights particular code segments for some
examples.

2.1 Basic Scene Graph Concepts

A scene graph is a “tree” structure that contains data arranged in a hierarchical
manner. The scene graph consists of parent nodes, child nodes, and data objects.
The parent nodes, called Group nodes, organize and, in some cases, control how
Java 3D interprets their descendants. Group nodes serve as the glue that holds a
scene graph together. Child nodes can either be Group nodes or Leaf nodes. Leaf
nodes have no children. They encode the core semantic elements of a scene graph,
for example what to draw (geometry), what to play (audio), how to illuminate
objects (lights), or what code to execute (behaviors). Leaf nodes refer to data
objects, called NodeComponent objects. NodeComponent objects are not scene
graph nodes, but they contain the data that Leaf nodes require, such as the geome-
try to draw or the sound sample to play.
A Java 3D application builds and manipulates a scene graph by constructing
Java 3D objects and then later modifying those objects by using their methods. A

Version 1.2, March 2000 11

2.1.1 Constructing a Simple Scene Graph JAVA 3D CONCEPTS

Java 3D program first constructs a scene graph, then, once built, hands that scene
graph to Java 3D for processing.
The structure of a scene graph determines the relationships among the objects in
the graph and determines which objects a programmer can manipulate as a single
entity. Group nodes provide a single point for handling or manipulating all the
nodes beneath it. A programmer can tune a scene graph appropriately by thinking
about what manipulations an application will need to perform. He or she can make
a particular manipulation easy or hard by grouping or regrouping nodes in various
ways.

2.1.1 Constructing a Simple Scene Graph

The code shown in Listing 2-1 constructs a simple scene graph consisting of a
group node and two leaf nodes. It first constructs one leaf node, the first of two
Shape3D nodes, using a constructor that takes both a Geometry and an Appearance
NodeComponent object. It then constructs the second Shape3D node, with only a
Geometry object. Next, since the second Shape3D node was created without an
Appearance object, it supplies the missing Appearance object using the Shape3D
node’s setAppearance method. At this point both leaf nodes have been fully con-
structed.
Listing 2-1 Code for Constructing a Simple Scene Graph

Shape3D myShape1 = new Shape3D(myGeometry1, myAppearance1);

Shape3D myShape2 = new Shape3D(myGeometry2);
myShape2.setAppearance(myAppearance2);

Group myGroup = new Group();

myGroup.addChild(myShape1);
myGroup.addChild(myShape2);

The code next constructs a group node to hold the two leaf nodes. It uses the Group
node’s addChild method to add the two leaf nodes to the group node as children,
finishing the construction of the scene graph. Figure 2-1 shows the constructed
scene graph, all the nodes, the node component objects, and the variables used in
constructing the scene graph.

2.1.2 A Place For Scene Graphs

Once a scene graph has been constructed, the question becomes what to do with it?
Java 3D cannot start rendering a scene graph until a program “gives” it the scene
graph. The program does this by inserting the scene graph into the virtual universe.

12 The Java 3D API Specification

JAVA 3D CONCEPTS A Place For Scene Graphs 2.1.2

Java 3D places restrictions on how a program can insert a scene graph into a uni-
verse.

myGroup

Group

myShape1 myShape2

myGeom1 myAppear1 myGeom2 myAppear2

Shape3D Shape3D

Geometry Appearance Geometry Appearance

Figure 2-1 A Simple Scene Graph

A Java 3D environment consists of two superstructure objects, VirtualUniverse and

Locale, and one or more graphs, rooted by a special BranchGroup node. Figure 2-2
shows these objects in context with other scene graph objects.
The VirtualUniverse object defines a universe. A universe allows a Java 3D pro-
gram to create a separate and distinct arena for defining objects and their relation-
ships to one another. Typically, Java 3D programs only have one VirtualUniverse
object. Programs that have more than one VirtualUniverse may share NodeCompo-
nent objects but not scene graph node objects.
The Locale object specifies a fixed position within the universe. That fixed position
defines an origin for all scene graph nodes beneath it. The Locale object allows a
programmer to specify that origin very precisely and with very high dynamic
range. A Locale can accurately specify a location anywhere in the known physical
universe and at the precision of Plank’s distance. Typically, Java 3D programs only
have one Locale object with a default origin of (0, 0, 0). Programs that have more
than one Locale object will set the location of the individual Locale objects so that
they provide an appropriate local origin for the nodes beneath them. For example,
to model the Mars landing, a programmer might create one Locale object with an
origin at Cape Canaveral and another with an origin located at the landing site on
Mars.

Version 1.2, March 2000 13

2.1.2 A Place For Scene Graphs JAVA 3D CONCEPTS

VirtualUniverse Object

Locale Object

Content branch BG View branch

BG

Content nodes
VP View
ViewPlatform Object
Other Objects

Figure 2-2 Content Branch, View Branch, and Superstructure

The BranchGroup node serves as the root of a branch graph. Collectively, the
BranchGroup node and all of its children form the branch graph. The two kinds of
branch graphs are called content branches and view branches. A content branch
contains only content-related leaf nodes while a view branch contains a ViewPlat-
form leaf node and may contain other content-related leaf nodes. Typically, a uni-
verse contains more than one branch graph. One view branch and any number of
content branches.
Besides serving as the root of a branch graph, the BranchGroup node has two spe-
cial properties: it alone may be inserted into a Locale object and it may be com-
piled. Java 3D treats uncompiled and compiled branch graphs identically, though
compiled branch graphs will typically render more efficiently.
We could not insert the scene graph created by our simple example (Listing 2-1)
into a Locale because it does not have a BranchGoup node for its root. Listing 2-2
shows a modified version of our first code example that creates a simple content
branch graph and the minimum of superstructure objects. Of special note, Locales
do not have children and they are not part of the scene graph. The method for insert-
ing a branch graph is addBranchGraph not addChild, the method for adding chil-
dren to all group nodes.

14 The Java 3D API Specification

JAVA 3D CONCEPTS Processing a Scene Graph 2.1.4

Listing 2-2 Code for Constructing a Scene Graph and Some Superstructure Objects

Shape3D myShape1 = new Shape3D(myGeometry1, myAppearance1);

Shape3D myShape2 = new Shape3D(myGeometry2, myAppearance2);

BranchGroup myBranch = new BranchGroup();

myBranch.addChild(myShape1);
myBranch.addChild(myShape2);
myBranch.compile();

VirtualUniverse myUniverse = new VirtualUniverse();

Locale myLocale = new Locale(myUniverse);
myLocale.addBranchGraph(myBranch);

2.1.3 SimpleUniverse Utility

Most Java 3D programs build an identical set of superstructure and view branch
objects, so the Java 3D utility packages provide a universe package for construct-
ing and manipulating the objects in a view branch. The classes in the universe
package provide a quick means for building a single view (single window) appli-
cation. Listing 2-3 shows a code fragment for using the SimpleUniverse class. Note
that the SimpleUniverse constructor takes a Canvas3D as an argument, in this case
referred to by the variable myCanvas.
Listing 2-3 Code for Constructing a Scene Graph Using the Universe Package

import com.sun.j3d.utils.universe.*;

Shape3D myShape1 = new Shape3D(myGeometry1, myAppearance1);

Shape3D myShape2 = new Shape3D(myGeometry2, myAppearance2);

BranchGroup myBranch = new BranchGroup();

myBranch.addChild(myShape1);
myBranch.addChild(myShape2);
myBranch.compile();

SimpleUniverse myUniv = new SimpleUniverse(myCanvas);

myUniv.addBranchGraph(myBranch);

2.1.4 Processing a Scene Graph

When given a scene graph, Java 3D processes that scene graph as efficiently as pos-
sible. How a Java 3D implementation processes a scene graph can vary, as long as
the implementation conforms to the semantics of the API. In general, a Java 3D
implementation will render all visible objects, play all enabled sounds, execute all

Version 1.2, March 2000 15

2.2 Features of Java 3D JAVA 3D CONCEPTS

triggered behaviors, process any identified input devices, and check for and gener-
ate appropriate collision events.
The order that a particular Java 3D implementation renders objects onto the display
is carefully not defined. One implementation might render the first Shape3D object
and then the second. Another might first render the second Shape3D node before it
renders the first one. Yet another implementation may render them in parallel.

2.2 Features of Java 3D

Java 3D allows a programmer to specify a broad range of information. It allows
control over the shape of objects, their color, and transparency. It allows control
over background effects, lighting, and environmental effects such as fog. It allows
control over the placement of all objects (even non-visible objects such as lights
and behaviors) in the scene graph and over their orientation and scale. It allows
control over how those objects move, rotate, stretch, shrink, or morph over time. It
allows control over what code should execute, what sounds should play and how
those sounds should sound and change over time.
Java 3D provides different techniques for controlling the effect of various features.
Some techniques act fairly locally, such as getting the color of a vertex. Other tech-
niques have broader influence, such as changing the color or appearance of an
entire object. Still other techniques apply to a broad number of objects. In the first
two cases, the programmer can modify a particular object or an object associated
with the affected object. In the latter case, Java 3D provides a means for specifying
more than one object spatially.

2.2.1 Bounds
Bounds objects allow a programmer to define a volume in space. There are three
ways to specify this volume: as a box, a sphere, or a set of planes enclosing a space.
Bounds objects specify a volume in which particular operations apply. Environ-
mental effects such as lighting, fog, alternate appearance, and model clipping
planes use bounds objects to specify their region of influence. Any object that falls
within the space defined by the bounds object has the particular environmental
effect applied. The proper use of bounds objects can ensure that these environmen-
tal effects are applied only to those objects in a particular volume, such as a light
applying only to the objects within a single room.
Bounds objects are also used to specify a region of action. Behaviors and sounds
only execute or play if they are close enough to the viewer. The use of behavior and

16 The Java 3D API Specification

JAVA 3D CONCEPTS Live and/or Compiled 2.2.3

sound bounds objects allows Java 3D to cull away those behaviors and sounds that
are too far away to affect the viewer (listener). By using bounds properly, a pro-
grammer can ensure that only the relevant behaviors and sounds execute or play.
Finally, bounds objects are used to specify a region of application for per-view
operations such as background, clip, and soundscape selection. For example, the
background node whose region of application is closest to the viewer is selected for
a given view.

2.2.2 Nodes
All scene graph nodes have an implicit location in space of (0, 0, 0). For objects
that exist in space, this implicit location provides a local coordinate system for that
object, a fixed reference point. Even abstract objects that may not seem to have a
well-defined location such as behaviors and ambient lights have this implicit loca-
tion. An object’s location provides an origin for its local coordinate system and just
as importantly an origin for any bounding volume information associated with that
object.

2.2.3 Live and/or Compiled

All scene graph objects, including nodes and node component objects, are either
part of an active universe or not. An object is said to be live if it is part of an active
universe. Additionally, branch graphs are either compiled or not. When a node is
either live or compiled, Java 3D enforces access restrictions to nodes and node
component objects. Java 3D allows only those operations enabled by the program
before a node or node component becomes live or is compiled. It is best to set capa-
bilities when you build your content. Listing 2-4 shows an example where we cre-
ate a TransformGroup node and enable it for writing.
Listing 2-4 Capabilities Example

TransformGroup myTrans = new TransformGroup();

myTrans.setCapability(Transform.ALLOW_TRANSFORM_WRITE);

By setting the capability to write the transform, Java 3D will allow the following
code to execute:
myTrans.setTransform3D(myT3D);

However, the following code will cause an exception:

myTrans.getTransform3D(myT3D);

Version 1.2, March 2000 17

2.2.3 Live and/or Compiled JAVA 3D CONCEPTS

The reason for the exception is that the TransformGroup is not enabled for reading
(ALLOW_TRANSFORM_READ).
It is important to ensure that all needed capabilities are set and that unnecessary
capabilities are not set. The process of compiling a branch graph examines the
capability bits and uses that information to reduce the amount of computation
needed to run a program.

18 The Java 3D API Specification

 C H A P T E R 3
Scene Graph Basics

A scene graph consists of Java 3D objects, called nodes, arranged in a tree

structure. The user creates one or more scene subgraphs and attaches them to a
virtual universe. The individual connections between Java 3D nodes always rep-
resent a directed relationship: parent to child. Java 3D restricts scene graphs in
one major way: Scene graphs may not contain cycles. Thus, a Java 3D scene
graph is a directed acyclic graph (DAG). See Figure 3-1.
Java 3D refines the Node object class into two subclasses: Group and Leaf node
objects. Group node objects group together one or more child nodes. A group
node can point to zero or more children but can have only one parent. The
SharedGroup node cannot have any parents (although it allows sharing portions
of a scene graph, as described in Chapter 7, “Reusing Scene Graphs”). Leaf node
objects contain the actual definitions of shapes (geometry), lights, fog, sounds,
and so forth. A leaf node has no children and only one parent. The semantics of
the various group and leaf nodes are described in subsequent chapters.

3.1 Scene Graph Structure

A scene graph organizes and controls the rendering of its constituent objects. The
Java 3D renderer draws a scene graph in a consistent way that allows for concur-
rence. The Java 3D renderer can draw one object independently of other objects.
Java 3D can allow such independence because its scene graphs have a particular
form and cannot share state among branches of a tree.

3.1.1 Spatial Separation

The hierarchy of the scene graph encourages a natural spatial grouping on the
geometric objects found at the leaves of the graph. Internal nodes act to group
their children together. A group node also defines a spatial bound that contains

Version 1.2, March 2000 19

3.1.2 State Inheritance SCENE GRAPH BASICS

all the geometry defined by its descendants. Spatial grouping allows for efficient
implementation of operations such as proximity detection, collision detection,
view frustum culling, and occlusion culling.

Virtual Universe

Hi-Res Locales

BG BG BG BranchGroup Nodes

Leaf Nodes

Figure 3-1 A Java 3D Scene Graph Is a DAG (Directed Acyclic Graph)

3.1.2 State Inheritance

A leaf node’s state is defined by the nodes in a direct path between the scene
graph’s root and the leaf. Because a leaf’s graphics context only relies on a linear
path between the root and that node, the Java 3D renderer can decide to traverse
the scene graph in whatever order it wishes. It can traverse the scene graph from
left to right and top to bottom, in level order from right to left, or even in paral-
lel. The only exceptions to this rule are spatially bounded attributes such as lights
and fog.
This characteristic is in marked contrast to many older scene graph–based APIs
(including PHIGS and SGI’s Inventor), where if a node above or to the left of a
node changes the graphics state, the change affects the graphics state of all nodes
below it or to its right.

20 The Java 3D API Specification

SCENE GRAPH BASICS Scene Graph Objects 3.2

The most common node object, along the path from the root to the leaf, that
changes the graphics state is the TransformGroup object. The TransformGroup
object can change the position, orientation, and scale of the objects below it.
Most graphics state attributes are set by a Shape3D leaf node through its constit-
uent Appearance object, thus allowing parallel rendering. The Shape3D node
also has a constituent Geometry object that specifies its geometry—this permits
different shape objects to share common geometry without sharing material
attributes (or vice versa).

3.1.3 Rendering
The Java 3D renderer incorporates all graphics state changes made in a direct
path from a scene graph root to a leaf object in the drawing of that leaf object.
Java 3D provides this semantic for both retained and compiled-retained modes.

3.2 Scene Graph Objects

A Java 3D scene graph consists of a collection of Java 3D node objects con-
nected in a tree structure. These node objects reference other scene graph objects
called node component objects. All scene graph node and component objects are
subclasses of a common SceneGraphObject class. The SceneGraphObject class
is an abstract class that defines methods that are common among nodes and com-
ponent objects.
Scene graph objects are constructed by creating a new instance of the desired
class and are accessed and manipulated using the object’s set and get methods.
Once a scene graph object is created and connected to other scene graph objects
to form a subgraph, the entire subgraph can be attached to a virtual universe—via
a high-resolution Locale object—making the object live (see Section 4.6.2,
“Locale Object”). Prior to attaching a subgraph to a virtual universe, the entire
subgraph can be compiled into an optimized, internal format (see Section 5.2,
“BranchGroup Node”).
An important characteristic of all scene graph objects is that they can only be
accessed or modified during the creation of a scene graph, except where explic-
itly allowed. Access to most set and get methods of objects that are part of a
live or compiled scene graph is restricted. Such restrictions provide the scene
graph compiler with usage information it can use in optimally compiling or ren-
dering a scene graph. Each object has a set of capability bits that enable certain
functionality when the object is live or compiled. By default, all capability bits
are disabled (cleared). Only those set and get methods corresponding to capa-

Version 1.2, March 2000 21

3.2 Scene Graph Objects SCENE GRAPH BASICS

bility bits that are explicitly enabled (set) prior to the object being compiled or
made live are legal. The methods for setting and getting capability bits are
described next.

Constructors
The SceneGraphObject specifies one constructor.

public SceneGraphObject()

Constructs a new SceneGraphObject with default parameters:

Parameters Default Values
capability bits clear (all bits)
isLive false
isCompiled false
userData null

Methods
The following methods are available on all scene graph objects.

public final boolean isCompiled()

public final boolean isLive()

The first method returns a flag that indicates whether the node is part of a scene
graph that has been compiled. If so, only those capabilities explicitly allowed by
the object’s capability bits are allowed. The second method returns a flag that
indicates whether the node is part of a scene graph that has been attached to a
virtual universe via a high-resolution Locale object.

public final boolean getCapability(int bit)

public final void setCapability(int bit)
public final void clearCapability(int bit)

These three methods provide applications with the means for accessing and mod-
ifying the capability bits of a scene graph object. The bit positions of the capabil-
ity bits are defined as public static final constants on a per-object basis. Every
instance of every scene graph object has its own set of capability bits. An exam-
ple of a capability bit is the ALLOW_BOUNDS_WRITE bit in node objects. Only those
methods corresponding to capabilities that are enabled before the object is first
compiled or made live are subsequently allowed for that object. A Restricte-
dAccessException is thrown if an application calls setCapability or clearCa-

22 The Java 3D API Specification

SCENE GRAPH BASICS Node Objects 3.2.1

pability on live or compiled objects. Note that only a single bit may be set or
cleared per method invocation—bits may not be ORed together.

public void setUserData(Object userData)

public Object getUserData()

These methods access or modify the userData field associated with this scene
graph object. The userData field is a reference to an arbitrary object and may be
used to store any user-specific data associated with this scene graph object—it is
not used by the Java 3D API. If this object is cloned, the userData field is copied
to the newly cloned object.

3.2.1 Node Objects

Node objects divide into group node objects and leaf node objects. Group nodes
serve to group their child node objects together according to the group node’s
semantics. Leaf nodes specify the actual elements that Java 3D uses in rendering;
specifically, geometric objects, lights, and sounds. These node objects are
described in Chapter 5, “Group Node Objects” and Chapter 6, “Leaf Node
Objects.”

Constants
Node object constants allow an application to individually enable runtime capa-
bilities. These capability bits are enforced only when the node is part of a live or
compiled scene graph.

public static final int ALLOW_BOUNDS_READ

public static final int ALLOW_BOUNDS_WRITE

These bits, when set using the setCapability method, specify that the node will
permit an application to invoke the getBounds and setBounds methods, respec-
tively. An application can choose to enable a particular set method but not the
associated get method, or vice versa. The application can choose to enable both
methods or, by default, leave the method(s) disabled.

public static final int ALLOW_AUTO_COMPUTE_BOUNDS_READ

public static final int ALLOW_AUTO_COMPUTE_BOUNDS_WRITE

These bits, when set using the setCapability method, specify that the node will
permit an application to invoke the getBoundsAutoCompute and set-
BoundsAutoCompute methods, respectively. An application can choose to enable
a particular set method but not the associated get method, or vice versa. The

Version 1.2, March 2000 23

3.2.1 Node Objects SCENE GRAPH BASICS

application can choose to enable both methods or, by default, leave the method(s)
disabled.

public static final int ENABLE_PICK_REPORTING

This flag specifies that this node will be reported in a SceneGraphPath. By

default, this is disabled.

public static final int ALLOW_PICKABLE_READ

public static final int ALLOW_PICKABLE_WRITE

These flags specify that this Node can have its pickability read or changed.

public static final int ENABLE_COLLISION_REPORTING

This flag specifies that this Node will be reported in the collision SceneGraph-
Path if a collision occurs. This capability is only specifiable for Group nodes; it
is ignored for Leaf nodes. The default for Group nodes is false. All interior nodes
not needed for uniqueness in a SceneGraphPath that don’t have this flag set to
true will not be reported in the SceneGraphPath.

public static final int ALLOW_COLLIDABLE_READ

public static final int ALLOW_COLLIDABLE_WRITE

These flags specify that this Node allows read or write access to its collidability
state.

public static final int ALLOW_LOCAL_TO_VWORLD_READ

This flag specifies that this node allows read access to its local-coordinates-to-
virtual-world-(Vworld)-coordinates transform.

Constructors
The Node object specifies the following constructor.

public Node()

This constructor constructs and initializes a Node object with default values. The
Node class provides an abstract class for all group and leaf nodes. It provides a
common framework for constructing a Java 3D scene graph, specifically, bound-
ing volumes. The default values are:
Parameters Default Value
pickable true
collidable true

24 The Java 3D API Specification

SCENE GRAPH BASICS Node Objects 3.2.1

Parameters Default Value

bounds autoCompute true
bounds N/A (automatically computed)

Methods
The following methods are available on Node objects, subject to the capabilities
that are enabled for live or compiled nodes.

public Node getParent()

Retrieves the parent of this node, or null if this node has no parent. This method
is only valid during the construction of the scene graph. If this object is part of a
live or compiled scene graph, a RestrictedAccessException will be thrown.

public Bounds getBounds()

public void setBounds(Bounds bounds)

These methods access or modify this node’s geometric bounds.

public void getLocalToVworld(Transform3D t)

public void getLocalToVworld(SceneGraphPath path, Transform3D t)

These methods access the local-coordinates-to-virtual-world-coordinates trans-

form for this node and place the result into the specified Transform3D argument.
The first form is used for nodes that are not part of a shared subgraph, the second
form is used for nodes that are part of a shared subgraph. The local-coordinates-
to-Vworld-coordinates transform is the composite of all transforms in the scene
graph from the root down to this node (via the specified Link nodes, in the sec-
ond case). It is only valid for nodes that are part of a live scene graph. An excep-
tion will be thrown if the node is not part of a live scene graph or if the
appropriate capability is not set. Additionally, the first form will throw an excep-
tion if the node is part of a shared subgraph.
public void setBoundsAutoCompute(boolean autoCompute)
public boolean getBoundsAutoCompute()

These methods set and get the value that determines whether the node’s geomet-
ric bounds are computed automatically, in which case the bounds will be read-
only, or are set manually, in which case the value specified by setBounds will be
used. The default is automatic.

Version 1.2, March 2000 25

3.2.2 NodeComponent Objects SCENE GRAPH BASICS

public void setPickable(boolean pickable)

public boolean getPickable()

These methods set and retrieve the flag indicating whether this node can be
picked. A setting of false means that this node and its children are all unpick-
able.

public void setCollidable(boolean collidable)

public boolean getCollidable()

The set method sets the collidable value. The get method returns the collidable
value. This value determines whether this node and its children, if a group node,
can be considered for collision purposes. If the value is false, neither this node
nor any children nodes will be traversed for collision purposes. The default value
is true. The collidable setting is the way that an application can perform collision
culling.

3.2.2 NodeComponent Objects

Node component objects include the actual geometry and appearance attributes
used to render the geometry. These component objects are described in
Chapter 8, “Node Component Objects.”

Constructors
The NodeComponent object specifies the following constructor.

public NodeComponent()

This constructor constructs and initializes a NodeComponent object with default

parameters. The NodeComponent class provides an abstract class for all compo-
nent objects. The default values are as follows:
Parameters Default Value
duplicate on clone tree false

Methods
The following methods are available on NodeComponent objects.

public void setDuplicateOnCloneTree(boolean duplicate)

public boolean getDuplicateOnCloneTree()

These methods access or modify the duplicateOnCloneTree value of the Node-

Component object. The duplicateOnCloneTree value is used by the cloneTree

26 The Java 3D API Specification

SCENE GRAPH BASICS Scene Graph Viewing Objects 3.4

method to determine if NodeComponent objects should be duplicated or just ref-

erenced in the cloned leaf object.

3.3 Scene Graph Superstructure Objects

Java 3D defines two scene graph superstructure objects, VirtualUniverse and
Locale, which are used to contain collections of subgraphs that comprise the
scene graph. These objects are described in more detail in Chapter 4, “Scene
Graph Superstructure.”

3.3.1 VirtualUniverse Object

A VirtualUniverse object consists of a list of Locale objects that contain a collec-
tion of scene graph nodes that exist in the universe. Typically, an application will
need only one VirtualUniverse, even for very large virtual databases. Operations
on a VirtualUniverse include enumerating the Locale objects contained within
the universe. See Section 4.6.1, “VirtualUniverse Object,” for more information.

3.3.2 Locale Object

The Locale object acts as a container for a collection of subgraphs of the scene
graph that are rooted by a BranchGroup node. A Locale also defines a location
within the virtual universe using high-resolution coordinates (HiResCoord) to
specify its position. The HiResCoord serves as the origin for all scene graph
objects contained within the Locale.
A Locale has no parent in the scene graph, but is implicitly attached to a virtual
universe when it is constructed. A Locale may reference an arbitrary number of
BranchGroup nodes, but has no explicit children.
The coordinates of all scene graph objects are relative to the HiResCoord of the
Locale in which they are contained. Operations on a Locale include setting or
getting the HiResCoord of the Locale, adding a subgraph, and removing a sub-
graph (see Section 4.6.2, “Locale Object,” for more information).

3.4 Scene Graph Viewing Objects

Java 3D defines five scene graph viewing objects that are not part of the scene
graph per se but serve to define the viewing parameters and to provide hooks into
the physical world. These objects are Canvas3D, Screen3D, View, PhysicalBody,

Version 1.2, March 2000 27

3.4.1 Canvas3D Object SCENE GRAPH BASICS

and PhysicalEnvironment. They are described in more detail in Chapter 9, “View

Model,” and Appendix C, “View Model Details.”

3.4.1 Canvas3D Object

The Canvas3D object encapsulates all of the parameters associated with the win-
dow being rendered into (see Section 9.9, “The Canvas3D Object”). When a
Canvas3D object is attached to a View object, the Java 3D traverser renders the
specified view onto the canvas. Multiple Canvas3D objects can point to the same
View object.

3.4.2 Screen3D Object

The Screen3D object encapsulates all of the parameters associated with the phys-
ical screen containing the canvas, such as the width and height of the screen in
pixels, the physical dimensions of the screen, and various physical calibration
values (see Section 9.8, “The Screen3D Object”).

3.4.3 View Object

The View object specifies information needed to render the scene graph.
Figure 3-2 shows a View object attached to a simple scene graph for viewing the
scene.
The View object is the central Java 3D object for coordinating all aspects of
viewing (see Section 9.7, “The View Object”). All viewing parameters in
Java 3D are either directly contained within the View object or within objects
pointed to by a View object. Java 3D supports multiple simultaneously active
View objects, each of which can render to one or more canvases.

3.4.4 PhysicalBody Object

The PhysicalBody object encapsulates all of the parameters associated with the
physical body, such as head position, right and left eye position, and so forth.
(see Section 9.10, “The PhysicalBody Object”).

3.4.5 PhysicalEnvironment Object

The PhysicalEnvironment object encapsulates all of the parameters associated
with the physical environment, such as calibration information for the tracker
base for the head or hand tracker (see Section 9.11, “The PhysicalEnvironment
Object”).

28 The Java 3D API Specification

SCENE GRAPH BASICS PhysicalEnvironment Object 3.4.5

Virtual Universe

Hi-Res Locale

BG

View Canvas3D Screen3D

VP
View
Platform

Physical Physical
Body Environment

Figure 3-2 Viewing a Scene Graph

Version 1.2, March 2000 29

 C H A P T E R 4
Scene Graph Superstructure

JAVA 3D’s superstructure consists of one or more VirtualUniverse objects, each

of which contains a set of one or more high-resolution Locale objects. The
Locale objects, in turn, contain collections of subgraphs that comprise the scene
graph (see Figure 4-1).

4.1 The Virtual Universe

Java 3D defines the concept of a virtual universe as a three-dimensional space
with an associated set of objects. Virtual universes serve as the largest unit of
aggregate representation, and can also be thought of as databases. Virtual uni-
verses can be very large, both in physical space units and in content. Indeed, in
most cases a single virtual universe will serve an application’s entire needs.
Virtual universes are separate entities in that no node object may exist in more
than one virtual universe at any one time. Likewise, the objects in one virtual
universe are not visible in, nor do they interact with objects in, any other virtual
universe.
To support large virtual universes, Java 3D introduces the concept of Locales that
have high-resolution coordinates as an origin. Think of high-resolution coordi-
nates as “tie-downs” that precisely anchor the locations of objects specified using
less precise floating-point coordinates that are within the range of influence of
the high-resolution coordinates.
A Locale, with its associated high-resolution coordinates, serves as the next level
of representation down from a virtual universe. All virtual universes contain one
or more high-resolution-coordinate Locales, and all other objects are attached to
a Locale. High-resolution coordinates act as an upper-level translation-only
transform node. For example, the coordinates of all objects attached to a particu-

Version 1.2, March 2000 31

4.2 Establishing a Scene SCENE GRAPH SUPERSTRUCTURE

lar Locale are all relative to the location of that Locale’s high-resolution coordi-
nates.

Virtual Universe

Hi-Res Locales

BG BG BG BranchGroup Nodes

Group Nodes

Leaf Nodes

Figure 4-1 The Virtual Universe

While a virtual universe is similar to the traditional computer graphics concept of

a scene graph, a given virtual universe can become so large that it is often better
to think of a scene graph as the descendent of a high-resolution-coordinate
Locale.

4.2 Establishing a Scene

To construct a three-dimensional scene, the programmer must execute a Java 3D
program. The Java 3D application must first create a VirtualUniverse object and
attach at least one Locale to it. Then the desired scene graph is constructed, start-
ing with a BranchGroup node and including at least one ViewPlatform object,
and is attached to the Locale. Finally, a View object is constructed that references
the ViewPlatform object (see Section 1.6, “Structuring the Java 3D Program”).
As soon as a scene graph containing a ViewPlatform is attached to the Virtu-
alUniverse, Java 3D’s rendering loop is engaged, and the scene will appear on
the drawing canvas(es) associated with the View object.

32 The Java 3D API Specification

SCENE GRAPH SUPERSTRUCTURE Java 3D High-resolution Coordinates 4.5.1

4.3 Loading a Virtual Universe

Java 3D is a runtime application programming interface (API), not a file format.
As an API, Java 3D provides no direct mechanism for loading or storing a virtual
universe. Constructing a scene graph involves the execution of a Java 3D pro-
gram. However, loaders to convert a number of standard 3D file formats to or
from Java 3D virtual universes are expected to be generally available.

4.4 Coordinate Systems

By default, Java 3D coordinate systems are right-handed, with the orientation
semantics being that +Y is the local gravitational up, +X is horizontal to the
right, and +Z is directly toward the viewer. The default units are meters.

4.5 High-resolution Coordinates

Double-precision floating-point, single-precision floating-point, or even fixed-
point representations of three-dimensional coordinates are sufficient to represent
and display rich 3D scenes. Unfortunately, scenes are not worlds, let alone uni-
verses. If one ventures even a hundred miles away from the (0.0, 0.0, 0.0) origin
using only single-precision floating-point coordinates, representable points
become quite quantized, to at very best a third of an inch (and much more
coarsely than that in practice).
To “shrink” down to a small size (say the size of an IC transistor), even very near
(0.0, 0.0, 0.0), the same problem arises.
If a large contiguous virtual universe is to be supported, some form of higher-res-
olution addressing is required. Thus the choice of 256-bit positional components
for “high-resolution” positions.

4.5.1 Java 3D High-resolution Coordinates

Java 3D high-resolution coordinates consist of three 256-bit fixed-point numbers,
one each for x, y, and z. The fixed point is at bit 128, and the value 1.0 is defined
to be exactly 1 meter. This coordinate system is sufficient to describe a universe
in excess of several hundred billion light years across, yet still define objects
smaller than a proton (down to below the planck length). Table 4-1 shows how
many bits are needed above or below the fixed point to represent the range of
interesting physical dimensions.

Version 1.2, March 2000 33

4.5.2 Java 3D Virtual World Coordinates SCENE GRAPH SUPERSTRUCTURE

Table 4-1 Java 3D High-Resolution Coordinates

2n Meters Units
87.29 Universe (20 billion light years)
69.68 Galaxy (100,000 light years)
53.07 Light year
43.43 Solar system diameter
23.60 Earth diameter
10.65 Mile
9.97 Kilometer
0.00 Meter
–19.93 Micron
–33.22 Angstrom
–115.57 Planck length

A 256-bit fixed-point number also has the advantage of being able to directly
represent nearly any reasonable single-precision floating-point value exactly.
High-resolution coordinates in Java 3D are only used to embed more traditional
floating point coordinate systems within a much higher-resolution substrate. In
this way a visually seamless virtual universe of any conceivable size or scale can
be created, without worry about numerical accuracy.

4.5.2 Java 3D Virtual World Coordinates

Within a given virtual world coordinate system, positions are expressed by three
floating point numbers. The virtual world coordinate scale is in meters, but this
can be affected by scale changes in the object hierarchy.

4.5.3 Details of High-resolution Coordinates

High-resolution coordinates are represented as signed, two’s-complement, fixed-
point numbers consisting of 256 bits. Although Java 3D keeps the internal repre-
sentation of high-resolution coordinates opaque, users specify such coordinates
using 8-element integer arrays. Java 3D treats the integer found at index 0 as
containing the most significant bits and that found at index 7 as containing the
least significant bits of the high-resolution coordinate. The binary point is located
at bit position 128, or between the integers at index 3 and 4. A high-resolution
coordinate of 1.0 is 1 meter.

34 The Java 3D API Specification

SCENE GRAPH SUPERSTRUCTURE Details of High-resolution Coordinates 4.5.3

The semantics of how file loaders deal with high-resolution coordinates is up to

the individual file loader, as Java 3D does not directly define any file-loading
semantics. However, some general advice can be given (note that this advice is
not officially part of the Java 3D specification).
For “small” virtual universes (on the order of hundreds of meters across in rela-
tive scale), a single Locale with high-resolution coordinates at location
(0.0, 0.0, 0.0) as the root node (below the VirtualUniverse object) is sufficient; a
loader can automatically construct this node during the loading process, and the
point in high-resolution coordinates does not need any direct representation in
the external file.
Larger virtual universes are expected to be usually constructed like computer
directory hierarchies, that is, as a “root” virtual universe containing mostly exter-
nal file references to embedded virtual universes. In this case, the file reference
object (user-specific data hung off a Java 3D group or hi-res node) defines the
location for the data to be read into the current virtual universe.
The data file’s contents should be parented to the file object node while being
read, thus inheriting the high-resolution coordinates of the file object as the new
relative virtual universe origin of the embedded scene graph. If this scene graph
itself contains high-resolution coordinates, it will need to be offset (translated) by
the amount in the file object’s high-resolution coordinates, and then added to the
larger virtual universe as new high-resolution coordinates, with their contents
hung off below them. Once again, the above procedure is not part of the official
Java 3D specification, but some more details on the care and use of high-resolu-
tion coordinates in external file formats will probably be available as a Java 3D
application note.
Authoring tools that directly support high-resolution coordinates should create
additional high-resolution coordinates as a user creates new geometry “suffi-
ciently” far away (or of different scale) from existing high-resolution coordi-
nates.
Semantics of widely moving objects. Most fixed and nearly-fixed objects stay
attached to the same high-resolution Locale. Objects that make wide changes in
position or scale may need to be periodically reparented to more appropriate
high-resolution Locale. If no appropriate high-resolution Locale exists, the appli-
cation may need to create a new one.
Semantics of viewing. The ViewPlatform object and the associated nodes in its
hierarchy are very often widely moving objects. Applications will typically
attach the view platform to the most appropriate high-resolution Locale. For dis-
play, all objects will first have their positions translated by the difference
Version 1.2, March 2000 35
4.6 API for Superstructure Objects SCENE GRAPH SUPERSTRUCTURE

between the location of their high-resolution Locale, and the view platform's
high-resolution Locale. (In the common case of the Locales being the same, no
translation is necessary.)

4.6 API for Superstructure Objects

This section describes the API for the VirtualUniverse, Locale, and HiResCoord
objects.

4.6.1 VirtualUniverse Object

The VirtualUniverse object consists of a set of Locale objects.

Constructors
The VirtualUniverse object has the following constructors.

public VirtualUniverse()

This constructs a new VirtualUniverse object. This VirtualUniverse can then be

used to create Locale objects.

Methods
The VirtualUniverse object has the following methods.

public Enumeration getAllLocales()

public int numLocales()

The first method returns the Enumeration object of all Locales in this virtual uni-
verse. The numLocales method returns the number of Locales.

public void removeLocale(Locale locale) New in 1.2

This method removes a Locale and its associates branch graphs from this uni-
verse. All branch graphs within the specified Locale are detached, regardless of
whether their ALLOW_DETACH capability bits are set. The Locale is then marked as
being dead: no branch graphs may subsequently be attached.

public void removeAllLocales() New in 1.2

This method removes all Locales and their associates branch graphs from this
universe. All branch graphs within each Locale are detached, regardless of
whether their ALLOW_DETACH capability bits are set. Each Locale is then marked

36 The Java 3D API Specification

SCENE GRAPH SUPERSTRUCTURE Locale Object 4.6.2

as being dead: no branch graphs may subsequently be attached. This method

should be called by applications and applets to allow Java 3D to cleanup its
resources.

public static void setJ3DThreadPriority(int priority) New in 1.2

public static int getJ3DThreadPriority() New in 1.2

These methods set and retrieve the priority of all Java 3D threads. The default
value is the priority of the thread that started Java 3D.

4.6.2 Locale Object

The Locale object consists of a point, specified using high-resolution coordi-
nates, and a set of subgraphs, rooted by BranchGroup node objects.

Constructors
The Locale object has the following constructors.

public Locale(VirtualUniverse universe)

public Locale(VirtualUniverse universe, int x[], int y[], int z[])
public Locale(VirtualUniverse universe, HiResCoord hiRes)

These three constructors create a new high-resolution Locale object in the speci-
fied VirtualUniverse. The first form constructs a Locale object located at
(0.0, 0.0, 0.0). The other two forms construct a Locale object using the specified
high-resolution coordinates. In the second form, the parameters x, y, and z are
arrays of eight 32-bit integers that specify the respective high-resolution coordi-
nate.

Methods
The Locale object has the following methods. For the Locale picking methods,
see Section 11.3.2, “BranchGroup Node and Locale Node Pick Methods.”

public VirtualUniverse getVirtualUniverse()

This method retrieves the virtual universe within which this Locale object is con-
tained.

public void setHiRes(int x[], int y[], int z[])

public void setHiRes(HiResCoord hiRes)
public void getHiRes(HiResCoord hiRes)

These methods set or get the high-resolution coordinates of this Locale.

Version 1.2, March 2000 37

4.6.3 HiResCoord Object SCENE GRAPH SUPERSTRUCTURE

public void addBranchGraph(BranchGroup branchGroup)

public void removeBranchGraph(BranchGroup branchGroup)
public void replaceBranchGraph(BranchGroup oldGroup,
BranchGroup newGroup)
public int numBranchGraphs()
public Enumeration getAllBranchGraphs()

The first three methods add, remove, and replace a branch graph in this Locale.
Adding a branch graph has the effect of making the branch graph “live.” The
fourth method retrieves the number of branch graphs in this Locale. The last
method retrieves an Enumeration object of all branch graphs.

4.6.3 HiResCoord Object

A HiResCoord object defines a point using a set of three high-resolution coordi-
nates, each of which consists of three two’s-complement fixed-point numbers.
Each high-resolution number consists of 256 total bits with a binary point at bit
128. Java 3D uses integer arrays of length eight to define or extract a single 256-
bit coordinate value. Java 3D interprets the integer at index 0 as the 32 most sig-
nificant bits and the integer at index 7 as the 32 least significant bits.

Constructors
The HiResCoord object has the following constructors.

public HiResCoord(int x[], int y[], int z[])

public HiResCoord(HiResCoord hc)
public HiResCoord()

The first constructor generates the high-resolution coordinate point from three
integer arrays of length eight. The integer arrays specify the coordinate values
corresponding with their name. The second constructor creates a new high-reso-
lution coordinate point by cloning the high-resolution coordinates hc. The third
constructor creates new high-resolution coordinates with value (0.0, 0.0, 0.0).

Methods

public void setHiResCoord(int x[], int y[], int z[])

public void setHiResCoord(HiResCoord hiRes)
public void setHiResCoordX(int x[])
public void setHiResCoordY(int y[])
public void setHiResCoordZ(int z[])

These five methods modify the value of high-resolution coordinates this. The
first method resets all three coordinate values with the values specified by the

38 The Java 3D API Specification

SCENE GRAPH SUPERSTRUCTURE HiResCoord Object 4.6.3

three integer arrays. The second method sets the value of this to that of high-
resolution coordinates hiRes. The third, fourth, and fifth methods reset the corre-
sponding coordinate of this.

public void getHiResCoord(int x[], int y[], int z[])

public void getHiResCoord(HiResCoord hc)
public void getHiResCoordX(int x[])
public void getHiResCoordY(int y[])
public void getHiResCoordZ(int z[])

These five methods retrieve the value of the high-resolution coordinates this.
The first method retrieves the high-resolution coordinates’ values and places
those values into the three integer arrays specified. All three arrays must have
length greater than or equal to eight. The second method updates the value of the
high-resolution coordinates hc to match the value of this. The third, fourth, and
fifth methods retrieve the coordinate value that corresponds to their name and
update the integer array specified, which must be of length eight or greater.

public void add(HiResCoord h1, HiResCoord h2)

public void sub(HiResCoord h1, HiResCoord h2)

These two methods perform arithmetic operations on high-resolution coordi-

nates. The first method adds h1 to h2 and stores the result in this. The second
method subtracts h2 from h1 and stores the result in this.

public void scale(int scale, HiResCoord h1)

public void scale(int scale)

These methods scale a high-resolution coordinate point. The first method scales
h1 by the scalar value scale and places the scaled coordinates into this. The
second method scales this by the scalar value scale and places the scaled coor-
dinates back into this.

public void negate(HiResCoord h1)

public void negate()

These two methods negate a high-resolution coordinate point. The first method
negates h1 and stores the result in this. The second method negates this and
stores its negated value back into this.

public void difference(HiResCoord h1, Vector3d v)

This method subtracts h1 from this and stores the resulting difference vector in
the double-precision floating-point vector v. Note that although the individual
high-resolution coordinate points cannot be represented accurately by double-

Version 1.2, March 2000 39

4.6.3 HiResCoord Object SCENE GRAPH SUPERSTRUCTURE

precision numbers, this difference vector between them can be accurately repre-
sented by doubles for many practical purposes, such as viewing.

public boolean equals(HiResCoord h1)

public boolean equals(Object o1)

The first method performs an arithmetic comparison between this and h1. It
returns true if the two high-resolution coordinate points are equal; otherwise, it
returns false. The second method returns true if the Object o1 is of type HiRes-
Coord and all of the data members of o1 are equal to the corresponding data
members in this HiResCoord.

public double distance(HiResCoord h1)

This method computes the linear distance between high-resolution coordinate

points this and h1, and returns this value expressed as a double. Note that
although the individual high-resolution coordinate points cannot be represented
accurately by double precision numbers, this distance between them can be accu-
rately represented by a double for many practical purposes.

40 The Java 3D API Specification

 C H A P T E R 5
Group Node Objects

G ROUP nodes are the glue elements used in constructing a scene graph. The
following subsections list the seven group nodes (see Figure 5-1) and their defi-
nitions. All group nodes can have a variable number of child node objects—
including other group nodes as well as leaf nodes. These children have an asso-
ciated index that allows operations to specify a particular child. However, unless
one of the special ordered group nodes is used, the Java 3D renderer can choose
to render a group node’s children in whatever order it wishes (including render-
ing the children in parallel).

SceneGraphObject
Node
Group
BranchGroup
OrderedGroup
DecalGroup
SharedGroup
Switch
TransformGroup

Figure 5-1 Group Node Hierarchy

5.1 Group Node

The Group node object is a general-purpose grouping node. Group nodes have
exactly one parent and an arbitrary number of children that are rendered in an
unspecified order (or in parallel). Null children are allowed; no operation is per-
formed on a null child node. Operations on Group node objects include adding,
removing, and enumerating the children of the Group node. The subclasses of
Group node add additional semantics.

Version 1.2, March 2000 41

5.1 Group Node GROUP NODE OBJECTS

Constants

public static final int ALLOW_CHILDREN_READ

public static final int ALLOW_CHILDREN_WRITE
public static final int ALLOW_CHILDREN_EXTEND

These flags, when enabled using the setCapability method, specify that this
Group node will allow the following methods, respectively:
• numChildren, getChild, getAllChildren
• setChild, insertChild, removeChild
• addChild, moveTo

These capability bits are enforced only when the node is part of a live or com-
piled scene graph.

public static final int ALLOW_COLLISION_BOUNDS_READ

public static final int ALLOW_COLLISION_BOUNDS_WRITE

These flags, when enabled using the setCapability method, specify that this
Group node will allow reading and writing of its collision bounds.

Constructors

public Group()

Constructs and initializes a Group node object with default parameters:

collision bounds = null
alternate collision target = false

Methods
The Group node class defines the following methods.

public int numChildren()

public Node getChild(int index)

The first method returns a count of the number of children. The second method
returns the child at the specified index.

public void setChild(Node child, int index)

public void insertChild(Node child, int index)
public void removeChild(int index)

The first method replaces the child at the specified index with a new child. The

42 The Java 3D API Specification

GROUP NODE OBJECTS Group Node 5.1

second method inserts a new child before the child at the specified index. The
third method removes the child at the specified index. Note that if this Group
node is part of a live or compiled scene graph, only BranchGroup nodes may be
added to or removed from it—and only if the appropriate capability bits are set.

public Enumeration getAllChildren()

This method returns an Enumeration object of all children.

public void addChild(Node child)

This method adds a new child as the last child in the group. Note that if this
Group node is part of a live or compiled scene graph, only BranchGroup nodes
may be added to it—and only if the appropriate capability bits are set.

public void moveTo(BranchGroup branchGroup)

This method moves the specified BranchGroup node from its old location in the
scene graph to the end of this group, in an atomic manner. Functionally, this
method is equivalent to the following lines:

branchGroup.detach();
this.addChild(branchGroup);

If either this Group or the specified BranchGroup is part of a live or compiled

scene graph, the appropriate capability bits must be set in the affected nodes.

public Bounds setCollisionBounds(Bounds bounds)

public Bounds getCollisionBounds()

These methods set and retrieve the collision bounding object for a node.

public void setAlternateCollisionTarget(boolean target)

public boolean getAlternateCollisionTarget()

The set method causes this Group node to be reported as the collision target
when collision is being used and this node or any of its children is in a collision.
The default is false. This method tries to set the capability bit
Node.ENABLE_COLLISION_REPORTING. The get method returns the collision tar-
get state.
For collision with USE_GEOMETRY set, the collision traverser will check the
geometry of all the Group node’s leaf descendants. For collision with
USE_BOUNDS set, the collision traverser will check the bounds at this Group

Version 1.2, March 2000 43

5.2 BranchGroup Node GROUP NODE OBJECTS

node. In both cases, if there is a collision, this Group node will be reported as the
colliding object in the SceneGraphPath.

5.2 BranchGroup Node

A BranchGroup is the root of a subgraph of a scene that may be compiled as a
unit, attached to a virtual universe, or included as a child of a group node in
another subgraph. A subgraph, rooted by a BranchGroup node, can be thought of
as a compile unit. The following things may be done with BranchGroup.
• A BranchGroup may be compiled by calling its compile method. This
causes the entire subgraph to be compiled. If any BranchGroup nodes are
contained within the subgraph, they are compiled as well (along with their
descendants).
• A BranchGroup may be inserted into a virtual universe by attaching it to a
Locale. The entire subgraph is then said to be live.
• A BranchGroup that is contained within another subgraph may be
reparented or detached at run time if the appropriate capabilities are set.
See Figure 5-2.
Note that if a BranchGroup is included in another subgraph, as a child of some
other group node, it may not be attached to a Locale.

Constants
The BranchGroup class adds the following new constant.

public static final int ALLOW_DETACH

This flag, when enabled using the setCapability method, allows this Branch-
Group node to be detached from its parent group node. This capability flag is
enforced only when the node is part of a live or compiled scene graph.

Constructors

public BranchGroup()

Constructs and initializes a new BranchGroup node object.

Methods
The BranchGroup class defines the following methods.

44 The Java 3D API Specification

GROUP NODE OBJECTS TransformGroup Node 5.3

Virtual Universe

Hi-Res Locale

BG BranchGroup Node

BG
Can be reparented or
removed at run time

Figure 5-2 Altering the Scene Graph at Run Time

public void compile()

This method compiles the scene graph rooted at this BranchGroup and creates
and caches a newly compiled scene graph.

public void detach()

This method detaches the BranchGroup node from its parent.

5.3 TransformGroup Node

The TransformGroup node specifies a single spatial transformation—via a
Transform3D object (see Section 8.1.29, “Transform3D Object”)—that can posi-
tion, orient, and scale all of its children.
The specified transformation must be affine. Further, if the TransformGroup node
is used as an ancestor of a ViewPlatform node in the scene graph, then the trans-
formation must be congruent—only rotations, translations, and uniform scales

Version 1.2, March 2000 45

5.3 TransformGroup Node GROUP NODE OBJECTS

are allowed in a direct path from a Locale to a ViewPlatform node. A BadTrans-

formException (see Section D.1, “BadTransformException”) is thrown if an
attempt is made to specify an illegal transform.

Note: Even though arbitrary affine transformations are allowed, better perfor-
mance will result if all matrices within a branch graph are congruent—containing
only rotations, translation, and uniform scale.

The effects of transformations in the scene graph are cumulative. The concatena-
tion of the transformations of each TransformGroup in a direct path from the
Locale to a Leaf node defines a composite model transformation (CMT) that
takes points in that Leaf node’s local coordinates and transforms them into Vir-
tual World (Vworld) coordinates. This composite transformation is used to trans-
form points, normals, and distances into Vworld coordinates. Points are
transformed by the CMT. Normals are transformed by the inverse-transpose of
the CMT. Distances are transformed by the scale of the CMT. In the case of a
transformation containing a nonuniform scale or shear, the maximum scale value
in any direction is used. This ensures, for example, that a transformed bounding
sphere, which is specified as a point and a radius, continues to enclose all objects
that are also transformed using a nonuniform scale.

Constants
The TransformGroup class adds the following new flags.

public static final int ALLOW_TRANSFORM_READ

public static final int ALLOW_TRANSFORM_WRITE

These flags, when enabled using the setCapability method, allow this node’s
Transform3D to be read or written. They are only used when the node is part of
a live or compiled scene graph.

Constructors

public TransformGroup()
public TransformGroup(Transform3D t1)

These construct and initialize a new TransformGroup. The first form initializes
the node’s Transform3D to the identity transformation; the second form initial-
izes the node’s Transform3D to a copy of the specified transform.

46 The Java 3D API Specification

GROUP NODE OBJECTS DecalGroup Node 5.5

Methods
The TransformGroup class defines the following methods.

public void setTransform(Transform3D t1)

public void getTransform(Transform3D t1)

These methods retrieve or set this node’s attached Transform3D object by copy-
ing the transform to or from the specified object.

public Node cloneNode(boolean forceDuplicate)

public void duplicateNode(Node originalNode,
boolean forceDuplicate)

The first method creates a new instance of the node. This method is called by
cloneTree to duplicate the current node. The second method copies all the node
information from the originalNode into the current node. This method is called
from the cloneNode method, which is in turn called by the cloneTree method.
For each NodeComponent object contained by the object being duplicated, the
NodeComponent’s duplicateOnCloneTree flag is used to determine whether the
NodeComponent should be duplicated in the new node or a reference to the cur-
rent node should be placed in the new node. This flag can be overridden by set-
ting the forceDuplicate parameter in the cloneTree method to true.

5.4 OrderedGroup Node

The OrderedGroup node guarantees that Java 3D will render its children in their
index order. Only the OrderedGroup node and its subclasses make any use of the
order of their children during rendering.

Constructors

public OrderedGroup()

Constructs and initializes a new OrderedGroup node object.

5.5 DecalGroup Node

The DecalGroup node is a subclass of the OrderedGroup node. The DecalGroup
node is an ordered group node used for defining decal geometry on top of other
geometry. The DecalGroup node specifies that its children should be rendered in

Version 1.2, March 2000 47

5.6 Switch Node GROUP NODE OBJECTS

index order and that they generate coplanar objects. Examples of this include
painted decals or text on surfaces and a checkerboard layered on top of a table.
The first child, at index 0, defines the surface on top of which all other children
are rendered. The geometry of this child must encompass all other children; oth-
erwise, incorrect rendering may result. The polygons contained within each of
the children must be facing the same way. If the polygons defined by the first
child are front facing, then all other surfaces should be front facing. In this case,
the polygons are rendered in order. The renderer can use knowledge of the copla-
nar nature of the surfaces to avoid Z-buffer collisions (for example, if the under-
lying implementation supports stenciling or polygon offset, then these techniques
may be employed). If the main surface is back facing, then all other surfaces
should be back facing and need not be rendered (even if back-face culling is dis-
abled).
Note that using the DecalGroup node does not guarantee that Z-buffer collisions
are avoided. An implementation of Java 3D may fall back to treating DecalGroup
node as an ordinary OrderedGroup node.

Constructors

public DecalGroup()

Constructs and initializes a new DecalGroup node object.

5.6 Switch Node

The Switch group node allows a Java 3D application to choose dynamically
among a number of subgraphs. The Switch node contains an ordered list of chil-
dren and a switch value. The switch value determines which child or children
Java 3D will render. Note that the index order of children is only used for select-
ing the appropriate child or children—it does not specify rendering order.

Constants

public static final int ALLOW_SWITCH_READ

public static final int ALLOW_SWITCH_WRITE

These flags, when enabled using the setCapability method, allow reading and
writing of the values that specify the child-selection criteria. They are only used
when the node is part of a live or compiled scene graph.

48 The Java 3D API Specification

GROUP NODE OBJECTS Switch Node 5.6

public static final int CHILD_NONE

public static final int CHILD_ALL
public static final int CHILD_MASK

These values, when used in place of a non-negative integer index value, indicate
which children of the Switch node are selected for rendering. A value of
CHILD_NONE indicates that no children are rendered. A value of CHILD_ALL indi-
cates that all children are rendered, effectively making this Switch node operate
as an ordinary Group node. A value of CHILD_MASK indicates that the childMask
BitSet is used to select the children that are rendered.

Constructors

public Switch()

Constructs a Switch node with default parameters:

Parameters Default Values
child selection index CHILD_NONE
child selection mask false (for all children)

public Switch(int whichChild)

public Switch(int whichChild, BitSet childMask)

These constructors initialize a new Switch node using the specified parameters.

Methods
The Switch node class defines the following methods.

public void setWhichChild(int whichChild)

public int getWhichChild()

These methods access or modify the index of the child that the Switch object will
draw. The value may be a non-negative integer, indicating a specific child, or it
may be one of the following constants: CHILD_NONE, CHILD_ALL, or CHILD_MASK.
If the specified value is out of range, then no children are drawn.

public void setChildMask(BitSet childMask)

public BitSet getChildMask()

These methods access or modify the mask used to select the children that the
Switch object will draw when the whichChild parameter is CHILD_MASK. This
parameter is ignored during rendering if the whichChild parameter is a value
other than CHILD_MASK.

Version 1.2, March 2000 49

5.7 SharedGroup Node GROUP NODE OBJECTS

public Node currentChild()

This method returns the currently selected child. If whichChild is out of range,
or is set to CHILD_MASK, CHILD_ALL, or CHILD_NONE, then null is returned.

5.7 SharedGroup Node

A SharedGroup node provides a mechanism for sharing the same subgraph in
different parts of the tree via a Link node. See Section 7.1.1, “SharedGroup
Node,” for a description of this node.

50 The Java 3D API Specification

 C H A P T E R 6
Leaf Node Objects

L EAF nodes define atomic entities such as geometry, lights, and sounds. The
leaf nodes and their associated meanings follow.

6.1 Leaf Node

The Leaf node is an abstract class for all scene graph nodes that have no chil-
dren. Leaf nodes specify lights, geometry, and sounds; provide special linking
and instancing capabilities for sharing scene graphs; and provide a view platform
for positioning and orienting a view in the virtual world. Figure 6-1 shows the
Leaf node object hierarchy.

Constructors

public Leaf()

Constructs and initializes a new Leaf object.

6.2 Shape3D Node

The Shape3D leaf node object specifies all geometric objects. It contains a list of
one or more Geometry component objects and a single Appearance component
object. The Geometry objects define the shape node’s geometric data. The
Appearance object specifies that object’s appearance attributes, including color,
material, texture, and so on. See Chapter 8, “Node Component Objects” for
details of the Geometry and Appearance objects.

Version 1.2, March 2000 51

6.2 Shape3D Node LEAF NODE OBJECTS

SceneGraphObject
Node
Leaf
AlternateAppearance
Background
Behavior
Predefined behaviors
BoundingLeaf
Clip
Fog
ExponentialFog
LinearFog
Light
AmbientLight
DirectionalLight
PointLight
SpotLight
Link
Morph
Shape3D
OrientedShape3D
Sound
BackgroundSound
PointSound
ConeSound
Soundscape
ViewPlatform
Figure 6-1 Leaf Node Hierarchy

The list of geometry objects must all be of the same equivalence class. That is,
the same basic type of primitive. For subclasses of GeometryArray, all point
objects are equivalent, all line objects are equivalent, and all polygon objects are
equivalent. For other subclasses of Geometry, only objects of the same subclass
are equivalent. The equivalence classes are as follows:
• GeometryArray (point): [Indexed]PointArray
• GeometryArray (line): [Indexed]{LineArray, LineStripArray}
• GeometryArray (polygon): [Indexed]{TriangleArray, TriangleStripArray,
TriangleFanArray, QuadArray}
• CompressedGeometry
• Raster
• Text3D

52 The Java 3D API Specification

LEAF NODE OBJECTS Shape3D Node 6.2

Constants
The Shape3D node object defines the following flags.

public static final int ALLOW_GEOMETRY_READ

public static final int ALLOW_GEOMETRY_WRITE
public static final int ALLOW_APPEARANCE_READ
public static final int ALLOW_APPEARANCE_WRITE
public static final int ALLOW_COLLISION_BOUNDS_WRITE
public static final int ALLOW_COLLISION_BOUNDS_READ
public static final int ALLOW_APPEARANCE_OVERRIDE_WRITE New in 1.2
public static final int ALLOW_APPEARANCE_OVERRIDE_READ New in 1.2

These flags, when enabled using the setCapability method, allow reading and
writing of the Geometry and Appearance component objects, the collision
bounds, and the appearance override enable respectively. These capability flags
are enforced only when the node is part of a live or compiled scene graph.

Constructors
The Shape3D node object defines the following constructors.
public Shape3D()

Constructs a Shape3D node with default parameters:

Parameter Default Value
appearance null (default values are used for all appearance attributes)
geometry { null }
collision bounds null
appearance override enable false

The list of geometry components is initialized with a null geometry component

as the single element with an index of 0. A null geometry component specifies
that no geometry is drawn. A null appearance component specifies that default
values are used for all appearance attributes.

public Shape3D(Geometry geometry, Appearance appearance)

public Shape3D(Geometry geometry)

The first form constructs and initializes a new Shape3D object with the specified
geometry and appearance components. The second form uses the specified
geometry and a null appearance component. The list of geometry components is
initialized with the specified geometry component as the single element with an
index of 0. If the geometry component is null, no geometry is drawn. A null

Version 1.2, March 2000 53

6.2 Shape3D Node LEAF NODE OBJECTS

appearance component specifies that default values are used for all appearance
attributes.

Methods
The Shape3D node object defines the following methods.

public void setGeometry(Geometry geometry)

public void setGeometry(Geometry geometry, int index) New in 1.2
public Geometry getGeometry()
public Geometry getGeometry(int index) New in 1.2

These methods access or modify the Geometry component object associated with
this Shape3D node. The first setGeometry method replaces the geometry com-
ponent at index 0 in this Shape3D node’s list of geometry components with the
specified geometry component. The second setGeometry method replaces the
geometry component at the specified index in this Shape3D node’s list of geom-
etry components with the specified geometry component. If there are existing
geometry components in the list (besides the one being replaced), the new geom-
etry component must be of the same equivalence class (point, line, polygon,
CompressedGeometry, Raster, Text3D) as the others. The first getGeometry
method retrieves the geometry component at index 0 from this Shape3D node’s
list of geometry components. The second getGeometry method retrieves the
geometry component at the specified index from this Shape3D node’s list of
geometry components.

public void insertGeometry(Geometry geometry, int index) New in 1.2

public void removeGeometry(int index) New in 1.2

These methods insert and remove the specified geometry component into or from
this Shape3D node’s list of geometry components. The insertGeometry method
inserts the specified geometry component into this Shape3D node’s list of geom-
etry components at the specified index. If there are existing geometry compo-
nents in the list, the new geometry component must be of the same equivalence
class (point, line, polygon, CompressedGeometry, Raster, Text3D) as the others.
The removeGeometry method removes the geometry component at the specified
index from this Shape3D node’s list of geometry components.

public void addGeometry(Geometry geometry) New in 1.2

This method appends the specified geometry component to this Shape3D node’s
list of geometry components. If there are existing geometry components in the
list, the new geometry component must be of the same equivalence class (point,
line, polygon, CompressedGeometry, Raster, Text3D) as the others.

54 The Java 3D API Specification

LEAF NODE OBJECTS OrientedShape3D Node 6.2.1

public Enumeration getAllGeometries() New in 1.2

This method returns an enumeration of this Shape3D node’s list of geometry

components.

public int numGeometries() New in 1.2

This method appends the specified geometry component to this Shape3D node’s
list of geometry components. If there are existing geometry components in the
list, the new geometry component must be of the same equivalence class (point,
line, polygon, CompressedGeometry, Raster, Text3D) as the others.

public void setAppearance(Appearance appearance)

public Appearance getAppearance()

These methods access or modify the Appearance component object associated

with this Shape3D node. Setting it to null results in default attribute use.

public void setCollisionBounds(Bounds bounds)

public Bounds getCollisionBounds()

These methods set and retrieve the collision bounds for this node.

public boolean intersect(SceneGraphPath path, PickShape pickShape)

public boolean intersect(SceneGraphPath path, PickRay pickRay,
double[] dist)

These two methods check if the geometry component of this shape node under
path intersects with the pickShape.

public void setAppearanceOverrideEnable(boolean flag) New in 1.2

public boolean getAppearanceOverrideEnable() New in 1.2

These methods set and retrieve the flag that indicates whether this node’s appear-
ance can be overridden. If the flag is true, this node’s appearance may be overrid-
den by an AlternateAppearance leaf node, regardless of the value of the ALLOW_
APPEARANCE_WRITE capability bit. The default value is false. See Section 6.15,
“AlternateAppearance Node.”

6.2.1 OrientedShape3D Node New in 1.2

The OrientedShape3D leaf node is a Shape3D node that is oriented along a spec-
ified axis or about a specified point. It defines an alignment mode and a rotation
point or axis. This will cause the local +z axis of the object to point at the
viewer’s eye position. This is done regardless of the transforms above this
OrientedShape3D node in the scene graph.

Version 1.2, March 2000 55

6.2.1 OrientedShape3D Node LEAF NODE OBJECTS

The OrientedShape3D node is similar in functionality to the Billboard behavior

(see Section 10.8, “Billboard Behavior”), but OrientedShape3D nodes will orient
themselves correctly for each view, and they can be used within a SharedGroup.
If the alignment mode is ROTATE_AXIS, the rotation will be around the specified
axis. If the alignment mode is ROTATE_ABOUT_POINT, the rotation will be about
the specified point, with an additional rotation to align the +y axis of the Trans-
formGroup with the +y axis in the View.
OrientedShape3D nodes are ideal for drawing screen-aligned text or for drawing
roughly-symmetrical objects. A typical use might consist of a quadrilateral that
contains a texture of a tree.

Constants
The OrientedShape3D node object defines the following flags:

public static final int ALLOW_MODE_READ New in 1.2

public static final int ALLOW_MODE_WRITE New in 1.2
public static final int ALLOW_AXIS_READ New in 1.2
public static final int ALLOW_AXIS_WRITE New in 1.2
public static final int ALLOW_POINT_READ New in 1.2
public static final int ALLOW_POINT_WRITE New in 1.2

These flags, when enabled using the setCapability method, allow reading and
writing of the alignment mode, alignment axis, and rotation point information,
respectively. These capability flags are enforced only when the node is part of a
live or compiled scene graph.

public static final int ROTATE_ABOUT_AXIS New in 1.2

Specifies that rotation should be about the specified axis.

public static final int ROTATE_ABOUT_POINT New in 1.2

Specifies that rotation should be about the specified point and that the children’s
Y-axis should match the view object’s Y-axis.

Constructors
The OrientedShape3D node specifies the following constructors.

56 The Java 3D API Specification

LEAF NODE OBJECTS OrientedShape3D Node 6.2.1

public OrientedShape3D() New in 1.2

Constructs an OrientedShape3D node with default parameters. The default val-

ues are as follows:
Parameter Default Value
alignment mode ROTATE_ABOUT_AXIS
alignment axis Y-axis (0,1,0)
rotation point (0,0,1)

public OrientedShape3D(Geometry geometry, Appearance appearance,

int mode, Vector3f axis) New in 1.2
public OrientedShape3D(Geometry geometry, Appearance appearance,
int mode, Point3f point) New in 1.2

The first constructor constructs an OrientedShape3D node with the specified

geometry component, appearance component, mode, and axis. The second con-
structor constructs an OrientedShape3D node with the specified geometry com-
ponent, appearance component, mode, and rotation point.

Methods

public void setAlignmentMode(int mode) New in 1.2

public int getAlignmentMode() New in 1.2

These methods set and retrieve the alignment mode. The alignment mode is one
of ROTATE_ABOUT_AXIS or ROTATE_ABOUT_POINT.

public void setAlignmentAxis(Vector3f axis) New in 1.2

public void setAlignmentAxis(float x, float y, float z) New in 1.2
public void getAlignmentAxis(Vector3f axis) New in 1.2

These methods set and retrieve thte alignment axis. This is the ray about which
this OrientedShape3D rotates when the mode is ROTATE_ABOUT_AXIS.

public void setRotationPoint(Point3f point) New in 1.2

public void setRotationPoint(float x, float y, float z) New in 1.2
public void getRotationPoint(Point3f point) New in 1.2

These methods set and retrieve the rotation point. This is the point about which
the OrientedShape3D rotates when the mode is ROTATE_ABOUT_POINT.

Version 1.2, March 2000 57

6.3 BoundingLeaf Node LEAF NODE OBJECTS

6.3 BoundingLeaf Node

The BoundingLeaf node defines a bounding region object that can be referenced
by other leaf nodes to define a region of influence (Fog and Light nodes), an acti-
vation region (Background, Clip, and Soundscape nodes), or a scheduling region
(Sound and Behavior nodes). The bounding region is defined in the local coordi-
nate system of the BoundingLeaf node. A reference to a BoundingLeaf node can
be used in place of a locally defined bounds object for any of the aforementioned
regions.
This allows an application to specify a bounding region in one coordinate system
(the local coordinate system of the BoundingLeaf node) other than the local
coordinate system of the node that references the bounds. For an example of how
this might be used, consider a closed room with a number of track lights. Each
light can move independent of the other lights and, as such, needs its own local
coordinate system. However, the bounding volume is used by all the lights in the
boundary of the room, which doesn’t move when the lights move. In this exam-
ple, the BoundingLeaf node allows the bounding region to be defined in the local
coordinate system of the room, rather than in the local coordinate system of a
particular light. All lights can then share this single bounding volume.

Constants
The BoundingLeaf node object defines the following flags.

public static final int ALLOW_REGION_READ

public static final int ALLOW_REGION_WRITE

These flags, when enabled using the setCapability method, allow an applica-
tion to invoke methods that respectively read and write the bounding region
object.

Constructors
The BoundingLeaf node object defines the following constructors.

public BoundingLeaf()

Constructs a BoundingLeaf node with a null (empty) bounding region.

public BoundingLeaf(Bounds region)

Constructs a BoundingLeaf node with the specified bounding region.

58 The Java 3D API Specification

LEAF NODE OBJECTS Background Node 6.4

Methods

public void setRegion(Bounds region)

public Bounds getRegion()

These methods set and retrieve the BoundingLeaf node’s bounding region.

6.4 Background Node

The Background leaf node defines either a solid background color or a back-
ground image that is used to fill the window at the beginning of each new frame.
It also specifies an application region in which this Background node is active. A
Background node is active when its application region intersects the ViewPlat-
form’s activation volume. If multiple Background nodes are active, the Back-
ground node that is “closest” to the eye will be used. If no Background nodes are
active, then the window is cleared to black.

Constants
The Background node object defines the following flags.

public static final int ALLOW_APPLICATION_BOUNDS_READ

public static final int ALLOW_APPLICATION_BOUNDS_WRITE
public static final int ALLOW_IMAGE_READ
public static final int ALLOW_IMAGE_WRITE
public static final int ALLOW_COLOR_READ
public static final int ALLOW_COLOR_WRITE
public static final int ALLOW_GEOMETRY_READ
public static final int ALLOW_GEOMETRY_WRITE

These flags, when enabled using the setCapability method, allow an applica-
tion to invoke methods that respectively read and write the application region, the
image, the color, and the background geometry. These capability flags are
enforced only when the node is part of a live or compiled scene graph.

Constructors
The Background node object defines the following constructors.

public Background()

Constructs a Background leaf node with default parameters:

Version 1.2, March 2000 59

6.4 Background Node LEAF NODE OBJECTS

Parameter Default Value

color black (0,0,0)
image null
geometry null
application bounds null
application boundingLeaf null

public Background(Color3f color)

public Background(float r, float g, float b)
public Background(ImageComponent2D image)
public Background(Branchgroup branch)

The first two forms construct a Background leaf node with the specified color.
The second form constructs a Background leaf node with the specified 2D image.
The final form constructs a Background leaf node with the specified geometry.

Methods
The Background node object defines the following methods.

public void getColor(Color3f color)

public void setColor(Color3f color)
public void setColor(float r, float g, float b)

These three methods access or modify the background color.

public ImageComponent2D getImage()

public void setImage(ImageComponent2D image)

These two methods access or modify the background image. If the image is not
null then it is used in place of the color.

public void setGeometry(BranchGroup branch)

public BranchGroup getGeometry()

These two methods access or modify the Background geometry. The setGeome-
try method sets the background geometry to the specified BranchGroup node. If
non-null, this background geometry is drawn on top of the background color or
image using a projection matrix that essentially puts the geometry at infinity. The
geometry should be pretessellated onto a unit sphere.

60 The Java 3D API Specification

LEAF NODE OBJECTS Clip Node 6.5

public void setApplicationBounds(Bounds region)

public Bounds getApplicationBounds()

These two methods access or modify the Background node’s application bounds.
This bounds is used as the application region when the application bounding leaf
is set to null. The getApplicationBounds method returns a copy of the associ-
ated bounds.

public void setApplicationBoundingLeaf(BoundingLeaf region)

public BoundingLeaf getApplicationBoundingLeaf()

These two methods access or modify the Background node’s application bound-
ing leaf. When set to a value other than null, this bounding leaf overrides the
application bounds object and is used as the application region.

6.5 Clip Node

The Clip leaf node defines the far clipping plane used to clip objects in the vir-
tual universe. It also specifies an application region in which this Clip node is
active. A Clip node is active when its application region intersects the ViewPlat-
form’s activation volume. If multiple Clip nodes are active, the Clip node that is
“closest” to the eye will be used. The back distance value specified by this Clip
node overrides the value specified in the View object. If no Clip nodes are active,
then the back clip distance is used from the View object.

Constants

public static final int ALLOW_APPLICATION_BOUNDS_READ

public static final int ALLOW_APPLICATION_BOUNDS_WRITE
public static final int ALLOW_BACK_DISTANCE_READ
public static final int ALLOW_BACK_DISTANCE_WRITE

These flags, when enabled using the setCapability method, allow an applica-
tion to invoke methods that respectively read and write the application region and
the back distance. These capability flags are enforced only when the node is part
of a live or compiled scene graph.

Constructors
The Clip node object defines the following constructors.

Version 1.2, March 2000 61

6.5 Clip Node LEAF NODE OBJECTS

public Clip()

Constructs a Clip node with default parameters:

Parameter Default Value
backDistance 100
scheduling bounds null
scheduling boundingLeaf null

public Clip(double backDistance)

Constructs a Clip leaf node with the rear clip plane at the specified distance, in
the local coordinate system, from the eye.

Methods
The Clip node object defines the following methods.

public void setBackDistance(double backDistance)

public double getBackDistance()

These methods access or modify the back clipping distances in the Clip node.
This distance specifies the back clipping plane in the local coordinate system of
the node. There are several considerations that need to be taken into account
when choosing values for the front and back clip distances. See Section 9.7.3,
“Projection and Clip Parameters,” for details.

public void setApplicationBounds(Bounds region)

public Bounds getApplicationBounds()

These two methods access or modify the Clip node’s application bounds. This
bounds is used as the application region when the application bounding leaf is
set to null. The getApplicationBounds method returns a copy of the associated
bounds.

public void setApplicationBoundingLeaf(BoundingLeaf region)

public BoundingLeaf getApplicationBoundingLeaf()

These two methods access or modify the Clip node’s application bounding leaf.
When set to a value other than null, this bounding leaf overrides the application
bounds object and is used as the application region.

62 The Java 3D API Specification

LEAF NODE OBJECTS ModelClip Node 6.6

6.6 ModelClip Node

The ModelClip leaf node defines a set of six arbitrary clipping planes in the vir-
tual universe. The planes are specified in the local coordinate system of this
node, and may be individually enabled or disabled. This node also specifies an
region of influence in which this set of planes is active.
A ModelClip node also contains a list of Group nodes that specifies the hierar-
chical scope of this ModelClip. If the scope list is empty, the ModelClip node
has universe scope; all nodes within the region of influence are affected by this
ModelClip node. If the scope list is non-empty, then only those Leaf nodes under
the Group nodes in the scope list are affected by this ModelClip node (subject to
the influencing bounds).
If the regions of influence of multiple ModelClip nodes overlap, the Java 3D sys-
tem will choose a single set of model clip planes for those objects that lie in the
intersection. This is done in an implementation-dependent manner, but in gen-
eral, the ModelClip node that is “closest” to the object is chosen.
The individual planes specify a half-space defined by the following equation:

Ax + By + Cz + D ≤ 0
where A, B, C, and D are the parameters that specify the plane.
The parameters are passed in the x, y, z, and w fields, respectively, of a Vector4d
object. The intersection of the set of half-spaces corresponding to the enabled
planes in this ModelClip node defines a region in which points are accepted.
Points in this acceptance region will be rendered (subject to view clipping and
other attributes). Points that are not in the acceptance region will not be rendered.

Constants
The ModelClip node object defines the following flags.

public static final int ALLOW_INFLUENCING_BOUNDS_READ New in 1.2

public static final int ALLOW_INFLUENCING_BOUNDS_WRITE New in 1.2
public static final int ALLOW_PLANE_READ New in 1.2
public static final int ALLOW_PLANE_WRITE New in 1.2
public static final int ALLOW_ENABLE_READ New in 1.2
public static final int ALLOW_ENABLE_WRITE New in 1.2
public static final int ALLOW_SCOPE_READ New in 1.2
public static final int ALLOW_SCOPE_WRITE New in 1.2

These flags, when enabled using the setCapability method, allow an applica-
tion to invoke methods that respectively read and write the influencing bounds
Version 1.2, March 2000 63
6.6 ModelClip Node LEAF NODE OBJECTS

and bounding leaf, planes, enable, and scope flags. These capability flags are
enforced only when the node is part of a live or compiled scene graph.

Constructors
The ModelClip node object defines the following constructors.

public ModelClip() New in 1.2

Constructs a ModelClip node with default parameters:

Parameter Default Value
planes[0] x ≤ 1 (1,0,0,–1)
planes[1] –x ≤ 1 (–1,0,0,–1)
planes[2] y ≤ 1 (0,1,0,–1)
planes[3] –y ≤ 1 (0–1,0–1)
planes[4] z ≤ 1 (0,0,1,–1)
planes[5] –z ≤ 1 (0,0,–1,–1)
enables all planes enabled
scope empty (universe scope)
influencing bounds null
influencing bounding leaf null

public ModelClip(Vector4d[] planes, boolean[] enables) New in 1.2

public ModelClip(Vector4d[] planes) New in 1.2

These constructors each construct a new ModelClip node. The first constructor
uses the specified planes and enable flags. The second constructor uses the spec-
ified parameters and uses defaults for those parameters not specified. Default val-
ues are described above.

Methods
The ModelClip node object defines the following methods.

public void setInfluencingBounds(Bounds region) New in 1.2

public Bounds getInfluencingBounds() New in 1.2

These methods access or modify the ModelClip node’s influencing region. This
is used when the influencing bounding leaf is set to null.

64 The Java 3D API Specification

LEAF NODE OBJECTS ModelClip Node 6.6

public void setInfluencingBoundingLeaf(BoundingLeaf region) New in 1.2

public BoundingLeaf getInfluencingBoundingLeaf() New in 1.2

These methods access or modify the ModelClip node’s influencing region. When
set to a value other than null, this overrides the influencing bounds object.

public void setPlanes(Vector4d[] planes) New in 1.2

public void setPlane(int planeNum, Vector4d plane) New in 1.2
public void getPlanes(Vector4d[] planes) New in 1.2
public void getPlane(int planeNum, Vector4d plane) New in 1.2

These methods access or modify the specified ModelClip node’s clipping planes.
The planes are an array of six model clipping planes. The set methods copy the
individual planes into this node. The get methods copy the individual planes into
the specified planes, which must be allocated by the caller.

public void setEnables(boolean[] enables) New in 1.2

public void setEnable(int planeNum, boolean enable) New in 1.2
public void getEnables(boolean[] enables) New in 1.2
public boolean getEnable(int planeNum) New in 1.2

These methods access or modify the specified ModelClip node’s enable flag. The
enables are an array of six booleans.

public void setScope(Group scope, int index) New in 1.2

This method replaces the node at the specified index in this ModelClip node’s
list of scopes with the specified Group node. By default, ModelClip nodes are
scoped only by their influencing bounds. This allows them to be further scoped
by a list of nodes in the hierarchy.

public Group getScope(int index) New in 1.2

This method retrieves the Group node at the specified index from this ModelClip
node’s list of scopes.

public void insertScope(Group scope, int index) New in 1.2

This method inserts the specified Group node into this ModelClip node’s list of
scopes at the specified index. By default, ModelClip nodes are scoped only by
their influencing bounds. This allows them to be further scoped by a list of nodes
in the hierarchy.

public void removeScope(int index) New in 1.2

This method removes the node at the specified index from this ModelClip node’s
list of scopes. If this operation causes the list of scopes to become empty, this
Version 1.2, March 2000 65
6.7 Fog Node LEAF NODE OBJECTS

ModelClip will have universe scope; all nodes within the region of influence will
be affected by this ModelClip node.

public Enumeration getAllScopes() New in 1.2

This method returns an enumeration of this ModelClip node’s list of scopes.

public void addScope(Group scope) New in 1.2

This method appends the specified Group node to this ModelClip node’s list of
scopes. By default, ModelClip nodes are scoped only by their influencing
bounds. This allows them to be further scoped by a list of nodes in the hierarchy.

public int numScopes() New in 1.2

This method returns the number of nodes in this ModelClip node’s list of scopes.
If this number is 0, the list of scopes is empty and this ModelClip node has uni-
verse scope: all nodes within the region of influence are affected by this Model-
Clip node.

6.7 Fog Node

The Fog leaf node is an abstract class that defines a common set of attributes that
control fog, or depth cueing, in the scene. The Fog node includes a parameter
that specifies the fog color and a Bounds object that specifies the region of influ-
ence for the Fog node.
Objects whose bounding volumes intersect the Fog node’s region of influence
have fog applied to their color after lighting and texturing have been applied. The
Fog node also contains a list of Group nodes that indicates the hierarchical scope
of this fog. If the list of scoping nodes is empty, the fog has universe scope and
will apply to all nodes in the virtual universe that are within the Fog node’s
region of influence.
If the regions of influence of multiple Fog nodes overlap, the Java 3D system
will choose a single set of fog parameters for those objects that lie in the inter-
section. This is done in an implementation-dependent manner, but in general, the
Fog node that is “closest” to the object is chosen.

Constants
The Fog node object defines the following flags.

66 The Java 3D API Specification

LEAF NODE OBJECTS Fog Node 6.7

public static final int ALLOW_INFLUENCING_BOUNDS_READ

public static final int ALLOW_INFLUENCING_BOUNDS_WRITE
public static final int ALLOW_COLOR_READ
public static final int ALLOW_COLOR_WRITE
public static final int ALLOW_SCOPE_READ
public static final int ALLOW_SCOPE_WRITE

These flags, when enabled using the setCapability method, allow an applica-
tion to invoke methods that respectively read and write the region of influence,
read and write color, and read and write scope information. These capability
flags are enforced only when the node is part of a live or compiled scene graph.

Constructors
The Fog node object defines the following constructors.

public Fog()

Constructs a Fog node with default parameters:

Parameter Default Value
color black (0,0,0)
scope empty (universe scope)
influencing bounds null
influencing boundingLeaf null

public Fog(float r, float g, float b)

public Fog(Color3f color)

These constructors each construct a new Fog node. The first constructor uses
default values for all parameters. The second constructor uses the specified
parameters and uses defaults for those parameters not specified. Default values
are described above.

Methods
The Fog node object defines the following methods.

public void setColor(float r, float g, float b)

public void setColor(Color3f color)
public void getColor(Color3f color)

These three methods access or modify the Fog node’s color. An application will
typically set this to the same value as the background color.

Version 1.2, March 2000 67

6.7.1 ExponentialFog Node LEAF NODE OBJECTS

public void setInfluencingBounds(Bounds region)

public Bounds getInfluencingBounds()

These methods access or modify the Fog node’s influencing bounds. This bounds
is used as the region of influence when the influencing bounding leaf is set to
null. The Fog node operates on all objects that intersect its region of influence.
The getInfluencingBounds method returns a copy of the associated bounds.

public void setInfluencingBoundingLeaf(BoundingLeaf region)

public BoundingLeaf getInfluencingBoundingLeaf()

These methods access or modify the Fog node’s influencing bounding leaf.
When set to a value other than null, this overrides the influencing bounds object
and is used as the region of influence.

public void setScope(Group scope, int index)

public Group getScope(int index)
public void addScope(Group scope)
public void insertScope(Group scope, int index)
public void removeScope(int index)
public int numScopes()
public Enumeration getAllScopes()

These methods access or modify the Fog node’s hierarchical scope. By default,
Fog nodes are scoped only by their regions of influence. These methods allow
them to be further scoped by a Group node in the hierarchy. The hierarchical
scoping of a Fog node cannot be accessed or modified if the node is part of a live
or compiled scene graph.

6.7.1 ExponentialFog Node

The ExponentialFog leaf node extends the Fog leaf node by adding a fog density
that is used as the exponent of the fog equation. For more information on the fog
equation, see Appendix E, “Equations.”
The density is defined in the local coordinate system of the node, but the actual
fog equation will ideally take place in eye coordinates.

Constants
The ExponentialFog node object defines the following flags.

68 The Java 3D API Specification

LEAF NODE OBJECTS LinearFog Node 6.7.2

public static final int ALLOW_DENSITY_READ

public static final int ALLOW_DENSITY_WRITE

These flags, when enabled using the setCapability method, allow an applica-
tion to invoke methods that respectively read and write the density values. These
capability flags are enforced only when the node is part of a live or compiled
scene graph.

Constructors
The ExponentialFog node object defines the following constructors.

public ExponentialFog()

Constructs an ExponentialFog node with default parameters:

Parameter Default Value
density 1.0

public ExponentialFog(float r, float g, float b)

public ExponentialFog(Color3f color)
public ExponentialFog(float r, float g, float b, float density)
public ExponentialFog(Color3f color, float density)

Each of these constructors creates a new ExponentialFog node using the speci-
fied parameters and use defaults for those parameters not specified.

Methods
The ExponentialFog node object defines the following methods.

public void setDensity(float density)

public float getDensity()

These two methods access or modify the density in the ExponentialFog object.

6.7.2 LinearFog Node

The LinearFog leaf node extends the Fog leaf node by adding a pair of distance
values, in Z, at which fog should start obscuring the scene and should maximally
obscure the scene.
The front and back fog distances are defined in the local coordinate system of the
node, but the actual fog equation will ideally take place in eye coordinates. For
more information on the fog equation, see Appendix E, “Equations.”

Version 1.2, March 2000 69

6.7.2 LinearFog Node LEAF NODE OBJECTS

Constants
The LinearFog node object defines the following flags.
public static final int ALLOW_DISTANCE_READ
public static final int ALLOW_DISTANCE_WRITE

These flags, when enabled using the setCapability method, allow an applica-
tion to invoke methods that respectively read and write the distance values. These
capability flags are enforced only when the node is part of a live or compiled
scene graph.

Constructors
The LinearFog node object defines the following constructors.

public LinearFog()

Constructs a LinearFog node with default parameters:

Parameter Default Value
frontDistance 0.1
backDistance 1.0

public LinearFog(float r, float g, float b)

public LinearFog(Color3f color)
public LinearFog(float r, float g, float b, double frontDistance,
double backDistance)
public LinearFog(Color3f color, double frontDistance,
double backDistance)

These constructors each construct a new LinearFog node with the specified
parameters and use defaults for those parameters not specified.

Methods
The LinearFog node object defines the following methods.

public void setFrontDistance(float frontDistance)

public float getFrontDistance()
public void setBackDistance(float backDistance)
public float getBackDistance()

These four methods access or modify the front and back distances in the Linear-
Fog object. The front distance is the distance at which the fog starts obscuring
objects. The back distance is the distance at which the fog fully obscures objects.

70 The Java 3D API Specification

LEAF NODE OBJECTS Light Node 6.8

Objects drawn closer than the front fog distance are not affected by fog. Objects
drawn farther than the back fog distance are drawn entirely in the fog color.

6.8 Light Node

The Light leaf node is an abstract class that defines the properties common to all
Light nodes. A light has associated with it a color, a state (whether it is on or
off), and a Bounds object that specifies the region of influence for the light.
Objects whose bounding volumes intersect the Light node’s region of influence
are lit by this light. The Light node also contains a Group node that indicates the
hierarchical scope of this light. If no scoping node is specified, then the light has
universe scope and applies to all nodes in the virtual universe that are within the
light’s region of influence.
The Java 3D lighting model is based on a subset of the OpenGL lighting model.

Constants
The Light node object defines the following flags.

public static final int ALLOW_INFLUENCING_BOUNDS_READ

public static final int ALLOW_INFLUENCING_BOUNDS_WRITE
public static final int ALLOW_STATE_READ
public static final int ALLOW_STATE_WRITE
public static final int ALLOW_COLOR_READ
public static final int ALLOW_COLOR_WRITE
public static final int ALLOW_SCOPE_READ
public static final int ALLOW_SCOPE_WRITE

These flags, when enabled using the setCapability method, allow reading and
writing of the region of influence, the state, the color, and the scope information,
respectively. These capability flags are enforced only when the node is part of a
live or compiled scene graph.

Constructors
The Light node object defines the following constructors.

public Light()

Constructs and initializes a light with default values:

Version 1.2, March 2000 71

6.8 Light Node LEAF NODE OBJECTS

Parameter Default Value

enable flag true
color white (1,1,1)
scope empty (universe scope)
influencing bounds null
influencing boundingLeaf null

public Light(Color3f color)

public Light(boolean lightOn, Color3f color)

These two constructors construct and initialize a light with the specified values.

Methods
The Light node object defines the following methods.

public void setEnable(boolean state)

public boolean getEnable()

These methods access or modify the state of this light (that is, whether the light
is enabled).

public void setColor(Color3f color)

public void getColor(Color3f color)

These methods access or modify the current color of this light.

public setInfluencingBounds(Bounds region)

public Bounds getInfluencingBounds()

These methods access or modify the Light node’s influencing bounds. This
bounds is used as the region of influence when the influencing bounding leaf is
set to null. The Light node operates on all objects that intersect its region of
influence. The getInfluencingBounds method returns a copy of the associated
bounds.

public setInfluencingBoundingLeaf(BoundingLeaf region)

public BoundingLeaf getInfluencingBoundingLeaf()

These methods access or modify the Light node’s influencing bounding leaf.
When set to a value other than null, this overrides the influencing bounds object
and is used as the region of influence.

72 The Java 3D API Specification

LEAF NODE OBJECTS DirectionalLight Node 6.8.2

public void setScope(Group scope, int index)

public Group getScope(int index)
public void addScope(Group scope)
public void insertScope(Group scope, int index)
public void removeScope(int index)
public int numScopes()
public Enumeration getAllScopes()

These methods access or modify the Light node’s hierarchical scope. By default,
Light nodes are scoped only by their regions of influence bounds. These methods
allow them to be further scoped by a node in the hierarchy.

6.8.1 AmbientLight Node

An AmbientLight node defines an ambient light source. It has the same attributes
as the abstract Light node.

Constructors
The AmbientLight node defines the following constructors.

public AmbientLight()
public AmbientLight(Color3f color)
public AmbientLight(boolean lightOn, Color3f color)

The first constructor constructs and initializes a new AmbientLight node using
default parameters. The next two constructors construct and initialize a new
AmbientLight node using the specified parameters. The color parameter is the
color of the light source. The lightOn flag indicates whether this light is on or
off.

6.8.2 DirectionalLight Node

A DirectionalLight node defines an oriented light with an origin at infinity. It has
the same attributes as a Light node, with the addition of a direction vector to
specify the direction in which it shines.

Constants
The DirectionalLight node object defines the following flags.

Version 1.2, March 2000 73

6.8.3 PointLight Node LEAF NODE OBJECTS

public static final int ALLOW_DIRECTION_READ

public static final int ALLOW_DIRECTION_WRITE

These flags, when enabled using the setCapability method, allow an applica-
tion to invoke methods that respectively read or write the associated direction.
These capability flags are enforced only when the node is part of a live or com-
piled scene graph.
The DirectionalLight’s direction vector is defined in the local coordinate system
of the node.

Constructors
The DirectionalLight node object defines the following constructors.

public DirectionalLight()

Constructs and initializes a directional light with default parameters:

Parameter Default Value
direction (0,0,–1)

public DirectionalLight(Color3f color, Vector3f direction)

public DirectionalLight(boolean LightOn, Color3f color,
Vector3f direction)

These constructors construct and initialize a directional light with the parameters
provided.

Methods
The DirectionalLight node object defines the following methods.

public void setDirection(Vector3f direction)

public void setDirection(float x, float y, float z)
public void getDirection(Vector3f direction)

These methods access or modify the light’s current direction.

6.8.3 PointLight Node

A PointLight node defines a point light source located at some point in space and
radiating light in all directions (also known as a positional light). It has the same
attributes as a Light node, with the addition of location and attenuation parame-
ters.

74 The Java 3D API Specification

LEAF NODE OBJECTS PointLight Node 6.8.3

The PointLight’s position is defined in the local coordinate system of the node.

Constants
The PointLight node object defines the following flags.

public static final int ALLOW_POSITION_READ

public static final int ALLOW_POSITION_WRITE
public static final int ALLOW_ATTENUATION_READ
public static final int ALLOW_ATTENUATION_WRITE

These flags, when enabled using the setCapability method, allow an applica-
tion to invoke methods that respectively read position, write position, read atten-
uation parameters, and write attenuation parameters. These capability flags are
enforced only when the node is part of a live or compiled scene graph.

Constructors
The PointLight Node defines the following constructors.

public PointLight()

Constructs and initializes a point light source with default parameters:

Parameter Default Value
position (0,0,0)
attenuation (1,0,0)

public PointLight(Color3f color, Point3f position,

Point3f attenuation)
public PointLight(boolean lightOn, Color3f color,
Point3f position, Point3f attenuation)

These constructors construct and initialize a point light with the specified param-
eters.

Methods
The PointLight node object defines the following methods.

public void setPosition(Point3f position)

public void setPosition(float x, float y, float z)
public void getPosition(Point3f position)

These methods access or modify the point light’s current position.

Version 1.2, March 2000 75

6.8.4 SpotLight Node LEAF NODE OBJECTS

public void setAttenuation(Point3f attenuation)

public void setAttenuation(float constant, float linear,
float quadratic)
public void getAttenuation(Point3f attenuation)

These methods access or modify the point light’s current attenuation. The values
presented to the methods specify the coefficients of the attenuation polynomial,
with constant providing the constant term, linear providing the linear coeffi-
cient, and quadratic providing the quadratic coefficient.

6.8.4 SpotLight Node

A SpotLight node defines a point light source located at some point in space and
radiating in a specific direction. It has the same attributes as a PointLight node,
with the addition of a direction of radiation, a spread angle to specify its limits,
and a concentration factor that specifies how quickly the light intensity attenuates
as a function of the angle of radiation as measured from the direction of radia-
tion.

Constants
The SpotLight node object defines the following flags.

public static final int ALLOW_SPREAD_ANGLE_READ

public static final int ALLOW_SPREAD_ANGLE_WRITE
public static final int ALLOW_CONCENTRATION_READ
public static final int ALLOW_CONCENTRATION_WRITE
public static final int ALLOW_DIRECTION_READ
public static final int ALLOW_DIRECTION_WRITE

These flags, when enabled using the setCapability method, allow an applica-
tion to invoke methods that respectively read and write spread angle, concentra-
tion, and direction. These capability flags are enforced only when the node is
part of a live or compiled scene graph.
The SpotLight’s direction vector and spread angle are defined in the local coordi-
nate system of the node.

Constructors
The SpotLight node object defines the following constructors.

76 The Java 3D API Specification

LEAF NODE OBJECTS Sound Node 6.9

public SpotLight()

Constructs and initializes a new spotlight with the default values:

Parameter Default Value
direction (0,0 –1)
spreadangle π radians
concentration 0.0

public SpotLight(Color3f color, Point3f position,

Point3f attenuation, Vector3f direction, float spreadAngle,
float concentration)
public SpotLight(boolean lightOn, Color3f color, Point3f position,
Point3f attenuation, Vector3f direction, float spreadAngle,
float concentration)

These construct and initialize a new spotlight with the parameters specified.

Methods
The SpotLight node object defines the following methods.

public void setSpreadAngle(float spreadAngle)

public float getSpreadAngle()

These methods access or modify the spread angle, in radians, of this spotlight.

public void setConcentration(float concentration)

public float getConcentration()

These methods access or modify the concentration of this spotlight.

public void setDirection(float x, float y, float z)

public void setDirection(Vector3f direction)
public void getDirection(Vector3f direction)

These methods access or modify the direction of this spotlight.

6.9 Sound Node

The Sound leaf node is an abstract class that defines the properties common to all
Sound nodes. A scene graph can contain multiple sounds. Each Sound node con-
tains a reference to the sound data, an amplitude scale factor, a release flag
denoting that the sound associated with this node is to play to the end when the
sound is disabled, the number of times the sound is to be repeated, a state
(whether the sound is on or off), a scheduling region, a priority, and a flag denot-
Version 1.2, March 2000 77
6.9 Sound Node LEAF NODE OBJECTS

ing if the sound is to continue playing “silently” even while it is inactive. When-
ever the listener is within the Sound node’s scheduling bounds, the sound is
potentially audible.

Constants
The Sound object contains the following flags.

public static final int ALLOW_SOUND_DATA_READ

public static final int ALLOW_SOUND_DATA_WRITE
public static final int ALLOW_INITIAL_GAIN_READ
public static final int ALLOW_INITIAL_GAIN_WRITE
public static final int ALLOW_LOOP_READ
public static final int ALLOW_LOOP_WRITE
public static final int ALLOW_RELEASE_READ
public static final int ALLOW_RELEASE_WRITE
public static final int ALLOW_CONT_PLAY_READ
public static final int ALLOW_CONT_PLAY_WRITE
public static final int ALLOW_ENABLE_READ
public static final int ALLOW_ENABLE_WRITE
public static final int ALLOW_SCHEDULING_BOUNDS_READ
public static final int ALLOW_SCHEDULING_BOUNDS_WRITE
public static final int ALLOW_PRIORITY_READ
public static final int ALLOW_PRIORITY_WRITE
public static final int ALLOW_DURATION_READ
public static final int ALLOW_CHANNELS_USED_READ
public static final int ALLOW_IS_PLAYING_READ
public static final int ALLOW_IS_READY_READ

These flags, when enabled using the setCapability method, allow an applica-
tion to invoke methods that respectively read and write the sound data, the initial
gain information, the loop information, the release flag, the continuous play flag,
the sound on/off switch, the scheduling region, the prioritization value, the dura-
tion information, and the sound playing information. These capability flags are
enforced only when the node is part of a live or compiled scene graph.

public static final float NO_FILTER

This constant defines a floating point value that denotes that no filter value is set.
Filters are described in Section 6.9.3, “ConeSound Node.”

public static final int DURATION_UNKNOWN

This constant denotes that the sound’s duration could not be calculated. A fall-
back for getDuration of a non-cached sound.

78 The Java 3D API Specification

LEAF NODE OBJECTS Sound Node 6.9

Constructors
The Sound node object defines the following constructors.

public Sound()

Constructs and initializes a new Sound node object that includes the following
defaults for its fields:
Parameter Default Value
soundData null
initialGain 1.0
loop 0
release flag false
continuous flag false
on switch false
scheduling region null (cannot be scheduled)
priority 1.0

public Sound(MediaContainer soundData, float initialGain)

Constructs and initializes a new Sound node object using the provided data and
gain parameter values, and defaults for all other fields. This constructor implic-
itly loads the sound data associated with this node if the implementation uses
sound caching.

public Sound(MediaContainer soundData, float initialGain,

int loopCount, boolean release, boolean continuous,
boolean enable, Bounds region, float priority)

Constructs and initializes a new Sound node object using the provided parameter
values.

Methods
The Sound node object defines the following methods.

public void setSoundData(MediaContainer soundData)

public MediaContainer getSoundData()

These methods provide a way to associate different types of audio data with a
Sound node. This data can be cached (buffered) or noncached (unbuffered or
streaming). If the AudioDevice has been attached to the PhysicalEnvironment,
the sound data is made ready to begin playing. Certain functionality cannot be

Version 1.2, March 2000 79

6.9 Sound Node LEAF NODE OBJECTS

applied to true streaming sound data: sound duration is unknown, looping is dis-
abled, and the sound cannot be restarted. Furthermore, depending on the imple-
mentation of the AudioDevice used, streaming, non-cached data may not be fully
spatialized.

public void setInitialGain(float amplitude)

public float getInitialGain()

This gain is a scale factor that is applied to the sound data associated with this
sound source to increase or decrease its overall amplitude.

public void setLoop(int loopCount)

public int getLoop()

Data for nonstreaming sound (such as a sound sample) can contain two loop
points marking a section of the data that is to be looped a specific number of
times. Thus, sound data can be divided into three segments: the attack (before
the begin loop point), the sustain (between the begin and end loop points), and
the release (after the end loop point). If there are no loop begin and end points
defined as part of the sound data (say for Java Media Player types that do not
contain sound samples), then the begin loop point is set at the beginning of the
sound data, and the end loop point at the end of the sound data. If this is the case,
looping the sound means repeating the whole sound. However, these begin and
end loop points can be placed anywhere within the sound data, allowing a por-
tion in the middle of the sound to be looped.
A sound can be looped a specified number of times after it is activated and
before it is completed. The loop count value explicitly sets the number of times
the sound is looped. Any non-negative number is a valid value. A value of 0
denotes that the looped section is not repeated, but is played only once. A value
of –1 denotes that the loop is repeated indefinitely.
Changing the loop count of a sound after the sound has been started will not
dynamically affect the loop count currently used by the sound playing. The new
loop count will be used the next time the sound is enabled.

public void setReleaseEnable(boolean state)

public boolean getReleaseEnable()

When a sound is disabled, its playback would normally stop immediately no

matter what part of the sound data was currently being played. By setting the
Release flag to true for nodes with nonstreaming sound data, the sound is
allowed to play from its current position in the sound data to the end of the data
(without repeats), thus playing the release portion of the sound before stopping.

80 The Java 3D API Specification

LEAF NODE OBJECTS Sound Node 6.9

public void setContinuousEnable(boolean state)

public boolean getContinuousEnable()

For some applications, it’s useful to turn a sound source “off” but to continue
“silently” playing the sound so that when it is turned back “on” the sound picks
up playing in the same location (over time) as it would have been if the sound
had never been disabled (turned off). Setting the continuous flag to true causes
the sound renderer to keep track of where (over time) the sound would be play-
ing even when the sound is disabled.

public setSchedulingBounds(Bounds region)

public Bounds getSchedulingBounds()

These two methods access or modify the Sound node’s scheduling bounds. This
bounds is used as the scheduling region when the scheduling bounding leaf is set
to null. A sound is scheduled for activation when its scheduling region inter-
sects the ViewPlatform’s activation volume. The getSchedulingBounds method
returns a copy of the associated bounds.

public void setSchedulingBoundingLeaf(BoundingLeaf region)

public BoundingLeaf getSchedulingBoundingLeaf()

These two methods access or modify the Sound node’s scheduling bounding leaf.
When set to a value other than null, this bounding leaf overrides the scheduling
bounds object and is used as the scheduling region.

public void setPriority(float ranking)

public float getPriority()

These methods access or modify the Sound node’s priority, which is used to rank
concurrently playing sounds in order of importance during playback. When more
sounds are started than the AudioDevice can handle, the Sound node with the
lowest priority ranking is deactivated. If a sound is deactivated (due to a sound
with a higher priority being started), it is automatically reactivated when
resources become available (for example, when a sound with a higher priority
finishes playing) or when the ordering of sound nodes is changed due to a change
in a Sound node’s priority.
Sounds with a lower priority than a sound that cannot be played due to a lack of
channels will be played. For example, assume we have eight channels available
for playing sounds. After ordering four sounds, we begin playing them in order,
checking if the number of channels required to play a given sound are actually
available before the sound is played. Furthermore, say the first sound needs three
channels to play, the second sound needs four channels, the third sound needs
three channels and the fourth sound needs only one channel. The first and sec-
Version 1.2, March 2000 81
6.9 Sound Node LEAF NODE OBJECTS

onds sounds can be started because they require seven of the eight available
channels. The third sound cannot be audibly started because it requires three
channels and only one is still available. Consequently, the third sound starts play-
ing “silently.” The fourth sound can and will be started since it only requires one
channel. The third sound will be made audible when three channels become
available (i.e., when the first or second sound is finished playing).
Sounds given the same priority are ordered randomly. If the application wants a
specific ordering it must assign unique priorities to each sound.
Methods to determine what audio output resources are required for playback of a
Sound node on a particular AudioDevice and to determine the currently available
audio output resources are described in Chapter 12, “Audio Devices.”

public void setEnable(boolean state)

public boolean getEnable()

These two methods access or modify the playing state of this sound (that is,
whether the sound is enabled). When enabled, the sound source is started and
thus can potentially be heard, depending on its activation state, gain control
parameters, continuation state, and spatialization parameters. If the continuous
state is true and the sound is not active, enabling the sound starts the sound
silently “playing” so that when the sound is activated, the sound is (potentially)
heard from somewhere in the middle of the sound data. The activation state can
change from active to inactive any number of times without stopping or starting
the sound. To restart a sound at the beginning of its data, re-enable the sound by
calling setEnable with a value of true.
Setting the enable flag to true during construction will act as a request to start
the sound playing “as soon as it can” be started. This could be close to immedi-
ately in limited cases, but several conditions, detailed below, must be meet for a
sound to be ready to be played.

public boolean isReady()

This method retrieves the sound’s “ready” status. If this sound is fully prepared
for playing (either audibly or silently) on all initialized audio devices, this
method returns true. Sound data associated with a Sound node, either during con-
struction (when the MediaContainer is passed into the constructor as a parame-
ter) or by calling setSoundData(), it can be prepared to begin playing only after
the following conditions are satisfied:
• The Sound node has non-null sound data associated with it
• The Sound node is live

82 The Java 3D API Specification

LEAF NODE OBJECTS BackgroundSound Node 6.9.1

• There is an active View in the Universe

• There is an initialized AudioDevice associated with the PhysicalEnviron-
ment.
Depending on the type of MediaContainer the sound data is and on the imple-
mentation of the AudioDevice used, sound data preparation could consist of
opening, attaching, loading, or copying into memory the associated sound data.
The query method, isReady(), returns true when the sound is fully prepro-
cessed so that it is playable (audibly if active, silently if not active).

public boolean isPlaying()

A sound source will not be heard unless it is both enabled (turned on) and acti-
vated. If this sound is audibly playing on any initialized audio device, this
method will return a status of true.
When the sound finishes playing its sound data (including all loops), it is implic-
itly disabled.

public boolean isPlayingSilently()

This method returns the sound’s silent status. If this sound is silently playing on
any initialized audio device, this method returns true.

public long getDuration()

This method returns the length of time (in milliseconds) that the sound media
associated with the sound source could run (including the number of times its
loop section is repeated) if it plays to completion. If the sound media type is
streaming, or if the sound is looped indefinitely, then a value of –1 (implying
infinite length) is returned.

public int getNumberOfChannelsUsed()

When a sound is started it could use more than one channel on the selected
AudioDevice it is to be played on. This method retrieves the number of channels
that are being used to render this sound on the audio device associated with the
VirtualUniverse’s primary view. The method returns 0 if sound is not playing.

6.9.1 BackgroundSound Node

A BackgroundSound node defines an unattenuated, nonspatialized sound source
that has no position or direction. It has the same attributes as a Sound node. This
type of sound is simply added to the sound mix without modification and is use-
ful for playing a mono or stereo music track, or an ambient sound effect. Unlike
Version 1.2, March 2000 83
6.9.2 PointSound Node LEAF NODE OBJECTS

a Background (visual) node, more than one BackgroundSound node can be

simultaneously enabled and active.

Constructors
The BackgroundSound node specifies the following constructor.

public BackgroundSound()

Constructs a BackgroundSound node object using the default parameters for

Sound nodes.

public BackgroundSound(MediaContainer soundData,

float initialGain)
public BackgroundSound(MediaContainer soundData,
float initialGain, int loopCount, boolean release,
boolean continuous, boolean enable, Bounds region,
float priority)

The first constructor constructs a new BackgroundSound node using only the
provided parameter values for the sound data and initial gain. The second con-
structor uses the provided parameter values for the sound data, initial gain, the
number of times the loop is looped, a flag denoting whether the sound data is
played to the end, a flag denoting whether the sound plays silently when dis-
abled, whether sound is switched on or off, the sound activation region, and a
priority value denoting the playback priority ranking.

6.9.2 PointSound Node

The PointSound node defines a spatially located sound whose waves radiate uni-
formly in all directions from some point in space. It has the same attributes as a
Sound object, with the addition of a location and the specification of distance-
based gain attenuation for listener positions between an array of distances.
The sound’s amplitude is attenuated based on the distance between the listener
and the sound source position. A piecewise linear curve (defined in terms of
pairs consisting of a distance and a gain scale factor) specifies the gain scale fac-
tor slope.
The PointSound’s location and attenuation distances are defined in the local
coordinate system of the node.

Constants
The PointSound object contains the following flags.

84 The Java 3D API Specification

LEAF NODE OBJECTS PointSound Node 6.9.2

public static final int ALLOW_POSITION_READ

public static final int ALLOW_POSITION_WRITE
public static final int ALLOW_DISTANCE_GAIN_READ
public static final int ALLOW_DISTANCE_GAIN_WRITE

These flags, when enabled using the setCapability method, allow an applica-
tion to invoke methods that respectively read and write the position and the dis-
tance gain array. These capability flags are enforced only when the node is part
of a live or compiled scene graph.

Constructors
The PointSound node object defines the following constructors.

public PointSound()

Constructs a PointSound node object that includes the defaults for a Sound
object plus the following defaults for its own fields:
Parameter Default Value
Position vector (0.0, 0.0, 0.0)
initialGain null (no attenuation performed)

public PointSound(MediaContainer soundData, float initialGain,

Point3f position)
public PointSound(MediaContainer soundData, float initialGain,
float posX, float posY, float posZ)

Both of these constructors construct a PointSound node object using only the
provided parameter values for sound data, sample gain, and position. The
remaining fields are set to the default values specified earlier. The first form uses
vectors as input for its position. The second form uses individual float parameters
for the elements of the position vector.
public PointSound(MediaContainer soundData, float initialGain,
int loopCount, boolean release, boolean continuous,
boolean enable, Bounds region, float priority,
Point3f position, Point2f distanceGain[])
public PointSound(MediaContainer soundData, float initialGain,
int loopCount, boolean release, boolean continuous,
boolean enable, Bounds region, float priority, float posX,
float posY, float posZ, Point2f distanceGain[])
public PointSound(MediaContainer soundData, float initialGain,
int loopCount, boolean release, boolean continuous,
boolean enable, Bounds region, float priority,
Point3f position, float attenuationDistance[],
float attenuationGain[])

Version 1.2, March 2000 85

6.9.2 PointSound Node LEAF NODE OBJECTS

public PointSound(MediaContainer soundData, float initialGain,

int loopCount, boolean release, boolean continuous,
boolean enable, Bounds region, float priority, float posX,
float posY, float posZ, float attenuationDistance[],
float attenuationGain[])

These four constructors construct a PointSound node object using the provided
parameter values. The first and third forms use points as input for the position.
The second and fourth forms use individual float parameters for the elements of
the position. The first and second forms accept an array of Point2f for the dis-
tance attenuation values where each pair in the array contains a distance and a
gain scale factor. The third and fourth forms accept separate arrays for the com-
ponents of distance attenuation, namely, the distance and gain scale factors. See
the description for the setDistanceGain method, below, for details on how the
separate arrays are interpreted.

Methods
The PointSound node object defines the following methods.

public void setPosition(Point3f position)

public void setPosition(float x, float y, float z)
public void getPosition(Point3f position)

These methods set and retrieve the position in 3D space from which the sound
radiates.

public void setDistanceGain(Point2f attenuation[])

public void setDistanceGain(float distance[], float gain[])
public int getDistanceGainLength()
public void getDistanceGain(Point2f attenuation[])
public void getDistanceGain(float distance[], float gain[])

These methods set and retrieve the sound’s distance attenuation. If this is not set,
no distance gain attenuation is performed (equivalent to using a gain scale factor
of 1.0 for all distances). See Figure 6-2. Gain scale factors are associated with
distances from the listener to the sound source via an array of distance and gain
scale factor pairs. The gain scale factor applied to the sound source is determined
by finding the range of values distance[i] and distance[i+1] that includes
the current distance from the listener to the sound source, then linearly interpo-
lating the corresponding values gain[i] and gain[i+1] by the same amount.
If the distance from the listener to the sound source is less than the first distance
in the array, the first gain scale factor is applied to the sound source. This creates
a spherical region around the listener within which all sound gain is uniformly
scaled by the first gain in the array.
86 The Java 3D API Specification
LEAF NODE OBJECTS PointSound Node 6.9.2

If the distance from the listener to the sound source is greater than the last dis-
tance in the array, the last gain scale factor is applied to the sound source.
The first form of setDistanceGain takes these pairs of values as an array of
Point2f. The second form accepts two separate arrays for these values. The dis-
tance and gainScale arrays should be of the same length. If the gainScale
array length is greater than the distance array length, the gainScale array ele-
ments beyond the length of the distance array are ignored. If the gainScale
array is shorter than the distance array, the last gainScale array value is
repeated to fill an array of length equal to distance array.
There are two methods for getDistanceGain, one returning an array of points,
the other returning separate arrays for each attenuation component.

1.0

Scale factor
0.5

0.0
0 10 20 30
Distance (from listener
to sound source)

Figure 6-2 PointSound Distance Gain Attenuation

Distance elements in this array of Point2f are a monotonically increasing set of

floating-point numbers measured from the location of the sound source. Gain
scale factor elements in this list of pairs can be any positive floating-point num-
bers. While for most applications this list of gain scale factors will usually be
monotonically decreasing, they do not have to be.

Version 1.2, March 2000 87

6.9.3 ConeSound Node LEAF NODE OBJECTS

Figure 6-2 shows a graphical representation of a distance gain attenuation list.

The values given for distance/gain pairs would be
( (10.0, 1.0), (12.0, 0.9), (16.0, 0.5), (17.0, 0.3),
(20.0, 0.16), (24.0, 0.12), (28.0, 0.05), (30.0, 0.0) )
Thus if the current distance from the listener to the sound source is 22 units, a
scale factor of 0.14 would be applied to the sound amplitude. If the current dis-
tance from the listener to the sound source is less than 10 units, the scale factor
of 1.0 would be applied to the sound amplitude. If the current distance from the
listener to the sound source is greater than 30 units, the scale factor of 0.0 would
be applied to the sound amplitude.
The getDistanceGainLength method returns the length of the distance gain
attenuation arrays. Arrays passed into getDistanceGain methods should all be
at least this size.

6.9.3 ConeSound Node

The ConeSound node object defines a PointSound node whose sound source is
directed along a specific vector in space. A ConeSound source is attenuated by
gain scale factors and filters based on the angle between the vector from the
source to the listener, and the ConeSound’s direction vector. This attenuation is
either a single spherical distance gain attenuation (as for a general PointSound
source) or dual front and back distance gain attenuations defining elliptical atten-
uation volumes. The angular filter and the active AuralAttribute component filter
define what filtering is applied to the sound source.
This node has the same attributes as a PointSound node, with the addition of a
direction vector and an array of points that each contain an angular distance (in
radians), a gain scale factor, and a filter (which for now consists of a lowpass fil-
ter cutoff frequency). Similar to the definition of the distance gain array for
PointSounds, a piecewise linear curve (defined in terms of radians from the axis)
specifies the slope of these additional attenuation values.
Figure 6-3 shows an approximation of angular attenuation (disregarding distance
attenuation).

88 The Java 3D API Specification

LEAF NODE OBJECTS ConeSound Node 6.9.3

DistanceGain[0]

DistanceGain[1]

angularAttenuation[3]

angularAttenuation[0]

Sound Direction (axis)

Attenuated Values

Figure 6-3 ConeSound

Constants
The ConeSound object contains the following flags.

public static final int ALLOW_DIRECTION_READ

public static final int ALLOW_DIRECTION_WRITE
public static final int ALLOW_ANGULAR_ATTENUATION_READ
public static final int ALLOW_ANGULAR_ATTENUATION_WRITE

These flags, when enabled using the setCapability method, allow an applica-
tion to invoke methods that respectively read and write the direction and the
angular attenuation array. These capability flags are enforced only when the node
is part of a live or compiled scene graph.

Constructors
The ConeSound node object defines the following constructors.

public ConeSound()

Constructs a ConeSound node object that includes the defaults for a PointSound
object plus the following defaults for its own fields:
Parameter Default Value
direction vector (0.0, 0.0, 1.0)

Version 1.2, March 2000 89

6.9.3 ConeSound Node LEAF NODE OBJECTS

Parameter Default Value

BackDistanceAttenuation null
Angular attenuation ((0.0, 1.0, NO_FILTER),(π/2, 0.0, NO_FILTER))

public ConeSound(MediaContainer soundData, float initialGain,

Point3f position, Vector3f direction)
public ConeSound(MediaContainer soundData, float initialGain,
float posX, float posY, float posZ, float dirX, float dirY,
float dirZ)

Both of these constructors construct a ConeSound node object using only the
provided parameter values for sound, overall initial gain, position, and direction.
The remaining fields are set to the default values listed earlier. The first form
uses points as input for its position and direction. The second form uses individ-
ual float parameters for the elements of the position and direction vectors.

public ConeSound(MediaContainer soundData, float initialGain,

int loopCount, boolean release, boolean continuous,
boolean enable, Bounds region, float priority,
Point3f position, Point2f frontDistanceAttenuation[],
Point2f backDistanceAttenuation[], Vector3f direction)
public ConeSound(MediaContainer soundData, float initialGain,
int loopCount, boolean release, boolean continuous,
boolean enable, Bounds region, float priority, float posX,
float posY, float posZ, float frontDistance[],
float frontDistanceGain[], float backDistance[],
float backDistanceGain[], float dirX, float dirY, float dirZ)

These constructors construct a ConeSound node object using the provided

parameter values. The first form uses points or vectors as input for its position,
direction, and front/back distance attenuation arrays. The second form uses indi-
vidual float parameters for the elements of the position, direction, and two dis-
tance attenuation arrays.
Unlike the single distance gain attenuation array for PointSounds, which define
spherical areas about the sound source between which gains are linearly interpo-
lated, this directed ConeSound can have two distance gain attenuation arrays that
define ellipsoidal attenuation areas. See the setDistanceGain PointSound
method for details on how the separate distance and distanceGain arrays are
interpreted.
The ConeSound’s direction vector and angular measurements are defined in the
local coordinate system of the node.

90 The Java 3D API Specification

LEAF NODE OBJECTS ConeSound Node 6.9.3

public ConeSound(MediaContainer soundData, float initialGain,

int loopCount, boolean release, boolean continuous,
boolean enable, Bounds region, float priority,
Point3f position, Point2f distanceAttenuation[],
Vector3f direction, Point3f angularAttenuation[])
public ConeSound(MediaContainer soundData, float initialGain,
int loopCount, boolean release, boolean continuous,
boolean enable, Bounds region, float priority, float posX,
float posY, float posZ, float distance[],
float distanceGain[], float dirX, float dirY, float dirZ,
float angle[], float angularGain[], float frequencyCutoff[])

These constructors construct a ConeSound node object using the provided

parameter values, which include a single spherical distance attenuation array.
The first form uses points and vectors as input for its position, direction, single
spherical distanceAttenuation array, and angularAttenuation array. The
second form uses individual float parameters for the elements of the position,
direction, distanceAttenuation array, and angularAttenuation array.
The first form accepts arrays of points for the distance attenuation and angular
values. Each Point2f in the distanceAttenuation array contains a distance and
a gain scale factor. Each Point3f in the angularAttenuation array contains an
angular distance, a gain scale factor, and a filtering value (which is currently
defined as a simple cutoff frequency).
The second form accepts separate arrays for the distance and gain scale factor
components of distance attenuation, and separate arrays for the angular distance,
angular gain, and filtering components of angular attenuation. See the setDis-
tanceGain PointSound method for details on how the separate distance and
distanceGain arrays are interpreted. See the setAngularAttenuation Cone-
Sound method for details on how the separate angularDistance, angularGain,
and filter arrays are interpreted.
public ConeSound(MediaContainer soundData, float initialGain,
int loopCount, boolean release, boolean continuous,
boolean enable, Bounds region, float priority,
Point3f position, Point2f frontDistanceAttenuation[],
Point2f backDistanceAttenuation[], Vector3f direction,
Point3f angularAttenuation[])
public ConeSound(MediaContainer soundData, float initialGain,
int loopCount, boolean release, float priority,
boolean continuous, boolean enable, Bounds region,
float posX, float posY, float posZ, float frontDistance[],
float frontDistanceGain[], float backDistance[],
float backDistanceGain[], float dirX, float dirY, float dirZ,
float angle[], float angularGain[], float frequencyCutoff[])

Version 1.2, March 2000 91

6.9.3 ConeSound Node LEAF NODE OBJECTS

These constructors construct a ConeSound node object using the provided

parameter values, which include two distance attenuation arrays defining ellipti-
cal distance attenuation regions. The first form uses points and vectors as input
for its position, direction, and attenuation arrays. The second form uses individ-
ual float parameters for these same elements.
These two constructors differ from the previous two constructors only in the def-
inition of the two distinct front and back distance attenuation arrays. See the
setDistanceGain ConeSound method for details on how the separate distance
and distanceGain arrays are interpreted. See the setAngularAttenuation
ConeSound method for details on how the separate angularDistance, angular-
Gain, and filter arrays are interpreted.

Methods
The ConeSound node object defines the following methods.

public void setDistanceGain(Point2f frontAttenuation[], Point2f

backAttenuation[])
public void setDistanceGain(float frontDistance[],
float frontGain[], float backDistance[], float backGain[])
public void setBackDistanceGain(Point2f attenuation[])
public void setBackDistanceGain(float distance[], float gain[])
public void getDistanceGain(Point2f frontAttenuation[], Point2f
backAttenuation[])
public void getDistanceGain(float frontDistance[],
float frontGain[], float backDistance[], float backGain[])

These methods set and retrieve the ConeSound’s two distance attenuation arrays.
If these are not set, no distance gain attenuation is performed (equivalent to using
a distance gain of 1.0 for all distances). If only one distance attenuation array is
set, spherical attenuation is assumed (see Figure 6-4). If both a front and back
distance attenuation are set, elliptical attenuation regions are defined (see
Figure 6-5). Use the PointSound setDistanceGain method to set the front dis-
tance attenuation array separately from the back distance attenuation array.
A front distance attenuation array defines monotonically increasing distances
from the sound source origin along the position direction vector. A back distance
attenuation array (if given) defines monotonically increasing distances from the
sound source origin along the negative direction vector. The two arrays must be
of the same length. The backDistance[i] gain values must be less than or equal
to frontDistance[i] gain values.

92 The Java 3D API Specification

LEAF NODE OBJECTS ConeSound Node 6.9.3

Listener

Angular distances

Sound
Source Distances
Figure 6-4 ConeSound with a Single Distance Gain Attenuation Array

Listener

Back distances Front distances

Figure 6-5 ConeSound with Two Distance Gain Attenuation Arrays

Gain scale factors are associated with distances from the listener to the sound
source via an array of distance and gain scale factor pairs (see Figure 6-2). The
gain scale factor applied to the sound source is the linear interpolated gain value
within the distance value range that includes the current distance from the lis-
tener to the sound source.
The getDistanceGainLength method (defined in PointSound) returns the length
of all distance gain attenuation arrays, including the back distance gain arrays.
Arrays passed into getBackDistanceGain methods should all be at least this size.

Version 1.2, March 2000 93

6.9.3 ConeSound Node LEAF NODE OBJECTS

public void setDirection(Vector3f direction)

public void setDirection(float x, float y, float z)
public void getDirection(Vector3f direction)

This value is the sound source’s direction vector. It is the axis from which angu-
lar distance is measured.

public void setAngularAttenuation(Point2f attenuation[])

public void setAngularAttenuation(Point3f attenuation[])
public void setAngularAttenuation(float angle[],
float angularGain[], float frequencyCutoff[])
public int getAngularAttenuationLength()
public void getAngularAttenuation(Point3f attenuation[])
public void getAngularAttenuation(float angle[],
float angularGain[], float frequencyCutoff[])

These methods set and retrieve the sound’s angular gain and filter attenuation
arrays. If these are not set, no angular gain attenuation or filtering is performed
(equivalent to using an angular gain scale factor of 1.0 and an angular filter of
NO_FILTER for all distances). This attenuation is defined as a triple of angular
distance, gain scale factor, and filter values. The distance is measured as the
angle in radians between the ConeSound’s direction vector and the vector from
the sound source position to the listener. Both the gain scale factor and filter
applied to the sound source are the linear interpolation of values within the dis-
tance value range that includes the angular distance from the sound source axis.
If the angular distance from the listener-sound-position vector and the sound’s
direction vector is less than the first distance in the array, the first gain scale fac-
tor and first filter are applied to the sound source. This creates a conical region
around the listener within which the sound is uniformly attenuated by the first
gain and the first filter in the array.
If the distance from the listener-sound-position vector and the sound’s direction
vector is greater than the last distance in the array, the last gain scale factor and
last filter are applied to the sound source.
Distance elements in this array of points are a monotonically increasing set of
floating point numbers measured from 0 to π radians. Gain scale factor elements
in this list of points can be any positive floating-point numbers. While for most
applications this list of gain scale factors will usually be monotonically decreas-
ing, they do not have to be. The filter (for now) is a single simple frequency cut-
off value.
In the first form of setAngularAttenuation, only the angular distance and
angular gain scale factor pairs are given. The filter values for these tuples are

94 The Java 3D API Specification

LEAF NODE OBJECTS Soundscape Node 6.10

implicitly set to NO_FILTER. In the second form of setAngularAttenuation, an

array of all three values is supplied.
The third form of setAngularAttenuation accepts three separate arrays for
these angular attenuation values. These arrays should be of the same length. If
the angularGain or filtering array length is greater than the angularDistance
array length, the array elements beyond the length of the angularDistance array
are ignored. If the angularGain or filtering array is shorter than the angu-
larDistance array, the last value of the short array is repeated to fill an array of
length equal to the angularDistance array.
The getAngularAttenuationArrayLength method returns the length of the
angular attenuation arrays. Arrays passed into getAngularAttenuation methods
should all be at least this size.
There are two methods for getAngularAttenuation, one returning an array of
points, the other returning separate arrays for each attenuation component.
Figure 6-3 shows an example of an angular attenuation defining four points of
the form (radiant distance, gain scale factor, cutoff filter frequency):
( (0.12, 0.8, NO_FILTER), (0.26, 0.6, 18000.0), (0.32, 0.4, 15000.0),
(0.40, 0.2, 11000.0) )

6.10 Soundscape Node

The Soundscape leaf node defines the attributes that characterize the listener’s
aural environment. This node defines an application region and an associated
aural attribute component object that controls reverberation and atmospheric
properties that affect sound source rendering. (Aural attributes are described in
Section 8.1.17, “AuralAttributes Object.”) Multiple Soundscape nodes can be
included in a single scene graph.
The Soundscape application region, different from a Sound node’s scheduling
region, is used to select which Soundscape (and thus which aural attribute object)
is to be applied to the sounds being rendered. This selection is based on the posi-
tion of the ViewPlatform (the “listener”), not the position of the sound.
It will be common for multiple Soundscape regions to be contained within a
scene graph. Figure 6-6 shows application regions for two Soundscape nodes: a
region with a large open area on the right, and a smaller, more constricted, less
reverberant area on the left.

Version 1.2, March 2000 95

 Application region 1 Application region 2

Figure 6-6 Multiple Soundscape Application Regions

The reverberation attributes for these two regions could be set to represent their
physical differences so that active sounds are rendered differently depending on
which region the listener is in.

Constants
The Soundscape node object defines the following flags.

public static final int ALLOW_APPLICATION_BOUNDS_READ

public static final int ALLOW_APPLICATION_BOUNDS_WRITE
public static final int ALLOW_ATTRIBUTES_READ
public static final int ALLOW_ATTRIBUTES_WRITE

These flags, when enabled using the setCapability method, allow an applica-
tion to invoke methods that respectively read and write the application region and
the aural attributes. These capability flags are enforced only when the node is
part of a live or compiled scene graph.

Constructors
The Soundscape node object defines the following constructors.

public Soundscape()

Constructs a Soundscape node object that includes the following defaults for its
elements:
LEAF NODE OBJECTS ViewPlatform Node 6.11

Parameter Default Value

application region null (no active region)
aural attributes null (uses default aural attributes)

public Soundscape(Bounds region, AuralAttributes attributes)

This method constructs a Soundscape node object using the specified application
region and aural attributes.

Methods
The Soundscape node object defines the following methods.

public void setApplicationBounds(Bounds region)

public Bounds getApplicationBounds()

These two methods access or modify the Soundscape node’s application bounds.
This bounds is used as the application region when the application bounding leaf
is set to null. The aural attributes associated with this Soundscape are used to
render the active sounds when this application region intersects the ViewPlat-
form’s activation volume. The getApplicationBounds method returns a copy of
the associated bounds.

public void setApplicationBoundingLeaf(BoundingLeaf region)

public BoundingLeaf getApplicationBoundingLeaf()

These two methods access or modify the Soundscape node’s application bound-
ing leaf. When set to a value other than null, this bounding leaf overrides the
application bounds object and is used as the application region.

public void setAuralAttributes(AuralAttributes attributes)

public AuralAttributes getAuralAttributes()

These two methods access or modify the aural attributes of this Soundscape. Set-
ting it to null results in default attribute use.

6.11 ViewPlatform Node

The ViewPlatform node object defines a viewing platform that is referenced by a
View object. The location, orientation, and scale of the composite transforms in
the scene graph from the root to the ViewPlatform specify where the viewpoint is
located and in which direction it is pointing. A viewer navigates through the vir-
tual universe by changing the transform in the scene graph hierarchy above the
ViewPlatform.
Version 1.2, March 2000 97
6.11 ViewPlatform Node LEAF NODE OBJECTS

Constants
The ViewPlatform node object defines the following flags.

public static final int ALLOW_POLICY_READ

public static final int ALLOW_POLICY_WRITE

These flags, when enabled using the setCapability method, allow an applica-
tion to invoke methods that respectively read and write the view attach policy.
These capability flags are enforced only when the node is part of a live or com-
piled scene graph.

Constructors

public ViewPlatform()

Constructs and initializes a new ViewPlatform leaf node object with default
parameters:
Parameter Default Value
view attach policy View.NOMINAL_HEAD
activation radius 62

Methods
The ViewPlatform node object defines the following methods:

public void setActivationRadius(float activationRadius)

public float getActivationRadius()

The activation radius defines an activation volume surrounding the center of the
ViewPlatform. This activation volume intersects with the scheduling regions and
application regions of other leaf node objects to determine which of those objects
may affect rendering.
Different leaf objects interact with the ViewPlatform’s activation volume differ-
ently. The Background, Clip, and Soundscape leaf objects each define a set of
attributes and an application region in which those attributes are applied. If more
than one node of a given type (Background, Clip, or Soundscape) intersects the
ViewPlatform’s activation volume, the “most appropriate” node is selected.
Sound leaf objects begin playing their associated sounds when their scheduling
region intersects a ViewPlatform’s activation volume. Multiple sounds may be
active at the same time.

98 The Java 3D API Specification

LEAF NODE OBJECTS Morph Node 6.13

Behavior objects act somewhat differently. Those Behavior objects with schedul-
ing regions that intersect a ViewPlatform’s activation volume become candidates
for scheduling. Effectively, a ViewPlatform’s activation volume becomes an
additional qualifier on the scheduling of all Behavior objects. See Chapter 10,
“Behaviors and Interpolators,” for more details.

public void setViewAttachPolicy(int policy)

public int getViewAttachPolicy()

The view attach policy determines how Java 3D places the user’s virtual eye
point as a function of head position. See Section 9.4.3, “View Attach Policy,” for
details.

6.12 Behavior Node

The Behavior leaf node allows an application to manipulate a scene graph at run
time. Behavior is an abstract class that defines properties common to all Behav-
ior objects in Java 3D. There are several predefined behaviors that are subclasses
of Behavior. Additionally, a Behavior leaf node may be subclassed by the user.
Behaviors are described in Chapter 10, “Behaviors and Interpolators.”

6.13 Morph Node

The Morph leaf node permits an application to morph between multiple Geome-
tryArrays. The Morph node contains a single Appearance node, an array of
GeometryArray objects, and an array of corresponding weights. The Morph node
combines these GeometryArrays into an aggregate shape based on each Geome-
tryArray’s corresponding weight. Typically, Behavior nodes will modify the
weights to achieve various morphing effects.

Constants
The Morph node specifies the following flags.

public static final int ALLOW_GEOMETRY_ARRAY_READ

public static final int ALLOW_GEOMETRY_ARRAY_WRITE
public static final int ALLOW_APPEARANCE_READ
public static final int ALLOW_APPEARANCE_WRITE
public static final int ALLOW_WEIGHTS_READ
public static final int ALLOW_WEIGHTS_WRITE
public static final int ALLOW_COLLISION_BOUNDS_READ
public static final int ALLOW_COLLISION_BOUNDS_WRITE

Version 1.2, March 2000 99

6.13 Morph Node LEAF NODE OBJECTS

public static final int ALLOW_APPEARANCE_OVERRIDE_READ New in 1.2

public static final int ALLOW_APPEARANCE_OVERRIDE_WRITE New in 1.2

These flags, when enabled using the setCapability method, allow an applica-
tion to invoke methods that respectively read and write the node’s, appearance,
weights, collision Bounds, and appearance override enable components.

Constructors
The Morph node specifies the following constructors.

public Morph(GeometryArray geometryArrays[])

Constructs and initializes a new Morph leaf node with the specified array of
GeometryArray objects. Default values are used for all other parameters:
Parameter Default Value
appearance null
weights [1, 0, 0, 0, ...]
collision bounds null
appearance override enable false

A null appearance object specifies that default values are used for all appearance
attributes.

public Morph(GeometryArray geometryArrays[],

Appearance appearance)

Constructs and initializes a new Morph leaf node with the specified array of
GeometryArray objects and the specified Appearance object. The length of the
geometryArrays parameter determines the number of weighted geometry arrays
in this Morph node. If geometryArrays is null, then a NullPointerException
is thrown. If the Appearance component is null, then default values are used for
all appearance attributes.

Methods
The Morph node specifies the following methods.

public void setGeometryArrays(GeometryArray geometryArrays[])

This method sets the array of GeometryArray objects in the Morph node. Each
GeometryArray component specifies colors, normals, and texture coordinates.
The length of the geometryArrays parameter must be equal to the length of the

100 The Java 3D API Specification

LEAF NODE OBJECTS Morph Node 6.13

array with which this Morph node was created; otherwise, an Illegal-
ArgumentException is thrown.

public GeometryArray getGeometryArray(int index)

This method retrieves a single geometry array from the Morph node. The index
parameter specifies which array is returned.

public void setAppearance(Appearance appearance)

public Appearance getAppearance()

These methods set and retrieve the Appearance component of this Morph node.
The Appearance component specifies material, texture, texture environment,
transparency, or other rendering parameters. Setting it to null results in default
attribute use.

public void setWeights(double weights[])

public double[] getWeights()

These methods set and retrieve the morph weight vector component of this
Morph node. The Morph node “weights” the corresponding GeometryArray by
the amount specified. The length of the weights parameter must be equal to the
length of the array with which this Morph node was created; otherwise, an Ille-
galArgumentException is thrown.

public void setCollisionBounds(Bounds bounds)

public Bounds getCollisionBounds()

These methods set and retrieve the collision bounding object of this node.

public boolean intersect(SceneGraphPath path, PickShape pickShape)

public boolean intersect(SceneGraphPath path, PickRay pickRay,
double[] dist)

These methods check if the geometry component of this morph node under path
intersects with the pickShape.

public void setAppearanceOverrideEnable(boolean flag) New in 1.2

public boolean getAppearanceOverrideEnable() New in 1.2

These methods set and retrieve the flag that indicates whether this node’s appear-
ance can be overridden. If the flag is true, this node’s appearance may be overrid-
den by an AlternateAppearance leaf node, regardless of the value of the ALLOW_
APPEARANCE_WRITE capability bit. The default value is false. See Section 6.15,
“AlternateAppearance Node.”

Version 1.2, March 2000 101

6.14 Link Node LEAF NODE OBJECTS

6.14 Link Node

The Link leaf node allows an application to reference a shared subgroup, rooted
by a SharedGroup node, from within a branch of the scene graph. Any number of
Link nodes can refer to the same SharedGroup node. See Section 7.1.2, “Link
Leaf Node,” for a description of this node.

6.15 AlternateAppearance Node

The AlternateAppearance leaf node is used for overriding the Appearance com-
ponent of selected nodes. It defines an Appearance component object and a
region of influence in which this AlternateAppearance node is active. An Alter-
nateAppearance node also contains a list of Group nodes that specifies the hier-
archical scope of this AlternateAppearance. If the scope list is empty, the
AlternateAppearance node has universe scope; all nodes within the region of
influence are affected by this AlternateAppearance node. If the scope list is non-
empty, only those Leaf nodes under the Group nodes in the scope list are affected
by this AlternateAppearance node (subject to the influencing bounds).
An AlternateAppearance node affects Shape3D and Morph nodes by overriding
their appearance component with the appearance component in this AlternateAp-
pearance node. Only those Shape3D and Morph nodes that explicitly allow their
appearance to be overridden are affected. The AlternateAppearance node has no
effect on Shape3D and Morph nodes that do not allow their appearance to be
overridden.
If the regions of influence of multiple AlternateAppearance nodes overlap, the
Java 3D system will choose a single alternate appearance for those objects that
lie in the intersection. This is done in an implementation-dependent manner, but
in general, the AlternateAppearance node that is “closest” to the object is chosen.

Constants
The AlternateAppearance node specifies the following flags:

public static final int ALLOW_INFLUENCING_BOUNDS_READ New in 1.2

public static final int ALLOW_INFLUENCING_BOUNDS_WRITE New in 1.2
public static final int ALLOW_APPEARANCE_READ New in 1.2
public static final int ALLOW_APPEARANCE_WRITE New in 1.2
public static final int ALLOW_SCOPE_READ New in 1.2
public static final int ALLOW_SCOPE_WRITE New in 1.2

102 The Java 3D API Specification

LEAF NODE OBJECTS AlternateAppearance Node 6.15

These flags, when enabled using the setCapability method, allow an applica-
tion to invoke methods that respectively read and write the node’s influencing
bounds and bounds leaf information, appearance information, and scope infor-
mation components.

Constructors
The AlternateAppearance node specifies the following constructors.

public AlternateAppearance() New in 1.2

Constructs an AlternateAppearance node with default parameters. The default

values are as follows:
Parameter Default Value
appearance null
scope empty (universe scope)
influencing bounds null
influencing bounding leaf null

public AlternateAppearance(Appearance appearance) New in 1.2

Constructs an AlternateAppearance node with the specified appearance.

Methods
The AlternateAppearance node specifies the following methods.

public void setAppearance(Appearance appearance) New in 1.2

public Appearance getAppearance() New in 1.2

These methods set and retrieve the appearance of this AlternateAppearance node.
This appearance overrides the appearance in those Shape3D and Morph nodes
affected by this AlternateAppearance node.

public void setInfluencingBounds(Bounds region) New in 1.2

public Bounds getInfluencingBounds() New in 1.2

These methods set and retrieve the AlternateAppearance’s influencing region to

the specified bounds. This is used when the influencing bounding leaf is set to
null.

public void setInfluencingBoundingLeaf(BoundingLeaf region) New in 1.2

public BoundingLeaf getInfluencingBoundingLeaf() New in 1.2

Version 1.2, March 2000 103

6.15 AlternateAppearance Node LEAF NODE OBJECTS

These methods set and retrieve the AlternateAppearance’s influencing region to

the specified bounding leaf. When set to a value other than null, this overrides
the influencing bounds object.

public void setScope(Group scope, int index) New in 1.2

public Group getScope(int index) New in 1.2

The first method replaces the node at the specified index in this AlternateAppear-
ance node’s list of scopes with the specified Group node. The second method
retrieves the Group node at the specified index from this AlternateAppearance
node’s list of scopes. By default, AlternateAppearance nodes are scoped only by
their influencing bounds. This allows them to be further scoped by a list of nodes
in the hierarchy.

public void insertScope(Group scope, int index) New in 1.2

public void removeScope(int index) New in 1.2

The first method inserts the specified Group node into this AlternateAppearance
node’s list of scopes at the specified index. The second method removes the node
at the specified index from this AlternateAppearance node’s list of scopes. If this
operation causes the list of scopes to become empty, this AlternateAppearance
will have universe scope; all nodes within the region of influence will be affected
by this AlternateAppearance node. By default, AlternateAppearance nodes are
scoped only by their influencing bounds. This allows them to be further scoped
by a list of nodes in the hierarchy.

public Enumeration getAllScopes() New in 1.2

This method returns an enumeration of this AlternateAppearance node’s list of

scopes.

public void addScope(Group scope) New in 1.2

This method appends the specified Group node to this AlternateAppearance

node’s list of scopes. By default, AlternateAppearance nodes are scoped only by
their influencing bounds. This allows them to be further scoped by a list of nodes
in the hierarchy.

public int numScopes() New in 1.2

This method returns the number of nodes in this AlternateAppearance node’s list
of scopes. If this number is 0, the list of scopes is empty and this AlternateAp-
pearance node has universe scope; all nodes within the region of influence are
affected by this AlternateAppearance node.

104 The Java 3D API Specification

 C H A P T E R 7
Reusing Scene Graphs

JAVA 3D provides application programmers with two different means for reus-
ing scene graphs. First, multiple scene graphs can share a common subgraph.
Second, the node hierarchy of a common subgraph can be cloned, while still
sharing large component objects such as geometry and texture objects. In the first
case, changes in the shared subgraph affect all scene graphs that refer to the
shared subgraph. In the second case, each instance is unique—a change in one
instance does not affect any other instance.

7.1 Sharing Subgraphs

An application that wishes to share a subgraph from multiple places in a scene
graph must do so through the use of the Link leaf node and an associated
SharedGroup node. The SharedGroup node serves as the root of the shared sub-
graph. The Link leaf node refers to the SharedGroup node. It does not incorpo-
rate the shared scene graph directly into its scene graph.

7.1.1 SharedGroup Node

A SharedGroup node allows multiple Link leaf nodes to share its subgraph (see
Figure 7-1) according to the following semantics:
• A SharedGroup may be referenced by one or more Link leaf nodes. Any
runtime changes to a node or component object in this shared subgraph
affect all graphs that refer to this subgraph.
• A SharedGroup may be compiled by calling its compile method prior to
being referenced by any Link leaf nodes.
• Only Link leaf nodes may refer to SharedGroup nodes. A SharedGroup
node cannot have parents or be attached to a Locale.

Version 1.2, March 2000 105

7.1.1 SharedGroup Node REUSING SCENE GRAPHS

Virtual Universe

Hi-Res Locale

BG BG BranchGroup Nodes

L Link Nodes
L

SG SharedGroup Node

Figure 7-1 Sharing a Subgraph

A shared subgraph may contain any group node, except an embedded

SharedGroup node (SharedGroup nodes cannot have parents). However, only the
following leaf nodes may appear in a shared subgraph:
• Light
• Link
• Morph
• Shape
• Sound
An IllegalSharingException is thrown if any of the following leaf nodes
appear in a shared subgraph:
106 The Java 3D API Specification
REUSING SCENE GRAPHS Link Leaf Node 7.1.2

• AlternateAppearance
• Background
• BoundingLeaf
• Behavior
• Clip
• Fog
• ModelClip
• Soundscape
• ViewPlatform

Constructors

public SharedGroup()

Constructs and initializes a new SharedGroup node object.

Methods
The SharedGroup node defines the following methods.

public void compile()

This method compiles the source SharedGroup associated with this object and
creates and caches a newly compiled scene graph.

7.1.2 Link Leaf Node

The Link leaf node allows an application to reference a shared graph, rooted by
a SharedGroup node, from within a branch graph or another shared graph. See
Figure 7-1. Any number of Link nodes can refer to the same SharedGroup node.

Constants
The Link node object defines two flags.

public static final int ALLOW_SHARED_GROUP_READ

public static final int ALLOW_SHARED_GROUP_WRITE

These flags, when enabled using the setCapability method, allow an applica-
tion to invoke methods that respectively read and write the SharedGroup node
pointed to by this Link node. These capability flags are enforced only when the
node is part of a live or compiled scene graph.

Version 1.2, March 2000 107

7.2 Cloning Subgraphs REUSING SCENE GRAPHS

Constructors
The Link node object defines two constructors.

public Link()
public Link(SharedGroup sharedGroup)

The first form constructs a Link node object that does not yet point to a
SharedGroup node. The second form constructs a Link node object that points to
the specified SharedGroup node.

Methods
The Link node object defines two methods.

public void setSharedGroup(SharedGroup sharedGroup)

public SharedGroup getSharedGroup()

These methods access and modify the SharedGroup node associated with this
Link leaf node.

7.2 Cloning Subgraphs

An application developer may wish to reuse a common subgraph without com-
pletely sharing that subgraph. For example, the developer may wish to create a
parking lot scene consisting of multiple cars, each with a different color. The
developer might define three basic types of cars, such as convertible, truck, and
sedan. To create the parking lot scene, the application will instantiate each type
of car several times. Then the application can change the color of the various
instances to create more variety in the scene. Unlike shared subgraphs, each
instance is a separate copy of the scene graph definition: Changes to one instance
do not affect any other instance.
Java 3D provides the cloneTree method for this purpose. The cloneTree
method allows the programmer to change some attributes (NodeComponent
objects) in a scene graph, while at the same time sharing the majority of the
scene graph data—the geometry.

Methods

public Node cloneTree()

public Node cloneTree(boolean forceDuplicate)
public Node cloneTree(boolean forceDuplicate,
boolean allowDanglingReferences)

108 The Java 3D API Specification

REUSING SCENE GRAPHS References to Node Component Objects 7.2.1

public Node cloneTree(NodeReferenceTable referenceTable) New in 1.2

public Node cloneTree(NodeReferenceTable referenceTable,
boolean forceDuplicate) New in 1.2
public Node cloneTree(NodeReferenceTable referenceTable,
boolean forceDuplicate, boolean allowDanglingReferences) New in 1.2

These methods start the cloning of the subgraph. The optional forceDuplicate
parameter, when set to true, causes leaf NodeComponent objects to ignore their
duplicateOnCloneTree value and always be duplicated (see Section 7.2.1,
“References to Node Component Objects”). The allowDanglingReferences
parameter, when set to true, will permit the cloning of a subgraph even when a
dangling reference is generated (see Section 7.2.3, “Dangling References”). Set-
ting forceDuplicate and allowDanglingReferences to false is the equivalent
of calling cloneTree without any parameters. This will result in NodeCompo-
nent objects being either duplicated or referenced in the cloned node, based on
their duplicateOnCloneTree value. A DanglingReferenceException will be
thrown if a dangling reference is encountered.
When the cloneTree method is called on a node, that node is duplicated along
with its entire internal state. If the node is a Group node, cloneTree is then
called on each of the node’s children.
The cloneTree method cannot be called on a live or compiled scene graph.

7.2.1 References to Node Component Objects

When cloneTree reaches a leaf node, there are two possible actions for handling
the leaf node’s NodeComponent objects (such as Material, Texture, and so forth).
First, the cloned leaf node can reference the original leaf node’s NodeComponent
object—the NodeComponent object itself is not duplicated. Since the cloned leaf
node shares the NodeComponent object with the original leaf node, changing the
data in the NodeComponent object will effect a change in both nodes. This mode
would also be used for objects that are read-only at run time.
Alternatively, the NodeComponent object can be duplicated, in which case the
new leaf node would reference the duplicated object. This mode allows data ref-
erenced by the newly created leaf node to be modified without that modification
affecting the original leaf node.
Figure 7-2 shows two instances of NodeComponent objects that are shared and
one NodeComponent element that is duplicated for the cloned subgraph.

Version 1.2, March 2000 109

7.2.2 References to Other Scene Graph Nodes REUSING SCENE GRAPHS

G G

Group Nodes

cloneTree

Leaf Nodes
Lf Lf Lf Lf Lf Lf

NodeComponents

Figure 7-2 Referenced and Duplicated NodeComponent Objects

Methods

public void setDuplicateOnCloneTree(boolean)

public void getDuplicateOnCloneTree()

These methods set a flag that controls whether a NodeComponent object is dupli-
cated or referenced on a call to cloneTree. By default this flag is false, mean-
ing that the NodeComponent object will not be duplicated on a call to
cloneTree—newly created leaf nodes will refer to the original NodeComponent
object instead.
If the cloneTree method is called with the forceDuplicate parameter set to
true, the duplicateOnCloneTree flag is ignored and the entire scene graph is
duplicated.

7.2.2 References to Other Scene Graph Nodes

Leaf nodes that contain references to other nodes (for example, Light nodes ref-
erence a Group node) can create a problem for the cloneTree method. After the
cloneTree operation is performed, the reference in the cloned leaf node will still
refer to the node in the original subgraph—a situation that is most likely incor-
rect (see Figure 7-3).
To handle these ambiguities, a callback mechanism is provided.

110 The Java 3D API Specification

REUSING SCENE GRAPHS References to Other Scene Graph Nodes 7.2.2

G G

N1 N2
cloneTree

Lf Lf Lf1 Lf Lf Lf2

Figure 7-3 References to Other Scene Graph Nodes

A leaf node that needs to update referenced nodes upon being duplicated by a
call to cloneTree must implement the updateNodeReferences method. By
using this method, the cloned leaf node can determine if any nodes referenced by
it have been duplicated and, if so, update the appropriate references to their
cloned counterparts.
Suppose, for instance, that the leaf node Lf1 in Figure 7-3 implemented the
updateNodeReferences method. Once all nodes had been duplicated, the clon-
eTree method would then call each cloned leaf’s node updateNodeReferences
method. When cloned leaf node Lf2’s method was called, Lf2 could ask if the
node N1 had been duplicated during the cloneTree operation. If the node had
been duplicated, leaf Lf2 could then update its internal state with the cloned
node, N2 (see Figure 7-4).

G G

N1 cloneTree N2

Lf Lf Lf1 Lf Lf Lf2

Figure 7-4 Updated Subgraph after updateNodeReferences Call

Version 1.2, March 2000 111

7.2.3 Dangling References REUSING SCENE GRAPHS

All predefined Java 3D nodes will automatically have their updateNodeRefer-

ences method defined. Only subclassed nodes that reference other nodes need to
have this method overridden by the user.

Methods

public void updateNodeReferences(NodeReferenceTable

referenceTable)

This SceneGraphObject node method is called by the cloneTree method after all
nodes in the subgraph have been cloned. The user can query the NodeReference-
Table object (see Section 7.2.5, “NodeReferenceTable Object”) to determine if
any nodes that the SceneGraphObject node references have been duplicated by
the cloneTree call and, if so, what the corresponding node is in the new sub-
graph. If a user extends a predefined Java 3D object and adds a reference to
another node, this method must be defined in order to ensure proper operation of
the cloneTree method. The first statement in the user’s updateNodeReferences
method must be super.updateNodeReferences(referenceTable). For pre-
defined Java 3D nodes, this method will be implemented automatically.
The NodeReferenceTable object is passed to the updateNodeReferences method
and allows references from the old subgraph to be translated into references in
the cloned subgraph. The translation is performed by the getNew-
NodeReference method.

public final SceneGraphObject

getNewObjectReference(SceneGraphObject oldReference)

This method takes a reference to the node in the original subgraph as an input
parameter and returns a reference to the equivalent node in the just-cloned sub-
graph. If the equivalent node in the cloned subgraph does not exist, either an
exception is thrown or a reference to the original node is returned (see
Section 7.2.3, “Dangling References”).

7.2.3 Dangling References

Because cloneTree is able to start the cloning operation from any node, there is
a potential for creating dangling references. A dangling reference can occur only
when a leaf node that contains a reference to another scene graph node is cloned.
If the referenced node is not cloned, a dangling reference situation exists: There
are now two leaf nodes that access the same node (Figure 7-5). A dangling refer-
ence is discovered when a leaf node’s updateNodeReferences method calls the
getNewNodeReference method and the cloned subgraph does not contain a
counterpart to the node being looked up.

112 The Java 3D API Specification

REUSING SCENE GRAPHS Subclassing Nodes 7.2.4

G
cloneTree

Lf

Figure 7-5 Dangling Reference: Bold Nodes Are Being Cloned

When a dangling reference is discovered, cloneTree can handle it in one of two

ways. If cloneTree is called without the allowDanglingReferences parameter
set to true, a dangling reference will result in a DanglingReferenceException
being thrown. The user can catch this exception if desired. If cloneTree is called
with the allowDanglingReferences parameter set to true, the update-
NodeReferences method will return a reference to the same object passed into
the getNewNodeReference method. This will result in the cloneTree operation
completing with dangling references, as in Figure 7-5.

7.2.4 Subclassing Nodes

All Java 3D predefined nodes (for example, Interpolators and LOD nodes) auto-
matically handle all node reference and duplication operations. When a user sub-
classes a Leaf object or a NodeComponent object, certain methods must be
provided in order to ensure the proper operation of cloneTree.
Leaf node subclasses (for example, Behaviors) that contain any user node-spe-
cific data that needs to be duplicated during a cloneTree operation must define
the following two methods:

Node cloneNode(boolean forceDuplicate);

void duplicateNode(Node n, boolean forceDuplicate)

The cloneNode method consists of three lines:

Version 1.2, March 2000 113

7.2.5 NodeReferenceTable Object REUSING SCENE GRAPHS

UserSubClass usc = new UserSubClass();

usc.duplicateNode(this, forceDuplicate);
return usc;

The duplicateNode method must first call super.duplicateNode before dupli-

cating any necessary user-specific data or setting any user-specific state.
NodeComponent subclasses that contain any user node-specific data must define
the following two methods:

NodeComponent cloneNodeComponent();
void duplicateNodeComponent(NodeComponent nc,
boolean forceDuplicate); New in 1.2

The cloneNodeComponent method consists of three lines:

UserNodeComponent unc = new UserNodeComponent();

unc.duplicateNodeComponent(this, forceDuplicate);
return un;

The duplicateNodeComponent must first call super.duplicateNodeComponent

and then can duplicate any user-specific data or set any user-specific state as nec-
essary.

7.2.5 NodeReferenceTable Object

The NodeReferenceTable object is used by a leaf node’s updateNodeReferences
method called by the cloneTree operation. The NodeReferenceTable maps
nodes from the original subgraph to the new nodes in the cloned subgraph. This
information can than be used to update any cloned leaf node references to refer-
ence nodes in the cloned subgraph. This object can only be created by Java 3D.

Constructors

public NodeReferenceTable() New in 1.2

Constructs an empty NodeReferenceTable.

114 The Java 3D API Specification

REUSING SCENE GRAPHS Example User Behavior Node 7.2.6

Methods

public SceneGraphObject getNewObjectReference(SceneGraphObject

oldReference)

This method takes a reference to the node in the original subgraph as an input
parameter and returns a reference to the equivalent node in the just-cloned sub-
graph. If the equivalent node in the cloned subgraph does not exist, either an
exception is thrown or a reference to the original node is returned (see
Section 7.2.3, “Dangling References”).

7.2.6 Example User Behavior Node

The following is an example of a user-defined Behavior object to show how to
properly define a node to be compatible with the cloneTree operation.

class RotationBehavior extends Behavior {

TransformGroup objectTransform;
WakeupOnElapsedFrames w;

Matrix4d rotMat = new Matrix4d();

Matrix4d objectMat = new Matrix4d();
Transform3D t = new Transform3D();

// Override Behavior's initialize method to set up wakeup

// criteria
public void initialize() {
// Establish initial wakeup criteria
wakeupOn(w);
}

// Override Behavior's stimulus method to handle the event

public void processStimulus(Enumeration criteria) {
// Rotate by another PI/120.0 radians
objectMat.mul(objectMat, rotMat);
t.set(objectMat);
objectTransform.setTransform(t);

// Set wakeup criteria for next time

wakeupOn(w);
}

// Constructor for rotation behavior.

public RotationBehavior(TransformGroup tg, int numFrames) {
w = new WakeupOnElapsedFrames(numFrames);
objectTransform = tg;
objectMat.setIdentity();

Version 1.2, March 2000 115

7.2.6 Example User Behavior Node REUSING SCENE GRAPHS

// Create a rotation matrix that rotates PI/120.0

// radians per frame
rotMat.rotX(Math.PI/120.0);

// Note: When this object is duplicated via cloneTree,

// the cloned RotationBehavior node needs to point to
// the TransformGroup in the just-cloned tree.
}

// Sets a new TransformGroup.

public void setTransformGroup(TransformGroup tg) {
objectTransform = tg;
}

// The next two methods are needed for cloneTree to operate

// correctly.
// cloneNode is needed to provide a new instance of the user
// derived subclass.
public Node cloneNode(boolean forceDuplicate) {
// Get all data from current node needed for
// the constructor
int numFrames = w.getElapsedFrameCount();

RotationBehavior r =
new RotationBehavior(objectTransform, numFrames);
r.duplicateNode(this, forceDuplicate);
return r;
}
// duplicateNode is needed to duplicate all super class
// data as well as all user data.
public void duplicateNode(Node originalNode, boolean
forceDuplicate) {
super.duplicateNode(originalNode, forceDuplicate);
// Nothing to do here - all unique data was handled
// in the constructor in the cloneNode routine.
}

// duplicateNode is needed to duplicate all super class

// data as well as all user data.
public void duplicateNode(Node originalNode, boolean
forceDuplicate) {
super.duplicateNode(originalNode, forceDuplicate);
// Nothing to do here - all unique data was handled
// in the constructor in the cloneNode routine.
}

116 The Java 3D API Specification

REUSING SCENE GRAPHS Example User Behavior Node 7.2.6

// Callback for when this leaf is cloned. For this object

// we want to find the cloned TransformGroup node that this
// clone Leaf node should reference.
public void updateNodeReferences(NodeReferenceTable t) {
super.updateNodeReferences(t);

// Update node's TransformGroup to proper reference

TransformGroup newTg =
(TransformGroup)t.getNewObjectReference(
objectTransform);
setTransformGroup(newTg);
}
}

Version 1.2, March 2000 117

 C H A P T E R 8
Node Component Objects

N ODE component objects include the actual geometry and appearance

attributes used to render the geometry.

8.1 Node Component Objects: Attributes

Node objects by themselves do not fully specify their exact semantics. They con-
tain information that further refines their exact meaning. Some of that informa-
tion is specified as an attribute and an associated floating-point or integer value.
In many cases, however, the information consists of references to more complex
entities called node component objects. Node component objects encapsulate
related state information in a single entity. See Figure 8-1.

8.1.1 Alpha Object

The Alpha node component object provides common methods for converting a
time value into an alpha value (a value in the range 0.0 to 1.0). See Section 10.6,
“Interpolator Behaviors,” for a description of the Alpha object.

8.1.2 Appearance Object

The Appearance object is a component object of a Shape3D node that defines all
rendering state attributes for that shape node. If the Appearance object in a
Shape3D node is null, default values will be used for all rendering state
attributes.

Constants
The Appearance component object defines the following flags.

Version 1.2, March 2000 119

8.1.2 Appearance Object NODE COMPONENT OBJECTS

SceneGraphObject
NodeComponent
Alpha
Appearance
AuralAttributes
ColoringAttributes
LineAttributes
PointAttributes
PolygonAttributes
RenderingAttributes
TextureAttributes
TransparencyAttributes
Material
MediaContainer
TextureUnitState
TexCoordGeneration
Texture
Texture2D
Texture3D
ImageComponent
ImageComponent2D
ImageComponent3D
DepthComponent
DepthComponentFloat
DepthComponentInt
DepthComponentNative
Bounds
BoundingBox
BoundingPolytope
BoundingSphere
Transform3D

Figure 8-1 Attribute Component Object Hierarchy

public static final int ALLOW_MATERIAL_READ

public static final int ALLOW_MATERIAL_WRITE
public static final int ALLOW_TEXTURE_READ
public static final int ALLOW_TEXTURE_WRITE
public static final int ALLOW_TEXGEN_READ
public static final int ALLOW_TEXGEN_WRITE
public static final int ALLOW_TEXTURE_ATTRIBUTES_READ
public static final int ALLOW_TEXTURE_ATTRIBUTES_WRITE
public static final int ALLOW_COLORING_ATTRIBUTES_READ
public static final int ALLOW_COLORING_ATTRIBUTES_WRITE
public static final int ALLOW_TRANSPARENCY_ATTRIBUTES_READ
public static final int ALLOW_TRANSPARENCY_ATTRIBUTES_WRITE

120 The Java 3D API Specification

NODE COMPONENT OBJECTS Appearance Object 8.1.2

public static final int ALLOW_RENDERING_ATTRIBUTES_READ

public static final int ALLOW_RENDERING_ATTRIBUTES_WRITE
public static final int ALLOW_POLYGON_ATTRIBUTES_READ
public static final int ALLOW_POLYGON_ATTRIBUTES_WRITE
public static final int ALLOW_LINE_ATTRIBUTES_READ
public static final int ALLOW_LINE_ATTRIBUTES_WRITE
public static final int ALLOW_POINT_ATTRIBUTES_READ
public static final int ALLOW_POINT_ATTRIBUTES_WRITE
public static final int ALLOW_TEXTURE_UNIT_STATE_READ New in 1.2
public static final int ALLOW_TEXTURE_UNIT_STATE_WRITE New in 1.2

These flags, when enabled using the setCapability method, allow an applica-
tion to invoke methods that read and write the specified component object refer-
ence (material, texture, texture coordinate generation, and so forth). These
capability flags are enforced only when the object is part of a live or compiled
scene graph.

Constructors
The Appearance object has the following constructor.

public Appearance()

Constructs and initializes an Appearance object using defaults for all state vari-
ables. All component object references are initialized to null.

Methods
The Appearance object has the following methods.

public void setMaterial(Material material)

public Material getMaterial()

The Material object specifies the desired material properties used for lighting.
Setting it to null disables lighting.

public void setTexture(Texture texture)

public Texture getTexture()

The Texture object specifies the desired texture map and texture parameters. Set-
ting it to null disables texture mapping. Applications must not set individual
texture component objects (texture, textureAttributes, or texCoordGeneration)
and the texture unit state array in the same Appearance object. Doing so will
result in an exception being thrown.

Version 1.2, March 2000 121

8.1.2 Appearance Object NODE COMPONENT OBJECTS

public void setTextureAttributes(TextureAttributes

textureAttributes)
public TextureAttributes getTextureAttributes()

These methods set and retrieve the TextureAttributes object. Setting it to null
results in default attribute use. Applications must not set individual texture com-
ponent objects (texture, textureAttributes, or texCoordGeneration) and the tex-
ture unit state array in the same Appearance object. Doing so will result in an
exception being thrown.

public void setColoringAttributes(ColoringAttributes

coloringAttributes)
public ColoringAttributes getColoringAttributes()

These methods set and retrieve the ColoringAttributes object. Setting it to null
results in default attribute use.

public void setTransparencyAttributes(

TransparencyAttributes transparencyAttributes)
public TransparencyAttributes getTransparencyAttributes()

These methods set and retrieve the TransparencyAttributes object. Setting it to

null results in default attribute use.

public void setRenderingAttributes(RenderingAttributes

renderingAttributes)
public RenderingAttributes getRenderingAttributes()

These methods set and retrieve the RenderingAttributes object. Setting it to null
results in default attribute use.

public void setPolygonAttributes(PolygonAttributes

polygonAttributes)
public PolygonAttributes getPolygonAttributes()

These methods set and retrieve the PolygonAttributes object. Setting it to null
results in default attribute use.

public void setLineAttributes(LineAttributes lineAttributes)

public LineAttributes getLineAttributes()

These methods set and retrieve the LineAttributes object. Setting it to null
results in default attribute use.

public void setPointAttributes(PointAttributes pointAttributes)

public PointAttributes getPointAttributes()

122 The Java 3D API Specification

NODE COMPONENT OBJECTS ColoringAttributes Object 8.1.3

These methods set and retrieve the PointAttributes object. Setting it to null
results in default attribute use.

public void setTexCoordGeneration(TexCoordGeneration

texCoordGeneration)
public TexCoordGeneration getTexCoordGeneration()

These methods set and retrieve the TexCoordGeneration object. Setting it to null
disables texture coordinate generation.

public void setTextureUnitState(TextureUnitState[] stateArray) New in 1.2

public void setTextureUnitState(int index, TextureUnitState state) New in 1.2
public TextureUnitState[] getTextureUnitState() New in 1.2
public TextureUnitState getTextureUnitState(int index) New in 1.2

These methods set and retrieve the texture-unit state for this Appearance object
(see Section 8.1.15, “TextureUnitState Object”). The first method sets the texture
unit state array to the specified array. A shallow copy of the array of references
to the TextureUnitState objects is made. If the specified array is null or if the
length of the array is 0, multi-texture is disabled. Within the array, a null Texture-
UnitState element disables the corresponding texture unit. The second method
sets the texture unit state array object at the specified index within the texture
unit state array to the specified object. If the specified object is null, the corre-
sponding texture unit is disabled. The index must be within the range [0, stateAr-
ray.length–1]. Applications must not set individual texture component objects
(texture, textureAttributes, or texCoordGeneration) and the texture unit state
array in the same Appearance object. Doing so will result in an exception being
thrown.

public int getTextureUnitCount() New in 1.2

This method retrieves the length of the texture unit state array from this Appear-
ance object. The length of this array specifies the maximum number of texture
units that will be used by this appearance object. If the array is null, a count of 0
is returned.

8.1.3 ColoringAttributes Object

The ColoringAttributes object defines attributes that apply to color mapping.

Version 1.2, March 2000 123

8.1.3 ColoringAttributes Object NODE COMPONENT OBJECTS

Constants

public static final int ALLOW_COLOR_READ

public static final int ALLOW_COLOR_WRITE
public static final int ALLOW_SHADE_MODEL_READ
public static final int ALLOW_SHADE_MODEL_WRITE

These flags, when enabled using the setCapability method, allow an applica-
tion to invoke methods that respectively read and write its color component and
shade model component information.

Constructors

public ColoringAttributes()

Constructs a ColoringAttributes node with default parameters:

Parameter Default Value

color white (1,1,1)
shadeModel SHADE_GOURAUD

public ColoringAttributes(Color3f color, int shadeModel)

public ColoringAttributes(float red, float green, float blue,
int shadeModel)

These constructors create a ColoringAttributes object with the specified values.

Methods

public void setColor(Color3f color)

public void setColor(float r, float g, float b)
public void getColor(Color3f color)

These methods set and retrieve the intrinsic color of this ColoringAttributes com-
ponent object. This color is only used for unlit geometry. If lighting is enabled,
the material colors are used in the lighting equation to produce the final color.
When vertex colors are present in unlit geometry, those vertex colors are used in
place of this ColoringAttributes color unless the vertex colors are ignored.

public void setShadeModel(int shadeModel)

public int getShadeModel()

These methods set and retrieve the shade model for this ColoringAttributes com-
ponent object. The shade model is one of the following:
• FASTEST: Uses the fastest available method for shading.

124 The Java 3D API Specification

NODE COMPONENT OBJECTS LineAttributes Object 8.1.4

• NICEST: Uses the nicest (highest quality) available method for shading.
• SHADE_FLAT: Does not interpolate color across the primitive.
• SHADE_GOURAUD: Smoothly interpolates the color at each vertex
across the primitive.

8.1.4 LineAttributes Object

The LineAttributes object defines attributes that apply to line primitives.

Constants
The LineAttributes object specifies the following variables.

public static final int ALLOW_WIDTH_READ

public static final int ALLOW_WIDTH_WRITE
public static final int ALLOW_PATTERN_READ
public static final int ALLOW_PATTERN_WRITE
public static final int ALLOW_ANTIALIASING_READ
public static final int ALLOW_ANTIALIASING_WRITE

These flags, when enabled using the setCapability method, allow an applica-
tion to invoke methods that read and write its individual component field infor-
mation.

public static final int PATTERN_SOLID

Draws a solid line with no pattern.

public static final int PATTERN_DASH

Draws a dashed line. Ideally, this will be drawn with a repeating pattern of eight
pixels on and eight pixels off.

public static final int PATTERN_DOT

Draws a dotted line. Ideally, this will be drawn with a repeating pattern of one
pixel on and seven pixels off.

public static final int PATTERN_DASH_DOT

Draws a dashed-dotted line. Ideally, this will be drawn with a repeating pattern
of seven pixels on, four pixels off, one pixel on, and four pixels off.

Version 1.2, March 2000 125

8.1.4 LineAttributes Object NODE COMPONENT OBJECTS

public static final int PATTERN_USER_DEFINED New in 1.2

Draws lines with a user-defined line pattern. The line pattern is specified with a
pattern mask and a scale factor.

Constructors

public LineAttributes()

Constructs a LineAttributes object with default parameters:

Parameter Default Value

lineWidth 1
linePattern PATTERN_SOLID
lineAntialiasing false

public LineAttributes(float lineWidth, int linePattern,

boolean lineAntialiasing)

Constructs a LineAttributes object with specified values of line width, pattern,

and whether antialiasing is enabled or disabled.

Methods

public void setLineWidth(float lineWidth)

public float getLineWidth()

These methods respectively set and retrieve the line width, in pixels, for this Lin-
eAttributes component object.

public void setLinePattern(int linePattern)

public int getLinePattern()

These methods respectively set and retrieve the line pattern for this LineAt-
tributes component object. The linePattern value describes the line pattern to
be used, which is one of the following: PATTERN_SOLID, PATTERN_DASH,
PATTERN_DOT, or PATTERN_DASH_DOT.

public void setLineAntialiasingEnable(boolean state)

public boolean getLineAntialiasingEnable()

The set method enables or disables line antialiasing for this LineAttributes com-
ponent object. The get method retrieves the state of the line antialiasing flag.
The flag is true if line antialiasing is enabled, false if line antialiasing is dis-
abled.

126 The Java 3D API Specification

NODE COMPONENT OBJECTS PointAttributes Object 8.1.5

public void setPatternMask(int mask) New in 1.2

public int getPatternMask() New in 1.2

These methods respectively set and retrieve the line pattern mask. The line pat-
tern mask is used when the linePattern attribute is set to PATTERN_USER_
DEFINED.

In this mode, the pattern is specified using a 16-bit mask that specifies on and off
segments. Bit 0 in the pattern mask corresponds to the first pixel of the line or
line strip primitive. A value of 1 for a bit in the pattern mask indicates that the
corresponding pixel is drawn, while a value of 0 indicates that the corresponding
pixel is not drawn. After all 16 bits in the pattern are used, the pattern is
repeated. For example, a mask of 0x00ff defines a dashed line with a repeating
pattern of eight pixels on followed by eight pixels off. A value of 0x0101 defines
a dotted line with a repeating pattern of one pixel on and seven pixels off.
The pattern continues around individual line segments of a line strip primitive. It
is restarted at the beginning of each new line strip. For line array primitives, the
pattern is restarted at the beginning of each line.

public void setPatternScaleFactor(int scaleFactor) New in 1.2

public int getPatternScaleFactor() New in 1.2

These methods respectively set and retrieve the line pattern scale factor. The line
pattern scale factor is used in conjunction with the patternMask when the line-
Pattern attribute is set to PATTERN_USER_DEFINED. The pattern is multiplied by
the scale factor such that each bit in the pattern mask corresponds to that many
consecutive pixels. For example, a scale factor of 3 applied to a pattern mask of
0x001f would produce a repeating pattern of 15 pixels on followed by 33 pixels
off. The valid range for this attribute is [1,15]. Values outside this range are
clamped.

8.1.5 PointAttributes Object

The PointAttributes object defines attributes that apply to point primitives.

Constants
The PointAttributes object specifies the following variables.

public static final int ALLOW_SIZE_READ

public static final int ALLOW_SIZE_WRITE

Version 1.2, March 2000 127

8.1.6 PolygonAttributes Object NODE COMPONENT OBJECTS

public static final int ALLOW_ANTIALIASING_READ

public static final int ALLOW_ANTIALIASING_WRITE

These flags, when enabled using the setCapability method, allow an applica-
tion to invoke methods that read and write its individual component field infor-
mation.

Constructors

public PointAttributes()

Constructs a PointAttributes object with default parameters:

Parameter Default Value

pointSize 1
pointAntialiasing false

public PointAttributes(float pointSize,

boolean pointAntialiasing)

Constructs a PointAttributes object with specified values.

Methods

public void setPointSize(float pointSize)

public float getPointSize()

These methods set and retrieve the point size, in pixels, for this Appearance com-
ponent object.

public void setPointAntialiasingEnable(boolean state)

public boolean getPointAntialiasingEnable()

The set method enables or disables point antialiasing for this PointAttributes
component object. The get method retrieves the state of the point antialiasing
flag. The flag is true if point antialiasing is enabled, false if point antialiasing
is disabled.

8.1.6 PolygonAttributes Object

The PolygonAttributes object defines attributes for rendering polygon primitives.

Constants
The PolygonAttributes object specifies the following variables.

128 The Java 3D API Specification

NODE COMPONENT OBJECTS PolygonAttributes Object 8.1.6

public static final int ALLOW_CULL_FACE_READ

public static final int ALLOW_CULL_FACE_WRITE
public static final int ALLOW_MODE_READ
public static final int ALLOW_MODE_WRITE
public static final int ALLOW_OFFSET_READ
public static final int ALLOW_OFFSET_WRITE
public static final int ALLOW_NORMAL_FLIP_READ
public static final int ALLOW_NORMAL_FLIP_WRITE

These flags, when enabled using the setCapability method, allow an applica-
tion to invoke methods that read and write its individual component field infor-
mation.

Constructors

public PolygonAttributes()

Constructs a PolygonAttributes object with default parameters:

Parameter Default Value

cullFace CULL_BACK
backFaceNormalFlip false
polygonMode POLYGON_FILL
polygonOffset 0.0
polygonOffsetFactor 0.0

public PolygonAttributes(int polygonMode, int cullFace,

float polygonOffset)
public PolygonAttributes(int polygonMode, int cullFace,
float polygonOffset, boolean backFaceNormalFlip)
public PolygonAttributes(int polygonMode, int cullFace,
float polygonOffset, boolean backFaceNormalFlip,
float polygonOffsetFactor) New in 1.2

These constructors create a new PolygonAttributes object with the specified val-
ues.

Methods

public void setCullFace(int cullFace)

public int getCullFace()

These methods set and retrieve the face culling flag for this PolygonAttributes
component object. The face culling flag is one of the following:

Version 1.2, March 2000 129

8.1.7 RenderingAttributes Object NODE COMPONENT OBJECTS

• CULL_NONE: Performs no face culling.

• CULL_FRONT: Culls all front-facing polygons.
• CULL_BACK: Culls all back-facing polygons.

public void setBackFaceNormalFlip(boolean backFaceNormalFlip)

public boolean getBackFaceNormalFlip()

These methods set and retrieve the back-face normal flip flag. This flag indicates
whether vertex normals of back-facing polygons should be flipped (negated)
prior to lighting. When this flag is set to true and back-face culling is disabled,
polygons are rendered as if the polygon had two sides with opposing normals.
This feature is disabled by default.

public void setPolygonMode(int polygonMode)

public int getPolygonMode()

These methods set and retrieve the polygon rasterization mode for this Appear-
ance component object. The polygon rasterization mode is one of the following:
• POLYGON_POINT: Renders polygonal primitives as points drawn at the
vertices of the polygon.
• POLYGON_LINE: Renders polygonal primitives as lines drawn between
consecutive vertices of the polygon.
• POLYGON_FILL: Renders polygonal primitives by filling the interior of
the polygon.

public void setPolygonOffset(float polygonOffset)

public float getPolygonOffset()

These methods set and retrieve the constant polygon offset. This screen-space
offset is added to the final, device-coordinate Z value of polygon primitives.

public void setPolygonOffsetFactor(float polygonOffsetFactor) New in 1.2

public float getPolygonOffsetFactor() New in 1.2

These methods set and retrieve the the polygon offset factor. This factor is multi-
plied by the slope of the polygon and then added to the final device coordinate Z
value of polygon primitives.

8.1.7 RenderingAttributes Object

The RenderingAttributes object defines common rendering attributes for all
primitive types.

130 The Java 3D API Specification

NODE COMPONENT OBJECTS RenderingAttributes Object 8.1.7

Constants

public static final int ALLOW_ALPHA_TEST_VALUE_READ

public static final int ALLOW_ALPHA_TEST_VALUE_WRITE
public static final int ALLOW_ALPHA_TEST_FUNCTION_READ
public static final int ALLOW_ALPHA_TEST_FUNCTION_WRITE
public static final int ALLOW_DEPTH_ENABLE_READ
public static final int ALLOW_VISIBLE_READ New in 1.2
public static final int ALLOW_VISIBLE_WRITE New in 1.2
public static final int ALLOW_IGNORE_VERTEX_COLORS_READ New in 1.2
public static final int ALLOW_IGNORE_VERTEX_COLORS_WRITE New in 1.2
public static final int ALLOW_RASTER_OP_READ New in 1.2
public static final int ALLOW_RASTER_OP_WRITE New in 1.2

These flags, when enabled using the setCapability method, allow an applica-
tion to invoke methods that respectively read and write its individual test value
and function information.

Constructors

public RenderingAttributes()

Constructs a RenderingAttributes object with default parameters:

Parameter Default Value

depthBufferEnable true
depthBufferWriteEnable true
alphaTestFunction ALWAYS
alphaTestValue 0.0
visible true
ignoreVertexColors false
rasterOpEnable false
rasterOp ROP_COPY

public RenderingAttributes(boolean depthBufferEnable,

boolean depthBufferWriteEnable, float alphaTestValue,
int alphaTestFunction)
public RenderingAttributes(boolean depthBufferEnable,
boolean depthBufferWriteEnable, float alphaTestValue,
int alphaTestFunction, boolean visible,
boolean ignoreVertexColors, boolean rasterOpEnable,
int rasterOp) New in 1.2

Constructs a RenderingAttributes object with specified values.

Version 1.2, March 2000 131

8.1.7 RenderingAttributes Object NODE COMPONENT OBJECTS

Methods

public void setDepthBufferEnable(boolean state)

public boolean getDepthBufferEnable()

These methods set and retrieve the depth buffer enable flag for this RenderingAt-
tributes component object. The flag is true if the depth buffer mode is enabled,
false if disabled.

public void setDepthBufferWriteEnable(boolean state)

public boolean getDepthBufferWriteEnable()

These methods set and retrieve the depth buffer write enable flag for this Render-
ingAttributes component object. The flag is true if the depth buffer mode is
writable, false if the depth buffer is read-only.

public void setAlphaTestValue(float value)

public float getAlphaTestValue()

These methods set and retrieve the alpha test value used by the alpha test func-
tion. This value is compared to the alpha value of each rendered pixel.

public void setAlphaTestFunction(int function)

public int getAlphaTestFunction()

These methods set and retrieve the alpha test function. The alpha test function is
one of the following:
• ALWAYS: Indicates pixels are always drawn irrespective of the alpha val-
ue. This effectively disables alpha testing.
• NEVER: Indicates pixels are never drawn irrespective of the alpha value.
• EQUAL: Indicates pixels are drawn if the pixel alpha value is equal to the
alpha test value.
• NOT_EQUAL: Indicates pixels are drawn if the pixel alpha value is not
equal to the alpha test value.
• LESS: Indicates pixels are drawn if the pixel alpha value is less than the
alpha test value.
• LESS_OR_EQUAL: Indicates pixels are drawn if the pixel alpha value is
less than or equal to the alpha test value.
• GREATER: Indicates pixels are drawn if the pixel alpha value is greater
than the alpha test value.
• GREATER_OR_EQUAL: Indicates pixels are drawn if the pixel alpha val-
ue is greater than or equal to the alpha test value.
132 The Java 3D API Specification
NODE COMPONENT OBJECTS TextureAttributes Object 8.1.8

public void setVisible(boolean visible) New in 1.2

public boolean getVisible() New in 1.2

These methods set and retrieve the visibility flag for this RenderingAttributes
component object. Invisible objects are not rendered (subject to the visibility pol-
icy for the current view), but they can be picked or collided with.

public void setIgnoreVertexColors(boolean ignoreVertexColors) New in 1.2

public boolean getIgnoreVertexColors() New in 1.2

These methods set and retrieve the flag that indicates whether vertex colors are
ignored for this RenderingAttributes object. If ignoreVertexColors is false,
per-vertex colors are used, when present in the associated Geometry objects, tak-
ing precedence over the ColoringAttributes color and Material diffuse color. If
ignoreVertexColors is true, per-vertex colors are ignored. In this case, if light-
ing is enabled, the Material diffuse color will be used as the object color. If light-
ing is disabled, the ColoringAttributes color will be used. The default value is
false.

public void setRasterOpEnable(boolean rasterOpEnable) New in 1.2

public boolean getRasterOpEnable() New in 1.2

These methods set and retrieve the rasterOp enable flag for this RenderingAt-
tributes component object. When set to true, this enables logical raster operations
as specified by the setRasterOp method. Enabling raster operations effectively
disables alpha blending, which is used for transparency and antialiasing. Raster
operations, especially XOR mode, are primarily useful when rendering to the
front buffer in immediate mode. Most applications will not wish to enable this
mode.

public void setRasterOp(int rasterOp) New in 1.2

public int getRasterOp() New in 1.2

These methods set and retrieve the raster operation function for this Renderin-
gAttributes component object. The rasterOp is one of the following:
• ROP_COPY: DST = SRC
• ROP_XOR: DST = SRC ^ DST

8.1.8 TextureAttributes Object

The TextureAttributes object defines attributes that apply to texture mapping.

Version 1.2, March 2000 133

8.1.8 TextureAttributes Object NODE COMPONENT OBJECTS

Constants

public static final int ALLOW_MODE_READ

public static final int ALLOW_MODE_WRITE
public static final int ALLOW_BLEND_COLOR_READ
public static final int ALLOW_BLEND_COLOR_WRITE
public static final int ALLOW_TRANSFORM_READ
public static final int ALLOW_TRANSFORM_WRITE
public static final int ALLOW_COLOR_TABLE_READ New in 1.2
public static final int ALLOW_COLOR_TABLE_WRITE New in 1.2

These flags, when enabled using the setCapability method, allow an applica-
tion to invoke methods that respectively read and write its individual component
field information.

Constructors

public TextureAttributes()

Constructs a TextureAttributes object with default parameters:

Parameter Default Value

textureMode REPLACE
blendColor black (0,0,0,0)
transform identity
perspCorrectionMode NICEST
textureColorTable null

public TextureAttributes(int textureMode, Transform3D transform,

Color4f textureBlendColor, int perspCorrectionMode)

These constructors create a new TextureAttributes object with the specified

parameters.

Methods

public void setTextureMode(int textureMode)

public int getTextureMode()

These methods set and retrieve the texture mode parameter for this Texture-
Attributes component object. The texture mode is one of the following:
• MODULATE: Modulates the object color with the texture color.
• DECAL: Applies the texture color to the object as a decal.

134 The Java 3D API Specification

NODE COMPONENT OBJECTS TextureAttributes Object 8.1.8

• BLEND: Blends the texture blend color with the object color.
• REPLACE: Replaces the object color with the texture color.

public void setTextureBlendColor(Color4f textureBlendColor)

public void setTextureBlendColor(float r, float g, float b,
float a)
public void getTextureBlendColor(Color4f textureBlendColor)

These methods set and retrieve the texture blend color for this TextureAttributes
component object. The texture blend color is used when the texture mode param-
eter is BLEND.

public void setTextureColorTable(int[][] table) New in 1.2

This method sets the texture color table from the specified table. The individual
integer array elements are copied. The array is indexed first by color component
(r, g, b, and a, respectively) and then by color value; table.length defines the
number of color components and table[0].length defines the texture color
table size. If the table is non-null, the number of color components must either be
three, for rgb data, or four, for rgba data. The size of each array for each color
component must be the same and must be a power of 2. If table is null or if the
texture color table size is 0, the texture color table is disabled. If the texture color
table size is greater than the device-dependent maximum texture color table size
for a particular Canvas3D, the texture color table is ignored for that canvas.
When enabled, the texture color table is applied after the texture filtering opera-
tion and before texture application. Each of the r, g, b, and a components are
clamped to the range [0,1], multiplied by textureColorTableSize–1, and
rounded to the nearest integer. The resulting value for each component is then
used as an index into the respective table for that component. If the texture color
table contains three components, alpha is passed through unmodified.
public void getTextureColorTable(int[][] table) New in 1.2

This method retrieves the texture color table and copies it into the specified array.
If the current texture color table is null, no values are copied. The array must be
allocated by the caller and must be large enough to hold the entire table (that is,
int[numTextureColorTableComponents][textureColorTableSize]).

public int getNumTextureColorTableComponents() New in 1.2

This method retrieves the number of color components in the current texture
color table. A value of 0 is returned if the texture color table is null.

Version 1.2, March 2000 135

8.1.9 TransparencyAttributes Object NODE COMPONENT OBJECTS

public int getTextureColorTableSize() New in 1.2

This method retrieves the size of the current texture color table. A value of 0 is
returned if the texture color table is null.

public void setTextureTransform(Transform3D transform)

public void getTextureTransform(Transform3D transform)

These methods set and retrieve the texture transform object used to transform
texture coordinates. A copy of the specified Transform3D object is stored in this
TextureAttributes object.

public void setPerspectiveCorrectionMode(int mode)

public int getPerspectiveCorrectionMode()

These methods set and retrieve the perspective correction mode to be used for
color and texture coordinate interpolation. The perspective correction mode is
one of the following:
• NICEST: Uses the nicest (highest quality) available method for texture
mapping perspective correction.
• FASTEST: Uses the fastest available method for texture mapping perspec-
tive correction.

8.1.9 TransparencyAttributes Object

The TransparencyAttributes object defines all attributes affecting the transpar-
ency of the object.

Constants

public static final int ALLOW_MODE_READ

public static final int ALLOW_MODE_WRITE
public static final int ALLOW_VALUE_READ
public static final int ALLOW_VALUE_WRITE
public static final int ALLOW_BLEND_FUNCTION_READ New in 1.2
public static final int ALLOW_BLEND_FUNCTION_WRITE New in 1.2

These flags, when enabled using the setCapability method, allow an applica-
tion to invoke methods that respectively read and write its individual component
field information.

136 The Java 3D API Specification

NODE COMPONENT OBJECTS TransparencyAttributes Object 8.1.9

Constructors

public TransparencyAttributes()

Constructs a new TransparencyAttributes object with default values:

Parameter Default Value

transparencyMode NONE
transparencyValue 0.0
srcBlendFunction BLEND_SRC_ALPHA
dstBlendFunction BLEND_ONE_MINUS_SRC_ALPHA

public TransparencyAttributes(int tMode, float tVal)

public TransparencyAttributes(int tMode, float tVal,
int srcBlendFunction, int dstBlendFunction) New in 1.2

Constructs a new TransparencyAttributes object with specified values.

Methods

public void setTransparencyMode(int transparencyMode)

public int getTransparencyMode()

These methods set and retrieve the transparency mode for this Appearance com-
ponent object. The transparency mode is one of the following:
• FASTEST: Uses the fastest available method for transparency.
• NICEST: Uses the nicest available method for transparency.
• SCREEN_DOOR: Uses screen-door transparency. This is done using an
on/off stipple pattern in which the percentage of transparent pixels is ap-
proximately equal to the value specified by the transparency parameter.
• BLENDED: Uses alpha blended transparency. The blend equation is spec-
ified by the srcBlendFunction and dstBlendFunction attributes. The
default equation is: alpha*src + (1-alpha)*dst, where alpha is 1 –
transparency.
• NONE: No transparency; opaque object.

public void setTransparency(float transparency)

public float getTransparency()

These methods set and retrieve this Appearance object’s transparency value. The
transparency value is in the range [0.0, 1.0], with 0.0 being fully opaque and 1.0
being fully transparent.

Version 1.2, March 2000 137

8.1.10 Material Object NODE COMPONENT OBJECTS

public void setSrcBlendFunction(int blendFunction) New in 1.2

public int getSrcBlendFunction() New in 1.2

These methods set and retrieve the source blend function used in blended trans-
parency and antialiasing operations. The source function specifies the factor that
is multiplied by the source color. This value is added to the product of the desti-
nation factor and the destination color. The default source blend function is
BLEND_SRC_ALPHA. The source blend function is one of the following:

• BLEND_ZERO: The blend function is f = 0.

• BLEND_ONE: The blend function is f = 1.
• BLEND_SRC_ALPHA: The blend function is f = alphasrc.
• BLEND_ONE_MINUS_SRC_ALPHA: The blend function is f = 1 –
alphasrc.

public void setDstBlendFunction(int blendFunction) New in 1.2

public int getDstBlendFunction() New in 1.2

These methods set and retrieve the destination blend function used in blended
transparency and antialiasing operations. The destination function specifies the
factor that is multiplied by the destination color. This value is added to the prod-
uct of the source factor and the source color. The default destination blend func-
tion is BLEND_ONE_MINUS_SRC_ALPHA.

8.1.10 Material Object

The Material object is a component object of an Appearance object that defines
the material properties used when lighting is enabled. If the Material object in an
Appearance object is null, lighting is disabled for all nodes that use that
Appearance object.

Constants
The Material object defines two flags.

public static final int ALLOW_COMPONENT_READ

public static final int ALLOW_COMPONENT_WRITE

These flags, when enabled using the setCapability method, allow an applica-
tion to invoke methods that respectively read and write its individual component
field information.

138 The Java 3D API Specification

NODE COMPONENT OBJECTS Material Object 8.1.10

Constructors
The Material object has the following constructors.

public Material()

Constructs and initializes a Material object using default values for all attributes.
The default values are as follows:

Parameter Default Value

lightingEnable true
ambientColor (0.2, 0.2, 0.2)
emissiveColor (0.0, 0.0, 0.0)
diffuseColor (1.0, 1.0, 1.0)
specularColor (1.0, 1.0, 1.0)
shininess 64

public Material(Color3f ambientColor, Color3f emissiveColor,

Color3f diffuseColor, Color3f specularColor, float shininess)

Constructs and initializes a new Material object using the specified parameters.
The ambient color, emissive color, diffuse color, specular color, and shininess
parameters are specified.

Methods
The Material object has the following methods.

public void setAmbientColor(Color3f color)

public void setAmbientColor(float r, float g, float b)
public void getAmbientColor(Color3f color)

This parameter specifies this material’s ambient color, that is, how much ambient
light is reflected by the material’s surface.

public void setEmissiveColor(Color3f color)

public void setEmissiveColor(float r, float g, float b)
public void getEmissiveColor(Color3f color)

This parameter specifies the color of light, if any, that the material emits. This
color is added to the color produced by applying the lighting equation.

Version 1.2, March 2000 139

8.1.11 Texture Object NODE COMPONENT OBJECTS

public void setDiffuseColor(Color3f color)

public void setDiffuseColor(float r, float g, float b)
public void setDiffuseColor(float r, float g, float b, float a)
public void getDiffuseColor(Color3f color)

This parameter specifies the color of the material when illuminated by a light
source. In addition to the diffuse color (red, green, and blue), the alpha value is
used to specify transparency such that transparency = (1 – alpha). When vertex
colors are present in geometry that is being lit, those vertex colors are used in
place of this diffuse color in the lighting equation unless the vertex colors are
ignored.

public void setSpecularColor(Color3f color)

public void setSpecularColor(float r, float g, float b)
public void getSpecularColor(Color3f color)

This parameter specifies the specular highlight color of the material.

public void setShininess(float shininess)

public float getShininess()

This parameter specifies a material specular scattering exponent, or shininess. It

takes a floating-point number in the range [1.0, 128.0], with 1.0 being not shiny
and 128.0 being very shiny.

public void setLightingEnable(boolean state)

public boolean getLightingEnable()

These methods set and retrieve the current state of the lighting enable flag (true
or false) for this Appearance component object.

public String toString()

This method returns a string representation of this Material’s values. If the scene
graph is live, only those values with their capability bit set will be displayed.

8.1.11 Texture Object

The Texture object is a component object of an Appearance object that defines
the texture properties used when texture mapping is enabled. If the Texture
object in an Appearance object is null, then texture mapping is disabled for all
nodes that use that Appearance object. The Texture object is an abstract class. As
such, all texture objects must be created as either a Texture2D object or a
Texture3D object.

140 The Java 3D API Specification

NODE COMPONENT OBJECTS Texture Object 8.1.11

Constants
The Texture object defines the following flags:

public static final int ALLOW_ENABLE_READ

public static final int ALLOW_ENABLE_WRITE
public static final int ALLOW_BOUNDARY_MODE_READ
public static final int ALLOW_FILTER_READ
public static final int ALLOW_IMAGE_READ
public static final int ALLOW_IMAGE_WRITE New in 1.2
public static final int ALLOW_MIPMAP_MODE_READ
public static final int ALLOW_BOUNDARY_COLOR_READ
public static final int ALLOW_FORMAT_READ New in 1.2
public static final int ALLOW_SIZE_READ New in 1.2

These flags, when enabled using the setCapability method, allow an applica-
tion to invoke methods that read, and in some cases write, its individual compo-
nent field information. The size information includes width, height, and number
of mipmap levels.

Constructors
The Texture object has the following constructor.

public Texture()

This constructor is not very useful as the default width and height are 0. The
other default values are as follows:

Parameter Default Value

enableFlag true
width 0
height 0
mipmapMode BASE_LEVEL
format RGB
boundaryMode S WRAP
boundaryMode T WRAP
minificationFilter BASE_LEVEL_POINT
magnificationFilter BASE_LEVEL_POINT
boundaryColor black (0,0,0,0)
array of images null

Version 1.2, March 2000 141

8.1.11 Texture Object NODE COMPONENT OBJECTS

public Texture(int mipMapMode, int format, int width, int height)

Constructs an empty Texture object with specified mipmapMode format, width,

and height. Defaults are used for all other parameters. If mipMapMode is set to
BASE_LEVEL, the image at level 0 must be set by the application using the setI-
mage method or the setImages method. If mipMapMode is set to MULTI_LEVEL_
MIPMAP, then images for all levels must be set. The mipmapMode can be one of the
following:
• BASE_LEVEL: Indicates that this Texture object only has a base-level
image. If multiple levels are needed, they will be implicitly computed.
• MULTI_LEVEL_MIPMAP: Indicates that this Texture object has multi-
ple images—one for each mipmap level (that is,
log2(max(width,height)) + 1 separate images). If mipmapMode is set to
MULTI_LEVEL_MIPMAP, images for all levels must be set.

The format is the data of textures saved in this object. The format can be one of
the following:
• INTENSITY: Specifies Texture contains only intensity values.
• LUMINANCE: Specifies Texture contains only luminance values.
• ALPHA: Specifies Texture contains only alpha values.
• LUMINANCE_ALPHA: Specifies Texture contains luminance and alpha
values.
• RGB: Specifies Texture contains red, green, and blue color values.
• RGBA: Specifies Texture contains red, green, and blue color values, and
an alpha value.

Methods
The Texture object has the following methods.

public void setBoundaryModeS(int boundaryModeS)

public int getBoundaryModeS()
public void setBoundaryModeT(int boundaryModeT)
public int getBoundaryModeT()

These parameters specify the boundary mode for the S and T coordinates in this
Texture object. The boundary mode is as follows:
• CLAMP: Clamps texture coordinates to be in the range [0, 1]. A constant
boundary color is used for U,V values that fall outside this range.

142 The Java 3D API Specification

NODE COMPONENT OBJECTS Texture Object 8.1.11

• WRAP: Repeats the texture by wrapping texture coordinates that are out-
side the range [0, 1]. Only the fractional portion of the texture coordinates
is used; the integer portion is discarded.

public void setMinFilter(int minFilter)

public int getMinFilter()

This parameter specifies the minification filter function. This function is used
when the pixel being rendered maps to an area greater than one texel. The mini-
fication filter is one of the following:
• FASTEST: Uses the fastest available method for processing geometry.
• NICEST: Uses the nicest available method for processing geometry.
• BASE_LEVEL_POINT: Selects the nearest texel in the level 0 texture
map.
• BASE_LEVEL_LINEAR: Performs a bilinear interpolation on the four
nearest texels in the level 0 texture map.
• MULTI_LEVEL_POINT: Selects the nearest texel in the nearest mipmap.
• MULTI_LEVEL_LINEAR: Performs trilinear interpolation of texels be-
tween four texels each from the two nearest mipmap levels.

public void setMagFilter(int magFilter)

public int getMagFilter()

This parameter specifies the magnification filter function. This function is used
when the pixel being rendered maps to an area less than or equal to one texel.
The value is one of the following:
• FASTEST: Uses the fastest available method for processing geometry.
• NICEST: Uses the nicest available method for processing geometry.
• BASE_LEVEL_POINT: Selects the nearest texel in the level 0 texture
map.
• BASE_LEVEL_LINEAR: Performs a bilinear interpolation on the four
nearest texels in the level 0 texture map.

public void setImage(int level, ImageComponent image)

public ImageComponent getImage(int level)

These methods set and retrieve the image for a specified mipmap level. Level 0
is the base level.

Version 1.2, March 2000 143

8.1.11 Texture Object NODE COMPONENT OBJECTS

public void setImages(ImageComponent[] images) New in 1.2

public ImageComponent[] getImages() New in 1.2

These methods set and retrieve the array of images for all mipmap levels.

public void setBoundaryColor(Color4f boundaryColor)

public void setBoundaryColor(float r, float g, float b, float a)
public void getBoundaryColor(Color4f boundaryColor)

This parameter specifies the texture boundary color for this Texture object. The
texture boundary color is used when boundaryModeS or boundaryModeT is set to
CLAMP. The magnification filter affects the boundary color as follows: For BASE_
LEVEL_POINT, the boundary color is ignored since the filter size is 1 and the
border is unused. For BASE_LEVEL_LINEAR, the boundary color is used.

public void setEnable(boolean state)

public boolean getEnable()

These methods set and retrieve the state of texture mapping for this Texture
object. A value of true means that texture mapping is enabled, false means that
texture mapping is disabled.
public void setMipMapMode(int mipMapMode)
public int getMipMapMode()

These methods set and retrieve the mipmap mode for texture mapping for this
Texture object. The mipmap mode is either BASE_LEVEL or MULTI_LEVEL_MIP_
MAP.

public int numMipMapLevels() New in 1.2

This method retrieves the number of mipmap levels needed for this Texture
object.

public int getFormat() New in 1.2

This method retrieves the format of this Texture object.

public int getWidth() New in 1.2

This method retrieves the width of this Texture object.

public int getHeight() New in 1.2

This method retrieves the height of this Texture object.

144 The Java 3D API Specification

NODE COMPONENT OBJECTS Texture3D Object 8.1.13

8.1.12 Texture2D Object

The Texture2D object is a subclass of the Texture class. It extends the Texture
class by adding a constructor for setting a 2D texture image.

Constructors
The Texture2D object has the following constructors.

public Texture2D()

This constructor is not very useful as the default width and height are 0.
public Texture2D(int mipmapMode, int format, int width, int height)

Constructs and initializes a Texture2D object with the specified attributes. The
mipmapMode parameter is either BASE_LEVEL or MULTI_LEVEL_MIPMAP. The for-
mat parameter is one of the following: INTENSITY, LUMINANCE, ALPHA, LUMI-
NANCE_ALPHA, RGB, or RGBA.

8.1.13 Texture3D Object

The Texture3D object is a subclass of the Texture class. It extends the Texture
class by adding a third texture coordinate and by adding a constructor for setting
a 3D texture image. If 3D texture mapping is not supported on a particular
Canvas3D, 3D texture mapping is ignored for that canvas.

Constructors
The Texture3D object has the following constructors.

public Texture3D()

Constructs a Texture3D object with default parameters.

Parameter Default Value

depth 0
boundaryModeR WRAP

public Texture3D(int mipmapMode, int format, int width, int height,

int depth)

Constructs and initializes a Texture3D object using the specified attributes. The
mipmapMode parameter is either BASE_LEVEL or MULTI_LEVEL_MIPMAP. The for-
mat parameter is one of INTENSITY, LUMINANCE, ALPHA, LUMINANCE_ALPHA, RGB,
or RGBA. The default value for a Texture3D object is as follows:

Version 1.2, March 2000 145

8.1.14 TexCoordGeneration Object NODE COMPONENT OBJECTS

Parameter Default Value

boundaryModeR WRAP

Methods
The Texture3D object has the following methods.

public void setBoundaryModeR(int boundaryModeR)

public int getBoundaryModeR()

This parameter specifies the boundary mode for the R coordinate in this Texture
object. The boundary mode is as follows:
• CLAMP: Clamps texture coordinates to be in the range [0, 1]. A constant
boundary color is used for R values that fall outside this range.
• WRAP: Repeats the texture by wrapping texture coordinates that are out-
side the range [0, 1]. Only the fractional portion of the texture coordinates
is used; the integer portion is discarded.

public int getDepth() New in 1.2

This method retrieves the depth of this Texture3D object.

8.1.14 TexCoordGeneration Object

The TexCoordGeneration object is a component object of an Appearance object
that defines the parameters used when texture coordinate generation is enabled. If
the TexCoordGeneration object in an Appearance object is null, texture coordi-
nate generation is disabled for all nodes that use that Appearance object.

Constants
The TexCoordGeneration object specifies the following variables.

public static final int ALLOW_ENABLE_READ

public static final int ALLOW_ENABLE_WRITE
public static final int ALLOW_FORMAT_READ
public static final int ALLOW_MODE_READ
public static final int ALLOW_PLANE_READ

These flags, when enabled using the setCapability method, allow an applica-
tion to invoke methods that read, and in some cases write, its individual compo-
nent field information.

146 The Java 3D API Specification

NODE COMPONENT OBJECTS TexCoordGeneration Object 8.1.14

public static final int OBJECT_LINEAR

Generates texture coordinates as a linear function in object coordinates.

public static final int EYE_LINEAR

Generates texture coordinates as a linear function in eye coordinates.

public static final int SPHERE_MAP

Generates texture coordinates using a spherical reflection mapping in eye coordi-

nates.

public static final int TEXTURE_COORDINATE_2

Generates 2D texture coordinates (S and T).

public static final int TEXTURE_COORDINATE_3

Generates 3D texture coordinates (S, T, and R).

Constructors
The TexCoordGeneration object has the following constructors.

public TexCoordGeneration()

Constructs a TexCoordGeneration object with default parameters:

Parameter Default Value

enableFlag true
textureGenerationMode OBJECT_LINEAR
format TEXTURE_COORDINATE_2
planeS (1,0,0,0)
planeT (0,1,0,0)
planeR (0,0,0,0)

public TexCoordGeneration(int genMode, int format)

public TexCoordGeneration(int genMode, int format,
Vector4f planeS)
public TexCoordGeneration(int genMode, int format,
Vector4f planeS, Vector4f planeT)
public TexCoordGeneration(int genMode, int format,
Vector4f planeS, Vector4f planeT, Vector4f planeR)

These constructors construct a TexCoordGeneration object by initializing the

Version 1.2, March 2000 147

8.1.14 TexCoordGeneration Object NODE COMPONENT OBJECTS

specified fields. Default values are used for those state variables not specified in
the constructor. The parameters are as follows:
• genMode: Texture generation mode. One of OBJECT_LINEAR, EYE_LINEAR,
or SPHERE_MAP.
• format: Texture format (2D or 3D). Either TEXTURE_COORDINATE_2 or
TEXTURE_COORDINATE_3.
• planeS: Plane equation for the S coordinate.
• planeT: Plane equation for the T coordinate.
• planeR: Plane equation for the R coordinate.

Methods
The TexCoordGeneration object has the following methods.

public void setEnable(boolean state)

public boolean getEnable()

This parameter enables or disables texture coordinate generation for this Appear-
ance component object. The value is true if texture coordinate generation is
enabled, false if texture coordinate generation is disabled.

public void setFormat(int format)

public int getFormat()

This parameter specifies the format, or dimension, of the generated texture coor-
dinates. The format value is either TEXTURE_COORDINATE_2 or TEXTURE_COORD-
INATE_3.

public void setGenMode(int genMode)

public int getGenMode()

This parameter specifies the texture coordinate generation mode. The value is
one of OBJECT_LINEAR, EYE_LINEAR, or SPHERE_MAP.

public void setPlaneS(Vector4f planeS)

public void getPlaneS(Vector4f planeS)

This parameter specifies the S coordinate plane equation. This plane equation is
used to generate the S coordinate in OBJECT_LINEAR and EYE_LINEAR texture
generation modes.

148 The Java 3D API Specification

NODE COMPONENT OBJECTS TextureUnitState Object 8.1.15

public void setPlaneT(Vector4f planeT)

public void getPlaneT(Vector4f planeT)

This parameter specifies the T coordinate plane equation. This plane equation is
used to generate the T coordinate in OBJECT_LINEAR and EYE_LINEAR texture
generation modes.

public void setPlaneR(Vector4f planeR)

public void getPlaneR(Vector4f planeR)

This parameter specifies the R coordinate plane equation. This plane equation is
used to generate the R coordinate in OBJECT_LINEAR and EYE_LINEAR texture
generation modes.

8.1.15 TextureUnitState Object New in 1.2

The TextureUnitState object defines all texture mapping state for a single texture
unit. An Appearance object contains an array of texture unit state objects to
define the state for multiple texture mapping units. The texture unit state consists
of the following:
• Texture – defines the texture image and filtering parameters used when tex-
ture mapping is enabled. These attributes are defined in a Texture object.
• Texture attributes – defines the attributes that apply to texture mapping,
such as the texture mode, texture transform, blend color, and perspective
correction mode. These attributes are defined in a TextureAttributes object.
• Texture coordinate generation – defines the attributes that apply to texture
coordinate generation, such as whether texture coordinate generation is en-
abled, coordinate format (2D or 3D coordinates), coordinate generation
mode (object linear, eye linear, or spherical reflection mapping), and the R,
S, and T coordinate plane equations. These attributes are defined in a Tex-
CoordGeneration object.

Constants
The TextureUnitState object has the following flags.

public static final int ALLOW_STATE_READ New in 1.2

public static final int ALLOW_STATE_WRITE New in 1.2

These flags, when enabled using the setCapability method, allow an applica-
tion to invoke methods that read or write this object’s texture, texture attribute, or
texture coordinate generation component information.

Version 1.2, March 2000 149

8.1.15 TextureUnitState Object NODE COMPONENT OBJECTS

Constructors
The TextureUnitState object has the following constructors.

public TextureUnitState() New in 1.2

public TextureUnitState(Texture texture,
TextureAttributes textureAttributes,
TexCoordGeneration texCoordGeneration) New in 1.2

Construct and initialize a TextureUnitState component object. The first construc-

tor uses defaults for all state variables. All component object references are ini-
tialized to null. The second constructor uses the specified component objects.

Methods
The TextureUnitState object has the following methods.

public void set(Texture texture,

TextureAttributes textureAttributes,
TexCoordGeneration texCoordGeneration) New in 1.2

This method sets the texture, texture attributes, and texture coordinate generation
components in this TextureUnitState object to the specified component objects.

public void setTexture(Texture texture) New in 1.2

public Texture getTexture() New in 1.2

These methods set and retrieve the texture object. Setting it to null disables tex-
ture mapping for the texture unit corresponding to this TextureUnitState object.

public void setTextureAttributes(TextureAttributes

textureAttributes) New in 1.2
public TextureAttributes getTextureAttributes() New in 1.2

These methods set and retrieve the textureAttributes object. Setting it to null will
result in default attribute usage for the texture unit corresponding to this Texture-
UnitState object.

public void setTexCoordGeneration(TexCoordGeneration

texCoordGeneration) New in 1.2
public TexCoordGeneration getTexCoordGeneration() New in 1.2

These methods set and retrieve the texCoordGeneration object. Setting it to null
disables texture coordinate generation for the texture unit corresponding to this
TextureUnitState object.

150 The Java 3D API Specification

NODE COMPONENT OBJECTS MediaContainer Object 8.1.16

8.1.16 MediaContainer Object

The MediaContainer object defines all sound data: cached state flag and associ-
ated sound media. Currently, this references the sound media in one of three
forms: URL string, URL object, or InputStream object. In a future release of
Java 3D, media data will include references to Java Media Player objects.
Only one type of sound media data specified using setURLString, setURLOb-
ject, or setInputStream may be non-null (or they may all be null). An attempt
to set more than one of these attributes to a non-null reference will result in an
exception being thrown. If all sound media data references are null, there is no
sound associated with this MediaContainer and Sound nodes referencing this
object cannot be played.

Constants
The MediaContainer object has the following flags.

public static final int ALLOW_CACHE_READ

public static final int ALLOW_CACHE_WRITE
public static final int ALLOW_URL_READ
public static final int ALLOW_URL_WRITE

These flags, when enabled using the setCapability method, allow an applica-
tion to invoke methods that read or write its cached flag and its URL string.

Constructors
The MediaContainer object has the following constructors.

public MediaContainer()

Constructs and initializes a new MediaContainer object using the following

default values.

Parameter Default Value

URL string data null
URL object data null
input stream data null
cache enable true

public MediaContainer(String path)

public MediaContainer(URL url)
public MediaContainer(InputStream stream) New in 1.2

Version 1.2, March 2000 151

8.1.17 AuralAttributes Object NODE COMPONENT OBJECTS

Constructs and initializes a new MediaContainer object using the specified

parameters.

Methods
The Sound object has the following methods.

public void setCacheEnable(boolean flag)

public boolean getCacheEnable()

This parameter specifies whether this component contains a noncached reference

to the sound data or explicit cached sound data.

public void setURL(String path)

public void setURL(URL url)
public String getURL()

These methods are deprecated in Java 3D version 1.2. Use the setURLString,
setURLObject, and getURLString methods instead.

public void setURLString(String path) New in 1.2

public String getURLString() New in 1.2

These methods set and retrieve the string of URL containing the sound data.
public void setURLObject(URL url) New in 1.2
public URL getURLObject() New in 1.2

These methods set and retrieve the URL containing the sound data.

public void setInputStream(InputStream stream) New in 1.2

public InputStream getInputStream() New in 1.2

These methods set and retrieve the input stream object containing the sound data.

8.1.17 AuralAttributes Object

The AuralAttributes object is a component object of a Soundscape node that
defines environmental audio parameters that affect sound rendering. These
attributes include gain scale factor, atmospheric rolloff, and parameters control-
ling reverberation, distance frequency filtering, and velocity-activated Doppler
effect.

8.1.17.1 Attribute Gain Rolloff

The rolloff scale factor is used to model atmospheric changes from the normal
speed of sound. The base value, 0.344 meters per millisecond used to approxi-
152 The Java 3D API Specification
NODE COMPONENT OBJECTS AuralAttributes Object 8.1.17

mate the speed of sound through air at room temperature, is multiplied by this
scale factor whenever the speed of sound is applied during spatialization calcula-
tions. Valid values are ≥ 0.0. Values > 1.0 increase the speed of sound, while val-
ues < 1.0 decrease its speed. A value of zero makes the sound silent (but the
sound continues to play).

8.1.17.2 Reverberation
Within Java 3D’s simple model for auralization, there are three components to
sound reverberation for a particular listening space:
• Delay time: Approximates the time from the start of a sound until it
reaches the listener after reflecting once off the surfaces in the region.
• Reflection coefficient: Attenuates the reverberated sound uniformly (for
all frequencies) as it bounces off surfaces.
• Feedback loop: Controls the maximum number of times a sound is
reflected off the surfaces.
None of these parameters are affected by sound position. Figure 8-2 shows the
interaction of these parameters.

1.0
Amplitude

Reflection
Coeff

Time
Effective zero
Reverberation (late reflections)
(Early) reflections
Direct signal
Reverb delay

Decay time

Figure 8-2 Sound Reverberation Parameters

The reflection coefficient for reverberation is a single scale factor used to approx-
imate the overall reflective or absorptive characteristics of the surfaces in a rever-
beration region in which the listener is located. This scale factor is applied to the
sound’s amplitude regardless of the sound’s position. A value of 1.0 represents

Version 1.2, March 2000 153

8.1.17 AuralAttributes Object NODE COMPONENT OBJECTS

complete (unattenuated) sound reflection, while a value of 0.0 represents full

absorption (reverberation is disabled).
The reverberation delay time is set either explicitly (in milliseconds), or implic-
itly by supplying an additional bounds volume (so the delay time can be calcu-
lated). The bounds of the reverberation space do not have to be the same as the
application region of the Soundscape node using this object.
The reverberation order defines the number of reverberation (feedback) loop iter-
ations to be executed while a sound is played. As long as the reflection coeffi-
cient is small enough, the reverberated sound decreases (as it would naturally)
each successive iteration. A value of 0 disables reverberation, a value of 1 creates
a single echo (given that the reverb delay is long enough), and a value of –1 sig-
nifies that reverberation is to loop until it reaches an amplitude of effective zero
(>60 dB or 1/1000 of sound amplitude). All other positive values are used as the
number of loop iterations.

8.1.17.3 Doppler Effect

Doppler effect can be used to create a greater sense of movement of sound
sources and can help unambiguate front-to-back localization errors. The fre-
quency of sound waves emanating from the source are raised or lowered based
on the speed of the source in relation to the listener, and several AuralAt-
tributes parameters.

The frequency scale factor can be used to increase or reduce the change of fre-
quency associated with the normal Doppler calculation, or to shift the pitch of
the sound directly if Doppler-effect is disabled. Values must be > 0.0 for sounds
to be heard. If the value is 0.0, sounds affected by this AuralAttributes object
are paused.
To simulate Doppler effect, the relative velocity (change in distance in the local
coordinate system between the sound source and the listener over time, in meters
per second) is calculated. This calculated velocity is multiplied by the given
velocity scale factor. Values must be ≥ 0.0. If the scale factor value is 0.0, Dop-
pler effect is not calculated or applied to the sound.

Constants
The AuralAttributes object has the following flags.

public static final int ALLOW_ATTRIBUTE_GAIN_READ

public static final int ALLOW_ATTRIBUTE_GAIN_WRITE
public static final int ALLOW_ROLLOFF_READ

154 The Java 3D API Specification

NODE COMPONENT OBJECTS AuralAttributes Object 8.1.17

public static final int ALLOW_ROLLOFF_WRITE

public static final int ALLOW_REFLECTION_COEFFICIENT_READ
public static final int ALLOW_REFLECTION_COEFFICIENT_WRITE
public static final int ALLOW_REVERB_DELAY_READ
public static final int ALLOW_REVERB_DELAY_WRITE
public static final int ALLOW_REVERB_ORDER_READ
public static final int ALLOW_REVERB_ORDER_WRITE
public static final int ALLOW_DISTANCE_FILTER_READ
public static final int ALLOW_DISTANCE_FILTER_WRITE
public static final int ALLOW_FREQUENCY_SCALE_FACTOR_READ
public static final int ALLOW_FREQUENCY_SCALE_FACTOR_WRITE
public static final int ALLOW_VELOCITY_SCALE_FACTOR_READ
public static final int ALLOW_VELOCITY_SCALE_FACTOR_WRITE

These flags, when enabled using the setCapability method, allow an applica-
tion to invoke methods that read or write the associated parameters.

Constructors
The AuralAttributes object has the following constructors.

public AuralAttributes()

Constructs and initializes a new AuralAttributes object using the following

default values:

Parameter Default Value

attributeGain 1.0
rolloff 1.0
reflectionCoeff 0.0
reverbDelay 0.0
reverbBounds null
reverbOrder 0
distanceFilter null (no filtering performed)
frequencyScaleFactor 1.0
velocityScaleFactor 1.0

public AuralAttributes(float gain, float rolloff,

float reflectionCoefficient, float reverbDelay,
int reverbOrder, Point2f distanceFilter[],
float frequencyScaleFactor, float velocityScaleFactor)

Version 1.2, March 2000 155

8.1.17 AuralAttributes Object NODE COMPONENT OBJECTS

public AuralAttributes(float gain, float rolloff,

float reflectionCoefficient, float reverbDelay,
int reverbOrder, float distance[], float frequencyCutoff,
float frequencyScaleFactor, float velocityScaleFactor)

Construct and initialize a new AuralAttributes object using the specified parame-
ters.

Methods
The AuralAttributes object has the following methods.

public void setAttributeGain(float gain)

public float getAttributeGain()

This parameter specifies an amplitude scale factor applied to the sound. Valid
values are ≥ 0.0.

public void setRolloff(float rolloff)

public float getRolloff()

The rolloff scale factor is used to model atmospheric changes from the normal
speed of sound. The base value of 0.344 meters per millisecond is used to
approximate the speed factor whenever the speed of sound is applied during spa-
tialization calculations. Valid values are ≥ 0.0. Values > 1.0 increase the speed of
sound; a value of 0.0 makes the sound silent (but the sound continues to play).

public void setReflectionCoefficient(float coefficient)

public float getReflectionCoefficient()

This parameter specifies an average amplitude scale factor for all sound waves
(independent of their frequencies) as they reflect off all surfaces within the acti-
vation region in which the listener is located. There is currently no method to
assign different reflective audio properties to individual surfaces. The range of
values is 0.0 to 1.0. A value of 0.0 represents a fully absorptive surface (no sound
waves reflect off), while a value of 1.0 represents a fully reflective surface
(amplitudes of sound waves reflecting off surfaces are not decreased).

public void setReverbDelay(float reverbDelay)

public float getReverbDelay()

This parameter specifies the delay time between each order of reflection while
reverberation is being rendered. In the first form of setReverbDelay, an explicit
delay time is given in milliseconds. In the second form, a reverberation bounds
volume is specified, and then the delay time is calculated, becoming the new
reverb time delay. A value of 0.0 for delay time disables reverberation.

156 The Java 3D API Specification

NODE COMPONENT OBJECTS AuralAttributes Object 8.1.17

public void setReverbDelay(Bounds reverbVolume)

This method is deprecated in Java 3D 1.2. Use setReverbBounds(Bounds)

method instead.

public void setReverbBounds(Bounds reverbVolume) New in 1.2

public Bounds getReverbBounds() New in 1.2

These methods set and retrieve the reverberation bounds volume. In this form the
reverberation bounds volume parameter is used to calculate the reverb delay time
and the reverb decay. Specification of a non-null bounding volume causes the
explicit values given for reverb delay and decay to be overridden by the implicit
values calculated from these bounds.

public void setReverbOrder(int reverbOrder)

public int getReverbOrder()

This parameter specifies the maximum number of times reflections will be added
to the reverberation being calculated. When the amplitude of the n-th reflection
reaches effective zero, no further reverberations need be added to the sound
image. A value of 0 disables reverberation. A value of –1 specifies that the rever-
beration calculations will loop indefinitely, until the n-th reflection term reaches
effective zero.

public void setDistanceFilter(Point2f attenuation[])

public void setDistanceFilter(float distance[],
float frequencyCutoff[])
public int getDistanceFilterLength()
public void getDistanceFilter(Point2f attenuation[])
public void getDistanceFilter(float distance[],
float frequencyCutoff[])

This parameter specifies a (distance, filter) attenuation pairs array. If this is not
set, no distance filtering is performed (equivalent to using a distance filter of
Sound.NO_FILTER for all distances). Currently, this filter is a low-pass cutoff fre-
quency. This array of pairs defines a piecewise linear slope for a range of values.
This attenuation array is similar to the PointSound node’s distanceAttenuation
pair array, except that frequency values are paired with distances in this list.
Using these pairs, distance-based low-pass frequency filtering can be applied
during sound rendering. Distances, specified in the local coordinate system in
meters, must be > 0. Frequencies (in Hz) must be > 0.
If the distance from the listener to the sound source is less than the first distance
in the array, the first filter is applied to the sound source. This creates a spherical
region around the listener within which a sound is uniformly attenuated by the

Version 1.2, March 2000 157

8.1.17 AuralAttributes Object NODE COMPONENT OBJECTS

first filter in the array. If the distance from the listener to the sound source is
greater than the last distance in the array, the last filter is applied to the sound
source.
The first form of setDistanceFilter takes these pairs of values as an array of
Point2f. The second form accepts two separate arrays for these values. The dis-
tance and frequencyCutoff arrays should be of the same length. If the fre-
quencyCutoff array length is greater than the distance array length, the
frequencyCutoff array elements beyond the length of the distance array are
ignored. If the frequencyCutoff array is shorter than the distance array, the
last frequencyCutoff array value is repeated to fill an array of length equal to
the distance array.
The getDistanceFilterLength method returns the length of the distance filter
arrays. Arrays passed into getDistanceFilter methods should all be at least
this size.
There are two methods for getDistanceFilter, one returning an array of points,
the other returning separate arrays for each attenuation component.
Distance elements in this array of pairs are a monotonically increasing set of
floating-point numbers measured from the location of the sound source. Fre-
quency cutoff elements in this list of pairs can be any positive float. While for
most applications this list of values will usually be monotonically decreasing,
they do not have to be.

public void setFrequencyScaleFactor(float frequencyScaleFactor)

public float getFrequencyScaleFactor()

This parameter specifies a scale factor applied to the frequency of sound during
rendering playback. If the Doppler effect is disabled, this scale factor can be used
to increase or decrease the original pitch of the sound. During rendering, this
scale factor expands or contracts the usual frequency shift applied to the sound
source due to Doppler-effect calculations. Valid values are ≥ 0.0; a value of 0.0
pauses the sound.

public void setVelocityScaleFactor(float velocityScaleFactor)

public float getVelocityScaleFactor()

This parameter specifies a scale factor applied to the relative velocity of the
sound relative to the listener’s position and movement in relation to the sound’s
position and movement over time. This scale factor is multiplied by the calcu-
lated velocity portion of the Doppler-effect equation used during sound render-
ing. This allows the application to exaggerate or reduce the relative velocity

158 The Java 3D API Specification

NODE COMPONENT OBJECTS ImageComponent Object 8.1.18

calculated by the standard Doppler equation. Valid values are ≥ 0.0. A value of
0.0 disables any Doppler calculation.

8.1.18 ImageComponent Object

The ImageComponent classes are used for texture and background images. The
ImageComponent object is an abstract class that is used to define 2D or 3D
ImageComponent classes used in a Java 3D scene graph.
Image data may be passed to this ImageComponent object in one of two ways:
by copying the image data into this object or by accessing the image data by ref-
erence.
• By copying: By default, the set and get image methods copy the image
data into or out of this ImageComponent object. This is appropriate for
many applications since the application may reuse the RenderedImage ob-
ject after copying it to the ImageComponent,
• By reference: A new feature in Java 3D version 1.2 allows image data to
be accessed by reference, directly from the RenderedImage object. To use
this feature, you need to construct an ImageComponent object with the by-
Reference flag set to true. In this mode, a reference to the input data is
saved but the data itself is not necessarily copied (although it may be, de-
pending on the value of the yUp flag, the format of the ImageComponent,
and the format of the RenderedImage). Image data referenced by an Im-
ageComponent object must not be modified. Applications must exercise
care not to violate this rule. If any referenced RenderedImage is modified
after it has been passed to an ImageComponent object, the results are un-
defined. Another restriction in by-reference mode is that if the specified
RenderedImage is not an instance of BufferedImage, this ImageCompo-
nent cannot be used for readRaster or off-screen rendering operations,
since these operations modify the ImageComponent data.
An image component object also specifies whether the orientation of its image
data is “y-up” or “y-down” (the default). Y-up mode causes images to be inter-
preted as having their origin at the lower left (rather than the default upper left)
of a texture or raster image with successive scan lines moving up. This is more
consistent with texture mapping data onto a surface, and maps directly into the
way textures are used in OpenGL and other 3D APIs. Setting the yUp flag to true
in conjunction with setting the byReference flag to true makes it possible for
Java 3D to avoid copying the texture map in some cases.
Note that all color fields are treated as unsigned values, even though Java does
not directly support unsigned variables. This means, for example, that an Image-
Version 1.2, March 2000 159
8.1.18 ImageComponent Object NODE COMPONENT OBJECTS

Component using a format of FORMAT_RGB5 can represent red, green, and blue
values between 0 and 31, while an ImageComponent using a format of FORMAT_
RGB8 can represent color values between 0 and 255. Even when byte values are
used to create a RenderedImage with 8-bit color components, the resulting colors
(bytes) are interpreted as if they were unsigned. Values greater than 127 can be
assigned to a byte variable using a type cast. For example:
byteVariable = (byte) intValue;// intValue can be > 127

If intValue is greater than 127, byteVariable will be negative. The correct

value will be extracted when it is used (by masking off the upper bits).

Constants
The ImageComponent object has the following flags:

public static final int ALLOW_SIZE_READ

public static final int ALLOW_FORMAT_READ
public static final int ALLOW_IMAGE_READ

These flags, when enabled using the setCapability method, allow an applica-
tion to invoke methods that read the associated parameters.
The ImageComponent object specifies the following variables, used to define 2D
or 3D ImageComponent classes. These variables specify the format of the pixel
data.

public static final int FORMAT_RGB

Specifies that each pixel contains three eight-bit channels, one each for red,
green, and blue. This is the same as FORMAT_RGB8.

public static final int FORMAT_RGBA

Specifies that each pixel contains four eight-bit channels, one each for red, green,
blue, and alpha. This is the same as FORMAT_RGBA8.

public static final int FORMAT_RGB8

Specifies that each pixel contains three eight-bit channels, one each for red,
green, and blue. This is the same as FORMAT_RGB.

public static final int FORMAT_RGBA8

Specifies that each pixel contains four eight-bit channels, one each for red, green,
blue, and alpha. This is the same as FORMAT_RGBA.

160 The Java 3D API Specification

NODE COMPONENT OBJECTS ImageComponent Object 8.1.18

public static final int FORMAT_RGB5

Specifies that each pixel contains three five-bit channels, one each for red, green,
and blue.

public static final int FORMAT_RGB5_A1

Specifies that each pixel contains three five-bit channels, one each for red, green,
and blue, and a one-bit channel for alpha.

public static final int FORMAT_RGB4

Specifies that each pixel contains three four-bit channels, one each for red, green,
and blue.

public static final int FORMAT_RGBA4

Specifies that each pixel contains four four-bit channels, one each for red, green,
blue, and alpha.

public static final int FORMAT_LUM4_ALPHA4

Specifies that each pixel contains two four-bit channels, one each for luminance
and alpha.

public static final int FORMAT_LUM8_ALPHA8

Specifies that each pixel contains two eight-bit channels, one each for luminance
and alpha.

public static final int FORMAT_R3_G3_B2

Specifies that each pixel contains two three-bit channels, one each for red and
green, and a two-bit channel for blue.

public static final int FORMAT_CHANNEL8

Specifies that each pixel contains one eight-bit channel. The channel can be used
for only luminance, alpha, or intensity.

Constructors
The ImageComponent object defines the following constructor.

Version 1.2, March 2000 161

8.1.19 ImageComponent2D Object NODE COMPONENT OBJECTS

public ImageComponent(int format, int width, int height)

This constructor constructs and initializes a new ImageComponent object using

the specified format, width, and height. Default values are used for all other
parameters. The default values are as follows:

Parameter Default Value

byReference false
yUp false

public ImageComponent(int format, int width, int height,

boolean byReference, boolean yUp) New in 1.2

Constructs an image component object using the specified format, width, height,
byReference flag, and yUp flag.

Methods
The ImageComponent object defines the following methods.

public int getWidth()

public int getHeight()
public int getFormat()

These methods retrieve the width, height, and format of this image component
object.

public boolean isByReference() New in 1.2

This method retrieves the data access mode for this ImageComponent object.

public void setYUp(boolean yUp) New in 1.2

This method sets the y-orientation of this ImageComponent object to y-up or y-

down.

public boolean isYUp() New in 1.2

This method retrieves the y-orientation for this ImageComponent object.

8.1.19 ImageComponent2D Object

The ImageComponent2D class defines a 2D image component. This is used for
texture images, background images, and raster components of Shape3D nodes.
Prior to Java 3D 1.2, only BufferedImage objects could be used as the input to an
ImageComponent2D object. As of Java 3D 1.2, an ImageComponent2D accepts

162 The Java 3D API Specification

NODE COMPONENT OBJECTS ImageComponent2D Object 8.1.19

any RenderedImage object (BufferedImage is an implementation of the Ren-

deredImage interface). The methods that set/get a BufferedImage object are left
in for compatibility. The new methods that set/get a RenderedImage are a super-
set of the old methods. In particular, the two set methods in the following exam-
ple are equivalent:

BufferedImage bi;
RenderedImage ri = bi;
ImageComponent2D ic;

// Set the image to the specified BufferedImage

ic.set(bi);

// Set the image to the specified RenderedImage

ic.set(ri);

Constructors
The ImageComponent2D object defines the following constructors.

public ImageComponent2D(int format, int width, int height)

public ImageComponent2D(int format, BufferedImage image)
public ImageComponent2D(int format, RenderedImage image) New in 1.2

The first constructor constructs and initializes a 2D image component object

using the specified format, width, and height, and a null image. The second and
third constructors construct and initialize a 2D image component object using the
specified format and image. A copy of the image is made.

public ImageComponent2D(int format, int width, int height,

boolean byReference, boolean yUp) New in 1.2
public ImageComponent2D(int format, BufferedImage image,
boolean byReference, boolean yUp) New in 1.2
public ImageComponent2D(int format, int width, int height,
boolean byReference, boolean yUp) New in 1.2

The first constructor constructs a 2D image component object using the specified
format, width, height, byReference flag, and yUp flag, and a null image. The sec-
ond and third constructors construct a 2D image component object using the
specified format, image, byReference flag, and yUp flag.

Methods
The ImageComponent2D object defines the following methods.

Version 1.2, March 2000 163

8.1.20 ImageComponent3D Object NODE COMPONENT OBJECTS

public void set(BufferedImage image)

public void set(RenderedImage image) New in 1.2

These methods set the image in this ImageComponent2D object to the specified
BufferedImage or RenderedImage object. If the data access mode is not by-refer-
ence, the image data is copied into this object. If the data access mode is by-ref-
erence, a reference to the image is saved, but the data is not necessarily copied.

public BufferedImage getImage()

public RenderedImage getRenderedImage() New in 1.2

These methods retrieve the image from this ImageComponent2D object. If the
data access mode is not by-reference, a copy of the image is made. If the data
access mode is by-reference, the reference is returned.

8.1.20 ImageComponent3D Object

The ImageComponent3D class defines a 3D image component. This is used for
texture images. Prior to Java 3D 1.2, only BufferedImage objects could be used
as the input to an ImageComponent3D object. As of Java 3D 1.2, an Image-
Component3D accepts an array of arbitrary RenderedImage object (BufferedIm-
age is an implementation of the RenderedImage interface). The methods that set/
get a BufferedImage object are left in for compatibility. The new methods that
set/get a RenderedImage are a superset of the old methods. In particular, the two
set methods in the following example are equivalent:

BufferedImage bi;
RenderedImage ri = bi;
ImageComponent3D ic;

// Set image 0 to the specified BufferedImage

ic.set(0, bi);

// Set image 0 to the specified RenderedImage

ic.set(0, ri);

Constructors
The ImageComponent3D object defines the following constructors.

164 The Java 3D API Specification

NODE COMPONENT OBJECTS ImageComponent3D Object 8.1.20

public ImageComponent3D(int format, int width, int height,

int depth)

Constructs and initializes a 3D image component object using the specified for-
mat, width, height, and depth. Default values are used for all other parameters.
The default values are as follows:

Parameter Default Value

array of images null

public ImageComponent3D(int format, BufferedImage[] images)

public ImageComponent3D(int format, RenderedImage[] images) New in 1.2

These two constructors construct and initialize a 3D image component object

using the specified format and array of images. Default values are used for all
other parameters.

public ImageComponent3D(int format, int width, int height,

int depth, boolean byReference, boolean yUp) New in 1.2

This constructor constructs a 3D image component object using the specified for-
mat, width, height, depth, byReference flag, and yUp flag. Default values are
used for all other parameters.

public ImageComponent3D(int format, BufferedImage[] images,

boolean byReference, boolean yUp) New in 1.2
public ImageComponent3D(int format, RenderedImage[] images,
boolean byReference, boolean yUp) New in 1.2

These two constructors construct a 3D image component object using the speci-
fied format, BufferedImage or RenderedImage array, byReference flag, and yUp
flag. Default values are used for all other parameters.

Methods
The ImageComponent3D object defines the following methods.

public int getDepth()

This method retrieves the depth of this 3D image component object.

public void set(RenderedImage[] images) New in 1.2

public void set(BufferedImage[] images)

These methods set the array of images in this image component to the specified
array of RenderedImage or BufferedImage objects. If the data access mode is not
by-reference, the data is copied into this object. If the data access mode is by-ref-

Version 1.2, March 2000 165

8.1.21 DepthComponent Object NODE COMPONENT OBJECTS

erence, a shallow copy of the array of references to the objects is made, but the
data is not necessarily copied.

public RenderedImage[] getRenderedImage() New in 1.2

public RenderedImage getRenderedImage(int index) New in 1.2

These methods retrieve the images or image from this ImageComponent3D

object. If the data access mode is not by-reference, a copy of the images is made.
If the data access mode is by-reference, the references are returned.

public BufferedImage[] getImage()

public BufferedImage getImage(int index)

These methods retrieve a copy of the images in this ImageComponent3D object.

If the data access mode is not by-reference, a copy of the images is made. If the
data access mode is by-reference, the references are returned.

public void set(int index, RenderedImage image) New in 1.2

public void set(int index, BufferedImage image)

These methods set this image component at the specified index to the specified
RenderedImage or BufferedImage object. If the data access mode is not by-refer-
ence, the data is copied into this object. If the data access mode is by-reference,
a reference to the image is saved, but the data is not necessarily copied.

8.1.21 DepthComponent Object

The DepthComponent object is an abstract base class that defines a 2D array of
depth (Z) values.

Constants
The DepthComponent object has the following flags:

public static final int ALLOW_SIZE_READ

public static final int ALLOW_DATA_READ

These flags, when enabled using the setCapability method, allow an applica-
tion to invoke methods that read the associated parameters.

Methods

public int getWidth()

public int getHeight()

These methods get the width and height of this object.

166 The Java 3D API Specification

NODE COMPONENT OBJECTS DepthComponentInt Object 8.1.23

8.1.22 DepthComponentFloat Object

The DepthComponentFloat object extends the DepthComponent object and
defines a 2D array of depth (Z) values in floating-point format in the range [0, 1].
A value of 0.0 indicates the closest Z value to the user, while a value of 1.0 indi-
cates the farthest Z value.

Constructors
The DepthComponentFloat object defines the following constructors.

public DepthComponentFloat(int width, int height)

Constructs a new floating-point depth (Z-buffer) component object with the spec-
ified width and height.

Methods

public void setDepthData(float depthData[])

public void getDepthData(float depthData[])

These methods set and retrieve the specified depth data for this object.

8.1.23 DepthComponentInt Object

The DepthComponentInt object extends the DepthComponent object and defines
a 2D array of depth (Z) values in integer format. Values are in the range [0, (2n) –
1], where n is the Z-buffer pixel depth.

Constructors
The DepthComponentInt object defines the following constructor.

public DepthComponentInt(int width, int height)

Constructs a new integer depth (Z-buffer) component object with the specified
width and height.

Methods

public void setDepthData(int depthData[])

public void getDepthData(int depthData[])

These methods set and retrieve the specified depth data for this object.

Version 1.2, March 2000 167

8.1.24 DepthComponentNative Object NODE COMPONENT OBJECTS

8.1.24 DepthComponentNative Object

The DepthComponentNative object extends the DepthComponent object and
defines a 2D array of depth (Z) values stored in the most efficient format for a
particular device. Values are not accessible by the user and may only be used to
read the Z values and subsequently write them back.

Constructors
The DepthComponentNative object defines the following constructor.

public DepthComponentNative(int width, int height)

Constructs a new native depth (Z-buffer) component object with the specified
width and height.

8.1.25 Bounds Object

Bounds objects define three varieties of containing volumes. Java 3D uses these
containing volumes to support various culling operations. The types of bounds
include an axis-aligned-box volume, a spherical volume, and a bounding poly-
tope.

Constructors
The Bounds object defines the following constructor.

public Bounds()

Constructs a new Bounds object.

Methods
The Bounds object defines the following methods.

public abstract Object clone()

Clone this object.

public abstract void set(Bounds boundsObject)

This method sets the value of this Bounds object to enclose the specified bound-
ing object.

168 The Java 3D API Specification

NODE COMPONENT OBJECTS Bounds Object 8.1.25

public abstract boolean intersect(Point3d origin,

Point3d direction)
public abstract boolean intersect(Point3d point)
public abstract boolean intersect(Bounds boundsObject)
public abstract boolean intersect(Bounds boundsObjects[])

These methods test for the intersection of this Bounds object with a ray, a point,
another Bounds object, or an array of Bounds objects, respectively.

public abstract Bounds closestIntersection(Bounds boundsObjects[])

This method finds the closest bounding object that intersects this bounding
object.

public abstract void combine(Bounds boundsObject)

public abstract void combine(Bounds boundsObjects[])
public abstract void combine(Point3d point)
public abstract void combine(Point3d points[])

These methods combine this Bounds object with a bounding object, an array of
bounding objects, a point, or an array of points, respectively.

public abstract void transform(Bounds bounds, Transform3D trans)

public abstract void transform(Transform3D trans)

The first method tranforms a Bounds object so that it bounds a volume that is the
result of transforming the given bounding object by the given transform. The sec-
ond method transforms the Bounds object by the given transform.

public abstract boolean equals(Object bounds) New in 1.2

This method indicates whether the specified bounds object is equal to this
Bounds object. They are equal if both the specified bounds object and this
Bounds are instances of the same Bounds subclass and all of the data members
of bounds are equal to the corresponding data members in this Bounds.

public abstract int hashCode() New in 1.2

This method returns a hash code for this Bounds object based on the data values
in this object. Two different Bounds objects of the same type with identical data
values (i.e., Bounds.equals returns true) will return the same hash code. Two
Bounds objects with different data members may return the same hash code
value, although this is not likely.

Version 1.2, March 2000 169

8.1.26 BoundingBox Object NODE COMPONENT OBJECTS

public abstract boolean isEmpty()

This method tests whether the bounds is empty. A bounds is empty if it is null
(either by construction or as the result of a null intersection) or if its volume is
negative. A bounds with a volume of zero is not empty.

8.1.26 BoundingBox Object

BoundingBox objects are axis-aligned bounding box volumes.

Constructors
The BoundingBox object defines the following constructors.

public BoundingBox()
public BoundingBox(Point3d lower, Point3d upper)
public BoundingBox(Bounds boundsObject)
public BoundingBox(Bounds bounds[])

The first constructor constructs and initializes a 2X unity BoundingBox about the
origin. The second constructor constructs and initializes a BoundingBox from the
given minimum and maximum in x, y, and z. The third constructor constructs and
initializes a BoundingBox from a bounding object. The fourth constructor con-
structs and initializes a BoundingBox from an array of bounding objects.

Methods
The BoundingBox object defines the following methods.

public void getLower(Point3d p1)

public void setLower(Point3d p1)
public void setLower(double xmin, double ymin, double zmin)

This parameter specifies the lower corner of this bounding box.

public void getUpper(Point3d p1)

public void setUpper(Point3d p1)
public void setUpper(double xmax, double ymax, double zmax)

This parameter specifies the upper corner of this bounding box.

public void set(Bounds boundsObject)

Sets the value of this bounding region to enclose the specified bounding object.

170 The Java 3D API Specification

NODE COMPONENT OBJECTS BoundingBox Object 8.1.26

public Object clone()

Creates a copy of this bounding box.

public void combine(Bounds boundsObject)

public void combine(Bounds boundsObjects[])
public void combine(Point3d point)
public void combine(Point3d points[])

These methods combine this bounding box with a bounding object, an array of
bounding objects, a point, or an array of points, respectively.

public void transform(Bounds boundsObject, Transform3D matrix)

public void transform(Transform3D matrix)

The first method transforms a bounding box so that it bounds a volume that is the
result of transforming the given bounding object by the given transform. The sec-
ond method transforms the bounding box by the given transform.

public boolean intersect(Point3d origin, Vector3d direction)

public boolean intersect(Point3d point)
public boolean intersect(Bounds boundsObject)
public boolean intersect(Bounds boundsObjects[])

These methods test for the intersection of this bounding box with a ray, a point,
another Bounds object, and an array of Bounds objects, respectively.

public boolean intersect(Bounds boundsObject,

BoundingBox newBoundBox)
public boolean intersect(Bounds boundsObjects[],
BoundingBox newBoundBox)

These methods compute a new BoundingBox that bounds the volume created by
the intersection of this BoundingBox with another Bounds object or array of
Bounds objects.

public Bounds closestIntersection(Bounds boundsObjects[])

This method finds the closest bounding object that intersects this bounding box.

public boolean equals(Object bounds) New in 1.2

This method indicates whether the specified bounds object is equal to this
BoundingBox object. They are equal if the specified bounds object is an instance
of BoundingBox and all of the data members of bounds are equal to the corre-
sponding data members in this BoundingBox.

Version 1.2, March 2000 171

8.1.27 BoundingSphere Object NODE COMPONENT OBJECTS

public int hashCode() New in 1.2

This method returns a hash code value for this BoundingBox object based on the
data values in this object. Two different BoundingBox objects with identical data
values (i.e., BoundingBox.equals returns true) will return the same hash code
value. Two BoundingBox objects with different data members may return the
same hash code value, although this is not likely.

public boolean isEmpty()

This method tests whether the bounding box is empty. A bounding box is empty
if it is null (either by construction or as the result of a null intersection) or if its
volume is negative. A bounding box with a volume of zero is not empty.

8.1.27 BoundingSphere Object

The BoundingSphere object defines a spherical bounding volume. It has two
associated values: the center point and the radius of the sphere.

Constructors
The BoundingSphere object defines the following constructors.

public BoundingSphere()
public BoundingSphere(Point3D center, double radius)
public BoundingSphere(Bounds boundsObject)
public BoundingSphere(Bounds boundsObjects[])

The first constructor constructs and initializes a BoundingSphere to unity (radius

= 1.0 and center at 0.0, 0.0, 0.0). The second constructor constructs and initial-
izes a BoundingSphere from a center and radius. The third constructor constructs
and initializes a BoundingSphere from a bounding object. The fourth constructor
constructs and initializes a BoundingSphere from an array of bounding objects.

Methods
The BoundingSphere object defines the following methods.

public double getRadius()

public void setRadius(double r)

This parameter specifies the bounding sphere radius.

172 The Java 3D API Specification

NODE COMPONENT OBJECTS BoundingSphere Object 8.1.27

public void getCenter(Point3d center)

public void setCenter(Point3d center)

This parameter defines the position of the bounding sphere.

public void set(Bounds boundsObject)

Sets the value of this bounding sphere to enclose the volume specified by the
Bounds object.

public Object clone()

Creates a copy of the bounding sphere.

public void combine(Bounds boundsObject)

public void combine(Bounds boundsObjects[])
public void combine(Point3d point)
public void combine(Point3d points[])

These methods combine this bounding sphere with a bounding object, an array
of bounding objects, a point, or an array of points, respectively.

public boolean intersect(Point3d origin, Point3d direction)

public boolean intersect(Point3d point)
public boolean intersect(Bounds boundsObject)
public boolean intersect(Bounds boundsObjects[])

These methods test for the intersection of this bounding sphere with the given
ray, point, another Bounds object, or an array of Bounds objects.

public boolean intersect(Bounds boundsObject,

BoundingSphere newBoundSphere)
public boolean intersect(Bounds boundsObjects[],
BoundingSphere newBoundSphere)

These methods compute a new BoundingSphere that bounds the volume created
by the intersection of this BoundingSphere with another Bounds object or array
of Bounds objects.

public Bounds closestIntersection(Bounds boundsObjects[])

This method finds the closest bounding object that intersects this bounding
sphere.

public void transform(Bounds boundsObject, Transform3D matrix)

public void transform(Transform3D matrix)

The first method transforms a bounding sphere so that it bounds a volume that is

Version 1.2, March 2000 173

8.1.28 BoundingPolytope Object NODE COMPONENT OBJECTS

the result of transforming the given bounding object by the given transform. The
second method transforms the bounding sphere by the given transform. Note that
when transforming a bounding sphere by a transformation matrix containing a
nonuniform scale or a shear, the result is a bounding sphere with a radius equal
to the maximal scale in any direction—the bounding sphere does not transform
into an ellipsoid.

public boolean equals(Object bounds) New in 1.2

This method indicates whether the specified bounds object is equal to this
BoundingSphere object. They are equal if the specified bounds object is an
instance of BoundingSphere and all of the data members of bounds are equal to
the corresponding data members in this BoundingSphere.

public int hashCode() New in 1.2

This method returns a hash code value for this BoundingSphere object based on
the data values in this object. Two different BoundingSphere objects with identi-
cal data values (i.e., BoundingSphere.equals returns true) will return the same
hash code value. Two BoundingSphere objects with different data members may
return the same hash code value, although this is not likely.

public String toString()

This method returns a string representation of this class.

public boolean isEmpty()

This method tests whether the bounding sphere is empty. A bounding sphere is
empty if it is null (either by construction or as the result of a null intersection)
or if its volume is negative. A bounding sphere with a volume of zero is not
empty.

8.1.28 BoundingPolytope Object

A BoundingPolytope object defines a polyhedral bounding region using the inter-
section of three or more half spaces. The region defined by a BoundingPolytope
is always convex and must be closed.
Each plane in the BoundingPolytope specifies a half-space defined by the equa-
tion:
Ax + By + Cz + D ≤ 0
where A, B, C, D are the parameters that specify the plane.

174 The Java 3D API Specification

NODE COMPONENT OBJECTS BoundingPolytope Object 8.1.28

The parameters are passed in the x, y, z, and w fields, respectively, of a Vector4d

object. The intersection of the set of half-spaces corresponding to the planes in
this BoundingPolytope defines the bounding region.

Constructors
The BoundingPolytope object defines the following constructors.

public BoundingPolytope()

This constructor constructs and initializes a BoundingPolytope to a set of six

planes that define a cube, such that –1 ≤ x,y,z ≤ 1. The values of the planes are as
follows:

planes[0] x ≤ 1 (1,0,0,–1)
planes[1] –x ≤ 1 (–1,0,0,–1)
planes[2] y ≤ 1 (0,1,0,–1)
planes[3] –y ≤ 1 (0,–1,0,–1)
planes[4] z ≤ 1 (0,0,1,–1)
planes[5] –z ≤ 1 (0,0,–1,–1)

public BoundingPolytope(Vector4d planes[])

public BoundingPolytope(Bounds boundsObject)
public BoundingPolytope(Bounds boundsObjects[])

The first constructor constructs and initializes a BoundingPolytope from an array

of bounding planes. The second constructor constructs and initializes a Bound-
ingPolytope from a Bounds object. The new polytope will circumscribe the
region specified by the input bounds. The final constructor constructs and initial-
izes a BoundingPolytope from an array of Bounds objects. The new polytope
will circumscribe the union of the regions specified by the input bounds objects.

Methods
The BoundingPolytope object defines the following methods.

public void setPlanes(Vector4d planes[])

public void getPlanes(Vector4d planes[])

These methods set and retrieve the bounding planes for this BoundingPolytope
object.

Version 1.2, March 2000 175

8.1.28 BoundingPolytope Object NODE COMPONENT OBJECTS

public int getNumPlanes()

This method returns the number of bounding planes for this bounding polytope.

public void set(Bounds boundsObject)

This method sets the planes for this BoundingPolytope by keeping its current
number and direction of the planes and computing new plane positions to
enclose the given Bounds object.

public Object clone()

This method creates a copy of the BoundingPolytope object.

public void combine(Bounds boundsObject)

public void combine(Bounds boundsObjects[])
public void combine(Point3d point)
public void combine(Point3d points[])

These methods combine this BoundingPolytope with a bounding object, an array

of bounding objects, a point, or an array of points, respectively.

public void transform(Bounds bounds, Transform3D matrix)

public void transform(Transform3D matrix)

The first method tranforms a bounding polytope so that it bounds a volume that
is the result of transforming the given bounding object by the given transform.
The second method transforms the bounding polytope by the given transform.

public boolean intersect(Point3d origin, Vector3d direction)

public boolean intersect(Point3d point)
public boolean intersect(Bounds boundsObject)
public boolean intersect(Bounds boundsObjects[])

These methods test for the intersection of this BoundingPolytope with the given
ray, point, another Bounds object, or array of Bounds objects, respectively.

public boolean intersect(Bounds boundsObject,

BoundingPolytope newBoundPolytope)
public boolean intersect(Bounds boundsObjects[],
BoundingPolytope newBoundPolytope)

These methods compute a new BoundingPolytope that bounds the volume cre-
ated by the intersection of this BoundingPolytope with another Bounds object or
array of Bounds objects.

176 The Java 3D API Specification

NODE COMPONENT OBJECTS Transform3D Object 8.1.29

public Bounds closestIntersection(Bounds boundsObjects[])

This method finds the closest bounding object that intersects this bounding poly-
tope.

public boolean equals(Object bounds) New in 1.2

This method indicates whether the specified bounds object is equal to this
BoundingPolytope object. They are equal if the specified bounds object is an
instance of BoundingPolytope and all of the data members of bounds are equal
to the corresponding data members in this BoundingPolytope.

public int hashCode() New in 1.2

This method returns a hash code value for this BoundingPolytope object based
on the data values in this object. Two different BoundingPolytope objects with
identical data values (i.e., BoundingPolytope.equals returns true) will return
the same hash code value. Two BoundingPolytope objects with different data
members may return the same hash code value, although this is not likely.

public boolean isEmpty()

This method tests whether the bounding polytope is empty. A bounding polytope
is empty if it is null (either by construction or as the result of a null intersection)
or if its volume is negative. A bounding polytope with a volume of zero is not
empty.

8.1.29 Transform3D Object

Transformations are represented by matrix multiplication and include such oper-
ations as rotation, scaling, and translation. The Transform3D object is repre-
sented internally as a 4 × 4 double-precision floating point matrix. The
mathematical representation is row major, as in traditional matrix mathematics.

Constants

public static final int ZERO

public static final int IDENTITY
public static final int SCALE
public static final int TRANSLATION
public static final int ORTHOGONAL
public static final int RIGID
public static final int CONGRUENT

Version 1.2, March 2000 177

8.1.29 Transform3D Object NODE COMPONENT OBJECTS

public static final int AFFINE

public static final int NEGATIVE_DETERMINANT

A Transform3D has an associated type that is internally computed when the

transform object is constructed and updated any time it is modified. A matrix
will typically have multiple types. For example, the type associated with an iden-
tity matrix is the result of ORing all of the types, except for ZERO and NEGATIVE_
DETERMINANT, together. There are public methods available to get the ORed type
of the transformation, the sign of the determinant, and the least general matrix
type. The matrix type flags are defined as follows:
• ZERO: Zero matrix.
• IDENTITY: Identity matrix.
• SCALE: This matrix is a uniform scale matrix—there are no rotational or
translation components.
• TRANSLATION: This matrix has translation components only. The scale
is unity and there are no rotational components.
• ORTHOGONAL: The four row vectors that make up an orthogonal matrix
form a basis, meaning that they are mutually orthogonal. The scale is unity
and there are no translation components.
• RIGID: The upper 3 × 3 of the matrix is orthogonal, and there is a transla-
tion component—the scale is unity.
• CONGRUENT: This is an angle- and length-preserving matrix, meaning
that it can translate, rotate, and reflect about an axis, and scale by an
amount that is uniform in all directions. These operations preserve the dis-
tance between any two points, and the angle between any two intersecting
lines.
• AFFINE: An affine matrix can translate, rotate, reflect, scale anisotropical-
ly, and shear. Lines remain straight, and parallel lines remain parallel, but
the angle between intersecting lines can change.
A matrix is also classified by the sign of its determinant:
• NEGATIVE_DETERMINANT: This matrix has a negative determinant.
An orthogonal matrix with a positive determinant is a rotation matrix. An
orthogonal matrix with a negative determinant is a reflection and rotation
matrix.
The Java 3D model for 4 × 4 transformations is

178 The Java 3D API Specification

NODE COMPONENT OBJECTS Transform3D Object 8.1.29

m 00 m 01 m 02 m 03 x x′
m 10 m 11 m 12 m 13 ⋅ y = y ′
m 20 m 21 m 22 m 23 z z′
m 30 m 31 m 32 m 33 w w′

x′ = m 00 ⋅ x + m 01 ⋅ y + m 02 ⋅ z + m 03 ⋅ w
y′ = m 10 ⋅ x + m 11 ⋅ y + m 12 ⋅ z + m 13 ⋅ w
z′ = m 20 ⋅ x + m 21 ⋅ y + m 22 ⋅ z + m 23 ⋅ w
w′ = m 30 ⋅ x + m 31 ⋅ y + m 32 ⋅ z + m 33 ⋅ w

Note: When transforming a Point3f or a Point3d, the input w is set to 1. When

transforming a Vector3f or Vector3d, the input w is set to 0.

Constructors
The Transform3D object defines the following constructors.

public Transform3D()

This constructs and initializes a new Transform3D object to the identity transfor-
mation.

public Transform3D(Transform3D t1)

This constructs and initializes a new Transform3D object from the specified
transform.

public Transform3D(Matrix3f m1, Vector3d t1, double s)

public Transform3D(Matrix3d m1, Vector3d t1, double s)
public Transform3D(Matrix3f m1, Vector3f t1, float s)

These construct and initialize a new Transform3D object from the rotation
matrix, translation, and scale values. The scale is applied only to the rotational
component of the matrix (upper 3 × 3) and not to the translational components of
the matrix.

public Transform3D(Matrix4f m1)

public Transform3D(Matrix4d m1)

These construct and initialize a new Transform3D object from the 4 × 4 matrix.
The type of the constructed transform is classified automatically.

Version 1.2, March 2000 179

8.1.29 Transform3D Object NODE COMPONENT OBJECTS

public Transform3D(float matrix[])

public Transform3D(double matrix[])

These construct and initialize a new Transform3D object from the array of length
16. The top row of the matrix is initialized to the first four elements of the array,
and so on. The type of the constructed transform is classified automatically.

public Transform3D(Quat4d q1, Vector3d t1, double s)

public Transform3D(Quat4f q1, Vector3d t1, double s)
public Transform3D(Quat4f q1, Vector3f t1, float s)

These construct and initialize a new Transform3D object from the quaternion q1,
the translation t1, and the scale s. The scale is applied only to the rotational
components of the matrix (the upper 3 × 3) and not to the translational compo-
nents of the matrix.

public Transform3D(GMatrix m1)

This constructs and initializes a new Transform3D object and initializes it to the
upper 4 × 4 of the specified GMatrix. If the specified matrix is smaller than
4 × 4, the remaining elements in the transformation matrix are assigned to zero.

Methods
The Transform3D object defines the following methods.

public final int getType()

This method retrieves the type of this matrix. The type is an ORed bitmask of all
of the type classifications to which it belongs.

public final int getBestType()

This method retrieves the least general type of this matrix. The order of general-
ity from least to most is as follows: ZERO, IDENTITY, SCALE, TRANSLATION,
ORTHOGONAL, RIGID, CONGRUENT, and AFFINE. If the matrix is ORTHOGONAL, call-
ing the method getDeterminantSign will yield more information.

public final void setAutoNormalize(boolean autoNormalize)

public final boolean getAutoNormalize()

These methods set and retrieve the state of autonormalization. Autonormalization

performs an automatic singular value decomposition (SVD) normalization of the
rotational components (upper 3 × 3) of this matrix after every subsequent matrix
operation on this object, unless the boolean is subsequently set to false. The
default value for this parameter is false.

180 The Java 3D API Specification

NODE COMPONENT OBJECTS Transform3D Object 8.1.29

public final boolean getDeterminantSign()

This method returns the sign of the determinant of this matrix. A return value of
true indicates a positive determinant. A return value of false indicates a nega-
tive determinant. In general, an orthogonal matrix with a positive determinant is
a pure rotation matrix; an orthogonal matrix with a negative determinant is both
a rotation and a reflection matrix.

public final void setIdentity()

This method sets this transform to the identity matrix.

public final void setZero()

This method sets this transform to all zeros.

public final void setEuler(Vector3d euler)

This method sets the rotational component (upper 3 × 3) of this transform to the
rotation matrix converted from the Euler angles provided. The euler parameter
is a Vector3d consisting of three rotation angles applied first about the X, then
the Y, then the Z axis. These rotations are applied using a static frame of refer-
ence. In other words, the orientation of the Y rotation axis is not affected by the
X rotation and the orientation of the Z rotation axis is not affected by the X or Y
rotation.

public final void setRotation(Matrix3d m1)

public final void setRotation(Matrix3f m1)

These methods set the rotational component (upper 3 × 3) of this transform to the
values in the specified matrix; the other elements of this transform are
unchanged. A singular value decomposition is performed on this object’s upper
3 × 3 matrix to factor out the scale, then this object’s upper 3 × 3 matrix compo-
nents are replaced by the input rotational components, and finally the scale is
reapplied to the rotational components.

public final void setRotation(Quat4f q1)

public final void setRotation(Quat4d q1)

These methods set the rotational component (upper 3 × 3) of this transform to the
appropriate values derived from the specified quaternion; the other elements of
this transform are unchanged. A singular value decomposition is performed on
this object’s upper 3 × 3 matrix to factor out the scale, then this object’s upper
3 × 3 matrix components are replaced by the matrix equivalent of the quaternion,
and finally the scale is reapplied to the rotational components.

Version 1.2, March 2000 181

8.1.29 Transform3D Object NODE COMPONENT OBJECTS

public final void setRotation(AxisAngle4d a1)

public final void setRotation(AxisAngle4f a1)

These methods set the rotational component (upper 3 × 3) of this transform to the
appropriate values derived from the specified axis-angle; the other elements of
this transform are unchanged. A singular value decomposition is performed on
this object’s upper 3 × 3 matrix to factor out the scale, then this object's upper
3 × 3 matrix components are replaced by the matrix equivalent of the axis-angle,
and finally the scale is reapplied to the rotational components.

public final void setScale(double scale)

public final double getScale()

The set method sets the scale component of this transform by factoring out the
current scale from the rotational component and multiplying by the new scale.
The get method performs an SVD normalization of this transform to calculate
and return the scale factor; this transform is not modified. If the matrix has non-
uniform scale factors, the largest of the x, y, and z scale factors will be returned.

public final void setScale(Vector3d scale)

public final void getScale(Vector3d scale)

The set method sets the possibly non-uniform scale component to the current
transform. Any existing scale is first factored out of the existing transform before
the new scale is applied. The get method returns the possibly non-uniform scale
components of the current transform and places them into the scale vector.

public final void setNonUniformScale(double xScale, double yScale,

double zScale)

A deprecated method. Use setScale(Vector3d) instead. Note that the set-

Scale method only modifies the scale component.

public final void scaleAdd(double s, Transform3D t1,

Transform3D t2)
public final void scaleAdd(double s, Transform3D t1)

The first method scales transform t1 by a uniform scale matrix with scale factor
s, then adds transform t2 (this = S * t1 + t2). The second method scales this
transform by a uniform scale matrix with scale factor s, then adds transform t1
(this = S * this + t1).

public final void setRotationScale(Matrix3f m1)

public final void setRotationScale(Matrix3d m1)
public final void getRotationScale(Matrix3f m1)

182 The Java 3D API Specification

NODE COMPONENT OBJECTS Transform3D Object 8.1.29

public final void getRotationScale(Matrix3d m1)

The set methods replace the upper 3 × 3 matrix values of this transform with the
values in the matrix m1. The get methods retrieve the upper 3 × 3 matrix values
of this transform and place them in the matrix m1.

public String toString()

This method returns the matrix elements of this transform as a string.

public final void add(Transform3D t1)

public final void add(Transform3D t1, Transform3D t2)
public final void sub(Transform3D t1)
public final void sub(Transform3D t1, Transform3D t2)

The first add method adds this transform to the transform t1 and places the result
back into this. The second add method adds the transforms t1 and t2 and
places the result into this. The first sub method subtracts transform t1 from this
transform and places the result back into this. The second sub method subtracts
transform t2 from t1 and places the result into this.

public final void add(double scalar)

public final void add(double scalar, Transform3D t1)

The first method adds a scalar to each component of this transform. The second
method adds a scalar to each component of the transform t1 and places the result
into this. Transform t1 is not modified.

public final void transpose()

public final void transpose(Transform3D t1)

The first method transposes this matrix in place. The second method transposes
transform t1 and places the value into this transform. The transform t1 is not
modified.

public void rotX(double angle)

public void rotY(double angle)
public void rotZ(double angle)

These three methods set the value of this matrix to a rotation matrix about the
specified axis. The matrices rotate in a counter-clockwise (right-handed) direc-
tion. The angle to rotate is specified in radians.

Version 1.2, March 2000 183

8.1.29 Transform3D Object NODE COMPONENT OBJECTS

public final void setTranslation(Vector3f trans)

public final void setTranslation(Vector3d trans)

This method modifies the translational components of this transform to the val-
ues of the argument. The other values of this transform are not modified.

public final void set(Quat4f q1)

public final void set(Quat4d q1)

These methods set the value of this transform to the matrix conversion of the
quaternion argument.
public final void set(Quat4d q1, Vector3d t1, double s)
public final void set(Quat4f q1, Vector3d t1, double s)
public final void set(Quat4f q1, Vector3f t1, float s)

These methods set the value of this matrix from the rotation expressed by the
quaternion q1, the translation t1, and the scale s.

public final void set(Vector3d trans)

public final void set(Vector3f trans)

These methods set the translational value of this matrix to the specified vector
parameter values and set the other components of the matrix as if this transform
were an identity matrix.

public final void set(Vector3d v1, double scale)

public final void set(Vector3f v1, float scale)

These methods set the value of this transform to a scale and translation matrix;
the translation is scaled by the scale factor and all of the matrix values are mod-
ified.
public final void set(Transform3D t1)

This method sets the matrix, type, and state of this transform to the matrix, type,
and state of the transform t1.
public final void set(double matrix[])
public final void set(float matrix[])

These methods set the matrix values of this transform to the specified matrix val-
ues.

184 The Java 3D API Specification

NODE COMPONENT OBJECTS Transform3D Object 8.1.29

public final void set(double scale)

public final void set(double scale, Vector3d v1)
public final void set(float scale, Vector3f v1)

The first method sets the value of this transform to a uniform scale; all of the
matrix values are modified. The next two methods set the value of this transform
to a scale and translation matrix; the scale is not applied to the translation and all
of the matrix values are modified.
public final void set(Matrix4d m1)
public final void set(Matrix4f m1)

These methods set the matrix values of this transform to the matrix values in the
specified matrix.

public final void set(Matrix3f m1)

public final void set(Matrix3d m1)

These methods set the rotational and scale components (upper 3 × 3) of this
transform to the matrix values in the specified matrix. The remaining matrix val-
ues are set to the identity matrix. All values of the matrix are modified.

public final void set(Matrix3f m1, Vector3f t1, float s)

public final void set(Matrix3f m1, Vector3d t1, double s)
public final void set(Matrix3d m1, Vector3d t1, double s)

These methods set the value of this matrix from the rotation expressed by the
rotation matrix m1, the translation t1, and the scale s. The scale is only applied to
the rotational component of the matrix (upper 3 × 3) and not to the translational
component of the matrix.

public final void set(GMatrix matrix)

These methods set the matrix values of this transform to the matrix values in the
specified matrix. The GMatrix object must specify a 4 × 4, 3 × 4, or 3 × 3 matrix.

public final void set(AxisAngle4f a1)

public final void set(AxisAngle4d a1)

These methods set the rotational component (upper 3 × 3) of this transform to the
matrix conversion of the specified axis-angle argument. The remaining matrix
values are set to the identity matrix. All values of the matrix are modified.

Version 1.2, March 2000 185

8.1.29 Transform3D Object NODE COMPONENT OBJECTS

public final void get(double matrix[])

public final void get(float matrix[])

These methods place the values of this transform into the specified matrix of
length 16. The first four elements of the array will contain the top row of the
transform matrix, and so on.
public final void get(Matrix4d matrix)
public final void get(Matrix4f matrix)

These methods place the values of this transform into the matrix argument.
public final void get(Matrix3d m1)
public final void get(Matrix3f m1)

These methods place the normalized rotational component of this transform into
the 3 × 3 matrix argument.

public final double get(Matrix3d m1, Vector3d t1)

public final float get(Matrix3f m1, Vector3f t1)
public final double get(Matrix3f m1, Vector3d t1)

These methods place the normalized rotational component of this transform into
the m1 parameter and the translational component into the t1 parameter.

public final void get(Quat4d q1)

public final void get(Quat4f q1)

These methods perform an SVD normalization of this matrix to acquire the nor-
malized rotational component. The values are placed into the quaternion q1
parameter.

public final double get(Quat4d q1, Vector3d t1)

public final float get(Quat4f q1, Vector3f t1)
public final double get(Quat4f q1, Vector3d t1)

These methods perform an SVD normalization of this transform to calculate the

rotation as a quaternion, the translation, and the scale. None of the matrix values
are modified.

public final void get(Vector3d trans)

public final void get(Vector3f trans)

These methods retrieve the translational components of this transform.

186 The Java 3D API Specification

NODE COMPONENT OBJECTS Transform3D Object 8.1.29

public final void invert()

public final void invert(Transform3D t1)

The first method inverts this transform in place. The second method sets the
value of this transform to the inverse of the transform t1. Both of these methods
use the transform type to determine the optimal algorithm for inverting the trans-
form.

public final double determinant()

This method calculates and returns the determinant of this transform.

public final void mul(Transform3D t1)

public final void mul(Transform3D t1, Transform3D t2)

The first method sets the value of this transform to the result of multiplying itself
with transform t1 (this = this * t1). The second method sets the value of this
transform to the result of multiplying transform t1 by transform t2
(this = t1 * t2).

public final void mul(double scalar)

public final void mul(double scalar, Transform3D t1)

The first method multiplies this transform by the scalar constant. The second
method multiplies transform t1 by the scalar constant and places the value into
this transform.

public final void mulInverse(Transform3D t1)

public final void mulInverse(Transform3D t1, Transform3D t2)

The first method multiplies this transform by the inverse of transform t1 and
places the result into this transform (this = this * t1–1). The second method mul-
tiplies transform t1 by the inverse of transform t2 and places the result into this
transform (this = t1 * t2–1).

public final void mulTransposeRight(Transform3D t1,Transform3D t2)

public final void mulTransposeLeft(Transform3D t1, Transform3D t2)
public final void mulTransposeBoth(Transform3D t1, Transform3D t2)

The first method multiplies the transform t1 by the transpose of transform t2

and places the result into this transform (this = t1 * transpose(t2)). The second
method multiplies the transpose of transform t1 by transform t2 and places the
result into this transform (this = transpose(t1) * t2). The third method multiplies
the transpose of transform t1 by the transpose of t2 and places the result into
this transform (this = transpose(t1) * transpose(t2)).

Version 1.2, March 2000 187

8.1.29 Transform3D Object NODE COMPONENT OBJECTS

public final void normalize()

public final void normalize(Transform3D t1)

Both of these methods use an SVD normalization. The first normalize method
normalizes the rotational components (upper 3 × 3) of matrix this and places
the results back into this. The second normalize method normalizes the rota-
tional components (upper 3 × 3) of transform t1 and places the result in this.

public final void normalizeCP()

public final void normalizeCP(Transform3D t1)

Both of these methods use a cross-product (CP) normalization. The first normal-
izeCP method normalizes the rotational components (upper 3 × 3) of this trans-
form and places the result into this transform. The second normalizeCP method
normalizes the rotational components (upper 3 × 3 of transform t1 and places the
result into this transform.

public boolean equals(Transform3D t1)

public boolean equals(Object o1)

The first method returns true if all of the data members of transform t1 are
equal to the corresponding data members in this transform. The second method
returns true if the Object o1 is of type Transform3D and all of the data members
of o1 are equal to the corresponding data members in this Transform3D.

public boolean epsilonEquals(Transform3D t1, double epsilon)

This method returns true if the L∞ distance between this transform and trans-
form m1 is less than or equal to the epsilon parameter; otherwise, it returns
false. The L∞ distance is equal to:

MAX[i=0,1,2,3 ; j=0,1,2,3 ; abs[(this.m(i,j) – m1.m(i,j)]

public int hashCode()

This method returns a hash number based on the data values in this object. Two
different Transform3D objects with identical data values (that is, true is returned
for trans.equals(Transform3D)) will return the same hash number. Two
Transform3D objects with different data members may return the same hash
value, although this is not likely.

public final void transform(Vector4d vec, vector4d vecOut)

public final void transform(Vector4f vec, Vector4f vecOut)
public final void transform(Vector4d vec)
public final void transform(Vector4f vec)

188 The Java 3D API Specification

NODE COMPONENT OBJECTS Transform3D Object 8.1.29

The first two methods transform the vector vec by this transform and place the
result into vecOut. The last two methods transform the vector vec by this trans-
form and place the result back into vec.

public final void transform(Point3d point, Point3d pointOut)

public final void transform(Point3f point, point3f pointOut)
public final void transform(Point3d point)
public final void transform(Point3f point)

The first two methods transform the point parameter by this transform and place
the result into pointOut. The last two methods transform the point parameter
by this transform and place the result back into point. In both cases, the fourth
element of the point input parameter is assumed to be 1.

public final void transform(Vector3d normal, Vector3d normalOut)

public final void transform(Vector3f normal, Vector3f normalOut)
public final void transform(Vector3d normal)
public final void transform(Vector3f normal)

The first two methods transforms the normal parameter by this transform and
place the value into normalOut. The third and fourth methods transform the nor-
mal parameter by this transform and place the value back into normal.

8.1.29.1 View Model Compatibility Mode Methods: Viewing Matrix

public void lookAt(Point3d eye, Point3d center, Vector3d up)

This is a utility method that specifies the position and orientation of a viewing
transformation. It works very much like the similar function in OpenGL. The
inverse of this transform can be used to control the ViewPlatform object within
the scene graph. Alternatively, this transform can be passed directly to the View’s
VpcToEc transform via the compatibility mode viewing functions defined in
Section C.11.2, “Using the Camera-based View Model.”

8.1.29.2 View Model Compatibility Mode Methods: Projection Matrix

public void frustum(double left, double right, double bottom,

double top, double near, double far)
public void perspective(double fovx, double aspect, double zNear,
double zFar)
public void ortho(double left, double right, double bottom,
double top, double near, double far)

These three utility methods allow an application to create a perspective or paral-

lel (orthographic) projection matrix. These three methods work very much like
the similar functions in OpenGL. The resulting Transform3D can be used to
Version 1.2, March 2000 189
8.2 Node Component Objects: Geometry NODE COMPONENT OBJECTS

directly set the View’s left and right projection transforms when in compatibility
mode. See Section C.11.2, “Using the Camera-based View Model,” for details.
The fovx parameter specifies the field of view in the x direction in radians.

8.2 Node Component Objects: Geometry

A Geometry object is an abstract class that specifies the geometry component
information required by a Shape3D node. Geometry objects describe both the
geometry and topology of the Shape3D nodes that reference them. Geometry
objects consist of four generic geometric types: CompressedGeometry, Geometr-
yArray, Raster, and Text3D (see Figure 8-3). Each of these geometric types
defines a visible object or set of objects. A Geometry object is used as a compo-
nent object of a Shape3D leaf node.

SceneGraphObject
NodeComponent
Geometry
CompressedGeometry
Raster
Text3D
GeometryArray
GeometryStripArray
LineStripArray
TriangleStripArray
TriangleFanArray
LineArray
PointArray
QuadArray
TriangleArray
IndexedGeometryArray
IndexedGeometryStripArray
IndexedLineStripArray
IndexedTriangleStripArray
IndexedTriangleFanArray
IndexedLineArray
IndexedPointArray
IndexedQuadArray
IndexedTriangleArray

Figure 8-3 Geometry Component Object Hierarchy

Constants
The Geometry object defines the following constant.

190 The Java 3D API Specification

NODE COMPONENT OBJECTS GeometryArray Object 8.2.1

public static final int ALLOW_INTERSECT

This flag specifies that this Geometry object allows the intersect operation.

Constructors

public Geometry()

Constructs a new Geometry object.

8.2.1 GeometryArray Object

A GeometryArray object is an abstract class from which several classes are
derived to specify a set of geometric primitives. A GeometryArray contains sep-
arate arrays of the following vertex components: coordinates, colors, normals,
and texture coordinates, and a bitmask indicating which of these components are
present.
Vertex data may be passed to this geometry array in one of two ways: by copying
the data into the array using the existing methods, or by passing a reference to
the data.
• By copying: The existing methods for setting positional coordinates, col-
ors, normals, and texture coordinates (e.g., setCoordinate, setColors,
etc.) copy the data into this GeometryArray. This is appropriate for many
applications and offers an application much flexibility in organizing its da-
ta. This is the default mode.
• By reference: A new set of methods in Java 3D version 1.2 allows data to
be accessed by reference, directly from the user’s arrays. To use this fea-
ture, set the BY_REFERENCE bit in the vertexFormat field of the constructor
for this GeometryArray. In this mode, the various set methods for coordi-
nates, normals, colors, and texture coordinates are not used. Instead, new
methods are used to set a reference to user-supplied coordinate, color, nor-
mal, and texture coordinate arrays (e.g., setCoordRefFloat, setColor-
RefFloat, etc.). Data in any array that is referenced by a live or compiled
GeometryArray object may only be modified via the updateData method
(subject to the ALLOW_REF_DATA_WRITE capability bit). Applications must
exercise care not to violate this rule. If any referenced geometry data is
modified outside of the updateData method, the results are undefined.
A single GeometryArray contains a predefined collection of per-vertex informa-
tion; all of the vertices in a GeometryArray object have the same format and
primitive type. Different GeometryArrays can contain different per-vertex infor-
mation. One GeometryArray might contain only three-space coordinates; another
Version 1.2, March 2000 191
8.2.1 GeometryArray Object NODE COMPONENT OBJECTS

might contain per-vertex coordinates, normals, colors, and texture coordinates;

yet another might contain any subset of the previous example.
All colors used in the GeometryArray object must be in the range [0.0, 1.0]. Val-
ues outside this range will cause undefined results. All normals used in the
GeometryArray object must be unit length vectors. That is their geometric length
must be 1.0. Normals that are not unit length vectors will cause undefined
results.
Note that the term coordinate, as used in the method names and method descrip-
tions, actually refers to a set of x, y, and z coordinates representing the position
of a single vertex. The term coordinates (plural) is used to indicate sets of x, y,
and z coordinates for multiple vertices. This is somewhat at odds with the math-
ematical definition of a coordinate, but is used as a convenient shorthand. Simi-
larly, the term texture coordinate is used to indicate a set of texture coordinates
for a single vertex, while the term texture coordinates (plural) is used to indicate
sets of texture coordinates for multiple vertices.

Constants
The GeometryArray object defines the following flags.

public static final int ALLOW_COORDINATE_READ

public static final int ALLOW_COORDINATE_WRITE

These flags specify that the GeometryArray object allows reading or writing of
the array of coordinates.

public static final int ALLOW_COLOR_READ

public static final int ALLOW_COLOR_WRITE

These flags specify that the GeometryArray object allows reading or writing of
the array of colors.

public static final int ALLOW_NORMAL_READ

public static final int ALLOW_NORMAL_WRITE

These flags specify that the GeometryArray object allows reading or writing of
the array of normals.

public static final int ALLOW_TEXCOORD_READ

public static final int ALLOW_TEXCOORD_WRITE

These flags specify that the GeometryArray object allows reading or writing of
the array of texture coordinates.

192 The Java 3D API Specification

NODE COMPONENT OBJECTS GeometryArray Object 8.2.1

public static final int ALLOW_COUNT_READ

public static final int ALLOW_COUNT_WRITE New in 1.2

These flags specify that the GeometryArray object allows reading or writing of
any count or initial index data (such as the vertex count) associated with the
GeometryArray.

public static final int ALLOW_FORMAT_READ

This flag specifies that the GeometryArray object allows reading the vertex for-
mat associated with the GeometryArray.

public static final int ALLOW_REF_DATA_READ New in 1.2

public static final int ALLOW_REF_DATA_WRITE New in 1.2

These flags specify that this GeometryArray allows reading or writing the geom-
etry data reference information for this object. The second flag also enables writ-
ing the referenced data itself, via the GeometryUpdater interface. These are only
used in by-reference geometry mode.

public static final int BY_REFERENCE New in 1.2

This flag specifies that the position, color, normal, and texture coordinate data for
this GeometryArray are accessed by reference.

public static final int INTERLEAVED New in 1.2

This flag specifies that the position, color, normal, and texture coordinate data for
this GeometryArray are accessed via a single interleaved, floating-point array
reference. All of the data values for each vertex are stored in consecutive mem-
ory locations. This is only valid in conjunction with the BY_REFERENCE flag.

Constructors
The GeometryArray object has the following constructors.

public GeometryArray(int vertexCount, int vertexFormat)

Constructs an empty GeometryArray object with the specified vertex format and
number of vertices. The vertexCount parameter specifies the number of vertex
elements in this array. The vertexFormat parameter is a mask indicating which
vertex components are present in each vertex. The vertex format is specified as a
set of flags that are bitwise ORed together to describe the per-vertex data. The
following vertex formats are supported.

Version 1.2, March 2000 193

8.2.1 GeometryArray Object NODE COMPONENT OBJECTS

• COORDINATES: Specifies that this vertex array contains coordinates. This

bit must be set.
• NORMALS: Specifies that this vertex array contains normals.
• COLOR_3: Specifies that this vertex array contains colors without alpha.
Colors are specified as floating-point values in the range [0.0, 1.0].
• COLOR_4: Specifies that this vertex array contains colors with alpha. Colors
are specified as floating-point values in the range [0.0, 1.0]. This takes pre-
cedence over COLOR_3.
• TEXTURE_COORDINATE_2: Specifies that this vertex array contains 2D
texture coordinates (S and T).
• TEXTURE_COORDINATE_3: Specifies that this vertex array contains 3D tex-
ture coordinates (S, T, and R). This takes precedence over TEXTURE_
COORDINATE_2.
• BY_REFERENCE: Indicates that the data is passed by reference rather than by
copying.
• INTERLEAVED: Indicates that the referenced data is interleaved in a single
array.
The GeometryArray object is constructed with the following default values:

Parameter Default Value

texCoordSetCount 1
texCoordSetMap {0}
validVertexCount vertexCount
initialVertexIndex 0
initialCoordIndex 0
initialColorIndex 0
initialNormalIndex 0
initialTexCoordIndex 0
all data array values 0.0
all data array references null

public GeometryArray(int vertexCount, int vertexFormat,

int texCoordSetCount, int[] texCoordSetMap) New in 1.2

Constructs an empty GeometryArray object with the specified number of verti-

ces, vertex format, number of texture coordinate sets, and texture coordinate
mapping array. Defaults are used for all other parameters.

194 The Java 3D API Specification

NODE COMPONENT OBJECTS GeometryArray Object 8.2.1

The texCoordSetCount parameter specifies the number of texture coordinate

sets in this GeometryArray object. If the vertexFormat parameter does not
include one of TEXTURE_COORDINATE_2 or TEXTURE_COORDINATE_3, the texCo-
ordSetCount parameter is not used.

The texCoordSetMap parameter specifies an array that maps texture coordinate

sets to texture units. The array is indexed by texture unit number for each texture
unit in the associated Appearance object. The values in the array specify the tex-
ture coordinate set within this GeometryArray object that maps to the corre-
sponding texture unit. All elements within the array must be less than
texCoordSetCount. A negative value specifies that no texture coordinate set
maps to the texture unit corresponding to the index.
If there are more texture units in any associated Appearance object than elements
in the mapping array, the extra elements are assumed to be –1. The same texture
coordinate set may be used for more than one texture unit. Each texture unit in
every associated Appearance must have a valid source of texture coordinates:
either a non-negative texture coordinate set must be specified in the mapping
array or texture coordinate generation must be enabled. Texture coordinate gen-
eration will take precedence for those texture units for which a texture coordinate
set is specified and texture coordinate generation is enabled. If vertexFormat
does not include one of TEXTURE_COORDINATE_2 or TEXTURE_COORDINATE_3, the
texCoordSetMap array is not used. The following example illustrates the use of
the texCoordSetMap array.

Index Element Description

0 1 Use texture coordinate set 1 for texture unit 0
1 –1 Use no texture coordinate set for texture unit 1
2 0 Use texture coordinate set 0 for texture unit 2
3 1 Reuse texture coordinate set 1 for texture unit 3

Methods
GeometryArray methods provide access (get and set methods) to individual
vertex component arrays in two different modes: as individual elements or as
arrays of multiple elements.

public int getVertexCount()

Retrieves the number of vertices in the GeometryArray.

Version 1.2, March 2000 195

8.2.1 GeometryArray Object NODE COMPONENT OBJECTS

public int getVertexFormat()

Retrieves the vertex format of the GeometryArray.

public void updateData(GeometryUpdater updater) New in 1.2

This method updates geometry array data that is accessed by reference. This
method calls the updateData method of the specified GeometryUpdater object to
synchronize updates to vertex data that is referenced by this GeometryArray
object. Applications that wish to modify such data must perform all updates via
this method.
This method may also be used to atomically set multiple references (e.g., to
coordinate and color arrays) or atomically change multiple data values through
the geometry data copying methods.

public void setValidVertexCount(int validVertexCount) New in 1.2

public int getValidVertexCount() New in 1.2

Sets or retrieves the valid vertex count for this GeometryArray object. This count
specifies the number of vertices actually used in rendering or other operations
such as picking and collision. This attribute is initialized to vertexCount.

public void setInitialVertexIndex(int initialVertexIndex) New in 1.2

public int getInitialVertexIndex() New in 1.2

Sets or retrieves the initial vertex index for this GeometryArray object. This
index specifies the first vertex within this geometry array that is actually used in
rendering or other operations such as picking and collision. This attribute is ini-
tialized to 0. This attribute is only used when the data mode for this geometry
array object is not BY_REFERENCE.

public void setCoordinate(int index, float coordinate[])

public void getCoordinate(int index, float coordinate[])
public void setCoordinate(int index, double coordinate[])
public void getCoordinate(int index, double coordinate[])

Sets or retrieves the coordinate associated with the vertex at the specified index
of this object. The index parameter is the vertex index in this geometry array.
The coordinate parameter is an array of three values containing the new coordi-
nate.

public void setCoordinate(int index, Point3f coordinate)

public void getCoordinate(int index, Point3f coordinate)
public void setCoordinate(int index, Point3d coordinate)
public void getCoordinate(int index, Point3d coordinate)

196 The Java 3D API Specification

NODE COMPONENT OBJECTS GeometryArray Object 8.2.1

Sets or retrieves the coordinate associated with the vertex at the specified index.
The index parameter is the vertex index in this geometry array. The coordinate
parameter is a vector containing the new coordinate.

public void setCoordinates(int index, float coordinates[])

public void getCoordinates(int index, float coordinates[])
public void setCoordinates(int index, double coordinates[])
public void getCoordinates(int index, double coordinates[])

Sets or retrieves the coordinates associated with the vertices starting at the spec-
ified index. The index parameter is the starting vertex index in this geometry
array. The coordinates parameter is an array of 3n values containing n new
coordinates. The length of the coordinates array determines the number of ver-
tices copied.

public void setCoordinates(int index, Point3f coordinates[])

public void getCoordinates(int index, Point3f coordinates[])
public void setCoordinates(int index, Point3d coordinates[])
public void getCoordinates(int index, Point3d coordinates[])

Sets or retrieves the coordinates associated with the vertices starting at the spec-
ified index. The index parameter is the starting vertex index in this geometry
array. The coordinates parameter is an array of points containing new coordi-
nates. The length of the coordinates array determines the number of vertices
copied.

public void setCoordinates(int index, Point3d coordinates[],

int start, int length)
public void setCoordinates(int index, Point3f coordinates[],
int start, int length)
public void setCoordinates(int index, float coordinates[],
int start, int length)
public void setCoordinates(int index, double coordinates[],
int start, int length)

These methods set the coordinates associated with the vertices starting at the
specified index for this object, using coordinate data starting from vertex index
start for length vertices. The index parameter is the starting destination vertex
index in this geometry array.

Version 1.2, March 2000 197

8.2.1 GeometryArray Object NODE COMPONENT OBJECTS

public void setColor(int index, float color[])

public void getColor(int index, float color[])
public void setColor(int index, byte color[])
public void getColor(int index, byte color[])

Sets or retrieves the color associated with the vertex at the specified index. The
index parameter is the vertex index in this geometry array. The color parameter
is an array of three or four values containing the new color.

public void setColor(int index, Color3f color)

public void getColor(int index, Color3f color)
public void setColor(int index, Color4f color)
public void getColor(int index, Color4f color)
public void setColor(int index, Color3b color)
public void getColor(int index, Color3b color)
public void setColor(int index, Color4b color)
public void getColor(int index, Color4b color)

Sets or retrieves the color associated with the vertex at the specified index. The
index parameter is the vertex index in this geometry array. The color parameter
is a vector containing the new color.

public void setColors(int index, float colors[])

public void getColors(int index, float colors[])
public void setColors(int index, byte colors[])
public void getColors(int index, byte colors[])

Sets or retrieves the colors associated with the vertices starting at the specified
index. The index parameter is the starting vertex index in this geometry array.
The colors parameter is an array of 3n or 4n values containing n new colors.
The length of the colors array determines the number of vertices copied.

public void setColors(int index, Color3f colors[])

public void getColors(int index, Color3f colors[])
public void setColors(int index, Color4f colors[])
public void getColors(int index, Color4f colors[])
public void setColors(int index, Color3b colors[])
public void getColors(int index, Color3b colors[])
public void setColors(int index, Color4b colors[])
public void getColors(int index, Color4b colors[])

Sets or retrieves the colors associated with the vertices starting at the specified
index. The index parameter is the starting vertex index in this geometry array.
The colors parameter is an array of vectors containing the new colors. The
length of the colors array determines the number of vertices copied.

198 The Java 3D API Specification

NODE COMPONENT OBJECTS GeometryArray Object 8.2.1

public void setColors(int index, float colors[], int start,

int length)
public void setColors(int index, byte colors[], int start,
int length)

These methods set the colors associated with the vertices starting at the specified
index for this object, using data in colors starting at index start for length
colors. The index parameter is the starting destination vertex index in this geom-
etry array. The colors parameter is an array of 3n or 4n values containing n new
colors.
public void setColors(int index, Color3f colors[], int start,
int length)
public void setColors(int index, Color4f colors[], int start,
int length)
public void setColors(int index, Color3b colors[], int start,
int length)
public void setColors(int index, Color4b colors[], int start,
int length)

These methods set the colors associated with the vertices starting at the specified
index for this object, using data in colors starting at index start for length
colors. The index parameter is the starting destination vertex index in this geom-
etry array. The colors parameter is an array of vectors containing new colors.

public void setNormal(int index, float normal[])

public void getNormal(int index, float normal[])

Sets or retrieves the normal associated with the vertex at the specified index. The
index parameter is the vertex index in this geometry array. The normal parame-
ter is the new normal.

public void setNormal(int index, Vector3f normal)

public void getNormal(int index, Vector3f normal)

Sets or retrieves the normal associated with the vertex at the specified index. The
index parameter is the vertex index in this geometry array. The normal parame-
ter is a vector containing the new normal.

public void setNormals(int index, float normals[])

public void getNormals(int index, float normals[])

Sets or retrieves the normals associated with the vertices starting at the specified
index. The index parameter is the starting vertex index in this geometry array.
The normals parameter is an array of 3n values containing n new normals. The
length of the normals array determines the number of vertices copied.

Version 1.2, March 2000 199

8.2.1 GeometryArray Object NODE COMPONENT OBJECTS

public void setNormals(int index, Vector3f normals[])

public void getNormals(int index, Vector3f normals[])

Sets or retrieves the normals associated with the vertices starting at the specified
index. The index parameter is the starting vertex index in this geometry array.
The normals parameter is an array of vectors containing new normals. The
length of the normals array determines the number of vertices copied.

public void setNormals(int index, float normals[], int start,

int length)
public void setNormals(int index, Vector3f normals[], int start,
int length)

These methods set the normals associated with the vertices starting at the speci-
fied index for this object, using data in normals starting at index start and end-
ing at index start+length. The index parameter is the starting destination
vertex index in this geometry array.

public int getTexCoordSetCount() New in 1.2

This method retrieves the number of texture coordinate sets in this Geometr-
yArray object.

public int getTexCoordSetMapLength() New in 1.2

This method retrieves the length of the texture coordinate set mapping array of
this GeometryArray object.

public void getTexCoordSetMap(int[] texCoordSetMap) New in 1.2

This method retrieves the texture coordinate set mapping array from this Geom-
etryArray object.

public void setTextureCoordinate(int texCoordSet, int index,

float[] texCoord) New in 1.2
public void setTextureCoordinate(int texCoordSet, int index,
TexCoord2f texCoord) New in 1.2
public void setTextureCoordinate(int texCoordSet, int index,
TexCoord3f texCoord) New in 1.2
public void getTextureCoordinate(int texCoordSet, int index,
float[] texCoord) New in 1.2
public void getTextureCoordinate(int texCoordSet, int index,
TexCoord2f texCoord) New in 1.2
public void getTextureCoordinate(int texCoordSet, int index,
TexCoord3f texCoord) New in 1.2

These methods set and retrieve the texture coordinate associated with the vertex
at the specified index in the specified texture coordinate set for this object.

200 The Java 3D API Specification

NODE COMPONENT OBJECTS GeometryArray Object 8.2.1

public void setTextureCoordinates(int texCoordSet, int index,

float[] texCoords) New in 1.2
public void setTextureCoordinates(int texCoordSet, int index,
TexCoord2f[] texCoords) New in 1.2
public void setTextureCoordinates(int texCoordSet, int index,
TexCoord3f[] texCoords) New in 1.2
public void getTextureCoordinates(int texCoordSet, int index,
float[] texCoords) New in 1.2
public void getTextureCoordinates(int texCoordSet, int index,
TexCoord2f[] texCoords) New in 1.2
public void getTextureCoordinates(int texCoordSet, int index,
TexCoord3f[] texCoords) New in 1.2

These methods set and retrieve the texture coordinates associated with the verti-
ces starting at the specified index in the specified texture coordinate set for this
object. The set methods copy the entire source array to this geometry array. For
the get methods, the length of the destination array determines the number of
texture coordinates copied.

public void setTextureCoordinates(int texCoordSet, int index,

float[] texCoords, int start, int length) New in 1.2
public void setTextureCoordinates(int texCoordSet, int index,
TexCoord2f[] texCoords, int start, int length) New in 1.2
public void setTextureCoordinates(int texCoordSet, int index,
TexCoord3f[] texCoords, int start, int length) New in 1.2

These methods set and retrieve the texture coordinates associated with the verti-
ces starting at the specified index in the specified texture coordinate set for this
object using data in texCoords starting at index start and ending at index
start+length.

public void setTextureCoordinate(int index, float texCoord[])

public void getTextureCoordinate(int index, float texCoord[])
public void setTextureCoordinate(int index, Point2f texCoord)
public void getTextureCoordinate(int index, Point2f texCoord)
public void setTextureCoordinate(int index, Point3f texCoord)
public void getTextureCoordinate(int index, Point3f texCoord)
public void setTextureCoordinates(int index, float texCoords[])
public void getTextureCoordinates(int index, float texCoords[])
public void setTextureCoordinates(int index, Point2f texCoords[])
public void getTextureCoordinates(int index, Point2f texCoords[])
public void setTextureCoordinates(int index, Point3f texCoords[])
public void getTextureCoordinates(int index, Point3f texCoords[])
public void setTextureCoordinates(int index, float texCoords[],
int start, int length)
public void setTextureCoordinates(int index, Point2f texCoords[],
int start, int length)

Version 1.2, March 2000 201

8.2.1 GeometryArray Object NODE COMPONENT OBJECTS

public void setTextureCoordinates(int index, Point3f texCoords[],

int start, int length)

These methods are deprecated in Java 3D version 1.2.

public void setInitialCoordIndex(int initialCoordIndex) New in 1.2

public int getInitialCoordIndex() New in 1.2

Sets or retrieves the initial coordinate index for this GeometryArray object. This
index specifies the first coordinate within the array of coordinates referenced by
this geometry array that is actually used in rendering or other operations such as
picking and collision. This attribute is initialized to 0. This attribute is only used
when the data mode for this geometry array object is BY_REFERENCE.

public void setInitialColorIndex(int initialColorIndex) New in 1.2

public int getInitialColorIndex() New in 1.2

Sets or retrieves the initial color index for this GeometryArray object. This index
specifies the first color within the array of colors referenced by this geometry
array that is actually used in rendering or other operations such as picking and
collision. This attribute is initialized to 0. This attribute is only used when the
data mode for this geometry array object is BY_REFERENCE.

public void setInitialNormalIndex(int initialNormalIndex) New in 1.2

public int getInitialNormalIndex() New in 1.2

Sets or retrieves the initial normal index for this GeometryArray object. This
index specifies the first normal within the array of normals referenced by this
geometry array that is actually used in rendering or other operations such as
picking and collision. This attribute is initialized to 0. This attribute is only used
when the data mode for this geometry array object is BY_REFERENCE.

public void setInitialTexCoordIndex(int texCoordSet,

int initialTexCoordIndex) New in 1.2
public int getInitialTexCoordIndex(int texCoordSet) New in 1.2

Sets or retrieves the initial texture coordinate index for the specified texture coor-
dinate set for this GeometryArray object. This index specifies the first texture
coordinate within the array of texture coordinates referenced by this geometry
array that is actually used in rendering or other operations such as picking and
collision. This attribute is initialized to 0. This attribute is only used when the
data mode for this geometry array object is BY_REFERENCE.

public void setCoordRefFloat(float[] coords) New in 1.2

public float[] getCoordRefFloat() New in 1.2
public void setCoordRefDouble(double[] coords) New in 1.2

202 The Java 3D API Specification

NODE COMPONENT OBJECTS GeometryArray Object 8.2.1

public double[] getCoordRefDouble() New in 1.2

Sets or retrieves the coordinate array reference to the specified array. The array
contains x, y, and z values for each vertex (for a total of 3*n values, where n is
the number of vertices). Only one of coordRefFloat, coordRefDouble,
coordRef3f, or coordRef3d may be non-null (or they may all be null). An
attempt to set more than one of these attributes to a non-null reference will result
in an exception being thrown. If all coordinate array references are null, the
entire geometry array object is treated as if it were null—any Shape3D or Morph
node that uses this geometry array will not be drawn.

public void setCoordRef3f(Point3f[] coords) New in 1.2

public Point3f[] getCoordRef3f() New in 1.2
public void setCoordRef3d(Point3d[] coords) New in 1.2
public Point3d[] getCoordRef3d() New in 1.2

Sets or retrieves the coordinate array reference to the specified array. The array
contains a Point3f or Point3d object for each vertex. Only one of coordRef-
Float, coordRefDouble, coordRef3f, or coordRef3d may be non-null (or they
may all be null). An attempt to set more than one of these attributes to a non-null
reference will result in an exception being thrown. If all coordinate array refer-
ences are null, the entire geometry array object is treated as if it were null—any
Shape3D or Morph node that uses this geometry array will not be drawn.

public void setColorRefFloat(float[] colors) New in 1.2

public float[] getColorRefFloat() New in 1.2
public void setColorRefByte(byte[] colors) New in 1.2
public byte[] getColorRefByte() New in 1.2

Sets or retrieves the color array reference to the specified array. The array con-
tains red, green, blue, and, optionally, alpha values for each vertex (for a total of
3*n or 4*n values, where n is the number of vertices). Only one of colorRef-
Float, colorRefByte, colorRef3f, colorRef4f, colorRef3b, or colorRef4b
may be non-null (or they may all be null). An attempt to set more than one of
these attributes to a non-null reference will result in an exception being thrown.
If all color array references are null and colors are enabled (i.e., the vertexFormat
includes either COLOR_3 or COLOR_4), the entire geometry array object is treated
as if it were null—any Shape3D or Morph node that uses this geometry array
will not be drawn.

public void setColorRef3f(Color3f[] colors) New in 1.2

public Color3f[] getColorRef3f() New in 1.2
public void setColorRef4f(Color4f[] colors) New in 1.2
public Color4f[] getColorRef4f() New in 1.2

Version 1.2, March 2000 203

8.2.1 GeometryArray Object NODE COMPONENT OBJECTS

public void setColorRef3b(Color3b[] colors) New in 1.2

public Color3b[] getColorRef3b() New in 1.2
public void setColorRef4b(Color4b[] colors) New in 1.2
public Color4b[] getColorRef4b() New in 1.2

Sets or retrieves the color array reference to the specified array. The array con-
tains a Color 3f, Color4f, Color3b, or Color4b object for each vertex. Only one
of colorRefFloat, colorRefByte, colorRef3f, colorRef4f, colorRef3b, or
colorRef4b may be non-null (or they may all be null). An attempt to set more
than one of these attributes to a non-null reference will result in an exception
being thrown. If all color array references are null and colors are enabled (i.e.,
the vertexFormat includes either COLOR_3 or COLOR_4), the entire geometry array
object is treated as if it were null—any Shape3D or Morph node that uses this
geometry array will not be drawn.

public void setNormalRefFloat(float[] normals) New in 1.2

public float[] getNormalRefFloat() New in 1.2

Sets or retrieves the float normal array reference to the specified array. The array
contains floating-point nx, ny, and nz values for each vertex (for a total of 3*n
values, where n is the number of vertices). Only one of normalRefFloat or
normalRef3f may be non-null (or they may all be null). An attempt to set more
than one of these attributes to a non-null reference will result in an exception
being thrown. If all normal array references are null and normals are enabled
(i.e., the vertexFormat includes NORMAL), the entire geometry array object is
treated as if it were null—any Shape3D or Morph node that uses this geometry
array will not be drawn.

public void setNormalRef3f(Vector3f[] normals) New in 1.2

public Vector3f[] getNormalRef3f() New in 1.2

Sets or retrieves the normal array reference to the specified array. The array con-
tains a Vector3f object for each vertex. Only one of normalRefFloat or
normalRef3f may be non-null (or they may all be null). An attempt to set more
than one of these attributes to a non-null reference will result in an exception
being thrown. If all normal array references are null and normals are enabled
(i.e., the vertexFormat includes NORMAL), the entire geometry array object is
treated as if it were null—any Shape3D or Morph node that uses this geometry
array will not be drawn.

public void setTexCoordRefFloat(int texCoordSet,

float[] texCoords) New in 1.2
public float[] getTexCoordRefFloat(int texCoordSet) New in 1.2

204 The Java 3D API Specification

NODE COMPONENT OBJECTS GeometryArray Object 8.2.1

Sets or retrieves the float texture coordinate array reference for the specified tex-
ture coordinate set to the specified array. The array contains floating-point s, t,
and, optionally, r values for each vertex (for a total of 2*n or 3*n values, where
n is the number of vertices). Only one of texCoordRefFloat, texCoordRef2f,
or texCoordRef3f may be non-null (or they may all be null). An attempt to set
more than one of these attributes to a non-null reference will result in an excep-
tion being thrown. If all texCoord array references are null and texture coordi-
nates are enabled (i.e., the vertexFormat includes either TEXTURE_COORDINATE_2
or TEXTURE_COORDINATE_3), the entire geometry array object is treated as if it
were null – any Shape3D or Morph node that uses this geometry array will not
be drawn.

public void setTexCoordRef2f(int texCoordSet,

TexCoord2f[] texCoords) New in 1.2
public TexCoord2f[] getTexCoordRef2f(int texCoordSet) New in 1.2
public void setTexCoordRef3f(int texCoordSet,
TexCoord3f[] texCoords) New in 1.2
public TexCoord3f[] getTexCoordRef3f(int texCoordSet) New in 1.2

Sets the texture coordinate array reference for the specified texture coordinate set
to the specified array. The array contains a TexCoord2f or TexCoord3f object for
each vertex. Only one of texCoordRefFloat, texCoordRef2f, or texCoordRef3f
may be non-null (or they may all be null). An attempt to set more than one of
these attributes to a non-null reference will result in an exception being thrown.
If all texCoord array references are null and texture coordinates are enabled (i.e.,
the vertexFormat includes either TEXTURE_COORDINATE_2 or TEXTURE_
COORDINATE_3), the entire geometry array object is treated as if it were null –
any Shape3D or Morph node that uses this geometry array will not be drawn.

public void setInterleavedVertices(float[] vertexData) New in 1.2

public float[] getInterleavedVertices() New in 1.2

Sets or retrieves the interleaved vertices array reference to the specified array.
The vertex components must be stored in a predetermined order in the array. The
order is: texture coordinates, colors, normals, and positional coordinates. Only
those components that are enabled appear in the vertex. The number of words per
vertex depends on which vertex components are enabled. Texture coordinates, if
enabled, use two words per vertex for TEXTURE_COORDINATE_2 or three words
per vertex for TEXTURE_COORDINATE_3. Colors, if enabled, use three words per
vertex for COLOR_3 or four words per vertex for COLOR_4. Normals, if enabled,
use three words per vertex. Positional coordinates, which are always enabled, use
three words per vertex. For example, the format of interleaved data for a Geom-
etryArray object whose vertexFormat includes COORDINATES, COLOR_3, and NOR-

Version 1.2, March 2000 205

8.2.2 GeometryUpdater Interface NODE COMPONENT OBJECTS

MALS would be: red, green, blue, Nx, Ny, Nz, x, y, z. All components of a vertex
are stored in adjacent memory locations. The first component of vertex 0 is
stored beginning at index 0 in the array. The first component of vertex 1 is stored
beginning at index words_per_vertex in the array. The total number of words
needed to store n vertices is words_per_vertex*n.

8.2.2 GeometryUpdater Interface

The GeometryUpdater interface is used in updating geometry data that is
accessed by reference from a live or compiled GeometryArray object (see
Section 8.2.1, “GeometryArray Object”). Applications that wish to modify such
data must define a class that implements this interface. An instance of that class
is then passed to the updateData method of the GeometryArray object to be
modified.

Methods

public void updateData(Geometry geometry) New in 1.2

This method updates geometry data that is accessed by reference. This method is
called by the updateData method of a GeometryArray object to effect safe
updates to vertex data that is referenced by that object. Applications that wish to
modify such data must implement this method and perform all updates within it.

Note: Applications should not call this method directly.

8.2.3 PointArray Object

The PointArray object extends GeometryArray and provides no additional meth-
ods. Objects of this class draw the array of vertices as individual points.

Constructors

public PointArray(int vertexCount, int vertexFormat)

Constructs an empty PointArray object with the specified vertex format and
number of vertices.

public PointArray(int vertexCount, int vertexFormat,

int texCoordSetCount, int[] texCoordSetMap) New in 1.2

206 The Java 3D API Specification

NODE COMPONENT OBJECTS TriangleArray Object 8.2.5

Constructs an empty PointArray object with the specified number of vertices,

and vertex format, number of texture coordinate sets, and texture coordinate
mapping array.

8.2.4 LineArray Object

The LineArray object extends GeometryArray and provides no additional meth-
ods. Objects of this class draw the array of vertices as individual line segments.
Each pair of vertices defines a line segment to be drawn.

Constructors

public LineArray(int vertexCount, int vertexFormat)

Constructs an empty LineArray object with the specified vertex format and num-
ber of vertices.

public LineArray(int vertexCount, int vertexFormat,

int texCoordSetCount, int[] texCoordSetMap) New in 1.2

Constructs an empty LineArray object with the specified number of vertices, and
vertex format, number of texture coordinate sets, and texture coordinate mapping
array.

8.2.5 TriangleArray Object

The TriangleArray object extends GeometryArray and provides no additional
methods. Objects of this class draw the array of vertices as individual triangles.
Each group of three vertices defines a triangle to be drawn.

Constructors

public TriangleArray(int vertexCount, int vertexFormat)

Constructs an empty TriangleArray object with the specified vertex format and
number of vertices.

public TriangleArray(int vertexCount, int vertexFormat,

int texCoordSetCount, int[] texCoordSetMap) New in 1.2

Constructs an empty TriangleArray object with the specified number of vertices,

and vertex format, number of texture coordinate sets, and texture coordinate
mapping array.

Version 1.2, March 2000 207

8.2.6 QuadArray Object NODE COMPONENT OBJECTS

8.2.6 QuadArray Object

The QuadArray object extends GeometryArray and provides no additional meth-
ods. Objects of this class draw the array of vertices as individual quadrilaterals.
Each group of four vertices defines a quadrilateral to be drawn. A quadrilateral
must be planar and convex or results are undefined. A quadrilateral may be ren-
dered as a pair of triangles with either diagonal line arbitrarily chosen to split the
quad.

Constructors

public QuadArray(int vertexCount, int vertexFormat)

Constructs an empty QuadArray object with the specified vertex format and
number of vertices.

public QuadArray(int vertexCount, int vertexFormat,

int texCoordSetCount, int[] texCoordSetMap) New in 1.2

Constructs an empty QuadArray object with the specified number of vertices,

and vertex format, number of texture coordinate sets, and texture coordinate
mapping array.

8.2.7 GeometryStripArray Object

GeometryStripArray is an abstract class from which all strip primitives (line
strip, triangle strip, and triangle fan) are derived. In addition to specifying the
array of vertex elements, which is inherited from GeometryArray, the Geome-
tryStripArray class specifies an array of per-strip vertex counts that specifies
where the separate strips appear in the vertex array.

Constructors
The GeometryStripArray object has the following constructors.

public GeometryStripArray(int vertexCount, int vertexFormat,

int stripVertexCounts[])

Constructs an empty GeometryStripArray object with the specified number of

vertices, vertex format, and an array of vertex counts per strip. The vertexCount
parameter specifies the number of vertex elements in this array.
The stripVertexCounts parameter is an array that specifies the count of the
number of vertices for each separate strip. The length of this array specifies the
number of separate strips. The sum of the vertex counts for all strips, as specified

208 The Java 3D API Specification

NODE COMPONENT OBJECTS LineStripArray Object 8.2.8

by the stripVertexCounts array, must equal the total count of all vertices as
specified by the vertexCount parameter.

public GeometryStripArray(int vertexCount, int vertexFormat,

int texCoordSetCount, int[] texCoordSetMap,
int[] stripVertexCounts) New in 1.2

Constructs an empty GeometryStripArray object with the specified number of

vertices, vertex format, number of texture coordinate sets, texture coordinate
mapping array, and array of per-strip vertex counts.

Methods
The GeometryStripArray object has the following methods.

public int getNumStrips()

This method returns the number of strips in the GeometryStripArray.

public void getStripVertexCounts(int stripVertexCounts[])

This method gets an array containing a list of vertex counts for each strip.

8.2.8 LineStripArray Object

The LineStripArray extends GeometryStripArray and provides no additional
methods. Objects of this class draw an array of vertices as a set of connected line
strips. An array of per-strip vertex counts specifies where the separate strips
appear in the vertex array. For every strip in the set, each vertex, beginning with
the second vertex in the array, defines a line segment to be drawn from the previ-
ous vertex to the current vertex.

Constructors

public LineStripArray(int vertexCount, int vertexFormat,

int stripVertexCounts[])

Constructs an empty LineStripArray object with the specified number of vertices,

vertex format, and array of vertex counts per strip.

public LineStripArray(int vertexCount, int vertexFormat,

int texCoordSetCount, int[] texCoordSetMap,
int[] stripVertexCounts) New in 1.2

Constructs an empty LineStripArray object with the specified number of vertices,

vertex format, number of texture coordinate sets, texture coordinate mapping
array, and array of per-strip vertex counts.
Version 1.2, March 2000 209
8.2.9 TriangleStripArray Object
The TriangleStripArray extends GeometryStripArray and provides no additional
methods. Objects of this class draw an array of vertices as a set of connected tri-
angle strips. An array of per-strip vertex counts specifies where the separate
strips appear in the vertex array. For every strip in the set, each vertex, beginning
with the third vertex in the array, defines a triangle to be drawn using the current
vertex and the two previous vertices.

Constructors

public TriangleStripArray(int vertexCount, int vertexFormat,

int stripVertexCounts[])

Constructs an empty TriangleStripArray object with the specified number of ver-

tices, vertex format, and array of vertex counts per strip.

public TriangleStripArray(int vertexCount, int vertexFormat,

int texCoordSetCount, int[] texCoordSetMap,
int[] stripVertexCounts) New in 1.2

Constructs an empty TriangleStripArray object with the specified number of ver-

tices, vertex format, number of texture coordinate sets, texture coordinate map-
ping array, and array of per-strip vertex counts.

8.2.10 TriangleFanArray Object

The TriangleFanArray extends GeometryStripArray and provides no additional
methods. Objects of this class draw an array of vertices as a set of connected tri-
angle fans. An array of per-strip vertex counts specifies where the separate strips
(fans) appear in the vertex array. For every strip in the set, each vertex, beginning
with the third vertex in the array, defines a triangle to be drawn using the current
vertex, the previous vertex, and the first vertex. This can be thought of as a col-
lection of convex polygons.

Constructors

public TriangleFanArray(int vertexCount, int vertexFormat,

int stripVertexCounts[])

Constructs an empty TriangleFanArray object with the specified number of verti-

ces, vertex format, and array of vertex counts per strip.
NODE COMPONENT OBJECTS IndexedGeometryArray Object 8.2.11

public TriangleFanArray(int vertexCount, int vertexFormat,

int texCoordSetCount, int[] texCoordSetMap,
int[] stripVertexCounts) New in 1.2

Constructs an empty TriangleFanArray object with the specified number of verti-

ces, vertex format, number of texture coordinate sets, texture coordinate mapping
array, and array of per-strip vertex counts.

8.2.11 IndexedGeometryArray Object

An IndexedGeometryArray object is an abstract class that extends Geometr-
yArray to allow vertex data to be accessed via a level of indirection. In addition
to the separate arrays of coordinates, colors, normals, and texture coordinates—
inherited from GeometryArray—an IndexedGeometryArray object adds corre-
sponding arrays of coordinate indices, color indices, normal indices, and texture
coordinate indices.

Constants
The IndexedGeometryArray object defines the following flags.

public static final int ALLOW_COORDINATE_INDEX_READ

public static final int ALLOW_COORDINATE_INDEX_WRITE

These flags specify that the IndexedGeometryArray object allows reading or

writing of the array of coordinate indices.

public static final int ALLOW_COLOR_INDEX_READ

public static final int ALLOW_COLOR_INDEX_WRITE

These flags specify that the IndexedGeometryArray object allows reading or

writing of the array of color indices.

public static final int ALLOW_NORMAL_INDEX_READ

public static final int ALLOW_NORMAL_INDEX_WRITE

These flags specify that the IndexedGeometryArray object allows reading or

writing of the array of normal indices.

public static final int ALLOW_TEXCOORD_INDEX_READ

public static final int ALLOW_TEXCOORD_INDEX_WRITE

These flags specify that the IndexedGeometryArray object allows reading or

writing of the array of texture coordinate indices.

Version 1.2, March 2000 211

8.2.11 IndexedGeometryArray Object NODE COMPONENT OBJECTS

Constructors
The IndexedGeometryArray object has two constructors that accept the same
parameters as GeometryArray.

public IndexedGeometryArray(int vertexCount, int vertexFormat,

int indexCount)

Constructs an empty IndexedGeometryArray object with the specified number of

vertices, vertex format, and number of indices. The index values in each of the
four index arrays (coordinates, colors, normals, and texture coordinates) are all
initialized to 0.

public IndexedGeometryArray(int vertexCount, int vertexFormat,

int texCoordSetCount, int[] texCoordSetMap, int indexCount) New in 1.2

Constructs an empty IndexedGeometryArray object with the specified number of

vertices, vertex format, number of texture coordinate sets, texture coordinate
mapping array, and number of indices. The index values in each of the four index
arrays (coordinates, colors, normals, and texture coordinates) are all initialized to
0.

Methods
IndexedGeometryArray methods provide access (get and set methods) to the
individual vertex component index arrays that are used when rendering the
geometry. This access is allowed in two different modes: as individual index ele-
ments or as arrays of multiple index elements.

public void setCoordinateIndex(int index, int coordinateIndex)

public int getCoordinateIndex(int index)

Sets or retrieves the coordinate index associated with the vertex at the specified
index.

public void setCoordinateIndices(int index,

int coordinateIndices[])
public void getCoordinateIndices(int index,
int coordinateIndices[])

Sets or retrieves the coordinate indices associated with the vertices starting at the
specified index.

public void setColorIndex(int index, int colorIndex)

public int getColorIndex(int index)

Sets or retrieves the color index associated with the vertex at the specified index.

212 The Java 3D API Specification

NODE COMPONENT OBJECTS IndexedGeometryArray Object 8.2.11

public void setColorIndices(int index, int colorIndices[])

public void getColorIndices(int index, int colorIndices[])

Sets or retrieves the color indices associated with the vertices starting at the spec-
ified index.

public void setNormalIndex(int index, int normalIndex)

public int getNormalIndex(int index)

Sets or retrieves the normal index associated with the vertex at the specified
index.

public void setnormalIndices(int index, int normalIndices[])

public void getNormalIndices(int index, int normalIndices[])

Sets or retrieves the normal indices associated with the vertices starting at the
specified index.

public void setTextureCoordinateIndex(int texCoordSet, int index,

int texCoordIndex) New in 1.2
public int getTextureCoordinateIndex(int texCoordSet, int index) New in 1.2

These methods set and retrieve the texture coordinate index associated with the
vertex at the specified index in the specified texture coordinate set for this object.

public void setTextureCoordinateIndices(int texCoordSet,

int index, int[] texCoordIndices) New in 1.2
public void getTextureCoordinateIndices(int texCoordSet,
int index, int[] texCoordIndices) New in 1.2

These methods set and retrieve the texture coordinate indices associated with the
vertices starting at the specified index in the specified texture coordinate set for
this object.

public void setTextureCoordinateIndex(int index,

int texCoordIndex)
public int getTextureCoordinateIndex(int index)
public void setTextureCoordinateIndices(int index,
int texCoordIndices[])
public void getTextureCoordinateIndices(int index,
int texCoordIndices[])

These methods are deprecated in Java 3D version 1.2.

public int getIndexCount()

Retrieves the number of indices for this IndexedGeometryArray.

Version 1.2, March 2000 213

8.2.12 IndexedPointArray Object NODE COMPONENT OBJECTS

8.2.12 IndexedPointArray Object

The IndexedPointArray object extends IndexedGeometryArray and provides no
additional methods. Objects of this class draw the array of vertices as individual
points.

Constructors
The IndexedPointArray object has the following constructors.

public IndexedPointArray(int vertexCount, int vertexFormat,

int indexCount)

Constructs an empty IndexedPointArray object with the specified number of ver-

tices, vertex format (see Section 8.2.1, “GeometryArray Object,” for a descrip-
tion of the supported vertex formats), and the number of indices in this array.

public IndexedPointArray(int vertexCount, int vertexFormat,

int texCoordSetCount, int[] texCoordSetMap, int indexCount) New in 1.2

Constructs an empty IndexedPointArray object with the specified number of ver-

tices, vertex format, number of texture coordinate sets, texture coordinate map-
ping array, and number of indices.

8.2.13 IndexedLineArray Object

The IndexedLineArray object extends IndexedGeometryArray and provides no
additional methods. Objects of this class draw the array of vertices as individual
line segments. Each pair of vertices defines a line segment to be drawn.

Constructors
The IndexedLineArray object has the following constructors.

public IndexedLineArray(int vertexCount, int vertexFormat,

int indexCount)

Constructs an empty IndexedLineArray object with the specified number of ver-

tices, vertex format, and the number of indices in this array. The vertexFormat
is a mask indicating which components are present in each vertex (see
Section 8.2.1, “GeometryArray Object,” for a description of the supported vertex
formats).

public IndexedLineArray(int vertexCount, int vertexFormat,

int texCoordSetCount, int[] texCoordSetMap, int indexCount) New in 1.2

214 The Java 3D API Specification

NODE COMPONENT OBJECTS IndexedQuadArray Object 8.2.15

Constructs an empty IndexedLineArray object with the specified number of ver-

tices, vertex format, number of texture coordinate sets, texture coordinate map-
ping array, and number of indices.

8.2.14 IndexedTriangleArray Object

The IndexedTriangleArray object extends IndexedGeometryArray and provides
no additional methods. Objects of this class draw the array of vertices as individ-
ual triangles. Each group of three vertices defines a triangle to be drawn.

Constructors
The IndexedTriangleArray object has the following constructors.

public IndexedTriangleArray(int vertexCount, int vertexFormat,

int indexCount)

Constructs an empty IndexedTriangleArray object with the specified number of

vertices, vertex format, and the number of indices in this array. The vertexFor-
mat is a mask indicating which components are present in each vertex (see
Section 8.2.1, “GeometryArray Object,” for a description of the supported vertex
formats).

public IndexedTriangleArray(int vertexCount, int vertexFormat,

int texCoordSetCount, int[] texCoordSetMap, int indexCount) New in 1.2

Constructs an empty IndexedTriangleArray object with the specified number of

vertices, vertex format, number of texture coordinate sets, texture coordinate
mapping array, and number of indices

8.2.15 IndexedQuadArray Object

The IndexedQuadArray object extends IndexedGeometryArray and provides no
additional methods. Objects of this class draw the array of vertices as individual
quadrilaterals. Each group of four vertices defines a quadrilateral to be drawn. A
quadrilateral must be planar and convex or results are undefined. A quadrilateral
may be rendered as a pair of triangles with either diagonal line arbitrarily chosen
to split the quad.

Constructors
The IndexedQuadArray object has the following constructors.

Version 1.2, March 2000 215

8.2.16 IndexedGeometryStripArray Object NODE COMPONENT OBJECTS

public IndexedQuadArray(int vertexCount, int vertexFormat,

int indexCount)

Constructs an empty IndexedQuadArray object with the specified number of ver-

tices, vertex format (see Section 8.2.1, “GeometryArray Object,” for a descrip-
tion of the supported vertex formats), and the number of indices in this array.

public IndexedQuadArray(int vertexCount, int vertexFormat,

int texCoordSetCount, int[] texCoordSetMap, int indexCount) New in 1.2

Constructs an empty IndexedQuadArray object with the specified number of ver-

tices, vertex format, number of texture coordinate sets, texture coordinate map-
ping array, and number of indices.

8.2.16 IndexedGeometryStripArray Object

IndexedGeometryStripArray is an abstract class from which all strip primitives
(line strip, triangle strip, and triangle fan) are derived. In addition to specifying
the array of vertex elements, which is inherited from IndexedGeometryArray, the
IndexedGeometryArrayStrip class specifies an array of per-strip index counts
that specifies where the separate strips appear in the indexed vertex array.

Constructors
The IndexedGeometryStripArray object has the following constructors.

public IndexedGeometryStripArray(int vertexCount,

int vertexFormat, int indexCount, int stripIndexCounts[])

Constructs an empty IndexedGeometryStripArray object with the specified num-

ber of vertices, vertex format, number of indices in the array, and an array of
index counts per strip. The vertexCount parameter specifies the number of ver-
tex elements in this array. The vertexFormat parameter is a mask indicating
which vertex components are present in each vertex. The indexCount parameter
specifies the number of indices in this array. The stripIndexCounts parameter
is an array that specifies the count of the number of indices for each separate
strip. The length of this array specifies the number of separate strips. The sum of
the index counts for all strips, as specified by the stripIndexCounts array, must
equal the total count of all indices as specified by the indexCount parameter.

public IndexedGeometryStripArray(int vertexCount,

int vertexFormat, int texCoordSetCount,
int[] texCoordSetMap, int indexCount,
int[] stripIndexCounts) New in 1.2

216 The Java 3D API Specification

NODE COMPONENT OBJECTS IndexedLineStripArray Object 8.2.17

Constructs an empty IndexedGeometryStripArray object with the specified num-

ber of vertices, vertex format, number of texture coordinate sets, texture coordi-
nate mapping array, number of indices, and array of per-strip index counts.

Methods
The IndexedGeometryArrayStrip object has the following methods.

public int getNumStrips()

Gets the number of strips in the IndexedGeometryStripArray.

public void getStripIndexCounts(int stripIndexCounts[])

Gets a list of the indexCounts for each strip.

8.2.17 IndexedLineStripArray Object

The IndexedLineStripArray extends IndexedGeometryStripArray and provides
no additional methods. Objects of this class draw an array of vertices as a set of
connected line strips. An array of per-strip index counts specifies where the sep-
arate strips appear in the indexed vertex array. For every strip in the set, each ver-
tex, beginning with the second vertex in the array, defines a line segment to be
drawn from the previous vertex to the current vertex.

Constructors
The IndexedLineStripArray object has the following constructors.

public IndexedLineStripArray(int vertexCount, int vertexFormat,

int indexCount, int stripIndexCounts[])

Constructs an empty IndexedLineStrip object with the specified number of verti-

ces, vertex format, number of indices in this array, and an array that specifies
number of indices for each strip. The vertexFormat parameter is a mask indicat-
ing which components are present in each vertex. This is specified as one or
more individual flags that are bitwise ORed together to describe the per-vertex
data (see Section 8.2.1, “GeometryArray Object,” for a description of the sup-
ported vertex formats).

Version 1.2, March 2000 217

8.2.18 IndexedTriangleStripArray Object NODE COMPONENT OBJECTS

public IndexedLineStripArray(int vertexCount, int vertexFormat,

int texCoordSetCount, int[] texCoordSetMap, int indexCount,
int[] stripIndexCounts) New in 1.2

Constructs an empty IndexedLineStripArray object with the specified number of

vertices, vertex format, number of texture coordinate sets, texture coordinate
mapping array, number of indices, and array of per-strip index counts.

8.2.18 IndexedTriangleStripArray Object

The IndexedTriangleStripArray extends IndexedGeometryStripArray and pro-
vides no additional methods. Objects of this class draw an array of vertices as a
set of connected triangle strips. An array of per-strip index counts specifies
where the separate strips appear in the indexed vertex array. For every strip in the
set, each vertex, beginning with the third vertex in the array, defines a triangle to
be drawn using the current vertex and the two previous vertices.

Constructors
The IndexedTriangleStripArray object has the following constructors.

public IndexedTriangleStripArray(int vertexCount,

int vertexFormat, int indexCount, int stripIndexCounts[])

Constructs an empty IndexedTriangleStripArray object with the specified number

of vertices, vertex format, number of indices in this array, and an array of index
counts per strip. The vertexFormat parameter is a mask indicating which com-
ponents are present in each vertex. This is specified as one or more individual
flags that are bitwise ORed together to describe the per-vertex data (see
Section 8.2.1, “GeometryArray Object,” for a description of the supported vertex
formats).

public IndexedTriangleStripArray(int vertexCount,

int vertexFormat, int texCoordSetCount,
int[] texCoordSetMap, int indexCount,
int[] stripIndexCounts) New in 1.2

Constructs an empty IndexedTriangleStripArray object with the specified number

of vertices, vertex format, number of texture coordinate sets, texture coordinate
mapping array, number of indices, and array of per-strip index counts.

8.2.19 IndexedTriangleFanArray Object

The IndexedTriangleFanArray extends IndexedGeometryStripArray and provides
no additional methods. Objects of this class draw an array of vertices as a set of

218 The Java 3D API Specification

NODE COMPONENT OBJECTS CompressedGeometry Object 8.2.20

connected triangle fans. An array of per-strip index counts specifies where the
separate strips (fans) appear in the indexed vertex array. For every strip in the set,
each vertex, beginning with the third vertex in the array, defines a triangle to be
drawn using the current vertex, the previous vertex, and the first vertex. This can
be thought of as a collection of convex polygons.

Constructors
The IndexedTriangleFanArray object has the following constructors.

public IndexedTriangleFanArray(int vertexCount, int vertexFormat,

int indexCount, int stripIndexCounts[])

Constructs an empty IndexedTriangleFanArray object with the specified number

of vertices, vertex format, number of indices in this array, and an array of index
counts per strip. The vertexFormat parameter is a mask indicating which com-
ponents are present in each vertex. This is specified as one or more individual
flags that are bitwise ORed together to describe the per-vertex data (see
Section 8.2.1, “GeometryArray Object,” for a description of the supported vertex
formats).

public IndexedTriangleFanArray(int vertexCount, int vertexFormat,

int texCoordSetCount, int[] texCoordSetMap, int indexCount,
int[] stripIndexCounts) New in 1.2

Constructs an empty IndexedTriangleFanArray object with the specified number

of vertices, vertex format, number of texture coordinate sets, texture coordinate
mapping array, number of indices, and array of per-strip index counts.

8.2.20 CompressedGeometry Object

The CompressedGeometry object is used to store geometry in a compressed for-
mat. CompressedGeometry objects use a special format for representing geomet-
ric information in one order of magnitude less space. The representation, though
lossy, preserves significant object quality during compression. There will be
parameters to allow the user to specify the degree of lossy-ness (for example, a
space versus quality knob).
For more information, see Appendix B, “3D Geometry Compression.”
Compressed geometry may be passed to this CompressedGeometry object in one
of two ways: by copying the data into this object using the existing constructor
or by passing a reference to the data.

Version 1.2, March 2000 219

8.2.20 CompressedGeometry Object NODE COMPONENT OBJECTS

• By copying: The existing CompressedGeometry constructor copies the

buffer of compressed geometry data into this CompressedGeometry ob-
ject. This is appropriate for many applications, and allows Java 3D to ver-
ify the data once and then not worry about it again.the data once and then
not worry about it again.
• By reference: A new constructor and set of methods in Java 3D version
1.2 allows compressed geometry data to be accessed by reference, directly
from the user’s array. To use this feature, you need to construct a Com-
pressedGeometry object with the byReference flag set to true. In this
mode, a reference to the input data is saved, but the data itself is not nec-
essarily copied. Note that the compressed geometry header is still copied
into this compressed geometry object. Data referenced by a Com-
pressedGeometry object must not be modified after the CompressedGeom-
etry object has been constructed. Applications must exercise care not to
violate this rule. If any referenced compressed geometry data is modified
after construction, the results are undefined.

Constants
The CompressedGeometry object specifies the following variables.

public static final int ALLOW_COUNT_READ

public static final int ALLOW_HEADER_READ
public static final int ALLOW_GEOMETRY_READ

These flags, when enabled using the setCapability method, allow an applica-
tion to invoke methods that read its individual component field information.

public static final int ALLOW_REF_DATA_READ New in 1.2

This flag specifies that this CompressedGeometry allows reading the geometry
data reference information for this object. This is only used in by-reference
geometry mode.

Constructors

public CompressedGeometry(CompressedGeometryHeader hdr,

byte geometry[])

Constructs a CompressedGeometry NodeComponent by copying the specified

compressed geometry data into this object. The hdr field is copied into the Com-
pressedGeometry object. The geometry parameter must conform to the com-
pressed geometry format as described in Appendix B, “3D Geometry
Compression.” If the version number of compressed geometry, as specified by

220 The Java 3D API Specification

NODE COMPONENT OBJECTS CompressedGeometry Object 8.2.20

the CompressedGeometryHeader, is incompatible with the supported version of

compressed geometry in the current version of Java 3D, the compressed geome-
try obejct will not be rendered.

public CompressedGeometry(CompressedGeometryHeader hdr,

byte[] compressedGeometry, boolean byReference) New in 1.2

Creates a new CompressedGeometry NodeComponent. The specified com-

pressed geometry data is either copied into this object or is accessed by refer-
ence. If the version number of compressed geometry, as specified by the
CompressedGeometryHeader, is incompatible with the supported version of
compressed geometry in the current version of Java 3D, the compressed geome-
try obejct will not be rendered.

Methods

public int getByteCount()

This method retrieves the size, in bytes, of the compressed geometry buffer.

public void getCompressedGeometryHeader

(CompressedGeometryHeader hdr)

This method retrieves the header for this CompressedGeometry object (see
Section 8.2.21, “CompressedGeometryHeader Object”). The header is copied
into the CompressedGeometryHeader object provided.

public void getCompressedGeometry(byte compGeom[])

This method retrieves the compressed geometry associated with the Com-
pressedGeometry object. Copies the compressed geometry from the Com-
pressedGeometry object into the given array.

public byte[] getCompressedGeometryRef() New in 1.2

This method retrieves the compressed geometry data reference with which this
CompressedGeometry object was constructed. It is only valid in by-reference
mode.

public Shape3D[] decompress()

This method decompresses the compressed geometry. Returns an array of Shape

nodes containing the decompressed geometry objects.

public boolean isByReference() New in 1.2

This method retrieves the data access mode for this CompressedGeometry object.
Version 1.2, March 2000 221
8.2.21 CompressedGeometryHeader Object NODE COMPONENT OBJECTS

8.2.21 CompressedGeometryHeader Object

The CompressedGeometryHeader object is used in conjunction with the Com-
pressedGeometry object. The CompressedGeometryHeader object contains infor-
mation specific to the compressed geometry data stored in the
CompressedGeometry NodeComponent object. This header is used to aid in the
processing of the compressed geometry by decompression routines. All members
in the CompressedGeometryHeader node are public, so no get or set routines
are provided. The CompressedGeometryHeader object should be created, and all
values set, by the geometry compression utility.

Constants

public static final int POINT_BUFFER

public static final int LINE_BUFFER
public static final int TRIANGLE_BUFFER

These flags indicate whether the compressed geometry is made up of individual

points, line segments, or triangles.

public static final int COLOR_IN_BUFFER

public static final int ALPHA_IN_BUFFER
public static final int NORMAL_IN_BUFFER

These flags indicate whether RGB, alpha color, or normal information is initial-
ized in the compressed geometry buffer.

public int majorVersionNumber

public int minorVersionNumber
public int minorMinorVersionNumber

These indicate the major, minor, and minor-minor version numbers for the com-
pressed geometry format that was used to compress the geometry. If the version
number of compressed geometry is incompatible with the supported version of
compressed geometry in the current version of Java 3D, the compressed geome-
try obejct will not be rendered.

public int bufferType

This flag describes the type of data in the compressed geometry buffer. Only one
type may be present in any given compressed geometry buffer.

public int bufferDataPresent

This flag indicates whether a particular data component (for example, color) is
present in the compressed geometry buffer, preceding any geometric data. If a
222 The Java 3D API Specification
NODE COMPONENT OBJECTS Raster Object 8.2.22

particular data type is not present then this information will be inherited from the
Appearance object.

public int size

This flag indicates the size of the compressed geometry, in bytes, that needs to be
applied to every point in the compressed geometry buffer to restore the geometry
to its original (uncompressed) position.

public int start

This flag contains the offset in bytes of the start of the compressed geometry
from the beginning of the compressed geometry buffer.

public Point3d lowerBound New in 1.2

public Point3d upperBound New in 1.2

These two flags specify two points that specify the upper and lower bounds of
the x, y, and z components for all positions in the compressed geometry buffer. If
null, a lower bound of (–1,–1,–1) and an upper bound of (1,1,1) is assumed. Java
3D will use this information to construct a bounding box around compressed
geometry objects that are used in nodes for which the auto compute bounds flag
is true. The default value for both points is null.

Constructor

public CompressedGeometryHeader()

Creates a new CompressedGeometryHeader object used for the creation of a

CompressedGeometry NodeComponent object. All instance data is declared pub-
lic and no get or set methods are provided. All values are set to 0 by default and
must be filled in by the application.

8.2.22 Raster Object

The Raster object extends Geometry to allow drawing a raster image that is
attached to a 3D location in the virtual world. The Raster object contains a point
that is defined in the local object coordinate system of the Shape3D node that
references the Raster. The Raster object also contains a type specifier, a reference
to an ImageComponent2D object or a DepthComponent object, and an integer
x,y offset and a size (width, height) to allow reading or writing of a portion of the
referenced image. In addition to being used as a type of geometry for drawing, a
Raster object may be used to read back pixel data (color and Z-buffer) from the
frame buffer in immediate mode.

Version 1.2, March 2000 223

8.2.22 Raster Object NODE COMPONENT OBJECTS

The geometric extent of a Raster object is a single 3D point, specified by the ras-
ter position. This means that geometry-based picking or collision with a Raster
object will only intersect the object at this single point; the 2D raster image is
neither pickable nor collidable.

Constants
The Raster object defines the following flags.

public static final int ALLOW_POSITION_READ

public static final int ALLOW_POSITION_WRITE
public static final int ALLOW_OFFSET_READ
public static final int ALLOW_OFFSET_WRITE
public static final int ALLOW_IMAGE_READ
public static final int ALLOW_IMAGE_WRITE
public static final int ALLOW_DEPTH_COMPONENT_READ
public static final int ALLOW_DEPTH_COMPONENT_WRITE
public static final int ALLOW_SIZE_READ
public static final int ALLOW_SIZE_WRITE
public static final int ALLOW_TYPE_READ

These flags specify that the Raster object allows reading or writing of the posi-
tion, offset, image, depth component, or size, or reading of the type.

public static final int RASTER_COLOR

Specifies a Raster object with color data. In this mode, the ImageComponent ref-
erence must point to a valid ImageComponent object.

public static final int RASTER_DEPTH

Specifies a Raster object with depth (Z-buffer) data. In this mode, the depth com-
ponent reference must point to a valid DepthComponent object.

public static final int RASTER_COLOR_DEPTH

Specifies a Raster object with both color and depth (Z-buffer) data. In this mode,
the image component reference must point to a valid ImageComponent object,
and the depth component reference must point to a valid DepthComponent
object.

Constructors

public Raster()

Constructs and initializes a new Raster object with default values:

224 The Java 3D API Specification

NODE COMPONENT OBJECTS Raster Object 8.2.22

Parameter Default Value

type RASTER_COLOR
pos (0,0,0)
offset (0,0)
size (0,0)
image null
depthComponent null

public Raster(Point3f pos, int type, int xOffset, int yOffset,

int width, int height, ImageComponent2D image,
DepthComponent depthComponent)
public Raster(Point3f pos, int type, Point offset, Dimension size,
ImageComponent2D image, DepthComponent depthComponent)

Constructs and initializes a new Raster object with the specified values.

Methods

public void setPosition(Point3f pos)

public void getPosition(Point3f pos)

These methods set and retrieve the position, in object coordinates, of this raster.
This position is transformed into device coordinates and is used as the upper-left
corner of the raster.

public void setType(int type)

public int getType()

These methods set and retrieve the type of this Raster object. The type is one of
the following: RASTER_COLOR, RASTER_DEPTH, or RASTER_COLOR_DEPTH.

public void setOffset(int xOffset, int yOffset)

public void setOffset(Point offset)
public void getOffset(Point offset)

These methods set and retrieve the offset within the array of pixels at which to
start copying.

public void setSize(int width, int height)

public void setSize(Dimension size)
public void getSize(Dimension size)

These methods set and retrieve the number of pixels to be copied from the pixel
array.

Version 1.2, March 2000 225

8.2.23 Font3D Object NODE COMPONENT OBJECTS

public void setImage(ImageComponent2D image)

public ImageComponent2D getImage()

These methods set and retrieve the pixel array used to copy pixels to or from a
Canvas3D. This is used when the type is RASTER_COLOR or RASTER_
COLOR_DEPTH.

public void setDepthComponent(DepthComponent depthComponent)

public DepthComponent getDepthComponent()

These methods set and retrieve the DepthComponent used to copy pixels to or
from a Canvas3D. This is used when the type is RASTER_DEPTH or RASTER_
COLOR_DEPTH.

8.2.23 Font3D Object

The Font3D object is used to contain 3D glyphs used in rendering 3D text. These
3D glyphs are constructed from a Java 2D font object and a FontExtrusion object
(see Section 8.2.24, “FontExtrusion Object”). To ensure correct rendering, the
2D font object should be created with the default transform.
A 3D Font consists of a Java 2D font, a tessellation tolerance, and an extrusion
path. The extrusion path describes how the edge of a glyph varies in the Z axis.

Constructors

public Font3D(java.awt.Font font, FontExtrusion extrudePath)

Creates a Font3D object from the specified Font and FontExtrusion objects,
using the default value for the tesselation tolerance. The default value is as fol-
lows:

Parameter Default Value

Tesselation tolerance 0.01

The FontExtrusion object (see Section 8.2.24, “FontExtrusion Object”) contains

the extrusion path to use on the 2D font glyphs. To ensure correct rendering, the
font must be created with the default AffineTransform. Passing null for the Fon-
tExtrusion parameter results in no extrusion being done.

public Font3D(Font font, double tessellationTolerance,

FontExtrusion extrudePath) New in 1.2

Creates a Font3D object from the specified Font and FontExtrusion objects,
using the specified tessellation tolerance. The FontExtrusion object (see

226 The Java 3D API Specification

NODE COMPONENT OBJECTS FontExtrusion Object 8.2.24

Section 8.2.24, “FontExtrusion Object”) contains the extrusion path to use on the
2D Font glyphs. To ensure correct rendering the font must be created with the
default AffineTransform. Passing null for the FontExtrusion parameter results in
no extrusion being done. The tessellationTolerance parameter corresponds
to the flatness parameter in the java.awt.Shape.getPathIterator method.

Methods

public void getBoundingBox(int glyphCode, BoundingBox bounds)

This method returns the 3D bounding box of the specified glyph code.

public Font getFont()

This method returns the Java 2D font used to create this Font3D object.

public void getFontExtrusion(FontExtrusion extrudePath)

This method retrieves the FontExtrusion object used to create this Font3D object
and copies it into the specified parameter. For information about the FontExtru-
sion object, see Section 8.2.24, “FontExtrusion Object.”

public double getTessellationTolerance() New in 1.2

This method returns the tessellation tolerance with which this Font3D was cre-
ated.

8.2.24 FontExtrusion Object

The FontExtrusion object is used to describe the extrusion path for a Font3D
object (see Section 8.2.23, “Font3D Object”). The extrusion path is used in con-
junction with a Font2D object. The extrusion path defines the edge contour of 3D
text. This contour is perpendicular to the face of the text. The contour has its ori-
gin at the edge of the glyph, with 1.0 being the height of the tallest glyph. Con-
tour must be monotonic in x. The user is responsible for data sanity and must
make sure that extrusionShape does not cause intersection of adjacent glyphs or
within a single glyph, else undefined output may be generated.

Constructors

public FontExtrusion()

Creates a FontExtrusion object with default parameters. The default parameters

are as follows:

Version 1.2, March 2000 227

8.2.25 Text3D Geometry Object NODE COMPONENT OBJECTS

Parameter Default Value

Extrusion shape null
Tesselation tolerance 0.01

A null extrusion shape specifies that a straight line from 0.0 to 0.2 (straight
bevel) is used.

public FontExtrusion(java.awt.Shape extrusionShape)

Creates a FontExtrusion object with the specified extrusion shape, using the
default tesselation tolerance. The extrusionShape parameter is used to construct
the edge contour of a Font3D object. Each shape begins with an implicit point at
0.0. Contour must be monotonic in x. An IllegalArgumentException is thrown if
multiple contours in extrusionShape, or contour is not monotonic, or least x-
value of a contour point is not 0.0f.

public FontExtrusion(Shape extrusionShape,

double tessellationTolerance) New in 1.2

Creates a FontExtrusion object with the specified shape, using the specified tes-
sellation tolerance. The specified shape is used to construct the edge contour of a
Font3D object. Each shape begins with an implicit point at 0.0. Contour must be
monotonic in x. The tessellationTolerance parameter corresponds to the
flatness parameter in the java.awt.Shape.getPathIterator method.

Methods

public void setExtrusionShape(java.awt.Shape extrusionShape)

public java.awt.Shape getExtrusionShape()

These methods set and retrieve the 2D shape object associated with this FontEx-
trusion object. The Shape object describes the extrusion path used to create a 3D
glyph from a 2D glyph. The set method sets the FontExtrusion's shape parame-
ter. the get method gets the FontExtrusion's shape parameter.

public double getTessellationTolerance() New in 1.2

This method returns the tessellation tolerance with which this FontExtrusion was
created.

8.2.25 Text3D Geometry Object

A Text3D object is a text string that has been converted to 3D geometry. The
Font3D object (see Section 8.2.23, “Font3D Object”) determines the appearance

228 The Java 3D API Specification

NODE COMPONENT OBJECTS Text3D Geometry Object 8.2.25

of the Text3D NodeComponent object. Each Text3D object has a text position—
a point in 3D space where the text should be placed. The 3D text can be placed
around this position using different alignments and paths. An OrientedShape3D
node may also be used for drawing screen-aligned text (see Section 6.2.1,
“OrientedShape3D Node”).
If 3D texture mapping is not supported on a particular Canvas3D, 3D texture
mapping is ignored for that canvas.

Constants
The Text3D object defines the following flags.

public static final int ALLOW_FONT3D_READ

public static final int ALLOW_FONT3D_WRITE
public static final int ALLOW_STRING_READ
public static final int ALLOW_STRING_WRITE
public static final int ALLOW_POSITION_READ
public static final int ALLOW_POSITION_WRITE
public static final int ALLOW_ALIGNMENT_READ
public static final int ALLOW_ALIGNMENT_WRITE
public static final int ALLOW_PATH_READ
public static final int ALLOW_PATH_WRITE
public static final int ALLOW_CHARACTER_SPACING_READ
public static final int ALLOW_CHARACTER_SPACING_WRITE
public static final int ALLOW_BOUNDING_BOX_READ

These flags control reading and writing of the Font3D component information
for Font3D, the String object, the text position value, the text alignment value,
the text path value, the character spacing, and the bounding box.

Constructors

public Text3D()

Create a new Text3D object with default parameters:

Parameter Default Value

font3D null
string null
position (0,0,0)
alignment ALIGN_FIRST
path PATH_RIGHT
characterSpacing 0.0

Version 1.2, March 2000 229

8.2.25 Text3D Geometry Object NODE COMPONENT OBJECTS

public Text3D(Font3D font3D)

public Text3D(Font3D font3D, String string)
public Text3D(Font3D font3D, String string, Point3f position)
public Text3D(Font3D font3D, String string, Point3f position,
int alignment, int path)

Create a new Text3D object with the defined parameters.

Methods

public Font3D getFont3D()

public void setFont3D(Font3D font3d)

These methods get and set the Font3D object associated with this Text3D object.

public String getString()

public void setString(String string)

These methods get and set the character string associated with this Text3D
object.

public void getPosition(Point3f position)

public void setPosition(Point3f position)

These methods get and set the text position. The position parameter is used to
determine the initial placement of the string. The text position is used in conjunc-
tion with the alignment and path to determine how the glyphs are to be placed in
the scene. The default value is (0.0, 0.0, 0.0).

public void setAlignment(int alignment)

public int getAlignment()

These methods set and get the text alignment policy for this Text3D NodeCom-
ponent object (see Figure 8-4). The alignment parameter is used to specify how
glyphs in the string are placed in relation to the position field. Valid values for
the alignment field are:
• ALIGN_CENTER: places the center of the string on the position point.
• ALIGN_FIRST: places the first character of the string on the position
point.
• ALIGN_LAST: places the last character of the string on the position point.
The default value of this field is ALIGN_FIRST.

230 The Java 3D API Specification

NODE COMPONENT OBJECTS Text3D Geometry Object 8.2.25

public void setPath(int path)

public int getPath()

These methods set and get the node’s path field. This field is used to specify how
succeeding glyphs in the string are placed in relation to the previous glyph (see
Figure 8-4). The path is relative to the local coordinate system of the Text3D
node. The default coordinate system (see Section 4.4, “Coordinate Systems”) is
right-handed with +Y being up, +X horizontal to the right, and +Z directed
toward the viewer. Valid values for this field are as follows:
• PATH_LEFT: places succeeding glyphs to the left (the –X direction) of the
current glyph.
• PATH_RIGHT: places succeeding glyphs to the right (the +X direction) of
the current glyph.
• PATH_UP: places succeeding glyphs above (the +Y direction) the current
glyph.
• PATH_DOWN: places succeeding glyphs below (the –Y direction) the cur-
rent glyph.
The default value of this field is PATH_RIGHT.

public void getBoundingBox(BoundingBox bounds)

This method retrieves the 3D bounding box that encloses this Text3D object.

ALIGN_FIRST ALIGN_CENTER ALIGN_LAST

PATH_RIGHT PATH_RIGHT PATH_RIGHT

TFEL_HTAP TFEL_HTAP TFEL_HTAP

P .P D
U U O
. W
. D
D N
.O .
O W .
W N P
N U
= Text position point

Figure 8-4 Various Text Alignments and Paths

Version 1.2, March 2000 231

8.3 Math Component Objects NODE COMPONENT OBJECTS

public void setCharacterSpacing(float characterSpacing)

public float getCharacterSpacing()

These methods set and get the character spacing used to construct the Text3D
string. This spacing is in addition to the regular spacing between glyphs as
defined in the Font object. A value of 1.0 in this space is measured as the width
of the largest glyph in the 2D font. The default value is 0.0.

8.3 Math Component Objects

Java 3D defines a number of additional objects that are used in the construction
and manipulation of other Java 3D objects. These objects provide low-level stor-
age and manipulation control for users. They provide methods for representing
vertex components (for example, color and position), volumes, vectors, and
matrices.
The tuple and matrix math classes are not part of Java 3D per se, but they are
needed by Java 3D and are defined here for convenience. Java 3D uses these
classes internally and also makes them available for use by applications. These
classes will be delivered in a separate javax.vecmath package. The tuple and
matrix math classes are described in detail in Appendix A, “Math Objects.”

8.3.1 Tuple Objects

The tuple objects, listed in Table 8-1, store tuples of length two, three, and four.
Java 3D tuples are used to store various kinds of information such as colors, nor-
mals, texture coordinates, vertices, and so forth.
The tuple classes are further subdivided by storage type, such as point, vector,
color, and so forth, and by class—whether the vector consists of single- or dou-
ble-precision floating-point numbers or bytes. Only the floating-point tuple
classes support math operations.
Table 8-1 Tuple Objects
Class Description
Tuple2d Used to represent two-component coordinates in double-precision floating-point
format. This class is further divided into the following:
Point2d: Represents x,y point coordinates.
Vector2d: Represents x,y vector coordinates.

232 The Java 3D API Specification

NODE COMPONENT OBJECTS Tuple Objects 8.3.1

Table 8-1 Tuple Objects (Continued)

Class Description
Tuple2f Used to represent two-component coordinates in single-precision floating-point
format. This class is further divided into the following:
Point2f: Represents x,y point coordinates.
TexCoord2f: Represents x,y texture coordinates.
Vector2f: Represents x,y vector coordinates.
Tuple3b Used to represent three-component color information stored as three bytes. This class
is further divided into the following:
Color3b: Represents RGB color values.
Tuple3d Used to represent point and vector coordinates in double-precision floating-point
format. This class is further divided into the following:
Point3d: Represents x,y,z point coordinates.
Vector3d: Represents x,y,z vector coordinates.
Tuple3f Used to represent three-component colors, point coordinates, texture coordinates, and
vectors in single-precision floating-point format. This class is further divided into the
following:
Color3f: Represents RGB color values.
Point3f: Represents x,y,z point coordinates.
TexCoord3f: Represents x,y,z texture coordinates.
Vector3f: Represents x,y,z vector coordinates.
Tuple3i Used to represent three-component point coordinates in signed integer format. This
class is further divided into the following:
Point3i: Represents x,y,z point coordinates.
Tuple4b Used to represent four-component color information stored as four bytes. This class is
further divided into the following:
Color4b: Represents RGBα color values.
Tuple4d Used to represent four-component color information, quaternions, and vectors stored
in double-precision floating-point format. This class is further divided into the
following:
Point4d: Represents x,y,z,w point coordinates.
Quat4d: Represents x,y,z,w quaternion coordinates.
Vector4d: Represents x,y,z,w vector coordinates.
Tuple4f Used to represent four-component color information, point coordinates, quaternions,
and vectors in single-precision floating-point format. This class is further divided into
the following:
Color4f: Represents RGBα color values.
Point4f: Represents x,y,z,w point coordinates.
Quat4f: Represents x,y,z,w quaternion coordinates.
Vector4f: Represents x,y,z,w vector coordinates.
Tuple4i Used to represent four-component point coordinates in signed integer format. This
class is further divided into the following:
Point4i: Represents x,y,z,w point coordinates.

Version 1.2, March 2000 233

8.3.2 Matrix Objects NODE COMPONENT OBJECTS

Table 8-1 Tuple Objects (Continued)

Class Description
AxisAngle4d Used to represent four-component axis-angle rotations consisting of double-precision
floating-point x, y, and z coordinates and a rotation angle in radians.
AxisAngle4f Used to represent four-component axis-angle rotations consisting of single-precision
floating point x, y, and z coordinates and a rotation angle in radians.
GVector Used to represent a general, dynamically resizeable, one-dimensional vector class.

These are described in more detail in Appendix A, “Math Objects.”

8.3.2 Matrix Objects

The matrix objects, listed in Table 8-2, define a complete 3 × 3 or 4 × 4 floating-
point transformation matrix. All the vector subclasses operate using this one
matrix type.
Table 8-2 Matrix Objects
Class Description
Matrix3d Used to represent a double-precision floating-point 3 × 3 matrix.
Matrix3f Used to represent a single-precision floating-point 3 × 3 matrix.
Matrix4d Used to represent a double-precision floating-point 4 × 4 matrix.
Matrix4f Used to represent a single-precision floating-point 4 × 4 matrix.
GMatrix A double-precision, general, dynamically resizeable N × M matrix class.

These are described in more detail in Appendix A, “Math Objects.”

234 The Java 3D API Specification

 C H A P T E R 9
View Model

JAVA 3D introduces a new view model that takes Java’s vision of “write once,
run anywhere” and generalizes it to include display devices and six-degrees-of-
freedom input peripherals such as head trackers. This “write once, view every-
where” nature of the new view model means that an application or applet written
using the Java 3D view model can render images to a broad range of display
devices, including standard computer displays, multiple-projection display
rooms, and head-mounted displays, without modification of the scene graph. It
also means that the same application, once again without modification, can ren-
der stereoscopic views and can take advantage of the input from a head tracker to
control the rendered view.
Java 3D’s view model achieves this versatility by cleanly separating the virtual
and the physical world. This model distinguishes between how an application
positions, orients, and scales a ViewPlatform object (a viewpoint) within the vir-
tual world and how the Java 3D renderer constructs the final view from that
viewpoint’s position and orientation. The application controls the ViewPlatform’s
position and orientation; the renderer computes what view to render using this
position and orientation, a description of the end-user’s physical environment,
and the user’s position and orientation within the physical environment.
This chapter first explains why Java 3D chose a different view model and some
of the philosophy behind that choice. It next describes how that model operates
in the simple case of a standard computer screen without head tracking—the
most common case. Finally, it presents the relevant parts of the API from a
developer’s perspective. Appendix C, “View Model Details,” describes the
Java 3D view model from an advanced developer and Java 3D implementor’s
perspective.

Version 1.2, March 2000 235

9.1 Why a New Model? VIEW MODEL

9.1 Why a New Model?

Camera-based view models as found in low-level APIs give developers control
over all rendering parameters. This makes sense when dealing with custom appli-
cations, less sense when dealing with systems that wish to have broader applica-
bility: systems such as viewers or browsers that load and display whole worlds as
a single unit or systems where the end users view, navigate, display, and even
interact with the virtual world.
Camera-based view models emulate a camera in the virtual world, not a human
in a virtual world. Developers must continuously reposition a camera to emulate
“a human in the virtual world.”
The Java 3D view model incorporates head tracking directly, if present, with no
additional effort from the developer, thus providing end users with the illusion
that they actually exist inside a virtual world.
The Java 3D view model, when operating in a non-head-tracked environment and
rendering to a single, standard display, acts very much like a traditional camera-
based view model, with the added functionality of being able to transparently
generate stereo views.

9.1.1 The Physical Environment Influences the View

Letting the application control all viewing parameters is not reasonable in sys-
tems in which the physical environment dictates some of the view parameters.
One example of this is a head-mounted display (HMD), where the optics of the
head-mounted display directly determine the field of view that the application
should use. Different HMDs have different optics, making it unreasonable for
application developers to hard-wire such parameters or allow end users to vary
that parameter at will.
Another example is a system that automatically computes view parameters as a
function of the user’s current head position. The specification of a world and a
predefined flight path through that world may not exactly specify an end-user’s
view. HMD users would expect to look and thus see to their left or right even
when following a fixed path through the environment—imagine an amusement
park ride with vehicles that follow fixed paths to present content to their visitors,
but visitors can continue to move their heads while on those rides.
Depending on the physical details of the end-user’s environment, the values of
the viewing parameters, particularly the viewing and projection matrices, will
vary widely. The factors that influence the viewing and projection matrices

236 The Java 3D API Specification

VIEW MODEL The Physical World 9.2.2

include the size of the physical display, how the display is mounted (on the user’s
head or on a table), whether the computer knows the user’s head location in three
space, the head mount’s actual field of view, the display’s pixels per inch, and
other such parameters. For more information, see Appendix C, “View Model
Details.”

9.2 Separation of Physical and Virtual

The Java 3D view model separates the virtual environment, where the application
programmer has placed objects in relation to one another, from the physical envi-
ronment, where the user exists, sees computer displays, and manipulates input
devices.
Java 3D also defines a fundamental correspondence between the user’s physical
world and the virtual world of the graphic application. This physical-to-virtual-
world correspondence defines a single common space, a space where an action
taken by an end user affects objects within the virtual world and where any activ-
ity by objects in the virtual world affects the end-user’s view.

9.2.1 The Virtual World

The virtual world is a common space in which virtual objects exist. The virtual
world coordinate system exists relative to a high-resolution Locale—each Locale
object defines the origin of virtual world coordinates for all of the objects
attached to that Locale. The Locale that contains the currently active
ViewPlatform object defines the virtual world coordinates that are used for ren-
dering. Java3D eventually transforms all coordinates associated with scene graph
elements into this common virtual world space.

9.2.2 The Physical World

The physical world is just that—the real, physical world. This is the space in
which the physical user exists, and within which he or she moves his or her head
and hands. This is the space in which any physical trackers define their local
coordinates, and in which several calibration coordinate systems are described.
The physical world is a space, not a common coordinate system between differ-
ent execution instances of Java 3D. So while two different computers at two dif-
ferent physical locations on the globe may be running at the same time, there is
no mechanism directly within Java 3D to relate their local physical world coordi-
nate systems with each other. Because of calibration issues, the local tracker (if

Version 1.2, March 2000 237

9.3 The Objects That Define the View VIEW MODEL

any) defines the local physical world coordinate system known to a particular
instance of Java 3D.

9.3 The Objects That Define the View

Java 3D distributes its view model parameters across several objects, specifically,
the View object and its associated component objects, the PhysicalBody object,
the PhysicalEnvironment object, the Canvas3D object, and the Screen3D object.
Figure 9-1 shows graphically the central role of the View object and the subsid-
iary role of its component objects.

Virtual universe

Hi-res locale

BG

View Canvas3D Screen3D

VP
View
Platform

Physical Physical
Body Environment

Figure 9-1 View Object, Its Component Objects, and Their Interconnection

The view-related objects shown in Figure 9-1 and their roles are as follows. For
each of these objects, the portion of the API that relates to modifying the virtual
world and the portion of the API that is relevant to non-head-tracked standard
display configurations are derived in this chapter. The remainder of the details
are described in Appendix C, “View Model Details.”
• ViewPlatform: A leaf node that locates a view within a scene graph. The
ViewPlatform’s parents specify its location, orientation, and scale within

238 The Java 3D API Specification

VIEW MODEL ViewPlatform: A Place in the Virtual World 9.4

the virtual universe. See Section 6.11, “ViewPlatform Node,” and

Section 9.4, “ViewPlatform: A Place in the Virtual World,” for more infor-
mation.
• View: The main view object. It contains many pieces of view state. See
Section 9.7, “The View Object,” for more information.
• Canvas3D: The 3D version of the Abstract Windowing Toolkit (AWT)
Canvas object. It represents a window in which Java 3D will draw images.
It contains a reference to a Screen3D object and information describing the
Canvas3D’s size, its shape, and its location within the Screen3D object.
See Section 9.9, “The Canvas3D Object,” for more information.
• Screen3D: An object that contains information describing the display
screen’s physical properties. Java 3D places display-screen information in
a separate object to prevent the duplication of screen information within
every Canvas3D object that shares a common screen. See Section 9.8,
“The Screen3D Object,” for more information.
• PhysicalBody: An object that contains calibration information describing
the user’s physical body. See Section 9.10, “The PhysicalBody Object,”
for more information.
• PhysicalEnvironment: An object that contains calibration information de-
scribing the physical world, mainly information that describes the environ-
ment’s six-degrees-of freedom tracking hardware, if present. See
Section 9.11, “The PhysicalEnvironment Object,” for more information.
Together, these objects describe the geometry of viewing rather than explicitly
providing a viewing or projection matrix. The Java 3D renderer uses this infor-
mation to construct the appropriate viewing and projection matrices. The geo-
metric focus of these view objects provides more flexibility in generating
views—a flexibility needed to support alternative display configurations.

9.4 ViewPlatform: A Place in the Virtual World

A ViewPlatform leaf node defines a coordinate system, and thus a reference
frame with its associated origin or reference point, within the virtual world. The
ViewPlatform serves as a point of attachment for View objects and as a base for
determining a renderer’s view.
Figure 9-2 shows a portion of a scene graph containing a ViewPlatform node.
The nodes directly above a ViewPlatform determine where that ViewPlatform is
located and how it is oriented within the virtual world. By modifying the
Transform3D object associated with a TransformGroup node anywhere directly

Version 1.2, March 2000 239

9.4.1 Moving Through the Virtual World VIEW MODEL

above a ViewPlatform, an application or behavior can move that ViewPlatform

anywhere within the virtual world. A simple application might define one Trans-
formGroup node directly above a ViewPlatform, as shown in Figure 9-2.
A VirtualUniverse may have many different ViewPlatforms, but a particular View
object can only attach itself to a single ViewPlatform. Thus, each rendering onto
a Canvas3D is done from the point of view of a single ViewPlatform.

Virtual Universe

Hi-res Locale

BranchGroup BG

TransformGroup TG

ViewPlatform View Canvas3D Screen3D

VP

Physical Physical
Body Environment

Figure 9-2 A Portion of a Scene Graph Containing a ViewPlatform Object

9.4.1 Moving Through the Virtual World

An application navigates within the virtual world by modifying a ViewPlatform’s
parent TransformGroup. Examples of applications that modify a ViewPlatform’s
location and orientation include browsers, object viewers that provide naviga-
tional controls, applications that do architectural walkthroughs, and even search-
and-destroy games.
Controlling the ViewPlatform object can produce very interesting and useful
results. Our first simple scene graph (see Figure 1-2) defines a scene graph for a
simple application that draws an object in the center of a window and rotates that

240 The Java 3D API Specification

VIEW MODEL Dropping In on a Favorite Place 9.4.2

object about its center point. In that figure, the Behavior object modifies the
TransformGroup directly above the Shape3D node.
An alternative application scene graph, shown in Figure 9-3, leaves the central
object alone and moves the ViewPlatform around the world. If the shape node
contains a model of the earth, this application could generate a view similar to
that seen by astronauts as they orbit the earth.
Had we populated this world with more objects, this scene graph would allow
navigation through the world via the Behavior node.

Virtual Universe

Locale Object

BG BG BranchGroup Nodes

T Behavior Node B BranchTransformGroup

T
Nodes
Shape3D Nodes User code
S
and data View
VP
ViewPlatform Object

Appearance Geometry Other Objects

Figure 9-3 A Simple Scene Graph with View Control

Applications and behaviors manipulate a TransformGroup through its access

methods. These methods (defined in Section 5.3, “TransformGroup Node”) allow
an application to retrieve and set the Group node’s Transform3D object.
Transform3D Node methods include getTransform and setTransform.

9.4.2 Dropping In on a Favorite Place

A scene graph may contain multiple ViewPlatform objects. If a user detaches a
View object from a ViewPlatform and then reattaches that View to a different
ViewPlatform, the image on the display will now be rendered from the point of
view of the new ViewPlatform. For more information, see Section 9.7, “The
View Object.”

Version 1.2, March 2000 241

9.4.3 View Attach Policy VIEW MODEL

9.4.3 View Attach Policy

The actual view that Java 3D’s renderer draws depends on the view attach policy
specified within the currently attached ViewPlatform. The ViewPlatform defines
the following methods for setting and retrieving the view attach policy.

Methods

public void setViewAttachPolicy(int policy)

public int getViewAttachPolicy()

These methods set and retrieve the coexistence center in virtual world policy.
The default attach policy is View.NOMINAL_HEAD. A ViewPlatform’s view attach
policy determines how Java 3D places the virtual eyepoint within the
ViewPlatform. The policy can have one of the following values:
• View.NOMINAL_HEAD: Ensures that the end-user’s nominal eye posi-
tion in the physical world corresponds to the virtual eye’s nominal eye po-
sition in the virtual world (the ViewPlatform’s origin). In essence, this
policy tells Java 3D to position the virtual eyepoint relative to the
ViewPlatform origin in the same way as the physical eyepoint is positioned
relative to its nominal physical-world origin. Deviations in the physical
eye’s position and orientation from nominal in the physical world generate
corresponding deviations of the virtual eye’s position and orientation in the
virtual world.
• View.NOMINAL_FEET: Ensures that the end-user’s virtual feet always
touch the virtual ground. This policy tells Java 3D to compute the physical-
to-virtual-world correspondence in a way that enforces this constraint.
Java 3D does so by appropriately offsetting the physical eye’s position by
the end-user’s physical height. Java 3D uses the nominalEyeHeightFrom-
Ground parameter found in the PhysicalBody object (see Section 9.10,
“The PhysicalBody Object”) to perform this computation.
• View.NOMINAL_SCREEN: Allows an application to always have the vir-
tual eyepoint appear at some “viewable” distance from a point of interest.
This policy tells Java 3D to compute the physical-to-virtual-world corre-
spondence in a way that ensures that the renderer moves the nominal vir-
tual eyepoint away from the point of interest by the amount specified by
the nominalEyeOffsetFromNominalScreen parameter found in the Phys-
icalBody object (see Section 9.10, “The PhysicalBody Object”).

242 The Java 3D API Specification

VIEW MODEL Composing Model and Viewing Transformations 9.5.1

9.4.4 Associating Geometry with a ViewPlatform

Java 3D does not have any built-in semantics for displaying a visible manifesta-
tion of a ViewPlatform within the virtual world (an avatar). However, a devel-
oper can construct and manipulate an avatar using standard Java 3D constructs.
A developer can construct a small scene graph consisting of a TransformGroup
node, a behavior leaf node, and a shape node and insert it directly under the
BranchGroup node associated with the ViewPlatform object. The shape node
would contain a geometric model of the avatar’s head. The behavior node would
change the TransformGroup’s transform periodically to the value stored in a
View object’s UserHeadToVworld parameter, (see Appendix C, “View Model
Details”). The avatar’s virtual head, represented by the shape node, will now
move around in lock-step with the ViewPlatform’s TransformGroup and any rel-
ative position and orientation changes of the user’s actual physical head (if a sys-
tem has a head tracker).

9.5 Generating a View

Java 3D generates viewing matrices in one of a few different ways, depending on
whether the end user has a head-mounted or a room-mounted display environ-
ment and whether or not head tracking is enabled. This section describes the
computation for a non-head-tracked, room-mounted display—a standard com-
puter display. Other environments are described in Appendix C, “View Model
Details.”
In the absence of head tracking, the ViewPlatform’s origin specifies the virtual
eye’s location and orientation within the virtual world. However, the eye location
provides only part of the information needed to render an image. The renderer
also needs a projection matrix. In the default mode, Java 3D uses the projection
policy, the specified field-of-view information, and the front and back clipping
distances to construct a viewing frustum.

9.5.1 Composing Model and Viewing Transformations

Figure 9-4 shows a simple scene graph. To draw the object labeled “S,” Java 3D
internally constructs the appropriate model, view platform, eye, and projection
matrices. Conceptually, the model transformation for a particular object is com-
puted by concatenating all the matrices in a direct path between the object and
the VirtualUniverse. The view matrix is then computed—again, conceptually—
by concatenating all the matrices between the VirtualUniverse object and the

Version 1.2, March 2000 243

9.5.1 Composing Model and Viewing Transformations VIEW MODEL

ViewPlatform attached to the current View object. The eye and projection matri-
ces are constructed from the View object and its associated component objects.

Virtual Universe

L Hi-Res Locale

BG

T1 Tv1

T2 View Canvas3D Screen3D

VP

Physical Physical
Body Environment

Figure 9-4 Object and ViewPlatform Transformations

In our scene graph, what we would normally consider the model transformation
would consist of the following three transformations: LT1T2. By multiplying
LT1T2 by a vertex in the shape object, we would transform that vertex into the
virtual universe’s coordinate system. What we would normally consider the view
platform transformation would be (LTv1)–1 or Tv1–1L–1. This presents a problem
since coordinates in the virtual universe are 256-bit fixed-point values, which
cannot be used to efficiently represent transformed points.
Fortunately, however, there is a solution to this problem. Composing the model
and view platform transformations gives us
Tv1–1L–1LT1T2 = Tv1–1IT1T2 = Tv1–1T1T2,
the matrix that takes vertices in an object’s local coordinate system and places
them in the ViewPlatform’s coordinate system. Note that the high-resolution
Locale transformations cancel each other out, which removes the need to actually
transform points into high-resolution VirtualUniverse coordinates. The general
formula of the matrix that transforms object coordinates to ViewPlatform coordi-
nates is Tvn–1…Tv2–1Tv1–1T1T2…Tm.

244 The Java 3D API Specification

VIEW MODEL Multiple Locales 9.5.2

As was mentioned above, the View object contains the remainder of the view
information, specifically, the eye matrix, E, that takes points in the View-
Platform’s local coordinate system and translates them into the user’s eye coordi-
nate system, and the projection matrix, P, that projects objects in the eye’s
coordinate system into clipping coordinates. The final concatenation of matrices
for rendering our shape object “S” on the specified Canvas3D is PETv1–1T1T2. In
general this is PETvn–1…Tv2–1Tv1–1T1T2…Tm.
The details of how Java 3D constructs the matrices E and P in different end-user
configurations are described in Appendix C, “View Model Details.”

9.5.2 Multiple Locales

Java 3D supports multiple high-resolution Locales. In some cases, these Locales
are close enough to each other that they can “see” each other, meaning that
objects can be rendered even though they are not in the same Locale as the
ViewPlatform object that is attached to the View. Java 3D automatically handles
this case without the application having to do anything. As in the previous exam-
ple, where the ViewPlatform and the object being rendered are attached to the
same Locale, Java 3D internally constructs the appropriate matrices for cases in
which the ViewPlatform and the object being rendered are not attached to the
same Locale.
Let’s take two Locales, L1 and L2, with the View attached to a ViewPlatform in
L1. According to our general formula, the modeling transformation—the trans-
formation that takes points in object coordinates and transforms them into Virtu-
alUniverse coordinates—is LT1T2…Tm. In our specific example, a point in
Locale L2 would be transformed into VirtualUniverse coordinates by
L2T1T2…Tm. The view platform transformation would be (L1Tv1Tv1…Tvn)–1 or
Tvn–1…Tv2–1Tv1–1L1–1. Composing these two matrices gives us
Tvn–1…Tv2–1Tv1–1L1–1L2T1T2…Tm.
Thus, to render objects in another Locale, it is sufficient to compute L1–1L2 and
use that as the starting matrix when composing the model transformations. Given
that a Locale is represented by a single high-resolution coordinate position, the
transformation L1–1L2 is a simple translation by L2 – L1. Again, it is not neces-
sary to actually transform points into high-resolution VirtualUniverse coordi-
nates.
In general, Locales that are close enough that the difference in their high-resolu-
tion coordinates can be represented in double precision by a noninfinite value are

Version 1.2, March 2000 245

9.6 A Minimal Environment VIEW MODEL

close enough to be rendered. In practice, more sophisticated culling techniques

can be used to only render those Locales that really are “close enough.”

9.6 A Minimal Environment

An application must create a minimal set of Java 3D objects before Java 3D can
render to a display device. In addition to a Canvas3D object, the application must
create a View object, with its associated PhysicalBody and PhysicalEnvironment
objects, and the following scene graph elements:
• A VirtualUniverse object
• A high-resolution Locale object
• A BranchGroup node object
• A TransformGroup node object with associated transform
• A ViewPlatform leaf node object that defines the position and orientation
within the virtual universe for generating views

9.7 The View Object

The View object coordinates all aspects of the rendering process. It contains all
the parameters or references to objects containing the parameters that determine
how to render images to the windows represented by its Canvas3D objects. It
also contains the set of canvases that represent various “windows” onto a view.
Java 3D allows applications to specify multiple simultaneously active View
objects, each controlling its own set of canvases. For more details on a View
object’s internals, see Section C.5, “The View Object.”

Constructors
The View object specifies the following constructor.

public View()

Constructs and initializes a new View object with default parameters:

Parameter Default Value
view policy SCREEN_VIEW
projection policy PERSPECTIVE_PROJECTION
screen scale policy SCALE_SCREEN_SIZE

246 The Java 3D API Specification

VIEW MODEL The View Object 9.7

Parameter Default Value

window resize policy PHYSICAL_WORLD
window movement policy PHYSICAL_WORLD
window eyepoint policy RELATIVE_TO_FIELD_OF_VIEW
monoscopic view policy CYCLOPEAN_EYE_VIEW
(deprecated in this class)
front clip policy PHYSICAL_EYE
back clip policy PHYSICAL_EYE
visibility policy VISIBILITY_DRAW_VISIBLE
coexistence centering flag true
compatibility mode false
left projection identity
right projection identity
vpc to ec transform identity
physical body null
physical environment null
screen scale 1.0
field of view π/4
left manual eye in coexistence (-0.033, 0.0, 0.4572)
right manual eye in coexistence (0.033, 0.0, 0.4572)
front clip distance 0.1
back clip distance 10.0
tracking enable false
user head to vworld enable false
list of Canvas3D objects empty
depth buffer freeze transparent true
scene antialiasing false
local eye lighting false
view platform null
behavior scheduler running true
view running true
minimum frame duration 0

Methods
The View object specifies the following methods.

Version 1.2, March 2000 247

9.7 The View Object VIEW MODEL

public void setPhysicalBody(PhysicalBody physicalBody)

public PhysicalBody getPhysicalBody()

These methods set and retrieve the View’s PhysicalBody object. See
Section 9.10, “The PhysicalBody Object,” for more information on the Physical-
Body object.

public void setPhysicalEnvironment(PhysicalEnvironment

physicalEnvironment)
public PhysicalEnvironment getPhysicalEnvironment()

These methods set and retrieve the View’s PhysicalEnvironment object. See
Section 9.11, “The PhysicalEnvironment Object,” for more information on the
PhysicalEnvironment object.

public void attachViewPlatform(ViewPlatform vp)

This method attaches a ViewPlatform leaf node to this View, replacing the exist-
ing ViewPlatform. If the ViewPlatform is part of a live scene graph, or is subse-
quently made live, the scene graph is rendered into all canvases in this View
object’s list of Canvas3D objects. To remove a ViewPlatform without attaching a
new one—causing the View to no longer be rendered—a null reference may be
passed to this method. In this case, the behavior is as if rendering were simulta-
neously stopped on all canvases attached to the View—the last frame that was
rendered in each remains visible until the View is again attached to a live
ViewPlatform object. See Section 6.11, “ViewPlatform Node,” for more informa-
tion on ViewPlatform objects.

public ViewPlatform getViewPlatform()

This method retrieves the currently attached ViewPlatform object.

public Canvas3D getCanvas3D(int index)

public void setCanvas3D(Canvas3D canvas3D, int index)
public void addCanvas3D(Canvas3D canvas3D)
public void insertCanvas3D(Canvas3D canvas3D, int index)
public void removeCanvas3D(int index)
public void removeCanvas3D(Canvas3D canvas3D)

These methods set, retrieve, add to, insert after, and remove a Canvas3D object
from this View. The index specifies the reference to the Canvas3D object within
the View object. See Section 9.9, “The Canvas3D Object” for more information
on Canvas3D objects.

248 The Java 3D API Specification

VIEW MODEL Projection Policy 9.7.1

public int numCanvas3Ds() New in 1.2

This method returns the the number of Canvas3Ds in this View.

public Enumeration getAllCanvas3Ds()

This method gets the Enumeration object of all the Canvas3Ds.

9.7.1 Projection Policy

The projection policy informs Java 3D whether it should generate a parallel pro-
jection or a perspective projection. This policy is attached to the Java 3D View
object.

Methods

public void setProjectionPolicy(int policy)

public int getProjectionPolicy()

These two methods set and retrieve the current projection policy for this view.
The projection policies are as follows:
• PARALLEL_PROJECTION: Specifies that Java 3D should compute a
parallel projection.
• PERSPECTIVE_PROJECTION: Specifies that Java 3D should compute a
perspective projection. This is the default setting.

public void setLocalEyeLightingEnable(boolean flag)

public boolean getLocalEyeLightingEnable()

These methods set and retrieve the local eye lighting flag, which indicates
whether the local eyepoint is used in lighting calculations for perspective projec-
tions. If this flag is set to true, the view vector is calculated per vertex based on
the direction from the actual eyepoint to the vertex. If this flag is set to false, a
single view vector is computed from the eyepoint to the center of the view frus-
tum. This is called infinite eye lighting. Local eye lighting is disabled by default,
and is ignored for parallel projections.

9.7.1.1 Window Sizing and Movement

When users resize or move windows, Java 3D can choose to think of the window
as attached either to the physical world or to the virtual world. The window
resize policy allows an application to specify how the view model will handle
resizing requests. The window resize policies are specified by two constants.

Version 1.2, March 2000 249

9.7.1 Projection Policy VIEW MODEL

Constants

public static final int PHYSICAL_WORLD

This variable specifies the policy for resizing and moving windows. This policy
is used in specifying windowResizePolicy and windowMovementPolicy. This
variable specifies that the specified action takes place only in the physical world.

public static final int VIRTUAL_WORLD

This variable specifies that Java 3D applies the associated policy in the virtual
world.

Methods

public void setWindowResizePolicy(int policy)

public int getWindowResizePolicy()

This variable specifies how Java 3D modifies the view when a user resizes a win-
dow. A value of PHYSICAL_WORLD states that Java 3D will treat window resizing
operations as only happening in the physical world. This implies that rendered
objects continue to fill the same percentage of the newly sized window, using
more or less pixels to draw those objects, depending on whether the window
grew or shrank in size. A value of VIRTUAL_WORLD states that Java 3D will treat
window resizing operations as also happening in the virtual world whenever a
resizing occurs in the physical world. This implies that rendered objects remain
the same size (use the same number of pixels), but since the window becomes
larger or smaller, the user sees more or less of the virtual world. The default
value is PHYSICAL_WORLD.

public void setWindowMovementPolicy(int policy)

public int getWindowMovementPolicy()

This variable specifies what part of the virtual world Java 3D will draw as a func-
tion of the window location on the display screen. A value of PHYSICAL_WORLD
states that the window acts as if it moves only on the physical screen. As the user
moves the window on the screen, the window’s position on the screen changes
but Java 3D continues to draw exactly the same image within that window. A
value of VIRTUAL_WORLD states that the window acts as if it also moves within the
virtual world. As the user moves the window on the physical screen, the win-
dow’s position on the screen changes and the image that Java 3D draws changes
as well to match what would be visible in the virtual world from a window in
that new position. The default value is PHYSICAL_WORLD.

250 The Java 3D API Specification

VIEW MODEL Projection and Clip Parameters 9.7.3

9.7.2 Clip Policies

The clip policies determine how Java 3D interprets clipping distances to both the
near and far clip planes. The policies can contain one of four values specifying
whether a distance measurement should be interpreted in the physical or the vir-
tual world and whether that distance measurement should be interpreted relative
to the physical eyepoint or the physical screen.

Methods

public void setFrontClipPolicy(int policy)

public int getFrontClipPolicy()
public void setBackClipPolicy(int policy)
public int getBackClipPolicy()

The front clip policy determines where Java 3D places the front clipping plane.
The value is one of the following: PHYSICAL_EYE, PHYSICAL_SCREEN, VIRTUAL_
EYE, or VIRTUAL_SCREEN. The default value is PHYSICAL_EYE.

The back clip policy determines where Java 3D places the back clipping plane.
The value is one of the following: PHYSICAL_EYE, PHYSICAL_SCREEN, VIRTUAL_
EYE, or VIRTUAL_SCREEN. The default value is PHYSICAL_EYE.

These policies are defined as follows.

• PHYSICAL_EYE: Specifies that the plane is located relative to the eye’s
position as measured in the physical space (in meters).
• PHYSICAL_SCREEN: Specifies that the plane is located relative to the
screen (that is, the image plate) as measured in physical space (in meters).
• VIRTUAL_EYE: Specifies that the plane is located relative to the virtual
eyepoint as measured in virtual world coordinates.
• VIRTUAL_SCREEN: Specifies that the plane is located relative to the
screen (that is, the image plate) as measured in virtual world coordinates.

9.7.3 Projection and Clip Parameters

The projection and clip parameters determine the view model’s field of view and
the front and back clipping distances.

Version 1.2, March 2000 251

9.7.3 Projection and Clip Parameters VIEW MODEL

public void setFieldOfView(double fieldOfView)

public double getFieldOfView()

In the default non-head-tracked mode, this value specifies the view model’s hori-
zontal field of view in radians. This value is ignored when the view model is
operating in head-tracked mode, or when the Canvas3D’s window eyepoint pol-
icy is set to a value other than the default setting of RELATIVE_TO_FIELD_OF_
VIEW (see Section C.5.3, “Window Eyepoint Policy”).

public void setFrontClipDistance(double distance)

public double getFrontClipDistance()

This value specifies the distance away from the clip origin, specified by the front
clip policy variable, in the direction of gaze where objects stop disappearing.
Objects closer than the clip origin (eye or screen) plus the front clip distance are
not drawn. Measurements are done in the space (physical or virtual) that is spec-
ified by the associated front clip policy parameter.

public void setBackClipDistance(double distance)

public double getBackClipDistance()

This value specifies the distance away from the clip origin (specified by the back
clip policy variable) in the direction of gaze where objects begin disappearing.
Objects farther away from the clip origin (eye or screen) plus the back clip dis-
tance are not drawn. Measurements are done in the space (physical or virtual)
that is specified by the associated back clip policy parameter. The View object’s
back clip distance is ignored if the scene graph contains an active Clip leaf node
(see Section 6.5, “Clip Node”).
There are several considerations that need to be taken into account when choos-
ing values for the front and back clip distances.
• The front clip distance must be greater than 0.0 in physical eye coordi-
nates.
• The front clipping plane must be in front of the back clipping plane, that
is, the front clip distance must be less than the back clip distance in phys-
ical eye coordinates.
• The front and back clip distances, in physical eye coordinates, must be less
than the largest positive single-precision floating point value, Float.MAX_
VALUE. In practice, since these physical eye coordinate distances are in
meters, the values should be much less than that.
• The ratio of the back distance divided by the front distance, in physical eye
coordinates, affects Z-buffer precision. This ratio should be less than about

252 The Java 3D API Specification

VIEW MODEL Frame Start Time, Duration, and Number 9.7.4

3000 to accommodate 16-bit Z-buffers. Values of 100 to less than 1000

will produce better results.
Violating any of the above rules will result in undefined behavior. In many cases,
no picture will be drawn.

9.7.4 Frame Start Time, Duration, and Number

The following methods are used to get information about system execution and
performance.

public long getCurrentFrameStartTime()

This method returns the time at which the most recent rendering frame started. It
is defined as the number of milliseconds since January 1, 1970 00:00:00 GMT.
Since multiple canvases might be attached to this View, the start of a frame is
defined as the point just prior to clearing any canvas attached to this View.

public long getLastFrameDuration()

This method returns the duration, in milliseconds, of the most recently completed
rendering frame. The time taken to render all canvases attached to this View is
measured. This duration is computed as the difference between the start of the
most recently completed frame and the end of that frame. Since multiple can-
vases might be attached to this View, the start of a frame is defined as the point
just prior to clearing any canvas attached to this View, while the end of a frame
is defined as the point just after swapping the buffer for all canvases.

public long getFrameNumber()

This method returns the frame number for this view. The frame number starts at
0 and is incremented prior to clearing all the canvases attached to this view.

public static int getMaxFrameStartTimes()

This method retrieves the implementation-dependent maximum number of

frames whose start times will be recorded by the system. This value is guaran-
teed to be at least 10 for all implementations of the Java 3D API.

public long getFrameStartTimes(long times[])

This method copies the last k frame start time values into the user-specified array.
The most recent frame start time is copied to location 0 of the array, the next
most-recent frame start time is copied into location 1 of the array, and so on. If
times.length is smaller that maxFrameStartTimes, only the last times.length

Version 1.2, March 2000 253

9.7.5 View Traversal and Behavior Scheduling VIEW MODEL

values are copied. If times.length is greater than maxFrameStartTimes, all

array elements after index maxFrameStartTimes – 1 are set to 0.

public void setMinimumFrameCycleTime(long duration) New in 1.2

public long getMinimumFrameCycleTime() New in 1.2

These methods set and retrieve the minimum frame cycle time, in milliseconds,
for this view. The Java 3D renderer will ensure that the duration between each
frame is at least the specified number of milliseconds. The default value is 0.

9.7.5 View Traversal and Behavior Scheduling

The following methods control the traversal, the rendering, and the execution of
the behavior scheduler for this view.

public final long[] stopBehaviorScheduler()

public final void startBehaviorScheduler()
public final boolean isBehaviorSchedulerRunning()

The first method stops the behavior scheduler after all currently-scheduled
behaviors are executed. Any frame-based behaviors scheduled to wake up on the
next frame will be executed at least once before the behavior scheduler is
stopped. The method returns a pair if integers that specify the beginning and end-
ing time (in milliseconds since January 1, 1970 00:00:00 GMT) of the behavior
scheduler’s last pass. The second method starts the behavior scheduler running
after it has been stopped. The third method retrieves a flag that indicates whether
the behavior scheduler is currently running.

public final void stopView()

public final void startView()
public final boolean isViewRunning()

The first method stops traversing this view after the current state of the scene
graph is reflected on all canvases attached to this view. The renderers associated
with these canvases are also stopped. The second method starts traversing this
view and starts the renderers associated with all canvases attached to this view.
The third method returns a flag indicating whether the traverser is currently run-
ning on this view.

Note: The above six methods are heavy-weight methods intended for verification
and image capture (recording). They are not intended to be used for flow control.

254 The Java 3D API Specification

VIEW MODEL Depth Buffer 9.7.7

public void renderOnce() New in 1.2

This method renders one frame for a stopped View. Functionally, this method is
equivalent to startView() followed by stopview(), except that it is atomic,
which guarantees that only one frame is rendered.

public void repaint() New in 1.2

This method requests that this View be scheduled for rendering as soon as possi-
ble. The repaint method may return before the frame has been rendered. If the
view is stopped, or if the view is continuously running (for example, due to a
free-running interpolator), this method will have no effect. Most applications will
not need to call this method, since any update to the scene graph or to viewing
parameters will automatically cause all affected views to be rendered.

9.7.6 Scene Antialiasing

public void setSceneAntialiasingEnable(boolean flag)

public boolean getSceneAntialiasingEnable()

These methods set and retrieve the scene antialiasing flag. Scene antialiasing is
either enabled or disabled for this view. If enabled, the entire scene will be
antialiased on each canvas in which scene antialiasing is available. Scene antial-
iasing is disabled by default.

Note: Line and point antialiasing are independent of scene antialiasing. If antial-
iasing is enabled for lines and points, the lines and points will be antialiased prior
to scene antialiasing.

9.7.7 Depth Buffer

public void setDepthBufferFreezeTransparent(boolean flag)

public boolean getDepthBufferFreezeTransparent()

The set method enables or disables automatic freezing of the depth buffer for
objects rendered during the transparent rendering pass (that is, objects rendered
using alpha blending) for this view. If enabled, depth buffer writes are disabled
during the transparent rendering pass regardless of the value of the depth-buffer-
write-enable flag in the RenderingAttributes object for a particular node. This
flag is enabled by default. The get method retrieves this flag.

Version 1.2, March 2000 255

9.8 The Screen3D Object VIEW MODEL

9.8 The Screen3D Object

The Screen3D object provides a 3D version of the AWT screen object. It con-
tains the screen’s physical properties. Java 3D will support multiple active
Screen3D objects as soon as AWT support is available. Of course, multiple
screens are only available if the machine configuration has multiple output
screens. Java 3D primarily needs to know the physical size (in meters) of the
Screen3D’s visible, addressable raster (the image plate) and, in head-tracking
mode, the position and orientation of this raster relative to a well-defined physi-
cal world coordinate system, specifically, the tracker base coordinate system.
Java 3D also needs to know how many pixels the raster can display in both the x
and y dimensions. This information allows Java 3D to calculate a pixel’s physical
dimension.
Calibration utilities can change a Screen3D’s physical characteristics or calibra-
tion transforms. See Section C.6, “The Screen3D Object.”
The Screen3D object has no public constructors. Instead, the Screen3D object
associated with a particular Canvas3D object can be obtained from the canvas by
calling the getScreen3D method. See Section 9.9.3, “Other Canvas3D Parame-
ters.”
Default values for Screen3D parameters are as follows:
Parameter Default Value
physical screen width 0.0254/90.0 * screen width (in pixels)
physical screen height 0.0254/90.0 * screen height (in pixels)
tracker base to image plate transform identity
head tracker to left image plate transform identity
head tracker to right image plate transform identity
off-screen size (0,0)

Methods
These methods provide applications with information concerning the underlying
display hardware, such as the screen’s width and height in pixels or in meters.

public Dimension getSize()

public Dimension getSize(Dimension rv) New in 1.2

These methods retrieve the width and height (in pixels) of this Screen3D. The
second method copies the width and height into the specified Dimension object.

256 The Java 3D API Specification

VIEW MODEL The Canvas3D Object 9.9

public double getPhysicalScreenWidth()

public double getPhysicalScreenHeight()

These methods retrieve the screen’s (image plate’s) physical width and height in
meters.

9.8.1 Off-screen Rendering

New for Java 3D 1.2 is an off-screen mode that allows rendering to a memory
image, which is possibly larger than the screen.

public void setSize(int width, int height) New in 1.2

public void setSize(Dimension d) New in 1.2

These methods set the width and height (in pixels) of this off-screen Screen3D.
The default size for off-screen Screen3D objects is (0,0).

Note: The off-screen size, physical width, and physical height must be set prior to
rendering to the associated off-screen canvas. Failure to do so will result in an
exception.

9.9 The Canvas3D Object

The Canvas3D object extends the java.awt.Canvas object to include 3D-related
information such as the size of the canvas in pixels, the Canvas3D’s location,
also in pixels, within a Screen3D object, and whether or not the canvas has stereo
enabled. The Canvas3D class is used either for on-screen rendering or off-screen
rendering. Because all Canvas3D objects contain a reference to a Screen3D
object and because Screen3D objects define the size of a pixel in physical units,
Java 3D can convert a Canvas3D size in pixels to a physical world size in meters.
It can also determine the Canvas3D’s position and orientation in the physical
world.
The Canvas3D class is used either for on-screen rendering or off-screen render-
ing. On-screen Canvas3Ds are added to AWT or Swing Container objects like
any other canvas. Java 3D automatically and continuously renders to all on-
screen canvases that are attached to an active View object. On-screen Canvas3Ds
can be either single or double buffered and they can be either stereo or mono-
scopic.

Version 1.2, March 2000 257

Off-screen Canvas3Ds must not be added to any Container. Java 3D renders to
off-screen canvases in response to the renderOffScreenBuffer method (see
“Off-screen Rendering”). Off-screen Canvas3Ds are single buffered. However,
on many systems, the actual rendering is done to an off-screen hardware buffer
or to a 3D library-specific buffer and only copied to the off-screen buffer of the
Canvas when the rendering is complete, at “buffer swap” time. Off-screen
Canvas3Ds are monoscopic.

Constructors
The Canvas3D object specifies the following constructors.

public Canvas3D(GraphicsConfiguration graphicsConfiguration)

This constructs and initializes a new Canvas3D object that Java 3D can render
into. The following Canvas3D parameters are initialized to default values as
shown:
Parameter Default Value
left manual eye in image plate (0.142, 0.135, 0.4572)
right manual eye in image plate (0.208, 0.135, 0.4572)
stereo enable true
double buffer enable true
monoscopic view policy View.CYCLOPEAN_EYE_VIEW
off-screen mode false
off-screen buffer null
off-screen location (0,0)

public Canvas3D(GraphicsConfiguration graphicsConfiguration,

boolean offScreen) New in 1.2

This constructs and initializes a new Canvas3D object that Java 3D can render
into.
Java 3D can render into this Canvas3D object. If the graphicsConfiguration
argument is null, a GraphicsConfiguration object will be constructed using the
default GraphicsConfigTemplate3D (see Section 9.9.4, “GraphicsConfigTem-
plate3D Object.”
For more information on the GraphicsConfiguration object, see the Java 2D spec-
ification, which is part of the AWT in JDK 1.2.
VIEW MODEL Off-screen Rendering 9.9.2

9.9.1 Window System–Provided Parameters

Java 3D specifies the size of a Canvas3D in pixels. It extracts this information
directly from the AWT’s window system. Java 3D only allows applications to
access these values, not change them.

public Dimension getLocationOnScreen()

public Dimension getSize()

These methods, inherited from the parent Canvas class, retrieve the Canvas3D’s
screen position and size in pixels.

9.9.2 Off-screen Rendering

New for Java 3D 1.2 is an off-screen mode that allows rendering to a memory
image, which is possibly larger than the screen.

public boolean isOffScreen() New in 1.2

This method retrieves the state of the renderer for this Canvas3D object.

public void setOffScreenBuffer(ImageComponent2D buffer) New in 1.2

public ImageComponent2D getOffScreenBuffer() New in 1.2

The first method sets the off-screen buffer for this Canvas3D. The specified
image is written into by the Java 3D renderer. The size of the specified Image-
Component determines the size, in pixels, of this Canvas3D – the size inherited
from Component is ignored. The second method retrieves the off-screen buffer
for this Canvas3D.

Note: The size, physical width, and physical height of the associated Screen3D
must be set explicitly prior to rendering. Failure to do so will result in an excep-
tion.

public void renderOffScreenBuffer() New in 1.2

This method schedules the rendering of a frame into this Canvas3D’s off-screen
buffer. The rendering is done from the point of view of the View object to which
this Canvas3D has been added. No rendering is performed if this Canvas3D
object has not been added to an active View. This method does not wait for the
rendering to actually happen. An application that wishes to know when the ren-
dering is complete must either subclass Canvas3D and override the postSwap
method, or call waitForOffScreenRendering. An IllegalStateException is

Version 1.2, March 2000 259

9.9.3 Other Canvas3D Parameters VIEW MODEL

thrown if this Canvas3D is not in off-screen mode, or if either the width or the
height of the associated Screen3D’s size is ≤ 0, or if the associated Screen3D’s
physical width or height is ≤ 0.

public void waitForOffScreenRendering() New in 1.2

This method waits for this Canvas3D’s off-screen rendering to be done. This
method will wait until the postSwap method of this off-screen Canvas3D has
completed. If this Canvas3D has not been added to an active view or if the ren-
derer is stopped for this Canvas3D, this method will return immediately. This
method must not be called from a render callback method of an off-screen
Canvas3D.

public void setOffScreenLocation(int x, int y) New in 1.2

public void setOffScreenLocation(Point p) New in 1.2

These methods set the location of this off-screen Canvas3D. The location is the
upper-left corner of the Canvas3D relative to the upper-left corner of the corre-
sponding off-screen Screen3D. The function of these methods is similar to that
of Component.setLocation for on-screen Canvas3D objects. The default loca-
tion is (0,0).

public Point getOffScreenLocation() New in 1.2

public Point getOffScreenLocation(Point rv) New in 1.2

These methods retrieve the location of this off-screen Canvas3D. The location is
the upper-left corner of the Canvas3D relative to the upper-left corner of the cor-
responding off-screen Screen3D. The function of these methods is similar to that
of Component.getLocation for on-screen Canvas3D objects. The second
method stores the location in the specified Point object. This method is useful if
the caller wants to avoid allocating a new Point object on the heap.

9.9.3 Other Canvas3D Parameters

public boolean getStereoAvailable()

This method specifies whether the underlying hardware supports field-sequential

stereo on this canvas. This is equivalent to:
((Boolean)queryProperties().get("stereoAvailable")).
booleanValue()

260 The Java 3D API Specification

VIEW MODEL Other Canvas3D Parameters 9.9.3

public boolean getStereoEnable()

public void setStereoEnable(boolean flag)

These methods set or retrieve the flag indicating whether this Canvas3D has ste-
reo enabled. If enabled, Java 3D generates left and right eye images. If the
Canvas3D’s StereoAvailable flag is false, Java 3D displays only the left eye’s
view even if an application sets StereoEnable to true. This parameter allows
applications to enable or disable stereo on a canvas-by-canvas basis.

public void getDoubleBufferAvailable()

This method specifies whether the underlying hardware supports double buffer-
ing on this canvas. This is equivalent to:
((Boolean)queryProperties().get("doubleBufferAvailable")).
booleanValue()

public boolean getDoubleBufferEnable()

public void setDoubleBufferEnable(boolean flag)

These methods set or retrieve the flag indicating whether this Canvas3D has dou-
ble buffering enabled. If disabled, all drawing is to the front buffer and no buffer
swap will be done between frames. It should be stressed that running Java 3D
with double buffering disabled is not recommended.

public boolean getSceneAntialiasingAvailable()

This method specifies whether the underlying hardware supports scene-level

antialiasing on this canvas. This is equivalent to:
((Boolean)queryProperties().get("sceneAntialiasingAvailable")).
booleanValue()

public View getView()

Retrieves the View object that points to this Canvas3D.

public Screen3D getScreen3D()

Retrieves the Screen3D object to which this Canvas3D is attached.

public final Map queryProperties() New in 1.2

This method returns a read-only Map object containing key-value pairs that
define various properties for this Canvas3D. All of the keys are String objects.
The values are key-specific, but most will be Boolean, Integer, Double, or String
objects. The currently-defined keys are:

Version 1.2, March 2000 261

9.9.3 Other Canvas3D Parameters VIEW MODEL

Key (String) Value Type Description

doubleBufferAvailable Boolean A Boolean indicating whether or not double
buffering is available for this Canvas3D. This is
equivalent to the getDoubleBufferAvailable
method. If this flag is false, the Canvas3D will be
rendered in single buffer mode; requests to enable
double buffering will be ignored.
stereoAvailable Boolean A Boolean indicating whether or not stereo is
available for this Canvas3D. This is equivalent to
the getStereoAvailable method. If this flag is
false, the Canvas3D will be rendered in
monoscopic mode; requests to enable stereo will
be ignored.
sceneAntialiasingAvailable Boolean A Boolean indicating whether or not scene
antialiasing is available for this Canvas3D. This is
equivalent to the
getSceneAntialiasingAvailable method. If
this flag is false, requests to enable scene
antialiasing will be ignored.
texture3DAvailable Boolean A Boolean indicating whether or not 3D Texture
mapping is available for this Canvas3D. If this flag
is false, 3D texture mapping is either not supported
by the underlying rendering layer or is otherwise
unavailable for this particular Canvas3D. All use
of 3D texture mapping will be ignored in this case.
textureColorTableSize Integer An Integer indicating the maximum size of the
texture color table for this Canvas3D. If the size is
0, the texture color table is either not supported by
the underlying rendering layer or is otherwise
unavailable for this particular Canvas3D. An
attempt to use a texture color table larger than
textureColorTableSize will be ignored; no
color lookup will be performed.
compressedGeometry. Integer An Integer indicating the major version number of
majorVersionNumber the version of compressed geometry supported by
this version of Java 3D.
compressedGeometry. Integer An Integer indicating the minor version number of
minorVersionNumber the version of compressed geometry supported by
this version of Java 3D.
compressedGeometry. Integer An Integer indicating the minor-minor version
minorMinorVersionNumber number of the version of compressed geometry
supported by this version of Java 3D.

262 The Java 3D API Specification

VIEW MODEL GraphicsConfigTemplate3D Object 9.9.4

9.9.4 GraphicsConfigTemplate3D Object

This GraphicsConfigTemplate3D class is used to obtain a valid GraphicsConfig-
uration that can be used by Java 3D. A user instantiates one of these objects and
then sets all non-default attributes as desired. The getGraphicsConfiguration
method found in the java.awt.GraphicsDevice class is then called with this
GraphicsConfigTemplate. A valid GraphicsConfiguration is returned that meets
or exceeds what was requested in the java.awt.GraphicsConfigTemplate.

Constructors

public GraphicsConfigTemplate3D()

This constructor constructs a new GraphicsConfigTemplate3D and sets all values

to their default:
Parameter Default Value
doubleBuffer REQUIRED
stereo UNNECESSARY
sceneAntialiasing UNNECESSARY
depthSize 16
redSize 2
greenSize 2
blueSize 2

Methods

public void setDoubleBuffer(int value)

public int getDoubleBuffer()

These methods set and retrieve the double-buffering attribute. The valid values
are: REQUIRED, PREFERRED, and UNNECESSARY.

public void setStereo(int value)

public int getStereo()

These methods set and retrieve the stereo attribute. The valid values are:
REQUIRED, PREFERRED, and UNNECESSARY.

public void setSceneAntialiasing(int value)

public int getSceneAntialiasing()

These methods set and retrieve the scene antialiasing attribute. The valid values
are: REQUIRED, PREFERRED, and UNNECESSARY.

Version 1.2, March 2000 263

9.10 The PhysicalBody Object VIEW MODEL

public void setDepthSize(int value)

public int getDepthSize()

These methods set and retrieve the depth buffer size requirement.

public void setRedSize(int value)

public int getRedSize()
public void setGreenSize(int value)
public int getGreenSize()
public void setBlueSize(int value)
public int getBlueSize()

These methods set and retrieve the number of red, green, and blue bits requested
by this template.

public java.awt.GraphicsConfiguration
getBestConfiguration(java.awt.GraphicsConfiguration[] gc)

This method returns the “best” configuration possible that passes the criteria
defined in the GraphicsConfigTemplate3D.

public boolean
isGraphicsConfigSupported(java.awt.GraphicsConfiguration
gc)

This method returns a boolean indicating whether or not the given GraphicsCon-
figuration can be used to create a drawing surface that can be rendered to. This
method returns true if this GraphicsConfiguration object can be used to create
surfaces that can be rendered to, false if the GraphicsConfiguration cannot be
used to create a drawing surface usable by this API.

9.10 The PhysicalBody Object

Java 3D defines a PhysicalBody object that contains information concerning the
end user’s physical characteristics. The head parameters allow end users to spec-
ify their own head’s characteristics, such as the location of the eyes and the inter-
pupilary distance. See Section C.8, “The PhysicalBody Object,” for details. The
default values are sufficient for applications that are running in a non-head-
tracked environment and that do not manually set the eyepoint.

Constructors

public PhysicalBody()

This constructor constructs and initializes a default PhysicalBody object.

264 The Java 3D API Specification

VIEW MODEL The PhysicalEnvironment Object 9.11

9.11 The PhysicalEnvironment Object

The PhysicalEnvironment object defines several methods that are described in
Section C.9, “The PhysicalEnvironment Object.” The default values are sufficient
for applications that do not use continuous input devices that are run in a non-
head-tracked display environment.

Constructors

public PhysicalEnvironment()

Constructs and initializes a default PhysicalEnvironment object.

Version 1.2, March 2000 265

 C H A P T E R 10
Behaviors and Interpolators

B EHAVIOR nodes provide the means for animating objects, processing key-
board and mouse inputs, reacting to movement, and enabling and processing pick
events. Behavior nodes contain Java code and state variables. A Behavior node’s
Java code can interact with Java objects, change node values within a Java 3D
scene graph, change the behavior’s internal state—in general, perform any com-
putation it wishes.
Simple behaviors can add surprisingly interesting effects to a scene graph. For
example, one can animate a rigid object by using a Behavior node to repetitively
modify the TransformGroup node that points to the object one wishes to animate.
Alternatively, a Behavior node can track the current position of a mouse and
modify portions of the scene graph in response.

10.1 Behavior Object

A Behavior leaf node object contains a scheduling region and two methods: an
initialize method called once when the behavior becomes “live” and a pro-
cessStimulus method called whenever appropriate by the Java 3D behavior
scheduler. The Behavior object also contains the state information needed by its
initialize and processStimulus methods.

The scheduling region defines a spatial volume that serves to enable the sched-
uling of Behavior nodes. A Behavior node is active (can receive stimuli) when-
ever a ViewPlatform’s activation volume intersects a Behavior object’s
scheduling region. Only active behaviors can receive stimuli.
The initialize method allows a Behavior object to initialize its internal state
and specify its initial wakeup condition(s). Java 3D invokes a behavior’s initial-
ize code when the behavior’s containing BranchGroup node is added to the vir-
tual universe. Java 3D does not invoke the initialize method in a new thread.
Version 1.2, March 2000 267
10.1.1 Code Structure BEHAVIORS AND INTERPOLATORS

Thus, for Java 3D to regain control, the initialize method must not execute an
infinite loop: It must return. Furthermore, a wakeup condition must be set or else
the behavior’s processStimulus method is never executed.
The processStimulus method receives and processes a behavior’s ongoing mes-
sages. The Java 3D behavior scheduler invokes a Behavior node’s processStim-
ulus method when a ViewPlatform’s activation volume intersects a Behavior
object’s scheduling region and all of that behavior’s wakeup criteria are satisfied.
The processStimulus method performs its computations and actions (possibly
including the registration of state change information that could cause Java 3D to
wake other Behavior objects), establishes its next wakeup condition, and finally
exits.

10.1.1 Code Structure

When the Java 3D behavior scheduler invokes a Behavior object’s processStim-
ulus method, that method may perform any computation it wishes. Usually, it
will change its internal state and specify its new wakeup conditions. Most proba-
bly, it will manipulate scene graph elements. However, the behavior code can
only change those aspects of a scene graph element permitted by the capabilities
associated with that scene graph element. A scene graph’s capabilities restrict
behavioral manipulation to those manipulations explicitly allowed.
The application must provide the Behavior object with references to those scene
graph elements that the Behavior object will manipulate. The application pro-
vides those references as arguments to the behavior’s constructor when it creates
the Behavior object. Alternatively, the Behavior object itself can obtain access to
the relevant scene graph elements either when Java 3D invokes its initialize
method or each time Java 3D invokes its processStimulus method.
Behavior methods have a very rigid structure. Java 3D assumes that they always
run to completion (if needed, they can spawn threads). Each method’s basic
structure consists of the following:
• Code to decode and extract references from the WakeupCondition enumer-
ation that caused the object’s awakening
• Code to perform the manipulations associated with the WakeupCondition
• Code to establish this behavior’s new WakeupCondition
• A path to Exit (so that execution returns to the Java 3D behavior scheduler)

268 The Java 3D API Specification

BEHAVIORS AND INTERPOLATORS WakeupCriterion Object 10.1.3

10.1.2 WakeupCondition Object

A WakeupCondition object is an abstract class specialized to fourteen different
WakeupCriterion objects and to four combining objects containing multiple
WakeupCriterion objects.
A Behavior node provides the Java 3D behavior scheduler with a WakeupCondi-
tion object. When that object’s WakeupCondition has been satisfied, the behavior
scheduler hands that same WakeupCondition back to the Behavior via an enu-
meration.

10.1.3 WakeupCriterion Object

Java 3D provides a rich set of wakeup criteria that Behavior objects can use in
specifying a complex WakeupCondition. These wakeup criteria can cause
Java 3D’s behavior scheduler to invoke a behavior’s processStimulus method
whenever
• The center of a ViewPlatform enters a specified region
• The center of a ViewPlatform exits a specified region
• A behavior is activated
• A behavior is deactivated
• A specified TransformGroup node’s transform changes
• Collision is detected between a specified Shape3D node’s Geometry object
and any other object
• Movement occurs between a specified Shape3D node’s Geometry object
and any other object with which it collides
• A specified Shape3D node’s Geometry object no longer collides with any
other object
• A specified Behavior object posts a specific event
• A specified AWT event occurs
• A specified time interval elapses
• A specified number of frames have been drawn
• The center of a specified Sensor enters a specified region
• The center of a specified Sensor exits a specified region
A Behavior object constructs a WakeupCriterion by constructing the appropriate
criterion object. The Behavior object must provide the appropriate arguments
(usually a reference to some scene graph object and possibly a region of inter-
Version 1.2, March 2000 269
10.1.4 Composing WakeupCriterion Objects BEHAVIORS AND INTERPOLATORS

est). Thus, to specify a WakeupOnViewPlatformEntry, a behavior would specify

the region that will cause the behavior to execute if a ViewPlatform enters it.

10.1.4 Composing WakeupCriterion Objects

A Behavior object can combine multiple WakeupCriterion objects into a more
powerful, composite WakeupCondition. Java 3D behaviors construct a composite
WakeupCondition in one of the following ways:
• WakeupAnd: An array of WakeupCriterion objects ANDed together.
WakeupCriterion && WakeupCriterion && ...

• WakeupOr: An array of WakeupCriterion objects ORed together.

WakeupCriterion || WakeupCriterion || ...

• WakeupAndOfOrs: An array of WakeupOr WakeupCondition objects that

are then ANDed together.
WakeupOr && WakeupOr && ...

• WakeupOrOfAnds: An array of WakeupAnd WakeupCondition objects

that are then ORed together.
WakeupAnd || WakeupAnd || ...

10.2 Composing Behaviors

Behavior objects can condition themselves to awaken only when signaled by
another Behavior node. The WakeupOnBehaviorPost WakeupCriterion takes as
arguments a reference to a Behavior node and an integer. These two arguments
allow a behavior to limit its wakeup criterion to a specific post by a specific
behavior.
The WakeupOnBehaviorPost WakeupCriterion permits behaviors to chain their
computations, allowing parenthetical computations—one behavior opens a door
and the second closes the same door, or one behavior highlights an object and the
second unhighlights the same object.

10.3 Scheduling
As a virtual universe grows large, Java 3D must carefully husband its resources
to ensure adequate performance. In a 10,000-object virtual universe with 400 or
so Behavior nodes, a naive implementation of Java 3D could easily end up con-
suming the majority of its compute cycles in executing the behaviors associated

270 The Java 3D API Specification

BEHAVIORS AND INTERPOLATORS How Java 3D Performs Execution Culling 10.4

with the 400 Behavior objects before it draws a frame. In such a situation, the
frame rate could easily drop to unacceptable levels.
Behavior objects are usually associated with geometric objects in the virtual uni-
verse. In our example of 400 Behavior objects scattered throughout a 10,000-
object virtual universe, only a few of these associated geometric objects would
be visible at a given time. A sizable fraction of the Behavior nodes—those asso-
ciated with nonvisible objects—need not be executed. Only those relatively few
Behavior objects that are associated with visible objects must be executed.
Java 3D mitigates the problem of a large number of Behavior nodes in a high-
population virtual universe through execution culling—choosing only to invoke
those behaviors that have high relevance.
Java 3D requires each behavior to have a scheduling region and to post a wakeup
condition. Together a behavior’s scheduling region and wakeup condition pro-
vide Java 3D’s behavior scheduler with sufficient domain knowledge to selec-
tively prune behavior invocations and only invoke those behaviors that absolutely
need to be executed.

10.4 How Java 3D Performs Execution Culling

Java 3D finds all scheduling regions associated with Behavior nodes and con-
structs a scheduling/volume tree. It also creates an AND/OR tree containing all
the Behavior node wakeup criteria. These two data structures provide the domain
knowledge Java 3D needs to prune unneeded behavior execution (to perform
“execution triage”).
Java 3D must track a behavior’s wakeup conditions only if a ViewPlatform
object’s activation volume intersects with that Behavior object’s scheduling
region. If the ViewPlatform object’s activation volume does not intersect with a
behavior’s scheduling region, Java 3D can safely ignore that behavior’s wakeup
criteria.
In essence, the Java 3D scheduler performs the following checks:
• Find all Behavior objects with scheduling regions that intersect the
ViewPlatform object’s activation volume.
• For each Behavior object within the ViewPlatform’s activation volume, if
that behavior’s WakeupCondition is true, schedule that Behavior object
for execution.

Version 1.2, March 2000 271

10.5 The Behavior API BEHAVIORS AND INTERPOLATORS

Java 3D’s behavior scheduler executes those Behavior objects that have been
scheduled by calling the behavior’s processStimulus method.

10.5 The Behavior API

The Java 3D behavior API spreads its functionality across three objects: the
Behavior leaf node, the WakeupCondition object and its subclasses, and the
WakeupCriterion objects.

10.5.1 The Behavior Node

The Behavior object is an abstract class that contains the framework for all
behavioral components in Java 3D.

Constructor
The Behavior leaf node class defines the following constructor.

public Behavior()

Constructs a Behavior node with default parameters:

Parameter Default Value
enable flag true
scheduling bounds null
scheduling bounding leaf null

Methods
The Behavior leaf node class defines the following methods.

public abstract void initialize()

This method, invoked by Java 3D’s behavior scheduler, is used to initialize the
behavior’s state variables and to establishes its WakeupConditions. Classes that
extend Behavior must provide their own initialize method. Applications
should not call this method.

public abstract void processStimulus(Enumeration criteria)

This method processes stimuli destined for this behavior. The behavior scheduler
invokes this method if its WakeupCondition is satisfied. Classes that extend

272 The Java 3D API Specification

BEHAVIORS AND INTERPOLATORS The Behavior Node 10.5.1

Behavior must provide their own processStimulus method. Applications should

not call this method.

public void setSchedulingBounds(Bounds region)

public Bounds getSchedulingBounds()

These two methods access or modify the Behavior node’s scheduling bounds.
This bounds is used as the scheduling region when the scheduling bounding leaf
is set to null. A behavior is scheduled for activation when its scheduling region
intersects the ViewPlatform’s activation volume (if its wakeup criteria have been
satisfied). The getSchedulingBounds method returns a copy of the associated
bounds.

public void setSchedulingBoundingLeaf(BoundingLeaf region)

public BoundingLeaf getSchedulingBoundingLeaf()

These two methods access or modify the Behavior node’s scheduling bounding
leaf. When set to a value other than null, this bounding leaf overrides the sched-
uling bounds object and is used as the scheduling region.

protected void wakeupOn(WakeupCondition criteria)

This method defines this behavior’s wakeup criteria. This method may only be
called from a Behavior object’s initialize or processStimulus methods to
(re)arm the next wakeup. It should be the last thing done by those methods.

public void postId(int postId)

This method, when invoked by a behavior, informs the Java 3D scheduler of the
identified event. The scheduler will schedule other Behavior objects that have
registered interest in this posting.

protected View getView()

This method returns the primary view associated with this behavior. This method
is useful with certain types of behaviors, such as Billboard and LOD, that rely on
per-View information and with behaviors in general in regards to scheduling (the
distance from the view platform determines the active behaviors). The “primary”
view is defined to be the first View attached to a live ViewPlatform, if there is
more than one active View. So, for instance, Billboard behaviors would be ori-
ented toward this primary view, in the case of multiple active views into the same
scene graph.

Version 1.2, March 2000 273

10.5.2 WakeupCondition Object BEHAVIORS AND INTERPOLATORS

10.5.2 WakeupCondition Object

WakeupCondition is an abstract class that is extended by the WakeupCriterion,
WakeupOr, WakeupAnd, WakeupOrOfAnds, and WakeupAndOfOr classes. A
Behavior node hands a WakeupCondition object to the behavior scheduler and
the behavior scheduler hands back an enumeration of that WakeupCondition.

Methods
The Java 3D API provides two methods for constructing WakeupCondition enu-
merations.

public Enumeration allElements()

public Enumeration triggeredElements()

These two methods create enumerators that sequentially access this WakeupCon-
dition’s wakeup criteria. The first method creates an enumerator that sequentially
presents all wakeup criteria that were used to construct this WakeupCondition.
The second method creates an enumerator that sequentially presents only those
wakeup criteria that have been satisfied.

10.5.3 The WakeupCriterion Objects

WakeupCriterion is an abstract class that consists of several subclasses. Each
subclass specifies one particular wakeup criterion, that criterion’s associated
arguments (if any), and either a flag that indicates whether this criterion caused a
Behavior object to awaken or a return field containing the information that
caused the Behavior object to awaken.

Methods

public boolean hasTriggered()

This predicate method returns true if this WakeupCriterion contributed to wak-

ing a Behavior object.

10.5.3.1 WakeupOnAWTEvent
This WakeupCriterion object specifies that Java 3D should awaken a behavior
when the specified AWT event occurs.

274 The Java 3D API Specification

BEHAVIORS AND INTERPOLATORS The WakeupCriterion Objects 10.5.3

Constructors

public WakeupOnAWTEvent(int AWTId)

public WakeupOnAWTEvent(long eventMask)

The first constructor creates a WakeupOnAWTEvent object that informs the

Java 3D scheduler to wake up the specified Behavior object whenever the AWT
event specified by AWTId occurs. The second constructor creates a Wake-
upOnAWTEvent object that informs the Java 3D scheduler to wake up the
specified Behavior object whenever any of the specified AWT EVENT_MASK
events occur. The eventMask consists of an ORed collection of EVENT_MASK val-
ues.

Methods

public AWTEvent[] getAWTEvent()

This method returns the array of consecutive AWT events that triggered this
WakeupCriterion to awaken the Behavior object. The Behavior object can
retrieve the AWTEvent array and process it in any way it wishes.

10.5.3.2 WakeupOnActivation
The WakeupOnActivation object specifies a wakeup the first time the
ViewPlatform’s activation region intersects with this object’s scheduling region.
This gives the behavior an explicit means of executing code when it is activated.

Constructors

public WakeupOnActivation()

This constructor creates a WakeupOnActivation criterion.

10.5.3.3 WakeupOnBehaviorPost
This WakeupCriterion object specifies that Java 3D should awaken this behavior
when the specified behavior posts the specified ID.

Constructors

public WakeupOnBehaviorPost(Behavior behavior, int postId)

This constructor creates a WakeupOnBehaviorPost object that informs the

Java 3D scheduler to wake up this Behavior object whenever the specified behav-
ior posts the specified postId. A postId of 0 specifies that this behavior should

Version 1.2, March 2000 275

10.5.3 The WakeupCriterion Objects BEHAVIORS AND INTERPOLATORS

awaken on any post from the specified behavior. Specifying a null behavior
implies that this behavior should awaken whenever any behavior posts the speci-
fied postId.

Methods

public int getPostId()

This method returns the postId used in creating this WakeupCriterion.

public Behavior getBehavior()

This method returns the behavior specified in this object’s constructor.

public int getTriggeringPostId()

This method returns the postid that caused the behavior to wake up. If the postid
used to construct this wakeup criterion was not zero, the triggering postid will
always be equal to the postid used in the constructor.

public Behavior getTriggeringBehavior()

This method returns the behavior that triggered this wakeup. If the arming behav-
ior used to construct this object was not null, the triggering behavior will be the
same as the arming behavior.

10.5.3.4 WakeupOnDeactivation
The WakeupOnDeactivation object specifies a wakeup on the first detection of a
ViewPlatform’s activation region no longer intersecting with this object’s sched-
uling region. This gives the behavior an explicit means of executing code when it
is deactivated.

Constructors

public WakeupOnDeactivation()

This constructor creates a new WakeupOnDeactivation criterion.

10.5.3.5 WakeupOnElapsedFrames
This WakeupCriterion object specifies that Java 3D should awaken this behavior
after it has rendered the specified number of frames. A value of 0 implies that
Java 3D will awaken this behavior at the next frame. The wakeup criterion can
either be passive or non-passive. If a behavior uses a non-passive WakeupOnE-
lapsedFrames, the rendering system will run continuously.

276 The Java 3D API Specification

BEHAVIORS AND INTERPOLATORS The WakeupCriterion Objects 10.5.3

Constructors

public WakeupOnElapsedFrames(int frameCount)

This constructor creates a non-passive WakeupOnElapsedFrames object that

informs the Java 3D scheduler to wake up the specified Behavior object after it
has drawn frameCount frames. A frameCount value of N means wake up at the
end of frame N, where the current frame is 0. A frameCount value of 0 means
wake up at the end of the current frame.

public WakeupOnElapsedFrames(int frameCount, boolean passive) New in 1.2

This constructor creates a WakeupOnElapsedFrames criterion. The passive flag

indicates whether this behavior is passive. A non-passive behavior will cause the
rendering system to run continuously. A passive behavior will only run when
some other event causes a frame to be run.

Methods

public int getElapsedFrameCount()

This method returns the frame count that was specified when constructing this
object.

public boolean isPassive() New in 1.2

This method retrieves the state of the passive flag that was used when construct-
ing this object.

10.5.3.6 WakeupOnElapsedTime
This WakeupCriterion object specifies that Java 3D should awaken this behavior
after an elapsed number of milliseconds.

Constructors

public WakeupOnElapsedTime(long milliseconds)

This constructor creates a WakeupOnElapsedTime object that informs the

Java 3D scheduler to wake up the specified Behavior object after the specified
number of milliseconds.

Note: The Java 3D scheduler will schedule the object after the specified number
of milliseconds have elapsed, not before. However, the elapsed time may actually
be slightly greater than the time specified.

Version 1.2, March 2000 277

10.5.3 The WakeupCriterion Objects BEHAVIORS AND INTERPOLATORS

Methods

public long getElapsedFrameTime()

This method returns the WakeupCriterion’s elapsed time value in milliseconds.

10.5.3.7 WakeupOnSensorEntry
This WakeupCriterion object specifies that Java 3D should awaken this behavior
when any sensor enters the specified region.

Note: There can be situations in which a sensor may enter and then exit an
armed region so rapidly that neither the Entry nor Exit condition is engaged.

Constructors

public WakeupOnSensorEntry(Bounds region)

This constructor creates a WakeupOnSensorEntry object that informs the

Java 3D scheduler to wake up the specified Behavior object whenever it detects a
sensor within the specified region for the first time.

Methods

public Bounds getBounds()

This method returns the Bounds object used in creating this WakeupCriterion.

public Sensor getTriggeringSensor() New in 1.2

This method retrieves he Sensor object that caused the wakeup.

10.5.3.8 WakeupOnSensorExit
This WakeupCriterion object specifies that Java 3D should awaken this behavior
when any sensor, already marked as within the region, is no longer in that region.

Note: This semantic guarantees that an Exit condition is engaged if its corre-
sponding Entry condition was engaged.

278 The Java 3D API Specification

BEHAVIORS AND INTERPOLATORS The WakeupCriterion Objects 10.5.3

Constructors

public WakeupOnSensorExit(Bounds region)

This constructor creates a WakeupOnSensorExit object that informs the

Java 3D scheduler to wake up the specified Behavior object the first time it
detects that a sensor has left the specified region.

Methods

public Bounds getBounds()

This method returns the Bounds object used in creating this WakeupCriterion.

public Sensor getTriggeringSensor() New in 1.2

This method retrieves the Sensor object that caused the wakeup.

10.5.3.9 WakeupOnCollisionEntry
This WakeupCriterion object specifies that Java 3D should awaken the Wake-
upOnCollisionEntry behavior when the specified object collides with any other
object in the scene graph.

Constants

public static final int USE_GEOMETRY

public static final int USE_BOUNDS

These constants specify whether collision against a Group, Shape, or Morph

node is done using the actual geometry or whether the geometric bounds are
used as an approximation.

Constructors

public WakeupOnCollisionEntry(SceneGraphPath armingPath)

public WakeupOnCollisionEntry(SceneGraphPath armingPath,
int speedHint)
public WakeupOnCollisionEntry(Node armingNode)
public WakeupOnCollisionEntry(Node armingNode, int speedHint)
public WakeupOnCollisionEntry(Bounds armingBounds)

These constructors create a WakeupOnCollisionEntry object that informs the

Java 3D scheduler to wake up the specified Behavior object if the specified
“armed” node’s geometry or the specified “armed” bounds collides with any

Version 1.2, March 2000 279

10.5.3 The WakeupCriterion Objects BEHAVIORS AND INTERPOLATORS

other object in the scene graph. The speedHint flag is either USE_GEOMETRY or
USE_BOUNDS.

Methods

public SceneGraphPath getArmingPath()

public Bounds getArmingBounds()

These methods return the “collideable” path or bounds object used in specifying
the collision detection.

public SceneGraphPath getTriggeringPath()

public Bounds getTriggeringBounds()

These methods return the path or bounds object that caused the collision.

10.5.3.10 WakeupOnCollisionExit
This WakeupCriterion object specifies that Java 3D should awaken the Wake-
upOnCollisionExit behavior when the specified object no longer collides with
any other object in the scene graph.

Constants

public static final int USE_GEOMETRY

public static final int USE_BOUNDS

These constants specify whether collision against a Group, Shape, or Morph

node is done using the actual geometry or whether the geometric bounds are
used as an approximation.

Constructors

public WakeupOnCollisionExit(SceneGraphPath armingPath)

public WakeupOnCollisionExit(SceneGraphPath armingPath,
int speedHint)
public WakeupOnCollisionExit(Node armingNode)
public WakeupOnCollisionExit(Node armingNode, int speedHint)
public WakeupOnCollisionExit(Bounds armingBounds)

These constructors create a WakeupOnCollisionExit object that informs the

Java 3D scheduler to wake up the specified Behavior object if the specified
“armed” node’s geometry or the specified “armed” bounds no longer collides
with any other object in the scene graph. The speedHint flag is either USE_
GEOMETRY or USE_BOUNDS.

280 The Java 3D API Specification

BEHAVIORS AND INTERPOLATORS The WakeupCriterion Objects 10.5.3

Methods

public SceneGraphPath getArmingPath()

public Bounds getArmingBounds()

These methods return the “collideable” path or bounds object used in specifying
the collision detection.

public SceneGraphPath getTriggeringPath()

public Bounds getTriggeringBounds()

These methods return the path or bounds object that caused the collision.

10.5.3.11 WakeupOnCollisionMovement
This WakeupCriterion object specifies that Java 3D should awaken the Wake-
upOnCollisionMovement behavior when the specified object moves while in a
state of collision with any other object in the scene graph.

Constants

public static final int USE_GEOMETRY

public static final int USE_BOUNDS

These constants specify whether collision against a Group, Shape, or Morph

node is done using the actual geometry or whether the geometric bounds are
used as an approximation.

Constructors

public WakeupOnCollisionMovement(SceneGraphPath armingPath)

public WakeupOnCollisionMovement(SceneGraphPath armingPath,
int speedHint)
public WakeupOnCollisionMovement(Node armingNode)
public WakeupOnCollisionMovement(Node armingNode, int speedHint)
public WakeupOnCollisionMovement(Bounds armingBounds)

These constructors create a WakeupOnCollisionMovement object that informs

the Java 3D scheduler to wake up the specified Behavior object if the specified
node’s geometry or the specified bounds collides with any other object in the
scene graph. The speedHint flag is either USE_GEOMETRY or USE_BOUNDS.

Version 1.2, March 2000 281

10.5.3 The WakeupCriterion Objects BEHAVIORS AND INTERPOLATORS

Methods

public SceneGraphPath getArmingPath()

public Bounds getArmingBounds()

These methods return the “collideable” path or bounds object used in specifying
the collision detection.

public SceneGraphPath getTriggeringPath()

public Bounds getTriggeringBounds()

These methods return the path or bounds object that caused the collision.

10.5.3.12 WakeupOnViewPlatformEntry
This WakeupCriterion object specifies that Java 3D should awaken the Wake-
upOnViewPlatformEntry behavior when any ViewPlatform enters the specified
region.

Note: There can be situations in which a ViewPlatform may enter and then exit
an armed region so rapidly that neither the Entry nor Exit condition is engaged.

Constructors

public WakeupOnViewPlatformEntry(Bounds region)

This constructor creates a WakeupOnViewPlatformEntry object that informs

the Java 3D scheduler to wake up the specified Behavior object whenever it
detects a ViewPlatform center within the specified region for the first time.

Methods

public Bounds getBounds()

This method returns the Bounds object used in creating this WakeupCriterion.

10.5.3.13 WakeupOnViewPlatformExit
This WakeupCriterion object specifies that Java 3D should awaken the Wake-
upOnViewPlatformExit behavior when any ViewPlatform, already marked as
within the region, is no longer in that region.

Note: This semantic guarantees that an Exit condition gets engaged if its corre-
sponding Entry condition was engaged.

282 The Java 3D API Specification

BEHAVIORS AND INTERPOLATORS The WakeupCriterion Objects 10.5.3

Constructors

public WakeupOnViewPlatformExit(Bounds region)

This constructor creates a WakeupOnViewPlatformExit object that informs the

Java 3D scheduler to wake up the specified Behavior object the first time it
detects that a ViewPlatform has left the specified region.

Methods

public Bounds getBounds()

This method returns the Bounds object used in creating this WakeupCriterion.

10.5.3.14 WakeupOnTransformChange
The WakeupOnTransformChange object specifies a wakeup when the transform
within a specified TransformGroup changes.

Constructors

public WakeupOnTransformChange(TransformGroup node)

This constructor creates a new WakeupOnTransformChange criterion.

Methods

public TransformGroup getTransformGroup()

This method returns the TransformGroup node used in creating this WakeupCri-
terion.

10.5.3.15 WakeupAnd
The WakeupAnd class specifies any number of wakeup conditions ANDed
together. This WakeupCondition object specifies that Java 3D should awaken this
Behavior when all of the WakeupCondition’s constituent wakeup criteria become
valid.

Constructors

public WakeupAnd(WakeupCriterion conditions[])

This constructor creates a WakeupAnd object that informs the Java 3D sched-
uler to wake up this Behavior object when all the conditions specified in the
array of WakeupCriterion objects have become valid.

Version 1.2, March 2000 283

10.5.3 The WakeupCriterion Objects BEHAVIORS AND INTERPOLATORS

10.5.3.16 WakeupOr
The WakeupOr class specifies any number of wakeup conditions ORed together.
This WakeupCondition object specifies that Java 3D should awaken this Behav-
ior when any of the WakeupCondition’s constituent wakeup criteria becomes
valid.

Constructors

public WakeupOr(WakeupCriterion conditions[])

This constructor creates a WakeupOr object that informs the Java 3D scheduler
to wake up this Behavior object when any condition specified in the array of
WakeupCriterion objects becomes valid.

10.5.3.17 WakeupAndOfOrs
The WakeupAndOfOrs class specifies any number of OR wakeup conditions
ANDed together. This WakeupCondition object specifies that Java 3D should
awaken this Behavior when all of the WakeupCondition’s constituent WakeupOr
conditions become valid.

Constructors

public WakeupAndOfOrs(WakeupOr conditions[])

This constructor creates a WakeupAndOfOrs object that informs the Java 3D

scheduler to wake up this Behavior object when all of the WakeupOr conditions
specified in the array of WakeupOr objects become valid.

10.5.3.18 WakeupOrOfAnds
The WakeupOrOfAnds class specifies any number of AND wakeup conditions
ORed together. This WakeupCondition object specifies that Java 3D should
awaken this Behavior when any of the WakeupCondition’s constituent Wakeu-
pAnd conditions becomes valid.

Constructors

public WakeupOrOfAnds(WakeupAnd conditions[])

This constructor creates a WakeupOrOfAnds object that informs the Java 3D

scheduler to wake up this Behavior object when any of the WakeupAnd condi-
tions specified in the array of WakeupAnd objects becomes valid.

284 The Java 3D API Specification

BEHAVIORS AND INTERPOLATORS Mapping Time to Alpha 10.6.1

10.6 Interpolator Behaviors

This section describes Java 3D’s predefined Interpolator behaviors. They are
called interpolators because they smoothly interpolate among the two extreme
values that an interpolator can produce. Interpolators perform simple behavioral
acts, yet they provide broad functionality.
The Java 3D API provides interpolators for a number of functions: manipulating
transforms within a TransformGroup, modifying the values of a Switch node,
and modifying Material attributes such as color and transparency.
These predefined Interpolator behaviors share the same mechanism for specify-
ing and later for converting a temporal value into an alpha value. Interpolators
consist of two portions: a generic portion that all interpolators share and a
domain-specific portion.
The generic portion maps time in milliseconds onto a value in the range
[0.0, 1.0] inclusive. The domain-specific portion maps an alpha value in the
range [0.0, 1.0] onto a value appropriate to the predefined behavior’s range of
outputs. An alpha value of 0.0 generates an interpolator’s minimum value, an
alpha value of 1.0 generates an interpolator’s maximum value, and an alpha
value somewhere in between generates a value proportionally in between the
minimum and maximum values.

10.6.1 Mapping Time to Alpha

Several parameters control the mapping of time onto an alpha value. That map-
ping is deterministic as long as its parameters do not change. Thus, two different
interpolators with the same parameters will generate the same alpha value given
the same time value. This means that two interpolators that do not communicate
can still precisely coordinate their activities, even if they reside in different
threads or even different processors—as long as those processors have consistent
clocks.
Figure 10-1 shows the components of an interpolator’s time-to-alpha mapping.
Time is represented on the horizontal axis. Alpha is represented on the vertical
axis. As we move from left to right, we see the alpha value start at 0.0, rise to
1.0, and then decline back to 0.0 on the right-hand side.
On the left-hand side, the trigger time defines when this interpolator’s waveform
begins in milliseconds. The region directly to the right of the trigger time,
labeled Phase Delay, defines a time period where the waveform does not change.

Version 1.2, March 2000 285

10.6.1 Mapping Time to Alpha BEHAVIORS AND INTERPOLATORS

During phase delays alpha is either 0 or 1, depending on which region it pre-

cedes.
Phase delays provide an important means for offsetting multiple interpolators
from one another, especially where the interpolators have all the same parame-
ters. The next four regions, labeled α increasing, α at 1, α decreasing, and α at
0, all specify durations for the corresponding values of alpha.
Interpolators have a loop count that determines how many times to repeat the
sequence of alpha increasing, alpha at 1, alpha decreasing, and alpha at 0; they
also have associated mode flags that enable either the increasing or decreasing
portions, or both, of the waveform.

Phase α α α α
delay increasing at 1 decreasing at 0
α

Trigger

Figure 10-1 An Interpolator’s Generic Time-to-Alpha Mapping Sequence

Developers can use the loop count in conjunction with the mode flags to generate
various kinds of actions. Specifying a loop count of 1 and enabling the mode flag
for only the alpha-increasing and alpha-at-1 portion of the waveform, we would
get the waveform shown in Figure 10-2.

Time

Figure 10-2 An Interpolator Set to a Loop Count of 1 with Mode Flags Set to Enable Only
the Alpha-Increasing and Alpha-at-1 Portion of the Waveform

In Figure 10-2, the alpha value is 0 before the combination of trigger time plus
the phase delay duration. The alpha value changes from 0 to 1 over a specified
interval of time, and thereafter the alpha value remains 1 (subject to the repro-
gramming of the interpolator’s parameters). A possible use of a single alpha-

286 The Java 3D API Specification

BEHAVIORS AND INTERPOLATORS Mapping Time to Alpha 10.6.1

increasing value might be to combine it with a rotation interpolator to program a

door opening.
Similarly, by specifying a loop count of 1 and a mode flag that enables only the
alpha-decreasing and alpha-at-0 portion of the waveform, we would get the
waveform shown in Figure 10-3.
In Figure 10-3, the alpha value is 1 before the combination of trigger time plus
the phase delay duration. The alpha value changes from 1 to 0 over a specified
interval, and thereafter the alpha value remains 0 (subject to the reprogramming
of the interpolator’s parameters). A possible use of a single α-decreasing value
might be to combine it with a rotation interpolator to program a door closing.

1
0

Time

Figure 10-3 An Interpolator Set to a Loop Count of 1 with Mode Flags Set to Enable Only
the Alpha-Decreasing and Alpha-at-0 Portion of the Waveform

We can combine both of the above waveforms by specifying a loop count of 1

and setting the mode flag to enable both the alpha-increasing and alpha-at-1 por-
tion of the waveform as well as the alpha-decreasing and alpha-at-0 portion of
the waveform. This combination would result in the waveform shown in
Figure 10-4.

1
0 0

Time

Figure 10-4 An Interpolator Set to a Loop Count of 1 with Mode Flags Set to Enable All Por-
tions of the Waveform

In Figure 10-4, the alpha value is 0 before the combination of trigger time plus
the phase delay duration. The alpha value changes from 0 to 1 over a specified
period of time, remains at 1 for another specified period of time, then changes
from 1 to 0 over a third specified period of time, and thereafter the alpha value
remains 0 (subject to the reprogramming of the interpolator’s parameters). A
possible use of an alpha-increasing followed by an alpha-decreasing value might

Version 1.2, March 2000 287

10.6.1 Mapping Time to Alpha BEHAVIORS AND INTERPOLATORS

be to combine it with a rotation interpolator to program a door swinging open

and then closing.
By increasing the loop count, we can get repetitive behavior, such as a door
swinging open and closed some number of times. At the extreme, we can specify
a loop count of –1 (representing infinity).
We can construct looped versions of the waveforms shown in Figure 10-2,
Figure 10-3, and Figure 10-4. Figure 10-5 shows a looping interpolator with
mode flags set to enable only the alpha-increasing and alpha-at-1 portion of the
waveform.

1 1 1 1 1 1 1
0 0 0 0 0 0 0

Time

Figure 10-5 An Interpolator Set to Loop Infinitely and Mode Flags Set to Enable Only the
Alpha-Increasing and Alpha-at-1 Portion of the Waveform

In Figure 10-5, alpha goes from 0 to 1 over a fixed duration of time, stays at 1 for
another fixed duration of time, and then repeats.
Similarly, Figure 10-6 shows a looping interpolator with mode flags set to enable
only the alpha-decreasing and alpha-at-0 portion of the waveform.

1 1 1 1 1 1 1
0 0 0 0 0 0 0

Time

Figure 10-6 An Interpolator Set to Loop Infinitely and Mode Flags Set to Enable Only the
Alpha-Decreasing and Alpha-at-0 Portion of the Waveform

Finally, Figure 10-7 shows a looping interpolator with both the increasing and
decreasing portions of the waveform enabled.
In all three cases shown by Figure 10-5, Figure 10-6, and Figure 10-7, we can
compute the exact value of alpha at any point in time.

288 The Java 3D API Specification

BEHAVIORS AND INTERPOLATORS The Alpha Class 10.6.3

1 1 1 1
0 0 0 0 0

Time

Figure 10-7 An Interpolator Set to Loop Infinitely and Mode Flags Set to Enable All Por-
tions of the Waveform

Java 3D’s preprogrammed behaviors permit other behaviors to change their

parameters. When such a change occurs, the alpha value changes to match the
state of the newly parameterized interpolator.

10.6.2 Acceleration of Alpha

Commonly, developers want alpha to change slowly at first and to speed up until
the change in alpha reaches some appropriate rate. This is analogous to acceler-
ating your car up to the speed limit—it does not start off immediately at the
speed limit. Developers specify this “ease-in, ease-out” behavior through two
additional parameters, the increasingAlphaRampDuration and the decreasin-
gAlphaRampDuration.

Each of these parameters specifies a period within the increasing or decreasing

alpha duration region during which the “change in alpha” is accelerated (until it
reaches its maximum per-unit-of-time step size) and then symmetrically deceler-
ated. Figure 10-8 shows three general examples of how the increasingAl-
phaRampDuration method can be used to modify the alpha waveform. A value of
0 for the increasing ramp duration implies that α is not accelerated; it changes at
a constant rate. A value of 0.5 or greater (clamped to 0.5) for this increasing
ramp duration implies that the change in α is accelerated during the first half of
the period and then decelerated during the second half of the period. For a value
of n that is less than 0.5, alpha is accelerated for duration n, held constant for
duration (1.0 – 2n), then decelerated for duration n of the period.

10.6.3 The Alpha Class

The Alpha node component object provides common methods for converting a
time value into an alpha value (a value in the range 0.0 to 1.0). The Alpha object
is effectively a function of time that generates alpha values in the range [0,1]
when sampled: ft = [0,1]. The function ft and the characteristics of the Alpha
object are determined by the following user-definable parameters:

Version 1.2, March 2000 289

10.6.3 The Alpha Class BEHAVIORS AND INTERPOLATORS

• loopCount: Specifies the number of times to run this Alpha. A value of -1

specifies that the Alpha loops indefinitely.
• triggerTime: Specifies the time in milliseconds since the start time that
this object first triggers. If startTime + triggerTime is less than cur-
rentTime, the Alpha object is started as soon as possible by the system.
• phaseDelayDuration: Specifies the number of milliseconds to wait after
triggerTime before actually starting this Alpha.
• mode: The mode can be set to INCREASING_ENABLE or DECREAS-
ING_ENABLE, or the ORed value of the two. INCREASING_ENABLE
activates the increasing Alpha parameters described below. DECREAS-
ING_ENABLE activates the decreasing Alpha parameters listed below.

Alpha Ramp Examples

Ramp = 0 Ramp ≥ 1/2 Duration Ramp < 1/2 Duration

•

α Acceleration

α Velocity

1 1 1
α Value
0 0 0

α Increasing α Increasing α Increasing

Figure 10-8 How an Alpha-Increasing Waveform Changes with Various Values of

increasingAlphaRampDuration

The increasing Alpha parameters are:

• increasingAlphaDuration: Specifies the time period during which Al-
pha goes from zero to one.
• increasingAlphaRampDuration: Specifies the time period during which
the Alpha step size increases at the beginning of the increasingAlphaDu-

290 The Java 3D API Specification

BEHAVIORS AND INTERPOLATORS The Alpha Class 10.6.3

ration and, correspondingly, decreases at the end of the increasingAl-

phaDuration. This parameter is clamped to half of increasing-
AlphaDuration. When this parameter is non-zero, one gets constant accel-
eration while it is in effect; constant positive acceleration at the beginning
of the ramp and constant negative acceleration at the end of the ramp. If
this parameter is zero, the effective velocity of the Alpha value is constant
and the acceleration is zero (i.e., linearly increasing alpha ramp).
• alphaAtOneDuration: Specifies the time period that Alpha stays at one.
The decreasing Alpha parameters are:
• decreasingAlphaDuration: Specifies the time period during which Al-
pha goes from one to zero.
• decreasingAlphaRampDuration: Specifies the time period during which
the Alpha step size increases at the beginning of the decreasingAlphaDu-
ration and, correspondingly, decreases at the end of the decreasingAl-
phaDuration. This parameter is clamped to half of decreasingAlpha-
Duration. When this parameter is non-zero, one gets constant acceleration
while it is in effect; constant positive acceleration at the beginning of the
ramp and constant negative acceleration at the end of the ramp. If this pa-
rameter is zero, the effective velocity of the Alpha value is constant and the
acceleration is zero (i.e., a linearly-decreasing alpha ramp).
• alphaAtZeroDuration: Specifies the time period that Alpha stays at zero.

Constants

public static final int INCREASING_ENABLE

public static final int DECREASING_ENABLE

These flags specify that this alpha’s mode is to use the increasing or decreasing
component of the alpha, respectively.

Constructors

public Alpha()

Constructs an Alpha object with default parameters:

Parameter Default Value
loopCount –1
mode INCREASING_ENABLE
triggerTime 0

Version 1.2, March 2000 291

10.6.3 The Alpha Class BEHAVIORS AND INTERPOLATORS

Parameter Default Value

phaseDelayDuration 0
increasingAlphaDuration 1000
increasingAlphaRampDuration 0
alphaAtOneDuration 0
decreasingAlphaDuration 0
decreasingAlphaRampDuration 0
alphaAtZeroDuration 0

public Alpha(int loopCount, long increasingAlphaDuration)

public Alpha(int loopCount, long triggerTime,
long phaseDelayDuration, long increasingAlphaDuration,
long increasingAlphaRampDuration, long alphaAtOneDuration)
public Alpha(int loopCount, int mode, long triggerTime,
long phaseDelayDuration, long increasingAlphaDuration,
long increasingAlphaRampDuration, long alphaAtOneDuration,
long decreasingAlphaDuration,
long decreasingAlphaRampDuration, long alphaAtZeroDuration)

Constructs a new Alpha object using the specified parameters to define the alpha
phases for the object.

Methods

public float value()

public float value(long atTime)

These methods return the alpha value (between 0.0 and 1.0 inclusive) based on
the time-to-alpha parameters established for this interpolator. The first method
returns the alpha for the current time. The second method returns the alpha for an
arbitrary given time. If the alpha mapping has not started, the starting alpha value
is returned. If the alpha mapping has completed, the ending alpha value is
returned.

public void setStartTime(long startTime)

public long getStartTime()

These methods set and retrieve this alpha’s start time, the base for all relative
time specifications. The default value of startTime is the system start time,
defined to be a global time base representing the start of Java 3D execution.

292 The Java 3D API Specification

BEHAVIORS AND INTERPOLATORS The Alpha Class 10.6.3

public void setLoopCount(int loopCount)

public int getLoopCount()

These methods set and retrieve this alpha’s loop count.

public void setMode(int mode)

public int getMode()

These methods set and retrieve this alpha’s mode, which defines which of the
alpha regions are active. The mode is one of the following values: INCREASING_
ENABLE, DECREASING_ENABLE, or both (when both of these modes are ORed
together).
If the mode is INCREASING_ENABLE, the increasingAlphaDuration, increas-
ingAlphaRampDuration, and alphaAtOneDuration are active. If the mode is
DECREASING_ENABLE, the decreasingAlphaDuration, decreasingAlphaRamp-
Duration, and alphaAtZeroDuration are active. If the mode is both constants
ORed, all regions are active. Active regions are all preceded by the phase delay
region.

public void setTriggerTime(long triggerTime)

public long getTriggerTime()

These methods set and retrieve this alpha’s trigger time.

public void setPhaseDelayDuration(long phaseDelayDuration)

public long getPhaseDelayDuration()

These methods set and retrieve this alpha’s phase delay duration.

public void setIncreasingAlphaDuration(long

increasingAlphaDuration)
public long getIncreasingAlphaDuration()

These methods set and retrieve this alpha’s increasingAlphaDuration.

public void setIncreasingAlphaRampDuration(long

increasingAlphaRampDuration)
public long getIncreasingAlphaRampDuration()

These methods set and retrieve this alpha’s increasingAlphaRampDuration.

public long getAlphaAtOneDuration()

This method sets and retrieves this alpha’s alphaAtOneDuration.

Version 1.2, March 2000 293

10.6.4 The Interpolator Base Class BEHAVIORS AND INTERPOLATORS

public void setDecreasingAlphaDuration(long

decreasingAlphaDuration)
public long getDecreasingAlphaDuration()

These methods set and retrieve this alpha’s decreasingAlphaDuration.

public void setDecreasingAlphaRampDuration(long

decreasingAlphaRampDuration)
public long getDecreasingAlphaRampDuration()

These methods set and retrieve this alpha’s decreasingAlphaRampDuration.

public long getAlphaAtZeroDuration()

This method sets and retrieves this alpha’s alphaAtZeroDuration.

public boolean finished()

This method returns true if this Alpha object is past its activity window, that is,
if it has finished all its looping activity. This method returns false if this Alpha
object is still active.

10.6.4 The Interpolator Base Class

Interpolator is an abstract behavior class from which several subclasses are
derived. The base Interpolator class contains an Alpha object that provides the
means for converting a time value (in milliseconds) into an alpha value in the
range [0.0, 1.0] inclusive. Its subclasses map this alpha value into domain-spe-
cific values in their range.

Constants

protected WakeupCriterion defaultWakeupCriterion

This is the default WakeupCondition for all interpolators. The wakeupOn method
of Behavior, which takes a WakeupCondition as the method parameter, will need
to be called at the end of the processStimulus method of any class that sub-
classes Interpolator. This is done with the following method call:
wakeupOn(defaultWakeupCriterion);

Constructors
The Interpolator behavior class has the following constructors.

294 The Java 3D API Specification

BEHAVIORS AND INTERPOLATORS PositionInterpolator Object 10.6.5

public Interpolator()

Constructs and initializes a new Interpolator a null alpha value.

public Interpolator(Alpha alpha)

Constructs and initializes a new Interpolator with the specified alpha value. This
constructor provides the common initialization code for all specializations of
Interpolator.

Methods

public void setAlpha(Alpha alpha)

public Alpha getAlpha()

These methods set and retrieve this interpolator’s Alpha object. Setting it to null
causes the Interpolator to stop running.

public void setEnable(boolean state)

public boolean getEnable()

These methods set and retrieve this Interpolator’s enabled state—the default is
enabled.

public void initialize()

This is the generic predefined interpolator initialize method. It schedules the

behavior to awaken at the next frame.

10.6.5 PositionInterpolator Object

The PositionInterpolator class extends Interpolator. It modifies the translational
component of its target TransformGroup by linearly interpolating between a pair
of specified positions (using the value generated by the specified Alpha object).
The interpolated position is used to generate a translation transform along the
local X-axis of this interpolator.

Constructors
The PositionInterpolator object specifies the following constructors.

public PositionInterpolator(Alpha alpha, TransformGroup target)

Constructs a trivial position interpolator with a specified target, an axisOf-

Translation set to the identity transformation, a startPosition of 0.0, and an
endPosition of 1.0 along the X-axis.

Version 1.2, March 2000 295

10.6.6 RotationInterpolator Object BEHAVIORS AND INTERPOLATORS

public PositionInterpolator(Alpha alpha, TransformGroup target,

Transform3D axisOfTranslation, float startPosition,
float endPosition)

Constructs and initializes a new PositionInterpolator that varies the target Trans-
formGroup node’s translational component (startPosition and endPosition).
The axisOfTranslation parameter specifies the transform that defines the local
coordinate system in which this interpolator operates. The translation is done
along the X-axis of this local coordinate system.

Methods
The PositionInterpolator object specifies the following methods.

public void setStartPosition(float position)

public float getStartPosition()

These two methods set and get the Interpolator’s start position.

public void setEndPosition(float position)

public float getEndPosition()

These two methods set and get the Interpolator’s end position.

public void setTarget(TransformGroup target)

public TransformGroup getTarget()

These two methods set and get the Interpolator’s target TransformGroup node.

public void setAxisOfTranslation(Transform3D axis)

public Transform3D getAxisOfTranslation()

These two methods set and get the Interpolator’s axis of translation.

public void processStimulus(Enumeration criteria)

This method is invoked by the behavior scheduler every frame. It maps the alpha
value that corresponds to the current time into a translation value, computes a
transform based on this value, and updates the specified TransformGroup node
with this new transform.

10.6.6 RotationInterpolator Object

The RotationInterpolator class extends Interpolator. It modifies the rotational
component of its target TransformGroup by linearly interpolating between a pair
of specified angles (using the value generated by the specified Alpha object). The

296 The Java 3D API Specification

BEHAVIORS AND INTERPOLATORS RotationInterpolator Object 10.6.6

interpolated angle is used to generate a rotation transform about the local Y-axis
of this interpolator.

Constructors

public RotationInterpolator(Alpha alpha, TransformGroup target)

Constructs a trivial rotation interpolator with a specified target, an axisOf-

Rotation set to identity, a minimum angle of 0 radians, and a maximum angle of
2π radians.

public RotationInterpolator(Alpha alpha, TransformGroup target,

Transform3D axisOfRotation, float minimumAngle,
float maximumAngle)

Constructs a new rotation interpolator that varies the target TransformGroup

node’s rotational component. The minimumAngle parameter is the starting angle,
in radians; maximumAngle is the ending angle, in radians. The axisOfRotation
parameter specifies the transform that defines the local coordinate system in
which this interpolator operates. The rotation is done about the Y-axis of this
local coordinate system.

Methods

public void setMinimumAngle(float angle)

public float getMinimumAngle()

These two methods set and get the interpolator’s minimum rotation angle, in
radians.

public void setMaximumAngle(float angle)

public float getMaximumAngle()

These two methods set and get the interpolator’s maximum rotation angle, in
radians.

public void setAxisOfRotation(Transform3D axis)

public Transform3D getAxisOfRotation()

These two methods set and get the interpolator’s axis of rotation.

public void setTarget(TransformGroup target)

public TransformGroup getTarget()

These two methods set and get the interpolator’s target TransformGroup node.

Version 1.2, March 2000 297

10.6.7 ColorInterpolator Object BEHAVIORS AND INTERPOLATORS

public void processStimulus(Enumeration criteria)

This method is invoked by the behavior scheduler every frame. It maps the alpha
value that corresponds to the current time into a rotation angle, computes a trans-
form based on this angle, and updates the specified TransformGroup node with
this new transform.

10.6.7 ColorInterpolator Object

The ColorInterpolator class extends Interpolator. It modifies the diffuse color of
its target material object by linearly interpolating between a pair of specified col-
ors (using the value generated by the specified Alpha object).

Constructors

public ColorInterpolator(Alpha alpha, Material target)

Constructs a trivial color interpolator with a specified target, a start color of

black, and an end color of white.

public ColorInterpolator(Alpha alpha, Material target,

Color3f startColor, color3f endColor)

Constructs a new ColorInterpolator object that varies the diffuse color of the tar-
get material between two color values (startColor and endColor).

Methods

public void setStartColor(Color3f color)

public void getStartColor(Color3f color)

These two methods set and get the interpolator’s start color.

public void setEndColor(Color3f color)

public void getEndColor(Color3f color)

These two methods set and get the interpolator’s end color.

public void setTarget(Material target)

public Material getTarget()

These two methods set and get the interpolator’s target Material component
object.

298 The Java 3D API Specification

BEHAVIORS AND INTERPOLATORS ScaleInterpolator Object 10.6.8

public void processStimulus(Enumeration criteria)

This method is invoked by the behavior scheduler every frame. It maps the alpha
value that corresponds to the current time into a color value and updates the dif-
fuse color of the target Material object with this new color value.

10.6.8 ScaleInterpolator Object

The ScaleInterpolator class extends Interpolator. It modifies the uniform scale
component of its target TransformGroup by linearly interpolating between a pair
of specified scale values (using the value generated by the specified Alpha
object). The interpolated scale value is used to generate a scale transform in the
local coordinate system of this interpolator.

Constructors

public ScaleInterpolator(Alpha alpha, TransformGroup target)

Constructs a trivial scale interpolator that varies its target TransformGroup node
between the two scale values, using the specified alpha, an identity matrix, a
minimum scale of 0.1, and a maximum scale of 1.0.

public ScaleInterpolator(Alpha alpha, TransformGroup target,

Transform3D axisOfScale, float minimumScale,
float maximumScale)

Constructs a new ScaleInterpolator object that varies the target TransformGroup

node’s scale component between two scale values (minimumScale and maximum-
Scale). The axisOfScale parameter specifies the transform that defines the local
coordinate system in which this interpolator operates. The scale is done about the
origin of this local coordinate system.

Methods

public void setMinimumScale(float scale)

public float getMinimumScale()

These two methods set and get the interpolator’s minimum scale.

public void setMaximumScale(float scale)

public float getMaximumScale()

These two methods set and get the interpolator’s maximum scale.

Version 1.2, March 2000 299

10.6.9 SwitchValueInterpolator Object BEHAVIORS AND INTERPOLATORS

public void setAxisOfScale(Transform3D axis)

public Transform3D getAxisOfScale()

These two methods set and get the interpolator’s axis of scale.

public void setTarget(TransformGroup target)

public TransformGroup getTarget()

These two methods set and get the interpolator’s target TransformGroup node.

public void processStimulus(Enumeration criteria)

This method is invoked by the behavior scheduler every frame. It maps the alpha
value that corresponds to the current time into a scale value, computes a trans-
form based on this value, and updates the specified TransformGroup node with
this new transform.

10.6.9 SwitchValueInterpolator Object

The SwitchValueInterpolator class extends Interpolator. It modifies the selected
child of the target Switch node by linearly interpolating between a pair of speci-
fied child index values (using the value generated by the specified Alpha object).

Constructors

public SwitchValueInterpolator(Alpha alpha, Switch target)

public SwitchValueInterpolator(Alpha alpha, Switch target,
int firstChildIndex, int lastChildIndex)

Constructs a new SwitchValueInterpolator object that varies the target Switch

node’s child index between the two values provided (firstChildIndex, the
index of the first children in the Switch node to select, and lastChildIndex, the
index of the last children in the Switch node to select).

Methods

public void setFirstChildIndex(int firstIndex)

public int getFirstChildIndex()

These two methods set and get the interpolator’s first child index.

public void setLastChildIndex(int lastIndex)

public int getLastChildIndex()

These two methods set and get the interpolator’s last child index.

300 The Java 3D API Specification

BEHAVIORS AND INTERPOLATORS TransparencyInterpolator Object 10.6.10

public void setTarget(Switch target)

public Switch getTarget()

These two methods set and get the interpolator’s target Switch node.

public void processStimulus(Enumeration criteria)

This method is invoked by the behavior scheduler every frame. It maps the alpha
value that corresponds to the current time into a child index value and updates
the specified Switch node with this new child index value.

10.6.10TransparencyInterpolator Object
The TransparencyInterpolator class extends Interpolator. It modifies the transpar-
ency of its target TransparencyAttributes object by linearly interpolating between
a pair of specified transparency values (using the value generated by the specified
Alpha object).

Constructors

public TransparencyInterpolator(Alpha alpha,

TransparencyAttributes target)

Constructs a trivial transparency interpolator with a specified target, a minimum

transparency of 0.0, and a maximum transparency of 1.0.

public TransparencyInterpolator(Alpha alpha,

TransparencyAttributes target, float minimumTransparency,
float maximumTransparency)

Constructs a new TransparencyInterpolator object that varies the target material’s

transparency between the two transparency values (minimumTransparency, the
starting transparency, and maximumTransparency, the ending transparency).

Methods

public void setMinimumTransparency(float transparency)

public float getMinimumTransparency()

These two methods set and get the interpolator’s minimum transparency.

public void setMaximumTransparency(float transparency)

public float getMaximumTransparency()

These two methods set and get the interpolator’s maximum transparency.

Version 1.2, March 2000 301

10.6.11 PathInterpolator Object BEHAVIORS AND INTERPOLATORS

public void setTarget(TransparencyAttributes target)

public TransparencyAttributes getTarget()

These two methods set and get the interpolator’s target TransparencyAttributes
component object.

public void processStimulus(Enumeration criteria)

This method is invoked by the behavior scheduler every frame. It maps the alpha
value that corresponds to the current time into a transparency value and updates
the specified TransparencyAttributes object with this new transparency value.

10.6.11PathInterpolator Object
The PathInterpolator class extends Interpolator. This class defines the base class
for all path interpolators. Subclasses have access to the computePathInterpola-
tion method, which computes the currentInterpolationValue given the cur-
rent time and alpha. The method also computes the currentKnotIndex, which is
based on the currentInterpolationValue.
The currentInterpolationValue is calculated by linearly interpolating among
a series of predefined knot and orientation, pairs (using the value generated by
the specified Alpha object). The last knot must have a value of 1.0. An interme-
diate knot with index k must have a value strictly greater than any knot with
index less than k.

Constants

protected float currentInterpolationValue

This value is the ratio between knot values indicated by the currentKnotIndex
variable. So if a subclass wanted to interpolate between knot values, it would use
the currentKnotIndex to get the bounding knots for the “real” value, then use
the currentInterpolationValue to interpolate between the knots. To calculate
this variable, a subclass needs to call the computePathInterpolation method
from the subclass’s processStimulus method. Then this variable will hold a
valid value that can be used in further calculations by the subclass.
protected int currentKnotIndex

This value is the index of the current base knot value, as determined by the alpha
function. A subclass wishing to interpolate between bounding knots would use
this index and the one following it, and would use the currentInterpolation-
Value variable as the ratio between these indices. To calculate this variable, a
subclass needs to call the computePathInterpolation method from the sub-

302 The Java 3D API Specification

BEHAVIORS AND INTERPOLATORS PositionPathInterpolator Object 10.6.12

class’s processStimulus method. Then this variable will hold a valid value that
can be used in further calculations by the subclass.

Constructors

public PathInterpolator(Alpha alpha, float knots[])

Constructs a new PathInterpolator object that varies the target Transform-

Group node’s transform.

Methods

public int getArrayLengths()

This method retrieves the length of the knot and position arrays (which are the
same length).

public void setKnot(int index, float knot)

public float getKnot(int index)

These methods set and retrieve the knot at the specified index for this interpola-
tor.

protected void setKnots(float[] knots) New in 1.2

public void getKnots(float[] knots) New in 1.2

These methods set and retrieve an array of knot values. The set method replaces
the existing array with the specified array. The get method copies the array of
knots from this interpolator into the specified array. The array must be large
enough to hold all of the knots.

protected void computePathInterpolation()

This method computes the base knot index and interpolation value given the cur-
rent value of alpha and the knots[] array. If the index is 0 and there should be no
interpolation, both the index variable and the interpolation variable are set to 0.
Otherwise, currentKnotIndex is set to the lower index of the two bounding
knot points and the currentInterpolationValue variable is set to the ratio of
the alpha value between these two bounding knot points.

10.6.12PositionPathInterpolator Object
The PositionPathInterpolator class extends PathInterpolator. It modifies the trans-
lational component of its target TransformGroup by linearly interpolating among
a series of predefined knot/position pairs (using the value generated by the spec-

Version 1.2, March 2000 303

10.6.12 PositionPathInterpolator Object BEHAVIORS AND INTERPOLATORS

ified Alpha object). The interpolated position is used to generate a translation

transform in the local coordinate system of this interpolator.
The first knot must have a value of 0.0. The last knot must have a value of 1.0.
An intermediate knot with index k must have a value strictly greater than any
knot with index less than k.

Constructors

public PositionPathInterpolator(Alpha alpha,

TransformGroup target, Transform3D axisOfTranslation,
float knots[], Point3f positions[])

Constructs a new PositionPathInterpolator that varies the translation of the target

TransformGroup’s transform. The axisOfTranslation parameter specifies the
transform that defines the local coordinate system in which this interpolator oper-
ates. The knots parameter specifies an array of knot values that specifies a
spline. The positions parameter specifies an array of position values at the
knots.

Methods

public void setPosition(int index, Point3f position)

public void getPosition(int index, Point3f position)

These two methods set and get the interpolator’s indexed position.

public void getPositions(Point3f[] positions) New in 1.2

This method copies the array of position values from this interpolator into the
specified array. The array must be large enough to hold all of the positions. The
individual array elements must be allocated by the caller.

public void setAxisOfTranslation(Transform3D axis)

public Transform3D getAxisOfTranslation()

These two methods set and get the interpolator’s axis of translation.

public void setTarget(TransformGroup target)

public TransformGroup getTarget()

These two methods set and get the interpolator’s target TransformGroup object.

304 The Java 3D API Specification

BEHAVIORS AND INTERPOLATORS RotPosPathInterpolator Object 10.6.13

public void setPathArrays(float[] knots, Point3f[] positions) New in 1.2

This method replaces the existing arrays of knot values and position values with
the specified arrays. The arrays of knots and positions are copied into this inter-
polator object.

public void processStimulus(Enumeration criteria)

This method is invoked by the behavior scheduler every frame. It maps the alpha
value that corresponds to the current time into a translation value, computes a
transform based on this value, and updates the specified TransformGroup node
with this new transform.

10.6.13RotPosPathInterpolator Object
The RotPosPathInterpolator class extends PathInterpolator. It modifies the rota-
tional and translational components of its target TransformGroup by linearly
interpolating among a series of predefined knot/position and knot/orientation
pairs (using the value generated by the specified Alpha object). The interpolated
position and orientation are used to generate a transform in the local coordinate
system of this interpolator.
The first knot must have a value of 0.0. The last knot must have a value of 1.0.
An intermediate knot with index k must have a value strictly greater than any
knot with index less than k.

Constructors

public RotPosPathInterpolator(Alpha alpha, TransformGroup target,

Transform3D axisOfRotPos, float knots[], Quat4f quats[],
Point3f positions[])

This constructor constructs a new RotPosPathInterpolator that varies the rotation

and translation of the target TransformGroup’s transform. The axisOfRotPos
parameter specifies the transform that defines the local coordinate system in
which this interpolator operates. The knots parameter specifies an array of knot
values that specifies a spline. The quats parameter specifies an array of quater-
nion values at the knots. The positions parameter specifies an array of position
values at the knots.

Version 1.2, March 2000 305

10.6.13 RotPosPathInterpolator Object BEHAVIORS AND INTERPOLATORS

Methods

public void setQuat(int index, Quat4f quat)

public void getQuat(int index, Quat4f quat)

These two methods set and get the interpolator’s indexed quaternion value.

public void getQuats(Quat4f[] quats) New in 1.2

This method copies the array of quaternion values from this interpolator into the
specified array. The array must be large enough to hold all of the quats. The indi-
vidual array elements must be allocated by the caller.

public void setPosition(int index, Point3f position)

public void getPosition(int index, Point3f position)

These two methods set and get the interpolator’s indexed position.

public void getPositions(Point3f[] positions) New in 1.2

This method copies the array of position values from this interpolator into the
specified array. The array must be large enough to hold all of the positions. The
individual array elements must be allocated by the caller.

public void setAxisOfRotPos(Transform3D axisOfRotPos)

public Transform3D getAxisOfRotPos()

These two methods set and get the interpolator’s axis of rotation and translation.

public void setTarget(TransformGroup target)

public TransformGroup getTarget()

These two methods set and get the interpolator’s target TransformGroup object.

public void setPathArrays(float[] knots, Quat4f[] quats,

Point3f[] positions) New in 1.2

This method replaces the existing arrays of knot values, quaternion values, and
position values with the specified arrays. The arrays of knots, quats, and posi-
tions are copied into this interpolator object.

public void processStimulus(Enumeration criteria)

This method is invoked by the behavior scheduler every frame. It maps the alpha
value that corresponds to the current time into translation and rotation values,
computes a transform based on these values, and updates the specified Trans-
formGroup node with this new transform.

306 The Java 3D API Specification

BEHAVIORS AND INTERPOLATORS RotPosScalePathInterpolator Object 10.6.14

10.6.14RotPosScalePathInterpolator Object
The RotPosScalePathInterpolator class extends PathInterpolator. It varies the
rotational, translational, and scale components of its target TransformGroup by
linearly interpolating among a series of predefined knot/position, knot/orienta-
tion, and knot/scale pairs (using the value generated by the specified Alpha
object). The interpolated position, orientation, and scale are used to generate a
transform in the local coordinate system of this interpolator.
The first knot must have a value of 0.0. The last knot must have a value of 1.0.
An intermediate knot with index k must have a value strictly greater than any
knot with index less than k.

Constructors

public RotPosScalePathInterpolator(Alpha alpha,

TransformGroup target, Transform3D axisOfRotPosScale,
float knots[], Quat4f quats[], Point3f positions[],
float scales[])

This constructor constructs a new RotPosScalePathInterpolator that varies the

rotation, translation, and scale of the target TransformGroup’s transform. The
axisOfRotPosScale parameter specifies the transform that defines the local
coordinate system in which this interpolator operates. The knots parameter spec-
ifies an array of knot values that specifies a spline. The quats parameter specifies
an array of quaternion values at the knots. The positions parameter specifies an
array of position values at the knots. The scale parameter specifies the scale
component value.

Methods

public void setScale(int index, float scale)

public float getScale(int index)

These two methods set and get the interpolator’s indexed scale value.

public void getScales(float[] scales) New in 1.2

This method copies the array of scale values from this interpolator into the spec-
ified array. The array must be large enough to hold all of the scales.

public void setQuat(int index, Quat4f quat)

public void getQuat(int index, Quat4f quat)

These two methods set and get the interpolator’s indexed quaternion value.

Version 1.2, March 2000 307

10.6.15 RotationPathInterpolator Object BEHAVIORS AND INTERPOLATORS

public void getQuats(Quat4f[] quats) New in 1.2

This method copies the array of quaternion values from this interpolator into the
specified array. The array must be large enough to hold all of the quats. The indi-
vidual array elements must be allocated by the caller.

public void setPosition(int index, Point3f position)

public void getPosition(int index, Point3f position)

These two methods set and get the interpolator’s indexed position.

public void getPositions(Point3f[] positions) New in 1.2

This method copies the array of position values from this interpolator into the
specified array. The array must be large enough to hold all of the positions. The
individual array elements must be allocated by the caller.

public void setAxisOfRotPosScale(Transform3D axisOfRotPosScale)

public Transform3D getAxisOfRotPosScale()

These two methods set and get the interpolator’s axis of rotation, translation, and
scale.

public void setTarget(TransformGroup target)

public TransformGroup getTarget()

These two methods set and get the interpolator’s target TransformGroup object.

public void setPathArrays(float[] knots, Quat4f[] quats,

Point3f[] positions, float[] scales) New in 1.2

This method replaces the existing arrays of knot values, quaternion values, posi-
tion values, and scale values with the specified arrays. The arrays of knots, quats,
positions, and scales are copied into this interpolator object.

public void processStimulus(Enumeration criteria)

This method is invoked by the behavior scheduler every frame. It maps the alpha
value that corresponds to the current time into translation, rotation, and scale val-
ues, computes a transform based on these values, and updates the specified
TransformGroup node with this new transform.

10.6.15RotationPathInterpolator Object
The RotationPathInterpolator class extends the PathInterpolator class. It varies
the rotational component of its target TransformGroup by linearly interpolating
among a series of predefined knot/orientation pairs (using the value generated by
308 The Java 3D API Specification
BEHAVIORS AND INTERPOLATORS RotationPathInterpolator Object 10.6.15

the specified Alpha object). The interpolated orientation is used to generate a

rotation transform in the local coordinate system of this interpolator.
The first knot must have a value of 0.0. The last knot must have a value of 1.0.
An intermediate knot with index k must have a value strictly greater than any
knot with index less than k.

Constructors

public RotationPathInterpolator(Alpha alpha,

TransformGroup target, Transform3D axisOfRotation,
float knots[], Quat4f quats[])

This constructor constructs a new RotationPathInterpolator object that varies the

target TransformGroup node’s transform. The axisOfRotation parameter speci-
fies the transform that defines the local coordinate system in which this interpo-
lator operates. The knots parameter specifies an array of knot values that
specifies a spline. The quats parameter specifies an array of quaternion values at
the knots.

Methods

public void setQuat(int index, Quat4f quat)

public void getQuat(int index, Quat4f quat)

These two methods set and get the interpolator’s indexed quaternion value.

public void setAxisOfRotation(Transform3D axisOfRotation)

public Transform3D getAxisOfRotation()

These two methods set and get the interpolator’s axis of rotation.

public void setTarget(TransformGroup target)

public TransformGroup getTarget()

These two methods set and get the interpolator’s target TransformGroup object.

public void setPathArrays(float[] knots, Quat4f[] quats) New in 1.2

This method replaces the existing arrays of knot values and quaternion values
with the specified arrays. The arrays of knots and quats are copied into this inter-
polator object.

Version 1.2, March 2000 309

10.7 Level-of-Detail Behaviors BEHAVIORS AND INTERPOLATORS

public void getQuats(Quat4f[] quats) New in 1.2

This method copies the array of quaternion values from this interpolator into the
specified array. The array must be large enough to hold all of the quats. The indi-
vidual array elements must be allocated by the caller.

public void processStimulus(Enumeration criteria)

This method is invoked by the behavior scheduler every frame. It maps the alpha
value that corresponds to the current time into a rotation angle, computes a trans-
form based on this angle, and updates the specified TransformGroup node with
this new transform.

10.7 Level-of-Detail Behaviors

The LOD (Level of Detail) leaf node is an abstract behavior class that operates
on a list of Switch group nodes to select one of the children of the Switch nodes.
Specializations of the LOD abstract behavior node implement various level-of-
detail policies.

10.7.1 LOD Object

The LOD behavior node is an abstract class that is subclassed to implement
selection among two or more levels of detail using an LOD selection criteria
defined by the subclass.

Constructors

public LOD()

Constructs and initializes a new LOD node.

Methods
The LOD node class defines the following methods.

public void addSwitch(Switch switchNode)

public void setSwitch(Switch switchNode, int index)
public void insertSwitch(Switch switchNode, int index)
public void removeSwitch(int index)
public Switch getSwitch(int index)
public int numSwitches()

310 The Java 3D API Specification

BEHAVIORS AND INTERPOLATORS DistanceLOD Object 10.7.2

The addSwitch method appends the specified Switch node to this LOD’s list of
switches. The setSwitch method replaces the specified Switch node with the
Switch node provided. The insertSwitch method inserts the specified Switch
node at the specified index. The removeSwitch method removes the Switch node
at the specified index. The getSwitch method returns the Switch node specified
by the index. The numSwitches method returns a count of this LOD’s switches.

public Enumeration getAllSwitches()

This method returns the Enumeration object of all switches.

10.7.2 DistanceLOD Object

The DistanceLOD behavior node implements a distance-based LOD policy. It
operates on a Switch group node to select one of the children of that Switch node
based on the distance of this LOD node from the viewer. An array of n monoton-
ically increasing distance values is specified, such that distances[0] is associated
with the highest level of detail and distances[n–1] is associated with the lowest
level of detail. Based on the actual distance from the viewer to this DistanceLOD
node, these n distance values [0, n–1] select from among n+1 levels of detail
[0, n]. If d is the distance from the viewer to the LOD node, then the equation for
determining which level of detail (child of the Switch node) is selected is:
0, if d ≤ distances[0]
i, if distances[i–1] < d ≤ distances[i]
n, if d > distances[n–1]
Both the position of this node and the array of LOD distances are defined in the
local coordinate system of this node.

Constructors

public DistanceLOD()

This constructor creates a DistanceLOD object with a single distance value set to
0.0 and is, therefore, not very useful.
public DistanceLOD(float distances[])
public DistanceLOD(float distances[], Point3f position)

Construct and initialize a new DistanceLOD node. The distances parameter

specifies a vector of doubles representing LOD cutoff distances. The position
parameter specifies the position of this node in local coordinates. The default
position is (0,0,0).

Version 1.2, March 2000 311

10.8 Billboard Behavior BEHAVIORS AND INTERPOLATORS

Methods

public void setPosition(Point3f position)

public void getPosition(Point3f position)

These methods set and retrieve the position parameter for this DistanceLOD
node. This position is specified in the local coordinates of this node, and is the
position from which the distance to the viewer is computed.

public int numDistances()

public double getDistance(int whichDistance)
public void setDistance(int whichDistance, double distance)

The numDistances method returns a count of the number of LOD distance cutoff
parameters. The getDistance method returns a particular LOD cutoff distance.
The setDistance method sets a particular LOD cutoff distance.

public void initialize()

This method sets up the initial wakeup criteria.

public void processStimulus(Enumeration criteria)

This method computes the appropriate level of detail.

10.8 Billboard Behavior

The Billboard behavior node operates on the TransformGroup node to cause the
local +z axis of the TransformGroup to point at the viewer’s eye position. This is
done regardless of the transforms above the specified TransformGroup node in
the scene graph.
Billboard nodes provide the most benefit for complex, roughly symmetric
objects. A typical use might consist of a quadrilateral that contains a texture map
of a tree.
The Billboard node is similar in functionality to the OrientedShape3D node. See
also Section 6.2.1, “OrientedShape3D Node.”

Constants
The Billboard class adds the following new constants.

public static final int ROTATE_ABOUT_AXIS

Specifies that rotation should be about the specified axis.

312 The Java 3D API Specification
BEHAVIORS AND INTERPOLATORS Billboard Behavior 10.8

public static final int ROTATE_ABOUT_POINT

Specifies that rotation should be about the specified point and that the children’s
Y-axis should match the ViewPlatform’s Y-axis.

Constructors
The Billboard class specifies the following constructors.

public Billboard()

Constructs a Billboard node with default parameters:

Parameter Default Value
alignment mode ROTATE_ABOUT_AXIS
alignment axis Y-axis (0,1,0)
rotation point (0,0,1)
target transform group (tg) null

public Billboard(TransformGroup tg)

Constructs a Billboard node with default parameters that operates on the speci-
fied TransformGroup node. The default alignment mode is ROTATE_ABOUT_AXIS
rotation with the axis pointing along the Y axis.

public Billboard(TransformGroup tg, int mode, Vector3f axis)

public Billboard(TransformGroup tg, int mode, Point3f point)

The first constructor constructs a Billboard behavior node with default parame-
ters that operates on the specified target TransformGroup node. The default
alignment mode is ROTATE_ABOUT_AXIS, with the axis along the Y-axis. The next
two constructors construct a Billboard behavior node with the specified axis and
mode that operates on the specified TransformGroup node. The axis parameter
specifies the ray about which the billboard rotates. The point parameter specifies
the position about which the billboard rotates. The mode parameter is the align-
ment mode and is either ROTATE_ABOUT_AXIS or ROTATE_ABOUT_POINT.

Methods
The Billboard class defines the following methods.

Version 1.2, March 2000 313

10.8 Billboard Behavior BEHAVIORS AND INTERPOLATORS

public void setAlignmentMode(int mode)

public int getAlignmentMode()

These methods, if enabled by the appropriate flag, permit an application to either

retrieve or set the Billboard node’s alignment mode, one of ROTATE_ABOUT_AXIS
or ROTATE_ABOUT_POINT.

public void setAlignmentAxis(Vector3f axis)

public void setAlignmentAxis(float x, float y, float z)
public void getAlignmentAxis(Vector3f axis)

These methods, if enabled by the appropriate flag, permit an application to set or

retrieve the Billboard node’s alignment axis.

public void setTarget(TransformGroup tg)

public TransformGroup getTarget()

These methods set or retrieve the target TransformGroup node for this Billboard
object.

public void setRotationPoint(float x, float y, float z)

public void setRotationPoint(Point3f point)
public void getRotationPoint(Point3f point)

The first two methods set the rotation point. The third method gets the rotation
point and sets the parameter to this value.

public void initialize()

This method sets up the initial wakeup criteria.

public void processStimulus(Enumeration criteria)

This method computes the appropriate transform.

314 The Java 3D API Specification

 C H A P T E R 11
Input Devices and Picking

JAVA 3D provides access to keyboards and mice using the standard Java API
for keyboard and mouse support. Additionally, Java 3D provides access to a vari-
ety of continuous-input devices such as six-degrees-of-freedom (6DOF) trackers
and joysticks.
Continuous-input devices like 6DOF trackers and joysticks have well defined
continuous inputs. Trackers produce a position and orientation that Java 3D
stores internally as a transformation matrix. Joysticks produce two continuous
values in the range [–1.0, 1.0] that Java 3D stores internally as a transformation
matrix with an identity rotation (no rotation) and one of the joystick values as the
X translation and the other as the Y translation component.
Unfortunately, continuous-input devices do not have the same level of consis-
tency when it comes to their associated switches or buttons. Still, the number of
buttons or switches attached to a particular sensing element remains constant
across all sensing elements associated with a single device.

11.1 InputDevice Interface

The InputDevice interface specifies an abstract input device that a developer can
use in implementing a device driver for a particular device. All implementations
of an InputDevice interface must implement all of its methods. Java 3D’s input
device scheduler uses these methods to interact with specific devices and incor-
porate their input. In addition to the generic methods that all InputDevices must
provide, implementations of an InputDevice will contain whatever device-spe-
cific information and methods are necessary to maintain that device’s proper
functioning.
All input devices consist of a number of Sensor objects that have a direct one-to-
one relationship with that device’s physical detectors. Sensor objects serve dou-
Version 1.2, March 2000 315
11.1.1 The Abstract Interface INPUT DEVICES AND PICKING

ble duty. They not only represent actual physical detectors but they also serve as
abstract six-degrees-of-freedom transformations that a Java 3D application can
access. The Sensor class is described in more detail in Section 11.2.3, “The Sen-
sor Object.”

11.1.1 The Abstract Interface

All input devices implement a consistent interface that allows the initialization,
processing of input, and finalization of a particular input device. A device-driver
programmer would implement the following methods in whatever device-specific
manner is necessary to perform the specified operations.

Constants

public static final int BLOCKING

public static final int NON_BLOCKING
public static final int DEMAND_DRIVEN

These three flags control how Java 3D schedules reads. The BLOCKING flag signi-
fies that the driver for a device is a blocking driver and that it should be sched-
uled for regular reads by Java 3D. A blocking driver is a driver that can cause the
thread accessing the driver (the Java 3D implementation thread calling the pol-
lAndProcessInput method) to block while the data is being accessed from the
driver. The NON_BLOCKING flag signifies that the driver for a device is a non-
blocking driver and that it should be scheduled for regular reads by Java 3D. The
DEMAND_DRIVEN flag signifies that the Java 3D implementation should not sched-
ule regular reads on the sensors of this device; the Java 3D implementation will
only call pollAndProcessInput when one of the device’s sensors’ getRead
methods is called. A DEMAND_DRIVEN driver must always provide the current
value of the sensor on demand whenever pollAndProcessInput is called. This
means that DEMAND_DRIVEN drivers are non-blocking by definition.

Methods

public abstract boolean initialize()

This method initializes the device. It returns true if initialization succeeded,

false otherwise.

public abstract void setProcessingMode(int mode)

public abstract int getProcessingMode()

These methods set and retrieve this device’s processing mode, one of BLOCKING,
NON_BLOCKING, or DEMAND_DRIVEN.

316 The Java 3D API Specification

INPUT DEVICES AND PICKING Instantiating and Registering a New Device 11.1.2

public int getSensorCount()

This method returns the number of Sensor objects associated with this device.

public Sensor getSensor(int sensorIndex)

This method returns the specified Sensor associated with this device.

public abstract void setNominalPositionAndOrientation()

This method sets the device’s current position and orientation as the device’s
nominal position and orientation (that is, establishes its reference frame relative
to the “tracker base” reference frame). This method is most useful in defining a
nominal pose in immersive head-tracked situations.

public abstract void pollAndProcessInput()

This method first polls the device for data values and then processes the values
received from the device. For BLOCKING and NON_BLOCKING drivers, this method
is called regularly and the Java 3D implementation can cache the sensor values.
For DEMAND_DRIVEN drivers, this method is called each time one of the Sen-
sor.getRead methods is called, and is not otherwise called.

public abstract void processStreamInput()

This method will not be called by the Java 3D implementation and should be
implemented as an empty method.

public abstract void close()

This method cleans up the device and relinquishes the associated resources. This
method should be called after the device has been unregistered from Java 3D via
the PhysicalEnvironment.removeInputDevice(InputDevice) method.

11.1.2 Instantiating and Registering a New Device

A browser or applications developer must instantiate whatever system-specific
input devices that he or she needs and that exist on the system. This available-
device information typically exists in a site configuration file. The browser or
application will instantiate the viewing environment as requested by the end user.
The API for instantiating devices is site-specific, but it consists of a device object
with a constructor and at least all of the methods specified in the Input-Device
interface.

Version 1.2, March 2000 317

11.2 Sensors INPUT DEVICES AND PICKING

Once instantiated, the browser or application must register the device with the
Java 3D input device scheduler. The API for registering devices is specified in
Section 9.7, “The View Object.” The addInputDevice method introduces new
devices to the Java 3D environment and the allInputDevices method produces
an enumeration that allows examination of all available devices within a Java 3D
environment.

11.2 Sensors
The Java 3D API provides only an abstract concept of a device. Rather than
focusing on issues of devices and device models, it instead defines the concept of
a sensor. A sensor consists of a timestamped sequence of input values and the
state of the buttons or switches at the time that Java 3D sampled the value. A
sensor also contains a hotspot offset specified in that sensor’s local coordinate
system. If not specified, the hotspot is (0.0, 0.0, 0.0).
Since a typical hardware environment contains multiple sensing elements,
Java 3D maintains an array of sensors. Users can access a sensor directly from
their Java code or they can assign a sensor to one of Java 3D’s predefined 6DOF
entities such as UserHead.

11.2.1 Using and Assigning Sensors

Using a sensor is as easy as accessing an object. The application developer writes
Java code to extract the associated sensor value from the array of sensors. The
developer can then directly apply that value to an element in a scene graph or
process the sensor values in whatever way necessary.
Java 3D includes three special six-degrees-of-freedom (6DOF) entities. These
include UserHead, DominantHand, and NondominantHand. An application
developer can assign or change which sensor drives one of these predefined enti-
ties. Java 3D uses the specified sensor to drive the 6DOF entity—most visibly
the View. Application developers should use this facility carefully. It is quite easy
to get the effect of a WristCam—and very disconcerting as well.

11.2.2 Behind the (Sensor) Scenes

Java 3D does not provide raw tracker or joystick-generated data in a sensor. At a
minimum, Java 3D normalizes the raw data using the registration and calibration
parameters either provided by or provided for the end user. It additionally may
filter and process the data to remove noise and improve latency. The application
programmer can suppress this latter effect on a sensor-by-sensor basis.

318 The Java 3D API Specification

INPUT DEVICES AND PICKING The Sensor Object 11.2.3

Unfortunately, tracker or sensor hardware may not always be available or be

operational. Thus, Java 3D provides both an available and an enable flag on a
per-sensor basis.

11.2.3 The Sensor Object

Java 3D stores its sensor array in the PhysicalEnvironment object. Each Sensor
in the array consists of a fixed number of SensorRead objects. Also associated
with each SensorRead is its timestamp and the state of that sensor’s buttons.

Constants
The Sensor object specifies the following constants.

public static final int PREDICT_NONE

public static final int PREDICT_NEXT_FRAME_TIME

These flags define the Sensor’s predictor type. The first flag defines no predic-
tion. The second flag specifies to generate the value to correspond with the next
frame time.

public static final int NO_PREDICTOR

public static final int HEAD_PREDICTOR
public static final int HAND_PREDICTOR

These flags define the Sensor’s predictor policy. The first flag specifies to use no
prediction policy. The second flag specifies to assume that the sensor is predict-
ing head position or orientation. The third flag specifies to assume that the sensor
is predicting hand position or orientation.

public static final int DEFAULT_SENSOR_READ_COUNT

This constant specifies the default number of SensorRead objects constructed

when no SensorRead count is specified.

Constructors
The Sensor object specifies the following constructors.

public Sensor(InputDevice device)

Constructs a Sensor object for the specified input device using default parame-
ters:

Version 1.2, March 2000 319

11.2.3 The Sensor Object INPUT DEVICES AND PICKING

Parameter Default Value

sensorReadCount 0
sensorButtonCount 0
hotspot (0,0,0)
predictor PREDICT_NONE
prediction policy NO_PREDICTOR

public Sensor(InputDevice device, int sensorReadCount)

public Sensor(InputDevice device, int sensorReadCount,
int sensorButtonCount)

These methods construct a new Sensor object associated with the specified
device and consisting of either a default number of SensorReads or sensorRead-
Count number of SensorReads and a hot spot at (0.0, 0.0, 0.0) specified in the
sensor’s local coordinate system. The default for sensorButtonCount is zero.

public Sensor(InputDevice device, Point3d hotspot)

public Sensor(InputDevice device, int sensorReadCount,
Point3d hotspot)
public Sensor(InputDevice device, int sensorReadCount,
int sensorButtonCount, Point3d hotspot)

These methods construct a new Sensor object associated with the specified
device and consisting of either sensorReadCount number of SensorReads or a
default number of SensorReads and an offset defining the sensor’s hot spot in the
sensor’s local coordinate system. The default for sensorButtonCount is zero.

Methods

public void setSensorReadCount(int count)

public int getSensorReadCount()
public int getSensorButtonCount()

These methods set and retrieve the number of SensorRead objects associated
with this sensor and the number of buttons associated with this sensor. Both the
number of SensorRead objects and the number of buttons are determined at Sen-
sor construction time.

public void getHotspot(Point3d hotspot)

public void setHotspot(Point3d hotspot)

These methods set and retrieve the sensor’s hotspot offset. The hotspot is speci-
fied in the sensor’s local coordinate system.

320 The Java 3D API Specification

INPUT DEVICES AND PICKING The Sensor Object 11.2.3

public void lastRead(Transform3D read)

public void lastRead(Transform3D read, int kth)

These methods extract the most recent sensor reading and the kth most recent
sensor reading from the Sensor object. In both cases, the methods copy the sen-
sor value into the specified argument.

public void getRead(Transform3D read)

public void getRead(Transform3D read, long deltaT)

The first method computes the sensor reading consistent with the prediction pol-
icy and copies that value into the read matrix. The second method computes the
sensor reading consistent as of time deltaT in the future and copies that value
into the read matrix. All times are in milliseconds.

public long lastTime()

public long lastTime(int k)

These methods return the time associated with the most recent sensor reading
and with the kth most recent sensor reading, respectively.
public int lastButtons(int values[])
public void lastButtons(int k, int values[])

The first method places the most recent sensor reading value for each button into
the array parameter. The second method places the kth most recent sensor read-
ing value for each button into the array parameter, where 0 is the most-recent
sensor reading, 1 is the next most recent sensor reading, and so on. These meth-
ods will throw an ArrayIndexOutOfBoundsException if values.length is less
than the number of buttons.

public void setPredictor(int predictor)

public int getPredictor()

These methods set and retrieve the sensor’s predictor policy. The predictor policy
is either PREDICT_NONE or PREDICT_NEXT_FRAME_TIME.

public void setPredictionPolicy(int policy)

public int getPredictionPolicy()

These methods set and retrieve the sensor’s predictor type. The predictor type is
one of the following: NO_PREDICTOR, HEAD_PREDICTOR, or HAND_PREDICTOR.

public void setDevice(InputDevice device)

public InputDevice getDevice()

These methods set and retrieve the sensor’s input device.

Version 1.2, March 2000 321

11.2.4 The SensorRead Object INPUT DEVICES AND PICKING

public SensorRead getCurrentSensorRead()

This method returns the current number of SensorRead objects per sensor.

public void setNextSensorRead(long time, Transform3D transform,

int[] values)
public void setNextSensorRead(SensorRead read)

The first method sets the next sensor read to the specified values; once these val-
ues are set via this method they become the current values returned by methods
such as lastRead(), lastTime() and lastButtons(); note that if there are no buttons
associated with this sensor then values can just be an empty array. The second
method sets the next SensorRead object to the specified values, including the
next SensorRead’s associated time, transformation, and button state array.

11.2.4 The SensorRead Object

A SensorRead object encapsulates all the information associated with a single
reading of a sensor, including a timestamp, a transform, and, optionally, button
values.

Constants

public static final int MAXIMUM_SENSOR_BUTTON_COUNT

This flag determines the maximum number of sensor-attached buttons tracked on

a per-sensor basis.

Constructors
The SensorRead object specifies the following constructor.
public SensorRead()

Constructs a SensorRead object with default parameters:

Parameter Default Value
numButtons 0
button values 0 (for all array elements)
transform identity
time current time

public SensorRead(int numButtons)

Constructs a SensorRead object with the specified number of buttons.

322 The Java 3D API Specification

INPUT DEVICES AND PICKING Picking 11.3

Methods

public void set(Transform3D t1)

public void get(Transform3D result)

These methods set and retrieve the SensorRead object’s transform. They allow a
device to store a new rotation and orientation value into the SensorRead object,
and a consumer of that value to access it.

public void setTime(long time)

public long getTime()

These methods set and retrieve the SensorRead object’s timestamp. They allow a
device to store a new timestamp value into the SensorRead object, and a con-
sumer of that value to access it.

public void setButtons(int values[])

public void getButtons(int values[])

These methods set and retrieve the SensorRead object’s button values. They
allow a device to store an integer that encodes the button values into the Sensor-
Read object, and a consumer of those values to access the state of the buttons.

public int getNumButtons() New in 1.2

This method returns the number of buttons associated with this SensorRead
object.

11.3 Picking
Behavior nodes provide the means for building developer-specific picking
semantics. An application developer can define custom picking semantics using
Java 3D’s behavior mechanism (see Chapter 10, “Behaviors and Interpolators”).
The developer might wish to define pick semantics that use a mouse to shoot a
ray into the virtual universe from the current viewpoint, find the first object along
that ray, and highlight that object when the end user releases the mouse button. A
typical scenario follows:
1. The application constructs a Behavior node that arms itself to awaken
when AWT detects a left-mouse-button-down event.
2. Upon awakening from a left-mouse-button-down event, the behavior
a. Updates a Switch node to draw a ray that emanates from the center of
the screen.

Version 1.2, March 2000 323

11.3.1 SceneGraphPath Object INPUT DEVICES AND PICKING

b. Changes that ray’s TransformGroup node so that the ray points in the
direction of the current mouse position.
c. Declares its interest in mouse-move or left-mouse-button-up events.
3. Upon awakening from a mouse-move event, the behavior
a. Changes that ray’s TransformGroup node so that the ray points in the
direction of the current mouse position.
b. Declares its interest in mouse-move or left-mouse-button-up events.
4. Upon awakening from a left-mouse-button-up event, the behavior
a. Changes that ray’s TransformGroup node so that the ray points in the
direction of the current mouse position.
b. Intersects the ray with all the objects in the virtual universe to find the
first object that the ray intersects.
c. Changes the appearance component of that object’s shape node to
highlight the selected object.
d. Declares its interest in left-mouse-button-down events.
Java 3D includes helping functions that aid in intersecting various geometric
objects with objects in the virtual universe by
• Intersecting an oriented ray with all the objects in the virtual universe. That
function can return the first object intersected along that ray, all the objects
that intersect that ray, or a list of all the objects along that ray sorted by dis-
tance from the ray’s origin.
• Intersecting a volume with all the objects in the virtual universe. That func-
tion returns a list of all the objects contained in that volume.
• Discovering which vertex within an object is closest to a specified ray.

Note: Picking and scene graph update are not synchronized. In Java 3D version
1.2, the elapsed time between a scene graph update and a pick (that uses the
updated scene graph) is about three frames.

11.3.1 SceneGraphPath Object

A SceneGraphPath object represents the path from a Locale to a terminal node in
the scene graph. This path consists of a Locale, a terminal node, and an array of
internal nodes that are in the path from the Locale to the terminal node. The ter-
minal node may be either a Leaf node or a Group node. A valid SceneGraphPath

324 The Java 3D API Specification

INPUT DEVICES AND PICKING SceneGraphPath Object 11.3.1

must uniquely identify a specific instance of the terminal node. For nodes that
are not under a SharedGroup, the minimal SceneGraphPath consists of the
Locale and the terminal node itself. For nodes that are under a SharedGroup, the
minimal SceneGraphPath consists of the Locale, the terminal node, and a list of
all Link nodes in the path from the Locale to the terminal node. A SceneGraph-
Path may optionally contain other interior nodes that are in the path. A
SceneGraphPath is verified for correctness and uniqueness when it is sent as an
argument to other methods of Java 3D.
In the array of internal nodes, the node at index 0 is the node closest to the
Locale. The indices increase along the path to the terminal node, with the node at
index length-1 being the node closest to the terminal node. The array of nodes
does not contain either the Locale (which is not a node) or the terminal node.
During picking and intersection tests, the user specifies the subtree of the scene
graph that should be tested. The whole tree for a Locale is searched by providing
the Locale to the picking or intersection tests.
The SceneGraphPath object returned by the picking methods represents all the
components in the subgraph that have the capability ENABLE_PICK_REPORTING
set between the root of the subtree and the picked or intersected object. All Link
nodes are implicitly enabled for pick reporting. Note that ENABLE_PICK_REPORT-
ING and ENABLE_COLLISION_REPORTING are disabled by default. This means that
the picking and collision methods will return the minimal SceneGraphPath by
default.
When a SceneGraphPath is returned from the picking or collision methods of
Java 3D, it will also contain the value of the LocalToVworld transform of the ter-
minal node that was in effect at the time the pick or collision occurred.

Constructors

public SceneGraphPath()

Constructs and initializes a new SceneGraphPath object with default values:

Parameter Default Value
root null
object null
list of (interior) nodes null
transform identity

Version 1.2, March 2000 325

11.3.1 SceneGraphPath Object INPUT DEVICES AND PICKING

public SceneGraphPath(Locale root, Node object)

public SceneGraphPath(Locale root, Node nodes[], Node object)

These construct and initialize a new SceneGraphPath object. The first form spec-
ifies the path’s Locale object and the object in question. The second form
includes an array of nodes that fall in between the Locale and the object in ques-
tion, and which nodes have their ENABLE_PICK_REPORTING capability bit set. The
object parameter may be a Group, Shape3D, or Morph node. If any other type of
leaf node is specified, an IllegalArgumentException is thrown.

Methods

public final void set(SceneGraphPath newPath)

public final void setLocale(Locale newLocale)
public final void setObject(Node object)
public final void setNode(int index, Node newNode)
public final void setNodes(Node nodes[])

These methods set the path’s values. The first method sets the path’s interior val-
ues. The second method sets the path’s Locale to the specified Locale. The third
method sets the path’s object to the specified object (a Group node, or a Shape3D
or Morph leaf node). The fourth method replaces the link node associated with
the specified index with the specified newLink. The last method replaces all of
the link nodes with the new list of link nodes.

public final Locale getLocale()

public final Node getObject()

The first method returns the path’s Locale. The second method returns the path’s
object.

public final int nodeCount()

public final Node getNode(int index)

The first method returns the number of intermediate nodes in this path. The sec-
ond method returns the node associated with the specified index.

public final void setTransform(Transform3D trans)

public final Transform3D getTransform()

The set method sets the transform component of this SceneGraphPath to the
value of the passed transform. The get method returns a copy of the transform
associated with this SceneGraphPath. The method returns null if there is no
transform associated. If this SceneGraphPath was returned by a Java 3D picking

326 The Java 3D API Specification

INPUT DEVICES AND PICKING BranchGroup Node and Locale Node Pick Methods 11.3.2

and collision method, the local-coordinate-to-virtual-coordinate transform for

this scene graph object at the time of the pick or collision is recorded.

public final boolean isSamePath(SceneGraphPath testPath)

This method determines whether two SceneGraphPath objects represent the same
path in the scene graph. Either object might include a different subset of internal
nodes; only the internal link nodes, the Locale, and the Node itself are compared.
The paths are not validated for correctness or uniqueness.
public boolean equals(SceneGraphPath testPath)
public boolean equals(Object o1)

The first method returns true if all of the data members of path testPath are
equal to the corresponding data members in this SceneGraphPath. The second
method returns true if the Object o1 is of type SceneGraphPath and all of the
data members of o1 are equal to the corresponding data members in this
SceneGraphPath and if the values of the transforms are equal.

public int hashCode()

This method returns a hash number based on the data values in this object. Two
different SceneGraphPath objects with identical data values (that is, trans.-
equals(SceneGraphPath) returns true) will return the same hash number. Two
paths with different data members may return the same hash value, although this
is not likely.

public String toString()

This method returns a string representation of this object. The string contains the
class names of all nodes in the SceneGraphPath.

11.3.2 BranchGroup Node and Locale Node Pick Methods

The following methods are in both the BranchGroup node class and the Locale
node class.

public SceneGraphPath[] pickAll(PickShape pickShape)

public SceneGraphPath[] pickAllSorted(PickShape pickShape)
public SceneGraphPath pickClosest(PickShape pickShape)
public SceneGraphPath pickAny(PickShape pickShape)

These methods return either an array of SceneGraphPath objects or a single

SceneGraphPath object. A SceneGraphPath object describes the entire path from
a Locale to a node that intersects the specified PickShape (see Section 11.3.3,

Version 1.2, March 2000 327

11.3.3 PickShape Object INPUT DEVICES AND PICKING

“PickShape Object”). The methods that return an array either return all the
picked objects or all the picked objects in sorted order starting with the objects
“closest” to the eyepoint and ending with the objects farthest from the eyepoint.
Methods that return a single SceneGraphPath return a single path object that
specifies either the object closest to the eyepoint or any picked object (this latter
method also implements the fastest pick operation possible). All ties in testing
for closest objects intersected result in an indeterminate order.

11.3.3 PickShape Object

The PickShape object is an abstract class for describing a shape that can be used
with the BranchGroup and Locale pick methods. The PickShape object is
extended by PickBounds, PickCone, PickCylinder, PickPoint, PickRay, and Pick-
Segment objects. The PickCylinder object is further extended by the PickCylin-
der and PickCylinderSegment objects. The PickCone object is further extended
by the PickConeRay and PickConeSegment objects.

Constructors

public PickShape()

Constructs a PickShape object.

11.3.4 PickBounds Object

The PickBounds object provides a bounds to supply to the BranchGroup and
Locale pick methods. See also Section 11.3.2, “BranchGroup Node and Locale
Node Pick Methods.”

Constructors

public PickBounds()
public PickBounds(Bounds boundsObject)

The first constructor creates a PickBounds initialized with the bounds set to null.
The second constructor creates a PickBounds with the bounds set to boundsOb-
ject.

Methods

public void set(Bounds boundsObject)

public Bounds get()

These methods set and retrieve the boundsObject of this PickBounds.

328 The Java 3D API Specification

INPUT DEVICES AND PICKING PickRay Object 11.3.6

11.3.5 PickPoint Object

The PickPoint object provides a point to supply to the BranchGroup and Locale
pick methods. See also Section 11.3.2, “BranchGroup Node and Locale Node
Pick Methods.”

Constructors

public PickPoint()
public PickPoint(Point3d location)

The first constructor creates a PickPoint initialized to (0,0,0). The second con-
structor creates a PickPoint at the specified location.

Methods

public void set(Point3d location)

public void get(Point3d location)

These methods set and retrieve the position of this PickPoint.

11.3.6 PickRay Object

The PickRay object is an encapsulation of a ray that is passed to the pick meth-
ods in BranchGroup and Locale. See also Section 11.3.2, “BranchGroup Node
and Locale Node Pick Methods.”

Constructors

public PickRay()
public PickRay(Point3d origin, Vector3d direction)

The first constructor creates a PickRay initialized with an origin and direction of
(0,0,0). The second constructor creates a PickRay from the specified origin and
direction.

Methods

public void set(Point3d origin, Vector3d direction)

public void get(Point3d origin, Vector3d direction)

These methods set and retrieve the origin and direction of this PickRay
object.

Version 1.2, March 2000 329

11.3.7 PickSegment Object INPUT DEVICES AND PICKING

11.3.7 PickSegment Object

The PickSegment object is an encapsulation of a segment that is passed to the
pick methods in BranchGroup and Locale. See also Section 11.3.2, “Branch-
Group Node and Locale Node Pick Methods.”

Constructors

public PickSegment()
public PickSegment(Point3d start, Point3d end)

The first constructor creates a PickSegment object with the start and end of the
segment initialized to (0,0,0). The second constructor creates a PickSegment
object from the specified start and end points.

Methods

public void set(Point3d start, Point3d end)

public void get(Point3d start, Point3d end)

These methods set and retrieve the start and end points of this PickSegment
object.

11.3.8 PickCone Object

The PickCone object is the abstract base class for all cone pick shapes. PickCone
is extended by the PickConeRay and PickConeSegment classes.

Constructors

public PickCone() New in 1.2

Constructs an empty PickCone. The origin and direction of the cone are initial-
ized to (0,0,0). The spread angle is initialized to π/64.

Methods

public void getOrigin(Point3d origin) New in 1.2

public void getDirection(Vector3d direction) New in 1.2
public double getSpreadAngle() New in 1.2

These three methods return the origin, direction, and spread angle of this Pick-
Cone, respectively.

330 The Java 3D API Specification

INPUT DEVICES AND PICKING PickConeSegment Object 11.3.10

11.3.9 PickConeRay Object New in 1.2

The PickConeRay object is an infinite cone pick ray shape. It can be used as an
argument to the picking methods in BranchGroup and Locale.

Constructors

public PickConeRay() New in 1.2

public PickConeRay(Point3d origin, Vector3d direction,
double spreadAngle) New in 1.2

The first constructor creates an empty PickConeRay. The origin and direction of
the cone are initialized to (0,0,0). The spread angle is initialized to π/64 radian.
The second constructor creates an infinite cone pick shape from the specified
parameters.

Methods

public void set(Point3d origin, Vector3d direction,

double spreadAngle) New in 1.2

This method sets the parameters of this PickCone to the specified values.

11.3.10PickConeSegment Object New in 1.2

The PickConeSegment object is a finite cone segment pick shape. It can be used
as an argument to the picking methods in BranchGroup and Locale.

Constructors

public PickConeSegment() New in 1.2

public PickConeSegment(Point3d origin, Point3d end,
double spreadAngle) New in 1.2

The first constructor creates an empty PickConeSegment. The origin and end
point of the cone are initialized to (0,0,0). The spread angle is initialized to π/64
radians. The second constructor creates a finite cone pick shape from the speci-
fied parameters.

Methods

public void set(Point3d origin, Point3d end, double spreadAngle) New in 1.2

This method sets the parameters of this PickCone to the specified values.

Version 1.2, March 2000 331

11.3.11 PickCylinder Object INPUT DEVICES AND PICKING

public void getEnd(Point3d end) New in 1.2

This method gets the end point of this PickConeSegment.

11.3.11PickCylinder Object New in 1.2

The PickCylinder object is the abstract base class of all cylindrical pick shapes.

Constructors

public PickCylinder() New in 1.2

This constructor creates an empty PickCylinder. The origin of the cylinder is ini-
tialized to (0,0,0). The radius is initialized to 0.

Methods

public void getOrigin(Point3d origin) New in 1.2

public double getRadius() New in 1.2
public void getDirection(Vector3d direction) New in 1.2

These three methods return the origin, radius, and direction of this PickCylinder
object.

11.3.12PickCylinderRay Object
The PickCylinderRay object is an infinite cylindrical ray pick shape. It can be
used as an argument to the picking methods in BranchGroup and Locale.

Constructors

public PickCylinderRay() New in 1.2

public PickCylinderRay(Point3d origin, Vector3d direction,
double radius) New in 1.2

The first constructor creates an empty PickCylinderRay. The origin and direction
of the cylindrical ray are initialized to (0,0,0). The radius is initialized to 0. The
second constructor creates an infinite cylindrical ray pick shape from the speci-
fied parameters.

Methods

public void set(Point3d origin, Vector3d direction, double radius) New in 1.2

This method sets the parameters of this PickCylinderRay to the specified values.

332 The Java 3D API Specification

INPUT DEVICES AND PICKING PickCylinderSegment Object 11.3.13

11.3.13PickCylinderSegment Object
The PickCylinderSegment object is a finite cylindrical segment pick shape. It can
be used as an argument to the picking methods in BranchGroup and Locale.

Constructors

public PickCylinderSegment() New in 1.2

public PickCylinderSegment(Point3d start, Point3d end,
double radius) New in 1.2

The first constructor creates an empty PickCylinderSegment. The start and end
points of the cylindrical segment are initialized to (0,0,0). The radius is initial-
ized to 0.

Methods

public void set(Point3d start, Point3d end, double radius) New in 1.2

This method sets the parameters of this PickCylinderSegment to the specified

values.

public void getEnd(Point3d end) New in 1.2

This method returns the end point of this PickCylinderSegment.

Version 1.2, March 2000 333

 C H A P T E R 12
Audio Devices

A Java 3D application running on a particular machine could have one of sev-

eral options available to it for playing the audio image created by the sound ren-
derer. Perhaps the machine on which Java 3D is executing has more than one
sound card (for example, one that is a wave table synthesis card and the other
with accelerated sound spatialization hardware). Furthermore, suppose there are
Java 3D audio device drivers that execute Java 3D audio methods on each of
these specific cards. The application would therefore have at least two audio
device drivers through which the audio could be produced. For such a case the
Java 3D application must choose the audio device driver with which sound ren-
dering is to be performed. Once this audio device is chosen, the application can
additionally select the type of audio playback on which device the rendered
sound image is to be output. The playback device (headphones or speaker(s)) is
physically connected to the port to which the selected device driver outputs.

12.1 AudioDevice Interface

The selection of this device driver is done through methods in the PhysicalEnvi-
ronment object (see Section C.9, “The PhysicalEnvironment Object”). The appli-
cation queries how many audio devices are available. For each device, the user
can get the AudioDevice object that describes it and query its characteristics.
Once a decision is made about which of the available audio devices to use for a
PhysicalEnvironment, the particular device is set into this PhysicalEnvironment’s
fields. Each PhysicalEnvironment object may use only a single audio device.
The AudioDevice object interface specifies an abstract audio device that creators
of Java 3D class libraries would implement for a particular device. Java 3D uses
several methods to interact with specific devices. Since all audio devices imple-
ment this consistent interface, the user could have a portable means of initializ-

Version 1.2, March 2000 335

12.1.1 Initialization AUDIO DEVICES

ing, setting particular audio device elements, and querying generic character-
istics for any audio device.

Constants

public static final int HEADPHONES

Specifies that audio playback will be through stereo headphones.

public static final int MONO_SPEAKER

Specifies that audio playback will be through a single speaker some distance
away from the listener.

public static final int STEREO_SPEAKERS

Specifies that audio playback will be through stereo speakers some distance
away from, and at some angle to, the listener.

12.1.1 Initialization
Each audio device driver must be initialized. The chosen device driver should be
initialized before any Java 3D Sound methods are executed because the imple-
mentation of the Sound methods, in general, is potentially device-driver depen-
dent.

Methods

public abstract boolean initialize()

Initialize the audio device. Exactly what occurs during initialization is imple-
mentation dependent. This method provides explicit control by the user over
when this initialization occurs.
public abstract boolean close()

Closes the audio device, releasing resources associated with this device.

12.1.2 Audio Playback

Methods to set and retrieve the audio playback parameters are part of the
AudioDevice object. The audio playback information specifies that playback will
be through one of the following:
• Stereo headphones.

336 The Java 3D API Specification

AUDIO DEVICES Audio Playback 12.1.2

• A monaural speaker.
• A pair of speakers, equally distant from the listener, both at some angle
from the head coordinate system Z axis. It’s assumed that the speakers are
at the same elevation and oriented symmetrically about the listener.
The type of playback chosen affects the sound image generated. Cross-talk can-
cellation is applied to the audio image if playback over stereo speakers is
selected.

Methods
The following methods affect the playback of sound processed by the Java 3D
sound renderer.

public abstract void setAudioPlaybackType(int type)

public abstract int getAudioPlaybackType()

These methods set and retrieve the type of audio playback device (HEADPHONES,
MONO_SPEAKER, or STEREO_SPEAKERS) used to output the analog audio from ren-
dering Java 3D Sound nodes.

public abstract void setCenterEarToSpeaker(float distance)

public abstract float getCenterEarToSpeaker()

These methods set and retrieve the distance in meters from the center ear (the
midpoint between the left and right ears) and one of the speakers in the listener’s
environment. For monaural speaker playback, a typical distance from the listener
to the speaker in a workstation cabinet is 0.76 meters. For stereo speakers placed
at the sides of the display, this might be 0.82 meters.

public abstract void setAngleOffsetToSpeaker(float angle)

public abstract float getAngleOffsetToSpeaker()

These methods set and retrieve the angle, in radians, between the vectors from
the center ear to each of the speaker transducers and the vectors from the center
ear parallel to the head coordinate’s Z axis. Speakers placed at the sides of the
computer display typically range between 0.175 and 0.350 radians (between 10
and 20 degrees).

public abstract PhysicalEnvironment getPhysicalEnvironment()

This method returns a reference to the AudioDevice’s PhysicalEnvironment

object.

Version 1.2, March 2000 337

12.1.3 Device-Driver-Specific Data AUDIO DEVICES

12.1.3 Device-Driver-Specific Data

While the sound image created for final output to the playback system is either
only monaural or stereo (for this version of Java 3D), most device-driver imple-
mentations will mix the left and right image signals generated for each rendered
sound source before outputting the final playback image. Each sound source will
use N input channels of this internal mixer.
Each implemented Java 3D audio device driver will have its own limitations and
driver-specific characteristics. These include channel availability and usage (dur-
ing rendering). Methods for querying these device-driver-specific characteristics
are provided below.

Methods

public abstract int getTotalChannels()

This method retrieves the maximum number of channels available for Java 3D
sound rendering for all sound sources.

public abstract int getChannelsAvailable()

During rendering, when Sound nodes are playing, this method returns the num-
ber of channels still available to Java 3D for rendering additional Sound nodes.

public abstract int getChannelsUsedForSound(Sound node)

This method queries the number of channels that are used, or would be used to
render a particular sound node. This method returns the number of channels
needed to render a particular Sound node. The return value is the same no matter
if the Sound is currently active and enabled (being played) or is inactive.

12.2 AudioDevice3D Interface

The AudioDevice3D Class extends the AudioDevice interface. The intent is for
this interface to be implemented by AudioDevice driver developers (whether a
Java 3D licensee or not). Each implementation will use a sound engine of their
choice.
The methods in this interface should not be called an application. The methods in
this interface are referenced by the core Java 3D Sound classes to render live,
scheduled sound on the AudioDevice chosen by the application or use chosen by
the application or user.

338 The Java 3D API Specification

AUDIO DEVICES AudioDevice3D Interface 12.2

Methods in this interface provide the Java 3D core a generic way to set and
query the audio device the application has chosen audio rendering to be per-
formed on. Methods in this interface include:
• Setup and clearing the sound as a sample on the device
• Start, stop, pause, unpause, mute, and unmute of sample on the device
• Set parameters for each sample corresponding to the fields in the Sound
node
• Set the current active aural parameters that affect all positional samples

Constants

public static final int BACKGROUND_SOUND

public static final int POINT_SOUND
public static final int CONE_SOUND

These constants specify the sound types. Sound types match the Sound node
classes defined for Java 3D core for BackgroundSound, PointSound, and Cone-
Sound. The type of sound a sample is loaded as determines which methods affect
it.

public static final int STREAMING_AUDIO_DATA

public static final int BUFFERED_AUDIO_DATA

These constants specify the sound data types. Samples can be processed as
streaming or buffered data. Fully spatializing sound sources may require data to
be buffered.
Sound data specified as streaming is not copied by the AudioDevice diver imple-
mentation. It is up the application to ensure that this data is continuously acces-
sible during sound rendering. Futhermore, full sound spatialization may not be
possible, for all AudioDevice3D implementations on unbuffered sound data.
Sound data specified as buffered is copied by the AudioDevice driver implemen-
tation.

Methods

public abstract void setView(View reference)

This method accepts a reference to the current View and passes reference to the
current View Object. The PhysicalEnvironment parameters (with playback type
and speaker placement) and the PhysicalBody parameters (position and orienta-
tion of ears) can be obtained from this object, and the transformations to and

Version 1.2, March 2000 339

12.2 AudioDevice3D Interface AUDIO DEVICES

from ViewPlatform coordinate (the space the listener’s head is in) and Virtual
World coordinates (the space the sounds are in).

public abstract int prepareSound(int soundType,

MediaContainer soundData)

Prepare the sound. This method accepts a reference to the MediaContainer that
contains a reference to sound data and information about the type of data it is.
The soundType parameter defines the type of sound associated with this sample
(Background, Point, or Cone).
Depending on the type of MediaContainer the sound data is and on the imple-
mentation of the AudioDevice used, sound data preparation could consist of
opening, attaching, or loading sound data into the device. Unless the cached is
true, this sound data should not be copied, if possible, into host or device mem-
ory.
Once this preparation is complete for the sound sample, an AudioDevice-specific
index, used to reference the sample in future method calls, is returned. All the
rest of the methods described below require this index as a parameter.

public abstract void clearSound(int index)

Clear the sound. This method requests that the AudioDevice free all resources
associated with the sample with index id.

public abstract long getSampleDuration(int index)

Query Sample duration. If it can be determined, this method returns the duration
in milliseconds of the sound sample. For non-cached streams, this method
returns Sound.DURATION_UNKNOWN.

public abstract int getNumberOfChannelsUsed(int index)

public abstract int getNumberOfChannelsUsed(int index,
boolean muted)

Query the number of channels used by Sound. These methods return the number
of channels (on the executing audio device) that this sound is using, if it is play-
ing, or is expected to use if it were begun to be played. The first method takes the
sound’s current state (including whether it is muted or unmuted) into account.
The second method uses the muted parameter to make the determination.
For some AudioDevice3D implementations:
• Muted sounds take up channels on the systems mixer (because they’re ren-
dered as samples playing with gain zero).

340 The Java 3D API Specification

AUDIO DEVICES AudioDevice3D Interface 12.2

• A single sound could be rendered using multiple samples, each taking up

mixer channels.

public abstract int startSample(int index)

Start sample. This method begins a sound playing on the AudioDevice and
returns a flag indicating whether or not the sample was started.

public abstract int stopSample(int index)

Stop sample. This method stops the sound on the AudioDevice and returns a flag
indicating whether or not the sample was stopped.

public abstract long getStartTime(int index)

Query last start time for this sound on the device. This method returns the system
time of when the sound was last “started.” Note that this start time will be as
accurate as the AudioDevice implementation can make it, but that it is not guar-
anteed to be exact.

public abstract void setSampleGain(int index, float scaleFactor)

Set gain scale factor. This method sets the overall gain scale factor applied to
data associated with this source to increase or decrease its overall amplitude. The
gain scaleFactor value passed into this method is the combined value of the
Sound node’s initial gain and the current AuralAttribute gain scale factors.

public abstract void setDistanceGain(int index,

double[] frontDistance, float[] frontAttenuationScaleFactor,
double[] backDistance, float[] backAttenuationScaleFactor)

Set distance gain. This method sets this sound’s distance gain elliptical attenua-
tion (not including the filter cutoff frequency) by defining corresponding arrays
containing distances from the sound’s origin and gain scale factors applied to all
active positional sounds. The gain scale factor is applied to sound based on the
distance the listener is from the sound source. These attenuation parameters are
ignored for BackgroundSound nodes. The backAttenuationScaleFactor
parameter is ignored for PointSound nodes.
For a full description of the attenuation parameters, see Section 6.9.3, “Cone-
Sound Node.”

public abstract void setDistanceFilter(int filterType,

double[] distance, float[] filterCutoff)

Set AuralAttributes distance filter. This method sets the distance filter corre-
sponding arrays containing distances and frequency cutoff applied to all active
Version 1.2, March 2000 341
12.2 AudioDevice3D Interface AUDIO DEVICES

positional sounds. The gain scale factor is applied to sound based on the distance
the listener is from the sound source. For a full description of this parameter and
how it is used, see Section 8.1.17, “AuralAttributes Object.”

public abstract void setLoop(int index, int count)

Set loop count. This method sets the number of times sound is looped during
play. For a complete description of this method, see the description for the
Sound.setLoop method in Section 6.9, “Sound Node.”

public abstract void muteSample(int index)

public abstract void unmuteSample(int index)

These methods mute and unmute a playing sound sample. The first method
makes a sample play silently. The second method makes a silently-playing sam-
ple audible. Ideally, the muting of a sample is implemented by stopping a sample
and freeing channel resources (rather than just setting the gain of the sample to
zero). Ideally, the un-muting of a sample restarts the muted sample by offset
from the beginning by the number of milliseconds since the time the sample
began playing.

public abstract void pauseSample(int index)

public abstract void unpauseSample(int index)

These methods pause and unpause a playing sound sample. The first method
temporarily stops a cached sample from playing without resetting the sample’s
current pointer back to the beginning of the sound data so that it can be un-
paused at a later time from the same location in the sample when the pause was
initiated. The second method restarts the paused sample from the location in the
sample where it was paused.

public abstract void setPosition(int index, Point3d position)

Set position. This method sets this sound’s location (in Local coordinates) from
provided the position.

public abstract void setDirection(int index, Vector3d direction)

Set direction. This method sets this sound’s direction from the local coordinate
vector provided. For a full description of the direction parameter, see
Section 6.9.3, “ConeSound Node.”

public abstract void setVworldXfrm(int index, Transform3D trans)

Set virtual world transform. This method passes a reference to the concatenated
transformation to be applied to local sound position and direction parameters.
342 The Java 3D API Specification
AUDIO DEVICES AudioDevice3D Interface 12.2

public abstract void setRolloff(float rolloff)

Set AuralAttributes gain rolloff. This method sets the speed-of-sound factor. For
a full description of this parameter and how it is used, see Section 8.1.17,
“AuralAttributes Object.”

public abstract void setAngularAttenuation(int index,

int filterType, double[] angle,
float[] attenuationScaleFactor, float[] filterCutoff)

Set angular attenuation. This method sets this sound’s angular gain attenuation
(including filter) by defining corresponding arrays containing angular offsets
from the sound’s axis, gain scale factors, and frequency cutoff applied to all
active directional sounds. Gain scale factor is applied to sound based on the
angle between the sound’s axis and the ray from the sound source origin to the
listener. The form of the attenuation parameter is fully described in Section 6.9.3,
“ConeSound Node.”

public abstract void setReflectionCoefficient(float coefficient)

Set AuralAttributes reverberation coefficient. This method sets the reflective or

absorptive characteristics of the surfaces in the region defined by the current
Soundscape region. For a full description of this parameter and how it is used,
see Section 8.1.17, “AuralAttributes Object.”

public abstract void setReverbDelay(float reverbDelay)

Set AuralAttributes reverberation delay. This method sets the delay time between
each order of reflection (while reverberation is being rendered) explicitly given
in milliseconds. A value for delay time of 0.0 disables reverberation. For a full
description of this parameter and how it is used, see Section 8.1.17, “AuralAt-
tributes Object.”

public abstract void setReverbOrder(int reverbOrder)

Set AuralAttributes reverberation order. This method sets the number of times
reflections are added to reverberation being calculated. A value of –1 specifies an
unbounded number of reverberations. For a full description of this parameter and
how it is used, see Section 8.1.17, “AuralAttributes Object.”

public abstract void setFrequencyScaleFactor(float

frequencyScaleFactor)

Set AuralAttributes frequency scale factor. This method specifies a scale factor
applied to the frequency (or wavelength). This parameter can also be used to
expand or contract the usual frequency shift applied to the sound source due to

Version 1.2, March 2000 343

12.3 Instantiating and Registering a New Device AUDIO DEVICES

Doppler effect calculations. Valid values are ≥ 0.0. A value greater than 1.0 will
increase the playback rate. For a full description of this parameter and how it is
used, see Section 8.1.17, “AuralAttributes Object.”

public abstract void setVelocityScaleFactor(float

velocityScaleFactor)

Set AuralAttributes velocity scale factor. This method specifies a velocity scale
factor applied to the velocity of sound relative to listener’s position and move-
ment in relation to the sound’s position and movement. This scale factor is mul-
tiplied by the calculated velocity portion of Doppler effect equation used during
sound rendering. For a full description of this parameter and how it is used, see
Section 8.1.17, “AuralAttributes Object.”

public abstract void updateSample(int index)

Explicit update of a sample. This method is called when a Sound is to be explic-

itly updated. It is only called when all a sound’s parameters are known to have
been passed to the audio device. In this way, an implementation can choose to
perform lazy-evaluation of a sample, rather than updating the rendering state of
the sample after every individual parameter changed. This method can be left as
a null method if the implementor so chooses.

12.3 Instantiating and Registering a New Device

A browser or applications developer must instantiate whatever system-specific
audio devices that he or she needs and that exist on the system. This device
information typically exists in a site configuration file. The browser or applica-
tion will instantiate the physical environment as requested by the end user.
The API for instantiating devices is site-specific, but it consists of a device object
with a constructor and at least all of the methods specified in the AudioDevice
interface.
Once instantiated, the browser or application must register the device with the
Java 3D sound scheduler by associating this device with a PhysicalEnvironment
object. The setAudioDevice method introduces new devices to the Java 3D
environment and the allAudioDevices method produces an enumeration that
allows examination of all available devices within a Java 3D environment. See
Section C.9, “The PhysicalEnvironment Object,” for more details.

344 The Java 3D API Specification

 C H A P T E R 13
Execution and Rendering
Model

JAVA 3D’s execution and rendering model assumes the existence of a Virtu-
alUniverse object and an attached scene graph. This scene graph can be minimal
and not noticeable from an application’s perspective when using immediate-
mode rendering, but it must exist.
Java 3D’s execution model intertwines with its rendering modes and with behav-
iors and their scheduling. This chapter first describes the three rendering modes,
then describes how an application starts up a Java 3D environment, and finally, it
discusses how the various rendering modes work within this framework.

13.1 Three Major Rendering Modes

Java 3D supports three different modes for rendering scenes: immediate mode,
retained mode, and compiled-retained mode. These three levels of API support
represent a potentially large variation in graphics processing speed and in on-the-
fly restructuring.

13.1.1 Immediate Mode

Immediate mode allows maximum flexibility at some cost in rendering speed.
The application programmer can either use or ignore the scene graph structure
inherent in Java 3D’s design. The programmer can choose to draw geometry
directly or to define a scene graph. Immediate mode can either be used indepen-
dently or mixed with retained and/or compiled-retained mode rendering. The
immediate-mode API is described in Chapter 14, “Immediate-Mode Rendering.”

Version 1.2, March 2000 345

13.1.2 Retained Mode EXECUTION AND RENDERING MODEL

13.1.2 Retained Mode

Retained mode allows a great deal of the flexibility provided by immediate mode
while also providing a substantial increase in rendering speed. All objects
defined in the scene graph are accessible and manipulable. The scene graph itself
is fully manipulable. The application programmer can rapidly construct the scene
graph, create and delete nodes, and instantly “see” the effect of edits. Retained
mode also allows maximal access to objects through a general pick capability.
Java 3D’s retained mode allows a programmer to construct objects, insert objects
into a database, compose objects, and add behaviors to objects.
In retained mode, Java 3D knows that the programmer has defined objects,
knows how the programmer has combined those objects into compound objects
or scene graphs, and knows what behaviors or actions the programmer has
attached to objects in the database. This knowledge allows Java 3D to perform
many optimizations. It can construct specialized data structures that hold an
object’s geometry in a manner that enhances the speed at which the Java 3D sys-
tem can render it. It can compile object behaviors so that they run at maximum
speed when invoked. It can flatten transformation manipulations and state
changes where possible in the scene graph.

13.1.3 Compiled-retained Mode

Compiled-retained mode allows the Java 3D API to perform an arbitrarily com-
plex series of optimizations including, but not restricted to, geometry compres-
sion, scene graph flattening, geometry grouping, and state change clustering.
Compiled-retained mode provides hooks for end-user manipulation and picking.
Pick operations return the closest object (in scene graph space) associated with
the picked geometry.
Java 3D’s compiled-retained mode ensures effective graphics rendering speed in
yet one more way. A programmer can request that Java 3D compile an object or
a scene graph. Once compiled, the programmer has minimal access to the inter-
nal structure of the object or scene graph. Capability flags provide access to
specified components that the application program may need to modify on a con-
tinuing basis.
A compiled object or scene graph consists of whatever internal structures
Java 3D wishes to create to ensure that objects or scene graphs render at maximal
rates. Because Java 3D knows that the majority of the compiled object’s or scene
graph’s components will not change, it can perform an extraordinary number of
optimizations, including the fusing of multiple objects into one conceptual
346 The Java 3D API Specification
EXECUTION AND RENDERING MODEL Retained and Compiled-retained Rendering Modes 13.2.2

object, turning an object into compressed geometry, or even breaking an object

up into like-kind components and reassembling the like-kind components into
new “conceptual objects.”

13.2 Instantiating the Render Loop

From an application’s perspective, Java 3D’s render loop runs continuously.
Whenever an application adds a scene branch to the virtual world, that scene
branch is instantly visible. This high-level view of the render loop permits con-
current implementations of Java 3D as well as serial implementations. The
remainder of this section describes the Java 3D render loop bootstrap process
from a serialized perspective. Differences that would appear in concurrent imple-
mentations are noted as well.

13.2.1 An Application-level Perspective

First the application must construct its scene graphs. It does this by constructing
scene graph nodes and component objects and linking them into self-contained
trees with a BranchGroup node as a root. The application next must obtain a ref-
erence to any constituent nodes or objects within that branch that it may wish to
manipulate. It sets the capabilities of all the objects to match their anticipated use
and only then compiles the branch using the BranchGroup’s compile method.
Whether or not it compiles the branch, the application can add it to the virtual
universe by adding the BranchGroup to a Locale object. The application repeats
this process for each branch it wishes to create. Note that for concurrent Java 3D
implementations, whenever an application adds a branch to the active virtual uni-
verse, that branch becomes visible.

13.2.2 Retained and Compiled-retained Rendering Modes

This initialization process is identical for retained and compiled-retained modes.
In both modes, the application builds a scene graph. In compiled-retained mode,
the application then compiles the scene graph. Then the application inserts the
(possibly compiled) scene graph into the virtual universe.

Version 1.2, March 2000 347

 C H A P T E R 14
Immediate-Mode Rendering

JAVA 3D is fundamentally a scene graph–based API. Most of the constructs in

the API are biased toward retained mode and compiled-retained mode rendering.
However, there are some applications that want both the control and the flexibil-
ity that immediate-mode rendering offers.
Immediate-mode applications can either use or ignore Java 3D’s scene graph
structure. By using immediate mode, end-user applications have more freedom,
but this freedom comes at the expense of performance. In immediate mode,
Java 3D has no high-level information concerning graphical objects or their com-
position. Because it has minimal global knowledge, Java 3D can only perform
localized optimizations on behalf of the application programmer.

14.1 Two Styles of Immediate-Mode Rendering

Use of Java 3D’s immediate mode falls into one of two categories: pure immedi-
ate-mode rendering and mixed-mode rendering in which immediate mode and
retained or compiled-retained mode interoperate and render to the same canvas.
The Java 3D renderer is idle in pure immediate mode, distinguishing it from
mixed-mode rendering.

14.1.1 Pure Immediate-Mode Rendering

Pure immediate-mode rendering provides for those applications and applets that
do not want Java 3D to do any automatic rendering of the scene graph. Such
applications may not even wish to build a scene graph to represent their graphi-
cal data. However, they use Java 3D’s attribute objects to set graphics state and
Java 3D’s geometric objects to render geometry.
A pure immediate mode application must create a minimal set of Java 3D objects
before rendering. In addition to a Canvas3D object, the application must create a
Version 1.2, March 2000 349
14.1.1 Pure Immediate-Mode Rendering IMMEDIATE-MODE RENDERING

View object, with its associated PhysicalBody and PhysicalEnvironment objects,

and the following scene graph elements: a VirtualUniverse object, a high-resolu-
tion Locale object, a BranchGroup node object, a TransformGroup node object
with associated transform and, finally, a ViewPlatform leaf node object that
defines the position and orientation within the virtual universe that generates the
view (see Figure 14-1).

Virtual Universe

Hi-res Locale

BranchGroup BG

TransformGroup TG

ViewPlatform View Canvas3D Screen3D

VP

Physical Physical
Body Environment

Figure 14-1 Minimal Immediate-Mode Structure

Java 3D provides utility functions that create much of this structure on behalf of
a pure immediate-mode application, making it less noticeable from the applica-
tion’s perspective—but the structure must exist.
All rendering is done completely under user control. It is necessary for the user
to clear the 3D canvas, render all geometry, and swap the buffers. Additionally,
rendering the right and left eye for stereo viewing becomes the sole responsibil-
ity of the application.
In pure immediate mode, the user must stop the Java 3D renderer, via the
Canvas3D object stopRenderer() method, prior to adding the Canvas3D object
to an active View object (that is, one that is attached to a live ViewPlatform
object).

350 The Java 3D API Specification

IMMEDIATE-MODE RENDERING Mixed-Mode Rendering 14.1.2

14.1.2 Mixed-Mode Rendering

Mixing immediate mode and retained or compiled-retained mode requires more
structure than pure immediate mode. In mixed mode, the Java 3D renderer is run-
ning continuously, rendering the scene graph into the canvas. The basic Java 3D
stereo rendering loop, executed for each Canvas3D, is as follows:

clear canvas (both eyes)

call preRender() // user-supplied method
set left eye view
render opaque scene graph objects
call renderField(FIELD_LEFT) // user-supplied method
render transparent scene graph objects
set right eye view
render opaque scene graph objects again
call renderField(FIELD_RIGHT) // user-supplied method
render transparent scene graph objects again
call postRender() // user-supplied method
synchronize and swap buffers
call postSwap() // user-supplied method

The basic Java 3D monoscopic rendering loop is as follows:

clear canvas
call preRender() // user-supplied method
set view
render opaque scene graph objects
call renderField(FIELD_ALL) // user-supplied method
render transparent scene graph objects
call postRender() // user-supplied method
synchronize and swap buffers
call postSwap() // user-supplied method

In both cases, the entire loop, beginning with clearing the canvas and ending with
swapping the buffers, defines a frame. The application is given the opportunity to
render immediate-mode geometry at any of the clearly identified spots in the ren-
dering loop. A user specifies his or her own rendering methods by extending the
Canvas3D class and overriding the preRender, postRender, postSwap, and/or
renderField methods.

Version 1.2, March 2000 351

14.2 Canvas3D Methods IMMEDIATE-MODE RENDERING

14.2 Canvas3D Methods

The Canvas3D methods that directly affect immediate-mode rendering are
described here.
When a Canvas3D object is created, it is initially marked as being started. This
means that as soon as the Canvas3D is added to an active View object, the ren-
dering loop will render the scene graph to the canvas. In pure immediate mode
the renderer must be stopped (via a call to stopRenderer) prior to adding the
canvas to an active View object.

Constants

public static final int FIELD_LEFT

public static final int FIELD_RIGHT
public static final int FIELD_ALL

These constants specify the field that the rendering loop for this Canvas3D is
rendering. The FIELD_LEFT and FIELD_RIGHT values indicate the left and right
fields of a field-sequential stereo rendering loop, respectively. The FIELD_ALL
value indicates a monoscopic or single-pass stereo rendering loop.

Methods

public GraphicsContext3D getGraphicsContext3D()

This method retrieves the immediate-mode 3D graphics context associated with

this Canvas3D. It creates a new graphics context if one does not already exist. It
returns a GraphicsContext3D object that can be used for immediate mode render-
ing to this Canvas3D.

public J3DGraphics2D getGraphics2D() New in 1.2

This method returns the 2D graphics object associated with this Canvas3D. A
new 2D graphics object is created if one does not already exist. See
“J3DGraphics2D.”

public void preRender()

Applications that wish to perform operations in the rendering loop prior to any
actual rendering must override this method. The Java 3D rendering loop invokes
this method after clearing the canvas and before any rendering has been done for
this frame. Applications should not call this method.

352 The Java 3D API Specification

IMMEDIATE-MODE RENDERING Canvas3D Methods 14.2

public void postRender()

Applications that wish to perform operations in the rendering loop following any
actual rendering must override this method. The Java 3D rendering loop invokes
this method after completing all rendering to the canvas for this frame and before
the buffer swap. Applications should not call this method.

public void postSwap()

Applications that wish to perform operations at the very end of the rendering
loop must override this method. The Java 3D rendering loop invokes this method
after completing all rendering to this canvas, and all other canvases associated
with the current view, for this frame following the buffer swap. Applications that
wish to perform operations at the very end of the rendering loop may override
this function. In off-screen mode, all rendering is copied to the off-screen buffer
before this method is called. Applications should not call this method.

public void renderField(int fieldDesc)

Applications that wish to perform operations during the rendering loop must
override this function. The Java 3D rendering loop invokes this method, possibly
twice, during the loop. It is called once for each field (once per frame on a mono-
scopic system or once each for the right eye and left eye on a field-sequential ste-
reo system). This method is called after all opaque objects are rendered and
before any transparent objects are rendered (subject to restrictions imposed by
OrderedGroup nodes). This is intended for use by applications that want to mix
retained/compiled-retained mode rendering with some immediate-mode render-
ing. The fieldDesc parameter is the field description: FIELD_LEFT, FIELD_
RIGHT, or FIELD_ALL. Applications that wish to work correctly in stereo mode
should render the same image for both FIELD_LEFT and FIELD_RIGHT calls. If
Java 3D calls the renderer with FIELD_ALL, the immediate-mode rendering only
needs to be done once. Applications should not call this method.

public final void startRenderer()

public final void stopRenderer()

These methods start or stop the Java 3D renderer for this Canvas3D object. If the
Java 3D renderer is currently running when stopRenderer is called, the render-
ing will be synchronized before being stopped. No further rendering will be done
to this canvas by Java 3D until the renderer is started again. If the Java 3D ren-
derer is not currently running when startRenderer is called, any rendering to
other Canvas3D objects sharing the same View will be synchronized before this
Canvas3D’s renderer is (re)started.

Version 1.2, March 2000 353

14.3 API for Immediate Mode IMMEDIATE-MODE RENDERING

public final boolean isRendererRunning() New in 1.2

This method retrieves the state of the renderer for this Canvas3D object.

public void swap()

This method synchronizes and swaps buffers on a double-buffered canvas for this
Canvas3D object. This method should only be called if the Java 3D renderer has
been stopped. In the normal case, the renderer automatically swaps the buffer.
This method calls the flush(true) methods of the associated 2D and 3D graph-
ics contexts, if they have been allocated. If the application invokes this method
and the canvas has a running Java 3D renderer, a RestrictedAccessException
exception is thrown. An IllegalStateExceptiion is thrown if this Canvas3D is
in off-screen mode.

14.3 API for Immediate Mode

The Java 3D immediate mode allows an application to directly set attributes and
draw three-dimensional geometry using the same objects as in Java 3D scene
graphs. An immediate-mode application renders by passing these objects to the
set and draw methods of a GraphicsContext3D object.

14.3.1 GraphicsContext3D
The GraphicsContext3D object is used for immediate-mode rendering into a 3D
canvas. It is created by, and associated with, a specific Canvas3D object. A
GraphicsContext3D class defines methods that manipulate 3D graphics state
attributes and draw 3D geometric primitives.
Note that the drawing methods in this class are not necessarily executed immedi-
ately. They may be buffered up for future execution. Applications must call the
flush(boolean) method to ensure that the rendering actually happens. The
flush method is implicitly called in the following cases:

• The readRaster method calls flush(true)

• The Canvas3D.swap method calls flush(true)
• The Java 3D renderer calls flush(true) prior to swapping the buffer for
a double-buffered on-screen Canvas3D
• The Java 3D renderer calls flush(true) prior to copying into the off-
screen buffer of an off-screen Canvas3D
• The Java 3D renderer calls flush(false) after calling the preRender,
renderField, postRender, and postSwap Canvas3D callback methods.

354 The Java 3D API Specification

IMMEDIATE-MODE RENDERING GraphicsContext3D 14.3.1

A single-buffered, pure-immediate mode application must explicitly call flush

to ensure that the graphics will be rendered to the Canvas3D.

Constants

public static final int STEREO_LEFT New in 1.2

public static final int STEREO_RIGHT New in 1.2
public static final int STEREO_BOTH New in 1.2

These constants specify whether rendering is done to the left eye, the right eye,
or to both.

Constructors
There are no publicly accessible constructors of GraphicsContext3D. An applica-
tion obtains a 3D graphics context object from the Canvas3D object into which
the application wishes to render by using the getGraphicsContext3D method.
The Canvas3D object creates a new GraphicsContext3D the first time an applica-
tion invokes getGraphicsContext3D. A new GraphicsContext3D initializes its
state variables to the following defaults:
Parameters Default Values
Background object null
Fog object null
ModelClip object null
Appearance object null
List of Light objects empty
High-Res coordinates (0, 0, 0,)
modelTransform identity
AuralAttributes object null
List of Sound objects empty
buffer override false
front buffer rendering false
stereo mode STEREO_BOTH

Methods

public Canvas3D getCanvas3D()

This method gets the Canvas3D that created this GraphicsContext3D.

Version 1.2, March 2000 355

14.3.1 GraphicsContext3D IMMEDIATE-MODE RENDERING

public void setAppearance(Appearance appearance)

public Appearance getAppearance()

These methods access or modify the current Appearance component object used
by this 3D graphics context. The graphics context stores a reference to the spec-
ified Appearance object. This means that the application may modify individual
appearance attributes by using the appropriate methods on the Appearance object
(see Section 8.1.2, “Appearance Object”). The Appearance component object
must not be part of a live scene graph, nor may it subsequently be made part of a
live scene graph—an IllegalSharingException is thrown in such cases. If the
Appearance object is null, default values will be used for all appearance
attributes—it is as if an Appearance node were created using the default con-
structor.

public void setBackground(Background background)

public Background getBackground()

These methods access or modify the current Background leaf node object used
by this 3D graphics context. The graphics context stores a reference to the spec-
ified Background node. This means that the application may modify the back-
ground color or image by using the appropriate methods on the Background node
object (see Section 6.4, “Background Node”). The Background node must not be
part of a live scene graph, nor may it subsequently be made part of a live scene
graph—an IllegalSharingException is thrown in such cases. If the Back-
ground object is null, the default background color of black (0,0,0) is used to
clear the canvas prior to rendering a new frame. The Background node’s applica-
tion region is ignored for immediate-mode rendering.

public void setFog(Fog fog)

public Fog getFog()

These methods access or modify the current Fog leaf node object used by this 3D
graphics context. The graphics context stores a reference to the specified Fog
node. This means that the application may modify the fog attributes using the
appropriate methods on the Fog node object (see Section 6.7, “Fog Node”). The
Fog node must not be part of a live scene graph, nor may it subsequently be
made part of a live scene graph—an IllegalSharingException is thrown in
such cases. If the Fog object is null, fog is disabled. Both the region of influence
and the hierarchical scope of the Fog node are ignored for immediate-mode ren-
dering.

356 The Java 3D API Specification

IMMEDIATE-MODE RENDERING GraphicsContext3D 14.3.1

public void addLight(Light light)

public void insertLight(Light light, int index)
public void setLight(Light light, int index)
public Light getLight(int index)
public void removeLight(int index)
public int numLights()
public Enumeration getAllLights()

These methods access or modify the list of lights used by this 3D graphics con-
text. The addLight method adds a new light to the end of the list of lights. The
insertLight method inserts a new light before the light at the specified index.
The setLight method replaces the light at the specified index with the light pro-
vided. The removeLight method removes the light at the specified index. The
numLights method returns a count of the number of lights in the list. The
getLight method returns the light at the specified index. The getAllLights
method retrieves the Enumeration object of all lights.
The graphics context stores a reference to each light object in the list of lights.
This means that the application may modify the light attributes for any of the
lights using the appropriate methods on that Light node object (see Section 6.8,
“Light Node”). None of the Light nodes in the list of lights may be part of a live
scene graph, nor may they subsequently be made part of a live scene graph—an
IllegalSharingException is thrown in such cases. Adding a null Light object
to the list will result in a NullPointerException. Both the region of influence
and the hierarchical scope of all lights in the list are ignored for immediate-mode
rendering.

public void setHiRes(int x[], int y[], int z[])

public void setHiRes(HiResCoord hiRes)
public void getHiRes(HiResCoord hiRes)

These methods access or modify the high-resolution coordinates of this graphics

context to the location specified by the parameters provided. In the first method,
the parameters x, y, and z are arrays of eight 32-bit integers that specify the high-
resolution coordinates point.

public void setModelTransform(Transform3D t)

public void multiplyModelTransform(Transform3D t)
public void getModelTransform(Transform3D t)

These methods access or modify the current model transform. The multiply-
ModelTransform method multiplies the current model transform by the specified
transform and stores the result back into the current model transform. The speci-
fied transformation must be affine. A BadTransformException is thrown (see

Version 1.2, March 2000 357

14.3.1 GraphicsContext3D IMMEDIATE-MODE RENDERING

Section D.1, “BadTransformException”) if an attempt is made to specify an ille-

gal Transform3D.

public void setBufferOverride(boolean bufferOverride) New in 1.2

public boolean getBufferOverride() New in 1.2

These methods set and retrieve a flag that specifies whether the double buffering
and stereo mode from the Canvas3D are overridden. When set to true, this
attribute enables the frontBufferRendering and stereoMode attributes.

public void setFrontBufferRendering(boolean frontBufferRendering) New in 1.2

public boolean getFrontBufferRendering() New in 1.2

These methods set and retrieve a flag that enables or disables immediate mode
rendering into the front buffer of a double buffered Canvas3D. This attribute is
only used when the bufferOverride flag is enabled. Note that this attribute has
no effect if double buffering is disabled or is not available on the Canvas3D.

public void setStereoMode(int stereoMode) New in 1.2

public int getStereoMode() New in 1.2

These methods set and retrieve the current stereo mode for immediate mode ren-
dering. The parameter specifies which stereo buffer or buffers is rendered into.
This attribute is only used when the bufferOverride flag is enabled. The stereo
mode is one of the following: STEREO_LEFT, STEREO_RIGHT, or STEREO_BOTH.
Note that this attribute has no effect if stereo is disabled or is not available on the
Canvas3D.

public void setModelClip(ModelClip modelClip) New in 1.2

public ModelClip getModelClip() New in 1.2

These methods set and retrieve the current ModelClip leaf node. The set method
sets the ModelClip to the specified object. The graphics context stores a refer-
ence to the specified ModelClip node. This means that the application may mod-
ify the model clipping attributes using the appropriate methods on the ModelClip
node object. The ModelClip node must not be part of a live scene graph, nor may
it subsequently be made part of a live scene graph-an IllegalSharingException is
thrown in such cases. If the ModelClip object is null, model clipping is disabled.
Both the region of influence and the hierarchical scope of the ModelClip node
are ignored for immediate-mode rendering.

358 The Java 3D API Specification

IMMEDIATE-MODE RENDERING GraphicsContext3D 14.3.1

public void setAuralAttributes(AuralAttributes attributes)

public AuralAttributes getAuralAttributes()

These methods access or modify the current AuralAttributes component object

used by this 3D graphics context. The graphics context stores a reference to the
specified AuralAttributes object. This means that the application may modify
individual audio attributes by using the appropriate methods in the Aural-
Attributes object (see Section 8.1.17, “AuralAttributes Object”). The Aural-
Attributes component object must not be part of a live scene graph, nor may it
subsequently be made part of a live scene graph—an IllegalSharingExcep-
tion is thrown in such cases. If the AuralAttributes object is null, default values
will be used for all audio attributes—it is as if an AuralAttributes object were
created using the default constructor.

public void addSound(Sound sound)

public void insertSound(Sound sound, int index)
public void setSound(Sound sound, int index)
public Sound getSound(int index)
public void removeSound(int index)
public int numSounds()
public boolean isSoundPlaying(int index)
public Enumeration getAllSounds()

These methods access or modify the list of sounds used by this 3D graphics con-
text. The addSound method appends the specified sound to this graphics con-
text’s list of sounds. The insertSound method inserts the specified sound at the
specified index location. The setSound method replaces the specified sound with
the sound provided. The removeSound method removes the sound at the speci-
fied index location. The numSounds method retrieves the current number of
sounds in this graphics context. The getSound method retrieves the index-
selected sound. The isSoundPlaying method retrieves the sound-playing flag.
The getAllSounds method retrieves the Enumeration object of all the sounds.
The graphics context stores a reference to each sound object in the list of sounds.
This means that the application may modify the sound attributes for any of the
sounds by using the appropriate methods on that Sound node object (see
Section 6.9, “Sound Node”). None of the Sound nodes in the list of sounds may
be part of a live scene graph, nor may they subsequently be made part of a live
scene graph—an IllegalSharingException is thrown in such cases. Adding a
null Sound object to the list results in a NullPointerException. If the list of
sounds is empty, sound rendering is disabled.
Adding or inserting a sound to the list of sounds implicitly starts the sound play-
ing. Once a sound is finished playing, it can be restarted by setting the sound’s

Version 1.2, March 2000 359

14.3.2 J3DGraphics2D IMMEDIATE-MODE RENDERING

enable flag to true. The scheduling region of all sounds in the list is ignored for
immediate-mode rendering.

public void readRaster(Raster raster)

This method reads an image from the frame buffer and copies it into the Image-
Component or DepthComponent objects referenced by the specified Raster
object. All parameters of the Raster object and the component ImageComponent
or DepthComponent objects must be set to the desired values prior to calling this
method. These values determine the location, size, and format of the pixel data
that is read. This method calls flush(true) prior to reading the frame buffer.

public void clear()

This method clears the canvas to the color or image specified by the current
Background leaf node object.

public void draw(Geometry geometry)

public void draw(Shape3D shape)

The first draw method draws the specified Geometry component object using the
current state in the graphics context. The second draw method draws the speci-
fied Shape3D leaf node object. This is a convenience method that is identical to
calling the setAppearance(Appearance) and draw(Geometry) methods passing
the Appearance and Geometry component objects of the specified Shape3D
nodes as arguments.

public void flush(boolean wait) New in 1.2

This method flushes all previously-executed rendering operations to the drawing

buffer for this 3D graphics context. The wait parameter indicates whether to
wait for the rendering to complete before returning from this call.

14.3.2 J3DGraphics2D New in 1.2

The J3DGraphics2D class extends Graphics2D to provide 2D rendering into a

Canvas3D. It is an abstract base class that is further extended by a non-public
Java 3D implementation class. This class allows Java 2D rendering to be mixed
with Java 3D rendering in the same Canvas3D, subject to the same restrictions as
imposed for 3D immediate-mode rendering: In mixed-mode rendering, all Java
2D requests must be done from one of the Canvas3D callback methods; in pure-
immediate mode, the Java 3D renderer must be stopped for the Canvas3D being
rendered into.

360 The Java 3D API Specification

IMMEDIATE-MODE RENDERING J3DGraphics2D 14.3.2

An application obtains a Java 3D 2D graphics context object from the Canvas3D

object that the application wishes to render into by using the getGraphics2D
method. A new J3DGraphics2D object is created if one does not already exist.
Note that the drawing methods in this class, including those inherited from
Graphics2D, are not necessarily executed immediately. They may be buffered up
for future execution. Applications must call the flush(boolean) method to
ensure that the rendering actually happens. The flush method is implicitly called
in the following cases:
• The Canvas3D.swap method calls flush(true)
• The Java 3D renderer calls flush(true) prior to swapping the buffer for
a double-buffered on-screen Canvas3D
• The Java 3D renderer calls flush(true) prior to copying into the off-
screen buffer of an off-screen Canvas3D.
• The Java 3D renderer calls flush(false) after calling the preRender,
renderField, postRender, and postSwap Canvas3D callback methods

A single-buffered, pure-immediate mode application must explicitly call flush

to ensure that the graphics will be rendered to the Canvas3D.

Methods

public abstract void flush(boolean wait) New in 1.2

This method flushes all previously-executed rendering operations to the drawing

buffer for this 2D graphics object.

public final Graphics create() New in 1.2

public final Graphics create(int x, int y, int width, int height) New in 1.2

These methods are not supported. The only way to obtain a J3DGraphics2D is
from the associated Canvas3D.

public final void setBackground(Color color) New in 1.2

public final Color getBackground() New in 1.2
public final void clearRect(int x, int y, int width, int height) New in 1.2

These methods are not supported. Clearing a Canvas3D is done implicitly via a
Background node in the scene graph or explicitly via the clear method in a 3D
graphics context.

Version 1.2, March 2000 361

 A PPE N D I X A
Math Objects

MATHEMATICAL objects allow Java 3D users to represent and manipulate

low-level mathematical constructs such as vectors and matrices. Math objects
also define specific operations that allow users to manipulate them in appropriate
ways.
Java 3D needs these vector and matrix math classes. It uses them internally and
also makes them available to applications for their use. However, they are not
part of Java 3D. Rather, they are defined here for convenience. These classes will
become more widely distributed, which is why Java 3D defines them as a sepa-
rate javax.vecmath package. Figure A-1 shows the math object hierarchy.

A.1 Tuple Objects

Java 3D uses tuple objects to represent and manipulate two-, three-, and four-ele-
ment values.

A.1.1 Tuple2d Class

The Tuple2d class is used for points and vectors. This class is a two-element
tuple that is represented by double-precision floating point x,y coordinates.

Variables
The component values of a Tuple2d are directly accessible through the public
variables x and y. To access the x component of a Tuple2d called upperLeft-
Corner, a programmer would write upperLeftCorner.x. The programmer
would access the y component similarly.

Version 1.2, March 2000 363

A.1.1 Tuple2d Class MATH OBJECTS

Tuple Objects
Tuple2d
Point2d
Vector2d
Tuple2f
Point2f
TexCoord2f
Vector2f
Tuple3b
Color3b
Tuple3d
Point3d
Vector3d
Tuple3f
Color3f
Point3f
TexCoord3f
Vector3f
Tuple3i
Point3i
Tuple4b
Color4b
Tuple4d
Point4d
Quat4d
Vector4d
Tuple4f
Color4f
Point4f
Quat4f
Vector4f
Tuple4i
Point4i
AxisAngle4d
AxisAngle4f
GVector
Matrix Objects
Matrix3f
Matrix3d
Matrix4f
Matrix4d
GMatrix

Figure A-1 Math Object Hierarchy

364 The Java 3D API Specification

MATH OBJECTS Tuple2d Class A.1.1

public double x
Public double y

The x and y coordinates, respectively.

Constructors

public Tuple2d(double x, double y)

public Tuple2d(double[] t)
public Tuple2d(Tuple2d t1)
public Tuple2d(Tuple2f t1)
public Tuple2d()

These five constructors each return a new Tuple2d. The first constructor gener-
ates a Tuple2d from two double-precision floating-point numbers x and y. The
second constructor generates a Tuple2d from the first two elements of array t.
The third and fourth constructors generate a Tuple2d from the tuple t1. The final
constructor generates a Tuple2d with the value of (0.0, 0.0).

Methods

public final void set(double x, double y)

public final void set(double[] t)
public final void set(Tuple2d t1)
public final void set(Tuple2f t1)
public final void get(double[] t)

The first set method sets the value of this tuple to the specified xy coordinates.
The second set method sets the value of this tuple from the two values specified
in the array t. The third and fourth set methods set the value of this tuple to the
value of the tuple t1. The get method copies the value of the elements of this
tuple into the array t.

public final void add(Tuple2d t1, Tuple2d t2)

public final void add(Tuple2d t1)
public final void sub(Tuple2d t1, Tuple2d t2)
public final void sub(Tuple2d t1)

The first add method sets the value of this tuple to the vector sum of tuples v1
and v2. The second add method sets the value of this tuple to the vector sum of
itself and tuple t1. The first sub method sets the value of this tuple to the vector
difference of tuple t1 and t2 (this = t1 – t2). The second sub method sets the
value of this tuple to the vector difference of itself and tuple t1 (this = this – t1).

Version 1.2, March 2000 365

A.1.1 Tuple2d Class MATH OBJECTS

public final void negate(Tuple2d t1)

public final void negate()

The first negate method sets the value of this tuple to the negation of tuple t1.
The second method negates the value of this vector in place.

public final void scale(double s, Tuple2d t1)

public final void scale(double s)
public final void scaleAdd(double s, Tuple2d t1)
public final void scaleAdd(double s, Tuple2d t1, Tuple2d t2)

The first scale method multiplies each element of the tuple t1 by the scale fac-
tor s and places the resulting scaled tuple into this. The second method multi-
plies each element of this tuple by the scale factor s and places the resulting
scaled tuple into this. The first scaleAdd method scales this tuple by the scale
factor s, adds the result to tuple t1, and places the result into the tuple this (this
= s*this + t1). The second scaleAdd method scales tuple t1 by the scale factor
s, adds the result to tuple t1, then places the result into the tuple this (this =
s*t1 + t2).

public final void absolute(Tuple2d t)

This method sets each component of the tuple parameter to its absolute value and
places the modified values into this tuple.

public final void clamp(double min, double max)

public final void clamp(double min, double max, Tuple2d t)
public final void clampMin(double min)
public final void clampMin(double min, Tuple2d t)
public final void clampMax(double max)
public final void clampMax(double max, Tuple2d t)

The first clamp method clamps this tuple to the range [min, max]. The second
clamp method clamps the values from tuple t to the range [min, max] and assigns
these clamped values to this tuple. The first clampMin method clamps each value
of this tuple to the min parameter. The second clampMin method clamps each
value of the tuple t and assigns these clamped values to this tuple. The first
clampMax method clamps each value of this tuple to the max parameter. The sec-
ond clampMax method clamps each value of tuple t to the max parameter and
assigns these clamped values to this tuple. In each method the values of tuple t
remain unchanged.

366 The Java 3D API Specification

MATH OBJECTS Tuple2d Class A.1.1

public final void interpolate(Tuple2d t1, Tuple2d t2, double alpha)

public final void interpolate(Tuple2d t1, double alpha)

The first method linearly interpolates between tuples t1 and t2 and places the
result into this tuple (this = (1 – alpha) * t1 + alpha * t2). The second method lin-
early interpolates between this tuple and tuple t1 and places the result into this
tuple (this = (1 – alpha) * this + alpha * t1).

public boolean equals(Tuple2d t1)

public boolean equals(Object t1)

The first method returns true if all of the data members of tuple t1 are equal to
the corresponding data members in this tuple. The second method returns true if
the Object t1 is of type Tuple2d and all of the data members of t1 are equal to
the corresponding data members in this Tuple2d.

public boolean epsilonEquals(Tuple2d t1, double epsilon)

This method returns true if the L∞ distance between this tuple and tuple t1 is
less than or equal to the epsilon parameter. Otherwise, this method returns
false. The L∞ distance is equal to

MAX [ abs ( x1 – x2 ), abs ( y1 – y2 ) ]

public int hashCode()

The hashCode method returns a hash number based on the data values in this
object. Two Tuple2d objects with identical data values (that is,
equals(Tuple2d) returns true) will return the same hash number. Two objects
with different data members may return the same hash number, although this is
not likely.

public String toString()

This method returns a string that contains the values of this Tuple2d.

A.1.1.1 Point2d Class

The Point2d class extends Tuple2d. The Point2d is a two-element point repre-
sented by double-precision floating-point x,y coordinates.

Constructors

public Point2d(double x, double y)

public Point2d(double p[])
public Point2d(Point2d p1)

Version 1.2, March 2000 367

A.1.1 Tuple2d Class MATH OBJECTS

public Point2d(Point2f p1)

public Point2d(Tuple2d t1)
public Point2d(Tuple2f t1)
public Point2d()

These seven constructors each return a new Point2d. The first constructor gener-
ates a Point2d from two double-precision floating-point numbers x and y. The
second constructor generates a Point2d from the first two elements of array p.
The third and fourth constructors generate a Point2d from the point p1. The fifth
and sixth constructors generate a Point2d from the tuple t1. The final constructor
generates a Point2d with the value of (0.0, 0.0).

Methods

public final double distanceSquared(Point2d p1)

public final double distance(Point2d p1)

The distanceSquared method computes the square of the Euclidean distance

between this point and point p1 and returns the result. The distance method
computes the Euclidean distance between this point and point p1 and returns the
result.

public final double distanceL1(Point2d p1)

This method computes the L1 (Manhattan) distance between this point and point
p1. The L1 distance is equal to

abs ( x1 – x2 ) + abs ( y1 – y2 )

public final double distanceLinf(Point2d p1)

This method computes the L∞ distance between this point and point p1. The L∞
distance is equal to

MAX [ abs ( x1 – x2 ), abs ( y1 – y2 ) ]

A.1.1.2 Vector2d Class

The Vector2d class extends Tuple2d. The Vector2f is a two-element vector repre-
sented by double-precision floating-point x,y coordinates.

Constructors

public Vector2d(double x, double y)

public Vector2d(double v[])

368 The Java 3D API Specification

MATH OBJECTS Tuple2f Class A.1.2

public Vector2d(Vector2d v1)

public Vector2d(Vector2f v1)
public Vector2d(Tuple2d t1)
public Vector2d(Tuple2f t1)
public Vector2d()

These seven constructors each return a new Vector2d. The first constructor gen-
erates a Vector2d from two floating-point numbers x and y. The second construc-
tor generates a Vector2d from the first two elements of array v. The third and
fourth constructors generate a Vector2d from the vector v1. The fifth and sixth
constructors generate a Vector2d from the specified tuple t1. The final construc-
tor generates a Vector2d with the value of (0.0, 0.0).

Methods

public final double dot(Vector2d v1)

The dot method computes the dot product between this vector and vector v1 and
returns the resulting value.

public final double lengthSquared()

public final double length()

The lengthSquared method computes the square of the length of the vector
this and returns its length as a double-precision floating-point number. The
length method computes the length of the vector this and returns its length as
a double-precision floating-point number.

public final void normalize(Vector2d v1)

public final void normalize()

The first normalize method normalizes the vector v1 to unit length and places
the result in this. The second normalize method normalizes the vector this
and places the resulting unit vector back into this.

public final double angle(Vector2d v1)

This method returns the angle, in radians, between this vector and vector v1. The
return value is constrained to the range [0, π].

A.1.2 Tuple2f Class

The Tuple2f class is a generic two-element tuple mostly used for specifying
points and vectors made up of single-precision floating-point x,y coordinates.

Version 1.2, March 2000 369

A.1.2 Tuple2f Class MATH OBJECTS

Variables
The component values of a Tuple2f are directly accessible through the public
variables x and y. To access the x component of a Tuple2f called upperLeftCor-
ner, a programmer would write upperLeftCorner.x. The programmer would
access the y component similarly.

public float x
public float y

The x and y coordinates, respectively.

Constructors

public Tuple2f(float x, float y)

public Tuple2f(float t[])
public Tuple2f(Tuple2f t1)
public Tuple2f(Tuple2d t1)
public Tuple2f()

These five constructors each return a new Tuple2f. The first constructor generates
a Tuple2f from two floating-point numbers x and y. The second constructor gen-
erates a Tuple2f from the first two elements of array t. The third and fourth con-
structors generate a Tuple2f from the tuple t1. The final constructor generates a
Tuple2f with the value of (0.0, 0.0).

Methods

public final void set(float x, float y)

public final void set(float t[])
public final void set(Tuple2f t1)
punlic final void set(Tiple2d t1)
public final void get(float t[])

The set methods set the value of tuple this to the values provided. The get
method copies the values of the elements of this tuple into the array t.

public final void add(Tuple2f t1, Tuple2f t2)

public final void add(Tuple2f t1)
public final void sub(Tuple2f t1, Tuple2f t2)
public final void sub(Tuple2f t1)

The first add method computes the element-by-element sum of tuples t1 and t2,
placing the result in this. The second add method computes the element-by-ele-
ment sum of this tuple and tuple t1, placing the result in this. The first sub
method performs an element-by-element subtraction of tuple t2 from tuple t1
370 The Java 3D API Specification
MATH OBJECTS Tuple2f Class A.1.2

and places the result in this (this = t1 – t2). The second sub method performs an
element-by-element subtraction of t1 from this and places the result in this
(this = this – t1).

public final void negate(Tuple2f t1)

public final void negate()

The first negate method sets the values of this tuple to the negative of the values
from tuple t1. The second negate method negates the tuple this and places the
resulting tuple back into this.

public final void scale(float s, Tuple2f t1)

public final void scale(float s)
public final void scaleAdd(float s, Tuple2f t1)
public final void scaleAdd(float s, Tuple2f t1, Tuple2f t2)

The first scale method multiplies each element of the tuple t1 by the scale fac-
tor s and places the resulting scaled tuple into this. The second scale method
multiplies each element of this tuple by the scale factor s and places the resulting
scaled tuple into this. The first scaleAdd method scales this tuple by the scale
factor s, adds the result to tuple t1, and places the result into the tuple this (this
= s*this + t1). The second scaleAdd method scales tuple t1 by the scale factor
s, adds the result to tuple t2, then places the result into the tuple this (this =
s*t1 + t2).

public final void absolute()

public final void absolute(Tuple2f t)

The first absolute method sets each component of this tuple to its absolute
value. The second absolute method sets each component of this tuple to the
absolute value of the corresponding component in tuple t.

public final void clamp(float min, float max)

public final void clamp(float min, float max, Tuple2f t)
public final void clampMin(float min)
public final void clampMin(float min, Tuple2f t)
public final void clampMax(float max)
public final void clampMax(float max, Tuple2f t)

The first clamp method clamps this tuple to the range [min, max]. The second
clamp method clamps the values from tuple t to the range [min, max] and assigns
these clamped values to this tuple. The first clampMin method clamps each value
of this tuple to the min parameter. The second clampMin method clamps each
value of the tuple t and assigns these clamped values to this tuple. The first
clampMax method clamps each value of this tuple to the max parameter. The sec-

Version 1.2, March 2000 371

A.1.2 Tuple2f Class MATH OBJECTS

ond clampMax method clamps each value of tuple t to the max parameter and
assigns these clamped values to this tuple. In each method the values of tuple t
remain unchanged.

public final void interpolate(Tuple2f t1, Tuple2f t2, float alpha)

public final void interpolate(Tuple2f t1, float alpha)

The first method linearly interpolates between tuples t1 and t2 and places the
result into this tuple (this = (1 – alpha) * t1 + alpha * t2). The second method lin-
early interpolates between this tuple and tuple t1 and places the result into this
tuple (this = (1 – alpha) * this + alpha * t1).

public boolean equals(Tuple2f t1)

public boolean equals(Object t1)

The first method returns true if all of the data members of tuple t1 are equal to
the corresponding data members in this tuple. The second method returns true if
the Object t1 is of type Tuple2f and all of the data members of t1 are equal to
the corresponding data members in this Tuple2f.

public boolean epsilonEquals(Tuple2f t1, float epsilon)

This method returns true if the L∞ distance between this tuple and tuple t1 is
less than or equal to the epsilon parameter. Otherwise, this method returns
false. The L∞ distance is equal to

MAX [ abs ( x1 – x2 ), abs ( y1 – y2 ) ]

public int hashCode()

The hashCode method returns a hash number based on the data values in this
object. Two Tuple2f objects with identical data values (that is, equals(Tuple2f)
returns true) will return the same hash number. Two objects with different data
members may return the same hash number, although this is not likely.

public String toString()

This method returns a string that contains the values of this Tuple2f.

A.1.2.1 Point2f Class

The Point2f class extends Tuple2f. The Point2f is a two-element point repre-
sented by single-precision floating-point x,y coordinates.

372 The Java 3D API Specification

MATH OBJECTS Tuple2f Class A.1.2

Constructors

public Point2f(float x, float y)

public Point2f(float p[])
public Point2f(Point2f p1)
public Point2f(Point2d p1)
public Point2f(Tuple2f t1)
public Point2f(Tuple2f t1)
public Point2f()

These seven constructors each return a new Point2f. The first constructor gener-
ates a Point2f from two floating-point numbers x and y. The second constructor
generates a Point2f from the first two elements of array p. The third and fourth
constructors generate a Point2f from the point p1. The fifth and sixth construc-
tors generate a Point2f from the tuple t1. The final constructor generates a
Point2f with the value of (0.0, 0.0).

Methods

public final float distanceSquared(Point2f p1)

public final float distance(Point2f p1)

The distanceSquared method computes the square of the Euclidean distance

between this point and point p1 and returns the result. The distance method
computes the Euclidean distance between this point and point p1 and returns the
result.

public final float distanceL1(Point2f p1)

This method computes the L1 (Manhattan) distance between this point and point
p1. The L1 distance is equal to

abs ( x1 – x2 ) + abs ( y1 – y2 )

public final float distanceLinf(Point2f p1)

This method computes the L∞ distance between this point and point p1. The L∞
distance is equal to

MAX [ abs ( x1 – x2 ), abs ( y1 – y2 ) ]

A.1.2.2 Vector2f Class

The Vector2f class extends Tuple2f. The Vector2f is a two-element vector repre-
sented by single-precision floating-point x,y coordinates.

Version 1.2, March 2000 373

A.1.2 Tuple2f Class MATH OBJECTS

Constructors

public Vector2f(float x, float y)

public Vector2f(float v[])
public Vector2f(Vector2f v1)
public Vector2f(Vector2d v1)
public Vector2f(Tuple2f t1)
public Vector2f(Tuple2d t1)
public Vector2f()

These seven constructors each return a new Vector2f. The first constructor gener-
ates a Vector2f from two floating-point numbers x and y. The second constructor
generates a Vector2f from the first two elements of array v. The third and fourth
constructors generate a Vector2f from the vector v1. The fifth and sixth construc-
tors generate a Vector2f from the specified tuple t1. The final constructor gener-
ates a Vector2f with the value of (0.0, 0.0).

Methods

public final float dot(Vector2f v1)

The dot method computes the dot product between this vector and vector v1 and
returns the resulting value.

public final float lengthSquared()

public final float length()

The lengthSquared method computes the square of the length of the vector
this and returns its length as a single-precision floating-point number. The
length method computes the length of the vector this and returns its length as
a single-precision floating-point number.

public final void normalize(Vector2f v1)

public final void normalize()

The first normalize method normalizes the vector v1 to unit length and places
the result in this. The second normalize method normalizes the vector this
and places the resulting unit vector back into this.

public final float angle(Vector2f v1)

This method returns the angle, in radians, between this vector and vector v1. The
return value is constrained to the range [0, π].

374 The Java 3D API Specification

MATH OBJECTS Tuple3b Class A.1.3

A.1.2.3 TexCoord2f Class

The TexCoord2f class is a subset of Tuple2f. The TexCoord2f is a two-element
vector represented by single-precision floating-point x,y coordinates.

Constructors

public TexCoord2f(float x, float y)

public TexCoord2f(float v[])
public TexCoord2f(TexCoord2f v1)
public TexCoord2f(Tuple2f t1)
public TexCoord2f()

These five constructors each return a new TexCoord2f. The first constructor gen-
erates a TexCoord2f from two floating-point numbers x and y. The second con-
structor generates a TexCoord2f from the first two elements of array v. The third
constructor generates a TexCoord2f from the TexCoord2f v1. The fourth con-
structor generates a TexCoord2f from the Tuple2f t1. The final constructor gen-
erates a TexCoord2f with the value of (0.0, 0.0).

A.1.3 Tuple3b Class

The Tuple3b class is used for colors. This class represents a three-byte tuple.
Note that Java defines a byte as a signed integer in the range [–128, 127]. How-
ever, colors are more typically represented by values in the range [0, 255].
Java 3D recognizes this and, in those cases where Tuple3b is used to represent
color, treats the bytes as if the range were [0, 255]—in other words, as if the
bytes were unsigned. Values greater than 127 can be assigned to a byte variable
using a type cast. For example:
byteVariable = (byte) intValue;// intValue can be > 127

If intValue is greater than 127, then byteVariable will be negative. The correct
value will be extracted when it is used (by masking off the upper bits).

Variables
The component values of a Tuple3b are directly accessible through the public
variables x, y, and z. To access the x (red) component of a Tuple3b called
myColor, a programmer would write myColor.x. The programmer would access
the y (green) and z (blue) components similarly.

Version 1.2, March 2000 375

A.1.3 Tuple3b Class MATH OBJECTS

public byte x
public byte y
public byte z

The red, green, and blue values, respectively.

Constructors

public Tuple3b(byte b1, byte b2, byte b3)

public Tuple3b(byte t[])
public Tuple3b(Tuple3b t1)
public Tuple3b()

These four constructors each return a new Tuple3b. The first constructor gener-
ates a Tuple3b from three bytes b1, b2, and b3. The second constructor generates
a Tuple3b from the first three elements of array t. The third constructor gener-
ates a Tuple3b from the byte-precision Tuple3b t1. The final constructor gener-
ates a Tuple3b with the value of (0.0, 0.0, 0.0).

Methods

public String toString()

This method returns a string that contains the values of this Tuple3b.

public final void set(byte t[])

public final void set(Tuple3b t1)
public final void get(byte t[])
public final void get(Tuple3b t1)

The first set method sets the values of the x, y, and z data members of this
Tuple3b to the values in the array t of length three. The second set method sets
the values of the x, y, and z data members of this Tuple3b to the values in the
argument tuple t1. The first get method places the values of the x, y, and z com-
ponents of this Tuple3b into the array t of length three. The second get method
places the values of the x, y, and z components of this Tuple3b into the tuple t1.
public boolean equals(Tuple3b t1)
public boolean equals(Object t1)

The first method returns true if all of the data members of Tuple3b t1 are equal
to the corresponding data members in this tuple. The second method returns true
if the Object t1 is of type Tuple3b and all of the data members of t1 are equal to
the corresponding data members in this Tuple3b.

376 The Java 3D API Specification

MATH OBJECTS Tuple3d Class A.1.4

public int hashCode()

This method returns a hash number based on the data values in this object. Two
different Tuple3b objects with identical data values (that is, equals(Tuple3b)
returns true) will return the same hash number. Two tuples with different data
members may return the same hash value, although this is not likely.

A.1.3.1 Color3b Class

The Color3b class extends Tuple3b and represents three-byte color values.

Constructors

public Color3b(byte c1, byte c2, byte c3)

public Color3b(byte c[])
public Color3b(Color3b c1)
public Color3b(Tuple3b t1)
public Color3b(Color color) New in 1.2
public Color3b()

These five constructors each return a new Color3b. The first constructor gener-
ates a Color3b from three bytes c1, c2, and c3. The second constructor generates
a Color3b from the first three elements of array c. The third constructor gener-
ates a Color3b from the byte-precision Color3b c1. The fourth constructor gener-
ates a Color3b from the tuple t1. The fifth constructor generates a Color3b from
the specified AWT Color object. The final constructor generates a Color3b with
the value of (0.0, 0.0, 0.0).

Methods

public final void set(Color color) New in 1.2

public final Color get() New in 1.2

The set method sets the R,G,B values of this Color3b object to those of the spec-
ified AWT Color object. The get method returns a new AWT Color object initial-
ized with the R,G,B values of this Color3b object.

A.1.4 Tuple3d Class

The Tuple3d class is a generic three-element tuple represented by double-preci-
sion floating-point x, y, and z coordinates.

Version 1.2, March 2000 377

A.1.4 Tuple3d Class MATH OBJECTS

Variables
The component values of a Tuple3d are directly accessible through the public
variables x, y, and z. To access the x component of a Tuple3d called upperLeft-
Corner, a programmer would write upperLeftCorner.x. The programmer
would access the y and z components similarly.

public double x
public double y
public double z

The x, y, and z coordinates, respectively.

Constructors

public Tuple3d(double x, double y, double z)

public Tuple3d(double t[])
public Tuple3d(Tuple3d t1)
public Tuple3d(Tuple3f t1)
public Tuple3d()

These five constructors each return a new Tuple3d. The first constructor gener-
ates a Tuple3d from three floating-point numbers x, y, and z. The second con-
structor generates a Tuple3d from the first three elements of array t. The third
constructor generates a Tuple3d from the double-precision Tuple3d t1. The
fourth constructor generates a Tuple3d from the single-precision Tuple3f t1. The
final constructor generates a Tuple3d with the value of (0.0, 0.0, 0.0).

Methods

public final void set(double x, double y, double z)

public final void set(double t[])
public final void set(Tuple3d t1)
public final void set(Tuple3f t1)
public final void get(double t[])
public final void get(Tuple3d t)

The four set methods set the value of tuple this to the values specified or to the
values of the specified vectors. The two get methods copy the x, y, and z values
into the array t of length three.

378 The Java 3D API Specification

MATH OBJECTS Tuple3d Class A.1.4

public final void add(Tuple3d t1, Tuple3d t2)

public final void add(Tuple3d t1)
public final void sub(Tuple3d t1, Tuple3d t2)
public final void sub(Tuple3d t1)

The first add method computes the element-by-element sum of tuples t1 and t2
and places the result in this. The second add method computes the ele-
ment-by-element sum of this tuple and tuple t1 and places the result into this.
The first sub method performs an element-by-element subtraction of tuple t2
from tuple t1 and places the result in this (this = t1 – t2). The second sub
method performs an element-by-element subtraction of tuple t1 from this tuple
and places the result in this (this = this – t1).

public final void negate(Tuple3d t1)

public final void negate()

The first negate method sets the values of this tuple to the negative of the values
from tuple t1. The second negate method negates the tuple this and places the
resulting tuple back into this.

public final void scaleAdd(double s, Tuple3f t1)

Deprecated method. See method below.

public final void scale(double s, Tuple3d t1)

public final void scale(double s)
public final void scaleAdd(double s, Tuple3d t1)
public final void scaleAdd(double s, Tuple3d t1, Tuple3d t2)

The first scale method multiplies each element of the tuple t1 by the scale fac-
tor s and places the resulting scaled tuple into this. The second scale method
multiplies each element of this tuple by the scale factor s and places the result-
ing scaled tuple back into this. The first scaleAdd method scales this tuple by
the scale factor s, adds the result to tuple t1, and places the result into tuple this
(this = s*this + t1). The second scaleAdd method scales the tuple t1 by the scale
factor s, adds the result to the tuple t2, and places the result into the tuple this
(this = s*t1 + t2).

public String toString()

This method returns a string that contains the values of this Tuple3d. The form is
(x, y, z).

Version 1.2, March 2000 379

A.1.4 Tuple3d Class MATH OBJECTS

public int hashCode()

This method returns a hash number based on the data values in this object. Two
different Tuple3d objects with identical data values (that is, equals(Tuple3d)
returns true) will return the same hash number. Two tuples with different data
members may return the same hash value, although this is not likely.

public boolean equals(Tuple3d v1)

public boolean equals(Object t1)

The first method returns true if all of the data members of Tuple3d v1 are equal
to the corresponding data members in this Tuple3d. The second method returns
true if the Object t1 is of type Tuple3d and all of the data members of t1 are
equal to the corresponding data members in this Tuple3d.

public boolean epsilonEquals(Tuple3d t1, double epsilon)

This method returns true if the L∞ distance between this tuple and tuple t1 is
less than or equal to the epsilon parameter. Otherwise, this method returns
false. The L∞ distance is equal to

MAX [ abs ( x1 – x2 ), abs ( y1 – y2 ), abs ( z1 – z2 ) ]

public final void absolute()

public final void absolute(Tuple3d t)

The first absolute method sets each component of this tuple to its absolute
value. The second absolute method sets each component of this tuple to the
absolute value of the corresponding component in tuple t.

public final void clamp(float min, float max)

public final void clamp(float min, float max, Tuple3d t)
public final void clampMin(float min)
public final void clampMin(float min, Tuple3d t)
public final void clampMax(float max)
public final void clampMax(float max, Tuple3d t)

Deprecated methods. See the next six methods.

public final void clamp(double min, double max)

public final void clamp(double min, double max, Tuple3d t)
public final void clampMin(double min)
public final void clampMin(double min, Tuple3d t)
public final void clampMax(double max)
public final void clampMax(double max, Tuple3d t)

380 The Java 3D API Specification

MATH OBJECTS Tuple3d Class A.1.4

The first clamp method clamps this tuple to the range [min, max]. The second
clamp method clamps the values from tuple t to the range [min, max] and assigns
these clamped values to this tuple. The first clampMin method clamps each value
of this tuple to the min parameter. The second clampMin method clamps each
value of the tuple t and assigns these clamped values to this tuple. The first
clampMax method clamps each value of this tuple to the max parameter. The sec-
ond clampMax method clamps each value of tuple t to the max parameter and
assigns these clamped values to this tuple. In each method, the values of tuple t
remain unchanged.

public final void interpolate(Tuple3d t1, Tuple3d t2, float alpha)

public final void interpolate(Tuple3d t1, float alpha)

Deprecated methods. See the next two methods.

public final void interpolate(Tuple3d t1, Tuple3d t2, double alpha)

public final void interpolate(Tuple3d t1, double alpha)

The first interpolate method linearly interpolates between tuples t1 and t2 and
places the result into this tuple (this = (1 – alpha) * t1 + alpha * t2). The second
interpolate method linearly interpolates between this tuple and tuple t1 and
places the result into this tuple (this = (1 – alpha) * this + alpha * t1).

A.1.4.1 Point3d Class

The Point3d class extends Tuple3d. The Point3d is a three-element point repre-
sented by double-precision floating-point x, y, and z coordinates.

Constructors

public Point3d(double x, double y, double z)

public Point3d(double p[])
public Point3d(Point3d p1)
public Point3d(Point3f p1)
public Point3d(Tuple3d t1)
public Point3d(Tuple3f t1)
public Point3d()

These seven constructors each return a new Point3d. The first constructor gener-
ates a Point3d from three floating-point numbers x, y, and z. The second con-
structor generates a Point3d from the first three elements of array p. The third
constructor generates a Point3d from the double-precision Point3d p1. The fourth
constructor generates a Point3d from the single-precision Point3f p1. The fifth
and sixth constructors generate a Point3d from the tuple t1. The final constructor
generates a Point3d with the value of (0.0, 0.0, 0.0).
Version 1.2, March 2000 381
A.1.4 Tuple3d Class MATH OBJECTS

Methods

public final double distanceSquared(Point3d p1)

public final double distance(Point3d p1)

The distanceSquared method computes the square of the Euclidean distance

between this Point3d and the Point3d p1 and returns the result. The distance
method computes the Euclidean distance between this Point3d and the Point3d
p1 and returns the result.

public final double distanceL1(Point3d p1)

This method computes the L1 (Manhattan) distance between this point and point
p1. The L1 distance is equal to

abs ( x1 – x2 ) + abs ( y1 – y2 ) + abs ( z1 – z2 )

public final double distanceLinf(Point3d p1)

This method computes the L∞ distance between this point and point p1. The L∞
distance is equal to

MAX [ abs ( x1 – x2 ), abs ( y1 – y2 ), abs ( z1 – z2 ) ]

public final void project(Point4d p1)

This method multiplies each of the x, y, and z components of the Point4d param-
eter p1 by 1/w and places the projected values into this point.

A.1.4.2 Vector3d Class

The Vector3d class extends Tuple3d. The Vector3d is a three-element vector rep-
resented by double-precision floating-point x, y, and z coordinates. If this value
represents a normal, it should be normalized.

Constructors

public Vector3d(double x, double y, double z)

public Vector3d(double v[])
public Vector3d(Vector3d v1)
public Vector3d(Vector3f v1)
public Vector3d(Tuple3d t1)
public Vector3d(Tuple3f t1)
public Vector3d()

382 The Java 3D API Specification

MATH OBJECTS Tuple3f Class A.1.5

These seven constructors each return a new Vector3d. The first constructor gen-
erates a Vector3d from three floating-point numbers x, y, and z. The second con-
structor generates a Vector3d from the first three elements of array v. The third
constructor generates a Vector3d from the double-precision vector v1. The fourth
constructor generates a Vector3d from the single-precision vector v1. The fifth
and sixth constructors generate a Vector3d from the tuple t1. The final construc-
tor generates a Vector3d with the value of (0.0, 0.0, 0.0).

Methods

public final void cross(Vector3d v1, Vector3d v2)

The cross method computes the vector cross-product of vectors v1 and v2 and
places the result in this.

public final void normalize(Vector3d v1)

public final void normalize()

The first normalize method normalizes the vector v1 to unit length and places
the result in this. The second normalize method normalizes the vector this
and places the resulting unit vector back into this.

public final double dot(Vector3d v1)

The dot method returns the dot product of this vector and vector v1.

public final double lengthSquared()

public final double length()

The lengthSquared method returns the squared length of this vector. The
length method returns the length of this vector.

public final double angle(Vector3d v1)

This method returns the angle, in radians, between this vector and the vector v1
parameter. The return value is constrained to the range [0, π].

A.1.5 Tuple3f Class

The Tuple3f class is a generic three-element tuple represented by single-preci-
sion floating-point x, y, and z coordinates.

Variables
The component values of a Tuple3f are directly accessible through the public
variables x, y, and z. To access the x component of a Tuple3f called upperLeft-
Version 1.2, March 2000 383
A.1.5 Tuple3f Class MATH OBJECTS

Corner, a programmer would write upperLeftCorner.x. The programmer

would access the y and z components similarly.

public float x
public float y
public float z

The x, y, and z coordinates, respectively.

Constructors

public Tuple3f(float x, float y, float z)

public Tuple3f(float t[])
public Tuple3f(Tuple3d t1)
public Tuple3f(Tuple3f t1)
public Tuple3f()

These five constructors each return a new Tuple3f. The first constructor generates
a Tuple3f from three floating-point numbers x, y, and z. The second constructor
generates a Tuple3f from the first three elements of array t. The third constructor
generates a Tuple3f from the double-precision Tuple3d t1. The fourth construc-
tor generates a Tuple3f from the single-precision Tuple3f t1. The final construc-
tor generates a Tuple3f with the value of (0.0, 0.0, 0.0).

Methods

public String toString()

This method returns a string that contains the values of this Tuple3f.

public final void set(float x, float y, float z)

public final void set(float t[])
public final void set(Tuple3f t1)
public final void set(Tuple3d t1)
public final void get(float t[])
public final void get(Tuple3f t)

The four set methods set the value of vector this to the coordinates provided or
to the values of the vectors provided. The first get method gets the value of this
vector and copies the values into the array t. The second get method gets the
value of this vector and copies the values into tuple t.

public final void add(Tuple3f t1, Tuple3f t2)

public final void add(Tuple3f t1)
public final void sub(Tuple3f t1, Tuple3f t2)
public final void sub(Tuple3f t1)

384 The Java 3D API Specification

MATH OBJECTS Tuple3f Class A.1.5

The first add method computes the element-by-element sum of tuples t1 and t2,
placing the result in this. The second add method computes the element-by-ele-
ment sum of this and tuple t1 and places the result in this. The first sub
method performs an element-by-element subtraction of tuple t2 from tuple t1
and places the result in this (this = t1 – t2). The second sub method performs an
element-by-element subtraction of tuple t1 from this tuple and places the result
into this (this = this – t1).

public final void negate(Tuple3f t1)

public final void negate()

The first negate method sets the values of this tuple to the negative of the values
from tuple t1. The second negate method negates the vector this and places the
resulting tuple back into this.

public final void scale(float s, Tuple3f t1)

public final void scale(float s)
public final void scaleAdd(float s, Tuple3f t1)
public final void scaleAdd(float s, Tuple3f t1, Tuple3f t2)

The first scale method multiplies each element of the vector t1 by the scale fac-
tor s and places the resulting scaled vector into this. The second scale method
multiples the vector this by the scale factor s and replaces this with the scaled
value. The first scaleAdd method scales this tuple by the scale factor s, adds the
result to tuple t1, and places the result into tuple this (this = s*this + t1). The
second scaleAdd method scales the tuple t1 by the scale factor s, adds the result
to the tuple t2, and places the result into the tuple this (this = s*t1 + t2).

public boolean equals(Tuple3f t1)

public boolean equals(Object t1)

The first method returns true if all of the data members of tuple t1 are equal to
the corresponding data members in this Tuple3f. The second method returns true
if the Object t1 is of type Tuple3f and all of the data members of t1 are equal to
the corresponding data members in this Tuple3f.

public boolean epsilonEquals(Tuple3f t1, float epsilon)

This method returns true if the L∞ distance between this tuple and tuple t1 is
less than or equal to the epsilon parameter. Otherwise, this method returns
false. The L∞ distance is equal to

MAX [ abs ( x1 – x2 ), abs ( y1 – y2 ), abs ( z1 – z2 ) ]

Version 1.2, March 2000 385

A.1.5 Tuple3f Class MATH OBJECTS

public final void absolute()

public final void absolute(Tuple3f t)

The first absolute method sets each component of this tuple to its absolute
value. The second absolute method sets each component of this tuple to the
absolute value of the corresponding component in tuple t.

public final void clamp(float min, float max)

public final void clamp(float min, float max, Tuple3f t)
public final void clampMin(float min)
public final void clampMin(float min, Tuple3f t)
public final void clampMax(float max)
public final void clampMax(float max, Tuple3f t)

The first clamp method clamps this tuple to the range [min, max]. The second
clamp method clamps the values from tuple t to the range [min, max] and assigns
these clamped values to this tuple. The first clampMin method clamps each value
of this tuple to the min parameter. The second clampMin method clamps each
value of the tuple t and assigns these clamped values to this tuple. The first
clampMax method clamps each value of this tuple to the max parameter. The sec-
ond clampMax method clamps each value of tuple t to the max parameter and
assigns these clamped values to this tuple. In each method the values of tuple t
remain unchanged.

public final void interpolate(Tuple3f t1, Tuple3f t2, float alpha)

public final void interpolate(Tuple3f t1, float alpha)

The first method linearly interpolates between tuples t1 and t2 and places the
result into this tuple (this = (1 – alpha) * t1 + alpha * t2). The second method lin-
early interpolates between this tuple and tuple t1 and places the result into this
tuple (this = (1–alpha) * this + alpha * t1).

public int hashCode()

This method returns a hash number based on the data values in this object. Two
different Tuple3f objects with identical data values (that is, equals(Tuple3f)
returns true) will return the same hash number. Two tuples with different data
members may return the same hash value, although this is not likely.

A.1.5.1 Point3f Class

The Point3f class extends Tuple3f. The Point3f is a three-element point repre-
sented by single-precision floating-point x, y, and z coordinates.

386 The Java 3D API Specification

MATH OBJECTS Tuple3f Class A.1.5

Constructors

public Point3f(float x, float y, float z)

public Point3f(float p[])
public Point3f(Point3d p1)
public Point3f(Point3f p1)
public Point3f(Tuple3d t1)
public Point3f(Tuple3f t1)
public Point3f()

These seven constructors each return a new Point3f. The first constructor gener-
ates a point from three floating-point numbers x, y, and z. The second construc-
tor (Point3f(float p[]) generates a point from the first three elements of array
p. The third constructor generates a point from the double-precision point p1.
The fourth constructor generates a point from the single-precision point p1. The
fifth and sixth constructors generate a Point3f from the tuple t1. The final con-
structor generates a point with the value of (0.0, 0.0, 0.0).

Methods

public final float distance(Point3f p1)

public final float distanceSquared(Point3f p1)

The distance method computes the Euclidean distance between this point and
the point p1 and returns the result. The distanceSquared method computes the
square of the Euclidean distance between this point and the point p1 and returns
the result.

public final float distanceL1(Point3f p1)

This method computes the L1 (Manhattan) distance between this point and point
p1. The L1 distance is equal to

abs ( x1 – x2 ) + abs ( y1 – y2 ) + abs ( z1 – z2 )

public final float distanceLinf(Point3f p1)

This method computes the L∞ distance between this point and point p1. The L∞
distance is equal to

MAX [ abs ( x1 – x2 ), abs ( y1 – y2 ), abs ( z1 – z2 ) ]

public final void project(Point4f p1)

This method multiplies each of the x, y, and z components of the Point4f param-
eter p1 by 1/w and places the projected values into this point.
Version 1.2, March 2000 387
A.1.5 Tuple3f Class MATH OBJECTS

A.1.5.2 Vector3f Class

The Vector3f class extends Tuple3f. The Vector3f is a three-element vector rep-
resented by single-precision floating-point x, y, and z coordinates.

Constructors

public Vector3f(float x, float y, float z)

public Vector3f(float v[])
public Vector3f(Vector3d v1)
public Vector3f(Vector3f v1)
public Vector3f(Tuple3d t1)
Public Vector3f(Tuple3f t1)
public Vector3f()

These seven constructors each return a new Vector3f. The first constructor gener-
ates a Vector3f from three floating-point numbers x, y, and z. The second con-
structor generates a Vector3f from the first three elements of array v. The third
constructor generates a Vector3f from the double-precision Vector3d v1. The
fourth constructor generates a Vector3f from the single-precision Vector3f v1.
The fifth and sixth constructors generate a Vector3f from the tuple t1. The final
constructor generates a Vector3f with the value of (0.0, 0.0, 0.0).

Methods

public final float length()

public final float lengthSquared()

The length method computes the length of the vector this and returns its length
as a single-precision floating-point number. The lengthSquared method com-
putes the square of the length of the vector this and returns its length as a sin-
gle-precision floating-point number.

public final void cross(Vector3f v1, Vector3f v2)

The cross method computes the vector cross-product of v1 and v2 and places
the result in this.

public final float dot(Vector3f v1)

The dot method computes the dot product between this vector and the vector v1
and returns the resulting value.

388 The Java 3D API Specification

MATH OBJECTS Tuple3f Class A.1.5

public final void normalize(Vector3f v1)

public final void normalize()

The first normalize method normalizes the vector v1 to unit length and places
the result in this. The second normalize method normalizes the vector this
and places the resulting unit vector back into this.

public final float angle(Vector3f v1)

This method returns the angle, in radians, between this vector and the vector
parameter. The return value is constrained to the range [0, π].

A.1.5.3 TexCoord3f Class

The TexCoord3f class extends Tuple3f. The TexCoord3f is a three-element tex-
ture coordinate represented by single-precision floating-point x, y, and z coordi-
nates.

Constructors

public TexCoord3f(float x, float y, float z)

public TexCoord3f(float v[])
public TexCoord3f(TexCoord3f v1)
public TexCoord3f(Tuple3d t1)
public TexCoord3f(Tuple3f t1)
public TexCoord3f()

These six constructors each return a new TexCoord3f. The first constructor gen-
erates a texture coordinate from three floating-point numbers x, y, and z. The
second constructor generates a texture coordinate from the first three elements of
array v. The third constructor generates a texture coordinate from the single-pre-
cision TexCoord3f v1. The fourth and fifth constructors generate a texture coor-
dinate from tuple t1. The final constructor generates a texture coordinate with
the value of (0.0, 0.0, 0.0).

A.1.5.4 Color3f Class

The Color3f class extends Tuple3f. The Color3f is a three-element color value
represented by single-precision floating-point x, y, and z values. The x, y, and z
values represent the red, blue, and green color values, respectively. Color compo-
nents should be in the range [0.0, 1.0].

Version 1.2, March 2000 389

A.1.6 Tuple3i Class MATH OBJECTS

Constructors

public Color3f(float x, float y, float z)

public Color3f(float v[])
public Color3f(Color3f v1)
public Color3f(Tuple3d t1)
public Color3f(Tuple3f t1)
public Color3f(Color color) New in 1.2
public Color3f()

These six constructors each return a new Color3f. The first constructor generates
a Color3f from three floating-point numbers x, y, and z. The second constructor
(Color3f(float v[]) generates a Color3f from the first three elements of array
v. The third constructor generates a Color3f from the single-precision color v1.
The fourth and fifth constructors generate a Color3f from the tuple t1. The sixth
constructor generates a Color3f from the specified AWT Color object. The final
constructor generates a Color3f with the value of (0.0, 0.0, 0.0).

Methods

public final void set(Color color) New in 1.2

public final Color get() New in 1.2

The set method sets the R,G,B values of this Color3f object to those of the spec-
ified AWT Color object. The get method returns a new AWT Color object initial-
ized with the R,G,B values of this Color3f object.

A.1.6 Tuple3i Class New in 1.2

The Tuple3i class is a generic three-element tuple represented by signed integer

x,y,z coordinates.

Variables
The component values of a Tuple3i are directly accessible through the public
variables x, y, and z. To access the x component of a Tuple3i called upperLeft-
Corner, a programmer would write upperLeftCorner.x. The programmer
would access the y and z components similarly.

public int x New in 1.2

public int y New in 1.2
public int z New in 1.2

The x, y, and z coordinates, respectively.

390 The Java 3D API Specification

MATH OBJECTS Tuple3i Class A.1.6

Constructors

public Tuple3i(int x, int y, int z) New in 1.2

public Tuple3i(int[] t) New in 1.2
public Tuple3i(Tuple3i t1) New in 1.2
public Tuple3i() New in 1.2

These four constructors each return a new Tuple3i. The first constructor gener-
ates a Tuple3i from the specified x, y, and z coordinates. The second constructor
generates a Tuple3i from the array of length 3. The third constructor generates a
Tuple3i from the specified Tuple3i. The final constructor generates a Tuple3i
with the value of (0,0,0).

Methods

public String toString() New in 1.2

This method returns a string that contains the values of this Tuple3i.

public final void set(int x, int y, int z) New in 1.2

public final void set(int[] t) New in 1.2
public final void set(Tuple3i t1) New in 1.2
public final void get(int[] t) New in 1.2
public final void get(Tuple3i t) New in 1.2

The first set method sets the value of this tuple to the specified x, y, and z coor-
dinates. The second set method sets the value of this tuple to the specified coor-
dinates in the array of length 3. The third set method sets the value of this tuple
to the value of tuple t1. The first get method copies the values of this tuple into
the array t. The second get method copies the values of this tuple into the tuple t.

public final void add(Tuple3i t1, Tuple3i t2) New in 1.2

public final void add(Tuple3i t1) New in 1.2

The first method sets the value of this tuple to the sum of tuples t1 and t2. The
second method sets the value of this tuple to the sum of itself and t1.

public final void sub(Tuple3i t1, Tuple3i t2) New in 1.2

public final void sub(Tuple3i t1) New in 1.2

The first method sets the value of this tuple to the difference of tuples t1 and t2
(this = t1 – t2). The second method sets the value of this tuple to the difference
of itself and t1 (this = this – t1).

Version 1.2, March 2000 391

A.1.6 Tuple3i Class MATH OBJECTS

public final void negate(Tuple3i t1) New in 1.2

public final void negate() New in 1.2

The first method sets the value of this tuple to the negation of tuple t1. The sec-
ond method negates the value of this tuple in place.

public final void scale(int s, Tuple3i t1) New in 1.2

public final void scale(int s) New in 1.2

The first method sets the value of this tuple to the scalar multiplication of tuple
t1. The second method sets he value of this tuple to the scalar multiplication of
the scale factor with this.

public final void scaleAdd(int s, Tuple3i t1, Tuple3i t2) New in 1.2
public final void scaleAdd(int s, Tuple3i t1) New in 1.2

The first method sets the value of this tuple to the scalar multiplication of tuple
t1 plus tuple t2 (this = s*t1 + t2). The second method sets the value of this tuple
to the scalar multiplication of itself and then adds tuple t1 (this = s*this + t1).

public boolean equals(Object t1) New in 1.2

This method returns true if the Object t1 is of type Tuple3i and all of the data
members of t1 are equal to the corresponding data members in this Tuple3i.

public final void clamp(int min, int max, Tuple3i t) New in 1.2
public final void clamp(int min, int max) New in 1.2

The first method clamps the tuple parameter to the range [low, high] and places
the values into this tuple. The second method clamps this tuple to the range [low,
high].
public final void clampMin(int min, Tuple3i t) New in 1.2
public final void clampMin(int min) New in 1.2
public final void clampMax(int max, Tuple3i t) New in 1.2
public final void clampMax(int max) New in 1.2

The first method clamps the minimum value of the tuple parameter to the min
parameter and places the values into this tuple. The second method clamps the
minimum value of this tuple to the min parameter. The third method clamps the
maximum value of the tuple parameter to the max parameter and places the val-
ues into this tuple. The final method clamps the maximum value of this tuple to
the max parameter.

392 The Java 3D API Specification

MATH OBJECTS Tuple4b Class A.1.7

public final void absolute(Tuple3i t) New in 1.2

public final void absolute() New in 1.2

The first method sets each component of the tuple parameter to its absolute value
and places the modified values into this tuple. The second method sets each com-
ponent of this tuple to its absolute value.

public int hashCode() New in 1.2

This method returns a hash code value based on the data values in this object.
Two different Tuple3i objects with identical data values (i.e., Tuple3i.equals
returns true) will return the same hash code value. Two objects with different
data members may return the same hash value, although this is not likely.

A.1.6.1 Point3i Class New in 1.2

The Point3i class extends Tuple3i. The Point3i is a three-element point repre-
sented by signed integer x,y,z coordinates.

Constructors

public Point3i(int x, int y, int z) New in 1.2

public Point3i(int[] t) New in 1.2
public Point3i(Tuple3i t1 New in 1.2
public Point3i() New in 1.2

These four constructors each return a new Point3i. The first constructor generates
a Point3i from the specified x, y, and z coordinates. The second constructor gen-
erates a Point3i from the array of length 3. The third constructor generates a
Point3i from the specified Tuple3i. The final constructor generates a Point3i with
the value of (0,0,0).

A.1.7 Tuple4b Class

The Tuple4b class represents four-byte tuples. Note that Java defines a byte as a
signed integer in the range [–128, 127]. However, colors are more typically rep-
resented by values in the range [0, 255]. Java 3D recognizes this and, in those
cases where Tuple4b is used to represent color, treats the bytes as if the range
were [0, 255]—in other words, as if the bytes were unsigned. Values greater than
127 can be assigned to a byte variable using a type cast. For example:
byteVariable = (byte) intValue;// intValue can be > 127

If intValue is greater than 127, then byteVariable will be negative. The correct
value will be extracted when it is used (by masking off the upper bits).

Version 1.2, March 2000 393

A.1.7 Tuple4b Class MATH OBJECTS

Variables
The component values of a Tuple4b are directly accessible through the public
variables x, y, z, and w. The x, y, z, and w values represent the red, green, blue,
and alpha values, respectively. To access the x (red) component of a Tuple4b
called backgroundColor, a programmer would write backgroundColor.x. The
programmer would access the y (green), z (blue), and w (alpha) components sim-
ilarly.

public byte x
public byte y
public byte z
public byte w

The red, green, blue, and alpha values, respectively.

Constructors

public Tuple4b(byte b1, byte b2, byte b3, byte b4)

public Tuple4b(byte t[])
public Tuple4b(Tuple4b t1)
public Tuple4b()

These four constructors each return a new Tuple4b. The first constructor gener-
ates a Tuple4b from four bytes b1, b2, b3, and b4. The second constructor
(Tuple4b(byte t[]) generates a Tuple4b from the first four elements of array t.
The third constructor generates a Tuple4b from the byte-precision Tuple4b t1.
The final constructor generates a Tuple4b with the value of (0.0, 0.0, 0.0, 0.0).

Methods

public String toString()

This method returns a string that contains the values of this Tuple4b.

public final void set(byte b[])

public final void set(Tuple4b t1)
public final void get(byte b[])
public final void get(Tuple4b t1)

The first set method sets the value of the data members of this Tuple4b to the
value of the array b. The second set method sets the value of the data members
of this Tuple4b to the value of the argument tuple t1. The first get method
places the values of the x, y, z, and w components of this Tuple4b into the byte

394 The Java 3D API Specification

MATH OBJECTS Tuple4b Class A.1.7

array b. The second get method places the values of the x, y, z, and w compo-
nents of this Tuple4b into the Tuple4b t1.

public boolean equals(Tuple4b t1)

public boolean equals(Object t1)

The first method returns true if all of the data members of Tuple4b t1 are equal
to the corresponding data members in this Tuple4b. The second method returns
true if the Object t1 is of type Tuple4b and all of the data members of t1 are
equal to the corresponding data members in this Tuple4b.

public int hashCode()

This method returns a hash number based on the data values in this object. Two
different Tuple4b objects with identical data values (that is, equals(Tuple4b)
returns true) will return the same hash number. Two Tuple4b objects with differ-
ent data members may return the same hash value, although this is not likely.

A.1.7.1 Color4b Class

The Color4b class extends Tuple4b. The Color4b is a four-byte color value (red,
green, blue, and alpha).

Constructors

public Color4b(byte b1, byte b2, byte b3, byte b4)

public Color4b(byte c[])
public Color4b(Color4b c1)
public Color4b(Tuple4b t1)
public Color4b(Color color) New in 1.2
public Color4b()

These five constructors each return a new Color4b. The first constructor gener-
ates a Color4b from four bytes b1, b2, b3, and b4. The second constructor gener-
ates a Color4b from the first four elements of byte array c. The third constructor
generates a Color4b from the byte-precision Color4b c1. The fourth constructor
generates a Color4b from the tuple t1. The fifth constructor generates a Color4b
from the specified AWT Color object. The final constructor generates a Color4b
with the value of (0.0, 0.0, 0.0, 0.0).

Methods

public final void set(Color color) New in 1.2

public final Color get() New in 1.2

Version 1.2, March 2000 395

A.1.8 Tuple4d Class MATH OBJECTS

The set method sets the R,G,B,A values of this Color4b object to those of the
specified AWT Color object. The get method returns a new AWT Color object
initialized with the R,G,B,A values of this Color4b object.

A.1.8 Tuple4d Class

The Tuple4d class represents a four-element tuple represented by double-preci-
sion floating-point x, y, z, and w coordinates.

Variables
The component values of a Tuple4d are directly accessible through the public
variables x, y, z, and w. To access the x component of a Tuple4d called upper-
LeftCorner, a programmer would write upperLeftCorner.x. The programmer
would access the y, z, and w components similarly.

public double x
public double y
public double z
public double w

The x, y, z, and w coordinates, respectively.

Constructors

public Tuple4d(double x, double y, double z, double w)

public Tuple4d(double t[])
public Tuple4d(Tuple4d t1)
public Tuple4d(Tuple4f t1)
public Tuple4d()

These five constructors each return a new Tuple4d. The first constructor gener-
ates a Tuple4d from four floating-point numbers x, y, z, and w. The second con-
structor (Tuple4d(double t[]) generates a Tuple4d from the first four elements
of array t. The third constructor generates a Tuple4d from the double-precision
tuple t1. The fourth constructor generates a Tuple4d from the single-precision
tuple t1. The final constructor generates a Tuple4d with the value of (0.0, 0.0,
0.0, 0.0).

Methods

public final void set(double x, double y, double z, double w)

public final void set(double t[])
public final void set(Tuple4d t1)

396 The Java 3D API Specification

MATH OBJECTS Tuple4d Class A.1.8

public final void set(Tuple4f t1)

public final void get(double t[])
public final void get(Tuple4d t)

These methods set the value of the tuple this to the values specified or to the
values of the specified tuples. The first get method retrieves the value of this
tuple and places it into the array t of length four, in x, y, z, w order. The second
get method retrieves the value of this tuple and places it into tuple t.

public final void add(Tuple4d t1, Tuple4d t2)

public final void add(Tuple4d t1)
public final void sub(Tuple4d t1, Tuple4d t2)
public final void sub(Tuple4d t1)

The first add method computes the element-by-element sum of the tuple t1 and
the tuple t2, placing the result in this. The second add method computes the
element-by-element sum of this tuple and the tuple t1 and places the result in
this. The first sub method performs an element-by-element subtraction of tuple
t2 from tuple t1 and places the result in this. The second sub method performs
an element-by-element subtraction of tuple t1 from this tuple and places the
result in this.

public final void negate(Tuple4d t1)

public final void negate()

The first negate method sets the values of this tuple to the negative of the values
from tuple t1. The second negate method negates the tuple this and places the
resulting tuple back into this.

public final void scaleAdd(float s, Tuple4d t1)

Deprecated method. See method below.

public final void scale(double s, Tuple4d t1)

public final void scale(double s)
public final void scaleAdd(double s, Tuple4d t1)
public final void scaleAdd(double s, Tuple4d t1, Tuple4d t2)

The first scale method multiplies each element of the tuple t1 by the scale fac-
tor s and places the resulting scaled tuple into this. The second scale method
multiples the tuple this by the scale factor s and replaces this with the scaled
value. The first scaleAdd method scales this tuple by the scale factor s, adds the
result to tuple t1, and places the result into tuple this (this = s*this + t1). The
second scaleAdd method scales the tuple t1 by the scale factor s, adds the result
to the tuple t2, and places the result into the tuple this (this = s*t1 + t2).

Version 1.2, March 2000 397

A.1.8 Tuple4d Class MATH OBJECTS

public void interpolate(Tuple4d t1, Tuple4d t2, float alpha)

public void interpolate(Tuple4d t1, float alpha)

Deprecated methods. See the next two methods.

public void interpolate(Tuple4d t1, Tuple4d t2, double alpha)

public void interpolate(Tuple4d t1, double alpha)

The first interpolate method linearly interpolates between tuples t1 and t2 and
places the result into this tuple (this = (1 – alpha) * t1 + alpha * t2). The second
interpolate method linearly interpolates between this tuple and tuple t1 and
places the result into this tuple (this = (1 – alpha) * this + alpha * t1).

public String toString()

This method returns a string that contains the values of this tuple. The form is
(x, y, z, w).

public boolean equals(Tuple4d v1)

public boolean equals(Object t1)

The first method returns true if all of the data members of tuple v1 are equal to
the corresponding data members in this tuple. The second method returns true if
the Object t1 is of type Tuple4d and all of the data members of t1 are equal to
the corresponding data members in this Tuple4d.

public boolean epsilonEquals(Tuple4d t1, double epsilon)

This method returns true if the L∞ distance between this Tuple4d and Tuple4d
t1 is less than or equal to the epsilon parameter. Otherwise, this method returns
false. The L∞ distance is equal to

MAX [ abs ( x1 – x2 ), abs ( y1 – y2 ), abs ( z1 – z2 ), abs ( w1 – w2 ) ]

public final void absolute()

public final void absolute(Tuple4d t)

The first absolute method sets each component of this tuple to its absolute
value. The second absolute method sets each component of this tuple to the
absolute value of the corresponding component in tuple t.

public final void clamp(float min, float max)

public final void clamp(float min, float max, Tuple4d t)
public final void clampMin(float min)
public final void clampMin(float min, Tuple4d t)

398 The Java 3D API Specification

MATH OBJECTS Tuple4d Class A.1.8

public final void clampMax(float max)

public final void clampMax(float max, Tuple4d t)

Deprecated methods. See the next six methods.

public final void clamp(double min, double max)

public final void clamp(double min, double max, Tuple4d t)
public final void clampMin(double min)
public final void clampMin(double min, Tuple4d t)
public final void clampMax(double max)
public final void clampMax(double max, Tuple4d t)

The first clamp method clamps this tuple to the range [min, max]. The second
clamp method clamps this tuple to the range [min, max] and places the values
into tuple t. The first clampMin method clamps the minimum value of this tuple
to the min parameter. The second clampMin method clamps the minimum value
of this tuple to the min parameter and places the values into the tuple t. The first
clampMax method clamps the maximum value of this tuple to the max parameter.
The second clampMax method clamps the maximum value of this tuple to the max
parameter and places the values into the tuple t.

public int hashCode()

This method returns a hash number based on the data values in this object. Two
different Tuple4d objects with identical data values (that is, equals(Tuple4d)
returns true) will return the same hash number. Two Tuple4d objects with differ-
ent data members may return the same hash value, although this is not likely.

A.1.8.1 Point4d Class

The Point4d class extends Tuple4d. The Point4d is a four-element point repre-
sented by double-precision floating-point x, y, z, and w coordinates.

Constructors

public Point4d(double x, double y, double z, double w)

public Point4d(double p[])
public Point4d(Point4d p1)
public Point4d(Point4f p1)
public Point4d(Tuple4d t1)
public Point4d(Tuple4f t1)
public Point4d(Tuple3d t1) New in 1.2
public Point4d()

These eight constructors each return a new Point4d. The first constructor gener-
ates a Point4d from four floating-point numbers x, y, z, and w. The second con-
Version 1.2, March 2000 399
A.1.8 Tuple4d Class MATH OBJECTS

structor (Point4d(double p[]) generates a Point4d from the first four elements
of array p. The third constructor generates a Point4d from the double-precision
point p1. The fourth constructor generates a Point4d from the single-precision
point p1. The fifth and sixth constructors generate a Point4d from tuple t1. The
seventh constructor generates a Point4d from the specified Tuple3d – the w com-
ponent of this point is set to 1. The final constructor generates a Point4d with the
value of (0.0, 0.0, 0.0, 0.0).

Methods

public final void set(Tuple3d t1) New in 1.2

This method sets the x,y,z components of this point to the corresponding compo-
nents of tuple t1. The w component of this point is set to 1.

public final double distance(Point4d p1)

public final double distanceSquared(Point4d p1)

The distance method computes the Euclidean distance between this point and
the point p1 and returns the result. The distanceSquared method computes the
square of the Euclidean distance between this point and the point p1 and returns
the result.

public final double distanceL1(Point4d p1)

This method computes the L1 (Manhattan) distance between this point and point
p1. The L1 distance is equal to

abs ( x1 – x2 ) + abs ( y1 – y2 ) + abs ( z1 – z2 ) + abs ( w1 – w2 )

public final double distanceLinf(Point4d p1)

This method computes the L∞ distance between this point and point p1. The L∞
distance is equal to

MAX [ abs ( x1 – x2 ), abs ( y1 – y2 ), abs ( z1 – z2 ), abs ( w1 – w2 ) ]

public final void project(Point4d p1)

This method multiplies each of the x, y, and z components of the point p1 by

1 ⁄ w , places the projected values into this point, and places a 1 into the w param-
eter of this point.

400 The Java 3D API Specification

MATH OBJECTS Tuple4d Class A.1.8

A.1.8.2 Vector4d Class

The Vector4d class extends Tuple4d. The Vector4d is a four-element vector rep-
resented by double-precision floating-point x, y, z, and w coordinates.

Constructors

public Vector4d(double x, double y, double z, double w)

public Vector4d(double v[])
public Vector4d(Vector4d v1)
public Vector4d(Vector4f v1)
public Vector4d(Tuple4d t1)
public Vector4d(Tuple4f t1)
public Vector4d(Tuple3d t1) New in 1.2
public Vector4d()

These eight constructors each return a new Vector4d. The first constructor gener-
ates a Vector4d from four floating-point numbers x, y, z, and w. The second con-
structor generates a Vector4d from the first four elements of array v. The third
constructor generates a Vector4d from the double-precision Vector4d v1. The
fourth constructor generates a Vector4d from the single-precision Vector4f v1.
The fifth and sixth constructors generate a Vector4d from tuple t1. The seventh
constructor generates a Vector4d from the specified Tuple3d – the w component
of this vector is set to 0. The final constructor generates a Vector4d with the
value of (0.0, 0.0, 0.0, 0.0).

Methods

public final void set(Tuple3d t1) New in 1.2

This method sets the x,y,z components of this vector to the corresponding com-
ponents of tuple t1. The w component of this vector is set to 0.

public final double length()

public final double lengthSquared()

The length method computes the length of the vector this and returns its length
as a double-precision floating-point number. The lengthSquared method com-
putes the square of the length of the vector this and returns its length as a dou-
ble-precision floating-point number.

public final void dot(Vector4d v1)

This method returns the dot product of this vector and vector v1.

Version 1.2, March 2000 401

A.1.8 Tuple4d Class MATH OBJECTS

public final void normalize(Vector4d v1)

public final void normalize()

The first normalize method normalizes the vector v1 to unit length and places
the result in this. The second normalize method normalizes the vector this
and places the resulting unit vector back into this.

public final double angle(Vector4d v1)

This method returns the (four-space) angle, in radians, between this vector and
the vector v1 parameter. The return value is constrained to the range [0, π].

A.1.8.3 Quat4d Class

The Quat4d class extends Tuple4d. The Quat4d is a four-element quaternion rep-
resented by double-precision floating-point x, y, z, and w values.

Constructors

public Quat4d(double x, double y, double z, double w)

public Quat4d(double q[])
public Quat4d(Quat4d q1)
public Quat4d(Quat4f q1)
public Quat4d(Tuple4d t1)
public Quat4d(Tuple4f t1)
public Quat4d()

These seven constructors each return a new Quat4d. The first constructor gener-
ates a quaternion from four floating-point numbers x, y, z, and w. The second
constructor generates a quaternion from the first four elements of array q of
length four. The third constructor generates a quaternion from the double-preci-
sion quaternion q1. The fourth constructor generates a quaternion from the sin-
gle-precision quaternion q1. The fifth and sixth constructors generate a Quat4d
from tuple t1. The final constructor generates a quaternion with the value of
(0.0, 0.0, 0.0, 0.0).

Methods

public final void conjugate(Quat4d q1)

public final void conjugate()

The first conjugate method sets the values of this quaternion to the conjugate of
quaternion q1. The second conjugate method negates the value of each of this
quaternion’s x, y, and z coordinates in place.

402 The Java 3D API Specification

MATH OBJECTS Tuple4d Class A.1.8

public final void mul(Quat4d q1, Quat4d q2)

public final void mul(Quat4d q1)

The first mul method sets the value of this quaternion to the quaternion product
of quaternions q1 and q2 (this = q1 * q2). Note that this is safe for aliasing (that
is, this can be q1 or q2). The second mul method sets the value of this quater-
nion to the quaternion products of itself and q1 (this = this * q1).

public final void mulInverse(Quat4d q1, Quat4d q2)

public final void mulInverse(Quat4d q1)

The first mulInverse method multiplies quaternion q1 by the inverse of

quaternion q2 and places the value into this quaternion. The values of both
quaternion arguments are preserved (this = q1 * q2–1). The second mulInverse
method multiplies this quaternion by the inverse of quaternion q1 and places the
value into this quaternion. The value of the argument q1 is preserved (this =
this * q1–1).

public final void inverse(Quat4d q1)

public final void inverse()

The first inverse method sets the value of this quaternion to the quaternion
inverse of quaternion q1. The second inverse method sets the value of this
quaternion to the quaternion inverse of itself.

public final void normalize(Quat4d q1)

public final void normalize()

The first normalize method sets the value of this quaternion to the normalized
value of quaternion q1. The second normalize method normalizes the value of
this quaternion in place.

public final void set(Matrix4f m1)

public final void set(Matrix4d m1)
public final void set(Matrix3f m1)
public final void set(Matrix3d m1)
public final void set(AxisAngle4f a)
public final void set(AxisAngle4d a)

These set methods set the value of this quaternion to the rotational component
of the passed matrix.

public final void interpolate(Quat4d q1, double alpha)

public final void interpolate(Quat4d q1, Quat4d q2, double alpha)

Version 1.2, March 2000 403

A.1.9 Tuple4f Class MATH OBJECTS

The first method performs a great circle interpolation between this quaternion
and the quaternion parameter and places the result into this quaternion. The sec-
ond method performs a great circle interpolation between quaternion q1 and
quaternion q2 and places the result into this quaternion.

A.1.9 Tuple4f Class

The Tuple4f class represents a four-element tuple represented by single-precision
floating-point x, y, z, and w values.

Variables
The component values of a Tuple4f are directly accessible through the public
variables x, y, z, and w. To access the x component of a Tuple4f called upper-
LeftCorner, a programmer would write upperLeftCorner.x. The programmer
would access the y, z, and w components similarly.

public double x
public double y
public double z
public double w

The x, y, z, and w values, respectively.

Constructors

public Tuple4f(float x, float y, float z, float w)

public Tuple4f(float t[])
public Tuple4f(Tuple4d t1)
public Tuple4f(Tuple4f t1)
public Tuple4f()

These five constructors each return a new Tuple4f. The first constructor generates
a Tuple4f from four floating-point numbers x, y, z, and w. The second constructor
(Tuple4f(float t[]) generates a Tuple4f from the first four elements of array
t. The third constructor generates a Tuple4f from the double-precision tuple t1.
The fourth constructor generates a Tuple4f from the single-precision tuple t1.
The final constructor generates a Tuple4f with the value of (0.0, 0.0, 0.0, 0.0).

Methods

public final void set(float x, float y, float z, float w)

public final void set(float t[])
public final void set(Tuple4f t1)

404 The Java 3D API Specification

MATH OBJECTS Tuple4f Class A.1.9

public final void set(Tuple4d t1)

public final void get(float t[])
public final void get(Tuple4f t)

The first set method sets the value of this tuple to the specified x, y, z, and w val-
ues. The second set method sets the value of this tuple to the specified coordi-
nates in the array. The next two methods set the value of tuple this to the value
of tuple t1. The get methods copy the value of this tuple into the tuple t.

public final void add(Tuple4f t1, Tuple4f t2)

public final void add(Tuple4f t1)
public final void sub(Tuple4f t1, Tuple4f t2)
public final void sub(Tuple4f t1)

The first add method computes the element-by-element sum of tuples t1 and t2
and places the result in this. The second add method computes the ele-
ment-by-element sum of this tuple and tuple t1 and places the result in this.
The first sub method performs the element-by-element subtraction of tuple t2
from tuple t1 and places the result in this (this = t1 – t2). The second sub
method performs the element-by-element subtraction of tuple t1 from this tuple
and places the result in this (this = this – t1).

public final void negate(Tuple4f t1)

public final void negate()

The first negate method sets the values of this tuple to the negative of the values
from tuple t1. The second negate method negates the tuple this and places the
resulting tuple back into this.

public final void scale(float s, Tuple4f t1)

public final void scale(float s)
public final void scaleAdd(float s, Tuple4f t1)
public final void scaleAdd(float s, Tuple4f t1, Tuple4f t2)

The first scale method multiplies each element of the tuple t1 by the scale fac-
tor s and places the resulting scaled tuple into this. The second scale method
multiples the tuple this by the scale factor s, replacing this with the scaled
value. The first scaleAdd method scales this tuple by the scale factor s, adds the
result to tuple t1, and places the result into tuple this (this = s*this + t1). The
second scaleAdd method scales the tuple t1 by the scale factor s, adds the result
to the tuple t2, and places the result into the tuple this (this = s*t1 + t2).

Version 1.2, March 2000 405

A.1.9 Tuple4f Class MATH OBJECTS

public String toString()

This method returns a string that contains the values of this Tuple4f. The form is
(x, y, z, w).

public boolean equals(Tuple4f t1)

public boolean equals(Object t1)

The first method returns true if all of the data members of Tuple4f t1 are equal
to the corresponding data members in this Tuple4f. The second method returns
true if the Object t1 is of type Tuple4f and all of the data members of t1 are
equal to the corresponding data members in this Tuple4f.

public boolean epsilonEquals(Tuple4f t1, float epsilon)

This method returns true if the L∞ distance between this Tuple4f and Tuple4f t1
is less than or equal to the epsilon parameter. Otherwise, this method returns
false. The L∞ distance is equal to

MAX [ abs ( x1 – x2 ), abs ( y1 – y2 ), abs ( z1 – z2 ), abs ( w1 – w2 ) ]

public final void absolute()

public final void absolute(Tuple4f t)

The first absolute method sets each component of this tuple to its absolute
value. The second absolute method sets each component of this tuple to the
absolute value of the corresponding component in tuple t.

public final void clamp(float min, float max)

public final void clamp(float min, float max, Tuple4f t)
public final void clampMin(float min)
public final void clampMin(float min, Tuple4f t)
public final void clampMax(float max)
public final void clampMax(float max, Tuple4f t)

The first clamp method clamps this tuple to the range [min, max]. The second
clamp method clamps this tuple to the range [min, max] and places the values
into tuple t. The first clampMin method clamps the minimum value of this tuple
to the min parameter. The second clampMin method clamps the minimum value
of this tuple to the min parameter and places the values into the tuple t. The first
clampMax method clamps the maximum value of this tuple to the max parameter.
The second clampMax method clamps the maximum value of this tuple to the max
parameter and places the values into the tuple t.

public void interpolate(Tuple4f t1, Tuple4f t2, float alpha)

public void interpolate(Tuple4f t1, float alpha)

406 The Java 3D API Specification

MATH OBJECTS Tuple4f Class A.1.9

The first interpolate method linearly interpolates between tuples t1 and t2 and
places the result into this tuple (this = (1 – alpha) * t1 + alpha * t2). The second
interpolate method linearly interpolates between this tuple and tuple t1 and
places the result into this tuple (this = (1 – alpha) * this + alpha * t1).

public int hashCode()

This method returns a hash number based on the data values in this object. Two
different Tuple4f objects with identical data values (that is, equals(Tuple4f)
returns true) will return the same hash number. Two Tuple4f objects with differ-
ent data members may return the same hash value, although this is not likely.

A.1.9.1 Point4f Class

The Point4f class extends Tuple4f. The Point4f is a four-element point repre-
sented by single-precision floating-point x, y, z, and w coordinates.

Constructors

public Point4f(float x, float y, float z, float w)

public Point4f(float p[])
public Point4f(Point4d p1)
public Point4f(Point4f p1)
public Point4f(Tuple4d t1)
public Point4f(Tuple4f t1)
public Point4f(Tuple3f t1) New in 1.2
public Point4f()

These eight constructors each return a new Point4f. The first constructor gener-
ates a Point4f from four floating-point numbers x, y, z, and w. The second con-
structor (Point4f(float p[]) generates a Point4f from the first four elements of
array p. The third constructor generates a Point4f from the double-precision
point p1. The fourth constructor generates a Point4f from the single-precision
point p1. The fifth and sixth constructors generate a Point4f from tuple t1. The
seventh constructor generates a Point4f from the specified Tuple3f – The w com-
ponent of this point is set to 1. The final constructor generates a Point4f with the
value of (0.0, 0.0, 0.0, 0.0).

Methods

public final void set(Tuple3f t1) New in 1.2

This method sets the x,y,z components of this point to the corresponding compo-
nents of tuple t1. The w component of this point is set to 1.

Version 1.2, March 2000 407

A.1.9 Tuple4f Class MATH OBJECTS

public final float distanceSquared(Point4f p1)

public final float distance(Point4f p1)

The distanceSquared method computes the square of the Euclidean distance

between this point and the point p1 and returns the result. The distance method
computes the Euclidean distance between this point and the point p1 and returns
the result.

public final float distanceL1(Point4f p1)

This method computes the L1 (Manhattan) distance between this point and point
p1. The L1 distance is equal to

abs ( x1 – x2 ) + abs ( y1 – y2 ) + abs ( z1 – z2 ) + abs ( w1 – w2 )

public final float distanceLinf(Point4f p1)

This method computes the L∞ distance between this point and point p1. The L∞
distance is equal to

MAX [ abs ( x1 – x2 ), abs ( y1 – y2 ), abs ( z1 – z2 ), abs ( w1 – w2 ) ]

public final void project(Point4f p1)

This method multiplies each of the x, y, and z components of the point p1 by

1 ⁄ w , places the projected values into this point, and places a 1 into the w param-
eter of this point.

A.1.9.2 Color4f Class

The Color4f class extends Tuple4f. The Color4f is a four-element color value
represented by single-precision floating-point x, y, z, and w values. The x, y, z,
and w values represent the red, blue, green, and alpha color values, respectively.
Color and alpha components should be in the range [0.0, 1.0].

Constructors

public Color4f(float x, float y, float z, float w)

public Color4f(float c[])
public Color4f(Color4f c1)
public Color4f(Tuple4d t1)
public Color4f(Tuple4f t1)
public Color4f(Color color) New in 1.2
public Color4f()

408 The Java 3D API Specification

MATH OBJECTS Tuple4f Class A.1.9

These seven constructors each return a new Color4f. The first constructor gener-
ates a Color4f from four floating-point numbers x, y, z, and w. The second con-
structor generates a Color4f from the first four elements of array c. The third
constructor generates a Color4f from the single-precision color c1. The fourth
and fifth constructors generate a Color4f from tuple t1. The sixth constructor
generates a Color4f from the specified AWT Color object. The final constructor
generates a Color4f with the value of (0.0, 0.0, 0.0, 0.0).

Methods

public final void set(Color color) New in 1.2

public final Color get() New in 1.2

The set method sets the R,G,B,A values of this Color4f object to those of the
specified AWT Color object. The get method returns a new AWT Color object
initialized with the R,G,B,A values of this Color4f object.

A.1.9.3 Vector4f Class

The Vector4f class extends Tuple4f. The Vector4f is a four-element vector repre-
sented by single-precision floating-point x, y, z, and w coordinates.

Constructors

public Vector4f(float x, float y, float z, float w)

public Vector4f(float v[])
public Vector4f(Vector4d v1)
public Vector4f(Vector4f v1)
public Vector4f(Tuple4d t1)
public Vector4f(Tuple4f t1)
public Vector4f(Tuple3f t1) New in 1.2
public Vector4f()

These eight constructors each return a new Vector4f. The first constructor gener-
ates a Vector4f from four floating-point numbers x, y, z, and w. The second con-
structor generates a Vector4f from the first four elements of array v. The third
constructor generates a Vector4f from the double-precision Vector4d v1. The
fourth constructor generates a Vector4f from the single-precision Vector4f v1.
The fifth and sixth constructors generate a Vector4f from tuple t1. The seventh
constructor generates a Vector4f from the specified Tuple3f – the w component
of this vector is set to 0. The final constructor generates a Vector4f with the value
of (0.0, 0.0, 0.0, 0.0).

Version 1.2, March 2000 409

A.1.9 Tuple4f Class MATH OBJECTS

Methods

public final void set(Tuple3f t1) New in 1.2

This method sets the x,y,z components of this vector to the corresponding com-
ponents of tuple t1. The w component of this vector is set to 0.

public final float length()

public final float lengthSquared()

The length method computes the length of the vector this and returns its length
as a single-precision floating-point number. The lengthSquared method com-
putes the square of the length of the vector this and returns its length as a sin-
gle-precision floating-point number.

public final float dot(Vector4f v1)

The dot method computes the dot product between this vector and the vector v1
and returns the resulting value.

public final void normalize(Vector4f v1)

public final void normalize()

The first normalize method sets the value of this vector to the normalization of
vector v1. The second normalize method normalizes this vector in place.

public final float angle(Vector4f v1)

This method returns the (four-space) angle, in radians, between this vector and
the vector v1 parameter. The return value is constrained to the range [0, π].

A.1.9.4 Quat4f Class

The Quat4f class extends Tuple4f. The Quat4f is a four-element quaternion rep-
resented by single-precision floating-point x, y, z, and w coordinates.

Constructors

public Quat4f(float x, float y, float z, float w)

public Quat4f(float q[])
public Quat4f(Quat4d q1)
public Quat4f(Quat4f q1)
public Quat4f(Tuple4d t1)
public Quat4f(Tuple4f t1)
public Quat4f()

410 The Java 3D API Specification

MATH OBJECTS Tuple4f Class A.1.9

These seven constructors each return a new Quat4f. The first constructor gener-
ates a quaternion from four floating-point numbers x, y, z, and w. The second
constructor generates a quaternion from the four floating-point numbers of array
q of length four. The third constructor generates a quaternion from the dou-
ble-precision quaternion q1. The fourth constructor generates a quaternion from
the single-precision quaternion q1. The fifth and sixth constructors generate a
quaternion from tuple t1. The final constructor generates a quaternion with the
value of (0.0, 0.0, 0.0, 0.0).

Methods

public final void conjugate(Quat4f q1)

public final void conjugate()

The first conjugate method sets the value of this quaternion to the conjugate of
quaternion q1. The second conjugate method sets the value of this quaternion to
the conjugate of itself.

public final void mul(Quat4f q1, Quat4f q2)

public final void mul(Quat4f q1)

The first mul method sets the value of this quaternion to the quaternion product
of quaternions q1 and q2 (this = q1 * q2). Note that this is safe for aliasing (that
is, this can be q1 or q2). The second mul method sets the value of this quater-
nion to the quaternion product of itself and q1 (this = this * q1).

public final void mulInverse(Quat4f q1, Quat4f q2)

public final void mulInverse(Quat4f q1)

The first mulInverse method multiplies quaternion q1 by the inverse of quater-

nion q2 and places the value into this quaternion. The value of both argument
quaternions is preserved (this = q1 * q2–1). The second mulInverse method mul-
tiplies this quaternion by the inverse of quaternion q1 and places the value into
this quaternion. The value of the argument quaternion is preserved
(this = this * q1–1).

public final void inverse(Quat4f q1)

public final void inverse()

The first inverse method sets the value of this quaternion to the quaternion
inverse of quaternion q1. The second inverse method sets the value of this
quaternion to the quaternion inverse of itself.

Version 1.2, March 2000 411

A.1.10 Tuple4i Class MATH OBJECTS

public final void normalize(Quat4f q1)

public final void normalize()

The first normalize method sets the value of this quaternion to the normalized
value of quaternion q1. The second normalize method normalizes the value of
this quaternion in place.

public final void set(Matrix4f m1)

public final void set(Matrix4d m1)
public final void set(Matrix3f m1)
public final void set(Matrix3d m1)
public final void set(AxisAngle4f a)
public final void set(AxisAngle4d a)

These set methods set the value of this quaternion to the rotational component
of the passed matrix.

public final void interpolate(Quat4f q1, float alpha)

public final void interpolate(Quat4f q1, Quat4f q2, float alpha)

The first method performs a great circle interpolation between this quaternion
and quaternion q1 and places the result into this quaternion. The second method
performs a great circle interpolation between quaternion q1 and quaternion q2
and places the result into this quaternion.

A.1.10 Tuple4i Class New in 1.2

The Tuple4i class represents a four-element tuple represented by signed integer

x,y,z,w coordinates.

Variables
The component values of a Tuple4i are directly accessible through the public
variables x, y, z, and w. To access the x component of a Tuple4i called upper-
LeftCorner, a programmer would write upperLeftCorner.x. The programmer
would access the y, z, and w components similarly.

public int x New in 1.2

public int y New in 1.2
public int z New in 1.2
public int w New in 1.2

The x, y, z, and w values, respectively.

412 The Java 3D API Specification

MATH OBJECTS Tuple4i Class A.1.10

Constructors

public Tuple4i(int x, int y, int z, int w) New in 1.2

public Tuple4i(int[] t) New in 1.2
public Tuple4i(Tuple4i t1) New in 1.2
public Tuple4i() New in 1.2

These four constructors each return a new Tuple4i. The first constructor gener-
ates a Tuple4i from the specified x, y, z, and w coordinates. The second construc-
tor generates a Tuple4i from the array of length 4. The third constructor
generates a Tuple4i from the specified Tuple4i The final constructor generates a
Tuple4i with the value of (0,0,0,0).

Methods

public final void set(int x, int y, int z, int w) New in 1.2

public final void set(int[] t) New in 1.2
public final void set(Tuple4i t1) New in 1.2
public final void get(int[] t) New in 1.2
public final void get(Tuple4i t) New in 1.2

The first set method sets the value of this tuple to the specified x, y, z, and w
coordinates. The second set method sets the value of this tuple to the specified
coordinates in the array of length 4. The third set method sets the value of this
tuple to the value of tuple t1. The first get method copies the values of this tuple
into the array t. The second get method copies the values of this tuple into the
tuple t.

public final void add(Tuple4i t1, Tuple4i t2) New in 1.2

public final void add(Tuple4i t1) New in 1.2

The first method sets the value of this tuple to the sum of tuples t1 and t2. The
second method sets the value of this tuple to the sum of itself and t1

public final void sub(Tuple4i t1, Tuple4i t2) New in 1.2

public final void sub(Tuple4i t1) New in 1.2

The first method sets the value of this tuple to the difference of tuples t1 and t2
(this = t1 – t2). The second method sets the value of this tuple to the difference
of itself and t1 (this = this – t1).

public final void negate(Tuple4i t1 New in 1.2

public final void negate() New in 1.2

The first method sets the value of this tuple to the negation of tuple t1. The sec-
ond method negates the value of this tuple in place.
Version 1.2, March 2000 413
A.1.10 Tuple4i Class MATH OBJECTS

public final void scale(int s, Tuple4i t1) New in 1.2

public final void scale(int s) New in 1.2

The first method sets the value of this tuple to the scalar multiplication of tuple
t1. The second method sets the value of this tuple to the scalar multiplication of
the scale factor with this.

public final void scaleAdd(int s, Tuple4i t1, Tuple4i t2) New in 1.2
public final void scaleAdd(int s, Tuple4i t1) New in 1.2

The first method sets the value of this tuple to the scalar multiplication of tuple
t1 plus tuple t2 (this = s*t1 + t2). The second method sets the value of this tuple
to the scalar multiplication of itself and then adds tuple t1 (this = s*this + t1).

public final void clamp(int min, int max, Tuple4i t) New in 1.2
public final void clamp(int min, int max) New in 1.2

The first method clamps the tuple parameter to the range [low, high] and places
the values into this tuple. The second method clamps this tuple to the range [low,
high].
public final void clampMin(int min, Tuple4i t) New in 1.2
public final void clampMin(int min) New in 1.2

The first method clamps the minimum value of the tuple parameter to the min
parameter and places the values into this tuple. The second method clamps the
minimum value of this tuple to the min parameter.
public final void clampMax(int max, Tuple4i t) New in 1.2
public final void clampMax(int max) New in 1.2

The first method clamps the maximum value of the tuple parameter to the max
parameter and places the values into this tuple. The second method clamps the
maximum value of this tuple to the max parameter.

public final void absolute(Tuple4i t) New in 1.2

public final void absolute() New in 1.2

The first method sets each component of the tuple parameter to its absolute value
and places the modified values into this tuple. The second method sets each com-
ponent of this tuple to its absolute value.

public String toString() New in 1.2

This method returns a string that contains the values of this Tuple4i.

414 The Java 3D API Specification

MATH OBJECTS AxisAngle4d Class A.1.11

public boolean equals(Object t1) New in 1.2

This method returns true if the Object t1 is of type Tuple4i and all of the data
members of t1 are equal to the corresponding data members in this Tuple4i.

public int hashCode() New in 1.2

This method returns a hash code value based on the data values in this object.
Two different Tuple4i objects with identical data values (i.e., Tuple4i.equals
returns true) will return the same hash code value. Two objects with different
data members may return the same hash value, although this is not likely.

A.1.10.1 Point4i Class New in 1.2

The Point4i class extends Tuple4i. The Point4i is a four-element point repre-
sented by signed integer x,y,z,w coordinates.

Constructors

public Point4i(int x, int y, int z, int w) New in 1.2

public Point4i(int[] t) New in 1.2
public Point4i(Tuple4i t1) New in 1.2
public Point4i() New in 1.2

These four constructors each return a Point4i. The first constructor generates a
Point4i from the specified x, y, z, and w coordinates. The second constructor
generates a Point4i from the array of length 4. The third constructor generates a
Point4i from the specified Tuple4i. The final constructor generates a Point4i with
the value of (0,0,0,0).

A.1.11 AxisAngle4d Class

The AxisAngle4d class represents a four-element axis-angle represented by dou-
ble-precision floating-point x, y, z coordinates and an angle of rotation in radians.
An axis-angle is a rotation of angle radians about the vector x,y,z.

Variables
The component values of an AxisAngle4d are directly accessible through the
public variables x, y, z, and angle. To access the x component of an
AxisAngle4d called myRotation, a programmer would write myRotation.x. The
programmer would access the y, z, and angle components similarly.

Version 1.2, March 2000 415

A.1.11 AxisAngle4d Class MATH OBJECTS

public double x
public double y
public double z
public double angle

The x, y, and z coordinates and the rotational angle, respectively. The rotation
angle is expressed in radians.

Constructors

public AxisAngle4d(double x, double y, double z, double angle)

public AxisAngle4d(double a[])
public AxisAngle4d(AxisAngle4d a1)
public AxisAngle4d(AxisAngle4f a1)
public AxisAngle4d(Vector3d axis, double angle) New in 1.2
public AxisAngle4d()

These six constructors each return a new AxisAngle4d. The first constructor gen-
erates an axis-angle from four floating-point numbers x, y, z, and angle. The
second constructor generates an axis-angle from the first four elements of array
a. The third constructor generates an axis-angle from the double-precision
axis-angle a1. The fourth constructor generates an axis-angle from the sin-
gle-precision axis-angle a1. The fifth constructor generates an axis-angle from
the specified axis and angle. The final constructor generates an axis-angle with
the value of (0.0, 0.0, 1.0, 0.0).

Methods

public final void set(double x, double y, double z, double angle)

public final void set(double a[])
public final void set(Matrix4f m1)
public final void set(Matrix4d m1)
public final void set(Matrix3f m1)
public final void set(Matrix3d m1)
public final void set(AxisAngle4f a1)
public final void set(AxisAngle4d a1)
public final void set(Quat4f q1)
public final void set(Quat4d q1)
public final void set(Vector3d axis, double angle) New in 1.2
public final void get(double a[])

The first set method sets the value of this axis-angle to the specified x, y, z, and
angle coordinates. The second set method sets the value of this axis-angle to
the specified x,y,z angle. The next four set methods set the value of this
axis-angle to the rotational component of the passed matrix m1. The next two set

416 The Java 3D API Specification

MATH OBJECTS AxisAngle4f Class A.1.12

methods set the value of this axis-angle to the value of axis-angle a1. The next
two set methods set the value of this axis-angle to the value of the passed
quaternion q1. The last set method sets the value of this axis-angle to the speci-
fied axis and angle. The get method retrieves the value of this axis-angle and
places it into the array a of length four in x,y,z,angle order.

public String toString()

This method returns a string that contains the values of this AxisAngle4d. The
form is (x, y, z, angle).

public boolean equals(AxisAngle4d v1)

public boolean equals(Object o1)

The first method returns true if all of the data members of AxisAngle4d v1 are
equal to the corresponding data members in this axis-angle. The second method
returns true if the Object o1 is of type AxisAngle4d and all of the data members
of o1 are equal to the corresponding data members in this AxisAngle4d.

public boolean epsilonEquals(AxisAngle4d a1, double epsilon)

This method returns true if the L∞ distance between this axis-angle and
axis-angle a1 is less than or equal to the epsilon parameter. Otherwise, this
method returns false. The L∞ distance is equal to

MAX [ abs ( x1 – x2 ), abs ( y1 – y2 ), abs ( z1 – z2 ), abs ( angle1 – angle2 ) ]

public int hashCode()

This method returns a hash number based on the data values in this object. Two
different AxisAngle4d objects with identical data values (that is,
equals(AxisAngle4d) returns true) will return the same hash number. Two
AxisAngle4d objects with different data members may return the same hash
value, although this is not likely.

A.1.12 AxisAngle4f Class

The AxisAngle4f class represents a four-element axis-angle represented by sin-
gle-precision floating-point x, y, and z coordinates and an angle of rotation in
radians. An axis-angle is a rotation of angle radians about the vector x,y,z.

Variables
The component values of an AxisAngle4f are directly accessible through the
public variables x, y, z, and angle. To access the x component of an

Version 1.2, March 2000 417

A.1.12 AxisAngle4f Class MATH OBJECTS

AxisAngle4f called myRotation, a programmer would write myRotation.x. The

programmer would access the y, z, and angle components similarly.

public float x
public float y
public float z
public float angle

The x, y, and z coordinates and the rotational angle, respectively. The rotation
angle is expressed in radians.

Constructors

public AxisAngle4f(float x, float y, float z, float angle)

public AxisAngle4f(float a[])
public AxisAngle4f(AxisAngle4f a1)
public AxisAngle4f(AxisAngle4d a1)
public AxisAngle4f(Vector3f axis, float angle) New in 1.2
public AxisAngle4f()

These six constructors each return a new AxisAngle4f. The first constructor gen-
erates an axis-angle from four floating-point numbers x, y, z, and angle. The
second constructor generates an axis-angle from the first four elements of array
a. The third constructor generates an axis-angle from the single-precision
axis-angle a1. The fourth constructor generates an axis-angle from the dou-
ble-precision axis-angle a1. The fifth constructor generates an axis-angle from
the specified axis and angle. The final constructor generates an axis-angle with
the value of (0.0, 0.0, 1.0, 0.0).

Methods

public final void set(float x, float y, float z, float angle)

public final void set(float a[])
public final void set(Matrix4f m1)
public final void set(Matrix4d m1)
public final void set(Matrix3f m1)
public final void set(Matrix3d m1)
public final void set(AxisAngle4f a1)
public final void set(AxisAngle4d a1)
public final void set(Quat4f q1)
public final void set(Quat4d q1)
public final void set(Vector3f axis, float angle) New in 1.2
public final void get(float a[])

418 The Java 3D API Specification

MATH OBJECTS GVector Class A.1.13

The first set method sets the value of this axis-angle to the specified x, y, z, and
angle coordinates. The second set method sets the value of this axis-angle to
the specified coordinates in the array a. The next four set methods set the value
of this axis-angle to the rotational component of the passed matrix m1. The next
two set methods set the value of this axis-angle to the value of axis-angle a1.
The next two set methods set the value of this axis-angle to the value of the
passed quaternion q1. The last set method sets the value of this axis-angle to the
specified axis and angle. The get method retrieves the value of this axis-angle
and places it into the array a of length four in x,y,z,angle order.

public String toString()

This method returns a string that contains the values of this axis-angle. The form
is (x, y, z, angle).

public boolean equals(AxisAngle4f a1)

public boolean equals(Object o1)

The first method returns true if all of the data members of axis-angle a1 are
equal to the corresponding data members in this axis-angle. The second method
returns true if the Object o1 is of type AxisAngle4f and all of the data members
of o1 are equal to the corresponding data members in this AxisAngle4f.

public boolean epsilonEquals(AxisAngle4f a1, float epsilon)

This method returns true if the L∞ distance between this axis-angle and
axis-angle a1 is less than or equal to the epsilon parameter. Otherwise, this
method returns false. The L∞ distance is equal to

MAX [ abs ( x1 – x2 ), abs ( y1 – y2 ), abs ( z1 – z2 ), abs ( angle1 – angle2 ) ]

public int hashCode()

This method returns a hash number based on the data values in this object. Two
different AxisAngle4f objects with identical data values (that is,
equals(AxisAngle4f) returns true) will return the same hash number. Two
AxisAngle4f objects with different data members may return the same hash
value, although this is not likely.

A.1.13 GVector Class

The GVector class represents a double-precision, general, dynamically resizable,
one-dimensional vector class. Index numbering begins with zero.

Version 1.2, March 2000 419

A.1.13 GVector Class MATH OBJECTS

Constructors

public GVector(int length)

public GVector(double vector[])
public GVector(GVector vector)
public GVector(Tuple2f tuple)
public GVector(Tuple3f tuple)
public GVector(Tuple3d tuple)
public GVector(Tuple4f tuple)
public GVector(Tuple4d tuple)
public GVector(double vector[], int length)

These nine constructors each return a new GVector. The first constructor gener-
ates a generalized mathematical vector with all elements set to 0.0: length rep-
resents the number of elements in the vector. The second and third constructors
generate a generalized mathematical vector and copy the initial value from the
parameter vector. The next four constructors generate a generalized mathemati-
cal vector and copy the initial value from the tuple parameter tuple. The final
method generates a generalized mathematical vector by copying length ele-
ments from the array parameter. The array must contain at least length elements
(i.e., vector.length ≥ length. The length of this new GVector is set to the
specified length.

Methods

public final void add(GVector v1)

public final void add(GVector v1, GVector v2)
public final void sub(GVector v1)
public final void sub(GVector v1, GVector v2)

The first add method computes the element-by-element sum of this GVector and
GVector v1 and places the result in this. The second add method computes the
element-by-element sum of GVectors v1 and v2 and places the result in this.
The first sub method performs the element-by-element subtraction of GVector v1
from this GVector and places the result in this (this = this – v1). The second
sub method performs the element-by-element subtraction of GVector v2 from
GVector v1 and places the result in this (this = v1 – v2).

public final void mul(GMatrix m1, GVector v1)

public final void mul(GVector v1, GMatrix m1)

The first mul method multiplies matrix m1 times vector v1 and places the result
into this vector (this = m1 * v1). The second mul method multiplies the transpose
of vector v1 (that is, v1 becomes a row vector with respect to the multiplication)

420 The Java 3D API Specification

MATH OBJECTS GVector Class A.1.13

times matrix m1 and places the result into this vector (this = transpose(v1) * m1).
The result is technically a row vector, but the GVector class only knows about
column vectors, so the result is stored as a column vector.

public final void negate()

This method negates the vector this and places the resulting vector back into
this.

public final void zero()

This method sets all the values in this vector to zero.

public final void setSize(int length)

public final void int getSize()

This method changes the size of this vector dynamically. If the size is increased,
no data values are lost. If the size is decreased, only those data values whose vec-
tor positions were eliminated are lost.

public final void set(double v[])

public final void set(GVector v)
public final void set(Tuple2f t)
public final void set(Tuple3f t)
public final void set(Tuple3d t)
public final void set(Tuple4f t)
public final void set(Tuple4d t)

The first set method sets the values of this vector to the values found in the array
v: The array should be at least equal in length to the number of elements in the
vector. The second set method sets the values of this vector to the values in vec-
tor v. The last 5 set methods set the value of this vector to the values in tuple t.

public final double getElement(int index)

public final void setElement(int index, double value)

These methods set and retrieve the specified index value of this vector.

public final double norm()

public final double normSquared()

The norm method returns the square root of the sum of the squares of this vector
(its length in n-dimensional space). The normSquared method returns the sum of
the squares of this vector (its length in n-dimensional space).

Version 1.2, March 2000 421

A.1.13 GVector Class MATH OBJECTS

public final void normalize(GVector v1)

public final void normalize()

The first normalize method sets the value of this vector to the normalization of
vector v1. The second normalize method normalizes this vector in place.

public final void scale(double s, GVector v1)

public final void scale(double s)
public final void scaleAdd(double s, GVector v1, GVector v2)

The first scale method sets the value of this vector to the scalar multiplication of
the scale factor s with the vector v1. The second scale method scales this vector
by the scale factor s. The scaleAdd method scales the vector v1 by the scale fac-
tor s, adds the result to the vector v2, and places the result into this vector
(this = s*v1 + v2).

public String toString()

This method returns a string that contains the values of this vector.

public int hashCode()

This method returns a hash number based on the data values in this object. Two
different GVector objects with identical data values (that is, equals(GVector)
returns true) will return the same hash number. Two objects with different data
members may return the same hash value, although this is not likely.

public boolean equals(GVector vector1)

public boolean equals(Object o1)

The first method returns true if all of the data members of GVector vector1 are
equal to the corresponding data members in this GVector. The second method
returns true if the Object o1 is of type GMatrix and all of the data members of o1
are equal to the corresponding data members in this GMatrix.

public boolean epsilonEquals(GVector v1, double epsilon)

This method returns true if the L∞ distance between this vector and vector v1 is
less than or equal to the epsilon parameter. Otherwise, this method returns
false. The L∞ distance is equal to

MAX [ abs ( x1 – x2 ), abs ( y1 – y2 ), … ]

public final double dot(GVector v1)

This method returns the dot product of this vector and vector v1.

422 The Java 3D API Specification

MATH OBJECTS Matrix Objects A.2

public final void SVDBackSolve(GMatrix U, GMatrix W, GMatrix V,

GVector x)
public final void LUDBackSolve(GMatrix LU, GVector b,
GVector permutation)

The first method solves for x in Ax = b, where x is this vector (n × 1), b is an

m × 1 vector, and A is an m × n matrix, defined as A = U * W * transpose(V). U,
W, and V must be precomputed and can be found by taking the singular value
decomposition (SVD) of A. The second method takes the LU matrix and the per-
mutation vector produced by the GMatrix method LUD and solves the equation
LU * x = b by placing the solution to the set of linear equations into this vector
(x).

public final double angle(GVector v1)

This method returns the (n-space) angle, in radians, between this vector and the
vector v1 parameter . The return value is constrained to the range [0, π].

public final void interpolate(GVector v1, GVector v2, float alpha)

public final void interpolate(GVector v1, float alpha)

Deprecated methods. See the next two methods.

public final void interpolate(GVector v1, GVector v2, double alpha)

public final void interpolate(GVector v1, double alpha)

The first method linearly interpolates between vectors v1 and v2 and places the
result into this vector (this = (1 – alpha) * v1 + alpha * v2). The second method
linearly interpolates between this vector and vector v1 and places the result into
this vector (this = (1 – alpha) * this + alpha * v1).

A.2 Matrix Objects

Java 3D uses matrix objects to represent rotations and full 3D transformations.
The matrix classes (as well as the associated Tuple and AxisAngle classes)
include code for accessing, manipulating, and updating the matrix, vector, and
AxisAngle classes. Java 3D further subdivides the matrix classes into 3 × 3
matrices (mainly to store rotations) and 4 × 4 matrices (mainly to store more
complex 3D transformations). These two classes in turn provide support for both
single-precision floating-point representations and for double-precision float-
ing-point representations.
Matrix operations try to minimize gratuitous allocation of memory, thus all
matrix operations update an existing object. To multiply two matrices together

Version 1.2, March 2000 423

A.2.1 Matrix3f Class MATH OBJECTS

and store the result in a third, a Java 3D application or applet would write
matrix3.mul(matrix1, matrix2). Here matrix3 receives the results of multi-
plying matrix1 with matrix2.
The Java 3D model for 3 × 3 transformations is

m00 m01 m02 x x′

m10 m11 m12 ⋅ y = y′
m20 m21 m22 z z′

x′ = m00 ⋅ x + m01 ⋅ y + m02 ⋅ z

y′ = m10 ⋅ x + m11 ⋅ y + m12 ⋅ z
z′ = m20 ⋅ x + m21 ⋅ y + m22 ⋅ z

The Java 3D model for 4 × 4 transformations is

m00 m01 m02 m03 x x′

m10 m11 m12 m13 ⋅ y = y′
m20 m21 m22 m23 z z′
m30 m31 m32 m33 w w′

x′ = m00 ⋅ x + m01 ⋅ y + m02 ⋅ z + m03 ⋅ w

y′ = m10 ⋅ x + m11 ⋅ y + m12 ⋅ z + m13 ⋅ w
z′ = m20 ⋅ x + m21 ⋅ y + m22 ⋅ z + m23 ⋅ w
w′ = m30 ⋅ x + m31 ⋅ y + m32 ⋅ z + m33 ⋅ w

Note: When transforming a Point3f or a Point3d, the input w is set to 1. When

transforming a Vector3f or Vector3d, the input w is set to 0.

A.2.1 Matrix3f Class

The Matrix3f class serves to contain 3 × 3 matrices mainly for storing and
manipulating 3D rotation matrices. The class includes five different constructors
for creating matrices and several operators for manipulating these matrices.

Variables
The component values of a Matrix3f are directly accessible through the public
variables m00, m01, m02, m10, m11, m12, m20, m21, and m22. To access the element
in row 2 and column 0 of matrix rotate, a programmer would write
rotate.m20. A programmer would access the other values similarly.

424 The Java 3D API Specification

MATH OBJECTS Matrix3f Class A.2.1

public float m00

public float m01
public float m02
public float m10
public float m11
public float m12
public float m20
public float m21
public float m22

These public variables are the elements of the matrix.

Constructors

public Matrix3f(float m00, float m01, float m02, float m10,

float m11, float m12, float m20, float m21, float m22)
public Matrix3f(float v[])
public Matrix3f(Matrix3d m1)
public Matrix3f(Matrix3f m1)
public Matrix3f()

These constructors each return a new Matrix3f object. The first constructor gen-
erates a 3 × 3 matrix from the nine values provided. The second constructor gen-
erates a 3 × 3 matrix from the first nine values in the array v. The third and fourth
constructors generate a new matrix with the same values as the passed matrix m1.
The final constructor generates a 3 × 3 matrix with all nine values set to 0.0.

Methods

public final void set(Quat4d q1)

public final void set(Quat4f q1)

These two set methods set the value of the matrix this to the matrix conversion
of the quaternion argument q1.

public final void set(Matrix3f m1)

public final void set(Matrix3d m1)

Sets the value of this matrix to the value of the argument.

public final void set(AxisAngle4d a1)

public final void set(AxisAngle4f a1)

These two set methods set the value of the matrix this to the matrix conversion
of the axis and angle argument a1.

Version 1.2, March 2000 425

A.2.1 Matrix3f Class MATH OBJECTS

public final void set(float scale)

public final void set(float m[])

The first method sets the value of this matrix to a scale matrix with the passed
scale amount. The second method sets the values of this matrix to the
row-major array parameter (that is, the first three elements of the array are cop-
ied into the first row of this matrix, and so forth).

public final void setElement(int row, int column, float value)

public final float getElement(int row, int column)

The setElement and getElement methods provide a means for accessing a sin-
gle element within a 3 × 3 matrix using indices. This is not a preferred method of
access, but Java 3D provides these methods for functional completeness. The
setElement method takes a row index row (where a value of 0 represents the
first row and a value of 2 represents the third row), a column index column
(where a value of 0 represents the first column and a value of 2 represents the
third column), and a value. It sets the corresponding element in matrix this to
the specified value. The getElement method also takes a row index row and a
column index column. It returns the element at the corresponding locations as a
floating-point value.

public final void setRow(int row, float x, float y, float z)

public final void setRow(int row, Vector3f v)
public final void setRow(int row, float v[])
public final void getRow(int row, Vector3f v)
public final void getRow(int row, float v[])

The three setRow methods provide a means for constructing a 3 × 3 matrix on a

row basis. The row parameter row determines which row the method invocation
affects. A row value of 0 represents the first row and a value of 2 represents the
third row. The first setRow method specifies the three new values as independent
floating-point values. The second setRow method uses the values in the Vector3f
v to update the matrix. The third setRow method uses the first three values in the
array v to update the matrix. In all three cases the matrix affected is the matrix
this. The two getRow methods copy the matrix values in the specified row into
the vector or array parameter, respectively.

public final void setColumn(int column, float x, float y, float z)

public final void setColumn(int column, Vector3f v)
public final void setColumn(int column, float v[])
public final void getColumn(int column, Vector3f v)
public final void getColumn(int column, float v[])

426 The Java 3D API Specification

MATH OBJECTS Matrix3f Class A.2.1

The three setColumn methods provide a means for constructing a 3 × 3 matrix

on a column basis. The column parameter determines which column the method
invocation affects. A column value of 0 represents the first column and a value of
2 represents the third column. The first setColumn method specifies the three
new values as independent floating-point values. The second setColumn method
uses the values in the Vector3f v to update the matrix. The third setColumn
method uses the first three values in the array v to update the matrix. In all three
cases the matrix affected is the matrix this. The two getColumn methods copy
the matrix values in the specified column into the vector or array parameter,
respectively.

public final void setZero()

This method sets this matrix to all zeros.

public final void setIdentity()

This method sets this Matrix3f to identity.

public final void add(Matrix3f m1, Matrix3f m2)

public final void add(Matrix3f m1)
public final void sub(Matrix3f m1, Matrix3f m2)
public final void sub(Matrix3f m1)

The first add method adds the matrix m1 to the matrix m2 and places the result
into the matrix this. The second add method adds the matrix this to the matrix
m1 and places the result into the matrix this. The first sub method performs an
element-by-element subtraction of matrix m2 from matrix m1 and places the result
into the matrix this. The second sub method performs an element-by-element
subtraction of the matrix m1 from the matrix this and places the result into the
matrix this.

public final void transform(Tuple3f t)

public final void transform(Tuple3f t, Tuple3f result)

The first method multiplies this matrix by the tuple t and places the result back
into the tuple (t = this*t). The second method multiplies this matrix by the tuple
t and places the result into the tuple result (result = this*t).

public final void transpose()

public final void transpose(Matrix3f m1)

The first method transposes this matrix in place. The second method sets the
value of this matrix to the transpose of the matrix m1.

Version 1.2, March 2000 427

A.2.1 Matrix3f Class MATH OBJECTS

public final void invert()

public final void invert(Matrix3f m1)

The first method inverts this matrix in place. The second method sets the value of
this matrix to the inverse of the matrix m1.

public final float determinant()

The determinant method computes the determinant of the matrix this and
returns the computed value.

public final void rotX(float angle)

public final void rotY(float angle)
public final void rotZ(float angle)

The three rot methods construct rotation matrices that rotate in a counter-clock-
wise (right-handed) direction around the axis specified as the last letter of the
method name. The constructed matrix replaces the value of the matrix this. The
rotation angle is expressed in radians.

public final void mul(Matrix3f m1, Matrix3f m2)

public final void mul(Matrix3f m1)

The first mul method multiplies matrix m1 with matrix m2 and places the result
into the matrix this. The second mul method multiplies the matrix this with the
matrix m1 and places the result into matrix this.

public final void mulNormalize(Matrix3f m1)

public final void mulNormalize(Matrix3f m1, Matrix3f m2)

The first mulNormalize method multiplies this matrix by matrix m1, performs an
SVD normalization of the result, and places the result back into this matrix (this
= SVDnorm(this ⋅ m1)). The second mulNormalize method multiplies matrix m1
by matrix m2, performs an SVD normalization of the result, and places the result
into this matrix (this = SVDnorm(m1 ⋅ m2)).

public final void mulTransposeBoth(Matrix3f m1, Matrix3f m2)

public final void mulTransposeRight(Matrix3f m1, Matrix3f m2)
public final void mulTransposeLeft(Matrix3f m1, Matrix3f m2)

The mulTransposeBoth method multiplies the transpose of matrix m1 (left) times

the transpose of matrix m2 (right) and places the result into this matrix. The mul-
TransposeRight method multiplies matrix m1 times the transpose of matrix m2
and places the result back into this matrix. The mulTransposeLeft method mul-
tiplies the transpose of matrix m1 times matrix m2 and places the result into this
matrix.

428 The Java 3D API Specification

MATH OBJECTS Matrix3f Class A.2.1

public final void normalize()

public final void normalize(Matrix3f m1)

The first normalize method performs a singular value decomposition normaliza-

tion of this matrix. The second normalize method performs a singular value
decomposition normalization of matrix m1 and places the normalized values into
this.

public final void normalizeCP()

public final void normalizeCP(Matrix3f m1)

The first normalizeCP method performs a cross-product normalization of this

matrix. The second normalizeCP method performs a cross-product normaliza-
tion of matrix m1 and places the normalized values into this.

public boolean equals(Matrix3f m1)

public boolean equals(Object o1)

The first method returns true if all of the data members of Matrix3f m1 are equal
to the corresponding data members in this Matrix3f. The second method returns
true if the Object o1 is of type Matrix3f and all of the data members of o1 are
equal to the corresponding data members in this Matrix3f.

public boolean epsilonEquals(Matrix3f m1, float epsilon)

This method returns true if the L∞ distance between this Matrix3f and Matrix3f
m1 is less than or equal to the epsilon parameter. Otherwise, this method
returns false. The L∞ distance is equal to
MAX[i = 0,1,2, ... n; j = 0,1,2,... n; abs(this.m(i,j) – m1.m(i,j)]

public final void negate()

public final void negate(Matrix3f m1)

The first method negates the value of this matrix in place (this = –this). The sec-
ond method sets the value of this matrix equal to the negation of the matrix m1
(this = –m1).

public final float getScale()

This method performs an SVD normalization of this matrix to calculate and

return the uniform scale factor. If the matrix has non-uniform scale factors, the
largest of the x, y, and z scale factors will be returned.

Version 1.2, March 2000 429

A.2.2 Matrix3d Class MATH OBJECTS

public final void setScale(float scale)

This method sets the scale component of the current matrix by factoring out the
current scale (by doing an SVD) and multiplying by the new scale.

public final void add(float scalar)

This method adds a scalar to each component of this matrix.

public final void add(float scalar, Matrix3f m1)

This method adds a scalar to each component of the matrix m1 and places the
result into this. Matrix m1 is not modified.

public final void mul(float scalar, Matrix3f m1)

This method multiplies each component of the matrix m1 by a scalar and places
the result into this. Matrix m1 is not modified.

public final void mul(float scalar)

This method multiplies each element of this matrix by a scalar.

public final void transform(Tuple3f t)

public final void transform(Tuple3f t, Tuple3f result)

The first method multiplies this matrix by the tuple t and places the result back
into the tuple (t = this*t). The second method multiplies this matrix by the
tuple t and places the result into the tuple result (result = this*t).

public int hashCode()

The hashCode method returns a hash number based on the data values in this
object. Two different Matrix3f objects with identical data values (that is,
equals(Matrix3f) returns true) will return the same hash number. Two
Matrix3f objects with different data members may return the same hash value,
although this is not likely.

public String toString()

The toString method returns a string that contains the values of this Matrix3f.

A.2.2 Matrix3d Class

The Matrix3d class serves to contain 3 × 3 matrices mainly for storing and
manipulating 3D rotation matrices. The class includes five different constructors
for creating matrices and several operators for manipulating these matrices.

430 The Java 3D API Specification

MATH OBJECTS Matrix3d Class A.2.2

Variables
The component values of a Matrix3d are directly accessible through the public
variables m00, m01, m02, m10, m11, m12, m20, m21, and m22. To access the element
in row 2 and column 0 of the matrix named rotate, a programmer would write
rotate.m20. Other matrix values are accessed similarly.

public double m00

public double m01
public double m02
public double m10
public double m11
public double m12
public double m20
public double m21
public double m22

These public variables are the elements of the matrix.

Constructors

public Matrix3d(double m00, double m01, double m02, double m10,

double m11, double m12, double m20, double m21, double m22)
public Matrix3d(double v[])
public Matrix3d()
public Matrix3d(Matrix3d m1)
public Matrix3d(Matrix3f m1)

These constructors each return a new Matrix3d object. The first constructor gen-
erates a 3 × 3 matrix from the nine values provided. The second constructor gen-
erates a 3 × 3 matrix from the first nine values in the array v. The third
constructor generates a 3 × 3 matrix with all nine values set to 0.0. The fourth
and fifth constructors generate a 3 × 3 matrix with the same values as the matrix
m1 parameter.

Methods

public final void set(Matrix3f m1)

public final void set(Matrix3d m1)

These methods set the value of this matrix to the value of the argument.

public final void set(double scale)

public final void set(double m[])

Version 1.2, March 2000 431

A.2.2 Matrix3d Class MATH OBJECTS

These methods set the value of the matrix this to a scale matrix with the passed
scale amount.

public final void set(AxisAngle4d a1)

public final void set(AxisAngle4f a1)

These two set methods set the value of the matrix this to the matrix conversion
of the axis and angle argument a1.

public final void set(Quat4d q1)

public final void set(Quat4f q1)

These two set methods set the value of the matrix this to the matrix conversion
of the quaternion argument q1.

public final void setElement(int row, int column, double value)

public final double getElement(int row, int column)

The setElement and getElement methods provide a means for accessing a sin-
gle element within a 3 × 3 matrix using indices. This is not a preferred method of
access, but Java 3D provides these methods for functional completeness. The
setElement method takes a row index row (where a value of 0 represents the
first row and a value of 2 represents the third row), a column index column
(where a value of 0 represents the first column and a value of 2 represents the
third column), and a value. It sets the corresponding element in matrix this to
the specified value. The getElement method also takes a row index row and a
column index column and returns the element at the corresponding locations as a
floating-point value.

public final void setRow(int row, double x, double y, double z)

public final void setRow(int row, Vector3d v)
public final void setRow(int row, double v[])
public final void getRow(int row, Vector3d v)
public final void getRow(int row, double v[])

The three setRow methods provide a means for constructing a 3 × 3 matrix on a

row basis. The row parameter determines which row the method invocation
affects. A row value of 0 represents the first row and a value of 2 represents the
third row. The first setRow method specifies the three new values as independent
floating-point values. The second setRow method uses the values in the Vector3d
v to update the matrix. The third setRow method uses the first three values in the
array v to update the matrix. In all three cases the matrix affected is the matrix
this. The two getRow methods copy the matrix values in the specified row into
the array or vector parameter, respectively.

432 The Java 3D API Specification

MATH OBJECTS Matrix3d Class A.2.2

public final void setColumn(int column, double x, double y,

double z)
public final void setColumn(int column, Vector3d v)
public final void setColumn(int column, double v[])
public final void getColumn(int column, Vector3d v)
public final void getColumn(int column, double v[])

The three setColumn methods provide a means for constructing a 3 × 3 matrix

on a column basis. The column parameter determines which column the method
invocation affects. A column value of 0 represents the first column and a value of
2 represents the third column. The first setColumn method specifies the three
new values as independent floating-point values. The second setColumn method
uses the values in the Vector3d v to update the matrix. The third setColumn
method uses the first three values in the array v to update the matrix. In all three
cases the matrix affected is the matrix this. The two getColumn methods copy
the matrix values in the specified column into the array or vector parameter,
respectively.

public final void add(Matrix3d m1, Matrix3d m2)

public final void add(Matrix3d m1)
public final void sub(Matrix3d m1, Matrix3d m2)
public final void sub(Matrix3d m1)

The first add method adds the matrix m1 to the matrix m2 and places the result
into the matrix this. The second add method adds the matrix this to the matrix
m1 and places the result into the matrix this. The first sub method performs an
element-by-element subtraction of matrix m2 from matrix m1 and places the result
into the matrix this. The second sub method performs an element-by-element
subtraction of the matrix m1 from the matrix this and places the result into the
matrix this.

public final void add(double scalar)

This method adds a scalar to each component of this matrix.

public final void add(double scalar, Matrix3d m1)

This method adds a scalar to each component of the matrix m1 and places the
result into this. Matrix m1 is not modified.

public final void transform(Tuple3d t)

public final void transform(Tuple3d t, Tuple3d result)

The first method multiplies this matrix by the tuple t and places the result back
into the tuple (t = this*t). The second method multiplies this matrix by the tuple
t and places the result into the tuple result (result = this*t).

Version 1.2, March 2000 433

A.2.2 Matrix3d Class MATH OBJECTS

public final void transpose()

public final void transpose(Matrix3d m1)

The first method transposes this matrix in place. The second method sets the
value of this matrix to the transpose of the matrix m1.

public final void invert()

public final void invert(Matrix3d m1)

The first method inverts this matrix in place. The second method sets the value of
this matrix to the inverse of the matrix m1.

public final double determinant()

The determinant method computes the determinant of the matrix this and
returns the computed value.

public final void rotX(double angle)

public final void rotY(double angle)
public final void rotZ(double angle)

The three rot methods construct rotation matrices that rotate in a counter-clock-
wise (right-handed) direction around the axis specified by the final letter of the
method name. The constructed matrix replaces the value of the matrix this. The
rotation angle is expressed in radians.

public final void mul(Matrix3d m1, Matrix3d m2)

public final void mul(Matrix3d m1)

The first mul method multiplies matrix m1 with matrix m2 and places the result
into the matrix this. The second mul method multiplies matrix this with matrix
m1 and places the result into the matrix this.

public final void mulNormalize(Matrix3d m1)

public final void mulNormalize(Matrix3d m1, Matrix3d m2)

The first mulNormalize method multiplies this matrix by matrix m1, performs an
SVD normalization of the result, and places the result back into this matrix (this
= SVDnorm(this ⋅ m1)). The second mulNormalize method multiplies matrix m1
by matrix m2, performs an SVD normalization of the result, and places the result
into this matrix (this = SVDnorm(m1 ⋅ m2)).

public final void mulTransposeBoth(Matrix3d m1, Matrix3d m2)

public final void mulTransposeRight(Matrix3d m1, Matrix3d m2)
public final void mulTransposeLeft(Matrix3d m1, Matrix3d m2)

434 The Java 3D API Specification

MATH OBJECTS Matrix3d Class A.2.2

The mulTransposeBoth method multiplies the transpose of matrix m1 (left) times

the transpose of matrix m2 (right) and places the result into this matrix. The mul-
TransposeRight method multiplies matrix m1 times the transpose of matrix m2
and places the result back into this matrix. The mulTransposeLeft method mul-
tiplies the transpose of matrix m1 times matrix m2 and places the result into this
matrix.

public final void normalize()

public final void normalize(Matrix3d m1)

The first normalize method performs a singular value decomposition normaliza-

tion of this matrix. The second normalize method performs a singular value
decomposition normalization of matrix m1 and places the normalized values into
this.

public final void normalizeCP()

public final void normalizeCP(Matrix3d m1)

The first normalizeCP method performs a cross-product normalization of this

matrix. The second normalizeCP method performs a cross-product normaliza-
tion of matrix m1 and places the normalized values into this.

public boolean equals(Matrix3d m1)

public boolean equals(Object t1)

The first method returns true if all of the data members of Matrix3d m1 are equal
to the corresponding data members in this Matrix3d. The second method returns
true if the Object t1 is of type Matrix3d and all of the data members of t1 are
equal to the corresponding data members in this Matrix3d.

public boolean epsilonEquals(Matrix3d m1, double epsilon)

This method returns true if the L∞ distance between this Matrix3d and
Matrix3d m1 is less than or equal to the epsilon parameter. Otherwise, this
method returns false. The L∞ distance is equal to
MAX[i = 0,1,2,; j = 0,1,2,; abs(this.m(i,j) – m1.m(i,j)]

public final void negate()

public final void negate(Matrix3d m1)

The first method negates the value of this matrix in place (this = –this). The sec-
ond method sets the value of this matrix equal to the negation of the matrix m1
(this = –m1).

Version 1.2, March 2000 435

A.2.2 Matrix3d Class MATH OBJECTS

public final double getScale()

This method performs an SVD normalization of this matrix to calculate and

return the uniform scale factor. If the matrix has non-uniform scale factors, the
largest of the x, y, and z scale factors will be returned.

public final void setScale(double scale)

This method sets the scale component of the current matrix by factoring out the
current scale (by doing an SVD) and multiplying by the new scale.

public final void mul(double scalar, Matrix3d m1)

This method multiplies each component of the matrix m1 by a scalar and places
the result into this. Matrix m1 is not modified.

public final void mul(double scalar)

This method multiplies each element of this matrix by a scalar.

public final void transform(Tuple3d t)

public final void transform(Tuple3d t, Tuple3d result)

The first method multiplies this matrix by the tuple t and places the result back
into the tuple (t = this*t). The second method multiplies this matrix by the
tuple t and places the result into the tuple result (result = this*t).

public final void setZero()

This method sets this matrix to all zeros.

public final void setIdentity()

This method sets this Matrix3d to identity.

public int hashCode()

The hashCode method returns a hash number based on the data values in this
object. Two different Matrix3d objects with identical data values (that is,
equals(Matrix3d) returns true) will return the same hash number. Two
Matrix3d objects with different data members may return the same hash value,
although this is not likely.

public String toString()

The toString method returns a string that contains the values of this Matrix3d.

436 The Java 3D API Specification

MATH OBJECTS Matrix4f Class A.2.3

A.2.3 Matrix4f Class

The Matrix4f class serves to contain 4 × 4 matrices mainly for storing and
manipulating 3D transformation matrices. The class includes seven different con-
structors for creating matrices and several operators for manipulating these
matrices.

Variables
The component values of a Matrix4f are directly accessible through the public
variables m00, m01, m02, m03, m10, m11, m12, m13, m20, m21, m22, m23, m30, m31,
m32, and m33. To access the element in row 2 and column 0 of matrix rotate, a
programmer would write rotate.m20. A programmer would access the other
values similarly.

public float m00

public float m01
public float m02
public float m03
public float m10
public float m11
public float m12
public float m13
public float m20
public float m21
public float m22
public float m23
public float m30
public float m31
public float m32
public float m33

These public variables are the elements of the matrix.

Constructors

public Matrix4f(float m00, float m01, float m02, float m03,

float m10, float m11, float m12, float m13,
float m20, float m21, float m22, float m23, float m30,
float m31, float m32, float m33)
public Matrix4f(float v[])
public Matrix4f(Quat4f q1, Vector3f t1, float s)
public Matrix4f(Matrix4d m1)
public Matrix4f(Matrix4f m1)

Version 1.2, March 2000 437

A.2.3 Matrix4f Class MATH OBJECTS

public Matrix4f(Matrix3f m1, Vector3f t1, float s)

public Matrix4f()

These constructors each return a new Matrix4f object. The first constructor gen-
erates a 4 × 4 matrix from the 16 values provided. The second constructor gener-
ates a 4 × 4 matrix from the first 16 values in the array v. The third constructor
generates a 4 × 4 matrix from the quaternion, translation, and scale values. The
scale is applied only to the rotational components of the matrix (upper 3 × 3) and
not to the translational components. The fourth and fifth constructors generate a
4 × 4 matrix with the same values as the passed matrix m1. The sixth constructor
generates a 4 × 4 matrix from the rotation matrix, translation, and scale values.
The scale is applied only to the rotational components of the matrix (upper 3 × 3)
and not to the translational components of the matrix. The final constructor gen-
erates a 4 × 4 matrix with all 16 values set to 0.0.

Methods

public final void set(Quat4f q1)

public final void set(Quat4d q1)
public final void set(Quat4f q1, Vector3f t1, float s)
public final void set(Quat4d q1, Vector3d t1, double s)
public final void set(Matrix4d m1)
public final void set(Matrix4f m1)
public final void set(AxisAngle4f a1)
public final void set(AxisAngle4d a1)

The first two set methods set the value of this matrix to the matrix conversion of
the quaternion argument q1. The next two set methods set the value of this
matrix from the rotation expressed by the quaternion q1, the translation t1, and
the scale s. The next two set methods set the value of this matrix to a copy of
the passed matrix m1. The last two set methods set the value of this matrix to the
matrix conversion of the axis and angle argument a1.

public final void set(Matrix3f m1)

public final void set(Matrix3d m1)

These methods set the rotational component (upper 3 × 3) of this matrix to the
matrix values in the m1 argument. The other elements of this matrix are initial-
ized as if this were an identity matrix (that is, an affine matrix with no transla-
tional component).

438 The Java 3D API Specification

MATH OBJECTS Matrix4f Class A.2.3

public final void set(float scale)

public final void set(float m[])

The first method sets the value of this matrix to a scale matrix with the passed
scale amount. The second method sets the value of this matrix to the row-major
array parameter (that is, the first four elements of the array are copied into the
first row of this matrix, and so forth).

public final void set(Vector3f v1)

This method sets the value of this matrix to a translation matrix with the passed
translation value.

public final void set(float scale, Vector3f t1)

public final void set(Vector3f t1, float scale)

These methods set the value of this matrix to a scale and translation matrix. In
the first method, the scale is not applied to the translation, and all of the matrix
values are modified. In the second method, the translation is scaled by the scale
factor, and all of the matrix values are modified.

public final void set(Matrix3f m1, Vector3f t1, float scale)

public final void set(Matrix3d m1, Vector3d t1, double scale)

These two methods set the value of this matrix from the rotation expressed by
the rotation matrix m1, the translation t1, and the scale scale. The translation is
not modified by the scale.

public final void get(Matrix3d m1)

public final void get(Matrix3f m1)
public final float get(Matrix3f m1, Vector3f t1)
public final void get(Quat4f q1)
public final void get(Vector3f trans)

The first two methods perform an SVD normalization of this matrix in order to
acquire the normalized rotational component. The values are placed into the
matrix parameter m1. The third method performs an SVD normalization of this
matrix to calculate the rotation as a 3 × 3 matrix, the translation, and the scale.
None of the matrix values in this matrix are modified. The fourth method per-
forms an SVD normalization of this matrix to acquire the normalized rotational
component. The values are placed into the quaternion q1. The final method
retrieves the translational components of this matrix and copies them into the
vector trans.

Version 1.2, March 2000 439

A.2.3 Matrix4f Class MATH OBJECTS

public final void setElement(int row, int column, float value)

public final float getElement(int row, int column)

The setElement and getElement methods provide a means for accessing a sin-
gle element within a 4 × 4 matrix using indices. This is not a preferred method of
access, but Java 3D provides these methods for functional completeness. The
setElement method takes a row index row (where a value of 0 represents the
first row and a value of 3 represents the fourth row), a column index column
(where a value of 0 represents the first column and a value of 3 represents the
fourth column), and a value. It sets the corresponding element in matrix this to
the specified value. The getElement method also takes a row index row and a
column index column and returns the element at the corresponding locations as a
floating-point value.

public final void getRotationScale(Matrix3f m1)

This method retrieves the upper 3 × 3 values of this matrix and places them into
the matrix m1.

public final void setScale(float scale)

public final float getScale()

The first method sets the scale component of the current matrix by factoring out
the current scale (by doing an SVD) and multiplying by the new scale. The sec-
ond method performs an SVD normalization of this matrix to calculate and
return the uniform scale factor. If the matrix has non-uniform scale factors, the
largest of the x, y, and z scale factors will be returned.

public final void add(float scalar)

This method adds a scalar to each component of this matrix.

public final void add(float scalar, Matrix4f m1)

This method adds a scalar to each component of the matrix m1 and places the
result into this. Matrix m1 is not modified.

public final void mul(float scalar, Matrix4f m1)

This method multiplies each component of the matrix m1 by a scalar and places
the result into this. Matrix m1 is not modified.

public final void mul(float scalar)

This method multiplies each element of this matrix by a scalar.

440 The Java 3D API Specification

MATH OBJECTS Matrix4f Class A.2.3

public final void setRow(int row, float x, float y, float z,

float w)
public final void setRow(int row, Vector4f v)
public final void setRow(int row, float v[])
public final void getRow(int row, Vector4f v)
public final void getRow(int row, float v[])

The three setRow methods provide a means for constructing a 4 × 4 matrix on a

row basis. The row parameter row determines which row the method invocation
affects. A row value of 0 represents the first row and a value of 3 represents the
fourth row. The first setRow method specifies the four new values as independent
floating-point values. The second setRow method uses the values in the Vector4f
v to update the matrix. The third setRow method uses the first four values in the
array v to update the matrix. In all three cases the matrix affected is the matrix
this. The two getRow methods copy the matrix values in the specified row into
the array or vector parameter, respectively.

public final void setColumn(int column, float x, float y, float z,

float w)
public final void setColumn(int column, Vector4f v)
public final void setColumn(int column, float v[])
public final void getColumn(int column, Vector4f v)
public final void getColumn(int column, float v[])

The three setColumn methods provide a means for constructing a 4 × 4 matrix

on a column basis. The column parameter determines which column the method
invocation affects. A column value of 0 represents the first column and a value of
3 represents the fourth column. The first setColumn method specifies the four
new values as independent double-precision floating-point values. The second
setColumn method uses the values in the Vector4f v to update the matrix. The
third setColumn method uses the first four values in the array v to update the
matrix. In all three cases the matrix affected is the matrix this. The two getCol-
umn methods copy the matrix values in the specified column into the array or
vector parameter, respectively.

public final void setRotation(Matrix3d m1)

public final void setRotation(Matrix3f m1)
public final void setRotation(Quat4f q1)
public final void setRotation(Quat4d q1)
public final void setRotation(AxisAngle4f a1)

These methods set the rotational component (upper 3 × 3) of this matrix to the
matrix values in the passed argument. The other elements of this matrix are
unchanged. In the first two methods, a singular value decomposition is per-
formed on this object’s upper 3 × 3 matrix to factor out the scale, then this
Version 1.2, March 2000 441
A.2.3 Matrix4f Class MATH OBJECTS

object’s upper 3 × 3 matrix components are replaced by the passed rotation com-
ponents, and finally the scale is reapplied to the rotational components. In the
next two methods, a singular value decomposition is performed on this object’s
upper 3 × 3 matrix to factor out the scale, then this object’s upper 3 × 3 matrix
components are replaced by the matrix equivalent of the quaternion, and finally
the scale is reapplied to the rotational components. In the last method, a singular
value decomposition is performed on this object’s upper 3 × 3 matrix to factor
out the scale, then this object’s upper 3 × 3 matrix components are replaced by
the matrix equivalent of the axis-angle, and finally the scale is reapplied to the
rotational components.

public final void setRotationScale(Matrix3f m1)

This method replaces the upper 3 × 3 matrix values of this matrix with the values
in the matrix m1.

public final void setTranslation(Vector3f trans)

This method modifies the translational components of this matrix to the values of
the vector trans. The other values of this matrix are not modified.

public final void setIdentity()

This method sets this Matrix4f to identity.

public final void setZero()

This method sets this matrix to all zeros.

public final void add(Matrix4f m1, Matrix4f m2)

public final void add(Matrix4f m1)
public final void sub(Matrix4f m1, Matrix4f m2)
public final void sub(Matrix4f m1)

The first add method adds the matrix m1 to the matrix m2 and places the result
into the matrix this. The second add method adds the matrix this to the matrix
m1 and places the result into the matrix this. The first sub method performs an
element-by-element subtraction of matrix m2 from matrix m1 and places the result
into the matrix this. The second sub method performs an element-by-element
subtraction of the matrix m1 from the matrix this and places the result into the
matrix this.

public final void transpose(Matrix4f m1)

public final void transpose()

442 The Java 3D API Specification

MATH OBJECTS Matrix4f Class A.2.3

The first transpose method transposes the matrix m1 and places the result into
the matrix this. The second transpose method transposes the matrix this and
places the result back into the matrix this.

public final void transform(Point3f point)

public final void transform(Point3f point, Point3f pointOut)

The first transform method postmultiplies this matrix by the Point3f point and
places the result back into point. The multiplication treats the three-element
point as if its fourth element were 1. The second transform method postmulti-
plies this matrix by the Point3f point and places the result into pointOut.

public final void transform(Vector3f normal)

public final void transform(Vector3f normal, Vector3f normalOut)

The first transform method postmultiplies this matrix by the Vector3f normal
and places the result back into normal. The multiplication treats the three-ele-
ment vector as if its fourth element were 0. The second transform method post-
multiplies this matrix by the Vector3f normal and places the result into
normalOut.

public final void transform(Tuple4f vec)

public final void transform(Tuple4f vec, Tuple4f vecOut)

The first transform method postmultiplies this matrix by the tuple vec and
places the result back into vec. The second transform method postmultiplies
this matrix by the tuple vec and places the result into vecOut.

public final void negate()

public final void negate(Matrix4f m1)

The first method negates the value of this matrix in place (this = –this). The sec-
ond method sets the value of this matrix equal to the negation of the matrix m1
(this = –m1).

public final void invert()

public final void invert(Matrix4f m1)

The first method inverts this matrix in place. The second method sets the value of
this matrix to the inverse of the matrix m1.

public final float determinant()

The determinant method computes the determinant of the matrix this and
returns the computed value.

Version 1.2, March 2000 443

A.2.3 Matrix4f Class MATH OBJECTS

public final void rotX(float angle)

public final void rotY(float angle)
public final void rotZ(float angle)

The three rot methods construct rotation matrices that rotate in a counter-clock-
wise (right-handed) direction around the axis specified as the last letter of the
method name. The constructed matrix replaces the value of the matrix this. The
rotation angle is expressed in radians.

public final void mul(Matrix4f m1, Matrix4f m2)

public final void mul(Matrix4f m1)

The first mul method multiplies matrix m1 with matrix m2 and places the result
into the matrix this. The second mul method multiplies the matrix this with
matrix m1 and places the result in matrix this.

public final void mulTransposeBoth(Matrix4f m1, Matrix4f m2)

public final void mulTransposeRight(Matrix4f m1, Matrix4f m2)
public final void mulTransposeLeft(Matrix4f m1, Matrix4f m2)

The mulTransposeBoth method multiplies the transpose of matrix m1 (left) times

the transpose of matrix m2 (right) and places the result into this matrix. The mul-
TransposeRight method multiplies matrix m1 times the transpose of matrix m2
and places the result back into this matrix. The mulTransposeLeft method mul-
tiplies the transpose of matrix m1 times matrix m2 and places the result into this
matrix.

public boolean equals(Matrix4f m1)

public boolean equals(Object t1)

The first method returns true if all of the data members of Matrix4f m1 are equal
to the corresponding data members in this Matrix4f. The second method returns
true if the Object t1 is of type Matrix4f and all of the data members of t1 are
equal to the corresponding data members in this Matrix4f.

public boolean epsilonEquals(Matrix4f m1, float epsilon)

This method returns true if the L∞ distance between this Matrix4f and Matrix4f
m1 is less than or equal to the epsilon parameter. Otherwise, this method returns
false. The L∞ distance is equal to

MAX[i = 0,1,2,3; j = 0,1,2,3; abs(this.m(i,j) – m1.m(i,j)]

444 The Java 3D API Specification

MATH OBJECTS Matrix4d Class A.2.4

public int hashCode()

The hashCode method returns a hash number based on the data values in this
object. Two different Matrix4f objects with identical data values (that is,
equals(Matrix4f) returns true) will return the same hash number. Two
Matrix4f objects with different data members may return the same hash value,
although this is not likely.

public String toString()

The toString method returns a string that contains the values of this Matrix4f.

A.2.4 Matrix4d Class

The Matrix4d class serves to contain 4 × 4 matrices mainly for storing and
manipulating 3D transformation matrices. The class includes nine different con-
structors for creating matrices and several operators for manipulating these
matrices.

Variables
The component values of a Matrix4d are directly accessible through the public
variables m00, m01, m02, m03, m10, m11, m12, m13, m20, m21, m22, m23, m30, m31,
m32, and m33. To access the element in row 2 and column 0 of matrix rotate, a
programmer would write rotate.m20. A programmer would access the other
values similarly.

public double m00

public double m01
public double m02
public double m03
public double m10
public double m11
public double m12
public double m13
public double m20
public double m21
public double m22
public double m23
public double m30
public double m31
public double m32
public double m33

These public variables are the elements of the matrix.

Version 1.2, March 2000 445

A.2.4 Matrix4d Class MATH OBJECTS

Constructors

public Matrix4d(double m00, double m01, double m02, double m03,

double m10, double m11, double m12, double m13, double m20,
double m21, double m22, double m23, double m30, double m31,
double m32, double m33)
public Matrix4d(double v[])
public Matrix4d(Quat4d q1, Vector3d t1, double s)
public Matrix4d(Quat4f q1, Vector3d t1, double s)
public Matrix4d(Matrix3d m1, Vector3d t1, double s)
public Matrix4d(Matrix3f m1, Vector3d t1, double s)
public Matrix4d(Matrix4d m1)
public Matrix4d(Matrix4f m1)
public Matrix4d()

These constructors each return a new Matrix4d object. The first constructor gen-
erates a 4 × 4 matrix from the 16 values provided. The second constructor gener-
ates a 4 × 4 matrix from the first 16 values in the array v. The third through sixth
constructors generate a 4 × 4 matrix from the quaternion, translation, and scale
values. The scale is applied only to the rotational components of the matrix
(upper 3 × 3) and not to the translational components. The seventh and eighth
constructors generate a 4 × 4 matrix with the same values as the passed matrix.
The final constructor generates a 4 × 4 matrix with all 16 values set to 0.0.

Methods

public final void get(Matrix3d m1)

public final void get(Matrix3f m1)
public final double get(Matrix3d m1, Vector3d t1)
public final double get(Matrix3f m1, Vector3d t1)
public final void get(Quat4f q1)
public final void get(Quat4d q1)
public final void get(Vector3d trans)

The first two methods perform an SVD normalization of this matrix in order to
acquire the normalized rotational component. The values are placed into the
passed parameter. The next two methods perform an SVD normalization of this
matrix to calculate the rotation as a 3 × 3 matrix, the translation, and the scale.
None of the matrix values are modified. The next two methods perform an SVD
normalization of this matrix to acquire the normalized rotational component. The
last two methods retrieve the translational components of this matrix.

public final void setElement(int row, int column, double value)

public final double getElement(int row, int column)

446 The Java 3D API Specification

MATH OBJECTS Matrix4d Class A.2.4

The setElement and getElement methods provide a means for accessing a sin-
gle element within a 4 × 4 matrix using indices. This is not a preferred method of
access, but Java 3D provides these methods for functional completeness. The
setElement method takes a row index row (where a value of 0 represents the
first row and a value of 3 represents the fourth row), a column index column
(where a value of 0 represents the first column and a value of 3 represents the
fourth column), and a value. It sets the corresponding element in matrix this to
the specified value. The getElement method also takes a row index row and a
column index column and returns the element at the corresponding locations as a
floating-point value.

public final void setRow(int row, double x, double y, double z,

double w)
public final void setRow(int row, Vector4d v)
public final void setRow(int row, double v[])
public final void getRow(int row, Vector4d v)
public final void getRow(int row, double v[])

The three setRow methods provide a means for constructing a 4 × 4 matrix on a

row basis. The row parameter determines which row the method invocation
affects. A row value of 0 represents the first row and a value of 3 represents the
fourth row. The first setRow method specifies the four new values as independent
floating-point values. The second setRow method uses the values in the Vector4d
v to update the matrix. The third setRow method uses the first four values in the
array v to update the matrix. In all three cases the matrix affected is the matrix
this. The two getRow methods copy the matrix values in the specified row into
the array or vector parameter, respectively.

public final void setColumn(int column, double x, double y,

double z, double w)
public final void setColumn(int column, Vector4d v)
public final void setColumn(int column, double v[])
public final void getColumn(int column, Vector4d v)
public final void getColumn(int column, double v[])

The three setColumn methods provide a means for constructing a 4 × 4 matrix

on a column basis. The column parameter determines which column the method
invocation affects. A column value of 0 represents the first column and a value of
3 represents the fourth column. The first setColumn method specifies the four
new values as independent double-precision floating-point values. The second
setColumn method uses the values in the Vector4d v to update the matrix. The
third setColumn method uses the first four values in the array v to update the
matrix. In all three cases the matrix affected is the matrix this. The two getCol-

Version 1.2, March 2000 447

A.2.4 Matrix4d Class MATH OBJECTS

umn methods copy the matrix values in the specified column into the array or
vector parameter, respectively.

public final void setRotation(Matrix3f m1)

public final void setRotation(Matrix3d m1)

These methods set the rotational component (upper 3 × 3) of this matrix to the
matrix values in the passed argument. The other elements of this matrix are
unchanged. A singular value decomposition is performed on this object’s upper
3 × 3 matrix to factor out the scale, then this object’s upper 3 × 3 matrix compo-
nents are replaced by the passed rotation components, and finally the scale is
reapplied to the rotational components.

public final void setRotation(Quat4f q1)

public final void setRotation(Quat4d q1)

These methods set the rotational component (upper 3 × 3) of this matrix to the
matrix values in the passed argument. The other elements of this matrix are
unchanged. A singular value decomposition is performed on this object’s upper
3 × 3 matrix to factor out the scale, then this object’s upper 3 × 3 matrix compo-
nents are replaced by the matrix equivalent of the quaternion, and finally the
scale is reapplied to the rotational components.

public final void setRotation(AxisAngle4d a1)

This method sets the rotational component (upper 3 × 3) of this matrix to the
equivalent values in the passed argument. The other elements of this matrix are
unchanged. A singular value decomposition is performed on this object’s upper
3 × 3 matrix to factor out the scale, then this object’s upper 3 × 3 matrix compo-
nents are replaced by the matrix equivalent of the axis-angle, and finally the scale
is reapplied to the rotational components.

public final void getRotationScale(Matrix3f m1)

public final void getRotationScale(Matrix3d m1)
public final void setRotationScale(Matrix3d m1)
public final void setRotationScale(Matrix3f m1)

The two get methods retrieve the upper 3 × 3 values of this matrix and place
them into the matrix m1. The two set methods replace the upper 3 × 3 matrix
values of this matrix with the values in the matrix m1.

public final void setTranslation(Vector3d trans)

This method modifies the translational components of this matrix to the values of
the Vector3d argument. The other values of this matrix are not modified.

448 The Java 3D API Specification

MATH OBJECTS Matrix4d Class A.2.4

public final void setScale(double scale)

public final double getScale()

The first method sets the scale component of the current matrix by factoring out
the current scale (by doing an SVD) and multiplying by the new scale. The sec-
ond method performs an SVD normalization of this matrix to calculate and
return the uniform scale factor. If the matrix has non-uniform scale factors, the
largest of the x, y, and z scale factors will be returned.

public final void add(double scalar)

This method adds a scalar to each component of this matrix.

public final void add(double scalar, Matrix4d m1)

This method adds a scalar to each component of the matrix m1 and places the
result into this. Matrix m1 is not modified.

public final void mul(double scalar, Matrix4d m1)

This method multiplies each component of the matrix m1 by a scalar and places
the result into this. Matrix m1 is not modified.

public final void mul(double scalar)

This method multiplies each element of this matrix by a scalar.

public final void add(Matrix4d m1, Matrix4d m2)

public final void add(Matrix4d m1)
public final void sub(Matrix4d m1, Matrix4d m2)
public final void sub(Matrix4d m1)

The first add method adds the matrix m1 to the matrix m2 and places the result
into the matrix this. The second add method adds the matrix this to the matrix
m1 and places the result into the matrix this. The first sub method performs an
element-by-element subtraction of matrix m2 from matrix m1 and places the result
into the matrix this. The second sub method performs an element-by-element
subtraction of the matrix m1 from the matrix this and places the result into the
matrix this.

public final void set(double m[])

This method sets the value of this matrix to the row-major array parameter (that
is, the first four elements of the array will be copied into the first row of this
matrix, and so forth).

Version 1.2, March 2000 449

public final void set(Matrix3f m1)
public final void set(Matrix3d m1)

These methods set the rotational component (upper 3 × 3) of this matrix to the
matrix values in the matrix argument. The other elements of this matrix are ini-
tialized as if this were an identity matrix (that is, an affine matrix with no trans-
lational component).

public final void set(Matrix4f m1)

public final void set(Matrix4d m1)

These methods set the value of this matrix to the value of the passed matrix m1.

public final void set(Quat4d q1)

public final void set(Quat4f q1)

These methods set the value of this matrix to the matrix conversion of the quater-
nion argument.

public final void set(AxisAngle4d a1)

public final void set(AxisAngle4f a1)

These methods set the value of this matrix to the matrix conversion of the axis
and angle argument.

public final void set(Vector3d v1)

This method sets the value of this matrix to a translation matrix by the passed
translation value.

public final void set(Quat4d q1, Vector3d t1, double s)

public final void set(Quat4f q1, Vector3d t1, double s)
public final void set(Quat4f q1, Vector3f t1, float s)

These methods set the value of this matrix to the rotation expressed by the
quaternion q1, the translation t1, and the scale s.

public final void set(double scale)

This method sets the value of this matrix to a scale matrix with the passed scale
amount.

public final void set(double scale, Vector3d v1)

This method sets the value of this matrix to a scale and translation matrix. The
scale is not applied to the translation, and all of the matrix values are modified.
MATH OBJECTS Matrix4d Class A.2.4

public final void set(Vector3d v1, double scale)

This method sets the value of this matrix to a scale and translation matrix. The
translation is scaled by the scale factor, and all of the matrix values are modified.

public final void set(Matrix3f m1, Vector3f t1, float scale)

public final void set(Matrix3d m1, Vector3d t1, double scale)

These methods set the value of this matrix from the rotation expressed by the
rotation matrix m1, the translation t1, and the scale s.

public final void negate(Matrix4d m1)

public final void negate()

The first method sets the value of this matrix to the negation of the m1 parameter.
The second method negates the value of this matrix (this = –this).

public final void transpose(Matrix4d m)

public final void transpose()

The first transpose method transposes the matrix m and places the result into the
matrix this. The second transpose method transposes the matrix this and
places the result back into the matrix this.

public final void transform(Tuple4d vec)

public final void transform(Tuple4f vec)
public final void transform(Tuple4d vec, Tuple4d vecOut)
public final void transform(Tuple4f vec, Tuple4f vecOut)

The first two transform methods postmultiply this matrix by the tuple vec and
place the result back into vec. The last two transform methods postmultiply this
matrix by the tuple vec and place the result into vecOut.

public final void transform(Point3d point)

public final void transform(Point3f point)
public final void transform(Point3d point, Point3d pointOut)
public final void transform(Point3f point, Point3f pointOut)

The first two transform methods postmultiply this matrix by the point argument
point and place the result back into point. The multiplication treats the
three-element point as if its fourth element were 1. The last two transform
methods postmultiply this matrix by the point argument point and place the
result into pointOut.

public final void transform(Vector3d normal)

public final void transform(Vector3f normal)

Version 1.2, March 2000 451

A.2.4 Matrix4d Class MATH OBJECTS

public final void transform(Vector3d normal, Vector3d normalOut)

public final void transform(Vector3f normal, Vector3f normalOut)

The first two transform methods postmultiply this matrix by the vector argu-
ment normal and place the result back into normal. The multiplication treats the
three-element vector as if its fourth element were 0. The last two transform
methods postmultiply this matrix by the vector argument normal and place the
result into normalOut.

public final void invert()

public final void invert(Matrix4d m1)

The first method inverts this matrix in place. The second method sets the value of
this matrix to the inverse of the matrix m1.

public final double determinant()

The determinant method computes the determinant of the matrix this and
returns the computed value.

public final void rotX(double angle)

public final void rotY(double angle)
public final void rotZ(double angle)

The rot methods construct rotation matrices that rotate in a counter-clockwise

(right-handed) direction around the axis specified as the last letter of the method
name. The constructed matrix replaces the value of the matrix this. The rotation
angle is expressed in radians.

public final void mul(Matrix4d m1, Matrix4d m2)

public final void mul(Matrix 4d m1)

The first mul method multiplies matrix m1 with matrix m2 and places the result
into the matrix this. The second mul method multiplies matrix this with matrix
m1 and places the result into the matrix this.

public final void mulTransposeBoth(Matrix4d m1, Matrix4d m2)

public final void mulTransposeRight(Matrix4d m1, Matrix4d m2)
public final void mulTransposeLeft(Matrix4d m1, Matrix4d m2)

The mulTransposeBoth method multiplies the transpose of matrix m1 (left) times

the transpose of matrix m2 (right) and places the result into this matrix. The mul-
TransposeRight method multiplies matrix m1 times the transpose of matrix m2
and places the result back into this matrix. The mulTransposeLeft method mul-
tiplies the transpose of matrix m1 times matrix m2 and places the result into this
matrix.

452 The Java 3D API Specification

MATH OBJECTS GMatrix Class A.2.5

public final void setZero()

This method sets this matrix to all zeros.

public final void setIdentity()

This method sets this Matrix4d to identity.

public boolean equals(Matrix4d m1)

public boolean equals(Object t1)

The first method returns true if all of the data members of Matrix4d m1 are equal
to the corresponding data members in this Matrix4d. The second method returns
true if the Object t1 is of type Matrix4d and all of the data members of t1 are
equal to the corresponding data members in this Matrix4d.

public boolean epsilonEquals(Matrix4d m1, float epsilon)

Deprecated method. See the next method.

public boolean epsilonEquals(Matrix4d m1, double epsilon)

This method returns true if the L∞ distance between this Matrix4d and
Matrix4d m1 is less than or equal to the epsilon parameter. Otherwise, this
method returns false. The L∞ distance is equal to
MAX[i = 0,1,2,3; j = 0,1,2,3; abs(this.m(i,j) – m1.m(i,j)]

public int hashCode()

The hashCode method returns a hash number based on the data values in this
object. Two different Matrix4d objects with identical data values (that is,
equals(Matrix4d) returns true) will return the same hash number. Two
Matrix4d objects with different data members may return the same hash value,
although this is not likely.

public String toString()

The toString method returns a string that contains the values of this Matrix4d.

A.2.5 GMatrix Class

The GMatrix class serves to contain a double-precision, general, and dynami-
cally resizeable M × N matrix. Row and column numbering begins with zero.
The representation is row major.

Version 1.2, March 2000 453

A.2.5 GMatrix Class MATH OBJECTS

The GMatrix data members are not public, thus allowing efficient implementa-
tions of sparse matrices. However, the data members can be modified through
public accessors. The class includes three different constructors for creating
matrices and several operators for manipulating these matrices.

Constructors

public GMatrix(int nRow, int nCol)

public GMatrix(int nRow, int nCol, double matrix[])
public GMatrix(GMatrix matrix)

These constructors each return a new GMatrix. The first constructor generates an
nRow by nCol identity matrix. Note that because row and column numbering
begins with zero, nRow and nCol will be one larger than the maximum possible
matrix index values. The second constructor generates an nRow by nCol matrix
initialized to the values in the array matrix. The last constructor generates a new
GMatrix and copies the initial values from the parameter matrix argument.

Methods

public final void mul(GMatrix m1, GMatrix m2)

public final void mul(GMatrix m1)

The first mul method multiplies matrix m1 with matrix m2 and places the result
into this. The second mul method multiplies this matrix with matrix m1 and
places the result into this.

public final void add(GMatrix m1)

public final void add(GMatrix m1, GMatrix m2)
public final void sub(GMatrix m1)
public final void sub(GMatrix m1, GMatrix m2)

The first add method adds this matrix to matrix m1 and places the result back into
this. The second add method adds matrices m1 and m2 and places the result into
this. The first sub method subtracts matrix m1 from the matrix this and places
the result into this. The second sub method subtracts matrix m2 from matrix m1
and places the result into the matrix this.

public final void negate()

public final void negate(GMatrix m1)

The first method negates the value of this matrix in place (this = –this). The sec-
ond method sets the value of this matrix to the negation of the matrix m1 (this =
–m1).

454 The Java 3D API Specification

MATH OBJECTS GMatrix Class A.2.5

public final void invert()

public final void invert(GMatrix m1)

The first method inverts this matrix in place. The second method sets the value of
this matrix to the inverse of the matrix m1.

public final void setIdentity()

This method sets this GMatrix to the identity matrix.

public final void setZero()

This method sets all the values in this matrix to zero.

public final void identityMinus()

This method subtracts this matrix from the identity matrix and puts the values
back into this (this = I – this).

public final void copySubMatrix(int rowSource, int colSource,

int numRow, int numCol, int rowDest, int colDest,
GMatrix target)

This method copies a submatrix derived from this matrix into the target matrix.
The rowSource and colSource parameters define the upper left of the submatrix.
The numRow and numCol parameters define the number of rows and columns in
the submatrix. The submatrix is copied into the target matrix starting at (rowD-
est, colDest). The target parameter is the matrix into which the submatrix will
be copied.

public final void setSize(int nRow, int nCol)

This method changes the size of this matrix dynamically. If the size is increased,
no data values will be lost. If the size is decreased, only those data values whose
matrix positions were eliminated will be lost.

public final void set(double matrix[])

public final void set(GMatrix m1)
public final void set(Matrix3f m1)
public final void set(Matrix3d m1)
public final void set(Matrix4f m1)
public final void set(Matrix4d m1)

The first set method sets the values of this matrix to the values found in the
matrix array parameter. The values are copied in one row at a time, in
row-major fashion. The array should be at least equal in length to the number of
matrix rows times the number of matrix columns in this matrix. The second set

Version 1.2, March 2000 455

A.2.5 GMatrix Class MATH OBJECTS

method sets the values of this matrix to the values found in matrix m1. The last
four set methods set the values of this matrix to the values found in matrix m1.

public final void get(Matrix3d m1)

public final void get(Matrix3f m1)
public final void get(Matrix4d m1)
public final void get(Matrix4f m1)
public final void get(GMatrix m1)

The first two methods place the values in the upper 3 × 3 of this matrix into the
matrix m1. The next two methods place the values in the upper 4 × 4 of this
matrix into the matrix m1. The final method places the values in this matrix into
the matrix m1. Matrix m1 should be at least as large as this matrix.

public final int getNumRow()

public final int getNumCol()

The getNumRow method returns the number of rows in this matrix. The getNum-
Col method returns the number of columns in this matrix.

public final void setElement(int row, int column, double value)

public final double getElement(int row, int column)

These methods set and retrieve the value at the specified row and column of this
matrix.

public final void setRow(int row, double array[])

public final void setRow(int row, GVector vector)
public final void getRow(int row, double array[])
public final void getRow(int row, GVector vector)
public final void setColumn(int col, double array[])
public final void setColumn(int col, GVector vector)
public final void getColumn(int col, double array[])
public final void getColumn(int col, GVector vector)

The setRow methods copy the values from the array into the specified row of this
matrix. The getRow methods place the values of the specified row into the array
or vertex. The setColumn methods copy the values from the array into the spec-
ified column of this matrix or vector. The getColumn methods place the values of
the specified column into the array or vector.

public final void setScale(double scale)

This method sets this matrix to a uniform scale matrix, and all of the values are
reset.

456 The Java 3D API Specification

MATH OBJECTS GMatrix Class A.2.5

public final void mulTransposeBoth(GMatrix m1, GMatrix m2)

public final void mulTransposeRight(GMatrix m1, GMatrix m2)
public final void mulTransposeLeft(GMatrix m1, GMatrix m2)

The mulTransposeBoth method multiplies the transpose of matrix m1 (left) times

the transpose of matrix m2 (right) and places the result into this matrix. The mul-
TransposeRight method multiplies matrix m1 times the transpose of matrix m2
and places the result back into this matrix. The mulTransposeLeft method mul-
tiplies the transpose of matrix m1 times matrix m2 and places the result into this
matrix.

public final void transpose()

public final void transpose(GMatrix m1)

The first transpose method transposes this matrix in place. The second trans-
pose method places the matrix values of the transpose of matrix m1 into this
matrix.

public String toString()

This method returns a string that contains the values of this GMatrix.

public int hashCode()

This method returns a hash number based on the data values in this object. Two
different GMatrix objects with identical data values (that is, equals(GMatrix)
returns true) will return the same hash number. Two objects with different data
members may return the same hash value, although this is not likely.

public boolean equals(GMatrix m1)

public boolean equals(Object o1)

The first method returns true if all of the data members of GMatrix m1 are equal
to the corresponding data members in this GMatrix. The second method returns
true if the Object o1 is of type GMatrix and all of the data members of o1 are
equal to the corresponding data members in this GMatrix.

public boolean epsilonEquals(GMatrix m1, float epsilon)

Deprecated method. See the next method.

public boolean epsilonEquals(GMatrix m1, double epsilon)

This method returns true if the L∞ distance between this GMatrix and GMatrix
m1 is less than or equal to the epsilon parameter. Otherwise, this method returns
false. The L∞ distance is equal to

Version 1.2, March 2000 457

A.2.5 GMatrix Class MATH OBJECTS

MAX[i = 0,1,2, ... n; j = 0,1,2,... n; abs(this.m(i,j) – m1.m(i,j)]

public final double trace()

This method returns the trace of this matrix.

public final int SVD(GMatrix U, GMatrix W, GMatrix V)

The SVD method finds the singular value decomposition (SVD) of this matrix
such that this = U * W * VT, and returns the rank of this matrix. The values of
U, W, and V are all overwritten. Note that the matrix V is output as V and not VT.
If this matrix is m × n, then U is m × m, W is a diagonal matrix that is m × n, and
V is n × n. The inverse of this matrix is this–1 = V * W–1 * UT, where W–1 is a
diagonal matrix computed by taking the reciprocal of each of the diagonal ele-
ments of matrix W.

public final int LUD(GMatrix LU, GVector permutation)

The LUD method performs an LU decomposition. This matrix must be a square

matrix, and the LU parameter must be the same size as this matrix. The diagonal
elements of L (unity) are not stored. The permutation parameter records the
row permutation affected by the partial pivoting, and is used as a parameter to
the GVector LUDBackSolve method to solve sets of linear equations. This method
returns +1 or –1, depending on whether the number of row interchanges was
even or odd, respectively.

458 The Java 3D API Specification

 A PPE N D I X B
3D Geometry Compression

JAVA 3D allows programmers to specify geometry using a binary compressed

geometry format. This compression format is used with APIs other than just
Java 3D, and can be used both as a runtime in-memory format for describing geom-
etry, as well as a storage and network format. Eventually the full specification of
the compressed geometry format described in this section will be part of its own
stand-alone specification, but for completeness it is included as an appendix to the
early specification of the Java 3D API.
Java 3D uses a compressed geometry format that allows 3D geometry to be repre-
sented in an order of magnitude less space than most traditional 3D representations,
with very little loss in object quality. The compression is achieved through several
layers of techniques.
For a binary format to be useful as an interchange format, it is essential that the for-
mat be thoroughly and unambiguously documented. This appendix attempts to
completely specify all the details of the compressed geometry format. To ensure
current and future compatibility, it is essential to only use the features explicitly
specified in this document. For a binary format to be useful as an interchange for-
mat, it is essential that the format be thoroughly and unambiguously documented.
This appendix attempts to completely specify all the details of the Compressed
Geometry format. To insure current and future compatibility, it is essential to only
use the features explicitly specified in this document. Any features, fields, usage,
etc. not specified in the document should be considered illegal, and their usage
would result in invalid Compressed Geometry data. “Invalid” means that using
such a construct will be incompatible with current implementations or will break
future implementations. This document will point out many of the constructs that
would cause the data to be invalid.

Version 1.2, March 2000 459

B.1 Compression 3D GEOMETRY COMPRESSION

B.1 Compression
The process of geometry compression is as follows:
1. The geometry to be compressed is converted into a generalized mesh form,
which allows a triangle to be, on average, specified by 0.80 vertices.
2. The data for each vertex component of the geometry is converted to the
most efficient representation format for its type and then quantized to as
few bits as possible.
3. These quantized bits are differenced between successive vertices, and the
results are modified Huffman-encoded into self-describing variable-bit-
length data elements.
4. These variable-length elements are strung together using Compressed Ge-
ometry’s seven geometry instructions into a final Compressed Geometry
block.

B.2 Decompression
For pure software implementations, upon receipt, compressed geometry blocks are
decompressed into the local host’s preferred geometry format by reversing the
above process. This decompression can be performed in a lazy manner, avoiding
full expansion into memory until the geometry is needed for rendering.

B.3 Appendix Organization

Before the bit details of the compression can be specified, several of the concepts
used in compressed geometry need elaboration. The first several sections are an
expansion of our SIGGRAPH '95 paper on compressed geometry.1
• Generalized Triangle Strip. This section is a refresher on the concept and
semantics of a generalized triangle strip.
• Generalized Triangle Mesh. This section introduces the concept and se-
mantics of a generalized triangle mesh.
• Position Representation and Quantization. This section describes the
fixed-point format used for 3D positional representation.

1. Deering, Michael. “Geometry Compression.” Computer Graphics Proceedings, Annual

Conference Series, 1995, ACM SIGGRAPH, pp 13–19.

460 The Java 3D API Specification

3D GEOMETRY COMPRESSION Generalized Triangle Strip B.4

• Color Representation and Quantization. This section describes the fixed-

point format used for color representation.
• Normal Representation and Quantization. This section describes a novel
folded table based representation of surface normals, and the fixed-point
format of the resultant normals.
• Modified Huffman Encoding. This section describes the variant of Huff-
man delta encoding used for compressed geometry.
• Compressed Geometry Instructions. This section gives an overview of the
seven compressed geometry instructions.
• Semantics of Compressed Geometry Instructions. This section contains
pseudo code to document the detailed semantics of compressed geometry
instruction execution.
• Compressed Geometry Assembly Syntax. This section gives an overview of
the assembly syntax for compressed geometry instructions.

B.4 Generalized Triangle Strip

A generalized triangle strip is a generalization of the concept of a “zig-zag” and tri-
angle fan. It is a sequence of vertices in which each vertex contains a two-bit
replacement code. This replacement code defines how the present vertex is to be
combined with previous vertices to form the next triangle. The replacement bits can
also be thought of as a generalization of the “move/draw” bit used for lines.
A stack of the last three vertices used to form a triangle is kept. The three vertices
are labeled oldest, middle, and newest. An incoming vertex of type replace_old-
est causes the oldest vertex to be replaced by the middle, the middle to be replaced
by the newest, and the incoming vertex to become the newest. This corresponds to
a PHIGS PLUS triangle strip (sometimes called a “zig-zag” strip). The replace-
ment type replace_middle leaves the oldest vertex unchanged, replaces the mid-
dle vertex by the newest, and the incoming vertex becomes the newest. This
corresponds to a triangle fan.
The replacement type restart marks the oldest and middle vertices as invalid, and
the incoming vertex becomes the newest. Generalized triangle strips must always
start with this code. A triangle will be output only when a replacement operation
results in three valid vertices.
Restart corresponds to a “move” operation in polylines, and allows multiple
unconnected variable-length triangle strips to be described by a single data struc-
ture passed in by the user, greatly reducing the overhead. The generalized triangle

Version 1.2, March 2000 461

B.4 Generalized Triangle Strip 3D GEOMETRY COMPRESSION

strip’s ability to effectively change from “strip” to “fan” mode in the middle of a
strip allows more complex geometry to be represented compactly, and requires less
input data bandwidth. The restart capability allows several pieces of disconnected
geometry to be passed as one data block. Figure B-1 shows a single generalized tri-
angle strip and the associated replacement codes.
Triangles are normalized such that the front face is always defined by a counter-
clockwise vertex order after transformation (assuming a right-handed coordinate
system). To support this, there are two flavors of restart: restart (counterclock-
wise and restart_reverse (clockwise). The vertex order is reversed after every
replace_oldest, but remains the same after every replace_middle.

Vertex Codes 1 3 5
1 Restart
2 RO
3 RO
4 RO 2 4 6
5 RO Triangle Strip
6 RO
7 Restart 10 9
8 RO
9 RO 7
10 RM 11 8
11 RM 14
12 RM
Triangle Fan
13 RM
12 13
14 RM
15 Restart 15 17
16 RO
Independent
17 RO Triangle
18 Restart
19 RO
16
20 RO
21 RO 20 21
22 Restart
23 RO Independent
24 RO Quad
25 RO 18 19
26 RO
33
27 RO 31
28 RO 30
29 RM 32
30 RM 22 24 29
31 RM 26
32 RM
28
33 RO
23 25 27
RO = Replace Oldest
RM = Replace Middle Mixed Strip

Figure B-1 A Generalized Triangle Strip

462 The Java 3D API Specification

3D GEOMETRY COMPRESSION Generalized Triangle Mesh B.5

B.5 Generalized Triangle Mesh

The first stage of compressed geometry is to convert triangle data into an efficient
linear strip form: the generalized triangle mesh. This is a near-optimal representa-
tion of triangle data, given fixed storage.
The existing concept of a generalized triangle strip structure allows for compact
representation of geometry while maintaining a linear data structure. That is, the
geometry can be extracted by a single monotonic scan over the vertex array data
structure. This is very important for pipelined hardware implementations. A data
format that requires random access back to main memory during processing is very
problematic.
However, by confining itself to linear strips, the generalized triangle strip format
leaves a potential factor of two (in space) on the table. Consider the geometry in
Figure B-2.

2 2 2
2 2 3

1 1 2 2
2 2 2
1 1 1
1 1 1
7
6 9 1 1
Start 8
2 3
1 4 5
Generalized Triangle Strip
R6, O1, O7, O2, O3, M4, M8, O5, O9, O10, M11,
M17, M16, M9, O15, O8, O7, M14, O13, M6,
O12, M18, M19, M20, M14, O21, O15, O22, O16,
O23, O17, O24, M30, M29, M28, M22, O21, M20,
M27, O26, M19, O25, O18
Generalized Triangle Mesh
R6p, O1, O7p, O2, O3, M4, M8p, O5, O9p, O10, M11,
M17p, M16p, M-3, O15p, O-5, O6, M14p, O13p, M-9,
O12, M18p, M19p, M20p, M-5, O21p, O-7, O22p, O-
9,
O23, O-10, O-7, M30, M29, M28, M-1, O-2, M-3,
M27, O26, M-4, O25, O-5

Figure B-2 A Generalized Triangle Strip

Version 1.2, March 2000 463

B.5 Generalized Triangle Mesh 3D GEOMETRY COMPRESSION

While it can be represented by one triangle strip, many of the interior vertices
appear twice in the strip. This is inherent in any approach wishing to avoid refer-
ences to old data. Some systems have tried using a simple regular mesh buffer to
support reuse of old vertices, but there is a problem with this approach in practice:
In general, geometry does not come in a perfectly regular rectangular mesh struc-
ture.
The generalized technique employed by compressed geometry addresses this prob-
lem. Old vertices are explicitly pushed into a queue, and then explicitly referenced
in the future when the old vertex is desired again. This fine control supports irreg-
ular meshes of nearly any shape. Any viable technique must recognize that storage
is finite; thus the maximum queue length is fixed at 16, requiring a four-bit index.
We refer to this queue as the mesh buffer. The combination of generalized triangle
strips and mesh buffer references is referred to as a generalized triangle mesh.
The fixed mesh buffer size requires all tessellators or restripifiers for compressed
geometry to break up any runs longer than 16 unique references. Since compressed
geometry is not meant to be programmed directly at the user level, but rather by
sophisticated tessellators or reformatters, this is not too onerous a restriction. Six-
teen old vertices allow up to 94 percent of the redundant geometry to avoid being
respecified. Figure B-2 also contains an example of a general mesh buffer repre-
sentation of the surface geometry.
The language of compressed geometry supports the four vertex replacement codes
of generalized triangle strips (replace oldest, replace middle, restart, and restart
reverse), and adds another bit in each vertex header to indicate if this vertex should
be pushed into the mesh buffer or not. The mesh buffer reference instruction has a
four-bit field to indicate which old vertex should be re-referenced, along with the
two-bit vertex replacement code. The semantics of a mesh buffer reference is that
they do not have an option to re-push their data into the mesh buffer; old vertices
can only be recycled once.
Geometry rarely is composed purely of positional data; generally a normal and/or
color are also specified per vertex. Therefore, mesh buffer entries are required to
contain storage for all associated per-vertex information (specifically including
normals, and colors.
For maximum space efficiency, when a vertex is specified in the data stream, (per-
vertex) normal and/or color information should be directly bundled with the posi-
tion information. This bundling is controlled by two state bits: bundle normals with
vertices (bnv), and bundle colors with vertices (bcv). When a vertex is pushed into
the mesh buffer, these bits control whether its bundled normal and/or color are
pushed as well. During a mesh buffer reference instruction, this process is reversed.

464 The Java 3D API Specification

3D GEOMETRY COMPRESSION Position Representation and Quantization B.6

The two bits specify if a normal and/or color should be inherited from the mesh
buffer storage, or inherited from the current normal or current color.
There are explicit instructions for setting these two current values. An important
exception to this rule occurs when an explicit “set current normal” instruction is
followed by a mesh buffer reference, with the bnv state bit active. In this case, the
former overrides the mesh buffer normal. This allows compact representation of
hard edges in surface geometry. The analogous semantics are also defined for col-
ors, allowing compact representation of hard edges in images embeded as geome-
try.

B.6 Position Representation and Quantization

The 8-bit exponent of 32-bit IEEE floating-point numbers allows positions literally
to span the known universe: from a scale of 100 billion light years, down to the
radius of subatomic particles. However, for any given tessellated object the expo-
nent is really specified just once by the current modeling matrix; within a given
modeling space, the object geometry is effectively described with only the 24-bit
fixed-point mantissa. Visually, in many cases far fewer bits are needed; thus the
language of compressed geometry supports variable quantization of position data
down to as little as one bit. The maximum number of bits supported is at most 16
bits of precision per component of position.
We still assume that the position and scale of the local modeling spaces are speci-
fied by full 32-bit or 64-bit floating-point coordinates. If sufficient numerical care
is taken, multiple such modeling spaces can be stitched together without cracks,
forming seamless geometry coordinate systems with much greater than 16-bit posi-
tional precision.
Most geometry is local, so within the 16-bit (or less) modeling space (of each
object), the delta difference between one vertex and the next in the generalized
mesh buffer stream is very likely to be less than 16 bits in significance. Indeed one
can histogram the bit length of neighboring position deltas in a batch of geometry
and, based on this histogram, assign a variable-length code to compactly represent
the vertices. The typical coding used in many other similar situations is customized
Huffman code; this is the case for compressed geometry. The details of the coding
of position deltas will be postponed until later, where they can be discussed in the
context of color and normal delta coding as well.

Version 1.2, March 2000 465

B.7 Color Representation and Quantization 3D GEOMETRY COMPRESSION

B.7 Color Representation and Quantization

We treat colors similar to positions, but without using negative values. Thus RGBα
color data is first quantized to 15-bit unsigned fraction components, and a zero sign
bit added to form a 16-bit signed number. These are absolute linear reflectivity val-
ues, with 1.0 representing 100 percent reflectivity. An additional parameter allows
color data to be quantized effectively to any amount less than 16 bits; that is, the
colors can all be within a 5-5-5 RGB color space. (The α field is optional, con-
trolled by the color alpha present (cap) state bit.) Note that this decision does not
necessarily cause mach banding on the final rendered image; individual pixel col-
ors are still interpolated between these quantized vertex colors, and vertices also
are subject to lighting.
The same delta coding is used for color components as is used for positions. Com-
pression of color data is where compressed geometry and traditional image com-
pression face the most similar problem. However, many of the more advanced
techniques for image compression were rejected for geometry color compression
because of the difference in focus.
Image compression makes several assumptions about the viewing of the decom-
pressed data that cannot be made for compressed geometry. In image compression,
it is known a priori that the pixels appear in a perfectly rectangular array, and that
when viewed, each pixel subtends a narrow range of visual angles. In compressed
geometry, one has almost no idea what the relationship between the viewer and the
rasterized geometry will be.
In image compression, it is known that the spatial frequency of the displayed pixels
on the viewer’s eyes is likely higher than the human visual system’s color acuity.
This is why colors are usually converted to yuv space, so that the uv color compo-
nents can be represented at a lower spatial frequency than the y (intensity) compo-
nent.
Usually the digital bits representing the subsampled uv components are split up
among two or more pixels. Compressed geometry cannot take advantage of this
because the display scale of the geometry relative to the viewer’s eye is not fixed.
Also, given that compressed triangle vertices are connected to four to eight or more
other vertices in the generalized triangle mesh, there is no consistent way of sharing
“half” the color information across vertices.
Similar arguments apply for the more sophisticated transforms used in traditional
image compression, such as the discrete cosine transform. These transforms
assume a regular (rectangular) sampling of pixel values, and require a large amount
of random access during decompression.

466 The Java 3D API Specification

3D GEOMETRY COMPRESSION Normal Representation and Quantization B.8

B.8 Normal Representation and Quantization

Probably the most innovative concept in compressed geometry is the method of
compressing surface normals. Traditionally, 96-bit normals (three 32-bit IEEE
floating-point numbers) are used in calculations to determine 8-bit color intensi-
ties. Theoretically, 96 bits of information could be used to represent 296 different
normals, spread evenly over the surface of a unit sphere. This is a normal every 2–
46 radians in any direction. Such angles are so exact that spreading out angles
evenly in every direction from earth, you could point out any rock on Mars with
subcentimeter accuracy.
But for normalized normals, the exponent bits are effectively unused. Given the
constraint |N| = 1, at least one of Nx, Ny, or Nz must be in the range of 0.5 to 1.0.
During rendering, this normal will be transformed by a composite modeling orien-
tation matrix T: N' = N ⋅ T.
Assuming the typical implementation in which lighting is performed in world coor-
dinates, the view transform is not involved in the processing of normals. If the nor-
mals have been pre-normalized, then to avoid redundant renormalization of the
normals, the composite modeling transformation matrix T is typically pre-normal-
ized to divide out any scale changes, and thus
T0,02 + T1,02 + T2,02 = 1, etc.
During the normal transformation, floating-point arithmetic hardware effectively
truncates all additive arguments to the accuracy of the largest component. The
result is that for a normalized normal being transformed by a scale-preserving
modeling orientation matrix, the numerical accuracy of the transformed normal
value is reduced to no more than 24-bit fixed-point accuracy in all but a few special
cases.
Even 24-bit normal components are still much higher in angular accuracy than the
(repaired) Hubble space telescope. After empirical tests, it was determined that an
angular density of 0.01 radians between normals gave results that were not visually
distinguishable from finer representations. This works out to about 100,000 nor-
mals distributed over the unit sphere. In rectilinear space, these normals still
require high accuracy of representation; we chose to use 16-bit components that
include one sign and one guard bit.
This still requires 48 bits to represent a normal. But since we are only interested in
100,000 specific normals, in theory a single 17-bit index could denote any of these
normals. The next section shows how it is possible to take advantage of this obser-
vation.

Version 1.2, March 2000 467

B.8.1 Normals as Indices 3D GEOMETRY COMPRESSION

B.8.1 Normals as Indices

The most obvious hardware implementation for converting an index of a normal on
the unit sphere back into an Nx Ny Nz value is by table look-up. The problem is the
size of the table. Fortunately, several symmetry tricks can be applied to greatly
reduce the size of the table (by a factor of 48).
First, the unit sphere is symmetrical in the eight quadrants by sign bits. In other
words, if we let three of the normal representation bits be the three sign bits of the
XYZ components of the normal, then we only need to find a way to represent one
eighth of the unit sphere. The all positive sign bit octant of the unit sphere is shown
in bold outline on the left half of Figure B-3. This 000 sign bit octant will be
referred to as the prime octant.
Second, each octant of the unit sphere can be split up into six identical pieces by
folding about the planes X = Y, X = Z, and Y = Z. Such a division of the prime octant
is shown in Figure B-3. The six possible sextants are encoded with another three
bits. Now only 1/48 of the sphere remains to be represented.
This reduces the 100,000-entry look-up table by a factor of 48, requiring only about
2,000 entries, small enough to fit into an on-chip ROM look-up table. This table
needs 11 address bits to index into it, so including our previous two 3-bit fields, the
result is a grand total of 17 bits for all three normal components.
Representing a finite set of unit normals is equivalent to positioning points on the
surface of the unit sphere. While no perfectly equal angular density distribution
exists for large numbers of points, many near-optimal distributions exist. Thus in
theory one of these with the same sort of 48-way symmetry described above could
be used for the decompression look-up table. However, several additional con-
straints mandate a different choice of encoding:
• We desire a scalable density distribution in which zeroing more and more
of the low-order address bits to the table still results in fairly even density
of normals on the unit sphere. Otherwise a different look-up table for every
encoding density would be required.
• We desire a delta-encodable distribution. Statistically, adjacent vertices in
geometry will have normals that are nearby on the surface of the unit
sphere. Nearby locations on the 2D space of the unit-sphere surface are
most succinctly encoded by a 2D offset. We desire a distribution where
such a metric exists.
• Finally, while the computational cost of the normal encoding process is not
too important, in general, distributions with lower encoding costs are pre-
ferred.

468 The Java 3D API Specification

3D GEOMETRY COMPRESSION Normal Encoding Parameterization B.8.2

For all these reasons, we decided to use a regular grid in the angular space within
one sextant as our distribution. Thus, rather than a monolithic 11-bit index, all nor-
mals within a sextant are much more conveniently represented as two 6-bit orthog-
onal angular addresses, revising our grand total to 18 bits. Just as for positions and
colors, if more quantization of normals is acceptable, then these 6-bit indices can
be reduced to fewer bits, and thus absolute normals can be represented using any-
where from 18 to as few as 6 bits. But as will be seen, we can delta-encode this
space, further reducing the number of bits required for high-quality representation
of normals.

B.8.2 Normal Encoding Parameterization

Points on a unit radius sphere are parameterized by two angles, θ and φ, using
spherical coordinates. θ is the angle about the Y-axis; φ is the longitudinal angle
from the y = 0 plane. The mapping between rectangular and spherical coordinates
is as follows:

x = cos θ ⋅ cos φ y = sin φ z = sin θ ⋅ cos φ (B.1)

Note that many different incompatible definitions of spherical coordinates exist

within mathematics and engineering. For the purposes of compressed geometry,
spherical coordinates used are those defined by equation B.1.
Points on the sphere are folded first by octant, and then by sort order of xyz into one
of six sextants. All the table encoding takes place in the positive octant, in the
region bounded by the half spaces:
x≥z z≥y y≥0

This triangular-shaped patch runs from 0 to π/4 radians in θ, and from 0 to as much
as 0.615479709 radians in φ: φmax.
Quantized angles are represented by two n-bit integers θ̂ n and φ̂ n , where n is in the
range of 0 to 6. The sextant coordinate system defined by these parameters is shown
in Figure B-4, for the case of n = 6. For a given n, the relationship between these
indices θ and φ is

–1 n n
θ ( θ̂ n ) = sin ( tan ( φ max ⋅ ( 2 – θ̂ n ) ⁄ 2 ) )
(B.2)
n
φ(φ̂ n) = φ max ⋅ φ̂ n ⁄ 2

Version 1.2, March 2000 469

B.8.2 Normal Encoding Parameterization 3D GEOMETRY COMPRESSION

These two equations show how values of θ̂ n and φ̂ n can be converted to spherical
coordinates θ and φ, which in turn can be converted to rectilinear normal coordinate
components via equation B.1.
To reverse the process, for example, to encode a given normal n into θ̂ n and φ̂ n , one
cannot just invert equation B.2. Instead, the n must first be folded into the canonical
octant and sextant, resulting in n'. Then n' must be dotted with all quantized nor-
mals in the sextant. For a fixed n, the values of θ̂ n and φ̂ n that result in the largest
(nearest unity) dot product define the proper encoding of n.
Now the complete bit format of absolute normals can be given. The uppermost
three bits specify the sextant, the next three bits the octant, and finally two n-bit
fields specify θ̂ n and φ̂ n . The three-bit sextant field takes on one of six values, the
binary codes for which are shown in Figure B-3.

Y
Y>Z X<Y

Y=Z 001 011 X=Y

Y<Z
101 010 X>Y

X 100 000

Z
Z<Z X>Z
X=Z

Figure B-3 Encoding of the Six Sextants of Each Octant of a Sphere

This discussion has ignored some details. In particular, the three normals at the cor-
ners of the canonical patch are multiply represented (6, 8, and 12 times). By
employing the two unused values of the sextant field, these normals can be
uniquely encoded as special normals. The normal sub-instruction describes the
special encoding used for two of these corner cases (14 total special normals).
This representation of normals is amenable to delta encoding. Within a given sex-
tant, the delta code between two normals is simply the difference in θ̂ n and φ̂ n : ∆θ̂ n
and ∆φ ˆ n.

470 The Java 3D API Specification

3D GEOMETRY COMPRESSION Special Warping Rules for Delta Normals B.8.3

B.8.3 Special Warping Rules for Delta Normals

With some additional work, this can be extended to sextants that share a common
edge. First we must define how sextants border each other. Consider the three edges
of the sextant coordinate system as defined in Figure B-4, and also examine
Figure B-3 to see the sextant connectivity within an octant and between octants.
The three possible neighbors of a sextant are shown schematically in Figure B-5.

θ̂ n

64
001 011
56
101 010
48
100 000
40

32

24

16

0 φ̂ n
0 8 16 24 32 40 48 56 64

Figure B-4 Sextant Coordinates

The left edge of a sextant will always be another sextant within the same octant, as
will be the diagonal edge of a sextant. Note that the coordinate system of a sextant
is only defined for coordinate values in the triangular region of the sextant.
For a given value of n (in the range of 1 to 6), where n is the number of bits of quan-
tization of the sextant coordinates, the valid coordinates are bounded by θ̂ n ≥ 0, φ̂ n
≥ 0, and θ̂ n + φ̂ n ≤ 2n. For any given sextant number, the left and diagonal neighbors
of that sextant are explicitly known. The bottom edge of a sextant will be the same
sextant number, but in a different octant. The octant will differ from the current
octant by the flip of exactly one of the sign bits. Which octant sign bit will be
flipped is also explicitly known. The rules for finding each edge neighbor for any
sextant are given in Table B-1.

Version 1.2, March 2000 471

B.8.3 Special Warping Rules for Delta Normals 3D GEOMETRY COMPRESSION

Invert θ̂ n Diagonal
neighbor
update sextant 2n – θ̂ n and 2n – φ̂ n
update sextant
Left
neighbor Sextant

Bottom
neighbor
Flip one bit of octant number

Bottom

Figure B-5 Sextant Neighbors and Their Relationships

Table B-1 Sextant Neighbors

Sextant Left Neighbor Diagonal Neighbor Bottom Neighbor

sextant 000 sextant 100 sextant 010 flip octant y

sextant 001 sextant 101 sextant 011 flip octant x

sextant 010 sextant 011 sextant 000 flip octant z

sextant 011 sextant 010 sextant 001 flip octant z

sextant 100 sextant 000 sextant 101 flip octant y

sextant 101 sextant 001 sextant 100 flip octant x

In Compressed Geometry, all component delta fields and all component absolute
fields (except component absolute normal fields) are represented by signed num-
bers. For each different coordinate component type, there are different wrap rules
for what happens when a delta component overflows the absolute representation
range. For positions, both positive and negative component values are legal, and
overflowing past the largest positive component value is explicitly defined to wrap
the coordinate to negative values, and overflowing the most negative component
value wraps to the positive values. For colors, negative component values are ille-
gal, and wrapping out of the positive component values is illegal. For normals, spe-
cial wrapping rules allow delta values to change the current sextant or octant in
certain cases, without explicitly specifying the new sextant or octant.
The special rules for wrapping during normal deltas are:

472 The Java 3D API Specification

3D GEOMETRY COMPRESSION Modified Huffman Encoding B.9

• Normal Case:
if θ̂ n + ∆θ̂ n ≥ 0 , φ̂ n + ∆φ
ˆ n ≥ 0, θ̂ n + ∆θ̂ n + φ̂ + ∆φ
n
ˆ n ≤ 2n :
new θ̂ n ← θ̂ n + ∆θ̂ n , new φ̂ n ← φ̂ n + ∆φ ˆ n ,
current sextant and octant unchanged.
• Left Edge Wrap Case:
if θ̂ n + ∆θ̂ n < 0 , φ̂ n + ∆φ
ˆ n ≥ 0, -( θ̂ n + ∆θ̂ n ) + φ̂ + ∆φ
n
ˆ n ≤ 2n :
new θ̂ n ← −( θ̂ n + ∆θ̂ n ), new φ̂ n ← φ̂ n + ∆φ ˆ n ,
current sextant updated from left edge rules in Table B-1, current octant
unchanged.
• Diagonal Edge Wrap Case:
if θ̂ n + ∆θ̂ n ≥ 0 , φ̂ n + ∆φ
ˆ n ≥ 0, θ̂ n + ∆θ̂ n + φ̂ + ∆φ
n
ˆ n > 2n :
new θ̂ n ← 2n - ( θ̂ n + ∆θ̂ n ) , new φ̂ n ← 2n - ( φ̂ n + ∆φ
ˆ n),
current sextant updated from diagonal edge rules in Table B-1, current octant
unchanged.
• Bottom Edge Wrap Case:
if θ̂ n + ∆θ̂ n ≥ 0 , φ̂ n + ∆φ
ˆ n < 0, θ̂ n + ∆θ̂ n − ( φ̂ + ∆φ
n
ˆ n ) ≤ 2n :
new θ̂ n ← θ̂ n + ∆θ̂ n , new φ̂ n ← −( φ̂ n + ∆φ ˆ n),
current sextant unchanged, current octant updated from bottom edge rules in
Table B-1.
Any wrap that does not fall into one of these categories is an illegal delta, and is not
allowed within a valid Compressed Geometry stream.
(Note that while the wrapping is defined here in terms of a given normal component
quantization value n, in most implementations the wrapping would be applied after
the current component values and delta values have been normalized into the great-
est allowed values, e.g., n = 6.)

B.9 Modified Huffman Encoding

There are many techniques known for minimally representing variable-length bit
fields. For compressed geometry, we have chosen a variation of the conventional
Huffman technique.
The Huffman compression algorithm takes in a set of symbols to be represented,
along with frequency of occurrence statistics (histograms) of those symbols. From
this, variable-length, uniquely identifiable bit patterns are generated that allow
these symbols to be represented with a near-minimum total number of bits, assum-
ing that symbols do occur at the frequencies specified.

Version 1.2, March 2000 473

B.9 Modified Huffman Encoding 3D GEOMETRY COMPRESSION

Many compression techniques, including JPEG, create unique symbols as tags to

indicate the length of a variable-length data field that follows. This data field is typ-
ically a specific-length delta value. Thus the final binary stream consists of (self-
describing length) variable-length tag symbols, each immediately followed by a
data field whose length is associated with that unique tag symbol.
The binary format for compressed geometry uses this technique to represent posi-
tion, normal, and color data fields. For compressed geometry, these <tag, data>
fields are immediately preceded by (a more conventional computer instruction set)
opcode field. These fields, plus potential additional operand bits, are referred to as
geometry instructions (see Figure B-6).
Traditionally, each value to be compressed is assigned its own associated label; for
example, an XYZ delta position would be represented by three tag/value pairs.
However, the delta XYZ values are not uncorrelated, and we can get both a denser
and simpler representation by taking advantage of this fact.
In general, the XYZ deltas statistically point equally in all directions in space. This
means that if the number of bits to represent the largest of these deltas is n, then
statistically the other two delta values require an average of n – 1.4 bits for their
representation. Thus we made the decision to use a single field-length tag to indi-
cate the bit length of ∆X, ∆Y, and ∆Z.
This also means that we cannot take advantage of another Huffman technique that
saves somewhat less than one more bit per component, but our bit savings by not
having to specify two additional tag fields (for ∆Y and ∆Z) outweigh this. A single
tag field also means that a hardware decompression engine can decompress all
three fields in parallel, if desired.
Similar arguments hold for deltas of RGBα values, and so here also a single field-
length tag indicates the bit-length of the ∆R, ∆G, ∆B, and ∆α (if present) fields.
The u v index fields of both absolute normals and delta normals are also parame-
terized by a single value (n), which can be specified by a single tag.
We chose to limit the length of the Huffman tag field to the relatively small value
of six bits. This was done to facilitate high-speed, low-cost hardware implementa-
tions. (A 64-entry tag look-up table allows decoding of tags in one clock cycle.)
Three such tables exist: one each for positions, normals, and colors. The tables con-
tain the length of the tag field, the length of the data field(s), a data normalization
coefficient (the up-shift), and an absolute/relative bit.
The tag field can be 0 to 6 bits in length. Zero-length tags are used when every entry
in the table is identical; same data length, same up-shift, and same absolute/relative

474 The Java 3D API Specification

3D GEOMETRY COMPRESSION Bit Layout of Compressed Geometry Instructions B.11

bit. The tag becomes irrelevant because there is nothing to differentiate. In general,
there are only a few specialized cases where zero length tags are useful.
One additional complication was required to enable reasonable hardware imple-
mentations. As will be seen in a later section, all instructions are broken up into an
eight-bit header and a variable-length body. Sufficient information is present in the
header to determine the length of the body. But to give the hardware time to process
the header information, the header of one instruction must be placed in the stream
before the body of the previous instruction. Thus the sequence … B0 H1B1 H2B2
H3 … has to be encoded as follows:
… H1 B0 H2 B1 H3 B2 …
This header forwarding is applied to all instructions. The vertex instruction option-
ally had one or two sub-fields that need forwarded headers. In these special cases
the headers are only six bits in length, because no opcode is present.

B.10 Compressed Geometry Instructions

Java 3D’s compressed geometry protocol defines seven instructions to be used in
specifying 3D geometry and certain affiliated attributes. Table B-2 gives a brief
overview of these instructions and some of their semantics. More detail of these
instructions, including their bit layout, is given in the following sections.

B.11 Bit Layout of Compressed Geometry Instructions

Figure B-6 shows the bit-level layout of the seven geometry decompression
instructions. Each instruction has a unique opcode, and then some (usually fixed
number of) arguments. In the case of the setColor instruction, the number of argu-
ments can be either three or four, depending on the current setting of the cap bit
(set by the setState instruction). In the case of the vertex instruction, the number
of arguments also varies by the current setting of the setState instruction.
The actual bit length of many of the components may vary, and if so, a unique
(dynamic) Huffman tag at the very start of any variable-length argument indirectly
specifies the size of the argument.

Version 1.2, March 2000 475

B.12 Compressed Geometry Instruction Bit Details 3D GEOMETRY COMPRESSION

Table B-2 Compressed Geometry Instructions

Instruction Description
vertex The primary instruction is vertex. A vertex instruction always specifies a 3D position,
two generalized triangle strip replacement bits (rep), a mesh buffer push (mbp) bit,
and may optionally specify a normal and/or a color. The presence of normal or color
data within a vertex instruction is controlled by two state bits known as the bundling
bits: bnv and bcv, respectively.
setNormal, There are also two stand-alone instructions for specifying normals and colors:
setColor setNormal and setColor. These instructions may be freely interspersed with vertex
instructions, and semantically have (nearly) the same effect as normals or colors
bundled directly with a normal. Once a color or normal value is specified, either
directly or bundled with a vertex instruction, that color or normal will remain in effect
as the current color or normal until a new value is specified. In this fashion, for
example, a constant material color may be specified to apply to a forthcoming
sequence of non-color-bundled vertices
setState The setState instruction updates the value of the three state bits. Two of these bits are
the normal and color bundling bits; the third is color alpha bundling.
mbr Mesh buffer reference. The mbr instruction allows any of the 16 vertices most
recently pushed into the mesh buffer to be reused in place of a vertex instruction at
this point. Two vertex replacement bits are also present.
setTable The setTable instruction allows a range of entries in one of the three Huffman
decompression tables all to be set to the same new value.
no The variable length no-operation nop instruction allows the compression bit stream
to be padded by a specified number of bits. This allows portions of the compression
data to be 32-bit aligned when desired, as is required at the end of a Compressed
Geometry block.

B.12 Compressed Geometry Instruction Bit Details

The following subsections describe the bit details of the compressed geometry
instructions, and much of their associated semantics. Along with each instruction,
its assembly (and disassembly) syntax is described.

B.12.1 nop Instruction

0 0 0 0 0 0 0 1 Bit 0 – 31

Assembly syntax: (nop <Bit count>)

476 The Java 3D API Specification

3D GEOMETRY COMPRESSION setState Instruction B.12.2

The variable length no-operation (nop) instruction has an 8-bit opcode, a 5-bit
count field, and a 0- to 31-bit field of zeros. The total length of the variable-length
no-operation instruction is between 13 and 44 bits.
The variable-length nop instruction’s primary use is to align compressed geometry
instructions to word boundaries, when desired. This is useful if one wishes to
“patch” a compressed geometry instruction in the middle of a stream without hav-
ing to bit-align the patch.

B.12.2 setState Instruction

bn

bc
ca

0 0 0 1 1 0 0 0

Assembly syntax: (setState {normalsBundled}

{colorsBundled} {alphaBundled})

The setState instruction has a 7-bit opcode, 3 bits of state to be set, and a spare,
for a total length of 11 bits. The first and second state bits indicate if normals and/
or colors will be bundled with vertex instructions, respectively. The third state bit
indicates if colors will contain an alpha value, in addition to the standard RGB. The
final state bit is unused, and reserved for future use.
In the assembly syntax, the specific unbundling of a value is indicated by three
unbundling tags: {normalsUnbundled} {colorsUnbundled} {alphaUnbundled}.
The six possible bundling can be combined in almost any order. If a tag is not
present for either bundling or unbundling a value, then the value is implicitly
unbundled. It is an error to have both a bundled and unbundled tag present for the
same value in the same setState instruction.

Version 1.2, March 2000 477

B.12.2 setState Instruction 3D GEOMETRY COMPRESSION

vertex

mbp
Position bits 0 – 5 rep Position bits
0 1 6–n
Normal bits Color bits

setNormal
1 1 Normal bits 0 – 5 Normal bits 6 – n

setColor

1 0 Color bits 0 – 5 Color bits 6 – n

mbr (meshBufferReference)
rep

rep

0 0 1 Index

setState
cap
bnv

bcv

0 0 0 1 1 0 0 0

setTable

0 0 0 1 0 Table Entry
Address range
nop

0 0 0 0 0 0 0 1 Bit Count 0s

Position Tag ∆X ∆Y ∆Z

Tag Sextant Octant ^θ ^

φ
t t Absolute

Normal Tag ^
∆θ ^
∆φ
t t Relative

Tag 11 Special Absolute special

Color Tag ∆R ∆G ∆B ∆α

Figure B-6 Bit Layout of Compressed Geometry Instructions

478 The Java 3D API Specification

3D GEOMETRY COMPRESSION setTable Instruction B.12.3

B.12.3 setTable Instruction

0 0 0 1 0 Table Data Length A/R Up-shift

Address/Range

Assembly syntax: (setTable <Table> <start fill>-<end fill>

<Data Length> <Up-shift> <A/R>)

The setTable instruction has a 5-bit op code, a 2-bit table field, a 7-bit address/
range field, a 4-bit data length field, an absolute/relative bit, and a 4-bit up-shift
field. The total instruction length is fixed at 23 bits. The table and address/range
fields specify which decompression table entries to update; the remaining fields
comprise the values to which to update the table entries.
The two-bit table specifies for which of the three decompression tables this update
is targeted:
00 Position
01 Color
10 Normal
11 Unused—reserved for future use

The seven-bit address/range field specifies which entries in the specified table are
to be set to the values in the following fields.
Address/Range Semantics Implicit Tag
Length
1a5a4a3a2a1a0 set table entry a5a4a3a2a1a0 6
01a5a4a3a2a1 set table entry a5a4a3a2a10 through a5a4a3a2a11 5
001a5a4a3a2 set table entry a5a4a3a200 through a5a4a3a211 4
0001a5a4a3 set table entry a5a4a3000 through a5a4a3111 3
00001a5a4 set table entry a5a40000 through a5a41111 2
000001a5 set table entry a500000 through a511111 1
0000001 set table entry 000000 through 111111 0

The idea is that table settings are made in aligned power-of-two ranges. The posi-
tion of the first ‘1’ bit in the address/range field indicates how many entries are to
be consecutively set; the remaining bits after the first ‘1’ are the upper address bits
of the base of the table entries to be set. This also sets the length of the “tag” that
this entry defines as equal to the number of address bits (if any) after the first ‘1’ bit.

Version 1.2, March 2000 479

B.12.4 mbr (meshBufferReference) Instruction 3D GEOMETRY COMPRESSION

The data length specifies how large the delta values to be associated with this tag
are; a data length of 12 implies that the upper 4 bits are to be sign extensions of the
incoming delta value. Note that the data length describes not the length of the delta
value coming in, but the final position of the delta value for reconstruction. In other
words, the data length field is the sum of the actual delta bits to be read in plus the
up-shift amount. For the position and color tables, the data length values of 1 to 15
correspond to lengths of 1 to 15, but the data length value of 0 encodes an actual
length of 16, as a length of 0 makes no sense for positions and colors. For normals,
a length of 0 is sometimes appropriate, and the maximum length needed is only 7.
Thus for normals, the values 0 to 7 map through 0 to 7, and 8 to 15 are not used.
The up-shift value is the number of bits that the delta values described by these tags
will be shifted up before being added to the current value. The up-shift is useful for
quantizing the data to save space; it cannot be used to extend the range of the data
represented. You are still limited to 16 bits (less for normals) for the resultant data
even with a large up-shift value. The up-shift amount is essentially the number of
low bits that you don’t need to specify in the incoming data as they will always be
zero. It is illegal for the up-shift to be greater than or equal to the data length.
So, there are three portions of the resultant data: the sign extension, the incoming
data, and the up-shift. For example, if you have a position with a data length of 12
and an up-shift of 4, then the resultant data is made up of 4 sign extension bits in
the high bits, 8 bits of incoming data, and 4 bits of zero in the low bits, for the up-
shift.
The absolute/relative flag indicates whether this table entry describes values that
are to be interpreted as an absolute reference or a relative delta – a 0 value indicates
relative, a 1 value indicates absolute. Note that for normals, absolute references
will have an additional six leading bits describing the absolute octant and sextant.

B.12.4 mbr (meshBufferReference) Instruction

rep

rep

0 0 1 Index

Assembly syntax: (mbr <rep> <index>)

Assembly syntax: <rep>:
RST Restart counterclockwise
RSTR Restart clockwise
RMID Replace middle

480 The Java 3D API Specification

3D GEOMETRY COMPRESSION mbr (meshBufferReference) Instruction B.12.4

ROLD Replace oldest

The mbr (meshBufferReference) instruction has a 3-bit opcode, a 4-bit mesh

buffer index field, and a 2-bit vertex replacement field, for a total length of nine
bits.
The index specifies which element of the mesh buffer should be used to define the
current vertex. A value of 0 indicates to use the most recent vertex that has been
pushed into the mesh buffer (before this instruction). Larger values indicate succes-
sively less recent pushes. Only the most recent 16 pushes are addressable.
The two-bit vertex replacement field has the same triangle semantics as it does
within the vertex instruction:
00 Restart clockwise
01 Restart counterclockwise
10 Replace middle
11 Replace oldest

There is no mesh buffer re-push bit; mesh buffer contents may be referenced mul-
tiple times until 16 newer vertices have been pushed; if a vertex is still needed it
must be resent.
In general, the semantics of executing a mesh buffer reference instruction is nearly
the same as executing a vertex instruction with data fields identical to those con-
tained at the indicated mesh buffer location. There are, however, several subtle dif-
ferences. First, as previously indicated, a mesh buffer reference never causes new
values to appear in the mesh buffer; nor does it cause any mesh buffer values to go
away.
Second, the effects of any intervening setState instructions changing the bundling
bits need to be considered. If normals were bundled when the vertex was original
pushed into the mesh buffer, but normals are not bundled when the mbr instruction
is executed, the old normal value does not replace the current normal value.
Instead, the mbr instruction will use the current setting of the normal value. The
same logic applies to colors and alpha. A mbr instruction only access the mesh
buffer for those vertex components that are currently bundled.
The inverse case is considered an error: if normals were not bundled at the time the
vertex instruction pushed a vertex into the mesh buffer, but normals are bundled at
the time of execution of the mbr instruction, the normal value will be undefined.
Such a sequence will result in an invalid Compressed Geometry object. Once
again, the same logic applies for colors. A push in a vertex instruction causes only
the currently bundled vertex components to be stored into the mesh buffer.
Version 1.2, March 2000 481
B.12.5 Position Sub-instruction 3D GEOMETRY COMPRESSION

There is one more special case: when normals are bundled, if a setNormal instruc-
tion was executed before a mbr instruction, and the instructions executed between
these two do not include any vertex or setState (or mbr) instructions, the semantics
of normal override apply. The semantics is that rather than inheriting all the data
fields of the vertex from the stored mesh buffer values, the normal value is instead
taken from the current normal value, as set by the setNormal instruction. This is to
allow for hard edges in otherwise shared geometry. The idea is that otherwise there
is no logical reason for a setNormal instruction that would have been invalidated
by the inheritance within the mbr instruction. Once again, a similar logic applies to
setColor instructions, and the generation of a color override condition. This sup-
ports hard edges in colors. Note that any overrides are invalidated by setState or
vertex instructions, and also are no longer in effect after a mbr instruction is
encountered.
Another effect of overrides is to override the invalidity of normals or colors having
not been bundled with vertices at the time of vertices being pushed into the mesh
buffer.

B.12.5 Position Sub-instruction

0–6 1–16 1–16 1–16

Tag ∆X ∆Y ∆Z

Assembly syntax: (Position <Tag> <∆X> <∆Y> <∆Z>)

The position sub-instruction can only appear within a compressed geometry ver-
tex instruction, and always as the first sub-instruction. The tag field can be between
0 and 6 bits in length; all three delta (or absolute) fields will have the same length,
between 1 and 16 bits, for a range of lengths between 3 and 54 bits.
As usual, the first six bits of the sub-instruction are actually forwarded ahead of the
rest of the instruction. Depending on the length of the tag and delta fields, the first
6 bits might only contain the tag, or the tag and some of the X field bits, or any sub-
set up to the entire sub-instruction, if short enough. However, it is possible for the
entire sub-instruction to be too short. It is not allowed for the tag together with the
X, Y, and Z fields to be smaller than the six bits that gets forwarded ahead. There
can be no “empty” bits in the forwarded header. If necessary, the tag and/or delta
(or absolute) fields must be expanded so that the total number bits used for the
entire sub-instruction is at least six. (Note that the expanded fields must be cor-
rectly described in the decompression table entry for the tag. On cannot simply add
padding within a position sub-instruction to a field the was previously specified
with a shorter length in a setTable instruction.)

482 The Java 3D API Specification

3D GEOMETRY COMPRESSION Color Sub-instruction B.12.6

For clarity, because it is by far the most typical case, the three coordinate bit fields
are labeled ∆X ∆Y ∆Z, though more properly they are X, Y, and Z fields; their
actual interpretation is absolute or relative depending on the setting of that bit in
the decompression table entry corresponding to the tag field. In both cases the
fields are signed two’s-complement numbers.
You must always specify at least one absolute position before using any relative
positions. It is illegal to have a relative position before the first absolute position.
It appears that, depending on the current position, half of the possible delta values
are illegal. (For ease of understanding these examples, we will treat positions as
integers.) For instance, going +10,000 from 30,000 will wrap past the positive limit
of 32,767 for signed 16-bit two’s complement arithmetic. However, this turns out
to be very useful. For example, if your current X position is –20,000 and the next
X position is 30,000 then the difference that you’d like to use as a delta is +50,000,
which is not directly representable. When you compute that difference using 16-bit
arithmetic, the value wraps to –15,536, which can be represented as a delta. When
–15,536 is added back to –20,000 on decompression, instead of getting –35,536,
again the 16-bit arithmetic wraps and we get 30,000, which is the desired result.

B.12.6 Color Sub-instruction

0–6 1–16 1–16 1–16 1–16

Tag ∆R ∆G ∆B ∆α

Assembly syntax: (Color <Tag> <∆R> <∆G> <∆B> {<∆α>})

The color sub-instruction can appear within either a compressed geometry vertex
instruction or setColor instruction. The tag field can be between 0 and 6 bits in
length; all three (or four) delta (or absolute) fields will have the same length,
between 1 and 16 bits, for a range of lengths between 3 and 54 (or 70) bits. As
usual, any sub-instruction with a total length of less than 6 bits has trailing zeros
added to pad the length to a minimum of 6 bits.
As usual, the first six bits of the sub-instruction are actually forwarded ahead of the
rest of the instruction. Depending on the length of the tag and delta fields, the first
six bits might only contain the tag, or the tag and some of the R field bits, or any
subset up to the entire sub-instruction, if short enough. However, it is possible for
the entire sub-instruction to be too short. It is not allowed for the tag together with
the R, G, and B (and α) fields to be smaller than the six bits that gets forwarded
ahead. There can be no “empty” bits in the forwarded header. If necessary, the tag

Version 1.2, March 2000 483

B.12.7 Normal Sub-instruction 3D GEOMETRY COMPRESSION

and/or delta (or absolute) fields must be expanded so that the total number bits used
for the entire sub-instruction is at least six.
For clarity, because it is by far the most typical case, the color component bit-fields
are labeled ∆R ∆G ∆B (∆α), though more properly they are R, G, and B fields; their
actual interpretation is absolute or relative depending on the setting of that bit in
the decompression table entry corresponding to the tag field. In both cases the
fields are signed two’s-complement numbers. A sign bit is required for absolute
color components. Negative color components make no sense and are ill-defined,
so the sign bit on absolute components should always be zero. Similarly for delta
color components, a negative result from adding a delta component to the current
component makes no sense, and so negative results are also ill-defined.
If the most recent setting of the cap bit by a setState instruction is zero, then no
fourth (alpha) field will be expected, and must not be present. If the cap bit was set,
then the alpha field will be processed and must be present.
You must always specify at least one absolute color before using any relative col-
ors. It is illegal to have a relative color before the first absolute color.
The rest of the graphics pipeline and frame buffer following the geometry decom-
pression stage may choose not to use all (up to) 16 bits of color component infor-
mation; in this case it is acceptable to truncate the trailing bits during
decompression. What the geometry decompression format does require is that
color setting of any size up to 16 bits be supported, even if all the bits are not used.
Typically, implementations may use just 12 bits, 8 bits, or even 5 bits from each
color component.

B.12.7 Normal Sub-instruction

0–6 0–7 0–7

Normal (relative) Tag ∆ θ̂ n ∆ φ̂ n

0–6 3 3 0–6 0–6

Normal (absolute) Tag Sextant θ̂ n φ̂ n

0–6 4
Normal (absolute
Tag 11 Special
special)

Assembly syntax: absolute: (Normal <Tag><Sextant><Octant>< θ̂ n >< φ̂ n >)

484 The Java 3D API Specification

3D GEOMETRY COMPRESSION Normal Sub-instruction B.12.7

Assembly syntax: relative: (Normal <Tag> <∆ θ̂ n > <∆ φ̂ n >)

Assembly syntax: special: (Normal <Tag> <Special>)
Assembly syntax: <Sextant>: 0,1,2,3,4,5 (as specified in Figure B-3)
Assembly syntax: Table B-3 below shows the assembly format for specifying
octants in the <octant> field of Normal sub-instructions (as well as setNormal
instructions).
Table B-3 Syntax for Specifying Octants
Syntax Octant
+++ +X +Y +Z
++- +X +Y –Z
+-+ +X –Y +Z
+-- +X –Y –Z
-++ –X +Y +Z
-+- –X +Y –Z
--+ –X –Y +Z
--- –X –Y –Z

Assembly syntax: Table B-4 below shows the assembly syntax for specifying the
special normals in the “Special” field of Normal sub-instructions (as well as set-
Normal instructions).
Table B-4 Syntax for Specifying Special Normals
Syntax Special NX NY NZ Comment
+00 0000 1.0 0.0 0.0 +X axis
-00 0010 –1.0 0.0 0.0 –X axis
0+0 0100 0.0 1.0 0.0 +Y axis
0-0 0110 0.0 –1.0 0.0 –Y axis
00+ 1000 0.0 0.0 1.0 +Z axis
00- 1010 0.0 0.0 –1.0 –Z axis
+++ 0001 1 ⁄ 3 1 ⁄ 3 1 ⁄ 3 +X +Y +Z
++- 0011 1 ⁄ 3 1 ⁄ 3 1 ⁄ 3 +X +Y –Z
+-+ 0101 1 ⁄ 3 1 ⁄ 3 1 ⁄ 3 +X –Y +Z
+-- 0111 1 ⁄ 3 1 ⁄ 3 1 ⁄ 3 +X –Y –Z
-++ 1001 1 ⁄ 3 1 ⁄ 3 1 ⁄ 3 –X +Y +Z
-+- 1011 1 ⁄ 3 1 ⁄ 3 1 ⁄ 3 –X +Y –Z

Version 1.2, March 2000 485

B.12.7 Normal Sub-instruction 3D GEOMETRY COMPRESSION

Table B-4 Syntax for Specifying Special Normals (Continued)

Syntax Special NX NY NZ Comment
--+ 1101 1 ⁄ 3 1 ⁄ 3 1 ⁄ 3 –X –Y +Z
--- 1111 1 ⁄ 3 1 ⁄ 3 1 ⁄ 3 –X –Y –Z

The Normal sub-instruction can appear within either a compressed geometry ver-
tex instruction or setNormal instruction. The tag field can be between 0 and 6 bits
in length; the last two angle fields will have the same length, between 0 and 7 bits
for deltas and between 0 and 6 bits for absolutes. Six more bits are always present
for absolute normals. The range of sizes for a relative normal can be from 6 to 20
bits, and an absolute normal can be from 6 to 24 bits.
As usual, the first six bits of the sub-instruction are actually forwarded ahead of the
rest of the instruction. Depending on the length of the tag and delta fields, the first
six bits might only contain the tag, or the tag and some of the other field bits, or any
subset up to the entire sub-instruction, if short enough. However, in the case of rel-
ative normals, it is possible for the entire sub-instruction to be too short. It is not
allowed for the tag together with the delta angle fields to be smaller than the six bits
that gets forwarded ahead. There can be no “empty” bits in the forwarded header.
If necessary, the tag and/or delta angle fields must be expanded so that the total
number bits used for the entire sub-instruction is at least six.
A Normal sub-instruction is interpreted as relative or absolute depending on the
current setting of that bit in the decompression table entry corresponding to the tag
field. Unlike the Position and Color sub-instructions, the number of fields of a
Normal instruction differ between the absolute and relative types.

When the sub-instruction is relative, there are two delta angle fields after the tag
field, both of the same length, up to seven bits. These two fields are signed two’s-
complement numbers. If after delta addition the resulting angle is outside the cur-
rent sextant or octant, the sextant/octant wrapping rules (described elsewhere)
apply. If zero-length angle fields are specified, this is equivalent to specifying a
zero value for both fields, i.e., no change from the previous normal. It may be easier
to use this method rather than turning off normal bundling for a small number of
identical normals.
When the sub-instruction is absolute, four bit fields follow the tag. The first is a
three-bit (fixed-length) absolute sextant field, indicating in which of six sextants of
an octant of the unit sphere this normal resides. The second field is also fixed at
three bits, and indicates in which octant of the unit sphere the normal resides. The
last two fields are absolute angles within the sextant, and are unsigned positive
numbers, up to six bits in length. If zero-length angle fields are specified, this is
equivalent to specifying a zero for both fields.

486 The Java 3D API Specification

3D GEOMETRY COMPRESSION Normal Sub-instruction B.12.7

At least one absolute normal must be specified before using any relative normals.
It is an error to have any relative normals before the first absolute normal.
Note that sextants are triangular in shape, thus range of valid angular coordinates
within a sextant fills only half the square, plus the diagional. Formally, after shift
normilization, angular coordinates in ordinary absolute normals must obey the
rule:
θ̂ 6 + φ̂ 6 ≤ 64, 0 ≤ θ̂ 6 < 64, 0 ≤ φ̂ 6 < 64

A number of normals lie on the edges or corners where sextants meet (e.g., at θ̂ n =
0 and φ̂ n = 0). These normals do not have a unique encoding; the same normal can
be specified using different sextants or octants. All of these encodings are legal;
usually the choice of encoding is decided by using the one that makes it the eaisest
to compute deltas from the previous and/or to the following normal.
Fourteen special absolute normals are encoded by the unused two settings within
the three sextant bits. This is indicated by specifying the angle fields to have a
length of zero (not present), and the first two bits of the sextant field to both have a
value of 1. Table B-5 lists the 14 special normals
Table B-5 The 14 Special Normals
Special NX NY NZ Comment
0000 1.0 0.0 0.0 +X axis
0010 –1.0 0.0 0.0 –X axis
0100 0.0 1.0 0.0 +Y axis
0110 0.0 –1.0 0.0 –Y axis
1000 0.0 0.0 1.0 +Z axis
1010 0.0 0.0 –1.0 –Z axis
0001 1⁄ 3 1⁄ 3 1⁄ 3 +X +Y +Z
0011 1⁄ 3 1⁄ 3 1⁄ 3 +X +Y –Z
0101 1⁄ 3 1⁄ 3 1⁄ 3 +X –Y +Z
0111 1⁄ 3 1⁄ 3 1⁄ 3 +X –Y –Z
1001 1⁄ 3 1⁄ 3 1⁄ 3 –X +Y +Z
1011 1⁄ 3 1⁄ 3 1⁄ 3 –X +Y –Z
1101 1⁄ 3 1⁄ 3 1⁄ 3 –X –Y +Z
1111 1⁄ 3 1⁄ 3 1⁄ 3 –X –Y –Z

Special normals are always absolute normals; they cannot be delta’d to from a pre-
vious normal. Unlike ordinary absolute normals, delta normals have the additional
restriction that they cannot be delta’d from. Thus the next normal after any special

Version 1.2, March 2000 487

B.12.8 vertex Instruction 3D GEOMETRY COMPRESSION

normal must always be an absolute normal (ordinary or special). In some cases this
overhead can be avoided by avoiding ever landing on a special normal, when this
purtibation of the data is does not negitively impact the visual apperance of the
object.
The rest of the graphics pipeline and frame buffer following the geometry decom-
pression stage may choose not to use all (up to) 16 bits of normal component infor-
mation; in this case it is acceptable to truncate the trailing bits during
decompression. What the compressed geometry format does require is that normal
settings of any size up to 18-bit absolute normals be supported, even if all the
decompressed bits are not used.

B.12.8 vertex Instruction

mbp

Position bits 0 – 5 rep Position bits

0 1 6–n
Normal bits Color bits

Assembly syntax: (vertex <rep> {push}

<position sub-instruction>
{<normal sub-instruction>}
{<color sub-instruction>})

Assembly syntax: <rep>:

RST Restart counterclockwise
RSTR Restart clockwise
RMID Replace middle
ROLD Replace oldest

The vertex instruction has a two-bit opcode, a position sub-instruction (always),

a two-bit vertex replacement field, a mesh buffer push bit, and, optionally, a normal
sub-instruction and/or a color instruction, depending on the current setting of the
state bundling bits. The two-bit vertex replacement field has the same triangle
semantics as it does within the mbr instruction:
00 Restart clockwise
01 Restart counterclockwise
10 Replace middle
11 Replace oldest

The mesh buffer push bit indicates whether this vertex should be pushed into the
mesh buffer so as to be eligible for later re-reference.

488 The Java 3D API Specification

3D GEOMETRY COMPRESSION setColor Instruction B.12.10

The Position, Normal, and Color sub-instructions have the semantics docu-
mented in their individual sections.

B.12.9 setNormal Instruction

1 1 Normal bits 0 – 5 Normal bits 6 – n

Assembly syntax: absolute: (setNormal <Tag> <Sextant> <Octant>

< θ̂ n > < φ̂ n >)

Assembly syntax: relative: (setNormal <Tag> < ∆θ̂ n > < ∆φ̂ n >)
Assembly syntax: absolute special: (setNormal <Tag> <Special>)
Assembly syntax: <Sextant>, <Octant>, <Special>: same as for normal sub-
instruction.
The setNormal instruction has a two-bit opcode, and a Normal sub-instruction.
The Normal sub-instruction has the semantics documented in Section B.12.7,
“Normal Sub-instruction.”
If a SetNormal instruction is present immediately before a mbr instruction, then the
new normal value overrides the normal data present in the mesh buffer for that par-
ticular mesh buffer reference.

B.12.10 setColor Instruction

1 0 Color bits 0 – 5 Color bits 6 – n

Assembly syntax: (setColor <Tag> <∆R> <∆G> <∆B> {<∆α>})

The setColor instruction has a two-bit opcode, and a color sub-instruction. The
color sub-instruction semantics are documented in Section B.12.6, “Color Sub-
instruction.”
If a setColor instruction is present immediately before a mbr (meshBufferRefer-
ence) instruction, then the new color value overrides the color data present in the
mesh buffer for that particular mesh buffer reference.

Version 1.2, March 2000 489

B.13 Semantics of Compressed Geometry Instructions 3D GEOMETRY COMPRESSION

B.13 Semantics of Compressed Geometry Instructions

The formal semantics of the compressed geometry format is best described by a
state description of the decompression process. It must be emphasized that these
state descriptions are given to show the formal semantics, not an efficient imple-
mentation.
The next few sections will present such a state description. While this description
is intended to be a complete and unambiguous description of the compressed
geometry format and decompression semantics, in practice studying both the com-
pression process and the decompression process, and studying code examples for
both, is a better approach for the human understanding process.

B.13.1 Header and Body to Variable-Length Instruction

Compressed geometry instructions have a minimum length of eight bits (six bits
for sub-instructions). This allows all geometry decompression instructions to be
split into two physically separate bit sequences within the compressed stream. The
first bit sequence is always of eight bits in length (six for sub-instructions), the sec-
ond bit sequence contains the remaining bits of the instruction (if any). Thus a log-
ical stream of N compressed geometry instructions, where each instruction is split
into two bit sequences Hi and Bi (i being from 0 to N – 1) is physically represented
as:
H0 B–1 H1 B0 H2 B1 … Hn–1 Bn–2 Hn Bn–1
Okay, so what is this “B–1”? All compressed geometry sequences have an implied
(not physically present) H–1 of a nop opcode, thus B–1 is always present (starting
at the eighth bit of the stream) as any valid variable-length nop body. (Just five
zeros, the minimum-length nop, is a good default.) Thus the implied nop opcode
“jump starts” the header-forwarded decompression process. This process is
reversed at the end of the stream. Hn is a nop opcode, but no body is present, as Bn–
1 is the last bits of the stream. (As will be described below, Bn–1 must end on a 32-
bit aligned boundary.)
This is viable because all compressed geometry streams are presented along with
a total bit length of their contents, so no explicit end-of-stream marker is needed.
Streams must be rounded up to the nearest full 64-bit word multiple by use of addi-
tional variable-length nop instructions of appropriate lengths (within the body of
the stream, that is, their headers appear before Hn). This implies that Hn–1 is usually
a nop instruction used to force alignment.
This “header-forwarding” shuffled representation is necessary for hardware
decompressors to operate efficiently. While this is not an issue for purely software-
490 The Java 3D API Specification
3D GEOMETRY COMPRESSION Variable-Length Instruction to Instruction B.13.2

based decompressor implementations, in order to have one canonical format for

both hard and soft decompressors, all decompressors must operate only on the
header-forwarded representation; this is the only “official” compression bit-format
specified. For a software decompressor, the extra unshuffling adds only slightly to
the overall overhead of decompression; for hardware, it is essential.
Thus the first stage in the decompression process is to put the two separate bit
sequences for each instruction back together. The next paragraph describes the fla-
vor of this process, going around the loop approximately one and one-half times.
The actual process is more accurately described in state machine semantics.
First the fixed-length eight- (or six-) bit header for the next full instruction (or sub-
instruction) to be processed is detached from the current head of the compressed
stream. Next, the variable-length body bits for the previous instruction (or sub-
instruction) are detached from the compressed stream and combined with the
already extracted header for the previous instruction; the previous instruction is
now complete and can be processed. Now the fixed-length header for the instruc-
tion after the next is detached from the bit stream, and then finally the variable-
length body for the next full instruction can be detached; the next instruction is now
complete and can be processed.

// pseudocode for converting bitstream into sequences of

// instructions
decompress(stream) {
current_header <- nop
while (not_empty(stream)) {
next_header <- get_header_bits(stream)
current_body <- get_n_bits(stream,
body_length(previous_header))
process_instruction(current_header, current_body)
current_header <- next_header
}
}

One slight complexity: the get_header_bits() only extracts six bits of header for
color or normal sub-instructions of a vertex instruction. It extracts a full eight
bits of header in all other cases.

B.13.2 Variable-Length Instruction to Instruction

The three decompression tables contain entries for each different numeric tag
describing whether the value in the stream is absolute or relative, and length and
shift constants describing how to convert the variable-length bit field back into a

Version 1.2, March 2000 491

B.13.3 Delta Position to Position 3D GEOMETRY COMPRESSION

fixed-length value. The fixed-length value for position and color components is 16
bits in length (sign, unit, 14 fraction); the fields for normal angles are 7 bits
(signed), and 3 each for sextant and octant (if present).

B.13.3 Delta Position to Position

absolute_position(x, y, z):
cur_x ← x, cur_y ← y, cur_z ← z

relative_position(∆x, ∆y, ∆z):

cur_x ← cur_x + ∆x, cur_y ← cur_y + ∆y, cur_z ← cur_z + ∆z

B.13.4 Delta Color to Color

absolute_color(r, g, b {, α}):
cur_r ← r, cur_g ← g, cur_b ← b, {cur_α ← α}

relative_color(∆r, ∆g, ∆b {, ∆α}):

cur_r ← cur_r + ∆r, cur_g ← cur_g + ∆g, cur_b ← cur_b + ∆b,
{cur_α ← cur_α + ∆α }

B.13.5 Encoded Delta Normal to Encoded Normal

State: cur_oct, cur_sex, cur_u, cur_v

absolute_normal(oct, sex, u, v):

cur_oct ← oct, cur_sex ← sex, cur_u ← u, cur_v ← v,

relative_normal(∆u, ∆v):

cur_u ← cur_u + ∆u, cur_v ← cur_v + ∆v,

if (cur_u < 0)
cur_u ← -cur_u, cur_sex ← flip_u[cur_sex]
else if (cur_v < 0)
cur_v ← -cur_v, cur_oct ← cur_oct <xor> flip_v[cur_sex]
else if (cur_u + cur_v > 64)
cur_u ← 64 - cur_u, cur_v ← 64 - cur_v,
cur_sex ← flip_uv[cur_sex]

flip_u[6] = { 4, 5, 3, 2, 0, 1 }
flip_v[6] = { 2, 4, 1, 1, 2, 4 }
flip_uv[6] = { 2, 3, 0, 1, 5, 4 }

492 The Java 3D API Specification

3D GEOMETRY COMPRESSION Instruction to Vertex B.14.1

B.13.6 Encoded Normal to Rectilinear Normal

nx ← norms[v,u].nx, ny ← norms[v,u].ny, nz ← norms[v,u].nz,

if (cur_sex & 4) t ← nx, nx ← nz, nz ← t
if (cur_sex & 2) t ← ny, ny ← nz, nz ← t
if (cur_sex & 1) t ← nx, nx ← ny, ny ← t
if (cur_oct & 1) nz ← -nz
if (cur_oct & 2) ny ← -ny
if (cur_oct & 4) nx ← -nx

The contents of the norms[] table is exactly specified, and the next revision of this
specification will contain an exact listing of the values.

B.14 Semantics of Vertices

The formal semantics of the vertex processing is best described by a state descrip-
tion of the decompression process. Once again it must be emphasized that these
state descriptions are given to show the formal semantics, not an efficient imple-
mentation.

B.14.1 Instruction to Vertex

This section describes the state change semantics caused by each instruction to
generate the next output vertex, prior to assembly into triangles. The internal state
consists of the three bundling bits, a current normal and current color, normal_
override and color_override bits, the 16 mesh buffer vertices, and a current
internal-cycling mesh buffer index.

normal(n):
current_normal ← n, normal_override ← 1

color(c):
current_color ← c, color_override ← 1

vertex(rep, mbp, p {, n} {, c}):

current_position ← p,
if (bnv) current_normal ← n,
if (bcv) current_color ← c,
output_vertex(rep, current_position, current_normal,
current_color)
if (push) mesh_buffer[mesh_index].position ← p

Version 1.2, March 2000 493

B.14.2 Vertex to Intermediate Triangle 3D GEOMETRY COMPRESSION

if (push && bnv) mesh_buffer[mesh_index].normal ← n

if (push && bcv) mesh_buffer[mesh_index].color ← c
if (push) mesh_index ← (mesh_index+1) & 15
normal_override ← 0, color_override ← 0

mesh buffer reference(rep, i):

current_position ←
mesh_buffer[(mesh_index - i - 1) & 15].position
if (bnv && !normal_override)
current_color ← mesh_buffer[(mesh_index - i - 1) & 15].color
if (bcv && !color_override)
current_color ← mesh_buffer[(mesh_index - i - 1) & 15].color
normal_override ← 0, color_override ← 0
output_vertex(rep, current_position, current_normal,
current_color)

set state(new_bnv, new_bcv, new_cap):

bnv ← new_bnv,
bcv ← new_bcv,
cap ← new_cap,
normal_override ← 0, color_override ← 0

set table(address, range, entry):

…

nop(length):
(null)

B.14.2 Vertex to Intermediate Triangle

This section describes the formal semantics of assembling vertices with replace-
ment instructions into nearly finished triangles: the semantics of generalized trian-
gle strips.

output_vertex(restart_reverse, newv):
newest ← newv, number_of_vertices ← 1, rev = 1

output_vertex(restart, newv):
newest ← newv, number_of_vertices ← 1, rev = 0

494 The Java 3D API Specification

3D GEOMETRY COMPRESSION Intermediate Triangle to Final Triangle B.14.3

output_vertex(replace_middle, newv):

if (number_of_vertices < 2)
middle ← newest, newest ← newv, number_of_vertices++
else if (number_of_vertices < 3)
oldest ← middle, middle ← newest, newest ← newv,
number_of_vertices++,
intermediate_triangle(restart, oldest, middle, newest)
else if (number_of_vertices == 3)
middle ← newest, newest ← newv,
intermediate_triangle(restart, oldest, middle, newest)

output_vertex(replace_oldest, newv):

if (number_of_vertices < 2)
middle ← newest, newest ← newv, number_of_vertices++
else if (number_of_vertices < 3)
oldest ← middle, middle ← newest, newest ← newv,
number_of_vertices++,
intermediate_triangle(restart, oldest, middle, newest)
else if (number_of_vertices == 3)
oldest ← middle, middle ← newest, newest ← newv,
rev = 1 - rev,
intermediate_triangle(restart, oldest, middle, newest)

B.14.3 Intermediate Triangle to Final Triangle

The final stage is to take into account the current reverse bit. This bit controls the
order in which the vertices are output to ensure they all face the correct way.

intermediate_triangle(rev, v1, v2, v3):

if (!rev)
final_triangle(v1.position, v1.normal, v1.color,
v2.position, v2.normal, v2.color,
v3.position, v3.normal, v3.color)
else if (rev)
final_triangle(v2.position, v2.normal, v2.color,
v1.position, v1.normal, v1.color,
v3.position, v3.normal, v3.color)

Version 1.2, March 2000 495

B.15 Outline of Geometry Process 3D GEOMETRY COMPRESSION

B.15 Outline of Geometry Process

Java 3D only formally defines the compressed geometry format and the decom-
pression semantics. Authoring tools are free to employ whatever compressed
geometry algorithms they choose, as long as the results adhere to the specifications
described in the previous sections.
However, to further document the semantics of the compressed geometry format,
an overview of one particular compressed geometry algorithm is given here.

B.15.1 Compressing Geometry Data

Group the geometry to be compressed into separate rigid objects. Typically such
objects will be individually culled during rendering, so you should not join objects
too extensively prior to compression. In optimized systems, the granularity of
object splitting will be computed by an algorithm that takes culling optimization
into account. (Both frustum and occlusion culling.)

B.15.2 Convert to Generalized Mesh Format

Once a group of geometry has been identified, it is next converted into generalized
mesh format. This is a complex step, and a number of topological analysis-based
algorithms have been applied to it. Note that to reduce compression time, when
space is a less important issue than time, a compressor might only stripify, not
meshify. Alternatively, the triangles have to have come from somewhere, and that
in many cases is a tessellator of higher order surfaces. Such a tessellator will
implicitly know the mesh connectivity, and may be able to generate the triangle
data directly in the generalized mesh format.
The next step is the quantization of the geometry positions, colors, and/or normals.
All these quantizations can be varied within the geometry, but for simplicity a sin-
gle fixed quantization of each is assumed here.

B.15.3 Position

Normalize the position data.

The containing bounding box for the object is computed. This is the minimal box
such that all geometry vertices are contained within it. The vertices are then all nor-
malized to be contained within this bounding box by first subtracting the XYZ
location of the bounding box center from the vertex XYZ and then dividing all the
XYZ vertex values by the half length of the longest side of the bounding box. Thus
all normalized positions will be within the ±1 unit cube. A constant matrix trans-
496 The Java 3D API Specification
3D GEOMETRY COMPRESSION Normals B.15.4

form corresponding to an offset to the center of the bounding box, and an inverse
scale by the half length of the longest side of the bounding box are created as a pro-
logue for the geometry data. Note that in practice a little more care must be taken.
The greatest positive value is actually ( 2 n – 1 – 1 ) ⁄ 2 n – 1 , when positions are quan-
tized to n bits. By symmetry, the smallest negative value allowed is
– ( 2 n – 1 – 1 ) ⁄ 2 n – 1 . The value –1 (only sign bit set, all other bits 0) is explicitly not
allowed. Thus when computing the scale factor (and center) that will normalize the
geometry, the actual representation range needs to be taken into account.

Quantize the position data.

Assuming that position data is to be quantized to n bits, each vertex position com-
ponent should be multiplied by the value of 2n and then rounded down to the near-
est integer. If rounded to the nearest integer, or rounded up, the value may overflow
the representation. Once again the goal is to take numbers from a given floating
point range, and represent all of them within an n-bit fixed point range.

B.15.4 Normals

Normalize the normals.

Each normal should be normalized to unit length.

Quantize the XYZ components of the normal to 14 bits accuracy

Each normal component should be multiplied by 214, rounded to the nearest inte-
ger, and then converted back to floating-point representation and divided by 214.

Fold the XYZ components of the normal to the positive (prime) octant
If an XYZ component of the normal is negative, invert it and save the original sign
bits as a three-bit octant value. It is important when compressing to always strip the
sign bits off first before applying sextant folding, and to reverse the process when
decompressing. Note that the octant bits read left to right: the upper bit is for the x-
axis, the middle for the y-axis, and the lowermost of the three is for the z-axis.

oct = 0;
if(nx < 0.0) oct |= 4, nx = -nx
if(ny < 0.0) oct |= 2, ny = -ny
if(nz < 0.0) oct |= 1, nz = -nz

Version 1.2, March 2000 497

B.15.5 Colors 3D GEOMETRY COMPRESSION

Fold the normal to the nX ≥ nZ ≥ nY sextant

Check (in exactly the following order):

sex = 0;
if (nx < ny) t = nx, nx = ny, ny = t, sex |= 1
if (nz < ny) t = ny, ny = nz, nz = t, sex |= 2
if (nx < nz) t = nx, nx = nz, nz = t, sex |= 4

Match the nearest quantized normal representation

Take the dot product of the normal with each of the quantized reference normals in
the table for the specified number of quantized normal bits. That UV normal index
for the reference normal that gives the greatest (nearest unity) dot product result is
the new quantized normal representation (along with the octant and sextant repre-
sentation). (There are more efficient was to compute this same results.) At this
point there are no specific tie breaking rules when two (or more) reference normals
produce the same candidate dot product results. Technically this is purely a com-
pressor internal issue.

Check for special normals

The u, v normal index generated by the previous stage will generally be in the full
7-bit range of the normal grid space. In this space, the two classes of special nor-
mals occur when u = 64, v = 0, and when u = 0, v = 64. When this is detected, the
sextant and octant bits must be examined to produce the proper special normal
encoding:

if (u == 64 && v == 0) { /* Six coordinate axis case */

if (sex == 0 || sex == 2) /* +/- x-axis */
special = ((oct & 4)?0x2:0);
else if (sex == 3 || sex == 1) /* +/- y-axis */
special = 4 | ((oct & 2)?0x2:0);
else if (sex == 5 || sex == 4) /* +/- z-axis */
special = 0x8 | ((oct & 1)?0x2:0);
} else
if (u == 0 && v == 64) /* Eight mid point case */
special = (oct<<1) | 1;

B.15.5 Colors
The colors are assumed to be in a 0.0 to 0.9 representation to begin with.

498 The Java 3D API Specification

3D GEOMETRY COMPRESSION Normal Delta Code Statistics B.15.9

Quantize the color values.

Assuming that color data is to be quantized to n bits, each vertex color component
(R, G, B, and optionally α) should be multiplied by the value of 2n and then
rounded down to the nearest integer. Just as with positions, there is no true repre-
sentation of positive unity.

B.15.6 Collect Delta Code Statistics

Make a pass in generalized mesh order through all vertices in the geometry. For
each successive pair of vertices, compute the difference between their component
values, compute the bit length of this (signed) difference, and histogram this bit
length. Specifics for each component type are detailed in the next sections.

B.15.7 Position Delta Code Statistics

Compute ∆X, ∆Y, and ∆Z. Determine which of these has the greatest magnitude.
Compute the number of bits for this component, including one sign bit. This is the
length to be histogrammed for positions.

B.15.8 Color Delta Code Statistics

Compute ∆R, ∆G, ∆B, and ∆α (if present). Determine which of these has the great-
est magnitude. Compute the number of bits for this component, including one sign
bit. This is the length to be histogrammed for colors.

B.15.9 Normal Delta Code Statistics

For a given pair of normals, check to see if they have the same octant and sextant,
and that neither is a special normal. If so, compute ∆U and ∆V. Determine which
of these has the greatest magnitude. Compute the number of bits for this compo-
nent, including one sign bit. This is the length to be histogrammed for this pair of
normals.
If the normals have different sextants and/or octants, but neither is a special normal,
check to see if their sextants share an edge. If so, the special normal wrapping rules
from Section B.8.3, “Special Warping Rules for Delta Normals” can be applied.
Depending on what type of edge they share, the delta including the change in edges
is encoded in one of three ways: U + ∆U < 0, V + ∆V < 0, and U + ∆U + V + ∆V
> 64. Each case is discussed in the paragraphs below. The sextant numbers are from
the binary codes shown in Figure B-3.

Version 1.2, March 2000 499

B.15.9 Normal Delta Code Statistics 3D GEOMETRY COMPRESSION

Sextants 0 and 4, 1 and 5, and 2 and 3 share the U = 0 edge. When crossing this
boundary, ∆U becomes ~U – last_u. This will generate a negative cur_u value
during decompression, which causes the decompressor to invert cur_u and look up
the new sextant in a table.
Sextants 0 and 2, 1 and 3, and 4 and 5 share the U + V = 64 edge. ∆U becomes 64
– U – last_u and ∆V becomes 64 – V – last_v. When cur_u + cur_v > 64, the
decompressor sets cur_u = 64 – cur_u and cur_v = 64 – cur_v, and a table lookup
determines the new sextant.
Each sextant shares the V = 0 edge with its corresponding sextant in another octant.
When in sextants 1 or 5, the normal moves across the X-axis, across the Y-axis for
sextants 0 or 4, and across the Z-axis for sextants 2 or 3. ∆V becomes ~V – last_
v. The decompressor inverts a negative cur_v and performs a table lookup for a
mask to exclusive-OR with the current octant value.

Note: When using the normal wrapping rules, a subtle bug can be introduced due
to the ambiguity of normals on a shared edge between two sextants. The normal
encoding rules have unambiguous tie breaking rules to determine which octant and
sextant a given normal resides in. However, the wrapping rules assume by default
that a delta-ed normal is in the same sextant and octant as its predecessor if the delta
only landed on an edge. This is subtly different than the sextant and octant that the
encoding rules might have suggested. The proper procedure is to keep track of
which octant and sextant a decompressor would believe that the normals being gen-
erated would lie in, and when the normal to delta to lands on an edge of this region,
change its sextant and octant from the what the encoding rules suggested to be the
same as where it is now delta-ing from. This change in default encoding is permis-
sible because the rectilinear normal encoded by values on a sextant edge are iden-
tical no matter which sextant claims ownership.

Otherwise the normals cannot be delta encoded, and so the second (target) normal
must be represented by an absolute reference to its three octant, three sextant, and
2 N-bit U V addresses. This is the length to be histogrammed for this pair of nor-
mals.

Note: Slightly higher compression density can be achieved at a slight expense in

representation accuracy by avoiding special normals when delta and wrapping dif-
ferences are generating compact results. Instead of generating the special normal,
a near-by non-special normal can be generated allowing for compact deltas. As
with any compression technique that intentionally further modifies / distorts the

500 The Java 3D API Specification

3D GEOMETRY COMPRESSION Compressed Geometry Assembly Syntax B.16

input data, doing this normal perturbation must be a policy choice of the compres-
sor itself, and subject to quality constraints of the user.

B.15.10 Assign Huffman Tags

Encode data into variable-bit length compressed geometry instructions.
One can use an algorithm similar to the one used by the JPEG image compression
standard. The main differences are how codes are reassigned when their lengths
exceed the maximum code length and how the data bits are encoded in the com-
pressed data stream, and also supporting additional attributes for codes (relative/
absolute, how many bits of left shift).
The frequencies of the data lengths are used as leaf nodes in a binary tree. The algo-
rithm used to generate the tree places the less frequent codes deeper in the tree.
After the tree is built, the traversal path to a leaf node becomes its Huffman code,
and the depth in the tree becomes its code length.
Codes generated with a length greater than six, the maximum code length, must be
shortened. These nodes are merged with more frequent nodes by increasing the
number of sign bits included with the smaller data length.

B.15.11 Assemble the Pieces into a Bit Stream

Given the sequence of variable-bit-length compressed geometry instructions, shuf-
fle the first eight (six) bits of each instruction ahead of its predecessor’s body.

B.16 Compressed Geometry Assembly Syntax

This section describes the assembly syntax for both the input to an assembler for
Compressed Geometry, and for the output of a disassembler of Compressed Geom-
etry.
The concept of a verbose ASCII assembly syntax for a compressed binary format
may seem like an oxymoron, but in fact a well defined assembly format is an
invaluable aid to debugging both compressors and decompressors. The ASCII
assembly format is not meant to a representation ever used for the transport of
Compressed Geometry; rather it is a debugging aid for those involved in program-
ming compressors and decompressors, and building hardware decompressors. The
assembly format is also useful for generating and understanding test vectors. Both
an assembler and a disassembler are available as stand alone C programs as tools.

Version 1.2, March 2000 501

B.16 Compressed Geometry Assembly Syntax 3D GEOMETRY COMPRESSION

For generating Compressed Geometry programmatically, a number of C and Java

based low level compression tools are also available. With the possible exception
of test vectors, software based compressors should use these direct binary output
routines; having a compressor generate an intermediate ASCII file representation
only to then be assembled into binary is needlessly inefficient. If these is a need to
examine the output of a compressor in a human readable form, a binary Com-
pressed Geometry file can always be disassembled into ASCII by the disassembler
when needed.
Because Compressed Geometry is a tightly encoded binary format, to make dis-
sembled output more understandable, it is appropriate to optionally perform some
partial decompression before generating the text output. Thus the Compressed
Geometry disassembler supports multiple levels of decompression during disas-
sembly. On the other hand, the Compressed Geometry assembler is not a compres-
sor, and thus only supports as input the lowest level syntax. There are five layers
successively more decompressed disassembly, with each level printed using either
decimal or hex numbers. The five layers and two numeric formats are expressed as
ten different levels of disassembly (with every other level just indicating that hex
output for integer fields):
1. Nearly raw. After a symbolic opcode, decimal (or optionally, hex) numbers
are printed for the modified huffman tag field, and for all data fields with-
out any additional interpretation, scaling, or un-delta-ing, except that prop-
er signed/unsigned semantics is followed. The only processing is to parse
the incoming bit stream into bit fields, and undo the effects of header for-
warding. The modified huffman tag is only used to determine the length of
the tag field and the following data fields. The opcode have no trailing let-
ter modifiers (as documented below); this indicates level 1.
2. Same as level 1, but printed using hex numbers (proceeded with a 0x
suffix).
3. Modified Huffman tag expanded. The properties of the modified huffman
tag are shown in line: the length of the tag, the length of the data fields, and
the left normalization shift for the field. The absolute/relative bit value is
shown by appending the letter ‘A’ or ‘R’ to the opcode (or ‘S’ for absolute
‘special’ normals).
4. Same as level 3, but printed using hex numbers (proceeded with the 0x
suffix).
5. Normalized. The left normalization shift is applied to the data fields, and
the specific properties of the modified huffman tag are no longer shown.
To differentiate level 2, the letter ‘N’ is appended to the opcode name, after
the absolute/relative/special letter.

502 The Java 3D API Specification

3D GEOMETRY COMPRESSION Compressed Geometry Assembly Syntax B.16

6. Same as level 5, but printed using hex numbers (proceeded with the 0x
suffix).
7. Un-delta’d. Like level 3, but relative values have had the running total
added to them, to show what the current full value is. Absolute values are
unchanged from level 3. To differentiate level 4, an ‘A’ suffix is added to
the lengthening opcode name.
8. Same as level 7, but printed using hex numbers (proceeded with the 0x
suffix).
9. Floating point. While up to now all values have been subsets of 16-bit
integers, before conversion to integer and quantization, most values were
floating point numbers in the 0 to 1.0 or −1.0 to 1.0 range. Level 5 shows
the values as floating point numbers, but it must be cautioned that these
data fields, while similar to the input un-compressed un-quantized values,
will usually be slightly different in value than the original data. This
floating point output format is primarily included as a convenience when a
user wants to understand the data closer to the original space.
10. Same as level 9, but non floating-point numbers printed using hex numbers
(preceeded with the 0x suffix).
Once again while the dissembler supports all 10 levels of output options, the
assembler only supports levels 1 and 2.
The syntax is fairly simple. Because the setting Colors or Normals can either be
stand-alone instructions, or components of a vertex instruction, parenthetic instruc-
tion grouping (lisp style) are used to make the ownership of arguments clear.
As an example, below is the disassembly (print level 1) of a four sided pyramid:
(nop 0)
(setTable Position 32-47 2 4 Rel)
(setTable Position 56-63 3 4 Rel)
(setTable Position 0-31 12 4 Rel)
(setTable Position 48-55 12 4 Abs)
(setTable Normal 0-31 5 0 Rel)
(setTable Normal 32-63 6 0 Abs)
(setTable Color 32-63 2 8 Rel)
(setTable Color 0-31 8 8 Abs)
(setState normalsBundled colorsUnbundled alphaUnbundled)
(setState normalsBundled colorsUnbundled alphaUnbundled)
(setColor 0 127 51 12)
(setState normalsBundled colorsUnbundled alphaUnbundled)
(setColor 32 0 0 0)
(vertex RST (Position 48 -2047 -2047 -205)
(Normal 32 4 --+ 44 0))

Version 1.2, March 2000 503

B.17 Compressed Geometry Instruction Verifier 3D GEOMETRY COMPRESSION

(vertex RMID (Position 0 2047 -2 0)

(Normal 32 5 +++ 44 0))
(vertex ROLD (Position 0 0 -2047 409)
(Normal 0 14 0))
(vertex ROLD (Position 0 2047 -2047 -409)
(Normal 32 4 +-+ 44 0))
(vertex ROLD (Position 56 2 0 0)
(Normal 32 4 --+ 44 0))
(vertex RST (Position 0 2047 -2 0)
(Normal 32 00-))
(vertex RMID (Position 0 -2047 2 0)
(Normal 32 00-))
(vertex ROLD (Position 32 -2 0 0)
(Normal 32 00-))
(nop 19)
(nop 29)

B.17 Compressed Geometry Instruction Verifier

This sections describes the rules for determining if a given binary sequence is a
valid Compressed Geometry block or not. These rules have been programmatically
implemented in a Compressed Geometry verifier, a stand alone C program that can
validate a given file containing a Compressed Geometry object. The verifier is also
available in a utility package in both C and Java for use within a larger systems.
In theory, every producer of Compressed Geometry should run such a verifier on
its output as a final check; and every consumer of Compressed Geometry should
run such a verifier on any input as an initial check. In practice for well debugged
programs and hardware implementations with error detection a separate verifica-
tion pass may not always be necessary, but it should always be available as an
option. (It is also important to note the just passing the verifier is not sufficient to
indicate that a Compressed Geometry compressor is functioning properly; the out-
put must also be examined visually for other types of error.)
When the stand alone verifier finds a violation, and appropriate error message is
printed out. This is quite useful when debugging compressors. The implementation
of the verifier is effectively an augmented decompressor, in which un-initialized
state is kept track of, and additional error checking is applied.
For a Compressed Geometry object to be valid, it must adhere to at least the fol-
lowing rules, along with the restrictions described in the rest of this document:

504 The Java 3D API Specification

3D GEOMETRY COMPRESSION Compressed Geometry Instruction Verifier B.17

Rule 1: Size, Alignment and Byte Order

Every Compressed Geometry is a sequence of binary data a multiple of four 8-
bit bytes in size, starting on an aligned 32-bit boundary, represented in network
byte order.

Rule 2: Beginnings
Every Compressed Geometry sequence starts with the body field of a nop in-
struction. Initial process proceeds as if a forwarded header of a nop instruction
had just been seen. The length field of this nop instruction body can be of any
legal length, though usually by convention the length field is 0, and thus the
first body consists of five zeros.

Rule 3: Endings
The last header in a Compressed Geometry sequence is a nop. This is followed
by the body of the next to last instruction. This next to last instruction can be
any instruction, and its body can be of any valid length for that instruction type,
but the body must end on a four byte 32-bit word aligned boundary. To achieve
this usually the next to last, and possible the next to next to last instruction(s)
are also nops, with lengths chosen to satisfy the ending requirement. Note that
the body for the last instruction (the nop) is not present in the Compressed Ge-
ometry sequence. The end of the Compressed Geometry is determined from a
separately specified size outside of the Compressed Geometry proper. Note
that this ending convention is symmetrical with the starting convention; the se-
quential concatenation of two valid Compressed Geometry objects is also a
valid Compressed Geometry object. For hardware, after a valid Compressed
Geometry object has been executed, another valid Compressed Geometry can
be executed without any pipeline flushes if desired.

Rule 4: Reserved Bits

Any bits or bit fields described as reserved in a Compressed Geometry instruc-
tion must be filled with zeros.

Rule 5: Valid Opcodes

Only the seven defined instruction opcodes that may be present in a valid Com-
pressed Geometry object.

Rule 6: No Defaults
All state used in the processing of Compressed Geometry must be defined be-
fore it is used; there are no implicit defaults for any of the state. The state in-
clude the contents of the decompression tables as defined by the setTable

Version 1.2, March 2000 505

B.17 Compressed Geometry Instruction Verifier 3D GEOMETRY COMPRESSION

instruction, the three bundling bits as defined by the setState instruction, the
contents of the mesh buffer as defined by vertex instructions with push en-
abled, and the current position, normal, and color (and alpha), as defined by ab-
solute settings in vertex instructions, setNormal instructions, and setColor
instructions. Note that this does not mean that all possible state needs to be de-
fined within a Compressed Geometry object. For example, only those portions
of the decompression tables actually referenced by a vertex or setNormal or
setColor instruction need be initialized first. The bits specified by setState al-
ways need to be referenced, unless there are no vertex instructions, which
would only occur in a geometry-less Compressed Geometry object. Mesh buff-
er elements need only be defined if they are accessed by mesh buffer reference
instructions. The current normal and the current color (and alpha) are special
cases; if they are not used within a Compressed Geometry object they may not
need to be initialized depending on the semantics of the outer incorporating
graphics API.
Specifically in a valid Compressed Geometry sequence no relative values for
positions, normals, colors (or alpha) may appear in a vertex or setNormal or
setColor instruction until after an absolute value has appeared for that particu-
lar item. There is no inheritance between different Compressed Geometry ob-
jects, each must be entirely stand-alone when it comes to state.

Rule 7: State Changes Immediately

State changed by setState and setTable instructions is in force and available as
of next instruction. (This specifically disallows pipelined hardware implemen-
tations from changing the semantics to force user visible delay slots.)

Rule 8: Valid XYZ Positions

Executing the position field of a vertex instruction will always result in a
signed sixteen bit fixed point value for the current X, Y, and Z position state.
All possible bit values are valid for these fields.

Rule 9: Valid Sextant Octant u v Normals

Executing a setNormal instruction, or executing (when present) the normal
sub-instruction of a vertex instruction will result in updated sextant, octant, u
and v fields. The wrapping semantics described earlier define the subset of val-
id values and delta operations allowed for these fields. If these fields are valid,
then a valid conversion back to a rectilinear Nx Ny Nz values is defined.

Rule 10: Valid RGB{α} Color

Executing a setColor instruction, or executing (when present) the color sub-in-
struction of a vertex instruction will always result in a signed sixteen bit fixed

506 The Java 3D API Specification

3D GEOMETRY COMPRESSION Compressed Geometry Instruction Verifier B.17

point value for the current R, G, B (and sometimes α) color state. Only positive
values are valid for these fields.

Rule 11: What Is Outside the Scope of these Rules

The results of executing a sequence of Compressed Geometry instructions in a
valid Compressed Geometry object is a sequence of specific vertex values and
connectivity information for triangles (or lines or points). What further pro-
cessing this output stream is subject to, and the semantics of this processing is
outside the scope of the specification of Compressed Geometry. For example,
the semantics of transformation, lighting, and shading are not specified by
Compressed Geometry. Note that even the semantic interpretation of what type
of color parameter the “color” values generated by Compressed Geometry is
left undefined by the Compressed Geometry specification; this is up to the
lighting equation (or for realistic rendering systems, more generally the pro-
grammable shader) of the outer incorporating graphics API. Specifically no
implication is made as to if the “color” value is an ambient color, a diffuse col-
or, a specular color, an emissive color, some combination thereof, or a more
generalized value used by a programmable shader. This of course also applies
to any interpretation of the α value, which may or may not be a opacity value.
As described above, for a Compressed Geometry object to be valid, it must follow
these rules plus adhere to the other constraints describing individual Compressed
Geometry instructions described in the rest of this document.

Version 1.2, March 2000 507

 A PPE N D I X C
View Model Details

A N application programmer writing a 3D graphics program that will deploy on

a variety of platforms must anticipate the likely end-user environments and must
carefully construct the view transformations to match those characteristics using
a low-level API. This appendix addresses many of the issues an application must
face and describes the sophisticated features that Java 3D’s advanced view model
provides.

C.1 An Overview of the Java 3D View Model

Both camera-based and Java 3D–based view models allow a programmer to
specify the shape of a view frustum and, under program control, to place, move,
and re-orient that frustum within the virtual environment. However, how they do
this varies enormously. Unlike the camera-based system, the Java 3D view model
allows slaving the view frustum’s position and orientation to that of a six-
degrees-of-freedom tracking device. By slaving the frustum to the tracker,
Java 3D can automatically modify the view frustum so that the generated images
match the end-user’s viewpoint exactly.
Java 3D must handle two rather different head-tracking situations. In one case,
we rigidly attach a tracker’s base, and thus its coordinate frame, to the display
environment. This corresponds to placing a tracker base in a fixed position and
orientation relative to a projection screen within a room, relative to a computer
display on a desk, or relative to the walls of a multiple-wall projection display. In
the second head-tracking situation, we rigidly attach a tracker’s sensor, not its
base, to the display device. This corresponds to rigidly attaching one of that
tracker’s sensors to a head-mounted display and placing the tracker base some-
where within the physical environment.

Version 1.2, March 2000 509

C.2 Physical Environments and Their Effects VIEW MODEL DETAILS

C.2 Physical Environments and Their Effects

Imagine an application where the end user sits on a magic carpet. The applica-
tion flies the user through the virtual environment by controlling the carpet’s
location and orientation within the virtual world. At first glance, it might seem
that the application also controls what the end user will see—and it does, but
only superficially.
The following two examples show how end-user environments can significantly
affect how an application must construct viewing transformations.

C.2.1 A Head-mounted Example

Imagine that the end user sees the magic carpet and the virtual world with a
head-mounted display and head tracker. As the application flies the carpet
through the virtual world, the user may turn to look to the left, right, or even
toward the rear of the carpet. Because the head tracker keeps the renderer
informed of the user’s gaze direction, it might not need to draw the scene directly
in front of the magic carpet. The view that the renderer draws on the head-
mount’s display must match what the end user would see had the experience
occurred in the real world.

C.2.2 A Room-mounted Example

Imagine a slightly different scenario, where the end user sits in a darkened room
in front of a large projection screen. The application still controls the carpet’s
flight path; however, the position and orientation of the user’s head barely influ-
ences the image drawn on the projection screen. If a user looks left or right, then
he or she only sees the darkened room. The screen does not move. It’s as if the
screen represents the magic carpet’s “front window” and the darkened room rep-
resents the “dark interior” of the carpet.
By adding a left and right screen, we give the magic carpet rider a more com-
plete view of the virtual world surrounding the carpet. Now our end user sees the
view to the left or right of the magic carpet by turning left or right.

C.2.3 Impact of Head Position and Orientation on the Camera

In the head-mounted example, the user’s head position and orientation signifi-
cantly affects a camera model’s camera position and orientation but has hardly
any effect on the projection matrix. In the room-mounted example, the user’s

510 The Java 3D API Specification

VIEW MODEL DETAILS Room-mounted Coordinate Systems C.3.1

head position and orientation contributes little to a camera model’s camera posi-
tion and orientation; however, it does affect the projection matrix.
From a camera-based perspective, the application developer must construct the
camera’s position and orientation by combining the virtual-world component (the
position and orientation of the magic carpet) and the physical-world component
(the user’s instantaneous head position and orientation).
Java 3D’s view model incorporates the appropriate abstractions to compensate
automatically for such variability in end-user hardware environments.

C.3 The Coordinate Systems

The basic view model consists of eight or nine coordinate systems, depending on
whether the end-user environment consists of a room-mounted display or a head-
mounted display. First we define the coordinate systems used in a room-mounted
display environment. Next we define the added coordinate system introduced
when using a head-mounted display system.

C.3.1 Room-mounted Coordinate Systems

The room-mounted coordinate system is divided into the virtual coordinate sys-
tem and the physical coordinate system. Figure C-1 shows these coordinate sys-
tems graphically. The coordinate systems within the grayed area exist in the
virtual world; those outside exist in the physical world. Note that the coexistence
coordinate system exists in both worlds.

C.3.1.1 The Virtual Coordinate Systems

The Virtual World Coordinate System

The virtual world coordinate system encapsulates the unified coordinate system
for all scene graph objects in the virtual environment. For a given View, the vir-
tual world coordinate system is defined by the Locale object that contains the
ViewPlatform object attached to the View. It is a right-handed coordinate system
with +x to the right, +y up, and +z toward the viewer.

The ViewPlatform Coordinate System

The ViewPlatform coordinate system is the local coordinate system of the
ViewPlatform leaf node to which the View is attached.

Version 1.2, March 2000 511

C.3.1 Room-mounted Coordinate Systems VIEW MODEL DETAILS

Head Head Tracker Tracker Base Other Trackers

LCC
Image Plate Coexistence
RCC Virtual

ViewPlatform Vworld
Fishtank Mode

Figure C-1 Display Rigidly Attached to the Tracker Base

The Coexistence Coordinate System

A primary implicit goal of any view model is to map a specified local portion of
the physical world onto a specified portion of the virtual world. Once estab-
lished, one can legitimately ask where the user’s head or hand is located within
the virtual world, or where a virtual object is located in the local physical world.
In this way the physical user can interact with objects inhabiting the virtual
world, and vice versa. To establish this mapping, Java 3D defines a special coor-
dinate system, called coexistence coordinates, that is defined to exist in both the
physical world and the virtual world.
The coexistence coordinate system exists half in the virtual world and half in the
physical world. The two transforms that go from the coexistence coordinate sys-
tem to the virtual world coordinate system and back again contain all the infor-
mation needed to expand or shrink the virtual world relative to the physical
world, as well as the information needed to position and orient the virtual world
relative to the physical world.
Modifying the transform that maps the coexistence coordinate system into the
virtual world coordinate system changes what the end user can see. The Java 3D
application programmer moves the end user within the virtual world by modify-
ing this transform.

C.3.1.2 The Physical Coordinate Systems

The Head Coordinate System

The head coordinate system allows an application to import its user’s head
geometry. The coordinate system provides a simple consistent coordinate frame
for specifying such factors as the location of the eyes and ears.

512 The Java 3D API Specification

VIEW MODEL DETAILS Head-mounted Coordinate Systems C.3.2

The Image Plate Coordinate System

The image plate coordinate system corresponds with the physical coordinate sys-
tem of the image generator. The image plate is defined as having its origin at the
lower left-hand corner of the display area and as lying in the display area’s XY
plane. Note that image plate is a different coordinate system than either left
image plate or right image plate. These last two coordinate systems are defined
in head-mounted environments only (see Section C.3.2, “Head-mounted Coordi-
nate Systems”).

The Head Tracker Coordinate System

The head tracker coordinate system corresponds to the six-degrees-of-freedom
tracker’s sensor attached to the user’s head. The head tracker’s coordinate system
describes the user’s instantaneous head position.

The Tracker Base Coordinate System

The tracker base coordinate system corresponds to the emitter associated with
absolute position/orientation trackers. For those trackers that generate relative
position/orientation information, this coordinate system is that tracker’s initial
position and orientation. In general, this coordinate system is rigidly attached to
the physical world.

C.3.2 Head-mounted Coordinate Systems

Head-mounted coordinate systems divide the same virtual coordinate systems
and the physical coordinate systems. Figure C-2 shows these coordinate systems
graphically. As with the room-mounted coordinate systems, the coordinate sys-
tems within the grayed area exist in the virtual world; those outside exist in the
physical world. Once again, the coexistence coordinate system exists in both
worlds. The arrangement of the coordinate system differs from those for a room-
mounted display environment. The head-mounted version of Java 3D’s coordi-
nate system differs in another way. It includes two image plate coordinate sys-
tems, one for each of an end-user’s eyes.

The Left Image Plate and Right Image Plate Coordinate Systems
The left image plate and right image plate coordinate systems correspond with
the physical coordinate system of the image generator associated with the left
and right eye, respectively. The image plate is defined as having its origin at the
lower left-hand corner of the display area and lying in the display area’s XY
plane. Note that the left image plate’s XY plane does not necessarily lie parallel

Version 1.2, March 2000 513

C.4 The ViewPlatform Object VIEW MODEL DETAILS

to the right image plate’s XY plane. Note that left image plate and right image
plate are different coordinate systems than the room-mounted display environ-
ment’s image plate coordinate system.

Head

LCC Left Image Plate

Head Tracker Tracker Base Coexistence
RCC Right Image Plate Virtual

Other Trackers ViewPlatform Vworld

Head-mounted Display (HMD) Mode

Figure C-2 Display Rigidly Attached to the Head Tracker (Sensor)

C.4 The ViewPlatform Object

The ViewPlatform object is a leaf object within the Java 3D scene graph. The
ViewPlatform object is the only portion of Java 3D’s viewing model that resides
as a node within the scene graph. Changes to TransformGroup nodes in the scene
graph hierarchy above a particular ViewPlatform object move the view’s location
and orientation within the virtual world (see Section 9.4, “ViewPlatform: A Place
in the Virtual World”). The ViewPlatform object also contains a ViewAttachPol-
icy and an ActivationRadius (see Section 6.11, “ViewPlatform Node,” for a com-
plete description of the ViewPlatform API).

C.5 The View Object

The View object is the central Java 3D object for coordinating all aspects of a
viewing situation. All parameters that determine the viewing transformation to be
used in rendering on a collected set of canvases in Java 3D are either directly
contained within the View object, or within objects pointed to by a View object
(or pointed to by these, etc.). Java 3D supports multiple simultaneously active
View objects, each of which controls its own set of canvases.
The Java 3D View object has several instance variables and methods, but most
are calibration variables or user-helping functions.

514 The Java 3D API Specification

VIEW MODEL DETAILS View Policy C.5.1

Methods

public void setTrackingEnable(boolean flag)

public boolean getTrackingEnable()

These methods set and retrieve a flag specifying whether to enable the use of six-
degrees-of-freedom tracking hardware.

public void getUserHeadToVworld(Transform3D t)

This method retrieves the user-head-to-vworld coordinate system transform. This

Transform3D object takes points in the user’s head coordinate system and trans-
forms them into points in the virtual world coordinate system. This value is read-
only. Java 3D continually generates it, but only if enabled by using the setUser-
HeadToVworldEnable method.

public void setUserHeadToVworldEnable(boolean flag)

public boolean getUserHeadToVworldEnable()

These methods set and retrieve a flag that specifies whether or not to repeatedly
generate the user-head-to-vworld transform (initially false).

public String toString()

This method returns a string that contains the values of this View object.

C.5.1 View Policy

The view policy informs Java 3D whether it should generate the view using the
head-tracked system of transformations or the head-mounted system of transfor-
mations. These policies are attached to the Java 3D View object.

Methods

public void setViewPolicy(int policy)

public int getViewPolicy()

These two methods set and retrieve the current policy for view computation. The
policy variable specifies how Java 3D uses its transforms in computing new
viewpoints, as follows:
• SCREEN_VIEW: Specifies that Java 3D should compute new viewpoints
using the sequence of transforms appropriate to nonattached, screen-based
head-tracked display environments, such as fishtank VR, multiple-projec-
tion walls, and VR desks. This is the default setting.

Version 1.2, March 2000 515

C.5.2 Screen Scale Policy VIEW MODEL DETAILS

• HMD_VIEW: Specifies that Java 3D should compute new viewpoints us-

ing the sequence of transforms appropriate to head-mounted display envi-
ronments. This policy is not available in compatibility mode (see
Section C.11, “Compatibility Mode”).

C.5.2 Screen Scale Policy

The screen scale policy specifies where the screen scale comes from. The policy
can be one of the following:
• SCALE_EXPLICIT: Specifies that the screen scale is taken from the user-
provided screenScale attribute.
• SCALE_SCREEN_SIZE: Specifies that the screen scale is derived from
the physical screen according to the following formula. This is the default
policy.
screenScale = physicalScreenWidth / 2.0

public void setScreenScalePolicy(int policy)

public int getScreenScalePolicy()

These methods set and retrieve the current screen scale policy.

public void setScreenScale(double scale)

public double getScreenScale()

These methods set and retrieve the screen scale value. This value is used when
the screen scale policy is SCALE_EXPLICIT.

C.5.3 Window Eyepoint Policy

The window eyepoint policy comes into effect in a non-head-tracked environ-
ment. The policy tells Java 3D how to construct a new view frustum based on
changes in the field of view and in the Canvas3D’s location on the screen. The
policy only comes into effect when the application changes a parameter that can
change the placement of the eyepoint relative to the view frustum.

Constants

public static final int RELATIVE_TO_FIELD_OF_VIEW

This variable tells Java 3D that it should modify the eyepoint position so it is
located at the appropriate place relative to the window to match the specified
field of view. This implies that the view frustum will change whenever the appli-

516 The Java 3D API Specification

VIEW MODEL DETAILS Monoscopic View Policy C.5.4

cation changes the field of view. In this mode, the eye position is read-only. This
is the default setting.

public static final int RELATIVE_TO_SCREEN

This variable tells Java 3D to interpret the eye’s position relative to the entire
screen. No matter where an end user moves a window (a Canvas3D), Java 3D
continues to interpret the eye’s position relative to the screen. This implies that
the view frustum changes shape whenever an end user moves the location of a
window on the screen. In this mode, the field of view is read-only.

public static final int RELATIVE_TO_WINDOW

This variable specifies that Java 3D should interpret the eye’s position informa-
tion relative to the window (Canvas3D). No matter where an end user moves a
window (a Canvas3D), Java 3D continues to interpret the eye’s position relative
to that window. This implies that the frustum remains the same no matter where
the end user moves the window on the screen. In this mode, the field of view is
read-only.

public static final int RELATIVE_TO_COEXISTENCE New in 1.2

This variable specifies that Java 3D should interpret the fixed eyepoint position in
the view as relative to the origin of coexistence coordinates. This eyepoint is
transformed from coexistence coordinates to image plate coordinates for each
Canvas3D. As in RELATIVE_TO_SCREEN mode, this implies that the view frustum
shape will change whenever a user moves the location of a window on the
screen.

Methods

public int getWindowEyepointPolicy()

public void setWindowEyepointPolicy(int policy)

This variable specifies how Java 3D handles the predefined eyepoint in a non-
head-tracked application. The variable can contain one of four values:
RELATIVE_TO_FIELD_OF_VIEW, RELATIVE_TO_SCREEN, RELATIVE_TO_WINDOW, or
RELATIVE_TO_COEXISTENCE. The default value is RELATIVE_TO_FIELD_OF_
VIEW.

C.5.4 Monoscopic View Policy

This policy specifies how Java 3D generates a monoscopic view.

Version 1.2, March 2000 517

C.5.5 Visibility Policy VIEW MODEL DETAILS

Constants

public static final int LEFT_EYE_VIEW

public static final int RIGHT_EYE_VIEW
public static final int CYCLOPEAN_EYE_VIEW

These constants specify the monoscopic view policy. The first constant specifies
that the monoscopic view should be the view as seen from the left eye. The sec-
ond constant specifies that the monoscopic view should be the view as seen from
the right eye. The third constant specifies that the monoscopic view should be the
view as seen from the “center eye,” the fictional eye half-way between the left
and right eyes. This is the default setting.

Methods

public void setMonoscopicViewPolicy(int policy) New in 1.2

public int getMonoscopicViewPolicy() New in 1.2

These methods are deprecated. Use the Canvas3D.setMonoscopicViewPolicy

and Canvas3D.getMonoscopicViewPolicy methods.

C.5.5 Visibility Policy

This policy specifies how visible and invisible objects are drawn.

Constants

public static final int VISIBILITY_DRAW_VISIBLE New in 1.2

public static final int VISIBILITY_DRAW_INVISIBLE New in 1.2
public static final int VISIBILITY_DRAW_ALL New in 1.2

These constants set the visibility policy for this view. The first constant specifies
that only visible objects are drawn (this is the default). The second constant spec-
ifies that only invisible objects are drawn. The third constant specifies that both
visible and invisible objects are drawn.

Methods

public void setVisibilityPolicy(int policy) New in 1.2

public int getVisibilityPolicy() New in 1.2

These methods set and retrieve the visibility policy for this view. The policy can
be one of VISIBILITY_DRAW_VISIBLE, VISIBILITY_DRAW_INVISIBLE, or
VISIBILITY_DRAW_ALL. The default visibility policy is VISIBILITY_DRAW_VISI-
BLE.

518 The Java 3D API Specification

VIEW MODEL DETAILS Sensors and Their Location in the Virtual World C.5.8

C.5.6 Coexistence Centering Enable

public void setCoexistenceCenteringEnable(boolean flag) New in 1.2

public boolean getCoexistenceCenteringEnable() New in 1.2

These methods set and retrieve the coexistenceCentering enable flag. If the coex-
istenceCentering flag is true, the center of coexistence in image plate coordi-
nates, as specified by the trackerBaseToImagePlate transform, is translated to the
center of either the window or the screen in image plate coordinates, according
to the value of windowMovementPolicy.
By default, coexistenceCentering is enabled. It should be disabled if the tracker-
BaseToImagePlate calibration transform is set to a value other than the identity
(for example, when rendering to multiple screens or when head tracking is
enabled). This flag is ignored for HMD mode, or when the coexistenceCenterIn-
PworldPolicy is not NOMINAL_SCREEN.

C.5.7 Eyepoint in Coexistence

public void setLeftManualEyeInCoexistence(Point3d position) New in 1.2

public void setRightManualEyeInCoexistence(Point3d position) New in 1.2
public void getLeftManualEyeInCoexistence(Point3d position) New in 1.2
public void getRightManualEyeInCoexistence(Point3d position) New in 1.2

These methods set and retrieve the position of the manual right and left eyes in
coexistence coordinates. These values determine eye placement when a head
tracker is not in use and the application is directly controlling the eye position in
coexistence coordinates. These values are ignored when in head-tracked mode or
when the windowEyepointPolicy is not RELATIVE_TO_COEXISTENCE.

C.5.8 Sensors and Their Location in the Virtual World

public void getSensorToVworld(Sensor sensor, Transform3D t)

public void getSensorHotSpotInVworld(Sensor sensor,
Point3d position)
public void getSensorHotSpotInVworld(Sensor sensor,
Point3f position)

The first method takes the sensor’s last reading and generates a sensor-to-vworld
coordinate system transform. This Transform3D object takes points in that sen-
sor’s local coordinate system and transforms them into virtual world coordinates.
The next two methods retrieve the specified sensor’s last hotspot location in vir-
tual world coordinates.

Version 1.2, March 2000 519

C.6 The Screen3D Object VIEW MODEL DETAILS

C.6 The Screen3D Object

A Screen3D object represents one independent display device. The most com-
mon environment for a Java 3D application is a desktop computer with or with-
out a head tracker. Figure C-3 shows a scene graph fragment for a display
environment designed for such an end-user environment. Figure C-4 shows a dis-
play environment that matches the scene graph fragment in Figure C-3.

TransformGroup TG

ViewPlatform View Canvas3D Screen3D

VP

Physical Physical
Body Environment

Figure C-3 A Portion of a Scene Graph Containing a Single Screen3D Object

Figure C-4 A Single-Screen Display Environment

A multiple-projection wall display presents a more exotic environment. Such

environments have multiple screens, typically three or more. Figure C-5 shows a
scene graph fragment representing such a system and Figure C-6 shows the cor-
responding display environment.

520 The Java 3D API Specification

VIEW MODEL DETAILS Screen3D Calibration Parameters C.6.1

TransformGroup TG
Canvas3D Screen3D

ViewPlatform View Canvas3D Screen3D

VP

Canvas3D Screen3D

Physical Physical
Body Environment

Figure C-5 A Portion of a Scene Graph Containing Three Screen3D Objects

Figure C-6 A Three-Screen Display Environment

A multiple-screen environment requires more care during the initialization and

calibration phase. Java 3D must know how the Screen3D’s are placed with
respect to one another, the tracking device, and the physical portion of the coex-
istence coordinate system.

C.6.1 Screen3D Calibration Parameters

The Screen3D object is the 3D version of AWT’s screen object (see Section 9.8,
“The Screen3D Object”). To use a Java 3D system, someone or some program
must calibrate the Screen3D object with the coexistence volume. These methods
allow that person or program to inform Java 3D of those calibration parameters.
Version 1.2, March 2000 521
C.6.2 Accessing and Changing Head Tracker Coordinates VIEW MODEL DETAILS

Measured Parameters
These calibration parameters are set once, typically by a browser, calibration pro-
gram, system administrator, or system calibrator, not by an applet.

public void setPhysicalScreenWidth(double width)

public void setPhysicalScreenHeight(double height)

These methods store the screen’s (image plate’s) physical width and height in
meters. The system administrator or system calibrator must provide these values
by measuring the display’s active image width and height. In the case of a head-
mounted display, this should be the display’s apparent width and height at the
focal plane.

C.6.2 Accessing and Changing Head Tracker Coordinates

public void setTrackerBaseToImagePlate(Transform3D t)

public void getTrackerBaseToImagePlate(Transform3D t)

These methods set and get the tracker-base-to-image-plate coordinate system

transform. This transform is typically a calibration constant. This is used only in
SCREEN_VIEW mode. Users must recalibrate whenever the image plate moves rel-
ative to the tracker.

public void setHeadTrackerToLeftImagePlate(Transform3D t)

public void getHeadTrackerToLeftImagePlate(Transform3D t)
public void setHeadTrackerToRightImagePlate(Transform3D t)
public void getHeadTrackerToRightImagePlate(Transform3D t)

These methods set and get the head-tracker-to-left-image-plate and head-tracker-

to-right-image-plate coordinate system transforms, respectively. These trans-
forms are typically calibration constants. They are used only in HMD_VIEW mode.

C.7 The Canvas3D Object

Java 3D provides special support for those applications that wish to manipulate
an eye position even in a non-head-tracked display environment. One situation
where such a facility proves useful is an application that wishes to generate a
very high-resolution image composed of lower-resolution tiled images. The
application must generate each tiled component of the final image from a com-
mon eye position with respect to the composite image but a different eye position
from the perspective of each individual tiled element.

522 The Java 3D API Specification

VIEW MODEL DETAILS Accessing and Modifying an Eye’s Image Plate Position C.7.2

C.7.1 Scene Antialiasing

public boolean getSceneAntialiasingAvailable()

This method returns a status flag indicating whether scene antialiasing is avail-
able.

C.7.2 Accessing and Modifying an Eye’s Image Plate Position

A Canvas3D object provides sophisticated applications with access to the eye’s
position information in head-tracked, room-mounted runtime environments. It
also allows applications to manipulate the position of an eye relative to an image
plate in non-head-tracked runtime environments.

public void setLeftManualEyeInImagePlate(Point3d position)

public void setRightManualEyeInImagePlate(Point3d position)
public void getLeftManualEyeInImagePlate(Point3d position)
public void getRightManualEyeInImagePlate(Point3d position)

These methods set and retrieve the position of the manual left and right eyes in
image plate coordinates. These values determine eye placement when a head
tracker is not in use and the application is directly controlling the eye position in
image plate coordinates. In head-tracked mode or when the windowEyepoint-
Policy is RELATIVE_TO_FIELD_OF_VIEW or RELATIVE_TO_COEXISTENCE, this
value is ignored. When the windowEyepointPolicy is RELATIVE_TO_WINDOW,
only the Z value is used.
public void getLeftEyeInImagePlate(Point3d position)
public void getRightEyeInImagePlate(Point3d position)
public void getCenterEyeInImagePlate(Point3d position)

These methods retrieve the actual position of the left eye, right eye, and center
eye in image plate coordinates and copy that value into the object provided. The
center eye is the fictional eye half-way between the left and right eye. These
three values are a function of the windowEyepointPolicy, the tracking enable
flag, and the manual left, right, and center eye positions.

public void getPixelLocationInImagePlate(int x, int y, Point3d

imagePlatePoint)
public void getPixelLocationInImagePlate(Point2d pixelLocation,
Point3d imagePlatePoint) New in 1.2

These methods compute the position of the specified AWT pixel value in image
plate coordinates and copy that value into the object provided.

Version 1.2, March 2000 523

C.7.3 Canvas Width and Height VIEW MODEL DETAILS

public void getPixelLocationFromImagePlate(Point3d

imagePlatePoint, Point2d pixelLocation) New in 1.2

This method projects the specified point from image plate coordinates into AWT
pixel coordinates. The AWT pixel coordinates are copied into the object pro-
vided.

public void getVworldToImagePlate(Transform3D t)

This method retrieves the current virtual-world-to-image-plate coordinate system

transform and places it into the specified object.

public void getImagePlateToVworld(Transform3D t)

This method retrieves the current image-plate-to-virtual-world coordinate system

transform and places it into the specified object.

C.7.3 Canvas Width and Height

public double getPhysicalWidth()

public double getPhysicalHeight()

These methods retrieve the physical width and height of this canvas window, in
meters.

C.7.4 Monoscopic View Policy

public void setMonoscopicViewPolicy(int policy) New in 1.2

public int getMonoscopicViewPolicy() New in 1.2

These methods set and retrieve the policy regarding how Java 3D generates
monoscopic view. If the policy is set to View.LEFT_EYE_VIEW, the view gener-
ated corresponds to the view as seen from the left eye. If set to View.RIGHT_
EYE_VIEW, the view generated corresponds to the view as seen from the right eye.
If set to View.CYCLOPEAN_EYE_VIEW, the view generated corresponds to the view
as seen from the “center eye,” the fictional eye half-way between the left and
right eye. The default monoscopic view policy is View.CYCLOPEAN_EYE_VIEW.

Note: For backward compatibility with Java 3D 1.1, if this attribute is set to its
default value of View.CYCLOPEAN_EYE_VIEW, the monoscopic view policy in the
View object will be used. An application should not use both the deprecated View
method and this Canvas3D method at the same time.

524 The Java 3D API Specification

VIEW MODEL DETAILS The PhysicalBody Object C.8

C.8 The PhysicalBody Object

The PhysicalBody object contains information concerning the physical character-
istics of the end-user’s body. The head parameters allow end users to specify
their own head’s characteristics and thus to customize any Java 3D application so
that it conforms to their unique geometry. The PhysicalBody object defines head
parameters in the head coordinate system. It provides a simple and consistent
coordinate frame for specifying such factors as the location of the eyes and thus
the interpupilary distance.

The Head Coordinate System

The head coordinate system has its origin on the head’s bilateral plane of sym-
metry, roughly half-way between the left and right eyes. The origin of the head
coordinate system is known as the center eye. The positive X-axis extends to the
right. The positive Y-axis extends up. The positive Z-axis extends into the skull.
Values are in meters.

Constructors

public PhysicalBody()

Constructs a default user PhysicalBody object with the following default eye and
ear positions:
Parameter Default Value
leftEyePosition (–0.033, 0.0, 0.0)
rightEyePosition (0.033, 0.0, 0.0)
leftEaPosition (–0.080, –0.030, 0.095)
rightEarPosition (0.080, –0.030, 0.095)
nominal eye height from ground 1.68
nominal eye offset from nominal 0.4572
screen
head to head tracker transform identity

public PhysicalBody(Point3d leftEyePosition,

Point3d rightEyePosition)
public PhysicalBody(Point3d leftEyePosition,
Point3d rightEyePosition, Point3d leftEarPosition,
Point3d rightEarPosition)

These methods construct a PhysicalBody object with the specified eye and ear
positions.

Version 1.2, March 2000 525

C.8 The PhysicalBody Object VIEW MODEL DETAILS

Methods

public void getLeftEyePosition(Point3d position)

public void setLeftEyePosition(Point3d position)
public void getRightEyePosition(Point3d position)
public void setRightEyePosition(Point3d position)

These methods set and retrieve the position of the center of rotation of a user’s
left and right eyes in head coordinates.

public void getLeftEarPosition(Point3d position)

public void setLeftEarPosition(Point3d position)
public void getRightEarPosition(Point3d position)
public void setRightEarPosition(Point3d position)

These methods set and retrieve the position of the user’s left and right ear posi-
tions in head coordinates.

public double getNominalEyeHeightFromGround()

public void setNominalEyeHeightFromGround(double height)

These methods set and retrieve the user’s nominal eye height as measured from
the ground to the center eye in the default posture. In a standard computer moni-
tor environment, the default posture would be seated. In a multiple-projection
display room environment or a head-tracked environment, the default posture
would be standing.

public double getNominalEyeOffsetFromNominalScreen()

public void setNominalEyeOffsetFromNominalScreen(double offset)

These methods set and retrieve the offset from the center eye to the center of the
display screen. This offset distance allows an “over the shoulder” view of the
scene as seen by the end user.

public void setHeadToHeadTracker(Transform3D t)

public void getHeadToHeadTracker(Transform t)

These methods set and retrieve the head-to-head-tracker coordinate system trans-
form. If head tracking is enabled, this transform is a calibration constant. If head
tracking is not enabled, this transform is not used. This transform is used in both
SCREEN_VIEW and HMD_VIEW modes.

public String toString()

This method returns a string that contains the values of this PhysicalBody object.

526 The Java 3D API Specification

VIEW MODEL DETAILS The PhysicalEnvironment Object C.9

C.9 The PhysicalEnvironment Object

The PhysicalEnvironment object contains information about the local physical
world of the end-user’s physical environment. This includes information about
audio output devices and tracking sensor hardware, if present.

Constructors

public PhysicalEnvironment()

Constructs and initializes a new PhysicalEnvironment object with default param-

eters:
Parameter Default Value
sensorCount 3
sensors null (for all array elements)
headIndex 0
rightHandIndex 1
leftHandIndex 2
dominantHandIndex 1
nondominantHandIndex 2
tracking available false
audio device null
input device list empty
coexistence to tracker base identity
transform
coexistence center in pworld View.NOMINAL_SCREEN
policy

public PhysicalEnvironment(int sensorCount)

Constructs and initializes a new PhysicalEnvironment object.

The sensor information provides real-time access to continuous-input devices
such as joysticks and trackers. It also contains two-degrees-of-freedom joystick
and six-degrees-of-freedom tracker information. See Section 11.2, “Sensors,” for
more information. Java 3D uses Java AWT’s event model for noncontinuous
input devices such as keyboards (see Chapter 11, “Input Devices and Picking”).
Audio device information associated with the PhysicalEnvironment object allows
the application a mechanism to choose a particular audio device (if more than
one is available) and explicitly set the type of audio playback for sound rendered

Version 1.2, March 2000 527

C.9 The PhysicalEnvironment Object VIEW MODEL DETAILS

using this device. See Chapter 12, “Audio Devices,” for more details on the fields
and methods that set and initialize the device driver and output playback associ-
ated with the audio device.

Methods
The PhysicalEnvironment object specifies the following methods pertaining to
audio output devices and input sensors.

public void setAudioDevice(AudioDevice device)

This method selects the specified AudioDevice object as the device through
which audio rendering for this PhysicalEnvironment will be performed.

public AudioDevice getAudioDevice()

This method retrieves the specified AudioDevice object.

public void addInputDevice(InputDevice device)

public void removeInputDevice(InputDevice device)

These methods add and remove an input device to or from the list of input
devices.

public Enumeration getAllInputDevices()

This method creates an enumerator that produces all input devices.

public void setSensorCount(int count)

public int getSensorCount()

These methods set and retrieve the count of the number of sensors stored within
the PhysicalEnvironment object. It defaults to a small number of sensors. It
should be set to the number of sensors available in the end-user’s environment
before initializing the Java 3D API.

public void setCoexistenceToTrackerBase(Transform3D t)

public void getCoexistenceToTrackerBase(Transform3D t)

These methods set the coexistence-to-tracker-base coordinate system transform.

If head tracking is enabled, this transform is a calibration constant. If head track-
ing is not enabled, this transform is not used. This is used in both SCREEN_VIEW
and HMD_VIEW modes.

public boolean getTrackingAvailable()

This method returns a status flag indicating whether or not tracking is available.

528 The Java 3D API Specification

VIEW MODEL DETAILS Viewing in Head-tracked Environments C.10

public void setSensor(int index, Sensor sensor)

public Sensor getSensor(int index)

The first method sets the sensor specified by the index to the sensor provided.
The second method retrieves the specified sensor.

public void setDominantHandIndex(int index)

public int getDominantHandIndex()

These methods set and retrieve the index of the dominant hand.

public void setNonDominantHandIndex(int index)

public int getNonDominantHandIndex()

These methods set and retrieve the index of the nondominant hand.

public void setHeadIndex(int index)

public int getHeadIndex()
public void setRightHandIndex(int index)
public int getRightHandIndex()
public void setLeftHandIndex(int index)
public int getLeftHandIndex()

These methods set and retrieve the index of the head, right hand, and left hand.
The index parameter refers to the sensor index.

Physical Coexistence Policy

public int getCoexistenceCenterInPworldPolicy()

public void setCoexistenceCenterInPworldPolicy(int policy)

These methods set and retrieve the physical coexistence policy used in this phys-
ical environment. This policy specifies how Java 3D will place the user’s eye-
point as a function of current head position during the calibration process.
Java 3D permits one of three values: NOMINAL_HEAD, NOMINAL_FEET, or NOMINAL_
SCREEN.

C.10 Viewing in Head-tracked Environments

Section 9.5, “Generating a View,” describes how Java 3D generates a view for a
standard flat-screen display with no head tracking. In this section, we describe
how Java 3D generates a view in a room-mounted, head-tracked display environ-
ment—either a computer monitor with shutter glasses and head tracking or a
multiple-wall display with head-tracked shutter glasses. Finally, we describe how

Version 1.2, March 2000 529

C.10.1 A Room-mounted Display with Head Tracking VIEW MODEL DETAILS

Java 3D generates view matrices in a head-mounted and head-tracked display

environment.

C.10.1 A Room-mounted Display with Head Tracking

When head tracking combines with a room-mounted display environment (for
example, a standard flat screen display), the ViewPlatform’s origin and orienta-
tion serves as a base for constructing the view matrices. Additionally, Java 3D
uses the end-user’s head position and orientation to compute where an end-user’s
eyes are located in physical space. Each eye’s position serves to offset the corre-
sponding virtual eye’s position relative to the ViewPlatform’s origin. Each eye’s
position also serves to specify that eye’s frustum since the eye’s position relative
to a Screen3D uniquely specifies that eye’s view frustum. Note that Java 3D will
access the PhysicalBody object to obtain information describing the user’s inter-
pupilary distance and tracking hardware, values it needs to compute the end-
user’s eye positions from the head position information.

C.10.2 A Head-mounted Display with Head Tracking

In a head-mounted environment, the ViewPlatform’s origin and orientation also
serves as a base for constructing view matrices. And, as in the head-tracked,
room-mounted environment, Java 3D also uses the end-user’s head position and
orientation to further modify the ViewPlatform’s position and orientation. In a
head-tracked, head-mounted display environment, an end-user’s eyes do not
move relative to their respective display screens, rather, the display screens move
relative to the virtual environment. A rotation of the head by an end user can rad-
ically affect the final view’s orientation. In this situation, Java 3D combines the
position and orientation from the ViewPlatform with the position and orientation
from the head tracker to form the view matrix. The view frustum, however, does
not change since the user’s eyes do not move relative to their respective display
screen, so Java 3D can compute the projection matrix once and cache the result.
If any of the parameters of a View object are updated, this will effect a change in
the implicit viewing transform (and thus image) of any Canvas3D that references
that View object.

C.11 Compatibility Mode

A camera-based view model allows application programmers to think about the
images displayed on the computer screen as if a virtual camera took those
images. Such a view model allows application programmers to position and ori-

530 The Java 3D API Specification

VIEW MODEL DETAILS Overview of the Camera-based View Model C.11.1

ent a virtual camera within a virtual scene, to manipulate some parameters of the
virtual camera’s lens (specify its field of view), and to specify the locations of
the near and far clipping planes.
Java 3D allows applications to enable compatibility mode for room-mounted,
non-head-tracked display environments, or to disable compatibility mode using
the following methods. Camera-based viewing functions are only available in
compatibility mode.

Methods

public void setCompatibilityModeEnable(boolean flag)

public boolean getCompatabilityModeEnable()

This flag turns compatibility mode on or off. Compatibility mode is disabled by

default.

Note: Use of these view-compatibility functions will disable some of Java 3D’s
view model features and limit the portability of Java 3D programs. These methods
are primarily intended to help jump-start porting of existing applications.

C.11.1 Overview of the Camera-based View Model

The traditional camera-based view model, shown in Figure C-7, places a virtual
camera inside a geometrically specified world. The camera “captures” the view
from its current location, orientation, and perspective. The visualization system
then draws that view on the user’s display device. The application controls the
view by moving the virtual camera to a new location, by changing its orientation,
by changing its field of view, or by controlling some other camera parameter.
The various parameters that users control in a camera-based view model specify
the shape of a viewing volume (known as a frustum because of its truncated
pyramidal shape) and locate that frustum within the virtual environment. The
rendering pipeline uses the frustum to decide which objects to draw on the dis-
play screen. The rendering pipeline does not draw objects outside the view frus-
tum and it clips (partially draws) objects that intersect the frustum’s boundaries.
Though a view frustum’s specification may have many items in common with
those of a physical camera, such as placement, orientation, and lens settings,
some frustum parameters have no physical analog. Most noticeably, a frustum
has two parameters not found on a physical camera: the near and far clipping
planes.
Version 1.2, March 2000 531
C.11.2 Using the Camera-based View Model VIEW MODEL DETAILS

View Frustum

Near Clipping Plane

Far Clipping Plane

Figure C-7 The Camera-based View Model

The location of the near and far clipping planes allow the application program-
mer to specify which objects Java 3D should not draw. Objects too far away from
the current eyepoint usually do not result in interesting images. Those too close
to the eyepoint might obscure the interesting objects. By carefully specifying
near and far clipping planes, an application programmer can control which
objects the renderer will not be drawing.
From the perspective of the display device, the virtual camera’s image plane cor-
responds to the display screen. The camera’s placement, orientation, and field of
view determine the shape of the view frustum.

C.11.2 Using the Camera-based View Model

The camera-based view model allows Java 3D to bridge the gap between existing
3D code and Java 3D’s view model. By using the camera-based view model
methods, a programmer retains the familiarity of the older view model but gains
some of the flexibility afforded by Java 3D’s new view model.
The traditional camera-based view model is supported in Java 3D by helping
methods in the Transform3D object. These methods were explicitly designed to
resemble as closely as possible the view functions of older packages, and thus
should be familiar to most 3D programmers. The resulting Transform3D objects
can be used to set compatibility-mode transforms in the View object.

C.11.2.1 Creating a Viewing Matrix

The Transform3D object provides the following method to create a viewing
matrix.

532 The Java 3D API Specification

VIEW MODEL DETAILS Using the Camera-based View Model C.11.2

public void lookAt(Point3d eye, Point3d center, Vector3d up)

This is a utility method that specifies the position and orientation of a viewing
transform. It works very similarly to the equivalent function in OpenGL. The
inverse of this transform can be used to control the ViewPlatform object within
the scene graph. Alternatively, this transform can be passed directly to the View’s
VpcToEc transform via the compatibility-mode viewing functions (see
Section C.11.2.3, “Setting the Viewing Transform”).

C.11.2.2 Creating a Projection Matrix

The Transform3D object provides the following three methods for creating a pro-
jection matrix. All three map points from eye coordinates (EC) to clipping coor-
dinates (CC). Eye coordinates are defined such that (0, 0, 0) is at the eye and the
projection plane is at z = –1.

public void frustum(double left, double right, double bottom,

double top, double near, double far)

The frustum method establishes a perspective projection with the eye at the apex
of a symmetric view frustum. The transform maps points from eye coordinates to
clipping coordinates. The clipping coordinates generated by the resulting trans-
form are in a right-handed coordinate system (as are all other coordinate systems
in Java 3D).
The arguments define the frustum and its associated perspective projection:
(left, bottom, -near) and (right, top, -near) specify the point on the near
clipping plane that maps onto the lower-left and upper-right corners of the win-
dow, respectively. The -far parameter specifies the far clipping plane. See
Figure C-8.

public void perspective(double fovx, double aspect, double zNear,

double zFar)

The perspective method establishes a perspective projection with the eye at the
apex of a symmetric view frustum, centered about the Z-axis, with a fixed field of
view. The resulting perspective projection transform mimics a standard camera-
based view model. The transform maps points from eye coordinates to clipping
coordinates. The clipping coordinates generated by the resulting transform are in
a right-handed coordinate system.
The arguments define the frustum and its associated perspective projection:
-near and -far specify the near and far clipping planes; fovx specifies the field
of view in the X dimension, in radians; and aspect specifies the aspect ratio of
the window. See Figure C-9.

Version 1.2, March 2000 533

C.11.2 Using the Camera-based View Model VIEW MODEL DETAILS

top
left

bottom
near right

far

Figure C-8 A Perspective Viewing Frustum

aspect = x/y

y
Θ x

fovx
zNear
zFar

Figure C-9 Perspective View Model Arguments

public void ortho(double left, double right, double bottom,

double top, double near, double far)

The ortho method establishes a parallel projection. The orthographic projection

transform mimics a standard camera-based video model. The transform maps
points from eye coordinates to clipping coordinates. The clipping coordinates
generated by the resulting transform are in a right-handed coordinate system.
The arguments define a rectangular box used for projection: (left, bottom,
-near) and (right, top, -near) specify the point on the near clipping plane
that maps onto the lower-left and upper-right corners of the window, respectively.
The -far parameter specifies the far clipping plane. See Figure C-10.

534 The Java 3D API Specification

VIEW MODEL DETAILS Using the Camera-based View Model C.11.2

top

left

Toward the right

Viewpoint

bottom

View Volume
near far

Figure C-10 Orthographic View Model

C.11.2.3 Setting the Viewing Transform

The View object provides the following compatibility-mode methods that operate
on the viewing transform.

public void setVpcToEc(Transform3D vpcToEc)

public void getVpcToEc(Transform3D vpcToEc)

This compatibility-mode method specifies the ViewPlatform coordinates (VPC)

to eye coordinates viewing transform. If compatibility mode is disabled, this
transform is derived from other values and is read-only.

C.11.2.4 Setting the Projection Transform

The View object provides the following compatibility-mode methods that operate
on the projection transform.

public void setLeftProjection(Transform3D projection)

public void getLeftProjection(Transform3D projection)
public void setRightProjection(Transform3D projection)
public void getRightProjection(Transform3D projection)

These compatibility-mode methods specify a viewing frustum for the left and
right eye that transforms points in eye coordinates to clipping coordinates. If
compatibility mode is disabled, a RestrictedAccessException is thrown. In
monoscopic mode, only the left eye projection matrix is used.

Version 1.2, March 2000 535

 A PPE N D I X D
Exceptions

T HE Java 3D API uses the standard Java exception model for handling errors
or exceptional conditions. In addition to using existing exception classes, such as
ArrayIndexOutOfBoundsException and IllegalArgumentException, Java 3D
defines several new runtime exceptions. These exceptions are thrown by various
Java 3D methods or by the Java 3D renderer to indicate an error condition of
some kind.
The exceptions defined by Java 3D, as part of the javax.media.j3d package, are
described in the following sections. They all extend RuntimeException and, as
such, need not be declared in the throws clause of methods that might cause the
exception to be thrown. This appendix is not an exhaustive list of all exceptions
expected for Java 3D. Additional exceptions will be added as the need arises.

D.1 BadTransformException
Indicates an attempt to use a Tranform3D object that is inappropriate for the
object in which it is being used. For example:
• Transforms that are used in the scene graph, within a TransformGroup
node, must be affine. They may optionally contain a nonuniform scale or a
shear, subject to other listed restrictions.
• All transforms in the TransformGroup nodes above a ViewPlatform object
must be congruent. This ensures that the Vworld-coordinates-to-ViewPlat-
form-coordinates transform is angle- and length-preserving with no shear
and only uniform scale.
• Most viewing transforms other than those in the scene graph can only con-
tain translation and rotation.

Version 1.2, March 2000 537

D.2 CapabilityNotSetException EXCEPTIONS

• The projection transform is allowed to be non-affine, but it must either be

a single-point perspective projection or a parallel projection.

Constructors

public BadTransformException()
public BadTransformException(String str)

These create the exception object that outputs the exception message. The first
form uses the default message. The second form specifies the message string to
be output.

D.2 CapabilityNotSetException
This exception indicates an access to a live or compiled Scene Graph object
without the required capability set.

Constructors

public CapabilityNotSetException()
public CapabilityNotSetException(String str)

These create the exception object that outputs the exception message. The first
form uses the default message. The second form specifies the message string to
be output.

D.3 DanglingReferenceException
This exception indicates that during a cloneTree call, an updated reference was
requested for a node that did not get cloned. This occurs when a subgraph is
duplicated via cloneTree and has at least one leaf node that contains a reference
to a node with no corresponding node in the cloned subgraph. This results in two
leaf nodes wanting to share access to the same node.
If dangling references are to be allowed during the cloneTree call, cloneTree
should be called with the allowDanglingReferences parameter set to true.

538 The Java 3D API Specification

EXCEPTIONS IllegalSharingException D.5

Constructors

public DanglingReferenceException()
public DanglingReferenceException(String str)

These create the exception object that outputs the exception message. The first
form uses the default message. The second form specifies the message string to
be output.

D.4 IllegalRenderingStateException
This exception indicates an illegal state for rendering. This includes:
• Lighting without specifying normals in a geometry array object
• Texturing without specifying texture coordinates in a geometry array ob-
ject

public illegalRenderingStateException()
public illegalRenderingStateException(String str)

These create the exception object that outputs the exception message. The first
form uses the default message. The second form specifies the message string to
be output.

D.5 IllegalSharingException
This exception indicates an illegal attempt to share a scene graph object. For
example, the following are illegal:
• Referencing a shared subgraph in more than one virtual universe
• Using the same component object both in the scene graph and in an imme-
diate-mode graphics context
• Including an unsupported type of leaf node within a shared subgraph
• Referencing a BranchGroup node in more than one of the following ways:
• Attaching it to a (single) Locale
• Adding it as a child of a Group node within the scene graph
• Referencing it from a (single) Background leaf node as background geometry

Version 1.2, March 2000 539

D.6 MismatchedSizeException EXCEPTIONS

Constructors

public IllegalSharingException()
public IllegalSharingException(String str)

These create the exception object that outputs the exception message. The first
form uses the default message. The second form specifies the message string to
be output.

D.6 MismatchedSizeException
This exception indicates that an operation cannot be completed properly because
of a mismatch in the sizes of the object attributes.

public MismatchedSizeException()
public MismatchedSizeException(String str)

These create the exception object that outputs the exception message. The first
form uses the default message. The second form specifies the message string to
be output.

D.7 MultipleParentException
This exception extends IllegalSharingException and indicates an attempt to
add a node that is already a child of one group node into another group node.

Constructors

public MultipleParentException()
public MultipleParentException(String str)

These create the exception object that outputs the exception message. The first
form uses the default message. The second form specifies the message string to
be output.

D.8 RestrictedAccessException
This exception indicates an attempt to access or modify a state variable without
permission to do so. For example, invoking a set method for a state variable that
is currently read-only.

540 The Java 3D API Specification

EXCEPTIONS SingularMatrixException D.10

Constructors

public RestrictedAccessException()
public RestrictedAccessException(String str)

These create the exception object that outputs the exception message. The first
form uses the default message. The second form specifies the message string to
be output.

D.9 SceneGraphCycleException
This exception indicates that one of the live scene graphs attached to a viewable
Locale has a cycle in it. Java 3D scene graphs are directed acyclic graphs and, as
such, do not permit cycles. This exception is either thrown by the Java 3D ren-
derer at scene graph traversal time or when a scene graph containing a cycle is
made live (added as a descendant of a Locale object).

Constructors

public SceneGraphCycleException()
public SceneGraphCycleException(String str)

These create the exception object that outputs the exception message. The first
form uses the default message. The second form specifies the message string to
be output.

D.10 SingularMatrixException
This exception, in the javax.vecmath package, indicates that the inverse of a
matrix cannot be computed.

Constructors

public SingularMatrixException()
public SingularMatrixException(String str)

These create the exception object that outputs the exception message. The first
form uses the default message. The second form specifies the message string to
be output.

Version 1.2, March 2000 541

D.11 SoundException EXCEPTIONS

D.11 SoundException
This exception indicates a problem in loading or playing a sound sample.

Constructors

public SoundException()
public SoundException(String str)

These create the exception object that outputs the exception message. The first
form uses the default message. The second form specifies the message string to
be output.

542 The Java 3D API Specification

 A PPE N D I X E
Equations

T HIS appendix contains the Java 3D equations for fog, lighting, sound, and
texture mapping. Many of the equations use the following symbols:

⋅ Multiplication
• Function operator for sound equations,
Dot product for all other equations

E.1 Fog Equations

The ideal fog equation is as follows:

C′ = C ⋅ f + C f ⋅ ( 1 – f ) (E.1)
The fog coefficient, f, is computed differently for linear and exponential fog. The
equation for linear fog is as follows:

B–z
f = ------------- (E.2)
B–F

The equation for exponential fog is as follows:

f = e –d ⋅ z (E.3)
The parameters used in the fog equations are as follows:

C = Color of the pixel being fogged

Cf = Fog color
d = Fog density
F = Front fog distance, measured in eye coordinates

Version 1.2, March 2000 543

E.2 Lighting Equations EQUATIONS

B = Back fog distance, measured in eye coordinates

z = The z-coordinate distance from the eyepoint to the pixel being
fogged, measured in eye coordinates
f = Fog coefficient

Fallbacks and Approximations

1. An implementation may approximate per-pixel fog by calculating the cor-
rect fogged color at each vertex and then linearly interpolating this color
across the primitive.
2. An implementation may approximate exponential fog using linear fog by
computing values of F and B that cause the resulting linear fog ramp to
most closely match the effect of the specified exponential fog function.
3. An implementation will ideally perform the fog calculations in eye coor-
dinates, which is an affine space. However, an implementation may ap-
proximate this by performing the fog calculations in a perspective space
(such as, device coordinates). As with other approximations, the imple-
mentation should match the specified function as closely as possible.

E.2 Lighting Equations

The ideal lighting equation is as follows:
Numamb Numlt
Me + Ma ⋅ ∑ ( Lc i ) + ∑ ( atten i ⋅ spot i ⋅ ( diff i + spec i ) ) (E.4)
i i

diff i = ( L i • N ) ⋅ Lc i ⋅ Md (E.5)

shin
spec i = ( S i • N ) ⋅ Lc i ⋅ Ms (E.6)

Note: If (Li • N) ≤ 0, then diffi and speci are set to 0.

2
atten i = 1 ⁄ ( K c i + K l i ⋅ d i + K q i ⋅ d i ) (E.7)

Note: For directional lights, atteni is set to 1.

exp i
spot i = max ( ( – L i ⋅ D i ) ,0 ) (E.8)

544 The Java 3D API Specification

EQUATIONS Lighting Equations E.2

Note: If the vertex is outside the spot light cone, as defined by the cutoff angle,
spoti is set to 0. For directional and point lights, spoti is set to 1.

This is a subset of OpenGL in that the Java 3D ambient and directional lights are
not attenuated and only ambient lights contribute to ambient lighting.
The parameters used in the lighting equation are as follows:

E = Eye vector
Ma = Material ambient color
Md = Material diffuse color
Me = Material emissive color
Ms = Material specular color
N = Vertex normal
shin = Material shininess

The per-light values are as follows:

di = Distance from vertex to light

Di = Spot light direction
expi = Spot light exponent
Kci = Constant attenuation
Kli = Linear attenuation
Kqi = Quadratic attenuation
Li = Direction from vertex to light
Lci = Light color
Si = Specular half-vector = || (Li + E) ||

Fallbacks and Approximations

1. An implementation may approximate the specular function using a differ-
ent power function that produces a similar specular highlight. For example,
the PHIGS+ lighting model specifies that the reflection vector (the light
vector reflected about the vertex normal) is dotted with the eye vector, and
that this dot product is raised to the specular power. An implementation
that uses such a model should map the shininess into an exponent that most
closely matches the effect produced by the ideal equation.

Version 1.2, March 2000 545

E.3 Sound Equations EQUATIONS

2. Implementations that do not have a separate ambient and diffuse color may
fall back to using an ambient intensity as a percentage of the diffuse color.
This ambient intensity should be calculated using the NTSC luminance
equation:

I = 0.30 ⋅ Red + 0.59 ⋅ Green + 0.11 ⋅ Blue (E.9)

E.3 Sound Equations

There are different sets of sound equations, depending on whether the application
uses headphones or speakers.

E.3.1 Headphone Playback Equations

For each sound source, Java 3D calculates a separate left and right output signal.
Each left and right sound image includes differences in the interaural intensity
and an interaural delay. The calculation results are a set of direct and indirect
(delayed) sound signals mixed together before being sent to the audio playback
system’s left and right transducers.

E.3.1.1 Interaural Time Difference (Delay)

For each PointSound and ConeSound source, the left and right output signals are
delayed based on the location of the sound and the orientation of the listener’s
head. The time difference between these two signals is called the interaural time
difference (ITD). The time delay of a particular sound reaching an ear is affected
by the arc the sound must travel around the listener’s head. Java 3D uses an
approximation of the ITD using a spherical head model. The interaural path dif-
ference is calculated based on the following cases:
1. The signal from the sound source to only one of the ears is direct. The ear
farthest from the sound is shadowed by the listener’s head
( sinα ≥ De ⁄ 2Dh ); see Figure E-1:

Ec = Vc
(E.10)
Ef = Vt + P
where

De π
P = -------  --- – ( γ – α )
2 2 

546 The Java 3D API Specification

EQUATIONS Headphone Playback Equations E.3.1

De Va
γ
α
Vt
Dh Vh

Vc

Figure E-1 Signal to Only One Ear Is Direct

2. The signals from the sound source reach both ears by indirect paths around
the head ( sinα < De ⁄ 2Dh ); see Figure E-2:
Ec = Vt + P′
(E.11)
Ef = Vt + P
where

De π
P = -------  --- – ( γ – α )
2 2 

De π
P' = -------  --- – ( γ + α )
2 2 

The time from the sound source to the closest ear is Ec ⁄ S , and the time from the
sound source to the farthest ear is Ef ⁄ S , where S is the current AuralAttribute
region’s speed of sound.
If the sound is closest to the left ear, then

IT D l = Ec ⁄ S
(E.12)
IT D r = Ef ⁄ S

If the sound is closest to the right ear, then

IT D l = Ef ⁄ S
(E.13)
IT D r = Ec ⁄ S

Version 1.2, March 2000 547

E.3.1 Headphone Playback Equations EQUATIONS

De γ Va
α
γ Dh Vh Vt

Vt
P'

Figure E-2 Signals to Both Ears Are Indirect

The parameters used in the ITD equations are as follows:

α = The smaller of the angles between Vh (or –Vh) and Va in radians

γ = Angle between Vh and radius to tangent point on Vt in radians
De = Distance between ears (interaural distance)
Dh = Distance from interaural center to sound source
Ec = Distance from sound source to ear closest to sound
Ef = Distance from sound source to ear farthest from sound
P, P' = Arc path around the head an indirect signal must travel to reach an
ear
S = Speed of sound for the current AuralAttribute region
Va = Vector from center ear forward parallel to Z axis of head coordi-
nates
Vc = Vector from sound source to ear closest to sound
Vh = Vector from center ear to sound source
Vt = Vector from sound source to tangent point on the listener’s head

E.3.1.2 Interaural Intensity (Gain) Difference

For each active and playing Point and ConeSound source, i, separate calculations
for the left and right signal (based on which ear is closest and which is farthest to
the source) are combined with nonspatialized BackgroundSound to create a ste-

548 The Java 3D API Specification

EQUATIONS Headphone Playback Equations E.3.1

reo sound image. Each equation below is calculated separately for the left and
right ear.
numS

∑ [ G i ⋅ ( F i • [ ITD i • Sample ( t ) ] ) ] (E.14)

I ( t ) = ------------------------------------------------------------------------------------------
i
maxNumS

Note: For BackgroundSound sources ITDi is an identity function so there is no

delay applied to the sample for these sources.

G i = Gi i ⋅ Gd i ⋅ Ga i ⋅ Gr i (E.15)

Note: For BackgroundSound sources Gdi = Gai = 1.0. For PointSound sources
Gai = 1.0.

F i = Fd i • Fa i (E.16)

Note: For BackgroundSound sources Fdi and Fai are identity functions. For
PointSound sources Fai is an identity function.

If the sound source is on the right side of the head, Ec is used for left G and F
calculations and Ef is used for right. Conversely, if the Sound source is on the
left side of the head, Ef is used for left calculations and Ec is used for right.

Attenuation
For sound sources with a single distanceGain array defined, the intersection
points of Vh (the vector from the sound source position through the listener’s
position) and the spheres (defined by the distanceGain array) are used to find the
index k where dk ≤ L ≤ dk+1. See Figure E-3.
For ConeSound sources with two distanceGain arrays defined, the intersection
points of Vh and the ellipsi (defined by both the front and back distanceGain
arrays) closest to the listener’s position are used to determine the index k. See
Figure E-4.
The equation for the distance gain is

( Gd k + 1 – Gd k ) ⋅ ( d 2 – d 1 )
Gd = Gd k + --------------------------------------------------------------- (E.17)
L – d1

Version 1.2, March 2000 549

E.3.1 Headphone Playback Equations EQUATIONS

Vh A = (d , Gd )
k k
B = (dk+1, Gdk+1)
B C = (αk, Gak)
D D = (αk+1, Gak+1)
Listener
A

C
α

Figure E-3 ConeSound with a Single Distance Gain Attenuation Array

A = (d1, Gdk)
B = (d2, Gdk+1)
C = (αk, Gak)
D = (αk+1, Gak+1)

Vh
B
frontDistanceAttenuation[] D
A Listener
C
α

backDistanceAttenuation[] frontDistanceAttenuation[]

Figure E-4 ConeSound with Two Distance Attenuation Arrays

Angular attenuation for both the spherical and elliptical cone sounds is identical.
The angular distances in the attenuation array closest to α are found and define
the index k into the angular attenuation array elements. The equation for the
angular gain is

( Ga k + 1 – Ga k ) ⋅ ( α k + 1 – α k )
Ga = Ga k + ---------------------------------------------------------------------- (E.18)
α – αk

550 The Java 3D API Specification

EQUATIONS Headphone Playback Equations E.3.1

Filtering
Similarly, the equations for calculating the AuralAttributes distance filter and the
ConeSound angular attenuation frequency cutoff filter are

( Fd k + 1 – Fd k ) ⋅ ( d 2 – d 1 )
Fd = Fd k + -------------------------------------------------------------
- (E.19)
L – d1

( Fa k + 1 – Fa k ) ⋅ ( α k + 1 – α k )
Fa = Fa k + --------------------------------------------------------------------
- (E.20)
α – αk

An N-pole lowpass filter may be used to perform the simple angular and distance
filtering defined in this version of Java 3D. These simple lowpass filters are
meant only as an approximation for full, FIR filters (to be added in some future
version of Java 3D).

Fallbacks and Approximations

1. If more than one lowpass filter is to be applied to the sound source (for ex-
ample, both an angular filter and a distance filter are applied to a Cone-
Sound source) it is only necessary to use a single filter, specifically the one
that has the lowest cutoff frequency.
2. There is no requirement to support anything higher than very simple two-
pole filtering. Any type of multipole lowpass filter can be used. If higher
N-pole or compound filtering are available on the device on which sound
rendering is being performed, use of these is encouraged, but not required.
The parameters used in the interaural intensity difference (IID) equations are as
follows:

A, B = Triples containing DistanceGain linear distance, gain scale fac-

tor, and AuralAttribute cutoff frequency
C, D = Triples containing AngularAttenuation angular distance, gain
scale factor, and cutoff frequency
α = Angle between Vh and Va in radians
Ec = Distance from sound source to ear closest to sound from the ITD
equation
Ef = Distance from sound source to ear farthest from sound source
from the ITD equation
Fa = Angular filter from ConeSound definition

Version 1.2, March 2000 551

E.3.1 Headphone Playback Equations EQUATIONS

Fd = Distance filter from AuralAttributes

Ga = Angular gain attenuation scale factor
Gd = Distance gain attenuation scale factor
Gi = Initial gain scale factor
Gr = Current AuralAttribute region’s gain scale factor
I = Stereo sound image
L = Listener distance from sound source
maxNumS = Maximum number of sound sources for the audio device that the
application is using for playback
numS = Number of sound sources
sample = Sound digital sample with a specific sample rate, bit precision,
and an optional encoding and/or compression format
Vh = Vector from center ear to sound source

E.3.1.3 Doppler Effect Equations

Between two snapshots of the head and the sound source positions some delta
time apart, the distance between the head and source is compared. If there has
been no change in the distance between the head and the sound source over this
delta time, the Doppler effect equation is as follows:

f′ = f (E.21)

If there has been a change in the distance between the head and the sound, the
Doppler effect equation is as follows:

f′ = f ⋅ Af ⋅ v (E.22)

When the head and sound are moving towards each other (the velocity ratio is
greater than 1.0), the velocity ratio equation is as follows:

( S ⋅ Ar ) + ( ∆v ( h, t ) ⋅ Av )
v = ------------------------------------------------------------- (E.23)
( S ⋅ Ar ) – ( ∆v ( s, t ) ⋅ Av )
When the head and sound are moving away from each other (the velocity ratio is
less than 1.0), the velocity ratio equation is as follows:

( S ⋅ Ar ) – ( ∆v ( h, t ) ⋅ Av )
v = ------------------------------------------------------------- (E.24)
( S ⋅ Ar ) + ( ∆v ( s, t ) ⋅ Av )

552 The Java 3D API Specification

EQUATIONS Headphone Playback Equations E.3.1

The parameters used in the Doppler effect equations are as follows:

Af = AuralAttribute frequency scale factor

Ar = AuralAttribute rolloff scale factor
Av = AuralAttribute velocity scale factor
∆v = Delta velocity
f = Frequency of sound
h = Listener’s head position
v = Ratio of delta velocities
Vh = Vector from center ear to sound source
s = Sound source position
S = Speed of sound
t = Time

Note: If the adjusted velocity of the head or the adjusted velocity of the sound is
greater than the adjusted speed of sound, f′ is undefined.

E.3.1.4 Reverberation Equations

The overall reverberant sounds, used to give the impression of the aural space in
which the active/enabled source sources are playing, is added to the stereo sound
image output from equation E.14.
numS
I′ ( t ) [ l, r ] = I ( t ) [ l, r ] + ∑ Ri (E.25)
i

Reverberation for each sound is approximated in the following:

fLoop

∑
j
Ri = [ ( Gr ⋅ Sample ( t ) i ) • D ( t + ( Tr ⋅ j ) ) ] (E.26)
j

Note that the reverberation calculation outputs the same image to both left and
right output signals (thus there is a single monaural calculation for each sound
reverberated). Correct first-order (early) reflections, based on the location of the
sound source, the listener, and the active AuralAttribute’s bounds, are not
required for this version of Java 3D. Approximations based on the reverberation

Version 1.2, March 2000 553

E.3.2 Speaker Playback Equations EQUATIONS

delay time, either suppled by the application or calculated as the average delay
time within the selected AuralAttribute’s application region, will be used.
The feedback loop is repeated until AuralAttribute’s reverberation feedback loop
count is reached or Grj ≤ 0.000976 (effective zero amplitude, –60 dB, using the
measure of –6 dB drop for every doubling of distance).

Fallbacks and Approximations

1. Reducing the number of feedback loops repeated while still maintaining
the overall impression of the environment. For example, if –10 dB were
used as the drop in gain for every doubling of distance, a scale factor of
0.015625 could be used as the effective zero amplitude, which can be
reached in only 15 loop iterations (rather than the 25 needed to reach
0.000976).
2. Using preprogrammed “room” reverberation algorithms that allow selec-
tion of a fixed set of “reverberation types” (for example, large hall, small
living room), which have implied reflection coefficients, delay times, and
feedback loop durations.
The parameters used in the reverberation equations are as follows:

D = Delay function
fLoop = Reverberation feedback loop count
Gr = Reverberation coefficient acting as a gain scale-factor
I = Stereo image of unreflected sound sources
R = Reverberation for each sound sources
Sample = Sound digital sample with a specific sample rate, bit precision,
and an optional encoding and/or compression format
t = Time
Tr = Reverberation delay time (approximating first-order delay in the
AuralAttribute region)

E.3.2 Speaker Playback Equations

Different speaker playback equations are used depending on whether the system
uses monaural or stereo speakers.

554 The Java 3D API Specification

EQUATIONS Speaker Playback Equations E.3.2

E.3.2.1 Monaural Speaker Output

The equations for headphone playback need only be modified to output a single
signal, rather than two signals for left and right transducers. Although there is
only one speaker, distance and filter attenuation, Doppler effect, elevation, and
front and back cues can be distinguished by the listener and should be included
in the sound image generated.

E.3.2.2 Stereo Speaker Output

In a two-speaker playback system, the signal from one speaker is actually heard
by both ears and this affects the spectral balance and interaural intensity and time
differences heard by each of the listener’s ears. Cross-talk cancellation must be
performed on the right and left signal to compensate for the delayed attenuated
signal heard by the ear opposite the speaker. Thus a delayed attenuated signal for
each of the stereo signals must be added to the output from the equations for
headphone playback.
The equations for stereo speaker playback assume that the two speakers are
placed symmetrically about the listener (at the same off-axis angle from the
viewing axis at an equal distance from the center of the listener’s head).

I′ ( t ) l = I ( t ) l + [ D ( t ) • [ G ( P, α ) ⋅ I ( t ) r ] ] (E.27)

I′ ( t ) r = I ( t ) r + [ D ( t ) • [ G ( P, α ) ⋅ I ( t ) l ] ] (E.28)

The parameters used in the cross-talk equations, expanding on the terms used for
the equations for headphone playback, are as follows:

α = Angle between vectors from speaker to near and far ears

D = Delay function of signal variant over time
G = Gain attenuation scale factors function taking initial distance and an-
gular gain scale factors into account
I = Sound image for left and right stereo signals calculated as for head-
phone output
P = Distance difference between near ear and far ear as defined for ITD,
the speaker substituted for the sound source in equation
t = Time

Version 1.2, March 2000 555

E.4 Texture Mapping Equations EQUATIONS

E.4 Texture Mapping Equations

Texture mapping can be divided into two steps. The first step takes the trans-
formed s and t (and possibly r) texture coordinates, the current texture image,
and the texture filter parameters, and computes a texture color based on looking
up the texture coordinates in the texture map. The second step applies the com-
puted texture color to the incoming pixel color using the specified texture mode
function.

E.4.1 Texture Lookup

The texture lookup stage maps a texture image onto a geometric polygonal prim-
itive. The most common method for doing this is to reverse map the s and t coor-
dinates from the primitive back onto the texture image, then filter and resample
the image. In the simplest case, a point in s, t space is transformed into a u, v
address in the texture image space (E.29), then this address is used to look up the
nearest texel value in the image. This method, used when the selected texture fil-
ter function is BASE_LEVEL_POINT, is called nearest-neighbor sampling or point
sampling.

u = s ⋅ width
(E.29)
v = t ⋅ height

i = trunc ( u )
(E.30)
j = trunc ( v )

Ct = T i, j (E.31)

If the texture boundary mode is REPEAT, then only the fractional bits of s and t
are used, ensuring that both s and t are less than 1.
If the texture boundary mode is CLAMP, then the s and t values are clamped to be
in the range [0, 1] before being mapped into u and v values. Further, if s ≥ 1, then
i is set to width – 1; if t ≥ 1, then j is set to height – 1.
The parameters in the point-sampled texture lookup equations are as follows:

width = Width, in pixels, of the texture image

height = Height, in pixels, of the texture image
s = Interpolated s coordinate at the pixel being textured
t = Interpolated t coordinate at the pixel being textured

556 The Java 3D API Specification

EQUATIONS Texture Lookup E.4.1

u = u coordinate in texture image space

v = v coordinate in texture image space
i = Integer row address into texture image
j = Integer column address into texture image
T = Texture image

The above equations are used when the selected texture filter function—either
the minification or the magnification filter function—is BASE_LEVEL_POINT.
Java 3D selects the appropriate texture filter function based on whether the tex-
ture image is minified or magnified when it is applied to the polygon. If the tex-
ture is applied to the polygon such that more than one texel maps onto a single
pixel, then the texture is said to be minified and the minification filter function is
selected. If the texture is applied to the polygon such that a single texel maps
onto more than one pixel, then the texture is said to be magnified and the magni-
fication filter function is selected. The selected function is one of the following:
BASE_LEVEL_POINT, BASE_LEVEL_LINEAR, MULTI_LEVEL_POINT, or MULTI_
LEVEL_LINEAR. In the case of magnification, the filter will always be one of the
two base level functions (BASE_LEVEL_POINT or BASE_LEVEL_LINEAR).
If the selected filter function is BASE_LEVEL_LINEAR, then a weighted average of
the four texels that are closest to the sample point in the base level texture image
is computed.

i 0 = trunc ( u – 0.5 )

j 0 = trunc ( v – 0.5 )
(E.32)
i1 = i0 + 1

j1 = j0 + 1

α = frac ( u – 0.5 )
(E.33)
β = frac ( v – 0.5 )

Ct = ( 1 – α ) ⋅ ( 1 – β ) ⋅ T i0, j0 + α ⋅ ( 1 – β ) ⋅ T i1, j0
(E.34)
+ ( 1 – α ) ⋅ β ⋅ T i0, j1 + α ⋅ β ⋅ T i1, j1

If the selected filter function is MULTI_LEVEL_POINT or MULTI_LEVEL_LINEAR,

the texture image needs to be sampled at multiple levels of detail. If multiple lev-
els of detail are needed and the texture object only defines the base level texture
image, Java 3D will compute multiple levels of detail as needed.

Version 1.2, March 2000 557

E.4.2 Texture Application EQUATIONS

Mipmapping is the most common filtering technique for handling multiple levels
of detail. If the implementation uses mipmapping, the equations for computing a
texture color based on texture coordinates are simply those used by the underly-
ing rendering API (such as OpenGL or PEX). Other filtering techniques are pos-
sible as well.

Fallbacks and Approximations

1. If the texture boundary mode is CLAMP, an implementation may either use
the closest boundary pixel or the constant boundary color attribute for
those values of s or t that are outside the range [0, 1].
2. An implementation can choose a technique other than mipmapping to per-
form the filtering of the texture image when the texture minification filter
is MULTI_LEVEL_POINT or MULTI_LEVEL_LINEAR.
3. If mipmapping is chosen by an implementation as the method for filtering,
it may approximate trilinear filtering with another filtering technique. For
example, an OpenGL implementation may choose to use LINEAR_MIPMAP_
NEAREST or NEAREST_MIPMAP_LINEAR in place of LINEAR_MIPMAP_LIN-
EAR.

E.4.2 Texture Application

Once a texture color has been computed, this color is applied to the incoming
pixel color. If lighting is enabled, only the emissive, ambient, and diffuse compo-
nents of the incoming pixel color are modified. The specular component is added
into the modified pixel color after texture application.
The equations for applying that color to the original pixel color are based on the
texture mode, as follows:

REPLACE Texture Mode

C′ = Ct (E.35)

MODULATE Texture Mode

C′ = C ⋅ Ct (E.36)

558 The Java 3D API Specification

EQUATIONS Texture Application E.4.2

DECAL Texture Mode

C′ rgb = C rgb ⋅ ( 1 – Ct α ) + Ct rgb ⋅ Ct α

(E.37)
C′ α = Cα

Note that the texture format must be either RGB or RGBA.

BLEND Texture Mode

C′ rgb = C rgb ⋅ ( 1 – Ct rgb ) + Cb rgb ⋅ Ct rgb

(E.38)
C′ α = C α ⋅ Ct α

Note that if the texture format is INTENSITY, alpha is computed identically to red,
green, and blue:

C′ α = C α ⋅ ( 1 – Ct α ) + Cb α ⋅ Ct α (E.39)

The parameters used in the texture mapping equations are as follows:

C = Color of the pixel being texture mapped (if lighting is enabled, then
this does not include the specular component)
Ct = Texture color
Cb = Blend color

Note that Crgb indicates the red, green, and blue channels of color C and that Cα
indicates the alpha channel of color C. This convention applies to the other color
variables as well.
If there is no alpha channel in the texture, a value of 1 is used for Ctα in BLEND
and DECAL modes.
When the texture mode is one of REPLACE, MODULATE, or BLEND, only certain of
the red, green, blue, and alpha channels of the pixel color are modified, depend-
ing on the texture format, as described below.
• INTENSITY: All four channels of the pixel color are modified. The inten-
sity value is used for each of Ctr, Ctg, Ctb, and Ctα in the texture applica-
tion equations, and the alpha channel is treated as an ordinary color
channel—the equation for C´rbg is also used for C´α.
• LUMINANCE: Only the red, green, and blue channels of the pixel color
are modified. The luminance value is used for each of Ctr, Ctg, and Ctb in

Version 1.2, March 2000 559

E.4.2 Texture Application EQUATIONS

the texture application equations. The alpha channel of the pixel color is
unmodified.
• ALPHA: Only the alpha channel of the pixel color is modified. The red,
green, and blue channels are unmodified.
• LUMINANCE_ALPHA: All four channels of the pixel color are modified.
The luminance value is used for each of Ctr, Ctg, and Ctb in the texture ap-
plication equations, and the alpha value is used for Ctα.
• RGB: Only the red, green, and blue channels of the pixel color are modi-
fied. The alpha channel of the pixel color is unmodified.
• RGBA: All four channels of the pixel color are modified.

Fallbacks and Approximations

An implementation may apply the texture to all components of the lit color,
rather than separating out the specular component. Conversely, an implementa-
tion may separate out the emissive and ambient components in addition to the
specular component, potentially applying the texture to the diffuse component
only.

560 The Java 3D API Specification

 A PPE N D I X F
The Utility Packages

THIS appendix summarizes the Java 3D utilities packages.

F.1 The Utility Packages
The com.sun.j3d.* packages provide aids to assist the application programmer in
setting up a user environment and getting a Java 3D application up and running as
quickly as possible. The utilities packages contain classes that are not part of the
formal Java 3D API specification. Since these packages are not part of the API
specification, they are subject to change and will evolve over time.
The most useful of these packages are the following:
• utils.universe – contains the SimpleUniverse class, which defines a
minimal user environment that includes all of the necessary objects on the
“view” side of the scene graph. See Section F.17, “utils.universe Package,”
for a description of this package.
• utils.geometry – contains geometry utilities, such as stripification, nor-
mal generation, tessellation, and primitive construction. See Section F.13,
“utils.geometry Package,” for a description of this package.
• utils.picking – contains the PickIntersection, PickTool, PickCanvas,
and PickResult classes, which simplify the construction of picking rou-
tines. See Section F.15, “utils.picking Package,” for a description of this
package.
• loaders – contains the Loader and Scene interfaces, which can be used to
implement a variety of Java 3D loaders in a standard manner. See
Section F.5, “loaders Package,” for a description of this package.

Version 1.2, March 2000 561

F.2 Package Overview THE UTILITY PACKAGES

F.2 Package Overview

The Java 3D utilities packages are all in the com.sun.j3d hierarchy. Table F-1 lists
the utilities packages.
Table F-1 Utilities Packages
Package Name Description

audioengines Useful only to people writing audio device drivers.

audioengines.javasound Defines an audio output device that accesses JavaSound’s

sound mixer functionality.

loaders Used in the construction of file loaders.

loaders.lw3d Implements a loader for Lightwave 3D scene files.

loaders.objectfile Implements a loader for Wavefront object files.

utils.applet Enables creating Java applets that can also run as stand-
alone applications.

utils.behaviors.interpolators Enhances the Interpolator class with the TCB (Kochanek-

Bartels) spline interpolation.

utils.behaviors.keyboard Useful for controlling the scene graph behavior from the
keyboard.

utils.behaviors.mouse Useful for controlling scene graph behavior with the

mouse, specifically object rotation, translation, and zoom.

utils.compression Useful for geometry compression.

utils.geometry Includes geometry utilities, such as stripification, normal

generation, tessellation, and primitive construction.

utils.image Useful for loading Java 3D texture objects.

utils.picking Useful for defining picking operations and retrieving in-

formation about the picked object.

utils.picking.behaviors Combines picking with mouse-based rotation, translation,

and zoom behaviors.

utils.universe Useful for setting up a user environment to quickly and

easily get a Java 3D program up and running.

562 The Java 3D API Specification

THE UTILITY PACKAGES audioengines.javasound Package F.4

F.3 audioengines Package

The com.sun.j3d.audioengines package is useful only to people writing audio
device drivers. Java 3D application developers are not expected to use the classes
in this package.
Table F-2 lists the classes in the com.sun.j3d.audioengines package.
Table F-2 audioengines Classes
Class Description

AudioEngine Extends: Object

Implements: AudioDevice
Encapsulates basic information about the AudioDevice, such
as the playback type (headphones, monaural speakers, or ste-
reo speakers) and the listener’s distance from the speakers.

AudioEngine3D Extends: AudioEngine

Implements: AudioDevice3D
Defines an audio output device that generates sound “image”
from high-level sound parameters passed to it while the scene
graph is active.

AuralParameters Extends: Object

Defines a set of fields that correspond to AuralAttribute fields.

Sample Extends: Object

Defines the data and methods associated with a sound sample
played through the AudioDevice.

F.4 audioengines.javasound Package

The com.sun.j3d.audioengines.javasound package contains a single public
class that implements a JavaSound-based audio device. Most programs should let
the SimpleUniverse (or Viewer) class in the universe package construct the audio
device.
Table F-3 lists the class in the com.sun.j3d.audioengines.javasound package.
Table F-3 audioengines.javasound Package
Class Description

JavaSoundMixer Extends: AudioEngine3D

Defines an audio output device that accesses JavaSound’s
sound mixer functionality.

Version 1.2, March 2000 563

F.5 loaders Package THE UTILITY PACKAGES

F.5 loaders Package

The com.sun.j3d.loaders package contains two interfaces, Loader and Scene,
that can be used to implement a variety of Java 3D loaders in a standard manner.
Base classes that implement these interfaces are also included as a convenience.

F.5.1 Interfaces
Table F-4 lists the interfaces in the com.sun.j3d.loaders package.
Table F-4 loaders Package Interfaces
Interface Description

Loader Used to specify the location and elements of a file format to

load. The interface is used to give loaders of various file for-
mats a common public interface.

Scene A set of methods used to extract Java 3D scene graph informa-

tion from a file loader utility. The interface is used to give
loaders of various file formats a common public interface.

F.5.2 Classes
Table F-5 lists the classes in the com.sun.j3d.loaders package.
Table F-5 loaders Package Classes
Class Description

LoaderBase Extends: Object

Implements: Loader
Abstract base class that can be used as a starting point for a
Loader. A specific file loader could extend this class and im-
plement the load methods.

SceneBase Extends: Object

Implements: Scene
Responsible for both the storage and retrieval of data from the
Scene. Most loaders will not need to extend this class.

F.5.3 Exceptions
Table F-6 lists the exceptions in the com.sun.j3d.loaders package.

564 The Java 3D API Specification

THE UTILITY PACKAGES loaders.objectfile Package F.7

Table F-6 loaders Package Exceptions

Exception Description

IncorrectFormatException Extends: RuntimeException

Indicates that a file of an incorrect type was passed to a loader.

ParsingErrorException Extends: RuntimeException

Indicates that the loader encountered a problem parsing the
specified file.

F.6 loaders.lw3d Package

The com.sun.j3d.loaders.lw3d package provides a file loader that allows appli-
cations to load Lightwave 3D scene files.
Table F-7 lists the class in the com.sun.j3d.loaders.lw3d package.
Table F-7 loaders.lw3d Package
Class Description

Lw3dLoader Extends: loaders.lw3d.TextfileParser

Implements: Loader
Allows users to load Lightwave 3D scene files.

F.7 loaders.objectfile Package

The com.sun.j3d.loaders.objectfile package provides a file loader that
allows applications to load Wavefront object files.
Table F-8 lists the class in the com.sun.j3d.loaders.objectfile package.
Table F-8 loaders.objectfile Package
Class Description

ObjectFile Extends: Object

Implements: Loader
Implements the Loader interface for the Wavefront .obj file
format, a standard 3D object file format created for use with
Wavefront’s Advanced Visualizer™ and available for pur-
chase from Viewpoint DataLabs, as well as other 3D model
companies.

Version 1.2, March 2000 565

F.8 utils.applet Package THE UTILITY PACKAGES

F.8 utils.applet Package

The com.sun.j3d.utils.applet package includes a single class, MainFrame,
that enables the creation of Java applets that can also run as stand-alone applica-
tions. The MainFrame class was developed by Jef Poskanzer of Acme Labs
<jef@acme.com>.
Table F-9 lists the class in the com.sun.j3d.applet package.
Table F-9 utils.applet Package
Class Description

MainFrame Extends: Frame

Implements: java.lang.Runnable, java.applet.AppletStub,
java.applet.AppletContext
Allows a Java applet to run as an application.

F.9 utils.behaviors.interpolators Package

The com.sun.j3d.utils.behaviors.interpolators package provides spline-
based interpolators using KCB (Kochanek-Bartels) splines (also known as the TCB
or Tension-Continuity-Bias spline). Applications can use these interpolators to
implement key-frame animation sequences.
Table F-10 lists the classes in the com.sun.j3d.utils.behaviors.interpola-
tors package.
Table F-10 utils.behaviors.interpolators Package
Class Description

KBCubicSplineCurve Extends: Object

A container class that holds a number of cubic spline seg-
ments.

KBCubicSplineSegment Extends: Object

Creates the representation of a KB (Kochanek-Bartels Spline).

KBKeyFrame Extends: Object

Represents a Key Frame that can be used for Kochanek-Bar-
tels spline interpolation.

566 The Java 3D API Specification

THE UTILITY PACKAGES utils.behaviors.mouse Package F.11

Table F-10 utils.behaviors.interpolators Package (Continued)

Class Description

KBRotPosScaleSplinePathIn- Extends: KBSplinePathInterpolator

terpolator Defines a behavior that varies the rotational, translational, and
scale components of its target TransformGroup by using the
Kochanek-Bartels cubic spline interpolation to interpolate
among a series of key frames (using the value generated by the
specified Alpha object). The interpolated position, orientation,
and scale are used to generate a transform in the local coordi-
nate system of this interpolator.

KBSplinePathInterpolator Extends: Interpolator

Defines the base class for all KB (Kochanek-Bartels) Spline
Path Interpolators.

F.10 utils.behaviors.keyboard Package

The com.sun.j3d.utils.behaviors.keyboard package contains classes that
take keyboard events and turns them into transform changes that are suitable for
use in modifying the ViewPlatform’s transformation matrix for navigation.
Table F-11 lists the classes in the com.sun.j3d.utils.behaviors.keyboard
package.
Table F-11 utils.behaviors.keyboard Package
Class Description

KeyNavigator Extends: Object

Accumulates AWT key events (key press and key release) and
computes a new transform based on the accumulated events
and elapsed time.

KeyNavigatorBehavior Extends: Behavior

A simple behavior that invokes the KeyNavigator to modify
the view platform transform.

F.11 utils.behaviors.mouse Package

The com.sun.j3d.utils.behaviors.mouse package contains classes that use
mouse events to modify object or viewing transformations. Subclasses exist to per-
form rotation, translation, and zoom operations.

Version 1.2, March 2000 567

F.11.1 Interfaces THE UTILITY PACKAGES

F.11.1 Interfaces
Table F-12 lists the interface in the com.sun.j3d.utils.behaviors.mouse pack-
age.
Table F-12 utils.behaviors.mouse Package Interface
Interface Description

MouseBehaviorCallback Allows a class to be notified when the transform is changed by

one of the MouseBehaviors. The class that is interested in
transform changes implements this interface, and the object
created with that class is registered with the desired subclass
of MouseBehavior using the setupCallback method. When
the transform changes, the registered object’s transform-
Changed method is invoked.

F.11.2 Classes
Table F-13 lists the classes in the com.sun.j3d.utils.behaviors.mouse pack-
age.
Table F-13 utils.behaviors.mouse Package Classes
Class Description

MouseBehavior Extends: Behavior

The base class for all mouse manipulators (MouseRotate,
MouseZoom, and MouseTranslate).

MouseRotate Extends: MouseBehavior

A Java 3D behavior object that lets users control the rotation
of an object via a mouse.

MouseTranslate Extends: MouseBehavior

A Java 3D behavior object that lets users control the transla-
tion (X, Y) of an object via a mouse drag motion with the third
mouse button (alt-click on PC).

MouseZoom Extends: MouseBehavior

A Java 3D behavior object that lets users control the Z axis
translation of an object via a mouse drag motion with the sec-
ond mouse button.

F.12 utils.compression Package

The com.sun.j3d.utils.compression package includes classes for compressing
geometry and for reading and writing compressed geometry resource files.

568 The Java 3D API Specification

THE UTILITY PACKAGES utils.geometry Package F.13

Table F-14 lists the classes in the com.sun.j3d.utils.compression package.

Table F-14 utils.compression Package
Class Description

CompressedGeometryFile Extends: Object

Provides methods to read and write compressed geometry re-
source files. These files usually end with the .cg extension and
support sequential as well as random access to multiple com-
pressed geometry objects.

CompressionStream Extends: Object

Used as input to a geometry compressor. It collects elements
such as vertices, normals, colors, mesh references, and quanti-
zation parameters in an ordered stream. This stream is then tra-
versed during the compression process and used to build the
compressed output buffer.

GeometryCompressor Extends: Object

Takes a stream of geometric elements and quantization param-
eters (the CompressionStream object) and compresses it into a
stream of commands as defined in Appendix B, “3D Geome-
try Compression.” The resulting data may be output in the
form of a CompressedGeometry node component or appended
to a CompressedGeometryFile.

F.13 utils.geometry Package

The com.sun.j3d.utils.geometry package contains geometry utilities, such as
stripification, normal generation, tessellation (polygon triangulation), and primi-
tive construction. The GeometryInfo class provides a common data storage format
for the stripification, normal generation and tessellation classes.
Table F-15 lists the classes in the com.sun.utils.geometry package.
Table F-15 utils.geometry Package
Class Description

Box Extends: Primitive

A geometry primitive created with a given length, width, and
height.

ColorCube Extends: Shape3D

A simple color-per-vertex cube with a different color for each
face.

Version 1.2, March 2000 569

F.13 utils.geometry Package THE UTILITY PACKAGES

Table F-15 utils.geometry Package (Continued)

Class Description

Cone Extends: Primitive

A geometry primitive defined with a radius and a height. It is
a capped cone centered at the origin with its central axis
aligned along the Y-axis.

Cylinder Extends: Primitive

A geometry primitive defined with a radius and a height. It is
a capped cylinder centered at the origin with its central axis
aligned along the Y-axis.

GeometryInfo Extends: Object

The object where you put your geometry if you want to use the
Java 3D utility packages. Once you have your data in the Ge-
ometryInfo object, you can send it to any (or all) of several
utilities to have operations performed on it, such as generating
normals or turning it into long strips for more efficient render-
ing. Geometry is loaded just as it is in the Java 3D Geometr-
yArray object, but there are fewer options for getting data into
the object. GeometryInfo itself contains some simple utilities,
such as calculating indices for non-indexed data (“indexify-
ing”) and getting rid of unused data in your indexed geometry
information (“compacting”).

NormalGenerator Extends: Object

Calculates and fills the normals of a GeometryInfo object. The
normals are computed based on an analysis of the indexed co-
ordinate information.

Primitive Extends: Group

The base class for all Java 3D primitives.

Sphere Extends: Primitive

A geometry primitive created with a given radius and resolu-
tion. It is centered at the origin.

Stripifier Extends: Object

Changes the primitive of the GeometryInfo object to triangle
strips. The strips are made by analyzing the triangles in the
original data and connecting them together.

570 The Java 3D API Specification

THE UTILITY PACKAGES utils.picking Package F.15

Table F-15 utils.geometry Package (Continued)

Class Description

Text2D Extends: Shape3D

Creates a texture-mapped rectangle that displays the text string
supplied by the user, given the appearance parameters also
supplied by the user.

Triangulator Extends: Object

Turns arbitrary polygons into triangles so they can be rendered
by Java 3D. Polygons can be concave, nonplanar, and can con-
tain holes (see GeometryInfo).

F.14 utils.image Package

The com.sun.j3d.utils.image package contains a single class, TextureLoader,
that is used to load a Java 3D texture object from a file. It will automatically scale
the image to a power of two and, optionally, compute mipmaps.
Table F-16 lists the class in the com.sun.j3d.utils.image package.
Table F-16 utils.image Package
Class Description

TextureLoader Extends: Object

Used for loading a texture from an Image or BufferedImage.
Methods are provided to retrieve the Texture object and the as-
sociated ImageComponent object or a scaled version of the
ImageComponent object. The default format is RGBA. Other
legal formats are: RGBA, RGBA4, RGB5_A1, RGB, RGB4,
RGB5, R3_G3_B2, LUM8_ALPHA8, LUM4_ALPHA4, LU-
MINANCE, and ALPHA.

F.15 utils.picking Package

The com.sun.j3d.utils.picking package includes classes that construct a pick
shape from a 2D mouse location, initiate a picking operation, and retrieve informa-
tion about the picked object(s).
Table F-17 lists the classes in the com.sun.j3d.utils.picking package.

Version 1.2, March 2000 571

F.16 utils.picking.behaviors Package THE UTILITY PACKAGES

Table F-17 utils.picking Package

Class Description

PickCanvas Extends: PickTool

Simplifies picking using mouse events from a canvas. This
class allows picking using canvas x,y locations by generating
the appropriate pick shape.

PickIntersection Extends: Object

Holds information about an intersection of a PickShape with a
Node as part of a PickResult. Information about the intersected
geometry, intersected primitive, intersection point, and closest
vertex can be inquired.

PickResult Extends: Object

Stores information about a pick hit. Detailed information
about the pick and each intersection of the PickShape with the
picked Node can be inquired.

PickTool Extends: Object

The base class for picking operations. The picking methods
will return a PickResult object for each object picked, which
can then be queried to obtain more detailed information about
the specific objects that were picked.

F.16 utils.picking.behaviors Package

The com.sun.j3d.utils.picking.behaviors package combines picking with
mouse-based rotation, translation, and zoom behaviors. Once an object is picked,
that object can be manipulated with the mouse.

F.16.1 Interfaces
Table F-18 lists the interface in the com.sun.j3d.utils.picking.behaviors
package.
Table F-18 utils.picking.behaviors Package Interfaces
Interface Description

PickingCallback Allows a class to be notified when a picked object is moved.

The class that is interested in object movement implements
this interface, and the object created with that class is regis-
tered with the desired subclass of PickMouseBehavior using
the setupCallback method. When the picked object moves,
the registered object’s transformChanged method is in-
voked.

572 The Java 3D API Specification

THE UTILITY PACKAGES utils.universe Package F.17

F.16.2 Classes
Table F-19 lists the classes in the com.sun.j3d.utils.picking.behaviors pack-
age.
Table F-19 utils.picking.behaviors Package Classes
Class Description

PickMouseBehavior Extends: Behavior

Base class that allows users to add picking and mouse manip-
ulation to the scene graph.

PickRotateBehavior Extends: PickMouseBehavior

A mouse behavior that allows users to pick and drag scene
graph objects.

PickTranslateBehavior Extends: PickMouseBehavior

A mouse behavior that allows users to pick and translate scene
graph objects.

PickZoomBehavior Extends: PickMouseBehavior

A mouse behavior that allows users to pick and zoom scene
graph objects.

F.17 utils.universe Package

The com.sun.j3d.universe package is useful for setting up a user environment
to quickly and easily get a Java 3D program up and running. Specifically, this class
creates a Locale, a single ViewingPlatform (with its associated ViewPlatform), and
a Viewer object (with its associated View, PhysicalBody, PhysicalEnvironment,
and AudioDevice). For many applications, the SimpleUniverse class will provide
all of the necessary functionality.
Table F-20 lists the classes in the com.sun.j3d.utils.universe package.
Table F-20 utils.universe Package
Class Description

MultiTransformGroup Extends: Object

A convenience class that effectively creates a series of Trans-
formGroup nodes connected one to another hierarchically.

PlatformGeometry Extends: BranchGroup

Holds any geometry that should be associated with the View-
ingPlatform object.

Version 1.2, March 2000 573

F.17 utils.universe Package THE UTILITY PACKAGES

Table F-20 utils.universe Package (Continued)

Class Description

SimpleUniverse Extends: VirtualUniverse

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 on the “view” side of the scene graph.
Specifically, this class creates a locale, a single ViewingPlat-
form, and a Viewer object (both with their default values).
Many basic Java 3D applications will find that SimpleUni-
verse provides all necessary functionality needed by their ap-
plications.

Viewer Extends: Object

Holds all the information that describes the physical and virtu-
al “presence” in the Java 3D universe.

ViewerAvatar Extends: BranchGroup

Holds geometry that should be associated with the View’s av-
atar.

ViewingPlatform Extends: BranchGroup

Used to set up the “view” side of a Java 3D scene graph. The
ViewingPlatform object contains a MultiTransformGroup
node to allow for a series of transforms to be linked together.
To this structure the ViewPlatform is added as well as any ge-
ometry to associate with this view platform.

574 The Java 3D API Specification

 A PPE N D I X G
CD-ROM Installation

T HIS appendix describes how to install the software on the CD-ROM that came
with this book. For descriptions of the program examples on the CD-ROM, see
Appendix H, “The Example Programs.”

G.1 What’s on the CD-ROM

The Java 3D CD-ROM contains the following:
• The Java 2 SDK, Standard Edition, v 1.2.2 for Solaris/SPARC systems
(Solaris 2.6 or subsequent compatible version)
• The Java 2 SDK, Standard Edition, v 1.2.2 for Windows (Windows 95,
Windows 98, Windows NT, and Windows2000)
• The Java 3D API Version 1.2, including the com.sun.j3d.* packages, for
Solaris/SPARC systems
• The Java 3D API Version 1.2, including the com.sun.j3d.* packages, for
Windows systems (OpenGL version)
• Sun OpenGL 1.2.1 for Solaris
• Example programs
• The javadocs and The Java 3D 1.2 API Specification (this book) in a
browsable format (both html and Adobe Acrobat)
The Java 3D CD-ROM does not contain OpenGL for Windows, which is required
to run Java 3D applications. See Section G.2.1, “Requirements for Windows Sys-
tems.”
The CD-ROM contains an index.html file with the latest information that may not
have made it into this book. This file also has more detailed installation instruc-
tions, if you find the need.

Version 1.2, March 2000 575

G.2 Installing the Software on Windows 95/98/NT Systems CD-ROM INSTALLATION

The index.html file can be read with any browser. If any information in this
appendix contradicts the index.html file, assume that the index.html file is cor-
rect.
The CD-ROM also contains the following directories:
doc/ Contains the javadocs, and a browsable copy of this book
programs/ Contains example programs and demos
solaris/ Contains shell scripts for installing the Java 2 SDK, Java 3D,
OpenGL, and any necessary patches on Solaris systems
win32/ Contains executable files for installing the Java 2 SDK and
Java 3D on Windows systems

G.2 Installing the Software on Windows 95/98/NT Systems

G.2.1 Requirements for Windows Systems

The system on which the contents of the CD-ROM are installed should have
• At least 65 megabytes of free disk space for the Java 2 SDK
• At least 10 megabytes of free disk space for the Java 3D API
This version of Java 3D for Windows 95/98/NT requires OpenGL from Microsoft
or a hardware accelerator that supports OpenGL 1.1 (or later). If you do not have
OpenGL installed on your system, contact your hardware vendor or download
OpenGL from:
http://www.opengl.org/

G.2.2 Installing the Java 2 SDK on Windows Systems

The installation program creates a directory C:\jdk1.2.2 where it puts both the
Java 2 SDK and the Java 3D API. It also creates a directory C:\Program
Files\Javasoft\1.2 where it puts the Java 2 JRE and Java 3D runtime.

To install the Java 2 SDK and Java 3D on a Windows system, follow these steps:
1. If your system does not already have OpenGL installed, install it before
installing the CD-ROM (see Section G.2.1, “Requirements for Windows
Systems”).
2. Insert the CD-ROM in your CD-ROM drive.

576 The Java 3D API Specification

CD-ROM INSTALLATION Installing the Java 3D API on Windows Systems G.2.3

3. Install the Java 2 SDK and JRE.

Open the win32 folder on the CD-ROM and execute the jdk1_2_2-001-
win.exe file. Follow the instructions the installer program provides.
4. Add the full path of the jdk1.2.2\bin directory to the PATH variable.
Typically, the full path looks something like this:
C:\jdk1.2.2\bin

5. Check the CLASSPATH variable.

Include “.” in your CLASSPATH or ensure that CLASSPATH is not set.
6. Verify that Java is installed by typing the following:
> java -version
java version “1.2.2”
Classic VM (build JDK-1.2.2-001, native threads, symcjit)

If you do not get the java version “1.2.2” message, verify that the
jdk1.2.2/bin directory is in your path in Step 4 above. If you get the
above message, proceed to Section G.2.3, “Installing the Java 3D API on
Windows Systems.”

G.2.3 Installing the Java 3D API on Windows Systems

To install the Java 3D API, follow these steps:
1. Install the Java 3D SDK.
Execute the java3d1_2-win-opengl_sdk.exe file.
2. Install the Java 3D runtime.
Execute the java3d1_2-win-opengl-rt.exe file.
3. Verify that Java 3D is installed by typing the following:
> cd c:\jdk1.2.2\demo\java3d\HelloUniverse
> java HelloUniverse

You should see a window with a multi-colored rotating cube.

4. See the README.Java3D-jdk file in the jdk.1.2.2 directory for more in-
formation about this release.

Version 1.2, March 2000 577

G.2.4 Installing the Javadocs on Windows Systems CD-ROM INSTALLATION

G.2.4 Installing the Javadocs on Windows Systems

The javadocs for Java 3D may be installed on your system for ready access. Alter-
natively, you may choose to save the disk space by not installing the javadocs and
read them directly off of the CD-ROM whenever needed (see Section G.4,
“Accessing the Documentation from the CD-ROM”).
You will need at least 10 megabytes of free disk space to install the Java 3D API
javadocs.
The javadocs are stored on the CD-ROM in a compressed (zip) format. To install
the javadocs on your system:
1. Create a directory on your system where you want to store the javadocs
(for example, C:\java3d\doc).
2. Open the win32 folder on the CD-ROM and select the java3d1_2-
doc.zip file.
3. Use a zip utility to unzip the javadoc.zip file into the directory you just
created.
To read the javadocs, point your browser to the index.html file in the newly-cre-
ated html directory.

G.3 Installing the Software on Solaris Systems

G.3.1 Requirements for Solaris Systems

The system on which the contents of the CD-ROM are installed should have
• At least 38 megabytes of free disk space for the Java 2 SDK
• At least 7 megabytes of free disk space for the Java 3D API
• At least 32 megabytes of free disk space for Sun OpenGL 1.2.1 for Solaris.
• Sun OpenGL for Solaris/SPARC, version 1.2 (or later). Sun OpenGL 1.2.1
for Solaris is provided on the CD-ROM.
• A frame buffer with OpenGL support, such as Elite3D, Creator3D, or
Expert3D.
• The Solaris 2.6 (or later) operating environment with the necessary patches
installed (see Section G.3.3, “Installing Patches on Solaris”).

578 The Java 3D API Specification

CD-ROM INSTALLATION Installing Patches on Solaris Systems G.3.3

G.3.2 Installing Sun OpenGL 1.2.1 for Solaris

If you do not already have at least Sun OpenGL 1.2 for Solaris on your system,
install Sun OpenGL 1.2.1 from the CD-ROM as follows:
1. Insert the CD-ROM in your CD-ROM drive.
2. su to root.
3. Run the installation program:
% /cdrom/solaris/opengl/ogl121.sh

4. Exit and restart your window system.

5. Run the ogl_install_check program to verify the installation:
% /usr/openwin/demo/GL/ogl_install_check

G.3.3 Installing Patches on Solaris Systems

Several patches are required to run Java and Java 3D on Solaris. These patches are
included on the CD-ROM in the /cdrom/solaris/patches directory. A README
file in this directory contains the complete list of patches for Solaris 2.6, Solaris 7,
and Solaris 8.
To install the patches for your system, proceed as follows:
1. Insert the CD-ROM in your CD-ROM drive.
2. su to root.
3. Run the following script:
% /cdrom/solaris/patches/install_patches.csh

This script determines the version of Solaris that is running and installs all
necessary patches for that version.
4. Reboot your system.
To show the installed patches, type the following:

% showrev -p

If you want to install an individual patch, rather than the entire set of patches, pro-
ceed as follows:
1. Insert the CD-ROM in your CD-ROM drive.
Version 1.2, March 2000 579
G.3.4 Installing the Java 2 SDK on Solaris Systems CD-ROM INSTALLATION

2. su to root.
3. Run patchadd with the path to the patch you want to install.
For example:

% patchadd /cdrom/solaris/patches/5.7/105181-17

4. Reboot your system.

G.3.4 Installing the Java 2 SDK on Solaris Systems

Note: You must have permission to write files in the directories where you want to
install Java and Java 3D. If you do not have this permission, the installation pro-
gram will run to completion but Java and Java 3D will not be installed.

To install the Java 2 SDK on a Solaris system, follow these steps:

1. Change directories to where you wish to install the Java 2 SDK.
For example, to install on /home/myhome:

% cd /home/myhome

2. Run the installation program.

% /cdrom/solaris/Solaris_JDK_1.2.2_05_sparc.bin

This will create a Solaris_JDK_1.2.2_05 directory containing the Java 2

SDK.
3. Update the PATH variable in your startup file.
Put <sdkhome>/Solaris_JDK_1.2.2_05/bin in your path ahead of /usr/
bin (or any other directory that may contain java).

4. Check the CLASSPATH variable.

Include “.” in your CLASSPATH or ensure that CLASSPATH is not set.
5. Verify that Java is installed by typing the following:
% java -version
java version “1.2.2”
Solaris VM (build Solaris_JDK_1.2.2_05, native threads, sunwjit)

580 The Java 3D API Specification

CD-ROM INSTALLATION Installing the Javadocs on Solaris Systems G.3.6

If you do not get the java version “1.2.2” message, verify that you
have put the jdk1.2.2/bin directory in your path in Step 3 above. If you
do get the above message, proceed to Section G.3.5, “Installing the Java
3D API on Solaris Systems.”

G.3.5 Installing the Java 3D API on Solaris Systems

To install the Java 3D API, follow these steps:
1. Change to the jdk1.2.2 directory. For example:
% cd /home/myhome/jdk1_2_2

2. Install the Java 3D API. Type the following:

% /cdrom/solaris/java3d1_2-solsparc.bin

3. Verify that Java 3D is installed by typing the following:

% cd demo/java3d/HelloUniverse
% java HelloUniverse

You should see a window with a multi-colored rotating cube.

4. See the README.Java3D-jdk file in the Solaris_JDK_1.2.2_05 directory
for more information about this release.

G.3.6 Installing the Javadocs on Solaris Systems

The javadocs for Java 3D may be installed on your system for ready access. Alter-
natively, you may choose to save the disk space by not installing the javadocs and
read them directly off of the CD-ROM whenever needed (see Section G.4,
“Accessing the Documentation from the CD-ROM”).
You will need at least 10 megabytes of free disk space to install the Java 3D API
javadocs.
The javadocs are stored on the CD-ROM in a compressed tar format. To install the
javadocs on your system:
1. Create a directory where you want to store the javadocs. For example:
% mkdir /home/myhome/java3d/doc

Version 1.2, March 2000 581

G.4 Accessing the Documentation from the CD-ROM CD-ROM INSTALLATION

2. Change to the directory you just created. For example:

% cd /home/myhome/java3d/doc

3. Untar the file into the newly created directory:

% zcat /cdrom/solaris/java3d1_2-doc.tar.Z | tar xvf -

To read the javadocs, point your browser to the index.html file in the newly-cre-
ated html directory.

G.4 Accessing the Documentation from the CD-ROM

The javadoc-generated API documentation and the text of this book are included
on the CD-ROM in a browsable (html) format. Additionally, the text of this book
is included in a PDF format.
A browsable version of the javadocs are available in the /doc/java3d1_2-doc
directory on the CD-ROM. Point your browser to the index.html file in this direc-
tory to view the Java 3D API documentation.
A browsable version of The Java 3D API Specification (this book) is available in
the /doc/j3dbook directory on the CD-ROM. Point your browser to the
index.html file in this directory to view the online version of this book. The text
of this book is also available in Adobe Acrobat (PDF) format in the /doc directory
as j3dbook.pdf. You can download a copy of the Adobe Acrobat Reader from:
http://www.adobe.com/products/acrobat/readstep.html

582 The Java 3D API Specification

 A PPE N D I X H
The Example Programs

T HIS appendix describes the example programs the on the CD-ROM. For infor-
mation on how to install the example programs, see Appendix G, “CD-ROM
Installation.”

H.1 Introduction
Before you can compile Java 3D applications or run the example programs, you
need to have installed or you need to install the following software on your system:
• Java 2 SDK version 1.2 or later (included on the CD-ROM)
• Java 3D API (included on the CD-ROM)
• OpenGL
The demo/java3d directory contains 37 subdirectories. All but two of these direc-
tories (geometry and images) contain at least one example program. Some direc-
tories contain several example programs.
Each example program consists of two files, a .java file and a .class file. For
example, the ConicWorld directory contains the .java and .class files for six
example programs: BoxExample, ConicWorld, FlipCylinder, SimpleCylinder,
TexturedCone, and TexturedSphere.

H.2 Running the Example Programs

All of the example programs can be run as standalone applications from a UNIX
shell or a DOS window. The syntax shown in this appendix is for UNIX. In DOS
windows, you will need to replace “/” with “\” and specify the correct drive letter
when referring to <jdkhome> (for example, “c:\jdk1.2.2”).

Version 1.2, March 2000 585

H.2.1 Running within a Browser THE EXAMPLE PROGRAMS

For example, to run the HelloUniverse program as described in Appendix G, “CD-

ROM Installation,” change your current directory (“cd”) to the <jdkhome>/demo/
java3d/HelloUniverse directory, where <jdkhome> is the directory in which the
Java 2 SDK is installed, and type the following:

% java HelloUniverse

Each of the other example programs can be run in a similar manner.

Some of the example programs require a larger heap size (memory pool) than the
default provided by Java. To increase the maximum heap size to 64 megabytes, run
java with the “–Xmx64m” option. For example:

% java -Xmx64m HelloUniverse

Several of the example programs can be run as applets, either within a browser
(using Java Plug-in) or by running the applet from within the Java utility program
called appletviewer.

H.2.1 Running within a Browser

Java 2 applets, including many Java 3D example programs, can be run within a
browser using Java Plug-in. Special HTML tags are required to cause Netscape or
Internet Explorer to use the correct version of the Java 2 platform via Java Plug-in.
All of the Java 3D example programs that can be run as applets include HTML files
that have been converted to use Java Plug-in. Refer to the following URL for infor-
mation on using Java Plug-in 1.2.2 HTML Converter to convert your own applets
to run in a browser:
http://java.sun.com/products/plugin/

On Windows, the Java Plug-in is automatically installed along with the Java 2 runt-
ime environment. Applets can be run in either Netscape Communicator or Internet
Explorer.
On Solaris, Java 3D applets can be run in Netscape Communicator 4.51 or later on
Solaris 2.6 or later. After installing Netscape Communicator, you need to install
Java Plug-in version 1.2 or later. Netscape Communicator and Java Plug-in may be
downloaded for free from:
http://www.sun.com/solaris/netscape/

Additional patches may be required (see the website for details).

586 The Java 3D API Specification

THE EXAMPLE PROGRAMS Program Descriptions H.3

In both cases (Windows and Solaris), Java 3D applets are run within the Java Plug-
in by opening the Java Plug-in version of the associated HTML file. These files are
of the form <demo-name>_plugin.html, where <demo-name> is the name of the
particular Java 3D applet. For example, to run the HelloUniverse example program
within a browser, open the HelloUniverse/HelloUniverse_plugin.html file in
your browser.
The following page contains links to all of the Java 3D demos that can be run as
applets:
<jdkhome>/demo/java3d/index.html

Just click on the link for a given demo to run that demo within your browser.
Some Java 3D applets require a larger heap size (memory pool) than the default
provided by Java Plug-in. To increase the heap size to 64 megabytes, run the Java
Plug-in Control Panel application (from the Start menu in the Programs section on
Windows) and set the “Java Run Time Parameters” to “–Xmx64m”.

H.2.2 Running within Appletviewer

To run Java 3D applets within appletviewer, open the original, unconverted ver-
sion of the associated HTML file (not the “_plugin” version). For example:

% appletviewer HelloUniverse.html

Some Java 3D applets require a larger heap size (memory pool) than the default
provided by Java. To increase the maximum heap size to 64 megabytes, run
appletviewer with the “–J–Xmx64m” option. For example:

% appletviewer -J-Xmx64m HelloUniverse.html

H.3 Program Descriptions

Several example programs are included in the demo/java3d directory. All of the
example programs are described here. Code fragments are listed for a few of the
example programs.

Version 1.2, March 2000 587

H.3.1 AWT_Interaction THE EXAMPLE PROGRAMS

H.3.1 AWT_Interaction
Directory: demo/java3d/AWT_Interaction
The AWT_Interaction program displays a cube in a window. A “Rotate” button at
the top of the window rotates the cube in steps each time the button is selected. This
program demonstrates modifying the scene graph directly from the AWT event
thread using the ActionListener interface. This example is derived from the Hel-
loUniverse example, but instead of being continuously modified by a RotationIn-
terpolator behavior, the object’s TransformGroup is set to a new value that is
computed each time the “Rotate” button is pressed.
The relevant source code fragments from AWT_Interaction.java are shown
below.

public class AWTInteraction extends Applet

implements ActionListener {
TransformGroup objTrans;
float angle = 0.0f;
Transform3D trans = new Transform3D();

Button rotateB = new Button("Rotate");

The above code creates instance variables for the current angle, the Transform-
Group that will be modified, and a button that will trigger the modification. The
AWTInteraction class implements ActionListener so that it can receive button
press events. The createSceneGraph method (not shown here) creates a root
BranchGroup, an object TransformGroup, and a color cube, much as in HelloUni-
verse.

public AWTInteraction() {
...
Panel p = new Panel();
p.add(rotateB);
add("North", p);

rotateB.addActionListener(this);
...
}

The constructor puts the Rotate button in a panel and adds the AWTInteraction
class as an action listener for the button.

588 The Java 3D API Specification

THE EXAMPLE PROGRAMS Appearance H.3.3

public void actionPerformed(ActionEvent e) {

if (e.getSource() == rotateB) {
angle += Math.toRadians(10);
trans.rotY(angle);
objTrans.setTransform(trans);
}
}

The actionPerformed method increments the angle, computes a new rotation

matrix, and updates the object’s TransformGroup. Since this is in an AWT event
listener method rather than in a behavior, the transform update is not synchronized
with the Java 3D renderer. In particular, if such an event listener method modifies
two objects in the Java 3D scene graph, there is no guarantee that the effects of
those two updates will be seen in the same frame. Also remember that it is never
safe for two threads to simultaneously modify the same Java 3D object. This means
that an object that is being updated by a behavior must not be modified by an AWT
event listener.

H.3.2 AlternateAppearance
Directory: demo/java3d/AlternateAppearance
The AlternateAppearanceBoundsTest and AlternateAppearanceScopeTest pro-
grams demonstrate the ability of the AlternateAppearance node to override the
appearance of Shape3D nodes. The programs display a 5 × 5 matrix of spheres and
a control panel. The control panel allows you to select different scopes, and appear-
ance colors. The AlternateAppearanceBoundsTest program allows you to choose
one of three different sizes of BoundingSpheres for the region of influence of the
AlternateAppearance node, select whether a bounds object or a bounding leaf is
used, and enable or disable the appearance override enable flag in each of the
objects. The AlternateAppearanceScopeTest program allows you to set the hierar-
chical scoping of the AlternateAppearance node and enable or disable the appear-
ance override enable flag in each object in a group of objects.

H.3.3 Appearance
Directory: demo/java3d/Appearance
The AppearanceTest program displays an image background and nine rotating tet-
rahedron primitives. The tetrahedra are constructed with different material proper-
ties. The relevant source code fragments from AppearanceTest.java are shown
below.
Version 1.2, March 2000 589
H.3.3 Appearance THE EXAMPLE PROGRAMS

int row, col;

Appearance[][] app = new Appearance[3][3];

for (row = 0; row < 3; row++)

for (col = 0; col < 3; col++)
app[row][col] = createAppearance(row * 3 + col);

for (int i = 0; i < 3; i++) {

double ypos = (double)(i - 1) * 0.6;
for (int j = 0; j < 3; j++) {
double xpos = (double)(j - 1) * 0.6;
objRoot.addChild(createObject(app[i][j],
0.12,xpos, ypos));
}
}

The above code, extracted from the createSceneGraph method, creates a 3 × 3

array of objects, each with its own Appearance, and adds them to the scene graph.
The createAppearance method takes in an object index from 0 to 8 and generates
a unique Appearance for each object (using a switch statement). The objects are, in
order from left to right and from bottom to top: an unlit solid, an unlit wire frame,
unlit points, a lit solid, a texture-mapped lit solid, a transparent lit solid, a lit solid
with no specularity, a lit solid with only a specular highlight (black ambient and
diffuse), and a lit solid with a different material color. The code fragments for the
texture mapped and transparent cases are shown below.

private Appearance createAppearance(int idx) {

Appearance app = new Appearance();

// Globally used colors

Color3f black = new Color3f(0.0f, 0.0f, 0.0f);
Color3f white = new Color3f(1.0f, 1.0f, 1.0f);

switch (idx) {
...
case 4:
// Set up the texture map
TextureLoader tex =
new TextureLoader("../images/apimage.jpg", this);
app.setTexture(tex.getTexture());

TextureAttributes texAttr = new TextureAttributes();

texAttr.setTextureMode(TextureAttributes.MODULATE);
app.setTextureAttributes(texAttr);

590 The Java 3D API Specification

THE EXAMPLE PROGRAMS Appearance H.3.3

app.setMaterial(new Material(white, black, white,

black, 1.0f));
break;

For Appearance number 4, the TextureLoader utility is used to load a JPEG image
from a file and create a Texture object. TextureAttributes are set up so that the list
color is blended with the texture map (MODULATE). Finally, a lighting Material
object is created with a default color of white.

case 5:
// Set up the transparency properties
TransparencyAttributes ta = new TransparencyAttributes();
ta.setTransparencyMode(ta.BLENDED);
ta.setTransparency(0.6f);
app.setTransparencyAttributes(ta);

// Set up the polygon attributes

PolygonAttributes pa = new PolygonAttributes();
pa.setCullFace(pa.CULL_NONE);
app.setPolygonAttributes(pa);

// Set up the material properties

Color3f objColor = new Color3f(0.7f, 0.8f, 1.0f);
app.setMaterial(new Material(objColor, black, objColor,
black, 1.0f));
break;

...

return app;
}

For Appearance number 5, TransparencyAttributes are set up to use blended trans-

parency with the object being 60% transparent. Back face culling is disabled in the
PolygonAttributes object so that the front and back faces of the transparent object
are visible. Finally, a lighting Material object is created with the specified object
color.
The createObject method (not shown) takes in an Appearance object, a scale
value, and x and y position values. From these parameters, it creates a rotating tet-
rahedron that is positioned and scaled appropriately. The geometry for the tetrahe-
dron is created by the Tetrahedron.java file.

Version 1.2, March 2000 591

H.3.4 AppearanceMixed THE EXAMPLE PROGRAMS

H.3.4 AppearanceMixed
Directory: demo/java3d/AppearanceMixed
The AppearanceMixed program displays the same image background and nine
rotating tetrahedra (with different material properties) as the AppearanceTest pro-
gram described above. It adds a pair of triangles that are drawn in immediate mode;
this immediate-mode rendering is mixed in with the retained-mode objects (the tet-
rahedra).
An application subclasses Canvas3D and overrides the renderField to render geom-
etry in mixed-immediate mode. The relevant source code fragments from the
MyCanvas3D class in AppearanceMixed.java are shown below.

static class MyCanvas3D extends Canvas3D {

private GraphicsContext3D gc;
...

private IndexedTriangleArray tri =

new IndexedTriangleArray(4,
IndexedTriangleArray.COORDINATES |
IndexedTriangleArray.NORMALS, 6);

private Point3f vert[];

private Vector3f normals[];

public void renderField(int fieldDesc) {

computeVert();
computeNormals();
gc.draw(tri);
}

private void computeVert() {

<modify vert[] array>
...
tri.setCoordinates(0, vert);
}

private void computeNormals() {

<compute new normals[] based on vert[] values>
...
tri.setNormals(0, normals);
}

592 The Java 3D API Specification

THE EXAMPLE PROGRAMS Background H.3.5

The renderField method is called by Java 3D during the rendering loop for each
frame. The AppearanceMixed example overrides this Canvas3D method to com-
pute a new set of vertices and normals for the pair of triangles and to draw the tri-
angles to the canvas. The computeVert and computeNormals update the vert and
normals array and then call the methods to copy these changes to the IndexedTri-
angleArray object.

public MyCanvas3D(GraphicsConfiguration gcfg) {

super(gcfg);
...

// Set up the graphics context

gc = getGraphicsContext3D();

// Create the appearance for the triangle fan

Appearance app = new Appearance();
...
gc.setAppearance(app);

// Set up the global lights

Color3f lColor1 = new Color3f(0.7f, 0.7f, 0.7f);
Vector3f lDir1= new Vector3f(-1.0f, -1.0f, -1.0f);
Color3f alColor = new Color3f(0.2f, 0.2f, 0.2f);
gc.addLight(new AmbientLight(alColor));
gc.addLight(new DirectionalLight(lColor1, lDir1));
}

The constructor for MyCanvas creates a Graphics3D object and initializes its
appearance and lights. Note that even though the scene graph also contains light
objects, they are not used for immediate mode rendering—lights must be created
and added to the graphics context in order for immediate mode geometry to be lit.

H.3.5 Background
Directory: demo/java3d/Background
The BackgroundGeometry program demonstrates the use of background geometry.
The inside of a Sphere is texture mapped and used as background geometry, which
is rendered by Java 3D as if it were infinitely far away. The background is position-
and scale-invariant—only rotations affect how the geometry is rendered. This
demo demonstrates this with a group of boxes drawn in the virtual world. The
viewing platform can be adjusted with the mouse buttons. Notice how translations
do not affect the background, but rotations do.

Version 1.2, March 2000 593

H.3.6 Billboard THE EXAMPLE PROGRAMS

H.3.6 Billboard
Directory: demo/java3d/Billboard
The Bboard and BboardPt programs demonstrate the use of Java 3D’s Billboard
behavior to rotate a billboard around the Y axis and around a fixed point, respec-
tively. Use the left mouse button to rotate the scene, the middle button to zoom, and
the right button to translate.

Note: Billboard’s functionality has largely been superseded by OrientedShape3D.

H.3.7 ConicWorld
Directory: demo/java3d/ConicWorld
This directory contains a README file and six demonstration programs:
• The ConicWorld program shows spheres, cylinders, and cones of different
resolutions and colors.
• The SimpleCylinder program demonstrates a simple cylinder object. The
left mouse button rotates the cylinder.
• The BoxExample program demonstrates a rotating texture-mapped box.
The left mouse button rotates the box, the middle button zooms.
• The FlipCylinder program puts up a textured cylinder that can be rotated
and zoomed with the mouse. The left mouse button rotates, the middle but-
ton zooms, and the right button translates.
• The TexturedCone and TexturedSphere programs demonstrate the use of
texture mapping with the Cone and Sphere primitives, respectively.
These programs demonstrate the use of the geometry primitives in the
com.sun.j3d.utils.geometry package.

H.3.8 FourByFour
Directory: demo/java3d/FourByFour
The FourByFour program only runs as an applet, either from a browser (using
FourByFour_plugin.html) or from appletviewer (using FourByFour.html).
FourByFour is a three-dimensional game of tic-tac-toe on a 4 × 4 × 4 cube. Once
loaded, press the “Instructions” button for information on how to play the game.

594 The Java 3D API Specification

THE EXAMPLE PROGRAMS GeometryCompression H.3.11

H.3.9 GearTest
Directory: demo/java3d/GearTest
The GearTest program shows a single rotating gear. The GearBox program shows
a rotating gear assembly with five gears and gear shafts. The entire gear assembly
can be manipulated with the mouse. The geometry in this example program is
mathematically computed, and demonstrates the use of different Java 3D geometry
types. The Gear, SpurGear, and Shaft classes contain most of the geometry creation
methods.

H.3.10 GeometryByReference
Directory: demo/java3d/GeometryByReference
The GeometryByReferenceTest program draws a pair of triangles using the new
geometry-by-reference API in the GeometryArray object. The geometry or color
data is modified when the corresponding item is selected from the “Update Data”
combo box.
The ImageComponentByReferenceTest program draws a small raster object in the
upper left corner and a larger texture mapped square, using the same image as a tex-
ture, in the middle of the window. This program demonstrates the new by-reference
API for passing image data to Java 3D. It also demonstrates the new Y-up versus
Y-down attribute for images. Use the combo boxes at the bottom of the screen to
select the desired mode for the raster image and the texture image.
The InterleavedTest program draws a pair of triangles using the new interleaved
geometry-by-reference API in the GeometryArray object.

H.3.11 GeometryCompression
Directory: demo/java3d/GeometryCompression
The cgview program loads an object from a compressed geometry resource (.cg)
file and displays it on the screen. The object can be manipulated with the mouse.
Run the program with the following command:
java cgview <.cg file> [object-number]

You can use one of the .cg resource files in the demo/java3d/geometry directory.
The following example will display a galleon (ship):

% java cgview ../geometry/galleon.cg

Version 1.2, March 2000 595

H.3.12 HelloUniverse THE EXAMPLE PROGRAMS

The obj2cg program reads one or more Wavefront .obj file, compresses them, and
appends the corresponding compressed objects to the specified compressed geom-
etry resource (.cg) file. Run the program with the following command:
java obj2cg <.obj file> [<.obj file> ...] <.cg file>

If the .cg file does not exist, it is created. If the file does exist and is a valid .cg
resource file, the new object(s) are appended to the objects in the existing file. If it
is not a valid .cg file, an exception is thrown.
The ObjectFileCompressor class provides the methods, used by obj2cg, to com-
press Wavefront .obj files into Java 3D CompressedGeometry nodes. The Object-
FileCompressor.html file is the javadoc that describes the methods.

H.3.12 HelloUniverse
Directory: demo/java3d/HelloUniverse
The HelloUniverse program creates a cube and a RotationInterpolator behavior
object that rotates the cube at a constant rate of π/2 radians per second. The code
for this program is described in Section 1.6.3, “HelloUniverse: A Sample Java 3D
Program.”

H.3.13 LOD
Directory: demo/java3d/LOD
The LOD program demonstrates the use of the DistanceLOD behavior to automat-
ically select from among four different resolutions of a shaded, lit sphere. The mid-
dle mouse button moves the object closer and farther away from the viewer. As the
object gets farther away from the viewer, successively lower-resolution versions of
the sphere are displayed.

H.3.14 Lightwave
Directory: demo/java3d/Lightwave directory
The Viewer program is a loader and viewer for Lightwave 3D scene files. This pro-
gram implements only a subset of the features in Lightwave 3D. The README.txt
file contains release notes for the loader. The Viewer program takes the name of a
Lightwave 3D scene (.lws) file as its only argument. For example:

% java Viewer ballcone.lws

will display a red cone moving behind a stationary green ball.

596 The Java 3D API Specification

THE EXAMPLE PROGRAMS ObjLoad H.3.17

H.3.15 ModelClip
Directory: demo/java3d/ModelClip
The ModelClipTest and ModelClipTest2 programs show model clipping. The
ModelClipTest program draws an object that is clipped by a model clipping plane.
The mouse can be used to manipulate the object. Note that the clipping plane
moves with the object. The ModelClipTest2 program has a fixed object with a mov-
able model clipping plane. The mouse can be used to manipulate the model clip-
ping plane.

H.3.16 Morphing
Directory: demo/java3d/Morphing
The Morphing program displays a hand at the bottom of the window that morphs
between the static views of the three hands at the top of the window. The
Pyramid2Cube program is a simpler example that morphs between three cubes.

H.3.17 ObjLoad
Directory: demo/java3d/ObjLoad
The ObjLoad program loads Wavefront object files. Run the program with the fol-
lowing command:
java ObjLoad [-s] [-n] [-t] [-c degrees] <.obj file>
where the options are as follows:
-s Spin (no user interaction)
-n No triangulation
-t No stripification
-c Set crease angle for normal generation (default is 60 without
smoothing group info, otherwise 180 within smoothing groups)

You can use one of the .obj files in the demo/java3d/geometry directory. The fol-
lowing example will display a galleon (ship):

% java ObjLoad ../geometry/galleon.obj

The relevant source code fragment from ObjLoad.java is shown below.

Version 1.2, March 2000 597

H.3.18 OffScreenCanvas3D THE EXAMPLE PROGRAMS

public BranchGroup createSceneGraph() {

...
int flags = ObjectFile.RESIZE;
...
ObjectFile f = new ObjectFile(flags,
(float)(creaseAngle * Math.PI / 180.0));
Scene s = null;
try {
s = f.load(filename);
}
catch (FileNotFoundException e) {
System.err.println(e);
System.exit(1);
}
catch (ParsingErrorException e) {
System.err.println(e);
System.exit(1);
}
catch (IncorrectFormatException e) {
System.err.println(e);
System.exit(1);
}

objTrans.addChild(s.getSceneGroup());

The above code fragment creates an ObjectFile loader with the desired flags and
crease angle, loads the specified filename (checking for file and parsing excep-
tions), and adds the loaded objects to the scene graph. This code fragment could
easily be modified to accommodate a variety of loaders.

H.3.18 OffScreenCanvas3D
Directory: demo/java3d/OffScreenCanvas3D
The OffScreenTest program creates a scene graph containing a cube and renders
that cube to an on-screen Canvas3D. In the postSwap routine of the on-screen
Canvas3D, an off-screen rendering of the same scene is done to the off-screen
buffer. The resulting image is then used as the source image for a Raster object in
the scene graph.
The PrintFromButton program is similar to the OffScreenTest program, except that
it doesn’t automatically render to the off-screen buffer during the postSwap call-
back of its on-screen Canvas3D. The off-screen rendering is done when the “Print”
button is pressed.

598 The Java 3D API Specification

THE EXAMPLE PROGRAMS PickTest H.3.21

H.3.19 OrientedShape3D
Directory: demo/java3d/OrientedShape3D
The OrientedTest and OrientedPtTest programs demonstrate the use of Java 3D’s
OrientedShape3D nodes to create geometry that is oriented about the Y axis and
around a fixed point, respectively. These are essentially the same example pro-
grams as used in the Billboard example, except that they use an OrientedShape3D
node rather than a Billboard behavior. Use the left mouse button to rotate the scene,
the middle button to zoom, and the right button to translate. Notice how the text
does not jump around like it does when using a Billboard behavior.

H.3.20 PackageInfo
Directory: demo/java3d/PackageInfo
The PackageInfo program lists the package information for the Java 3D packages
installed on the system. This can be used to determine which version of Java 3D
you are running.
The QueryProperties program lists the values of the properties returned by the que-
ryProperties method of the Canvas3D that is created from the preferred Graph-
icsConfiguration returned by SimpleUniverse.

H.3.21 PickTest
Directory: demo/java3d/PickTest
The PickTest program displays several 3D objects and a control panel. The control
panel allows the user to change the pick mode, pick tolerance, and the view mode.
You can pick and rotate objects with the mouse. The PickTest program demon-
strates the use of the PickMouseBehavior utility classes.
The IntersectTest program demonstrates the ability to get geometric intersection
information from a picked object. Use the mouse to pick a point on one of the
objects in the window. The program illuminates the picked location and the vertices
of the primitive with tiny spheres. Information about the picked primitive and the
point of intersection is printed. The IntersectTest program uses a mouse-based
behavior, IntersectInfoBehavior, to control the picking. The relevant source code
fragments from IntersectInfoBehavior.java are shown below.

PickCanvas pickCanvas;
PickResult[] pickResult;

Version 1.2, March 2000 599

H.3.22 PickText3D THE EXAMPLE PROGRAMS

public IntersectInfoBehavior(Canvas3D canvas3D,

BranchGroup branchGroup,
float size) {

pickCanvas = new PickCanvas(canvas3D, branchGroup);

pickCanvas.setTolerance(5.0f);
pickCanvas.setMode(PickCanvas.GEOMETRY_INTERSECT_INFO);
...

The IntersectInfoBehavior class constructor creates a new PickCanvas object, ini-

tializes the PickCanvas with the desired tolerance, and sets the mode to allow
geometry intersection information to be retrieved.

public void processStimulus(Enumeration criteria) {

...
<check for mouse event>

if (eventId == MouseEvent.MOUSE_PRESSED) {
int x = ((MouseEvent)event[i]).getX();
int y = ((MouseEvent)event[i]).getY();
pickCanvas.setShapeLocation(x, y);
Point3d eyePos = pickCanvas.getStartPosition();
pickResult = pickCanvas.pickAllSorted();
if (pickResult != null) {
// Get node info
Node curNode = pickResult[0].getObject();
Geometry curGeom = ((Shape3D)curNode).getGeometry();
GeometryArray curGeomArray = (GeometryArray) curGeom;
// Get closest intersection results
PickIntersection pi =
pickResult[0].getClosestIntersection(eyePos);

<get specific info from PickIntersection>

}
}
...

The processStimulus method checks for a mouse event and initiates a pick, via the
PickCanvas object, at the selected location. It then looks for pick results and
extracts the intersection information from the pick result (if any).

H.3.22 PickText3D
Directory: demo/java3d/PickText3D

600 The Java 3D API Specification

THE EXAMPLE PROGRAMS PureImmediate H.3.24

The PickText3DBounds and PickText3DGeometry programs demonstrate bounds-

based and geometry-based picking of Text3D objects, respectively. Both programs
allow you to pick and rotate the text strings with the mouse. PickText3DBounds
uses only bounds-based picking, so the string can be picked anywhere within the
vicinity of its letters. PickText3DGeometry uses geometry-based picking, so the
string can only be picked exactly on one of the letters in the string.

H.3.23 PlatformGeometry
Directory: demo/java3d/PlatformGeometry
The SimpleGeometry program displays two geometry objects: a sphere and a rotat-
ing cube. The sphere is created as PlatformGeometry using the universe utilities.
This means that it is always in a fixed location relative to the viewer.

H.3.24 PureImmediate
Directory: demo/java3d/PureImmediate
The PureImmediate program demonstrates Java 3D’s pure immediate mode. In this
mode, objects are not placed into a scene graph, but are instead drawn using the
GraphicsContext3D drawing methods. The Java 3D renderer for the Canvas into
which the immediate mode graphics are rendered must be stopped prior to imme-
diate mode rendering. In this mode, the rendering is done from a user-controlled
thread.
The relevant source code fragments from PureImmediate.java are shown below.

public class PureImmediate extends Applet implements Runnable {

private Canvas3D canvas;
private GraphicsContext3D gc = null;
private Geometry cube = null;
private Transform3D cmt = new Transform3D();

// One rotation (2*PI radians) every 6 seconds

private Alpha rotAlpha = new Alpha(-1, 6000);

The above code creates instance variables for a Canvas3D, the GraphicsContext
associated with the canvas, a geometry object for drawing, a Transform3D object
for rotation, and an alpha object to allow the rotation to be time-based. The Pure-
Immediate class implements Runnable so that it can be run by a user-created draw-
ing thread.

Version 1.2, March 2000 601

H.3.24 PureImmediate THE EXAMPLE PROGRAMS

public void render() {

if (gc == null) {
// Set up Graphics context
gc = canvas.getGraphicsContext3D();
gc.setAppearance(new Appearance());

// Set up geometry
cube = new ColorCube(0.4).getGeometry();
}

// Compute angle of rotation based on alpha value

double angle = rotAlpha.value() * 2.0*Math.PI;
cmt.rotY(angle);

// Render the geometry for this frame

gc.clear();
gc.setModelTransform(cmt);
gc.draw(cube);
canvas.swap();
}

public void run() {

while (true) {
render();
Thread.yield();
}
}

The render method renders a single frame. After ensuring that the graphics context
is set up and the geometry is created, it computes the new rotation matrix, clears
the canvas, draws the cube, and swaps the draw and display buffer. The run method
is the entry point for our drawing thread. It calls the render method in a loop, yield-
ing control to other threads once per frame.

public PureImmediate() {
<construct canvas3d, set layout of applet, create canvas>

canvas.stopRenderer();
add("Center", canvas);

// Create the universe and viewing branch

SimpleUniverse u = new SimpleUniverse(canvas);
u.getViewingPlatform().setNominalViewingTransform();

602 The Java 3D API Specification

THE EXAMPLE PROGRAMS SplineAnim H.3.28

// Start a new thread that will continuously render

new Thread(this).start();
}

The constructor creates the 3D canvas, stops the Java 3D renderer, sets up the view-
ing branch (necessary even in pure immediate mode) and starts up the drawing
thread.

H.3.25 ReadRaster
Directory: demo/java3d/ReadRaster
The ReadRaster program creates a scene graph containing a cube and renders that
cube. In the postSwap routine of the Canvas3D, the contents of the canvas are read
back using the Immediate mode readRaster method. The resulting image is then
used as the source image for a Raster object in the scene graph.

H.3.26 Sound
Directory: demo/java3d/Sound
SimpleSounds shows a rotating cube and plays three different sounds, including a
voice saying “Hello Universe.”
ReverberateSound demonstrates different amounts of reverberation. It plays a
voice saying “Hello Universe” in several different environments, including a
closet, acoustic lab, garage, dungeon (both medium and large), and a cavern.

H.3.27 SphereMotion
Directory: demo/java3d/SphereMotion
The SphereMotion program shows a lit sphere that is continuously moving closer
and farther from the viewer. The sphere is lit by two light sources, one fixed and
one rotating around the sphere. Depending on a command line option, the two light
sources are created as directional lights (the default), point lights or spot lights. Run
the program with the following command:
java SphereMotion [-dir | -point | -spot]

H.3.28 SplineAnim
Directory: demo/java3d/SplineAnim

Version 1.2, March 2000 603

H.3.29 Text2D THE EXAMPLE PROGRAMS

The SplineAnim program demonstrates the use of KBRotPosScaleSplinePathIn-

terpolator (see the description in Table F-10) to do spline animation paths using
Kochanek-Bartels splines. A red cone is animated along a spline path specified by
five knot points, which are shown as cyan spheres.
The mouse buttons operate as follows:
• The left mouse button changes the scene orientation.
• The middle mouse button zooms in and out.
• The right mouse button pans the scene.
A control panel allows you to toggle between spline and linear interpolation, a
slider to adjust the speed of the animation, and an animation start/stop button.

H.3.29 Text2D
Directory: demo/java3d/Text2D
The Text2DTest program shows three different types of 2D text using the Text2D
utility class.

H.3.30 Text3D
Directory: demo/java3d/Text3D
The Text3DLoad program permits you to enter your own text and see how it dis-
plays in 3D. The command for running Text3DLoad is as follows:
java Text3DLoad [-f fontname] [-t tesselation] <text>

The fontname variable allows you to specify one of the Java Font names, such as
Helvetica, TimesRoman, and Courier. The tesselation variable specifies how
finely to tessellate the font glyphs. Once the text displays, the left mouse button
rotates the text, the middle button zooms, and the right button translates.

H.3.31 TextureByReference
Directory: demo/java3d/TextureByReference
The TextureByReference program shows a set of animating textures using the
image component by-reference feature. A control panel allows you to flip the
image or to set the texture and geometry by-reference flag, the image orientation
flag (y-up or y-down), and the image type. It also allows you to control the texture
animation speed and to stop and restart the animation.

604 The Java 3D API Specification

THE EXAMPLE PROGRAMS VirtualInputDevice H.3.35

H.3.32 TextureTest
Directory: demo/java3d/TextureTest
The TextureImage program displays a rotating cube with a user-specified image
file mapped onto the surface. The command for running TextureImage is as fol-
lows:
java TextureImage <image-filename> [-f ImageComponent format]

The ImageComponent format variable allows you to specify the format of the pixel
data. If you do not specify an image file, the rotating cube will appear white. You
can use one of the image files in the demo/java3d/images directory. For example:

% java TextureImage ../images/earth.jpg

will display the rotating cube with an image of earth mapped onto it.

H.3.33 TickTockCollision
Directory: demo/java3d/TickTockCollision
The TickTockCollision program shows an oscillating colored cube that collides
with two rectangular objects. The rectangular objects change color when they col-
lide with the cube.

H.3.34 TickTockPicking
Directory: demo/java3d/TickTockPicking
The TickTockPicking program displays a set of nine spinning tetrahedra and an
oscillating colored cube. Picking the cube or one of the tetrahedra with the left
mouse button causes it to change color.

H.3.35 VirtualInputDevice
Directory: demo/java3d/VirtualInputDevice
This directory contains another version of the HelloUniverse program with view-
ing position controls implemented via the InputDevice interface.

Version 1.2, March 2000 605

 Glossary

avatar
The software representation of a person as the person appears to others in a
shared virtual universe. The avatar may or may not resemble an actual person.

branch graph
A graph rooted to a BranchGroup node. See also scene graph and shared graph.

CC
Clipping coordinates.

center ear
Midpoint between left and right ears of listener.

center eye
Midpoint between left and right eyes of viewer. This is the head coordinate sys-
tem origin.

compiled
A subgraph may be compiled by an application using the compile method of the
root node—a BranchGroup or a SharedGroup—of the graph. A compiled object
is any object that is part of a compiled graph. An application can compile some
or all of the subgraphs that make up a complete scene graph. Java 3D compiles
these graphs into an internal format. Additionally, Java 3D provides restricted
access to methods of compiled objects or graphs. See also live.

compiled-retained mode
One of three modes in which Java 3D objects are rendered. In this mode, Java 3D
renders the scene graph, or a portion of the scene graph, that has been previously
compiled into an internal format. See also retained mode, immediate mode.

Version 1.2, March 2000 607

 GLOSSARY

content branch
A branch graph that contains content-related leaf nodes, such as Shape3D nodes.
No viewing-specific nodes are contained in a content branch.

DAG
Directed acyclic graph. A scene graph.

EC
Eye coordinates.

frustum
See view frustum.

group node
A node within a scene graph that composes, transforms, selects, and in general
modifies its descendant nodes. See also leaf node, root node.

HMD
Head-mounted display.

image plate
The display area; the viewing screen or head-mounted display.

immediate mode
One of three modes in which Java 3D objects are rendered. In this mode objects
are rendered directly, under user control, rather than as part of a scene graph tra-
versal. See also retained mode, compiled-retained mode.

IID
Interaural intensity difference. The difference between the perceived amplitude
(gain) of the signal from a source as it reaches the listener’s left and right ears.

ITD
Interaural time difference. The difference in time in the arrival of the signal from
a sound source as it reaches the listener’s left and right ears.

leaf node
A node within a scene graph that contains the visual, auditory, and behavioral
components of the scene. See also group node, root node.

608 The Java 3D API Specification

live
A live graph is any graph that is attached to a Locale object, or a shared graph
that is referenced by a live graph. A live object is any object that is part of a live
graph. Live objects are subject to being traversed and rendered by the Java 3D
renderer. Additionally, Java 3D provides restricted access to methods of live
objects or graphs. See also compiled.

LOD
Level of detail. A predefined Behavior that operates on a Switch node to select
from among multiple versions of an object or collection of objects.

polytope
A bounding volume defined by a closed intersection of half-spaces.

retained mode
One of three modes in which Java 3D objects are rendered. In this mode, Java 3D
traverses the scene graph and renders the objects that are in the graph. See also
compiled-retained mode, immediate mode.

root node
A node within a scene graph that establishes the default environment. See also
group node, leaf node.

scene graph
A collection of branch graphs rooted to a Locale. A virtual universe has one or
more scene graphs. See also branch graph and shared graph.

shared graph
A graph rooted to a SharedGroup node. See also branch graph and scene graph.

stride
The part of an interleaved array that defines the length of a vertex.

three space
Three-dimensional space.

view branch
A branch graph that contains a ViewPlatform leaf node and may contain other
content-related leaf nodes for geometry associated with a viewer.

Version 1.2, March 2000 609

 GLOSSARY

view frustum
A truncated, pyramid-shaped viewing area that defines how much of the world
the viewer sees. Objects not within the view frustum are not visible. Objects that
intersect the boundaries of the viewing frustum are clipped (partially drawn).

VPC
View platform coordinates.

610 The Java 3D API Specification

 Index

2D texture coordinates, 147, 194 Tuple3d, 379

3D text, 226, 227, 229 Tuple3f, 384
3D texture coordinates, 147, 194 Tuple3i, 391
Tuple4d, 397
Tuple4f, 405
Tuple4i, 413
A addBranchGraph method, 38
absolute method addCanvas3D method, 248
Tuple2d, 366 addChild method, 43
Tuple2f, 371 addGeometry method, 54
Tuple3d, 380 addInputDevice method, 528
Tuple3f, 386 addLight method, 357
Tuple3i, 393 addScope method
Tuple4d, 398 AlternateAppearance, 104
Tuple4f, 406 Fog, 68
Tuple4i, 414 Light, 73
acceleration of alpha, 289 ModelClip, 66
accessing an object, 318 addSound method, 359
accessing data by reference, 191 addSwitch method, 310
ActionListener, 588 AFFINE flag, 178
activation radius, 98 ALIGN_CENTER flag, 230
activation volume, 98 ALIGN_FIRST flag, 230
add method ALIGN_LAST flag, 230
GMatrix, 454 allElements method, 274
GVector, 420 ALLOW_ALIGNMENT_READ
HiResCoord, 39 flag, 229
Matrix3d, 433 ALLOW_ALIGNMENT_WRITE
Matrix3f, 427, 430 flag, 229
Matrix4d, 449 ALLOW_ALPHA_TEST_FUNCTION_
Matrix4f, 440, 442 READ flag, 131
Transform3D, 183 ALLOW_ALPHA_TEST_FUNCTION_
Tuple2d, 365 WRITE flag, 131
Tuple2f, 370

Version 1.2, March 2000 611

 INDEX

ALLOW_ALPHA_TEST_VALUE_ ALLOW_ATTENUATION_WRITE
READ flag, 131 flag, 75
ALLOW_ALPHA_TEST_VALUE_ ALLOW_ATTRIBUTE_GAIN_READ
WRITE flag, 131 flag, 154
ALLOW_ANGULAR_ ALLOW_ATTRIBUTE_GAIN_WRITE
ATTENUATION_READ flag, 89 flag, 154
ALLOW_ANGULAR_ ALLOW_ATTRIBUTES_READ
ATTENUATION_WRITE flag, 89 flag, 96
ALLOW_ANTIALIASING_READ flag ALLOW_ATTRIBUTES_WRITE
LineAttributes, 125 flag, 96
PointAttributes, 128 ALLOW_AUTO_COMPUTE_
ALLOW_ANTIALIASING_WRITE flag BOUNDS_READ flag, 23
LineAttributes, 125 ALLOW_AUTO_COMPUTE_
BOUNDS_WRITE flag, 23
PointAttributes, 128
ALLOW_AXIS_READ flag, 56
ALLOW_APPEARANCE_OVERRIDE_
READ flag ALLOW_AXIS_WRITE flag, 56
Morph, 100 ALLOW_BACK_DISTANCE_READ
flag, 61
Shape3D, 53
ALLOW_BACK_DISTANCE_WRITE
ALLOW_APPEARANCE_OVERRIDE_ flag, 61
WRITE flag
ALLOW_BLEND_COLOR_READ
Morph, 100 flag, 134
Shape3D, 53 ALLOW_BLEND_COLOR_WRITE
ALLOW_APPEARANCE_READ flag flag, 134
AlternateAppearance, 102 ALLOW_BLEND_FUNCTION_READ
Morph, 99 flag, 136
Shape3D, 53 ALLOW_BLEND_FUNCTION_WRITE
ALLOW_APPEARANCE_WRITE flag flag, 136
AlternateAppearance, 102 ALLOW_BOUNDARY_COLOR_READ
Morph, 99 flag, 141
Shape3D, 53 ALLOW_BOUNDARY_MODE_READ
flag, 141
ALLOW_APPLICATION_BOUNDS_
READ flag ALLOW_BOUNDING_BOX_READ
flag, 229
Background, 59
ALLOW_BOUNDS_READ flag, 23
Clip, 61
ALLOW_BOUNDS_WRITE flag, 23
Soundscape, 96
ALLOW_CACHE_READ flag, 151
ALLOW_APPLICATION_BOUNDS_
WRITE flag ALLOW_CACHE_WRITE flag, 151
Background, 59 ALLOW_CHANNELS_USED_READ
flag, 78
Clip, 61
ALLOW_CHARACTER_SPACING_
Soundscape, 96
READ flag, 229
ALLOW_ATTENUATION_READ
ALLOW_CHARACTER_SPACING_
flag, 75
WRITE flag, 229

612 The Java 3D API Specification

INDEX

ALLOW_CHILDREN_EXTEND ALLOW_COMPONENT_READ
flag, 42 flag, 138
ALLOW_CHILDREN_READ flag, 42 ALLOW_COMPONENT_WRITE
ALLOW_CHILDREN_WRITE flag, 42 flag, 138
ALLOW_COLLIDABLE_READ ALLOW_CONCENTRATION_READ
flag, 24 flag, 76
ALLOW_COLLIDABLE_WRITE ALLOW_CONCENTRATION_WRITE
flag, 24 flag, 76
ALLOW_COLLISION_BOUNDS_ ALLOW_CONT_PLAY_READ flag, 78
READ flag ALLOW_CONT_PLAY_WRITE
Group, 42 flag, 78
Morph, 99 ALLOW_COORDINATE_INDEX_
Shape3D, 53 READ flag, 211
ALLOW_COLLISION_BOUNDS_ ALLOW_COORDINATE_INDEX_
WRITE flag WRITE flag, 211
Group, 42 ALLOW_COORDINATE_READ
flag, 192
Morph, 99
ALLOW_COORDINATE_WRITE
Shape3D, 53 flag, 192
ALLOW_COLOR_INDEX_READ ALLOW_COUNT_READ flag
flag, 211
CompressedGeometry, 220
ALLOW_COLOR_INDEX_WRITE
flag, 211 GeometryArray, 193
ALLOW_COLOR_READ flag ALLOW_COUNT_WRITE flag, 193
Background, 59 ALLOW_CULL_FACE_READ
flag, 129
ColoringAttributes, 124
ALLOW_CULL_FACE_WRITE
Fog, 67 flag, 129
GeometryArray, 192 ALLOW_DATA_READ flag, 166
Light, 71 ALLOW_DENSITY_READ flag, 69
ALLOW_COLOR_TABLE_READ ALLOW_DENSITY_WRITE flag, 69
flag, 134
ALLOW_DEPTH_COMPONENT_
ALLOW_COLOR_TABLE_WRITE READ flag, 224
flag, 134
ALLOW_DEPTH_COMPONENT_
ALLOW_COLOR_WRITE flag WRITE flag, 224
Background, 59 ALLOW_DEPTH_ENABLE_READ
ColoringAttributes, 124 flag, 131
Fog, 67 ALLOW_DETACH flag, 44
GeometryArray, 192 ALLOW_DIRECTION_READ flag
Light, 71 ConeSound, 89
ALLOW_COLORING_ATTRIBUTES_ DirectionalLight, 74
READ flag, 120 SpotLight, 76
ALLOW_COLORING_ATTRIBUTES_ ALLOW_DIRECTION_WRITE flag
WRITE flag, 120
ConeSound, 89
DirectionalLight, 74
Version 1.2, March 2000 613
 INDEX

ALLOW_DIRECTION_WRITE flag Shape3D, 53

(Continued) ALLOW_GEOMETRY_WRITE flag
SpotLight, 76 Background, 59
ALLOW_DISTANCE_FILTER_READ Shape3D, 53
flag, 155 ALLOW_HEADER_READ flag, 220
ALLOW_DISTANCE_FILTER_WRITE ALLOW_IGNORE_VERTEX_
flag, 155 COLORS_READ flag, 131
ALLOW_DISTANCE_GAIN_READ ALLOW_IGNORE_VERTEX_
flag, 85 COLORS_WRITE flag, 131
ALLOW_DISTANCE_GAIN_WRITE ALLOW_IMAGE_READ flag
flag, 85
Background, 59
ALLOW_DISTANCE_READ flag, 70
ImageComponent, 160
ALLOW_DISTANCE_WRITE flag, 70
Raster, 224
ALLOW_DURATION_READ flag, 78
Texture, 141
ALLOW_ENABLE_READ flag
ALLOW_IMAGE_WRITE flag
ModelClip, 63
Background, 59
Sound, 78
Raster, 224
TexCoordGeneration, 146
Texture, 141
Texture, 141
ALLOW_INFLUENCING_BOUNDS_
ALLOW_ENABLE_WRITE flag READ flag
ModelClip, 63 AlternateAppearance, 102
Sound, 78 Fog, 67
TexCoordGeneration, 146 Light, 71
Texture, 141 ModelClip, 63
ALLOW_FILTER_READ flag, 141 ALLOW_INFLUENCING_BOUNDS_
ALLOW_FONT3D_READ flag, 229 WRITE flag
ALLOW_FONT3D_WRITE flag, 229 AlternateAppearance, 102
ALLOW_FORMAT_READ flag Fog, 67
GeometryArray, 193 Light, 71
ImageComponent, 160 ModelClip, 63
TexCoordGeneration, 146 ALLOW_INITIAL_GAIN_READ
Texture, 141 flag, 78
ALLOW_FREQUENCY_SCALE_ ALLOW_INITIAL_GAIN_WRITE
FACTOR_READ flag, 155 flag, 78
ALLOW_FREQUENCY_SCALE_ ALLOW_INTERSECT flag, 191
FACTOR_WRITE flag, 155 ALLOW_IS_PLAYING_READ flag, 78
ALLOW_GEOMETRY_ARRAY_READ ALLOW_IS_READY_READ flag, 78
flag, 99 ALLOW_LINE_ATTRIBUTES_READ
ALLOW_GEOMETRY_ARRAY_ flag, 121
WRITE flag, 99 ALLOW_LINE_ATTRIBUTES_WRITE
ALLOW_GEOMETRY_READ flag flag, 121
Background, 59 ALLOW_LOCAL_TO_VWORLD_
CompressedGeometry, 220 READ flag, 24

614 The Java 3D API Specification

INDEX

ALLOW_LOOP_READ flag, 78 TexCoordGeneration, 146

ALLOW_LOOP_WRITE flag, 78 ALLOW_PLANE_WRITE flag, 63
ALLOW_MATERIAL_READ flag, 120 ALLOW_POINT_ATTRIBUTES_READ
ALLOW_MATERIAL_WRITE flag, 121
flag, 120 ALLOW_POINT_ATTRIBUTES_
ALLOW_MIPMAP_MODE_READ WRITE flag, 121
flag, 141 ALLOW_POINT_READ flag, 56
ALLOW_MODE_READ flag ALLOW_POINT_WRITE flag, 56
OrientedShape3D, 56 ALLOW_POLICY_READ flag, 98
PolygonAttributes, 129 ALLOW_POLICY_WRITE flag, 98
TexCoordGeneration, 146 ALLOW_POLYGON_ATTRIBUTES_
TextureAttributes, 134 READ flag, 121
TransparencyAttributes, 136 ALLOW_POLYGON_ATTRIBUTES_
ALLOW_MODE_WRITE flag WRITE flag, 121
OrientedShape3D, 56 ALLOW_POSITION_READ flag
PolygonAttributes, 129 PointLight, 75
TextureAttributes, 134 PointSound, 85
TransparencyAttributes, 136 Raster, 224
ALLOW_NORMAL_FLIP_READ Text3D, 229
flag, 129 ALLOW_POSITION_WRITE flag
ALLOW_NORMAL_FLIP_WRITE PointLight, 75
flag, 129 PointSound, 85
ALLOW_NORMAL_INDEX_READ Raster, 224
flag, 211 Text3D, 229
ALLOW_NORMAL_INDEX_WRITE ALLOW_PRIORITY_READ flag, 78
flag, 211 ALLOW_PRIORITY_WRITE flag, 78
ALLOW_NORMAL_READ flag, 192 ALLOW_RASTER_OP_READ
ALLOW_NORMAL_WRITE flag, 192 flag, 131
ALLOW_OFFSET_READ flag ALLOW_RASTER_OP_WRITE
PolygonAttributes, 129 flag, 131
Raster, 224 ALLOW_REF_DATA_READ flag
ALLOW_OFFSET_WRITE flag CompressedGeometry, 220
PolygonAttributes, 129 GeometryArray, 193
Raster, 224 ALLOW_REF_DATA_WRITE flag, 193
ALLOW_PATH_READ flag, 229 ALLOW_REFLECTION_
ALLOW_PATH_WRITE flag, 229 COEFFICIENT_READ flag, 155
ALLOW_PATTERN_READ flag, 125 ALLOW_REFLECTION_
ALLOW_PATTERN_WRITE flag, 125 COEFFICIENT_WRITE flag, 155
ALLOW_PICKABLE_READ flag, 24 ALLOW_REGION_READ flag, 58
ALLOW_PICKABLE_WRITE flag, 24 ALLOW_REGION_WRITE flag, 58
ALLOW_PLANE_READ flag ALLOW_RELEASE_READ flag, 78
ModelClip, 63 ALLOW_RELEASE_WRITE flag, 78

Version 1.2, March 2000 615

 INDEX

ALLOW_RENDERING_ ALLOW_SIZE_WRITE flag

ATTRIBUTES_READ flag, 121 PointAttributes, 127
ALLOW_RENDERING_ Raster, 224
ATTRIBUTES_WRITE flag, 121 ALLOW_SOUND_DATA_READ
ALLOW_REVERB_DELAY_READ flag, 78
flag, 155 ALLOW_SOUND_DATA_WRITE
ALLOW_REVERB_DELAY_WRITE flag, 78
flag, 155 ALLOW_SPREAD_ANGLE_READ
ALLOW_REVERB_ORDER_READ flag, 76
flag, 155 ALLOW_SPREAD_ANGLE_WRITE
ALLOW_REVERB_ORDER_WRITE flag, 76
flag, 155 ALLOW_STATE_READ flag
ALLOW_ROLLOFF_READ flag, 154 Light, 71
ALLOW_ROLLOFF_WRITE flag, 155 MultiTextureState, 149
ALLOW_SCHEDULING_BOUNDS_ ALLOW_STATE_WRITE flag
READ flag, 78
Light, 71
ALLOW_SCHEDULING_BOUNDS_
MultiTextureState, 149
WRITE flag, 78
ALLOW_STRING_READ flag, 229
ALLOW_SCOPE_READ flag
ALLOW_STRING_WRITE flag, 229
AlternateAppearance, 102
ALLOW_SWITCH_READ flag, 48
Fog, 67
ALLOW_SWITCH_WRITE flag, 48
Light, 71
ALLOW_TEXCOORD_INDEX_READ
ModelClip, 63
flag, 211
ALLOW_SCOPE_WRITE flag
ALLOW_TEXCOORD_INDEX_WRITE
AlternateAppearance, 102 flag, 211
Fog, 67 ALLOW_TEXCOORD_READ flag, 192
Light, 71 ALLOW_TEXCOORD_WRITE
ModelClip, 63 flag, 192
ALLOW_SHADE_MODEL_READ ALLOW_TEXGEN_READ flag, 120
flag, 124 ALLOW_TEXGEN_WRITE flag, 120
ALLOW_SHADE_MODEL_WRITE ALLOW_TEXTURE_ATTRIBUTES_
flag, 124 READ flag, 120
ALLOW_SHARED_GROUP_READ ALLOW_TEXTURE_ATTRIBUTES_
flag, 107 WRITE flag, 120
ALLOW_SHARED_GROUP_WRITE ALLOW_TEXTURE_READ flag, 120
flag, 107
ALLOW_TEXTURE_UNIT_STATE_
ALLOW_SIZE_READ flag READ flag, 121
DepthComponent, 166 ALLOW_TEXTURE_UNIT_STATE_
ImageComponent, 160 WRITE flag, 121
PointAttributes, 127 ALLOW_TEXTURE_WRITE flag, 120
Raster, 224 ALLOW_TRANSFORM_READ flag
Texture, 141 TextureAttributes, 134
TransformGroup, 46

616 The Java 3D API Specification

INDEX

ALLOW_TRANSFORM_WRITE flag angle flag

TextureAttributes, 134 AxisAngle4d, 416
TransformGroup, 46 AxisAngle4f, 418
ALLOW_TRANSPARENCY_ angle method
ATTRIBUTES_READ flag, 120 Gvector, 423
ALLOW_TRANSPARENCY_ Vector2d, 369
ATTRIBUTES_WRITE flag, 120 Vector2f, 374
ALLOW_TYPE_READ flag, 224 Vector3D, 383
ALLOW_URL_READ flag, 151 Vector3f, 389
ALLOW_URL_WRITE flag, 151 Vector4d, 402
ALLOW_VALUE_READ flag, 136 Vector4f, 410
ALLOW_VALUE_WRITE flag, 136 angular attenuation, 88, 95
ALLOW_VELOCITY_SCALE_ animating rigid objects, 267
FACTOR_READ flag, 155
animation, 267–314
ALLOW_VELOCITY_SCALE_
antialiasing, 126, 128, 255
FACTOR_WRITE flag, 155
support for, 261
ALLOW_VISIBLE_READ flag, 131
appearance component, overriding, 102
ALLOW_VISIBLE_WRITE flag, 131
Appearance object, 8, 119, 356
ALLOW_WEIGHTS_READ flag, 99
AppearanceMixed program, 589, 592
ALLOW_WEIGHTS_WRITE flag, 99
applet package, 566
ALLOW_WIDTH_READ flag, 125
applet run as an application, 566
ALLOW_WIDTH_WRITE flag, 125
applets, support for building, 5
alpha
appletviewer, 586, 587
acceleration of, 289
application region, 61, 62, 97
test, 132
application scene graph, 6
ALPHA flag, 142
ArrayIndexOutOfBoundsException, 537
Alpha object, 119, 289
atmospheric conditions, 156
ALPHA_IN_BUFFER flag, 222
atmospheric rolloff, 152
alphaAtOneDuration parameter, 291
attachViewPlatform method, 248
alphaAtZeroDuration parameter, 291
attenuation, pointlight, 76
AlternateAppearance leaf node, 102
audio device driver, 335
AlternateAppearanceBoundsTest
program, 589 data, 338
AlternateAppearanceScopeTest initialization, 336
program, 589 audio devices, 335–344
ALWAYS flag, 132 audio output device, 563
ambient light AudioDevice object, 335–344
color, 139 AudioDevice3D interface, 338
source, 73 audioengines package, 563
AmbientLight leaf node, 73 audioengines.javasound package, 563
amplitude scale factor, 77, 156 aural attributes, 97, 359
AuralAttributes node component
object, 152, 155, 359
Version 1.2, March 2000 617
 INDEX

avatar, 243, 574 bounding region, 59

AWTInteraction class, 588 BoundingBox node component
AWTInteraction program, 588 object, 170
AxisAngle4d class, 234, 415 BoundingLeaf node, 58
AxisAngle4f class, 234, 417 BoundingPolytope node component
object, 174
BoundingSphere node component
object, 172
B Bounds node component object, 168
back clip policy, 251, 252 Box class, 569
background color, 356 BoxExample program, 594
background geometry, 60, 593 BranchGroup node, 8, 44, 327
Background leaf node, 59, 356 browser support, 5
BACKGROUND_SOUND flag, 339 bufferDataPresent constant, 222
BackgroundGeometry program, 593 BUFFERED_AUDIO_DATA flag, 339
BackgroundSound leaf node, 83 bufferType constant, 222
BadTransformException, 537 bundle colors with vertices state bit, 464
BASE_LEVEL flag, 142 bundle normals with vertices state
BASE_LEVEL_LINEAR flag, 143, 557 bit, 464
BASE_LEVEL_POINT flag, 143, 557 BY_REFERENCE flag, 193, 194
Bboard program, 594
BboartPt program, 594
Behavior leaf node, 99, 267, 272 C
behaviors, 267–314 calibration parameters, 521, 522
behaviors.interpolators package, 566 camera-based view model, 530, 532
behaviors.keyboard package, 567 helping methods, 532
behaviors.mouse package, 568 canvas sizing and movement, 249
Billboard behavior node, 312 Canvas3D object, 28, 238, 239, 257, 522
Billboard programs, 594 CapabilityNotSetException, 538
BLEND flag, 135 CC (Clipping Coordinates), 535
blend function CD-ROM
destination, 138 contents, 575
source, 138 installation in Windows 95/98/NT
BLEND_ONE flag, 138 systems, 576
BLEND_ONE_MINUS_SRC_ALPHA installation on Solaris systems, 578
flag, 138 center eye, 525
BLEND_SRC_ALPHA flag, 138 cgview program, 595
BLEND_ZERO flag, 138 character string, 230
BLENDED flag, 137 CHILD_ALL flag, 49
blocking driver, 316 CHILD_MASK flag, 49
BLOCKING flag, 316 CHILD_NONE flag, 49
boundary mode, 142, 146

618 The Java 3D API Specification

INDEX

CLAMP flag BoundingSphere, 173

Texture, 142 Bounds, 168
Texture3D, 146 cloneNode method, 113
clamp method cloneNodeComponent method, 114
Tuple2d, 366 cloneTree method, 108
Tuple2f, 371 cloning subgraphs, 108–117
Tuple3d, 380 close method
Tuple3f, 386 AudioDevice, 336
Tuple3i, 392 InputDevice, 317
Tuple4d, 398, 399 closestIntersection method
Tuple4f, 406 BoundingBox, 171
Tuple4i, 414 BoundingPolytope, 177
clampMax method BoundingSphere, 173
Tuple2d, 366 Bounds, 169
Tuple2f, 371 code structure, 268
Tuple3d, 380 coexistence coordinates, 512
Tuple3f, 386 collision detection, 20
Tuple3i, 392 color
Tuple4d, 399 alpha present state bit, 466
Tuple4f, 406 component information, 124
Tuple4i, 414 diffuse, 139, 140
clampMin method emissive, 139
Tuple2d, 366 light, 139
Tuple2f, 371 material, 140
Tuple3d, 380 parameter, 198
Tuple3f, 386 specular, 139
Tuple3i, 392 specular highlight, 140
Tuple4d, 398, 399 sub-command, 483
Tuple4f, 406 COLOR_3 flag, 194
Tuple4i, 414 COLOR_4 flag, 194
clear method, 360 COLOR_IN_BUFFER flag, 222
clearCapability method, 22 Color3b class, 377
clearRect method, 361 Color3f class, 389
clearSound method, 340 Color4b class, 395
Clip leaf node, 61 Color4f class, 408
clip policies, 251 ColorCube class, 569
Clipping Coordinates (CC), 535 ColoringAttributes object, 123
clipping plane, 61, 62, 63, 251 ColorInterpolator object, 298
clone method colors parameter, 198
BoundingBox, 171 combine method
BoundingPolytope, 176 BoundingBox, 171

Version 1.2, March 2000 619

 INDEX

combine method (Continued) ViewPlatform, 511

BoundingPolytope, 176 virtual world, 511, 515
BoundingSphere, 173 COORDINATES flag, 194
Bounds, 169 copySubMatrix method, 455
compatibility mode, 531 create method, 361
compile method cross method
BranchGroup, 45 Vector3d, 383
SharedGroup, 107 Vector3f, 388
compiled-retained mode, 3, 346 cross-product normalization, 188, 429,
component objects, See node component 435
objects CULL_BACK flag, 130
CompressedGeometry node component CULL_FRONT flag, 130
object, 219, 222 CULL_NONE flag, 130
CompressedGeometryFile class, 569 currentChild method, 50
CompressedGeometryHeader node currentInterpolationValue flag, 302
component object, 222 currentKnotIndex flag, 302
compression CYCLOPEAN_EYE_VIEW flag, 518
geometry, 459–507, 568 Cylinder class, 570
image, 466 cylindrical ray pick shape, 332
compression package, 569 cylindrical segment pick shape, 333
CompressionStream class, 569
computePathInterpolation method, 303
concentration, spotlight, 77
Cone class, 570 D
cone pick shape, 331 dangling references, 112
CONE_SOUND flag, 339 DanglingReferenceException, 538
ConeSound leaf node, 88 dashed line, 125
CONGRUENT flag, 177 dashed-dotted line, 125
ConicWorld program, 594 DECAL flag, 134
conjugate method decal geometry, 47
Quat4d, 402 DecalGroup node, 47
Quat4f, 411 decompress method, 221
constant polygon offset, 130 decompression, geometry, 460
coordinate systems, 33, 511–514 DECREASING_ENABLE flag, 291
head, 512, 515, 525 decreasingAlphaDuration parameter, 291
head tracker, 513 decreasingAlphaRampDuration
high-resolution, 38 parameter, 291
image plate, 513 DEFAULT_SENSOR_READ_
left image plate, 513 COUNT, 319
physical, 512 defaultWakeupCriterion flag, 294
right image plate, 513 DEMAND_DRIVEN flag, 316
tracker base, 513

620 The Java 3D API Specification

INDEX

depth buffer distanceLinf method

enable flag, 132 Point2d, 368
freezing, 255 Point2f, 373
mode, 132 Point3d, 382
write enable flag, 132 Point3f, 387
DepthComponent object, 166 Point4d, 400
DepthComponentFloat object, 167 Point4f, 408
DepthComponentInt object, 167 DistanceLOD behavior node, 311
DepthComponentNative object, 168 distanceSquared method
destination blend function, 138 Point2d, 368
detach method, 45 Point2f, 373
determinant method Point3d, 382
Matrix3d, 434 Point3f, 387
Matrix3f, 428 Point4d, 400
Matrix4d, 452 Point4f, 408
Matrix4f, 443 Doppler
Transform3D, 187 effect equations, 552
difference method, 39 scale factor, 158
diffuse color, 139, 140 dot method
direction, spotlight, 77 GVector, 422
directional light, 73 Vector2d, 369
DirectionalLight leaf node, 73 Vector2f, 374
discrete cosine transform, 466 Vector3d, 383
distance attenuation, 88 Vector3f, 388
distance frequency filtering, 152 Vector4d, 401
distance method Vector4f, 410
HiResCoord, 40 dotted line, 125
Point2d, 368 double buffering
Point2f, 373 enable flag, 261
Point3d, 382 override, 358
Point3f, 387 support for, 261
Point4d, 400 draw method, 360
Point4f, 408 duplicateNode method, 113
distanceL1 method duplicateNodeComponent method, 114
Point2d, 368 DURATION_UNKNOWN flag, 78
Point2f, 373
Point3d, 382
Point3f, 387
Point4d, 400
E
Point4f, 408 EC (Eye Coordinates), 535
emissive color, 139

Version 1.2, March 2000 621

 INDEX

ENABLE_COLLISION_REPORTING Tuple3i, 392

flag, 24 Tuple4b, 395
ENABLE_PICK_REPORTING flag, 24 Tuple4d, 398
environment, sound, 95 Tuple4f, 406
epsilonEquals method Tuple4i, 415
AxisAngle4d, 417 equations, 543–560
AxisAngle4f, 419 Doppler effect, 552
GMatrix, 457 exponential fog, 543
GVector, 422 fog, 543
Matrix3d, 435 headphone playback, 546
Matrix3f, 429 lighting, 544
Matrix4d, 453 reverberation, 553
Matrix4f, 444 sound, 546
Transform3D, 188 speaker playback, 554
Tuple2d, 367 texture application, 558
Tuple2f, 372 texture lookup, 556
Tuple3d, 380 texture mapping, 556
Tuple3f, 385 error handling, 537
Tuple4d, 398 Euler angles, 181
Tuple4f, 406 example programs, 585–??
EQUAL flag, 132 running, 585
equals method exceptions, 537–542
AxisAngle4d, 417 execution and rendering model, 345–347
AxisAngle4f, 419 execution culling, 271
BoundingBox, 171 exponential fog equation, 543
BoundingPolytope, 177 ExponentialFog leaf node, 68
BoundingSphere, 174 extensibility, 3
Bounds, 169 extrusion path, 226, 227
GMatrix, 457 Eye Coordinates (EC), 535
GVector, 422 eye position manipulation, 522
HiResCoord, 40 EYE_LINEAR flag, 147
Matrix3d, 435 eyepoint policy, 516
Matrix3f, 429
Matrix4d, 453
Matrix4f, 444
SceneGraphPath, 327 F
Transform3D, 188 face culling flag, 129
Tuple2d, 367 FASTEST flag
Tuple2f, 372 ColoringAttributes, 124
Tuple3b, 376 Texture, 143
Tuple3d, 380 TextureAttributes, 136
Tuple3f, 385 TransparencyAttributes, 137

622 The Java 3D API Specification

INDEX

field of view, 252 generalized triangle strip, 461

FIELD_ALL flag, 352 genMode parameter, 148
FIELD_LEFT flag, 352 geometry
FIELD_RIGHT flag, 352 component information, 190
field-sequential stereo, 260 compression, 346, 459–507
file loader, 564 data, updating, 206
finished method, 294 decompression, 460
FlipCylinder program, 594 grouping, 346
flush method instructions, 474
GraphicsContext3D, 360 types
J3DGraphics2D, 361 GeometryArray, 191
Raster, 223
fog equations, 543
Geometry object, 8, 190, 360
Fog leaf node, 66, 356
geometry package, 569
Font3D object, 226
GeometryArray object, 191
FontExtrusion object, 227
GeometryByReferenceTest program, 595
forceDuplicate parameter, 109
GeometryCompressor class, 569
FORMAT_CHANNEL8 flag, 161
GeometryInfo class, 570
FORMAT_LUM4_ALPHA4 flag, 161
GeometryStripArray object, 208
FORMAT_LUM8_ALPHA8 flag, 161
GeometryUpdater interface, 206
FORMAT_R3_G3_B2 flag, 161
get method
FORMAT_RGB flag, 160
AxisAngle4d, 416
FORMAT_RGB4 flag, 161
AxisAngle4f, 418
FORMAT_RGB5 flag, 161
Color3b, 377
FORMAT_RGB5_A1 flag, 161
Color3f, 390
FORMAT_RGB8 flag, 160
Color4b, 395
FORMAT_RGBA flag, 160
Color4f, 409
FORMAT_RGBA4 flag, 161
GMatrix, 456
FORMAT_RGBA8 flag, 160
Matrix4d, 446
FourByFour program, 594
Matrix4f, 439
front clip policy, 251, 252
PickBounds, 328
frustum, 531
PickPoint, 329
frustum culling, 496
PickRay, 329
frustum method, 189, 533
PickSegment, 330
SensorRead, 323
Transform3D, 186
G Tuple2d, 365
gain scale factor, 86, 93, 152 Tuple2f, 370
game support, 5 Tuple3b, 376
GearBox program, 595 Tuple3d, 378
GearTest program, 595 Tuple3f, 384
generalized triangle mesh, 463 Tuple3i, 391

Version 1.2, March 2000 623

 INDEX

get method (Continued) Shape3D, 55

Tuple4b, 394 getAppearanceOverrideEnable method
Tuple4d, 397 Morph, 101
Tuple4f, 405 Shape3D, 55
Tuple4i, 413 getApplicationBoundingLeaf method
getActivationRadius method, 98 Background, 61
getAlignment method, 230 Clip, 62
getAlignmentAxis method Soundscape, 97
Billboard, 314 getApplicationBounds method
OrientedShape3D, 57 Background, 61
getAlignmentMode method Clip, 62
Billboard, 314 Soundscape, 97
OrientedShape3D, 57 getArmingBounds method
getAllBranchGraphs method, 38 WakeupOnCollisionEntry, 280
getAllCanvas3Ds method, 249 WakeupOnCollisionExit, 281
getAllChildren method, 43 WakeupOnCollisionMovement, 282
getAllGeometries method, 55 getArmingPath method
getAllInputDevices method, 528 WakeupOnCollisionEntry, 280
getAllLights method, 357 WakeupOnCollisionExit, 281
getAllLocales method, 36 WakeupOnCollisionMovement, 282
getAllScopes method getArrayLengths method, 303
AlternateAppearance, 104 getAttenuation method, 76
Fog, 68 getAttributeGain method, 156
Light, 73 getAudioDevice method, 528
ModelClip, 66 getAudioPlaybackType method, 337
getAllSounds method, 359 getAuralAttributes method
getAllSwitches method, 311 GraphicsContext3D, 359
getAlpha method, 295 Soundscape, 97
getAlphaAtOneDuration method, 293 getAutoNormalize method, 180
getAlphaAtZeroDuration method, 294 getAWTEvent method, 275
getAlphaTestFunction method, 132 getAxisOfRotation method
getAlphaTestValue flag, 132 RotationInterpolator, 297
getAlternateCollisionTarget method, 43 RotationPathInterpolator, 309
getAmbientColor method, 139 getAxisOfRotPos method, 306
getAngleOffsetToSpeaker method, 337 getAxisOfRotPosScale method, 308
getAngularAttenuation method, 94 getAxisOfScale method, 300
getAngularAttenuationLength getAxisOfTranslation method
method, 94 PositionInterpolator, 296
getAppearance method PositionPathInterpolator, 304
AlternateAppearance, 103 getBackClipDistance method, 252
GraphicsContext3D, 356 getBackClipPolicy method, 251
Morph, 101

624 The Java 3D API Specification

INDEX

getBackDistance method getCoexistenceCenteringEnable

Clip, 62 method, 519
LinearFog, 70 getCoexistenceCenterInPworldPolicy
getBackFaceNormalFlip method, 130 method, 529
getBackground method getCoexistenceToTrackerBase
method, 528
GraphicsContext3D, 356
getCollidable method, 26
J3DGraphics2D, 361
getCollisionBounds method
getBehavior method, 276
Group, 43
getBestConfiguration method, 264
Morph, 101
getBestType method, 180
Shape3D, 55
getBlueSize method, 264
getColor method
getBoundaryColor method, 144
Background, 60
getBoundaryModeR method, 146
ColoringAttributes, 124
getBoundaryModeS method, 142
Fog, 67
getBoundaryModeT method, 142
GeometryArray, 198
getBoundingBox method
Light, 72
Font3D, 227
getColorIndex method, 212
Text3D, 231
getColorIndices method, 213
getBounds method
getColoringAttributes method, 122
Node, 25
getColorRef3b method, 204
WakeupOnSensorEntry, 278
getColorRef3f method, 203
WakeupOnSensorExit, 279
getColorRef4b method, 204
WakeupOnViewPlatformEntry, 282
getColorRef4f method, 203
WakeupOnViewPlatformExit, 283
getColorRefByte method, 203
getBoundsAutoCompute method, 25
getColorRefFloat method, 203
getBufferOverride method, 358
getColors method, 198
getButtons method, 323
getColumn method
getByteCount method, 221
GMatrix, 456
getCacheEnable method, 152
Matrix3d, 433
getCanvas3D method
Matrix3f, 426
GraphicsContext3D, 355
Matrix4d, 447
View, 248
Matrix4f, 441
getCapability method, 22
getCompatabilityModeEnable
getCenter method, 173 method, 531
getCenterEarToSpeaker method, 337 getCompressedGeometry method, 221
getCenterEyeInImagePlate method, 523 getCompressedGeometryHeader
getChannelsAvailable method, 338 method, 221
getChannelsUsedForSound method, 338 getCompressedGeometryRef
getCharacterSpacing method, 232 method, 221
getChild method, 42 getConcentration method, 77
getChildMask method, 49 getContinuousEnable method, 81

Version 1.2, March 2000 625

 INDEX

getCoordinate method, 196 PointSound, 86

getCoordinateIndex method, 212 getDistanceGainLength method, 86
getCoordinateIndices method, 212 getDominantHandIndex method, 529
getCoordinates method, 197 getDoubleBuffer method, 263
getCoordRef3d method, 203 getDoubleBufferAvailable method, 261
getCoordRef3f method, 203 getDoubleBufferEnable method, 261
getCoordRefDouble method, 203 getDstBlendFunction method, 138
getCoordRefFloat method, 202 getDuplicateOnCloneTree method, 26,
getCullFace method, 129 110
getCurrentFrameStartTime method, 253 getDuration method, 83
getCurrentSensorRead method, 322 getElapsedFrameCount method, 277
getDecreasingAlphaDuration getElapsedFrameTime method, 278
method, 294 getElement method
getDecreasingAlphaRampDuration GMatrix, 456
method, 294 GVector, 421
getDensity method, 69 Matrix3d, 432
getDepth method Matrix3f, 426
ImageComponent3D, 165 Matrix4d, 446
Texture3D, 146 Matrix4f, 440
getDepthBufferEnable method, 132 getEmissiveColor method, 139
getDepthBufferFreezeTransparent getEnable method
method, 255 Behavior, 295
getDepthBufferWriteEnable flag, 132 Light, 72
getDepthComponent method, 226 ModelClip, 65
getDepthData method Sound, 82
DepthComponentFloat, 167 TexCoordGeneration, 148
DepthComponentInt, 167 Texture, 144
getDepthSize method, 264 getEnables method, 65
getDeterminantSign method, 181 getEnd method
getDevice method, 321 PickConeSegment, 332
getDiffuseColor method, 140 PickCylinderSegment, 333
getDirection method getEndColor method, 298
ConeSound, 94 getEndPosition method, 296
DirectionalLight, 74 getExtrusionShape method, 228
PickCone, 330 getFieldOfView method, 252
PickCylinder, 332 getFirstChildIndex method, 300
SpotLight, 77 getFog method, 356
getDistance method, 312 getFont method, 227
getDistanceFilter method, 157 getFont3D method, 230
getDistanceFilterLength method, 157 getFontExtrusion method, 227
getDistanceGain method getFormat method
ConeSound, 92 ImageComponent, 162

626 The Java 3D API Specification

INDEX

getFormat method (Continued) Texture, 143

TexCoordGeneration, 148 getImagePlateToVworld method, 524
Texture, 144 getImages method, 144
getFrameNumber method, 253 getIncreasingAlphaDuration method, 293
getFrameStartTimes method, 253 getIncreasingAlphaRampDuration
getFrequencyScaleFactor method, 158 method, 293
getFrontBufferRendering mode, 358 getIndexCount method, 213
getFrontClipDistance method, 252 getInfluencingBoundingLeaf method
getFrontClipPolicy method, 251 AlternateAppearance, 103
getFrontDistance method, 70 Fog, 68
getGenMode method, 148 Light, 72
getGeometry method ModelClip, 65
Background, 60 getInfluencingBounds method
Shape3D, 54 AlternateAppearance, 103
getGeometryArray method, 101 Fog, 68
getGraphics2D method, 352 Light, 72
getGraphicsContext3D method, 352 ModelClip, 64
getGreenSize method, 264 getInitialColorIndex method, 202
getHeadIndex method, 529 getInitialCoordIndex method, 202
getHeadToHeadTracker method, 526 getInitialGain method, 80
getHeadTrackerToLeftImagePlate getInitialNormalIndex method, 202
method, 522 getInitialTexCoordIndex method, 202
getHeadTrackerToRightImagePlate getInitialVertexIndex method, 196
method, 522 getInputStream method, 152
getHeight method getInterleavedVertices method, 205
DepthComponent, 166 getKnot method, 303
ImageComponent, 162 getKnots method, 303
Texture, 144 getLastChildIndex method, 300
getHiRes method getLastFrameDuration method, 253
GraphicsContext3D, 357 getLeftEarPosition method, 526
Locale, 37 getLeftEyeInImagePlate method, 523
getHiResCoord method, 39 getLeftEyePosition method, 526
getHiResCoordX method, 39 getLeftHandIndex method, 529
getHiResCoordY method, 39 getLeftManualEyeInCoexistence
getHiResCoordZ method, 39 method, 519
getHotspot method, 320 getLeftManualEyeInImagePlate
getIgnoreVertexColors method, 133 method, 523
getImage method getLeftProjection method, 535
Background, 60 getLight method, 357
ImageComponent2D, 164 getLightingEnable method, 140
ImageComponent3D, 166 getLineAntialiasingEnable method, 126
Raster, 226 getLineAttributes method, 122

Version 1.2, March 2000 627

 INDEX

getLinePattern method, 126 getNumberOfChannelsUsed method

getLineWidth method, 126 AudioDevice3D, 340
getLocale method, 326 Sound, 83
getLocalEyeLightingEnable method, 249 getNumButtons method, 323
getLocalToVworld method, 25 getNumCol method, 456
getLocationOnScreen method, 259 getNumPlanes method, 176
getLoop method, 80 getNumRow method, 456
getLoopCount method, 293 getNumStrips method
getLower method, 170 GeometryStripArray, 209
getMagFilter method, 143 IndexedGeometryStripArray, 217
getMaterial method, 121 getNumTextureColorTableComponents
getMaxFrameStartTimes method, 253 method, 135
getMaximumAngle method, 297 getObject method, 326
getMaximumScale method, 299 getOffScreenBuffer method, 259
getMaximumTransparency method, 301 getOffScreenLocation method, 260
getMinFilter method, 143 getOffset method, 225
getMinimumAngle method, 297 getOrigin method
getMinimumFrameCycleTime PickCone, 330
method, 254 PickCylinder, 332
getMinimumScale method, 299 getParent method, 25
getMinimumTransparency method, 301 getPath method, 231
getMipMapMode method, 144 getPatternMask method, 127
getMode method, 293 getPatternScaleFactor method, 127
getModelClip method, 358 getPerspectiveCorrectionMode
getModelTransform method, 357 method, 136
getMonoscopicViewPolicy method, 524 getPhaseDelayDuration method, 293
getMultiTextureCount method, 123 getPhysicalBody method, 248
getMultiTextureState method, 123 getPhysicalEnvironment method
getNewObjectReference method, 112, AudioDevice, 337
115 View, 248
getNode method, 326 getPhysicalHeight method, 524
getNominalEyeHeightFromGround getPhysicalScreenHeight method, 257
method, 526 getPhysicalScreenWidth method, 257
getNominalEyeOffsetFromNominalScree getPhysicalWidth method, 524
n method, 526 getPickable method, 26
getNonDominantHandIndex method, 529 getPixelLocationFromImagePlate
getNormal method, 199 method, 524
getNormalIndex method, 213 getPixelLocationInImagePlate
getNormalIndices method, 213 method, 523
getNormalRef3f method, 204 getPlane method, 65
getNormalRefFloat method, 204 getPlaneR method, 149
getNormals method, 200 getPlaneS method, 148

628 The Java 3D API Specification

INDEX

getPlanes method getRasterOp method, 133

BoundingPolytope, 175 getRasterOpEnable method, 133
ModelClip, 65 getRead method, 321
getPlaneT method, 149 getRedSize method, 264
getPointAntialiasingEnable method, 128 getReflectionCoefficient method, 156
getPointAttributes method, 122 getRegion method, 59
getPointSize method, 128 getReleaseEnable method, 80
getPolygonAttributes method, 122 getRenderedImage method
getPolygonMode method, 130 ImageComponent2D, 164
getPolygonOffset method, 130 ImageComponent3D, 166
getPolygonOffsetFactor method, 130 getRenderingAttributes method, 122
getPosition method getReverbBounds method, 157
DistanceLOD, 312 getReverbDelay method, 156
PointLight, 75 getReverbOrder method, 157
PointSound, 86 getRightEarPosition method, 526
PositionPathInterpolator, 304 getRightEyeInImagePlate method, 523
Raster, 225 getRightEyePosition method, 526
RotPosPathInterpolator, 306 getRightHandIndex method, 529
RotPosScalePathInterpolator, 308 getRightManualEyeInCoexistence
Text3D, 230 method, 519
getPositions method getRightManualEyeInImagePlate
PositionPathInterpolator, 304 method, 523
RotPosPathInterpolator, 306 getRightProjection method, 535
RotPosScalePathInterpolator, 308 getRolloff method, 156
getPostId method, 276 getRotationPoint method
getPredictionPolicy method, 321 Billboard, 314
getPredictor method, 321 OrientedShape3D, 57
getPriority method, 81 getRotationScale method
getProcessingMode method, 316 Matrix4d, 448
getProjectionPolicy method, 249 Matrix4f, 440
getQuat method Transform3D, 182
RotationPathInterpolator, 309 getRow method
RotPosPathInterpolator, 306 GMatrix, 456
RotPosScalePathInterpolator, 307 Matrix3d, 432
getQuats method Matrix3f, 426
RotationPathInterpolator, 310 Matrix4d, 447
RotPosPathInterpolator, 306 Matrix4f, 441
RotPosScalePathInterpolator, 308 getSampleDuration method, 340
getRadius method getScale method
BoundingSphere, 172 Matrix3d, 436
PickCylinder, 332 Matrix3f, 429
Matrix4d, 449

Version 1.2, March 2000 629

 INDEX

getScale method (Continued) getSpecularColor method, 140

Matrix4f, 440 getSpreadAngle method
RotPosScalePathInterpolator, 307 PickCone, 330
Transform3D, 182 SpotLight, 77
getScales method, 307 getSrcBlendFunction method, 138
getSceneAntialiasingAvailable getStartColor method, 298
method, 261, 523 getStartPosition method, 296
getSceneAntialiasingEnable method, 255 getStartTime method
getSchedulingBoundingLeaf method Alpha, 292
Behavior, 273 AudioDevice3D, 341
Sound, 81 getStereo method, 263
getSchedulingBounds method getStereoAvailable method, 260
Behavior, 273 getStereoEnable method, 261
Sound, 81 getStereoMode method, 358
getScope method getString method, 230
AlternateAppearance, 104 getStripIndexCounts method, 217
Fog, 68 getStripVertexCounts method, 209
Light, 73 getSwitch method, 310
ModelClip, 65 getTarget method
getScreen3D method, 261 Billboard, 314
getScreenScale method, 516 ColorInterpolator, 298
getScreenScalePolicy method, 516 PositionInterpolator, 296
getSensor method PositionPathInterpolator, 304
InputDevice, 317 RotationInterpolator, 297
PhysicalEnvironment, 529 RotationPathInterpolator, 309
getSensorButtonCount method, 320 RotPosPathInterpolator, 306
getSensorCount method RotPosScalePathInterpolator, 308
InputDevice, 317 ScaleInterpolator, 300
PhysicalEnvironment, 528 SwitchValueInterpolator, 301
getSensorHotSpotInVworld method, 519 TransparencyInterpolator, 302
getSensorReadCount method, 320 getTessellationTolerance method
getSensorToVworld method, 519 Font3D, 227
getShadeModel method, 124 FontExtrusion, 228
getSharedGroup method, 108 getTexCoordGeneration method
getShininess method, 140 Appearance, 123
getSize method MultiTextureState, 150
Canvas3D, 259 getTexCoordRef2f method, 205
GVector, 421 getTexCoordRef3f method, 205
Raster, 225 getTexCoordRefFloat method, 204
Screen3D, 256 getTexCoordSetCount method, 200
getSound method, 359 getTexCoordSetMap method, 200
getSoundData method, 79

630 The Java 3D API Specification

INDEX

getTexCoordSetMapLength method, 200 WakeupOnSensorExit, 279

getTexture method getTriggerTime method, 293
Appearance, 121 getType method
MultiTextureState, 150 Raster, 225
getTextureAttributes method Transform3D, 180
Appearance, 122 getUpper method, 170
MultiTextureState, 150 getURL method (deprecated), 152
getTextureBlendColor method, 135 getURLObject method, 152
getTextureColorTable method, 135 getURLString method, 152
getTextureColorTableSize method, 136 getUserData method, 23
getTextureCoordinate method, 200 getUserHeadToVworld method, 515
getTextureCoordinateIndex method, 213 getUserHeadToVworldEnable flag, 515
getTextureCoordinateIndices getValidVertexCount method, 196
method, 213 getVelocityScaleFactor method, 158
getTextureCoordinates method, 201 getVertexCount method, 195
getTextureMode method, 134 getVertexFormat method, 196
getTextureTransform method, 136 getView method
getTime method, 323 Behavior, 273
getTotalChannels method, 338 Canvas3D, 261
getTrackerBaseToImagePlate getViewAttachPolicy method, 99, 242
method, 522 getViewPlatform method, 248
getTrackingAvailable method, 528 getViewPolicy method, 515
getTrackingEnable method, 515 getVirtualUniverse method, 37
getTransform method getVisibilityPolicy method, 518
SceneGraphPath, 326 getVisible method, 133
TransformGroup, 47 getVpcToEc method, 535
getTransformGroup method, 283 getVworldToImagePlate method, 524
getTransparency method, 137 getWeights method, 101
getTransparencyAttributes method, 122 getWhichChild method, 49
getTransparencyMode method, 137 getWidth method
getTriggeringBehavior method, 276 DepthComponent, 166
getTriggeringBounds method ImageComponent, 162
WakeupOnCollisionEntry, 280 Texture, 144
WakeupOnCollisionExit, 281 getWindowEyepointPolicy method, 517
WakeupOnCollisionMovement, 282 getWindowMovementPolicy
getTriggeringPath method method, 250
WakeupOnCollisionEntry, 280 getWindowResizePolicy method, 250
WakeupOnCollisionExit, 281 glossary, 607–610
WakeupOnCollisionMovement, 282 GMatrix class, 234, 453
getTriggeringPostId method, 276 graphics context, 360
getTriggeringSensor method GraphicsConfigTemplate3D class, 263
WakeupOnSensorEntry, 278 GraphicsConfiguration, 263
Version 1.2, March 2000 631
 INDEX

GraphicsContext3D object, 352, 354 Tuple4f, 407

great circle interpolation, 404, 412 Tuple4i, 415
GREATER flag, 132 hasTriggered method, 274
GREATER_OR_EQUAL flag, 132 head
Group node object, 42 coordinate system, 512, 515, 525
group nodes, 19, 41–50 parameters, 264, 525
BranchGroup, 44 position, 510
DecalGroup, 47 tracker coordinate system, 513
OrderedGroup, 47 tracking, 526
SharedGroup, 50 HEAD_PREDICTOR flag, 319
Switch, 48 head-mounted coordinate system, 513
TransformGroup, 45 headphone playback equations, 546
GVector class, 234, 419 HEADPHONES flag, 336
HelloUniverse program, 9, 596, 605
hierarchical scope, 68, 73
high-resolution coordinates, 31, 33, 38,
H 357
HAND_PREDICTOR flag, 319 HiResCoord object, 27, 38
hardware platforms, 4 HMD_VIEW flag, 516
hashCode method Huffman
AxisAngle4d, 417 compression algorithm, 473
AxisAngle4f, 419 encoding, 460, 465, 473
BoundingBox, 172
BoundingPolytope, 177
BoundingSphere, 174
Bounds, 169 I
GMatrix, 457 IDENTITY flag, 177
GVector, 422 identityMinus method, 455
Matrix3d, 436 IllegalArgumentException, 537
Matrix3f, 430 IllegalRenderingStateException, 539
Matrix4d, 453 IllegalSharingException, 539
Matrix4f, 445 image compression, 466
SceneGraphPath, 327 image package, 571
Transform3D, 188 image plate coordinate system, 513
Tuple2d, 367 ImageComponent node component
Tuple2f, 372 object, 159
Tuple3b, 377 ImageComponent2D node component
object, 162
Tuple3d, 380
ImageComponent3D node component
Tuple3f, 386 object, 164
Tuple3i, 393 ImageComponentByReferenceTest
Tuple4b, 395 program, 595
Tuple4d, 399

632 The Java 3D API Specification

INDEX

immediate mode, 3, 345 insertSwitch method, 310

API for, 354 instantiating and registering a new device
rendering, 349–361 audio devices, 344
IncorrectFormatException, 565 input devices, 317
INCREASING_ENABLE flag, 291 INTENSITY flag, 142
increasingAlphaDuration parameter, 290 interaural
increasingAlphaRampDuration delay, 546
parameter, 290 intensity, 546
indexCount parameter, 216 intensity difference (IID), 548
IndexedGeometryArray object, 211 time difference (ITD), 546
IndexedGeometryStripArray object, 216 INTERLEAVED flag, 193, 194
IndexedLineArray object, 214 InterleavedTest program, 595
IndexedLineStripArray object, 217 interpolate method
IndexedPointArray object, 214 GVector, 423
IndexedQuadArray object, 215 Quat4d, 403
IndexedTriangleArray object, 215 Quat4f, 412
IndexedTriangleFanArray object, 218 Tuple2d, 367
IndexedTriangleStripArray object, 218 Tuple2f, 372
infinite eye lighting, 249 Tuple3d, 381
influencing region, 68, 72 Tuple3f, 386
Fog node, 68 Tuple4d, 398
Light node, 72 Tuple4f, 406
initialization method, 267 Interpolator object, 294
initialize method interpolators, utilities for, 566
AudioDevice, 336 interpupilary distance, 264, 525
Behavior, 272 intersect method
Billboard, 314 BoundingBox, 171
DistanceLOD, 312 BoundingPolytope, 176
InputDevice, 316 BoundingSphere, 173
Interpolator, 295 Bounds, 169
input devices, 315–333 Morph, 101
InputDevice object, 315 Shape3D, 55
insertCanvas3D method, 248 IntersectTest program, 599
insertChild method, 42 introduction to Java 3D, 1–??
insertGeometry method, 54 inverse method
insertLight method, 357 Quat4d, 403
insertScope method Quat4f, 411
AlternateAppearance, 104 invert method
Fog, 68 GMatrix, 455
Light, 73 Matrix3d, 434
ModelClip, 65 Matrix3f, 428
insertSound method, 359
Version 1.2, March 2000 633
 INDEX

invert method (Continued)

Matrix4d, 452
K
KBCubicSplineCurve class, 566
Matrix4f, 443
KBCubicSplineSegment class, 566
Transform3D, 187
KBKeyFrame class, 566
isBehaviorSchedulerRunning
method, 254 KBRotPosScaleSplinePathInterpolator
class, 567
isByReference method
KBSplinePathInterpolator class, 567
CompressedGeometry, 221
keyboard input processing, 267
ImageComponent, 162
keyboard, utilities for, 567
isCompiled method, 22
KeyNavigator class, 567
isEmpty method
KeyNavigatorBehavior class, 567
BoundingBox, 172
Kochanek-Bartels (TCB) spline
BoundingPolytope, 177
interpolation, 566
BoundingSphere, 174 Kochanek-Bartels (TCB) splines, 604
Bounds, 170
isGraphicsConfigSupported method, 264
isLive method, 22
isOffScreen method, 259 L
isPlaying method, 83 L – 1 distance
isPlayingSilently method, 83 Point2d, 368
isReady method, 82 Point2f, 373
isRendererRuning method, 354 Point3d, 382
isSamePath method, 327 Point3f, 387
isSoundPlaying method, 359 Point4d, 400
isViewRunning method, 254 Point4f, 408
isYUp method, 162 L – infinite distance
GMatrix, 457
Matrix4d, 453
Point2d, 368
J Point2f, 373
J3DGraphics2D object, 360 Point3d, 382
javadocs Point3f, 387
installation on Solaris systems, 582 Point4d, 400
installation on Windows Point4f, 408
systems, 578
lastButtons method, 321
JavaSoundMixer class, 563
lastRead method, 321
joystick input processing, 315
lastTime method, 321
JPEG image loader, 591
Leaf node, 51

634 The Java 3D API Specification

INDEX

leaf nodes, 19, 51–104 LESS_OR_EQUAL flag, 132

AlternateAppearance, 102 light
AmbientLight, 73 ambient source, 73
Background, 59 color, 139
BackgroundSound, 83 directional, 73
Behavior, 99, 267, 272 list of, 357
BoundingLeaf, 58 spot, 76
Clip, 61 Light leaf node, 71
ConeSound, 88 lighting equations, 544
DirectionalLight, 73 Lightwave 3D scene files, loader and
ExponentialFog, 68 viewer, 596
Fog, 66, 356 Lightwave 3D scene files, loader for, 565
Light, 71 line
LinearFog, 69 antialiasing flag, 126
Link, 102, 105, 107 pattern, 126
ModelClip, 63 mask, 127
scale factor, 127
Morph, 99 strip primitive, 208
OrientedShape3D, 55 LINE_BUFFER flag, 222
PointLight, 74 LinearFog leaf node, 69
PointSound, 84 LineArray object, 207
Shape3D, 51 LineAttributes object, 125
Sound, 77, 98 LineStripArray object, 209
Soundscape, 95 Link leaf node, 102, 105, 107
SpotLight, 76 Loader interface, 564
ViewPlatform, 97, 239–243, 514 LoaderBase class, 564
LEFT_EYE_VIEW flag, 518 loaders package, 564
length method loaders.lw3d package, 565
Vector2d, 369 loaders.objectfile package, 565
Vector2f, 374 local eye lighting, 249
Vector3d, 383 Locale object, 27, 37
Vector3f, 388 locales, 31
Vector4d, 401 LOD (level of detail) behavior
Vector4f, 410 nodes, 310
lengthSquared method LOD program, 596
Vector2d, 369 logical raster operations, 133
Vector2f, 374 lookAt method, 189, 533
Vector3d, 383 loop points, sound, 80
Vector3f, 388 loopCount parameter, 290
Vector4d, 401 lowerBound flag, 223
Vector4f, 410 LU decomposition, 458
LESS flag, 132 LUD method, 458

Version 1.2, March 2000 635

 INDEX

LUDBackSolve method, 423 mipmap

LUMINANCE flag, 142 level, 142, 143, 144
LUMINANCE_ALPHA flag, 142 mode, 144
Lw3dLoader class, 565 MismatchedSizeException, 540
mixed mode rendering, 351
mode parameter, 290
model transform, 244, 357
M ModelClip leaf node, 63
mach banding, 466 ModelClipTest program, 597
magnification filter, 143 ModelClipTest2 program, 597
MainFrame class, 566 MODULATE flag, 134
majorVersionNumber constant, 222 MONO_SPEAKER flag, 336
Manhattan distance monoscopic view policy
Point2d, 368 Canvas3D object, 524
Point2f, 373 View object, 517
Point3d, 382 Morph leaf node, 99
Point3f, 387 Morphing program, 597
Point4d, 400 mouse behaviors, utilities for, 567
Point4f, 408 mouse input processing, 267
material color, 140 MouseBehavior class, 568
Material object, 121, 138 MouseBehaviorCallback interface, 568
math node component objects, 232, 363– MouseRotate class, 568
458
MouseTranslate class, 568
matrix multiplication, 177
MouseZoom class, 568
matrix objects, 234, 423–458
moveTo method, 43
Matrix3d class, 234, 430
moving objects semantics, 35
Matrix3f class, 234, 424
mul method
Matrix4d class, 234, 445
GMatrix, 454
Matrix4f class, 234, 437
GVector, 420
MAXIMUM_SENSOR_BUTTON_
Matrix3d, 434, 436
COUNT flag, 322
Matrix3f, 428, 430
MediaContainer node component
object, 151 Matrix4d, 449, 452
memory pool, increasing size of, 586, 587 Matrix4f, 440, 444
mesh buffer, 464 Quat4d, 403
meshBufferReference command, 481 Quat4f, 411
minification filter function, 143 Transform3D, 187
minimum environment, 246 mulInverse method
minorMinorVersionNumber Quat4d, 403
constant, 222 Quat4f, 411
minorVersionNumber constant, 222 Transform3D, 187

636 The Java 3D API Specification

INDEX

mulNormalize method Matrix4d, 451

Matrix3d, 434 Matrix4f, 443
Matrix3f, 428 Tuple2d, 366
MULTI_LEVEL_LINEAR flag, 143, 557 Tuple2f, 371
MULTI_LEVEL_MIPMAP flag, 142 Tuple3d, 379
MULTI_LEVEL_POINT flag, 143 Tuple3f, 385
multiple texture mapping units, 149 Tuple3i, 392
MultipleParentException, 540 Tuple4d, 397
multiplyModelTransform method, 357 Tuple4f, 405
MultiTransformGroup class, 573 Tuple4i, 413
mulTransposeBoth method NEGATIVE_DETERMINANT flag, 178
GMatrix, 457 NEVER flag, 132
Matrix3d, 434 NICEST flag
Matrix3f, 428 ColoringAttributes, 125
Matrix4d, 452 Texture, 143
Matrix4f, 444 TextureAttributes, 136
Transform3D, 187 TransparencyAttributes, 137
mulTransposeLeft method NO_FILTER flag, 78
GMatrix, 457 NO_PREDICTOR flag, 319
Matrix3d, 434 node component objects, 119–234
Matrix3f, 428 Appearance, 119
Matrix4d, 452 AuralAttributes, 152, 155, 359
Matrix4f, 444 BoundingBox, 170
Transform3D, 187 BoundingPolytope, 174
mulTransposeRight method BoundingSphere, 172
GMatrix, 457 Bounds, 168
Matrix3d, 434 ColoringAttributes, 123
Matrix3f, 428 CompressedGeometry, 219, 222
Matrix4d, 452 CompressedGeometryHeader, 222
Matrix4f, 444 DepthComponent, 166
Transform3D, 187 DepthComponentFloat, 167
muteSample method, 342 DepthComponentInt, 167
DepthComponentNative, 168
Font3D, 226
FontExtrusion, 227
N Geometry, 190
negate method GeometryArray, 191
GMatrix, 454 GeometryStripArray, 208
GVector, 421 ImageComponent, 159
HiResCoord, 39 ImageComponent2D, 162
Matrix3d, 435 ImageComponent3D, 164
Matrix3f, 429

Version 1.2, March 2000 637

 INDEX

node component objects (Continued) nodeCount method, 326

IndexedGeometryArray, 211 NodeReferenceTable object, 114
IndexedGeometryStripArray, 216 NOMINAL_FEET flag, 242
IndexedLineArray, 214 NOMINAL_HEAD flag, 242
IndexedLineStripArray, 217 NOMINAL_SCREEN flag, 242
IndexedPointArray, 214 NON_BLOCKING flag, 316
IndexedQuadArray, 215 NONE flag, 137
IndexedTriangleArray, 215 nop command, 477
IndexedTriangleFanArray, 218 norm method, 421
IndexedTriangleStripArray, 218 normal
LineArray, 207 command, 489
LineAttributes, 125 parameter, 199
LineStripArray, 209 sub-command, 486
Material, 138 NORMAL_IN_BUFFER flag, 222
math, 232, 363–458 NormalGenerator class, 570
matrix, 234 normalize method
MediaContainer, 151 GVector, 422
NodeReferenceTable, 114 Matrix3d, 435
PointArray, 206 Matrix3f, 429
PointAttributes, 127 Quat4d, 403
PolygonAttributes, 128 Quat4f, 412
QuadArray, 208 Transform3D, 188
Raster, 223 Vector2d, 369
references to, 109 Vector2f, 374
RenderingAttributes, 130 Vector3d, 383
TexCoordGeneration, 146 Vector3f, 389
Text3D, 228 Vector4d, 402
Texture, 140 Vector4f, 410
Texture2D, 145 normalizeCP method
Texture3D, 145 Matrix3d, 435
TextureAttributes, 133 Matrix3f, 429
TextureUnitState, 149 Transform3D, 188
Transform3D, 177 NORMALS flag, 194
TransparencyAttributes, 136 normals parameter, 199
TriangleArray, 207 normSquared method, 421
TriangleFanArray, 210 NOT_EQUAL flag, 132
TriangleStripArray, 210 NTSC luminance equation, 546
tuple, 232 numBranchGraphs method, 38
Node object, 23, 24 numCanvas3Ds method, 249
node objects, See node component numChildren method, 42
objects, group nodes, leaf nodes numDistances method, 312
NodeComponent object, 26

638 The Java 3D API Specification

INDEX

numGeometries method, 55 PATH_DOWN flag, 231

numLights method, 357 PATH_LEFT flag, 231
numLocales method, 36 PATH_RIGHT flag, 231
numMipMapLevels method, 144 PATH_UP flag, 231
numScopes method PathInterpolator object, 302
AlternateAppearance, 104 PATTERN_DASH flag, 125
Fog, 68 PATTERN_DASH_DOT flag, 125
Light, 73 PATTERN_DOT flag, 125
ModelClip, 66 PATTERN_SOLID flag, 125
numSounds method, 359 PATTERN_USER_DEFINED flag, 126
numSwitches method, 310 pauseSample method, 342
perspective
correction mode, 136
method, 189, 533
O projection matrix, 189
obj2cg program, 596 PERSPECTIVE_PROJECTION
object hierarchy, 6 flag, 249
OBJECT_LINEAR flag, 147 phaseDelayDuration parameter, 290
ObjectFile class, 565 physical
ObjLoad program, 597 body, 28
occlusion culling, 20, 496 coexistence policy, 529
off-screen rendering, 259 coordinate systems, 512
OffScreenTest program, 598 environment, 28
OpenGL, 576 world, 237
installing on Solaris systems, 579 PHYSICAL_EYE flag, 251
OrderedGroup node, 47 PHYSICAL_SCREEN flag, 251
OrientedPtTest program, 599 PHYSICAL_WORLD flag, 250
OrientedShape3D leaf node, 55 PhysicalBody object, 28, 238, 239, 264,
OrientedTest program, 599 350, 525
ortho method, 189, 534 PhysicalEnvironment object, 28, 238, 239,
ORTHOGONAL flag, 177 265, 350, 527
orthographic projection matrix, 189 pick shapes
cone, 330
cone ray, 331
cone segment, 331
P cylinder, 332
PackageInfo program, 599 cylindrical ray, 332
packages, utility, 561–574 cylindrical segment, 333
parallel projection matrix, 189 point, 329
PARALLEL_PROJECTION flag, 249 ray, 329
ParsingErrorException, 565 segment, 330
passive flag, 277 pickAll method, 327

Version 1.2, March 2000 639

 INDEX

pickAllSorted method, 327 PointArray object, 206

pickAny method, 327 PointAttributes object, 127
PickBounds object, 328 PointLight leaf node, 74
PickCanvas class, 572 PointSound leaf node, 84
pickClosest method, 327 policies
PickCone object, 330 back clip, 251
PickConeRay object, 331 clip, 251
PickConeSegment object, 331 eyepoint, 516
PickCylinder object, 332 front clip, 251
PickCylinderRay object, 332 monoscopic view
PickCylinderSegment object, 333 Canvas3D object, 524
View object, 517
picking, 196, 202, 224, 323–333
physical coexistance, 529
picking package, 571
projection, 249
picking.behaviors package, 572
screen scale, 516
PickIntersection class, 572
sensor predictor type, 321
PickPoint object, 329
view, 515
PickRay object, 329
view attach, 98, 242
PickResult class, 572
visibility, 518
PickSegment object, 330
window eyepoint, 517
PickShape object, 328
window resize, 249
PickTest program, 599
pollAndProcessInput method, 317
PickText3DBounds program, 601
polygon rasterization mode, 130
PickText3DGeometry program, 601
POLYGON_FILL flag, 130
PickTool class, 572
POLYGON_LINE flag, 130
planeR parameter, 148
POLYGON_POINT flag, 130
planeS parameter, 148
PolygonAttributes object, 128
planeT parameter, 148
polytope, 174
PlatformGeometry class, 573
position sub-command, 482
playing state, sound, 82
position, pointlight, 75
point antialiasing flag, 128
PositionInterpolator object, 295
point size, 128
PositionPathInterpolator object, 303
POINT_BUFFER flag, 222
postId method, 273
POINT_SOUND flag, 339
postRender method, 353
Point2d class, 367
postSwap method, 353
Point2f class, 372
PREDICT_NEXT_FRAME_TIME
Point3d class, 381 flag, 319
Point3f class, 386 PREDICT_NONE flag, 319
Point3i class, 393 predictor policy, 321
Point4d class, 399 predictor type, 321
Point4f class, 407 prepareSound method, 340
Point4i class, 415 preRender method, 352

640 The Java 3D API Specification

INDEX

Primitive class, 570 Quat4f class, 410

primitives, utilities for, 569 queryProperties method, 261
PrintFromButton program, 598 QueryProperties program, 599
priority, 81
processing mode, 316
processStimulus method
Behavior, 272
R
Billboard, 314 R coordinate plane equation, 149
ColorInterpolator, 299 Raster node component object, 223
DistanceLOD, 312 RASTER_COLOR flag, 224
PositionInterpolator, 296 RASTER_COLOR_DEPTH flag, 224
PositionPathInterpolator, 305 RASTER_DEPTH flag, 224
RotationInterpolator, 298 ray pick shape, 332
RotationPathInterpolator, 310 README file, 576
RotPosPathInterpolator, 306 readRaster method, 360
RotPosScalePathInterpolator, 308 ReadRaster program, 603
ScaleInterpolator, 300 reflection coefficient, 153
SwitchValueInterpolator, 301 reflection vector, 545
TransparencyInterpolator, 302 region
processStreamInput method, 317 application, 61, 62, 97
program sample of influence, 68, 72
Fog node, 68
HelloUniverse, 9 Light node, 72
programming conventions, xvii scheduling, 81, 273
programming paradigm, 2 RELATIVE_TO_COEXISTENCE
project method flag, 517
Point3d, 382 RELATIVE_TO_FIELD_OF_VIEW
Point3f, 387 flag, 516
Point4d, 400 RELATIVE_TO_SCREEN flag, 517
Point4f, 408 RELATIVE_TO_WINDOW flag, 517
projection policy, 249 removeAllLocales method, 36
proximity detection, 20 removeBranchGraph method, 38
pure immediate mode rendering, 349 removeCanvas3D method, 248
PureImmediate program, 601 removeChild method, 42
Pyramid2Cube program, 597 removeGeometry method, 54
removeInputDevice method, 528
removeLight method, 357
removeLocale method, 36
Q removeScope method
QuadArray object, 208 AlternateAppearance, 104
quadrilateral, 208, 215 Fog, 68
quantization of color data, 466 Light, 73
Quat4d class, 402

Version 1.2, March 2000 641

 INDEX

removeScope method (Continued) Matrix4d, 452

ModelClip, 65 Matrix4f, 444
removeSound method, 359 RotationInterpolator object, 296
removeSwitch method, 310 RotationPathInterpolator object, 308
render loop, 347 RotPosPathInterpolator object, 305
renderField method, 353 RotPosScalePathInterpolator object, 307
rendering, 21 rotX method
immediate mode, 349–361 Matrix3d, 434
modes, 345 Matrix3f, 428
RenderingAttributes object, 130 Matrix4d, 452
renderOffScreenBuffer method, 259 Matrix4f, 444
renderOnce method, 255 Transform3D, 183
repaint method, 255 rotY method
REPLACE flag, 135 Matrix3d, 434
replace_middle, 462 Matrix3f, 428
replace_oldest, 462 Matrix4d, 452
replaceBranchGraph method, 38 Matrix4f, 444
restart_clockwise, 462 Transform3D, 183
restart_counterclockwise, 462 rotZ method
RestrictedAccessException, 540 Matrix3d, 434
retained mode, 3, 346 Matrix3f, 428
ReverberateSound program, 603 Matrix4d, 452
reverberation, 95, 153 Matrix4f, 444
delay, 154, 156 Transform3D, 183
equations, 553
order, 154, 157
RGB flag, 142
RGBA flag, 142
S
RIGHT_EYE_VIEW flag, 518 S coordinate plane equation, 148
RIGID flag, 177 SCALE flag, 177
ROP_COPY flag, 133 scale method
ROP_XOR flag, 133 GVector, 422
ROTATE_ABOUT_AXIS flag HiResCoord, 39
Billboard, 312 Tuple2d, 366
OrientedShape3D, 56 Tuple2f, 371
ROTATE_ABOUT_POINT flag Tuple3d, 379
Billboard, 313 Tuple3f, 385
OrientedShape3D, 56 Tuple3i, 392
rotation, 177 Tuple4d, 397
rotation matrices Tuple4f, 405
Matrix3d, 434 Tuple4i, 414
SCALE_EXPLICIT flag, 516

642 The Java 3D API Specification

INDEX

SCALE_SCREEN_SIZE flag, 516 set method

scaleAdd method AxisAngle4d, 416
GVector, 422 AxisAngle4f, 418
Transform3D, 182 BoundingBox, 170
Tuple2d, 366 BoundingPolytope, 176
Tuple2f, 371 BoundingSphere, 173
Tuple3d, 379 Bounds, 168
Tuple3f, 385 Color3b, 377
Tuple3i, 392 Color3f, 390
Tuple4d, 397 Color4b, 395
Tuple4f, 405 Color4f, 409
Tuple4i, 414 GMatrix, 455
ScaleInterpolator object, 299 GVector, 421
scaling, 177 ImageComponent2D, 164
scene antialiasing, 255, 523 ImageComponent3D, 165, 166
scene graph, 19–28 Matrix3d, 431
flattening, 346 Matrix3f, 425
node component objects, 119–234 Matrix4d, 449, 451
objects, 21 Matrix4f, 438
reusing, 105–112 MultiTextureState, 150
structure, 19 PickBounds, 328
superstructure objects, 27 PickConeSegment, 331
viewing objects, 27 PickCylinderRay, 332
Scene interface, 564 PickCylinderSegment, 333
SceneBase class, 564 PickPoint, 329
SceneGraphCycleException, 541 PickRay, 329
SceneGraphObject, 21 PickSegment, 330
scheduling Point4f, 407
behavior, 270 Quat4d, 403
region, 81, 267, 271, 273 Quat4f, 412
volume tree, 271 SceneGraphPath, 326
screen scale policy, 516 SensorRead, 323
screen scale value, 516 Transform3D, 184, 185
SCREEN_DOOR flag, 137 Tuple2d, 365
SCREEN_VIEW flag, 515 Tuple2f, 370
Screen3D object, 28, 238, 239, 256, 520 Tuple3b, 376
calibration parameters, 521 Tuple3d, 378
screen-door transparency, 137 Tuple3f, 384
Sensor object, 319 Tuple3i, 391
SensorRead object, 322 Tuple4b, 394
sensors, 318 Tuple4d, 396

Version 1.2, March 2000 643

 INDEX

set method (Continued) setAuralAttributes method

Tuple4f, 404 GraphicsContext3D, 359
Tuple4i, 413 Soundscape, 97
Vector4f, 410 setAutoNormalize method, 180
setActivationRadius method, 98 setAxisOfRotation method
setAlignment method, 230 RotationInterpolator, 297
setAlignmentAxis method RotationPathInterpolator, 309
Billboard, 314 setAxisOfRotPos method, 306
OrientedShape3D, 57 setAxisOfRotPosScale method, 308
setAlignmentMode method setAxisOfScale method, 300
Billboard, 314 setAxisOfTranslation method
OrientedShape3D, 57 PositionInterpolator, 296
setAlpha method, 295 PositionPathInterpolator, 304
setAlphaTestFunction method, 132 setBackClipDistance method, 252
setAlphaTestValue flag, 132 setBackClipPolicy method, 251
setAlternateCollisionTarget method, 43 setBackDistance method
setAmbientColor method, 139 Clip, 62
setAngleOffsetToSpeaker method, 337 LinearFog, 70
setAngularAttenuation method setBackDistanceGain method, 92
AudioDevice3D, 343 setBackFaceNormalFlip method, 130
ConeSound, 94 setBackground method
setAppearance method GraphicsContext3D, 356
AlternateAppearance, 103 J3DGraphics2D, 361
GraphicsContext3D, 356 setBlueSize method, 264
Morph, 101 setBoundaryColor method, 144
Shape3D, 55 setBoundaryModeR method, 146
setAppearanceOverrideEnable method setBoundaryModeS method, 142
Morph, 101 setBoundaryModeT method, 142
Shape3D, 55 setBounds method, 25
setApplicationBoundingLeaf method setBoundsAutoCompute method, 25
Background, 61 setBufferOverride method, 358
Clip, 62 setButtons method, 323
Soundscape, 97 setCacheEnable method, 152
setApplicationBounds method setCanvas3D method, 248
Background, 61 setCapability method, 22
Clip, 62 setCenter method, 173
Soundscape, 97 setCenterEarToSpeaker method, 337
setAttenuation method, 76 setCharacterSpacing method, 232
setAttributeGain method, 156 setChild method, 42
setAudioDevice method, 528 setChildMask method, 49
setAudioPlaybackType method, 337 setCoexistenceCenteringEnable
method, 519

644 The Java 3D API Specification

INDEX

setCoexistenceCenterInPworldPolicy setCoordRefDouble method, 202

method, 529 setCoordRefFloat method, 202
setCoexistenceToTrackerBase setCullFace method, 129
method, 528 setDecreasingAlphaDuration
setCollidable method, 26 method, 294
setCollisionBounds method setDecreasingAlphaRampDuration
Group, 43 method, 294
Morph, 101 setDensity method, 69
Shape3D, 55 setDepthBufferEnable method, 132
setColor command, 489 setDepthBufferFreezeTransparent
setColor method method, 255
Background, 60 setDepthBufferWriteEnable method, 132
ColoringAttributes, 124 setDepthComponent method, 226
Fog, 67 setDepthData method
GeometryArray, 198 DepthComponentFloat, 167
Light, 72 DepthComponentInt, 167
setColorIndex method, 212 setDepthSize method, 264
setColorIndices method, 213 setDevice method, 321
setColoringAttributes method, 122 setDiffuseColor method, 140
setColorRef3b method, 204 setDirection method
setColorRef3f method, 203 AudioDevice3D, 342
setColorRef4b method, 204 ConeSound, 94
setColorRef4f method, 203 DirectionalLight, 74
setColorRefByte method, 203 SpotLight, 77
setColorRefFloat method, 203 setDistance method, 312
setColors method, 198 setDistanceFilter method
setColumn method AudioDevice3D, 341
GMatrix, 456 AuralAttributes, 157
Matrix3d, 433 setDistanceGain method
Matrix3f, 426 AudioDevice3D, 341
Matrix4d, 447 ConeSound, 92
Matrix4f, 441 PointSound, 86
setCompatibilityModeEnable setDominantHandIndex method, 529
method, 531 setDoubleBuffer method, 263
setConcentration method, 77 setDoubleBufferEnable method, 261
setContinuousEnable method, 81 setDstBlendFunction method, 138
setCoordinate method, 196 setDuplicateOnCloneTree method, 26,
setCoordinateIndex method, 212 110
setCoordinateIndices method, 212 setElement method
setCoordinates method, 197 GMatrix, 456
setCoordRef3d method, 203 GVector, 421
setCoordRef3f method, 203 Matrix3d, 432

Version 1.2, March 2000 645

 INDEX

setElement method (Continued) setHiRes method

Matrix3f, 426 GraphicsContext3D, 357
Matrix4d, 446 Locale, 37
Matrix4f, 440 setHiResCoord method, 38
setEmissiveColor method, 139 setHiResCoordX method, 38
setEnable method setHiResCoordY method, 38
Behavior, 295 setHiResCoordZ method, 38
Light, 72 setHotspot method, 320
ModelClip, 65 setIdentity method
Sound, 82 GMatrix, 455
TexCoordGeneration, 148 Matrix3d, 436
Texture, 144 Matrix3f, 427
setEnables method, 65 Matrix4d, 453
setEndColor method, 298 Matrix4f, 442
setEndPosition method, 296 Transform3D, 181
setEuler method, 181 setIgnoreVertexColors method, 133
setExtrusionShape method, 228 setImage method
setFieldOfView method, 252 Background, 60
setFirstChildIndex method, 300 Raster, 226
setFog method, 356 Texture, 143
setFont3D method, 230 setImages method, 144
setFormat method, 148 setIncreasingAlphaDuration method, 293
setFrequencyScaleFactor method setIncreasingAlphaRampDuration
AudioDevice3D, 343 method, 293
AuralAttributes, 158 setInfluencingBoundingLeaf method
setFrontBufferRendering method, 358 AlternateAppearance, 103
setFrontClipDistance method, 252 Fog, 68
setFrontClipPolicy method, 251 Light, 72
setFrontDistance method, 70 ModelClip, 65
setGenMode method, 148 setInfluencingBounds method
setGeometry method AlternateAppearance, 103
Background, 60 Fog, 68
Shape3D, 54 Light, 72
setGeometryArrays method, 100 ModelClip, 64
setGreenSize method, 264 setInitialColorIndex method, 202
setHeadIndex method, 529 setInitialCoordIndex method, 202
setHeadToHeadTracker method, 526 setInitialGain method, 80
setHeadTrackerToLeftImagePlate setInitialNormalIndex method, 202
method, 522 setInitialTexCoordIndex method, 202
setHeadTrackerToRightImagePlate setInitialVertexIndex method, 196
method, 522 setInputStream method, 152
setInterleavedVertices method, 205

646 The Java 3D API Specification

INDEX

setKnot method, 303 setNode method, 326

setKnots method, 303 setNodes method, 326
setLastChildIndex method, 300 setNominalEyeHeightFromGround
setLeftEarPosition method, 526 method, 526
setLeftEyePosition method, 526 setNominalEyeOffsetFromNominalScree
setLeftHandIndex method, 529 n method, 526
setLeftManualEyeInCoexistence setNominalPositionAndOrientation
method, 519 method, 317
setLeftManualEyeInImagePlate setNonDominantHandIndex method, 529
method, 523 setNonUniformScale method
setLeftProjection method, 535 (deprecated), 182
setLight method, 357 setNormal method, 199
setLightingEnable method, 140 setNormalIndex method, 213
setLineAntialiasingEnable method, 126 setNormalIndices method, 213
setLineAttributes method, 122 setNormalRef3f method, 204
setLinePattern method, 126 setNormalRefFloat method, 204
setLineWidth method, 126 setNormals method, 200
setLocale method, 326 setObject method, 326
setLocalEyeLightingEnable method, 249 setOffScreenBuffer method, 259
setLoop method setOffScreenLocation method, 260
AudioDevice3D, 342 setOffset method, 225
Sound, 80 setPath method, 231
setLoopCount method, 293 setPathArrays method
setLower method, 170 PositionPathInterpolator, 305
setMagFilter method, 143 RotationPathInterpolator, 309
setMaterial method, 121 RotPosPathInterpolator, 306
setMaximumAngle method, 297 RotPosScalePathInterpolator, 308
setMaximumScale method, 299 setPatternMask method, 127
setMaximumTransparency method, 301 setPatternScaleFactor method, 127
setMinFilter method, 143 setPerspectiveCorrectionMode
method, 136
setMinimumAngle method, 297
setPhaseDelayDuration method, 293
setMinimumFrameCycleTime
method, 254 setPhysicalBody method, 248
setMinimumScale method, 299 setPhysicalEnvironment method, 248
setMinimumTransparency method, 301 setPhysicalScreenHeight method, 522
setMipMapMode method, 144 setPhysicalScreenWidth method, 522
setMode method, 293 setPickable method, 26
setModelClip method, 358 setPlane method, 65
setModelTransform method, 357 setPlaneR method, 149
setMonoscopicViewPolicy method, 524 setPlaneS method, 148
setMultiTextureState method, 123 setPlanes method
setNextSensorRead method, 322 BoundingPolytope, 175

Version 1.2, March 2000 647

 INDEX

setPlanes method (Continued) setReverbDelay method

ModelClip, 65 AudioDevice3D, 343
setPlaneT method, 149 AuralAttributes, 156
setPointAntialiasingEnable method, 128 setReverbOrder method
setPointAttributes method, 122 AudioDevice3D, 343
setPointSize method, 128 AuralAttributes, 157
setPolygonAttributes method, 122 setRightEarPosition method, 526
setPolygonMode method, 130 setRightEyePosition method, 526
setPolygonOffset method, 130 setRightHandIndex method, 529
setPolygonOffsetFactor method, 130 setRightManualEyeInCoexistence
setPosition method method, 519
AudioDevice3D, 342 setRightManualEyeInImagePlate
DistanceLOD, 312 method, 523
PointLight, 75 setRightProjection method, 535
PointSound, 86 setRolloff method
PositionPathInterpolator, 304 AudioDevice3D, 343
Raster, 225 AuralAttributes, 156
RotPosPathInterpolator, 306 setRotation method
RotPosScalePathInterpolator, 308 Matrix4d, 448
Text3D, 230 Matrix4f, 441
setPredictionPolicy method, 321 Transform3D, 181
setPredictor method, 321 setRotationPoint method
setPriority method, 81 Billboard, 314
setProcessingMode method, 316 OrientedShape3D, 57
setProjectionPolicy method, 249 setRotationScale method
setQuat method Matrix4d, 448
RotationPathInterpolator, 309 Matrix4f, 442
RotPosPathInterpolator, 306 Transform3D, 182
RotPosScalePathInterpolator, 307 setRow method
setRadius method, 172 GMatrix, 456
setRasterOp method, 133 Matrix3d, 432
setRasterOpEnable method, 133 Matrix3f, 426
setRedSize method, 264 Matrix4d, 447
setReflectionCoefficient method Matrix4f, 441
AudioDevice3D, 343 setSampleGain method, 341
AuralAttributes, 156 setScale method
setRegion method, 59 GMatrix, 456
setReleaseEnable method, 80 Matrix3f, 430
setRenderingAttributes method, 122 Matrix4d, 449
setReverbBounds method, 157 Matrix4f, 440
RotPosScalePathInterpolator, 307
Transform3D, 182

648 The Java 3D API Specification

INDEX

setSceneAntialiasingEnable method, 255 setTarget method

setSchedulingBoundingLeaf method Billboard, 314
Behavior, 273 ColorInterpolator, 298
Sound, 81 PositionInterpolator, 296
setSchedulingBounds method PositionPathInterpolator, 304
Behavior, 273 RotationInterpolator, 297
Sound, 81 RotationPathInterpolator, 309
setScope method RotPosPathInterpolator, 306
AlternateAppearance, 104 RotPosScalePathInterpolator, 308
Fog, 68 ScaleInterpolator, 300
Light, 73 SwitchValueInterpolator, 301
ModelClip, 65 TransparencyInterpolator, 302
setScreenScale method, 516 setTexCoordGeneration method
setScreenScalePolicy method, 516 Appearance, 123
setSensor method, 529 MultiTextureState, 150
setSensorCount method, 528 setTexCoordRef2f method, 205
setSensorReadCount method, 320 setTexCoordRef3f method, 205
setShadeModel method, 124 setTexCoordRefFloat method, 204
setSharedGroup method, 108 setTexture method
setShininess method, 140 Appearance, 121
setSize method MultiTextureState, 150
GMatrix, 455 setTextureAttributes method
GVector, 421 Appearance, 122
Raster, 225 MultiTextureState, 150
Screen3D, 257 setTextureBlendColor method, 135
setSound method, 359 setTextureColorTable method, 135
setSoundData method, 79 setTextureCoordinate method, 200
setSpecularColor method, 140 setTextureCoordinateIndex method, 213
setSpreadAngle method, 77 setTextureCoordinateIndices
setSrcBlendFunction method, 138 method, 213
setStartColor method, 298 setTextureCoordinates method, 201
setStartPosition method, 296 setTextureMode method, 134
setStartTime method, 292 setTextureTransform method, 136
setState command, 477 setTime method, 323
setStereo method, 263 setTrackerBaseToImagePlate
setStereoEnable method, 261 method, 522
setStereoMode method, 358 setTrackingEnable method, 515
setString method, 230 setTransform method
setSwitch method, 310 SceneGraphPath, 326
setTable command, 479 TransformGroup, 47

Version 1.2, March 2000 649

 INDEX

setTranslation method SHADE_GOURAUD flag, 125

Matrix4d, 448 Shape3D leaf node, 21, 51, 360
Matrix4f, 442 shared subgraphs, 105–108
Transform3D, 184 SharedGroup node, 50, 105
setTransparency method, 137 shininess, 139
setTransparencyAttributes method, 122 SimpleCylinder program, 594
setTransparencyMode method, 137 SimpleGeometry program, 601
setTriggerTime method, 293 SimpleSounds program, 603
setType method, 225 SimpleUniverse class, 574
setUpper method, 170 singular value decomposition, 429, 448,
setURL method (deprecated), 152 458
setURLObject method, 152 SingularMatrixException, 541
setURLString method, 152 size constant, 223
setUserData method, 23 solid line, 125
setUserHeadToVworldEnable sound
method, 515 caching, 79
setValidVertexCount method, 196 enable, 83
setVelocityScaleFactor method environment, 95
AudioDevice3D, 344 equations, 546
AuralAttributes, 158 list, 359
setView method, 339 loop points, 80
setViewAttachPolicy method, 99, 242 playing state, 82
setViewPolicy method, 515 reflection, 156
setVisibilityPolicy method, 518 reverberation, 153
setVisible method, 133 sample, 77
setVpcToEc method, 535 scheduling region, 81, 273
setVworldXfrm method, 342 speed, 156
setWeights method, 101 Sound leaf node, 77, 98
setWhichChild method, 49 SoundException, 542
setWindowEyepointPolicy method, 517 Soundscape leaf node, 95
setWindowMovementPolicy method, 250 source blend function, 138
setWindowResizePolicy method, 250 spatial separation, 19
setYUp method, 162 speaker playback equations, 554
setZero method specular
GMatrix, 455 color, 139
Matrix3d, 436 highlight color, 140
Matrix3f, 427 scattering exponent, 140
Matrix4d, 453 speed of sound, 156
Matrix4f, 442 Sphere class, 570
Transform3D, 181 SPHERE_MAP flag, 147
shade model component information, 124 SphereMotion program, 603
SHADE_FLAT flag, 125 spherical bounding volume, 172

650 The Java 3D API Specification

INDEX

spline animation paths, 604 Tuple3d, 379

SplineAnim program, 604 Tuple3f, 384
spot light, 76 Tuple3i, 391
SpotLight leaf node, 76 Tuple4d, 397
spread angle, spotlight, 77 Tuple4f, 405
start flag, 223 Tuple4i, 413
startBehaviorScheduler method, 254 subclassing nodes, 113
startRenderer method, 353 subgraphs
startSample method, 341 cloning, 108–117
startView method, 254 shared, 105–108
state change clustering, 346 surface normal compression, 467
state inheritance, 20 SVD method, 458
stereo enabled flag, 261 SVDBackSolve method, 423
stereo mode, 358 swap method, 354
stereo mode override, 358 Switch group node, 48
STEREO_BOTH flag, 355 SwitchValueInterpolator object, 300
STEREO_LEFT flag, 355
STEREO_RIGHT flag, 355
STEREO_SPEAKERS flag, 336
StereoAvailable, 261
T
stimulus method, 268 T coordinate plane equation, 149
stopBehaviorScheduler method, 254 tessellation tolerance, 226, 228
stopRenderer method, 353 TexCoord2f class, 375
stopSample method, 341 TexCoord3f class, 389
stopView method, 254 TexCoordGeneration node component
object, 146
STREAMING_AUDIO_DATA flag, 339
text
Stripifier class, 570
alignment policy, 230
stripIndexCounts parameter, 216
position, 230
stripVertexCounts parameter, 208
Text2D class, 571
style conventions, xvii
Text2DTest program, 604
sub method
Text3D object, 228
GMatrix, 454
Text3DLoad program, 604
GVector, 420
texture
HiResCoord, 39
application equations, 558
Matrix3d, 433
blend color, 135
Matrix3f, 427
boundary color, 144
Matrix4d, 449
coordinate generation mode, 148
Matrix4f, 442
coordinates, 147
Transform3D, 183
filter parameters, 556
Tuple2d, 365
lookup equations, 556
Tuple2f, 370
map, 121, 143, 556

Version 1.2, March 2000 651

 INDEX

texture (Continued) Matrix4f, 445

mapping, 140 PhysicalBody, 526
equations, 556 SceneGraphPath, 327
perspective correction, 136 Transform3D, 183
mode, 134
Tuple2d, 367
node component object, 140
Tuple2f, 372
object, 121
Tuple3b, 376
transform object, 136
Tuple3d, 379
texture loaders, 571
Tuple3f, 384
Texture node component object, 140
Tuple4b, 394
texture unit state, 123
Tuple4d, 398
TEXTURE_COORDINATE_2 flag
Tuple4f, 406
GeometryArray, 194
Tuple4i, 414
TexCoordGeneration, 147
View, 515
TEXTURE_COORDINATE_3 flag
trace method, 458
GeometryArray, 194
tracker, 315
TexCoordGeneration, 147
base coordinate system, 513
Texture2D node component object, 145
input processing, 315
Texture3D node component object, 145
transform method
TextureAttributes object, 133
BoundingBox, 171
TextureByReference program, 604
BoundingPolytope, 176
TexturedCone program, 594
BoundingSphere, 173
TexturedSphere program, 594
Bounds, 169
TextureImage program, 605
Matrix3d, 433, 436
TextureLoader class, 571
Matrix3f, 427, 430
TextureLoader utility, 591
Matrix4d, 451
TextureUnitState node component
Matrix4f, 443
object, 149
Transform3D, 188
TextureUnitState object, 123
Transform3D node component
threads, priority, 37
object, 177
TickTockCollision program, 605
TransformGroup node, 8, 21, 45, 324
TickTockPicking program, 605
translation, 177
toString method
TRANSLATION flag, 177
AxisAngle4d, 417
transparency
AxisAngle4f, 419
alpha value, 140
BoundingSphere, 174
attributes affecting, 136
GMatrix, 457
minimum, 301
GVector, 422
mode, 137
Material, 140
value, 137
Matrix3d, 436
TransparencyAttributes object, 136
Matrix3f, 430
TransparencyInterpolator object, 301
Matrix4d, 453

652 The Java 3D API Specification

INDEX

transpose method upperBound flag, 223

GMatrix, 457 USE_BOUNDS flag
Matrix3d, 434 WakeupOnCollisionEntry, 279
Matrix3f, 427 WakeupOnCollisionExit, 280
Matrix4d, 451 WakeupOnCollisionMovement, 281
Matrix4f, 442 USE_GEOMETRY flag
Transform3D, 183 WakeupOnCollisionEntry, 279
triangle fan primitive, 208 WakeupOnCollisionExit, 280
triangle strip primitive, 208 WakeupOnCollisionMovement, 281
TRIANGLE_BUFFER flag, 222 user-defined line pattern, 126
TriangleArray node component utility packages, 561–574
object, 207
TriangleFanArray node component
object, 210
TriangleStripArray node component V
object, 210 value method, 292
Triangulator class, 571 Vector2d class, 368
triggeredElements method, 274 Vector2f class, 373
triggerTime parameter, 290 Vector3d class, 382
tuple objects, 232, 363–415 Vector3f class, 388
Tuple2d class, 232, 363 Vector4d class, 401
Tuple2f class, 233, 369 Vector4f class, 409
Tuple3b class, 233, 375 velocity-activated Doppler effect, 152
Tuple3d class, 233, 377 vertex command, 488
Tuple3f class, 233, 383 vertexCount parameter
Tuple3i class, 233, 390 GeometryArray, 193
Tuple4b class, 233, 393 GeometryStripArray, 208
Tuple4d class, 233, 396 IndexedGeometryStripArray, 216
Tuple4f class, 233, 404 vertexFormat parameter
Tuple4i class, 233, 412 GeometryArray, 193
IndexedGeometryStripArray, 216
IndexedLineStripArray, 217
U IndexedTriangleFanArray, 219
IndexedTriangleStripArray, 218
universe package, 573
view
unmuteSample method, 342
attach policy, 98, 242
unpauseSample method, 342
frustum, 509, 531
updateData method culling, 20
GeometryArray, 196 model, 235–265, 509–535
GeometryUpdater, 206 platform transform, 244
updateNodeReferences method, 112 policy, 515
updateSample method, 344

Version 1.2, March 2000 653

View object, 28, 238, 239, 246, 247, 350, wakeup
514 conditions, 268, 271
Viewer class, 574 criterion, 269
Viewer program, 596 WakeupAnd object, 283
ViewerAvatar class, 574 WakeupAndOfOrs object, 284
viewing WakeupCondition object, 274
matrices, 243 WakeupCriterion object, 270, 274
semantics, 35 wakeupOn method, 273
ViewingPlatform class, 574 WakeupOnActivation object, 275
ViewPlatform WakeupOnAWTEvent object, 275
coordinate system, 511 WakeupOnBehaviorPost object, 275
Coordinates (VPC), 535 WakeupOnCollisionEntry object, 279
leaf node, 97, 239–243, 514 WakeupOnCollisionExit object, 280
virtual camera, 531 WakeupOnCollisionMovement
virtual universe, 31–40 object, 281
loading, 33 WakeupOnDeactivation object, 276
virtual world, 237 WakeupOnElapsedFrames object, 277
coordinate system, 511, 515 WakeupOnElapsedTime object, 277
coordinates, 34 WakeupOnSensorEntry object, 278
VIRTUAL_EYE flag, 251 WakeupOnSensorExit object, 279
VIRTUAL_SCREEN flag, 251 WakeupOnTransformChange object, 283
VIRTUAL_WORLD flag, 250 WakeupOnViewPlatformEntry
VirtualInputDevice programs, 605 object, 282
VirtualUniverse object, 6, 27, 36, 345 WakeupOnViewPlatformExit object, 283
visibility policy, 518 WakeupOr object, 284
VISIBILITY_DRAW_ALL flag, 518 WakeupOrOfAnds object, 284
VISIBILITY_DRAW_INVISIBLE Wavefront .obj files, loader for, 565
flag, 518 window
VISIBILITY_DRAW_VISIBLE resize policy, 249
flag, 518 sizing and movement, 249
vnop command, 484, 489 window system provided parameters, 259
VPC (ViewPlatform Coordinates), 535 WRAP flag
Texture, 143
Texture3D, 146
W
w flag
Tuple4b, 394 X
Tuple4d, 396 x flag
Tuple4f, 404 AxisAngle4d, 416
Tuple4i, 412 AxisAngle4f, 418
waitForOffScreenRendering method, 260 Tuple2d, 365
INDEX

x flag (Continued)
Tuple2f, 370
Z
z flag
Tuple3b, 376
AxisAngle4d, 416
Tuple3d, 378
AxisAngle4f, 418
Tuple3f, 384
Tuple3b, 376
Tuple3i, 390
Tuple3d, 378
Tuple4b, 394
Tuple3f, 384
Tuple4d, 396
Tuple3i, 390
Tuple4f, 404
Tuple4b, 394
Tuple4i, 412
Tuple4d, 396
Tuple4f, 404
Tuple4i, 412
Y ZERO flag, 177
y flag zero method, 421
AxisAngle4d, 416
AxisAngle4f, 418
Tuple2d, 365
Tuple2f, 370
Tuple3b, 376
Tuple3d, 378
Tuple3f, 384
Tuple3i, 390
Tuple4b, 394
Tuple4d, 396
Tuple4f, 404
Tuple4i, 412

Version 1.2, March 2000 655