Deprecated AGL Functions

A function identified as deprecated has been superseded and may become unsupported in the future.

Deprecated in OS X v10.5

aglDevicesOfPixelFormat

Returns the graphics devices supported by a pixel format object. (Deprecated in OS X v10.5. Use aglDisplaysOfPixelFormat instead.)

GDHandle * aglDevicesOfPixelFormat (
   AGLPixelFormat pix,
   GLint *ndevs
);
Parameters
pix

A pixel format object.

ndevs

On return, points to the number of devices in the list returned by the function.

Return Value

An array of graphics devices or or NULL if the function fails for any reason. If an error occurs, call the function aglGetError to determine what the error is.

Discussion

You typically use this function after you call the function aglChoosePixelFormat, which can return a list of more than one pixel format object. The first pixel format object in the list is guaranteed to support all of the graphics devices requested of that function.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.5.
Declared In
agl.h

aglGetDrawable

Returns the drawable object attached to a rendering context. (Deprecated in OS X v10.5.)

AGLDrawable aglGetDrawable (
   AGLContext ctx
);
Parameters
ctx

A rendering context that's attached to a window or a graphics device.

Return Value

The drawable object (either a Carbon window or a full-screen graphics port) that is attached to the rendering context, or NULL for any of the following reasons:

  • No drawable object is attached.

  • A pixel buffer or offscreen memory area is attached.

  • The function fails for any reason.

If the function returns NULL, call the function aglGetError to determine what the error is.

Discussion

If the rendering context is a pixel buffer context, call aglGetPBuffer.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.5.
Declared In
agl.h

aglQueryRendererInfo

Creates and returns a renderer information object that contains properties and values for all renderers driving the specified displays. (Deprecated in OS X v10.5. Instead use aglQueryRendererInfoForCGDirectDisplayIDs.)

AGLRendererInfo aglQueryRendererInfo (
   const AGLDevice *gdevs,
   GLint ndev
);
Parameters
gdevs

A pointer to a list of graphics devices to which you want to restrict the query. Pass NULL to obtain information for all graphics devices on the system.

ndev

The number of graphics devices in gdev. Pass 0 if gdevs is NULL. AGL sets the AGL_BAD_DEVICE error if the ndev parameter is nonzero and the gdevs parameter is not an array of valid devices.

Return Value

A renderer information object that describes all renderers able to drive the devices specified by the gdevs parameter. The function returns NULL if it fails for any reason. If an error occurs, call the function aglGetError to determine what the error is.

Discussion

This function normally returns a list of more than one renderer information object—one for each renderer found on the system. To access data in the first renderer information object tin the list, call the function aglDescribeRenderer. To access data in a renderer information object that is not the first one in the list, use aglNextRendererInfo.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.5.
Declared In
agl.h

aglSetDrawable

Attaches a rendering context to a Carbon window. (Deprecated in OS X v10.5.)

GLboolean aglSetDrawable (
   AGLContext ctx,
   AGLDrawable draw
);
Parameters
ctx

A rendering context returned by the function aglCreateContext.

draw

The drawable object—which must be a Carbon window—to attach to the AGL rendering context. You need to supply a CGrafPtr data type obtained from a valid window. The Window Manager function GetWindowPort returns the CGrafPtr associated with a Carbon window. To disable rendering for a rendering context, pass NULL.

Return Value

Returns GL_FALSE if it fails for any reason, GL_TRUE otherwise. If an error occurs, call the function aglGetError to determine what the error is.

Discussion

After calling this function, AGL directs subsequent OpenGL rendering calls to the specified rendering context to modify the window content. In addition, the function aglSetDrawable performs all of the actions performed by aglUpdateContext.

When a rendering context is initially attached to the window, its viewport is set to the full size of the window. If the rendering context is subsequently attached to the same window, its viewport is unaltered.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.5.
Declared In
agl.h

aglSurfaceTexture

Allows texturing from a drawable object that has an attached rendering context, using the surface contents as the source data for the texture. (Deprecated in OS X v10.5.)

void aglSurfaceTexture (
   AGLContext context,
   GLenum target,
   GLenum internalformat,
   AGLContext surfacecontext
);
Parameters
context

A rendering context attached to the window that's the target of the texture operation.

target

A constant that specifies an OpenGL target texture. You can supply any of the texture targets defined by the OpenGL specification, including:

  • GL_TEXTURE_2D, a texture whose dimensions are a power of two.

  • GL_TEXTURE_RECTANGLE_EXT, a texture whose dimensions are not a power of two.

  • GL_TEXTURE_CUBE_MAP, a mapped cube texture.

internalformat

A constant that specifies the internal color format of the texture— either GL_RGB or GL_RGBA.

surfacecontext

A rendering context that's attached to the window that's the source of the texture data.

Discussion

The aglSurfaceTexture function behaves similar to the function glTexImage2D. The texture target and internal format must be supported by the renderer of the target rendering context, and the geometry of the source drawable object must be compatible with the texture target. For example, if the texture target is GL_TEXTURE_2D, the window must conform to power-of-two dimensions.

Before calling this function you must use OpenGL calls to set up the OpenGL texture referred to by the target parameter. That is, enable texturing, generate a texture name, bind it to a texture target, and so forth. For more information, see OpenGL Programming Guide.

The target and source windows must use the same renderer (virtual screen) or the function fails, most typically by not texturing the target rendering context.

An error condition occurs if the surface rendering context is not attached to a windowed drawable object; the drawable object cannot be an offscreen area or pixel buffer. It’s also possible to get standard OpenGL errors similar to the errors that can occur for the function glTexImage2D. Use the function glError to query OpenGL errors.

Availability
  • Available in OS X v10.2 and later.
  • Deprecated in OS X v10.5.
Declared In
agl.h

aglUseFont

Creates bitmap display lists from a font. (Deprecated in OS X v10.5.)

GLboolean aglUseFont (
   AGLContext ctx,
   GLint fontID,
   Style face,
   GLint size,
   GLint first,
   GLint count,
   GLint base
);
Parameters
ctx

A rendering context.

fontID

The font ID associated with the font whose character glyphs you want to use. The fontID value can identify any font family that is valid for passing into the TextFont function.

face

The font style. The face value can be any valid style that can be passed into the TextFace function.

size

The font size.

first

The index of the first glyph to use.

count

The number of glyphs to use.

base

The index of the first display list to generate.

Return Value

Returns GL_FALSE if it fails for any reason, GL_TRUE otherwise. If an error occurs, call the function aglGetError to determine what the error is.

Discussion

A display list contains one or more OpenGL commands that are stored and available to be executed later by your application. The aglUseFont function generates a set of display lists, each of which contains a single call to the OpenGL glBitmap function. AGL generates names for each display list by using the value specified in the base parameter and increasing sequentially to base + count – 1.

The prototype for the glBitmap function is :

void glBitmap(GLsizei width,
            GLsizei height,
            GLfloat xorig,
            GLfloat yorig,
            GLfloat xmove,
            GLfloat ymove,
            const GLubyte *bitmap)
 

AGL generates parameters for each glBitmap command in each display list using the following rules:

  • The formatting parameters—xorig, yorig, width, and height—are computed from the font metrics provided in the font as 0, font descent – 1, font width, and font ascent + descent, respectively.

  • The xmove parameter based on the width metric of the glyph.

  • The ymove is set to 0.

  • The glyph image is converted to the appropriate format for the bitmap parameter.

AGL creates empty display lists for all glyphs that you request and that are not defined in the font. For current fonts, see the file fonts.h.

For more information on the glBitmap function see the OpenGL Reference Manual. You might also want to look at the glNewList function, which is the function that AGL uses to generate the display lists.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.5.
Declared In
agl.h

Deprecated in OS X v10.6

aglSetFullScreen

Attaches a rendering context to a full screen graphics device. (Deprecated in OS X v10.6.)

GLboolean aglSetFullScreen (
   AGLContext ctx,
   GLsizei width,
   GLsizei height,
   GLsizei freq,
   GLint device
);
Parameters
ctx

A rendering context.

width

The width, in pixels, of the graphics device. This value must be an exact match to the graphics device.

height

The height, in pixels, of the graphics device. This value must be an exact match to the graphics device.

freq

The refresh frequency of the graphics device, in Hertz. If you specify a frequency of 0, AGL uses the highest refresh frequency available for the specified width and height. If you specify a nonzero frequency, AGL chooses the closest frequency available for the given geometry. If a display provides only a 0 refresh frequency, AGL matches it with width and height regardless of the value of frequency passed.

device

This parameter is ignored in OS X, where all devices that are compatible with the pixel format of the rendering context are considered when selecting a full screen graphics device.

Return Value

Returns GL_FALSE if it fails for any reason, GL_TRUE otherwise. If an error occurs, call the function aglGetError to determine what the error is.

Discussion

Passing 0 for the width, 0 for the height, and 0 for the frequency sets up a full screen context at the current height, width, and refresh rate.

After calling this function, subsequent OpenGL rendering calls directed to the full-screen graphics device. The rendering context must be created with respect to a pixel format that supports a full-screen device, which you can request by passing AGL_FULLSCREEN to the function aglChoosePixelFormat. The aglSetFullScreen function also performs all of the actions performed by aglUpdateContext. The aglSetFullScreen function uses information obtained from the pixel format object use to create the rendering context to choose the color depth for full-screen display mode.

When a rendering context is initially attached to a full screen graphics device, its viewport is set to the full size of the device. If the rendering context is subsequently attached to the same device, its viewport is unaltered. To disable a rendering context, call aglSetDrawable with the draw parameter set to NULL.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.6.
Declared In
agl.h

Deprecated in OS X v10.7

aglCreatePBuffer

Creates a pixel buffer of the specified size, compatible with the specified texture target. (Deprecated in OS X v10.7.)

GLboolean aglCreatePBuffer (
   GLint width,
   GLint height,
   GLenum target,
   GLenum internalFormat,
   GLint max_level,
   AGLPbuffer *pbuffer
);
Parameters
width

The width, in pixels, of the pixel buffer.

height

The height, in pixels, of the pixel buffer.

target

A constant that specifies the type of the pixel buffer target texture. You can supply any of the following texture targets:

  • GL_TEXTURE_2D, a texture whose dimensions are a power of two.

  • GL_TEXTURE_RECTANGLE_EXT, a texture whose dimensions are not a power of two.

  • GL_TEXTURE_CUBE_MAP, a mapped cube texture.

internalFormat

A constant that specifies the internal color format of the pixel buffer, which can be GL_RGB or GL_RGBA. The format controls whether the alpha channel of the pixel buffer is used for texturing operations.

max_level

The maximum level of mipmap detail allowable. Pass 0 for a pixel buffer that's not using mipmaps. The value passed should never exceed the actual maximum number of mipmap levels that can be represented with the given width and height.

pbuffer

On return, points to a new pixel buffer object.

Return Value

Returns GL_FALSE if it fails for any reason, GL_TRUE otherwise. If an error occurs, call the function aglGetError to determine what the error is.

Discussion

This function does not have any knowledge of OpenGL contexts or pixel format objects and does not specifically allocate the storage needed for the actual pixel buffer. These operations occur when you call the function aglSetPBuffer.

You can determine the dimensional limits of a pixel buffer by calling the OpenGL function glGetInteger. You can find the maximum size supported by querying GL_MAX_VIEWPORT_DIMS and the minimum size by querying GL_MIN_PBUFFER_VIEWPORT_DIMS_APPLE, which returns two integer values (similar to GL_MAX_VIEWPORT_DIMS). All pixel buffer dimensions that you request with the function aglCreatePBuffer should fall within these limits (inclusively) and should comply with any limitations imposed by the texture target you select.

The maximum viewport size supported in OS X is quite large. You should take into consideration the amount of video or system memory required to support the requested pixel buffer size, including additional memory needed for multiple buffers and options such as multisampling.

Availability
  • Available in OS X v10.3 and later.
  • Deprecated in OS X v10.7.
Declared In
agl.h

aglDescribePBuffer

Retrieves information that describes the specified pixel buffer object. (Deprecated in OS X v10.7.)

GLboolean aglDescribePBuffer (
   AGLPbuffer pbuffer,
   GLint *width,
   GLint *height,
   GLenum *target,
   GLenum *internalFormat,
   GLint *max_level
);
Parameters
pbuffer

A pixel buffer object.

width

On return, points to the width, in pixels, of the pixel buffer.

height

On return, points to the height, in pixels, of the pixel buffer.

target

On return, points to a constant that specifies the pixel buffer target texture type, such as:

  • GL_TEXTURE_2D, a texture whose dimensions are a power of two.

  • GL_TEXTURE_RECTANGLE_EXT, a texture whose dimensions are not a power of two.

  • GL_TEXTURE_CUBE_MAP, a mapped cube texture.

internalFormat

On return, points to a constant that specifies the internal color format of the pixel buffer— either GL_RGB or GL_RGBA.

max_level

On return, points to the maximum level of mipmap detail or 0 if the pixel buffer doesn't use mipmaps.

Return Value

Returns GL_FALSE if it fails for any reason, GL_TRUE otherwise. If an error occurs, call the function aglGetError to determine what the error is.

Discussion

The width, height, texture target, and internal texture color format of a pixel buffer object are set at its creation and cannot be changed without destroying and then creating the object again. The level is set when the pixel buffer object is attached to a rendering context by calling the function aglSetPBuffer.

Availability
  • Available in OS X v10.3 and later.
  • Deprecated in OS X v10.7.
Declared In
agl.h

aglDestroyPBuffer

Releases the resources associated with a pixel buffer object. (Deprecated in OS X v10.7.)

GLboolean aglDestroyPBuffer (
   AGLPbuffer pbuffer
);
Parameters
pbuffer

The pixel buffer object whose resources you want to release.

Return Value

Returns GL_FALSE if it fails for any reason, GL_TRUE otherwise. If an error occurs, call the function aglGetError to determine what the error is.

Discussion

Call this function only after you no longer need to use the pixel buffer object. Before calling this function, you should delete all texture objects associated with the pixel buffer object. You do not need to make sure that all texturing commands have completed prior to calling this function, because the OpenGL framework manages texturing synchronization.

Availability
  • Available in OS X v10.3 and later.
  • Deprecated in OS X v10.7.
Declared In
agl.h

aglGetPBuffer

Retrieves a pixel buffer and its parameters for a specified rendering context. (Deprecated in OS X v10.7.)

GLboolean aglGetPBuffer (
   AGLContext ctx,
   AGLPbuffer *pbuffer,
   GLint *face,
   GLint *level,
   GLint *screen
);
Parameters
ctx

A rendering context.

pbuffer

On return, points to the pixel buffer object attached to the rendering context.

face

On return, points to the cube map face that is set if the pixel buffer texture target type is GL_TEXTURE_CUBE_MAP; otherwise 0 for all other texture target types.

level

On return, points to the current mipmap level for drawing.

screen

On return, points to the current virtual screen number, as set by the last valid call to aglSetPBuffer.

Return Value

Returns GL_FALSE if it fails for any reason, GL_TRUE otherwise. If an error occurs, call the function aglGetError to determine what the error is.

Availability
  • Available in OS X v10.3 and later.
  • Deprecated in OS X v10.7.
See Also
Declared In
agl.h

aglSetOffScreen

Attaches a rendering context to an offscreen memory area. (Deprecated in OS X v10.7.)

GLboolean aglSetOffScreen (
   AGLContext ctx,
   GLsizei width,
   GLsizei height,
   GLsizei rowbytes,
   GLvoid *baseaddr
);
Parameters
ctx

A rendering context returned by the function aglCreateContext.

width

The width, in pixels, of the offscreen memory area.

height

The height, in pixels, of the offscreen memory area.

rowbytes

The number of bytes in each row of the offscreen memory area.

baseaddr

A pointer to the base address of the memory area.

Return Value

Returns GL_FALSE if it fails for any reason, GL_TRUE otherwise. If it fails, call the function aglGetError to determine what the error is.

Discussion

After calling this function, subsequent OpenGL rendering calls modify the offscreen memory. The rendering context must be created with respect to a pixel format that supports offscreen rendering, which you can request by passing AGL_OFFSCREEN to the aglChoosePixelFormat function. The aglSetOffScreen function also performs all of the actions performed by aglUpdateContext. The pixel size of the pixel format is set so that it is equal to the buffer depth of the offscreen area.

When a rendering context is attached to an offscreen memory area, its viewport is set to the full size of the offscreen area.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.7.
Declared In
agl.h

aglSetPBuffer

Attaches a pixel buffer object to a rendering context. (Deprecated in OS X v10.7.)

GLboolean aglSetPBuffer (
   AGLContext ctx,
   AGLPbuffer pbuffer,
   GLint face,
   GLint level,
   GLint screen
);
Parameters
ctx

A rendering context.

pbuffer

A pixel buffer object.

face

The cube map face to draw if the buffer texture target is type GL_TEXTURE_CUBE_MAP; otherwise pass 0.

level

The mipmap level to draw. This must not exceed the maximum mipmap level set when the pixel buffer object was created. Pass 0 for a texture target that does not support mipmaps.

screen

A virtual screen value. The virtual screen determines the renderer that OpenGL uses to draw to the pixel buffer object. For best performance, for a pixel buffer used as a texture source, you should supply the a virtual screen value that results in using the same renderer used by the context that's the texturing target.

Return Value

Returns GL_FALSE if it fails for any reason, GL_TRUE otherwise. If an error occurs, call the function aglGetError to determine what the error is. See Discussion for more details.

Discussion

The first time you call this function for a specific pixel buffer object, the system creates the necessary buffers. The buffers are created to support the pixel formats used to create the rendering context. The storage requirements for pixel buffer objects, which can be quite large, are very similar to the requirements for windows or views with OpenGL contexts attached. All drawable objects compete for the same scarce resources. This function can fail is there is not enough contiguous VRAM for each buffer. It's best to code defensively with a scheme that reduces resource consumption without causing the application to resort to failure. Unless, of course, failure is the only viable alternative.

The ability to attach a pbuffer to a context is supported only on renderers that export GL_APPLE_pixel_buffer in the GL_EXTENSIONS string. Before calling this function, you should programmatically determine if it’s possible to attach a pbuffer to a context by querying GL_EXTENSIONS in the context and looking for GL_APPLE_pixel_buffer. If that extension is not present, the renderer won’t allow setting the pbuffer. (In this case, the function correctly returns GL_FALSE, although the error returned by aglGetError may be misleading.)

In order of performance, these are the renderers you should consider using when setting up a rendering context to attach to a pbuffer:

  • A hardware renderer.

  • The generic render, but only with an offscreen pixel format and glTexSubImage.

  • The Apple software renderer, which supports pbuffers in OS X v10.4.8 and later.

Availability
  • Available in OS X v10.3 and later.
  • Deprecated in OS X v10.7.
See Also
Declared In
agl.h

aglTexImagePBuffer

Binds the contents of a pixel buffer to a data source for a texture object. (Deprecated in OS X v10.7.)

GLboolean aglTexImagePBuffer (
   AGLContext ctx,
   AGLPbuffer pbuffer,
   GLint source
);
Parameters
ctx

A rendering context, which is the target context for the texture operation. This is the context that you plan to render content to. This is not the context attached to the pixel buffer.

pbuffer

A pixel buffer object.

source

The source buffer to texture from, which should be a valid OpenGL buffer such as GL_FRONT or GL_BACK and should be compatible with the buffer and renderer attributes that you used to create the rendering context attached to the pixel buffer. This means that the pixel buffer must possess the buffer in question for the texturing operation to succeed.

Return Value

Returns GL_FALSE if it fails for any reason, GL_TRUE otherwise. If an error occurs, call the function aglGetError to determine what the error is.

Discussion

You must generate and bind a texture name (using standard OpenGL texturing calls) that is compatible with the pixel buffer texture target. Don't supply a texture object that was used previously for nonpixel buffer texturing operations unless a you first call the OpenGL function glDeleteTextures and then regenerate the texture name.

If you modify the content of a pixel buffer that uses mipmap levels, you must call this function again before drawing with the pixel buffer, to ensure that the content is synchronized with OpenGL. For pixel buffers without mipmaps, simply rebind to the texture object to synchronize content.

No OpenGL texturing calls that modify a pixel buffer texture content are permitted (such as glTexSubImage2D or glCopyTexImage2D) with the pixel buffer texture as the destination. It is permitted to use texturing commands to read data from a pixel buffer texture, such as glCopyTexImage2D, with the pixel buffer texture as the source. It is also legal to use OpenGL functions such as glReadPixels to read the contents of a pixel buffer directly through the pixel buffer context.

Note that texturing with the aglTexImagePBuffer function can fail to produce the intended results without error in the same way other OpenGL texturing commands can normally fail. The function fails if you do not enable the proper texture target, set an incompatible filter mode, or other conditions described in the OpenGL specification.

You don't need to share a context when a pixel buffer object is a texture source. You can use independent pixel formats and OpenGL contexts for both the pixel buffer and the target drawable object without sharing resources, and still texture using a pixel buffer in the target context.

For details on how to use a pixel buffer object as a texture source, see OpenGL Programming Guide for Mac.

Availability
  • Available in OS X v10.3 and later.
  • Deprecated in OS X v10.7.
Declared In
agl.h

Deprecated in OS X v10.8

aglCopyContext

Copies the specified state variables from one rendering context to another. (Deprecated in OS X v10.8.)

GLboolean aglCopyContext (
   AGLContext src,
   AGLContext dst,
   GLuint mask
);
Parameters
src

The source rendering context.

dst

The destination rendering context.

mask

A mask that specifies the state variables to copy. Pass a bit field that contains the bitwise OR of the state variable names that you want to copy. Use the symbolic mask constants that are passed to the OpenGL function glPushAttrib. To copy as many state variables as possible, supply the constant GL_ALL_ATTRIB_BITS. For a description of the symbolic mask constants, see OpenGL Reference Manual.

Return Value

Returns GL_FALSE if the function fails for any reason, GL_TRUE otherwise. If an error occurs, call the function aglGetError to determine what the error is.

Discussion

Not all OpenGL state values can be copied. For example, pixel pack and unpack state, render mode state, and select and feedback state are not copied. The state that can be copied is exactly the state that is manipulated by the OpenGL call glPushAttrib.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.8.
Declared In
agl.h

Deprecated in OS X v10.9

aglChoosePixelFormat

Creates a pixel format object that satisfies the constraints of the specified buffer and renderer attributes. (Deprecated in OS X v10.9.)

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

A pointer to an AGLDevice data type that contains an array of Mac OS graphics devices. AGL chooses pixel formats and renderers that are appropriate for these devices. To create a pixel format object that supports all devices on the system, pass NULL.

ndev

The number of graphics devices that your application supplies in the gdevs parameter. Pass 0 if you also pass NULL for the gdevs parameter.

attribs

A NULL terminated array that contains a list of buffer and renderer attributes. Attributes can be Boolean or integer. If an attribute is integer, you must supply the desired value immediately following the attribute. If the attribute is Boolean, do not supply a value because its presence in the attributes array implies a true value. For information on the attributes that you can supply, see “Buffer and Renderer Attributes,” “Renderer Attributes”, and the Discussion below.

Return Value

A new pixel format object that contains pixel format information and a list of virtual screens. Returns NULL if the system cannot find a pixel format and virtual screen that satisfies the constraints of the buffer and renderer attributes.

Discussion

After a pixel format object is created successfully, the integer attributes are set to values that are as close to the desired value as can be provided by the system. Attribute values can differ for each virtual screen. You can use the AGL_MINIMUM_POLICY and AGL_MAXIMUM_POLICY attributes to control how the system chooses the setting. For more information on choosing attributes, see OpenGL Programming Guide for Mac.

The Boolean attribute constants include the following. For complete descriptions, see “Buffer and Renderer Attributes” and “Renderer Attributes”.

The following are integer attribute constants and must be followed by a value. For complete descriptions, see “Buffer and Renderer Attributes” and “Renderer Attributes”.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.9.
Declared In
agl.h

aglConfigure

Sets the value of a global option. (Deprecated in OS X v10.9.)

GLboolean aglConfigure (
   GLenum pname,
   GLuint param
);
Parameters
pname

The name of the option whose value you want to set. See “Globally Configured Options” for a list of constants you can pass.

param

The value to set the option to.

Return Value

Returns GL_FALSE if it fails for any reason, GL_TRUE otherwise. If an error occurs, call the function aglGetError to determine what the error is.

Discussion

This function changes the values of options that affect the operation of OpenGL in all rendering contexts in the application, not just the current rendering context.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.9.
Declared In
agl.h

aglCreateContext

Creates an AGL rendering context. (Deprecated in OS X v10.9.)

AGLContext aglCreateContext (
   AGLPixelFormat pix,
   AGLContext share
);
Parameters
pix

A pixel format object creating by calling the function aglChoosePixelFormat.

share

The rendering context with which to share the OpenGL object state—including texture objects, programs and shader display lists, vertex array objects, vertex buffer objects, pixel buffer objects, and frame buffer objects—and the object state associated which each of these object types. Pass NULL to indicate that no sharing is to take place.

Return Value

A new rendering context. The aglCreateContext function returns NULL if the function fails for any reason. You can call the function aglGetError to determine what the error is.

Discussion

If the pixel format object you supply is able to support multiple graphics devices, then the rendering context can render transparently across the supported devices. With a multiple-device rendering context, sharing is possible only when the relationship between the renderers and the graphics devices they support is the same for all rendering contexts that are shared. Normally you achieve the best results by using the same pixel format object for all shared rendering contexts. For more information, see OpenGL Programming Guide for Mac.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.9.
Declared In
agl.h

aglCreatePixelFormat

Creates a pixel format with the provided attributes. (Deprecated in OS X v10.9.)

AGLPixelFormat aglCreatePixelFormat (
   const GLint *attribs
);
Parameters
attribs

The attributes for the pixel format.

Return Value

A pixel format object.

Availability
  • Available in OS X v10.5 and later.
  • Deprecated in OS X v10.9.
Declared In
agl.h

aglDescribePixelFormat

Retrieves the value of an attribute associated with a pixel format object. (Deprecated in OS X v10.9.)

GLboolean aglDescribePixelFormat (
   AGLPixelFormat pix,
   GLint attrib,
   GLint *value
);
Parameters
pix

The pixel format object to query.

attrib

The attribute whose value you want to obtain. For a list of possible attributes, see “Buffer and Renderer Attributes.”

value

On return, points to the value of the attribute.

Return Value

Returns GL_FALSE if it fails for any reason, GL_TRUE otherwise. If an error occurs, call the function aglGetError to determine what the error is.

Discussion

On multiscreen systems that support multiple renderers simultaneously, aglChoosePixelFormat can return a list of more than one pixel format object. To retrieve the data in pixel format objects other than the first one in the list, call aglNextPixelFormat. Then pass the returned pixel format object to aglDescribePixelFormat to retrieve an attribute value.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.9.
Declared In
agl.h

aglDescribeRenderer

Obtains the value associated with a renderer property. (Deprecated in OS X v10.9.)

GLboolean aglDescribeRenderer (
   AGLRendererInfo rend,
   GLint prop,
   GLint *value
);
Parameters
rend

An opaque renderer information object that contains a description of the renderer capabilities you want to inspect. You obtain a renderer information object by calling the function aglQueryRendererInfo.

prop

The renderer property whose value you want to obtain. See “Renderer Properties” for a list of the constants you can supply for this parameter. There are also a number of constants described in “Buffer and Renderer Attributes” that you can supply to this function.

value

On return, points to the value of the requested property.

Return Value

Returns GL_FALSE if it fails for any reason, GL_TRUE otherwise. If an error occurs, call the function aglGetError to determine what the error is.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.9.
Declared In
agl.h

aglDestroyContext

Frees the resources associated with a rendering context. (Deprecated in OS X v10.9.)

GLboolean aglDestroyContext (
   AGLContext ctx
);
Parameters
ctx

The rendering context whose resources you want to release.

Return Value

Returns GL_FALSE if it fails for any reason, GL_TRUE otherwise. If an error occurs, call the function aglGetError to determine what the error is.

Discussion

This function frees all the resources used by the rendering context passed to it. If the rendering context that you pass is the current rendering context, the current context is set to NULL and there is no current rendering context after the function executes.

After you call this function, you must make sure that you do not use the destroyed rendering context. This includes using AGL macros in which the rendering context is explicitly passed to OpenGL.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.9.
Declared In
agl.h

aglDestroyPixelFormat

Frees the memory associated with a pixel format object. (Deprecated in OS X v10.9.)

void aglDestroyPixelFormat (
   AGLPixelFormat pix
);
Parameters
pix

The pixel format object whose resources you want to release. This must be a pixel format object returned by the functionaglChoosePixelFormat. AGL sets a AGL_BAD_PIXELFMT error if you pass the returned value from the function aglNextPixelFormat or the pix parameter is not a valid pixel format.

Discussion

A copy of the pixel format data is made by the aglCreateContext function, so your application can free a pixel format immediately after creating a rendering context with it. On the other hand, a pixel format object can be useful for enumerating virtual screens when multiple renderers are supported, so you may want to retain it.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.9.
Declared In
agl.h

aglDestroyRendererInfo

Frees resources associated with a renderer information object. (Deprecated in OS X v10.9.)

void aglDestroyRendererInfo (
   AGLRendererInfo rend
);
Parameters
rend

The renderer information object whose resources you want to release.

Discussion

AGL sets a AGL_BAD_RENDINFO error if you pass an invalid renderer information object. You can check for this error by calling aglGetError.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.9.
Declared In
agl.h

aglDisable

Disables an option for a rendering context. (Deprecated in OS X v10.9.)

GLboolean aglDisable (
   AGLContext ctx,
   GLenum pname
);
Parameters
ctx

A rendering context.

pname

The capability that you want to disable. You can pass any of the constants listed in “Context Options and Parameters” that specify they can be enabled or disabled.

Return Value

Returns GL_FALSE if it fails for any reason, GL_TRUE otherwise. If an error occurs, call the function aglGetError to determine what the error is.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.9.
See Also
Declared In
agl.h

aglDisplaysOfPixelFormat

Returns the graphics devices supported by a pixel format object. (Deprecated in OS X v10.9.)

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

A pixel format object.

ndevs

On return, points to the number of devices in the list returned by the function.

Return Value

An array of display IDs or or NULL if the function fails for any reason. If an error occurs, call the function aglGetError to determine what the error is.

Discussion

You typically use this function after you call the function aglChoosePixelFormat, which can return a list of more than one pixel format object. The first pixel format object in the list is guaranteed to support all of the graphics devices requested of that function. You call aglDisplaysOfPixelFormat to find out which graphics devices are supported by other pixel format objects in the list.

Availability
  • Available in OS X v10.5 and later.
  • Deprecated in OS X v10.9.
Declared In
agl.h

aglEnable

Enables an option for a rendering context. (Deprecated in OS X v10.9.)

GLboolean aglEnable (
   AGLContext ctx,
   GLenum pname
);
Parameters
ctx

A rendering context.

pname

The option you want to enable. You can pass any of the constants listed in “Context Options and Parameters” that specify they can be enabled or disabled.

Return Value

Returns GL_FALSE if it fails for any reason, GL_TRUE otherwise. If an error occurs, call the function aglGetError to determine what the error is.

Discussion

To set the value associated with a rendering context option, use the function aglSetInteger. For example, if you enable AGL_SWAP_RECT, you can specify the area of the window that is affected by the aglSwapBuffers function by setting the rectangle size with the function aglSetInteger.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.9.
Declared In
agl.h

aglErrorString

Returns a string that describes the specified AGL error code. (Deprecated in OS X v10.9.)

const GLubyte * aglErrorString (
   GLenum code
);
Parameters
code

An AGL error code returned by the function aglGetError. For a description of these constants, see “Error Codes.”

Return Value

An error string that describes the error code passed in the code parameter. If the code is invalid, returns the string “No such error code.”

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.9.
See Also
Declared In
agl.h

aglGetCGLContext

Gets the CGL rendering context associated with an AGL rendering context. (Deprecated in OS X v10.9.)

GLboolean aglGetCGLContext (
   AGLContext ctx,
   void **cgl_ctx
);
Parameters
ctx

An AGL rendering context.

cgl_ctx

On return, points to the CGL rendering context associated with the specified AGL rendering context.

Return Value

Returns GL_FALSE if it fails for any reason, GL_TRUE otherwise. If an error occurs, call the function aglGetError to determine what the error is.

Discussion

You should use this function only when you absolutely need to use a non-AGL function that requires an CGL rendering context. You can cast the returned CGL rendering context to another data type as needed. Note that destroying the AGL rendering context also destroys the CGL rendering context, thus rendering the data reference returned by this function invalid.

Availability
  • Available in OS X v10.4 and later.
  • Deprecated in OS X v10.9.
Declared In
agl.h

aglGetCGLPixelFormat

Gets the CGL pixel format object associated with an AGL pixel format. (Deprecated in OS X v10.9.)

GLboolean aglGetCGLPixelFormat (
   AGLPixelFormat pix,
   void **cgl_pix
);
Parameters
pix

An AGL pixel format object.

cgl_pix

On return, points to the CGL pixel format object associated with the specified AGL pixel format.

Return Value

Returns GL_FALSE if it fails for any reason, GL_TRUE otherwise. If an error occurs, call the function aglGetError to determine what the error is.

Discussion

You should use this function only when you absolutely need to pass a CGL pixel format object to a non-AGL function. You can cast the returned CGL pixel format object to another data type as needed. Note that destroying the AGL pixel format object also destroys the CGL pixel format object, thus making the data reference returned invalid.

Availability
  • Available in OS X v10.4 and later.
  • Deprecated in OS X v10.9.
Declared In
agl.h

aglGetCurrentContext

Returns the current rendering context. (Deprecated in OS X v10.9.)

AGLContext aglGetCurrentContext (
   void
);
Return Value

The current rendering context. If there is no current rendering context, returns NULL.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.9.
Declared In
agl.h

aglGetError

Returns an AGL error code. (Deprecated in OS X v10.9.)

GLenum aglGetError (
   void
);
Return Value

The value of the global AGL error flag. See “Error Codes” for a complete description of the error codes that can be returned.

Discussion

This function is similar to the OpenGL function glGetError. You call the function aglGetError whenever an AGL function returns FALSE to retrieve the error code associated with the error condition. Each error is assigned a numeric code and a symbolic name. When an error occurs, the error flag is set to the appropriate error code value. No other errors are recorded until aglGetError is called, the error code is returned, and the flag is reset to AGL_NO_ERROR. If a call to aglGetError returns AGL_NO_ERROR, this means that there has been no detectable error since the last call to aglGetError.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.9.
Declared In
agl.h

aglGetHIViewRef

Retrieves the HIView object associated with an AGL context. (Deprecated in OS X v10.9.)

HIViewRef aglGetHIViewRef (
   AGLContext ctx
);
Parameters
ctx

The AGL context whose HIView object you want to retrieve.

Return Value

The HIView object associated with the context.

Availability
  • Available in OS X v10.5 and later.
  • Deprecated in OS X v10.9.
Declared In
agl.h

aglGetInteger

Retrieves the integer setting of an AGL context option. (Deprecated in OS X v10.9.)

GLboolean aglGetInteger (
   AGLContext ctx,
   GLenum pname,
   GLint *params
);
Parameters
ctx

An rendering context.

pname

The option whose value you want to retrieve. You can pass any of the constants listed in “Context Options and Parameters” that have an associated value.

params

On return, points to the value of the option.

Return Value

Returns GL_FALSE if it fails for any reason, GL_TRUE otherwise. If an error occurs, call the function aglGetError to determine what the error is. See “Error Codes” for more information.

Discussion

Use aglEnable to enable the option.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.9.
See Also
Declared In
agl.h

aglGetVersion

Gets the major and minor version numbers of the AGL library. (Deprecated in OS X v10.9.)

void aglGetVersion (
   GLint *major,
   GLint *minor
);
Parameters
major

On return, points to he major version number of the AGL library.

minor

On return, points to the minor version number of the AGL library.

Discussion

AGL implementations with the same major version number are upwardly compatible, meaning that the implementation with the highest minor number is a superset of the version with the lowest minor number.

Certain features, such as index color support, are deprecated in OS X. The current version of AGL might not be a full superset of AGL for Mac OS 9 or of earlier versions of AGL.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.9.
Declared In
agl.h

aglGetVirtualScreen

Returns the current virtual screen number associated with a rendering context. (Deprecated in OS X v10.9.)

GLint aglGetVirtualScreen (
   AGLContext ctx
);
Parameters
ctx

A rendering context.

Return Value

Returns the virtual screen number of the context. The value is always 0 on a single-monitor system and –1 if the function fails for any reason. If an error occurs, call the function aglGetError to determine what the error is.

Discussion

The current virtual screen is set automatically by the function aglUpdateContext. The current virtual screen can change when a drawable object is moved or resized across graphics device boundaries. A change in the current virtual screen can affect the return values of some OpenGL functions and in most cases also means that the renderer has changed.

For detailed information on virtual screens, see OpenGL Programming Guide for Mac.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.9.
Declared In
agl.h

aglGetWindowRef

Retrieves the window associated with an AGL context. (Deprecated in OS X v10.9.)

WindowRef aglGetWindowRef (
   AGLContext ctx
);
Parameters
ctx

The AGL context whose window you want to retrieve.

Return Value

The window associated with the context.

Availability
  • Available in OS X v10.5 and later.
  • Deprecated in OS X v10.9.
Declared In
agl.h

aglIsEnabled

Reports whether an option is enabled for a rendering context. (Deprecated in OS X v10.9.)

GLboolean aglIsEnabled (
   AGLContext ctx,
   GLenum pname
);
Parameters
ctx

A rendering context.

pname

The capability whose state you want to check. You can pass any of the constants listed in “Context Options and Parameters” that specify they can be enabled or disabled.

Return Value

GL_FALSE if the option is disabled or if it fails for any reason; GL_TRUE otherwise. If an error occurs, call the function aglGetError to determine what the error is.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.9.
Declared In
agl.h

aglNextPixelFormat

Returns the next pixel format object in a list of pixel format objects. (Deprecated in OS X v10.9.)

AGLPixelFormat aglNextPixelFormat (
   AGLPixelFormat pix
);
Parameters
pix

A pointer to pixel format object.

Return Value

The next pixel format object in a list of pixel formats. Returns NULL if the pix parameter represents the last pixel format object in the list or if the function fails for any reason. If an error occurs, call the function aglGetError to determine what the error is.

Discussion

You typically use this function after you’ve called the function aglChoosePixelFormat, which generates a list of more than one pixel format object when all the graphics devices on the system are not supported by a single renderer. To find the number of renderers associated with a pixel format object, you can call aglNextPixelFormat to iterate through the list and count the entries.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.9.
Declared In
agl.h

aglNextRendererInfo

Returns the next renderer information object. (Deprecated in OS X v10.9.)

AGLRendererInfo aglNextRendererInfo (
   AGLRendererInfo rend
);
Parameters
rend

A renderer information object that contains one or more renderer information objects. You obtain a renderer information object by calling the function aglQueryRendererInfo.

Return Value

The next renderer information object in the list. Returns NULL if the object is the last in the list or if the function fails for any reason. In case of a failure, call the function aglGetError to determine what the error is.

Discussion

You typically use this function to iterate through a list of renderer information objects returned by the function aglQueryRendererInfo. Most systems have more than one renderer installed because support for different buffer depths is typically provided by separate renderers.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.9.
Declared In
agl.h

aglQueryRendererInfoForCGDirectDisplayIDs

Creates and returns a renderer information object that contains properties and values for all renderers driving the specified displays. (Deprecated in OS X v10.9.)

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

A pointer to the list of IDs to which you want to restrict the query. . Pass NULL to obtain information for all graphics devices on the system.

ndev

The number of graphics devices in dspIDs. Pass 0 if dspIDs is NULL. AGL sets the AGL_BAD_DEVICE error if the ndev parameter is nonzero and the dspIDs parameter is not an array of valid devices.

Availability
  • Available in OS X v10.5 and later.
  • Deprecated in OS X v10.9.
Declared In
agl.h

aglResetLibrary

Resets the AGL library. (Deprecated in OS X v10.9. This function is not needed in OS X.)

void aglResetLibrary (
   void
);
Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.9.
Declared In
agl.h

aglSetCurrentContext

Sets the specified rendering context as the current rendering context. (Deprecated in OS X v10.9.)

GLboolean aglSetCurrentContext (
   AGLContext ctx
);
Parameters
ctx

The rendering context to set as the current rendering context. Pass NULL to release the current rendering context without assigning a new one.

Return Value

Returns GL_FALSE if it fails for any reason, GL_TRUE otherwise. If an error occurs, call the function aglGetError to determine what the error is.

Discussion

There can be only one current rendering context. Subsequent OpenGL rendering calls operate on the current rendering context to modify the drawable object associated with it.

You can use AGL macros to bypass the current rendering context mechanism and maintain your own current rendering context.

A context is current on a per-thread basis. Multiple threads must serialize calls into the same context.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.9.
Declared In
agl.h

aglSetHIViewRef

Sets an AGL context to the specified HIView object. (Deprecated in OS X v10.9.)

GLboolean aglSetHIViewRef (
   AGLContext ctx,
   HIViewRef hiview
);
Parameters
ctx

An AGL context.

hiview

The HIView object to set.

Return Value

true if the HIView object is successfully set; false otherwise.

Availability
  • Available in OS X v10.5 and later.
  • Deprecated in OS X v10.9.
Declared In
agl.h

aglSetInteger

Sets the value of an option for a rendering context. (Deprecated in OS X v10.9.)

GLboolean aglSetInteger (
   AGLContext ctx,
   GLenum pname,
   const GLint *params
);
Parameters
ctx

A rendering context.

pname

The rendering context option whose value you want to set. You can pass any of the constants listed in “Context Options and Parameters” that have an associated integer value.

params

A pointer to the value to set the parameter to.

Return Value

Returns GL_FALSE if it fails for any reason, GL_TRUE otherwise. If an error occurs, call the function aglGetError to determine what the error is.

Discussion

Use aglEnable to enable the option.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.9.
See Also
Declared In
agl.h

aglSetVirtualScreen

Forces subsequent OpenGL commands to the specified virtual screen. (Deprecated in OS X v10.9.)

GLboolean aglSetVirtualScreen (
   AGLContext ctx,
   GLint screen
);
Parameters
ctx

A rendering context.

screen

A virtual screen number, which must be a value between 0 and the number of virtual screens minus one. You can obtain the number of virtual screens available associated with a rendering context by calling the function aglDescribePixelFormat, passing in the pixel format object used to create the rendering context and the attribute constant AGL_VIRTUAL_SCREEN.

Return Value

Returns GL_FALSE if it fails for any reason, GL_TRUE otherwise. If an error occurs, call the function aglGetError to determine what the error is.

Discussion

You should use the aglSetVirtualScreen function only when it is necessary to override the default behavior. The current virtual screen is normally set automatically by the functions aglSetDrawable or aglUpdateContext. Setting the virtual screen forces the renderer associated with the virtual screen to process OpenGL commands issued to the specified context. Changing the virtual screen changes the current renderer. Because the current virtual screen determines which OpenGL renderer is processing commands, the return values of all glGetXXX functions can be affected by the current virtual screen.

For detailed information on virtual screens, see OpenGL Programming Guide for Mac.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.9.
Declared In
agl.h

aglSetWindowRef

Sets an AGL context to the specified window. (Deprecated in OS X v10.9.)

GLboolean aglSetWindowRef (
   AGLContext ctx,
   WindowRef window
);
Parameters
ctx

An AGL context.

window

The window to set.

Return Value

true if the window is successfully set; false otherwise.

Availability
  • Available in OS X v10.5 and later.
  • Deprecated in OS X v10.9.
Declared In
agl.h

aglSwapBuffers

Exchanges the front and back buffers of the specified rendering context. (Deprecated in OS X v10.9.)

void aglSwapBuffers (
   AGLContext ctx
);
Parameters
ctx

The rendering context whose buffers you want to swap. AGL sets the AGL_BAD_CONTEXT error if the ctx parameter is not a valid AGL rendering context.

Discussion

The aglSwapBuffers function either swaps the buffers or copies the back buffer content to the front buffer. Before it returns, aglSwapBuffers invokes the OpenGL function glFlush.

To synchronize with a monitor retrace, set the current swap interval (AGL_SWAP_INTERVAL) to 1 by calling the function aglSetInteger.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.9.
Declared In
agl.h

aglUpdateContext

Notifies the rendering context that the window geometry has changed. (Deprecated in OS X v10.9.)

GLboolean aglUpdateContext (
   AGLContext ctx
);
Parameters
ctx

The rendering context that needs updating.

Return Value

Returns GL_FALSE if it fails for any reason, GL_TRUE otherwise. If an error occurs, call the function aglGetError to determine what the error is.

Discussion

You must call the aglUpdateContext function any time that the geometry of the drawable object changes. You should call this function after the completion of any move or resize action.

Availability
  • Available in OS X v10.0 and later.
  • Deprecated in OS X v10.9.
Declared In
agl.h