The OpenGL Porting Guide Document Number 007-1797-020 CONTRIBUTORS Written by C J Silverio, Beth Fryer, and Jed Hartman Edited by Nancy Schweiger Cover design and illustration by Rob Aguilar, Rikk Carey, Dean Hodgkinson, Erik Lindholm, and Kay Maitz Production by Lorrie Williams Engineering contributions by Kurt Akeley, Allen Akin, Gavin Bell, Derrick Burns, Dave Ciemiewicz, Tom Davis, Chris Frazier, Phil Karlton, Reuel Nash, Mark Segal, Dave Shreiner, Rolf van Widenfelt, and Mason Woo © Copyright 1994, 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. Silicon Graphics and IRIS are registered trademarks and GL, Graphics Library, IRIS GL, IRIS IM, IRIS Indigo, IRIX, OpenGL, Open Inventor, Personal IRIS, and RealityEngine are trademarks of Silicon Graphics, Inc. X Window System is a trademark of Massachusetts Institute of Technology. OSF/Motif is a trademark of the Open Software Foundation, Inc. The OpenGL Porting Guide Document Number 007-1797-020 Contents List of Figures ix List of Tables xi About This Guide xiii How to Use This Guide xiii What This Guide Contains xiv Where To Get More Information xv Style Conventions xvi 1. Introduction to Porting from IRIS GL to OpenGL 1 What’s Different? 1 Tools and Libraries to Help Port Your Code 3 How to Port Your Code to OpenGL 3 If You’re Not Porting Your Code to OpenGL Yet 5 2. Using toogl 7 How to Get and Call toogl 7 Using gdiff to Compare Files 8 What toogl Will and Won’t Do for You 8 Hints for Using toogl Effectively 9 iii Contents Editing toogl Output: Areas that Need Special Attention 9 Windowing, Device, and Event Calls 10 Parentheses and Quotes 10 Defined Color Constants 10 clear() Calls 10 Get Calls 11 rotate() 12 swaptmesh() 12 Texturing 12 defs/binds 12 Calls without Direct Equivalents 12 Finding OpenGL Replacements for IRIS GL Calls 13 Performance 13 Editing toogl Output: An Example 14 3. After toogl: How to Finish Porting to OpenGL 15 Header Files 15 Porting greset() 16 Porting IRIS GL ‘Get’ Commands 18 Porting Commands that Required Current Graphics Position 19 Porting Screen and Buffer Clearing Commands 20 Porting Matrix and Transformation Calls 22 Porting MSINGLE Mode Code 26 Porting “Get” Calls For Matrices and Transformations 26 Viewports, Screenmasks, and Scrboxes 28 Clipping Planes 29 iv Contents Porting Drawing Commands 29 The IRIS GL Sphere Library 29 The v() Commands 31 bgn/end Commands 31 Points 34 Lines 35 Polygons and Quadrilaterals 36 Tessellated Polygons 40 Triangles 40 Arcs and Circles 41 Spheres 42 Porting Color, Shading, and Writemask Commands 43 Color Calls 44 Shading Models 45 Porting Pixel Operations 46 Porting Depth Cueing and Fog Commands 48 Porting Curve and Surface Commands 51 NURBS Objects 52 NURBS Curves 52 Trimming Curves 54 NURBS Surfaces 54 Porting Antialiasing Calls 58 Blending 58 afunction() Test Functions 60 Antialiasing Calls 60 Accumulation Buffer Calls 61 Stencil Plane Calls 62 Porting Display Lists 63 Porting bbox2() Calls 64 Edited Display Lists 65 A Sample Implementation of a Display List 65 Porting defs, binds, and sets: Replacing ‘Tables’ of Stored Definitions 67 Porting Lighting and Materials Calls 68 v Contents Porting Texture Calls 73 Translating tevdef() 75 Translating texdef() 76 Translating texgen() 78 Texturing in OpenGL: An Example 79 Porting Picking Calls 81 Porting Feedback Calls 87 Porting RealityEngine Graphics Features 90 OpenGL Extensions 94 4. Using the Auxiliary Library to Replace Windowing and Event Handling Calls 95 Running a Program That Uses the Auxiliary Library 95 Windowing 96 Replacing prefposition() with auxInitPosition() 96 Porting Display Mode Initialization Calls with auxInitDisplayMode() 96 Replacing winopen() with auxInitWindow() 98 Windowing with the Auxiliary Library: Example Program 98 Event Handling: Replacing qdevice(), qtest(), and qread() 99 Handling Redraw Events 99 Handling Keyboard Input 101 Handling Mouse Events 102 Input Handling with the Auxiliary Library: Example Program 103 Managing Background Events 106 Using Color-Index Mode 106 Other Auxiliary Library Routines 107 5. Mixed-Model Programming 109 What Is a Mixed-Model Program? 109 Porting IRIS GL Mixed-Model Programs 110 Two Choices For Mixed-Model Programming 110 Using Xt and a Widget Set 111 Using Xlib 111 vi Contents Some General Hints on Mixed-Model Programming 112 You Can’t Change Window Depth and Display Mode 112 Installing Color Maps 112 Fonts and Strings 112 Porting to Mixed-Model Using Xt and a Widget Set 114 What You Need to Know About Xt and IRIS IM 115 You Don’t Have to Use IRIS IM 116 What You Need to Replace with X 117 Using the OpenGL Widget 117 Other Information Sources for Mixed-Model Programming 122 Mixed-Model Programming Using Xlib and OpenGL GLX Commands 122 Code Example: Opening a Window with OpenGL GLX 123 X Color Maps 125 A Sample X Event Loop 125 A. OpenGL Commands and Their IRIS GL Equivalents 127 B. Differences Between OpenGL and IRIS GL 165 C. Some Important OpenGL Basics 179 OpenGL Command Names 179 OpenGL Defined Types 181 Error Handling 181 D. Example OpenGL Program with the Auxiliary Library 183 E. Example Mixed-Model Program with WorkProc 187 F. Example Mixed-Model Programs With Xlib 197 Example One: iobounce.c 197 IRIS GL Version 197 OpenGL Version of iobounce.c 200 Example Two: zrgb.c 207 IRIS GL Version of zrgb.c 207 OpenGL version of zrgb.c 213 Index 223 vii List of Figures Figure 3-1 A Generic IRIS GL Translation 23 Figure 3-2 A Generic OpenGL Translation 23 Figure 3-3 An OpenGL Matrix Example 23 Figure 3-4 Drawing Angles: IRIS GL vs. OpenGL 42 ix List of Tables Table 3-1 State Attribute Groups 17 Table 3-2 Calls for Clearing the Screen 21 Table 3-3 Matrix Operations 24 Table 3-4 Matrix Modes 25 Table 3-5 Arguments for Transformation Matrix Queries 26 Table 3-6 Viewport Calls 28 Table 3-7 Clipping Plane Calls 29 Table 3-8 Calls for Drawing Quadrics 30 Table 3-9 Calls for Drawing Primitives 32 Table 3-10 Valid Commands inside a Begin/End Structure 33 Table 3-11 Calls for Drawing Points 34 Table 3-12 Calls for Drawing Lines 35 Table 3-13 Calls for Drawing Polygons 36 Table 3-14 Polygon Modes 37 Table 3-15 Polygon Stipple Calls 38 Table 3-16 Tessellated Polygon Calls 40 Table 3-17 Calls for Drawing Triangles 41 Table 3-18 Calls for Drawing Arcs and Circles 41 Table 3-19 Calls for Drawing Spheres 43 Table 3-20 Color Calls 44 Table 3-21 Shading and Dithering 45 Table 3-22 Pixel Operations 46 Table 3-23 Calls for Managing Fog 48 Table 3-24 Fog Parameters 49 Table 3-25 Fog Modes 50 Table 3-26 Calls for Managing NURBS Objects 52 Table 3-27 Calls for Drawing NURBS Curves 53 xi Table 3-28 NURBS Curve Types 53 Table 3-29 Calls for Drawing NURBS Trimming Curves 54 Table 3-30 Calls for Drawing NURBS Surfaces 54 Table 3-31 NURBS Surface Types 54 Table 3-32 Blending Calls 59 Table 3-33 Blending Factors 59 Table 3-34 Alpha Test Functions 60 Table 3-35 Calls to Draw Antialiased Primitives 60 Table 3-36 Accumulation Buffer Calls 62 Table 3-37 Accumulation Buffer Operations 62 Table 3-38 Stencil Operations 63 Table 3-39 Display List Commands 64 Table 3-40 Lighting and Materials Commands 69 Table 3-41 Material Definition Parameters 69 Table 3-42 Lighting Model Parameters 70 Table 3-43 Light Parameters 71 Table 3-44 Texture Commands 74 Table 3-45 Texture Environment Options 75 Table 3-46 IRIS GL and OpenGL Texture Parameters 77 Table 3-47 Values for IRIS GL and OpenGL Texture Parameters 77 Table 3-48 Texture Coordinate Names 78 Table 3-49 Texture Generation Modes and Planes 78 Table 3-50 Calls for Picking 81 Table 3-51 Feedback Calls 87 Table 3-52 RealityEngine Calls 90 Table 4-1 auxInitDisplayMode() Arguments and IRIS GL Command Equivalents 97 Table A-1 IRIS GL Commands and Their OpenGL Equivalents 127 Table C-1 Command Suffixes and Corresponding Argument Types 179 Table C-2 OpenGL Equivalents to C Data Types 181 Table C-3 glGetError() Return Values 182 xii About This Guide This guide tells you how to port your existing IRIS GL™ code to OpenGL™. It describes how to use the automatic translation script (called toogl), lists OpenGL equivalents for IRIS GL calls, describes how to reimplement IRIS GL windowing code with X and IRIS IM™ (IRIS IM is Silicon Graphics’ port of the industry-standard OSF/Motif™ software), and gives you the basics of what you need to know about X. This book is intended for developers who have been using IRIS GL. It is not an introduction to graphics programming and it is not comprehensive OpenGL documentation.