Data Management in Quartz 2D

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 data into Quartz, such as those that get image or PDF data from a file or another part of your application. Other routines accept 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.

Quartz recognizes three broad categories of data sources and destinations:

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 or iOS graphics technologies, as shown in Figure 10-1. Other graphics technologies in Mac OS X or iOS often provide their own routines to communicate with Quartz. For example, a Mac OS X application can send Quartz images to Core Image and use it to alter the image with sophisticated effects.

Figure 10-1  Moving data to and from Quartz 2D in Mac OS X
Moving data to and from Quartz 2D

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 the preferred way to move image data into Quartz. 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. After you have a CGImageSourceRef, you can accomplish these tasks:

The function CGPDFDocumentCreateWithURL is a convenience function that creates a PDF document from the file located at the specified URL.

Data providers are an older mechanism with more limited functionality. They can be used to obtain image or PDF data.

You can supply a data provider to:

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

Table 10-1  Functions that move data into Quartz 2D

Function

Use this function

CGImageSourceCreateWithDataProvider

To create an image source from a data provider.

CGImageSourceCreateWithData

To create an image source from a CFData object.

CGImageSourceCreateWithURL

To create an image source from a URL that specifies the location of image data.

CGPDFDocumentCreateWithURL

To create a PDF document from data that resides at the specified URL.

CGDataProviderCreateSequential

To read image or PDF data in a stream. You supply callbacks to handle the data.

CGDataProviderCreateDirectAccess

To read image or PDF data in a block. You supply callbacks to handle the data.

CGDataProviderCreateWithData

To read a buffer of image or PDF data supplied by your application. You provide a callback to release the memory you allocated for the data.

CGDataProviderCreateWithURL

Whenever you can supply a URL that specifies the target for data access to image or PDF data.

CGDataProviderCreateWithCFData

To read image or PDF data from a CFData object.

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.

An image destination is the preferred way to move image data out of Quartz. 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. After you have a CGImageDestinationRef, you can accomplish these tasks:

The function CGPDFContextCreateWithURL is a convenience function that writes PDF data to the location specified by a URL.

Data consumers are an older mechanism with more limited functionality. They are used to write image or PDF data. You can supply a data consumer to:

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

Table 10-2  Functions that move data out of Quartz 2D

Function

Use this function

CGImageDestinationCreateWithDataConsumer

To write image data to a data consumer.

CGImageDestinationCreateWithData

To write image data to a CFData object.

CGImageDestinationCreateWithURL

Whenever you can supply a URL that specifies where to write the image data.

CGPDFContextCreateWithURL

Whenever you can supply a URL that specifies where to write PDF data.

CGDataConsumerCreateWithURL

Whenever you can supply a URL that specifies where to write the image or PDF data.

CGDataConsumerCreateWithCFData

To write image or PDF data to a CFData object.

CGDataConsumerCreate

To write image or PDF data using callbacks you supply.

Moving Data Between Quartz 2D and Core Image in Mac OS X

The Core Image framework is an Objective-C API provided in Mac OS X 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. 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.

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:

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