CGLayer

An offscreen context for reusing content drawn with Core Graphics.

Overview

Layer 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 CGLayerRef object is a much better representation than a bitmap context.

Using CGLayerRef 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). Core Graphics can cache CGLayerRef objects to the video card, making drawing a CGLayerRef to a destination much faster than rendering the equivalent image constructed from a bitmap context.

A CGLayerRef 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 CGLayerRef object using a bitmap context, the layer is rendered as a bitmap when drawn to any other graphics context.

You can use a CGLayerRef 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 layer.

Any Core Graphics object that you draw repeatedly—including CGPathRef, CGShadingRef, and CGPDFPageRef objects—benefit from improved performance if you draw it to a CGLayerRef object.

Topics

Creating Layer Objects

CGLayerCreateWithContext

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

Drawing Layer Content

CGContextDrawLayerInRect

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

CGContextDrawLayerAtPoint

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

Retaining and Releasing Layers

CGLayerRelease

Decrements the retain count of a layer object.

CGLayerRetain

Increments the retain count of a layer object.

Getting the CFType ID for a Layer

CGLayerGetTypeID

Returns the unique type identifier used for CGLayerRef objects.

Getting Layer Information

CGLayerGetSize

Returns the width and height of a layer object.

CGLayerGetContext

Returns the graphics context associated with a layer object.

Data Types

CGLayerRef

An offscreen context for reusing content drawn with Core Graphics.

See Also

Opaque Types

CGBitmapContext

A type of CGContextRef that you can use for drawing bits to memory.

CGColor

A set of components that define a color, with a color space specifying how to interpret them.

CGColorConversionInfo

An object that describes how to convert between color spaces for use by other system services.

CGColorSpace

A profile that specifies how to interpret a color value for display.

CGContext

A Quartz 2D drawing destination.

CGDataConsumer

An abstraction for data-writing tasks that eliminates the need to manage a raw memory buffer.

CGDataProvider

An abstraction for data-reading tasks that eliminates the need to manage a raw memory buffer.

CGFont

A set of character glyphs and layout information for drawing text.

CGFunction

A general facility for defining and using callback functions.

CGGLContext

Deprecated. A type of CGContextRef for drawing OpenGL content.

CGGradient

A definition for a smooth transition between colors for drawing radial and axial gradient fills.

CGImage

A bitmap image or image mask.

CGPath

Immutable and mutable types for graphics paths: mathematical descriptions of shapes or lines to be drawn in a graphics context.

CGPattern

A 2D pattern to be used for drawing graphics paths.

CGPDFArray

An array structure within a PDF document.

CGPDFContentStream

A representation of one or more content data streams in a PDF page.

CGPDFContext

A type of CGContextRef for drawing PDF content.

CGPDFDictionary

A dictionary structure within a PDF document.

CGPDFDocument

A document that contains PDF (Portable Document Format) drawing information.

CGPDFObject

An object representing content within a PDF document.

CGPDFOperatorTable

A set of callback functions for operators used when scanning content in a PDF document.

CGPDFPage

A page in a PDF document.

CGPDFScanner

A parser object for handling content and operators in a PDF content stream.

CGPDFStream

A stream or sequence of data bytes in a PDF document.

CGPDFString

A text string in a PDF document.

CGPSConverter

An object that converts PostScript data to PDF data.

CGShading

A definition for a smooth transition between colors, controlled by a custom function you provide, for drawing radial and axial gradient fills.