OpenGL Performer™ Programmer’s Guide 007-1680-060 CONTRIBUTORS Written by George Eckel and Ken Jones Edited by Rick Thompson and Susan Wilkening Illustrated by Chrystie Danzer and Chris Wengelski Production by Adrian Daley and Karen Jacobson Engineering contributions by Angus Dorbie, Tom Flynn, Yair Kurzion, Radomir Mech, Alexandre Naaman, Marcin Romaszewicz, Allan Schaffer, and Jenny Zhao COPYRIGHT © 1997, 2000 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 electronic (software) version of this document was developed at private expense; if acquired under an agreement with the USA government or any contractor thereto, it is acquired as "commercial computer software" subject to the provisions of its applicable license agreement, as specified in (a) 48 CFR 12.212 of the FAR; or, if acquired for Department of Defense units, (b) 48 CFR 227-7202 of the DoD FAR Supplement; or sections succeeding thereto. Contractor/manufacturer is Silicon Graphics, Inc., 1600 Amphitheatre Pkwy 2E, Mountain View, CA 94043-1351. TRADEMARKS AND ATTRIBUTIONS Silicon Graphics,IRIS, IRIS Indigo, IRIX, ImageVision Library, Indigo, Indy, InfiniteReality, Onyx, OpenGL, are registered trademarks, SGI, and CASEVision, Crimson, Elan Graphics, IRIS Geometry Pipeline, IRIS GL, IRIS Graphics Library, IRIS InSight, IRIS Inventor, Indigo Elan, Indigo2, InfiniteReality2, OpenGL Performer, Personal IRIS, POWER Series, Performance Co-Pilot, RealityEngine, RealityEngine2, SGI logo, 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. Linux is a registered trademark of Linus Torvalds. Motif is a registered trademark of Open Software Foundation. Netscape is a trademark of Netscape Communications Corp. Purify is a registered trademark of Rational Software Corporation. WindView is a trademark of Wind River Systems. X Window System is a trademark of Massachusetts Institute of Technology. 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 The 2.4 version of OpenGL Performer contains the following new features: • Product name has been changed from IRIS Performer to OpenGL Performer. • OpenGL Performer interfaces only with the OpenGL graphics library. Unlike IRIS Performer, it does not use the IRIS GL library. • OpenGL Performer runs on both the IRIX and Linux operating systems. • Multi-texture support. • Multiprocessing enhancements. • pfFlux enhancements. • pfShader. • Double-precision DCS support. • pfLOD enhancements. • Volume fog. • Anisotrophic filtering. 007-1680-060 iii Record of Revision Version Description 001 1997 Original publication. 002 November 2000 Updated for the 2.4 version of OpenGL Performer. 007-1680-060 v Contents Examples . xxvii Figures . xxxi Tables . xxxv About This Guide. xxxix Why Use OpenGL Performer? . xxxix What You Should Know Before Reading This Guide . xl How to Use This Guide . xl What This Guide Contains . xl Sample Applications . xlii Conventions . xlii Internet and Hardcopy Reading for the OpenGL Performer Series . xliii Bibliography . xliii Computer Graphics . xliii OpenGL Graphics Library . xliv X, Xt, IRIS IM, and Window Systems . xlv Visual Simulation . xlv Mathematics of Flight Simulation . xlvi Virtual Reality. xlvi Geometric Reasoning. xlvii Conference Proceedings . xlvii Survey Articles in Magazines . xlviii Obtaining Publications . xlviii Reader Comments . xlviii 007-1680-060 vii Contents 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. 3 Set Routines . 4 Get Routines . 4 Action Routines . 5 Enable and Disable of Modes . 5 Mode, Attribute, or Value . 6 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 . 24 viii 007-1680-060 Contents 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 3. Nodes and Node Types . 45 Nodes . 45 Attribute Inheritance . 45 pfNode . 47 pfGroup . 49 Working with Nodes . 52 Instancing . 52 Bounding Volumes . 55 007-1680-060 ix Contents Node Types . 57 pfScene Nodes . 57 pfSCS Nodes . 58 pfDCS Nodes . 58 pfFCS Nodes . 59 pfDoubleSCS Nodes . 60 pfDoubleDCS Nodes . 60 pfDoubleFCS Nodes . 63 pfSwitch Nodes . 63 pfSequence Nodes . 63 pfLOD Nodes . 66 pfASD Nodes . 66 pfLayer Nodes . 66 pfGeode Nodes . 67 pfText Nodes . 69 pfBillboard Nodes . 71 pfPartition Nodes . 74 Sample Program . 76 4. Database Traversal . 81 Scene Graph Hierarchy . 83 Database Traversals . 83 State Inheritance . 83 Database Organization . 84 Application Traversal . 84 Cull Traversal . 86 Traversal Order . 86 Visibility Culling . 87 Organizing a Database for Efficient Culling . 90 Sorting the Scene . 93 Paths through the Scene Graph . 95 Draw Traversal . 96 x 007-1680-060 Contents Controlling and Customizing Traversals . 96 pfChannel Traversal Modes . 96 pfNode Draw Mask . 97 pfNode Cull and Draw Callbacks . 97 Process Callbacks . .101 Process Callbacks and Passthrough Data . .103 Intersection Traversal . .105 Testing Line Segment Intersections . .105 Intersection Requests: pfSegSets . .106 Intersection Return Data: pfHit Objects . .106 Intersection Masks . .107 Discriminator Callbacks . .109 Line Segment Clipping . .110 Traversing Special Nodes . .110 Picking . .111 Performance . .111 Intersection Methods for Segments . .112 5. Frame and Load Control . .115 Frame-Rate Management . .115 Selecting the Frame Rate . .116 Achieving the Frame Rate . .116 Fixing the Frame Rate . .117 Level-of-Detail Management . .122 Level-of-Detail Models . .122 Level-of-Detail States . .126 Level-of-Detail Range Processing . ..