Java 3D API specification

This book represents the definitive Java 3D API specification, providing authoritative and detailed descriptions of each element of the API. It offers an informative overview of Java 3D, comprehensive instructions for "scene graph" definition and construction, and a detailed description of the Java 3D View Model, an innovative model enabling applications to be displayed on a wide array of devices.

The book also covers: input devices, such as six-degrees-of-freedom trackers; picking mechanisms; behaviors and interpolators for animating objects; and audio capabilities. The Java 3D Execution and Rendering Model is described in depth, including the immediate, retained, and compiled-retained modes.

Comprehensive and definitive, this book is an essential reference for any Java programmer interested in entering the exciting world of three-dimensional Internet applications.

Table of contents :
Preface xix

1 Introduction to Java3D ..... 1

1.1 Goals ..... 1

1.2 Programming Paradigm ..... 2

1.2.1 The Scene Graph Programming Model ..... 2

1.2.2 Rendering Modes ..... 2

1.2.3 Extensibility ..... 3

1.3 High Performance ..... 4

1.3.1 Layered Implementation ..... 4

1.3.2 Target Hardware Platforms ..... 4

1.4 Support for Building Applications and Applets ..... 5

1.4.1 Browsers ..... 5

1.4.2 Games ..... 5

1.5 Overview of Java3D Object Hierarchy ..... 6

1.6 Structuring the Java3D Program ..... 7

1.6.1 Java3D Application Scene Graph ..... 7

1.6.2 Recipe for a Java3D Program ..... 8

1.6.3 HelloUniverse: A Sample Java3D Program ..... 9

2 Scene Graph Basics ..... 15

2.1 Scene Graph Structure ..... 15

2.1.1 Spatial Separation ..... 15

2.1.2 State Inheritance ..... 16

2.1.3 Rendering ..... 17

2.2 Scene Graph Objects ..... 17

2.2.1 Node Objects ..... 19

2.2.2 NodeComponent Objects ..... 22

2.3 Scene Graph Superstructure Objects ..... 23

2.3.1 VirtualUniverse Object ..... 24

2.3.2 Locale Object ..... 24

2.4 Scene Graph Viewing Objects ..... 24

2.4.1 Canvas3D Object ..... 24

2.4.2 Screen3D Object ..... 25

2.4.3 View Object ..... 25

2.4.4 PhysicalBody Object ..... 26

2.4.5 PhysicalEnvironment Object ..... 26

3 Scene Graph Superstructure ..... 27

3.1 The Virtual Universe ..... 27

3.2 Establishing a Scene ..... 28

3.3 Loading a Virtual Universe ..... 29

3.4 Coordinate Systems ..... 29

3.5 High-Resolution Coordinates ..... 29

3.5.1 Java3D High-Resolution Coordinates ..... 29

3.5.2 Java3D Virtual World Coordinates ..... 30

3.5.3 Details of High-Resolution Coordinates ..... 30

3.6 API for Superstructure Objects ..... 32

3.6.1 VirtualUniverse Object ..... 32

3.6.2 Locale Object ..... 33

3.6.3 HiResCoord Object ..... 34

4 Group Node Objects ..... 37

4.1 Group Node ..... 37

4.2 BranchGroup Node ..... 40

4.3 TransformGroup Node ..... 42

4.4 OrderedGroup Node ..... 44

4.5 DecalGroup Node ..... 44

4.6 Switch Node ..... 45

4.7 SharedGroup Node ..... 47

5 Leaf Node Objects ..... 49

5.1 Leaf Node ..... 49

5.2 Shape3D Node ..... 51

5.3 BoundingLeaf Node ..... 53

5.4 Background Node ..... 54

5.5 Clip Node ..... 56

5.6 Fog Node ..... 57

5.6.1 ExponentialFog Node ..... 59

5.6.2 LinearFog Node ..... 60

5.7 Light Node ..... 62

5.7.1 AmbientLight Node ..... 63

5.7.2 DirectionalLight Node ..... 64

5.7.3 PointLight Node ..... 65

5.7.4 SpotLight Node ..... 66

5.8 Sound Node ..... 68

5.8.1 BackgroundSound Node ..... 72

5.8.2 PointSound Node ..... 73

5.8.3 ConeSound Node ..... 77

5.9 Soundscape Node ..... 84

5.10 ViewPlatform Node ..... 86

5.11 Behavior Node ..... 87

5.12 Morph Node ..... 87

5.13 Link Node ..... 89

6 Reusing Scene Graphs ..... 91

6.1 Sharing Subgraphs ..... 91

6.1.1 SharedGroup Node ..... 91

6.1.2 Link Leaf Node ..... 93

6.2 Cloning Subgraphs ..... 94

6.2.1 References to Node Component Objects ..... 95

6.2.2 References to Other Scene Graph Nodes ..... 96

6.2.3 Dangling References ..... 99

6.2.4 Subclassing Nodes ..... 99

6.2.5 NodeReferenceTable Object ..... 100

6.2.6 Example User Behavior Node ..... 101

7 Node Component Objects ..... 103

7.1 Node Component Objects: Attributes ..... 103

7.1.1 Appearance Object ..... 103

7.1.2 ColoringAttributes Object ..... 107

7.1.3 LineAttributes Object ..... 108

7.1.4 PointAttributes Object ..... 110

7.1.5 PolygonAttributes Object ..... 111

7.1.6 RenderingAttributes Object ..... 112

7.1.7 TextureAttributes Object ..... 114

7.1.8 TransparencyAttributes Object ..... 115

7.1.9 Material Object ..... 117

7.1.10 Texture Object ..... 119

7.1.11 Texture2D Object ..... 122

7.1.12 Texture3D Object ..... 123

7.1.13 TexCoordGeneration Object ..... 124

7.1.14 MediaContainer Object ..... 126

7.1.15 AuralAttributes Object ..... 128

7.1.16 ImageComponent Object ..... 133

7.1.17 ImageComponent2D Object ..... 135

7.1.18 ImageComponent3D Object ..... 136

7.1.19 DepthComponent Object ..... 137

7.1.20 DepthComponentFloat Object ..... 137

7.1.21 DepthComponentInt Object ..... 138

7.1.22 DepthComponentNative Object ..... 138

7.1.23 Bounds Object ..... 139

7.1.24 BoundingBox Object ..... 140

7.1.25 BoundingSphere Object ..... 141

7.1.26 BoundingPolytope Object ..... 143

7.1.27 Transform3D Object ..... 145

7.2 Node Component Objects: Geometry ..... 157

7.2.1 GeometryArray Object ..... 157

7.2.2 PointArray Object ..... 164

7.2.3 LineArray Object ..... 164

7.2.4 TriangleArray Object ..... 165

7.2.5 QuadArray Object ..... 165

7.2.6 GeometryStripArray Object ..... 165

7.2.7 LineStripArray Object ..... 166

7.2.8 TriangleStripArray Object ..... 166

7.2.9 TriangleFanArray Object ..... 167

7.2.10 IndexedGeometryArray Object ..... 167

7.2.11 IndexedPointArray Object ..... 170

7.2.12 IndexedLineArray Object ..... 170

7.2.13 IndexedTriangleArray Object ..... 171

7.2.14 IndexedQuadArray Object ..... 171

7.2.15 IndexedGeometryStripArray Object ..... 172

7.2.16 IndexedLineStripArray Object ..... 172

7.2.17 IndexedTriangleStripArray Object ..... 173

7.2.18 IndexedTriangleFanArray Object ..... 174

7.2.19 CompressedGeometry Object ..... 174

7.2.20 CompressedGeometryHeader Object ..... 175

7.2.21 Raster Object ..... 176

7.2.22 Font3D Object ..... 179

7.2.23 FontExtrusion Object ..... 180

7.2.24 Text3D Geometry Object ..... 181

7.3 Math Component Objects ..... 184

7.3.1 Tuple Objects ..... 184

7.3.2 Matrix Objects ..... 185

8 View Model ..... 187

8.1 Why a New Model? ..... 188

8.1.1 The Physical Environment Influences the View ..... 188

8.2 Separation of Physical and Virtual ..... 189

8.2.1 The Virtual World ..... 189

8.2.2 The Physical World ..... 189

8.3 The Objects That Define the View ..... 190

8.4 ViewPlatform: A Place in the Virtual World ..... 191

8.4.1 Moving Through the Virtual World ..... 192

8.4.2 Dropping In on a Favorite Place ..... 193

8.4.3 View Attach Policy ..... 194

8.4.4 Associating Geometry with a ViewPlatform ..... 195

8.5 Generating a View ..... 195

8.5.1 Composing Model and Viewing Transformations ..... 196

8.5.2 Multiple Locales ..... 197

8.6 A Minimal Environment ..... 198

8.7 The View Object ..... 198

8.7.1 Projection Policy ..... 200

8.7.2 Clip Policies ..... 202

8.7.3 Projection and Clip Parameters ..... 203

8.7.4 Frame Start Time and Duration ..... 204

8.7.5 Scene Antialiasing ..... 204

8.7.6 Depth Buffer ..... 204

8.8 The Screen3D Object ..... 205

8.9 The Canvas3D Object ..... 205

8.9.1 Window System,Provided Parameters ..... 206

8.9.2 Other Canvas3D Parameters ..... 206

8.10 The PhysicalBody Object ..... 207

8.11 The PhysicalEnvironment Object ..... 208

9 Behaviors and Interpolators ..... 209

9.1 Behavior Object ..... 209

9.1.1 Code Structure ..... 210

9.1.2 WakeupCondition Object ..... 211

9.1.3 WakeupCriterion Object ..... 211

9.1.4 Composing WakeupCriterion Objects ..... 212

9.2 Composing Behaviors ..... 212

9.3 Scheduling ..... 212

9.4 How Java3D Performs Execution Culling ..... 213

9.5 The Behavior API ..... 214

9.5.1 The Behavior Node ..... 214

9.5.2 WakeupCondition Object ..... 215

9.5.3 The WakeupCriterion Objects ..... 216

9.6 Interpolator Behaviors ..... 226

9.6.1 Mapping Time to Alpha ..... 226

9.6.2 Acceleration of Alpha ..... 230

9.6.3 The Alpha Class ..... 231

9.6.4 The Interpolator Base Class ..... 234

9.6.5 PositionInterpolator Object ..... 235

9.6.6 RotationInterpolator Object ..... 236

9.6.7 ColorInterpolator Object ..... 237

9.6.8 ScaleInterpolator Object ..... 238

9.6.9 SwitchValueInterpolator Object ..... 239

9.6.10 TransparencyInterpolator Object ..... 240

9.6.11 PositionPathInterpolator Object ..... 241

9.6.12 RotPosPathInterpolator Object ..... 243

9.6.13 RotPosScalePathInterpolator Object ..... 244

9.6.14 RotationPathInterpolator Object ..... 246

9.7 Level-of-Detail Behaviors ..... 247

9.7.1 LOD Object ..... 247

9.7.2 DistanceLOD Object ..... 248

9.8 Billboard Behavior ..... 249

10 Input Devices and Picking ..... 251

10.1 InputDevice Interface ..... 251

10.1.1 The Abstract Interface ..... 252

10.1.2 Instantiating and Registering a New Device ..... 253

10.2 Sensors ..... 253

10.2.1 Using and Assigning Sensors ..... 254

10.2.2 Behind the (Sensor) Scenes ..... 254

10.2.3 The Sensor Object ..... 254

10.2.4 The SensorRead Object ..... 257

10.3 Picking ..... 258

10.3.1 SceneGraphPath Object ..... 259

10.3.2 BranchGroup Node and Locale Node Pick Methods ..... 261

10.3.3 PickShape Object ..... 261

10.3.4 PickPoint Object ..... 261

10.3.5 PickRay Object ..... 262

10.3.6 PickSegment Object ..... 262

11 Audio Devices ..... 265

11.1 AudioDevice Interface ..... 265

11.1.1 Initialization ..... 266

11.1.2 Audio Playback ..... 267

11.1.3 Device-Driver-Specific Data ..... 268

11.2 Instantiating and Registering a New Device ..... 269

12 Execution and Rendering Model ..... 271

12.1 Three Major Rendering Modes ..... 271

12.1.1 Immediate Mode ..... 271

12.1.2 Retained Mode ..... 272

12.1.3 Compiled-retained Mode ..... 272

12.2 Instantiating the Render Loop ..... 273

12.2.1 An Application-level Perspective ..... 273

12.2.2 Retained and Compiled-retained Rendering Modes ..... 273

13 Immediate-Mode Rendering ..... 275

13.1 Two Styles of Immediate-Mode Rendering ..... 275

13.1.1 Pure Immediate-Mode Rendering ..... 275

13.1.2 Mixed-Mode Rendering ..... 277

13.2 Canvas3D Methods ..... 278

13.3 API for Immediate Mode ..... 280

13.3.1 GraphicsContext3D ..... 280

A Math Objects 285

A.1 Tuple Objects 285

A.1.1 Tuple2f Class ..... 285

A.1.2 Tuple3b Class ..... 291

A.1.3 Tuple3d Class ..... 293

A.1.4 Tuple3f Class ..... 299

A.1.5 Tuple4b Class ..... 305

A.1.6 Tuple4d Class ..... 307

A.1.7 Tuple4f Class ..... 314

A.1.8 AxisAngle4d Class ..... 322

A.1.9 AxisAngle4f Class ..... 323

A.1.10 GVector Class ..... 325

A.2 Matrix Objects ..... 329

A.2.1 Matrix3f Class ..... 330

A.2.2 Matrix3d Class ..... 336

A.2.3 Matrix4f Class ..... 342

A.2.4 Matrix4d Class ..... 350

A.2.5 GMatrix Class ..... 358

B 3D Geometry Compression ..... 365

B.1 Compression ..... 365

B.2 Decompression ..... 366

B.3 Appendix Organization ..... 366

B.4 Generalized Triangle Strip ..... 366

B.5 Generalized Triangle Mesh ..... 367

B.6 Position Representation and Quantization ..... 370

B.7 Color Representation and Quantization ..... 371

B.8 Normal Representation and Quantization ..... 372

B.8.1 Normals as Indices ..... 373

B.8.2 Normal Encoding Parameterization ..... 374

B.9 Modified Huffman Encoding ..... 376

B.10 Geometry Compression Commands ..... 377

B.11 Bit Layout of Geometry Decompression Commands ..... 379

B.12 Geometry Decompression Command Bit Details ..... 379

B.12.1 NOP ..... 379

B.12.2 setState ..... 379

B.12.3 setTable ..... 381

B.12.4 meshBufferReference ..... 382

B.12.5 Position Subcommand ..... 383

B.12.6 Color Subcommand ..... 383

B.12.7 Normal Subcommand ..... 384

B.12.8 vertex ..... 386

B.12.9 normal ..... 387

B.12.10 color ..... 387

B.13 Semantics of Geometry Decompression Commands ..... 387

B.13.1 Header and Body to Variable-Length Command ..... 388

B.13.2 Variable-Length Command to Command ..... 389

B.13.3 Delta Position to Position ..... 389

B.13.4 Delta Color to Color ..... 390

B.13.5 Encoded Delta Normal to Encoded Normal ..... 390

B.13.6 Encoded Normal to Rectilinear Normal ..... 390

B.14 Semantics of Vertices ..... 391

B.14.1 Command to Vertex ..... 391

B.14.2 Vertex to Intermediate Triangle ..... 392

B.14.3 Intermediate Triangle to Final Triangle ..... 393

B.15 Outline of Geometry Process ..... 394

B.15.1 Compressing Geometry Data ..... 394

B.15.2 Convert to Generalized Mesh Format ..... 394

B.15.3 Position ..... 394

B.15.4 Normals ..... 395

B.15.5 Colors ..... 396

B.15.6 Collect Delta Code Statistics ..... 396

B.15.7 Position Delta Code Statistics ..... 396

B.15.8 Color Delta Code Statistics ..... 396

B.15.9 Normal Delta Code Statistics ..... 396

B.15.10 Assign Huffman Tags ..... 397

B.15.11 Assemble the Pieces into a Bit Stream ..... 398

C View Model Details ..... 399

C.1 An Overview of the Java3D View Model ..... 399

C.2 Physical Environments and Their Effects ..... 400

C.2.1 A Head-mounted Example ..... 400

C.2.2 A Room-mounted Example ..... 400

C.2.3 Impact of Head Position and Orientation on the Camera ..... 400

C.3 The Coordinate Systems ..... 401

C.3.1 Room-mounted Coordinate Systems ..... 401

C.3.2 Head-mounted Coordinate Systems ..... 403

C.4 The ViewPlatform Object ..... 404

C.5 The View Object ..... 404

C.5.1 View Policy ..... 405

C.5.2 Screen Scale Policy ..... 406

C.5.3 Window Eyepoint Policy ..... 406

C.5.4 Monoscopic View Policy ..... 407

C.5.5 Sensors and Their Location in the Virtual World ..... 408

C.6 The Screen3D Object ..... 408

C.6.1 Screen3D Calibration Parameters ..... 410

C.6.2 Accessing and Changing Head Tracker Coordinates ..... 411

C.7 The Canvas3D Object ..... 411

C.7.1 Scene Antialiasing ..... 412

C.7.2 Accessing and Modifying an Eye's Image Plate Position ..... 412

C.7.3 Canvas Width and Height ..... 413

C.8 The PhysicalBody Object ..... 413

C.9 The PhysicalEnvironment Object ..... 415

C.10 Viewing in Head-tracked Environments ..... 417

C.10.1 A Room-mounted Display with Head Tracking ..... 418

C.10.2 A Head-mounted Display with Head Tracking ..... 418

C.11 Compatibility Mode ..... 418

C.11.1 Overview of the Camera-based View Model ..... 419

C.11.2 Using the Camera-based View Model ..... 420

D Exceptions ..... 425

D.1 BadTransformException ..... 425

D.2 CapabilityNotSetException ..... 426

D.3 DanglingReferenceException ..... 426

D.4 IllegalSharingException ..... 427

D.5 MultipleParentException ..... 427

D.6 RestrictedAccessException ..... 428

D.7 SceneGraphCycleException ..... 428

D.8 SingularMatrixException ..... 429

D.9 SoundException ..... 429

E Equations ..... 431

E.1 Fog Equations ..... 431

E.2 Lighting Equations ..... 432

E.3 Sound Equations ..... 434

E.3.1 Headphone Playback Equations ..... 434

E.3.2 Speaker Playback Equations ..... 442

E.4 Texture Mapping Equations ..... 443

E.4.1 Texture Lookup ..... 443

E.4.2 Texture Application ..... 446

F VRML Support ..... 449

F.1 VRML 1.0 ..... 449

F.1.1 Mapping VRML 1.0 Files onto Java3D Objects ..... 450

F.1.2 A VRML 1.0 Browsing Environment ..... 450

F.2 VRML 2.0 ..... 450

F.2.1 VRML Support Requires a VRML Runtime Environment ..... 451

F.2.2 An Approach ..... 451

F.2.3 A Browser ..... 452

F.2.4 Optimizing for Viewing versus Editing ..... 453