CGPath Reference

Derived from
Framework
ApplicationServices/ApplicationServices.h
Companion guide
Declared in
CGContext.h
CGPath.h

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

Modifying Quartz Paths

Getting Information about Quartz Paths

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

Availability
  • Available in OS X v10.2 and later.
Declared In
CGPath.h

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

Availability
  • Available in OS X v10.2 and later.
Declared In
CGPath.h

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

Availability
  • Available in OS X v10.2 and later.
Declared In
CGPath.h

CGPathAddEllipseInRect

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

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.

Availability
  • Available in OS X v10.4 and later.
Related Sample Code
Declared In
CGPath.h

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
);
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);
}
Availability
  • Available in OS X v10.2 and later.
Declared In
CGPath.h

CGPathAddLineToPoint

Appends a line segment to a mutable graphics path.

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).

Availability
  • Available in OS X v10.2 and later.
Declared In
CGPath.h

CGPathAddPath

Appends a path to onto a mutable graphics path.

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
CGPath.h

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

Availability
  • Available in OS X v10.2 and later.
Declared In
CGPath.h

CGPathAddRect

Appends a rectangle to a mutable graphics path.

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);
Availability
  • Available in OS X v10.2 and later.
Declared In
CGPath.h

CGPathAddRects

Appends an array of rectangles to a mutable graphics path.

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]);
}
Availability
  • Available in OS X v10.2 and later.
Declared In
CGPath.h

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

Availability
  • Available in OS X v10.7 and later.
Declared In
CGPath.h

CGPathAddRoundedRect

Appends a rounded rectangle to a mutable graphics path.

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.

Availability
  • Available in OS X v10.9 and later.
Declared In
CGPath.h

CGPathApply

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

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
CGPath.h

CGPathCloseSubpath

Closes and completes a subpath in a mutable graphics path.

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
CGPath.h

CGPathContainsPoint

Checks whether a point is contained in a graphics path.

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.

Availability
  • Available in OS X v10.4 and later.
Declared In
CGPath.h

CGPathCreateCopy

Creates an immutable copy of a graphics path.

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
CGPath.h

CGPathCreateCopyByDashingPath

Creates a dashed copy of another path.

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.

Availability
  • Available in OS X v10.7 and later.
Declared In
CGPath.h

CGPathCreateCopyByStrokingPath

Creates a stroked copy of another path.

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.

Availability
  • Available in OS X v10.7 and later.
Declared In
CGPath.h

CGPathCreateCopyByTransformingPath

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

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.

Availability
  • Available in OS X v10.7 and later.
Declared In
CGPath.h

CGPathCreateMutable

Creates a mutable graphics path.

CGMutablePathRef CGPathCreateMutable (
   void
);
Return Value

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

Availability
  • Available in OS X v10.2 and later.
Declared In
CGPath.h

CGPathCreateMutableCopy

Creates a mutable copy of an existing graphics path.

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
CGPath.h

CGPathCreateMutableCopyByTransformingPath

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

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.

Availability
  • Available in OS X v10.7 and later.
Declared In
CGPath.h

CGPathCreateWithEllipseInRect

Create an immutable path of an ellipse.

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.

Availability
  • Available in OS X v10.7 and later.
Declared In
CGPath.h

CGPathCreateWithRect

Create an immutable path of a rectangle.

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);
Availability
  • Available in OS X v10.5 and later.
Related Sample Code
Declared In
CGPath.h

CGPathCreateWithRoundedRect

Create an immutable path of a rounded rectangle.

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.

Availability
  • Available in OS X v10.9 and later.
Declared In
CGPath.h

CGPathEqualToPath

Indicates whether two graphics paths are equivalent.

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
CGPath.h

CGPathGetBoundingBox

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

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
CGPath.h

CGPathGetCurrentPoint

Returns the current point in a graphics path.

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
CGPath.h

CGPathGetPathBoundingBox

Returns the bounding box of a graphics path.

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.

Availability
  • Available in OS X v10.6 and later.
Declared In
CGPath.h

CGPathGetTypeID

Returns the Core Foundation type identifier for Quartz graphics paths.

CFTypeID CGPathGetTypeID (
   void
);
Return Value

The Core Foundation identifier for the opaque type CGPathRef.

Availability
  • Available in OS X v10.2 and later.
Declared In
CGPath.h

CGPathIsEmpty

Indicates whether or not a graphics path is empty.

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
CGPath.h

CGPathIsRect

Indicates whether or not a graphics path represents a rectangle.

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
CGPath.h

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

Availability
  • Available in OS X v10.2 and later.
Declared In
CGPath.h

CGPathRelease

Decrements the retain count of a graphics path.

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
CGPath.h

CGPathRetain

Increments the retain count of a graphics path.

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
CGPath.h

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

Discussion

See also CGPathApply.

Availability
  • Available in OS X v10.2 and later.
Declared In
CGPath.h

Data Types

CGPathRef

An opaque type that represents an immutable graphics path.

   
typedef const struct CGPath *CGPathRef;
Availability
  • Available in OS X v10.2 and later.
Declared In
CGPath.h

CGMutablePathRef

An opaque type that represents a mutable graphics path.

   
typedef struct CGPath *CGMutablePathRef;
Availability
  • Available in OS X v10.2 and later.
Declared In
CGPath.h

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.

Availability
  • Available in OS X v10.2 and later.
Declared In
CGPath.h

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.

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.

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. The element holds a single point for the destination. 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 a new point. The element holds a single point for the destination. 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. The element holds a control point and a destination 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. The element holds two control points and a destination 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. The element does not contain any points. See the function CGPathCloseSubpath.

Available in OS X v10.2 and later.

Declared in CGPath.h.

Discussion

For more information about paths, see CGPathRef.

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.

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.

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.

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.