OpenGL® on Silicon Graphics® Systems Document Number 007-2392-002 CONTRIBUTORS Written by Renate Kempf and Jed Hartman. Revised by Renate Kempf. Illustrated by Dany Galgani and Martha Levine Edited by Christina Cary Production by Allen Clardy Engineering contributions by Allen Akin, Steve Anderson, David Blythe, Sharon Rose Clay, Terrence Crane, Kathleen Danielson, Tom Davis, Celeste Fowler, Ziv Gigus, David Gorgen, Paul Hansen, Paul Ho, Simon Hui, George Kyriazis, Mark Kilgard, Phil Lacroute, John Leech, Mark Peercy, Dave Shreiner, Chris Tanner, Joel Tesler, Gianpaolo Tommasi, Bill Torzewski, Bill Wehner, Nancy Cam Winget, Paula Womack, David Yu, and others. Some of the material in this book is from “OpenGL from the EXTensions to the SOLutions,” which is part of the developer’s toolbox. St. Peter’s Basilica image courtesy of ENEL SpA and InfoByte SpA. Disk Thrower image courtesy of Xavier Berenguer, Animatica. © 1996,1998 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, OpenGL, InfiniteReality, IRIS, IRIS Indigo, and IRIX are registered trademarks and Developer Magic, IMPACT, IRIS GL, IRIS InSight, IRIS ViewKit, IRIS Performer, Elan, Express, Indy, Indigo, Indigo2, Indigo2 IMPACT, Indigo2 High IMPACT, Indigo2 Maximum IMPACT, O2, Onyx, Open Inventor, R8000, R10000, RapidApp, and RealityEngine are trademarks of Silicon Graphics, Inc. Extreme is a trademark used under license by Silicon Graphics Inc. Intel is a trademark of Intel Corporation. OS/2 is a trademark of International Business Machines Corporation. Windows NT is a trademark and Windows a registered trademark of Microsoft Corporation. Motif and OSF/Motif are trademarks of Open Software Foundation. X Window System is a tradmark of X Consortium, Inc. OpenGL® on Silicon Graphics® Systems Document Number 007-2392-002 Contents List of Examples xxiii List of Figures xxv List of Tables xxvii About This Guide xxix What This Guide Contains xxix What You Should Know Before Reading This Guide xxxi Background Reading xxxii OpenGL and Associated Tools and Libraries xxxii X Window System: Xlib, X Toolkit, and OSF/Motif xxxii Other Sources xxxiii Conventions Used in This Guide xxxiii Typographical Conventions xxxiii Function Naming Conventions xxxiv Changes in this Version of the Manual xxxv 1. OpenGL on Silicon Graphics Systems 1 Using OpenGL With the X Window System 1 GLX Extension to the X Window System 2 Libraries, Tools, Toolkits, and Widget Sets 2 RapidApp 3 Open Inventor 4 IRIS ViewKit 5 IRIS IM Widget Set 5 Xlib Library 5 Note to IRIS GL Users 5 Extensions to OpenGL 6 iii Contents Debugging and Performance Optimization 7 Debugging Your Program 7 Tuning Your OpenGL Application 7 Maximizing Performance With IRIS Performer 8 Location of Example Source Code 8 2. OpenGL and X: Getting Started 9 Background and Terminology 9 X Window System on Silicon Graphics Systems 9 Silicon Graphics X Server 10 GLX Extension to X 10 Compiling With the GLX Extension 10 X Window System Concepts 11 GLX and Overloaded Visuals 11 GLX Drawables—Windows and Pixmaps 12 Rendering Contexts 13 Resources As Server Data 13 X Window Colormaps 14 Libraries, Toolkits, and Tools 14 Widgets and the Xt Library 14 Xt Library 15 For More Information About Xt 15 Other Toolkits and Tools 15 Integrating Your OpenGL Program With IRIS IM 16 Simple Motif Example Program 16 Looking at the Example Program 19 Opening the X Display 20 Selecting a Visual 21 Creating a Rendering Context 22 Creating the Window 23 Binding the Context to the Window 23 Mapping the Window 24 iv Contents Integrating OpenGL Programs With X—Summary 25 Compiling With OpenGL and Related Libraries 26 Link Lines for Individual Libraries 26 Link Lines for Groups of Libraries 26 3. OpenGL and X: Examples 27 Using Widgets 27 About OpenGL Drawing-Area Widgets 28 Drawing-Area Widget Setup and Creation 29 Setting Up Fallback Resources 29 Creating the Widgets 30 Choosing the Visual for the Drawing-Area Widget 31 Creating Multiple Widgets With Identical Characteristics 31 Using Drawing-Area Widget Callbacks 32 Input Handling With Widgets and Xt 34 Background Information 34 Using the Input Callback 35 Using Actions and Translations 36 Creating Colormaps 37 Widget Troubleshooting 38 Keyboard Input Disappears 38 Inheritance Issues 38 Using Xlib 39 Simple Xlib Example Program 40 Creating a Colormap and a Window 42 Installing the Colormap 44 Xlib Event Handling 45 Handling Mouse Events 45 Exposing a Window 47 Using Fonts and Strings 48 v Contents 4. OpenGL and X: Advanced Topics 51 Using Animations 51 Swapping Buffers 52 Controlling an Animation With Workprocs 53 General Workproc Information 53 Workproc Example 54 Controlling an Animation With Timeouts 56 Using Overlays 58 Introduction to Overlays 58 Note for IRIS GL Users 60 Creating Overlays 60 Overlay Troubleshooting 63 Rubber Banding 64 Using Popup Menus With the GLwMDrawingArea Widget 64 Using Visuals 66 Some Background on Visuals 67 Running OpenGL Applications Using a Single Visual 68 Using Colormaps 69 Background Information About Colormaps 70 Color Variation Across Colormaps 70 Multiple Colormap Issues 71 Choosing Which Colormap to Use 72 Colormap Example 74 Stereo Rendering 74 Stereo Rendering Background Information 75 Quad Buffer Stereo 75 Divided-Screen Stereo 75 For More Information on Stereo Rendering 75 Stereo Rendering 76 Performing Stereo Rendering on High-End Systems 76 Performing Stereo Rendering on Low-End and Mid-Range Systems 76 vi Contents Using Pixmaps 77 Creating and Using Pixmaps 78 Direct and Indirect Rendering 79 Performance Considerations for X and OpenGL 80 Portability 80 5. Introduction to OpenGL Extensions 81 Determining Extension Availability 81 How to Check for OpenGL Extension Availability 82 Example Program: Checking for Extension Availability 83 Checking for GLX Extension Availability 84 Finding Information About Extensions 85 Reference Pages 85 Example Programs 85 Extension Specifications 85 6. Resource Control Extensions 87 EXT_import_context—The Import Context Extension 88 Importing a Context 88 Retrieving Display and Context Information 89 New Functions 89 EXT_make_current_read—The Make Current Read Extension 90 Read and Write Drawables 90 Possible Match Errors 91 Retrieving the Current Drawable’s Name 92 New Functions 92 EXT_visual_info—The Visual Info Extension 92 Using the Visual Info Extension 92 Using Transparent Pixels 94 EXT_visual_rating—The Visual Rating Extension 94 Using the Visual Rating Extension 95 vii Contents SGIX_dm_pbuffer—The Digital Media Pbuffer Extension 95 Creating a Digital Media Pbuffer 96 Creating a DMBuffer 96 Creating a Digital Media Pbuffer 97 Associating Pbuffer and DMbuffer 97 Compatibility Conditions 98 Image Layouts 98 Pixel Formats 99 OpenGL Rendering to DMbuffers 99 Creating DMParams Structure and DMBuffer Pool 100 Creating a Compatible DMPbuffer 100 Associating the DMBuffer With the DMPbuffer 101 DMbuffers as OpenGL Textures 102 New Function 103 SGIX_fbconfig—The Framebuffer Configuration Extension 104 Why Use the Framebuffer Configuration Extension? 104 Describing a Drawable With a GLXFBConfigSGIX Construct 104 Less-Rigid Similarity Requirements When Matching Context and Drawable 105 Less-Rigid Match of GLX Visual and X Visual 105 GLXFBConfigSGIX Constructs 106 Choosing a GLXFBConfigSGIX Construct 106 Retrieving FBConfig Attribute Values 110 How an FBConfig Is Selected 111 New Functions 112 SGIX_pbuffer—The Pixel Buffer Extension 112 About GLXPbuffers 112 PBuffers and Pixmaps 113 Volatile and Preserved Pbuffers 113 Creating a PBuffer 114 Rendering to a GLXPbuffer 115 Directing the Buffer Clobber Event 116 New Functions 117 viii Contents 7. Texturing Extensions 119 EXT_texture3D—The 3D Texture Extension 120 Why Use the 3D Texture Extension? 120 Using 3D Textures 121 3D Texture Example Program 123 New Functions 125 SGI_texture_color_table—The Texture Color Table Extension 126 Why Use a Texture Color Table? 126 Using Texture Color Tables 126 Texture Color Table and Internal Formats 127 Using Texture Color Table On Different Platforms 128 Texture Color Table on Indigo2 IMPACT Systems 128 Texture Color Table on InfiniteReality Systems 128 SGIS_detail_texture—The Detail Texture Extension 129 Using the Detail Texture Extension 129 Creating a Detail Texture and a Low-Resolution Texture 130 Detail Texture Computation 132 Customizing the Detail Function 132 Using Detail Texture and Texture Object 134 Detail Texture Example Program 134 New Functions 136 SGIS_filter4_parameters—The Filter4 Parameters Extension 136 Using the Filter4 Parameters Extension 137 SGIS_point_line_texgen—The Point or Line Texture Generation Extension 138 Why Use Point or Line Texture Generation 138 SGIS_sharpen_texture—The Sharpen Texture Extension 139 About the Sharpen Texture Extension 139 How to Use the Sharpen Texture Extension 140 How Sharpen