---

Programming Interfaces

The programming interfaces that you'll use fall into two categories—those specific to the Macintosh platform and those defined by the OpenGL Architecture Review Board. The Apple-specific programming interfaces are what Cocoa and Carbon applications use to communicate with the Mac OS X windowing system. These APIs don't create OpenGL content, they simply manage content, direct it to a drawing destination (onscreen or offscreen), and control various aspects of the rendering operation. The OpenGL APIs actually create content. OpenGL routines accept vertex, pixel, and texture data and assemble the data to create content that has the illusion of being three-dimensional. The final content resides in a framebuffer, where it will languish unseen by the user unless your application uses a windowing-system specific API to direct the content onscreen.

In this section:

OpenGL APIs Specific to Mac OS X
Apple-Implemented OpenGL Libraries

OpenGL APIs Specific to Mac OS X

Mac OS X offers three easy-to-use application programming interfaces (APIs) that are specific to the Macintosh platform: the NSOpenGL classes, the AGL API, and the CGL API. Throughout this document, these three APIs are referred to as the Apple-specific OpenGL APIs.

Cocoa provides four classes specifically for OpenGL—NSOpenGLView, NSOpenGLContext, NSOpenGLPixelFormat, and NSOpenGLPixelBuffer. The NSOpenGLView class provides easy access to a basic OpenGL context that can be set up in Interface Builder. NSOpenGLView is a subclass of NSView and has the expected facilities to display OpenGL content in a view. NSOpenGLContext and NSOpenGLPixelFormat, along with NSView, are the building blocks for the NSOpenGLView class. Applications that subclass NSOpenGLView do not need to directly subclass NSOpenGLPixelFormat or NSOpenGLContext. Applications that need customization or flexibility, can subclass NSView. The NSOpenGLPixelBuffer class provides hardware-accelerated offscreen drawing. Using the NSOpenGL classes, you can also draw to the full screen.

For detailed information on the NSOpenGL classes, see the following reference documentation:

• NSOpenGLView Class Reference

• NSOpenGLContext Class Reference

• NSOpenGLPixelBuffer Class Reference

• NSOpenGLPixelFormat Class Reference

Apple Graphics Library (AGL) is the Apple interface to OpenGL for Carbon applications. It can be used by both Mach-O and CFM binaries, although CFM binaries are not recommended in Mac OS X because it's not possible to generate a universal binary with them. (A universal binary runs natively on both PowerPC and Intel-based Macintosh computers.) AGL supports drawing to the full screen as well as to Carbon windows and offscreen locations. In addition to the standard functionality, AGL provides full support for hardware-accelerated offscreen drawing, bitmap font rendering, and the ability to render content directly to a texture (also called render-to-texture functionality). The AGL API resides in the AGL framework. Applications must include the AGL.h header file (System/Library/Frameworks/AGL.framework/AGL.h) to access AGL functionality. AGL Reference provides a complete description of this API.

The Core OpenGL API (CGL) is the basis for the NSOpenGL classes and AGL. CGL offers the most direct access to system functionality and provides the highest level of graphics performance and control for drawing to the full screen. CGL is windowing-system agnostic but is accessible from both Cocoa and Carbon applications. The CGL API resides in the OpenGL framework. Applications must include the OpenGL.h header file (System/Library/Frameworks/OpenGL.framework/OpenGL.h) to access CGL functionality. CGL Reference provides a complete description of this API.

Apple-Implemented OpenGL Libraries

Mac OS X also provides the full suite of graphics libraries that are part of every implementation of OpenGL: GL, GLU, GLUT, and GLX. Two of these—GL and GLU—provide low-level drawing support. The other two—GLUT and GLX—support drawing to the screen.

Your application typically interfaces directly with the core OpenGL library (GL), the OpenGL Utility library (GLU), and the OpenGL Utility Toolkit (GLUT). The GL library provides a low-level modular API that allows you to define graphical objects. It supports the core functions that are common to all OpenGL implementations, as mandated by the OpenGL specification. It provides support for two fundamental types of graphics primitives: objects defined by sets of vertices, such as line segments and simple polygons, and objects that are pixel-based images, such as filled rectangles and bitmaps. The GL API does not handle complex custom graphical objects; your application must decompose them into simpler geometries.

The GLU library combines functions from the GL library to support more advanced graphics features. It runs on all conforming implementations of OpenGL. GLU is capable of creating and handling complex polygons (including quartic equations), processing nonuniform rational b-spline curves (NURBs), scaling images, and decomposing a surface to a series of polygons (tessellation).

The GLUT library provides a cross-platform API for performing operations associated with the user windowing environment—displaying and redrawing content, handling events, and so on. It is implemented on most UNIX, Linux, and Windows platforms. As such, any code that you write with GLUT can be reused across multiple platforms. However, such code is constrained by a generic set of user interface elements and event-handling options. This book does not show how to use GLUT. If you are interested in GLUT, see the sample code in the ADC Reference Library. GLUT Basics is a simple example that will get you started.

GLX is an OpenGL extension that supports using OpenGL within a window provided by the X Window system. X11 for Mac OS X is available as an optional installation using the Mac OS X installation DVD. (It's not shown in Figure 1-3.) See OpenGL Programming for the X Window System, published by Addison Wesley for more information.

This document does not show how to use these libraries. For detailed information, either go to the OpenGL Foundation website http://www.opengl.org, or see the most recent version of "The Redbook"—OpenGL Programming Guide, published by Addison Wesley.

---