OpenGL Programming Guide for Mac OS X 2006-10-03 Intel and Intel Core are registered Apple Computer, Inc. trademarks of Intel Corportation or its © 2004, 2006 Apple Computer, Inc. subsidiaries in the United States and other All rights reserved. countries. OpenGL is a registered trademark of Silicon No part of this publication may be Graphics, Inc. reproduced, stored in a retrieval system, or transmitted, in any form or by any means, PowerPC and and the PowerPC logo are mechanical, electronic, photocopying, trademarks of International Business recording, or otherwise, without prior Machines Corporation, used under license written permission of Apple Computer, Inc., therefrom. with the following exceptions: Any person X Window System is a trademark of the is hereby authorized to store documentation Massachusetts Institute of Technology. on a single computer for personal use only Simultaneously published in the United and to print copies of documentation for States and Canada. personal use provided that the documentation contains Apple’s copyright Even though Apple has reviewed this document, APPLE MAKES NO WARRANTY OR notice. REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS The Apple logo is a trademark of Apple DOCUMENT, ITS QUALITY, ACCURACY, Computer, Inc. MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. AS A RESULT, THIS Use of the “keyboard” Apple logo DOCUMENT IS PROVIDED “AS IS,” AND YOU, THE READER, ARE ASSUMING THE (Option-Shift-K) for commercial purposes ENTIRE RISK AS TO ITS QUALITY AND without the prior written consent of Apple ACCURACY. may constitute trademark infringement and IN NO EVENT WILL APPLE BE LIABLE FOR unfair competition in violation of federal DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES and state laws. RESULTING FROM ANY DEFECT OR INACCURACY IN THIS DOCUMENT, even if No licenses, express or implied, are granted advised of the possibility of such damages. with respect to any of the technology THE WARRANTY AND REMEDIES SET described in this document. Apple retains FORTH ABOVE ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL OR WRITTEN, all intellectual property rights associated EXPRESS OR IMPLIED. No Apple dealer, agent, with the technology described in this or employee is authorized to make any document. This document is intended to modification, extension, or addition to this warranty. assist application developers to develop Some states do not allow the exclusion or applications only for Apple-labeled or limitation of implied warranties or liability for Apple-licensed computers. incidental or consequential damages, so the above limitation or exclusion may not apply to Every effort has been made to ensure that you. This warranty gives you specific legal rights, and you may also have other rights which the information in this document is vary from state to state. accurate. Apple is not responsible for typographical errors. Apple Computer, Inc. 1 Infinite Loop Cupertino, CA 95014 408-996-1010 Apple, the Apple logo, Carbon, Cocoa, ColorSync, iPhoto, Logic, Mac, Mac OS, Macintosh, Quartz, and Xcode are trademarks of Apple Computer, Inc., registered in the United States and other countries. Finder is a trademark of Apple Computer, Inc. Objective-C is a registered trademark of NeXT Software, Inc. Contents Introduction Introduction to OpenGL Programming Guide for Mac OS X 11 Who Should Read This Document? 12 Organization of This Document 12 See Also 13 Chapter 1 OpenGL on the Mac Platform 15 Structure of OpenGL in Mac OS X 16 Programming Interfaces 17 OpenGL APIs Specific to Mac OS X 17 Apple-Implemented OpenGL Libraries 18 Terminology 19 Renderer 19 Renderer and Buffer Attributes 19 Pixel Format Objects 20 Rendering Contexts 20 Drawable Objects 20 Virtual Screens 21 Running an OpenGL Program in Mac OS X 25 See Also 26 Chapter 2 Drawing to a Window or View 29 General Approach 29 Drawing to a Cocoa View 31 Drawing to an NSOpenGLView Class: A Tutorial 31 Drawing OpenGL Content to a Custom View 36 Drawing to a Carbon Window 39 What's Next 41 See Also 41 Chapter 3 Drawing to the Full Screen 43 General Approach 44 Using Cocoa to Create a Full-Screen Context 44 Using AGL to Create a Full-Screen Context 46 Using CGL to Create a Full-Screen Context 48 3 2006-10-03 | © 2004, 2006 Apple Computer, Inc. All Rights Reserved. CONTENTS Adjusting Display Modes 49 What's Next? 50 See Also 50 Chapter 4 Drawing Offscreen 51 Setting Up an Offscreen Drawable Object 51 Using a Hidden View or Window 53 Rendering to a Pixel Buffer 55 Setting Up a Pixel Buffer for Offscreen Drawing 56 Using a Pixel Buffer as a Texture Source 56 Rendering to a Pixel Buffer on a Remote System 58 Rendering to a Framebuffer Object 58 Drawing a Texture Offscreen 59 Drawing a Renderbuffer Image Offscreen 61 See Also 63 Chapter 5 Determining the OpenGL Capabilities Supported by the Hardware 65 Detecting Functionality 65 Guidelines for Code That Checks for Functionality 68 See Also 69 Chapter 6 Techniques for Working with Rendering Contexts 71 Context Parameters 71 Swap Interval 72 Surface Opacity 72 Surface Drawing Order 72 Vertex and Fragment Processing 73 Back Buffer Size Control 73 Updating a Rendering Context 74 Tracking Renderer Changes 75 Updating a Rendering Context for a Custom Cocoa View 75 Updating a Rendering Context for a Carbon Window 77 Updating Full-screen AGL and CGL Rendering Contexts 80 Sharing Rendering Contexts 81 See Also 84 Chapter 7 Techniques for Choosing Attributes 85 Buffer Size Attribute Selection Tips 85 Attributes that are not Recommended 86 Ensuring a Valid Pixel Format Object 86 Ensuring a Specific Type of Renderer 87 Ensuring a Single Renderer for a Display 88 4 2006-10-03 | © 2004, 2006 Apple Computer, Inc. All Rights Reserved. CONTENTS See Also 89 Chapter 8 Techniques for Working with Vertex Data 91 Best Practices for Working with Vertex Data 91 Using Extensions to Improve Performance 93 Vertex Array Range Extension 94 Vertex Buffer Object Extension 96 Fence Extension 98 Double Buffering Vertex Data 99 See Also 100 Chapter 9 Techniques for Working with Texture Data 103 Using Extensions to Optimize 104 Apple Client Storage 105 Apple Texture Range and Rectangle Texture 106 Combining Extensions 107 Optimal Data Formats and Types 109 Working with Non–Power-of-Two Textures 109 Creating Textures from Image Data 111 Creating a Texture from a Cocoa View 111 Creating a Texture from a Quartz Image Source 113 Downloading Texture Data 114 Double Buffering Texture Data 115 See Also 116 Chapter 10 Techniques for Scene Anti-Aliasing 119 Guidelines 119 General Approach 120 Hinting for a Specific Anti-Aliasing Technique 121 Setting Up Full Scene Anti-Aliasing 122 See Also 124 Chapter 11 Multithreading and OpenGL 125 Program Design 125 Guidelines for Threading OpenGL Applications 126 When Things Go Wrong 127 Threading APIs 128 See Also 128 Chapter 12 Improving Performance 129 Best Practices 130 5 2006-10-03 | © 2004, 2006 Apple Computer, Inc. All Rights Reserved. CONTENTS Use Flush and Finish Routines Effectively 130 Be Mindful of OpenGL State Variables 131 Draw Only When Necessary 132 Synchronize with the Screen Refresh Rate 133 Use OpenGL Macros 133 Use the CPU and the GPU Asynchronously 134 Use Appropriate Routines for Images and Pixel Data 135 Retrieve Error Information Only When Debugging 136 Use Optimal Data Types and Formats 136 Gathering and Analyzing Baseline Performance Data 136 Identifying Bottlenecks with Shark 141 See Also 141 Appendix A OpenGL Functionality by Version 143 Version 1.1 143 Version 1.2 144 Version 1.3 145 Version 1.4 145 Version 1.5 146 Version 2.0 146 Appendix B Setting Up Function Pointers to OpenGL Routines 147 Obtaining a Function Pointer to an Arbitrary OpenGL Entry Point 147 Initializing Entry Points 150 Appendix C Quartz Display Services and Full-Screen Mode 153 Displays and Display Modes 153 Fading the Display 155 Controlling the Pointer 158 See Also 158 Glossary 159 Document Revision History 163 6 2006-10-03 | © 2004, 2006 Apple Computer, Inc. All Rights Reserved. Figures, Tables, and Listings Chapter 1 OpenGL on the Mac Platform 15 Figure 1-1 OpenGL provides the reflections in iChat 15 Figure 1-2 Layers of OpenGL for Mac OS X 16 Figure 1-3 The programing interfaces used for OpenGL content 17 Figure 1-4 Data flow through OpenGL 21 Figure 1-5 A virtual screen displays what the user sees 22 Figure 1-6 Two virtual screens 23 Figure 1-7 A virtual screen can represent more than one physical screen 23 Figure 1-8 Two virtual screens and two graphics cards 24 Figure 1-9 The flow of data through OpenGL 25 Chapter 2 Drawing to a Window or View 29 Figure 2-1 OpenGL content in a Cocoa view (left) and a Carbon window (right) 29 Figure 2-2 The Classes pane 32 Figure 2-3 Subclassing NSOpenGLView 32 Figure 2-4 Creating files for MyOpenGLView 33 Figure 2-5 Dragging an NSOpenGLView object to a window 33 Figure 2-6 The Attributes pane in the inspector 34 Figure 2-7 The output from the Golden Triangle program 36 Listing 2-1 The interface for MyOpenGLView 34 Listing 2-2 Include OpenGL/gl.h 35 Listing 2-3 The drawRect: method for MyOpenGLView 35 Listing 2-4 Code that draws a triangle using OpenGL commands 35 Listing 2-5 The interface for a custom OpenGL view 37 Listing 2-6 The initWithFrame:pixelFormat: method 37 Listing 2-7 The lockFocus method 38 Listing 2-8 The drawRect method for a custom view 38 Listing 2-9 Detaching the context from a drawable object 38 Listing 2-10 Setting a Carbon window as a drawable object 40 Chapter 3 Drawing to the Full Screen 43 Figure 3-1 Drawing OpenGL content to the full screen 43 Listing 3-1 Using Cocoa to set up full-screen drawing 45 Listing 3-2 A function that sets up a full-screen context using AGL 46 Listing 3-3 Setting up a full-screen context using CGL 48 7 2006-10-03 | © 2004, 2006 Apple Computer, Inc.