Next Page >

Hide TOC

CGL Reference

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

Overview

The CGL (Core OpenGL) API is 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 NULL terminated array that contains a list of buffer and renderer attributes. Attributes can be Boolean or integer. If an attribute is integer, you must supply the desired value immediately following the attribute. If the attribute is Boolean, do not supply a value because its presence in the attributes array implies a true value. For information on the attributes that you can supply, see “Buffer and Renderer Attributes” 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 OS X.

The Boolean attribute constants include the following:

The integer attribute constants must be followed by a value:

Availability

Available in Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

Declared In

OpenGL.h

CGLCopyContext

Copies the specified state variables from one rendering context to another.

CGLError CGLCopyContext (
   CGLContextObj src,
   CGLContextObj dst,
   GLbitfield mask
);

Parameters

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

Return Value

A result code. See “CGL Result Codes.”

Discussion

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

Availability

Available in Mac OS X v10.0 and later.

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 OS X.

Availability

Available in Mac OS X v10.0 and later.

Declared In

OpenGL.h

CGLCreatePBuffer

Creates a pixel buffer of the specified size, compatible with the specified texture target.

CGLError CGLCreatePBuffer (
   GLsizei width,
   GLsizei height,
   GLenum target,
   GLenum internalFormat,
   GLint max_level,
   CGLPBufferObj *pbuffer
);

Parameters

width

The width, in pixels, of the pixel buffer.

height

The height, in pixels, of the pixel buffer.

target

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

GL_TEXTURE_2D, a texture whose dimensions are a power of two.
GL_TEXTURE_RECTANGLE_EXT, a texture whose dimensions are not a power of two.
GL_TEXTURE_CUBE_MAP, a mapped cube texture.

internalFormat

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

max_level

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

pbuffer

On return, points to a new pixel buffer object.

Return Value

A result code. See “CGL Result Codes.” This function returns kCGLBadAlloc if it cannot allocate storage for the pixel buffer data structure. It returns kCGLBadValue for any of these conditions:

A negative max_level value provided or a max_level value greater than the maximum possible mipmap levels for the given width and height provided.
A max_level value greater than 0 used with a GL_TEXTURE_RECTANGLE_EXT texture target
The dimensions provided for a GL_TEXTURE_CUBE_MAP texture target aren't equal.

Discussion

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

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

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

Availability

Available in Mac OS X v10.3 and later.

Declared In

OpenGL.h

CGLDescribePBuffer

Retrieves information that describes the specified pixel buffer object.

CGLError CGLDescribePBuffer (
   CGLPBufferObj obj,
   GLsizei *width,
   GLsizei *height,
   GLenum *target,
   GLenum *internalFormat,
   GLint *mipmap
);

Parameters

obj

A pointer to pixel buffer object.

width

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

height

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

target

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

GL_TEXTURE_2D, a texture whose dimensions are a power of two.
GL_TEXTURE_RECTANGLE_EXT, a texture whose dimensions are not a power of two.
GL_TEXTURE_CUBE_MAP, a mapped cube texture.

internalFormat

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

mipmap

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

Return Value

A result code. See “CGL Result Codes.”

Discussion

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

Availability

Available in Mac OS X v10.3 and later.

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, OpenGL Programming Guide for Mac OS X.

Availability

Available in Mac 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 Mac OS X v10.0 and later.

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

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

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

Availability

Available in Mac OS X v10.0 and later.

Declared In

OpenGL.h

CGLDestroyPBuffer

Releases the resources associated with a pixel buffer object.

CGLError CGLDestroyPBuffer (
   CGLPBufferObj pbuffer
);

Parameters

pbuffer: The pixel buffer object whose resources you want to release.

Return Value

A result code. See “CGL Result Codes.”

Discussion

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

The results of issuing commands to a destroyed pixel buffer object are undefined.

Availability

Available in Mac OS X v10.3 and later.

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

The system makes a copy of the pixel format object when you call the function CGLCreateContext, so you can free a pixel format object immediately after passing it to the context creation function.

Availability

Available in Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

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 Mac OS X v10.0 and later.

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 Mac 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 may 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 monitor, rather than immediately after CGLFlushDrawable is called. An implicit glFlush 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 Mac OS X v10.0 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 Mac OS X v10.0 and later.

Declared In

CGLCurrent.h

CGLGetOffScreen

Retrieves an offscreen buffer and its parameters for a specified rendering context.

CGLError CGLGetOffScreen (
   CGLContextObj ctx,
   GLsizei *width,
   GLsizei *height,
   GLint *rowbytes,
   void **baseaddr
);

Parameters

ctx: A rendering context.
width: On return, points to the width, in pixels, of the offscreen buffer. If the rendering context is not attached to an offscreen drawable object, the value of width is set to 0.
height: On return, points to the height, in pixels, of the offscreen buffer. If the rendering context is not attached to an offscreen drawable object, the value of height is set to 0.
rowbytes: On return, points to the number of bytes per row of the offscreen buffer. If the context is not attached to an offscreen drawable object, the value of rowbytes is set to 0.
baseaddr: On return, points to the base address of the offscreen buffer. If the context is not attached to an offscreen drawable object, the value of baseaddr is set to NULL.

Availability

Available in Mac OS X v10.0 and later.

Declared In

OpenGL.h

CGLGetOption

Obtains the value of a global option.

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 Mac 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 Mac OS X v10.0 and later.

Declared In

OpenGL.h

CGLGetPBuffer

Retrieves a pixel buffer and its parameters for a specified rendering context.

CGLError CGLGetPBuffer (
   CGLContextObj ctx,
   CGLPBufferObj *pbuffer,
   GLenum *face,
   GLint *level,
   GLint *screen
);

Parameters

ctx: A rendering context.
pbuffer: On return, points to the pixel buffer object attached to the rendering context.
face: On return, points to the cube map face that is set if the pixel buffer texture target type is GL_TEXTURE_CUBE_MAP; otherwise 0 for all other texture target types.
level: On return, points to the current mipmap level for drawing.
screen: On return, points to the current virtual screen number, as set by the last valid call to CGLSetPBuffer.

Return Value

A result code. See “CGL Result Codes.”

Availability

Available in Mac OS X v10.3 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 he 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 Mac OS X v10.0 and later.

Declared In

OpenGL.h

CGLGetVirtualScreen

Gets the current virtual screen number associated with 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-monitor 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 OS X.

Availability

Available in Mac OS X v10.0 and later.

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 Mac 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 OS X.

Availability

Available in Mac OS X v10.4 and later.

Declared In

OpenGL.h

CGLQueryRendererInfo

Creates a renderer information object that contains properties and values for all renderers driving the specified displays.

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, set every bit in display_mask to true.
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 Mac OS X v10.0 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 Mac OS X v10.0 and later.

Declared In

CGLCurrent.h

CGLSetFullScreen

Attaches a rendering context to its full-screen drawable object.

CGLError CGLSetFullScreen (
   CGLContextObj ctx
);

Parameters

ctx: A rendering context.

Return Value

A result code. See “CGL Result Codes.”

Discussion

Before calling this function, you must set up the rendering context using a pixel format object created with the kCGLPFAFullScreen attribute (see “Buffer and Renderer Attributes”). Some OpenGL renderers, such as the software renderer, do not support full-screen mode. After you call the function CGLChoosePixelFormat with the full-screen attribute, you need to check whether the pixel format object is created successfully.

You must capture the display prior to entering full-screen mode and release it after exiting. After calling this function subsequent OpenGL drawing is rendered into the entire screen. For more information, see OpenGL Programming Guide for Mac OS X.

To exit full-screen mode, call CGLClearDrawable.

Availability

Available in Mac OS X v10.0 and later.

Declared In

OpenGL.h

CGLSetOffScreen

Attaches a rendering context to an offscreen buffer.

CGLError CGLSetOffScreen (
   CGLContextObj ctx,
   GLsizei width,
   GLsizei height,
   GLint rowbytes,
   void *baseaddr
);

Parameters

ctx: A rendering context.
width: The width, in pixels, of the offscreen buffer.
height: The height, in pixels, of the offscreen buffer.
rowbytes: The number of bytes per row of the offscreen buffer, which must be greater than or equal to width times bytes per pixel.
baseaddr: A pointer to a block of memory to use as the offscreen buffer. The size of the memory must be at least rowbytes*height bytes.

Return Value

A result code. See “CGL Result Codes.”

Discussion

Before calling this function, you must set up the rendering context using a pixel format object created with the kCGLPFAOffScreen attribute. For more information about kCGLPFAOffScreen, see “Buffer and Renderer Attributes.”

After calling this function subsequent OpenGL drawing is rendered into the offscreen buffer and the viewport of the rendering context is set to the full size of the offscreen area.

To exit offscreen mode call CGLClearDrawable.

To obtain functionality similar to offscreen mode on renderers that do not support it, attach the context to a hidden window and use the OpenGL function glReadPixels.

Availability

Available in Mac OS X v10.0 and later.

Declared In

OpenGL.h

CGLSetOption

Sets the value of a global option.

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 Mac 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 the parameter to.

Return Value

A result code. See “CGL Result Codes.”

Discussion

Availability

Available in Mac OS X v10.0 and later.

Declared In

OpenGL.h

CGLSetPBuffer

Attaches a pixel buffer object to a rendering context.

CGLError CGLSetPBuffer (
   CGLContextObj ctx,
   CGLPBufferObj pbuffer,
   GLenum face,
   GLint level,
   GLint screen
);

Parameters

ctx: A rendering context.
pbuffer: A pixel buffer object.
face: The cube map face to draw if the pixel buffer texture target type is GL_TEXTURE_CUBE_MAP; otherwise pass 0.
level: The mipmap level to draw. This must not exceed the maximum mipmap level set when the pixel buffer object was created. Pass 0 for a texture target that does not support mipmaps.
screen: A virtual screen value. The virtual screen determines the renderer OpenGL uses to draw to the pixel buffer object. For best performance, for a pixel buffer used as a texture source, you should supply the a virtual screen value that results in using the same renderer used by the context that's the texturing target.

Return Value

A result code. See “CGL Result Codes.”

Discussion

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

The ability to attach a pbuffer to a context is supported only on renderers that export GL_APPLE_pixel_buffer in the GL_EXTENSIONS string. Before calling this function, you should programmatically determine if it’s possible to attach a pbuffer to a context by querying GL_EXTENSIONS in the context and looking for GL_APPLE_pixel_buffer. If that extension is not present, the renderer won’t allow setting the pbuffer.

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

A hardware renderer.
The generic render, but only with an offscreen pixel format and glTexSubImage.
The Apple software renderer, which supports pbuffers in Mac OS X v10.4.8 and later.

Availability

Available in Mac OS X v10.3 and later.

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 OS X.

Availability

Available in Mac OS X v10.0 and later.

Declared In

OpenGL.h

CGLTexImagePBuffer

Binds the contents of a pixel buffer to a data source for a texture object.

CGLError CGLTexImagePBuffer (
   CGLContextObj ctx,
   CGLPBufferObj pbuffer,
   GLenum source
);

Parameters

ctx: A rendering context, which is the target context for the texture operation. This is the context that you plan to render content to. This is not the context attached to the pixel buffer.
pbuffer: A pixel buffer object.
source: The source buffer to texture from, which should be a valid OpenGL buffer such as GL_FRONT or GL_BACK and should be compatible with the buffer and renderer attributes that you used to create the rendering context attached to the pixel buffer. This means that the pixel buffer must possess the buffer in question for the texturing operation to succeed.

Return Value

A result code. See “CGL Result Codes.”

Discussion

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

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

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

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

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

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

Availability

Available in Mac OS X v10.3 and later.

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 Mac OS X v10.4 and later.

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 Mac 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 Mac 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 Mac 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 Mac OS X v10.0 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: Specifies to use a left buffer.
kCGLStereoscopicBit: Specifies to a left and right buffer.
kCGLSingleBufferBit: Specifies to use a front buffer.
kCGLDoubleBufferBit: Specifies to use a front and back buffer.

Availability

Available in Mac OS X v10.0 and later.

Declared In

CGLTypes.h

Buffer and Renderer Attributes

Specify attributes used to choose pixel formats and virtual screens.

 typedef enum _CGLPix kCGLPFAAllRenderers kCGLPFADoubleBuffer kCGLPFAStereo kCGLPFAAuxBuffers kCGLPFAColorSize kCGLPFAAlphaSize kCGLPFADepthSize kCGLPFAStencilSize kCGLPFAAccumSize kCGLPFAMinimumPolicy kCGLPFAMaximumPolicy kCGLPFAOffScreen kCGLPFAFullScreen kCGLPFASampleBuffers kCGLPFASamples kCGLPFAAuxDepthStencil kCGLPFAColorFloat kCGLPFAMultisample kCGLPFASupersample kCGLPFASampleAlpha kCGLPFARendererID kCGLPFASingleRenderer kCGLPFANoRecovery kCGLPFAAccelerated kCGLPFAClosestPolicy kCGLPFARobust kCGLPFABackingStore kCGLPFAMPSafe kCGLPFAWindow kCGLPFAMultiScreen kCGLPFACompliant kCGLPFADisplayMask kCGLPFAPBuffer kCGLPFARemotePBuffer kCGLPFAVirtualS } CGLPixelFormatAttribute;

elFormatAttribute { = 1, = 5, = 6, = 7, = 8, = 11, = 12, = 13, = 14, = 51, = 52, = 53, = 54, = 55, = 56, = 57, = 58, = 59, = 60, = 61, = 70, = 71, = 72, = 73, = 74, = 75, = 76, = 78, = 80, = 81, = 83, = 84, = 90, = 91, creenCount = 128,

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.