---

CGImageDestination Reference

Overview

CGImageDestination objects, available in Mac 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
);

Parameters

idst

An image destination

image

The image to add.

properties

An optional dictionary that specifies the properties of the added image. The dictionary can contain any of the properties described in “Destination Properties” or the image properties described in CGImageProperties Reference.

Discussion

The function logs an error if you add more images than what you specified when you created the image destination.

Availability

• Available in Mac OS X version 10.4 and later.

Declared In

CGImageDestination.h

CGImageDestinationAddImageFromSource

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

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

Parameters

idst

An image destination.

isrc

An image source.

index

An index that specifies the location of the image in the image source. The index is zero-based.

properties

A dictionary that specifies properties to overwrite or add to the source image properties. If a key in properties has the value kCFNull, the corresponding property in the image destination is removed. The dictionary can contain any of the properties described in “Destination Properties” or the image properties described in CGImageProperties Reference.

Availability

• Available in Mac OS X version 10.4 and later.

Declared In

CGImageDestination.h

CGImageDestinationCopyTypeIdentifiers

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

CFArrayRef CGImageDestinationCopyTypeIdentifiers (
   void
);

Return Value

Returns an array of the UTIs that are supported for image destinations. See Uniform Type Identifiers Overview for a list of system-declared and third-party UTIs that can be returned.

Availability

• Available in Mac OS X version 10.4 and later.

Declared In

CGImageDestination.h

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
);

Parameters

data

The data object to write to. For more information on data objects, see CFData Reference and Data Objects.

type

The uniform type identifier (UTI) of the resulting image file. See Uniform Type Identifiers Overview for a list of system-declared and third-party UTIs.

count

The number of images (not including thumbnail images) that the image file will contain.

options

Reserved for future use. Pass NULL.

Return Value

An image destination. You are responsible for releasing this object using CFRelease.

Availability

• Available in Mac OS X version 10.4 and later.

Declared In

CGImageDestination.h

CGImageDestinationCreateWithDataConsumer

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

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

Parameters

consumer

The data consumer to write to. For information on data consumers see CGDataConsumer Reference and Quartz 2D Programming Guide.

type

The uniform type identifier (UTI) of the resulting image file. See Uniform Type Identifiers Overview for a list of system-declared and third-party UTIs.

count

The number of images (not including thumbnail images) that the image file will contain.

options

Reserved for future use. Pass NULL.

Return Value

An image destination. You are responsible for releasing this object using CFRelease.

Availability

• Available in Mac OS X version 10.4 and later.

Declared In

CGImageDestination.h

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
);

Parameters

url

The URL to write to. If the URL already exists, the data at this location is overwritten.

type

The UTI (uniform type identifier) of the resulting image file. See Uniform Type Identifiers Overview for a list of system-declared and third-party UTIs.

count

The number of images (not including thumbnail images) that the image file will contain.

options

Reserved for future use. Pass NULL.

Return Value

An image destination. You are responsible for releasing this object using CFRelease.

Availability

• Available in Mac OS X version 10.4 and later.

Declared In

CGImageDestination.h

CGImageDestinationFinalize

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

bool CGImageDestinationFinalize (
   CGImageDestinationRef idst
);

Parameters

idst

An image destination.

Return Value

Returns true if the image is successfully written; false otherwise.

Discussion

You must call this function or the output of the image destination will not be valid. After calling this function, no additional data can be added to the image destination.

Availability

• Available in Mac OS X version 10.4 and later.

Declared In

CGImageDestination.h

CGImageDestinationGetTypeID

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

CFTypeID CGImageDestinationGetTypeID (
   void
);

Return Value

Returns the Core Foundation type ID for an image destination.

Discussion

A type identifier is an integer that identifies the opaque type to which a Core Foundation object belongs. You use type IDs in various contexts, such as when you are operating on heterogeneous collections.

Availability

• Available in Mac OS X version 10.4 and later.

Declared In

CGImageDestination.h

CGImageDestinationSetProperties

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

void CGImageDestinationSetProperties (
   CGImageDestinationRef idst,
   CFDictionaryRef properties
);

Parameters

idst

An image destination.

properties

A dictionary that contains the properties to apply. You can set any of the properties described in “Destination Properties” or the image properties described in CGImageProperties Reference.

Availability

• Available in Mac OS X version 10.4 and later.

Declared In

CGImageDestination.h

Data Types

CGImageDestinationRef

An opaque type that represents an image destination.

typedef struct CGImageDestination *CGImageDestinationRef;

Availability

• Available in Mac OS X v10.4 and later.

Declared In

CGImageDestination.h

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 Mac OS X v10.4 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 Mac OS X v10.4 and later.

Declared in CGImageDestination.h.

Declared In

CGImageDestination.h

---