Creating Patterns

Quartz 2D keeps track of all the information needed to draw a pattern in an instance of the CGPattern opaque data type. To draw a pattern, you crate an instance of this opaque data type by calling CGPatternCreate and supplying all the relevant options.

The Pattern Cell Callback

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.

Putting It Together

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

Listing 13.5. A CGPatternCreate Sample

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.