IRIS Performer™ Programmer’s Guide Document Number 007-1680-040 CONTRIBUTORS Written by George Eckel Edited by Steven Hiatt Illustrated by Dany Galgani Production by Derrald Vogt and Linda Rae Sande Engineering contributions by Sharon Clay, Brad Grantham, Don Hatch, Jim Helman, Michael Jones, Martin McDonald, John Rohlf, Allan Schaffer, Chris Tanner, Jenny Zhao, Yair Kurzion, and Tom McReynolds © Copyright 1995 -1997 Silicon Graphics, Inc.— All Rights Reserved This document contains proprietary and confidential information of Silicon Graphics, Inc. The contents of this document may not be disclosed to third parties, 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 94039-7311. Indigo, Indy, IRIS, IRIS Indigo, ImageVision Library, Onyx, OpenGL, Silicon Graphics, and the Silicon Graphics logo are registered trademarks and Crimson, Elan Graphics, Geometry Pipeline, Indigo Elan, Indigo2, IRIS GL, IRIS Graphics Library, IRIS InSight, IRIS Inventor, IRIS Performer, IRIX, Personal IRIS, POWER Series, Performance Co-Pilot, RealityEngine, RealityEngine2, and Showcase are trademarks of Silicon Graphics, Inc. AutoCAD is a registered trademark of Autodesk, Inc. DrAW Computing Associates is a trademark of DrAW Computing Associates. Netscape is a trademark of Netscape Communications Corp. Motif is a registered trademark of Open Software Foundation. WindView is a trademark of Wind River Systems. X Window System is a trademark of Massachusetts Institute of Technology. Many of the techniques and methods disclosed in this Programmer’s 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™ Programmer’s Guide Document Number 007-1680-040 Contents List of Examples xix Figures xxiii List of Tables xxvii About This Guide xxxi Why Use IRIS Performer? xxxi What You Should Know Before Reading This Guide xxxii Internet and Hard Copy Reading for the Performer Series xxxii How to Use This Guide xxxiv What This Guide Contains xxxiv Sample Applications xxxv Conventions xxxvi Bibliography xxxvi X, Xt, IRIS IM, and Window Systems xxxviii Visual Simulation xxxix Mathematics of Flight Simulation xxxix Virtual Reality xxxix Geometric Reasoning xl Conference Proceedings xl Survey Articles in Magazines xli 1. IRIS Performer Programming Interface 3 General Naming Conventions 3 Prefixes 3 Header Files 4 Naming in C and C++ 4 Abbreviations 4 Macros, Tokens, and Enums 5 iii Contents Class API 5 Object Creation 5 Set Routines 6 Get Routines 6 Action Routines 7 Enable and Disable of Modes 7 Mode, Attribute, or Value 7 Base Classes 8 Inheritance Graph 9 Libpr and Libpf Objects 11 User Data 11 pfDelete() and Reference Counting 12 Copying Objects with pfCopy() 16 Printing Objects with pfPrint() 17 Determining Object Type 18 2. Setting Up the Display Environment 23 Using Pipes 25 The Functional Stages of a Pipeline 25 Creating and Configuring a pfPipe 27 Example of pfPipe Use 29 Using Channels 30 Creating and Configuring a pfChannel 31 Setting Up a Scene 31 Setting Up a Viewport 32 Setting Up a Viewing Frustum 32 Setting Up a Viewpoint 34 Example of Channel Use 36 Controlling the Video Output 39 Using Multiple Channels 40 One Window per Pipe, Multiple Channels per Window 40 Using Channel Groups 44 Multiple Channels and Multiple Windows 48 iv Contents 3. Nodes and Node Types 51 Nodes 51 Attribute Inheritance 51 pfNode 53 pfGroup 55 Working With Nodes 58 Instancing 58 Bounding Volumes 61 Node Types 63 pfScene Nodes 63 pfSCS Nodes 64 pfDCS Nodes 64 pfFCS Nodes 65 pfSwitch Nodes 66 pfSequence Nodes 66 pfLOD Nodes 69 pfASD Nodes 69 pfLayer Nodes 69 pfGeode Nodes 71 pfText Nodes 72 pfBillboard Nodes 74 pfPartition Nodes 77 Sample Program 79 4. Database Traversal 85 Scene Graph Hierarchy 87 Database Traversals 87 State Inheritance 88 Database Organization 88 Application Traversal 89 v Contents Cull Traversal 90 Traversal Order 90 Visibility Culling 91 Organizing a Database for Efficient Culling 94 Sorting the Scene 97 Paths Through the Scene Graph 99 Draw Traversal 100 Controlling and Customizing Traversals 100 pfChannel Traversal Modes 100 pfNode Draw Mask 101 pfNode Cull and Draw Callbacks 102 Process Callbacks 105 Process Callbacks and Passthrough Data 107 Intersection Traversal 109 Testing Line Segment Intersections 110 Intersection Requests: pfSegSets 110 Intersection Return Data: pfHit Objects 111 Intersection Masks 112 Discriminator Callbacks 114 Line Segment Clipping 114 Traversing Special Nodes 115 Picking 115 Performance 115 Intersection Methods for Segments 116 5. Frame and Load Control 121 Frame-Rate Management 121 Selecting the Frame Rate 122 Achieving the Frame Rate 122 Fixing the Frame Rate 123 vi Contents Maintaining Frame Rate Using Dynamic Video Resolution 128 The Channel in DVR 129 DVR Scaling 129 Customizing DVR 130 Understanding the Stress Filter 131 Level-of-Detail Management 132 Level-of-Detail Models 133 Level of Detail States 136 Level-of-Detail Range Processing 138 Level-of-Detail Transition Blending 141 Terrain Level of Detail 143 Dynamic Load Management 144 Successful Multiprocessing With IRIS Performer 147 Review of Rendering Stages 147 Choosing a Multiprocessing Model 148 Asynchronous Database Processing 153 Rules for Invoking Functions While Multiprocessing 155 Multiprocessing and Memory 158 Shared Memory and pfInit() 159 pfDataPools 160 Passthrough Data 160 6. Creating Visual Effects 165 Using pfEarthSky 165 Atmospheric Effects 166 7. Importing Databases 173 Overview of IRIS Performer Database Creation and Conversion 173 libpfdu - Utilities for Creation of Efficient IRIS Performer Run-Time Structures 174 pfdLoadFile - Loading Arbitrary Databases into IRIS Performer 175 Database Loading Details 177 vii Contents Developing Custom Importers 180 Structure and Interpretation of the Database File Format 180 Scene Graph Creation using Nodes as defined in libpf 181 Defining Geometry and Graphics State for libpr 181 Creation of a IRIS Performer Database Converter using libpfdu 182 Maximizing Database Loading and Paging Performance with PFB and PFI Formats 192 pfconv 192 pficonv 193 Supported Database Formats 193 Description of Supported Formats 195 AutoDesk 3DS Format 195 Silicon Graphics BIN Format 196 Side Effects POLY Format 197 Brigham Young University BYU Format 199 Optimizer CSB Format 200 Virtual Cliptexture CT Loader 200 Designer’s Workbench DWB Format 200 AutoCAD DXF Format 201 MultiGen OpenFlight Format 203 McDonnell-Douglas GDS Format 205 Silicon Graphics GFO Format 205 Silicon Graphics IM Format 207 AAI/Graphicon IRTP Format 208 Silicon Graphics Open Inventor Format 208 Lightscape Technologies LSA and LSB Formats 210 Medit Productions MEDIT Format 213 NFF Neutral File Format 214 Wavefront Technology OBJ Format 216 Silicon Graphics PFB Format 217 Silicon Graphics PFI Format 218 Silicon Graphics PHD Format 219 Silicon Graphics PTU Format 221 USNA Standard Graphics Format 223 viii Contents Silicon Graphics SGO Format 224 USNA Simple Polygon File Format 227 Sierpinski Sponge Loader 228 Star Chart Format 228 3D Lithography STL Format 229 SuperViewer SV Format 230 Geometry Center Triangle Format 234 UNC Walkthrough Format 234 WRL Format 235 Database Operators with Pseudo Loaders 235 8. Geometry 239 Geometry Sets 239 Primitive Types 241 pfGeoSet Draw Mode 242 Primitive Connectivity 244 Attributes 246 Attribute Bindings 248 Indexed Arrays 249 pfGeoSet Operations 251 3D Text 251 pfFont 251 pfString 253 ix Contents 9. Graphics State 259 Immediate Mode 259 Rendering Modes 261 Rendering Values 266 Enable / Disable 266 Rendering Attributes 267 Graphics Library Matrix Routines 283 Sprite Transformations 283 Display Lists 285 State Management 286 State Override 287 pfGeoState 288 10. ClipTextures 297 Overview 298 Cliptexture Levels 299 Cliptexture Assumptions 300 Image Cache 301 Toroidal Loading 304 Updating the Clipcenter 306 Virtual Cliptextures 307 Cliptexture Support Requirements 308 Special Features 308 How Cliptextures Interact with the Rest of the System 309 Cliptexture Support in IRIS Performer 310 Cliptexture Manipulation 311 Cliptexture API 313 Preprocessing ClipTextures 313 Building a MIPmap 314 Formatting Image Data 315 Tiling an Image 315 Cliptexture Configuration 316 x Contents Configuration API 317 libpr Functionality 317 Configuration Utilities 321 Configuration Files 323 Post-Scene Graph Load Configuration 339 MPClipTextures 339 pfMPClipTexture Utilities 341 Using Cliptextures with Multiple Pipes 344 Texture Memory and Hardware Support Checking 347 Manipulating Cliptextures 347 Cliptexture Load Control 348 Invalidating Cliptextures