CGL Reference

Framework	OpenGL/OpenGL.h
Companion guide	OpenGL Programming Guide for Mac
Declared in	CGLCurrent.h CGLTypes.h OpenGL.h

Overview

CGL (Core OpenGL) is the lowest-level programming interface for the Apple implementation of OpenGL. CGL supports full-screen OpenGL drawing and drawing to pixel buffers, which are a hardware-accelerated offscreen drawing location. Any Cocoa or Carbon application can use CGL to get the most direct access to system functionality. The Cocoa classes that support OpenGL and the AGL API are each built on top of CGL.

Functions by Task

Managing Pixel Format Objects

Managing Contexts

Getting and Setting Context Options

Locking and Unlocking Contexts

Managing Drawable Objects

Managing Pixel Buffers

Getting Error Information

Getting and Setting Global Information

Getting Renderer Information

Managing Virtual Screens

Functions

CGLChoosePixelFormat

Creates a pixel format object that satisfies the constraints of the specified buffer and renderer attributes.

CGLError CGLChoosePixelFormat (
   const CGLPixelFormatAttribute *attribs,
   CGLPixelFormatObj *pix,
   GLint *npix
);

Parameters

attribs: A 0 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” and the Discussion below.
pix: The memory address of a pixel format object. On return, points to a new pixel format object that contains pixel format information and a list of virtual screens. If there are no pixel formats or virtual screens that satisfy the constraints of the buffer and renderer attributes, the value of pix is set to NULL.
npix: On return, points to the number of virtual screens referenced by pix. If pix is NULL, the value of npix is set to 0.

Return Value

A result code. See “CGL Result Codes.”

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. Attributes can have different values for each virtual screen. You can use the kCGLPFAMinimumPolicy and kCGLPFAMaximumPolicy 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:

The integer attribute constants must be followed by a value:

kCGLPFAColorSize
kCGLPFAAlphaSize
kCGLPFADepthSize
kCGLPFAStencilSize
kCGLPFAAccumSize
kCGLPFASampleBuffers
kCGLPFASamples
kCGLPFARendererID
kCGLPFADisplayMask
kCGLPFAOpenGLProfile
kCGLPFAVirtualScreenCount

Starting in OS X v10.5, pixel format objects are reference counted. Pixel format objects are created with a reference count of 1 and are destroyed when the last reference to the object is released.

Availability

Available in OS X v10.0 and later.

Related Sample Code

Declared In

OpenGL.h

CGLClearDrawable

Disassociates a rendering context from any drawable objects attached to it.

CGLError CGLClearDrawable (
   CGLContextObj ctx
);

Parameters

ctx: A rendering context.

Return Value

A result code. See “CGL Result Codes.”

Availability

Available in OS X v10.0 and later.

Related Sample Code

GLFullScreen

Declared In

OpenGL.h

CGLCreateContext

Creates a CGL rendering context.

CGLError CGLCreateContext (
   CGLPixelFormatObj pix,
   CGLContextObj share,
   CGLContextObj *ctx
);

Parameters

pix: A pixel format object created by calling the function CGLChoosePixelFormat.
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.
ctx: The memory address of a context object. On return, points to a new context object with the buffers and attributes specified by the pix parameter. If the context can not be created as specified, the value of ctx is set to NULL.

Return Value

A result code. See “CGL Result Codes.”

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 display by using the same pixel format object for all shared rendering contexts. For more information, see OpenGL Programming Guide for Mac.

Starting in OS X v10.5, CGL rendering objects are reference counted. Pixel format objects are created with a reference count of 1 and are destroyed when the last reference to the object is released.

Availability

Available in OS X v10.0 and later.

Related Sample Code

Declared In

OpenGL.h

CGLDescribePixelFormat

Retrieves the values of an attribute associated with a pixel format object.

CGLError CGLDescribePixelFormat (
   CGLPixelFormatObj pix,
   GLint pix_num,
   CGLPixelFormatAttribute attrib,
   GLint *value
);

Parameters

pix: The pixel format object to query.
pix_num: The virtual screen number whose attribute value you want to retrieve. This value must be between 0 and the number of virtual screens minus one.
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

A result code. See “CGL Result Codes.”

Discussion

A pixel format object can contain different values for each virtual screen, which is why you must supply a virtual screen number in the pix_num parameter.

You can obtain the number of virtual screens associated with the pixel format object by calling the function CGLDescribePixelFormat, passing the pixel format object, 0 for the virtual screen number, and the attribute constant kCGLPFAVirtualScreenCount. For more information about virtual screens, see OpenGL Programming Guide for Mac.

Availability

Available in OS X v10.0 and later.

Declared In

OpenGL.h

CGLDescribeRenderer

Obtains the value associated with a renderer property.

CGLError CGLDescribeRenderer (
   CGLRendererInfoObj rend,
   GLint rend_num,
   CGLRendererProperty prop,
   GLint *value
);

Parameters

rend: An opaque renderer information object that contains a description of the renderer capabilities you want to inspect. You can obtain a renderer information object by calling the function CGLQueryRendererInfo. You must call CGLDestroyRendererInfo when you no longer need this object.
rend_num: The index of the renderer inside the renderer information object—a value between 0 and the number of renderers minus one. The number of renderers can be obtained by calling CGLDescribeRenderer, passing in rend, renderer number 0, and the renderer property kCGLRPRendererCount.
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.
value: On return, points to the value of the requested property.

Return Value

A result code. See “CGL Result Codes.”

Availability

Available in OS X v10.0 and later.

Related Sample Code

Declared In

OpenGL.h

CGLDestroyContext

Frees the resources associated with a rendering context.

CGLError CGLDestroyContext (
   CGLContextObj ctx
);

Parameters

ctx: The rendering context to destroy.

Return Value

A result code. See “CGL Result Codes.”

Discussion

Starting in Mac OS 10.5, CGL rendering contexts are reference counted. For compatibility reasons, calling CGLDestroyContext clears the drawable associated with the rendering context. Calling CGLDestroyContext is the equivalent of calling both CGLClearDrawable and CGLReleaseContext).

Availability

Available in OS X v10.0 and later.

Related Sample Code

Declared In

OpenGL.h

CGLDestroyPixelFormat

Frees the memory associated with a pixel format object.

CGLError CGLDestroyPixelFormat (
   CGLPixelFormatObj pix
);

Parameters

pix: The pixel format object to destroy.

Return Value

A result code. See “CGL Result Codes.”

Discussion

Calling this function is equivalent to calling CGLReleasePixelFormat.

Availability

Available in OS X v10.0 and later.

Related Sample Code

Declared In

OpenGL.h

CGLDestroyRendererInfo

Frees resources associated with a renderer information object.

CGLError CGLDestroyRendererInfo (
   CGLRendererInfoObj rend
);

Parameters

rend: The renderer information object to destroy.

Return Value

A result code. See “CGL Result Codes.”

Availability

Available in OS X v10.0 and later.

Related Sample Code

Declared In

OpenGL.h

CGLDisable

Disables an option for a rendering context.

CGLError CGLDisable (
   CGLContextObj ctx,
   CGLContextEnable pname
);

Parameters

ctx: A rendering context.
pname: The option to disable. For a list of possible options, see “Context Options.”

Return Value

A result code. See “CGL Result Codes.”

Availability

Available in OS X v10.0 and later.

Related Sample Code

DispatchFractal

Declared In

OpenGL.h

CGLEnable

Enables an option for a rendering context.

CGLError CGLEnable (
   CGLContextObj ctx,
   CGLContextEnable pname
);

Parameters

ctx: A rendering context.
pname: The option to enable. For a list of possible options, see “Context Options.”

Return Value

A result code. See “CGL Result Codes.”

Discussion

Some context options have values associated with them. Use CGLSetParameter and CGLGetParameter to set and get context parameter values.

Availability

Available in OS X v10.0 and later.

Related Sample Code

Declared In

OpenGL.h

CGLErrorString

Returns a string that describes the specified result code.

const char * CGLErrorString (
   CGLError error
);

Parameters

error: The CGL result code constant returned from a CGL function. For a description of these constants, see “CGL Result Codes.”

Return Value

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

Availability

Available in OS X v10.0 and later.

Declared In

OpenGL.h

CGLFlushDrawable

Copies the back buffer of a double-buffered context to the front buffer.

CGLError CGLFlushDrawable (
   CGLContextObj ctx
);

Parameters

ctx: The context object.

Return Value

A result code. See “CGL Result Codes.”

Discussion

To create a double-buffered context, specify the kCGLPFADoubleBuffer attribute (see “Buffer and Renderer Attributes”) when you create the pixel format object for the rendering context. If the backing store attribute is set to false, the buffers can be exchanged rather than copied. This is often the case in full-screen mode. If the receiver is not a double-buffered context, this call does nothing.

If you set the swap interval attribute (kCGLCPSwapInterval) appropriately, the copy takes place during the vertical retrace of the display, rather than immediately after CGLFlushDrawable is called. An implicit glFlush operation is performed by CGLFlushDrawable before it returns. For optimal performance, an application should not call glFlush immediately before calling CGLFlushDrawable. Subsequent OpenGL commands can be issued immediately after calling CGLFlushDrawable, but are not executed until the buffer copy is completed. For more information about kCGLCPSwapInterval, see “Context Parameters.”

Availability

Available in OS X v10.0 and later.

Related Sample Code

Declared In

OpenGL.h

CGLGetContextRetainCount

Returns the current retain count of a CGL rendering context.

GLuint CGLGetContextRetainCount (
   CGLContextObj ctx
);

Parameters

ctx: The CGL rendering context whose retain count you wish to discover.

Return Value

The retain count of the CGL rendering context.

Availability

Available in OS X v10.5 and later.

Declared In

OpenGL.h

CGLGetCurrentContext

Returns the current rendering context.

CGLContextObj CGLGetCurrentContext (
   void
);

Return Value

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

Availability

Available in OS X v10.0 and later.

Related Sample Code

Declared In

CGLCurrent.h

CGLGetGlobalOption

Retrieves the value of a global option.

CGLError CGLGetGlobalOption (
   CGLGlobalOption pname,
   GLint *params
);

Parameters

pname: The name of the option whose value you want to get. See “Global Options” for a list of constants you can pass.
params: On return, a pointer to the value of the option.

Return Value

A result code. See “CGL Result Codes.”

Availability

Available in OS X v10.6 and later.

Declared In

OpenGL.h

CGLGetOption

Obtains the value of a global option. (Deprecated. Use CGLGetGlobalOption instead.)

CGLError CGLGetOption (
   CGLGlobalOption pname,
   GLint *param
);

Parameters

pname: The name of the option whose value you want to get. See “Global Options” for a list of constants you can pass.
param: On return, a pointer to the value of the option.

Return Value

A result code. See “CGL Result Codes.”

Availability

Available in OS X v10.0 and later.

Declared In

OpenGL.h

CGLGetParameter

Retrieves the value of a rendering context parameter.

CGLError CGLGetParameter (
   CGLContextObj ctx,
   CGLContextParameter pname,
   GLint *params
);

Parameters

ctx: A rendering context.
pname: The parameter whose value you want to retrieve. For a list of possible parameters, see “Context Parameters.”
params: On return, points to the value of the parameter.

Return Value

A result code. See “CGL Result Codes.”

Discussion

Some parameters may need to have a corresponding context option enabled for their value to take effect. You can enable, disable, and test whether an option is enabled with CGLEnable, CGLDisable, and CGLIsEnabled.

Availability

Available in OS X v10.0 and later.

Related Sample Code

Declared In

OpenGL.h

CGLGetPixelFormat

Retrieves the current pixel format associated with a CGL rendering context.

CGLPixelFormatObj CGLGetPixelFormat (
   CGLContextObj ctx
);

Parameters

ctx: The CGL rendering context whose format you want to receive.

Return Value

A pixel format object describing the pixel format of the CGL rendering context.

Discussion

The pixel format object is not retained before being returned to your application. If your application needs to maintain this object, it should call CGLRetainPixelFormat.

Availability

Available in OS X v10.5 and later.

Declared In

OpenGL.h

CGLGetPixelFormatRetainCount

Returns the retain count of a pixel format object.

GLuint CGLGetPixelFormatRetainCount (
   CGLPixelFormatObj pix
);

Parameters

pix: A pixel format object.

Return Value

The retain count of the pixel format object.

Discussion

You can use this function to monitor the retain count of a pixel format object.

Availability

Available in OS X v10.5 and later.

Declared In

OpenGL.h

CGLGetVersion

Gets the major and minor version numbers of the CGL library.

void CGLGetVersion (
   GLint *majorvers,
   GLint *minorvers
);

Parameters

majorvers: On return, points to the major version number of the CGL library.
minorvers: On return, points to the minor version number of the CGL library.

Discussion

CGL 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.

Availability

Available in OS X v10.0 and later.

Declared In

OpenGL.h

CGLGetVirtualScreen

Gets the current virtual screen number associated with a rendering context.

CGLError CGLGetVirtualScreen (
   CGLContextObj ctx,
   GLint *screen
);

Parameters

ctx: A rendering context.
screen: On return, points to the virtual screen associated with the context. The value is always 0 on a single-display system and –1 if the function fails for any reason.

Return Value

A result code. See “CGL Result Codes.”

Discussion

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.

Related Sample Code

OpenCL NBody Simulation Example

Declared In

OpenGL.h

CGLIsEnabled

Reports whether an option is enabled for a rendering context.

CGLError CGLIsEnabled (
   CGLContextObj ctx,
   CGLContextEnable pname,
   GLint *enable
);

Parameters

ctx: A rendering context.
pname: The option to query. For a list of possible options, see “Context Options.”
enable: On return, enable is set to true if the option is enabled.

Return Value

A result code. See “CGL Result Codes.”

Discussion

To set or get parameter values associated with a context option, use CGLSetParameter or CGLGetParameter.

Availability

Available in OS X v10.0 and later.

Declared In

OpenGL.h

CGLLockContext

Locks a CGL rendering context.

CGLError CGLLockContext (
   CGLContextObj ctx
);

Parameters

ctx: The CGL context to lock.

Return Value

A result code. See “CGL Result Codes.”

Discussion

The function CGLLockContext blocks the thread it is on until all other threads have unlocked the same context using the function CGLUnlockContext. You can use CGLLockContext recursively. Context-specific CGL calls by themselves do not require locking, but you can guarantee serial processing for a group of calls by surrounding them with CGLLockContext and CGLUnlockContext. Keep in mind that calls from the OpenGL API (the API provided by the Architecture Review Board) require locking.

Applications that use NSOpenGL classes with multithreading can lock contexts using the functions CGLLockContext and CGLUnlockContext. To perform rendering in a thread other than the main one, you can lock the context that you want to access and safely execute OpenGL commands. The locking calls must be placed around all OpenGL calls in all threads.

For more information on multithreading OpenGL applications, see OpenGL Programming Guide for Mac.

Availability

Available in OS X v10.4 and later.

Related Sample Code

Declared In

OpenGL.h

CGLQueryRendererInfo

Creates a renderer information object that contains properties and values for renderers able to drive all the specified displays in a given display mask.

CGLError CGLQueryRendererInfo (
   GLuint display_mask,
   CGLRendererInfoObj *rend,
   GLint *nrend
);

Parameters

display_mask: A bit field that contains the bitwise OR of OpenGL display masks returned by the CGDisplayIDToOpenGLDisplayMask function. If you want to obtain information for all renderers in the system you must call CGLQueryRendererInfo once for each display bit.
rend: The memory address of a renderer information object. On return, points to a renderer information object that describes all renderers that are able to drive the displays specified by the display_mask parameter. If display_mask does not specify any displays, the value of rend is set to NULL. You must call CGLDestroyRendererInfo when you no longer need this object.
nrend: On return, points to the number of renderers described in the renderer information object. If display_mask does not specify any displays, the value of nrend is set to 0.

Return Value

A result code. See “CGL Result Codes.”

Availability

Available in OS X v10.0 and later.

Related Sample Code

Declared In

OpenGL.h

CGLReleaseContext

Decrements the retain count on a CGL rendering context.

void CGLReleaseContext (
   CGLContextObj ctx
);

Parameters

ctx: The rendering context to be released.

Discussion

Each call to CGLReleaseContext decreases the retain count by 1.

When the retain count reaches 0, all resources associated with the rendering context are freed. If the rendering context that you pass is the current rendering context and it is freed, the current context is set to NULL and there is no current rendering context after the function executes. After the context is freed, you must make sure you do not use the destroyed rendering context. This includes using CGL macros in which the rendering context is explicitly passed to OpenGL.

Availability

Available in OS X v10.5 and later.

Declared In

OpenGL.h

CGLReleasePixelFormat

Decrements the reference count of a pixel format object.

void CGLReleasePixelFormat (
   CGLPixelFormatObj pix
);

Parameters

pix: The pixel format object whose reference count should be decremented.

Discussion

The system retains the pixel format object when you call the function CGLCreateContext, so you can release a pixel format object immediately after passing it to the context creation function.

Each call to CGLReleasePixelFormat decreases the reference count by 1. If the reference count reaches 0, the pixel format object is destroyed.

Availability

Available in OS X v10.5 and later.

Declared In

OpenGL.h

CGLRetainContext

Increments the retain count on a CGL rendering context.

CGLContextObj CGLRetainContext (
   CGLContextObj ctx
);

Parameters

ctx: The rendering context to be retained.

Return Value

The same context that was passed into the function.

Discussion

Each call to CGLRetainContext increases the retain count by 1. To prevent memory leaks, each retain call must be balanced with a call to CGLReleaseContext.

Availability

Available in OS X v10.5 and later.

Declared In

OpenGL.h

CGLRetainPixelFormat

Increments the receiver’s reference count.

CGLPixelFormatObj CGLRetainPixelFormat (
   CGLPixelFormatObj pix
);

Parameters

pix: The pixel format object whose reference count should be incremented.

Return Value

The object being retained.

Discussion

Each call to CGLRetainPixelFormat increases the reference count by 1. Each call to CGLRetainPixelFormat must be matched with a call to CGLReleasePixelFormat.

Availability

Available in OS X v10.5 and later.

Declared In

OpenGL.h

CGLSetCurrentContext

Sets the specified rendering context as the current rendering context.

CGLError CGLSetCurrentContext (
   CGLContextObj 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

A result code. See “CGL Result Codes.” If the function fails, the current context remains unchanged.

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.

Related Sample Code

Declared In

CGLCurrent.h

CGLSetGlobalOption

Sets the value of a global option.

CGLError CGLSetGlobalOption (
   CGLGlobalOption pname,
   const GLint *params
);

Parameters

pname: The name of the option whose value you want to set. See “Global Options” for a list of constants you can pass.
params: The value to set the option to.

Return Value

A result code. See “CGL Result Codes.”

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.6 and later.

Declared In

OpenGL.h

CGLSetOption

Sets the value of a global option. (Deprecated. Use CGLSetGlobalOption instead.)

CGLError CGLSetOption (
   CGLGlobalOption pname,
   GLint param
);

Parameters

pname: The name of the option whose value you want to set. See “Global Options” for a list of constants you can pass.
param: The value to set the option to.

Return Value

A result code. See “CGL Result Codes.”

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.

Declared In

OpenGL.h

CGLSetParameter

Sets the value of a rendering context parameter.

CGLError CGLSetParameter (
   CGLContextObj ctx,
   CGLContextParameter pname,
   const GLint *params
);

Parameters

ctx: A rendering context.
pname: The parameter whose value you want to set. For a list of possible parameters, see “Context Parameters.”
params: A pointer to the value to set the parameter to.

Return Value

A result code. See “CGL Result Codes.”

Discussion

Availability

Available in OS X v10.0 and later.

Related Sample Code

Declared In

OpenGL.h

CGLSetVirtualScreen

Forces subsequent OpenGL commands to the specified virtual screen.

CGLError CGLSetVirtualScreen (
   CGLContextObj 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. The number of virtual screens available in a context can be obtained by calling the function CGLDescribePixelFormat, passing in the pixel format object used to create the rendering context, 0 for the virtual screen number (pix_num parameter), and the attribute constant kCGLPFAVirtualScreenCount.

Return Value

A result code. See “CGL Result Codes.”

Discussion

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. You should use this function only when it is necessary to override the default behavior. The current virtual screen is normally set automatically. 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.

Related Sample Code

OpenCL NBody Simulation Example

Declared In

OpenGL.h

CGLUnlockContext

Unlocks a CGL rendering context.

CGLError CGLUnlockContext (
   CGLContextObj ctx
);

Parameters

ctx: The CGL context to unlock.

Return Value

A result code. See “CGL Result Codes.”

Availability

Available in OS X v10.4 and later.

Related Sample Code

Declared In

OpenGL.h

Data Types

CGLContextObj

Represents a pointer to an opaque CGL context object.

typedef struct _CGLContextObject *CGLContextObj;

Discussion

This data type points to a structure that CGL 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 a CGL context object.

Availability

Available in OS X v10.0 and later.

Declared In

CGLTypes.h

CGLPixelFormatObj

Represents a pointer to an opaque pixel format object.

typedef struct _CGLPixelFormatObject *CGLPixelFormatObj;

Discussion

This data type points to a structure that CGL 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.

Declared In

CGLTypes.h

CGLRendererInfoObj

Represents a pointer to an opaque renderer information object.

typedef struct _CGLRendererInfoObject *CGLRendererInfoObj;

Discussion

This data type points to a structure that CGL 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.

Declared In

CGLTypes.h

CGLPBufferObj

Represents a pointer to an opaque pixel buffer object.

typedef struct _CGLPBufferObject *CGLPBufferObj;

Discussion

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

Availability

Available in OS X v10.3 and later.

Declared In

CGLTypes.h

Constants

Buffer Mode Flags

Define constants used to set buffer modes.

#define kCGLMonoscopicBit   0x00000001
#define kCGLStereoscopicBit x00000002
#define kCGLSingleBufferBit x00000004
#define kCGLDoubleBufferBit x00000008

Constants

kCGLMonoscopicBit: The left buffer.
kCGLStereoscopicBit: The left and right buffer.
kCGLSingleBufferBit: The front buffer.
kCGLDoubleBufferBit: The front and back buffer.

Buffer and Renderer Attributes

Specify attributes used to choose pixel formats and virtual screens.

typedef enum _CGLPixelFormatAttribute {
   kCGLPFAAllRenderers       =   1,
   kCGLPFADoubleBuffer       =   5,
   kCGLPFAStereo             =   6,
   kCGLPFAAuxBuffers         =   7,
   kCGLPFAColorSize          =   8,
   kCGLPFAAlphaSize          =  11,
   kCGLPFADepthSize          =  12,
   kCGLPFAStencilSize        =  13,
   kCGLPFAAccumSize          =  14,
   kCGLPFAMinimumPolicy      =  51,
   kCGLPFAMaximumPolicy      =  52,
   kCGLPFAOffScreen          =  53,
   kCGLPFAFullScreen         =  54,
   kCGLPFASampleBuffers      =  55,
   kCGLPFASamples            =  56,
   kCGLPFAAuxDepthStencil    =  57,
   kCGLPFAColorFloat         =  58,
   kCGLPFAMultisample        =  59,
   kCGLPFASupersample        =  60,
   kCGLPFASampleAlpha        =  61,
   kCGLPFARendererID         =  70,
   kCGLPFASingleRenderer     =  71,
   kCGLPFANoRecovery         =  72,
   kCGLPFAAccelerated        =  73,
   kCGLPFAClosestPolicy      =  74,
   kCGLPFARobust             =  75,
   kCGLPFABackingStore       =  76,
   kCGLPFAMPSafe             =  78,
   kCGLPFAWindow             =  80,
   kCGLPFAMultiScreen        =  81,
   kCGLPFACompliant          =  83,
   kCGLPFADisplayMask        =  84,
   kCGLPFAPBuffer            =  90,
   kCGLPFARemotePBuffer      =  91,
   kCGLPFAAllowOfflineRenderers = 96,
   kCGLPFAAcceleratedCompute =  97,
   kCGLPFAOpenGLProfile      =  99,
   kCGLPFAVirtualScreenCount = 128,
} CGLPixelFormatAttribute;

Constants

kCGLPFAAllRenderers

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 CGLTypes.h.

kCGLPFADoubleBuffer

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 CGLTypes.h.

kCGLPFAStereo

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 CGLTypes.h.

kCGLPFAAuxBuffers

The associated value is a nonnegative integer that indicates the desired number of auxiliary buffers. Pixel formats with the smallest number of auxiliary buffers that meet or exceed the specified number are preferred. (Deprecated. Deprecated in OS X v10.7. This attribute must not be specified if the attributes array also requests a profile other than a legacy OpenGL profile; if present, pixel format creation fails.)

Available in OS X v10.0 and later.

Declared in CGLTypes.h.

kCGLPFAColorSize

The associated value is a nonnegative buffer size specification. A color buffer that most closely matches the specified size is preferred. If unspecified, OpenGL chooses a color buffer size that matches the screen.

Available in OS X v10.0 and later.

Declared in CGLTypes.h.

kCGLPFAAlphaSize

The associated value is a nonnegative buffer size specification. An alpha buffer that most closely matches the specified size is preferred.

Available in OS X v10.0 and later.

Declared in CGLTypes.h.

kCGLPFADepthSize

The associated value is a nonnegative depth buffer size specification. A depth buffer that most closely matches the specified size is preferred.

Available in OS X v10.0 and later.

Declared in CGLTypes.h.

kCGLPFAStencilSize

The associated value is a nonnegative integer that indicates the desired number of stencil bitplanes. The smallest stencil buffer of at least the specified size is preferred.

Available in OS X v10.0 and later.

Declared in CGLTypes.h.

kCGLPFAAccumSize

The associated value is a nonnegative buffer size specification. An accumulation buffer that most closely matches the specified size is preferred. (Deprecated. Deprecated in OS X v10.7. This attribute must not be specified if the attributes array also requests a profile other than a legacy OpenGL profile; if present, pixel format creation fails.)

Available in OS X v10.0 and later.

Declared in CGLTypes.h.

kCGLPFAMinimumPolicy

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 CGLTypes.h.

kCGLPFAMaximumPolicy

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 CGLTypes.h.

kCGLPFAOffScreen

This constant is a Boolean attribute. If it is present in the attributes array, only renderers that are capable of rendering to an offscreen memory area and have buffer depth exactly equal to the desired buffer depth are considered. The kCGLPFAClosestPolicy attribute is implied. Do not supply a value with this constant because its presence in the array implies true. (Deprecated. Deprecated in OS X v10.7. This attribute must not be specified if the attributes array also requests a profile other than a legacy OpenGL profile; if present, pixel format creation fails.)

Available in OS X v10.0 and later.

Declared in CGLTypes.h.

kCGLPFAFullScreen

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. The kCGLPFASingleRenderer attribute is implied. Do not supply a value with this constant because its presence in the array implies true. (Deprecated. Deprecated in OS X v10.6 or later. This attribute must not be specified if the attributes array also requests a profile other than a legacy OpenGL profile; if present, pixel format creation fails.)

Available in OS X v10.0 and later.

Declared in CGLTypes.h.

kCGLPFAAuxDepthStencil

This constant is a Boolean attribute. If it is present in the attributes array, each auxiliary buffer has its own depth-stencil buffer. Do not supply a value with this constant because its presence in the array implies true. (Deprecated. Deprecated in OS X v.10.7 or later. This attribute must not be specified if the attributes array also requests a profile other than a legacy OpenGL profile; if present, pixel format creation fails.)

Available in OS X v10.2 and later.

Declared in CGLTypes.h.

kCGLPFAColorFloat

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.2 and later.

Declared in CGLTypes.h.

kCGLPFAMultisample

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 CGLTypes.h.

kCGLPFASupersample

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 CGLTypes.h.

kCGLPFASampleAlpha

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 CGLTypes.h.

kCGLPFASampleBuffers

The number of multisample buffers. The associated value is a nonnegative integer that indicates the number of existing independent sample buffers. Typically, the value is 0 if no multisample buffer exists or 1.

Available in OS X v10.1 and later.

Declared in CGLTypes.h.

kCGLPFASamples

The number of samples per multisample buffer. The associated value is a nonnegative integer that indicates the desired number of samples that can be taken within a single pixel. The smallest sample buffer with at least the specified number of samples is preferred.

Available in OS X v10.1 and later.

Declared in CGLTypes.h.

kCGLPFARendererID

The associated value is a nonnegative renderer ID number and can be any of the constants defined in “Renderer IDs.” OpenGL renderers that match the specified ID are preferred. Of note is kCGLRendererGenericFloatID, which selects the Apple software renderer. The other constants select renderers for specific hardware vendors.

Available in OS X v10.0 and later.

Declared in CGLTypes.h.

kCGLPFASingleRenderer

This constant is a Boolean attribute. If it is present in the attributes array, a single rendering engine is chosen. On systems with multiple displays, this disables ability of OpenGL to drive different displays through different graphics accelerator cards with a single context. This attribute is not generally useful. 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 CGLTypes.h.

kCGLPFANoRecovery

This constant is a Boolean attribute. If it is present in the attributes array, the OpenGL failure recovery mechanisms are disabled. Normally, if an accelerated renderer fails due to lack of resources, OpenGL automatically switches to another renderer. This attribute disables these features so that rendering is always performed by the chosen renderer. This attribute is not generally useful. 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 CGLTypes.h.

kCGLPFAAccelerated

This constant is a Boolean attribute. If it is present in the attributes array, only hardware accelerated renderers are considered. If false, accelerated renderers are still 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 CGLTypes.h.

kCGLPFAClosestPolicy

This constant is a Boolean attribute. If it is present in the attributes array, the pixel format choosing policy is altered for the color buffer such that the buffer closest to the requested size is preferred, regardless of the actual color buffer depth of the supported graphics device. 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 CGLTypes.h.

kCGLPFARobust

This constant is a Boolean attribute. If it is present in the attributes array, only renderers that do not have any failure modes associated with a lack of video card resources are considered. This attribute is not generally useful. Do not supply a value with this constant because its presence in the array implies true. (Deprecated. Deprecated in OS X v10.5 and later. This attribute must not be specified if the attributes array also requests a profile other than a legacy OpenGL profile; if present, pixel format creation fails.)

Available in OS X v10.0 and later.

Declared in CGLTypes.h.

kCGLPFABackingStore

This constant is a Boolean attribute. If it is present in the attributes array, OpenGL considers only renderers that have a back color buffer the full size of the drawable object and that guarantee the back buffer contents to be valid after a call to CGLFlushDrawable. 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 CGLTypes.h.

kCGLPFAMPSafe

This constant is a Boolean attribute. If it is present in the attributes array, OpenGL considers only renderers that are thread-safe. Because all renderers are thread-safe, this attribute is not useful. Do not supply a value with this constant because its presence in the array implies true. (Deprecated. Deprecated in OS X v10.5 and later. This attribute must not be specified if the attributes array also requests a profile other than a legacy OpenGL profile; if present, pixel format creation fails.)

Available in OS X v10.0 and later.

Declared in CGLTypes.h.

kCGLPFAWindow

This constant is a Boolean attribute. If it is present in the attributes array, only renderers that are capable of rendering to a window are considered. This attribute is implied if neither kCGLPFAFullScreen nor kCGLPFAOffScreen is specified. Because CGL supports only full-screen or offscreen drawable objects, this attribute is not useful. Do not supply a value with this constant because its presence in the array implies true. (Deprecated. Deprecated in OS X v10.7. This attribute must not be specified if the attributes array also requests a profile other than a legacy OpenGL profile; if present, pixel format creation fails.)

Available in OS X v10.0 and later.

Declared in CGLTypes.h.

kCGLPFAMultiScreen

This constant is a Boolean attribute. If it is present in the attributes array, only renderers capable of driving multiple displays are considered. This attribute is not generally useful. Do not supply a value with this constant because its presence in the array implies true. (Deprecated. Deprecated in OS X v10.5 and later. This attribute must not be specified if the attributes array also requests a profile other than a legacy OpenGL profile; if present, pixel format creation fails.)

Available in OS X v10.0 and later.

Declared in CGLTypes.h.

kCGLPFACompliant

This constant is a Boolean attribute. If it is present in the attributes array, pixel format selection is only open to OpenGL compliant renderers. This attribute is implied unless kCGLPFAAllRenderers is specified. This attribute is not useful in the attribute array. Do not supply a value with this constant because its presence in the array implies true. (Deprecated. Deprecated in OS X v10.7. This attribute must not be specified if the attributes array also requests a profile other than a legacy OpenGL profile; if present, pixel format creation fails.)

Available in OS X v10.0 and later.

Declared in CGLTypes.h.

kCGLPFADisplayMask

The associated value is a bit mask of supported physical displays. All displays specified in the bit mask are guaranteed to be supported by the pixel format. Displays not specified in the bit mask may still be supported. The bit mask is managed by the Quartz Display Services, available in the CGDirectDisplay.h header of the Application Services umbrella framework. A CGDirectDisplayID must be converted to an OpenGL display mask using the function CGDisplayIDToOpenGLDisplayMask. This attribute is not generally useful.

Available in OS X v10.0 and later.

Declared in CGLTypes.h.

kCGLPFAPBuffer

This constant is a Boolean attribute. If it is present in the attributes array, the pixel format can be used to render to a pixel buffer. Do not supply a value with this constant because its presence in the array implies true. (Deprecated. Deprecated in OS X v10.7. This attribute must not be specified if the attributes array also requests a profile other than a legacy OpenGL profile; if present, pixel format creation fails.)

Available in OS X v10.3 and later.

Declared in CGLTypes.h.

kCGLPFARemotePBuffer

This constant is a Boolean attribute. If it is present in the attributes array, the pixel format can be used to render offline to a pixel buffer. Do not supply a value with this constant because its presence in the array implies true. (Deprecated. Deprecated in OS X v10.7. This attribute must not be specified if the attributes array also requests a profile other than a legacy OpenGL profile; if present, pixel format creation fails.)

Available in OS X v10.3 and later.

Declared in CGLTypes.h.

kCGLPFAAllowOfflineRenderers

This constant is a Boolean attribute. If it is present in the attribute array, renderers that are available but not currently connected to a display may be considered.

Available in OS X v10.5 and later.

Declared in CGLTypes.h.

kCGLPFAAcceleratedCompute

This constant is a Boolean attribute. If it is present in the attributes array, only renderers that render to a hardware device that is capable of OpenCL processing are considered.

Available in OS X v10.6 and later.

Declared in CGLTypes.h.

kCGLPFAOpenGLProfile

The associated value can be any of the constants defined in “OpenGL Profiles.” If it is present in the attribute arrays, only renderers capable of supporting an OpenGL context that provides the functionality promised by the profile are considered.

Available in OS X v10.7 and later.

Declared in CGLTypes.h.

kCGLPFAVirtualScreenCount

This attribute may be used to obtain the number of virtual screens specified by an existing pixel format object. To retrieve the value, call the function CGLDescribePixelFormat, passing the pixel format object, the virtual screen number 0, and this attribute. This attribute is not useful in the attribute array that's used to create a pixel format object.

Available in OS X v10.0 and later.

Declared in CGLTypes.h.

Discussion

These constants are used by CGLChoosePixelFormat and CGLDescribePixelFormat. The existence of a Boolean attribute in the attribute array of CGLChoosePixelFormat implies a true value. Other attribute constants must be followed by a value.

Color and Accumulation Buffer Format Flags

Specify formats for the color and accumulation buffers.

#define kCGLRGB444Bit       0x00000040
#define kCGLARGB4444Bit     0x00000080
#define kCGLRGB444A8Bit     0x00000100
#define kCGLRGB555Bit       0x00000200
#define kCGLARGB1555Bit     0x00000400
#define kCGLRGB555A8Bit     0x00000800
#define kCGLRGB565Bit       0x00001000
#define kCGLRGB565A8Bit     0x00002000
#define kCGLRGB888Bit       0x00004000
#define kCGLARGB8888Bit     0x00008000
#define kCGLRGB888A8Bit     0x00010000
#define kCGLRGB101010Bit    0x00020000
#define kCGLARGB2101010Bit  0x00040000
#define kCGLRGB101010_A8Bit x00080000
#define kCGLRGB121212Bit    0x00100000
#define kCGLARGB12121212Bit x00200000
#define kCGLRGB161616Bit    0x00400000
#define kCGLRGBA16161616Bit x00800000
#define kCGLRGBFloat64Bit   0x01000000
#define kCGLRGBAFloat64Bit  0x02000000
#define kCGLRGBFloat128Bit  0x04000000
#define kCGLRGBAFloat128Bit x08000000
#define kCGLRGBFloat256Bit  0x10000000
#define kCGLRGBAFloat256Bit x20000000

Constants

kCGLRGB444Bit: 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.
kCGLARGB4444Bit: 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.
kCGLRGB444A8Bit: A format that has 8-16 bits per pixel with an RGB channel layout, and the channels located in the following bits: A=7:0, R=11:8, G=7:4, B=3:0.
kCGLRGB555Bit: 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.
kCGLARGB1555Bit: 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.
kCGLRGB555A8Bit: 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.
kCGLRGB565Bit: 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.
kCGLRGB565A8Bit: 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.
kCGLRGB888Bit: 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.
kCGLARGB8888Bit: 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.
kCGLRGB888A8Bit: 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.
kCGLRGB101010Bit: 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.
kCGLARGB2101010Bit: 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.
kCGLRGB101010_A8Bit: 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.
kCGLRGB121212Bit: 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.
kCGLARGB12121212Bit: 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.
kCGLRGB161616Bit: A format that has 64 bits per pixel with an RGB channel layout, and the channels located in the following bits: R=63:48, G=47:32, B=31:16.
kCGLRGBA16161616Bit: A format that has 64 bits per pixel with an ARGB channel layout, and the channels located in the following bits: R=63:48, G=47:32, B=31:16, A=15:0.
kCGLRGBFloat64Bit: A format that has 64 bits per pixel with an RGB half floating-point channel layout.
kCGLRGBAFloat64Bit: A format that has 64 bits per pixel with an ARGB half floating-point channel layout.
kCGLRGBFloat128Bit: A format that has 128 bits per pixel with an RGB IEEE floating-point channel layout.
kCGLRGBAFloat128Bit: A format that has 128 bits per pixel with an ARGB IEEE floating-point channel layout.
kCGLRGBFloat256Bit: A format that has 256 bits per pixel with an RGB IEEE double channel layout.
kCGLRGBAFloat256Bit: A format that has 256 bits per pixel with an ARGB IEEE double channel layout.

Context Options

Specify options that affect a rendering context.

typedef enum _CGLContextEnable {
   kCGLCESwapRectangle    = 201,
   kCGLCERasterization    = 221,
   kCGLCEStateValidation  = 301,
   kCGLCESurfaceBackingSize = 305,
   kCGLCEDisplayListOptimization = 307,
   kCGLCEMPEngine         = 313
} CGLContextEnable;

Constants

kCGLCESwapRectangle

If enabled, the area of the drawable object that is affected by CGLFlushDrawable is restricted to a rectangle specified by the values of kCGLCPSwapRectangle. However, the portion of the drawable object that lies outside of the swap rectangle may still be flushed to the screen by a visibility change or other user interface action. To set or get the values of kCGLCPSwapRectangle, use the functions CGLSetParameter or CGLGetParameter, respectively. For more information about kCGLCPSwapRectangle, see “Context Parameters.”

Available in OS X v10.0 and later.

Declared in CGLTypes.h.

kCGLCERasterization

If disabled, all rasterization of 2D and 3D primitives is disabled. This state is useful for debugging and to characterize the performance of an OpenGL driver without actually rendering.

Available in OS X v10.0 and later.

Declared in CGLTypes.h.

kCGLCEStateValidation

If enabled, OpenGL inspects the context state each time that CGLSetVirtualScreen 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. In CGL, a renderer is switched only if you call CGLSetVirtualScreen with a virtual screen number different from the current one.

Available in OS X v10.0 and later.

Declared in CGLTypes.h.

kCGLCESurfaceBackingSize

If enabled, overrides the surface backing size.

Available in OS X v10.3 and later.

Declared in CGLTypes.h.

kCGLCEDisplayListOptimization

If disabled, turns off optimization for the display list.

Available in OS X v10.3 and later.

Declared in CGLTypes.h.

kCGLCEMPEngine

If enabled, OpenGL performs its own internal calculations on a separate thread.

Available in OS X v10.4 and later.

Declared in CGLTypes.h.

Discussion

These are used by the functions CGLEnable, CGLDisable, and CGLIsEnabled.

Context Parameters

Specify parameters that apply to a specific rendering context.

typedef enum _CGLContextParameter {
   kCGLCPSwapRectangle    = 200,
   kCGLCPSwapInterval     = 222,
   kCGLCPDispatchTableSize = 224,
   kCGLCPClientStorage    = 226,
   kCGLCPSurfaceTexture    = 228,
   kCGLCPSurfaceOrder      = 235,
   kCGLCPSurfaceOpacity    = 236,
   kCGLCPSurfaceBackingSize = 304,
   kCGLCPSurfaceSurfaceVolatile = 306,
   kCGLCPReclaimResources  = 308,
   kCGLCPCurrentRendererID  = 309,
   kCGLCPGPUVertexProcessing  = 310,
   kCGLCPGPUFragmentProcessing  = 311,
   kCGLCPHasDrawable             = 314,
   kCGLCPMPSwapsInFlight         = 315,
} CGLContextParameter;

Constants

kCGLCPSwapRectangle

Set or get the swap rectangle. The swap rectangle is represented as an array of four long values: {x, y, width, height}. For this rectangle to affect the outcome of calling the function CGLFlushDrawable, the context option kCGLCESwapRectangle must be enabled. For more information about kCGLCESwapRectangle, see “Context Options.”

Available in OS X v10.0 and later.

Declared in CGLTypes.h.

kCGLCPSwapInterval

Set or get the swap interval. The swap interval is represented as one long value. If the swap interval is set to 0 (the default), CGLFlushDrawable executes as soon as possible, without regard to the vertical refresh rate of the monitor. If the swap interval is set to 1, the buffers are swapped only during the vertical retrace of the monitor.

Available in OS X v10.0 and later.

Declared in CGLTypes.h.

kCGLCPDispatchTableSize

Set or get the dispatch table size.

Available in OS X v10.3 and later.

Declared in CGLTypes.h.

kCGLCPClientStorage

Set or get an arbitrary 32-bit value. A typical usage would be to store a pointer to application-specific data associated with the context.

Available in OS X v10.0 and later.

Declared in CGLTypes.h.

kCGLCPSurfaceTexture

Set the surface texture. Supply a surface ID, target, and internal format.

Available in OS X v10.3 and later.

Declared in CGLTypes.h.

kCGLCPSurfaceOrder

Set or get 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 CGLTypes.h.

kCGLCPSurfaceOpacity

Set or get the surface opacity. 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 CGLTypes.h.

kCGLCPSurfaceBackingSize

Set or get the height and width of the back buffer. You can use this to let the system scale an image automatically on swapping to a variable-size buffer. The back buffer size remains fixed at the size that you set up regardless of whether the image is resized to display larger onscreen.

Available in OS X v10.3 and later.

Declared in CGLTypes.h.

kCGLCPSurfaceSurfaceVolatile

Set or get the volatile state of a surface.

Available in OS X v10.3 and later.

Declared in CGLTypes.h.

kCGLCPReclaimResources

Enable or disable reclaiming resources.

Available in OS X v10.4 and later.

Declared in CGLTypes.h.

kCGLCPCurrentRendererID

The current renderer ID. You can get this setting.

Available in OS X v10.4 and later.

Declared in CGLTypes.h.

kCGLCPGPUVertexProcessing

The GPU is currently processing vertices with the GPU. You can get this state.

Available in OS X v10.4 and later.

Declared in CGLTypes.h.

kCGLCPGPUFragmentProcessing

The CPU is currently processing fragments with the GPU. You can get this state.

Available in OS X v10.4 and later.

Declared in CGLTypes.h.

kCGLCPHasDrawable

Returns a Boolean that indicates whether a drawable is attached to the context.

Available in OS X v10.5 and later.

Declared in CGLTypes.h.

kCGLCPMPSwapsInFlight

The number of frames that the multithreaded OpenGL engine can process before stalling. The default value is 1. New frames are queued when the application calls CGLFlushDrawable. A larger number may improve overall performance, but adds latency between when a frame is rendered and when a frame is displayed. Interactive applications should leave this value at the default.

Available in OS X v10.5 and later.

Declared in CGLTypes.h.

Discussion

These constants are used by the functions CGLSetParameter and CGLGetParameter.

Global Options

Specify options that apply globally.

typedef enum _CGLGlobalOption {
   kCGLGOFormatCacheSize  = 501,
   kCGLGOClearFormatCache = 502,
   kCGLGORetainRenderers  = 503,
   kCGLGOResetLibrary     = 504,
   kCGLGOUseErrorHandler  = 505,
   kCGLGOUseBuildCache    = 506,
} CGLGlobalOption;

Constants

kCGLGOFormatCacheSize

The pixel format cache size, a positive integer. After an application calls CGLChoosePixelFormat for the last time, it may set the cache size to 1 to minimize the memory used by CGL. If an application intends 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. The cache size is initially set to 5.

Available in OS X v10.0 and later.

Declared in CGLTypes.h.

kCGLGOClearFormatCache

If set to a true value, the pixel format object cache contents are freed. This does not affect the size of the cache for future storage of pixel format objects. To minimize the memory consumed by the cache, the application should also set the cache size to 1 via the kCGLGOFormatCacheSize global option. CGLGetGlobalOption always reports a false value for this constant.

Available in OS X v10.0 and later.

Declared in CGLTypes.h.

kCGLGORetainRenderers

If true, CGL does not unload any plug-in renderers even if they are no longer in use. This constant is useful to improve the performance of applications that repeatedly destroy and recreate their only (or last) rendering context. Normally, when the last context created by a particular plug-in renderer is destroyed, that renderer is unloaded from memory. If false, CGL 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 CGLTypes.h.

kCGLGOResetLibrary

If set to a true value, CGL is reset to its initial state. All contexts created with CGLCreateContext are destroyed, all plug-in renderers are unloaded from memory, and global options are reset to their initial values. Renderer information objects and pixel format objects are not destroyed. CGLGetGlobalOption always reports a false value for this constant. (Deprecated. Deprecated in OS X v10.4 or later.)

Available in OS X v10.0 and later.

Declared in CGLTypes.h.

kCGLGOUseErrorHandler

If true, CGL errors are propagated to Core Graphics.

Available in OS X v10.0 and later.

Declared in CGLTypes.h.

kCGLGOUseBuildCache

If true, the shader compiler utilizes more memory to cache portions of compiled shaders. Shaders that share similar code may be compiled more quickly when this is enabled. This feature is off by default, and must be enabled at startup. (Deprecated. Deprecated in OS X v 10.6 or later.)

Available in OS X v10.5 and later.

Declared in CGLTypes.h.

Discussion

These constants are used by the functions CGLGetGlobalOption and CGLSetGlobalOption.

Renderer IDs

Define constants that specify hardware and software renderers.

kCGLRendererGenericID         0x00020200
kCGLRendererGenericFloatID    0x00020400
kCGLRendererAppleSWID         0x00020600
kCGLRendererATIRage128ID      0x00021000
kCGLRendererATIRadeonID       0x00021200
kCGLRendererATIRageProID      0x00021400
kCGLRendererATIRadeon8500ID   0x00021600
kCGLRendererATIRadeon9700ID   0x00021800
kCGLRendererATIRadeonX1000ID  0x00021900
kCGLRendererATIRadeonX2000ID  0x00021A00
kCGLRendererATIRadeonX3000ID  0x00021B00
kCGLRendererGeForce2MXID      0x00022000
kCGLRendererGeForce3ID        0x00022200
kCGLRendererGeForceFXID       0x00022400
kCGLRendererGeForce8xxxID     0x00022600
kCGLRendererVTBladeXP2ID      0x00023000
kCGLRendererIntel900ID        0x00024000
kCGLRendererIntelX3100ID      0x00024200
kCGLRendererIntelHDID         0x00024300
kCGLRendererMesa3DFXID        0x00040000
   
kCGLRendererIDMatchingMask    0x00FE7F00

Constants

kCGLRendererGenericID

The software renderer. (Deprecated. Deprecated in OS X v10.5 or later, and on all Intel-based Macintosh computers.)

kCGLRendererGenericFloatID

The floating-point software renderer.

kCGLRendererAppleSWID

The Apple software renderer ID.

kCGLRendererATIRage128ID

The ATI Rage128 renderer.

kCGLRendererATIRadeonID

The ATI Radeon renderer.

kCGLRendererATIRageProID

The ATI RagePro renderer.

kCGLRendererATIRadeon8500ID

The ATI Radeon 8500 renderer.

kCGLRendererATIRadeon9700ID

Specifies the ATI Radeon 9700 renderer.

kCGLRendererATIRadeonX1000ID

The ATI Radeon X1000 renderer.

kCGLRendererATIRadeonX2000ID

The ATI Radeon X2000 renderer.

kCGLRendererATIRadeonX3000ID

The ATI Radeon X3000 renderer.

kCGLRendererGeForce2MXID

The NVIDIA GeForce2MX or GeForce4MX renderer.

kCGLRendererGeForce3ID

The NVIDIA GeForce3 or GeForce4 renderer.

kCGLRendererGeForceFXID

The NVIDIA GeForceFX, GeForce 6xxx, or GeForce 7xxx renderer.

kCGLRendererGeForce8xxxID

The NVIDIA GeForce 8xxx and 9xxx renderers.

kCGLRendererVTBladeXP2ID

The VTBook renderer.

kCGLRendererIntel900ID

The Intel GMA 900 renderer.

kCGLRendererIntelX3100ID

The Intel GMA X3100 renderer.

kCGLRendererIntelHDID

The Intel HD Graphics renderer.

kCGLRendererMesa3DFXID

The Mesa 3DFX renderer.

kCGLRendererIDMatchingMask

Renderer IDs returned from CGLDescribePixelFormat must be combined with this mask using an AND operation before being compared to any of the renderer IDs found in this section. Bits that are outside this mask are reserved for use by Apple.

Declared In

CGLRenderers.h

OpenGL Profiles

Defines constants that specify the functionality provided by the renderer.

typedef enum _CGLOpenGLProfile {
   kCGLOGLPVersion_Legacy   = 0x1000,
   kCGLOGLPVersion_3_2_Core = 0x3200,
} CGLOpenGLProfile;

Constants

kCGLOGLPVersion_Legacy

The requested profile is a legacy (pre-OpenGL 3.0) profile.

Available in OS X v10.7 and later.

Declared in CGLTypes.h.

kCGLOGLPVersion_3_2_Core

The requested profile must implement the OpenGL 3.2 core functionality.

Available in OS X v10.7 and later.

Declared in CGLTypes.h.

Discussion

An OpenGL Profile is requested as part of the pixel format attributes string. When a context is created for a profile, the context must at least implement the requested version of the OpenGL specification. The context may implement a different version of the OpenGL specification as long as the version it implements is compatible with the requested version.

Renderer Properties

Specify renderer properties.

typedef enum _CGLRendererProperty {
   kCGLRPOffScreen           =  53,
   kCGLRPFullScreen          =  54,
   kCGLRPRendererID          =  70,
   kCGLRPAccelerated         =  73,
   kCGLRPRobust              =  75,
   kCGLRPBackingStore        =  76,
   kCGLRPMPSafe              =  78,
   kCGLRPWindow              =  80,
   kCGLRPMultiScreen         =  81,
   kCGLRPCompliant           =  83,
   kCGLRPDisplayMask         =  84,
   kCGLRPBufferModes         = 100,
   kCGLRPColorModes          = 103,
   kCGLRPAccumModes          = 104,
   kCGLRPDepthModes          = 105,
   kCGLRPStencilModes        = 106,
   kCGLRPMaxAuxBuffers       = 107,
   kCGLRPMaxSampleBuffers    = 108,
   kCGLRPMaxSamples          = 109,
   kCGLRPSampleModes         = 110,
   kCGLRPSampleAlpha         = 111,
   kCGLRPVideoMemory         = 120,
   kCGLRPTextureMemory       = 121,
   kCGLRPGPUVertProcCapable  = 122,
   kCGLRPGPUFragProcCapable  = 123,
   kCGLRPRendererCount       = 128,
   kCGLRPOnline              = 129,
   kCGLRPAcceleratedCompute  = 130,
   kCGLRPVideoMemoryMegabytes = 131,
   kCGLRPTextureMemoryMegabytes = 132,
} CGLRendererProperty;

Constants

kCGLRPOffScreen

This constant is a Boolean attribute. If true, the renderer supports offscreen drawable objects.

Available in OS X v10.0 and later.

Declared in CGLTypes.h.

kCGLRPFullScreen

This constant is a Boolean attribute. If true, the renderer supports full screen drawable objects.

Available in OS X v10.0 and later.

Declared in CGLTypes.h.

kCGLRPRendererID

The associated value is the renderer ID. Renderer ID constants are associated with specific hardware vendors. See “Renderer IDs.”

Available in OS X v10.0 and later.

Declared in CGLTypes.h.

kCGLRPAccelerated

This constant is a Boolean attribute. If true, the renderer is hardware accelerated.

Available in OS X v10.0 and later.

Declared in CGLTypes.h.

kCGLRPRobust

This constant is a Boolean attribute. If true, the renderer does not have any failure modes caused by a lack of video card resources.

Available in OS X v10.0 and later.

Declared in CGLTypes.h.

kCGLRPBackingStore

This constant is a Boolean attribute. If true, the renderer can provide a back color buffer the full size of the drawable object and can guarantee the back buffer contents to be valid after a call to CGLFlushDrawable.

Available in OS X v10.0 and later.

Declared in CGLTypes.h.

kCGLRPMPSafe

This constant is a Boolean attribute. If true, the renderer is thread-safe. All renderers are thread-safe in OS X.

Available in OS X v10.0 and later.

Declared in CGLTypes.h.

kCGLRPWindow

This constant is a Boolean attribute. If true, the renderer supports window drawable objects.

Available in OS X v10.0 and later.

Declared in CGLTypes.h.

kCGLRPMultiScreen

This constant is a Boolean attribute. If true, the renderer is presently attached to multiple displays.

Available in OS X v10.0 and later.

Declared in CGLTypes.h.

kCGLRPCompliant

This constant is a Boolean attribute. If true, the renderer is OpenGL compliant. All renderers are OpenGL compliant in OS X.

Available in OS X v10.0 and later.

Declared in CGLTypes.h.

kCGLRPDisplayMask

The associated value is a bit mask of physical displays that the renderer can drive. The bit mask is managed by Quartz Display Services. A CGDirectDisplayID data type must be converted to an OpenGL display mask using the function CGDisplayIDToOpenGLDisplayMask. For more information on this function, see Quartz Display Services Reference.

Available in OS X v10.0 and later.

Declared in CGLTypes.h.

kCGLRPBufferModes

The associated value is the bitwise OR of buffer mode flags supported by the renderer. The value can be any of the constants defined in “Buffer Mode Flags.”

Available in OS X v10.0 and later.

Declared in CGLTypes.h.

kCGLRPColorModes

The associated value is the bitwise OR of color format flags supported by the renderer. The value can be any of the constants defined in “Color and Accumulation Buffer Format Flags.”

Available in OS X v10.0 and later.

Declared in CGLTypes.h.

kCGLRPAccumModes

The associated value is the bitwise OR of color/accumulation buffer format flags supported by the renderer. The value can be any of the constants defined in “Color and Accumulation Buffer Format Flags.”

Available in OS X v10.0 and later.

Declared in CGLTypes.h.

kCGLRPDepthModes

The associated value is the bitwise OR of depth/stencil buffer depth flags supported by the renderer. The value can be any of the constants defined in “Stencil and Depth Modes.”

Available in OS X v10.0 and later.

Declared in CGLTypes.h.

kCGLRPStencilModes

The associated value is the bitwise OR of depth/stencil buffer depth flags supported by the renderer. The value can be any of the constants defined in “Stencil and Depth Modes.”

Available in OS X v10.0 and later.

Declared in CGLTypes.h.

kCGLRPMaxAuxBuffers

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

Available in OS X v10.0 and later.

Declared in CGLTypes.h.

kCGLRPMaxSampleBuffers

The associated value is the maximum number of independent sample buffers supported by the renderer. Typically, the value is 0 if no multisample buffer exists, or 1 if one exists.

Available in OS X v10.1 and later.

Declared in CGLTypes.h.

kCGLRPMaxSamples

The associated value is the maximum number of samples per pixel that the renderer supports.

Available in OS X v10.1 and later.

Declared in CGLTypes.h.

kCGLRPSampleModes

A bit field of supported sample modes.

Available in OS X v10.3 and later.

Declared in CGLTypes.h.

kCGLRPSampleAlpha

If true, there is support for alpha sampling.

Available in OS X v10.3 and later.

Declared in CGLTypes.h.

kCGLRPVideoMemory

The associated value is the number of bytes of video memory available to the renderer.

Available in OS X v10.0 and later.

Declared in CGLTypes.h.

kCGLRPTextureMemory

The associated value is the number of bytes of texture memory available to the renderer.

Available in OS X v10.0 and later.

Declared in CGLTypes.h.

kCGLRPGPUVertProcCapable

This constant is a Boolean attribute. If true, the renderer is capable of running vertex shader programs.

Available in OS X v10.4 and later.

Declared in CGLTypes.h.

kCGLRPGPUFragProcCapable

This constant is a Boolean attribute. If true, the renderer is capable of running fragment shader programs.

Available in OS X v10.4 and later.

Declared in CGLTypes.h.

kCGLRPRendererCount

The associated value is the number of renderers in a specific renderer information object. To determine the number of renderers in a renderer information object, call the function CGLDescribeRenderer, passing in the object, renderer number 0, and this renderer property.

Available in OS X v10.0 and later.

Declared in CGLTypes.h.

kCGLRPOnline

This constant is a Boolean attribute. If true, the renderer is currently attached to a display.

Available in OS X v10.5 and later.

Declared in CGLTypes.h.

kCGLRPAcceleratedCompute

This constant is a Boolean attribute. If true, the device is capable of running OpenCL programs.

Available in OS X v10.6 and later.

Declared in CGLTypes.h.

kCGLRPVideoMemoryMegabytes

The associated value is the number of megabytes of video memory available to the renderer.

Available in OS X v10.7 and later.

Declared in CGLTypes.h.

kCGLRPTextureMemoryMegabytes

The associated value is the number of megabytes of texture memory available to the renderer.

Available in OS X v10.7 and later.

Declared in CGLTypes.h.

Discussion

These constants are used by the function CGLDescribeRenderer.

Sampling Modes

Define modes used for full scene anti-aliasing.

#define kCGLSupersampleBit x00000001
#define kCGLMultisampleBit x00000002

Constants

kCGLSupersampleBit: Supersampling mode.
kCGLMultisampleBit: Multisampling mode.

Stencil and Depth Modes

Define resolutions for the depth and stencil buffers.

#define kCGL0Bit            0x00000001
#define kCGL1Bit            0x00000002
#define kCGL2Bit            0x00000004
#define kCGL3Bit            0x00000008
#define kCGL4Bit            0x00000010
#define kCGL5Bit            0x00000020
#define kCGL6Bit            0x00000040
#define kCGL8Bit            0x00000080
#define kCGL10Bit           0x00000100
#define kCGL12Bit           0x00000200
#define kCGL16Bit           0x00000400
#define kCGL24Bit           0x00000800
#define kCGL32Bit           0x00001000
#define kCGL48Bit           0x00002000
#define kCGL64Bit           0x00004000
#define kCGL96Bit           0x00008000
#define kCGL128Bit          0x00010000

Constants

kCGL0Bit: A 0-bit resolution.
kCGL1Bit: A 1-bit resolution.
kCGL2Bit: A 2-bit resolution.
kCGL3Bit: A 3-bit resolution.
kCGL4Bit: A 4-bit resolution.
kCGL5Bit: A 5-bit resolution.
kCGL6Bit: A 6-bit resolution.
kCGL8Bit: A 8-bit resolution.
kCGL10Bit: A 10-bit resolution.
kCGL12Bit: A 12-bit resolution.
kCGL16Bit: A 16-bit resolution.
kCGL24Bit: A 24-bit resolution.
kCGL32Bit: A 32-bit resolution.
kCGL48Bit: A 48-bit resolution.
kCGL64Bit: A 64-bit resolution.
kCGL96Bit: A 96-bit resolution.
kCGL128Bit: A 128-bit resolution.

Result Codes

The following result code constants, declared in the CGLTypes.h header file, can be used as parameters to the function CGLErrorString.

Result Code	Value	Description
`kCGLNoError`	0	No error. Available in OS X v10.3 and later.
`kCGLBadAttribute`	10000	Invalid pixel format attribute. Valid attributes can be found in “Buffer and Renderer Attributes.” Available in OS X v10.0 and later.
`kCGLBadProperty`	10001	Invalid renderer property. Valid renderer properties can be found in “Renderer Properties.” Available in OS X v10.0 and later.
`kCGLBadPixelFormat`	10002	Invalid pixel format object. A valid pixel format object can be obtained by calling the function `CGLChoosePixelFormat`. Available in OS X v10.0 and later.
`kCGLBadRendererInfo`	10003	Invalid renderer information object. A valid renderer information object can be obtained by calling the function `CGLQueryRendererInfo`. Available in OS X v10.0 and later.
`kCGLBadContext`	10004	Invalid context object. A valid context object can be obtained by calling the function `CGLCreateContext`. Available in OS X v10.0 and later.
`kCGLBadDrawable`	10005	Invalid drawable object. This error occurs when you attempt to attach a second, incompatible, rendering context to a drawable object. For more information about incompatible contexts, see the discussion section of the function `CGLCreateContext`. This error also occurs when you attempt to attach a context to a full-screen drawable object, and the color depth of the drawable object is different than that specified by the pixel format object used to create the context. The `kCGLPFAColorSize` attribute, described in “Buffer and Renderer Attributes,” specifies the color depth of a pixel format. Available in OS X v10.0 and later.
`kCGLBadDisplay`	10006	Invalid display. Available in OS X v10.0 and later.
`kCGLBadState`	10007	Invalid context state. This error occurs when a context state is inspected for readiness to switch renderers. To be in a valid state, a context be in render mode and have an attribute stack depth of `0`, and a modelview, projection, and texture stack depth of `1`. For more information about state verification, see the context enable constant `kCGLCEStateValidation`, described in “Context Options.” Available in OS X v10.0 and later.
`kCGLBadValue`	10008	Invalid numerical value. Available in OS X v10.0 and later.
`kCGLBadMatch`	10009	Invalid share context. Two contexts are a bad match if their pixel format objects use different renderers. Available in OS X v10.0 and later.
`kCGLBadEnumeration`	10010	Invalid constant. Available in OS X v10.0 and later.
`kCGLBadOffScreen`	10011	Invalid offscreen drawable object. Available in OS X v10.0 and later.
`kCGLBadFullScreen`	10012	Invalid full-screen drawable object. Available in OS X v10.0 and later.
`kCGLBadWindow`	10013	Invalid window. Available in OS X v10.0 and later.
`kCGLBadAddress`	10014	Invalid memory address. This error occurs when you pass an invalid pointer into a function that requires a memory address other than `NULL`. Available in OS X v10.0 and later.
`kCGLBadCodeModule`	10015	Invalid code module. Available in OS X v10.0 and later.
`kCGLBadAlloc`	10016	Invalid memory allocation. This error occurs when CGL is unable to allocate memory. Available in OS X v10.0 and later.
`kCGLBadConnection`	10017	Invalid connection to Core Graphics. Available in OS X v10.0 and later.

Did this document help you?

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.

CGL Reference

Overview

Functions by Task

Managing Pixel Format Objects

Managing Contexts

Getting and Setting Context Options

Locking and Unlocking Contexts

Managing Drawable Objects

Managing Pixel Buffers

Getting Error Information

Getting and Setting Global Information

Getting Renderer Information

Managing Virtual Screens

Functions

CGLChoosePixelFormat

Parameters

Return Value

Discussion

Availability

See Also

Related Sample Code

Declared In

CGLClearDrawable

Parameters

Return Value

Availability

See Also

Related Sample Code

Declared In

CGLCreateContext

Parameters

Return Value

Discussion

Availability

See Also

Related Sample Code

Declared In

CGLDescribePixelFormat

Parameters

Return Value

Discussion

Availability

See Also

Declared In

CGLDescribeRenderer

Parameters

Return Value

Availability

See Also

Related Sample Code

Declared In

CGLDestroyContext

Parameters

Return Value

Discussion

Availability

See Also

Related Sample Code

Declared In

CGLDestroyPixelFormat

Parameters

Return Value

Discussion

Availability

See Also

Related Sample Code

Declared In

CGLDestroyRendererInfo

Parameters

Return Value

Availability

See Also

Related Sample Code

Declared In

CGLDisable

Parameters

Return Value

Availability

See Also

Related Sample Code