CGPattern Reference

Overview

The CGPatternRef opaque type represents a pattern that you can use to stroke along or fill in a graphics path. Quartz tiles the pattern cell for you, based on parameters you specify when you call CGPatternCreate.

To create a dashed line, see CGContextSetLineDash in CGContext Reference.

Functions by Task

Creating a Pattern

• CGPatternCreate

Getting the CFType ID

• CGPatternGetTypeID

Retaining and Releasing a Pattern

• CGPatternRetain
• CGPatternRelease

Functions

CGPatternCreate

Creates a pattern object.

CGPatternRef CGPatternCreate (
   void *info,
   CGRect bounds,
   CGAffineTransform matrix,
   CGFloat xStep,
   CGFloat yStep,
   CGPatternTiling tiling,
   bool isColored,
   const CGPatternCallbacks *callbacks
);

Parameters

info

A pointer to private storage used by your pattern drawing function, or NULL. For more information, see the discussion below.

bounds

The bounding box of the pattern cell, specified in pattern space. (Pattern space is an abstract space that maps to the default user space by the transformation matrix you specify with the matrix parameter.) The drawing done in your pattern drawing function is clipped to this rectangle.

matrix

A matrix that represents a transform from pattern space to the default user space of the context in which the pattern is used. If no transform is needed, pass the identity matrix.

xStep

The horizontal displacement between cells, specified in pattern space. For no additional horizontal space between cells (so that each pattern cells abuts the previous pattern cell in the horizontal direction), pass the width of the pattern cell.

yStep

The vertical displacement between cells, specified in pattern space. For no additional vertical space between cells (so that each pattern cells abuts the previous pattern cell in the vertical direction), pass the height of the pattern cell.

tiling

A CGPatternTiling constant that specifies the desired tiling method. For more information about tiling methods, see “Tiling Patterns”.

isColored

If you want to draw your pattern using its own intrinsic color, pass true. If you want to draw an uncolored (or masking) pattern that uses the fill or stroke color in the graphics state, pass false.

callbacks

A pointer to a pattern callback function table—your pattern drawing function is an entry in this table. See CGPatternCallbacks for more information about callback function tables for patterns.

Discussion

Quartz calls your drawing function at the appropriate time to draw the pattern cell. A pattern cell must be invariant—that is, the pattern cell should be drawn exactly the same way each time the drawing function is called.

The appearance of a pattern cell is unaffected by changes in the graphics state of the context in which the pattern is used.

See CGPatternDrawPatternCallback for more information about pattern drawing functions.

Related Sample Code

• GeekGameBoard

CGPatternGetTypeID

Returns the type identifier for Quartz patterns.

CFTypeID CGPatternGetTypeID (
   void
);

CGPatternRelease

Decrements the retain count of a Quartz pattern.

void CGPatternRelease (
   CGPatternRef pattern
);

Parameters

pattern

The pattern to release.

Discussion

This function is equivalent to CFRelease, except that it does not cause an error if the pattern parameter is NULL.

Related Sample Code

• GeekGameBoard

CGPatternRetain

Increments the retain count of a Quartz pattern.

CGPatternRef CGPatternRetain (
   CGPatternRef pattern
);

Parameters

pattern

The pattern to retain.

Discussion

This function is equivalent to CFRetain, except that it does not cause an error if the pattern parameter is NULL.

Callbacks

CGPatternDrawPatternCallback

Draws a pattern cell.

typedef void (*CGPatternDrawPatternCallback) (
   void * info,
   CGContextRef context
);
   

If you name your function MyDrawPattern, you would declare it like this:

void MyDrawPattern (
   void * info,
   CGContextRef context
);

Parameters

info

A generic pointer to private data associated with the pattern. This is the same pointer you supplied to CGPatternCreate.

context

The graphics context for drawing the pattern cell.

Discussion

When a pattern is used to stroke or fill a graphics path, Quartz calls your custom drawing function at the appropriate time to draw the pattern cell. The cell should be drawn exactly the same way each time the drawing function is called.

In a drawing function associated with an uncolored pattern, you should not attempt to set a stroke or fill color or color space—if you do so, the result is undefined.

To learn how to associate your drawing function with a Quartz pattern, see CGPatternCreate and CGPatternCallbacks.

CGPatternReleaseInfoCallback

Release private data or resources associated with the pattern.

typedef void (*CGPatternReleaseInfoCallback) (
   void * info
);
   

If you name your function MyCGPatternReleaseInfo, you would declare it like this:

void MyCGPatternReleaseInfo (
   void * info
);

Parameters

info

A generic pointer to private data shared among your callback functions. This is the same pointer you supplied to CGPatternCreate.

Discussion

Quartz calls your release function when it frees your pattern object.

To learn how to associate your release function with a Quartz pattern, see CGPatternCreate and CGPatternCallbacks.

Data Types

CGPatternRef

An opaque type that represents a pattern.

typedef struct CGPattern * CGPatternRef;

CGPatternCallbacks

A structure that holds a version and two callback functions for drawing a custom pattern.

struct CGPatternCallbacks {
   unsigned int version;
   CGPatternDrawPatternCallback drawPattern;
   CGPatternReleaseInfoCallback releaseInfo;
};
typedef struct CGPatternCallbacks CGPatternCallbacks;

Fields

version

The version of the structure passed in as a parameter to the CGPatternCreate. For this version of the structure, you should set this value to zero.

drawPattern

A pointer to a custom function that draws the pattern. For information about this callback function, see CGPatternDrawPatternCallback.

releaseInfo

An optional pointer to a custom function that’s invoked when the pattern is released. CGPatternReleaseInfoCallback.

Discussion

You supply a CGPatternCallbacks structure to the function CGPatternCreate to create a data provider for direct access. The functions specified by the CGPatternCallbacks structure are responsible for drawing the pattern and for handling the pattern’s memory management.

Constants

Tiling Patterns

Different methods for rendering a tiled pattern.

enum CGPatternTiling {
   kCGPatternTilingNoDistortion,
   kCGPatternTilingConstantSpacingMinimalDistortion,
   kCGPatternTilingConstantSpacing
};
typedef enum CGPatternTiling CGPatternTiling;

Constants

kCGPatternTilingNoDistortion

The pattern cell is not distorted when painted. The spacing between pattern cells may vary by as much as 1 device pixel.

Available in Mac OS X v10.1 and later.

Declared in CGPattern.h.

kCGPatternTilingConstantSpacingMinimalDistortion

Pattern cells are spaced consistently. The pattern cell may be distorted by as much as 1 device pixel when the pattern is painted.

Available in Mac OS X v10.1 and later.

Declared in CGPattern.h.

kCGPatternTilingConstantSpacing

Pattern cells are spaced consistently, as with kCGPatternTilingConstantSpacingMinimalDistortion. The pattern cell may be distorted additionally to permit a more efficient implementation.

Available in Mac OS X v10.1 and later.

Declared in CGPattern.h.

---