CIImage Class Reference

Inherits from
Conforms to
Framework
Library/Frameworks/CoreImage.framework
Availability
Available in OS X v10.4 and later.
Companion guide
Declared in
CIImage.h
CIImageProvider.h
Related sample code

Overview

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 defines methods for creating and initializing images. Additional methods that support drawing and initializing an image with an NSBitmapImageRep object are defined in CIImage Additions Reference.

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.

Tasks

Creating an Image

Creating an Image by Modifying an Existing Image

Initializing an Image

Getting Image Information

Getting Autoadjustment Filters

Class Methods

emptyImage

Creates and returns an empty image object.

+ (CIImage *)emptyImage
Return Value

An image object.

Availability
  • Available in OS X v10.5 and later.
Declared In
CIImage.h

imageWithBitmapData:bytesPerRow:size:format:colorSpace:

Creates and returns an image object from bitmap data.

+ (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.

Availability
  • Available in OS X v10.4 and later.
Declared In
CIImage.h

imageWithCGImage:

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

+ (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.

Availability
  • Available in OS X v10.4 and later.
Related Sample Code
Declared In
CIImage.h

imageWithCGImage:options:

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

+ (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.

Availability
  • Available in OS X v10.4 and later.
Declared In
CIImage.h

imageWithCGLayer:

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

+ (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.

Availability
  • Available in OS X v10.4 and later.
Declared In
CIImage.h

imageWithCGLayer:options:

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

+ (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.

Availability
  • Available in OS X v10.4 and later.
Declared In
CIImage.h

imageWithColor:

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

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

A color object.

Return Value

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

Availability
  • Available in OS X v10.5 and later.
Declared In
CIImage.h

imageWithContentsOfURL:

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

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

The location of the file.

Return Value

An image object initialized with the contents of the file.

Availability
  • Available in OS X v10.4 and later.
Declared In
CIImage.h

imageWithContentsOfURL:options:

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

+ (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.

Availability
  • Available in OS X v10.4 and later.
Declared In
CIImage.h

imageWithCVImageBuffer:

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

+ (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.

Availability
  • Available in OS X v10.4 and later.
Declared In
CIImage.h

imageWithCVImageBuffer:options:

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

+ (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.

Availability
  • Available in OS X v10.4 and later.
Declared In
CIImage.h

imageWithData:

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

+ (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.

Availability
  • Available in OS X v10.4 and later.
Declared In
CIImage.h

imageWithData:options:

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

+ (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.

Availability
  • Available in OS X v10.4 and later.
Declared In
CIImage.h

imageWithImageProvider:size::format:colorSpace:options:

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

+ (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.

Availability
  • Available in OS X v10.6 and later.
Declared In
CIImageProvider.h

imageWithIOSurface:

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

+ (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.

Availability
  • Available in OS X v10.6 and later.
Declared In
CIImage.h

imageWithIOSurface:options:

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

+ (CIImage *)imageWithIOSurface:(IOSurfaceRef)surface options:(NSDictionary *)d
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.

Availability
  • Available in OS X v10.6 and later.
Declared In
CIImage.h

imageWithTexture:size:flipped:colorSpace:

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

+ (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

YES 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.

Availability
  • Available in OS X v10.4 and later.
Related Sample Code
Declared In
CIImage.h

imageWithTexture:size:flipped:options:

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

+ (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

YES 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.

Availability
  • Available in OS X v10.9 and later.
Declared In
CIImage.h

Instance Methods

autoAdjustmentFilters

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

- (NSArray *)autoAdjustmentFilters
Return Value

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

Availability
  • Available in OS X v10.8 and later.
Declared In
CIImage.h

autoAdjustmentFiltersWithOptions:

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

- (NSArray *)autoAdjustmentFiltersWithOptions:(NSDictionary *)dict
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.

Availability
  • Available in OS X v10.8 and later.
Declared In
CIImage.h

colorSpace

Returns the color space of the image.

- (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.

Availability
  • Available in OS X v10.4 and later.
Declared In
CIImage.h

definition

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

- (CIFilterShape *)definition
Return Value

A filter shape object.

Availability
  • Available in OS X v10.4 and later.
See Also
Declared In
CIImage.h

extent

Returns a rectangle that specifies the extent of the image.

- (CGRect)extent
Return Value

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

Availability
  • Available in OS X v10.4 and later.
Declared In
CIImage.h

imageByApplyingTransform:

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

- (CIImage *)imageByApplyingTransform:(CGAffineTransform)matrix
Parameters
matrix

An affine transform.

Return Value

The transformed image object.

Availability
  • Available in OS X v10.4 and later.
Related Sample Code
Declared In
CIImage.h

imageByCroppingToRect:

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

- (CIImage *)imageByCroppingToRect:(CGRect)r
Return Value

An image object cropped to the specified rectangle.

Availability
  • Available in OS X v10.5 and later.
Declared In
CIImage.h

initWithBitmapData:bytesPerRow:size:format:colorSpace:

Initializes an image object with bitmap data.

- (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.

Availability
  • Available in OS X v10.4 and later.
Declared In
CIImage.h

initWithCGImage:

Initializes an image object with a Quartz 2D image.

- (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.

Availability
  • Available in OS X v10.4 and later.
Declared In
CIImage.h

initWithCGImage:options:

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

- (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.

Availability
  • Available in OS X v10.4 and later.
Declared In
CIImage.h

initWithCGLayer:

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

- (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.

Availability
  • Available in OS X v10.4 and later.
Related Sample Code
Declared In
CIImage.h

initWithCGLayer:options:

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

- (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.

Availability
  • Available in OS X v10.4 and later.
Declared In
CIImage.h

initWithColor:

Initializes an image with the specified color.

- (id)initWithColor:(CIColor *)color
Parameters
color

A color object.

Return Value

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

Availability
  • Available in OS X v10.5 and later.
Declared In
CIImage.h

initWithContentsOfURL:

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

- (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.

Availability
  • Available in OS X v10.4 and later.
Declared In
CIImage.h

initWithContentsOfURL:options:

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

- (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.

Availability
  • Available in OS X v10.4 and later.
Declared In
CIImage.h

initWithCVImageBuffer:

Initializes an image object from the contents of CVImageBuffer object.

- (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:

Availability
  • Available in OS X v10.4 and later.
Related Sample Code
Declared In
CIImage.h

initWithCVImageBuffer:options:

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

- (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:

Availability
  • Available in OS X v10.4 and later.
Declared In
CIImage.h

initWithData:

Initializes an image object with the supplied image data.

- (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.

Availability
  • Available in OS X v10.4 and later.
Declared In
CIImage.h

initWithData:options:

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

- (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.

Availability
  • Available in OS X v10.4 and later.
Declared In
CIImage.h

initWithImageProvider:size::format:colorSpace:options:

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

- (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.

Availability
  • Available in OS X v10.6 and later.
Declared In
CIImageProvider.h

initWithIOSurface:

Initializes an image with the contents of an IOSurface.

- (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.

Availability
  • Available in OS X v10.6 and later.
Declared In
CIImage.h

initWithIOSurface:options:

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

- (id)initWithIOSurface:(IOSurfaceRef)surface options:(NSDictionary *)d
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.

Availability
  • Available in OS X v10.6 and later.
Declared In
CIImage.h

initWithIOSurface:plane:format:options:

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

- (id)initWithIOSurface:(IOSurfaceRef)surface plane:(size_t)plane format:(CIFormat)format options:(NSDictionary *)d
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.

Availability
  • Available in OS X v10.9 and later.
Declared In
CIImage.h

initWithTexture:size:flipped:colorSpace:

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

- (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

YES 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.

Availability
  • Available in OS X v10.4 and later.
Declared In
CIImage.h

initWithTexture:size:flipped:options:

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

- (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

YES 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.

Availability
  • Available in OS X v10.9 and later.
Declared In
CIImage.h

properties

Returns a dictionary containing image metadata.

- (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.

Availability
  • Available in OS X v10.8 and later.
Declared In
CIImage.h

url

Returns the URL the image was loaded from.

- (NSURL *)properties
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).

Availability
  • Available in OS X v10.4 and later.
Declared In
CIImage.h

Constants

CIFormat

A data type used for specifying image pixel formats.

typedef int CIFormat;
Availability
  • Available in OS X v10.6 and later.
Declared In
CIImage.h

Pixel Formats

Image data pixel formats.

extern CIFormat kCIFormatARGB8;
extern CIFormat kCIFormatRGBA16;
extern CIFormat kCIFormatRGBAf;
extern CIFormat kCIFormatRGBAh;
Constants
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.

Declared in CIImage.h.

kCIFormatRGBA16

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

Available in OS X v10.4 and later.

Declared in CIImage.h.

kCIFormatRGBAf

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

Available in OS X v10.4 and later.

Declared in CIImage.h.

kCIFormatRGBAh

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

Available in OS X v10.4 and later.

Declared in CIImage.h.

Declared In
CIImage.h

Image Dictionary Keys

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

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

The key for a color space. The value you supply for this dictionary key must be a CGColorSpaceRef data type. 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.

Available in OS X v10.6 and later.

Declared in CIImage.h.

kCIImageProperties

The key for image metadata properties. 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.

Declared in CIImage.h.

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.

Declared in CIImage.h.

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.

Declared in CIImage.h.

Declared In
CIImage.h

Autoadjustment Keys

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

NSString *kCIImageAutoAdjustEnhance;
NSString *kCIImageAutoAdjustRedEye;
NSString *kCIImageAutoAdjustFeatures;
Constants
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.

Declared in CIImage.h.

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.

Declared in CIImage.h.

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.

Declared in CIImage.h.