CGImageDestination Reference

Overview

CGImageDestination objects, available in OS X v10.4 or later, abstract the data-writing task. An image destination can represent a single image or multiple images. It can contain thumbnail images as well as properties for each image.

The functions described in this reference can write data to three kinds of destinations: a URL, a CFData object, and a data consumer. After creating a CGImageDestination object for the appropriate destination, you can add image data and set image properties. When you are finished adding data, call the function CGImageDestinationFinalize to write the image data and properties to the URL, CFData object, or data consumer.

Functions by Task

Creating Image Destinations

• CGImageDestinationCreateWithDataConsumer
• CGImageDestinationCreateWithData
• CGImageDestinationCreateWithURL

Adding Images

• CGImageDestinationAddImage
• CGImageDestinationAddImageFromSource

Getting Type Identifiers

• CGImageDestinationCopyTypeIdentifiers
• CGImageDestinationGetTypeID

Setting Properties

• CGImageDestinationSetProperties

Finalizing an Image Destination

• CGImageDestinationFinalize

Functions

CGImageDestinationAddImage

Adds an image to an image destination.

void CGImageDestinationAddImage (
   CGImageDestinationRef idst,
   CGImageRef image,
   CFDictionaryRef properties
);

CGImageDestinationAddImageFromSource

Adds an image from an image source to an image destination.

void CGImageDestinationAddImageFromSource (
   CGImageDestinationRef idst,
   CGImageSourceRef isrc,
   size_t index,
   CFDictionaryRef properties
);

CGImageDestinationCopyTypeIdentifiers

Returns an array of the uniform type identifiers (UTIs) that are supported for image destinations.

CFArrayRef CGImageDestinationCopyTypeIdentifiers (
   void
);

CGImageDestinationCreateWithData

Creates an image destination that writes to a Core Foundation mutable data object.

CGImageDestinationRef CGImageDestinationCreateWithData (
   CFMutableDataRef data,
   CFStringRef type,
   size_t count,
   CFDictionaryRef options
);

CGImageDestinationCreateWithDataConsumer

Creates an image destination that writes to the specified data consumer.

CGImageDestinationRef CGImageDestinationCreateWithDataConsumer (
   CGDataConsumerRef consumer,
   CFStringRef type,
   size_t count,
   CFDictionaryRef options
);

CGImageDestinationCreateWithURL

Creates an image destination that writes to a location specified by a URL.

CGImageDestinationRef CGImageDestinationCreateWithURL (
   CFURLRef url,
   CFStringRef type,
   size_t count,
   CFDictionaryRef options
);

CGImageDestinationFinalize

Writes image data and properties to the data, URL, or data consumer associated with the image destination.

bool CGImageDestinationFinalize (
   CGImageDestinationRef idst
);

CGImageDestinationGetTypeID

Returns the unique type identifier of an image destination opaque type.

CFTypeID CGImageDestinationGetTypeID (
   void
);

CGImageDestinationSetProperties

Applies one or more properties to all images in an image destination.

void CGImageDestinationSetProperties (
   CGImageDestinationRef idst,
   CFDictionaryRef properties
);

Data Types

CGImageDestinationRef

An opaque type that represents an image destination.

typedef struct CGImageDestination *CGImageDestinationRef;

Constants

Destination Properties

Properties for a single image in an image destination.

const CFStringRef kCGImageDestinationLossyCompressionQuality
const CFStringRef kCGImageDestinationBackgroundColor

Constants

kCGImageDestinationLossyCompressionQuality

The desired compression quality to use when writing to an image destination. If present, the value associated with this key must be a CFNumberRef data type in the range 0.0 to 1.0. A value of 1.0 specifies to use lossless compression if destination format supports it. A value of 0.0 implies to use maximum compression.

Available in iOS 4.0 and later.

Declared in CGImageDestination.h.

kCGImageDestinationBackgroundColor

The desired background color to composite against when writing an image that has an alpha component to a destination format that does not support alpha. If present, the value associated with this key must be a CGColorRef data type without an alpha component of its own. If not present, and if a background color is needed, a white color is used.

Available in iOS 4.0 and later.

Declared in CGImageDestination.h.