Mac Developer Library

Developer

CGL Reference

Options
Deployment Target:

On This Page

CGL Reference

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

  • Creates a CGL rendering context.

    Declaration

    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.

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

    Declaration

    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.

  • Increments the retain count on a CGL rendering context.

    Declaration

    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.

  • Decrements the retain count on a CGL rendering context.

    Declaration

    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.

  • Returns the current retain count of a CGL rendering context.

    Declaration

    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.

  • Frees the resources associated with a rendering context.

    Declaration

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

    See Also

    CGLCreateContext

  • Returns the current rendering context.

    Declaration

    CGLContextObj CGLGetCurrentContext ( void );

    Return Value

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

  • Sets the specified rendering context as the current rendering context.

    Declaration

    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.

  • Enables an option for a rendering context.

    Declaration

    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.

  • Disables an option for a rendering context.

    Declaration

    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.

  • Reports whether an option is enabled for a rendering context.

    Declaration

    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.

  • Sets the value of a rendering context parameter.

    Declaration

    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

    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.

    See Also

    CGLGetParameter

  • Retrieves the value of a rendering context parameter.

    Declaration

    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.

    See Also

    CGLSetParameter

  • Locks a CGL rendering context.

    Declaration

    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.

    See Also

    CGLUnlockContext

  • Unlocks a CGL rendering context.

    Declaration

    CGLError CGLUnlockContext ( CGLContextObj ctx );

    Parameters

    ctx

    The CGL context to unlock.

    Return Value

    A result code. See CGL Result Codes.

    See Also

    CGLLockContext

  • Attaches a rendering context to an offscreen buffer.

    Declaration

    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.

    See Also

    CGLGetOffScreen

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

    Declaration

    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.

    See Also

    CGLSetOffScreen

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

    Use CGLSetFullScreenOnDisplay instead.

    Declaration

    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.

    To exit full-screen mode, call CGLClearDrawable.

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

    Declaration

    CGLError CGLSetFullScreenOnDisplay ( CGLContextObj ctx, GLuint display_mask );

    Parameters

    ctx

    A rendering context.

    display_mask

    A bit field that contains the OpenGL display mask for the screen you wish the context to cover.

    Return Value

    A result code. See CGL Result Codes.

    Discussion

    This function obtains a drawable object that covers an entire screen and attaches it to the rendering context. A full-screen rendering context may allow the underlying renderer to provide better performance compared to a context associated with a window that partially covers the screen.

    Prior to calling this function, your application should ensure that the context is capable of rendering to this display by querying the appropriate renderer properties. For more information, see CGLQueryRendererInfo. Note that some renderers, including the software renderer, do not support full-screen mode.

    You must capture the screen 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.

    To exit full-screen mode, call CGLClearDrawable.

    In OS X v10.6 or later, this function is not deprecated, but is usually not necessary. If your application creates a window that completely covers the screen, the system implicitly creates a full-screen instance, for the same potential performance benefit.

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

    Declaration

    CGLError CGLClearDrawable ( CGLContextObj ctx );

    Parameters

    ctx

    A rendering context.

    Return Value

    A result code. See CGL Result Codes.

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

    Declaration

    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.

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

    Declaration

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

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

  • Retrieves information that describes the specified pixel buffer object.

    Declaration

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

    Parameters

    obj

    A pointer to the 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.

    See Also

    CGLCreatePBuffer

  • Increments the retain count on a pixel buffer object.

    Declaration

    CGLPBufferObj CGLRetainPBuffer ( CGLPBufferObj pbuffer );

    Parameters

    pbuffer

    The pixel buffer object whose retain count you wish to increment.

    Return Value

    The pixel buffer object that received the call.

    Discussion

    Each call to CGLRetainPBuffer increases the retain count by 1. To prevent the pixel buffer object from being leaked, each retain call must be matched with a call to CGLReleasePBuffer.

  • Decrements the retain count on a pixel buffer object.

    Declaration

    void CGLReleasePBuffer ( CGLPBufferObj pbuffer );

    Parameters

    pbuffer

    The pixel buffer object whose retain count you wish to decrement.

    Discussion

    Call this function only after you no longer need to use the pixel buffer object. Before releasing the pixel buffer object, you should delete any texture objects associated with it. 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.

    Each call to CGLReleasePBuffer decreases the retain count by 1. When the retain count reaches 0, the pixel buffer object’s resources are freed and the object is destroyed. The results of issuing commands to a destroyed pixel buffer object are undefined.

  • Returns the retain count of a pixel buffer object.

    Declaration

    GLuint CGLGetPBufferRetainCount ( CGLPBufferObj pbuffer );

    Parameters

    pbuffer

    The pixel buffer object whose retain count you wish to retrieve.

    Return Value

    The retain count of the pixel buffer object.

  • Releases the resources associated with a pixel buffer object.

    Declaration

    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

    Starting in OS X v10.5, pixel buffer objects are reference counted. Calling this function is equivalent to calling CGLReleasePBuffer.

    See Also

    CGLCreatePBuffer

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

    Declaration

    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.

    See Also

    CGLSetPBuffer

  • Attaches a pixel buffer object to a rendering context.

    Declaration

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

    Parameters

    ctx

    The rendering context to attach the pixel buffer to.

    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 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 pixel buffer 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 pixel buffer 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 pixel buffer.

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

    • A hardware renderer.

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

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

    See Also

    CGLGetPBuffer

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

    Declaration

    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 get the 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.

  • Returns a string that describes the specified result code.

    Declaration

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

  • Sets the value of a global option.

    Use CGLSetGlobalOption instead.

    Declaration

    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.

    See Also

    CGLGetOption

  • Obtains the value of a global option.

    Use CGLGetGlobalOption instead.

    Declaration

    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.

    See Also

    CGLSetOption

  • Retrieves the value of a global option.

    Declaration

    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.

  • Sets the value of a global option.

    Declaration

    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.

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

    Declaration

    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.

  • Obtains the value associated with a renderer property.

    Declaration

    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.

  • Frees resources associated with a renderer information object.

    Declaration

    CGLError CGLDestroyRendererInfo ( CGLRendererInfoObj rend );

    Parameters

    rend

    The renderer information object to destroy.

    Return Value

    A result code. See CGL Result Codes.

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

    Declaration

    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.

  • Forces subsequent OpenGL commands to the specified virtual screen.

    Declaration

    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.

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

    Declaration

    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.

Data Types

  • Represents a pointer to an opaque CGL context object.

    Declaration

    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.

    Import Statement

  • Represents a pointer to an opaque pixel format object.

    Declaration

    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.

    Import Statement

  • Represents a pointer to an opaque renderer information object.

    Declaration

    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.

    Import Statement

  • Represents a pointer to an opaque pixel buffer object.

    Declaration

    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.

    Import Statement

Constants

  • Define constants used to set buffer modes.

    Declaration

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

  • Specify attributes used to choose pixel formats and virtual screens.

    Declaration

    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.

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

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

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

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

    • kCGLPFAAlphaSize

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

    • kCGLPFADepthSize

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

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

    • kCGLPFAAccumSize

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

      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.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    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.

  • Specify formats for the color and accumulation buffers.

    Declaration

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

  • Specify options that affect a rendering context.

    Declaration

    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.

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

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

    • kCGLCESurfaceBackingSize

      If enabled, overrides the surface backing size.

    • kCGLCEDisplayListOptimization

      If disabled, turns off optimization for the display list.

    • kCGLCEMPEngine

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

    Discussion

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

  • Specify parameters that apply to a specific rendering context.

    Declaration

    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.

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

    • kCGLCPDispatchTableSize

      Set or get the dispatch table size.

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

    • kCGLCPSurfaceTexture

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

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

    • kCGLCPSurfaceOpacity

      Set or get the surface opacity. A value of 1 means the surface is opaque (the default); 0 means completely transparent.

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

    • kCGLCPSurfaceSurfaceVolatile

      Set or get the volatile state of a surface.

    • kCGLCPReclaimResources

      Enable or disable reclaiming resources.

    • kCGLCPCurrentRendererID

      The current renderer ID. You can get this setting.

    • kCGLCPGPUVertexProcessing

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

    • kCGLCPGPUFragmentProcessing

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

    • kCGLCPHasDrawable

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

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

    Discussion

    These constants are used by the functions CGLSetParameter and CGLGetParameter.

  • Specify options that apply globally.

    Declaration

    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.

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

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

    • 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 in OS X v10.4 or later.

    • kCGLGOUseErrorHandler

      If true, CGL errors are propagated to Core Graphics.

    • 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 in OS X v 10.6 or later.

    Discussion

    These constants are used by the functions CGLGetGlobalOption and CGLSetGlobalOption.

  • Define constants that specify hardware and software renderers.

    Declaration

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

  • Defines constants that specify the functionality provided by the renderer.

    Declaration

    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.

    • kCGLOGLPVersion_3_2_Core

      The requested profile must implement the OpenGL 3.2 core functionality.

    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.

  • Specify renderer properties.

    Declaration

    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.

    • kCGLRPFullScreen

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

    • kCGLRPRendererID

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

    • kCGLRPAccelerated

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

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

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

    • kCGLRPMPSafe

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

    • kCGLRPWindow

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

    • kCGLRPMultiScreen

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

    • kCGLRPCompliant

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

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

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

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

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

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

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

    • kCGLRPMaxAuxBuffers

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

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

    • kCGLRPMaxSamples

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

    • kCGLRPSampleModes

      A bit field of supported sample modes.

    • kCGLRPSampleAlpha

      If true, there is support for alpha sampling.

    • kCGLRPVideoMemory

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

    • kCGLRPTextureMemory

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

    • kCGLRPGPUVertProcCapable

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

    • kCGLRPGPUFragProcCapable

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

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

    • kCGLRPOnline

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

    • kCGLRPAcceleratedCompute

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

    • kCGLRPVideoMemoryMegabytes

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

    • kCGLRPTextureMemoryMegabytes

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

    Discussion

    These constants are used by the function CGLDescribeRenderer.

  • Define modes used for full scene anti-aliasing.

    Declaration

    #define kCGLSupersampleBit x00000001 #define kCGLMultisampleBit x00000002

    Constants

    • kCGLSupersampleBit

      Supersampling mode.

    • kCGLMultisampleBit

      Multisampling mode.

  • Define resolutions for the depth and stencil buffers.

    Declaration

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

  • No error.

    Value

    0

    Description

    No error.

  • Invalid pixel format attribute. Valid attributes can be found in Buffer and Renderer Attributes.

    Value

    10000

    Description

    Invalid pixel format attribute. Valid attributes can be found in Buffer and Renderer Attributes.

  • Invalid renderer property. Valid renderer properties can be found in Renderer Properties.

    Value

    10001

    Description

    Invalid renderer property. Valid renderer properties can be found in Renderer Properties.

  • Invalid pixel format object. A valid pixel format object can be obtained by calling the function CGLChoosePixelFormat.

    Value

    10002

    Description

    Invalid pixel format object. A valid pixel format object can be obtained by calling the function CGLChoosePixelFormat.

  • Invalid renderer information object. A valid renderer information object can be obtained by calling the function CGLQueryRendererInfo.

    Value

    10003

    Description

    Invalid renderer information object. A valid renderer information object can be obtained by calling the function CGLQueryRendererInfo.

  • Invalid context object. A valid context object can be obtained by calling the function CGLCreateContext.

    Value

    10004

    Description

    Invalid context object. A valid context object can be obtained by calling the function CGLCreateContext.

  • Value

    10005

    Description

    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.

  • Invalid display.

    Value

    10006

    Description

    Invalid display.

  • Value

    10007

    Description

    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.

  • Invalid numerical value.

    Value

    10008

    Description

    Invalid numerical value.

  • Value

    10009

    Description

    Invalid share context. Two contexts are a bad match if their pixel format objects use different renderers.

  • Invalid constant.

    Value

    10010

    Description

    Invalid constant.

  • Invalid offscreen drawable object.

    Value

    10011

    Description

    Invalid offscreen drawable object.

  • Invalid full-screen drawable object.

    Value

    10012

    Description

    Invalid full-screen drawable object.

  • Invalid window.

    Value

    10013

    Description

    Invalid window.

  • Invalid memory address. This error occurs when you pass an invalid pointer into a function that requires a memory address other than NULL.

    Value

    10014

    Description

    Invalid memory address. This error occurs when you pass an invalid pointer into a function that requires a memory address other than NULL.

  • Invalid code module.

    Value

    10015

    Description

    Invalid code module.

  • Invalid memory allocation. This error occurs when CGL is unable to allocate memory.

    Value

    10016

    Description

    Invalid memory allocation. This error occurs when CGL is unable to allocate memory.

  • Invalid connection to Core Graphics.

    Value

    10017

    Description

    Invalid connection to Core Graphics.