Mac Developer Library

Developer

QuartzCore Framework Reference CIImage Class Reference

Options
Deployment Target:

On This Page
Language:

CIImage

Inheritance


Conforms To


Import Statement


Swift

import QuartzCore

Objective-C

@import QuartzCore;

Availability


Available in OS X v10.4 and later.

The CIImage class represents an image. Core Image images are immutable. You use CIImage objects in conjunction with other Core Image classes—such as CIFilter, CIContext, CIVector, and CIColor—to take advantage of the built-in Core Image filters when processing images. You can create CIImage objects with data supplied from a variety of sources, including Quartz 2D images, Core Video image buffers (CVImageBufferRef), URL-based objects, and NSData objects.

Although a CIImage object has image data associated with it, it is not an image. You can think of a CIImage object as an image “recipe.” A CIImage object has all the information necessary to produce an image, but Core Image doesn’t actually render an image until it is told to do so. This “lazy evaluation” method allows Core Image to operate as efficiently as possible.

CIContext and CIImage objects are immutable, which means each can be shared safely among threads. Multiple threads can use the same GPU or CPU CIContext object to render CIImage objects. However, this is not the case for CIFilter objects, which are mutable. A CIFilter object cannot be shared safely among threads. If you app is multithreaded, each thread must create its own CIFilter objects. Otherwise, your app could behave unexpectedly.

Core Image also provides autoadjustment methods that analyze an image for common deficiencies and return a set of filters to correct those deficiencies. The filters are preset with values for improving image quality by altering values for skin tones, saturation, contrast, and shadows and for removing red-eye or other artifacts caused by flash. (See “Getting Autoadjustment Filters”.)

For a discussion of all the methods you can use to create CIImage objects on iOS and OS X, see Core Image Programming Guide.

  • Creates and returns an empty image object.

    Declaration

    Swift

    class func emptyImage() -> CIImage!

    Objective-C

    + (CIImage *)emptyImage

    Return Value

    An image object.

    Import Statement

    Objective-C

    @import QuartzCore;

    Swift

    import QuartzCore

    Availability

    Available in OS X v10.5 and later.

  • Creates and returns an image of infinite extent that is initialized the specified color.

    Declaration

    Objective-C

    + (CIImage *)imageWithColor:(CIColor *)color

    Parameters

    color

    A color object.

    Return Value

    The image object initialized with the color represented by the CIColor object.

    Import Statement

    Objective-C

    @import QuartzCore;

    Availability

    Available in OS X v10.5 and later.

  • Creates and returns an image object from bitmap data.

    Declaration

    Objective-C

    + (CIImage *)imageWithBitmapData:(NSData *)d bytesPerRow:(size_t)bpr size:(CGSize)size format:(CIFormat)f colorSpace:(CGColorSpaceRef)cs

    Parameters

    d

    The bitmap data for the image. This data must be premultiplied.

    bpr

    The number of bytes per row.

    size

    The dimensions of the image.

    f

    The format and size of each pixel. You must supply a pixel format constant. See “Pixel Formats”.

    cs

    The color space that the image is defined in. If this value is nil, the image is not color matched. Pass nil for images that don’t contain color data (such as elevation maps, normal vector maps, and sampled function tables).

    Return Value

    An image object.

    Import Statement

    Objective-C

    @import QuartzCore;

    Availability

    Available in OS X v10.4 and later.

  • Creates and returns an image object from a Quartz 2D image.

    Declaration

    Objective-C

    + (CIImage *)imageWithCGImage:(CGImageRef)image

    Parameters

    image

    A Quartz 2D image (CGImageRef) object. For more information, see Quartz 2D Programming Guide and CGImage Reference.

    Return Value

    An image object initialized with the contents of the Quartz 2D image.

    Import Statement

    Objective-C

    @import QuartzCore;

    Availability

    Available in OS X v10.4 and later.

  • Creates and returns an image object from a Quartz 2D image using the specified options.

    Declaration

    Objective-C

    + (CIImage *)imageWithCGImage:(CGImageRef)image options:(NSDictionary *)d

    Parameters

    image

    A Quartz 2D image (CGImageRef) object. For more information, see Quartz 2D Programming Guide and CGImage Reference.

    d

    A dictionary specifying image options. (See “Image Dictionary Keys”.)

    Return Value

    An image object initialized with the contents of the Quartz 2D image and the specified options.

    Import Statement

    Objective-C

    @import QuartzCore;

    Availability

    Available in OS X v10.4 and later.

  • Creates and returns an image object from the contents supplied by a CGLayer object.

    Declaration

    Objective-C

    + (CIImage *)imageWithCGLayer:(CGLayerRef)layer

    Parameters

    layer

    A CGLayer object. For more information see Quartz 2D Programming Guide and CGLayer Reference.

    Return Value

    An image object initialized with the contents of the layer object.

    Import Statement

    Objective-C

    @import QuartzCore;

    Availability

    Available in OS X v10.4 and later.

  • Creates and returns an image object from the contents supplied by a CGLayer object, using the specified options.

    Declaration

    Objective-C

    + (CIImage *)imageWithCGLayer:(CGLayerRef)layer options:(NSDictionary *)d

    Parameters

    layer

    A CGLayer object. For more information see Quartz 2D Programming Guide and CGLayer Reference.

    d

    A dictionary specifying image options. (See “Image Dictionary Keys”.)

    Return Value

    An image object initialized with the contents of the layer object and set up with the specified options.

    Import Statement

    Objective-C

    @import QuartzCore;

    Availability

    Available in OS X v10.4 and later.

  • Creates and returns an image object from the contents of a file.

    Declaration

    Objective-C

    + (CIImage *)imageWithContentsOfURL:(NSURL *)url

    Parameters

    url

    The location of the file.

    Return Value

    An image object initialized with the contents of the file.

    Import Statement

    Objective-C

    @import QuartzCore;

    Availability

    Available in OS X v10.4 and later.

  • Creates and returns an image object from the contents of a file, using the specified options.

    Declaration

    Objective-C

    + (CIImage *)imageWithContentsOfURL:(NSURL *)url options:(NSDictionary *)d

    Parameters

    url

    The location of the file.

    d

    A dictionary specifying image options. (See “Image Dictionary Keys”.)

    Return Value

    An image object initialized with the contents of the file and set up with the specified options.

    Import Statement

    Objective-C

    @import QuartzCore;

    Availability

    Available in OS X v10.4 and later.

  • Creates and returns an image object from the contents of CVImageBuffer object.

    Declaration

    Objective-C

    + (CIImage *)imageWithCVImageBuffer:(CVImageBufferRef)imageBuffer

    Parameters

    imageBuffer

    A CVImageBuffer object. For more information, see Core Video Programming Guide and Core Video Reference Collection.

    Return Value

    An image object initialized with the contents of the image buffer object.

    Import Statement

    Objective-C

    @import QuartzCore;

    Availability

    Available in OS X v10.4 and later.

  • Creates and returns an image object from the contents of CVImageBuffer object, using the specified options.

    Declaration

    Objective-C

    + (CIImage *)imageWithCVImageBuffer:(CVImageBufferRef)imageBuffer options:(NSDictionary *)dict

    Parameters

    imageBuffer

    A CVImageBuffer object. For more information, see Core Video Programming Guide and Core Video Reference Collection.

    dict

    A dictionary specifying image options. (See “Image Dictionary Keys”.)

    Return Value

    An image object initialized with the contents of the image buffer object and set up with the specified options.

    Import Statement

    Objective-C

    @import QuartzCore;

    Availability

    Available in OS X v10.4 and later.

  • Creates and returns an image object initialized with the supplied image data.

    Declaration

    Objective-C

    + (CIImage *)imageWithData:(NSData *)data

    Parameters

    data

    The data object that holds the contents of an image file (such as TIFF, GIF, JPG, or whatever else the system supports). The image data must be premultiplied.

    Return Value

    An image object initialized with the supplied data, or nil if the method cannot create an image representation from the contents of the supplied data object.

    Import Statement

    Objective-C

    @import QuartzCore;

    Availability

    Available in OS X v10.4 and later.

  • Creates and returns an image object initialized with the supplied image data, using the specified options.

    Declaration

    Objective-C

    + (CIImage *)imageWithData:(NSData *)data options:(NSDictionary *)d

    Parameters

    data

    A pointer to the image data. The data must be premultiplied

    d

    A dictionary specifying image options. (See “Image Dictionary Keys”.)

    Return Value

    An image object initialized with the supplied data and set up with the specified options.

    Import Statement

    Objective-C

    @import QuartzCore;

    Availability

    Available in OS X v10.4 and later.

  • Creates and returns an image object initialized with data provided by an image provider.

    Declaration

    Objective-C

    + (CIImage *)imageWithImageProvider:(id)p size:(size_t)width :(size_t)height format:(CIFormat)f colorSpace:(CGColorSpaceRef)cs options:(NSDictionary *)dict

    Parameters

    p

    A data provider that implements the CIImageProvider informal protocol. Core Image maintains a strong reference to this object until the image is deallocated.

    width

    The width of the image.

    height

    The height of the image.

    f

    A pixel format constant. See “Pixel Formats”.

    cs

    The color space that the image is defined in. If the this value is nil, the image is not color matched. Pass nil for images that don’t contain color data (such as elevation maps, normal vector maps, and sampled function tables).

    dict

    A dictionary that specifies image-creation options, which can be kCIImageProviderTileSize or kCIImageProviderUserInfo. See CIImageProvider Protocol Reference for more information on these options.

    Return Value

    An image object initialized with the data from the data provider. Core Image does not populate the image object until the object needs the data.

    Import Statement

    Objective-C

    @import QuartzCore;

    Availability

    Available in OS X v10.6 and later.

  • Creates and returns an image object initialized with data supplied by an OpenGL texture.

    Declaration

    Objective-C

    + (CIImage *)imageWithTexture:(unsigned int)name size:(CGSize)size flipped:(BOOL)flag colorSpace:(CGColorSpaceRef)cs

    Parameters

    name

    An OpenGL texture. Because CIImage objects are immutable, the texture must remain unchanged for the life of the image object. See the discussion for more information.

    size

    The dimensions of the texture.

    flag

    YEStrue to have Core Image flip the coordinates of the texture vertically to convert between OpenGL and Core Image coordinate systems.

    cs

    The color space that the image is defined in. If the colorSpace value is nil, the image is not color matched. Pass nil for images that don’t contain color data (such as elevation maps, normal vector maps, and sampled function tables).

    Return Value

    An image object initialized with the texture data.

    Discussion

    When using a texture to create a CIImage object, the texture must be valid in the Core Image context (CIContext) that you draw the CIImage object into. This means that one of the following must be true:

    • The texture must be created using the CGLContext object that the CIContext is based on.

    • The context that the texture was created in must be shared with the CGLContext that the CIContext is based on.

    Note that textures do not have a retain and release mechanism. This means that your application must make sure that the texture exists for the life cycle of the image. When you no longer need the image, you can delete the texture.

    Core Image ignores the texture filtering and wrap modes (GL_TEXTURE_FILTER and GL_TEXTURE_WRAP) that you set through OpenGL. The filter and wrap modes are overridden by what the CISampler object specifies when you apply a filter to the CIImage object.

    Import Statement

    Objective-C

    @import QuartzCore;

    Availability

    Available in OS X v10.4 and later.

  • Creates and returns an image object initialized with data supplied by an OpenGL texture.

    Declaration

    Objective-C

    + (CIImage *)imageWithTexture:(unsigned int)name size:(CGSize)size flipped:(BOOL)flag options:(NSDictionary *)options

    Parameters

    name

    An OpenGL texture. Because CIImage objects are immutable, the texture must remain unchanged for the life of the image object. See the discussion for more information.

    size

    The dimensions of the texture.

    flag

    YEStrue to have Core Image flip the coordinates of the texture vertically to convert between OpenGL and Core Image coordinate systems.

    options

    A dictionary specifying image options. (See “Image Dictionary Keys”.)

    Return Value

    An image object initialized with the texture data.

    Discussion

    When using a texture to create a CIImage object, the texture must be valid in the Core Image context (CIContext) that you draw the CIImage object into. This means that one of the following must be true:

    • The texture must be created using the CGLContext object that the CIContext is based on.

    • The context that the texture was created in must be shared with the CGLContext that the CIContext is based on.

    Note that textures do not have a retain and release mechanism. This means that your application must make sure that the texture exists for the life cycle of the image. When you no longer need the image, you can delete the texture.

    Core Image ignores the texture filtering and wrap modes (GL_TEXTURE_FILTER and GL_TEXTURE_WRAP) that you set through OpenGL. The filter and wrap modes are overridden by what the CISampler object specifies when you apply a filter to the CIImage object.

    Import Statement

    Objective-C

    @import QuartzCore;

    Availability

    Available in OS X v10.9 and later.

  • Creates and returns an image from the contents of an IOSurface.

    Declaration

    Objective-C

    + (CIImage *)imageWithIOSurface:(IOSurfaceRef)surface

    Parameters

    surface

    An IOSurface object.

    Return Value

    An image object initialized with the data from the IOSurface object.

    Discussion

    An IOSurface object is a framebuffer object that is suitable for sharing across process boundaries. You can use it to allow your app to move complex image decompression and drawing logic into a separate process for the purpose of increasing security.

    Import Statement

    Objective-C

    @import QuartzCore;

    Availability

    Available in OS X v10.6 and later.

  • Creates, using the specified options, and returns an image from the contents of an IOSurface.

    Declaration

    Objective-C

    + (CIImage *)imageWithIOSurface:(IOSurfaceRef)surface options:(NSDictionary *)options

    Parameters

    surface

    An IOSurface object.

    options

    A dictionary specifying image options. (See “Image Dictionary Keys”.)

    Return Value

    An image object initialized with the data from the IOSurface.

    Import Statement

    Objective-C

    @import QuartzCore;

    Availability

    Available in OS X v10.6 and later.

  • Returns a new image created by applying a filter to the original image with the specified name and parameters.

    Declaration

    Swift

    func imageByApplyingFilter(_ filterName: String!, withInputParameters params: [NSObject : AnyObject]!) -> CIImage!

    Objective-C

    - (CIImage *)imageByApplyingFilter:(NSString *)filterName withInputParameters:(NSDictionary *)params

    Parameters

    filterName

    The name of the filter to apply, as used when creating a CIFilter instance with the filterWithName: method.

    params

    A dictionary whose key-value pairs are set as input values to the filter. Each key is a constant that specifies the name of an input parameter for the filter, and the corresponding value is the value for that parameter. See Core Image Filter Reference for built-in filters and their allowed parameters.

    Return Value

    An image object representing the result of applying the filter.

    Discussion

    Calling this method is equivalent to the following sequence of steps:

    1. Creating a CIFilter instance

    2. Setting the original image as the filter’s inputImage parameter

    3. Setting the remaining filter parameters from the params dictionary

    4. Retrieving the outputImage object from the filter

    Import Statement

    Objective-C

    @import QuartzCore;

    Swift

    import QuartzCore

    Availability

    Available in OS X v10.10 and later.

  • Returns a new image that represents the original image after applying an affine transform.

    Declaration

    Swift

    func imageByApplyingTransform(_ matrix: CGAffineTransform) -> CIImage!

    Objective-C

    - (CIImage *)imageByApplyingTransform:(CGAffineTransform)matrix

    Parameters

    matrix

    An affine transform.

    Return Value

    The transformed image object.

    Import Statement

    Objective-C

    @import QuartzCore;

    Swift

    import QuartzCore

    Availability

    Available in OS X v10.4 and later.

  • Returns a new image that represents the original image after cropping to a rectangle.

    Declaration

    Swift

    func imageByCroppingToRect(_ r: CGRect) -> CIImage!

    Objective-C

    - (CIImage *)imageByCroppingToRect:(CGRect)r

    Return Value

    An image object cropped to the specified rectangle.

    Import Statement

    Objective-C

    @import QuartzCore;

    Swift

    import QuartzCore

    Availability

    Available in OS X v10.5 and later.

  • Returns a new image created by transforming the original image to the specified EXIF orientation.

    Declaration

    Swift

    func imageByApplyingOrientation(_ orientation: Int32) -> CIImage!

    Objective-C

    - (CIImage *)imageByApplyingOrientation:(int)orientation

    Parameters

    orientation

    An integer specifying an image orientation according to the EXIF specification. For details, see kCGImagePropertyOrientation.

    Return Value

    An image object representing the result of rotating or mirroring the image to the target orientation.

    Discussion

    This method determines and then applies the transformation needed to reorient the image to the specified orientation. If you plan to also apply other transformations, you can retrieve the transformation this method would use by calling the imageTransformForOrientation: method.

    Import Statement

    Objective-C

    @import QuartzCore;

    Swift

    import QuartzCore

    Availability

    Available in OS X v10.10 and later.

  • Returns a new image created by clamping the original image so that the pixel colors along its edges extend infinitely in all directions.

    Declaration

    Swift

    func imageByClampingToExtent() -> CIImage!

    Objective-C

    - (CIImage *)imageByClampingToExtent

    Return Value

    An image object representing the result of the clamp operation.

    Discussion

    Calling this method is equivalent to using the CIAffineClamp filter, which creates an image of infinite extent by repeating pixel colors from the edges of the original image.

    This operation can be useful when using the image as input to other filters. When an image has finite extent, Core Image treats the area outside the extent as if it were filled with empty (black, zero alpha) pixels. If you apply a filter that samples from outside the image’s extent, those empty pixels affect the result of the filter.

    For example, applying the CIGaussianBlur filter to an image softens the edges of the blurred image, because the opaque pixels at the edges of the image blur into the transparent pixels outside the image’s extent. Applying a clamp effect before the blur filter avoids edge softening by making the original image opaque in all directions. (However, the blurred image will also have infinite extent. Use the imageByCroppingToRect: method to return to the original image’s dimensions while retaining hard edges.)

    Import Statement

    Objective-C

    @import QuartzCore;

    Swift

    import QuartzCore

    Availability

    Available in OS X v10.10 and later.

  • Returns a new image created by compositing the original image over the specified destination image.

    Declaration

    Swift

    func imageByCompositingOverImage(_ dest: CIImage!) -> CIImage!

    Objective-C

    - (CIImage *)imageByCompositingOverImage:(CIImage *)dest

    Parameters

    dest

    An image to serve as the destination of the compositing operation.

    Return Value

    An image object representing the result of the compositing operation.

    Discussion

    Calling this method is equivalent to using the CISourceOverCompositing filter. To use other compositing operations and blending modes, create a CIFilter object using one of the built-in filters from the CICategoryCompositeOperation category. For details, see Core Image Filter Reference.

    Import Statement

    Objective-C

    @import QuartzCore;

    Swift

    import QuartzCore

    Availability

    Available in OS X v10.4 and later.

  • Initializes an image with the specified color.

    Declaration

    Swift

    init!(color color: CIColor!)

    Objective-C

    - (id)initWithColor:(CIColor *)color

    Parameters

    color

    A color object.

    Return Value

    The initialized image object or nil if the object could not be initialized.

    Import Statement

    Objective-C

    @import QuartzCore;

    Swift

    import QuartzCore

    Availability

    Available in OS X v10.5 and later.

  • Initializes an image object with bitmap data.

    Declaration

    Swift

    init!(bitmapData d: NSData!, bytesPerRow bpr: Int, size size: CGSize, format f: CIFormat, colorSpace c: CGColorSpace!)

    Objective-C

    - (id)initWithBitmapData:(NSData *)d bytesPerRow:(size_t)bpr size:(CGSize)size format:(CIFormat)f colorSpace:(CGColorSpaceRef)c

    Parameters

    d

    The bitmap data to use for the image. The data you supply must be premultiplied.

    bpr

    The number of bytes per row.

    size

    The size of the image data.

    f

    A pixel format constant. See “Pixel Formats”.

    c

    The color space that the image is defined in and must be a Quartz 2D color space (CGColorSpaceRef). Pass nil for images that don’t contain color data (such as elevation maps, normal vector maps, and sampled function tables).

    Return Value

    The initialized image object or nil if the object could not be initialized.

    Import Statement

    Objective-C

    @import QuartzCore;

    Swift

    import QuartzCore

    Availability

    Available in OS X v10.4 and later.

  • Initializes an image object with a Quartz 2D image.

    Declaration

    Swift

    init!(CGImage image: CGImage!)

    Objective-C

    - (id)initWithCGImage:(CGImageRef)image

    Parameters

    image

    A Quartz 2D image (CGImageRef) object. For more information, see Quartz 2D Programming Guide and CGImage Reference.

    Return Value

    The initialized image object or nil if the object could not be initialized.

    Import Statement

    Objective-C

    @import QuartzCore;

    Swift

    import QuartzCore

    Availability

    Available in OS X v10.4 and later.

  • Initializes an image object with a Quartz 2D image, using the specified options.

    Declaration

    Swift

    init!(CGImage image: CGImage!, options d: [NSObject : AnyObject]!)

    Objective-C

    - (id)initWithCGImage:(CGImageRef)image options:(NSDictionary *)d

    Parameters

    image

    A Quartz 2D image (CGImageRef) object. For more information, see Quartz 2D Programming Guide and CGImage Reference.

    d

    A dictionary specifying image options. (See “Image Dictionary Keys”.)

    Return Value

    The initialized image object or nil if the object could not be initialized.

    Import Statement

    Objective-C

    @import QuartzCore;

    Swift

    import QuartzCore

    Availability

    Available in OS X v10.4 and later.

  • Initializes an image object with the specified bitmap image representation.

    Declaration

    Swift

    init?(bitmapImageRep bitmapImageRep: NSBitmapImageRep)

    Objective-C

    - (instancetype)initWithBitmapImageRep:(NSBitmapImageRep *)bitmapImageRep

    Parameters

    bitmapImageRep

    An image representation object containing the bitmap data.

    Return Value

    The initialized image object or nil if the object could not be initialized.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Initializes an image object from the contents supplied by a CGLayer object.

    Declaration

    Swift

    init!(CGLayer layer: CGLayer!)

    Objective-C

    - (id)initWithCGLayer:(CGLayerRef)layer

    Parameters

    layer

    A CGLayer object. For more information see Quartz 2D Programming Guide and CGLayer Reference.

    Return Value

    The initialized image object or nil if the object could not be initialized.

    Import Statement

    Objective-C

    @import QuartzCore;

    Swift

    import QuartzCore

    Availability

    Available in OS X v10.4 and later.

  • Initializes an image object from the contents supplied by a CGLayer object, using the specified options.

    Declaration

    Swift

    init!(CGLayer layer: CGLayer!, options d: [NSObject : AnyObject]!)

    Objective-C

    - (id)initWithCGLayer:(CGLayerRef)layer options:(NSDictionary *)d

    Parameters

    layer

    A CGLayer object. For more information see Quartz 2D Programming Guide and CGLayer Reference.

    d

    A dictionary specifying image options. (See “Image Dictionary Keys”.)

    Return Value

    The initialized image object or nil if the object could not be initialized.

    Import Statement

    Objective-C

    @import QuartzCore;

    Swift

    import QuartzCore

    Availability

    Available in OS X v10.4 and later.

  • Initializes an image object by reading an image from a URL.

    Declaration

    Swift

    init!(contentsOfURL url: NSURL!)

    Objective-C

    - (id)initWithContentsOfURL:(NSURL *)url

    Parameters

    url

    The location of the image file to read.

    Return Value

    The initialized image object or nil if the object could not be initialized.

    Import Statement

    Objective-C

    @import QuartzCore;

    Swift

    import QuartzCore

    Availability

    Available in OS X v10.4 and later.

  • Initializes an image object by reading an image from a URL, using the specified options.

    Declaration

    Swift

    init!(contentsOfURL url: NSURL!, options d: [NSObject : AnyObject]!)

    Objective-C

    - (id)initWithContentsOfURL:(NSURL *)url options:(NSDictionary *)d

    Parameters

    url

    The location of the image file to read.

    d

    A dictionary specifying image options. (See “Image Dictionary Keys”.)

    Return Value

    The initialized image object or nil if the object could not be initialized.

    Import Statement

    Objective-C

    @import QuartzCore;

    Swift

    import QuartzCore

    Availability

    Available in OS X v10.4 and later.

  • Initializes an image object from the contents of CVImageBuffer object.

    Declaration

    Swift

    init!(CVImageBuffer imageBuffer: CVImageBuffer!)

    Objective-C

    - (id)initWithCVImageBuffer:(CVImageBufferRef)imageBuffer

    Parameters

    imageBuffer

    A CVImageBuffer object in a supported pixel format constant. For more information, see Core Video Programming Guide and Core Video Reference Collection.

    Return Value

    The initialized image object or nil if the object could not be initialized.

    Discussion

    The imageBuffer parameter must be in one of the following formats:

    Import Statement

    Objective-C

    @import QuartzCore;

    Swift

    import QuartzCore

    Availability

    Available in OS X v10.4 and later.

  • Initializes an image object from the contents of CVImageBuffer object, using the specified options.

    Declaration

    Swift

    init!(CVImageBuffer imageBuffer: CVImageBuffer!, options dict: [NSObject : AnyObject]!)

    Objective-C

    - (id)initWithCVImageBuffer:(CVImageBufferRef)imageBuffer options:(NSDictionary *)dict

    Parameters

    imageBuffer

    A CVImageBuffer object in a supported pixel format constant. For more information, see Core Video Programming Guide and Core Video Reference Collection.

    dict

    A dictionary that contains options for creating an image object. (See “Image Dictionary Keys”.) The pixel format is supplied by the CVImageBuffer object.)

    Return Value

    The initialized image object or nil if the object could not be initialized.

    Discussion

    The imageBuffer parameter must be in one of the following formats:

    Import Statement

    Objective-C

    @import QuartzCore;

    Swift

    import QuartzCore

    Availability

    Available in OS X v10.4 and later.

  • Initializes an image object with the supplied image data.

    Declaration

    Swift

    init!(data data: NSData!)

    Objective-C

    - (id)initWithData:(NSData *)data

    Parameters

    data

    The image data. The data you supply must be premultiplied.

    Return Value

    The initialized image object or nil if the object could not be initialized.

    Import Statement

    Objective-C

    @import QuartzCore;

    Swift

    import QuartzCore

    Availability

    Available in OS X v10.4 and later.

  • Initializes an image object with the supplied image data, using the specified options.

    Declaration

    Swift

    init!(data data: NSData!, options d: [NSObject : AnyObject]!)

    Objective-C

    - (id)initWithData:(NSData *)data options:(NSDictionary *)d

    Parameters

    data

    The image data. The data you supply must be premultiplied.

    d

    A dictionary specifying image options. (See “Image Dictionary Keys”.)

    Return Value

    The initialized image object or nil if the object could not be initialized.

    Import Statement

    Objective-C

    @import QuartzCore;

    Swift

    import QuartzCore

    Availability

    Available in OS X v10.4 and later.

  • Initializes an image object with data provided by an image provider, using the specified options.

    Declaration

    Swift

    init!(imageProvider p: AnyObject!, size width : Int, _ height: Int, format f: CIFormat, colorSpace cs: CGColorSpace!, options dict: [NSObject : AnyObject]!)

    Objective-C

    - (id)initWithImageProvider:(id)p size:(size_t)width :(size_t)height format:(CIFormat)f colorSpace:(CGColorSpaceRef)cs options:(NSDictionary *)dict

    Parameters

    p

    A data provider that implements the CIImageProvider informal protocol. Core Image maintains a strong reference to this object until the image is deallocated.

    width

    The width of the image data.

    height

    The height of the image data.

    f

    A pixel format constant. See “Pixel Formats”.

    cs

    The color space of the image. If this value is nil, the image is not color matched. Pass nil for images that don’t contain color data (such as elevation maps, normal vector maps, and sampled function tables).

    dict

    A dictionary that specifies image-creation options, which can be kCIImageProviderTileSize or kCIImageProviderUserInfo. See CIImageProvider Protocol Reference for more information on these options.

    Return Value

    The initialized image object or nil if the object could not be initialized.

    Discussion

    Core Image does not populate the image until it actually needs the data.

    Import Statement

    Objective-C

    @import QuartzCore;

    Swift

    import QuartzCore

    Availability

    Available in OS X v10.6 and later.

  • Initializes an image object with data supplied by an OpenGL texture.

    Declaration

    Swift

    init!(texture name: UInt32, size size: CGSize, flipped flag: Bool, colorSpace cs: CGColorSpace!)

    Objective-C

    - (id)initWithTexture:(unsigned int)name size:(CGSize)size flipped:(BOOL)flag colorSpace:(CGColorSpaceRef)cs

    Parameters

    name

    An OpenGL texture. Because CIImage objects are immutable, the texture must remain unchanged for the life of the image object. See the discussion for more information.

    size

    The dimensions of the texture.

    flag

    YEStrue to have Core Image flip the coordinates of the texture vertically to convert between OpenGL and Core Image coordinate systems.

    cs

    The color space that the image is defined in. This must be a Quartz color space (CGColorSpaceRef). If the colorSpace value is nil, the image is not color matched. Pass nil for images that don’t contain color data (such as elevation maps, normal vector maps, and sampled function tables).

    Return Value

    The initialized image object or nil if the object could not be initialized.

    Discussion

    When using a texture to create a CIImage object, the texture must be valid in the Core Image context (CIContext) that you draw the CIImage object into. This means that one of the following must be true:

    • The texture must be created using the CGLContext object that the CIContext is based on.

    • The context that the texture was created in must be shared with the CGLContext that the CIContextis based on.

    Note that textures do not have a retain and release mechanism. This means that your application must make sure that the texture exists for the life cycle of the image. When you no longer need the image, you can delete the texture.

    Core Image ignores the texture filtering and wrap modes (GL_TEXTURE_FILTER and GL_TEXTURE_WRAP) that you set through OpenGL. The filter and wrap modes are overridden by what the CISampler object specifies when you apply a filter to the CIImage object.

    Import Statement

    Objective-C

    @import QuartzCore;

    Swift

    import QuartzCore

    Availability

    Available in OS X v10.4 and later.

  • Initializes an image object with data supplied by an OpenGL texture.

    Declaration

    Swift

    init!(texture name: UInt32, size size: CGSize, flipped flag: Bool, options options: [NSObject : AnyObject]!)

    Objective-C

    - (id)initWithTexture:(unsigned int)name size:(CGSize)size flipped:(BOOL)flag options:(NSDictionary *)options

    Parameters

    name

    An OpenGL texture. Because CIImage objects are immutable, the texture must remain unchanged for the life of the image object. See the discussion for more information.

    size

    The dimensions of the texture.

    flag

    YEStrue to have Core Image flip the coordinates of the texture vertically to convert between OpenGL and Core Image coordinate systems.

    options

    A dictionary specifying image options. (See “Image Dictionary Keys”.)

    Return Value

    The initialized image object or nil if the object could not be initialized.

    Discussion

    When using a texture to create a CIImage object, the texture must be valid in the Core Image context (CIContext) that you draw the CIImage object into. This means that one of the following must be true:

    • The texture must be created using the CGLContext object that the CIContext is based on.

    • The context that the texture was created in must be shared with the CGLContext that the CIContextis based on.

    Note that textures do not have a retain and release mechanism. This means that your application must make sure that the texture exists for the life cycle of the image. When you no longer need the image, you can delete the texture.

    Core Image ignores the texture filtering and wrap modes (GL_TEXTURE_FILTER and GL_TEXTURE_WRAP) that you set through OpenGL. The filter and wrap modes are overridden by what the CISampler object specifies when you apply a filter to the CIImage object.

    Import Statement

    Objective-C

    @import QuartzCore;

    Swift

    import QuartzCore

    Availability

    Available in OS X v10.9 and later.

  • Initializes an image with the contents of an IOSurface.

    Declaration

    Swift

    init!(IOSurface surface: IOSurface!)

    Objective-C

    - (id)initWithIOSurface:(IOSurfaceRef)surface

    Parameters

    surface

    An IOSurface object.

    Return Value

    An image object initialized with the data from the IOSurface object.

    Discussion

    An IOSurface object is a framebuffer object that is suitable for sharing across process boundaries. You can use it to allow your app to move complex image decompression and drawing logic into a separate process for the purpose of increasing security.

    Import Statement

    Objective-C

    @import QuartzCore;

    Swift

    import QuartzCore

    Availability

    Available in OS X v10.6 and later.

  • Initializes, using the specified options, an image with the contents of an IOSurface.

    Declaration

    Swift

    init!(IOSurface surface: IOSurface!, options options: [NSObject : AnyObject]!)

    Objective-C

    - (id)initWithIOSurface:(IOSurfaceRef)surface options:(NSDictionary *)options

    Parameters

    surface

    An IOSurface object.

    options

    A dictionary specifying image options. (See “Image Dictionary Keys”.)

    Return Value

    An image object initialized with the data from the IOSurface.

    Import Statement

    Objective-C

    @import QuartzCore;

    Swift

    import QuartzCore

    Availability

    Available in OS X v10.6 and later.

  • Initializes, using the specified format and options, an image with the contents of a specific data plane in an IOSurface.

    Declaration

    Swift

    init!(IOSurface surface: IOSurface!, plane plane: Int, format format: CIFormat, options options: [NSObject : AnyObject]!)

    Objective-C

    - (id)initWithIOSurface:(IOSurfaceRef)surface plane:(size_t)plane format:(CIFormat)format options:(NSDictionary *)options

    Parameters

    surface

    An IOSurface object.

    plane

    The index of the data plane in the IOSurface object containing bitmap data for initializing the image.

    format

    A pixel format constant. See “Pixel Formats”.

    options

    A dictionary specifying image options. (See “Image Dictionary Keys”.)

    Return Value

    An image object initialized with the data from the IOSurface.

    Import Statement

    Objective-C

    @import QuartzCore;

    Swift

    import QuartzCore

    Availability

    Available in OS X v10.9 and later.

  • Returns a filter shape object that represents the domain of definition of the image.

    Declaration

    Swift

    func definition() -> CIFilterShape!

    Objective-C

    - (CIFilterShape *)definition

    Return Value

    A filter shape object.

    Import Statement

    Objective-C

    @import QuartzCore;

    Swift

    import QuartzCore

    Availability

    Available in OS X v10.4 and later.

    See Also

    – extent

  • Returns a rectangle that specifies the extent of the image.

    Declaration

    Swift

    func extent() -> CGRect

    Objective-C

    - (CGRect)extent

    Return Value

    A rectangle that specifies the extent of the image in working space coordinates.

    Import Statement

    Objective-C

    @import QuartzCore;

    Swift

    import QuartzCore

    Availability

    Available in OS X v10.4 and later.

    See Also

    – definition

  • Returns a dictionary containing image metadata.

    Declaration

    Swift

    func properties() -> [NSObject : AnyObject]!

    Objective-C

    - (NSDictionary *)properties

    Return Value

    An NSDictionary object containing image metadata.

    Discussion

    If the CIImage object is the output of a filter (or filter chain), this method returns the metadata from the filter’s original input image.

    Import Statement

    Objective-C

    @import QuartzCore;

    Swift

    import QuartzCore

    Availability

    Available in OS X v10.8 and later.

  • Returns the URL the image was loaded from.

    Declaration

    Swift

    func url() -> NSURL!

    Objective-C

    - (NSURL *)url

    Return Value

    An NSURL object referencing the location the image was loaded from.

    Discussion

    Returns nil if the URL cannot be determined. A URL is only available if the image object was created with a URL (as by the initWithContentsOfURL: method and related methods).

    Import Statement

    Objective-C

    @import QuartzCore;

    Swift

    import QuartzCore

    Availability

    Available in OS X v10.4 and later.

  • Returns the color space of the image.

    Declaration

    Swift

    func colorSpace() -> Unmanaged<CGColorSpace>!

    Objective-C

    - (CGColorSpaceRef)colorSpace

    Return Value

    A CGColorSpaceRef object describing the image’s color space.

    Discussion

    Returns nil if the image’s color space cannot be determined.

    Import Statement

    Objective-C

    @import QuartzCore;

    Swift

    import QuartzCore

    Availability

    Available in OS X v10.4 and later.

  • Returns the transformation needed to reorient the image to the specified orientation.

    Declaration

    Swift

    func imageTransformForOrientation(_ orientation: Int32) -> CGAffineTransform

    Objective-C

    - (CGAffineTransform)imageTransformForOrientation:(int)orientation

    Parameters

    orientation

    An integer specifying an image orientation according to the EXIF specification. For details, see kCGImagePropertyOrientation.

    Return Value

    An affine transform that will rotate or mirror the image to match the specified orientation when applied.

    Discussion

    This method determines the transformation needed to match the specified orientation, but does not apply that transformation to the image. To apply the transformation (possibly after concatenating it with other transformations), use the imageByApplyingTransform: method or the CIAffineTransform filter. To determine and apply the transformation in a single step, use the imageByApplyingOrientation: method.

    Import Statement

    Objective-C

    @import QuartzCore;

    Swift

    import QuartzCore

    Availability

    Available in OS X v10.10 and later.

  • Draws all or part of the image at the specified point in the current coordinate system.

    Declaration

    Swift

    func drawAtPoint(_ point: NSPoint, fromRect srcRect: NSRect, operation op: NSCompositingOperation, fraction delta: CGFloat)

    Objective-C

    - (void)drawAtPoint:(NSPoint)point fromRect:(NSRect)srcRect operation:(NSCompositingOperation)op fraction:(CGFloat)delta

    Parameters

    point

    The location in the current coordinate system at which to draw the image.

    srcRect

    The source rectangle specifying the portion of the image you want to draw. The coordinates of this rectangle must be specified using the image's own coordinate system.

    op

    The compositing operation to use when drawing the image. For details, see NSCompositingOperation.

    delta

    The opacity of the image, specified as a value from 0.0 to 1.0. Specifying a value of 0.0 draws the image as fully transparent while a value of 1.0 draws the image as fully opaque. Values greater than 1.0 are interpreted as 1.0.

    Discussion

    The image content is drawn at its current resolution and is not scaled unless the CTM of the current coordinate system itself contains a scaling factor. The image is otherwise positioned and oriented using the current coordinate system.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Draws all or part of the image in the specified rectangle in the current coordinate system

    Declaration

    Swift

    func drawInRect(_ dstRect: NSRect, fromRect srcRect: NSRect, operation op: NSCompositingOperation, fraction delta: CGFloat)

    Objective-C

    - (void)drawInRect:(NSRect)dstRect fromRect:(NSRect)srcRect operation:(NSCompositingOperation)op fraction:(CGFloat)delta

    Parameters

    dstRect

    The rectangle in which to draw the image.

    srcRect

    The source rectangle specifying the portion of the image you want to draw. The coordinates of this rectangle must be specified using the image's own coordinate system.

    op

    The compositing operation to use when drawing the image. For details, see NSCompositingOperation.

    delta

    The opacity of the image, specified as a value from 0.0 to 1.0. Specifying a value of 0.0 draws the image as fully transparent while a value of 1.0 draws the image as fully opaque. Values greater than 1.0 are interpreted as 1.0.

    Discussion

    If the srcRect and dstRect rectangles have different sizes, the source portion of the image is scaled to fit the specified destination rectangle. The image is otherwise positioned and oriented using the current coordinate system.

    Import Statement

    Objective-C

    @import AppKit;

    Swift

    import AppKit

    Availability

    Available in OS X v10.4 and later.

  • Returns all possible automatically selected and configured filters for adjusting the image.

    Declaration

    Swift

    func autoAdjustmentFilters() -> [AnyObject]!

    Objective-C

    - (NSArray *)autoAdjustmentFilters

    Return Value

    An array of CIFilter instances preconfigured for correcting deficiencies in the supplied image.

    Import Statement

    Objective-C

    @import QuartzCore;

    Swift

    import QuartzCore

    Availability

    Available in OS X v10.8 and later.

  • Returns a subset of automatically selected and configured filters for adjusting the image.

    Declaration

    Swift

    func autoAdjustmentFiltersWithOptions(_ options: [NSObject : AnyObject]!) -> [AnyObject]!

    Objective-C

    - (NSArray *)autoAdjustmentFiltersWithOptions:(NSDictionary *)options

    Parameters

    options

    You can control which filters are returned by supplying one or more of the keys described in Autoadjustment Keys.

    The options dictionary can also contain a CIDetectorImageOrientation key. Because some autoadjustment filters rely on face detection, you should specify an image orientation if you want to enable these filters for an image containing face whose orientation does not match that of the image.

    Return Value

    An array of CIFilter instances preconfigured for correcting deficiencies in the supplied image.

    Import Statement

    Objective-C

    @import QuartzCore;

    Swift

    import QuartzCore

    Availability

    Available in OS X v10.8 and later.

Data Types

  • A data type used for specifying image pixel formats.

    Declaration

    Swift

    typealias CIFormat = Int32

    Objective-C

    typedef int CIFormat;

    Import Statement

    Objective-C

    @import QuartzCore;

    Swift

    import QuartzCore

    Availability

    Available in OS X v10.6 and later.

  • Image data pixel formats.

    Declaration

    Swift

    var kCIFormatARGB8: CIFormat var kCIFormatRGBA16: CIFormat var kCIFormatRGBAf: CIFormat var kCIFormatRGBAh: CIFormat

    Objective-C

    extern CIFormat kCIFormatARGB8; extern CIFormat kCIFormatRGBA16; extern CIFormat kCIFormatRGBAf; extern CIFormat kCIFormatRGBAh;

    Constants

    • kCIFormatARGB8

      kCIFormatARGB8

      A 32 bit-per-pixel, fixed-point pixel format in which the alpha value precedes the red, green and blue color components.

      Available in OS X v10.4 and later.

    • kCIFormatRGBA16

      kCIFormatRGBA16

      A 64 bit-per-pixel, fixed-point pixel format.

      Available in OS X v10.4 and later.

    • kCIFormatRGBAf

      kCIFormatRGBAf

      A 128 bit-per-pixel, floating-point pixel format.

      Available in OS X v10.4 and later.

    • kCIFormatRGBAh

      kCIFormatRGBAh

      A 64 bit-per-pixel, floating-point pixel format.

      Available in OS X v10.4 and later.

  • Constants used as keys in the options dictionary when initializing an image.

    Declaration

    Swift

    let kCIImageColorSpace: String let kCIImageProperties: String let kCIImageTextureTarget: String let kCIImageTextureFormat: String

    Objective-C

    extern NSString *kCIImageColorSpace; extern NSString *kCIImageProperties; extern NSString *kCIImageTextureTarget; extern NSString *kCIImageTextureFormat;

    Constants

    • kCIImageColorSpace

      kCIImageColorSpace

      The key for a color space.

      For more information on this data type see CGColorSpace Reference. Typically you use this option when you need to load an elevation, mask, normal vector, or RAW sensor data directly from a file without color correcting it. This constant specifies to override Core Image, which, by default, assumes that data is in GenericRGB.

      To request that Core Image perform no color management, specify the NSNull object as the value for this key. Use this option for images that don’t contain color data (such as elevation maps, normal vector maps, and sampled function tables).

      Available in OS X v10.6 and later.

    • kCIImageProperties

      kCIImageProperties

      The key for image metadata properties.

      The value you supply for this dictionary key must be a CGColorSpaceRef data type. If a value for this key isn’t supplied, the image’s colorSpace dictionary are populated automatically by calling CGImageSourceCopyPropertiesAtIndex. To ensure that an image has no metadata properties, set the value of this key to [NSNull null].

      Available in OS X v10.8 and later.

    • kCIImageTextureTarget

      kCIImageTextureTarget

      The key for an OpenGL texture target.

      The value for this key must be an NSNumber object containing a supported OpenGL texture target constant, either GL_TEXTURE_2D or GL_TEXTURE_RECTANGLE_ARB. You may only use this key when initializing an image using the initWithTexture:size:flipped:options: method.

      Available in OS X v10.9 and later.

    • kCIImageTextureFormat

      kCIImageTextureFormat

      The key for an OpenGL texture format.

      The value for this key must be an NSNumber object containing a Core Image pixel format constant. (See Pixel Formats.) You may only use this key when initializing an image using the initWithTexture:size:flipped:options: method.

      Available in OS X v10.9 and later.

  • Constants used as keys in the options dictionary for the autoAdjustmentFiltersWithOptions: method.

    Declaration

    Swift

    let kCIImageAutoAdjustEnhance: String let kCIImageAutoAdjustRedEye: String let kCIImageAutoAdjustFeatures: String let kCIImageAutoAdjustCrop: String let kCIImageAutoAdjustLevel: String

    Objective-C

    NSString *kCIImageAutoAdjustEnhance; NSString *kCIImageAutoAdjustRedEye; NSString *kCIImageAutoAdjustFeatures; NSString *kCIImageAutoAdjustCrop; NSString *kCIImageAutoAdjustLevel;

    Constants

    • kCIImageAutoAdjustEnhance

      kCIImageAutoAdjustEnhance

      A key used to specify whether to return enhancement filters.

      The value associated with this key is a CFBoolean value. Supply false to indicate not to return enhancement filters. If you don’t specify this option, Core Image assumes its value is true.

      Available in OS X v10.8 and later.

    • kCIImageAutoAdjustRedEye

      kCIImageAutoAdjustRedEye

      A key used to specify whether to return a red eye filter.

      The value associated with this key is a CFBoolean value. Supply false to indicate not to return a red eye filter. If you don’t specify this option, Core Image assumes its value is true.

      Available in OS X v10.8 and later.

    • kCIImageAutoAdjustFeatures

      kCIImageAutoAdjustFeatures

      A key used to specify an array of features that you want to apply enhancement and red eye filters to.

      The associated value is an array of CIFeature objects. If you don’t supply an array, the Core Image searches for features using the CIDetector class.

      Available in OS X v10.8 and later.

    • kCIImageAutoAdjustCrop

      kCIImageAutoAdjustCrop

      A key used to specify whether to return a filter that crops the image to focus on detected features.

      The value associated with this key is a CFBoolean value. If true, the returned filters include an operation that crops the image around the features specified with the kCIImageAutoAdjustFeatures option (or any features detected in the image, if that option is not present). Supply false to indicate not to return a crop filter. If you don’t specify this option, Core Image assumes its value is false.

      Available in OS X v10.10 and later.

    • kCIImageAutoAdjustLevel

      kCIImageAutoAdjustLevel

      A key used to specify whether to return a filter that rotates the image to keep a level perspective.

      The value associated with this key is a CFBoolean value. If true, Core Image analyzes the image to determine whether it would benefit from rotation—for example, a landscape photo in which the horizon is not horizontal—and returns a filter to perform that rotation. Supply false to indicate not to return a rotation filter. If you don’t specify this option, Core Image assumes its value is false.

      Available in OS X v10.10 and later.