Using a Bitmap Context for Offscreen Drawing

A bitmap graphics context in Quartz is analogous to an offscreen graphics world with user-supplied storage for the pixel map (NewGWorldFromPtr). You can create bitmap contexts with many different pixel formats, including 8-bit gray, 16-bit RGB, and 32 bit RGBA, ARGB, and CMYK.

You create a bitmap context by calling the function CGBitmapContextCreate and passing in a specific set of attributes, including a bitmap into which Quartz renders your drawing. You’re free to use the bitmap for other purposes—for example, you could create a bitmap context and a graphics world that share the same memory.

After drawing in a bitmap context, you can easily transfer the bitmap image to another Quartz context of any type. To maintain device independence, copying an image is a drawing operation and not a blitting operation. There are two steps:

1. Create a Quartz image from the bitmap. In Mac OS X v10.4 and later, you can use the function CGBitmapContextCreateImage.

2. Draw the image in the destination context using the function CGContextDrawImage.

For detailed information about creating and using bitmap contexts, see Graphics Contexts in Quartz 2D Programming Guide.

Using a CGLayer Object for Offscreen Drawing

Starting in Mac OS X 10.4, the recommended way to draw offscreen is to create a CGLayer object and draw to it. CGLayers are opaque types that provide a context for offscreen drawing. A CGLayer object is created from an existing graphics context by calling the function CGLayerCreateWithContext. The resulting CGLayer object has all the characteristics of the graphics context that the layer is created from. After the layer object is created, you pass it to the function CGLayerGetContext to get a graphics context for the layer. It is this graphics context that you draw to using the function CGLayerDrawAtPoint and CGLayerDrawInRect. You cannot access layer drawing directly.

CGLayer objects are cached by the operating system whenever possible, which greatly improves drawing performance. One important feature of CGLayers is that you do not need to know the device characteristics of the destination context.

It’s best to use a CGLayer when you need to:

• Reuse your drawing, as in the background scene for a game.

• Draw the same image multiple times, as in a game sprite.

To use CGLayer, follow these steps:

1. Call the function CGLayerCreateWithContext to create a CGLayer object from an existing graphics context. The resulting CGLayer object has all the characteristics of the graphics context that the layer is created from. Carbon applications can use the context provided in the kEventControlDraw event for this purpose.

2. After the layer object is created, pass it to the function CGLayerGetContext to get a graphics context for the layer. It is this graphics context that you draw to.

3. To draw to the layer graphics context, use any of the Quartz drawing functions (such as CGContextDrawPath, CGContextFillRect, and so forth), passing the layer graphics context as the context parameter. Note that you cannot access the drawing in the layer directly.

4. To draw the contents of a CGLayer to a destination graphics context (possibly the same graphics context used to create the layer, but it doesn’t need to be). Use the functions CGLayerDrawAtPoint and CGLayerDrawInRect.

For a code example that shows how to draw using CGLayer objects, see CGLayer Drawing in Quartz 2D Programming Guide.

Relevant Resources

In Quartz 2D Programming Guide, see:

• CGLayer Drawing

• Graphics Contexts

See these reference documents:

• CGContext Reference

• CGBitmapContext Reference

• CGLayer Reference