OpenGL Performer™ Programmer’s Guide Version 3.2 007-1680-100 CONTRIBUTORS Written by George Eckel and Ken Jones Illustrated by Chrystie Danzer and Chris Wengelski Production by Karen Jacobson Engineering contributions by Angus Dorbie, Paolo Farinelli, Tom Flynn, Yair Kurzion, Radomir Mech, Alexandre Naaman, Marcin Romaszewicz, Stace Peterson, Allan Schaffer, and Jenny Zhao COPYRIGHT © 1994, 2000–2004 Silicon Graphics, Inc. All rights reserved; provided portions may be copyright in third parties, as indicated elsewhere herein. No permission is granted to copy, distribute, or create derivative works from the contents of this electronic documentation in any manner, in whole or in part, without the prior written permission of Silicon Graphics, Inc. LIMITED RIGHTS LEGEND The software described in this document is "commercial computer software" provided with restricted rights (except as to included open/free source) as specified in the FAR 52.227-19 and/or the DFAR 227.7202, or successive sections. Use beyond license provisions is a violation of worldwide intellectual property laws, treaties and conventions. This document is provided with limited rights as defined in 52.227-14. TRADEMARKS AND ATTRIBUTIONS Silicon Graphics, SGI, the SGI logo, IRIS, IRIX, ImageVision Library, Indigo, Indy, InfiniteReality, O2, Octane, Onyx, Onyx2, and OpenGL are registered trademarks and CASEVision, Crimson, Elan Graphics, IRIS Geometry Pipeline, IRIS GL, IRIS Graphics Library, IRIS InSight, IRIS Inventor, Indigo Elan, Indigo2, InfinitePerformance, InfiniteReality2, InfiniteReality4, Onyx4, OpenGL Multipipe, OpenGL Performer, Performance Co-Pilot, REACT, RealityEngine, RealityEngine2, Showcase, Silicon Graphics Prism, UltimateVision, and VPro are trademarks of Silicon Graphics, Inc., in the United States and/or other countries worldwide. AutoCAD is a registered trademark of Autodesk, Inc. CATIA is a registered trademark of DASSAULT SYSTEMES S.A. Designer’s Workbench is a trademark of Centric Software, Inc. Lightscape is a trademark of Autodesk, Inc. Linux is a registered trademark of Linus Torvalds. Maya is a registered trademark and Wavefront is a trademark of Alias Systems, a division of Silicon Graphics Limited in the United States and/or other countries worldwide. Motif is a registered trademark and X Window System and OSF/Motif are trademarks of The Open Group. Purify is a registered trademark of Rational Software Corporation. Red Hat is a registered trademark of Red Hat, Inc. RPC is a trademark of ArchVision. VTune is a trademark of Intel Corporation. WindView is a trademark of Wind River Systems. Microsoft, Windows, and Windows NT are registered trademarks of Microsoft Corporation in the United States and other countries. Maya is a trademark of Alias Systems. All other trademarks mentioned herein are the property of their respective owners. PATENT DISCLOSURE 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 OpenGL Performer application on SGI systems. This functionality and OpenGL Performer are not available for re-implementation and distribution on other platforms without the explicit permission of Silicon Graphics. New Features in This Guide This revision of the guide documents OpenGL Performer 3.2, which has support for the following features: • Silicon Graphics Prism visualization systems • OpenGL 2.0 Shading Language • Scene graph optimizer • New compositor API • Maya 6.0 exporter 007-1680-100 iii Record of Revision Version Description 020 1994 Original publication. 060 November 2000 Updated for the 2.4 version of OpenGL Performer. 070 November 2001 Updated for the 2.5 version of OpenGL Performer. 080 December 2002 Updated for the 3.0 version of OpenGL Performer. 090 December 2003 Updated for the 3.1 version of OpenGL Performer. 100 November 2004 Updated for the 3.2 version of OpenGL Performer. 007-1680-100 v Contents Figures . xxxi Tables . xxxvii Examples . xli About This Guide. xlv Why Use OpenGL Performer? . xlv What You Should Know Before Reading This Guide . xlvi How to Use This Guide . xlvi What This Guide Contains . xlvi Sample Applications . xlviii Conventions . xlix Internet and Hardcopy Reading for the OpenGL Performer Series . xlix Reader Comments . l 1. OpenGL Performer Programming Interface . 1 General Naming Conventions . 1 Prefixes. 1 Header Files . 2 Naming in C and C++ . 2 Abbreviations . 3 Macros, Tokens, and Enums. 3 Class API . 3 Object Creation . 4 Set Routines . 4 Get Routines . 4 Action Routines . 5 Enable and Disable of Modes . 5 Mode, Attribute, or Value . 6 007-1680-100 vii Contents Base Classes . 6 Inheritance Graph . 7 libpr and libpf Objects . 10 User Data . 10 pfDelete() and Reference Counting . 11 Copying Objects with pfCopy() . 15 Printing Objects with pfPrint() . 15 Determining Object Type . 17 2. Setting Up the Display Environment . 19 Using Pipes . 21 The Functional Stages of a Pipeline . 21 Creating and Configuring a pfPipe . 23 Example of pfPipe Use . 25 Using Channels . 26 Creating and Configuring a pfChannel . .26 Setting Up a Scene . 27 Setting Up a Viewport . 27 Setting Up a Viewing Frustum . 28 Setting Up a Viewpoint . 30 Example of Channel Use . 32 Controlling the Video Output. 34 Using Multiple Channels . 35 One Window per Pipe, Multiple Channels per Window . 36 Using Channel Groups. 40 Multiple Channels and Multiple Windows. 43 Importing OpenGL Multipipe SDK (MPK) Configuration Files . 44 3. Nodes and Node Types . 49 Nodes . 49 Attribute Inheritance . 49 pfNode . 51 pfGroup. 53 viii 007-1680-100 Contents Working with Nodes . 56 Instancing . 56 Bounding Volumes . 59 Node Types. 61 pfScene Nodes. 61 pfSCS Nodes . 62 pfDCS Nodes . 62 pfFCS Nodes . 63 pfDoubleSCS Nodes . 64 pfDoubleDCS Nodes . 64 pfDoubleFCS Nodes . 67 pfSwitch Nodes . 67 pfSequence Nodes . 67 pfLOD Nodes . 70 pfASD Nodes . 70 pfLayer Nodes . 70 pfGeode Nodes . 71 pfText Nodes . 73 pfBillboard Nodes . 75 pfPartition Nodes . 78 Sample Program . 80 4. Database Traversal . 85 Scene Graph Hierarchy . 87 Database Traversals . 87 State Inheritance . 87 Database Organization . 88 Application Traversal . 88 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 . .100 007-1680-100 ix Contents Draw Traversal . 100 Optimizing the Drawing of Sub-bins . 101 Bin Draw Callbacks . 101 Controlling and Customizing Traversals . 102 pfChannel Traversal Modes . 102 Cull Programs . 103 pfNode Draw Mask . 112 pfNode Cull and Draw Callbacks . 113 Process Callbacks . 116 Process Callbacks and Passthrough Data . 118 Intersection Traversal . 120 Testing Line Segment Intersections . 120 Intersection Requests: pfSegSets . 121 Intersection Return Data: pfHit Objects . 121 Intersection Masks. 122 Discriminator Callbacks . 124 Line Segment Clipping . 125 Traversing Special Nodes. 125 Picking . 126 Performance . 126 Intersection Methods for Segments . 127 5. Frame and Load Control . 129 Frame Rate Management . 129 Selecting the Frame Rate . 130 Achieving the Frame Rate . 130 Fixing the Frame Rate . 131 Level-of-Detail Management . 136 Level-of-Detail Models . 136 Level-of-Detail States . 140 Level-of-Detail Range Processing . 141 Level-of-Detail Transition Blending . 145 Run-Time User Control Over LOD Evaluation. 146 Terrain Level-of-Detail . 147 x 007-1680-100 Contents Maintaining Frame Rate Using Dynamic Video Resolution . .148 The Channel in.