Mac Developer Library

Developer

OpenGL Framework Reference CGL Reference

Options
Deployment Target:

On This Page
Language:

CGL Reference

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Swift

import OpenGL

Objective-C

@import OpenGL;

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

    Swift

    func CGLCreateContext(_ pix: CGLPixelFormatObj, _ share: CGLContextObj, _ ctx: UnsafeMutablePointer<CGLContextObj>) -> CGLError

    Objective-C

    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.

    Import Statement

    Objective-C

    @import OpenGL;

    Swift

    import OpenGL

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import OpenGL;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.8.

  • Increments the retain count on a CGL rendering context.

    Declaration

    Swift

    func CGLRetainContext(_ ctx: CGLContextObj) -> CGLContextObj

    Objective-C

    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.

    Import Statement

    Objective-C

    @import OpenGL;

    Swift

    import OpenGL

    Availability

    Available in OS X v10.5 and later.

  • Decrements the retain count on a CGL rendering context.

    Declaration

    Swift

    func CGLReleaseContext(_ ctx: CGLContextObj)

    Objective-C

    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.

    Import Statement

    Objective-C

    @import OpenGL;

    Swift

    import OpenGL

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Swift

    func CGLGetContextRetainCount(_ ctx: CGLContextObj) -> GLuint

    Objective-C

    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.

    Import Statement

    Objective-C

    @import OpenGL;

    Swift

    import OpenGL

    Availability

    Available in OS X v10.5 and later.

  • Frees the resources associated with a rendering context.

    Declaration

    Swift

    func CGLDestroyContext(_ ctx: CGLContextObj) -> CGLError

    Objective-C

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

    Import Statement

    Objective-C

    @import OpenGL;

    Swift

    import OpenGL

    Availability

    Available in OS X v10.0 and later.

    See Also

    CGLCreateContext

  • Returns the current rendering context.

    Declaration

    Swift

    func CGLGetCurrentContext() -> CGLContextObj

    Objective-C

    CGLContextObj CGLGetCurrentContext ( void );

    Return Value

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

    Import Statement

    Objective-C

    @import OpenGL;

    Swift

    import OpenGL

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func CGLSetCurrentContext(_ ctx: CGLContextObj) -> CGLError

    Objective-C

    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.

    Import Statement

    Objective-C

    @import OpenGL;

    Swift

    import OpenGL

    Availability

    Available in OS X v10.0 and later.

  • Enables an option for a rendering context.

    Declaration

    Swift

    func CGLEnable(_ ctx: CGLContextObj, _ pname: CGLContextEnable) -> CGLError

    Objective-C

    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.

    Import Statement

    Objective-C

    @import OpenGL;

    Swift

    import OpenGL

    Availability

    Available in OS X v10.0 and later.

  • Disables an option for a rendering context.

    Declaration

    Swift

    func CGLDisable(_ ctx: CGLContextObj, _ pname: CGLContextEnable) -> CGLError

    Objective-C

    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.

    Import Statement

    Objective-C

    @import OpenGL;

    Swift

    import OpenGL

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func CGLIsEnabled(_ ctx: CGLContextObj, _ pname: CGLContextEnable, _ enable: UnsafeMutablePointer<GLint>) -> CGLError

    Objective-C

    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.

    Import Statement

    Objective-C

    @import OpenGL;

    Swift

    import OpenGL

    Availability

    Available in OS X v10.0 and later.

  • Sets the value of a rendering context parameter.

    Declaration

    Swift

    func CGLSetParameter(_ ctx: CGLContextObj, _ pname: CGLContextParameter, _ params: UnsafePointer<GLint>) -> CGLError

    Objective-C

    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.

    Import Statement

    Objective-C

    @import OpenGL;

    Swift

    import OpenGL

    Availability

    Available in OS X v10.0 and later.

    See Also

    CGLGetParameter

  • Retrieves the value of a rendering context parameter.

    Declaration

    Swift

    func CGLGetParameter(_ ctx: CGLContextObj, _ pname: CGLContextParameter, _ params: UnsafeMutablePointer<GLint>) -> CGLError

    Objective-C

    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.

    Import Statement

    Objective-C

    @import OpenGL;

    Swift

    import OpenGL

    Availability

    Available in OS X v10.0 and later.

    See Also

    CGLSetParameter

  • Locks a CGL rendering context.

    Declaration

    Swift

    func CGLLockContext(_ ctx: CGLContextObj) -> CGLError

    Objective-C

    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.

    Import Statement

    Objective-C

    @import OpenGL;

    Swift

    import OpenGL

    Availability

    Available in OS X v10.4 and later.

    See Also

    CGLUnlockContext

  • Unlocks a CGL rendering context.

    Declaration

    Swift

    func CGLUnlockContext(_ ctx: CGLContextObj) -> CGLError

    Objective-C

    CGLError CGLUnlockContext ( CGLContextObj ctx );

    Parameters

    ctx

    The CGL context to unlock.

    Return Value

    A result code. See CGL Result Codes.

    Import Statement

    Objective-C

    @import OpenGL;

    Swift

    import OpenGL

    Availability

    Available in OS X v10.4 and later.

    See Also

    CGLLockContext

  • Attaches a rendering context to an offscreen buffer.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import OpenGL;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.7.

    See Also

    CGLGetOffScreen

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import OpenGL;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.7.

    See Also

    CGLSetOffScreen

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

    Deprecation Statement

    Use CGLSetFullScreenOnDisplay instead.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import OpenGL;

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import OpenGL;

    Availability

    Available in OS X v10.5 and later.

    Deprecated in OS X v10.7.

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

    Declaration

    Swift

    func CGLClearDrawable(_ ctx: CGLContextObj) -> CGLError

    Objective-C

    CGLError CGLClearDrawable ( CGLContextObj ctx );

    Parameters

    ctx

    A rendering context.

    Return Value

    A result code. See CGL Result Codes.

    Import Statement

    Objective-C

    @import OpenGL;

    Swift

    import OpenGL

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func CGLFlushDrawable(_ ctx: CGLContextObj) -> CGLError

    Objective-C

    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.

    Import Statement

    Objective-C

    @import OpenGL;

    Swift

    import OpenGL

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import OpenGL;

    Availability

    Available in OS X v10.3 and later.

    Deprecated in OS X v10.7.

  • Retrieves information that describes the specified pixel buffer object.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import OpenGL;

    Availability

    Available in OS X v10.3 and later.

    Deprecated in OS X v10.7.

    See Also

    CGLCreatePBuffer

  • Increments the retain count on a pixel buffer object.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import OpenGL;

    Availability

    Available in OS X v10.5 and later.

    Deprecated in OS X v10.7.

  • Decrements the retain count on a pixel buffer object.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import OpenGL;

    Availability

    Available in OS X v10.5 and later.

    Deprecated in OS X v10.7.

  • Returns the retain count of a pixel buffer object.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import OpenGL;

    Availability

    Available in OS X v10.5 and later.

    Deprecated in OS X v10.7.

  • Releases the resources associated with a pixel buffer object.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import OpenGL;

    Availability

    Available in OS X v10.3 and later.

    Deprecated in OS X v10.7.

    See Also

    CGLCreatePBuffer

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import OpenGL;

    Availability

    Available in OS X v10.3 and later.

    Deprecated in OS X v10.7.

    See Also

    CGLSetPBuffer

  • Attaches a pixel buffer object to a rendering context.

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import OpenGL;

    Availability

    Available in OS X v10.3 and later.

    Deprecated in OS X v10.7.

    See Also

    CGLGetPBuffer

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

    Declaration

    Objective-C

    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.

    Import Statement

    Objective-C

    @import OpenGL;

    Availability

    Available in OS X v10.3 and later.

    Deprecated in OS X v10.7.

  • Returns a string that describes the specified result code.

    Declaration

    Swift

    func CGLErrorString(_ error: CGLError) -> UnsafePointer<Int8>

    Objective-C

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

    Import Statement

    Objective-C

    @import OpenGL;

    Swift

    import OpenGL

    Availability

    Available in OS X v10.0 and later.

  • Sets the value of a global option.

    Use CGLSetGlobalOption instead.

    Declaration

    Swift

    func CGLSetOption(_ pname: CGLGlobalOption, _ param: GLint) -> CGLError

    Objective-C

    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.

    Import Statement

    Objective-C

    @import OpenGL;

    Swift

    import OpenGL

    Availability

    Available in OS X v10.0 and later.

    See Also

    CGLGetOption

  • Obtains the value of a global option.

    Use CGLGetGlobalOption instead.

    Declaration

    Swift

    func CGLGetOption(_ pname: CGLGlobalOption, _ param: UnsafeMutablePointer<GLint>) -> CGLError

    Objective-C

    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.

    Import Statement

    Objective-C

    @import OpenGL;

    Swift

    import OpenGL

    Availability

    Available in OS X v10.0 and later.

    See Also

    CGLSetOption

  • Retrieves the value of a global option.

    Declaration

    Swift

    func CGLGetGlobalOption(_ pname: CGLGlobalOption, _ params: UnsafeMutablePointer<GLint>) -> CGLError

    Objective-C

    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.

    Import Statement

    Objective-C

    @import OpenGL;

    Swift

    import OpenGL

    Availability

    Available in OS X v10.6 and later.

  • Sets the value of a global option.

    Declaration

    Swift

    func CGLSetGlobalOption(_ pname: CGLGlobalOption, _ params: UnsafePointer<GLint>) -> CGLError

    Objective-C

    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.

    Import Statement

    Objective-C

    @import OpenGL;

    Swift

    import OpenGL

    Availability

    Available in OS X v10.6 and later.

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

    Declaration

    Swift

    func CGLGetVersion(_ majorvers: UnsafeMutablePointer<GLint>, _ minorvers: UnsafeMutablePointer<GLint>)

    Objective-C

    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.

    Import Statement

    Objective-C

    @import OpenGL;

    Swift

    import OpenGL

    Availability

    Available in OS X v10.0 and later.

  • Obtains the value associated with a renderer property.

    Declaration

    Swift

    func CGLDescribeRenderer(_ rend: CGLRendererInfoObj, _ rend_num: GLint, _ prop: CGLRendererProperty, _ value: UnsafeMutablePointer<GLint>) -> CGLError

    Objective-C

    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.

    Import Statement

    Objective-C

    @import OpenGL;

    Swift

    import OpenGL

    Availability

    Available in OS X v10.0 and later.

  • Frees resources associated with a renderer information object.

    Declaration

    Swift

    func CGLDestroyRendererInfo(_ rend: CGLRendererInfoObj) -> CGLError

    Objective-C

    CGLError CGLDestroyRendererInfo ( CGLRendererInfoObj rend );

    Parameters

    rend

    The renderer information object to destroy.

    Return Value

    A result code. See CGL Result Codes.

    Import Statement

    Objective-C

    @import OpenGL;

    Swift

    import OpenGL

    Availability

    Available in OS X v10.0 and later.

  • 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

    Swift

    func CGLQueryRendererInfo(_ display_mask: GLuint, _ rend: UnsafeMutablePointer<CGLRendererInfoObj>, _ nrend: UnsafeMutablePointer<GLint>) -> CGLError

    Objective-C

    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.

    Import Statement

    Objective-C

    @import OpenGL;

    Swift

    import OpenGL

    Availability

    Available in OS X v10.0 and later.

  • Forces subsequent OpenGL commands to the specified virtual screen.

    Declaration

    Swift

    func CGLSetVirtualScreen(_ ctx: CGLContextObj, _ screen: GLint) -> CGLError

    Objective-C

    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.

    Import Statement

    Objective-C

    @import OpenGL;

    Swift

    import OpenGL

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Swift

    func CGLGetVirtualScreen(_ ctx: CGLContextObj, _ screen: UnsafeMutablePointer<GLint>) -> CGLError

    Objective-C

    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.

    Import Statement

    Objective-C

    @import OpenGL;

    Swift

    import OpenGL

    Availability

    Available in OS X v10.0 and later.

Data Types

  • Represents a pointer to an opaque CGL context object.

    Declaration

    Swift

    typealias CGLContextObj = UnsafeMutablePointer<_CGLContextObject>

    Objective-C

    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

    Objective-C

    @import OpenGL;

    Swift

    import OpenGL

    Availability

    Available in OS X v10.0 and later.

  • Represents a pointer to an opaque pixel format object.

    Declaration

    Swift

    typealias CGLPixelFormatObj = COpaquePointer

    Objective-C

    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

    Objective-C

    @import OpenGL;

    Swift

    import OpenGL

    Availability

    Available in OS X v10.0 and later.

  • Represents a pointer to an opaque renderer information object.

    Declaration

    Swift

    typealias CGLRendererInfoObj = COpaquePointer

    Objective-C

    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

    Objective-C

    @import OpenGL;

    Swift

    import OpenGL

    Availability

    Available in OS X v10.0 and later.

  • Represents a pointer to an opaque pixel buffer object.

    Declaration

    Objective-C

    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

    Objective-C

    @import OpenGL;

    Availability

    Available in OS X v10.3 and later.

    Deprecated in OS X v10.7.

Constants

  • Define constants used to set buffer modes.

    Declaration

    Objective-C

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

    Constants

    • kCGLMonoscopicBit

      kCGLMonoscopicBit

      The left buffer.

    • kCGLStereoscopicBit

      kCGLStereoscopicBit

      The left and right buffer.

    • kCGLSingleBufferBit

      kCGLSingleBufferBit

      The front buffer.

    • kCGLDoubleBufferBit

      kCGLDoubleBufferBit

      The front and back buffer.

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

    Declaration

    Swift

    typealias CGLPixelFormatAttribute = _CGLPixelFormatAttribute

    Objective-C

    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

      kCGLPFAAllRenderers

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

      Available in OS X v10.0 and later.

    • kCGLPFADoubleBuffer

      kCGLPFADoubleBuffer

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

      Available in OS X v10.0 and later.

    • kCGLPFAStereo

      kCGLPFAStereo

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

      Available in OS X v10.0 and later.

    • kCGLPFAAuxBuffers

      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.

      Available in OS X v10.0 and later.

    • kCGLPFAColorSize

      kCGLPFAColorSize

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

      Available in OS X v10.0 and later.

    • kCGLPFAAlphaSize

      kCGLPFAAlphaSize

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

      Available in OS X v10.0 and later.

    • kCGLPFADepthSize

      kCGLPFADepthSize

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

      Available in OS X v10.0 and later.

    • kCGLPFAStencilSize

      kCGLPFAStencilSize

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

      Available in OS X v10.0 and later.

    • kCGLPFAAccumSize

      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.

      Available in OS X v10.0 and later.

    • kCGLPFAMinimumPolicy

      kCGLPFAMinimumPolicy

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

      Available in OS X v10.0 and later.

    • kCGLPFAMaximumPolicy

      kCGLPFAMaximumPolicy

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

      Available in OS X v10.0 and later.

    • kCGLPFAOffScreen

      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.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.7.

    • kCGLPFAFullScreen

      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.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.6.

    • kCGLPFAAuxDepthStencil

      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.

      Available in OS X v10.2 and later.

    • kCGLPFAColorFloat

      kCGLPFAColorFloat

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

      Available in OS X v10.2 and later.

    • kCGLPFAMultisample

      kCGLPFAMultisample

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

      Available in OS X v10.3 and later.

    • kCGLPFASupersample

      kCGLPFASupersample

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

      Available in OS X v10.3 and later.

    • kCGLPFASampleAlpha

      kCGLPFASampleAlpha

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

      Available in OS X v10.3 and later.

    • kCGLPFASampleBuffers

      kCGLPFASampleBuffers

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

      Available in OS X v10.2 and later.

    • kCGLPFASamples

      kCGLPFASamples

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

      Available in OS X v10.2 and later.

    • kCGLPFARendererID

      kCGLPFARendererID

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

      Available in OS X v10.0 and later.

    • kCGLPFASingleRenderer

      kCGLPFASingleRenderer

      This constant is a Boolean attribute. If it is present in the attributes array, a single rendering engine is chosen. On systems with multiple displays, this disables ability of OpenGL to drive different displays through different graphics accelerator cards with a single context. This attribute is not generally useful. Do not supply a value with this constant because its presence in the array implies true.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.9.

    • kCGLPFANoRecovery

      kCGLPFANoRecovery

      This constant is a Boolean attribute. If it is present in the attributes array, the OpenGL failure recovery mechanisms are disabled. Normally, if an accelerated renderer fails due to lack of resources, OpenGL automatically switches to another renderer. This attribute disables these features so that rendering is always performed by the chosen renderer. This attribute is not generally useful. Do not supply a value with this constant because its presence in the array implies true.

      Available in OS X v10.0 and later.

    • kCGLPFAAccelerated

      kCGLPFAAccelerated

      This constant is a Boolean attribute. If it is present in the attributes array, only hardware accelerated renderers are considered. If false, accelerated renderers are still preferred. Do not supply a value with this constant because its presence in the array implies true.

      Available in OS X v10.0 and later.

    • kCGLPFAClosestPolicy

      kCGLPFAClosestPolicy

      This constant is a Boolean attribute. If it is present in the attributes array, the pixel format choosing policy is altered for the color buffer such that the buffer closest to the requested size is preferred, regardless of the actual color buffer depth of the supported graphics device. Do not supply a value with this constant because its presence in the array implies true.

      Available in OS X v10.0 and later.

    • kCGLPFARobust

      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.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.5.

    • kCGLPFABackingStore

      kCGLPFABackingStore

      This constant is a Boolean attribute. If it is present in the attributes array, OpenGL considers only renderers that have a back color buffer the full size of the drawable object and that guarantee the back buffer contents to be valid after a call to CGLFlushDrawable. Do not supply a value with this constant because its presence in the array implies true.

      Available in OS X v10.0 and later.

    • kCGLPFAMPSafe

      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.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.5.

    • kCGLPFAWindow

      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.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.9.

    • kCGLPFAMultiScreen

      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.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.5.

    • kCGLPFACompliant

      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.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.9.

    • kCGLPFADisplayMask

      kCGLPFADisplayMask

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

      Available in OS X v10.0 and later.

    • kCGLPFAPBuffer

      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.

      Available in OS X v10.3 and later.

      Deprecated in OS X v10.7.

    • kCGLPFARemotePBuffer

      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.

      Available in OS X v10.3 and later.

      Deprecated in OS X v10.9.

    • kCGLPFAAllowOfflineRenderers

      kCGLPFAAllowOfflineRenderers

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

      Available in OS X v10.5 and later.

    • kCGLPFAAcceleratedCompute

      kCGLPFAAcceleratedCompute

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

      Available in OS X v10.6 and later.

    • kCGLPFAOpenGLProfile

      kCGLPFAOpenGLProfile

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

      Available in OS X v10.7 and later.

    • kCGLPFAVirtualScreenCount

      kCGLPFAVirtualScreenCount

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

      Available in OS X v10.0 and later.

    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.

    Import Statement

    Objective-C

    @import OpenGL;

    Swift

    import OpenGL

    Availability

    Available in OS X v10.0 and later.

  • Specify formats for the color and accumulation buffers.

    Declaration

    Objective-C

    #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

      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

      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

      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

      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

      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

      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

      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

      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

      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

      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

      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

      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

      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

      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

      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

      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

      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

      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

      kCGLRGBFloat64Bit

      A format that has 64 bits per pixel with an RGB half floating-point channel layout.

    • kCGLRGBAFloat64Bit

      kCGLRGBAFloat64Bit

      A format that has 64 bits per pixel with an ARGB half floating-point channel layout.

    • kCGLRGBFloat128Bit

      kCGLRGBFloat128Bit

      A format that has 128 bits per pixel with an RGB IEEE floating-point channel layout.

    • kCGLRGBAFloat128Bit

      kCGLRGBAFloat128Bit

      A format that has 128 bits per pixel with an ARGB IEEE floating-point channel layout.

    • kCGLRGBFloat256Bit

      kCGLRGBFloat256Bit

      A format that has 256 bits per pixel with an RGB IEEE double channel layout.

    • kCGLRGBAFloat256Bit

      kCGLRGBAFloat256Bit

      A format that has 256 bits per pixel with an ARGB IEEE double channel layout.

  • Specify options that affect a rendering context.

    Declaration

    Swift

    typealias CGLContextEnable = _CGLContextEnable

    Objective-C

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

    Constants

    • kCGLCESwapRectangle

      kCGLCESwapRectangle

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

      Available in OS X v10.0 and later.

    • kCGLCERasterization

      kCGLCERasterization

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

      Available in OS X v10.0 and later.

    • kCGLCEStateValidation

      kCGLCEStateValidation

      If enabled, OpenGL inspects the context state each time that CGLSetVirtualScreen is called to ensure that it is in an appropriate state for switching between renderers. Normally, the state is inspected only when it is actually necessary to switch renderers. In CGL, a renderer is switched only if you call CGLSetVirtualScreen with a virtual screen number different from the current one.

      Available in OS X v10.0 and later.

    • kCGLCESurfaceBackingSize

      kCGLCESurfaceBackingSize

      If enabled, overrides the surface backing size.

      Available in OS X v10.3 and later.

    • kCGLCEDisplayListOptimization

      kCGLCEDisplayListOptimization

      If disabled, turns off optimization for the display list.

      Available in OS X v10.3 and later.

    • kCGLCEMPEngine

      kCGLCEMPEngine

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

      Available in OS X v10.4 and later.

    Discussion

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

    Import Statement

    Objective-C

    @import OpenGL;

    Swift

    import OpenGL

    Availability

    Available in OS X v10.0 and later.

  • Specify parameters that apply to a specific rendering context.

    Declaration

    Swift

    typealias CGLContextParameter = _CGLContextParameter

    Objective-C

    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

      kCGLCPSwapRectangle

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

      Available in OS X v10.0 and later.

    • kCGLCPSwapInterval

      kCGLCPSwapInterval

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

      Available in OS X v10.0 and later.

    • kCGLCPDispatchTableSize

      kCGLCPDispatchTableSize

      Set or get the dispatch table size.

      Available in OS X v10.3 and later.

    • kCGLCPClientStorage

      kCGLCPClientStorage

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

      Available in OS X v10.0 and later.

    • kCGLCPSurfaceTexture

      kCGLCPSurfaceTexture

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

      Available in OS X v10.3 and later.

      Deprecated in OS X v10.9.

    • kCGLCPSurfaceOrder

      kCGLCPSurfaceOrder

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

      Available in OS X v10.2 and later.

    • kCGLCPSurfaceOpacity

      kCGLCPSurfaceOpacity

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

      Available in OS X v10.2 and later.

    • kCGLCPSurfaceBackingSize

      kCGLCPSurfaceBackingSize

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

      Available in OS X v10.3 and later.

    • kCGLCPSurfaceSurfaceVolatile

      kCGLCPSurfaceSurfaceVolatile

      Set or get the volatile state of a surface.

      Available in OS X v10.3 and later.

    • kCGLCPReclaimResources

      kCGLCPReclaimResources

      Enable or disable reclaiming resources.

      Available in OS X v10.4 and later.

    • kCGLCPCurrentRendererID

      kCGLCPCurrentRendererID

      The current renderer ID. You can get this setting.

      Available in OS X v10.4 and later.

    • kCGLCPGPUVertexProcessing

      kCGLCPGPUVertexProcessing

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

      Available in OS X v10.4 and later.

    • kCGLCPGPUFragmentProcessing

      kCGLCPGPUFragmentProcessing

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

      Available in OS X v10.4 and later.

    • kCGLCPHasDrawable

      kCGLCPHasDrawable

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

      Available in OS X v10.5 and later.

    • kCGLCPMPSwapsInFlight

      kCGLCPMPSwapsInFlight

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

      Available in OS X v10.5 and later.

    Discussion

    These constants are used by the functions CGLSetParameter and CGLGetParameter.

    Import Statement

    Objective-C

    @import OpenGL;

    Swift

    import OpenGL

    Availability

    Available in OS X v10.0 and later.

  • Specify options that apply globally.

    Declaration

    Swift

    typealias CGLGlobalOption = _CGLGlobalOption

    Objective-C

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

    Constants

    • kCGLGOFormatCacheSize

      kCGLGOFormatCacheSize

      The pixel format cache size, a positive integer. After an application calls CGLChoosePixelFormat for the last time, it may set the cache size to 1 to minimize the memory used by CGL. If an application intends to use n different attribute lists to choose n different pixel formats repeatedly, then the application should set the cache size to n to maximize performance. The cache size is initially set to 5.

      Available in OS X v10.0 and later.

    • kCGLGOClearFormatCache

      kCGLGOClearFormatCache

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

      Available in OS X v10.0 and later.

    • kCGLGORetainRenderers

      kCGLGORetainRenderers

      If true, CGL does not unload any plug-in renderers even if they are no longer in use. This constant is useful to improve the performance of applications that repeatedly destroy and recreate their only (or last) rendering context. Normally, when the last context created by a particular plug-in renderer is destroyed, that renderer is unloaded from memory. If false, CGL returns to its normal mode of operation and all renderers that are not in use are unloaded.

      Available in OS X v10.0 and later.

    • kCGLGOResetLibrary

      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.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.4.

    • kCGLGOUseErrorHandler

      kCGLGOUseErrorHandler

      If true, CGL errors are propagated to Core Graphics.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.7.

    • kCGLGOUseBuildCache

      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.

      Available in OS X v10.5 and later.

    Discussion

    These constants are used by the functions CGLGetGlobalOption and CGLSetGlobalOption.

    Import Statement

    Objective-C

    @import OpenGL;

    Swift

    import OpenGL

    Availability

    Available in OS X v10.0 and later.

  • Define constants that specify hardware and software renderers.

    Declaration

    Swift

    var kCGLRendererGenericFloatID: Int { get } var kCGLRendererAppleSWID: Int { get } var kCGLRendererATIRadeonX2000ID: Int { get } var kCGLRendererATIRadeonX3000ID: Int { get } var kCGLRendererGeForce8xxxID: Int { get } var kCGLRendererIntelHDID: Int { get }

    Objective-C

    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

      kCGLRendererGenericID

      The software renderer.

      Deprecated in OS X v10.5 or later, and on all Intel-based Macintosh computers.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.5.

    • kCGLRendererGenericFloatID

      kCGLRendererGenericFloatID

      The floating-point software renderer.

      Available in OS X v10.3 and later.

    • kCGLRendererAppleSWID

      kCGLRendererAppleSWID

      The Apple software renderer ID.

      Available in OS X v10.9 and later.

    • kCGLRendererATIRage128ID

      kCGLRendererATIRage128ID

      The ATI Rage128 renderer.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.5.

    • kCGLRendererATIRadeonID

      kCGLRendererATIRadeonID

      The ATI Radeon renderer.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.6.

    • kCGLRendererATIRageProID

      kCGLRendererATIRageProID

      The ATI RagePro renderer.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.6.

    • kCGLRendererATIRadeon8500ID

      kCGLRendererATIRadeon8500ID

      The ATI Radeon 8500 renderer.

      Available in OS X v10.2 and later.

      Deprecated in OS X v10.6.

    • kCGLRendererATIRadeon9700ID

      kCGLRendererATIRadeon9700ID

      Specifies the ATI Radeon 9700 renderer.

      Available in OS X v10.2 and later.

      Deprecated in OS X v10.6.

    • kCGLRendererATIRadeonX1000ID

      kCGLRendererATIRadeonX1000ID

      The ATI Radeon X1000 renderer.

      Available in OS X v10.4 and later.

      Deprecated in OS X v10.8.

    • kCGLRendererATIRadeonX2000ID

      kCGLRendererATIRadeonX2000ID

      The ATI Radeon X2000 renderer.

      Available in OS X v10.4 and later.

    • kCGLRendererATIRadeonX3000ID

      kCGLRendererATIRadeonX3000ID

      The ATI Radeon X3000 renderer.

      Available in OS X v10.6 and later.

    • kCGLRendererGeForce2MXID

      kCGLRendererGeForce2MXID

      The NVIDIA GeForce2MX or GeForce4MX renderer.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.6.

    • kCGLRendererGeForce3ID

      kCGLRendererGeForce3ID

      The NVIDIA GeForce3 or GeForce4 renderer.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.6.

    • kCGLRendererGeForceFXID

      kCGLRendererGeForceFXID

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

      Available in OS X v10.2 and later.

      Deprecated in OS X v10.8.

    • kCGLRendererGeForce8xxxID

      kCGLRendererGeForce8xxxID

      The NVIDIA GeForce 8xxx and 9xxx renderers.

      Available in OS X v10.4 and later.

    • kCGLRendererVTBladeXP2ID

      kCGLRendererVTBladeXP2ID

      The VTBook renderer.

      Available in OS X v10.3 and later.

      Deprecated in OS X v10.6.

    • kCGLRendererIntel900ID

      kCGLRendererIntel900ID

      The Intel GMA 900 renderer.

      Available in OS X v10.4 and later.

      Deprecated in OS X v10.8.

    • kCGLRendererIntelX3100ID

      kCGLRendererIntelX3100ID

      The Intel GMA X3100 renderer.

      Available in OS X v10.5 and later.

      Deprecated in OS X v10.8.

    • kCGLRendererIntelHDID

      kCGLRendererIntelHDID

      The Intel HD Graphics renderer.

      Available in OS X v10.6 and later.

    • kCGLRendererMesa3DFXID

      kCGLRendererMesa3DFXID

      The Mesa 3DFX renderer.

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.6.

    • kCGLRendererIDMatchingMask

      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

    Swift

    typealias CGLOpenGLProfile = _CGLOpenGLProfile

    Objective-C

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

    Constants

    • kCGLOGLPVersion_Legacy

      kCGLOGLPVersion_Legacy

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

      Available in OS X v10.7 and later.

    • kCGLOGLPVersion_3_2_Core

      kCGLOGLPVersion_3_2_Core

      The requested profile must implement the OpenGL 3.2 core functionality.

      Available in OS X v10.7 and later.

    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.

    Import Statement

    Objective-C

    @import OpenGL;

    Swift

    import OpenGL

    Availability

    Available in OS X v10.7 and later.

  • Specify renderer properties.

    Declaration

    Swift

    typealias CGLRendererProperty = _CGLRendererProperty

    Objective-C

    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

      kCGLRPOffScreen

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

      Available in OS X v10.0 and later.

    • kCGLRPFullScreen

      kCGLRPFullScreen

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

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.6.

    • kCGLRPRendererID

      kCGLRPRendererID

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

      Available in OS X v10.0 and later.

    • kCGLRPAccelerated

      kCGLRPAccelerated

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

      Available in OS X v10.0 and later.

    • kCGLRPRobust

      kCGLRPRobust

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

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.5.

    • kCGLRPBackingStore

      kCGLRPBackingStore

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

      Available in OS X v10.0 and later.

    • kCGLRPMPSafe

      kCGLRPMPSafe

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

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.5.

    • kCGLRPWindow

      kCGLRPWindow

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

      Available in OS X v10.0 and later.

    • kCGLRPMultiScreen

      kCGLRPMultiScreen

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

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.5.

    • kCGLRPCompliant

      kCGLRPCompliant

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

      Available in OS X v10.0 and later.

    • kCGLRPDisplayMask

      kCGLRPDisplayMask

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

      Available in OS X v10.0 and later.

    • kCGLRPBufferModes

      kCGLRPBufferModes

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

      Available in OS X v10.0 and later.

    • kCGLRPColorModes

      kCGLRPColorModes

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

      Available in OS X v10.0 and later.

    • kCGLRPAccumModes

      kCGLRPAccumModes

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

      Available in OS X v10.0 and later.

    • kCGLRPDepthModes

      kCGLRPDepthModes

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

      Available in OS X v10.0 and later.

    • kCGLRPStencilModes

      kCGLRPStencilModes

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

      Available in OS X v10.0 and later.

    • kCGLRPMaxAuxBuffers

      kCGLRPMaxAuxBuffers

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

      Available in OS X v10.0 and later.

    • kCGLRPMaxSampleBuffers

      kCGLRPMaxSampleBuffers

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

      Available in OS X v10.2 and later.

    • kCGLRPMaxSamples

      kCGLRPMaxSamples

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

      Available in OS X v10.2 and later.

    • kCGLRPSampleModes

      kCGLRPSampleModes

      A bit field of supported sample modes.

      Available in OS X v10.3 and later.

    • kCGLRPSampleAlpha

      kCGLRPSampleAlpha

      If true, there is support for alpha sampling.

      Available in OS X v10.3 and later.

    • kCGLRPVideoMemory

      kCGLRPVideoMemory

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

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.7.

    • kCGLRPTextureMemory

      kCGLRPTextureMemory

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

      Available in OS X v10.0 and later.

      Deprecated in OS X v10.7.

    • kCGLRPGPUVertProcCapable

      kCGLRPGPUVertProcCapable

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

      Available in OS X v10.4 and later.

    • kCGLRPGPUFragProcCapable

      kCGLRPGPUFragProcCapable

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

      Available in OS X v10.4 and later.

    • kCGLRPRendererCount

      kCGLRPRendererCount

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

      Available in OS X v10.0 and later.

    • kCGLRPOnline

      kCGLRPOnline

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

      Available in OS X v10.5 and later.

    • kCGLRPAcceleratedCompute

      kCGLRPAcceleratedCompute

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

      Available in OS X v10.6 and later.

    • kCGLRPVideoMemoryMegabytes

      kCGLRPVideoMemoryMegabytes

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

      Available in OS X v10.7 and later.

    • kCGLRPTextureMemoryMegabytes

      kCGLRPTextureMemoryMegabytes

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

      Available in OS X v10.7 and later.

    Discussion

    These constants are used by the function CGLDescribeRenderer.

    Import Statement

    Objective-C

    @import OpenGL;

    Swift

    import OpenGL

    Availability

    Available in OS X v10.0 and later.

  • Define modes used for full scene anti-aliasing.

    Declaration

    Objective-C

    #define kCGLSupersampleBit x00000001 #define kCGLMultisampleBit x00000002

    Constants

    • kCGLSupersampleBit

      kCGLSupersampleBit

      Supersampling mode.

    • kCGLMultisampleBit

      kCGLMultisampleBit

      Multisampling mode.

  • Define resolutions for the depth and stencil buffers.

    Declaration

    Objective-C

    #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

      kCGL0Bit

      A 0-bit resolution.

    • kCGL1Bit

      kCGL1Bit

      A 1-bit resolution.

    • kCGL2Bit

      kCGL2Bit

      A 2-bit resolution.

    • kCGL3Bit

      kCGL3Bit

      A 3-bit resolution.

    • kCGL4Bit

      kCGL4Bit

      A 4-bit resolution.

    • kCGL5Bit

      kCGL5Bit

      A 5-bit resolution.

    • kCGL6Bit

      kCGL6Bit

      A 6-bit resolution.

    • kCGL8Bit

      kCGL8Bit

      A 8-bit resolution.

    • kCGL10Bit

      kCGL10Bit

      A 10-bit resolution.

    • kCGL12Bit

      kCGL12Bit

      A 12-bit resolution.

    • kCGL16Bit

      kCGL16Bit

      A 16-bit resolution.

    • kCGL24Bit

      kCGL24Bit

      A 24-bit resolution.

    • kCGL32Bit

      kCGL32Bit

      A 32-bit resolution.

    • kCGL48Bit

      kCGL48Bit

      A 48-bit resolution.

    • kCGL64Bit

      kCGL64Bit

      A 64-bit resolution.

    • kCGL96Bit

      kCGL96Bit

      A 96-bit resolution.

    • kCGL128Bit

      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.

    Available in OS X v10.3 and later.

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

    Available in OS X v10.0 and later.

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

    Available in OS X v10.0 and later.

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

    Available in OS X v10.0 and later.

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

    Available in OS X v10.0 and later.

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

    Available in OS X v10.0 and later.

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

    Available in OS X v10.0 and later.

  • Invalid display.

    Value

    10006

    Description

    Invalid display.

    Available in OS X v10.0 and later.

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

    Available in OS X v10.0 and later.

  • Invalid numerical value.

    Value

    10008

    Description

    Invalid numerical value.

    Available in OS X v10.0 and later.

  • Value

    10009

    Description

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

    Available in OS X v10.0 and later.

  • Invalid constant.

    Value

    10010

    Description

    Invalid constant.

    Available in OS X v10.0 and later.

  • Invalid offscreen drawable object.

    Value

    10011

    Description

    Invalid offscreen drawable object.

    Available in OS X v10.0 and later.

  • Invalid full-screen drawable object.

    Value

    10012

    Description

    Invalid full-screen drawable object.

    Available in OS X v10.0 and later.

  • Invalid window.

    Value

    10013

    Description

    Invalid window.

    Available in OS X v10.0 and later.

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

    Available in OS X v10.0 and later.

  • Invalid code module.

    Value

    10015

    Description

    Invalid code module.

    Available in OS X v10.0 and later.

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

    Available in OS X v10.0 and later.

  • Invalid connection to Core Graphics.

    Value

    10017

    Description

    Invalid connection to Core Graphics.

    Available in OS X v10.0 and later.