Apple Developer Connection
Member Login Log In | Not a Member? Contact ADC

Next Page > Hide TOC

CGContext Reference

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

Overview

The CGContextRef opaque type represents a Quartz 2D drawing destination. A graphics context contains drawing parameters and all device-specific information needed to render the paint on a page to the destination, whether the destination is a window in an application, a bitmap image, a PDF document, or a printer. You can obtain a graphics context by using Quartz graphics context creation functions or by using higher-level functions provided in the Carbon, Cocoa, or Printing frameworks. Quartz provides creation functions for various flavors of Quartz graphics contexts including bitmap images and PDF. The Carbon and Cocoa frameworks provide functions for obtaining window graphics contexts. The Printing framework provides functions that obtain a graphics context appropriate for the destination printer.

Functions by Task

Managing Graphics Contexts

Saving and Restoring the Current Graphics State

Getting and Setting Graphics State Parameters

Constructing Paths

These functions are used to define the geometry of the current path.

Painting Paths

These functions are used to stroke along or fill in the current path.

Getting Information About Paths

Modifying Clipping Paths

Setting Color, Color Space, and Shadow Values

Transforming User Space

These functions allow you to examine and change the current transformation matrix (CTM) in a graphics context.

Using Transparency Layers

Drawing an Image to a Graphics Context

Drawing PDF Content to a Graphics Context

Drawing With a Gradient

Drawing With a Shading

Setting Up a Page-Based Graphics Context

Drawing Glyphs

Drawing Text

Converting Between Device Space and User Space

Functions

CGContextAddArc

Adds an arc of a circle to the current path, using a center point, radius, and end point.

void CGContextAddArc (
   CGContextRef c,
   CGFloat x,
   CGFloat y,
   CGFloat radius,
   CGFloat startAngle,
   CGFloat endAngle,
   int clockwise
);

Parameters
context

A graphics context.

x

The x-value, in user space coordinates, for the center of the arc.

y

The y-value, in user space coordinates, for the center of the arc.

radius

The radius of the arc, in user space coordinates.

startAngle

The angle to the starting point of the arc, measured in radians from the positive x-axis.

endAngle

The angle to the end point of the arc, measured in radians from the positive x-axis.

clockwise

Pass 1 to draw the arc clockwise; 0 otherwise.

Discussion

When you call this function, Quartz builds an arc of a circle centered on the point you provide. The arc is of the specified radius and extends between the start and end point. (You can also use CGContextAddArc as a convenient way to draw a circle, by setting the start point to 0 and the end point to 2*Pi.)

If the current path already contains a subpath, Quartz additionally appends a straight line segment from the current point to the starting point of the arc. If the current path is empty, Quartz creates a new subpath for the arc and does not add the initial straight line segment.

After adding the arc, the current point is reset to the end point of arc (the second tangent point).

Availability
See Also
Declared In
CGContext.h

CGContextAddArcToPoint

Adds an arc of a circle to the current path, using a radius and tangent points.

void CGContextAddArcToPoint (
   CGContextRef c,
   CGFloat x1,
   CGFloat y1,
   CGFloat x2,
   CGFloat y2,
   CGFloat radius
);

Parameters
context

A graphics context whose current path is not empty.

x1

The x-value, in user space coordinates, 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-value, in user space coordinates, 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-value, in user space coordinates, for the end point of the second tangent line. The second tangent line is drawn from (x1,y1) to (x2,y2).

y2

The y-value, in user space coordinates, 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 draws 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. After adding the arc, the current point is reset to the end point of arc (the second tangent point).

Availability
See Also
Declared In
CGContext.h

CGContextAddCurveToPoint

Appends a cubic Bézier curve from the current point, using the provided control points and end point .

void CGContextAddCurveToPoint (
   CGContextRef c,
   CGFloat cp1x,
   CGFloat cp1y,
   CGFloat cp2x,
   CGFloat cp2y,
   CGFloat x,
   CGFloat y
);

Parameters
context

A graphics context whose current path is not empty.

cp1x

The x-value, in user space coordinates, for the first control point of the curve.

cp1y

The y-value, in user space coordinates, for the first control point of the curve.

cp2x

The x-value, in user space coordinates, for the second control point of the curve.

cp2y

The y-value, in user space coordinates, for the second control point of the curve.

x

The x-value, in user space coordinates, at which to end the curve.

y

The y-value, in user space coordinates, at which to end the curve.

Discussion

This function appends a cubic curve to the current path. After adding the segment, the current point is reset from the beginning of the new segment to the end point of that segment.

Availability
See Also
Declared In
CGContext.h

CGContextAddEllipseInRect

Adds an ellipse that fits inside the specified rectangle.

void CGContextAddEllipseInRect (
   CGContextRef context,
   CGRect rect
);

Parameters
context

A graphics context.

rect

A rectangle that defines the area for the ellipse to fit in.

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.

Availability
Declared In
CGContext.h

CGContextAddLines

Adds a sequence of connected straight-line segments to the current path.

void CGContextAddLines (
   CGContextRef c,
   const CGPoint points[],
   size_t count
);

Parameters
context

A graphics context .

points

An array of values that specify the start and end points of the line segments to draw. Each point in the array specifies a position in user space. The first point is the array specifies the initial starting point.

count

The number of elements in the points array.

Discussion

This is a convenience function that adds a sequence of connected line segments to the current path in a graphics context. Quartz connects each point in the array with the subsequent point in the array, using straight line segments.

On return, the current point is the last point in the array. This function does not automatically close the path created by the line segments. If you want to close the path, you must call CGContextClosePath.

Availability
See Also
Declared In
CGContext.h

CGContextAddLineToPoint

Appends a straight line segment from the current point to the provided point .

void CGContextAddLineToPoint (
   CGContextRef c,
   CGFloat x,
   CGFloat y
);

Parameters
context

A graphics context whose current path is not empty.

x

The x-value, in user space coordinates, for the end of the line segment.

y

The y-value, in user space coordinates, for the end of the line segment.

Discussion

After adding the line segment, the current point is reset from the beginning of the new line segment to the endpoint of that line segment.

Availability
See Also
Declared In
CGContext.h

CGContextAddPath

Adds a previously created Quartz path object to the current path in a graphics context.

void CGContextAddPath (
   CGContextRef context,
   CGPathRef path
);

Parameters
context

A graphics context .

path

A previously created Quartz path object. See CGPath Reference.

Discussion

Quartz applies the current transformation matrix (CTM) to the points in the new path before they are added to the current path in the graphics context.

Availability
Declared In
CGContext.h

CGContextAddQuadCurveToPoint

Appends a quadratic Bézier curve from the current point, using a control point and an end point you specify.

void CGContextAddQuadCurveToPoint (
   CGContextRef c,
   CGFloat cpx,
   CGFloat cpy,
   CGFloat x,
   CGFloat y
);

Parameters
context

A graphics context whose current path is not empty.

cpx

The x-coordinate of the user space for the control point of the curve.

cpy

The y-coordinate of the user space for the control point of the curve.

x

The x-coordinate of the user space at which to end the curve.

y

The y-coordinate of the user space at which to end the curve.

Discussion

This function appends a quadratic curve to the current subpath. After adding the segment, the current point is reset from the beginning of the new segment to the end point of that segment.

Availability
See Also
Declared In
CGContext.h

CGContextAddRect

Adds a rectangular path to the current path.

void CGContextAddRect (
   CGContextRef c,
   CGRect rect
);

Parameters
context

A graphics context.

rect

A rectangle, specified in user space coordinates.

Availability
See Also
Declared In
CGContext.h

CGContextAddRects

Adds a set rectangular paths to the current path.

void CGContextAddRects (
   CGContextRef c,
   const CGRect rects[],
   size_t count
);

Parameters
context

A graphics context.

rects

An array of rectangles, specified in user space coordinates.

count

The number of rectangles in the rects array.

Availability
See Also
Declared In
CGContext.h

CGContextBeginPage

Starts a new page in a page-based graphics context.

void CGContextBeginPage (
   CGContextRef c,
   const CGRect *mediaBox
);

Parameters
context

A page-based graphics context such as a PDF context. If you specify a context that does not support multiple pages, this function does nothing.

mediaBox

A Quartz rectangle defining the bounds of the new page, expressed in units of the default user space, or NULL. These bounds supersede any supplied for the media box when you created the context. If you pass NULL, Quartz uses the rectangle you supplied for the media box when the graphics context was created.

Discussion

When using a graphics context that supports multiple pages, you should call this function together with CGContextEndPage to delineate the page boundaries in the output. In other words, each page should be bracketed by calls to CGContextBeginPage and CGContextEndPage. Quartz ignores all drawing operations performed outside a page boundary in a page-based context.

Availability
Declared In
CGContext.h

CGContextBeginPath

Creates a new empty path in a graphics context.

void CGContextBeginPath (
   CGContextRef c
);

Parameters
context

A graphics context.

Discussion

A graphics context can have only a single path in use at any time. If the specified context already contains a current path when you call this function, Quartz replaces the previous current path with the new path. In this case, Quartz discards the old path and any data associated with it.

The current path is not part of the graphics state. Consequently, saving and restoring the graphics state has no effect on the current path.

Availability
See Also
Declared In
CGContext.h

CGContextBeginTransparencyLayer

Begins a transparency layer.

void CGContextBeginTransparencyLayer (
   CGContextRef context,
   CFDictionaryRef auxiliaryInfo
);

Parameters
context

A graphics context.

auxiliaryInfo

A dictionary that specifies any additional information, or NULL.

Discussion

Until a corresponding call to CGContextEndTransparencyLayer, all subsequent drawing operations in the specified context are composited into a fully transparent backdrop (which is treated as a separate destination buffer from the context).

After a call to CGContextEndTransparencyLayer, the result is composited into the context using the global alpha and shadow state of the context. This operation respects the clipping region of the context.

After a call to this function, all of the parameters in the graphics state remain unchanged with the exception of the following:

Ending the transparency layer restores these parameters to their previous values. Quartz maintains a transparency layer stack for each context, and transparency layers may be nested.

Tip: For best performance, make sure that you set the smallest possible clipping area for the objects in the transparency layer prior to calling CGContextBeginTransparencyLayer.

Availability
Declared In
CGContext.h

CGContextBeginTransparencyLayerWithRect

Begins a transparency layer whose contents are bounded by the specified rectangle.

void CGContextBeginTransparencyLayerWithRect(CGContextRef context, CGRect rect, CFDictionaryRef auxiliaryInfo);

Parameters
context

A graphics context.

rect

The rectangle, specified in user space, that bounds the transparency layer.

auxiliaryInfo

A dictionary that specifies any additional information, or NULL.

Discussion

This function is identical to CGContextBeginTransparencyLayer except that the content of the transparency layer is within the bounds of the provided rectangle.

Availability
Declared In
CGContext.h

CGContextClearRect

Paints a transparent rectangle.

void CGContextClearRect (
   CGContextRef c,
   CGRect rect
);

Parameters
context

The graphics context in which to paint the rectangle.

rect

The rectangle, in user space coordinates.

Discussion

If the provided context is a window or bitmap context, Quartz effectively clears the rectangle. For other context types, Quartz fills the rectangle in a device-dependent manner. However, you should not use this function in contexts other than window or bitmap contexts.

Availability
Declared In
CGContext.h

CGContextClip

Modifies the current clipping path, using the nonzero winding number rule.

void CGContextClip (
   CGContextRef c
);

Parameters
context

A graphics context that contains a path. If the context does not have a current path, the function does nothing.

Discussion

The function uses the nonzero winding number rule to calculate the intersection of the current path with the current clipping path. Quartz then uses the path resulting from the intersection as the new current clipping path for subsequent painting operations.

Unlike the current path, the current clipping path is part of the graphics state. Therefore, to re-enlarge the paintable area by restoring the clipping path to a prior state, you must save the graphics state before you clip and restore the graphics state after you’ve completed any clipped drawing.

After determining the new clipping path, the function resets the context’s current path to an empty path.

See alsoCGContextEOClip

Availability
Declared In
CGContext.h

CGContextClipToMask

Maps a mask into the specified rectangle and intersects it with the current clipping area of the graphics context.

void CGContextClipToMask (
   CGContextRef c,
   CGRect rect,
   CGImageRef mask
);

Parameters
c

A graphics context.

rect

The rectangle to map the mask parameter to.

mask

An image or an image mask. If mask is an image, then it must be in the DeviceGray color space, may not have an alpha component, and may not be masked by an image mask or masking color.

Discussion

If the mask parameter is an image mask, then Quartz clips in a manner identical to the behavior seen with the function CGContextDrawImage—the mask indicates an area to be left unchanged when drawing. The source samples of the image mask determine which points of the clipping area are changed, acting as an "inverse alpha" value. If the value of a source sample in the image mask is S, then the corresponding point in the current clipping area is multiplied by an alpha value of (1–S). For example, if S is 1 then the point in the clipping area becomes transparent. If S is 0, the point in the clipping area is unchanged.

If the mask parameter is an image, then mask acts like an alpha mask and is blended with the current clipping area. The source samples of mask determine which points of the clipping area are changed. If the value of the source sample in mask is S, then the corresponding point in the current clipping area is multiplied by an alpha of S. For example, if S is 0, then the point in the clipping area becomes transparent. If S is 1, the point in the clipping area is unchanged.

Availability
Declared In
CGContext.h

CGContextClipToRect

Sets the clipping path to the intersection of the current clipping path with the area defined by the specified rectangle.

void CGContextClipToRect (
   CGContextRef c,
   CGRect rect
);

Parameters
context

The graphics context for which to set the clipping path.

rect

A CGRect value that specifies, in the user space, the location and dimensions of the rectangle to be used in determining the new clipping path.

Discussion

This function sets the specified graphics context’s clipping region to the area which intersects both the current clipping path and the specified rectangle.

After determining the new clipping path, the CGContextClipToRect function resets the context’s current path to an empty path.

See also CGContextClipToRects.

Availability
Declared In
CGContext.h

CGContextClipToRects

Sets the clipping path to the intersection of the current clipping path with the region defined by an array of rectangles.

void CGContextClipToRects (
   CGContextRef c,
   const CGRect rects[],
   size_t count
);

Parameters
context

The graphics context for which to set the clipping path.

rects

An array of rectangles. The locations and dimensions of the rectangles are specified in the user space coordinate system.

count

The total number of array entries in the rects parameter.

Discussion

This function sets the clipping path to the intersection of the current clipping path and the region within the specified rectangles.

After determining the new clipping path, the function resets the context’s current path to an empty path.

See also CGContextClipToRect.

Availability
Declared In
CGContext.h

CGContextClosePath

Closes and terminates an open path.

void CGContextClosePath (
   CGContextRef c
);

Parameters
context

A graphics context.

Discussion

If a path is open, this function closes and terminate the path. Quartz closes a path by drawing a straight line that connects the current point to the starting point. If the current point and the starting point are the same, you must still call this function to close the path. After Quartz terminates the path, the current point is no longer defined. If there is no open path, this function does nothing.

When you fill or clip an open path, Quartz implicitly closes the subpath for you.

Availability
See Also
Declared In
CGContext.h

CGContextConcatCTM

Transforms the user coordinate system in a context using a specified matrix.

void CGContextConcatCTM (
   CGContextRef c,
   CGAffineTransform transform
);

Parameters
context

A graphics context.

transform

The transformation matrix to apply to the specified context’s current transformation matrix.

Discussion

When you call the function CGContextConcatCTM, it concatenates (that is, it combines) two matrices, by multiplying them together. The order in which matrices are concatenated is important, as the operations are not commutative. When you call CGContextConcatCTM, the resulting CTM in the context is: CTMnew = transform * CTMcontext.

Availability
Declared In
CGContext.h

CGContextConvertPointToDeviceSpace

Returns a point that is transformed from user space coordinates to device space coordinates.

CGPoint CGContextConvertPointToDeviceSpace (
   CGContextRef c,
   CGPoint point
);

Parameters
c

A graphics context.

point

The point, in user space coordinates, to transform.

Return Value

The coordinates of the point in device space coordinates.

Availability
See Also
Declared In
CGContext.h

CGContextConvertPointToUserSpace

Returns a point that is transformed from device space coordinates to user space coordinates.

CGPoint CGContextConvertPointToUserSpace (
   CGContextRef c,
   CGPoint point
);

Parameters
c

A graphics context.

point

The point, in device space coordinates, to transform.

Return Value

The coordinates of the point in user space coordinates.

Availability
See Also
Declared In
CGContext.h

CGContextConvertRectToDeviceSpace

Returns a rectangle that is transformed from user space coordinate to device space coordinates.

CGRect CGContextConvertRectToDeviceSpace (
   CGContextRef c,
   CGRect rect
);

Parameters
context

A graphics context.

rect

The rectangle, in user space coordinates, to transform.

Return Value

The rectangle in device space coordinates.

Discussion

In general affine transforms do not preserve rectangles. As a result, this function returns the smallest rectangle that contains the transformed corner points of the rectangle.

Availability
See Also
Declared In
CGContext.h

CGContextConvertRectToUserSpace

Returns a rectangle that is transformed from device space coordinate to user space coordinates.

CGRect CGContextConvertRectToUserSpace (
   CGContextRef c,
   CGRect rect
);

Parameters
context

A graphics context.

rect

The rectangle, in device space coordinates, to transform.

Return Value

The rectangle in user space coordinates.

Discussion

In general, affine transforms do not preserve rectangles. As a result, this function returns the smallest rectangle that contains the transformed corner points of the rectangle.

Availability
See Also
Declared In
CGContext.h

CGContextConvertSizeToDeviceSpace

Returns a size that is transformed from user space coordinates to device space coordinates.

CGSize CGContextConvertSizeToDeviceSpace (
   CGContextRef c,
   CGSize size
);

Parameters
c

A graphics context.

size

The size, in user space coordinates, to transform.

Return Value

The size in device space coordinates.

Availability
See Also
Declared In
CGContext.h

CGContextConvertSizeToUserSpace

Returns a size that is transformed from device space coordinates to user space coordinates

CGSize CGContextConvertSizeToUserSpace (
   CGContextRef c,
   CGSize size
);

Parameters
context

A graphics context.

size

The size, in device space coordinates, to transform.

Return Value

The size in user space coordinates.

Availability
See Also
Declared In
CGContext.h

CGContextDrawImage

Draws an image into a graphics context.

void CGContextDrawImage (
   CGContextRef c,
   CGRect rect,
   CGImageRef image
);

Parameters
context

The graphics context in which to draw the image.

rect

The location and dimensions in user space of the bounding box in which to draw the image.

image

The image to draw.

Discussion

Quartz scales the image—disproportionately, if necessary—to fit the bounds specified by the rect parameter.

Availability
Declared In
CGContext.h

CGContextDrawLinearGradient

Paints a gradient fill that varies along the line defined by the provided starting and ending points.

void CGContextDrawLinearGradient(
   CGContextRef context,
   CGGradientRef gradient,
   CGPoint startPoint,
   CGPoint endPoint,
   CGGradientDrawingOptions options
);

Parameters
context

A Quartz graphics context.

gradient

A CGGradient object.

startPoint

The coordinate that defines the starting point of the gradient.

endPoint

The coordinate that defines the ending point of the gradient.

options

Option flags (kCGGradientDrawsBeforeStartLocation or kCGGradientDrawsAfterEndLocation) that control whether the fill is extended beyond the starting or ending point.

Discussion

The color at location 0 in the CGGradient object is mapped to the starting point. The color at location 1 in the CGGradient object is mapped to the ending point. Colors are linearly interpolated between these two points based on the location values of the gradient. The option flags control whether the gradient is drawn before the start point or after the end point.

Availability
Declared In
CGContext.h

CGContextDrawPath

Draws the current path using the provided drawing mode.

void CGContextDrawPath (
   CGContextRef c,
   CGPathDrawingMode mode
);

Parameters
context

A graphics context that contains a path to paint.

mode

A path drawing mode constant—kCGPathFill, kCGPathEOFill, kCGPathStroke, kCGPathFillStroke, or kCGPathEOFillStroke. For a discussion of these constants, see CGPath Reference.

Discussion

This function draws the current path using the specified drawing mode. If the current path contains several disjoint portions (or subpaths), Quartz fills each one independently. Any subpath that you did not explicitly close by calling CGContextClosePath is closed implicitly by the fill routines.

Availability
See Also
Declared In
CGContext.h

CGContextDrawPDFDocument

Draws a page of a PDF document into a graphics context.

void CGContextDrawPDFDocument (
   CGContextRef c,
   CGRect rect,
   CGPDFDocumentRef document,
   int page
);

Parameters
context

The graphics context in which to draw the PDF page.

rect

A CGRect value that specifies the dimensions and location of the area in which to draw the PDF page, in units of the user space. When drawn, Quartz scales the media box of the page to fit the rectangle you specify.

document

The PDF document to draw.

page

A value that specifies the PDF page number to draw. If the specified page does not exist, the function does nothing.

Special Considerations

For applications running in Mac OS X version 10.3 and later, it is recommended that you replace this function with CGContextDrawPDFPage. If you do so, and want to specify the drawing rectangle, you should use CGPDFPageGetDrawingTransform to get an appropriate transform, concatenate it with the current transformation matrix, clip to the rectangle, and then call CGContextDrawPDFPage.

Availability
Declared In
CGContext.h

CGContextDrawPDFPage

Draws a page in the current user space of a PDF context.

void CGContextDrawPDFPage (
   CGContextRef c,
   CGPDFPageRef page
);

Parameters
context

The graphics context in which to draw the PDF page.

page

A Quartz PDF page.

Discussion

This function works in conjunction with the opaque type CGPDFPageRef to draw individual pages into a PDF context.

For applications running in Mac OS X version 10.3 and later, this function is recommended as a replacement for the older function CGContextDrawPDFDocument.

Availability
Declared In
CGContext.h