NSOpenGLContext Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in OS X v10.0 and later.
Companion guide
Declared in
NSOpenGL.h
Related sample code

Overview

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.

Every NSOpenGLContext object wraps a low-level, platform-specific Core OpenGL (CGL) context. Your application can retrieve the CGL context by calling the CGLContextObj method. For more information on the underling CGL context, see CGL Reference.

Tasks

Context Creation

Managing the Current Context

Drawable Object Management

Flushing the Drawing Buffer

Copying Attributes

Context Parameter Handling

Working with Virtual Screens

Creating Textures

Getting the CGL Context Object

Working with Pixel Buffers

Class Methods

clearCurrentContext

Sets the current context to nil.

+ (void)clearCurrentContext
Discussion

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

Availability
  • Available in OS X v10.0 and later.
Declared In
NSOpenGL.h

currentContext

Returns the current OpenGL graphics context.

+ (NSOpenGLContext *)currentContext
Return Value

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

Availability
  • Available in OS X v10.0 and later.
Declared In
NSOpenGL.h

Instance Methods

CGLContextObj

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

- (void *)CGLContextObj
Return Value

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

Availability
  • Available in OS X v10.3 and later.
Declared In
NSOpenGL.h

clearDrawable

Disassociates the receiver from its viewport.

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

Availability
  • Available in OS X v10.0 and later.
Declared In
NSOpenGL.h

createTexture:fromView:internalFormat:

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

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

Availability
  • Available in OS X v10.2 and later.
Declared In
NSOpenGL.h

currentVirtualScreen

Returns the current virtual screen for the receiver.

- (GLint)currentVirtualScreen
Return Value

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

Availability
  • Available in OS X v10.2 and later.
Declared In
NSOpenGL.h

flushBuffer

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

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

Availability
  • Available in OS X v10.0 and later.
Declared In
NSOpenGL.h

getValues:forParameter:

Returns the value of the requested parameter.

- (void)getValues:(GLint *)vals forParameter:(NSOpenGLContextParameter)param
Parameters
vals

On input, a pointer to a variable with enough space for one or more long integers. On output, the variable contains the value (or values) for the given parameter.

param

The parameter you want to get. For a list of parameters, see the table in NSOpenGLContextParameter.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSOpenGL.h

initWithCGLContextObj:

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

- (id)initWithCGLContextObj:(void *)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.

Availability
  • Available in OS X v10.6 and later.
Declared In
NSOpenGL.h

initWithFormat:shareContext:

Returns an NSOpenGLContext object initialized with the specified pixel format information.

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

Availability
  • Available in OS X v10.0 and later.
Declared In
NSOpenGL.h

makeCurrentContext

Sets the receiver as the current OpenGL context object.

- (void)makeCurrentContext
Discussion

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

Availability
  • Available in OS X v10.0 and later.
Declared In
NSOpenGL.h

pixelBuffer

Returns the pixel-buffer object attached to the receiver. (Deprecated. Use framebuffer objects instead.)

- (NSOpenGLPixelBuffer *)pixelBuffer
Return Value

The pixel buffer object.

Availability
  • Available in OS X v10.3 and later.
Declared In
NSOpenGL.h

pixelBufferCubeMapFace

Returns the cube map face of the pixel buffer attached to the receiver. (Deprecated. Use framebuffer objects instead.)

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

Availability
  • Available in OS X v10.3 and later.
Declared In
NSOpenGL.h

pixelBufferMipMapLevel

Returns the mipmap level of the pixel buffer attached to the receiver. (Deprecated. Use framebuffer objects instead.)

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

Availability
  • Available in OS X v10.3 and later.
Declared In
NSOpenGL.h

setCurrentVirtualScreen:

Sets the current virtual screen for the receiver.

- (void)setCurrentVirtualScreen:(GLint)screen
Parameters
screen

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

Availability
  • Available in OS X v10.2 and later.
Related Sample Code
Declared In
NSOpenGL.h

setFullScreen

Sets the receiver to full-screen mode. (Deprecated. Full-screen mode contexts are deprecated. See “Drawing to the Full Screen”.)

- (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.  */
}
Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSOpenGL.h

setOffScreen:width:height:rowbytes:

Instructs the receiver to render into an offscreen buffer with the specified attributes. (Deprecated. Use a OpenGL framebuffer object instead.)

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

Availability
  • Available in OS X v10.0 and later.
Declared In
NSOpenGL.h

setPixelBuffer:cubeMapFace:mipMapLevel:currentVirtualScreen:

Attaches the specified pixel buffer to the receiver. (Deprecated. Use framebuffer objects instead.)

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

Availability
  • Available in OS X v10.3 and later.
Declared In
NSOpenGL.h

setTextureImageToPixelBuffer:colorBuffer:

Attaches the image data in the specified pixel buffer to the texture object currently bound by the receiver. (Deprecated. Use framebuffer objects instead.)

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

Availability
  • Available in OS X v10.3 and later.
Related Sample Code
Declared In
NSOpenGL.h

setValues:forParameter:

Sets the value of the specified parameter.

- (void)setValues:(const GLint *)vals forParameter:(NSOpenGLContextParameter)param
Parameters
vals

The new value (or values) for the parameter.

param

The parameter you want to modify. For a list of parameters, see NSOpenGLContextParameter.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSOpenGL.h

setView:

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

- (void)setView:(NSView *)view
Parameters
view

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

Availability
  • Available in OS X v10.0 and later.
Declared In
NSOpenGL.h

update

Updates the receiver's drawable object.

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

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSOpenGL.h

view

Returns the receiver’s view.

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

Availability
  • Available in OS X v10.0 and later.
Declared In
NSOpenGL.h

Constants

NSOpenGLContextParameter

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

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

Declared in NSOpenGL.h.

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.

Declared in NSOpenGL.h.

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.

Declared in NSOpenGL.h.

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.

Declared in NSOpenGL.h.

NSOpenGLCPReclaimResources

Enable or disable reclaiming resources.

Available in OS X v10.7 and later.

Declared in NSOpenGL.h.

NSOpenGLCPCurrentRendererID

The current renderer ID. You can get this setting.

Available in OS X v10.7 and later.

Declared in NSOpenGL.h.

NSOpenGLCPGPUVertexProcessing

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

Available in OS X v10.7 and later.

Declared in NSOpenGL.h.

NSOpenGLCPGPUFragmentProcessing

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

Available in OS X v10.7 and later.

Declared in NSOpenGL.h.

NSOpenGLCPHasDrawable

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

Available in OS X v10.7 and later.

Declared in NSOpenGL.h.

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.

Declared in NSOpenGL.h.

NSOpenGLCPSwapRectangle

Sets or gets the swap rectangle. (Deprecated. 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.

Declared in NSOpenGL.h.

NSOpenGLCPSwapRectangleEnable

Enables or disables the swap rectangle in the context’s drawable object. (Deprecated. 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.

Declared in NSOpenGL.h.

NSOpenGLCPRasterizationEnable

If disabled, all rasterization of 2D and 3D primitives is disabled. (Deprecated. 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.

Declared in NSOpenGL.h.

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

Declared in NSOpenGL.h.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSOpenGL.h