Creating Shadings

With the CGFunction in hand, the next step in drawing a shading is to create the shading object itself. Quartz 2D includes separate routines for creating axial and radial shadings. The primary difference in the parameters between the two routines is the geometrical information that defines where the shading will draw in the context.

There is another option that affects the way Quartz 2D draws shadings that has not yet been discussed. As part of creating a shading, you indicate whether or not you want the colors of the shading to extend beyond its end points. You extend the blend on the starting and ending sides independently. Figure 13.4 shows the effect of extending colors for both shading shapes.

Figure 13.4. Extending Axial and Radial Shadings

The shadings in Figure 13.4 are drawn on top of a context that is filled with a checkerboard pattern. The shadings on the left do not have the shadings extended. The shadings stop at the bounds of their defining geometry. The shadings on the right include extensions. The colors at either end of the shading extend as far as they can filling the context and obscuring the checkered background.

Axial Shadings

As seen earlier, Quartz defines the geometry of an axial shading with a line segment that runs perpendicular to the colors in the shading. Correspondingly, when you create the shading, you supply the endpoints of that line. In addition, you define the color space that the shading will use and the function that returns colors in that space. A complete example of creating a shading is shown in Listing 13.3.

Listing 13.3. Creating an Axial Shading

CGRect shadingStage = mediaBox; CGPoint startPoint = CGPointMake(     shadingStage.origin.x + (shadingStage.size.width / 4),     shadingStage.origin.y + (shadingStage.size.height / 4)); CGPoint endPoint = CGPointMake(     CGRectGetMaxX(shadingStage) - (shadingStage.size.width / 4),     CGRectGetMaxY(shadingStage) - (shadingStage.size.height / 4)); CGColorSpaceRef colorSpace =     CGColorSpaceCreateWithName(kCGColorSpaceGenericGray); CGShadingRef shadingObject =     CGShadingCreateAxial(colorSpace, startPoint,                            endPoint, rampShading,                            false, false); CGColorSpaceRelease(colorSpace); colorSpace = NULL; 

This code creates the unextended axial shading in Figure 13.4. The code begins by selecting a start and end points for the shading based on the bounding box of the illustration. It then creates the generic gray color space used by this particular shading. The routine that creates the shading object itself is CGShadingCreateAxial. The color space and endpoints are accompanied by the CGFunctionRef, named rampShading, and two boolean parameters. The booleans ask Quartz not to extend the colors of the shading.

Radial Shadings

Creating a radial works the same way as creating an axial shading. The only difference is that the defining geometry is two circles instead of a single line. Each of the circles is defined by a center point and a radius. Listing 13.4 is the code that created the shadings for the unextended radial portion of Figure 13.4.

Listing 13.4. Creating a Radial Shading

CGColorSpaceRef colorSpace =     CGColorSpaceCreateWithName(kCGColorSpaceGenericGray); CGShadingRef shadingObject =     CGShadingCreateRadial(            colorSpace,            CGPointMake(50, 50), 10,            CGPointMake(50, 50), 50,            rampShading, false, false); 

This listing is much shorter than the axial sample, primarily because the geometry is easier to create. The two circles that define the shading share a center point, and only their radii change. The starting circle uses a radius of 10, while the ending circle uses a radius of 50. Beyond that, the parameters for CGShadingCreateRadial are identical to those used in Listing 13.3.

Drawing Shadings

Drawing a shading is a very simple operation after you've created it. To draw a shading you simply call the CGContext routine CGContextDrawShading. This routine takes two parameters, a context, and the shading you want to draw into it.

If you look at the shadings in Figure 13.4, you will notice that they fill the context, particularly those where you've indicated that the colors should extend beyond the edges of the shading's geometry. Unless you are using shading as a background, you will probably set up a clipping path first and then draw the shading inside of that.