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 Cocoa framework provides 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. For more information on how paths are defined, see CGPath Reference.

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, possibly preceded by a straight line segment

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

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

Specify 1 to create a clockwise arc or 0 to create a counterclockwise arc.

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 of the final path is dependent on the current transformation matrix of the graphics context. For example, on iOS, a UIView flips the Y-coordinate by scaling the Y values by -1. In a flipped coordinate system, specifying a clockwise arc results in a counterclockwise arc after the transformation is applied.

If the current path already contains a subpath, Quartz adds a line connecting the current point to the starting point of the arc. If the current path is empty, Quartz creates a new 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.0 and later.
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
c

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

Availability
  • Available in OS X v10.0 and later.
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
c

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. On return, the current point is set to the end point of that segment.

Availability
  • Available in OS X v10.0 and later.
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.

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.

Availability
  • Available in OS X v10.4 and later.
Related Sample Code
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
c

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 in 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 a path, using the following operation:

CGContextMoveToPoint (c, points[0].x, points[0].y);
for (k = 1; k < count; k++) {
    CGContextAddLineToPoint (c, points[k].x, points[k].y);
}
Availability
  • Available in OS X v10.0 and later.
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
c

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 set to the endpoint of the line segment.

Availability
  • Available in OS X v10.0 and later.
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

If the source path is non-empty, then its path elements are appended in order onto the current path. Quartz applies the current transformation matrix (CTM) to the points before adding them to the path.

After the call completes, the start point and current point of the path are those of the last subpath in path.

Availability
  • Available in OS X v10.2 and later.
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
c

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 set to the end point of the curve.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGContext.h

CGContextAddRect

Adds a rectangular path to the current path.

void CGContextAddRect (
   CGContextRef c,
   CGRect rect
);
Parameters
c

A graphics context.

rect

A rectangle, specified in user space coordinates.

Discussion

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

// start at origin
CGContextMoveToPoint (c, CGRectGetMinX(rect), CGRectGetMinY(rect));
 
// add bottom edge
CGContextAddLineToPoint (c, CGRectGetMaxX(rect), CGRectGetMinY(rect));
 
// add right edge
CGContextAddLineToPoint (c, CGRectGetMaxX(rect), CGRectGetMaxY(rect);
 
// add top edge
CGContextAddLineToPoint (c, CGRectGetMinX(rect), CGRectGetMaxY(rect));
 
// add left edge and close
CGContextClosePath (c);
Availability
  • Available in OS X v10.0 and later.
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
c

A graphics context.

rects

An array of rectangles, specified in user space coordinates.

count

The number of rectangles in the rects 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++) {
    CGContextAddRect (c, m, rects[k]);
}
Availability
  • Available in OS X v10.0 and later.
Declared In
CGContext.h

CGContextBeginPage

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

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

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
  • Available in OS X v10.0 and later.
Declared In
CGContext.h

CGContextBeginPath

Creates a new empty path in a graphics context.

void CGContextBeginPath (
   CGContextRef c
);
Parameters
c

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 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
  • Available in OS X v10.0 and later.
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:

  • The global alpha is set to 1.

  • The shadow is turned off.

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.

Availability
  • Available in OS X v10.3 and later.
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
  • Available in OS X v10.5 and later.
Declared In
CGContext.h

CGContextClearRect

Paints a transparent rectangle.

void CGContextClearRect (
   CGContextRef c,
   CGRect rect
);
Parameters
c

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
  • Available in OS X v10.0 and later.
Declared In
CGContext.h

CGContextClip

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

void CGContextClip (
   CGContextRef c
);
Parameters
c

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.

If the current path includes any open subpaths, Quartz treats them as if they were closed by calling CGContextClosePath.

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.

Availability
  • Available in OS X v10.0 and later.
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
  • Available in OS X v10.4 and later.
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
c

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.

Availability
  • Available in OS X v10.0 and later.
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
c

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.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGContext.h

CGContextClosePath

Closes and terminates the current path’s subpath.

void CGContextClosePath (
   CGContextRef c
);
Parameters
c

A graphics context.

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 CGContextMoveToPoint. In this case, a new subpath is implicitly created with a starting and current point equal to the previous subpath’s starting point.

If the current path is empty or the current subpath is already closed, this function does nothing.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGContext.h

CGContextConcatCTM

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

void CGContextConcatCTM (
   CGContextRef c,
   CGAffineTransform transform
);
Parameters
c

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
  • Available in OS X v10.0 and later.
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
  • Available in OS X v10.4 and later.
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
  • Available in OS X v10.4 and later.
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
c

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
  • Available in OS X v10.4 and later.
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
c

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
  • Available in OS X v10.4 and later.
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
  • Available in OS X v10.4 and later.
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
c

A graphics context.

size

The size, in device space coordinates, to transform.

Return Value

The size in user space coordinates.

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

CGContextCopyPath

Returns a Quartz path object built from the current path information in a graphics context.

CGPathRef CGContextCopyPath(
   CGContextRef context
);
Parameters
context

A graphics context whose current path is not empty.

Return Value

A Quartz path object containing the current path data.

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

CGContextDrawImage

Draws an image into a graphics context.

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

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

CGContextDrawPath

Draws the current path using the provided drawing mode.

void CGContextDrawPath (
   CGContextRef c,
   CGPathDrawingMode mode
);
Parameters
c

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

As a side effect when you call this function, Quartz clears the current path.

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

CGContextDrawPDFPage

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

void CGContextDrawPDFPage (
   CGContextRef c,
   CGPDFPageRef page
);
Parameters
c

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.

Availability
  • Available in OS X v10.3 and later.
Declared In
CGContext.h

CGContextDrawRadialGradient

Paints a gradient fill that varies along the area defined by the provided starting and ending circles.

void CGContextDrawRadialGradient(
   CGContextRef context,
   CGGradientRef gradient,
   CGPoint startCenter,
   CGFloat startRadius,
   CGPoint endCenter,
   CGFloat endRadius,
   CGGradientDrawingOptions options
);
Parameters
context

A Quartz graphics context.

gradient

A CGGradient object.

startCenter

The coordinate that defines the center of the starting circle.

startRadius

The radius of the starting circle.

endCenter

The coordinate that defines the center of the ending circle.

endRadius

The radius of the ending circle.

options

Option flags (kCGGradientDrawsBeforeStartLocation or kCGGradientDrawsAfterEndLocation) that control whether the gradient is drawn before the starting circle or after the ending circle.

Discussion

The color at location 0 in the CGGradient object is mapped to the circle defined by startCenter and startRadius. The color at location 1 in the CGGradient object is mapped to the circle defined by endCenter and endRadius. Colors are linearly interpolated between the starting and ending circles 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
  • Available in OS X v10.5 and later.
Related Sample Code
Declared In
CGContext.h

CGContextDrawShading

Fills the clipping path of a context with the specified shading.

void CGContextDrawShading (
   CGContextRef c,
   CGShadingRef shading
);
Parameters
c

The graphics context in which to draw the shading.

shading

A Quartz shading. Quartz retains this object; upon return, you may safely release it.

Discussion

In OS X v10.5 and later, the preferred way to draw gradients is to use a CGGradient object. See CGGradient Reference.

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

CGContextDrawTiledImage

Repeatedly draws an image, scaled to the provided rectangle, to fill the current clip region.

void CGContextDrawTiledImage(
   CGContextRef context,
   CGRect rect,
   CGImageRef image
);
Parameters
context

The graphics context in which to draw the image.

rect

A rectangle that specifies the origin and size of the destination tile. Quartz scales the image—disproportionately, if necessary—to fit the bounds specified by the rect parameter.

image

The image to draw.

Discussion

Quartz draws the scaled image starting at the origin of the rectangle in user space, then moves to a new point (horizontally by the width of the tile and/or vertically by the height of the tile), draws the scaled image, moves again, draws again, and so on, until the current clip region is tiled with copies of the image. Unlike patterns, the image is tiled in user space, so transformations applied to the CTM affect the final result.

Availability
  • Available in OS X v10.5 and later.
Declared In
CGContext.h

CGContextEndPage

Ends the current page in a page-based graphics context.

void CGContextEndPage (
   CGContextRef c
);
Parameters
c

A page-based graphics context.

Discussion

When using a graphics context that supports multiple pages, you should call this function to terminate drawing in the current page.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGContext.h

CGContextEndTransparencyLayer

Ends a transparency layer.

void CGContextEndTransparencyLayer (
   CGContextRef context
);
Parameters
context

A graphics context.

Availability
  • Available in OS X v10.3 and later.
Declared In
CGContext.h

CGContextEOClip

Modifies the current clipping path, using the even-odd rule.

void CGContextEOClip (
   CGContextRef c
);
Parameters
c

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

Discussion

The function uses the even-odd 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.

If the current path includes any open subpaths, Quartz treats them as if they were closed by calling CGContextClosePath.

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.

Availability
  • Available in OS X v10.0 and later.
See Also
Related Sample Code
Declared In
CGContext.h

CGContextEOFillPath

Paints the area within the current path, using the even-odd fill rule.

void CGContextEOFillPath (
   CGContextRef c
);
Parameters
c

A graphics context that contains a path to fill.

Discussion

Quartz treats each subpath as if it were closed by calling CGContextClosePath. The even-odd rule is described in “Filling a Path” in Quartz 2D Programming Guide. As a side effect when you call this function, Quartz clears the current path.

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

CGContextFillEllipseInRect

Paints the area of the ellipse that fits inside the provided rectangle, using the fill color in the current graphics state.

void CGContextFillEllipseInRect (
   CGContextRef context,
   CGRect rect
);
Parameters
context

A graphics context.

rect

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

Discussion

As a side effect when you call this function, Quartz clears the current path.

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

CGContextFillPath

Paints the area within the current path, using the nonzero winding number rule.

void CGContextFillPath (
   CGContextRef c
);
Parameters
c

A graphics context that contains a path to fill.

Discussion

Quartz treats each subpath as if it were closed by calling CGContextClosePath. The nonzero winding number rule is described in “Filling a Path” in Quartz 2D Programming Guide. As a side effect when you call this function, Quartz clears the current path.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGContext.h

CGContextFillRect

Paints the area contained within the provided rectangle, using the fill color in the current graphics state.

void CGContextFillRect (
   CGContextRef c,
   CGRect rect
);
Parameters
c

A graphics context.

rect

A rectangle, in user space coordinates.

Discussion

As a side effect when you call this function, Quartz clears the current path.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGContext.h

CGContextFillRects

Paints the areas contained within the provided rectangles, using the fill color in the current graphics state.

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

A graphics context .

rects

An array of rectangles, in user space coordinates.

count

The number rectangles in the rects array.

Discussion

As a side effect when you call this function, Quartz clears the current path.

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

CGContextFlush

Forces all pending drawing operations in a window context to be rendered immediately to the destination device.

void CGContextFlush (
   CGContextRef c
);
Parameters
c

The window context to flush. If you pass a PDF context or a bitmap context, this function does nothing.

Discussion

When you call this function, Quartz immediately flushes the current drawing to the destination device (for example, a screen). Because the system software flushes a context automatically at the appropriate times, calling this function could have an adverse effect on performance. Under normal conditions, you do not need to call this function.

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

CGContextGetClipBoundingBox

Returns the bounding box of a clipping path.

CGRect CGContextGetClipBoundingBox (
   CGContextRef c
);
Parameters
c

The graphics context to modify.

Return Value

The bounding box of the clipping path, specified in user space.

Discussion

The bounding box is the smallest rectangle completely enclosing all points in the clipping path, including control points for any Bezier curves in the path.

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

CGContextGetCTM

Returns the current transformation matrix.

CGAffineTransform CGContextGetCTM (
   CGContextRef c
);
Parameters
c

A graphics context.

Return Value

The transformation matrix for the current graphics state of the specified context.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGContext.h

CGContextGetInterpolationQuality

Returns the current level of interpolation quality for a graphics context.

CGInterpolationQuality CGContextGetInterpolationQuality (
   CGContextRef c
);
Parameters
c

The graphics context to examine.

Return Value

The current level of interpolation quality.

Discussion

Interpolation quality is a graphics state parameter that provides a hint for the level of quality to use for image interpolation (for example, when scaling the image). Not all contexts support all interpolation quality levels.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGContext.h

CGContextGetPathBoundingBox

Returns the smallest rectangle that contains the current path.

CGRect CGContextGetPathBoundingBox (
   CGContextRef c
);
Parameters
c

The graphics context, containing a path, to examine.

Return Value

A CGRect value that specifies the dimensions and location, in user space, of the bounding box of the path. If there is no path, the function returns CGRectNull.

Discussion

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

Availability
  • Available in OS X v10.0 and later.
Declared In
CGContext.h

CGContextGetPathCurrentPoint

Returns the current point in a non-empty path.

CGPoint CGContextGetPathCurrentPoint (
   CGContextRef c
);
Parameters
c

The graphics context containing the path to examine.

Return Value

A CGPoint value that specifies the location, in user space, of current point in the context’s path. If there is no path, the function returns CGPointZero.

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

CGContextGetTextMatrix

Returns the current text matrix.

CGAffineTransform CGContextGetTextMatrix (
   CGContextRef c
);
Parameters
c

The graphics context for which to obtain the text matrix.

Return Value

The current text matrix.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGContext.h

CGContextGetTextPosition

Returns the location at which text is drawn.

CGPoint CGContextGetTextPosition (
   CGContextRef c
);
Parameters
c

The graphics context from which to obtain the current text position.

Return Value

Returns a CGPoint value that specifies the x and y values at which text is to be drawn, in user space coordinates.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGContext.h

CGContextGetTypeID

Returns the type identifier for Quartz graphics contexts.

CFTypeID CGContextGetTypeID (
   void
);
Return Value

The identifier for the opaque type CGContextRef.

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

CGContextGetUserSpaceToDeviceSpaceTransform

Returns an affine transform that maps user space coordinates to device space coordinates.

CGAffineTransform CGContextGetUserSpaceToDeviceSpaceTransform (
   CGContextRef c
);
Parameters
c

A graphics context.

Return Value

The affine transforms that maps the user space of the graphics context to the device space.

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

CGContextIsPathEmpty

Indicates whether the current path contains any subpaths.

bool CGContextIsPathEmpty (
   CGContextRef c
);
Parameters
c

The graphics context containing the path to examine.

Return Value

Returns 1 if the context’s path contains no subpaths, otherwise returns 0.

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

CGContextMoveToPoint

Begins a new subpath at the point you specify.

void CGContextMoveToPoint (
   CGContextRef c,
   CGFloat x,
   CGFloat y
);
Parameters
c

A graphics context.

x

The x-value, in user space coordinates, for the point.

y

The y-value, in user space coordinates, for the point.

Discussion

This point you specify becomes the start point of a new subpath. The current point is set to this start point.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGContext.h

CGContextPathContainsPoint

Checks to see whether the specified point is contained in the current path.

bool CGContextPathContainsPoint (
   CGContextRef context,
   CGPoint point,
   CGPathDrawingMode mode
);
Parameters
context

A graphics context.

point

The point to check, specified in user space units.

mode

A path drawing mode—kCGPathFill, kCGPathEOFill, kCGPathStroke, kCGPathFillStroke, or kCGPathEOFillStroke. See CGPath Reference.

Return Value

Returns true if point is inside the current path of the graphics context; false otherwise.

Discussion

A point is contained within the path of a graphics context if the point is inside the painted region when the path is stroked or filled with opaque colors using the specified path drawing mode. A point can be inside a path only if the path is explicitly closed by calling the function CGContextClosePath, for paths drawn directly to the current context, or CGPathCloseSubpath, for paths first created as CGPath objects and then drawn to the current context.

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

CGContextRelease

Decrements the retain count of a graphics context.

void CGContextRelease (
   CGContextRef c
);
Parameters
c

The graphics context to release.

Discussion

This function is equivalent to CFRelease, except it does not cause an error if c is NULL.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGContext.h

CGContextReplacePathWithStrokedPath

Replaces the path in the graphics context with the stroked version of the path.

void CGContextReplacePathWithStrokedPath (
   CGContextRef c
);
Parameters
c

A graphics context.

Discussion

Quartz creates a stroked path using the parameters of the current graphics context. The new path is created so that filling it draws the same pixels as stroking the original path.You can use this path in the same way you use the path of any context. For example, you can clip to the stroked version of a path by calling this function followed by a call to the function CGContextClip.

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

CGContextRestoreGState

Sets the current graphics state to the state most recently saved.

void CGContextRestoreGState (
   CGContextRef c
);
Parameters
c

The graphics context whose state you want to modify.

Discussion

Quartz removes the graphics state that is at the top of the stack so that the most recently saved state becomes the current graphics state.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGContext.h

CGContextRetain

Increments the retain count of a graphics context.

CGContextRef CGContextRetain (
   CGContextRef c
);
Parameters
c

The graphics context to retain.

Return Value

The same graphics context you passed in as the context parameter.

Discussion

This function is equivalent to CFRetain, except it does not cause an error if c is NULL.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGContext.h

CGContextRotateCTM

Rotates the user coordinate system in a context.

void CGContextRotateCTM (
   CGContextRef c,
   CGFloat angle
);
Parameters
c

A graphics context.

angle

The angle, in radians, by which to rotate the coordinate space of the specified context. Positive values rotate counterclockwise and negative values rotate clockwise.)

Discussion

The direction that the context is rotated may appear to be altered by the state of the current transformation matrix prior to executing this function. For example, on iOS, a UIView applies a transformation to the graphics context that inverts the Y-axis (by multiplying it by -1). Rotating the user coordinate system on coordinate system that was previously flipped results in a rotation in the opposite direction (that is, positive values appear to rotate the coordinate system in the clockwise direction).

Availability
  • Available in OS X v10.0 and later.
Declared In
CGContext.h

CGContextSaveGState

Pushes a copy of the current graphics state onto the graphics state stack for the context.

void CGContextSaveGState (
   CGContextRef c
);
Parameters
c

The graphics context whose current graphics state you want to save.

Discussion

Each graphics context maintains a stack of graphics states. Note that not all aspects of the current drawing environment are elements of the graphics state. For example, the current path is not considered part of the graphics state and is therefore not saved when you call the CGContextSaveGState function. The graphics state parameters that are saved are:

  • CTM (current transformation matrix)

  • clip region

  • image interpolation quality

  • line width

  • line join

  • miter limit

  • line cap

  • line dash

  • flatness

  • should anti-alias

  • rendering intent

  • fill color space

  • stroke color space

  • fill color

  • stroke color

  • alpha value

  • font

  • font size

  • character spacing

  • text drawing mode

  • shadow parameters

  • the pattern phase

  • the font smoothing parameter

  • blend mode

To restore your drawing environment to a previously saved state, you can use CGContextRestoreGState.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGContext.h

CGContextScaleCTM

Changes the scale of the user coordinate system in a context.

void CGContextScaleCTM (
   CGContextRef c,
   CGFloat sx,
   CGFloat sy
);
Parameters
c

A graphics context.

sx

The factor by which to scale the x-axis of the coordinate space of the specified context.

sy

The factor by which to scale the y-axis of the coordinate space of the specified context.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGContext.h

CGContextSetAllowsAntialiasing

Sets whether or not to allow anti-aliasing for a graphics context.

void CGContextSetAllowsAntialiasing (
   CGContextRef context,
   bool allowsAntialiasing
);
Parameters
context

A graphics context.

allowsAntialiasing

A Boolean value that specifies whether or not to allow antialiasing. Pass true to allow antialiasing; false otherwise. This parameter is not part of the graphics state.

Discussion

Quartz performs antialiasing for a graphics context if both the allowsAntialiasing parameter and the graphics state parameter shouldAntialias are true.

This parameter is not part of the graphics state.

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

CGContextSetAllowsFontSmoothing

Sets whether or not to allow font smoothing for a graphics context.

void CGContextSetAllowsFontSmoothing(
   CGContextRef context,
   bool allowsFontSmoothing
);
Parameters
context

A graphics context.

allowsFontSmoothing

A Boolean value that specifies whether font smoothing is allowed in the specified context.

Discussion

Font are smoothed if they are antialiased when drawn and if font smoothing is both allowed and enabled. For information on how to enable font smoothing, see the CGContextSetShouldSmoothFonts function. It is not usually necessary to make changes to both parameters at the same time; either can be used to disable font smoothing.

This parameter is not part of the graphics state.

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

CGContextSetAllowsFontSubpixelPositioning

Sets whether or not to allow subpixel positioning for a graphics context

void CGContextSetAllowsFontSubpixelPositioning(
   CGContextRef context,
   bool allowsFontSubpixelPositioning
);
Parameters
context

A graphics context.

allowsFontSubpixelPositioning

A Boolean value that specifies whether subpixel positioning of glyphs is allowed in the specified context.

Discussion

Sub-pixel positioning is used by the graphics context if it is allowed, enabled, and if the font itself is antialiased when drawn. For information on how to enable subpixel positioning, see the CGContextSetShouldSubpixelPositionFonts function.

This parameter is not part of the graphics state.

Availability
  • Available in OS X v10.5 and later.
Declared In
CGContext.h

CGContextSetAllowsFontSubpixelQuantization

Sets whether or not to allow subpixel quantization for a graphics context

void CGContextSetAllowsFontSubpixelQuantization(
   CGContextRef context,
   bool allowsFontSubpixelQuantization
);
Parameters
context

A graphics context.

allowsFontSubpixelQuantization

A Boolean value that specifies whether subpixel quantization of glyphs is allowed in the specified context.

Discussion

Sub-pixel quantization is used by the graphics context if it is allowed, enabled, and if glyphs would be drawn at subpixel positions. For information on how to enable subpixel quantization, see the CGContextSetShouldSubpixelQuantizeFonts function.

This parameter is not part of the graphics state.

Availability
  • Available in OS X v10.5 and later.
Declared In
CGContext.h

CGContextSetAlpha

Sets the opacity level for objects drawn in a graphics context.

void CGContextSetAlpha (
   CGContextRef c,
   CGFloat alpha
);
Parameters
c

The graphics context for which to set the current graphics state’s alpha value parameter.

alpha

A value that specifies the opacity level. Values can range from 0.0 (transparent) to 1.0 (opaque). Values outside this range are clipped to 0.0 or 1.0.

Discussion

This function sets the alpha value parameter for the specified graphics context. To clear the contents of the drawing canvas, use CGContextClearRect.

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

CGContextSetBlendMode

Sets how Quartz composites sample values for a graphics context.

void CGContextSetBlendMode (
   CGContextRef context,
   CGBlendMode mode
);
Parameters
context

The graphics context to modify.

mode

A blend mode. See “CGBlendMode” for a list of the constants you can supply.

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

CGContextSetCharacterSpacing

Sets the current character spacing.

void CGContextSetCharacterSpacing (
   CGContextRef c,
   CGFloat spacing
);
Parameters
c

The graphics context for which to set the character spacing.

spacing

A value that represents the amount of additional space to place between glyphs, in text space coordinates.

Discussion

Quartz adds the additional space to the advance between the origin of one character and the origin of the next character. For information about the text coordinate system, see CGContextSetTextMatrix.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGContext.h

CGContextSetCMYKFillColor

Sets the current fill color to a value in the DeviceCMYK color space.

void CGContextSetCMYKFillColor (
   CGContextRef c,
   CGFloat cyan,
   CGFloat magenta,
   CGFloat yellow,
   CGFloat black,
   CGFloat alpha
);
Parameters
c

The graphics context for which to set the current fill color.

cyan

The cyan intensity value for the color to set. The DeviceCMYK color space permits the specification of a value ranging from 0.0 (does not absorb the secondary color) to 1.0 (fully absorbs the secondary color).

magenta

The magenta intensity value for the color to set. The DeviceCMYK color space permits the specification of a value ranging from 0.0 (does not absorb the secondary color) to 1.0 (fully absorbs the secondary color).

yellow

The yellow intensity value for the color to set. The DeviceCMYK color space permits the specification of a value ranging from 0.0 (does not absorb the secondary color) to 1.0 (fully absorbs the secondary color).

black

The black intensity value for the color to set. The DeviceCMYK color space permits the specification of a value ranging from 0.0 (does not absorb the secondary color) to 1.0 (fully absorbs the secondary color).

alpha

A value that specifies the opacity level. Values can range from 0.0 (transparent) to 1.0 (opaque). Values outside this range are clipped to 0.0 or 1.0.

Discussion

Quartz provides convenience functions for each of the device color spaces that allow you to set the fill or stroke color space and the fill or stroke color with one function call.

When you call this function, two things happen:

  • Quartz sets the current fill color space to DeviceCMYK.

  • Quartz sets the current fill color to the value specified by the cyan, magenta, yellow, black, and alpha parameters.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGContext.h

CGContextSetCMYKStrokeColor

Sets the current stroke color to a value in the DeviceCMYK color space.

void CGContextSetCMYKStrokeColor (
   CGContextRef c,
   CGFloat cyan,
   CGFloat magenta,
   CGFloat yellow,
   CGFloat black,
   CGFloat alpha
);
Parameters
c

The graphics context for which to set the current stroke color.

cyan

The cyan intensity value for the color to set. The DeviceCMYK color space permits the specification of a value ranging from 0.0 (does not absorb the secondary color) to 1.0 (fully absorbs the secondary color).

magenta

The magenta intensity value for the color to set. The DeviceCMYK color space permits the specification of a value ranging from 0.0 (does not absorb the secondary color) to 1.0 (fully absorbs the secondary color).

yellow

The yellow intensity value for the color to set. The DeviceCMYK color space permits the specification of a value ranging from 0.0 (does not absorb the secondary color) to 1.0 (fully absorbs the secondary color).

black

The black intensity value for the color to set. The DeviceCMYK color space permits the specification of a value ranging from 0.0 (does not absorb the secondary color) to 1.0 (fully absorbs the secondary color).

alpha

A value that specifies the opacity level. Values can range from 0.0 (transparent) to 1.0 (opaque). Values outside this range are clipped to 0.0 or 1.0.

Discussion

When you call this function, two things happen:

  • Quartz sets the current stroke color space to DeviceCMYK.

  • Quartz sets the current stroke color to the value specified by the cyan, magenta, yellow, black, and alpha parameters.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGContext.h

CGContextSetFillColor

Sets the current fill color.

void CGContextSetFillColor (
   CGContextRef c,
   const CGFloat components[]
);
Parameters
c

The graphics context for which to set the current fill color.

components

An array of intensity values describing the color to set. The number of array elements must equal the number of components in the current fill color space, plus an additional component for the alpha value.

Discussion

The current fill color space must not be a pattern color space. For information on setting the fill color when using a pattern color space, see CGContextSetFillPattern. Note that the preferred API to use is now CGContextSetFillColorWithColor.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGContext.h

CGContextSetFillColorSpace

Sets the fill color space in a graphics context.

void CGContextSetFillColorSpace (
   CGContextRef c,
   CGColorSpaceRef colorspace
);
Parameters
c

The graphics context for which to set the fill color space.

colorspace

The new fill color space. Quartz retains this object; upon return, you may safely release it.

Discussion

As a side effect of this function, Quartz assigns an appropriate initial value to the fill color, based on the specified color space. To change this value, call CGContextSetFillColor. Note that the preferred API to use is now CGContextSetFillColorWithColor.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGContext.h

CGContextSetFillColorWithColor

Sets the current fill color in a graphics context, using a Quartz color.

void CGContextSetFillColorWithColor (
   CGContextRef c,
   CGColorRef color
);
Parameters
c

The graphics context for which to set the fill color.

color

The new fill color.

Availability
  • Available in OS X v10.3 and later.
Declared In
CGContext.h

CGContextSetFillPattern

Sets the fill pattern in the specified graphics context.

void CGContextSetFillPattern (
   CGContextRef c,
   CGPatternRef pattern,
   const CGFloat components[]
);
Parameters
c

The graphics context to modify.

pattern

A fill pattern. Quartz retains this object; upon return, you may safely release it.

components

If the pattern is an uncolored (or a masking) pattern, pass an array of intensity values that specify the color to use when the pattern is painted. The number of array elements must equal the number of components in the base space of the fill pattern color space, plus an additional component for the alpha value.

If the pattern is a colored pattern, pass an alpha value.

Discussion

The current fill color space must be a pattern color space. Otherwise, the result of calling this function is undefined. If you want to set a fill color, not a pattern, use CGContextSetFillColorWithColor.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGContext.h

CGContextSetFlatness

Sets the accuracy of curved paths in a graphics context.

void CGContextSetFlatness (
   CGContextRef c,
   CGFloat flatness
);
Parameters
c

The graphics context to modify.

flatness

The largest permissible distance, measured in device pixels, between a point on the true curve and a point on the approximated curve.

Discussion

This function controls how accurately curved paths are rendered. Setting the flatness value to less than 1.0 renders highly accurate curves, but lengthens rendering times.

In most cases, you should not change the flatness value. Customizing the flatness value for the capabilities of a particular output device impairs the ability of your application to render to other devices.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGContext.h

CGContextSetFont

Sets the platform font in a graphics context.

void CGContextSetFont (
   CGContextRef c,
   CGFontRef font
);
Parameters
c

The graphics context for which to set the font.

font

A Quartz font.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGContext.h

CGContextSetFontSize

Sets the current font size.

void CGContextSetFontSize (
   CGContextRef c,
   CGFloat size
);
Parameters
c

A graphics context.

size

A font size, expressed in text space units.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGContext.h

CGContextSetGrayFillColor

Sets the current fill color to a value in the DeviceGray color space.

void CGContextSetGrayFillColor (
   CGContextRef c,
   CGFloat gray,
   CGFloat alpha
);
Parameters
c

The graphics context for which to set the current fill color.

gray

A value that specifies the desired gray level. The DeviceGray color space permits the specification of a value ranging from 0.0 (absolute black) to 1.0 (absolute white). Values outside this range are clamped to 0.0 or 1.0.

alpha

A value that specifies the opacity level. Values can range from 0.0 (transparent) to 1.0 (opaque). Values outside this range are clipped to 0.0 or 1.0.

Discussion

When you call this function, two things happen:

  • Quartz sets the current fill color space to DeviceGray.

  • Quartz sets the current fill color to the value you specify in the gray and alpha parameters.

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

CGContextSetGrayStrokeColor

Sets the current stroke color to a value in the DeviceGray color space.

void CGContextSetGrayStrokeColor (
   CGContextRef c,
   CGFloat gray,
   CGFloat alpha
);
Parameters
c

The graphics context for which to set the current stroke color.

gray

A value that specifies the desired gray level. The DeviceGray color space permits the specification of a value ranging from 0.0 (absolute black) to 1.0 (absolute white). Values outside this range are clamped to 0.0 or 1.0.

alpha

A value that specifies the opacity level. Values can range from 0.0 (transparent) to 1.0 (opaque). Values outside this range are clipped to 0.0 or 1.0.

Discussion

When you call this function, two things happen:

  • Quartz sets the current stroke color space to DeviceGray. The DeviceGray color space is a single-dimension space in which color values are specified solely by the intensity of a gray value (from absolute black to absolute white).

  • Quartz sets the current stroke color to the value you specify in the gray and alpha parameters.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGContext.h

CGContextSetInterpolationQuality

Sets the level of interpolation quality for a graphics context.

void CGContextSetInterpolationQuality (
   CGContextRef c,
   CGInterpolationQuality quality
);
Parameters
c

The graphics context to modify.

quality

A CGInterpolationQuality constant that specifies the required level of interpolation quality. For possible values, see “CGInterpolationQuality”.

Discussion

Interpolation quality is merely a hint to the context—not all contexts support all interpolation quality levels.

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

CGContextSetLineCap

Sets the style for the endpoints of lines drawn in a graphics context.

void CGContextSetLineCap (
   CGContextRef c,
   CGLineCap cap
);
Parameters
c

The graphics context to modify.

cap

A line cap style constant—kCGLineCapButt (the default), kCGLineCapRound, or kCGLineCapSquare. See CGPath Reference.

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

CGContextSetLineDash

Sets the pattern for dashed lines in a graphics context.

void CGContextSetLineDash (
   CGContextRef c,
   CGFloat phase,
   const CGFloat lengths[],
   size_t count
);
Parameters
c

The graphics context to modify.

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.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGContext.h

CGContextSetLineJoin

Sets the style for the joins of connected lines in a graphics context.

void CGContextSetLineJoin (
   CGContextRef c,
   CGLineJoin join
);
Parameters
c

The graphics context to modify.

join

A line join value—kCGLineJoinMiter (the default), kCGLineJoinRound, or kCGLineJoinBevel. See CGPath Reference.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGContext.h

CGContextSetLineWidth

Sets the line width for a graphics context.

void CGContextSetLineWidth (
   CGContextRef c,
   CGFloat width
);
Parameters
c

The graphics context to modify.

width

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

Discussion

The default line width is 1 unit. When stroked, the line straddles the path, with half of the total width on either side.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGContext.h

CGContextSetMiterLimit

Sets the miter limit for the joins of connected lines in a graphics context.

void CGContextSetMiterLimit (
   CGContextRef c,
   CGFloat limit
);
Parameters
c

The graphics context to modify.

limit

The miter limit to use.

Discussion

If the current line join style is set to kCGLineJoinMiter (see CGContextSetLineJoin), 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.0 and later.
Declared In
CGContext.h

CGContextSetPatternPhase

Sets the pattern phase of a context.

void CGContextSetPatternPhase (
   CGContextRef c,
   CGSize phase
);
Parameters
c

The graphics context to modify.

phase

A pattern phase, specified in user space.

Discussion

The pattern phase is a translation that Quartz applies prior to drawing a pattern in the context. The pattern phase is part of the graphics state of a context, and the default pattern phase is (0,0). Setting the pattern phase has the effect of temporarily changing the pattern matrix of any pattern you draw. For example, setting the context’s pattern phase to (2,3) has the effect of moving the start of pattern cell tiling to the point (2,3) in default user space.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGContext.h

CGContextSetRenderingIntent

Sets the rendering intent in the current graphics state.

void CGContextSetRenderingIntent (
   CGContextRef c,
   CGColorRenderingIntent intent
);
Parameters
c

The graphics context to modify.

intent

A rendering intent constant—kCGRenderingIntentDefault, kCGRenderingIntentAbsoluteColorimetric, kCGRenderingIntentRelativeColorimetric, kCGRenderingIntentPerceptual, or kCGRenderingIntentSaturation. For a discussion of these constants, see CGColorSpace Reference.

Discussion

The rendering intent specifies how Quartz should handle colors that are not located within the gamut of the destination color space of a graphics context. If you do not explicitly set the rendering intent, Quartz uses perceptual rendering intent for drawing sampled images and relative colorimetric rendering intent for all other drawing.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGContext.h

CGContextSetRGBFillColor

Sets the current fill color to a value in the DeviceRGB color space.

void CGContextSetRGBFillColor (
   CGContextRef c,
   CGFloat red,
   CGFloat green,
   CGFloat blue,
   CGFloat alpha
);
Parameters
c

The graphics context for which to set the current fill color.

red

The red intensity value for the color to set. The DeviceRGB color space permits the specification of a value ranging from 0.0 (zero intensity) to 1.0 (full intensity).

green

The green intensity value for the color to set. The DeviceRGB color space permits the specification of a value ranging from 0.0 (zero intensity) to 1.0 (full intensity).

blue

The blue intensity value for the color to set. The DeviceRGB color space permits the specification of a value ranging from 0.0 (zero intensity) to 1.0 (full intensity).

alpha

A value that specifies the opacity level. Values can range from 0.0 (transparent) to 1.0 (opaque). Values outside this range are clipped to 0.0 or 1.0.

Discussion

When you call this function, two things happen:

  • Quartz sets the current fill color space to DeviceRGB.

  • Quartz sets the current fill color to the value specified by the red, green, blue, and alpha parameters.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGContext.h

CGContextSetRGBStrokeColor

Sets the current stroke color to a value in the DeviceRGB color space.

void CGContextSetRGBStrokeColor (
   CGContextRef c,
   CGFloat red,
   CGFloat green,
   CGFloat blue,
   CGFloat alpha
);
Parameters
c

The graphics context for which to set the current stroke color.

red

The red intensity value for the color to set. The DeviceRGB color space permits the specification of a value ranging from 0.0 (zero intensity) to 1.0 (full intensity).

green

The green intensity value for the color to set. The DeviceRGB color space permits the specification of a value ranging from 0.0 (zero intensity) to 1.0 (full intensity).

blue

The blue intensity value for the color to set. The DeviceRGB color space permits the specification of a value ranging from 0.0 (zero intensity) to 1.0 (full intensity).

alpha

A value that specifies the opacity level. Values can range from 0.0 (transparent) to 1.0 (opaque). Values outside this range are clipped to 0.0 or 1.0.

Discussion

When you call this function, two things happen:

  • Quartz sets the current stroke color space to DeviceRGB.

  • Quartz sets the current stroke color to the value specified by the red, green, blue, and alpha parameters.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGContext.h

CGContextSetShadow

Enables shadowing in a graphics context.

void CGContextSetShadow (
   CGContextRef context,
   CGSize offset,
   CGFloat blur
);
Parameters
context

A graphics context.

offset

Specifies a translation of the context’s coordinate system, to establish an offset for the shadow ({0,0} specifies a light source immediately above the screen).

blur

A non-negative number specifying the amount of blur.

Discussion

Shadow parameters are part of the graphics state in a context. After shadowing is set, all objects drawn are shadowed using a black color with 1/3 alpha (i.e., RGBA = {0, 0, 0, 1.0/3.0}) in the DeviceRGB color space.

To turn off shadowing:

  • Use the standard save/restore mechanism for the graphics state.

  • Use CGContextSetShadowWithColor to set the shadow color to a fully transparent color (or pass NULL as the color).

Availability
  • Available in OS X v10.3 and later.
Declared In
CGContext.h

CGContextSetShadowWithColor

Enables shadowing with color a graphics context.

void CGContextSetShadowWithColor (
   CGContextRef context,
   CGSize offset,
   CGFloat blur,
   CGColorRef color
);
Parameters
context

The graphics context to modify.

offset

Specifies a translation in base-space.

blur

A non-negative number specifying the amount of blur.

color

Specifies the color of the shadow, which may contain a non-opaque alpha value. If NULL, then shadowing is disabled.

Availability
  • Available in OS X v10.3 and later.
Declared In
CGContext.h

CGContextSetShouldAntialias

Sets anti-aliasing on or off for a graphics context.

void CGContextSetShouldAntialias (
   CGContextRef c,
   bool shouldAntialias
);
Parameters
c

The graphics context to modify.

shouldAntialias

A Boolean value that specifies whether anti-aliasing should be turned on. Anti-aliasing is turned on by default when a window or bitmap context is created. It is turned off for other types of contexts.

Discussion

Anti-aliasing is a graphics state parameter.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGContext.h

CGContextSetShouldSmoothFonts

Enables or disables font smoothing in a graphics context.

void CGContextSetShouldSmoothFonts (
   CGContextRef c,
   bool shouldSmoothFonts
);
Parameters
c

The graphics context to modify.

shouldSmoothFonts

A Boolean value that specifies whether to enable font smoothing.

Discussion

There are cases, such as rendering to a bitmap, when font smoothing is not appropriate and should be disabled. Note that some contexts (such as PostScript contexts) do not support font smoothing.

This parameter is part of the graphics state. Because of this, you use this when you want to temporarily override this setting in a drawing method.

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

CGContextSetShouldSubpixelPositionFonts

Enables or disables subpixel positioning in a graphics context.

void CGContextSetShouldSubpixelPositionFonts(
   CGContextRef context,
   bool shouldSubpixelPositionFonts
);
Parameters
context

A graphics context.

shouldSubpixelPositionFonts

A Boolean value that specifies whether to enable subpixel positioning.

Discussion

When enabled, the graphics context may position glyphs on nonintegral pixel boundaries. When disabled, the position of glyphs are always forced to integral pixel boundaries.

This parameter is part of the graphics state.

Availability
  • Available in OS X v10.5 and later.
Declared In
CGContext.h

CGContextSetShouldSubpixelQuantizeFonts

Enables or disables subpixel quantization in a graphics context.

void CGContextSetShouldSubpixelQuantizeFonts(
   CGContextRef context,
   bool shouldSubpixelQuantizeFonts
);
Parameters
context

A graphics context.

shouldSubpixelQuantizeFonts

A Boolean value that specifies whether to enable subpixel quantization.

Discussion

When enabled, the graphics context may quantize the subpixel positions of glyphs.

This parameter is part of the graphics state.

Availability
  • Available in OS X v10.5 and later.
Declared In
CGContext.h

CGContextSetStrokeColor

Sets the current stroke color.

void CGContextSetStrokeColor (
   CGContextRef c,
   const CGFloat components[]
);
Parameters
c

The graphics context for which to set the current stroke color.

components

An array of intensity values describing the color to set. The number of array elements must equal the number of components in the current stroke color space, plus an additional component for the alpha value.

Discussion

The current stroke color space must not be a pattern color space. For information on setting the stroke color when using a pattern color space, see CGContextSetStrokePattern. Note that the preferred API is now CGContextSetStrokeColorWithColor.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGContext.h

CGContextSetStrokeColorSpace

Sets the stroke color space in a graphics context.

void CGContextSetStrokeColorSpace (
   CGContextRef c,
   CGColorSpaceRef colorspace
);
Parameters
c

The graphics context for the new stroke color space.

colorspace

The new stroke color space. Quartz retains this object; upon return, you may safely release it.

Discussion

As a side effect when you call this function, Quartz assigns an appropriate initial value to the stroke color, based on the color space you specify. To change this value, call CGContextSetStrokeColor. Note that the preferred API is now CGContextSetStrokeColorWithColor.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGContext.h

CGContextSetStrokeColorWithColor

Sets the current stroke color in a context, using a Quartz color.

void CGContextSetStrokeColorWithColor (
   CGContextRef c,
   CGColorRef color
);
Parameters
c

The graphics context to modify.

color

The new stroke color.

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

CGContextSetStrokePattern

Sets the stroke pattern in the specified graphics context.

void CGContextSetStrokePattern (
   CGContextRef c,
   CGPatternRef pattern,
   const CGFloat components[]
);
Parameters
c

The graphics context to modify.

pattern

A pattern for stroking. Quartz retains this object; upon return, you may safely release it.

components

If the specified pattern is an uncolored (or masking) pattern, pass an array of intensity values that specify the color to use when the pattern is painted. The number of array elements must equal the number of components in the base space of the stroke pattern color space, plus an additional component for the alpha value.

If the specified pattern is a colored pattern, pass an alpha value.

Discussion

The current stroke color space must be a pattern color space. Otherwise, the result of calling this function is undefined. If you want to set a stroke color, not a stroke pattern, use CGContextSetStrokeColorWithColor.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGContext.h

CGContextSetTextDrawingMode

Sets the current text drawing mode.

void CGContextSetTextDrawingMode (
   CGContextRef c,
   CGTextDrawingMode mode
);
Parameters
c

A graphics context.

mode

A text drawing mode (such as kCGTextFill or kCGTextStroke) that specifies how Quartz renders individual glyphs in a graphics context. See “CGTextDrawingMode” for a complete list.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGContext.h

CGContextSetTextMatrix

Sets the current text matrix.

void CGContextSetTextMatrix (
   CGContextRef c,
   CGAffineTransform t
);
Parameters
c

A graphics context.

transform

The text matrix to set.

Discussion

The text matrix specifies the transform from text space to user space. To produce the final text rendering matrix that is used to actually draw the text on the page, Quartz concatenates the text matrix with the current transformation matrix and other parameters from the graphics state.

Note that the text matrix is not a part of the graphics state—saving or restoring the graphics state has no effect on the text matrix. The text matrix is an attribute of the graphics context, not of the current font.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGContext.h

CGContextSetTextPosition

Sets the location at which text is drawn.

void CGContextSetTextPosition (
   CGContextRef c,
   CGFloat x,
   CGFloat y
);
Parameters
c

A graphics context.

x

A value for the x-coordinate at which to draw the text, in user space coordinates.

y

A value for the y-coordinate at which to draw the text, in user space coordinates.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGContext.h

CGContextShowGlyphsAtPositions

Draws glyphs at the provided position.

void CGContextShowGlyphsAtPositions(
   CGContextRef context,
   const CGGlyph glyphs[],
   const CGPoint positions[],
   size_t count
);
Parameters
c

The graphics context in which to display the glyphs.

glyphs

An array of Quartz glyphs.

positions

The positions for the glyphs. Each item in this array matches with the glyph at the corresponding index in the glyphs array. The position of each glyph is specified in text space, and, as a consequence, is transformed through the text matrix to user space.

count

The number of items in the glyphs array.

Availability
  • Available in OS X v10.5 and later.
Declared In
CGContext.h

CGContextStrokeEllipseInRect

Strokes an ellipse that fits inside the specified rectangle.

void CGContextStrokeEllipseInRect (
   CGContextRef context,
   CGRect rect
);
Parameters
context

A graphics context.

rect

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

Discussion

As a side effect when you call this function, Quartz clears the current path.

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

CGContextStrokeLineSegments

Strokes a sequence of line segments.

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

A graphics context.

points

An array of points, organized as pairs—the starting point of a line segment followed by the ending point of a line segment. For example, the first point in the array specifies the starting position of the first line, the second point specifies the ending position of the first line, the third point specifies the starting position of the second line, and so forth.

count

The number of points in the points array.

Discussion

This function is equivalent to the following code:

CGContextBeginPath (context);
for (k = 0; k < count; k += 2) {
    CGContextMoveToPoint(context, s[k].x, s[k].y);
    CGContextAddLineToPoint(context, s[k+1].x, s[k+1].y);
}
CGContextStrokePath(context);

As a side effect when you call this function, Quartz clears the current path.

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

CGContextStrokePath

Paints a line along the current path.

void CGContextStrokePath (
   CGContextRef c
);
Parameters
c

A graphics context.

Discussion

Quartz uses the line width and stroke color of the graphics state to paint the path. As a side effect when you call this function, Quartz clears the current path.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGContext.h

CGContextStrokeRect

Paints a rectangular path.

void CGContextStrokeRect (
   CGContextRef c,
   CGRect rect
);
Parameters
c

A graphics context .

rect

A rectangle, specified in user space coordinates.

Discussion

Quartz uses the line width and stroke color of the graphics state to paint the path. As a side effect when you call this function, Quartz clears the current path.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGContext.h

CGContextStrokeRectWithWidth

Paints a rectangular path, using the specified line width.

void CGContextStrokeRectWithWidth (
   CGContextRef c,
   CGRect rect,
   CGFloat width
);
Parameters
c

A graphics context.

rect

A rectangle, in user space coordinates.

width

A value, in user space units, that is greater than zero. This value does not affect the line width values in the current graphics state.

Discussion

Aside from the line width value, Quartz uses the current attributes of the graphics state (such as stroke color) to paint the line. The line straddles the path, with half of the total width on either side.

As a side effect when you call this function, Quartz clears the current path.

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

CGContextSynchronize

Marks a window context for update.

void CGContextSynchronize (
   CGContextRef c
);
Parameters
c

The window context to synchronize. If you pass a PDF context or a bitmap context, this function does nothing.

Discussion

When you call this function, all drawing operations since the last update are flushed at the next regular opportunity. Under normal conditions, you do not need to call this function.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGContext.h

CGContextTranslateCTM

Changes the origin of the user coordinate system in a context.

void CGContextTranslateCTM (
   CGContextRef c,
   CGFloat tx,
   CGFloat ty
);
Parameters
c

A graphics context.

tx

The amount to displace the x-axis of the coordinate space, in units of the user space, of the specified context.

ty

The amount to displace the y-axis of the coordinate space, in units of the user space, of the specified context.

Availability
  • Available in OS X v10.0 and later.
Declared In
CGContext.h

Data Types

CGContextRef

An opaque type that represents a Quartz 2D drawing environment.

typedef struct CGContext * CGContextRef;
Availability
  • Available in OS X v10.0 and later.
Declared In
CGContext.h

Constants

CGBlendMode

Compositing operations for images.

enum CGBlendMode {
   kCGBlendModeNormal,
   kCGBlendModeMultiply,
   kCGBlendModeScreen,
   kCGBlendModeOverlay,
   kCGBlendModeDarken,
   kCGBlendModeLighten,
   kCGBlendModeColorDodge,
   kCGBlendModeColorBurn,
   kCGBlendModeSoftLight,
   kCGBlendModeHardLight,
   kCGBlendModeDifference,
   kCGBlendModeExclusion,
   kCGBlendModeHue,
   kCGBlendModeSaturation,
   kCGBlendModeColor,
   kCGBlendModeLuminosity,
   kCGBlendModeClear,
   kCGBlendModeCopy,
   kCGBlendModeSourceIn,
   kCGBlendModeSourceOut,
   kCGBlendModeSourceAtop,
   kCGBlendModeDestinationOver,
   kCGBlendModeDestinationIn,
   kCGBlendModeDestinationOut,
   kCGBlendModeDestinationAtop,
   kCGBlendModeXOR,
   kCGBlendModePlusDarker,
   kCGBlendModePlusLighter
};
typedef enum CGBlendMode CGBlendMode;
Constants
kCGBlendModeNormal

Paints the source image samples over the background image samples.

Available in OS X v10.4 and later.

Declared in CGContext.h.

kCGBlendModeMultiply

Multiplies the source image samples with the background image samples. This results in colors that are at least as dark as either of the two contributing sample colors.

Available in OS X v10.4 and later.

Declared in CGContext.h.

kCGBlendModeScreen

Multiplies the inverse of the source image samples with the inverse of the background image samples. This results in colors that are at least as light as either of the two contributing sample colors.

Available in OS X v10.4 and later.

Declared in CGContext.h.

kCGBlendModeOverlay

Either multiplies or screens the source image samples with the background image samples, depending on the background color. The result is to overlay the existing image samples while preserving the highlights and shadows of the background. The background color mixes with the source image to reflect the lightness or darkness of the background.

Available in OS X v10.4 and later.

Declared in CGContext.h.

kCGBlendModeDarken

Creates the composite image samples by choosing the darker samples (either from the source image or the background). The result is that the background image samples are replaced by any source image samples that are darker. Otherwise, the background image samples are left unchanged.

Available in OS X v10.4 and later.

Declared in CGContext.h.

kCGBlendModeLighten

Creates the composite image samples by choosing the lighter samples (either from the source image or the background). The result is that the background image samples are replaced by any source image samples that are lighter. Otherwise, the background image samples are left unchanged.

Available in OS X v10.4 and later.

Declared in CGContext.h.

kCGBlendModeColorDodge

Brightens the background image samples to reflect the source image samples. Source image sample values that specify black do not produce a change.

Available in OS X v10.4 and later.

Declared in CGContext.h.

kCGBlendModeColorBurn

Darkens the background image samples to reflect the source image samples. Source image sample values that specify white do not produce a change.

Available in OS X v10.4 and later.

Declared in CGContext.h.

kCGBlendModeSoftLight

Either darkens or lightens colors, depending on the source image sample color. If the source image sample color is lighter than 50% gray, the background is lightened, similar to dodging. If the source image sample color is darker than 50% gray, the background is darkened, similar to burning. If the source image sample color is equal to 50% gray, the background is not changed. Image samples that are equal to pure black or pure white produce darker or lighter areas, but do not result in pure black or white. The overall effect is similar to what you’d achieve by shining a diffuse spotlight on the source image. Use this to add highlights to a scene.

Available in OS X v10.4 and later.

Declared in CGContext.h.

kCGBlendModeHardLight

Either multiplies or screens colors, depending on the source image sample color. If the source image sample color is lighter than 50% gray, the background is lightened, similar to screening. If the source image sample color is darker than 50% gray, the background is darkened, similar to multiplying. If the source image sample color is equal to 50% gray, the source image is not changed. Image samples that are equal to pure black or pure white result in pure black or white. The overall effect is similar to what you’d achieve by shining a harsh spotlight on the source image. Use this to add highlights to a scene.

Available in OS X v10.4 and later.

Declared in CGContext.h.

kCGBlendModeDifference

Subtracts either the source image sample color from the background image sample color, or the reverse, depending on which sample has the greater brightness value. Source image sample values that are black produce no change; white inverts the background color values.

Available in OS X v10.4 and later.

Declared in CGContext.h.

kCGBlendModeExclusion

Produces an effect similar to that produced by kCGBlendModeDifference, but with lower contrast. Source image sample values that are black don’t produce a change; white inverts the background color values.

Available in OS X v10.4 and later.

Declared in CGContext.h.

kCGBlendModeHue

Uses the luminance and saturation values of the background with the hue of the source image.

Available in OS X v10.4 and later.

Declared in CGContext.h.

kCGBlendModeSaturation

Uses the luminance and hue values of the background with the saturation of the source image. Areas of the background that have no saturation (that is, pure gray areas) don’t produce a change.

Available in OS X v10.4 and later.

Declared in CGContext.h.

kCGBlendModeColor

Uses the luminance values of the background with the hue and saturation values of the source image. This mode preserves the gray levels in the image. You can use this mode to color monochrome images or to tint color images.

Available in OS X v10.4 and later.

Declared in CGContext.h.

kCGBlendModeLuminosity

Uses the hue and saturation of the background with the luminance of the source image. This mode creates an effect that is inverse to the effect created by kCGBlendModeColor.

Available in OS X v10.4 and later.

Declared in CGContext.h.

kCGBlendModeClear

R = 0

Available in OS X v10.5 and later.

Declared in CGContext.h.

kCGBlendModeCopy

R = S

Available in OS X v10.5 and later.

Declared in CGContext.h.

kCGBlendModeSourceIn

R = S*Da

Available in OS X v10.5 and later.

Declared in CGContext.h.

kCGBlendModeSourceOut

R = S*(1 - Da)

Available in OS X v10.5 and later.

Declared in CGContext.h.

kCGBlendModeSourceAtop

R = S*Da + D*(1 - Sa)

Available in OS X v10.5 and later.

Declared in CGContext.h.

kCGBlendModeDestinationOver

R = S*(1 - Da) + D

Available in OS X v10.5 and later.

Declared in CGContext.h.

kCGBlendModeDestinationIn

R = D*Sa

Available in OS X v10.5 and later.

Declared in CGContext.h.

kCGBlendModeDestinationOut

R = D*(1 - Sa)

Available in OS X v10.5 and later.

Declared in CGContext.h.

kCGBlendModeDestinationAtop

R = S*(1 - Da) + D*Sa

Available in OS X v10.5 and later.

Declared in CGContext.h.

kCGBlendModeXOR

R = S*(1 - Da) + D*(1 - Sa). This XOR mode is only nominally related to the classical bitmap XOR operation, which is not supported by Quartz 2D.

Available in OS X v10.5 and later.

Declared in CGContext.h.

kCGBlendModePlusDarker

R = MAX(0, 1 - ((1 - D) + (1 - S)))

Available in OS X v10.5 and later.

Declared in CGContext.h.

kCGBlendModePlusLighter

R = MIN(1, S + D)

Available in OS X v10.5 and later.

Declared in CGContext.h.

Discussion

The blend mode constants introduced in OS X v10.5 represent the Porter-Duff blend modes. The symbols in the equations for these blend modes are:

  • R is the premultiplied result

  • S is the source color, and includes alpha

  • D is the destination color, and includes alpha

  • Ra, Sa, and Da are the alpha components of R, S, and D

You can find more information on blend modes, including examples of images produced using them, and many mathematical descriptions of the modes, in PDF Reference, Fourth Edition, Version 1.5, Adobe Systems, Inc. If you are a former QuickDraw developer, it may be helpful for you to think of blend modes as an alternative to transfer modes

For examples of using blend modes see "Setting Blend Modes" and "Using Blend Modes With Images" in Quartz 2D Programming Guide.

CGInterpolationQuality

Levels of interpolation quality for rendering an image.

enum CGInterpolationQuality {
   kCGInterpolationDefault = 0,
   kCGInterpolationNone = 1,
   kCGInterpolationLow = 2,
   kCGInterpolationMedium = 4,
   kCGInterpolationHigh = 3
};
typedef enum CGInterpolationQuality CGInterpolationQuality;
Constants
kCGInterpolationDefault

The default level of quality.

Available in OS X v10.1 and later.

Declared in CGContext.h.

kCGInterpolationNone

No interpolation.

Available in OS X v10.1 and later.

Declared in CGContext.h.

kCGInterpolationLow

A low level of interpolation quality. This setting may speed up image rendering.

Available in OS X v10.1 and later.

Declared in CGContext.h.

kCGInterpolationMedium

A medium level of interpolation quality. This setting is slower than the low setting but faster than the high setting.

Available in OS X v10.6 and later.

Declared in CGContext.h.

kCGInterpolationHigh

A high level of interpolation quality. This setting may slow down image rendering.

Available in OS X v10.1 and later.

Declared in CGContext.h.

Discussion

You use the function CGContextSetInterpolationQuality to set the interpolation quality in a graphics context.

CGTextDrawingMode

Modes for rendering text.

enum CGTextDrawingMode {
   kCGTextFill,
   kCGTextStroke,
   kCGTextFillStroke,
   kCGTextInvisible,
   kCGTextFillClip,
   kCGTextStrokeClip,
   kCGTextFillStrokeClip,
   kCGTextClip
};
typedef enum CGTextDrawingMode CGTextDrawingMode;
Constants
kCGTextFill

Perform a fill operation on the text.

Available in OS X v10.0 and later.

Declared in CGContext.h.

kCGTextStroke

Perform a stroke operation on the text.

Available in OS X v10.0 and later.

Declared in CGContext.h.

kCGTextFillStroke

Perform fill, then stroke operations on the text.

Available in OS X v10.0 and later.

Declared in CGContext.h.

kCGTextInvisible

Do not draw the text, but do update the text position.

Available in OS X v10.0 and later.

Declared in CGContext.h.

kCGTextFillClip

Perform a fill operation, then intersect the text with the current clipping path.

Available in OS X v10.0 and later.

Declared in CGContext.h.

kCGTextStrokeClip

Perform a stroke operation, then intersect the text with the current clipping path.

Available in OS X v10.0 and later.

Declared in CGContext.h.

kCGTextFillStrokeClip

Perform fill then stroke operations, then intersect the text with the current clipping path.

Available in OS X v10.0 and later.

Declared in CGContext.h.

kCGTextClip

Specifies to intersect the text with the current clipping path. This mode does not paint the text.

Available in OS X v10.0 and later.

Declared in CGContext.h.

Discussion

You provide a text drawing mode constant to the function CGContextSetTextDrawingMode to set the current text drawing mode for a graphics context. Text drawing modes determine how Quartz renders individual glyphs onscreen. For example, you can set a text drawing mode to draw text filled in or outlined (stroked) or both. You can also create special effects with the text clipping drawing modes, such as clipping an image to a glyph shape.

CGTextEncoding

Text encodings for fonts.

enum CGTextEncoding {
   kCGEncodingFontSpecific,
   kCGEncodingMacRoman
};
typedef enum CGTextEncoding CGTextEncoding;
Constants
kCGEncodingFontSpecific

The built-in encoding of the font.

Available in OS X v10.0 and later.

Declared in CGContext.h.

kCGEncodingMacRoman

The MacRoman encoding. MacRoman is an ASCII variant originally created for use in the Mac OS, in which characters 127 and lower are ASCII, and characters 128 and higher are non-English characters and symbols.

Available in OS X v10.0 and later.

Declared in CGContext.h.

Discussion

For more information on setting the font in a graphics context, see CGContextSelectFont.