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:

• 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 , CGImageSourceCopyProperties, and CGImageSourceCopyTypeIdentifiers.

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:

• 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.

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.

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:

• 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.

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:

• 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.

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

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.

• 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.