---

Introduction to OpenGL Programming Guide for Mac OS X

Contents:

Who Should Read This Document?
Organization of This Document
See Also

OpenGL Programming Guide for Mac OS X describes the Apple implementation of the OpenGL graphics standard in Mac OS X and shows how to use this implementation effectively to achieve stunning 3D graphics. OpenGL is an open, cross-platform, three-dimensional (3D) graphics standard with broad industry support. OpenGL greatly eases the task of writing real-time 2D or 3D graphics applications by providing a mature, well-documented graphics processing pipeline that supports the abstraction of current and future hardware accelerators.

OpenGL was developed by Silicon Graphics, Inc. (SGI). It is based on the SGI IRIS Graphics Library, first released in 1992. As an open standard, it is now controlled by the OpenGL Architecture Review Board (ARB), a consortium whose members include many of the major companies in the computer graphics industry, one of which is Apple.

OpenGL is an excellent choice for 3D graphics development on the Macintosh platform because it offers the following:

• Reliable implementation. Each implementation of OpenGL, including the Apple one, adheres to the OpenGL specification and must pass a set of conformance tests.

• Industry acceptance. Besides OpenGL for Mac OS X, there are OpenGL implementations for Windows, Linux, Irix, Solaris, and many game consoles.

• Performance. OpenGL uses available graphics processing hardware features to improve rendering speeds.

• Controlled evolution. OpenGL extensions enable developers to take advantage of hardware-specific improvements as they become available. Successful innovations are automatically incorporated into the Apple implementation.

• Full feature set. OpenGL provides hundreds of graphics routines that you use to define objects and apply transformations to them. It also provides routines that let you package data so that it uses the least amount of resources, thereby optimizing performance.

• Platform independence. The Apple implementation of OpenGL is cross-platform, which means that you can leverage your Mac OS X development efforts onto other systems. The OpenGL core functionality abstracts hardware details and guarantees consistent presentation on any compliant hardware and software configuration.

Who Should Read This Document?

Any developer who is familiar with OpenGL code and wants to run OpenGL programs in Mac OS X will want to read this document. OpenGL provides the API that communicates with the graphics hardware. Apple provides APIs that communicate with the Mac OS X windowing system. By reading this guide, you'll see how to use the Apple APIs to draw your OpenGL content onscreen from within a Cocoa or Carbon application. The book discusses the essential concepts for understanding the Apple OpenGL interfaces used for procedural C and Objective-C, and provides techniques and tips for getting the best performance possible on the platform.

This guide assumes that you are an experienced OpenGL programmer who wants to create Mac OS X software that has real-time 2D or 3D graphics. Although this guide provides some advice on optimizing OpenGL code, it does not provide entry-level information on how to use the OpenGL API maintained by the OpenGL Architecture Review Board (ARB). If you are unfamiliar with OpenGL, first read the following programming guide and consult the companion reference as needed:

• OpenGL Programming Guide, by the OpenGL Architecture Review Board; otherwise known as "The Redbook.”

• OpenGL Reference Pages.

Organization of This Document

This programming guide contains the following chapters:

• “OpenGL on the Mac Platform” discusses fundamental concepts for understanding how to use the Apple implementation of OpenGL, describes the graphics layers and programming interfaces, introduces essential terminology, and provides an overview of an OpenGL program running in Mac OS X.

• “Drawing to a Window or View” shows the basics of onscreen drawing using the CGL, AGL, and Cocoa APIs.

• “Drawing to the Full Screen” describes how to use the CGL, AGL, and Cocoa APIs for full-screen drawing, and includes information on adjusting the display mode.

• “Drawing Offscreen” shows how to draw to GPU memory, offscreen windows, pixel buffers, and framebuffer objects.

• “Determining the OpenGL Capabilities Supported by the Hardware” provides information on how to detect which version of OpenGL is available on a system and which features are supported by the hardware.

• “Techniques for Working with Rendering Contexts” shows how to create and update rendering contexts, set a context to a specific display, and share contexts.

• “Techniques for Choosing Attributes” discusses which render and buffer attributes to use and which to avoid, and which to choose to achieve specific objectives.

• “Techniques for Working with Vertex Data” provides guidelines, describes the data path, and shows how to optimize vertex data throughput.

• “Techniques for Working with Texture Data” provides guidelines, describes the data path, shows how to use images as textures, and discusses how to optimize texture data throughput.

• “Techniques for Scene Anti-Aliasing” describes the primary methods provided by anti-aliasing hardware and shows how to use hints that indicate which method you prefer.

• “Multithreading and OpenGL” provides guidelines for multithreading and discusses effective program designs.

• “Improving Performance” discusses best practices and shows how to analyze performance.

This programming guide contains these appendixes:

• “OpenGL Functionality by Version” contains tables that summarize new functionality and, in the online versions of this document, provides links to the OpenGL specification that describes the functionality in detail.

• “Setting Up Function Pointers to OpenGL Routines” describes how to obtain function pointers to arbitrary OpenGL entry points.

• “Quartz Display Services and Full-Screen Mode” shows how to use the Quartz Display Services API to accomplish a number of tasks that are useful in full-screen mode.

The “Glossary” provides definitions for most of the terminology in the book. You can find definitions for those terms that are not in the glossary either on the OpenGL Foundation website http://www.opengl.org or in OpenGL Programming Guide ("The Redbook").

See Also

You'll want to keep these reference documents handy as you develop your OpenGL program for Mac OS X:

• NSOpenGLView Class Reference, NSOpenGLContext Class Reference, NSOpenGLPixelBuffer Class Reference, and NSOpenGLPixelFormat Class Reference provide a complete description of the classes and methods needed to draw OpenGL content in a Cocoa application.

• AGL Reference provides a complete description of the functions needed to draw OpenGL content in a Carbon application.

• CGL Reference describes functions in the Core OpenGL API, which can be used to draw OpenGL content to the full screen from either a Cocoa or Carbon application.

• OpenGL Extensions Guide provides information about OpenGL extensions supported in Mac OS X.

• Cocoa Drawing Guide explains how to draw 2D content in a Cocoa application and also contains information on how to set up OpenGL drawing.

You can download sample applications that demonstrate how to use Apple APIs for OpenGL drawing from the ADC Reference Library.

The OpenGL Foundation website, http://www.opengl.org, provides information on OpenGL commands, the Architecture Review Board, logo requirements, OpenGL news, and many other topics. It's a site that you'll want to visit regularly. Among the many resources it provides, the following are important reference documents for OpenGL developers:

• OpenGL 2.0 Specification provides detailed information for every OpenGL command.

• OpenGL Reference describes GL, the main OpenGL library.

• OpenGL GLU Reference describes the OpenGL Utility Library, which contains graphical extensions based entirely on GL functions.

• OpenGL GLUT Reference describes the OpenGL Utility Toolkit, a standard API for performing operations associated with a windowing environment other than the Cocoa and Carbon environments.

• OpenGL API Code and Tutorial Listings provides code examples for fundamental tasks, such as modeling and texture mapping, as well as for advanced techniques, such as high dynamic range rendering (HDRR).

Although you don't need to learn how to use a shading language to write OpenGL programs for Mac OS X, it's a growing area that you may want to investigate. The Apple implementation of OpenGL supports shading programs should you want to incorporate them into your code.

• OpenGL Shading Language, by Randi J. Rost, is an excellent guide for those who want to write programs that compute surface properties (also known as shaders).

• Core Image Programming Guide describes how to use the Core Image API to access built-in image processing filters and how to write your own filters. The appendix Core Image Kernel Language, describes the shading language that's supported in Core Image and provides examples of kernel routines.

• The Quartz Composer application, available in /Developer/Applications/Graphics Tools/, has a kernel patch that you can use to test kernel routines that you write using the Core Image kernel language.

---