The first step in creating shading is defining the color function. Unfortunately, if you read the description of the CGFunction opaque data type in the header file, you may find yourself lost in a sea of mathematical rigor. The actual idea that a CGFunctionRef embodies is actually pretty simple.

CGFunction is actually a generic mechanism for representing any function that takes an arbitrary number of floating point inputs and returns an arbitrary number of floating point outputs. When you create a CGFunction object, you indicate how many inputs and how many outputs your function will have. You also provide valid ranges for the input and output values.

The part of the CGFunctionRef that performs the color calculations is a callback routine in your application that has the following signature:

void CGFunctionEvaluateCallback(void *info, const float *in, float *out)

The first parameter to this routine is a block of arbitrary information that your application defines for its own purposes while evaluating the function. The second and third parameters represent C-style arrays of floating point values. These arrays are where your function receives its input values and stores the results of the function. In the case of the color function for a shading, the function you create takes a single input, the position between the start and end of the blend, and returns the components of a color. The number of color components the function must return depends on the color space the shading draws in. For example in an RGB shading, the function will return four values, three for the color channels and one for the alpha value.

Note

Shadings can have partially transparent areas if the color function simply specifies an alpha value in the color returned by the color function. Unfortunately, many printers have trouble printing graphics containing alpha channels, including shadings. If you run into this problem in your own application, you can work around the problem by drawing the shading into an image and drawing that image in the place of the shading. Unfortunately, this representation of the shading will draw with a fixed resolution.

If the function accepts a block of user data, the CGFunction object can keep track of another callback to dispose of the data when the CGFunction is no longer needed. That callback has the signature

void CGFunctionReleaseInfoCallback(void *info)

The system will call not call this routine until it destroys the CGFunction object. This gives the application the opportunity to clean up any resources stored in that data.

All of these input values come together in a call to CGFunctionCreate. Listing 13.1 shows how you might create a CGFunction for supplying the color values of an RGB shading.

// Tell the OS that our function expects one input value,
// in the domain [0,6], and returns values in the range [0,1]
const float kValidDomain[2] = { 0, 6 };
const short kChannelsPerColor = 4; // R, G, B, A
const float kValidRange[kChannelsPerColor][2] = {
                           { 0, 1 },
                           { 0, 1 },
                           { 0, 1 },
                           { 0, 1 } };

CGFunctionCallbacks kRGBShadingCallbackRoutines =
{
    0,                     // Callback Structure Version
    RainbowShading,        // Evaluation Callback
    NULL                   // Release User Data Callback
};
CGFunctionRef rainbowShading =
    ::CGFunctionCreate(
           NULL,
           1,
           kValidDomain,
           kChannelsPerColor,
           (float *) kValidRange,
           &kRGBShadingCallbackRoutines);

The constants at the top of Listing 13.1 define the logistics of the function you’re creating. The function will accept a single input, and kValidDomain defines the valid range for that input. For reasons that will become clear, you need to define the function so that the input extends from 0 at the start of the shading to 6.0 at its end. As mentioned previously, the function will return four output values representing an RGB color with Alpha. The kValidRange array provides the valid ranges for each output value. Because these represent the color components of a Quartz color, they fall in the range 0 to 1. The callbacks passed to a CGFunction are collected into a CGFunctionCallbacks structure. The first field of this structure is a version placeholder that allows Apple to change the definition of this structure in the future. In this case structure version 0 is being used. The next field is the function evaluation callback. RainbowShading is the name of a routine that computes the shading color. This shading function doesn’t pass application data to the evaluation routine, so the callback that releases the info data structure is not used.

The routine CGFunctionCreate builds the final object from all of these elements. The first parameter to CGFunctionCreate is the application-specific information pointer. Because it’s unused, NULL is passed. The argument is the number of input parameters the function expects and the valid range for those parameters. Following this, the routine call specifies the number of output values and their valid domains. The final parameter, of course, is the evaluation routine.

The CGFunctionRef just created uses the RainbowShading callback to evaluate the function. That routine is given in Listing 13.2.

void RainbowShading(void *info, const float *in, float *out)
{
   // colors of the knots in parameter space
   static float const shadingColors[7][4] = {
           { 1.0, 0.0, 0.0, 1.0}, // red
           { 1.0, 0.5, 0.0, 1.0}, // orange
           { 1.0, 1.0, 0.0, 1.0}, // yellow
           { 0.0, 1.0, 0.0, 1.0}, // green
           { 0.0, 0.0, 1.0, 1.0}, // blue
           { 0.5, 0.0, 1.0, 1.0}, // indigo
           { 0.5, 0.0, 0.5, 1.0}, // violet
   };

   // Retrieve the function's input (a single float in the
   // domain [0,6])
   float parameterValue = *in;

   // Use the input to find the index of the color on the left side
   // of the current sub-interval
   int colorIndex = (int)parameterValue;
   if(colorIndex == 6) {
           colorIndex = 5;
   }

   // We subtract of the integer part and get a sub-interval scale
   // between 0 and 1.0
   float t = parameterValue - colorIndex;

   // Use all those calculations to create a color value that is the
   // result of this function. We copy each component into the function
   // result array.
   for(unsigned short ctr = 0; ctr < 4; ctr++) {
           out[ctr] =
                   (1.0 - t) * shadingColors[colorIndex][ctr] +
                   (t) * shadingColors[colorIndex + 1][ctr];
   }
}

This routine defines a color sequence that has all the colors of the rainbow. The routine begins with an array of color values that will make the shading. The input parameter will be between 0 and 6 because that’s the way the function was set up when it was created. This value is used to select the interval inside of the color array and the position within that interval that the code is looking for. The loop at the end of the array calculates an interpolated value for each component of the color to be returned. This particular shading example uses a fixed array of colors, if the array of source colors was passed in as part of the info parameter, but the code could create many function objects that use the same callback to generate shadings with many different colors.

Note

When Quartz sends your shading object to a PDF, it tries to convert your shading function into a representation that can be stored in the file directly. Unfortunately, it is possible for your application to create functions that are too complex for this mechanism. If you are drawing a shading into a PDF and find that the colors in the PDF do not match your color function, you may have a function that is too complex. If you run into this problem, one potential solution is to render the shading into an image or CGLayer and then draw that into the PDF.

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.

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.

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.

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

A cell is simply a rectangular drawing space that contains Quartz 2D graphics. For colored patterns, the cell’s graphic will define both color and shape information. For a stencil pattern, the cell’s graphic includes shapes but no colors. Figure 13.5 contains a very simple example of a cell that contains some basic line art.

Figure 13.5. A Simple Cell

In this figure, and in some of the figures to follow, a dotted line has been added that shows where the boundary of the cell is. In this case the bounding rectangle of the cell is 48 points square. For this example, and cell, a color cell is used.

If you asked Quartz 2D to draw this cell in a pattern with a cell spacing of 48 points in the x and y directions, the results might look something like this

Figure 13.6. Pattern Drawn with 48 Point Spacing

The left side of this illustration shows the cells with their boundaries marked. The rectangle on the right shows how Quartz 2D might draw this pattern when it is used to fill a rectangle.

One of the drawing options you can change when you create a pattern is the spacing of the cells. You can change the horizontal and vertical spacing of the pattern’s cell independently. If you ask Quartz to draw the pattern with a horizontal spacing of 72 points and a vertical spacing of 60 points, the resulting pattern might look something like this

Figure 13.7. Pattern Drawn with a Different Spacing

The computer takes the additional spacing and uses it to insert blank space between the pattern cells.

In this example, the spacing is the same size as the cell’s height and width, but you could just as easily use values that are smaller. If the graphics of adjacent cells overlap, Mac OS X will still draw the pattern to the best of its ability. However, the order in which Quartz draws the pattern is undefined. The effect you get from drawing an overlapping pattern to the screen may not match the effect of drawing that pattern to a PDF or the printer.

In addition to changing the spacing of a pattern, you can also apply a transformation to it. The tiled graphic of a pattern is drawn in its own coordinate space, the pattern space. A Quartz 2D application can supply an affine transform that defines how the computer maps the tiled graphic from pattern space to user space. You can use this to achieve patterns where the tiling consists of just about any parallelogram. If you draw the tiling of Figure 13.6 into a rectangle, applying a transformation between pattern space and user space at the same time, the results might look something like Figure 13.8.

Figure 13.8. The Pattern Drawn with a Transformation

When you draw a pattern with a transformation, the mathematics involved can introduce small errors into the spacing of a pattern, particularly when working with bitmap contexts. Quartz can compensate for these spacing errors by slightly warping the cells in-place within the pattern. Your application has some control over whether or not the computer makes this trade-off. Quartz 2D defines three constants that affect the spacing versus shape trade-off.

In introducing patterns the difference between colored and stencil patterns were briefly discribed. A color pattern is one where the color of the cell is defined as part of that cell. In a stencil pattern, your cell defines the shapes that you want to draw, but all of the shapes in the cell are drawn in the same color. You supply the color when you draw the pattern, not when the cell is created.

The cell defined in Figure 13.5 is a color pattern cell. The cell itself contains two colors, a gray and black. The figures that follow show the effects of using this cell in a colored pattern.

Figure 13.9 shows a stencil cell and several rectangles that are filled with a stencil pattern using that cell. In each rectangle is drawn the stencil pattern with a different color. Each rectangle was drawn using the same pattern, with just a different color supplied each time pattern was drawn.

Figure 13.9. A Stencil Pattern Drawn with Several Colors

A callback routine provides the graphics for a pattern cell. The callback has the routine signature

void DrawPatternCellCallback(void *info, CGContextRef cgContext);

Like the callback for a CGFunction, the pattern cell callback accepts a pointer to a block of data that the application can use for its own purposes. The second parameter is a CGContext. The callback draws the graphics of the cell into that context it receives in the second parameter. As is the custom in Quartz 2D, when the system passes in the context, the origin is at the lower left corner of the cell. As usual, however, transformations can relocate the origin to make it easier to draw into the cell.

The pattern also can store a pointer to the routine that disposes of the application specific info when the pattern gets destroyed. The signature of that function is

void ReleasePatternInfoCallback(void *info);

When you create a CGPattern, you provide these callbacks to Quartz 2D by packing the routine pointers into an instance of the CGPatternCallbacks structure. This structure also has a field that indicates the version of the structure you are using.

Listing 13.5 contains the code used to create the pattern drawn in Figure 13.2 at the beginning of the chapter.

const float kPatternWidth = 100;
const float kPatternHeight = 100;
const bool  kPatternIsColored = true;

const CGRect patternBounds =
        CGRectMake(0, 0, kPatternWidth, kPatternHeight);
const CGPatternCallbacks kPatternCallbacks =
{
        0,
        DrawCirclesAndTriangle,
        NULL
};

CGAffineTransform patternTransform = CGAffineTransformIdentity;
patternTransform = CGAffineTransformMakeRotation( -pi / 4.0);
patternTransform = CGAffineTransformScale(patternTransform,
        0.33333, 0.5);
patternTransform = CGAffineTransformRotate(patternTransform,
        pi / 4.0);

CGPatternRef pattern = CGPatternCreate(
        NULL,
        patternBounds,
        patternTransform,
        kPatternWidth, // used as horizontal spacing
        kPatternHeight,// used as vertical spacing
        kCGPatternTilingNoDistortion,
        kPatternIsColored,
        &kPatternCallbacks);

There are many constants in the code above which can lead to the impression that it is more complex than it is. The focus of the listing is the call to CGPatternCreate at the end. The first parameter is the application specific info data that Quartz will pass to your pattern callback. That info is not used in this sample, so NULL is passed in. The second parameter is a rectangle that defines the bounds of the pattern cell. The third parameter is the CGAffineTransform that maps the pattern’s graphics from pattern space to user space. In this case a simple transformation that skews the graphic slightly is passed.

The pattern width and pattern height are used as the spacing parameters. This corresponds to the options used to draw Figure 13.6. You pass the spacing constant that asks Quartz to ensure your shapes are not distorted, at the expense of potential spacing inaccuracies.This pattern procedure is going to draw a colored cell, so you create a colored pattern instead of a stencil pattern.

The last parameter, of course, is the structure that describes the pattern callbacks. The routine that draws the cell in this case is DrawCirclesAndTriangle.

To create a pattern color space, you call the routine CGColorSpaceCreatePattern. This routine accepts a single parameter. For colored patterns, you should pass NULL as the base color space. If you are using a stencil pattern, you should pass a traditional color space like Generic RGB or the color space of the main display. When you draw the stencil pattern you will specify the color with which Quartz should draw the stencil by specifying the components of a color from this color space.

After creating the pattern color space, your code can use CGContextSetFillCol orSpace and CGContextSetStrokeColorSpace to indicate that you want to use a pattern for fills or strokes, respectively.

After you have the color space settings of the context set up, you can set the current fill pattern for the context by calling CGContextSetFillPattern and the current stroke pattern with CGContextSetStrokePattern. Each of these routines accept the context you wish to change, a CGPatternRef, and an array of floating point values.

The values you supply in the floating point array depend on what type of pattern you are working with. If you are working with a colored pattern, then you should pass in a single floating point value that indicates the alpha value you want to use for your colored pattern. For example, if you pass in 0.5 as the alpha value, the computer will draw your pattern with 50% translucency.

If you are working with a stencil pattern, the floating point array is where you specify the color Quartz should apply to the stencil. You will need to specify the components of a color in the color space you provided as a base to the pattern color space you created. For example, if you indicated that your pattern’s base space was Generic CMYK, your floating point array would have five values in it—one for each of the four color components and one for the alpha value.

After calling CGContextSetFillPattern or CGContextSetStrokePattern, any strokes or fills that your code calls for will draw with the current pattern. Listing 13.6 ties together the entire process of drawing with a colored pattern. This is part of the code used to draw Figure 13.2.

float opaque = 1.0;
CGColorSpaceRef patternSpace = CGColorSpaceCreatePattern(NULL);
CGContextSetFillColorSpace(inContext, patternSpace);
CGContextSetFillPattern(inContext, pattern, &opaque);
CGContextAddRect(inContext, bounds);
CGContextFillPath(inContext);
CGColorSpaceRelease(patternSpace);
CGPatternRelease(pattern);

You are drawing a colored pattern so you pass NULL to CGColorSpaceCreatePattern. You then tell the computer that we are interested in using the color space you’ve created as the fill color space. The pattern passed to CGContextSetFillPattern is the same pattern created in Listing 13.5. To use the pattern, you simply add a rectangular path to the current context and then call CGContextFillPath. Quartz will fill the path with your pattern. Upon returning, you clean up the pattern space and the pattern.

Listing 13.7 is a block of code that draws a stencil cell in seven different colors. This listing was taken from the Patterns code sample from the code sample CD.

// To draw the pattern we need a pattern color space
CGColorSpaceRef baseColorSpace = CGColorSpaceCreateWithName(
        kCGColorSpaceGenericRGB);
CGColorSpaceRef patternSpace = CGColorSpaceCreatePattern(
        baseColorSpace);
CGColorSpaceRelease(baseColorSpace);
baseColorSpace = NULL;

CGContextSetFillColorSpace(inContext, patternSpace);
CGColorSpaceRelease(patternSpace);
patternSpace = NULL;

static float const rainbowColors[7][4] = {
        { 1.0, 0.0, 0.0, 1.0 }, // red
        { 1.0, 0.5, 0.0, 1.0 }, // orange
        { 1.0, 1.0, 0.0, 1.0 }, // yellow
        { 0.0, 1.0, 0.0, 1.0 }, // green
        { 0.0, 0.0, 1.0, 1.0 }, // blue
        { 0.5, 0.0, 1.0, 1.0 }, // indigo
        { 0.5, 0.0, 0.5, 1.0 }, // violet
};
// Add a path to fill with our pattern and fill it.
float rectHeight = bounds.size.height / 7;
for(short ctr = 0; ctr < 7; ctr++) {
        CGRect patternBounds = CGRectMake(
                       bounds.origin.x,
                       bounds.origin.y + ctr * rectHeight,
                       bounds.size.width,
                       rectHeight);

        CGContextSetFillPattern(inContext,
               pattern, rainbowColors[ctr]);
        CGContextAddRect(inContext, patternBounds);
        CGContextFillPath(inContext);
}

CGPatternRelease(pattern);
pattern = NULL;

This code listing begins much like the previous one, with the construction of a pattern color space. In this case, because you are using a stencil pattern, you need to provide a base color space (Generic RGB has been chosen here). As before, after creating the pattern color space, you set up the context to use that the fill color space for the port.

The large array in the middle of the code example simply defines seven RGBA colors (the same ones used in the shading example). The loop at the bottom is responsible for drawing the pattern in a series of seven rectangles. To draw each rectangle, you set the current fill pattern and call CGContextSeFillPattern to pass one of the seven colors as the color the computer should apply through the stencil. The pattern is drawn, then, using CGContextFillPath.