Section 8.2. Apple Mac OS X

8.2. Apple Mac OS X

Besides GLUT, Apple fully supports three OpenGL interfaces specific to Apple platforms: CGL, NSOpenGL, and AGL. A description of supported Apple interfaces is available at the following Web site:

     http://developer.apple.com/qa/qa2001/qa1269.html 

CGL, or Core OpenGL, is the lowest-level of the three interfaces. It can't be used for windowed rendering but can be used for full-screen and offscreen rendering. NSOpenGL, available through Cocoa, is the most recent Apple interface. It presents an object-oriented interface using a set of Objective-C classes.

AGL is the primary OpenGL interface for Carbon applications. OpenGL^® Distilled focuses on this interface because of its widespread use, support for operating systems older than Mac OS X, and similarities to the WGL and GLX interfaces. AGL Reference documents the AGL interface. See the OpenGL section of the Apple Developer Connection Web site for this and other Apple-specific OpenGL information:

     http://developer.apple.com/graphicsimaging/opengl/ 

8.2.1. Creating Contexts

In AGL, you must specify a pixel format when creating a context. The pixel format describes the characteristics and capabilities of the renderer and drawing surface(s).

To obtain a list of pixel formats, call aglChoosePixelFormat().

AGLPixelFormat aglChoosePixelFormat( const AGLDevice* gdevs,
  GLint ndev, const GLint* attribs );

Returns the identifiers of pixel formats that meet the specified requirements. gdevs indicates the graphics devices; pass NULL to obtain pixel formats for all devices installed in a system. ndev is the number of devices in gdevs; pass zero if gdevs is NULL.

attribs is an array of constants that specify specific requirements for the pixel format. An element of the array can be a Boolean value, such as AGL_RGBA, or consecutive elements are constant-value pairs, such as AGL_DEPTH_SIZE, 24. You must terminate the array by specifying AGL_NONE as the final element.

aglChoosePixelFormat() returns the first of possibly several pixel formats meeting the requirements specified by the parameters. To obtain the next pixel format, call aglNextPixelFormat(). aglChoosePixelFormat() returns NULL if no pixel formats match the list of requirements in attrib.

Use aglChoosePixelFormat() to specify OpenGL rendering requirements such as color, double buffering, depth buffer size, and color buffer size. The following code, for example, requests a double-buffered RGBA pixel format with 24-bit color buffers and a 24-bit depth buffer:

 const GLint attrib[] = { AGL_RGBA, AGL_DOUBLEBUFFER,         AGL_BUFFER_SIZE, 24, AGL_DEPTH_SIZE, 24, AGL_NONE }; AGLPixelFormat fmt = aglChoosePixelFormat( NULL, 0, attrib ); 

The attribute array elements shown above specify the drawing-surface characteristics. Other attribute element values control renderer selection. Include the constants AGL_ACCELERATED and AGL_NO_RECOVERY in attrib to select only hardware-accelerated pixel formats, for example.

AGLPixelFormat is an opaque type. The pixel formats returned by aglChoosePixelFormat() and aglNextPixelFormat() match as closely as possible to the attributes specified in attrib. To examine the returned pixel formats in detail to ensure that they meet your application's specifications, use aglDescribePixelFormat(). See Apple OpenGL Reference for information on aglDescribePixelFormat().

After you've obtained an appropriate pixel format, pass it to aglCreateContext() to create a context.

AGLContext aglCreateContext( AGLPixelFormat pix, AGLContext
  share );

Creates an OpenGL rendering context. pix is the desired pixel format, as obtained from aglChoosePixelFormat().

share specifies a context to share OpenGL objects with, such as display lists, buffer objects, and texture objects. If share is NULL, the context stores its own OpenGL objects.

aglCreateContext() returns NULL if it's unable to create a context for any reason.

To share OpenGL objects between contexts, your application must create the contexts according to certain criteria. If two contexts were created with the same pixel format, AGL allows sharing. There are other, less restrictive rules that also allow sharing; see Apple OpenGL Reference for more information.

After creating the context, you can free pixel-format resources by calling aglDestroyPixelFormat( pix ), where pix is the pixel format returned by aglChoosePixelFormat().

8.2.2. Using Contexts

Before issuing OpenGL commands, your application needs to associate the rendering context with a drawable and make it current.

To associate the rendering context with a drawable, call aglSetDrawable().

GLboolean aglSetDrawable( AGLContext ctx, AGLDrawable draw );

Associates the specified context with the specified drawable. ctx is a rendering context, and draw is an AGL drawable. The AGLDrawable type is equivalent to a CGrafPtr. Drawables may be windows, offscreen buffers, or pixel buffer objects.

To disable rendering for a context, call aglSetDrawable( ctx, NULL ).

You can associate multiple contexts with a single drawable, but only one context can be current at a time. To set the current context, call aglSetCurrentContext().

GLboolean aglSetCurrentContext( AGLContext ctx );

Makes ctx the current OpenGL context, and makes the previously current context noncurrent.

aglSetCurrentContext() returns GL_FALSE if it fails for any reason and GL_TRUE otherwise.

The following code demonstrates how to associate a context with a window drawable and make the context current:

 AGLContext ctx; WindowRef win; ... aglSetDrawable( ctx, GetWindowPort(win) ); aglSetCurrentContext( ctx ); 

When you have associated a context with a drawable and made it current, subsequent OpenGL commands use state from the current context, and rendering affects its drawable.

To make the current context noncurrent without making a new context current, call aglSetCurrentContext( NULL ).

8.2.3. Swapping Buffers

If your context is double buffered (that is, if you specified AGL_DOUBLEBUFFER in the attrib parameter to aglChoosePixelFormat() and created a context with the returned pixel format), you must swap buffers after rendering a frame to display the contents of the back buffer. To swap buffers, call aglSwapBuffers().

void aglSwapBuffers( AGLContext ctx );

Makes the back buffer associated with ctx visible. The contents of the new back buffer are undefined after this call.

aglSwapBuffers() implicitly flushes any buffered OpenGL commands (that is, it implicitly calls glFlush()).

AGL supports application control over whether the swap buffer command is synchronized to the monitor vertical retrace. See the description of aglSwapBuffers() in Apple OpenGL Reference for more information.

8.2.4. Deleting Contexts

To delete a context and free its resources, call aglDestroyContext().

GLboolean aglDestroyContext( AGLContext ctx );

Deletes the OpenGL rendering context specified by ctx. If ctx is the current context, aglDestroyContext() implicitly calls aglSetCurrentContext( NULL ), making ctx noncurrent and leaving no current context.

Carbon applications typically delete contexts upon receiving the kEventWindowClose event.