---

CAOpenGLLayer Class Reference

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

•   asynchronous  property
• – isAsynchronous
• – canDrawInCGLContext:pixelFormat:forLayerTime:displayTime:
• – drawInCGLContext:pixelFormat:forLayerTime:displayTime:

Managing the Pixel Format

• – copyCGLPixelFormatForDisplayMask:
• – releaseCGLPixelFormat:

Managing the Rendering Context

• – copyCGLContextForPixelFormat:
• – releaseCGLContext:

Properties

For more about Objective-C properties, see “Properties” in The Objective-C 2.0 Programming Language.

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 Mac OS X v10.5 and later.

See Also

• – isAsynchronous

Related Sample Code

• CALayerEssentials

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 Mac 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 Mac 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 Mac 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 Mac OS X v10.5 and later.

Declared In

CAOpenGLLayer.h

isAsynchronous

A synthesized accessor for the asynchronous property.

- (BOOL)isAsynchronous

See Also

•   @property asynchronous

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 Mac 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 Mac OS X v10.5 and later.

Declared In

CAOpenGLLayer.h

---