Mac Developer Library

Developer

ApplicationServices Framework Reference CGLayer Reference

Options
Deployment Target:

On This Page
Language:

CGLayer Reference

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Swift

import CoreGraphics

Objective-C

@import CoreGraphics;

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

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

    Declaration

    Swift

    func CGLayerCreateWithContext(_ context: CGContext!, _ size: CGSize, _ auxiliaryInfo: CFDictionary!) -> CGLayer!

    Objective-C

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

    Parameters

    context

    The graphics context you want to create the layer relative to. The layer uses this graphics context as a reference for initialization.

    size

    The size, in default user space units, of the layer relative to the graphics context.

    auxiliaryInfo

    Reserved for future use. Pass NULL.

    Return Value

    A CGLayer object. You are responsible for releasing this object using the function CGLayerRelease when you no longer need the layer.

    Discussion

    After you create a CGLayer object, you should reuse it whenever you can to facilitate the Quartz caching strategy. Quartz caches any objects that are reused, including CGLayer objects. Objects that are reused frequently remain in the cache. In contrast, objects that are used once in a while may be moved in and out of the cache according to their frequency of use. If you don’t reuse CGLayer objects, Quartz won’t cache them. This means that you lose an opportunity to improve the performance of your application.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X version 10.4 and later.

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

    Declaration

    Swift

    func CGContextDrawLayerInRect(_ context: CGContext!, _ rect: CGRect, _ layer: CGLayer!)

    Objective-C

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

    Parameters

    context

    The graphics context associated with the layer.

    rect

    The rectangle, in current user space coordinates, to draw to.

    layer

    The layer whose contents you want to draw.

    Discussion

    The contents are scaled, if necessary, to fit into the rectangle.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X version 10.4 and later.

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

    Declaration

    Swift

    func CGContextDrawLayerAtPoint(_ context: CGContext!, _ point: CGPoint, _ layer: CGLayer!)

    Objective-C

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

    Parameters

    context

    The graphics context associated with the layer.

    point

    The location, in current user space coordinates, to use as the origin for the drawing.

    layer

    The layer whose contents you want to draw.

    Discussion

    Calling the function CGContextDrawLayerAtPoint is equivalent to calling the function CGContextDrawLayerInRect with a rectangle that has its origin at point and its size equal to the size of the layer.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X version 10.4 and later.

  • Decrements the retain count of a CGLayer object.

    Declaration

    Objective-C

    void CGLayerRelease ( CGLayerRef layer );

    Parameters

    layer

    The layer to release.

    Discussion

    This function is equivalent to calling CFRelease (layer) except that it does not crash (as CFRetain does) if the layer parameter is null.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Availability

    Available in OS X version 10.4 and later.

  • Increments the retain count of a CGLayer object.

    Declaration

    Objective-C

    CGLayerRef CGLayerRetain ( CGLayerRef layer );

    Parameters

    layer

    The layer to retain.

    Return Value

    The same layer you passed in as the layer parameter.

    Discussion

    This function is equivalent to calling CFRetain (layer) except that it does not crash (as CFRetain does) if the layer parameter is null.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Availability

    Available in OS X version 10.4 and later.

  • Returns the unique type identifier used for CGLayer objects.

    Declaration

    Swift

    func CGLayerGetTypeID() -> CFTypeID

    Objective-C

    CFTypeID CGLayerGetTypeID ( void );

    Return Value

    The type identifier for CGLayer objects.

    Discussion

    A type identifier is an integer that identifies the opaque type to which a Core Foundation object belongs. You use type IDs in various contexts, such as when you are operating on heterogeneous collections.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X version 10.4 and later.

  • Returns the width and height of a CGLayer object.

    Declaration

    Swift

    func CGLayerGetSize(_ layer: CGLayer!) -> CGSize

    Objective-C

    CGSize CGLayerGetSize ( CGLayerRef layer );

    Parameters

    layer

    The layer whose width and height you want to obtain.

    Return Value

    The width and height of the layer, in default user space coordinates.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X version 10.4 and later.

  • Returns the graphics context associated with a CGLayer object.

    Declaration

    Swift

    func CGLayerGetContext(_ layer: CGLayer!) -> CGContext!

    Objective-C

    CGContextRef CGLayerGetContext ( CGLayerRef layer );

    Parameters

    layer

    The layer whose graphics context you want to obtain.

    Return Value

    The graphics context associated with the layer.

    Discussion

    The context that’s returned is the context for the layer itself, not the context that you specified when you created the layer.

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X version 10.4 and later.

Data Types

  • An opaque type used for offscreen drawing.

    Declaration

    Swift

    typealias CGLayerRef = CGLayer

    Objective-C

    typedef struct CGLayer *CGLayerRef;

    Import Statement

    Objective-C

    @import CoreGraphics;

    Swift

    import CoreGraphics

    Availability

    Available in OS X v10.4 and later.