CAOpenGLLayer Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/QuartzCore.framework
Availability
Available in OS X v10.5 and later.
Declared in
CAOpenGLLayer.h
Companion guides
Related sample code

Overview

CAOpenGLLayer provides a layer suitable for rendering OpenGL content.

To provide OpenGL content you subclass CAOpenGLLayer and override drawInCGLContext:pixelFormat:forLayerTime:displayTime:. You can specify that the OpenGL content is static by setting the asynchronous property to NO.

Tasks

Drawing the Content

Managing the Pixel Format

Managing the Rendering Context

Properties

asynchronous

Determines when the contents of the layer are updated.

@property BOOL asynchronous
Discussion

If NO, the contents of the layer are updated only in response to receiving a setNeedsDisplay message. When YES, the receiver’s canDrawInCGLContext:pixelFormat:forLayerTime:displayTime: is called periodically to determine if the OpenGL content should be updated.

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

Instance Methods

canDrawInCGLContext:pixelFormat:forLayerTime:displayTime:

Returns whether the receiver should draw OpenGL content for the specified time.

- (BOOL)canDrawInCGLContext:(CGLContextObj)glContext pixelFormat:(CGLPixelFormatObj)pixelFormat forLayerTime:(CFTimeInterval)timeInterval displayTime:(const CVTimeStamp *)timeStamp
Parameters
glContext

The CGLContextObj in to which the OpenGL content would be drawn.

pixelFormat

The pixel format used when the glContext was created.

timeInterval

The current layer time.

timeStamp

The display timestamp associated with timeInterval. Can be null.

Return Value

YES if the receiver should render OpenGL content, NO otherwise.

Discussion

This method is called before attempting to render the frame for the layer time specified by timeInterval. If the method returns NO, the frame is skipped. The default implementation always returns YES.

Availability
  • Available in OS X v10.5 and later.
Declared In
CAOpenGLLayer.h

copyCGLContextForPixelFormat:

Returns the rendering context the receiver requires for the specified pixel format.

- (CGLContextObj)copyCGLContextForPixelFormat:(CGLPixelFormatObj)pixelFormat
Parameters
pixelFormat

The pixel format for the rendering context.

Return Value

A new CGLContext with renderers for pixelFormat.

Discussion

This method is called when a rendering context is needed by the receiver. The default implementation allocates a new context with a null share context.

You should not call this method directly, it is intended to be overridden by subclasses.

Availability
  • Available in OS X v10.5 and later.
Declared In
CAOpenGLLayer.h

copyCGLPixelFormatForDisplayMask:

Returns the OpenGL pixel format suitable for rendering to the set of displays specified by the display mask.

- (CGLPixelFormatObj)copyCGLPixelFormatForDisplayMask:(uint32_t)mask
Parameters
mask

The display mask the OpenGL content will be rendered on.

Discussion

This method is called when a pixel format object is needed for the receiver. The default implementation returns a 32bpp fixed point pixelf format, with the NoRecovery and Accelerated flags set.

You should not call this method directly, it is intended to be overridden by subclasses.

Availability
  • Available in OS X v10.5 and later.
Declared In
CAOpenGLLayer.h

drawInCGLContext:pixelFormat:forLayerTime:displayTime:

Draws the OpenGL content for the specified time.

- (void)drawInCGLContext:(CGLContextObj)glContext pixelFormat:(CGLPixelFormatObj)pixelFormat forLayerTime:(CFTimeInterval)timeInterval displayTime:(const CVTimeStamp *)timeStamp
Parameters
glContext

The rendering context in to which the OpenGL content should be rendered.

pixelFormat

The pixel format used when the glContext was created.

timeInterval

The current layer time.

timeStamp

The display timestamp associated with timeInterval. Can be null.

Discussion

This method is called when a new frame needs to be generated for the layer time specified by timeInterval. The viewport of glContext is set correctly for the size of the layer. No other state is defined. If the method enables OpenGL features, it should disable them before returning.

The default implementation of the method flushes the context.

Availability
  • Available in OS X v10.5 and later.
Declared In
CAOpenGLLayer.h

isAsynchronous

A synthesized accessor for the asynchronous property.

- (BOOL)isAsynchronous

releaseCGLContext:

Releases the specified rendering context.

- (void)releaseCGLContext:(CGLContextObj)glContext
Parameters
glContext

The rendering context to release.

Discussion

This method is called when the OpenGL context that was previously returned by copyCGLContextForPixelFormat: is no longer needed.

You should not call this method directly, it is intended to be overridden by subclasses.

Availability
  • Available in OS X v10.5 and later.
Declared In
CAOpenGLLayer.h

releaseCGLPixelFormat:

Releases the specified OpenGL pixel format object.

- (void)releaseCGLPixelFormat:(CGLPixelFormatObj)pixelFormat
Parameters
pixelFormat

The pixel format object to release.

Discussion

This method is called when the OpenGL pixel format that was previously returned by copyCGLContextForPixelFormat:.

You should not call this method directly, it is intended to be overridden by subclasses.

Availability
  • Available in OS X v10.5 and later.
Declared In
CAOpenGLLayer.h