Mac Developer Library

Developer

ApplicationServices Framework Reference CGImageDestination Reference

Options
Deployment Target:

On This Page
Language:

CGImageDestination Reference

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Swift

import ImageIO

Objective-C

@import ImageIO;

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

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

    Declaration

    Swift

    func CGImageDestinationCreateWithDataConsumer(_ consumer: CGDataConsumer!, _ type: CFString!, _ count: Int, _ options: CFDictionary!) -> CGImageDestination!

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ImageIO;

    Swift

    import ImageIO

    Availability

    Available in OS X version 10.4 and later.

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

    Declaration

    Swift

    func CGImageDestinationCreateWithData(_ data: CFMutableData!, _ type: CFString!, _ count: Int, _ options: CFDictionary!) -> CGImageDestination!

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ImageIO;

    Swift

    import ImageIO

    Availability

    Available in OS X version 10.4 and later.

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

    Declaration

    Swift

    func CGImageDestinationCreateWithURL(_ url: CFURL!, _ type: CFString!, _ count: Int, _ options: CFDictionary!) -> CGImageDestination!

    Objective-C

    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.

    Import Statement

    Objective-C

    @import ImageIO;

    Swift

    import ImageIO

    Availability

    Available in OS X version 10.4 and later.

  • 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

    Objective-C

    @import ImageIO;

    Swift

    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: Int, _ 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

    Objective-C

    @import ImageIO;

    Swift

    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

    Objective-C

    @import ImageIO;

    Swift

    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

    Objective-C

    @import ImageIO;

    Swift

    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

    Objective-C

    @import ImageIO;

    Swift

    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

    Objective-C

    @import ImageIO;

    Swift

    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.