Mac Developer Library

Developer

AppKit Framework Reference NSOpenGLContext Class Reference

Options
Deployment Target:

On This Page
Language:

NSOpenGLContext

All OpenGL calls are rendered into an OpenGL graphics context, which in Cocoa is represented by the NSOpenGLContext class. The context is created using an NSOpenGLPixelFormatobject that specifies the context’s buffer types and other attributes. A context can be full-screen, offscreen, or associated with an NSView object. A context draws into its drawable object, which is the frame buffer that is the target of OpenGL drawing operations. More...

Inheritance


Conforms To


Import Statement


import AppKit @import AppKit;

Availability


Available in OS X v10.0 and later.
  • Returns an NSOpenGLContext object initialized with the specified pixel format information.

    Declaration

    Swift

    init?(format format: NSOpenGLPixelFormat!, shareContext share: NSOpenGLContext?)

    Objective-C

    - (instancetype)initWithFormat:(NSOpenGLPixelFormat *)format shareContext:(NSOpenGLContext *)share

    Parameters

    format

    The pixel format to request for the OpenGL graphics context.

    share

    Another OpenGL graphics context whose texture namespace and display lists you want to share with the receiver. If you do not want to share those features with another graphics context, you may pass nil for this parameter.

    Return Value

    An NSOpenGLContext object initialized with the specified parameters, or nil if the object could not be created.

    Discussion

    If the parameters contain invalid information, this method returns nil. This may happen if one of the following situations occurs:

    • The format parameter is nil or contains an invalid pixel format.

    • The share parameter is not nil and contains an invalid context.

    • The share parameter contains a context with a pixel format that is incompatible with the one in format.

    Pixel formats are incompatible if they use different renderers; this can happen if, for example, one format required an accumulation buffer that could only be provided by the software renderer, and the other format did not.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Initializes and returns a NSOpenGLContext object using an existing CGL context.

    Declaration

    Swift

    init!(CGLContextObj context: UnsafeMutablePointer<_CGLContextObject>)

    Objective-C

    - (NSOpenGLContext *)initWithCGLContextObj:(struct _CGLContextObject *)context

    Parameters

    context

    The CGL context to wrap inside the NSOpenGLContext object.

    Return Value

    An initialized context.

    Discussion

    If your application already has a CGL context, you can wrap a NSOpenGLContext object around it using this method. This method retains the CGL context by calling CGLRetainContext.

    Only one NSOpenGLContext object can wrap a specific context.

    Your application should not call CGLDestroyContext to dispose of the CGL context. Instead, your application should call CGLReleaseContext to decrement its reference count.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.6 and later.

  • Sets the current context to nil.

    Declaration

    Swift

    class func clearCurrentContext()

    Objective-C

    + (void)clearCurrentContext

    Discussion

    Until you issue a subsequent call to the makeCurrentContext method, OpenGL calls do nothing.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the current OpenGL graphics context.

    Declaration

    Swift

    class func currentContext() -> NSOpenGLContext?

    Objective-C

    + (NSOpenGLContext *)currentContext

    Return Value

    The current OpenGL graphics context, or nil if no such object has been set.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets the receiver as the current OpenGL context object.

    Declaration

    Swift

    func makeCurrentContext()

    Objective-C

    - (void)makeCurrentContext

    Discussion

    Subsequent OpenGL calls are rendered into the context defined by the receiver.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets the receiver’s viewport to the specified NSView object.

    Declaration

    Swift

    unowned(unsafe) var view: NSView!

    Objective-C

    @property(assign) NSView *view

    Parameters

    view

    The view to use for drawing. The full size of the view is used for the viewport.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Returns the receiver’s view.

    Declaration

    Swift

    unowned(unsafe) var view: NSView!

    Objective-C

    @property(assign) NSView *view

    Return Value

    The view, or nil if the receiver has no drawable object, is in full-screen mode, or is in offscreen mode.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Sets the receiver to full-screen mode.

    Deprecation Statement

    Full-screen mode contexts are deprecated. See Drawing to the Full Screen in OpenGL Programming Guide for Mac.

    Declaration

    Objective-C

    - (void)setFullScreen

    Discussion

    In full-screen mode, the receiver renders onto the entire screen. The receiver’s viewport is set to the full size of the screen. Call the clearDrawable method to exit full-screen mode.

    The NSOpenGLPFAFullScreen attribute must have been specified in the receiver’s NSOpenGLPixelFormat. Some OpenGL renderers, like the software renderer, do not support full-screen mode. The following code determines if a full-screen pixel format is possible on a given system:

    • NSOpenGLPixelFormatAttribute attrs[] =
    • {
    • NSOpenGLPFAFullScreen,
    • nil
    • };
    • NSOpenGLPixelFormat* pixFmt = [[NSOpenGLPixelFormat alloc] initWithAttributes:attrs];
    • /* Check if initWithAttributes succeeded. */
    • if(pixFmt == nil) {
    • /* initWithAttributes failed. There is no full-screen renderer. */
    • }

    Import Statement

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.7.

  • Instructs the receiver to render into an offscreen buffer with the specified attributes.

    Deprecation Statement

    Use a OpenGL framebuffer object instead.

    Declaration

    Objective-C

    - (void)setOffScreen:(void *)baseaddr width:(GLsizei)width height:(GLsizei)height rowbytes:(GLint)rowbytes

    Parameters

    baseaddr

    The base address of the buffer in memory. This buffer must contain at least rowbytes * height bytes.

    width

    The width of the memory buffer, measured in pixels.

    height

    The height of the memory buffer, measured in pixels.

    rowbytes

    The number of bytes in a single row of the buffer. This value must be greater than or equal to the value in width times the number of bytes per pixel.

    Discussion

    The receiver’s viewport is set to the full size of the offscreen area. Call the clearDrawable method to exit offscreen mode.

    The NSOpenGLPFAOffScreen attribute must have been specified in the receiver’s pixel format object.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.7.

  • Disassociates the receiver from its viewport.

    Declaration

    Swift

    func clearDrawable()

    Objective-C

    - (void)clearDrawable

    Discussion

    This method disassociates the receiver from any associated NSView object. If the receiver is in full-screen or offscreen mode, it exits that mode.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Updates the receiver's drawable object.

    Declaration

    Swift

    func update()

    Objective-C

    - (void)update

    Discussion

    Call this method whenever the receiver’s drawable object changes size or location. A multithreaded application must synchronize all threads that access the same drawable object and call update for each thread’s context serially.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Copies the back buffer to the front buffer of the receiver.

    Declaration

    Swift

    func flushBuffer()

    Objective-C

    - (void)flushBuffer

    Discussion

    If the receiver is not a double-buffered context, this call does nothing.

    If the NSOpenGLPixelFormat object used to create the context had a NOfalse backing store attribute (NSOpenGLPFABackingStore), the buffers may be exchanged rather than copied. This is often the case in full-screen mode.

    According to the swap interval context attribute (see NSOpenGLCPSwapInterval), the copy may take place during the vertical retrace of the monitor, rather than immediately after flushBuffer is called. An implicit glFlush is done by flushBuffer before it returns. For optimal performance, an application should not call glFlush immediately before calling flushBuffer. Subsequent OpenGL commands can be issued immediately after calling flushBuffer, but are not executed until the buffer copy is completed.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.

  • Copies selected groups of state variables to the receiver.

    Declaration

    Objective-C

    - (void)copyAttributesFromContext:(NSOpenGLContext *)context withMask:(GLbitfield)mask

    Parameters

    context

    The OpenGL graphics context containing the desired state variables.

    mask

    A bitfield containing a bitwise OR of the same symbolic names that are passed to the OpenGL call glPushAttrib. The single symbolic constant GL_ALL_ATTRIB_BITS can be used to copy the maximum possible portion of the rendering state.

    Discussion

    Not all values for OpenGL states can be copied. For example, the 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

    Availability

    Deprecated in OS X 10.8.

  • Sets the current virtual screen for the receiver.

    Declaration

    Swift

    var currentVirtualScreen: GLint

    Objective-C

    @property GLint currentVirtualScreen

    Parameters

    screen

    The virtual screen number, which is a value between 0 and the number of virtual screens minus one.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.2 and later.

  • Returns the current virtual screen for the receiver.

    Declaration

    Swift

    var currentVirtualScreen: GLint

    Objective-C

    @property GLint currentVirtualScreen

    Return Value

    The virtual screen number, which is a value between 0 and the number of virtual screens minus one.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.2 and later.

  • Creates a new texture from the contents of the specified view.

    Declaration

    Objective-C

    - (void)createTexture:(GLenum)target fromView:(NSView *)view internalFormat:(GLenum)format

    Parameters

    target

    The identifier for the new texture.

    view

    The view to use to generate the texture. This parameter must be either an NSOpenGLView object or some other kind of NSView object that’s associated with an NSOpenGLContext object.

    format

    The format for the texture, interpreted as a GLenum data type.

    Discussion

    The new texture is assigned the identifier in the target parameter and is associated with the receiver's context.

    Import Statement

    Availability

    Available in OS X v10.2 and later.

    Deprecated in OS X v10.8.

  • Returns the low-level, platform-specific Core OpenGL (CGL) context object represented by the receiver.

    Declaration

    Swift

    var CGLContextObj: UnsafeMutablePointer<_CGLContextObject> { get }

    Objective-C

    @property(readonly) struct _CGLContextObject *CGLContextObj

    Return Value

    A pointer to the CGLContextObj data type represented by the receiver.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.3 and later.

  • Attaches the specified pixel buffer to the receiver.

    Deprecation Statement

    Use framebuffer objects instead.

    Declaration

    Objective-C

    - (void)setPixelBuffer:(NSOpenGLPixelBuffer *)pixelBuffer cubeMapFace:(GLenum)face mipMapLevel:(GLint)level currentVirtualScreen:(GLint)screen

    Parameters

    pixelBuffer

    The pixel buffer to attach.

    face

    For pixel buffers with a texture target of GL_CUBE_MAP, this parameter should be zero or one of the following values:

    • GL_TEXTURE_CUBE_MAP_POSITIVE_X

    • GL_TEXTURE_CUBE_MAP_POSITIVE_Y

    • GL_TEXTURE_CUBE_MAP_POSITIVE_Z

    • GL_TEXTURE_CUBE_MAP_NEGATIVE_X

    • GL_TEXTURE_CUBE_MAP_NEGATIVE_Y

    • GL_TEXTURE_CUBE_MAP_NEGATIVE_Z

    level

    The desired mipmap level for rendering. This value must be less than or equal to the maximum texture mipmap level of pixelBuffer (accessible through an NSOpenGLPixelBuffer object’s textureMaxMipMapLevel method).

    screen

    The virtual screen of the receiver (if applicable) should be set to the same value as the current virtual screen you are using for rendering onscreen

    Discussion

    The NSOpenGLPixelBuffer object gives the receiver access to accelerated offscreen rendering in the pixel buffer, which is primarily used for textures.

    Import Statement

    Availability

    Available in OS X v10.3 and later.

    Deprecated in OS X v10.7.

  • pixelBuffer pixelBuffer (OS X v10.7)

    Returns the pixel-buffer object attached to the receiver.

    Deprecation Statement

    Use framebuffer objects instead.

    Declaration

    Objective-C

    - (NSOpenGLPixelBuffer *)pixelBuffer

    Return Value

    The pixel buffer object.

    Import Statement

    Availability

    Available in OS X v10.3 and later.

    Deprecated in OS X v10.7.

  • Returns the cube map face of the pixel buffer attached to the receiver.

    Deprecation Statement

    Use framebuffer objects instead.

    Declaration

    Objective-C

    - (GLenum)pixelBufferCubeMapFace

    Return Value

    For pixel buffers with a texture target of GL_CUBE_MAP, this value is zero or one of the following values:

    • GL_TEXTURE_CUBE_MAP_POSITIVE_X

    • GL_TEXTURE_CUBE_MAP_POSITIVE_Y

    • GL_TEXTURE_CUBE_MAP_POSITIVE_Z

    • GL_TEXTURE_CUBE_MAP_NEGATIVE_X

    • GL_TEXTURE_CUBE_MAP_NEGATIVE_Y

    • GL_TEXTURE_CUBE_MAP_NEGATIVE_Z

    Import Statement

    Availability

    Available in OS X v10.3 and later.

    Deprecated in OS X v10.7.

  • Returns the mipmap level of the pixel buffer attached to the receiver.

    Deprecation Statement

    Use framebuffer objects instead.

    Declaration

    Objective-C

    - (GLint)pixelBufferMipMapLevel

    Return Value

    The desired mipmap level for rendering. This value should be less than or equal to the maximum texture mipmap level of pixelBuffer (accessible through an NSOpenGLPixelBuffer object’s textureMaxMipMapLevel method).

    Import Statement

    Availability

    Available in OS X v10.3 and later.

    Deprecated in OS X v10.7.

  • Attaches the image data in the specified pixel buffer to the texture object currently bound by the receiver.

    Deprecation Statement

    Use framebuffer objects instead.

    Declaration

    Objective-C

    - (void)setTextureImageToPixelBuffer:(NSOpenGLPixelBuffer *)pixelBuffer colorBuffer:(GLenum)source

    Parameters

    pixelBuffer

    The pixel buffer to attach.

    source

    An OpenGL constant indicating which of the pixel buffer's color buffers to use. Potential values for this parameter include GL_FRONT, GL_BACK, and GL_AUX0.

    Discussion

    This method corresponds to the Core OpenGL method CGLTexImagePBuffer.

    Import Statement

    Availability

    Available in OS X v10.3 and later.

    Deprecated in OS X v10.7.

Data Types

  • The following attribute names are used by setValues:forParameter: and getValues:forParameter::

    Declaration

    Swift

    enum NSOpenGLContextParameter : Int { case GLCPSwapInterval case GLCPSurfaceOrder case GLCPSurfaceOpacity case GLCPSurfaceBackingSize case GLCPReclaimResources case GLCPCurrentRendererID case GLCPGPUVertexProcessing case GLCPGPUFragmentProcessing case GLCPHasDrawable case GLCPMPSwapsInFlight case GLCPSwapRectangle case GLCPSwapRectangleEnable case GLCPRasterizationEnable case GLCPStateValidation case GLCPSurfaceSurfaceVolatile }

    Objective-C

    typedef enum { NSOpenGLCPSwapInterval = 222, NSOpenGLCPSurfaceOrder = 235, NSOpenGLCPSurfaceOpacity = 236, NSOpenGLCPSurfaceBackingSize = 304, NSOpenGLCPReclaimResources = 308, NSOpenGLCPCurrentRendererID = 309, NSOpenGLCPGPUVertexProcessing = 310, NSOpenGLCPGPUFragmentProcessing = 311, NSOpenGLCPHasDrawable = 314, NSOpenGLCPMPSwapsInFlight = 315, /* The following parameters are obsolete and deprecated for new development. */ NSOpenGLCPSwapRectangle = 200, NSOpenGLCPSwapRectangleEnable = 201, NSOpenGLCPRasterizationEnable = 221, NSOpenGLCPStateValidation = 301, NSOpenGLCPSurfaceSurfaceVolatile = 306 } NSOpenGLContextParameter;

    Constants

    • GLCPSwapInterval

      NSOpenGLCPSwapInterval

      Sets or gets the swap interval.

      The swap interval is represented as one long. If the swap interval is set to 0 (the default), the flushBuffer method 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.

    • GLCPSurfaceOrder

      NSOpenGLCPSurfaceOrder

      Get or set the surface order.

      If the surface order is set to 1 (the default), the order is above the window (default). If the value is –1, the order is below the window.

      Available in OS X v10.2 and later.

    • GLCPSurfaceOpacity

      NSOpenGLCPSurfaceOpacity

      Set or get the surface opacity.

      If the opacity is set to 1 (the default), the surface is opaque. If the value is 0, the surface is non-opaque.

      Available in OS X v10.2 and later.

    • GLCPSurfaceBackingSize

      NSOpenGLCPSurfaceBackingSize

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

    • GLCPReclaimResources

      NSOpenGLCPReclaimResources

      Enable or disable reclaiming resources.

      Available in OS X v10.7 and later.

    • GLCPCurrentRendererID

      NSOpenGLCPCurrentRendererID

      The current renderer ID. You can get this setting.

      Available in OS X v10.7 and later.

    • GLCPGPUVertexProcessing

      NSOpenGLCPGPUVertexProcessing

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

      Available in OS X v10.7 and later.

    • GLCPGPUFragmentProcessing

      NSOpenGLCPGPUFragmentProcessing

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

      Available in OS X v10.7 and later.

    • GLCPHasDrawable

      NSOpenGLCPHasDrawable

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

      Available in OS X v10.7 and later.

    • GLCPMPSwapsInFlight

      NSOpenGLCPMPSwapsInFlight

      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 the flushBuffer method. 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.7 and later.

    • GLCPSwapRectangle

      NSOpenGLCPSwapRectangle

      Sets or gets the swap rectangle.

      Deprecated. Do not use this for new development.

      The swap rectangle is represented as an array of four longs: {x, y, width, height}.

      Available in OS X v10.0 and later.

    • GLCPSwapRectangleEnable

      NSOpenGLCPSwapRectangleEnable

      Enables or disables the swap rectangle in the context’s drawable object.

      Deprecated. Do not use this for new development.

      If enabled, the area that is affected by the flushBuffer method is restricted to a rectangle specified by the values of NSOpenGLCPSwapRectangle. 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.

      Available in OS X v10.0 and later.

    • GLCPRasterizationEnable

      NSOpenGLCPRasterizationEnable

      If disabled, all rasterization of 2D and 3D primitives is disabled.

      Deprecated. Do not use this for new development.

      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.

    • GLCPStateValidation

      NSOpenGLCPStateValidation

      If enabled, OpenGL inspects the context state each time the update method is called to ensure that it is in an appropriate state for switching between renderers.

      Deprecated. Do not use this for new development.

      Normally, the state is inspected only when it is actually necessary to switch renderers. This is useful when using a single monitor system to test that an application performs correctly on a multiple-monitor system.

      Available in OS X v10.0 and later.

    Import Statement

    import AppKit

    Availability

    Available in OS X v10.0 and later.