iOS Developer Library

Developer

ApplicationServices Framework Reference CGPath Reference

Options
Deployment Target:

On This Page
Language:

CGPath Reference

A graphics path is a mathematical description of a series of shapes or lines. CGPathRef defines an opaque type that represents an immutable graphics path. CGMutablePathRef defines an opaque type that represents a mutable graphics path. Neither CGPathRef nor CGMutablePathRef define functions to draw a path. To draw a Quartz path to a graphics context, you add the path to the graphics context by calling CGContextAddPath and then call one of the context’s drawing functions—see CGContext Reference.

Each figure in the graphics path is constructed with a connected set of lines and Bézier curves, called a subpath. A subpath has an ordered set of path elements that represent single steps in the construction of the subpath. (For example, a line segment from one corner of a rectangle to another corner is a path element. Every subpath includes a starting point, which is the first point in the subpath. The path also maintains a current point, which is the last point in the last subpath.

To append a new subpath onto a mutable path, your application typically calls CGPathMoveToPoint to set the subpath’s starting point and initial current point, followed by a series of CGPathAdd* calls to add line segments and curves to the subpath. As segments or curves are added to the subpath, the subpath’s current point is updated to point to the end of the last segment or curve to be added. The lines and curves of a subpath are always connected, but they are not required to form a closed set of lines. Your application explicitly closes a subpath by calling CGPathCloseSubpath. Closing the subpath adds a line segment that terminates at the subpath’s starting point, and also changes how those lines are rendered—for more information see Paths in Quartz 2D Programming Guide.

Functions

  • Creates a mutable graphics path.

    Declaration

    Swift

    func CGPathCreateMutable() -> CGMutablePath!

    Objective-C

    CGMutablePathRef CGPathCreateMutable ( void );

    Return Value

    A new mutable path. You are responsible for releasing this object.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Create an immutable path of an ellipse.

    Declaration

    Swift

    func CGPathCreateWithEllipseInRect(_ rect: CGRect, _ transform: UnsafePointer<CGAffineTransform>) -> CGPath!

    Objective-C

    CGPathRef CGPathCreateWithEllipseInRect ( CGRect rect, const CGAffineTransform *transform );

    Parameters

    rect

    The rectangle that bounds the ellipse.

    transform

    A pointer to an affine transformation matrix, or NULL if no transformation is needed. If specified, Quartz applies the transformation to the ellipse before it is added to the path.

    Return Value

    A new, immutable path. You are responsible for releasing this object.

    Discussion

    This is a convenience function that creates a path of an ellipse. Using this convenience function is more efficient than creating a mutable path and adding an ellipse to it.

    The ellipse is approximated by a sequence of Bézier curves. Its center is the midpoint of the rectangle defined by the rect parameter. If the rectangle is square, then the ellipse is circular with a radius equal to one-half the width (or height) of the rectangle. If the rect parameter specifies a rectangular shape, then the major and minor axes of the ellipse are defined by the width and height of the rectangle.

    The ellipse forms a complete subpath of the path—that is, the ellipse drawing starts with a move-to operation and ends with a close-subpath operation, with all moves oriented in the clockwise direction. If you supply an affine transform, then the constructed Bézier curves that define the ellipse are transformed before they are added to the path.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 5.0 and later.

  • Create an immutable path of a rectangle.

    Declaration

    Swift

    func CGPathCreateWithRect(_ rect: CGRect, _ transform: UnsafePointer<CGAffineTransform>) -> CGPath!

    Objective-C

    CGPathRef CGPathCreateWithRect ( CGRect rect, const CGAffineTransform *transform );

    Parameters

    rect

    The rectangle to add.

    transform

    A pointer to an affine transformation matrix, or NULL if no transformation is needed. If specified, Quartz applies the transformation to the rectangle before it is added to the path.

    Return Value

    A new, immutable path. You are responsible for releasing this object.

    Discussion

    This is a convenience function that creates a path of an rectangle. Using this convenience function is more efficient than creating a mutable path and adding an rectangle to it.

    The rectangle is created using the following sequence of operations:

    • // start at origin
    • CGPathMoveToPoint (path, transform, CGRectGetMinX(rect), CGRectGetMinY(rect));
    • // add bottom edge
    • CGPathAddLineToPoint (path, transform, CGRectGetMaxX(rect), CGRectGetMinY(rect));
    • // add right edge
    • CGPathAddLineToPoint (path, transform, CGRectGetMaxX(rect), CGRectGetMaxY(rect);
    • // add top edge
    • CGPathAddLineToPoint (path, transform, CGRectGetMinX(rect), CGRectGetMaxY(rect));
    • // add left edge and close
    • CGPathCloseSubpath (path);

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 4.0 and later.

  • Create an immutable path of a rounded rectangle.

    Declaration

    Swift

    func CGPathCreateWithRoundedRect(_ rect: CGRect, _ cornerWidth: CGFloat, _ cornerHeight: CGFloat, _ transform: UnsafePointer<CGAffineTransform>) -> CGPath!

    Objective-C

    CGPathRef CGPathCreateWithRoundedRect ( CGRect rect, CGFloat cornerWidth, CGFloat cornerHeight, const CGAffineTransform *transform );

    Parameters

    rect

    The rectangle to add.

    cornerWidth

    The width of the rounded corner sections.

    cornerHeight

    The height of the rounded corner sections.

    transform

    A pointer to an affine transformation matrix, or NULL if no transformation is needed. If specified, Quartz applies the transformation to the rectangle before it is added to the path.

    Return Value

    A new, immutable path. You are responsible for releasing this object.

    Discussion

    This is a convenience function that creates a path of an rounded rectangle. Using this convenience function is more efficient than creating a mutable path and adding an rectangle to it.

    Each corner of the rounded rectangle is one-quarter of an ellipse with axes equal to the cornerWidth and cornerHeight parameters. The rounded rectangle forms a complete subpath and is oriented in the clockwise direction.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 7.0 and later.

  • Creates an immutable copy of a graphics path.

    Declaration

    Swift

    func CGPathCreateCopy(_ path: CGPath!) -> CGPath!

    Objective-C

    CGPathRef CGPathCreateCopy ( CGPathRef path );

    Parameters

    path

    The path to copy.

    Return Value

    A new, immutable copy of the specified path. You are responsible for releasing this object.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Creates an immutable copy of a graphics path transformed by a transformation matrix.

    Declaration

    Swift

    func CGPathCreateCopyByTransformingPath(_ path: CGPath!, _ transform: UnsafePointer<CGAffineTransform>) -> CGPath!

    Objective-C

    CGPathRef CGPathCreateCopyByTransformingPath ( CGPathRef path, const CGAffineTransform *transform );

    Parameters

    path

    The path to copy.

    transform

    A pointer to an affine transformation matrix, or NULL if no transformation is needed. If specified, Quartz applies the transformation to all elements of the new path.

    Return Value

    A new, immutable copy of the path. You are responsible for releasing this object.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 5.0 and later.

  • Creates a dashed copy of another path.

    Declaration

    Swift

    func CGPathCreateCopyByDashingPath(_ path: CGPath!, _ transform: UnsafePointer<CGAffineTransform>, _ phase: CGFloat, _ lengths: UnsafePointer<CGFloat>, _ count: UInt) -> CGPath!

    Objective-C

    CGPathRef CGPathCreateCopyByDashingPath ( CGPathRef path, const CGAffineTransform *transform, CGFloat phase, const CGFloat *lengths, size_t count );

    Parameters

    path

    The path to copy.

    transform

    A pointer to an affine transformation matrix, or NULL if no transformation is needed. If specified, Quartz applies the transformation to elements of the converted path before adding them to the new path.

    phase

    A value that specifies how far into the dash pattern the line starts, in units of the user space. For example, passing a value of 3 means the line is drawn with the dash pattern starting at three units from its beginning. Passing a value of 0 draws a line starting with the beginning of a dash pattern.

    lengths

    An array of values that specify the lengths of the painted segments and unpainted segments, respectively, of the dash pattern—or NULL for no dash pattern.

    For example, passing an array with the values [2,3] sets a dash pattern that alternates between a 2-user-space-unit-long painted segment and a 3-user-space-unit-long unpainted segment. Passing the values [1,3,4,2] sets the pattern to a 1-unit painted segment, a 3-unit unpainted segment, a 4-unit painted segment, and a 2-unit unpainted segment.

    count

    If the lengths parameter specifies an array, pass the number of elements in the array. Otherwise, pass 0.

    Return Value

    A new, immutable path. You are responsible for releasing this object.

    Discussion

    The new path is created so that filling the new path draws the same pixels as stroking the original path with the specified dash parameters.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 5.0 and later.

  • Creates a stroked copy of another path.

    Declaration

    Swift

    func CGPathCreateCopyByStrokingPath(_ path: CGPath!, _ transform: UnsafePointer<CGAffineTransform>, _ lineWidth: CGFloat, _ lineCap: CGLineCap, _ lineJoin: CGLineJoin, _ miterLimit: CGFloat) -> CGPath!

    Objective-C

    CGPathRef CGPathCreateCopyByStrokingPath ( CGPathRef path, const CGAffineTransform *transform, CGFloat lineWidth, CGLineCap lineCap, CGLineJoin lineJoin, CGFloat miterLimit );

    Parameters

    path

    The path to copy.

    transform

    A pointer to an affine transformation matrix, or NULL if no transformation is needed. If specified, Quartz applies the transformation to elements of the converted path before adding them to the new path.

    lineWidth

    The line width to use, in user space units. The value must be greater than 0.

    lineCap

    A line cap style constant—kCGLineCapButt (the default), kCGLineCapRound, or kCGLineCapSquare. See “CGLineCap”.

    lineJoin

    A line join value—kCGLineJoinMiter (the default), kCGLineJoinRound, or kCGLineJoinBevel. See “CGLineJoin”.

    miterLimit

    The miter limit to use.

    Return Value

    A new, immutable path. You are responsible for releasing this object.

    Discussion

    The new path is created so that filling the new path draws the same pixels as stroking the original path.

    If the line join style is set to kCGLineJoinMiter, Quartz uses the miter limit to determine whether the lines should be joined with a bevel instead of a miter. Quartz divides the length of the miter by the line width. If the result is greater than the miter limit, Quartz converts the style to a bevel.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 5.0 and later.

  • Creates a mutable copy of an existing graphics path.

    Declaration

    Swift

    func CGPathCreateMutableCopy(_ path: CGPath!) -> CGMutablePath!

    Objective-C

    CGMutablePathRef CGPathCreateMutableCopy ( CGPathRef path );

    Parameters

    path

    The path to copy.

    Return Value

    A new, mutable, copy of the specified path. You are responsible for releasing this object.

    Discussion

    You can modify a mutable graphics path by calling the various CGPath geometry functions, such as CGPathAddArc, CGPathAddLineToPoint, and CGPathMoveToPoint.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Creates a mutable copy of a graphics path transformed by a transformation matrix.

    Declaration

    Swift

    func CGPathCreateMutableCopyByTransformingPath(_ path: CGPath!, _ transform: UnsafePointer<CGAffineTransform>) -> CGMutablePath!

    Objective-C

    CGMutablePathRef CGPathCreateMutableCopyByTransformingPath ( CGPathRef path, const CGAffineTransform *transform );

    Parameters

    path

    The path to copy.

    transform

    A pointer to an affine transformation matrix, or NULL if no transformation is needed. If specified, Quartz applies the transformation to all elements of the new path.

    Return Value

    A new, mutable copy of the specified path transformed by the transform parameter. You are responsible for releasing this object.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 5.0 and later.

  • Decrements the retain count of a graphics path.

    Declaration

    Objective-C

    void CGPathRelease ( CGPathRef path );

    Parameters

    path

    The graphics path to release.

    Discussion

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

    Import Statement

    Availability

    Available in iOS 2.0 and later.

  • Increments the retain count of a graphics path.

    Declaration

    Objective-C

    CGPathRef CGPathRetain ( CGPathRef path );

    Parameters

    path

    The graphics path to retain.

    Return Value

    The same path you passed in as the path parameter.

    Discussion

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

    Import Statement

    Availability

    Available in iOS 2.0 and later.

  • Appends an arc to a mutable graphics path, possibly preceded by a straight line segment.

    Declaration

    Swift

    func CGPathAddArc(_ path: CGMutablePath!, _ m: UnsafePointer<CGAffineTransform>, _ x: CGFloat, _ y: CGFloat, _ r: CGFloat, _ startAngle: CGFloat, _ endAngle: CGFloat, _ clockwise: Bool)

    Objective-C

    void CGPathAddArc ( CGMutablePathRef path, const CGAffineTransform *m, CGFloat x, CGFloat y, CGFloat radius, CGFloat startAngle, CGFloat endAngle, bool clockwise );

    Parameters

    path

    The mutable graphics path to change.

    m

    A pointer to an affine transformation matrix, or NULL if no transformation is needed. If specified, Quartz applies the transformation to the arc before it is added to the path.

    x

    The x-coordinate of the center point of the arc.

    y

    The y-coordinate of the center point of the arc.

    r

    The radius of the arc.

    startAngle

    The angle (in radians) that determines the starting point of the arc, measured from the x-axis in the current user space.

    endAngle

    The angle (in radians) that determines the ending point of the arc, measured from the x-axis in the current user space.

    clockwise

    A Boolean value that specifies whether or not to draw the arc in the clockwise direction, before applying the transformation matrix.

    Discussion

    An arc is a segment of a circle with radius r centered at a point (x,y). When you call this function, you provide the center point, radius, and two angles in radians. Quartz uses this information to determine the end points of the arc, and then approximates the new arc using a sequence of cubic Bézier curves. The clockwise parameter determines the direction in which the arc is created. The actual direction may change depending on the coordinate system transformation applied to the path.

    A transformation may be applied to the Bézier curves before they are added to the path. If no transform is needed, the second argument should be NULL.

    If the specified path already contains a subpath, Quartz implicitly adds a line connecting the subpath’s current point to the beginning of the arc. If the path is empty, Quartz creates a new subpath with a starting point set to the starting point of the arc.

    The ending point of the arc becomes the new current point of the path.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Appends an arc to a mutable graphics path, possibly preceded by a straight line segment.

    Declaration

    Swift

    func CGPathAddRelativeArc(_ path: CGMutablePath!, _ matrix: UnsafePointer<CGAffineTransform>, _ x: CGFloat, _ y: CGFloat, _ radius: CGFloat, _ startAngle: CGFloat, _ delta: CGFloat)

    Objective-C

    void CGPathAddRelativeArc ( CGMutablePathRef path, const CGAffineTransform *matrix, CGFloat x, CGFloat y, CGFloat radius, CGFloat startAngle, CGFloat delta );

    Parameters

    path

    The mutable graphics path to change.

    matrix

    A pointer to an affine transformation matrix, or NULL if no transformation is needed. If specified, Quartz applies the transformation to the arc before it is added to the path.

    x

    The x-coordinate of the center point of the arc.

    y

    The y-coordinate of the center point of the arc.

    radius

    The radius of the arc.

    startAngle

    The angle (in radians) that determines the starting point of the arc, measured from the x-axis in the current user space.

    delta

    The distance the arc should travel (in radians). A positive value indicates a counter-clockwise arc in the current user space.

    Discussion

    The angle to the second endpoint of the arc is calculated by adding the delta to the start angle.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 5.0 and later.

  • Appends an arc to a mutable graphics path, possibly preceded by a straight line segment.

    Declaration

    Swift

    func CGPathAddArcToPoint(_ path: CGMutablePath!, _ m: UnsafePointer<CGAffineTransform>, _ x1: CGFloat, _ y1: CGFloat, _ x2: CGFloat, _ y2: CGFloat, _ radius: CGFloat)

    Objective-C

    void CGPathAddArcToPoint ( CGMutablePathRef path, const CGAffineTransform *m, CGFloat x1, CGFloat y1, CGFloat x2, CGFloat y2, CGFloat radius );

    Parameters

    path

    The mutable path to change. The path must not be empty.

    m

    A pointer to an affine transformation matrix, or NULL if no transformation is needed. If specified, Quartz applies the transformation to the arc before it is added to the path.

    x1

    The x-coordinate of the user space for the end point of the first tangent line. The first tangent line is drawn from the current point to (x1,y1).

    y1

    The y-coordinate of the user space for the end point of the first tangent line. The first tangent line is drawn from the current point to (x1,y1).

    x2

    The x-coordinate of the user space for the end point of the second tangent line. The second tangent line is drawn from (x1,y1) to (x2,y2).

    y2

    The y-coordinate of the user space for the end point of the second tangent line. The second tangent line is drawn from (x1,y1) to (x2,y2).

    radius

    The radius of the arc, in user space coordinates.

    Discussion

    This function uses a sequence of cubic Bézier curves to create an arc that is tangent to the line from the current point to (x1,y1) and to the line from (x1,y1) to (x2,y2). The start and end points of the arc are located on the first and second tangent lines, respectively. The start and end points of the arc are also the “tangent points” of the lines.

    If the current point and the first tangent point of the arc (the starting point) are not equal, Quartz appends a straight line segment from the current point to the first tangent point.

    The ending point of the arc becomes the new current point of the path.

    For another way to draw an arc in a path, see CGPathAddArc.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Appends a cubic Bézier curve to a mutable graphics path.

    Declaration

    Swift

    func CGPathAddCurveToPoint(_ path: CGMutablePath!, _ m: UnsafePointer<CGAffineTransform>, _ cp1x: CGFloat, _ cp1y: CGFloat, _ cp2x: CGFloat, _ cp2y: CGFloat, _ x: CGFloat, _ y: CGFloat)

    Objective-C

    void CGPathAddCurveToPoint ( CGMutablePathRef path, const CGAffineTransform *m, CGFloat cp1x, CGFloat cp1y, CGFloat cp2x, CGFloat cp2y, CGFloat x, CGFloat y );

    Parameters

    path

    The mutable path to change. The path must not be empty.

    m

    A pointer to an affine transformation matrix, or NULL if no transformation is needed. If specified, Quartz applies the transformation to the curve before it is added to the path.

    cp1x

    The x-coordinate of the first control point.

    cp1y

    The y-coordinate of the first control point.

    cp2x

    The x-coordinate of the second control point.

    cp2y

    The y-coordinate of the second control point.

    x

    The x-coordinate of the end point of the curve.

    y

    The y-coordinate of the end point of the curve.

    Discussion

    Appends a cubic Bézier curve from the current point in a path to the specified location using two control points, after an optional transformation. Before returning, this function updates the current point to the specified location (x,y).

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Appends an array of new line segments to a mutable graphics path.

    Declaration

    Swift

    func CGPathAddLines(_ path: CGMutablePath!, _ m: UnsafePointer<CGAffineTransform>, _ points: UnsafePointer<CGPoint>, _ count: UInt)

    Objective-C

    void CGPathAddLines ( CGMutablePathRef path, const CGAffineTransform *m, const CGPoint points[], size_t count );

    Parameters

    path

    The mutable path to change.

    m

    A pointer to an affine transformation matrix, or NULL if no transformation is needed. If specified, Quartz applies the transformation to the lines before adding them to the path.

    points

    An array of points that specifies the line segments to add.

    count

    The number of elements in the array.

    Discussion

    This is a convenience function that adds a sequence of connected line segments to a path, using the following operation:

    • CGPathMoveToPoint (path, m, points[0].x, points[0].y);
    • for (k = 1; k < count; k++) {
    • CGPathAddLineToPoint (path, m, points[k].x, points[k].y);
    • }

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Appends a line segment to a mutable graphics path.

    Declaration

    Swift

    func CGPathAddLineToPoint(_ path: CGMutablePath!, _ m: UnsafePointer<CGAffineTransform>, _ x: CGFloat, _ y: CGFloat)

    Objective-C

    void CGPathAddLineToPoint ( CGMutablePathRef path, const CGAffineTransform *m, CGFloat x, CGFloat y );

    Parameters

    path

    The mutable path to change. The path must not be empty.

    m

    A pointer to an affine transformation matrix, or NULL if no transformation is needed. If specified, Quartz applies the transformation to the line before it is added to the path.

    x

    The x-coordinate of the end point of the line.

    y

    The y-coordinate of the end point of the line.

    Discussion

    Before returning, this function updates the current point to the specified location (x,y).

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Appends a path to onto a mutable graphics path.

    Declaration

    Swift

    func CGPathAddPath(_ path1: CGMutablePath!, _ m: UnsafePointer<CGAffineTransform>, _ path2: CGPath!)

    Objective-C

    void CGPathAddPath ( CGMutablePathRef path1, const CGAffineTransform *m, CGPathRef path2 );

    Parameters

    path1

    The mutable path to change.

    m

    A pointer to an affine transformation matrix, or NULL if no transformation is needed. If specified, Quartz applies the transformation to path2 before it is added to path1.

    path2

    The path to add.

    Discussion

    If the source path is non-empty, then its path elements are appended in order onto the mutable path. After the call completes, the start point and current point of the path are those of the last subpath in path2.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Appends a quadratic Bézier curve to a mutable graphics path.

    Declaration

    Swift

    func CGPathAddQuadCurveToPoint(_ path: CGMutablePath!, _ m: UnsafePointer<CGAffineTransform>, _ cpx: CGFloat, _ cpy: CGFloat, _ x: CGFloat, _ y: CGFloat)

    Objective-C

    void CGPathAddQuadCurveToPoint ( CGMutablePathRef path, const CGAffineTransform *m, CGFloat cpx, CGFloat cpy, CGFloat x, CGFloat y );

    Parameters

    path

    The mutable path to change. The path must not be empty.

    m

    A pointer to an affine transformation matrix, or NULL if no transformation is needed. If specified, Quartz applies the transformation to the curve before adding it to the path.

    cpx

    The x-coordinate of the control point.

    cpy

    The y-coordinate of the control point.

    x

    The x-coordinate of the end point of the curve.

    y

    The y-coordinate of the end point of the curve.

    Discussion

    Before returning, this function updates the current point to the specified location (x, y).

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Appends a rectangle to a mutable graphics path.

    Declaration

    Swift

    func CGPathAddRect(_ path: CGMutablePath!, _ m: UnsafePointer<CGAffineTransform>, _ rect: CGRect)

    Objective-C

    void CGPathAddRect ( CGMutablePathRef path, const CGAffineTransform *m, CGRect rect );

    Parameters

    path

    The mutable path to change.

    m

    A pointer to an affine transformation matrix, or NULL if no transformation is needed. If specified, Quartz applies the transformation to the rectangle before adding it to the path.

    rect

    The rectangle to add.

    Discussion

    This is a convenience function that adds a rectangle to a path, using the following sequence of operations:

    • // start at origin
    • CGPathMoveToPoint (path, m, CGRectGetMinX(rect), CGRectGetMinY(rect));
    • // add bottom edge
    • CGPathAddLineToPoint (path, m, CGRectGetMaxX(rect), CGRectGetMinY(rect));
    • // add right edge
    • CGPathAddLineToPoint (path, m, CGRectGetMaxX(rect), CGRectGetMaxY(rect);
    • // add top edge
    • CGPathAddLineToPoint (path, m, CGRectGetMinX(rect), CGRectGetMaxY(rect));
    • // add left edge and close
    • CGPathCloseSubpath (path);

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Appends an array of rectangles to a mutable graphics path.

    Declaration

    Swift

    func CGPathAddRects(_ path: CGMutablePath!, _ m: UnsafePointer<CGAffineTransform>, _ rects: UnsafePointer<CGRect>, _ count: UInt)

    Objective-C

    void CGPathAddRects ( CGMutablePathRef path, const CGAffineTransform *m, const CGRect rects[], size_t count );

    Parameters

    path

    The mutable path to change.

    m

    An affine transformation matrix, or NULL if no transformation is needed. If specified, Quartz applies the transformation to the rectangles before adding them to the path.

    rects

    The array of new rectangles to add.

    count

    The number of elements in the array.

    Discussion

    This is a convenience function that adds an array of rectangles to a path, using the following operation:

    • for (k = 0; k < count; k++) {
    • CGPathAddRect (path, m, rects[k]);
    • }

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Appends a rounded rectangle to a mutable graphics path.

    Declaration

    Swift

    func CGPathAddRoundedRect(_ path: CGMutablePath!, _ transform: UnsafePointer<CGAffineTransform>, _ rect: CGRect, _ cornerWidth: CGFloat, _ cornerHeight: CGFloat)

    Objective-C

    void CGPathAddRoundedRect ( CGMutablePathRef path, const CGAffineTransform *transform, CGRect rect, CGFloat cornerWidth, CGFloat cornerHeight );

    Parameters

    path

    The mutable path to change.

    transform

    A pointer to an affine transformation matrix, or NULL if no transformation is needed. If specified, Quartz applies the transformation to the rectangle before adding it to the path.

    rect

    The rectangle to add.

    cornerWidth

    The width of the rounded corner sections.

    cornerHeight

    The height of the rounded corner sections.

    Discussion

    This is a convenience function that adds a path of an rounded rectangle.

    Each corner of the rounded rectangle is one-quarter of an ellipse with axes equal to the cornerWidth and cornerHeight parameters. The rounded rectangle forms a complete subpath and is oriented in the clockwise direction.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 7.0 and later.

  • For each element in a graphics path, calls a custom applier function.

    Declaration

    Swift

    func CGPathApply(_ path: CGPath!, _ info: UnsafeMutablePointer<Void>, _ function: CGPathApplierFunction)

    Objective-C

    void CGPathApply ( CGPathRef path, void *info, CGPathApplierFunction function );

    Parameters

    path

    The path to which the function will be applied.

    info

    A pointer to the user data that Quartz will pass to the function being applied, or NULL.

    function

    A pointer to the function to apply. See CGPathApplierFunction for more information.

    Discussion

    For each element in the specified path, Quartz calls the applier function, which can examine (but not modify) the element.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Starts a new subpath at a specified location in a mutable graphics path.

    Declaration

    Swift

    func CGPathMoveToPoint(_ path: CGMutablePath!, _ m: UnsafePointer<CGAffineTransform>, _ x: CGFloat, _ y: CGFloat)

    Objective-C

    void CGPathMoveToPoint ( CGMutablePathRef path, const CGAffineTransform *m, CGFloat x, CGFloat y );

    Parameters

    path

    The mutable path to change.

    m

    A pointer to an affine transformation matrix, or NULL if no transformation is needed. If specified, Quartz applies the transformation to the point before changing the path.

    x

    The x-coordinate of the new location.

    y

    The y-coordinate of the new location.

    Discussion

    This function ends the subpath already in progress (if any) and starts a new subpath, initializing the starting point and the current point to the specified location (x,y) after an optional transformation.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Closes and completes a subpath in a mutable graphics path.

    Declaration

    Swift

    func CGPathCloseSubpath(_ path: CGMutablePath!)

    Objective-C

    void CGPathCloseSubpath ( CGMutablePathRef path );

    Parameters

    path

    The path to change.

    Discussion

    Appends a line from the current point to the starting point of the current subpath and ends the subpath.

    After closing the subpath, your application can begin a new subpath without first calling CGPathMoveToPoint. In this case, a new subpath is implicitly created with a starting and current point equal to the previous subpath’s starting point.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Adds to a path an ellipse that fits inside a rectangle.

    Declaration

    Swift

    func CGPathAddEllipseInRect(_ path: CGMutablePath!, _ m: UnsafePointer<CGAffineTransform>, _ rect: CGRect)

    Objective-C

    void CGPathAddEllipseInRect ( CGMutablePathRef path, const CGAffineTransform *m, CGRect rect );

    Parameters

    path

    The path to modify.

    m

    An affine transform to apply to the ellipse, or NULL if you don’t want to transform the ellipse.

    rect

    A rectangle to enclose the ellipse.

    Discussion

    The ellipse is approximated by a sequence of Bézier curves. Its center is the midpoint of the rectangle defined by the rect parameter. If the rectangle is square, then the ellipse is circular with a radius equal to one-half the width (or height) of the rectangle. If the rect parameter specifies a rectangular shape, then the major and minor axes of the ellipse are defined by the width and height of the rectangle.

    The ellipse forms a complete subpath of the path—that is, the ellipse drawing starts with a move-to operation and ends with a close-subpath operation, with all moves oriented in the clockwise direction. If you supply an affine transform, then the constructed Bézier curves that define the ellipse are transformed before they are added to the path.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Indicates whether two graphics paths are equivalent.

    Declaration

    Swift

    func CGPathEqualToPath(_ path1: CGPath!, _ path2: CGPath!) -> Bool

    Objective-C

    bool CGPathEqualToPath ( CGPathRef path1, CGPathRef path2 );

    Parameters

    path1

    The first path being compared.

    path2

    The second path being compared.

    Return Value

    A Boolean value that indicates whether or not the two specified paths contain the same sequence of path elements. If the paths are not the same, returns false.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Returns the bounding box containing all points in a graphics path.

    Declaration

    Swift

    func CGPathGetBoundingBox(_ path: CGPath!) -> CGRect

    Objective-C

    CGRect CGPathGetBoundingBox ( CGPathRef path );

    Parameters

    path

    The graphics path to evaluate.

    Return Value

    A rectangle that represents the bounding box of the specified path. If the path is empty, this function returns CGRectNull.

    Discussion

    The bounding box is the smallest rectangle completely enclosing all points in the path, including control points for Bézier and quadratic curves.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Returns the bounding box of a graphics path.

    Declaration

    Swift

    func CGPathGetPathBoundingBox(_ path: CGPath!) -> CGRect

    Objective-C

    CGRect CGPathGetPathBoundingBox ( CGPathRef path );

    Parameters

    path

    The graphics path to evaluate.

    Return Value

    A rectangle that represents the path bounding box of the specified path. If the path is empty, this function returns CGRectNull.

    Discussion

    The path bounding box is the smallest rectangle completely enclosing all points in the path but not including control points for Bézier and quadratic curves.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 4.0 and later.

  • Returns the current point in a graphics path.

    Declaration

    Swift

    func CGPathGetCurrentPoint(_ path: CGPath!) -> CGPoint

    Objective-C

    CGPoint CGPathGetCurrentPoint ( CGPathRef path );

    Parameters

    path

    The path to evaluate.

    Return Value

    The current point in the specified path.

    Discussion

    If the path is empty—that is, if it has no elements—this function returns CGPointZero (see CGGeometry Reference). To determine whether a path is empty, use CGPathIsEmpty.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Returns the Core Foundation type identifier for Quartz graphics paths.

    Declaration

    Swift

    func CGPathGetTypeID() -> CFTypeID

    Objective-C

    CFTypeID CGPathGetTypeID ( void );

    Return Value

    The Core Foundation identifier for the opaque type CGPathRef.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Indicates whether or not a graphics path is empty.

    Declaration

    Swift

    func CGPathIsEmpty(_ path: CGPath!) -> Bool

    Objective-C

    bool CGPathIsEmpty ( CGPathRef path );

    Parameters

    path

    The path to evaluate.

    Return Value

    A Boolean value that indicates whether the specified path is empty.

    Discussion

    An empty path contains no elements.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Indicates whether or not a graphics path represents a rectangle.

    Declaration

    Swift

    func CGPathIsRect(_ path: CGPath!, _ rect: UnsafeMutablePointer<CGRect>) -> Bool

    Objective-C

    bool CGPathIsRect ( CGPathRef path, CGRect *rect );

    Parameters

    path

    The path to evaluate.

    rect

    On input, a pointer to an uninitialized rectangle. If the specified path represents a rectangle, on return contains a copy of the rectangle.

    Return Value

    A Boolean value that indicates whether the specified path represents a rectangle. If the path represents a rectangle, returns true.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Checks whether a point is contained in a graphics path.

    Declaration

    Swift

    func CGPathContainsPoint(_ path: CGPath!, _ m: UnsafePointer<CGAffineTransform>, _ point: CGPoint, _ eoFill: Bool) -> Bool

    Objective-C

    bool CGPathContainsPoint ( CGPathRef path, const CGAffineTransform *m, CGPoint point, bool eoFill );

    Parameters

    path

    The path to evaluate the point against.

    m

    An affine transform. If m is not NULL then the point is transformed by this affine transform prior to determining whether the path contains the point.

    point

    The point to check.

    eoFill

    A Boolean value that, if true, specifies to use the even-odd fill rule to evaluate the painted region of the path. If false, the winding fill rule is used.

    Return Value

    Returns true if the point is contained in the path; false otherwise.

    Discussion

    A point is contained in a path if it would be inside the painted region when the path is filled.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

Callbacks

  • Defines a callback function that can view an element in a graphics path.

    Declaration

    Objective-C

    typedef void (*CGPathApplierFunction) ( void *info, const CGPathElement *element );

    Discussion

    See also CGPathApply.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

Data Types

  • An opaque type that represents an immutable graphics path.

    Declaration

    Swift

    typealias CGPathRef = CGPath

    Objective-C

    typedef const struct CGPath *CGPathRef;

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • An opaque type that represents a mutable graphics path.

    Declaration

    Swift

    typealias CGMutablePathRef = CGMutablePath

    Objective-C

    typedef struct CGPath *CGMutablePathRef;

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • A data structure that provides information about a path element.

    Declaration

    Swift

    struct CGPathElement { var type: CGPathElementType var points: UnsafeMutablePointer<CGPoint> }

    Objective-C

    struct CGPathElement { CGPathElementType type; CGPoint * points; }; typedef struct CGPathElement CGPathElement;

    Fields

    type

    An element type (or operation).

    points

    An array of one or more points that serve as arguments.

    Availability

    Available in iOS 2.0 and later.

Constants

  • Options for rendering a path.

    Declaration

    Swift

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

    Objective-C

    enum CGPathDrawingMode { kCGPathFill, kCGPathEOFill, kCGPathStroke, kCGPathFillStroke, kCGPathEOFillStroke }; typedef enum CGPathDrawingMode CGPathDrawingMode;

    Constants

    • kCGPathFill

      kCGPathFill

      Render the area contained within the path using the non-zero winding number rule.

      Available in iOS 2.0 and later.

    • kCGPathEOFill

      kCGPathEOFill

      Render the area within the path using the even-odd rule.

      Available in iOS 2.0 and later.

    • kCGPathStroke

      kCGPathStroke

      Render a line along the path.

      Available in iOS 2.0 and later.

    • kCGPathFillStroke

      kCGPathFillStroke

      First fill and then stroke the path, using the nonzero winding number rule.

      Available in iOS 2.0 and later.

    • kCGPathEOFillStroke

      kCGPathEOFillStroke

      First fill and then stroke the path, using the even-odd rule.

      Available in iOS 2.0 and later.

    Discussion

    You can pass a path drawing mode constant to the function CGContextDrawPath to specify how Quartz should paint a graphics context’s current path.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • The type of element found in a path.

    Declaration

    Swift

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

    Objective-C

    enum CGPathElementType { kCGPathElementMoveToPoint, kCGPathElementAddLineToPoint, kCGPathElementAddQuadCurveToPoint, kCGPathElementAddCurveToPoint, kCGPathElementCloseSubpath }; typedef enum CGPathElementType CGPathElementType;

    Constants

    • kCGPathElementMoveToPoint

      kCGPathElementMoveToPoint

      The path element that starts a new subpath. The element holds a single point for the destination. See the function CGPathMoveToPoint.

      Available in iOS 2.0 and later.

    • kCGPathElementAddLineToPoint

      kCGPathElementAddLineToPoint

      The path element that adds a line from the current point to a new point. The element holds a single point for the destination. See the function CGPathAddLineToPoint.

      Available in iOS 2.0 and later.

    • kCGPathElementAddQuadCurveToPoint

      kCGPathElementAddQuadCurveToPoint

      The path element that adds a quadratic curve from the current point to the specified point. The element holds a control point and a destination point. See the function CGPathAddQuadCurveToPoint.

      Available in iOS 2.0 and later.

    • kCGPathElementAddCurveToPoint

      kCGPathElementAddCurveToPoint

      The path element that adds a cubic curve from the current point to the specified point. The element holds two control points and a destination point. See the function CGPathAddCurveToPoint.

      Available in iOS 2.0 and later.

    • kCGPathElementCloseSubpath

      kCGPathElementCloseSubpath

      The path element that closes and completes a subpath. The element does not contain any points. See the function CGPathCloseSubpath.

      Available in iOS 2.0 and later.

    Discussion

    For more information about paths, see CGPathRef.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Styles for rendering the endpoint of a stroked line.

    Declaration

    Swift

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

    Objective-C

    enum CGLineCap { kCGLineCapButt, kCGLineCapRound, kCGLineCapSquare }; typedef enum CGLineCap CGLineCap;

    Constants

    • kCGLineCapButt

      kCGLineCapButt

      A line with a squared-off end. Quartz draws the line to extend only to the exact endpoint of the path. This is the default.

      Available in iOS 2.0 and later.

    • kCGLineCapRound

      kCGLineCapRound

      A line with a rounded end. Quartz draws the line to extend beyond the endpoint of the path. The line ends with a semicircular arc with a radius of 1/2 the line’s width, centered on the endpoint.

      Available in iOS 2.0 and later.

    • kCGLineCapSquare

      kCGLineCapSquare

      A line with a squared-off end. Quartz extends the line beyond the endpoint of the path for a distance equal to half the line width.

      Available in iOS 2.0 and later.

    Discussion

    A line cap specifies the method used by CGContextStrokePath to draw the endpoint of the line. To change the line cap style in a graphics context, you use the function CGContextSetLineCap.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.

  • Junction types for stroked lines.

    Declaration

    Swift

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

    Objective-C

    enum CGLineJoin { kCGLineJoinMiter, kCGLineJoinRound, kCGLineJoinBevel }; typedef enum CGLineJoin CGLineJoin;

    Constants

    • kCGLineJoinMiter

      kCGLineJoinMiter

      A join with a sharp (angled) corner. Quartz draws the outer sides of the lines beyond the endpoint of the path, until they meet. If the length of the miter divided by the line width is greater than the miter limit, a bevel join is used instead. This is the default. To set the miter limit, see CGContextSetMiterLimit.

      Available in iOS 2.0 and later.

    • kCGLineJoinRound

      kCGLineJoinRound

      A join with a rounded end. Quartz draws the line to extend beyond the endpoint of the path. The line ends with a semicircular arc with a radius of 1/2 the line’s width, centered on the endpoint.

      Available in iOS 2.0 and later.

    • kCGLineJoinBevel

      kCGLineJoinBevel

      A join with a squared-off end. Quartz draws the line to extend beyond the endpoint of the path, for a distance of 1/2 the line’s width.

      Available in iOS 2.0 and later.

    Discussion

    A line join specifies how CGContextStrokePath draws the junction between connected line segments. To set the line join style in a graphics context, you use the function CGContextSetLineJoin.

    Import Statement

    import CoreGraphics

    Availability

    Available in iOS 2.0 and later.