---

Data Management

Managing data is a task every graphics application needs to perform. For Quartz, data management refers to supplying data to or receiving data from Quartz 2D routines. Some Quartz 2D routines move blocks of data into Quartz, such as those that get image or PDF data from a file or another part of your application. Other routines accept blocks of Quartz data, such as those that write image or PDF data to a file or provide the data to another part of your application.

Quartz provides a variety of functions for managing data. By reading this chapter, you should be able to determine which functions are best for your application. As you’ll see, some routines are available only in Mac OS X v10.4 and later while others have been with Quartz since its beginning.

Quartz recognizes three broad categories of data sources and destinations:

• URL. Data whose location can be specified as a URL can act as a supplier or receiver of data. You pass a URL to a Quartz function using the Core Foundation data type CFURLRef.

• CFData. The Core Foundation data types CFDataRef and CFMutableDataRef are data objects that let simple allocated buffers take on the behavior of Core Foundation objects. CFData is “toll-free bridged” with its Cocoa Foundation counterpart, the NSData class. This means that if you are using Quartz 2D with the Cocoa framework, you can pass an NSData object to any Quartz function that takes a CFData object.

• Raw data. You can provide a pointer to data of any type along with a set of callbacks that take care of basic memory management for the data.

The data itself, whether represented by a URL, a CFData object, or a data buffer, can be image data or PDF data. Image data can use any type of file format. Quartz understands most of the common image file formats. Some of the Quartz data management functions work specifically with image data, a few work only with PDF data, while others are more generic and can be used either for PDF or image data.

URL, CFData, and raw data sources and destinations refer to data outside the realm of Mac OS X graphics technologies, as shown in Figure 10-1. Your application can also move data between Quartz 2D and Core Image, which is another Mac OS X graphics technology. Although this is a fairly trivial operation, it’s an important one to keep in mind because Core Image can add impressive capabilities to your graphics application.

These sections provide detailed information on data management in Quartz 2D:

• “Moving Data Into Quartz 2D”

• “Moving Data Out Of Quartz 2D”

• “Moving Data Between Quartz 2D and Core Image”

Moving Data Into Quartz 2D

The functions for getting data from a data source are listed in Table 10-1. All these functions, except for CGPDFDocumentCreateWithURL, either return an image source (CGImageSourceRef) or a data provider (CGDataProviderRef). Image sources and data providers abstract the data-access task and eliminate the need for applications to manage data through a raw memory buffer. Image sources are used exclusively for obtaining image data, but are available only in Mac OS X v10.4 or later. An image source represents a wide variety of image data. An image source can contain more than one image, thumbnail images, and properties for each image and the image file.

Data providers can be used to obtain image or PDF data, and all, except for CGDataProviderCreateWithCFData, are available in Mac OS Xv10.0 or later. The function CGPDFDocumentCreateWithURL is a convenience function that creates a PDF document from the file located at the specified URL.

You can supply a data provider to:

• An image creation function, such as CGImageCreate, CGImageCreateWithPNGDataProvider, or CGImageCreateWithJPEGDataProvider.

• The PDF document creation function CGPDFDocumentCreateWithProvider.

• The function CGImageSourceUpdateDataProvider to update an existing image source with new data.

When you are working with image data and your application runs in Mac OS X v10.4 or later, image sources are the preferred way to move image data into Quartz. After you have a CGImageSourceRef, you can accomplish these tasks:

• Create images (CGImageRef) using the functions CGImageSourceCreateImageAtIndex, CGImageSourceCreateThumbnailAtIndex, or CGImageSourceCreateIncremental. A CGImageRef data type represents a single Quartz image.

• Add content to an image source using the functions CGImageSourceUpdateData or CGImageSourceUpdateDataProvider.

• Obtain information from an image source using the functions CGImageSourceGetCount , CGImageSourceGetProperties, and CGImageSourceCopyTypeIdentifiers.

For more information on images, see “Bitmap Images and Image Masks.”

Moving Data Out Of Quartz 2D

The functions listed in Table 10-2 move data out of Quartz 2D. All these functions, except for CGPDFContextCreateWithURL, either return an image destination (CGImageDestinationRef) or a data consumer (CGDataConsumerRef). Image destination and data consumers abstract the data-writing task, letting Quartz take care of the details for you. Image destinations are used exclusively for writing image data, but are available only in Mac OS X v10.4 or later. Similar to image sources, an image destination can represent a variety of image data, from a single image to a destination that contains multiple images, thumbnail images, and properties for each image or for the image file.

Data consumers can be used to write image or PDF data, and all, except for CGDataConsumerCreateWithCFData, are available in Mac OS X v10.0 or later. The function CGPDFContextCreateWithURL is a convenience function that writes PDF data to the location specified by a URL.

You can supply a data consumer to:

• The PDF context creation function CGPDFContextCreate. This function returns a graphics context that records your drawing as a sequence of PDF drawing commands that are passed to the data consumer object.

• The function CGImageDestinationCreateWithDataConsumer to create an image destination from a data consumer.

When you are working with image data and your application runs in Mac OS X v10.4 or later, an image destination is the preferred way to move image data out of Quartz. After you have a CGImageDestinationRef, you can accomplish these tasks:

• Add images (CGImageRef) to a destination using the functions CGImageDestinationAddImage or CGImageDestinationAddImageFromSource. A CGImageRef data type represents a single Quartz image.

• Set properties using the function CGImageDestinationSetProperties.

• Obtain information from an image destination using the functions CGImageDestinationCopyTypeIdentifiers or CGImageDestinationGetTypeID.

For more information on images, see “Bitmap Images and Image Masks.”

Moving Data Between Quartz 2D and Core Image

The Core Image framework is an Objective-C API that supports image processing. Core Image lets you access built-in image filters for both video and still images and provides support for custom filters and near real-time processing. You can apply Core Image filters to Quartz 2D images. For example, you can use Core Image to correct color, distort the geometry of images, blur or sharpen images, and create a transition between images. Core Image also allows you to apply an iterative process to an image—one that feeds back the output of a filter operation to the input. To understand the capabilities of Core Image more fully, see Core Image Programming Guide.

Core Image methods operate on images that are packaged as Core Image images, or CIImage objects. Although “CIImage” looks similar to the “CGImage” on the printed page (or display screen), Core Image does not operate directly on Quartz images (CGImageRef data types). Quartz images must be converted to Core Image images before you apply a Core Image filter to the image.

The Quartz 2D API does not provide any functions that package Quartz images as Core Image images. But Core Image does. The following Core Image methods create a Core Image image from either a Quartz image or a Quartz layer (CGLayerRef). You can use them to move Quartz 2D data to Core Image.

• imageWithCGImage:

• imageWithCGImage:options:

• imageWithCGLayer:

• imageWithCGLayer:options:

The following Core Image methods return a Quartz image from a Core Image image. You can use them to move a processed image back into Quartz 2D:

• createCGImage:fromRect:

• createCGLayerWithSize:info:

For a complete description of Core Image methods, see Core Image Reference Collection.

---