Fills

Filling a path colors the interior of that path. There are several techniques that Quartz 2D can use to fill a path. By far the most common is simply filling the path with a solid color. Quartz can use any color it can represent to fill a path. In particular, the alpha channel in Quartz 2D's color model offers the advantage of being able to use translucent colors to fill paths.

Quartz 2D can fill paths with more than just solid colors. If you are working through the base Core Graphics APIs, you also can fill a path with a repeating pattern or a smooth gradient of colors called a shading. To use these special fill types, an application must create a number of supporting objects. For that reason, discussion of shadings and patterns is deferred to Chapter 13, "Shadings and Patterns."

Regardless of what you use to fill the path, however, the computer has to determine, "What part of user space is the inside of the path?" For simple paths, shapes like rectangles, circles, and other basic closed loops, it is pretty easy to figure out what part of user space constitutes the interior of the path. For more complex paths such as those with lots of self-intersections or paths that consist of more than one contour, the question becomes much less intuitive. In every case, Quartz uses a technique called winding rules to find the interior of a path.

Winding Rules

The winding rules in Quartz 2D are based on simple tests. The tests take under consideration a point in user space and a path. They examine the way the path winds around that point and determine whether or not that particular point is inside the path. Quartz 2D is not actually going to apply the winding rules to each point it wants to color. That would take too long. These tests are really a conceptual model that help to describe how the winding rules affect drawing.

Quartz 2D supports two different winding rules. They are called the Even/Odd winding rule and the Non-Zero winding rule. Figure 7.1 demonstrates each of these.

Figure 7.1. Winding Fills and the Interior of Paths

To help describe the differences between the two techniques, this diagram has been annotated with some additional information. The dots in Figure 7.1 represent the "particular points" to which we're going to apply the winding tests.

The tests also rely on a line that extends from the point of interest in an arbitrary direction. Figure 7.1 includes arrows that show the (marginally) arbitrary directions that our lines extend from the points. The star-shaped path in the top of the figure is single, self-intersecting contour. The hexagonal paths, in the bottom half of the figure are each built from two contours.

Direction arrowheads have been left off in the left-hand side of the figure because the Even/Odd winding fill produces the same results regardless of the contour directions. The test starts out at the point of interest and travels along the direction line. Each time the line crosses a segment of the path, the test increments a counter. Once outside of the path, if the number of crossings is an odd number, the starting point must have been inside of the path (otherwise it was outside). In Figure 7.1, the paths each cross their reference lines twice so both points are outside of their respective paths. This leads to the observation that both the star and the hexagon have holes in their centers when tested filled with the Even/Odd winding rule.

The Non-Zero winding test uses a similar technique but takes the directions of the contours into account. The test proceeds much as in the Even/Odd winding test, but this time, when the path crosses the reference line, if it is travelling in one direction (say from the top of the line to the bottom in our diagram), then we increment the winding counter. If the path crosses the line in the other direction, the test subtracts one from the counter. After taking into account all the path crossings, if the winding number is zero, the starting point was outside of the path.

The hexagonal paths in the right side of Figure 7.1 demonstrate the importance of path direction in the Non-Zero winding fill rule. Note that when both contours in the hexagonal path are in the same direction, the center of the shape is inside the path. If the contours are in opposite directions, however, the path contains a hole.

Using the Core Graphics APIs directly you select the winding rule you want to use with a path by choosing the appropriate routine. For example, if you want to fill the current path using the Non-Zero winding fill rule, you would simply call CGContextFillPath. If you want to use the Even/Odd rule, however, you would call CGContextEOFillPath. (Similar routines are available for clipping, CGContextClip and CGContextEOClip).

Using an NSBezierPath instance, you select the appropriate winding rule by calling the method setWindingRule:. This method takes one of two constants as a parameter, either NSNonZeroWindingRule or NSEvenOddWindingRule.

Filling Routines

CGContextFillPath and CGContextEOFillPath are two of the routines that ask a CGContext to fill a path. These two routines allow you to fill a path with a solid color or with a pattern.

When using the Core Graphics APIs, the computer uses the CGContext's current fill color to fill the path. The fill color is part of the context's graphics state. There are a number of routines in the CGContext API that allow you to specify a fill color:

CGContextSetFillColorWithColor This routine allows you to set the current fill color using a CGColorRef. A CGColorRef encapsulates both a color space and color components so this routine completely defines the fill color.

CGContextSetFillColor This routine allows you to specify the components of the color to use as a fill color. It accepts a C-style array of floating point color values. The number of elements in this array depends on the current fill color space. If the color space requires N components to represent a color, you must supply N+1 components in the array. The last component is used to specify the alpha value for the color. For example, RGB color spaces require three components (red, green, and blue) to specify a color. If the CGContext is currently using an RGB color space, you will need to supply four components to CGContextSetFillColor. To change the fill color space of a CGContext, you use the routine CGContextSetFillColorSpace.

CGContextSetGrayFillColor This routine sets the current fill color space of the context to a Device Gray color space and changes the current fill color to a gray color based on the arguments to the routine.

CGContextSetRGBFillColor This routine changes the current fill color space to Device RGB and changes the current fill color to the one specified in the argument list.

CGContextSetCMYKFillColor As you might already have guessed, this routine changes the current fill color space to Device CMYK and then sets the current fill color to the one specified in the routine's parameters.

When working with Cocoa, you specify the fill color of the current NSGraphicsContext using NSColor's set or setFill methods. An NSColor object encapsulates all the color space and color value information needed to completely specify a color. The set method changes both the fill and stroke colors of the current context while the setFill method allows you to change the fill color independently. After you have established the fill color, you simply call the fill method of the NSBezierPath instance you want to draw.