AGL Reference

Framework
AGL/agl.h
Companion guide
Declared in
agl.h
aglRenderers.h

Overview

The AGL (Apple Graphics Library) API is part of the Apple implementation of OpenGL in OS X. AGL contains the windowing system–specific implementation of OpenGL functions and commands for Carbon. Using AGL functions, you can create and destroy AGL rendering contexts, select OpenGL renderers, swap buffers, and perform operations on drawable objects (windows, pixel buffers, offscreen memory, and full-screen graphics devices).

To use AGL from the Carbon framework, your application must link to both the AGL and the OpenGL (OpenGL/OpenGL.h) frameworks.

Functions by Task

Managing Pixel Format Objects

Managing Contexts

Getting and Setting Context Options

Managing Drawable Objects

Managing Pixel Buffers

Using a Window as a Texture Source

Getting Error Information

Getting and Setting Global Information

Getting Renderer Information

Generating Bitmap Display Lists

Managing Virtual Screens

Getting and Setting Windows

Getting and Setting HIView Objects

Data Types

AGLContext

Represents a pointer to an opaque AGL context object.

typedef struct __AGLContextRec  *AGLContext;
Discussion

This data type points to a structure that AGL uses to maintain state and other information associated with an OpenGL rendering context. Use the functions described in “Managing Contexts” and “Getting and Setting Context Options” to create, manage, access, and free an AGL context object.

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

AGLDevice

Defines a reference to a list of graphics devices.

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

AGLDrawable

Defines an opaque data type that represents a Carbon window.

typedef CGrafPtr AGLDrawable;
Discussion

This data type points to a structure that AGL uses to keep track of the information needed to transmit rendering operations from bits in memory to the onscreen pixels associated with a Carbon window. This data type is a CGrafPtr "under the hood." The Window Manager function GetWindowPort returns the CGrafPtr associated with a Carbon window.

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

AGLPbuffer

Represents a pointer to an opaque pixel buffer object.

typedef struct __AGLPBufferRec  *AGLPbuffer;
Discussion

This data type points to a structure that AGL uses for hardware accelerated offscreen drawing. Use the functions described in “Managing Pixel Buffers” to create, manage, access, and free a pixel buffer object.

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

AGLPixelFormat

Represents a pointer to an opaque pixel format object.

typedef struct __AGLPixelFormatRec *AGLPixelFormat;
Discussion

This data type points to a structure that AGL uses to maintain pixel format and virtual screen information for a given set of renderer and buffer options. Use the functions described in “Managing Pixel Format Objects” to create, manage, access, and free a pixel format object.

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

AGLRendererInfo

Represents a pointer to an opaque renderer information object.

typedef struct __AGLRendererInfoRec *AGLRendererInfo;
Discussion

This data type points to a structure that AGL uses to maintain information about the renderers associated with a display. Use the functions described in “Getting Renderer Information” to create, access, and free a renderer information object.

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

Constants

Bit Depths

Define resolutions for the depth and stencil buffers.

#define AGL_0_BIT 0x00000001
#define AGL_1_BIT 0x00000002
#define AGL_2_BIT 0x00000004
#define AGL_3_BIT 0x00000008
#define AGL_4_BIT 0x00000010
#define AGL_5_BIT 0x00000020
#define AGL_6_BIT 0x00000040
#define AGL_8_BIT 0x00000080
#define AGL_10_BIT 0x00000100
#define AGL_12_BIT 0x00000200
#define AGL_16_BIT 0x00000400
#define AGL_24_BIT 0x00000800
#define AGL_32_BIT 0x00001000
#define AGL_48_BIT 0x00002000
#define AGL_64_BIT 0x00004000
#define AGL_96_BIT 0x00008000
#define AGL_128_BIT 0x00010000
Constants
AGL_0_BIT

A bit depth of 0.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_1_BIT

A bit depth of 1 bit.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_2_BIT

A bit depth of 2 bits.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_3_BIT

A bit depth of 3 bits.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_4_BIT

A bit depth of 4 bits.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_5_BIT

A bit depth of 5 bits.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_6_BIT

A bit depth of 6 bits.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_8_BIT

A bit depth of 7 bits.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_10_BIT

A bit depth of 10 bits.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_12_BIT

A bit depth of 12 bits.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_16_BIT

A bit depth of 16 bits.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_24_BIT

A bit depth of 24 bits.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_32_BIT

A bit depth of 32 bits.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_48_BIT

A bit depth of 48 bits.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_64_BIT

A bit depth of 64 bits.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_96_BIT

A bit depth of 96 bits.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_128_BIT

A bit depth of 128 bits.

Available in OS X v10.0 and later.

Declared in agl.h.

Declared In
agl.h

Buffer and Renderer Attributes

Specify attributes used to create a pixel format object.

#define AGL_NONE 0
#define AGL_ALL_RENDERERS 1
#define AGL_BUFFER_SIZE 2
#define AGL_LEVEL 3
#define AGL_RGBA 4
#define AGL_DOUBLEBUFFER 5
#define AGL_STEREO 6
#define AGL_AUX_BUFFERS 7
#define AGL_RED_SIZE 8
#define AGL_GREEN_SIZE 9
#define AGL_BLUE_SIZE 10
#define AGL_ALPHA_SIZE 11
#define AGL_DEPTH_SIZE 12
#define AGL_STENCIL_SIZE 13
#define AGL_ACCUM_RED_SIZE 14
#define AGL_ACCUM_GREEN_SIZE 15
#define AGL_ACCUM_BLUE_SIZE 16
#define AGL_ACCUM_ALPHA_SIZE 17
#define AGL_PIXEL_SIZE 50
#define AGL_MINIMUM_POLICY 51
#define AGL_MAXIMUM_POLICY 52
#define AGL_OFFSCREEN 53
#define AGL_FULLSCREEN 54
#define AGL_SAMPLE_BUFFERS_ARB 55
#define AGL_SAMPLES_ARB 56
#define AGL_AUX_DEPTH_STENCIL 57
#define AGL_COLOR_FLOAT 58
#define AGL_MULTISAMPLE 59
#define AGL_SUPERSAMPLE 60
#define AGL_SAMPLE_ALPHA 61
Constants
AGL_NONE

Used to terminate a pixel format attribute list.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_ALL_RENDERERS

This constant is a Boolean attribute. If it is present in the attributes array, pixel format selection is open to all available renderers, including debug and special-purpose renderers that are not OpenGL compliant. Do not supply a value with this constant because its presence in the array implies true.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_BUFFER_SIZE

The associated value is a nonnegative integer that specifies the number of bits per color buffer. For RGBA pixel formats, the buffer size is the sum of the red, green, blue, and alpha sizes. For color index pixel formats, the buffer size is the size of the color indexes. The smallest color index buffer of at least the specified size is preferred. Ignored if the AGL_RGBA attribute is asserted.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_LEVEL

The associated value is an integer that specifies the frame buffer level of the pixel format. Positive levels correspond to frame buffers that overlay the default buffer, and negative levels correspond to frame buffers that underlay the default level. Buffer level zero corresponds to the default frame buffer of the display. Buffer level one is the first overlay frame buffer, level two the second overlay frame buffer, and so on. Negative buffer levels correspond to underlay frame buffers.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_RGBA

This constant is a Boolean attribute. If it is present in the attributes array, specifies that the color buffers store red, green, blue, and alpha values. In this case, only RGBA pixel formats are considered. Do not supply a value with this constant because its presence in the array implies true.

If this attribute is not present in the attributes array, color buffers store color indexes. In this case, only color index pixel formats are considered.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_DOUBLEBUFFER

This constant is a Boolean attribute. If it is present in the attributes array, only double-buffered pixel formats are considered. Otherwise, only single-buffered pixel formats are considered. Do not supply a value with this constant because its presence in the array implies true.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_STEREO

This constant is a Boolean attribute. If it is present in the attributes array, only stereo pixel formats are considered. Otherwise, only monoscopic pixel formats are considered. Do not supply a value with this constant because its presence in the array implies true.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_AUX_BUFFERS

The associated value is a nonnegative integer that specifies the number of auxiliary buffers that are available. A value of 0 indicates that no auxiliary buffers exist. Pixel formats with the smallest number of auxiliary buffers that meet or exceed the specified number are preferred.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_RED_SIZE

The associated value is a nonnegative integer that specifies the number of red component bits. The value is 0 if the AGL_RGBA attribute is GL_FALSE. A red buffer that most closely matches the specified size is preferred.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_GREEN_SIZE

The associated value is a nonnegative integer that specifies the number of green component bits. The value is 0 if the AGL_RGBA attribute is GL_FALSE. A green buffer that most closely matches the specified size is preferred.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_BLUE_SIZE

The associated value is a nonnegative integer that specifies the number of blue component bits. The value is 0 if the AGL_RGBA attribute is GL_FALSE. A blue buffer that most closely matches the specified size is preferred.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_ALPHA_SIZE

The associated value is a nonnegative integer that specifies the number of alpha component bits. The value is 0 if the AGL_RGBA attribute is GL_FALSE. An alpha buffer that most closely matches the specified size is preferred.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_DEPTH_SIZE

The associated value is a nonnegative integer that specifies the number of bits in the depth buffer. A depth buffer that most closely matches the specified size is preferred.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_STENCIL_SIZE

The associated value is a nonnegative integer that specifies the number of bits in the stencil buffer. The smallest stencil buffer of at least the specified size is preferred.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_ACCUM_RED_SIZE

The associated value is a nonnegative integer that specifies the number of bits of red stored in the accumulation buffer. A red accumulation buffer that most closely matches the specified size is preferred.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_ACCUM_GREEN_SIZE

The associated value is a nonnegative integer that specifies the number of bits of green stored in the accumulation buffer. A green accumulation buffer that most closely matches the specified size is preferred.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_ACCUM_BLUE_SIZE

The associated value is a nonnegative integer that specifies the number of bits of blue stored in the accumulation buffer. A blue accumulation buffer that most closely matches the specified size is preferred.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_ACCUM_ALPHA_SIZE

The associated value is a nonnegative integer that specifies the number of bits of alpha stored in the accumulation buffer. An alpha accumulation buffer that most closely matches the specified size is preferred.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_PIXEL_SIZE

The associated value is a nonnegative integer that specifies the number frame buffer bits per pixel. The pixel size is the number of bits required to store each pixel in the color buffer, including unused bits. If the pixel format has an alpha channel that is stored in a separate buffer, its size is not included in the pixel size.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_MINIMUM_POLICY

This constant is a Boolean attribute. If it is present in the attributes array, the pixel format choosing policy is altered for the color, depth, and accumulation buffers such that only buffers of size greater than or equal to the desired size are considered. Do not supply a value with this constant because its presence in the array implies true.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_MAXIMUM_POLICY

This constant is a Boolean attribute. If it is present in the attributes array, the pixel format choosing policy is altered for the color, depth, and accumulation buffers such that, if a nonzero buffer size is requested, the largest available buffer is preferred. Do not supply a value with this constant because its presence in the array implies true.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_OFFSCREEN

This constant is a Boolean attribute. If it is present in the attributes array, only renderers that are capable of rendering to an off-screen memory area and have buffer depth exactly equal to the desired buffer depth are considered. Do not supply a value with this constant because its presence in the array implies true, and thereby enables the attribute.

If enabled, and if the drawable object currently attached to a rendering context is an offscreen drawable object, the associated values are the width, height, and row bytes of the offscreen memory area. If enabled, and if the drawable object is not an offscreen type, the width, height, and row bytes are each 0. When the AGL_OFFSCREEN attribute is present, the AGL_CLOSEST_POLICY attribute is implied.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_FULLSCREEN

This constant is a Boolean attribute. If it is present in the attributes array, only renderers that are capable of rendering to a full-screen drawable object are considered. Furthermore, the gdevs parameter must be set to a pointer to the GDevice on which full-screen rendering is desired and the ndev parameter must be set to 1.

If present, and if the drawable object that is currently attached to a rendering context is a full-screen drawable object, the associated values are the width, height, and refresh frequency of the full-screen device, rounded to the nearest integer. If present, and if the drawable object is not a full-screen type, the width, height, and refresh frequency are each 0.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_SAMPLE_BUFFERS_ARB

The associated value is the number of multisample buffers.

Available in OS X v10.2 and later.

Declared in agl.h.

AGL_SAMPLES_ARB

The associated value is the number of samples per multisample buffer.

Available in OS X v10.2 and later.

Declared in agl.h.

AGL_AUX_DEPTH_STENCIL

The associated value is the independent depth and/or the stencil buffers for the auxiliary buffer.

Available in OS X v10.2 and later.

Declared in agl.h.

AGL_COLOR_FLOAT

This constant is a Boolean attribute. If it is present in the attributes array, color buffers store floating-point pixels. Do not supply a value with this constant because its presence in the array implies true.

Available in OS X v10.3 and later.

Declared in agl.h.

AGL_MULTISAMPLE

This constant is a Boolean attribute. If it is present in the attributes array, specifies a hint to the driver to prefer multisampling. Do not supply a value with this constant because its presence in the array implies true.

Available in OS X v10.3 and later.

Declared in agl.h.

AGL_SUPERSAMPLE

This constant is a Boolean attribute. If it is present in the attributes array, specifies a hint to the driver to prefer supersampling. Do not supply a value with this constant because its presence in the array implies true.

Available in OS X v10.3 and later.

Declared in agl.h.

AGL_SAMPLE_ALPHA

This constant is a Boolean attribute. If it is present in the attributes array, request alpha filtering when multisampling. Do not supply a value with this constant because its presence in the array implies true.

Available in OS X v10.3 and later.

Declared in agl.h.

Discussion

Each of these constants can be assigned to the the attribute array passed to the function aglChoosePixelFormat. They can also be passed to the function aglDescribePixelFormat.

Declared In
agl.h

Buffer Mode Flags

Define constants used to set buffer modes.

#define AGL_MONOSCOPIC_BIT 0x00000001
#define AGL_STEREOSCOPIC_BIT 0x00000002
#define AGL_SINGLEBUFFER_BIT 0x00000004
#define AGL_DOUBLEBUFFER_BIT 0x00000008
Constants
AGL_MONOSCOPIC_BIT

A left buffer.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_STEREOSCOPIC_BIT

A left and right buffer.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_SINGLEBUFFER_BIT

A front buffer.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_DOUBLEBUFFER_BIT

A front and back buffer.

Available in OS X v10.0 and later.

Declared in agl.h.

Declared In
agl.h

Color Modes

Specify formats and color channel layout information for the color buffer.

#define AGL_RGB8_BIT 0x00000001
#define AGL_RGB8_A8_BIT 0x00000002
#define AGL_BGR233_BIT 0x00000004
#define AGL_BGR233_A8_BIT 0x00000008
#define AGL_RGB332_BIT 0x00000010
#define AGL_RGB332_A8_BIT 0x00000020
#define AGL_RGB444_BIT 0x00000040
#define AGL_ARGB4444_BIT 0x00000080
#define AGL_RGB444_A8_BIT 0x00000100
#define AGL_RGB555_BIT 0x00000200
#define AGL_ARGB1555_BIT 0x00000400
#define AGL_RGB555_A8_BIT 0x00000800
#define AGL_RGB565_BIT 0x00001000
#define AGL_RGB565_A8_BIT 0x00002000
#define AGL_RGB888_BIT 0x00004000
#define AGL_ARGB8888_BIT 0x00008000
#define AGL_RGB888_A8_BIT 0x00010000
#define AGL_RGB101010_BIT 0x00020000
#define AGL_ARGB2101010_BIT 0x00040000
#define AGL_RGB101010_A8_BIT 0x00080000
#define AGL_RGB121212_BIT 0x00100000
#define AGL_ARGB12121212_BIT 0x00200000
#define AGL_RGB161616_BIT 0x00400000
#define AGL_ARGB16161616_BIT 0x00800000
#define AGL_INDEX8_BIT 0x20000000
#define AGL_INDEX16_BIT 0x40000000
#define AGL_RGBFLOAT64_BIT 0x01000000
#define AGL_RGBAFLOAT64_BIT 0x02000000
#define AGL_RGBFLOAT128_BIT 0x04000000
#define AGL_RGBAFLOAT128_BIT 0x08000000
#define AGL_RGBFLOAT256_BIT 0x01000000
#define AGL_RGBAFLOAT256_BIT 0x02000000
Constants
AGL_RGB8_BIT

Specifies a format that has 8 bits per pixel with an RGB channel layout: RGB=7:0, inverse color map.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_RGB8_A8_BIT

Specifies an 8-8 ARGB bits per pixel format and the channels located in the following bits: A=7:0, RGB=7:0, inverse color map.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_BGR233_BIT

Specifies a format that has 8 bits per pixel with an RGB channel layout, and the channels located in the following bits: B=7:6, G=5:3, R=2:0

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_BGR233_A8_BIT

Specifies an 8-8 ARGB bits per pixel format and the channels located in the following bits: A=7:0, B=7:6, G=5:3, R=2:0

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_RGB332_BIT

Specifies a format that has 8 bits per pixel with an RGB channel layout, and the channels located in the following bits: R=7:5, G=4:2, B=1:0

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_RGB332_A8_BIT

Specifies an 8-8 ARGB bits per pixel format and the channels located in the following bits: A=7:0, R=7:5, G=4:2, B=1:0

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_RGB444_BIT

Specifies a format that has 16 bits per pixel with an RGB channel layout, and the channels located in the following bits: R=11:8, G=7:4, B=3:0

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_ARGB4444_BIT

Specifies a format that has 16 bits per pixel with an ARGB channel layout, and the channels located in the following bits: A=15:12, R=11:8, G=7:4, B=3:0

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_RGB444_A8_BIT

Specifies a format that has 8-16 bits per pixel with an ARGB channel layout, and the channels located in the following bits: A=7:0, R=11:8, G=7:4, B=3:0

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_RGB555_BIT

Specifies a format that has 16 bits per pixel with an RGB channel layout, and the channels located in the following bits: R=14:10, G=9:5, B=4:0. The top bit is not used.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_ARGB1555_BIT

Specifies a format that has 16 bits per pixel with an ARGB channel layout, and the channels located in the following bits: A=15, R=14:10, G=9:5, B=4:0

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_RGB555_A8_BIT

Specifies a format that has 8-16 bits per pixel with an ARGB channel layout, and the channels located in the following bits: A=7:0, R=14:10, G=9:5, B=4:0

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_RGB565_BIT

Specifies a format that has 16 bits per pixel with an RGB channel layout, and the channels located in the following bits: R=15:11, G=10:5, B=4:0

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_RGB565_A8_BIT

Specifies a format that has 8-16 bits per pixel with an ARGB channel layout, and the channels located in the following bits: A=7:0, R=15:11, G=10:5, B=4:0

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_RGB888_BIT

Specifies a format that has 32 bits per pixel with an RGB channel layout, and the channels located in the following bits: R=23:16, G=15:8, B=7:0; R, G, and B take 1 byte each.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_ARGB8888_BIT

Specifies a format that has 32 bits per pixel with an ARGB channel layout, and the channels located in the following bits: A=31:24, R=23:16, G=15:8, B=7:0

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_RGB888_A8_BIT

Specifies a format that has 8-32 bits per pixel with an ARGB channel layout, and the channels located in the following bits: A=7:0, R=23:16, G=15:8, B=7:0

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_RGB101010_BIT

Specifies a format that has 32 bits per pixel with an RGB channel layout, and the channels located in the following bits: R=29:20, G=19:10, B=9:0

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_ARGB2101010_BIT

Specifies a format that has 32 bits per pixel with an ARGB channel layout, and the channels located in the following bits: A=31:30 R=29:20, G=19:10, B=9:0

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_RGB101010_A8_BIT

Specifies a format that has 8-32 bits per pixel with an ARGB channel layout, and the channels located in the following bits: A=7:0 R=29:20, G=19:10, B=9:0

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_RGB121212_BIT

Specifies a format that has 48 bits per pixel with an RGB channel layout, and the channels located in the following bits: R=35:24, G=23:12, B=11:0

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_ARGB12121212_BIT

Specifies a format that has 48 bits per pixel with an ARGB channel layout, and the channels located in the following bits: A=47:36, R=35:24, G=23:12, B=11:0

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_RGB161616_BIT

Specifies a format that has 64 bits per pixel with an RGB channel layout, and the channels located in the following bits: R=47:32, G=31:16, B=15:0

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_ARGB16161616_BIT

Specifies a format that has 64 bits per pixel with an ARGB channel layout, and the channels located in the following bits: A=63:48, R=47:32, G=31:16, B=15:0

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_INDEX8_BIT

Specifies an 8 bit color look up table. (Deprecated)

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_INDEX16_BIT

Specifies an 16 bit color look up table. (Deprecated)

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_RGBFLOAT64_BIT

Specifies a format that has 64 bits per pixel with an RGB channel layout, half-floating point values. (A half-float is a 16-bit floating-point value.)

Available in OS X v10.3 and later.

Declared in agl.h.

AGL_RGBAFLOAT64_BIT

Specifies a format that has 64 bits per pixel with an ARGB channel layout, half-floating point values. (A half-float is a 16-bit floating-point value.)

Available in OS X v10.3 and later.

Declared in agl.h.

AGL_RGBFLOAT128_BIT

Specifies a format that has 128 bits per pixel with an RGB channel layout, IEEE floating point values.

Available in OS X v10.3 and later.

Declared in agl.h.

AGL_RGBAFLOAT128_BIT

Specifies a format that has 128 bits per pixel with an ARGB channel layout, IEEE floating point values.

Available in OS X v10.3 and later.

Declared in agl.h.

AGL_RGBFLOAT256_BIT

Specifies a format that has 256 bits per pixel with an RGB channel layout, IEEE double values.

Available in OS X v10.3 and later.

Declared in agl.h.

AGL_RGBAFLOAT256_BIT

Specifies a format that has 256 bits per pixel with an ARGB channel layout, IEEE double values.

Available in OS X v10.3 and later.

Declared in agl.h.

Declared In
agl.h

Context Options and Parameters

Define options and parameters that apply to a specific rendering context.

#define AGL_SWAP_RECT 200
#define AGL_BUFFER_RECT 202
#define AGL_SWAP_LIMIT 203
#define AGL_COLORMAP_TRACKING 210
#define AGL_COLORMAP_ENTRY 212
#define AGL_RASTERIZATION 220
#define AGL_SWAP_INTERVAL 222
#define AGL_STATE_VALIDATION 230
#define AGL_BUFFER_NAME 231
#define AGL_ORDER_CONTEXT_TO_FRONT 232
#define AGL_CONTEXT_SURFACE_ID 233
#define AGL_CONTEXT_DISPLAY_ID 234
#define AGL_SURFACE_ORDER 235
#define AGL_SURFACE_OPACITY 236
#define AGL_CLIP_REGION 254
#define AGL_FS_CAPTURE_SINGLE 255
#define AGL_SURFACE_BACKING_SIZE 304
#define AGL_ENABLE_SURFACE_BACKING_SIZE 305
#define AGL_SURFACE_VOLATILE 306
Constants
AGL_SWAP_RECT

Enable or set the swap rectangle. The associated parameter must contain four values: the x and y window coordinates of the swap rectangle, followed by its width and height. If enabled, the area of the window that is affected by the function aglSwapBuffers is restricted to a subrectangle of the entire window.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_BUFFER_RECT

Enable or set the buffer rectangle. The associated parameter must contain four values: the x and y window coordinates of the buffer rectangle, relative to the structure bounds of the window, followed by its width and height. If enabled, the drawable rectangle of the window and all of its associated buffers are restricted to the specified rectangle.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_SWAP_LIMIT

Enable or disable the swap asynchronous limit.

Available in OS X v10.2 and later.

Declared in agl.h.

AGL_COLORMAP_TRACKING

Enable or disable color map tracking.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_COLORMAP_ENTRY

The associated value is a color map entry specifies as {index, r, g, b}.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_RASTERIZATION

Enable or disable all rasterization of 2D and 3D primitives. You can use this option to debug and characterize the performance of an OpenGL driver without actually rendering.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_SWAP_INTERVAL

The associated parameter contains one value: the current swap interval setting. A value of 0 specifies not to synchronize to the vertical retrace. All other values indicate to synchronize to the vertical retrace.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_STATE_VALIDATION

Enables or disables state validation for multiscreen functionality. If enabled, the AGL library inspects the rendering context state each time that the function aglUpdateContext is called to ensure that it is in an appropriate state for switching between renderers. Normally, the state is inspected only when it is actually necessary to switch renderers. This option is useful when you want to use a single monitor system to test that an application will perform correctly on a multiple monitor system.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_BUFFER_NAME

The associated value is a buffer name. You can use this option to allow multiple OpenGL contexts to share a buffer.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_ORDER_CONTEXT_TO_FRONT

Specifies to order the current rendering context in front of all the other contexts.

Available in OS X v10.1 and later.

Declared in agl.h.

AGL_CONTEXT_SURFACE_ID

The associated value is the ID of the drawable surface for the rendering context. You can’t set this value because the system sets it. However, you can retrieve the value using the function aglGetInteger.

Available in OS X v10.2 and later.

Declared in agl.h.

AGL_CONTEXT_DISPLAY_ID

The associated value is a list of the display IDs of all displays touched by the rendering context, up to a maximum of 32 displays. You can’t set this list of values because the system assigns display ID values. However, you can retrieve the value using the function aglGetInteger.

Available in OS X v10.2 and later.

Declared in agl.h.

AGL_SURFACE_ORDER

The associated value is the position of the OpenGL surface relative to the window. A value of 1 means that the position is above the window; a value of –1 specifies a position that is below the window.

Available in OS X v10.2 and later.

Declared in agl.h.

AGL_SURFACE_OPACITY

The associated value specifies the opacity of the OpenGL surface. A value of 1 means the surface is opaque (the default); 0 means completely transparent.

Available in OS X v10.2 and later.

Declared in agl.h.

AGL_CLIP_REGION

Enables or sets the drawable clipping region. The associated value is a rgnHandle data type that defines the clipping region.

Available in OS X v10.2 and later.

Declared in agl.h.

AGL_FS_CAPTURE_SINGLE

Enables the capture of a single display for full-screen rendering. This option is disabled by default.

Available in OS X v10.2 and later.

Declared in agl.h.

AGL_SURFACE_BACKING_SIZE

The associated value specifies the width and height of surface backing size.

Available in OS X v10.4 and later.

Declared in agl.h.

AGL_ENABLE_SURFACE_BACKING_SIZE

Enable or disable the surface backing-size override.

Available in OS X v10.4 and later.

Declared in agl.h.

AGL_SURFACE_VOLATILE

Flags the surface as a candidate for deletion.

Available in OS X v10.4 and later.

Declared in agl.h.

Declared In
agl.h

Error Codes

Defines the error codes that can be returned by the aglGetError function.

#define AGL_NO_ERROR                 0
#define AGL_BAD_ATTRIBUTE        10000
#define AGL_BAD_PROPERTY         10001
#define AGL_BAD_PIXELFMT         10002
#define AGL_BAD_RENDINFO         10003
#define AGL_BAD_CONTEXT          10004
#define AGL_BAD_DRAWABLE         10005
#define AGL_BAD_GDEV             10006
#define AGL_BAD_STATE            10007
#define AGL_BAD_VALUE            10008
#define AGL_BAD_MATCH            10009
#define AGL_BAD_ENUM             10010
#define AGL_BAD_OFFSCREEN        10011
#define AGL_BAD_FULLSCREEN       10012
#define AGL_BAD_WINDOW           10013
#define AGL_BAD_POINTER          10014
#define AGL_BAD_MODULE           10015
#define AGL_BAD_ALLOC            10016
#define AGL_BAD_CONNECTION       10017
Constants
AGL_NO_ERROR

No error.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_BAD_ATTRIBUTE

Invalid pixel format attribute.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_BAD_PROPERTY

Invalid renderer property.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_BAD_PIXELFMT

Invalid pixel format.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_BAD_RENDINFO

Invalid renderer info.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_BAD_CONTEXT

Invalid rendering context.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_BAD_DRAWABLE

Invalid drawable object. A change of virtual screens (renderers) fails if the surface width and height cannot be set to the values requested, or if the creation of a drawable object or surfaces needed to support a pixel buffer fails for other reasons.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_BAD_GDEV

Invalid graphics device.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_BAD_STATE

Invalid rendering context state.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_BAD_VALUE

Invalid numerical value.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_BAD_MATCH

Invalid share rendering context.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_BAD_ENUM

Invalid enumerant.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_BAD_OFFSCREEN

Invalid offscreen drawable object.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_BAD_FULLSCREEN

Invalid full-screen drawable object.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_BAD_WINDOW

Invalid window.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_BAD_POINTER

Invalid pointer.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_BAD_MODULE

Invalid code module.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_BAD_ALLOC

Memory allocation failure.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_BAD_CONNECTION

Unable to connect to the window server.

Available in OS X v10.3 and later.

Declared in agl.h.

Discussion

Unlike many Carbon APIs, AGL functions don’t return result codes for specific error conditions. Instead, AGL functions that fail either return GL_FALSE or NULL. You can find out the specific nature of the error by calling the function aglGetError, which returns the appropriate error code.

Declared In
agl.h

Globally Configured Options

Specify options that apply globally.

#define AGL_FORMAT_CACHE_SIZE 501
#define AGL_CLEAR_FORMAT_CACHE 502
#define AGL_RETAIN_RENDERERS 503
Constants
AGL_FORMAT_CACHE_SIZE

The associated value is the size of the positive pixel format cache and is initially set to 5. If your application needs to use n different attribute lists to choose n different pixel formats repeatedly, then the application should set the cache size to n to maximize performance. After your application calls the aglChoosePixelFormat function for the last time, you might want to set the cache size to 1 to minimize the memory used by the AGL library.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_CLEAR_FORMAT_CACHE

When the associated value is nonzero, specifies to reset the pixel format cache. Clearing the cache does not affect the size of the cache for future storage of pixel formats. To minimize the memory consumed by the cache, your application should also set the cache size to 1.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_RETAIN_RENDERERS

Specifies whether or not to retain loaded plug-in renderers in memory. When the associated value is nonzero, the AGL library will not unload any plug-in renderers even if they are no longer in use. This option is useful to improve the performance of applications that repeatedly destroy and recreate their only (or last) rendering context. Normally, when the last rendering context created by a particular plug-in renderer is destroyed, that renderer is unloaded from memory. When the associated value is zero, AGL returns to its normal mode of operation and all renderers that are not in use are unloaded.

Available in OS X v10.0 and later.

Declared in agl.h.

Discussion

You can pass any of these options, along with the appropriate value, to the function aglConfigure.

Declared In
agl.h

Renderer Attributes

Define options for managing renderers.

#define AGL_RENDERER_ID 70
#define AGL_SINGLE_RENDERER 71
#define AGL_NO_RECOVERY 72
#define AGL_ACCELERATED 73
#define AGL_CLOSEST_POLICY 74
#define AGL_ROBUST 75
#define AGL_BACKING_STORE 76
#define AGL_MP_SAFE 78
#define AGL_WINDOW 80
#define AGL_MULTISCREEN 81
#define AGL_VIRTUAL_SCREEN 82
#define AGL_COMPLIANT 83
#define AGL_PBUFFER 90
#define AGL_REMOTE_PBUFFER 91
Constants
AGL_RENDERER_ID

The associated value is a nonnegative integer that specifies a renderer. If present, OpenGL renderers that match the specified ID are preferred. See “Renderer IDs” for possible values. You can pass this constant to the function aglDescribeRenderer.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_SINGLE_RENDERER

This constant is a Boolean attribute. If it is present in the attributes array, specifies that a single pixel format represents a single renderer for all screens. On systems with multiple screens, this option disables the ability of the AGL library to drive different monitors through different graphics accelerator cards with a single AGL rendering context.. Do not supply a value with this constant because its presence in the array implies true.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_NO_RECOVERY

This constant is a Boolean attribute. If it is present in the attributes array, specifies that failure recovery features are disabled for this pixel format. Normally, if an accelerated renderer cannot attach to a drawable object due to insufficient video memory, AGL automatically switches to another renderer. This attribute disables these features so that rendering will always be done by the chosen renderer. For example, with this option enabled, you won't get a software renderer as a fallback if a hardware-accelerated renderer runs out of resources.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_ACCELERATED

This constant is a Boolean attribute. If it is present in the attributes array, specifies renderers that are attached to a hardware accelerated graphics device. It is usually impossible to support more than one accelerated graphics device, because typically when a window spans more than one device, OpenGL uses the software renderer. You can pass this constant to the function aglDescribeRenderer to find out whether a particular renderer is hardware accelerated.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_CLOSEST_POLICY

The associated value specifies a color buffer size. When set, this option alters the pixel format choosing policy such that a color buffer closest to the requested size is preferred, regardless of the actual color buffer depth of the supported graphics device.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_ROBUST

This constant is a Boolean attribute. If it is present in the attributes array, specifies that AGL should consider only those renderers that do not have any failure modes associated with a lack of video card resources. You can pass this constant to the function aglDescribeRenderer.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_BACKING_STORE

This constant is a Boolean attribute. If it is present in the attributes array, specifies that AGL should consider only those renderers that have a back color buffer the full size of the drawable object (regardless of window visibility). AGL guarantees that the back buffer contents will be valid after a call to the aglSwapBuffers function. You can pass this constant to the function aglDescribeRenderer.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_MP_SAFE

This constant is a Boolean attribute. If it is present in the attributes array, specifies a renderer that is multiprocessor safe. This attribute is deprecated in OS X because all renderers can accept commands for threads running on a second processor. However, this does not mean that all renderers are thread-safe or reentrant.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_WINDOW

This constant is a Boolean attribute. If it is present in the attributes array, specifies that the pixel format can be used to render to an onscreen window. You can pass this constant to the function aglDescribeRenderer.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_MULTISCREEN

This constant is a Boolean attribute. If it is present in the attributes array, specifies that the renderer is capable of driving multiple screens with the same rendering context. (A single window can span multiple screens.) You can pass this constant to the function aglDescribeRenderer.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_VIRTUAL_SCREEN

The associated value is an integer that specifies the virtual screen number of the pixel format.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_COMPLIANT

This constant is a Boolean attribute. If it is present in the attributes array, specifies a pixel format that is fully compliant with OpenGL. All OS X renderers are OpenGL-compliant. You can pass this constant to the function aglDescribeRenderer.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_PBUFFER

This constant is a Boolean attribute. If it is present in the attributes array, specifies that the renderer can render to a pixel buffer. You can pass this constant to the function aglDescribeRenderer.

Available in OS X v10.3 and later.

Declared in agl.h.

AGL_REMOTE_PBUFFER

This constant is a Boolean attribute. If it is present in the attributes array, specifies that the renderer can render offline to a pixel buffer.

Available in OS X v10.3 and later.

Declared in agl.h.

Declared In
agl.h

Renderer IDs

Define constants that specify hardware and software renderers.

#define AGL_RENDERER_GENERIC_ID               0x00020200
#define AGL_RENDERER_GENERIC_FLOAT_ID         0x00020400
#define AGL_RENDERER_APPLE_SW_ID              0x00020600
#define AGL_RENDERER_ATI_RAGE_128_ID          0x00021000
#define AGL_RENDERER_ATI_RADEON_ID            0x00021200
#define AGL_RENDERER_ATI_RAGE_PRO_ID          0x00021400
#define AGL_RENDERER_ATI_RADEON_8500_ID       0x00021600
#define AGL_RENDERER_ATI_RADEON_9700_ID       0x00021800
#define AGL_RENDERER_ATI_RADEON_X1000_ID      0x00021900
#define AGL_RENDERER_NVIDIA_GEFORCE_2MX_ID    0x00022000
#define AGL_RENDERER_NVIDIA_GEFORCE_3_ID      0x00022200
#define AGL_RENDERER_NVIDIA_GEFORCE_FX_ID     0x00022400
#define AGL_RENDERER_VT_BLADE_XP2_ID          0x00023000
#define AGL_RENDERER_INTEL_900_ID             0x00024000
#define AGL_RENDERER_MESA_3DFX_ID             0x00040000
Constants
AGL_RENDERER_GENERIC_ID

A generic display device. (Deprecated. Deprecated on Intel-based Macintosh computers.)

Available in OS X v10.0 and later.

Declared in aglRenderers.h.

AGL_RENDERER_GENERIC_FLOAT_ID

A floating-point software renderer that is optimized for vector-based processors, is programmable, and supports shading.

Available in OS X v10.3 and later.

Declared in aglRenderers.h.

AGL_RENDERER_APPLE_SW_ID

The Apple software renderer.

Available in OS X v10.2 and later.

Declared in aglRenderers.h.

AGL_RENDERER_ATI_RAGE_128_ID

An ATI Rage 128 display device.

Available in OS X v10.2 and later.

Declared in aglRenderers.h.

AGL_RENDERER_ATI_RADEON_ID

An ATI Radeon display device.

Available in OS X v10.2 and later.

Declared in aglRenderers.h.

AGL_RENDERER_ATI_RAGE_PRO_ID

An ATI Rage Pro display device.

Available in OS X v10.2 and later.

Declared in aglRenderers.h.

AGL_RENDERER_ATI_RADEON_8500_ID

An ATI Radeon 8500 display device.

Available in OS X v10.2 and later.

Declared in aglRenderers.h.

AGL_RENDERER_ATI_RADEON_9700_ID

An ATI Radeon 9700 display device.

Available in OS X v10.3 and later.

Declared in aglRenderers.h.

AGL_RENDERER_ATI_RADEON_X1000_ID

An ATI Radeon 9700 display device.

Available in OS X v10.5 and later.

Declared in aglRenderers.h.

AGL_RENDERER_NVIDIA_GEFORCE_2MX_ID

An NVIDIA GeForce 2MX display device or an NVIDIA GeForce 4MX.

Available in OS X v10.2 and later.

Declared in aglRenderers.h.

AGL_RENDERER_NVIDIA_GEFORCE_3_ID

An NVIDIA GeForce 3 display device or an NVIDIA GeForce 4 Ti.

Available in OS X v10.2 and later.

Declared in aglRenderers.h.

AGL_RENDERER_NVIDIA_GEFORCE_FX_ID

An NVIDIA GeForce FX, GeForce 6, or GeForce 7 display device.

Available in OS X v10.3 and later.

Declared in aglRenderers.h.

AGL_RENDERER_VT_BLADE_XP2_ID

A Village Tronic display device.

Available in OS X v10.3 and later.

Declared in aglRenderers.h.

AGL_RENDERER_INTEL_900_ID

An Intel GMA 900 display device.

Available in OS X v10.5 and later.

Declared in aglRenderers.h.

AGL_RENDERER_MESA_3DFX_ID

A Mesa 3DFX display device.

Available in OS X v10.2 and later.

Declared in aglRenderers.h.

Declared In
aglrenderers.h

Renderer Properties

Specify constants that you can use to query renderer properties.

#define AGL_BUFFER_MODES 100
#define AGL_MIN_LEVEL 101
#define AGL_MAX_LEVEL 102
#define AGL_COLOR_MODES 103
#define AGL_ACCUM_MODES 104
#define AGL_DEPTH_MODES 105
#define AGL_STENCIL_MODES 106
#define AGL_MAX_AUX_BUFFERS 107
#define AGL_VIDEO_MEMORY 120
#define AGL_TEXTURE_MEMORY 121
#define AGL_RENDERER_COUNT 128
Constants
AGL_BUFFER_MODES

The associated value can be a bitwise OR of the any of the constants specified in “Buffer Mode Flags.”

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_MIN_LEVEL

The associated value specifies the minimum overlay buffer level. Negative values indicate an underlay buffer.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_MAX_LEVEL

The associated value specifies the maximum overlay buffer level.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_COLOR_MODES

The associated value can be a bitwise OR of any of the constants specified in “Color Modes.”

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_ACCUM_MODES

The associated value can be a bitwise OR of any of the constants specified in “Color Modes.”

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_DEPTH_MODES

The associated value can be the bitwise OR of any of the constants specified in “Bit Depths.”

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_STENCIL_MODES

The associated value can be the bitwise OR of any of the constants specified in “Bit Depths.”

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_MAX_AUX_BUFFERS

The associated value is the maximum number of auxiliary buffers that can be supported by the renderer.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_VIDEO_MEMORY

The associated value is the amount of video memory.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_TEXTURE_MEMORY

The associated value is the amount of texture memory.

Available in OS X v10.0 and later.

Declared in agl.h.

AGL_RENDERER_COUNT

The associated value is the number of renderers.

Available in OS X v10.3 and later.

Declared in agl.h.

Discussion

You can pass these constants to the function aglDescribeRenderer to find out the property value for a specific renderer.

Declared In
agl.h