oCOSMO 3D User manual

Cosmo 3D

™

Programmer’s Guide

Document Number 007-3445-002

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.

The contents of this document may not be copied or duplicated in any form, in whole

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.

iii

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

viii

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

Contents

ix

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

x

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

Contents

xi

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

9. Viewing the Scene 97

Setting the Screen Display of the Scene 97

Using a Camera to View a Scene 98

csCamera 99

xii

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

Contents

xiii

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

xiv

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

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

Contents

xv

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

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

xvi

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

Contents

xvii

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

xix

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

xx

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

oCOSMO 3D User manual

Other documents