CGContext Reference

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.

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.

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.

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.

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.

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.

Discussion

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

Discussion

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

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.

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.

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.

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.

Discussion

Anti-aliasing is a graphics state parameter.

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.

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.

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.

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.

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.

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.

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.

Discussion

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

This parameter is part of the graphics state.

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.

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.

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.

Discussion

This is a convenience function that adds a sequence of connected line segments to a path, using the following operation:

Discussion

After adding the line segment, the current point is set to the endpoint of the line segment.

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.

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.

Discussion

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

Discussion

This is a convenience function that adds an array of rectangles to a path, using the following operation:

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.

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.

Discussion

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

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.

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.

Discussion

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

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.

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.

Discussion

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

Discussion

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

Discussion

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

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.

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.

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.

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.

Discussion

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

Discussion

This function is equivalent to the following code:

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

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.

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.

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.

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.

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.

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.

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.

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.

Discussion

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

Discussion

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

When you call this function, two things happen:

• Quartz sets the current fill color space to DeviceCMYK.

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

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.

Discussion

When you call this function, two things happen:

• Quartz sets the current stroke color space to DeviceCMYK.

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

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.

Discussion

When you call this function, two things happen:

• Quartz sets the current fill color space to DeviceGray.

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

Discussion

When you call this function, two things happen:

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

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

Discussion

When you call this function, two things happen:

• Quartz sets the current fill color space to DeviceRGB.

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

Discussion

When you call this function, two things happen:

• Quartz sets the current stroke color space to DeviceRGB.

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

Discussion

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

To turn off shadowing:

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

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

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.

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.

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.

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

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.

Discussion

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

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.

Discussion

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