CGPath Reference

Overview

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 by Task

Creating and Managing Paths

• CGPathCreateMutable
• CGPathCreateWithEllipseInRect
• CGPathCreateWithRect
• CGPathCreateCopy
• CGPathCreateCopyByTransformingPath
• CGPathCreateCopyByDashingPath
• CGPathCreateCopyByStrokingPath
• CGPathCreateMutableCopy
• CGPathCreateMutableCopyByTransformingPath
• CGPathRelease
• CGPathRetain

Modifying Quartz Paths

• CGPathAddArc
• CGPathAddRelativeArc
• CGPathAddArcToPoint
• CGPathAddCurveToPoint
• CGPathAddLines
• CGPathAddLineToPoint
• CGPathAddPath
• CGPathAddQuadCurveToPoint
• CGPathAddRect
• CGPathAddRects
• CGPathApply
• CGPathMoveToPoint
• CGPathCloseSubpath
• CGPathAddEllipseInRect

Getting Information about Quartz Paths

• CGPathEqualToPath
• CGPathGetBoundingBox
• CGPathGetPathBoundingBox
• CGPathGetCurrentPoint
• CGPathGetTypeID
• CGPathIsEmpty
• CGPathIsRect
• CGPathContainsPoint

Functions

CGPathAddArc

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

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

CGPathAddArcToPoint

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

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

CGPathAddCurveToPoint

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

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

CGPathAddEllipseInRect

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

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

CGPathAddLines

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

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

CGPathMoveToPoint (path, m, points[0].x, points[0].y);

for (k = 1; k < count; k++) {

    CGPathAddLineToPoint (path, m, points[k].x, points[k].y);

}

CGPathAddLineToPoint

Appends a line segment to a mutable graphics path.

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

CGPathAddPath

Appends a path to onto a mutable graphics path.

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

CGPathAddQuadCurveToPoint

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

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

CGPathAddRect

Appends a rectangle to a mutable graphics path.

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

// 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);

CGPathAddRects

Appends an array of rectangles to a mutable graphics path.

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

for (k = 0; k < count; k++) {

    CGPathAddRect (path, m, rects[k]);

}

CGPathAddRelativeArc

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

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

CGPathApply

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

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

CGPathCloseSubpath

Closes and completes a subpath in a mutable graphics path.

void CGPathCloseSubpath (
   CGMutablePathRef path
);

CGPathContainsPoint

Checks whether a point is contained in a graphics path.

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

CGPathCreateCopy

Creates an immutable copy of a graphics path.

CGPathRef CGPathCreateCopy (
   CGPathRef path
);

CGPathCreateCopyByDashingPath

Creates a dashed copy of another path.

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

CGPathCreateCopyByStrokingPath

Creates a stroked copy of another path.

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

CGPathCreateCopyByTransformingPath

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

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

CGPathCreateMutable

Creates a mutable graphics path.

CGMutablePathRef CGPathCreateMutable (
   void
);

CGPathCreateMutableCopy

Creates a mutable copy of an existing graphics path.

CGMutablePathRef CGPathCreateMutableCopy (
   CGPathRef path
);

CGPathCreateMutableCopyByTransformingPath

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

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

CGPathCreateWithEllipseInRect

Create an immutable path of an ellipse.

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

CGPathCreateWithRect

Create an immutable path of a rectangle.

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

// 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);

CGPathEqualToPath

Indicates whether two graphics paths are equivalent.

bool CGPathEqualToPath (
   CGPathRef path1,
   CGPathRef path2
);

CGPathGetBoundingBox

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

CGRect CGPathGetBoundingBox (
   CGPathRef path
);

CGPathGetCurrentPoint

Returns the current point in a graphics path.

CGPoint CGPathGetCurrentPoint (
   CGPathRef path
);

CGPathGetPathBoundingBox

Returns the bounding box of a graphics path.

CGRect CGPathGetPathBoundingBox (
   CGPathRef path
);

CGPathGetTypeID

Returns the Core Foundation type identifier for Quartz graphics paths.

CFTypeID CGPathGetTypeID (
   void
);

CGPathIsEmpty

Indicates whether or not a graphics path is empty.

bool CGPathIsEmpty (
   CGPathRef path
);

CGPathIsRect

Indicates whether or not a graphics path represents a rectangle.

bool CGPathIsRect (
   CGPathRef path,
   CGRect *rect
);

CGPathMoveToPoint

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

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

CGPathRelease

Decrements the retain count of a graphics path.

void CGPathRelease (
   CGPathRef path
);

CGPathRetain

Increments the retain count of a graphics path.

CGPathRef CGPathRetain (
   CGPathRef path
);

Callbacks

CGPathApplierFunction

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

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

If you name your function MyCGPathApplierFunc, you would declare it like this:

void MyCGPathApplierFunc (
   void *info,
   const CGPathElement *element
);

Data Types

CGPathRef

An opaque type that represents an immutable graphics path.

   
typedef const struct CGPath *CGPathRef;

CGMutablePathRef

An opaque type that represents a mutable graphics path.

   
typedef struct CGPath *CGMutablePathRef;

CGPathElement

A data structure that provides information about a path element.

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.

Constants

CGPathDrawingMode

Options for rendering a path.

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

Constants

kCGPathFill

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

Available in OS X v10.0 and later.

Declared in CGContext.h.

kCGPathEOFill

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

Available in OS X v10.0 and later.

Declared in CGContext.h.

kCGPathStroke

Render a line along the path.

Available in OS X v10.0 and later.

Declared in CGContext.h.

kCGPathFillStroke

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

Available in OS X v10.0 and later.

Declared in CGContext.h.

kCGPathEOFillStroke

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

Available in OS X v10.0 and later.

Declared in CGContext.h.

CGPathElementType

The type of element found in a path.

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

Constants

kCGPathElementMoveToPoint

The path element that starts a new subpath. See the function CGPathMoveToPoint.

Available in OS X v10.2 and later.

Declared in CGPath.h.

kCGPathElementAddLineToPoint

The path element that adds a line from the current point to the specified point. See the function CGPathAddLineToPoint.

Available in OS X v10.2 and later.

Declared in CGPath.h.

kCGPathElementAddQuadCurveToPoint

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

Available in OS X v10.2 and later.

Declared in CGPath.h.

kCGPathElementAddCurveToPoint

The path element that adds a cubic curve from the current point to the specified point. See the function CGPathAddCurveToPoint.

Available in OS X v10.2 and later.

Declared in CGPath.h.

kCGPathElementCloseSubpath

The path element that closes and completes a subpath. See the function CGPathCloseSubpath.

Available in OS X v10.2 and later.

Declared in CGPath.h.

CGLineCap

Styles for rendering the endpoint of a stroked line.

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

Constants

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 OS X v10.0 and later.

Declared in CGPath.h.

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 OS X v10.0 and later.

Declared in CGPath.h.

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 OS X v10.0 and later.

Declared in CGPath.h.

CGLineJoin

Junction types for stroked lines.

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

Constants

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 OS X v10.0 and later.

Declared in CGPath.h.

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 OS X v10.0 and later.

Declared in CGPath.h.

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 OS X v10.0 and later.

Declared in CGPath.h.