Retired Document

Important: This document may not represent best practices for current development. Links to downloads and other resources may no longer be valid.

Technical Q&A QA1523

AGL Changes for Mac OS X Leopard (v. 10.5)

Q: What has changed for AGL in Mac OS X v.10.5?

A: The following is a detailed list of changes to the AGL framework on Mac OS X v.10.5 as shown on the agl.h header file.

This header is located at:

/System/Library/Frameworks/AGL.framework/Headers/agl.h

New for Mac OS X Leopard v.10.5

The Apple OpenGL Interface or AGL, has been updated on this release of the OS to take full advantage of the Quartz Display Services and support setting HIViewRef and WindowRef directly as rendering destinations.

The new version of the API is defined as:
#define AGL_VERSION_3_0 1

Pixel format management

The new entry points regarding pixel formats are as follows:

 AGLPixelFormat aglCreatePixelFormat(const GLint *attribs);

 CGDirectDisplayID *aglDisplaysOfPixelFormat(AGLPixelFormat pix, GLint *ndevs);

To support the new pixel format creation with aglCreatePixelFormat, the following pixel formate attribute name is defined as:

#define AGL_DISPLAY_MASK          84  /* mask limiting supported displays             */

As an example of usage, the following listing creates a pixel format that limits the renderers to those supported by the main display only.

Listing 1 Creating a pixel format .

 // Get display ID to use for a mask

    // The main display as configured via System Preferences

    CGDirectDisplayID displayID = CGMainDisplayID();

    CGOpenGLDisplayMask openGLDisplayMask = CGDisplayIDToOpenGLDisplayMask(displayID);

    // Solely as an example of possible use, this pixel format limits

    // the possible renderers to those supported by the screen mask.

    // In this case the main display.

    GLint attrib[] = {	AGL_RGBA,

                        AGL_DOUBLEBUFFER,

                        AGL_DEPTH_SIZE, 16,

                        AGL_DISPLAY_MASK, openGLDisplayMask, // New to Mac OS X v10.5

                        AGL_NONE };

    // aglChoosePixelFormat has been deprecated on Mac OS X v10.5 use aglCreatePixelFormat

    // as shown below.

    AGLPixelFormat thePixelFormat = aglCreatePixelFormat(attrib); // New to Mac OS X v10.5

Render Information

The new way of querying renderer information based on CGDirectDisplayID:

 AGLRendererInfo aglQueryRendererInfoForCGDirectDisplayIDs(const CGDirectDisplayID *dspIDs, GLint ndev);

Drawable Functions

The new drawable functions are based on WindowRef and HIViewRef and are defined as:

 GLboolean aglSetWindowRef(AGLContext ctx, WindowRef window);

 WindowRef aglGetWindowRef(AGLContext ctx);

 GLboolean aglSetHIViewRef(AGLContext ctx, HIViewRef hiview);

 HIViewRef aglGetHIViewRef(AGLContext ctx);

The following source shows how to create an AGL context and set it's drawable based on a WindowRef

Listing 2 Setting the AGL context drawable based on a WindowRef.

 AGLContext theAGLContext = aglCreateContext(thePixelFormat, NULL); // No context to share with

    // Instead of aglSetDrawable use

    // aglSetWindowRef or aglSetHIViewRef

    aglSetWindowRef(theAGLContext, window);

Deprecated Items

AGLDevice is a QuickDraw type; it has been deprecated, use CGDirectDisplayID.
typedef GDHandle AGLDevice;

The integer parameter AGL_CLIP_REGION has been deprecated.

#define AGL_CLIP_REGION          254  /* Enable or set the drawable clipping region */

AGLDrawable is a QuickDraw type; it has been deprecated, use WindowRef or HIViewRef.
typedef CGrafPtr AGLDrawable;

aglSetDrawable and aglGetDrawable have been deprecated; use aglGetWindowRef or aglSetHIViewRef.

 GLboolean aglSetDrawable(AGLContext ctx, AGLDrawable draw);

 AGLDrawable aglGetDrawable(AGLContext ctx);

aglUseFont has been deprecated and no replacement is available at this time. As an alternative Quartz can be used to draw text into a string texture, or a texture atlas of several characters.

GLboolean aglUseFont(AGLContext ctx, GLint fontID,

                                         Style face, GLint size, GLint first, GLint count, GLint base);

aglSurfaceTexture has been deprecated, no replacement available at this time. There is no explicit need for a replacement since a framebuffer object (FBO) or a PBuffer provides this functionality.
void aglSurfaceTexture (AGLContext context, GLenum target, GLenum internalformat, AGLContext surfacecontext);

References

Document Revision History

Date	Notes
2014-03-06	This Q&A describes the new and deprecated APIs for Apple OpenGL (AGL)
2008-01-04	New document that this Q&A describes the new and deprecated APIs for Apple OpenGL (AGL)