The Inventor Mentor Programming Object-Oriented 3D Graphics with Open Inventor, Release 2

Josie Wernecke Open Inventor Architecture Group

T T ADDISON-WESLEY

Boston • San Francisco • New York • Toronto • Montreal London • Munich • Paris • Madrid

Capetown • Sydney • Tokyo • Singapore • Mexico City

Contents

About This Book v

What This Book Contains v How to Use This Book vii What You Should Know Before Reading This Book viii Conventions Used in This Book viii

Tips ix Advanced Information ix

Key to Scene Graph Diagrams ix Suggestions for Further Reading ix

Acknowledgments xi

Part I: Getting Started

1. Overview 3

What Is Open Inventor? 4 Objects, not Drawings 5

Using Database Objects in a Variety of Ways 6 Animation 6

How Does Open Inventor Relate to OpenGL? 9 The Inventor Toolkit 11

The Scene Database 12 Node Kits 13 Manipulators 14

xiii

Inventor Component Library 15 Inventor Class Tree 16 Extending the Toolkit 17

2. An Inventor Sampler 21

"Hello, Cone" 22 A Red Cone 22 Using Engines to Make the Cone Spin 24 Adding a Trackball Manipulator 26 Adding the Examiner Viewer 28

Naming Conventions 29 Scene Basic Types 30

Methods 31 Types versus Fields 32

Coordinate Systems in Inventor 32 Include Files 32

Part II: Building a Scene Graph

3. Nodes and Groups 35

The Scene Database 36 Scene Graphs 37 Types of Nodes 38

Creating Nodes 38 What's in a Node? 38 What Happens When You Apply an Action to a Node? 39 Shape Nodes 40 Property Nodes 41 Groups 44

Creating Groups 44 Ordering of Children 45 Why Is Order Important? 46 Separators 49 Other Subclasses of SoGroup 51

xiv

Shared Instancing of Nodes 54 Paths 58

Where Do Paths Come From? 59 What Are Paths Used For? 60

Fields within a Node 60 Why Fields? 61 Single- versus Multiple-Value Fields 61 Single-Value Fields: Setting and Getting Values 62 Multiple-Value Fields: Setting and Getting Values 64 Ignore Flag 67

Override Flag 67 References and Deletion 68

Reference Counting 69 How Nodes Are Deleted .....70 Nodes with Zero References 72 Summary of References and Deletion 74

Node Types 74 Naming Nodes 75

4. Cameras and Lights 79

Using Lights and Cameras 80 Cameras 80

SoCamera 81 Subclasses of SoCamera 83 SoPerspectiveCamera 83 SoOrthographicCamera 84 Mapping the Camera Aspect Ratio to the Viewport 85 Viewing a Scene with Different Cameras 86

Lights 90 SoLight 91 Subclasses of SoLight 91 SoPointLight 92 SoDirectionalLight 92 SoSpotLight 94 Using Multiple Lights 94

xv

5. Shapes, Properties, and Binding 99

Simple Shapes 100 Complex Shapes 100

Face Set 102 Indexed Face Set 105 Triangle Strip Set 109 Quad Mesh 112

Property Nodes 115 Material Node 117 Draw-Style Node 118 Light-Model Node 120 Environment Node 121 Shape-Hints Node 122 Complexity Node 124 Units ^ode 125

Binding Nodes 126 Indexed Binding 128 Binding per Vertex 130 Nuances 130 Using a Material-Binding Node 130 Normal Binding 132 Generating Normals Automatically 132

Transformations 133 SoTransform Node 133 Order of Transformations 134

Part III: More About Nodes

6. Text 139

Two-Dimensional Text 140 Font Type and Size 141 Using 2D Text 141

Three-Dimensional Text 144 Parts of 3D Text 146 Profile 146 Simple Use of 3D Text 147 Advanced Use of 3D Text 150

xvi

7. Textures 155

Creating Textured Objects 156 What Is a Texture Map? 157 Nodes Used for Texture Mapping 157 Using the Defaults 158

Key Concepts 160 Wrapping a Texture around an Object 160 How a Texture Affects the Underlying Colors 160 Storing an Image 162

SoTexture2 Node 165 Fields of an SoTexture2 Node 165 Transforming a Texture Map 166

Mapping the Texture onto the Object 168 Using the Default Texture Mapping 168 Specifying Texture Coordinates Explicitly 175 Using a Texture-Coordinate Function 177

8. Curves and Surfaces 181

Overview 182 Classes Used with NURBS Shapes 182 Parametric Curves 183

Key Concepts 184 Control Points and Order 185 Continuity of a Curve 186 Basis Function 187 Summary of NURBS Relationships 192 Rational Curves 193 N-U-R-B-S Spells NURBS 194

Examples of NURBS Curves 194 B-Spline Curve 194 Uniform B-Spline Curve Passing through Endpoints 197

xvii

NURBS Surfaces 199 Bezier Surface 199 Trimming NURBS Surfaces 202

Suggestions for Further Reading 207

Part IV: Using a Scene Graph

9. Applying Actions 211

Inventor Actions 212 General Model 213 Applying an Action 214 Rendering 215

Setting the Transparency Quality 216 Antialiasing 218 Printing and Off-screen Rendering 219 Caching ; 224 Culling Part of the Scene 227

Calculating a Bounding Box 229 Create an Instance of the Action 229 Apply the Action 229 Obtain Results 229

Accumulating a Transformation Matrix 230 Create an Instance of the Action 231 Apply the Action 231 Obtain Results 231

Writing to a File 233 Searching for a Node 234

Specify the Search Criteria 234 Apply the Action 235 Obtain the Results 235

Picking 236 Picking Style 237 Create an Instance of the Action 237 Set Parameters 237 Apply the Action 239 Obtain Results 239 Using the Pick Action 244

Calling Back to the Application 245 Create an Instance of the Action 246 Register Callback Functions 246 Apply the Action 248 Using a Callback for Generated Primitives 248

10. Handling Events and Selection 251

Overview 252 General Programming Model for Event Handling 252

Using the X Window System 253 Render Area 254 Inventor Events (SoEvent) 255 Scene Manager 256

Inventor Event Handling 256 How Nodes Handle Events: SoHandleEventAction 257

SoNode 258 SoGroup 258 SoManipulator 258 SoSelection 260 Finding the Event Handler 262

Using Event Callback Nodes 264 Sending Events Directly to the Application 266 Selection 268

Managing the Selection List 268 Highlighting Selected Objects 272 Callback Functions for Selection Changes 273

11. File Format 283

Writing a Scene Graph 284 Reading a File into the Database 284 File Format Syntax 285

File Header 286 Writing a Node 286 Writing Values within a Field 287 Ignore Flag 290 Field Connections 290

xix

Global Fields 291 Writing an Engine 292 Writing a Path 292 Defining and Using Shared Instances of Nodes 297 Writing a Node Kit 298 Including Other Files 301 ASCII and Binary Versions 302

Reading in Extender Nodes and Engines 302 File Format for Unknown Nodes and Engines 303 Alternate Representation 303

Reading from a String 304

Part V: Application Tools

12. Sensors 309

Introduction to Sensors 310 Sensor Queues 311 Key Terms 311

Data Sensors 311 General Sequence for Data Sensors 312 Callback Function 313 Priorities 313 Triggering a Data Sensor 314 Using a Field Sensor 314 Using the Trigger Node and Field 316

Other Delay-Queue Sensors 318 General Sequence for One-Shot and Idle Sensors 318 SoOneShotSensor 318 SoIdleSensor 320

Timer-Queue Sensors 320 General Sequence for Timer-Queue Sensors 320 SoAlarmSensor 321 SoTimerSensor 322 Processing the Sensor Queues 323

xx

13. Engines 327

Introduction to Engines 328 General Uses of Engines 329 Types of Engines 332 Making Field Connections 334

Multiple Connections 335 Field Conversion 335

Reference Counting 336 Disabling a Connection 336 Updating Values 337 Global Fields 337 Animation Engines 340

Elapsed-Time Engine 340 One-Shot Engine .342 Time-Counter Engine 342

Gate Engine 344 Arithmetic Engines 347

Boolean Engine 347 Calculator Engine 350 Using the Calculator to Constrain Object Behavior 352

Nodes Used for Animation 354 Rotor Node 355 Blinker Node 357

14. Node Kits 359

Why Node Kits? 360 Hidden Children and SoNodeKitPath 361 Node-Kit Classes 362 Node-Kit Catalog 363 Parts Created by Default 367 Selecting Parts and Setting Values 368 Other Methods: getPart() and setPart() 369

The getPart() Method 369 The setPart() Method 370

xxi

Macros for Getting Parts 371 The SO_GET_PART() Macro 371 The SO_CHECK_PART() Macro 371

Specifying Part Names 372 Creating Paths to Parts 374 Using List Parts 377 Using Separator Kits to Create Motion Hierarchies 377 Examples 378

Simple Use of Node Kits 379 Using Node Kits with Editors 381 Creating a Motion Hierarchy 384

15. Draggers and Manipulators 389

What Is a Dragger? 390 Types of Draggers 390 Manipulators versus Draggers 393 Simple Draggers 395

Field Connections 395 Callback Functions 397 Using Multiple Draggers 398

Manipulators 401 Replacing a Node with a Manipulator 401 Using the replaceNode() Method 403

Customizing a Dragger 411 Parts of a Dragger 411 Changing a Part after Building the Dragger 413 Changing the Default Geometry for a Part 415

Part VI: Using the Toolkit with Other Libraries

16. Inventor Component Library 421

Introduction to Components 422 Xt Utility Functions 422

xxii

Render Area 424 Methods 424 Xt Devices 425 Using the Overlay Planes 425

Xt Components 428 General Model 429

Construct the Component 429 Show and Hide the Component 430 Passing Data to the Application 431

Viewers 438 Constructing a Viewer 439 Specifying the Scene Graph for the Viewer 440 Methods for SoXtViewer 444 Methods for SoXtFullViewer ,445

Using the 3D Clipboard 447 Creating an Instance of SoXtClipboard 447 Copying Data onto the Clipboard 448 Pasting Data from the Clipboard 448

17. Using Inventor with OpenGL 451

Introduction 452 OpenGL State Variables and Inventor 453 Color-Index Mode 458 Using an SoCallback Node 461

Caching 461 Using a Callback Node 462

Applying a Render Action Inside a GLX Window 466

A. An Introduction to Object-Oriented Programming for C Programmers 471

What Is Object-Oriented Programming? 472 Data Abstraction 472 Inheritance 473 Implementing Data Abstraction and Inheritance: Classes 473 Class Hierarchies 474

An Example of a Class: Sphere 475 An Example of Inheritance: HollowSphere 476

Suggested Reading 478

B. An Introduction to the C API 479

Naming C Functions 480 Abbreviating C Function Names 481 Creating and Deleting Objects from C 484 Overloaded C++ Methods 485 Calling Functions 485 C Classes and Manual Pages 485 A Sample Open Inventor Program in C 486

C. Error Handling 487

Runtime Type-Checking 488 Posting an Error 488 Handling an Error 488 Debugging 489

Index 491

xxiv