IRIS Performer™ Getting Started Guide Document Number 007-3560-001 CONTRIBUTORS Written by George Eckel Illustrated by Dany Galgani Production by Linda Rae Sande Engineering contributions by the Performer Team, including Sharon Clay, Tom McReynolds, Don Hatch, Jenny Zhao, Remi Arnaud,Yair Kurzion, and Rob Mace. St Peter’s Basilica image courtesy of ENEL SpA and InfoByte SpA. Disk Thrower image courtesy of Xavier Berenguer, Animatica. © 1997, Silicon Graphics, Inc.— All Rights Reserved 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, Geometry Engine, Indigo, and OpenGL are registered trademarks and Geometry Pipeline, GL, Graphics Library, Indigo Magic, InfiniteReality, Optimizer, Inventor, IRIS GL, IRIS Graphics Library, IRIS InSight, IRIS Inventor, IRIS Performer, IRIX, O2, and Onyx2 are trademarks of Silicon Graphics, Inc. Designer’s Workbench is a trademark of Coryphaeus. DRaW Computing Associates is a registered trademark. OpenFlight is a trademark of Multigen. Motif is a registered trademark and OSF/Motif is a trademark of Open Software Foundation. Netscape is a trademark of Netscape Communications Corporation. X Window System is a trademark of Massachusetts Institute of Technology. Yosemite image copyright of Delphi International. DI-GUY image copyright of Boston Dynamics Inc. Palace image copyright of de Pinxi. Clouds image copyright of SWRI. Ocean and Marine Effects Simulation image copyright of Paradigm Simulation Inc. PATENT DISCLOSURE Many of the techniques and methods disclosed in this Getting Started Guide are covered by patents held by Silicon Graphics including U.S. Patent Nos. 5,051,737; 5,369,739; 5,438,654; 5,394,170; 5,528,737; 5,528,738; 5,581,680; 5,471,572 and patent applications pending. We encourage you to use these features in your IRIS Performer application on Silicon Graphics systems. This functionality and IRIS Performer are not available for re-implementation and distribution on other platforms without the explicit permission of Silicon Graphics. IRIS Performer™ Getting Started Guide Document Number 007-3560-001 Contents Figures xv Tables xix About This Guide xxi What Is IRIS Performer? xxi Why Use IRIS Performer? xxii What You Should Know Before Reading This Guide xxii What This Guide Contains xxiii Part One: Overview of IRIS Performer xxiii Conventions xxiv Internet and Hard Copy Reading for the Performer Series xxv Bibliography xxvi Computer Graphics xxvii The IRIS GL and OpenGL Graphics Libraries xxviii X, Xt, IRIS IM, and Window Systems xxviii Visual Simulation xxix Mathematics of Flight Simulation xxx Virtual Reality xxx Geometric Reasoning xxx Conference Proceedings xxx Survey Articles in Magazines xxxi v Contents PART I Overview of IRIS Performer 1. Getting Acquainted With IRIS Performer 3 Installing the Software 3 Exploring the IRIS Performer Sample Scenes With Perfly 3 Locations of perfly and Example Source Code 3 Command Line Control of Perfly 7 Other Motion Models 7 Loading Databases into Performer 9 Going Beyond Visual Simulation 10 2. IRIS Performer Basics 11 IRIS Performer Applications 11 Library Structure of IRIS Performer 12 Features 14 Survey of Visual Simulation Techniques 17 Low-Latency Image Generation 19 Consistent Frame Rates 20 Rich Scene Content 21 Texture Mapping 23 Character Animation 24 Database Construction 26 Overview of the IRIS Performer Library Structure 27 The libpf Visual Simulation Library 27 The libpr High-Performance Rendering Library 31 The libpfdu Geometry Builder Library 34 Graphics Libraries 37 OpenGL vs. IRIS GL 37 Porting From IRIS GL to OpenGL 38 X and IRIS IM 38 vi Contents PART II Programming With IRIS Performer 3. Performer Programming Interface 41 General Naming Conventions 41 Prefixes 41 Header Files 42 Naming in C and C++ 42 Abbreviations 42 Macros, Tokens, and Enums 43 Class API 43 Object Creation 43 Set Routines 44 Get Routines 44 Action Routines 45 Enable and Disable of Modes 45 Mode, Attribute, or Value 46 Base Classes 46 Inheritance Graph 47 Libpr and Libpf Objects 49 User Data 49 pfDelete() and Reference Counting 50 Copying Objects with pfCopy() 54 Printing Objects with pfPrint() 54 Determining Object Type 56 4. Introduction to Performer Concepts 57 Scene-to-Screen Path 57 Scene Graph 58 Channels 60 vii Contents The Parts of a Performer Application 65 Initializing Performer 65 Creating the Pipe, Channel, and Pipe Window 66 Loading the Scene Graph 66 Positioning the Channel 67 Besides starting the CULL and DRAW processes, this call, along with pfSync, handles frame synchronization. 67 Creating the Simulation Loop 67 Inputting and Reading User Events 68 Implementing User Input Using Window Events 69 Retrieving User Events 70 5. Creating a Display with pfChannel 73 Creating and Configuring a pfChannel 75 Create a pfPipe 75 Create a pfChannel Rendered by a pfPipe 76 Create and Configure a pfPipeWindow 76 Attach a pfScene to the pfChannel 76 Configure a Viewport for the pfChannel 76 Creating a Background for a pfChannel 77 Initializing the pfChannel View 77 Bounding Volumes 79 Defining the Viewing Frustum 79 Channel Callbacks 83 Using Multiple Channels 85 Grouping Channels 86 Choosing the Attributes to Share 86 Using View Offsets 88 Multiple Pipes 89 Setting the Multiprocessing Configuration 90 Creating Multiple pfPipes 91 viii Contents 6. Creating Scene Graphs 93 What Is a Node? 94 Node Attributes 94 Scene Graph Nodes 95 Group Nodes 95 Leaf Nodes 97 Creating a Scene Graph 97 Creating and Attaching the pfScene Node 97 Adding Nodes in a Scene Graph 98 Arrangement of Nodes 98 Loading Scene Graphs 99 Loading a Scene Graph 99 Saving a Scene Graph 101 Scene Graph Traversals 102 Pipelined Traversals 102 Traversal Order 103 Customizing Performer Traversals 104 Setting Up Node Callbacks 104 Sample Customized Traversals 106 7. Creating Geometry with pfGeoSet 109 pfGeoSet Overview 110 Creating a pfGeoSet 111 Creating a pfGeoSet Object 111 Setting the Primitive Type 111 Setting the Number of Primitives 112 Setting the Number of Vertices Per Stripped Primitive 112 Attributes of pfGeoSet Primitives 113 Setting the Attributes 115 Attribute Bindings 115 Indexed Arrays 116 Packed Attributes 118 Drawing and Printing a pfGeoSet 119 ix Contents Placing Geometry in a Scene Graph 119 Creating Common Geometric Objects 121 Utilities to Create Common Geometric Objects 122 8. Specifying the Appearance of Geometry with pfState and pfGeoState 123 Setting the Graphics State 123 Global State 124 Defining a pfGeoState 124 Setting Modal pfGeoState Values 126 Setting pfGeoState Attributes 129 Using Textures 131 Enabling Texture Mapping 131 Creating a Texture Object 132 Loading an Image as a Texture 132 Specifying a Texture Attributes 133 Specifying Texture Formats 134 Setting the Texture Environment 135 Setting the Texture Coordinates 136 Specifying the Material 137 Specifying the Color and Shininess 137 Specifying Lighting 139 pfLightSource Nodes 140 9. Placing Geometry in a Scene 141 World Space and Object Space 141 Transformation Node Isolation 142 World Space 142 Transformation Nodes 143 Transformation Node Functionality 143 Ordering Transformation Nodes in the Scene Graph 144 Using pfFCS 144 pfFCS, pfFlux, and pfEngine Example 145 x Contents Using DCS Nodes 146 Creating a DCS Node 146 Setting the DCS Node 147 Optimizing the Use of DCS Nodes 147 Using SCS Nodes 148 Creating a SCS Node 148 Setting the SCS Node 148 Optimizing SCS Transformations 150 10. Controlling Frame Rate 153 Double Buffering 153 Specifying a Target Frame Rate 154 pfFrameRate 155 pfFieldRate 155 Frame Synchronization 156 Phase Control 156 Adjusting the Frame Rate Automatically 157 Stress Filters 158 Dynamic Video Resolution 158 11. Multiprocessing 161 Performer Stages 161 Optional, Asynchronous Stages 162 Benefits of Multiprocessing 163 Shared Memory 164 Printing Process States 165 Setting Up Multiprocessing 166 Multiprocessing Models 166 Common Multiprocessing Models 168 Default Processing Models 169 Choosing a Multiprocessing Model 169 Automatic Multiprocessing 170 xi Contents 12. Database Paging 171 Anticipating Paging 171 Database Process 172 Handling Memory for the DBASE Process 173 Changing the Scene Graph 173 13. Intersection Testing 179 Creating an ISECT Process 180 Synchronous ISECT Process 181 Constructing a Segment Set for pfNodeIsectSegs() 181 Setting the Mode 182 Intersection Masks 182 Creating the Segment Array 183 The pfSegSet Bound 183 Testing for Intersections 184 Intersection Information 184 14. Creating a User Interface 189 Traveling Through a Scene 189 Create a Transformer 190 Initialize the Transformer 191 Set Up Transformer Input and Output 192 Update the Channel 192 Scale the Motion 193 Example Implementing User Interaction 194 15. Optimizing Performance 201 General Performance Tips 201 Performer Statistics Display 202 Rendering the Statistics Tool 203 Specifying the Statistics to Gather 204