CGLayer Reference

Overview

CGLayer objects are useful for offscreen drawing and can be used in much the same way that a bitmap context can be used. In fact, a CGLayer object is a much better representation than a bitmap context.

Using CGLayer objects can improve performance, particularly when you need to capture a piece of drawing that you stamp repeatedly (using the same scale factor and orientation). Quartz can cache CGLayer objects to the video card, making drawing a CGLayer to a destination much faster than rendering the equivalent image constructed from a bitmap context.

A CGLayer object is created relative to a graphics context. Although layer uses this graphics context as a reference for initialization, you are not restricted to drawing the layer to this graphics context. You can draw the layer to other graphics contexts, although any limitations of the original context are imposed. For example, if you create a CGLayer object using a bitmap context, the layer is rendered as a bitmap when drawn to any other graphics context.

You can use a CGLayer when you want to apply a shadow to a group of objects (such as a group of circles) rather than to individual objects.

Use these layers in your code whenever you can, especially when:

• You need to reuse a filled or stroked shape.

• You are building a scene and at least some of it can be reused. Put the reusable drawing in its own CGLayer.

Any CG object that you draw repeatedly—including CGPath, CGShading, and CGPDFPage—benefit from improved performance if you draw it to a CGLayer object.

Functions by Task

Creating Layer Objects

• CGLayerCreateWithContext

Drawing Layer Content

• CGContextDrawLayerInRect
• CGContextDrawLayerAtPoint

Retaining and Releasing Layers

• CGLayerRelease
• CGLayerRetain

Getting the CFType ID for a Layer

• CGLayerGetTypeID

Getting Layer Information

• CGLayerGetSize
• CGLayerGetContext

Functions

CGContextDrawLayerAtPoint

Draws the contents of a CGLayer object at the specified point.

void CGContextDrawLayerAtPoint (
   CGContextRef context,
   CGPoint point,
   CGLayerRef layer
);

CGContextDrawLayerInRect

Draws the contents of a CGLayer object into the specified rectangle.

void CGContextDrawLayerInRect (
   CGContextRef context,
   CGRect rect,
   CGLayerRef layer
);

CGLayerCreateWithContext

Creates a CGLayer object that is associated with a graphics context.

CGLayerRef CGLayerCreateWithContext (
   CGContextRef context,
   CGSize size,
   CFDictionaryRef auxiliaryInfo
);

CGLayerGetContext

Returns the graphics context associated with a CGLayer object.

CGContextRef CGLayerGetContext (
   CGLayerRef layer
);

CGLayerGetSize

Returns the width and height of a CGLayer object.

CGSize CGLayerGetSize (
   CGLayerRef layer
);

CGLayerGetTypeID

Returns the unique type identifier used for CGLayer objects.

CFTypeID CGLayerGetTypeID (
   void
);

CGLayerRelease

Decrements the retain count of a CGLayer object.

void CGLayerRelease (
   CGLayerRef layer
);

CGLayerRetain

Increments the retain count of a CGLayer object.

CGLayerRef CGLayerRetain (
   CGLayerRef layer
);

Data Types

CGLayerRef

An opaque type used for offscreen drawing.

typedef struct CGLayer *CGLayerRef;