OpenGL Programming Guide for Mac OS X - Apple

  • Published on

  • View

  • Download


OpenGL Programming Guide for Mac OS X - Apple


<ul><li><p>OpenGL Programming Guide for Mac OS XGraphics &amp; Animation: 3D Drawing</p><p>2011-06-06</p></li><li><p>Apple Inc. 2004, 2011 Apple Inc.All rights reserved.</p><p>No part of this publication may be reproduced,stored in a retrieval system, or transmitted, inany form or by any means, mechanical,electronic, photocopying, recording, orotherwise, without prior written permission ofApple Inc., with the following exceptions: Anyperson is hereby authorized to storedocumentation on a single computer forpersonal use only and to print copies ofdocumentation for personal use provided thatthe documentation contains Apples copyrightnotice.</p><p>The Apple logo is a trademark of Apple Inc.</p><p>No licenses, express or implied, are grantedwith respect to any of the technology describedin this document. Apple retains all intellectualproperty rights associated with the technologydescribed in this document. This document isintended to assist application developers todevelop applications only for Apple-labeledcomputers.</p><p>Apple Inc.1 Infinite LoopCupertino, CA 95014408-996-1010</p><p>.Mac is a registered service mark of Apple Inc.</p><p>Apple, the Apple logo, Carbon, Cocoa, iChat,Instruments, iPhoto, Logic, Mac, Mac OS,Macintosh, Objective-C, Pages, Quartz, andXcode are trademarks of Apple Inc., registeredin the United States and other countries.</p><p>OpenCL is a trademark of Apple Inc.</p><p>DEC is a trademark of Digital EquipmentCorporation.</p><p>IOS is a trademark or registered trademark ofCisco in the U.S. and other countries and is usedunder license.</p><p>OpenGL is a registered trademark of SiliconGraphics, Inc.</p><p>UNIX is a registered trademark of The OpenGroup</p><p>X Window System is a trademark of theMassachusetts Institute of Technology.</p><p>Even though Apple has reviewed this document,APPLE MAKES NO WARRANTY OR REPRESENTATION,EITHER EXPRESS OR IMPLIED, WITH RESPECT TOTHIS DOCUMENT, ITS QUALITY, ACCURACY,MERCHANTABILITY, OR FITNESS FOR A PARTICULARPURPOSE. AS A RESULT, THIS DOCUMENT IS</p><p>PROVIDED AS IS, AND YOU, THE READER, AREASSUMING THE ENTIRE RISK AS TO ITS QUALITYAND ACCURACY.</p><p>IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT,INDIRECT, SPECIAL, INCIDENTAL, ORCONSEQUENTIAL DAMAGES RESULTING FROM ANYDEFECT OR INACCURACY IN THIS DOCUMENT, evenif advised of the possibility of such damages.</p><p>THE WARRANTY AND REMEDIES SET FORTH ABOVEARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORALOR WRITTEN, EXPRESS OR IMPLIED. No Appledealer, agent, or employee is authorized to makeany modification, extension, or addition to thiswarranty.</p><p>Some states do not allow the exclusion or limitationof implied warranties or liability for incidental orconsequential damages, so the above limitation orexclusion may not apply to you. This warranty givesyou specific legal rights, and you may also haveother rights which vary from state to state.</p></li><li><p>Contents</p><p>Introduction About OpenGL for Mac OS X 13</p><p>At a Glance 13OpenGL Is a C-based, Platform-Neutral API 14Different Rendering Destinations Require Different Setup Commands 14OpenGL on Macs Exists in a Heterogenous Environment 14OpenGL Helps Applications Harness the Power of Graphics Processors 14Concurrency in OpenGL Applications Requires Additional Effort 15Performance Tuning Allows Your Application to Provide an Exceptional User Experience 15</p><p>How to Use This Document 15Prerequisites 16See Also 16</p><p>Chapter 1 OpenGL on the Mac Platform 19</p><p>OpenGL Concepts 19OpenGL Implements a Client-Server Model 20OpenGL Commands Can Be Executed Asynchronously 20OpenGL Commands Are Executed In Order 21OpenGL Copies Client Data at Call-Time 21OpenGL Relies on Platform-Specific Libraries For Critical Functionality 21</p><p>OpenGL in Mac OS X 21Accessing OpenGL Within Your Application 23</p><p>OpenGL APIs Specific to Mac OS X 23Apple-Implemented OpenGL Libraries 24</p><p>Terminology 25Renderer 25Renderer and Buffer Attributes 25Pixel Format Objects 25OpenGL Profiles 26Rendering Contexts 26Drawable Objects 26Virtual Screens 27Offline Renderer 31</p><p>Running an OpenGL Program in Mac OS X 31Making Great OpenGL Applications on the Macintosh 32</p><p>Chapter 2 Drawing to a Window or View 35</p><p>General Approach 35Drawing to a Cocoa View 36</p><p>Drawing to an NSOpenGLView Class: A Tutorial 37</p><p>32011-06-06 | 2004, 2011 Apple Inc. All Rights Reserved.</p></li><li><p>Drawing OpenGL Content to a Custom View 39</p><p>Chapter 3 Drawing to the Full Screen 43</p><p>Creating a Full-Screen Application 43</p><p>Chapter 4 Drawing Offscreen 45</p><p>Rendering to a Framebuffer Object 45Using a Framebuffer Object as a Texture 46Using a Framebuffer Object as an Image 49</p><p>Rendering to a Pixel Buffer 51Setting Up a Pixel Buffer for Offscreen Drawing 51Using a Pixel Buffer as a Texture Source 52Rendering to a Pixel Buffer on a Remote System 53</p><p>Chapter 5 Choosing Renderer and Buffer Attributes 55</p><p>OpenGL Profiles (Mac OS X v10.7) 55Buffer Size Attribute Selection Tips 56Ensuring That Back Buffer Contents Remain the Same 56Ensuring a Valid Pixel Format Object 57Ensuring a Specific Type of Renderer 58Ensuring a Single Renderer for a Display 58Allowing Offline Renderers 59OpenCL 60Deprecated Attributes 60</p><p>Chapter 6 Working with Rendering Contexts 63</p><p>Update the Rendering Context When the Renderer or Geometry Changes 63Tracking Renderer Changes 64Updating a Rendering Context for a Custom Cocoa View 64</p><p>Context Parameters Alter the Contexts Behavior 66Swap Interval Allows an Application to Synchronize Updates to the Screen Refresh 66Surface Opacity Specifies How the OpenGL Surface Blends with Surfaces Behind It 66Surface Drawing Order Specifies the Position of the OpenGL Surface Relative to the Window67Determining Whether Vertex and Fragment Processing Happens on the GPU 67Controlling the Back Buffer Size 68</p><p>Sharing Rendering Context Resources 69</p><p>Chapter 7 Determining the OpenGL Capabilities Supported by the Renderer 73</p><p>Detecting Functionality 73Guidelines for Code That Checks for Functionality 76</p><p>42011-06-06 | 2004, 2011 Apple Inc. All Rights Reserved.</p><p>CONTENTS</p></li><li><p>OpenGL Renderer Implementation-Dependent Values 77</p><p>Chapter 8 OpenGL Application Design Strategies 79</p><p>Visualizing OpenGL 79Designing a High-Performance OpenGL Application 81Update OpenGL Content Only When Your Data Changes 83</p><p>Synchronize with the Screen Refresh Rate 85Avoid Synchronizing and Flushing Operations 85</p><p>Using glFlush Effectively 86Avoid Querying OpenGL State 86Use Fences for Finer-Grained Synchronization 87</p><p>Allow OpenGL to Manage Your Resources 88Use Double Buffering to Avoid Resource Conflicts 88Be Mindful of OpenGL State Variables 90Replace State Changes with OpenGL Objects 90Use Optimal Data Types and Formats 90Use OpenGL Macros 91</p><p>Chapter 9 Best Practices for Working with Vertex Data 93</p><p>Understand How Vertex Data Flows Through OpenGL 93Techniques for Handling Vertex Data 95Vertex Buffers 96</p><p>Using Vertex Buffers 96Buffer Usage Hints 98Flush Buffer Range Extension 100</p><p>Vertex Array Range Extension 100Vertex Array Object 102</p><p>Chapter 10 Best Practices for Working with Texture Data 105</p><p>Using Extensions to Improve Texture Performance 106Pixel Buffer Objects 107Apple Client Storage 110Apple Texture Range and Rectangle Texture 110Combining Client Storage with Texture Ranges 112</p><p>Optimal Data Formats and Types 113Working with NonPower-of-Two Textures 113Creating Textures from Image Data 115</p><p>Creating a Texture from a Cocoa View 116Creating a Texture from a Quartz Image Source 118Getting Decompressed Raw Pixel Data from a Source Image 119</p><p>Downloading Texture Data 119Double Buffering Texture Data 120</p><p>52011-06-06 | 2004, 2011 Apple Inc. All Rights Reserved.</p><p>CONTENTS</p></li><li><p>Chapter 11 Customizing the OpenGL Pipeline with Shaders 123</p><p>Shader Basics 125Advanced Shading Extensions 126</p><p>Transform Feedback 126GPU Shader 4 126Geometry Shaders 127Uniform Buffers 127</p><p>Chapter 12 Techniques for Scene Anti-Aliasing 129</p><p>Guidelines 129General Approach 130Hinting for a Specific Anti-Aliasing Technique 131</p><p>Chapter 13 Concurrency and OpenGL 133</p><p>Identifying Whether an OpenGL Application Can Benefit from Concurrency 133OpenGL Restricts Each Context to a Single Thread 134Strategies for Implementing Concurrency in OpenGL Applications 134Multithreaded OpenGL 135Perform OpenGL Computations in a Worker Task 136Use Multiple OpenGL Contexts 137Guidelines for Threading OpenGL Applications 138</p><p>Chapter 14 Tuning Your OpenGL Application 141</p><p>Gathering and Analyzing Baseline Performance Data 142Using OpenGL Driver Monitor to Measure Stalls 147</p><p>Identifying Bottlenecks with Shark 147</p><p>Appendix A Legacy OpenGL Functionality by Version 149</p><p>Version 1.1 149Version 1.2 150Version 1.3 150Version 1.4 151Version 1.5 152Version 2.0 152Version 2.1 152</p><p>Appendix B Updating an Application to Support the OpenGL 3.2 Core Specification 153</p><p>Removed Functionality 153Extension Changes on Mac OS X 153</p><p>62011-06-06 | 2004, 2011 Apple Inc. All Rights Reserved.</p><p>CONTENTS</p></li><li><p>Appendix C Setting Up Function Pointers to OpenGL Routines 155</p><p>Obtaining a Function Pointer to an Arbitrary OpenGL Entry Point 155Initializing Entry Points 156</p><p>Document Revision History 159</p><p>Glossary 163</p><p>72011-06-06 | 2004, 2011 Apple Inc. All Rights Reserved.</p><p>CONTENTS</p></li><li><p>82011-06-06 | 2004, 2011 Apple Inc. All Rights Reserved.</p><p>CONTENTS</p></li><li><p>Figures, Tables, and Listings</p><p>Chapter 1 OpenGL on the Mac Platform 19</p><p>Figure 1-1 OpenGL provides the reflections in iChat 19Figure 1-2 OpenGL client-server model 20Figure 1-3 Graphics platform model 20Figure 1-4 MacOS X OpenGL driver model 22Figure 1-5 Layers of OpenGL for Mac OS X 22Figure 1-6 The programing interfaces used for OpenGL content 23Figure 1-7 Data flow through OpenGL 27Figure 1-8 A virtual screen displays what the user sees 28Figure 1-9 Two virtual screens 29Figure 1-10 A virtual screen can represent more than one physical screen 29Figure 1-11 Two virtual screens and two graphics cards 30Figure 1-12 The flow of data through OpenGL 31</p><p>Chapter 2 Drawing to a Window or View 35</p><p>Figure 2-1 OpenGL content in a Cocoa view 35Figure 2-2 The output from the Golden Triangle program 39Listing 2-1 The interface for MyOpenGLView 37Listing 2-2 Include OpenGL/gl.h 37Listing 2-3 The drawRect: method for MyOpenGLView 38Listing 2-4 Code that draws a triangle using OpenGL commands 38Listing 2-5 The interface for a custom OpenGL view 40Listing 2-6 The initWithFrame:pixelFormat: method 40Listing 2-7 The lockFocus method 41Listing 2-8 The drawRect method for a custom view 41Listing 2-9 Detaching the context from a drawable object 41</p><p>Chapter 3 Drawing to the Full Screen 43</p><p>Figure 3-1 Drawing OpenGL content to the full screen 43</p><p>Chapter 4 Drawing Offscreen 45</p><p>Listing 4-1 Setting up a framebuffer for texturing 48Listing 4-2 Setting up a renderbuffer for drawing images 50</p><p>Chapter 5 Choosing Renderer and Buffer Attributes 55</p><p>Table 5-1 Renderer types and pixel format attributes 58</p><p>92011-06-06 | 2004, 2011 Apple Inc. All Rights Reserved.</p></li><li><p>Listing 5-1 Using the CGL API to create a pixel format object 57Listing 5-2 Setting an NSOpenGLContext object to use a specific display 59Listing 5-3 Setting a CGL context to use a specific display 59</p><p>Chapter 6 Working with Rendering Contexts 63</p><p>Figure 6-1 A fixed size back buffer and variable size front buffer 69Figure 6-2 Shared contexts attached to the same drawable object 69Figure 6-3 Shared contexts and more than one drawable object 70Listing 6-1 Handling context updates for a custom view 64Listing 6-2 Using CGL to set up synchronization 66Listing 6-3 Using CGL to set surface opacity 67Listing 6-4 Using CGL to set surface drawing order 67Listing 6-5 Using CGL to check whether the GPU is processing vertices and fragments 68Listing 6-6 Using CGL to set up back buffer size control 68Listing 6-7 Setting up an NSOpenGLContext object for sharing 70Listing 6-8 Setting up a CGL context for sharing 71</p><p>Chapter 7 Determining the OpenGL Capabilities Supported by the Renderer 73</p><p>Table 7-1 Common OpenGL renderer limitations 77Table 7-2 OpenGL shader limitations 77Listing 7-1 Checking for OpenGL functionality 74Listing 7-2 Setting up a valid rendering context to get renderer functionality information 75</p><p>Chapter 8 OpenGL Application Design Strategies 79</p><p>Figure 8-1 OpenGL graphics pipeline 80Figure 8-2 OpenGL client-server architecture 81Figure 8-3 Application model for managing resources 82Figure 8-4 Single-buffered vertex array data 89Figure 8-5 Double-buffered vertex array data 89Listing 8-1 Setting up a Core Video display link 84Listing 8-2 Setting up synchronization 85Listing 8-3 Disabling state variables 90Listing 8-4 Using CGL macros 91</p><p>Chapter 9 Best Practices for Working with Vertex Data 93</p><p>Figure 9-1 Vertex data sets can be quite large 93Figure 9-2 Vertex data path 94Figure 9-3 Immediate mode requires a copy of the current vertex data 94Listing 9-1 Submitting vertex data using glDrawElements. 94Listing 9-2 Using the vertex buffer object extension with dynamic data 97Listing 9-3 Using the vertex buffer object extension with static data 98</p><p>102011-06-06 | 2004, 2011 Apple Inc. All Rights Reserved.</p><p>FIGURES, TABLES, AND LISTINGS</p></li><li><p>Listing 9-4 Geometry with different usage patterns 98Listing 9-5 Using the vertex array range extension with dynamic data 101Listing 9-6 Using the vertex array range extension with static data 102</p><p>Chapter 10 Best Practices for Working with Texture Data 105</p><p>Figure 10-1 Textures add realism to a scene 105Figure 10-2 Texture data path 105Figure 10-3 Data copies in an OpenGL program 106Figure 10-4 The client storage extension eliminates a data copy 110Figure 10-5 The texture range extension eliminates a data copy 111Figure 10-6 Combining extensions to eliminate data copies 112Figure 10-7 Normalized and non-normalized coordinates 114Figure 10-8 An image segmented into power-of-two tiles 115Figure 10-9 Using an image as a texture for a cube 116Figure 10-10 Single-buffered data 121Figure 10-11 Double-buffered data 121Listing 10-1 Using texture extensions for a rectangular texture 112Listing 10-2 Using texture extensions for a power-of-two texture 113Listing 10-3 Building an OpenGL texture from an NSView object 116Listing 10-4 Using a Quartz image as a texture source 118Listing 10-5 Getting pixel data from a source image 119Listing 10-6 Code that downloads texture data 120</p><p>Chapter 11 Customizing the OpenGL Pipeline with Shaders 123</p><p>Figure 11-1 OpenGL fixed-function pipeline 123Figure 11-2 OpenGL shader pipeline 124Listing 11-1 Loading a Shader 125</p><p>Chapter 12 Techniques for Scene Anti-Aliasing 129</p><p>Table 12-1 Anti-aliasing hints 132</p><p>Chapter 13 Concurrency and OpenGL 133</p><p>Figure 13-1 CPU processing and OpenGL on separate threads 136Figure 13-2 Two contexts on separate threads 138Listing 13-1 Enabling the multithreaded OpenGL engine 135</p><p>Chapter 14 Tuning Your OpenGL Application 141</p><p>Figure 14-1 Output produced by the top application 143Figure 14-2 The OpenGL Profiler window 144Figure 14-3 A statistics window 145</p><p>112011-06-06 | 2004, 2011 Apple Inc. All Rights Reserved.</p><p>FIGURES, TABLES, AND LISTINGS</p></li><li><p>Figure 14-4 A Trace window 146Figure 14-5 The graph view in OpenGL Driver Monitor 147</p><p>Appendix A Legacy OpenGL Functionality by Version 149</p><p>Table A-1 Functionality added in OpenGL 1.1 149Table...</p></li></ul>


View more >