Mac Developer Library

Developer

ApplicationServices Framework Reference CGImageDestination Reference

Options
Deployment Target:

On This Page
Language:

CGImageDestination Reference

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

  • Adds an image to an image destination.

    Declaration

    Swift

    func CGImageDestinationAddImage(_ idst: CGImageDestination!, _ image: CGImage!, _ properties: CFDictionary!)

    Objective-C

    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.

    Import Statement

    import ImageIO

    Availability

    Available in OS X version 10.4 and later.

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

    Declaration

    Swift

    func CGImageDestinationAddImageFromSource(_ idst: CGImageDestination!, _ isrc: CGImageSource!, _ index: UInt, _ properties: CFDictionary!)

    Objective-C

    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.

    Import Statement

    import ImageIO

    Availability

    Available in OS X version 10.4 and later.

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

    Declaration

    Swift

    func CGImageDestinationCopyTypeIdentifiers() -> CFArray!

    Objective-C

    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.

    Import Statement

    import ImageIO

    Availability

    Available in OS X version 10.4 and later.

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

    Declaration

    Swift

    func CGImageDestinationGetTypeID() -> CFTypeID

    Objective-C

    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.

    Import Statement

    import ImageIO

    Availability

    Available in OS X version 10.4 and later.

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

    Declaration

    Swift

    func CGImageDestinationFinalize(_ idst: CGImageDestination!) -> Bool

    Objective-C

    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.

    Import Statement

    import ImageIO

    Availability

    Available in OS X version 10.4 and later.

Data Types

  • An opaque type that represents an image destination.

    Declaration

    Swift

    typealias CGImageDestinationRef = CGImageDestination

    Objective-C

    typedef struct CGImageDestination *CGImageDestinationRef;

    Import Statement

    import ImageIO

    Availability

    Available in OS X v10.4 and later.

Constants

  • Properties for a single image in an image destination.

    Declaration

    Swift

    let kCGImageDestinationLossyCompressionQuality: CFString! let kCGImageDestinationBackgroundColor: CFString!

    Objective-C

    const CFStringRef kCGImageDestinationLossyCompressionQuality const CFStringRef kCGImageDestinationBackgroundColor

    Constants

    • kCGImageDestinationLossyCompressionQuality

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

    • kCGImageDestinationBackgroundColor

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

    Import Statement