oCOSMO Cosmo 3D, Cosmo 3DTM User Manual

Cosmo 3D

™

Programmer’s Guide

Document Number 007-3445-002

CONTRIBUTORS

Written by George Eckel Illustrated by Dany Galgani and Martha Levine Production by Carlos Miqueo Engineering contributions by Brian Cabral, John Rohlf, Brad Grantham, Chris

Tanner, Rich Silba, Tonia Spyridi, Michael Jones, Trina Roy, Chris Walker

St. Peter’s Basilica image courtesy of ENEL SpA and InfoByte SpA. Disk Thrower

image courtesy of Xavier Berenguer, Animatica.

or in part, without the prior written permission of Silicon Graphics, Inc.

RESTRICTED RIGHTS LEGEND Use, duplication, or disclosure of the technical data contained in this document by

the Government is subject to restrictions as set forth in subdivision (c) (1) (ii) of the Rights in Technical Data and Computer Software clause at DFARS 52.227-7013 and/or in similar or successor clauses in the FAR, or in the DOD or NASA FAR Supplement. Unpublished rights reserved under the Copyright Laws of the United States. Contractor/manufacturer is Silicon Graphics, Inc., 2011 N. Shoreline Blvd., Mountain View, CA 94043-1389.

Silicon Graphics, the Silicon Graphics logo and OpenGL are registered trademarks, and Cosmo 3D, ImageVision, Inspector, OpenGL Optimizer, Open Inventor, and Performer are trademarks, of Silicon Graphics, Inc. Java is a registered trademark of Sun Microsystems, Inc.

Cosmo 3D™ Programmer’s Guide Document Number 007-3445-002

Contents at a Glance

List of Figures xxi

List of Tables xxiii

About This Guide xxv

What This Guide Contains xxv

Related Reading xxv

Who Should Read This Guide xxv

What You Should Know Before Reading This Guide xxv

Suggestions for Further Reading xxv

Style Conventions xxvi

1. Getting Started with Cosmo 3D 1

Understanding a Cosmo 3D Scene Graph 2

Scene Graph Base Classes 2

The csObject Class 3

Reference Counting 3

Runtime Typing 4

The csContainer Class 5

The csField Class 5

Field Access 5

Single-Item and Multi-Item Fields 6

The csNode Class 6

Scene Graph Construction Classes 7

The csGroup Class 8

The csTransform Class 9

The csShape Class 11

The csAppearance Class 11

The csGeometry Class 11

vii

Contents

Classes That Determine How Things Are Drawn 12

csContext 12

The csEnvironment Classes 12

Classes defining Geometric Objects 13

Steps for Creating and Displaying a Simple Scene Graph 13

2. Creating Geometries 15

Geometry Terminology 16

Using Large Geometries 16

Creating csGeoSet Objects 17

csGeoSet Fields 19

Setting the Number of Primitives 19

csGeoSet Attributes 20

Attribute Bindings 20

Setting Attribute Bindings 21

Setting Attributes 22

Indexing Attributes 23

When to Index Attributes 24

Specifying Attributes 26

Using More Specific Attribute Arrays 26

Indexing Attributes 28

Setting Attributes Example 28

Editing Attribute Arrays 29

Cosmo 3D-Derived csGeoSet Objects 30

Using csPointSet 30

Using csLineSet 31

Using csIndexedLineSet 31

Using csLineStripSet 31

Using csTriSet 31

Using csTriFanSet 32

Using csTriStripSet 32

Using csPolySet 33

Using csQuadSet 33

Using csIndexedFaceSet 33

viii

3. Specifying the Appearance of Geometries 35

csContext Overview 35

State Machine 36

Inheritance Mask 36

Accessing States 37

What Modifies the Graphics State? 38

Traversal Order 38

csContext in Multi-threaded Programs 38

Overriding Appearances and Geometry Properties with csContext 39

Making the Screen One Color 39

Changing the Context 39

Using csAppearance 40

Inheriting Appearance Values 40

Setting Appearance Fields Locally 40

Lazy Updating of Appearance Values 41

Applying Textures to Geometries 42

Texture Map Coordinates 42

Applying a Texture 43

Specifying a Texture Image 44

Texture Mode Settings 44

Texture Environment Settings 46

Color Components 47

Specifying Texture Coordinates 48

Using the Default 48

Using the Texture Coordinate Function 48

Setting the csTexGen Mode 50

Enabling Texture Generation 50

Material Settings 51

Material Example 52

Filling Geometries 52

Shade Model Settings 53

Transparency Settings 53

Producing Transparency Without Blending 53

Contents

4. Scene Graph Nodes 55

What Is a Node 56

Node Types 56

Leaf Nodes 57

csShape 57

Group Nodes 58

Group Node Types 58

Using csSwitch to Switch Between Nodes 59

Using csBillboard 60

Setting the Values in Scene Graph Nodes 61

Using set() and get() Methods to Set and Get Single-Value Fields 61

Using Tokens to Set and Get Single-Value Fields 62

Using set() and get() Methods to Set and Get Multiple-Value Fields 62

Using Tokens to Set and Get Multiple-Value Fields 63

5. Building a Scene Graph 65

Creating Scene Graphs 66

Root Node 66

Applying Actions to Multiple Root Nodes 67

Creating A Sample Scene Graph 68

Diagramming Scene Graphs 69

Scene Graph Diagrams At A Glance 69

Altering Scene Graphs 73

Loading a VRML Scene Graph 74

Saving Scene Graphs 75

Troubleshooting Scene Graph Construction 75

6. Placing Shapes in a Scene 77

Creating a Sense of Depth 77

Overriding the Default Order of Layering Shapes 78

Transforming Shapes to New Locations, Sizes, and Orientations 79

Placing Transform Nodes 79

Setting the Transformation 80

Ordering Transformations 81

Placing Geometries in World Space 82

Cosmo 3D Matrices 82

7. Traversing the Scene Graph 83

Scene Graph Actions 83

Action Types 84

csAction 84

Rendering the Scene 85

Playing Sound Files 86

The Order In Which Actions Are Passed Between Nodes 86

Top-Down Traversals 86

8. Lighting and Fog 89

Using Lights in Scenes 89

csLight 90

csDirectionalLight 90

csSpotLight 91

csPointLight 91

Limiting the Scope of Lights 92

The Scope of the Light Array 92

csEnvironment Methods 92

Using Fog in Scenes 93

Uses of Fog in Cosmo 3D Applications 93

How to Use Fog in Cosmo 3D Applications 94

Enabling Fog 94

How to Use Fog 95

Contents

9. Viewing the Scene 97

Setting the Screen Display of the Scene 97

Using a Camera to View a Scene 98

csCamera 99

Contents

csOrthoCamera 101

csPerspCamera 101

Setting the Frustum 102

Setting the Clip Planes 103

Setting the Fields of View 103

Offsetting the Fields of View 103

csFrustumCamera 105

10. Scene Graph Engines 107

Engines 107

Input and Output Fields 108

Connecting Engines to Other Nodes 108

Connecting Engines to Other Engines 108

Engine Types 109

Engines that Interpolate Values 110

Interpolator Engine Terminology 111

csSpline 112

Keys and Key Values 113

csSpline Fields 113

csColorInterpolator 114

csCoordinateInterpolator 114

csNormalInterpolator 114

csOrientationInterpolator 115

csPositionInterpolator 116

csScalarInterpolator 116

csSelectorEng3F and csSelectorEng4F 117

Engines That Change Shapes 117

csMorphEng 117

csMorphEng Fields 118

csMorphEng3f and csMorphEng4f 118

csTransformEng 119

xii

11. Sensors 121

csTimeSensor 122

Enabling csTimeSensor 122

Updating csTimeSensor 123

Updating with csWindow 123

Setting the Start and Stop Times 123

isActive 124

Setting Cycle Duration 124

Continuing Timer Events 125

Cycle Time Event 125

Fraction Changed Event 125

csSphereSensor 126

Virtual Sphere 126

Offsetting the Rotation 126

csSphereSensor Events 127

Updating csSphereSensor 128

Setting Up csSphereSensor 128

Scope of csSphereSensor 128

Rotating Geometry Using csSphereSensor 129

csPlaneSensor 130

Setting Up csPlaneSensor 130

Scope of csPlaneSensor 131

csPlaneSensor Events 131

Updating csPlaneSensor 132

Limiting Translations 132

Unclamped Translations 132

Local or World Translations 133

csPlaneSensor Offsets 133

Contents

xiii

Contents

csTouchSensor 134

Associating csTouchSensor and Geometry 134

Scope of csTouchSensor 135

csTouchSensor Output 135

isOver Event 135

Hit Events 136

touchTime Events 136

12. User Interface Mechanisms 137

Creating a csWindow 137

Manipulating the Window Stack 138

Handling User Input 139

Using Callback Functions 139

Querying Devices 140

Selecting Screen Objects 140

Using csIsectAction 140

Using Pick() 141

Storing Selected Screen Objects 142

Creating Your Own Window 143

Sample Window Code 143

xiv

13. Multiprocessing 145

Implementing Multiprocessing 146

Creating Threads 146

Starting Threads 147

Thread Parameters 148

Thread Blocking 148

Cleaning the csContext Fields 150

Multithreaded Example 150

14. Optimizing Rendering 151

Face Culling 152

Back Patch Culling 152

Back Patch Culling Advantage 153

When to Use Back Patch Culling 154

Method of Calculation 154

Updating the View Vector 155

Normals 155

Choosing the Type of Normal 156

Using Back Patch Culling 157

Enabling Back Patch Culling 157

Building Back Patch Culling Data for a csGeoSet 158

Updating Back Patch Culling Data 158

Back Patch Culling Code 159

Culling the View Frustum 160

Level of Detail Reduced for Performance 160

Choosing a Child Node Based on Range 161

Transitioning Between Levels of Detail 162

Performance Programming Techniques 163

Minimize Use of csAppearance Fields 163

Minimize Use of csAppearance Modes 163

Indexing csGeoSet Attributes 164

Setting the Transformation Matrix Directly 164

Compiling Part of a Scene Graph 164

Contents

15. Adding Sounds To Virtual Worlds 167

Overview 168

csSound Fields 169

Choosing Sound Samples to Play 169

Sound Priority 170

Playing the Sound File 170

Locating and Directing the Sound 170

Reverse Direction Sound 172

How to Play a Sound File 173

Contents

Specifying Audio Files 174

Manipulating the Audio Samples Directly 176

Example Setting a csAudioSamples Node 176

Playing Sound in Immediate Mode 177

csSoundPlayer Methods 177

A. Cosmo Basic Types 179

Array Storage Class Types 180

Data Class 180

Array Classes 181

Array Methods 181

Returning Array Data 183

Vector Classes 183

Vector Math 184

Vector Methods 184

csVec3s 186

csVec4ub Methods 186

Transforming csVec3f Vectors 186

Bounding Volumes 187

Field Classes 188

csField 189

csFieldInfo 189

csMField 189

csAtomField 190

csArrayField 190

Other Math Classes 191

csSeg 191

csPlane 192

csFrustum 192

xvi

B. Cosmo 3D Sample Application 193

Cube.cxx Explained 195

Understanding the Different Parts of Cube.cxx 202

Scene Graph for Cube.cxx 203

Relating Local Space to World Space 204

Creating the User Interface 206

Rendering World Space 206

Summary 207

C. Cosmo 3D Class Hierarchy 209

Index 215

Contents

xvii

List of Figures

Figure 1-1 Cube Scene Graph 8 Figure 1-2 Two Transformations into World Space 10 Figure 2-1 Primitives in a csGeoSet 18 Figure 2-2 Sequential Specification of Attributes Per Primitive 23 Figure 2-3 Indexed Attributes 24 Figure 2-4 Deciding Whether to Index Attributes 25 Figure 2-5 Stride and Offset Values 27 Figure 2-6 TriFanSet 32 Figure 2-7 Triangle Strip 32 Figure 3-1 Inheritance Mask 37 Figure 3-2 Applying a Texture to a Geometry 42 Figure 3-3 Texture Coordinates 43 Figure 3-4 Non-Perspective and Perspective Modes 45 Figure 3-5 Texture Coordinate Function 48 Figure 3-6 Repeated Texture on a Geometry 49 Figure 4-1 A Simple Grouping 58 Figure 4-2 Setting Single and Multiple-Value Variables 61 Figure 5-1 Scene Graph 65 Figure 5-2 Multiple Root Nodes 67 Figure 5-3 Simple Scene Graph 69 Figure 5-4 Two Sets of Data Rendered Differently 70 Figure 5-5 Torso Subgraph 71 Figure 5-6 Showing the Same Geometry in Two Locations 72 Figure 6-1 Placement of csTransform Nodes 79 Figure 6-2 Scaling in Different Orientations 81 Figure 6-3 Order of Transformations 81 Figure 7-1 The Flow of an Action Through A Scene Graph 87

xix

List of Figures

Figure 9-1 Viewport 98 Figure 9-2 Aspect Ratio 99 Figure 9-3 Changing the Window Without Changing the Image’s Aspect 100 Figure 9-4 Perspective Explained 102 Figure 9-5 Horizontal and Vertical Fields of View Offsets 104 Figure 10-1 Keys and Key Values 110 Figure 10-2 Engine Terminology 111 Figure 10-3 Spline 112 Figure 11-1 Rotation and trackPoint Representations 127 Figure 11-2 Placing csSphereSensor in a Scene Graph 129 Figure 11-3 Placing csPlaneSensor in a Scene Graph 131 Figure 11-4 Placing csTouchSensor in a Scene Graph 134 Figure 12-1 Ray Pick Action 141 Figure 12-2 Creating Your Own Window 143 Figure 13-1 Multiprocessing 145 Figure 13-2 Blocking Action of Multiple Threads 149 Figure 14-1 Before and After Back Patch Culling 153 Figure 14-2 Viewing Angle 154 Figure 14-3 Face and Primitive Normals 155 Figure 14-4 Direction of Normals 156 Figure 14-5 csLOD Ranges 162 Figure 14-6 Arranging Scene Graph Nodes 165 Figure 15-1 Sound Classes 168 Figure 15-2 Sound Direction 171 Figure 15-3 Forward and Reverse Sound Propagation 172 Figure A-1 Bounding Sphere 187 Figure B-1 Cube Application 194 Figure B-2 Cube Scene Graph 203 Figure B-3 Two Transformations Into World Space 205

List of Tables

Table 2-1 Geometry Terminology 16 Table 2-2 Fields in a csGeoSet 19 Table 2-3 Attribute Bindings 21 Table 4-1 Examples of Fields in Nodes 56 Table 8-1 Fields in csFog 94 Table 15-1 csAudioClip Fields 173 Table 15-2 Fields of csSoundSamples 175

xxi

About This Guide

Cosmo 3D is a new toolkit that brings 3D graphics programming to desktop applications. Cosmo 3D is a scene graph API; its concepts are new, but similar to concepts developed in Open Inventor, Performer, and OpenGL.

This guide shows you how to develop Cosmo 3D applications. Included are descriptions of Cosmo 3D applications that you can run on your workstation, as well as code examples that you can use as a guide when developing your Cosmo 3D applications.

This guide presents the developer’s view of the Cosmo 3D’s C++ library with C++ examples.

What This Guide Contains

This guide presents information about Cosmo 3D in a task-oriented manner: the topics in this guide are arranged to coincide with the order in which you need to refer to them while writing a Cosmo 3D application. To illustrate the use of Cosmo 3D, code examples are sprinkled throughout the guide. Additional sample source code is provided in the /usr/share/optimizer/cosmo1.1/cosmo/test/C++ directory.

Brief descriptions of the chapters in this guide follow:

• Chapter 1, “Getting Started with Cosmo 3D,” provides an overview of Cosmo 3D, introduces some of its most basic classes, and lists the steps involved in creating a typical application.

• Chapter 2, “Creating Geometries,” discusses large, ready-made geometries, such as csSphere and csCube objects, and explains how to use the csGeoSet-derived classes provided by Cosmo 3D and how to create your own csGeoSet-derived classes.

xxiii

About This Guide

• Chapter 3, “Specifying the Appearance of Geometries,” describes the appearance ﬁelds in csContext and csAppearance.

• Chapter 4, “Scene Graph Nodes,” describes nodes and node types.

• Chapter 5, “Building a Scene Graph,” describes how to build and edit a scene

graph.

• Chapter 6, “Placing Shapes in a Scene,” describes how to place shapes in scenes.

• Chapter 7, “Traversing the Scene Graph,” describes how an action traverses a scene

graph and a description of the actions available in Cosmo 3D.

• Chapter 8, “Lighting and Fog,” describes how to use lights, change the shadow modeling, and change the screen to one color. It also discusses fog, a new feature in Cosmo 3D 1.1.

• Chapter 9, “Viewing the Scene,” describes how to set up the viewport and how to use cameras to view a scene.

• Chapter 10, “Scene Graph Engines,” describes csEngine and the multiple subclasses derived from it.

• Chapter 11, “Sensors,” explains how to implement sensors. Sensors are used to detect time passing and ointer device events.

xxiv

• Chapter 12, “User Interface Mechanisms,” discusses how to implement user interaction using X window code, csWindow, and selection mechanisms.

• Chapter 13, “Multiprocessing,” describes how to implement multiprocessing.

• Chapter 14, “Optimizing Rendering,” describes the Cosmo 3D nodes and programming techniques that can help optimize your application’s performance.

• Chapter 15, “Adding Sounds To Virtual Worlds,” describes how to set and play

sound using Cosmo 3D.

• Appendix A, “Cosmo Basic Types,” discusses all of the basic types that are used in other Cosmo 3D classes.

• Appendix B, “Cosmo 3D Sample Application,” lists a complete sample application and explains its components.

• Appendix C, “Cosmo 3D Class Hierarchy,” shows the class hierarcy in Cosmo 3D.

These chapters and appendices are followed by an index.

Related Reading

Reference pages for Cosmo 3D are obtained by pointing your web browser at:

• For IRIX: /usr/share/Optimizer/doc/developer

• For Windows: <inst_dir>/doc/developer

Where inst_dir is the directory where Optimizer was installed. The default installation location is <system_drive>:/Progral Files/Silicon Graphics/Optimizer.

Who Should Read This Guide

This guide is written for developers of OpenGL Optimizer applications. Developers use Cosmo 3D scene graph nodes and actions to develop OpenGL Optimizer applications.

What You Should Know Before Reading This Guide

About This Guide

This guide is written with the assumption that the reader is experienced with C++.

Suggestions for Further Reading

For information on Open Inventor, see the following:

• Wernecke, Josie, The Inventor Mentor. Reading, Mass.:Addison Wesley 1994

• Wernecke, Josie, The Inventor Toolmaker. Reading, Mass.:Addison Wesley 1994

• Open Inventor Architecture Group, Open Inventor C++ Reference Manual. Reading,

Mass.:Addison Wesley 1994

• OpenGL Architecture Review Board, M. Woo, J. Neider, and Tom Davis, OpenGL

Programming Guide, Second Edition, 1997. (Also known as “the Red book.”)

For information on OpenGL Optimizer; see the following SGI manual:

OpenGL Optimizer Programmer’s Guide: An Open API for Large-Model Visualization

(document number 007-2852-002).

xxv

About This Guide

Style Conventions

These style conventions are used in this guide:

• Bold—Functions, class names, node names, data members, and data types

• Italics—Variables, ﬁlenames, spatial dimensions, and commands

• Regular—Program names and enumerated types

Code examples are set off from the text in a ﬁxed-space font.

xxvi

Chapter 1

1. Getting Started with Cosmo 3D

Cosmo 3D is a scene graph API that brings 3D graphics programming to desktop applications. Cosmo 3D speeds up and facilitates the process of creating complex graphics applications. It allows applications to use a higher-level interface than the lower-level OpenGL language that it is based on. Developers interact with C++ objects that are arranged in an object hierarchy.

With its scene graph architecture and features such as culling, level of detail (LOD), 2D texture mapping, and audio, Cosmo 3D enables you to develop complex graphic applications, for example, professional character animations and gaming applications.

After creating a scene graph using Cosmo 3D objects, developers can use the OpenGL Optimizer API to improve performance. See the manual OpenGL Optimizer Programmer’s Guide: An Open API for Large-Model Visualization for more information.

This chapter gives an overview of the base classes of a Cosmo 3D scene graph. Understanding how each class contributes to the scene graph is essential for making optimal use of the API. These are the sections in this chapter:

•“Understanding a Cosmo 3D Scene Graph” on page 2.

•“Scene Graph Base Classes” on page 2.

•“Scene Graph Construction Classes” on page 7.

•“Classes That Determine How Things Are Drawn” on page 12.

•“Classes deﬁning Geometric Objects” on page 13.

•“Steps for Creating and Displaying a Simple Scene Graph” on page 13.

Chapter 1: Getting Started with Cosmo 3D

Understanding a Cosmo 3D Scene Graph

A scene graph is a directed acyclical graph of nodes that embodies the semantics of what is to be drawn, but not how it is to be drawn. Developers interacting with a scene graph are interested in achieving a result, usually seeing a model on screen and manipulating it. They leave it up to Cosmo 3D to achieve this result in the most efﬁcient way.

A Cosmo 3D scene graph consists of objects that inherit appropriate methods and ﬁelds from the Cosmo 3D classes. Conceptually, there are four kinds of classes:

• Base classes—csObject, csField, csContainer, and csNode. These classes are never instantiated directly. Instead, applications create subclasses that inherit certain functionality from the base classes. Base classes are discussed in this chapter.

• Scene graph construction classes—csGroup, csShape, csGeometry, and csAppearance determine appearance in a general way.

• Speciﬁc appearance classes—csContext, csDrawTraversal, csEnvironment and some of their subclasses determine how things are drawn, for example, whether lights or fog are applied.

• Geometry classes, such as csSphere or csCylinder, are the building blocks of the model itself.

This manual starts by discussing the different kinds of classes. It then brieﬂy lists the steps required to create a simple sample program. The sample program itself is listed in Appendix B, “Cosmo 3D Sample Application.”

Scene Graph Base Classes

This section discusses the following abstract, base classes that provide the functionality that is necessary to implement a scene graph:

•“The csObject Class”

•“The csContainer Class”

•“The csField Class”

•“The csNode Class”

Scene Graph Base Classes

The csObject Class

The csObject class is the base class for all objects in a scene; where an object is an entity that you can place in the scene graph. A csObject provides reference counting and runtime typing for all its children.

Reference Counting

Many kinds of data objects in Cosmo 3D can be placed in a hierarchical scene graph. Using instancing, an object can be referenced multiple times. Scene graphs can become quite complex, which can cause problems if you’re not careful. Deleting objects can be a particularly dangerous operation, for example, if you delete an object that another object still references.

Within each csObject is a counter that keeps track of the number of objects referencing a particular instance. Reference counting provides a bookkeeping mechanism that makes object deletion safe: an object should never be deleted if its reference count is greater than zero. In general, you should only unreference an object in case it is referenced by another object.

It is just as important, however, not to unreference an object that has not been referenced. Because the reference count is an unsigned integer, unreferencing an object that has not been referenced decrements the reference count from 0 to a large positive number and it will never be deleted.

Each csObject is created with a reference count of 0. It is important to reference an object when it is created to make sure that someone else does not delete it when they unreference it.

When object A is attached to object B, the reference count of A is incremented. Additionally, if A replaces a previously referenced object C, the reference count of C is decremented.

Chapter 1: Getting Started with Cosmo 3D

Example 1-1 demonstrates how reference counts are incremented and decremented.

Example 1-1 Objects and Reference Counts

csAppearance *appearanceA, *appearanceC; csGeoSet *gset; csShape *shape;

shape->setGeometry(0, gset); /* Attach appearanceC to gset. Reference count of appearanceC * is incremented. */ shape->setAppearance(appearanceC);

/* Attach appearanceA to gset, replacing appearanceC. Reference * count of appearanceC is decremented and that of appearanceA * is incremented. */ shape->setAppearance(appearanceA);

When the reference count of an existing csObject becomes 0, the object is assumed not to be referenced by any other object and is deleted. An object that has nothing above itself in the scene hierarchy is removed because it is no longer part of the scene graph.

This automatic reference counting is usually all you ever need to use. However, the routines csObject::Ref(), csObject::Unref(), and csObject::GetRefCount() allow you to increment, decrement, and retrieve the reference count of a csObject should you wish to do so.

Runtime Typing

Each csObject knows what type it is. Applications can ﬁnd out the class object of an instance by querying the object with getClassType(), as in the following example:

// csContainer *ctr

if(ctr->getType() == csMaterial::getClassType())

printf(“It’s a csMaterial!\n”);

else

printf(“It’s not a csMaterial!\n”);

You need to know the runtime type of an object so you can invoke the right code to manipulate an object.

For checking the derivation of a type, use csObject::isOfType().

+ 231 hidden pages

oCOSMO Cosmo 3D, Cosmo 3DTM User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual