iOS Developer Library

Developer

ApplicationServices Framework Reference CGPattern Reference

Options
Deployment Target:

On This Page
Language:

CGPattern Reference

The CGPatternRef opaque type represents a pattern that you can use to stroke along or fill in a graphics path. Quartz tiles the pattern cell for you, based on parameters you specify when you call CGPatternCreate.

To create a dashed line, see CGContextSetLineDash in CGContext Reference.

Functions

  • Creates a pattern object.

    Declaration

    Swift

    func CGPatternCreate(_ info: UnsafeMutablePointer<Void>, _ bounds: CGRect, _ matrix: CGAffineTransform, _ xStep: CGFloat, _ yStep: CGFloat, _ tiling: CGPatternTiling, _ isColored: Bool, _ callbacks: UnsafePointer<CGPatternCallbacks>) -> CGPattern!

    Objective-C

    CGPatternRef CGPatternCreate ( void *info, CGRect bounds, CGAffineTransform matrix, CGFloat xStep, CGFloat yStep, CGPatternTiling tiling, bool isColored, const CGPatternCallbacks *callbacks );

    Parameters

    info

    A pointer to private storage used by your pattern drawing function, or NULL. For more information, see the discussion below.

    bounds

    The bounding box of the pattern cell, specified in pattern space. (Pattern space is an abstract space that maps to the default user space by the transformation matrix you specify with the matrix parameter.) The drawing done in your pattern drawing function is clipped to this rectangle.

    matrix

    A matrix that represents a transform from pattern space to the default user space of the context in which the pattern is used. If no transform is needed, pass the identity matrix.

    xStep

    The horizontal displacement between cells, specified in pattern space. For no additional horizontal space between cells (so that each pattern cells abuts the previous pattern cell in the horizontal direction), pass the width of the pattern cell.

    yStep

    The vertical displacement between cells, specified in pattern space. For no additional vertical space between cells (so that each pattern cells abuts the previous pattern cell in the vertical direction), pass the height of the pattern cell.

    tiling

    A CGPatternTiling constant that specifies the desired tiling method. For more information about tiling methods, see “Tiling Patterns”.

    isColored

    If you want to draw your pattern using its own intrinsic color, pass true. If you want to draw an uncolored (or masking) pattern that uses the fill or stroke color in the graphics state, pass false.

    callbacks

    A pointer to a pattern callback function table—your pattern drawing function is an entry in this table. See CGPatternCallbacks for more information about callback function tables for patterns.

    Return Value

    A new Quartz pattern. You are responsible for releasing this object using CGPatternRelease.

    Discussion

    Quartz calls your drawing function at the appropriate time to draw the pattern cell. A pattern cell must be invariant—that is, the pattern cell should be drawn exactly the same way each time the drawing function is called.

    The appearance of a pattern cell is unaffected by changes in the graphics state of the context in which the pattern is used.

    See CGPatternDrawPatternCallback for more information about pattern drawing functions.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Returns the type identifier for Quartz patterns.

    Declaration

    Swift

    func CGPatternGetTypeID() -> CFTypeID

    Objective-C

    CFTypeID CGPatternGetTypeID ( void );

    Return Value

    The identifier for the opaque type CGPatternRef.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Increments the retain count of a Quartz pattern.

    Declaration

    Objective-C

    CGPatternRef CGPatternRetain ( CGPatternRef pattern );

    Parameters

    pattern

    The pattern to retain.

    Return Value

    The same pattern you passed in as the pattern parameter.

    Discussion

    This function is equivalent to CFRetain, except that it does not cause an error if the pattern parameter is NULL.

    Import Statement

    Availability

    Available in iOS 2.0 and later.

  • Decrements the retain count of a Quartz pattern.

    Declaration

    Objective-C

    void CGPatternRelease ( CGPatternRef pattern );

    Parameters

    pattern

    The pattern to release.

    Discussion

    This function is equivalent to CFRelease, except that it does not cause an error if the pattern parameter is NULL.

    Import Statement

    Availability

    Available in iOS 2.0 and later.

Callbacks

  • Draws a pattern cell.

    Declaration

    Objective-C

    typedef void (*CGPatternDrawPatternCallback) ( void * info, CGContextRef context );

    Parameters

    info

    A generic pointer to private data associated with the pattern. This is the same pointer you supplied to CGPatternCreate.

    context

    The graphics context for drawing the pattern cell.

    Discussion

    When a pattern is used to stroke or fill a graphics path, Quartz calls your custom drawing function at the appropriate time to draw the pattern cell. The cell should be drawn exactly the same way each time the drawing function is called.

    In a drawing function associated with an uncolored pattern, you should not attempt to set a stroke or fill color or color space—if you do so, the result is undefined.

    To learn how to associate your drawing function with a Quartz pattern, see CGPatternCreate and CGPatternCallbacks.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Release private data or resources associated with the pattern.

    Declaration

    Objective-C

    typedef void (*CGPatternReleaseInfoCallback) ( void * info );

    Parameters

    info

    A generic pointer to private data shared among your callback functions. This is the same pointer you supplied to CGPatternCreate.

    Discussion

    Quartz calls your release function when it frees your pattern object.

    To learn how to associate your release function with a Quartz pattern, see CGPatternCreate and CGPatternCallbacks.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

Data Types

  • An opaque type that represents a pattern.

    Declaration

    Swift

    typealias CGPatternRef = CGPattern

    Objective-C

    typedef struct CGPattern * CGPatternRef;

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • A structure that holds a version and two callback functions for drawing a custom pattern.

    Declaration

    Swift

    struct CGPatternCallbacks { var version: UInt32 var drawPattern: CGPatternDrawPatternCallback var releaseInfo: CGPatternReleaseInfoCallback }

    Objective-C

    struct CGPatternCallbacks { unsigned int version; CGPatternDrawPatternCallback drawPattern; CGPatternReleaseInfoCallback releaseInfo; }; typedef struct CGPatternCallbacks CGPatternCallbacks;

    Fields

    version

    The version of the structure passed in as a parameter to the CGPatternCreate. For this version of the structure, you should set this value to zero.

    drawPattern

    A pointer to a custom function that draws the pattern. For information about this callback function, see CGPatternDrawPatternCallback.

    releaseInfo

    An optional pointer to a custom function that’s invoked when the pattern is released. CGPatternReleaseInfoCallback.

    Discussion

    You supply a CGPatternCallbacks structure to the function CGPatternCreate to create a data provider for direct access. The functions specified by the CGPatternCallbacks structure are responsible for drawing the pattern and for handling the pattern’s memory management.

    Availability

    Available in iOS 2.0 and later.

Constants

  • Different methods for rendering a tiled pattern.

    Declaration

    Swift

    struct CGPatternTiling { init(_ value: UInt32) var value: UInt32 }

    Objective-C

    enum CGPatternTiling { kCGPatternTilingNoDistortion, kCGPatternTilingConstantSpacingMinimalDistortion, kCGPatternTilingConstantSpacing }; typedef enum CGPatternTiling CGPatternTiling;

    Constants

    • kCGPatternTilingNoDistortion

      kCGPatternTilingNoDistortion

      The pattern cell is not distorted when painted. The spacing between pattern cells may vary by as much as 1 device pixel.

      Available in iOS 2.0 and later.

    • kCGPatternTilingConstantSpacingMinimalDistortion

      kCGPatternTilingConstantSpacingMinimalDistortion

      Pattern cells are spaced consistently. The pattern cell may be distorted by as much as 1 device pixel when the pattern is painted.

      Available in iOS 2.0 and later.

    • kCGPatternTilingConstantSpacing

      kCGPatternTilingConstantSpacing

      Pattern cells are spaced consistently, as with kCGPatternTilingConstantSpacingMinimalDistortion. The pattern cell may be distorted additionally to permit a more efficient implementation.

      Available in iOS 2.0 and later.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.