CGContext Reference
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
-
CGContextGetInterpolationQuality
-
CGContextSetFlatness
-
CGContextSetInterpolationQuality
-
CGContextSetLineCap
-
CGContextSetLineDash
-
CGContextSetLineJoin
-
CGContextSetLineWidth
-
CGContextSetMiterLimit
-
CGContextSetPatternPhase
-
CGContextSetFillPattern
-
CGContextSetRenderingIntent
-
CGContextSetShouldAntialias
-
CGContextSetStrokePattern
-
CGContextSetBlendMode
-
CGContextSetAllowsAntialiasing
-
CGContextSetAllowsFontSmoothing
-
CGContextSetShouldSmoothFonts
-
CGContextSetAllowsFontSubpixelPositioning
-
CGContextSetShouldSubpixelPositionFonts
-
CGContextSetAllowsFontSubpixelQuantization
-
CGContextSetShouldSubpixelQuantizeFonts
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.
-
CGContextAddArc
-
CGContextAddArcToPoint
-
CGContextAddCurveToPoint
-
CGContextAddLines
-
CGContextAddLineToPoint
-
CGContextAddPath
-
CGContextCopyPath
-
CGContextAddQuadCurveToPoint
-
CGContextAddRect
-
CGContextAddRects
-
CGContextBeginPath
-
CGContextClosePath
-
CGContextMoveToPoint
-
CGContextAddEllipseInRect
Painting Paths
These functions are used to stroke along or fill in the current path.
-
CGContextClearRect
-
CGContextDrawPath
-
CGContextEOFillPath
-
CGContextFillPath
-
CGContextFillRect
-
CGContextFillRects
-
CGContextFillEllipseInRect
-
CGContextStrokePath
-
CGContextStrokeRect
-
CGContextStrokeRectWithWidth
-
CGContextReplacePathWithStrokedPath
-
CGContextStrokeEllipseInRect
-
CGContextStrokeLineSegments
Getting Information About Paths
-
CGContextIsPathEmpty
-
CGContextGetPathCurrentPoint
-
CGContextGetPathBoundingBox
-
CGContextPathContainsPoint
Modifying Clipping Paths
-
CGContextClip
-
CGContextEOClip
-
CGContextClipToRect
-
CGContextClipToRects
-
CGContextGetClipBoundingBox
-
CGContextClipToMask
Setting Color, Color Space, and Shadow Values
-
CGContextSetAlpha
-
CGContextSetCMYKFillColor
-
CGContextSetFillColor
-
CGContextSetCMYKStrokeColor
-
CGContextSetFillColorSpace
-
CGContextSetFillColorWithColor
-
CGContextSetGrayFillColor
-
CGContextSetGrayStrokeColor
-
CGContextSetRGBFillColor
-
CGContextSetRGBStrokeColor
-
CGContextSetShadow
-
CGContextSetShadowWithColor
-
CGContextSetStrokeColor
-
CGContextSetStrokeColorSpace
-
CGContextSetStrokeColorWithColor
Transforming User Space
These functions allow you to examine and change the current transformation matrix (CTM) in a graphics context.
Using Transparency Layers
-
CGContextBeginTransparencyLayer
-
CGContextBeginTransparencyLayerWithRect
-
CGContextEndTransparencyLayer
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
-
CGContextShowGlyphsAtPositions
-
CGContextShowGlyphs
Deprecated in iOS 7.0 -
CGContextShowGlyphsAtPoint
Deprecated in iOS 7.0 -
CGContextShowGlyphsWithAdvances
Deprecated in iOS 7.0
Drawing Text
-
CGContextGetTextMatrix
-
CGContextGetTextPosition
-
CGContextSetCharacterSpacing
-
CGContextSetFont
-
CGContextSetFontSize
-
CGContextSetTextDrawingMode
-
CGContextSetTextMatrix
-
CGContextSetTextPosition
-
CGContextSelectFont
Deprecated in iOS 7.0 -
CGContextShowText
Deprecated in iOS 7.0 -
CGContextShowTextAtPoint
Deprecated in iOS 7.0
Converting Between Device Space and User Space
-
CGContextGetUserSpaceToDeviceSpaceTransform
-
CGContextConvertPointToDeviceSpace
-
CGContextConvertPointToUserSpace
-
CGContextConvertSizeToDeviceSpace
-
CGContextConvertSizeToUserSpace
-
CGContextConvertRectToDeviceSpace
-
CGContextConvertRectToUserSpace
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 or0
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 iOS 2.0 and later.
See Also
Declared In
CGContext.h
CGContextAddArcToPoint
Adds an arc of a circle to the current path, using a radius and tangent points.
void CGContextAddArcToPoint ( CGContextRef c, CGFloat x1, CGFloat y1, CGFloat x2, CGFloat y2, CGFloat radius );
Parameters
-
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 iOS 2.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 iOS 2.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 iOS 2.0 and later.
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 is the array specifies the initial starting point.
count
-
The number of elements in the
points
array.
Discussion
This is a convenience function that adds a sequence of connected line segments to 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 iOS 2.0 and later.
See Also
Declared In
CGContext.h
CGContextAddLineToPoint
Appends a straight line segment from the current point to the provided point .
void CGContextAddLineToPoint ( CGContextRef c, CGFloat x, CGFloat y );
Parameters
-
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 iOS 2.0 and later.
See Also
Declared In
CGContext.h
CGContextAddPath
Adds a previously created Quartz path object to the current path in a graphics context.
void CGContextAddPath ( CGContextRef context, CGPathRef path );
Parameters
-
context
-
A graphics context .
path
-
A previously created Quartz path object. See CGPath Reference.
Discussion
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 iOS 2.0 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 iOS 2.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 iOS 2.0 and later.
See Also
Declared In
CGContext.h
CGContextAddRects
Adds a set rectangular paths to the current path.
void CGContextAddRects ( CGContextRef c, const CGRect rects[], size_t count );
Parameters
-
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 iOS 2.0 and later.
See Also
Declared In
CGContext.h
CGContextBeginPage
Starts a new page in a page-based graphics context.
void CGContextBeginPage ( CGContextRef c, const CGRect *mediaBox );
Parameters
-
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 passNULL
, 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 iOS 2.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 iOS 2.0 and later.
See Also
Declared In
CGContext.h
CGContextBeginTransparencyLayer
Begins a transparency layer.
void CGContextBeginTransparencyLayer ( CGContextRef context, CFDictionaryRef auxiliaryInfo );
Parameters
-
context
-
A graphics context.
auxiliaryInfo
-
A dictionary that specifies any additional information, or
NULL
.
Discussion
Until a corresponding call to CGContextEndTransparencyLayer
, all subsequent drawing operations in the specified context are composited into a fully transparent backdrop (which is treated as a separate destination buffer from the context).
After a call to CGContextEndTransparencyLayer
, the result is composited into the context using the global alpha and shadow state of the context. This operation respects the clipping region of the context.
After a call to this function, all of the parameters in the graphics state remain unchanged with the exception of the following:
-
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.
Tip: For best performance, make sure that you set the smallest possible clipping area for the objects in the transparency layer prior to calling CGContextBeginTransparencyLayer
.
Availability
- Available in iOS 2.0 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 iOS 2.0 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 iOS 2.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 iOS 2.0 and later.
See Also
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 iOS 2.0 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 iOS 2.0 and later.
See Also
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 iOS 2.0 and later.
See Also
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 iOS 2.0 and later.
See Also
Declared In
CGContext.h
CGContextConcatCTM
Transforms the user coordinate system in a context using a specified matrix.
void CGContextConcatCTM ( CGContextRef c, CGAffineTransform transform );
Parameters
-
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 iOS 2.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 iOS 2.0 and later.
See Also
Declared In
CGContext.h
CGContextConvertPointToUserSpace
Returns a point that is transformed from device space coordinates to user space coordinates.
CGPoint CGContextConvertPointToUserSpace ( CGContextRef c, CGPoint point );
Parameters
-
c
-
A graphics context.
point
-
The point, in device space coordinates, to transform.
Return Value
The coordinates of the point in user space coordinates.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
CGContext.h
CGContextConvertRectToDeviceSpace
Returns a rectangle that is transformed from user space coordinate to device space coordinates.
CGRect CGContextConvertRectToDeviceSpace ( CGContextRef c, CGRect rect );
Parameters
-
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 iOS 2.0 and later.
See Also
Declared In
CGContext.h
CGContextConvertRectToUserSpace
Returns a rectangle that is transformed from device space coordinate to user space coordinates.
CGRect CGContextConvertRectToUserSpace ( CGContextRef c, CGRect rect );
Parameters
-
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 iOS 2.0 and later.
See Also
Declared In
CGContext.h
CGContextConvertSizeToDeviceSpace
Returns a size that is transformed from user space coordinates to device space coordinates.
CGSize CGContextConvertSizeToDeviceSpace ( CGContextRef c, CGSize size );
Parameters
-
c
-
A graphics context.
size
-
The size, in user space coordinates, to transform.
Return Value
The size in device space coordinates.
Availability
- Available in iOS 2.0 and later.
See Also
Declared In
CGContext.h
CGContextConvertSizeToUserSpace
Returns a size that is transformed from device space coordinates to user space coordinates
CGSize CGContextConvertSizeToUserSpace ( CGContextRef c, CGSize size );
Parameters
-
c
-
A graphics context.
size
-
The size, in device space coordinates, to transform.
Return Value
The size in user space coordinates.
Availability
- Available in iOS 2.0 and later.
See Also
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 iOS 2.0 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 iOS 2.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
orkCGGradientDrawsAfterEndLocation
) 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 iOS 2.0 and later.
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
, orkCGPathEOFillStroke
. 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 iOS 2.0 and later.
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 iOS 2.0 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
orkCGGradientDrawsAfterEndLocation
) 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 iOS 2.0 and later.
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 iOS 2.0 and later.
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 iOS 2.0 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 iOS 2.0 and later.
See Also
Declared In
CGContext.h
CGContextEndTransparencyLayer
Ends a transparency layer.
void CGContextEndTransparencyLayer ( CGContextRef context );
Parameters
-
context
-
A graphics context.
Availability
- Available in iOS 2.0 and later.
See Also
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 iOS 2.0 and later.
See Also
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 iOS 2.0 and later.
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 iOS 2.0 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 iOS 2.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 iOS 2.0 and later.
See Also
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 iOS 2.0 and later.
See Also
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 iOS 2.0 and later.
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 iOS 2.0 and later.
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 iOS 2.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 iOS 2.0 and later.
See Also
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 iOS 2.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 iOS 2.0 and later.
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 iOS 2.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 iOS 2.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 iOS 2.0 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 iOS 2.0 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 iOS 2.0 and later.
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 iOS 2.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
, orkCGPathEOFillStroke
. 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 iOS 2.0 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 iOS 2.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 iOS 2.0 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 iOS 2.0 and later.
See Also
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 iOS 2.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 iOS 2.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 iOS 2.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 iOS 2.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 iOS 2.0 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 iOS 2.0 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 iOS 2.0 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 iOS 2.0 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) to1.0
(opaque). Values outside this range are clipped to0.0
or1.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 iOS 2.0 and later.
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 iOS 2.0 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 iOS 2.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) to1.0
(opaque). Values outside this range are clipped to0.0
or1.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
, andalpha
parameters.
Availability
- Available in iOS 2.0 and later.
See Also
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) to1.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) to1.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) to1.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) to1.0
(fully absorbs the secondary color).
alpha
-
A value that specifies the opacity level. Values can range from
0.0
(transparent) to1.0
(opaque). Values outside this range are clipped to0.0
or1.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
, andalpha
parameters.
Availability
- Available in iOS 2.0 and later.
See Also
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 iOS 2.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 iOS 2.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 iOS 2.0 and later.
See Also
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 iOS 2.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 iOS 2.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 iOS 2.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 iOS 2.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) to1.0
(absolute white). Values outside this range are clamped to0.0
or1.0
.
alpha
-
A value that specifies the opacity level. Values can range from
0.0
(transparent) to1.0
(opaque). Values outside this range are clipped to0.0
or1.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
andalpha
parameters.
Availability
- Available in iOS 2.0 and later.
See Also
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) to1.0
(absolute white). Values outside this range are clamped to0.0
or1.0
.
alpha
-
A value that specifies the opacity level. Values can range from
0.0
(transparent) to1.0
(opaque). Values outside this range are clipped to0.0
or1.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
andalpha
parameters.
Availability
- Available in iOS 2.0 and later.
See Also
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 iOS 2.0 and later.
See Also
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
, orkCGLineCapSquare
. See CGPath Reference.
Availability
- Available in iOS 2.0 and later.
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 of0
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, pass0
.
Availability
- Available in iOS 2.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
, orkCGLineJoinBevel
. See CGPath Reference.
Availability
- Available in iOS 2.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 iOS 2.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 iOS 2.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 iOS 2.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
, orkCGRenderingIntentSaturation
. 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 iOS 2.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) to1.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) to1.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) to1.0
(full intensity).
alpha
-
A value that specifies the opacity level. Values can range from
0.0
(transparent) to1.0
(opaque). Values outside this range are clipped to0.0
or1.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
, andalpha
parameters.
Availability
- Available in iOS 2.0 and later.
See Also
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) to1.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) to1.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) to1.0
(full intensity).
alpha
-
A value that specifies the opacity level. Values can range from
0.0
(transparent) to1.0
(opaque). Values outside this range are clipped to0.0
or1.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
, andalpha
parameters.
Availability
- Available in iOS 2.0 and later.
See Also
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 passNULL
as the color).
Availability
- Available in iOS 2.0 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 iOS 2.0 and later.
See Also
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 iOS 2.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 iOS 2.0 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 iOS 2.0 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 iOS 2.0 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 iOS 2.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 iOS 2.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 iOS 2.0 and later.
See Also
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 iOS 2.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
orkCGTextStroke
) that specifies how Quartz renders individual glyphs in a graphics context. See“CGTextDrawingMode”
for a complete list.
Availability
- Available in iOS 2.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 iOS 2.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 iOS 2.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 iOS 2.0 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 iOS 2.0 and later.
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 iOS 2.0 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 iOS 2.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 iOS 2.0 and later.
See Also
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 iOS 2.0 and later.
See Also
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 iOS 2.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 iOS 2.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 iOS 2.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 iOS 2.0 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 iOS 2.0 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 iOS 2.0 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 iOS 2.0 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 iOS 2.0 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 iOS 2.0 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 iOS 2.0 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 iOS 2.0 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 iOS 2.0 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 iOS 2.0 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 iOS 2.0 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 iOS 2.0 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 iOS 2.0 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 iOS 2.0 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 iOS 2.0 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 iOS 2.0 and later.
Declared in CGContext.h
.
kCGBlendModeClear
R = 0
Available in iOS 2.0 and later.
Declared in CGContext.h
.
kCGBlendModeCopy
R = S
Available in iOS 2.0 and later.
Declared in CGContext.h
.
kCGBlendModeSourceIn
R = S*Da
Available in iOS 2.0 and later.
Declared in CGContext.h
.
kCGBlendModeSourceOut
R = S*(1 - Da)
Available in iOS 2.0 and later.
Declared in CGContext.h
.
kCGBlendModeSourceAtop
R = S*Da + D*(1 - Sa)
Available in iOS 2.0 and later.
Declared in CGContext.h
.
kCGBlendModeDestinationOver
R = S*(1 - Da) + D
Available in iOS 2.0 and later.
Declared in CGContext.h
.
kCGBlendModeDestinationIn
R = D*Sa
Available in iOS 2.0 and later.
Declared in CGContext.h
.
kCGBlendModeDestinationOut
R = D*(1 - Sa)
Available in iOS 2.0 and later.
Declared in CGContext.h
.
kCGBlendModeDestinationAtop
R = S*(1 - Da) + D*Sa
Available in iOS 2.0 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 iOS 2.0 and later.
Declared in CGContext.h
.
kCGBlendModePlusDarker
R = MAX(0, 1 - ((1 - D) + (1 - S)))
Available in iOS 2.0 and later.
Declared in CGContext.h
.
-
R = MIN(1, S + D)
Available in iOS 2.0 and later.
Declared in
CGContext.h
.
kCGBlendModePlusLighter
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 iOS 2.0 and later.
Declared in CGContext.h
.
kCGInterpolationNone
No interpolation.
Available in iOS 2.0 and later.
Declared in CGContext.h
.
kCGInterpolationLow
A low level of interpolation quality. This setting may speed up image rendering.
Available in iOS 2.0 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 iOS 4.0 and later.
Declared in CGContext.h
.
-
A high level of interpolation quality. This setting may slow down image rendering.
Available in iOS 2.0 and later.
Declared in
CGContext.h
.
kCGInterpolationHigh
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 iOS 2.0 and later.
Declared in CGContext.h
.
kCGTextStroke
Perform a stroke operation on the text.
Available in iOS 2.0 and later.
Declared in CGContext.h
.
kCGTextFillStroke
Perform fill, then stroke operations on the text.
Available in iOS 2.0 and later.
Declared in CGContext.h
.
kCGTextInvisible
Do not draw the text, but do update the text position.
Available in iOS 2.0 and later.
Declared in CGContext.h
.
kCGTextFillClip
Perform a fill operation, then intersect the text with the current clipping path.
Available in iOS 2.0 and later.
Declared in CGContext.h
.
kCGTextStrokeClip
Perform a stroke operation, then intersect the text with the current clipping path.
Available in iOS 2.0 and later.
Declared in CGContext.h
.
kCGTextFillStrokeClip
Perform fill then stroke operations, then intersect the text with the current clipping path.
Available in iOS 2.0 and later.
Declared in CGContext.h
.
-
Specifies to intersect the text with the current clipping path. This mode does not paint the text.
Available in iOS 2.0 and later.
Declared in
CGContext.h
.
kCGTextClip
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 iOS 2.0 and later.
Declared in CGContext.h
.
-
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 iOS 2.0 and later.
Declared in
CGContext.h
.
kCGEncodingMacRoman
Discussion
For more information on setting the font in a graphics context, see CGContextSelectFont
.