---

Drawing With a CGLayer

You need to perform the following tasks to draw using a CGLayer:

1. “Create a CGLayer Initialized With an Existing Graphics Context”

2. “Get a Graphics Context for the CGLayer”

3. “Draw to the CGLayer Graphics Context”

4. “Draw the CGLayer to the Destination Graphics Context”

The sections that follow describe each task. See “Example: Using Multiple CGLayer objects to Draw a Flag” for a detailed code example.

Create a CGLayer Initialized With an Existing Graphics Context

The function CGLayerCreateWithContext returns a CGLayer that is initialized with an existing graphics context. The layer inherits all the characteristics of the graphics context, including the color space, size, resolution, and pixel format. Later, when you draw the CGLayer to a destination, Quartz automatically color matches the CGLayer to the destination context.

The function CGLayerCreateWithContext takes three parameters:

• The graphics context to create the CGLayer from. Typically you pass a window graphics context so that you can later draw the CGLayer onscreen.

• The size of the CGLayer relative to the graphics context. The layer can be the same size as the graphics context or smaller. If you need to retrieve the layer size later, you can call the function CGLayerGetSize.

• An auxiliary dictionary. This parameter is currently unused, so pass NULL.

Get a Graphics Context for the CGLayer

Quartz always draws to a graphics context. Now that you have a CGLayer, you must create a graphics context associated with the layer. Anything you draw into the layer graphics context is part of the CGLayer.

The function CGLayerGetContext takes a CGLayer as a parameter and returns a graphics context associated with the layer.

Draw to the CGLayer Graphics Context

After you obtain the graphics context associated with a CGLayer, you can perform any drawing you’d like to the layer graphics context. You can open a PDF file or an image file and draw the file contents to the layer. You can use any of the Quartz 2D functions to draw rectangles, lines, and other drawing primitives. Figure 12-3 shows an example of drawing rectangles and lines to a layer.

For example, to draw a filled rectangle to a CGLayer graphics context, you call the function CGContextFillRect, supplying the graphics context you obtained from the function CGLayerGetContext. If the graphics context is named myLayerContext, the function call looks like this:

CGContextFillRect (myLayerContext, myRect)

Draw the CGLayer to the Destination Graphics Context

When you are ready to draw the layer to its destination graphics context you can use either of the following functions:

• CGContextDrawLayerInRect, which draws a CGLayer to a graphics context in the rectangle specified.

• CGContextDrawLayerAtPoint, which draws the layer to a graphics context at the point specified.

Typically the destination graphics context you supply is a window graphics context and it is the same graphics context you use to create the CGLayer. Figure 12-4 shows the result of repeatedly drawing the CGLayer drawing shown in Figure 12-3. To achieve the patterned effect, you call either of the layer drawing functions repeatedly—CGContextDrawLayerAtPoint or CGContextDrawLayerInRect—changing the offset each time. For example you can call the function CGContextTranslateCTM to change the origin of the coordinate space each time you draw the CGLayer.

---