OpenGL Performer™ Programmer’s Guide 007-1680-070 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–2001 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, IRIX, ImageVision Library, Indigo, Indy, InfiniteReality, O2, Octane, Onyx, Onyx2, and OpenGL are registered trademarks and SGI, the SGI logo, CASEVision, Crimson, Elan Graphics, IRIS Geometry Pipeline, IRIS GL, IRIS Graphics Library, IRIS Indigo, IRIS InSight, IRIS Inventor, Indigo Elan, Indigo2, InfiniteReality2, OpenGL Performer, Personal IRIS, Performance Co-Pilot, RealityEngine, RealityEngine2, Showcase, and VPro 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. OSF/Motif and X Window System are trademarks of The Open Group. 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 the following features of OpenGL Performer 2.5: • Image-Based rendering to replace a complex object with pre-rendered images of the object as seen from different angles • Real-Time shadows to project an object’s true shadow upon any and all other objects in the scene • Light shafts with cone attenuation and spot illumination of objects in the scene • Cull programs to optimize and combine multi-pass rendering effects by selection of the OpenGL Performer draw bin based on user-defined attributes 007-1680-070 iii Record of Revision Version Description 001 1997 Original publication. 002 November 2000 Updated for the 2.4 version of OpenGL Performer. 003 November 2001 Updated for the 2.5 version of OpenGL Performer. 007-1680-070 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 . xliv OpenGL Graphics Library . xliv X, Xt, IRIS IM, and Window Systems . xlv Visual Simulation . xlvi Mathematics of Flight Simulation . xlvi Virtual Reality. xlvi Geometric Reasoning. xlvii Conference Proceedings . xlvii Survey Articles in Magazines . xlviii Obtaining Publications . xlix Reader Comments . xlix 007-1680-070 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-070 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-070 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 . 96 Draw Traversal . 96 Optimizing the Drawing of Sub-bins . .97 Bin Draw Callbacks . 97 x 007-1680-070 Contents Controlling and Customizing Traversals . 98 pfChannel Traversal Modes . 98 Cull Programs . 99 pfNode Draw Mask . .105 pfNode Cull and Draw Callbacks . .106 Process Callbacks . .109 Process Callbacks and Passthrough Data . .111 Intersection Traversal . .114 Testing Line Segment Intersections . .114 Intersection Requests: pfSegSets . .114 Intersection Return Data: pfHit Objects . .115 Intersection Masks . .116 Discriminator Callbacks . .118 Line Segment Clipping . .118 Traversing Special Nodes . .119 Picking . .119 Performance . .119 Intersection Methods for Segments . .120 5. Frame and Load Control . .123 Frame-Rate Management . .123 Selecting the Frame Rate . .124 Achieving the Frame Rate . .124 Fixing the Frame Rate . ..