---

CIImage Class Reference

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.

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.

Tasks

Creating an Image

• + emptyImage
• + imageWithColor:
• + imageWithBitmapData:bytesPerRow:size:format:colorSpace:
• + imageWithCGImage:
• + imageWithCGImage:options:
• + imageWithCGLayer:
• + imageWithCGLayer:options:
• + imageWithContentsOfURL:
• + imageWithContentsOfURL:options:
• + imageWithCVImageBuffer:
• + imageWithCVImageBuffer:options:
• + imageWithData:
• + imageWithData:options:
• + imageWithImageProvider:size:format:colorSpace:options:
• + imageWithTexture:size:flipped:colorSpace:

Creating an Image by Modifying an Existing Image

• – imageByApplyingTransform:
• – imageByCroppingToRect:

Initializing an Image

• – initWithColor:
• – initWithBitmapData:bytesPerRow:size:format:colorSpace:
• – initWithCGImage:
• – initWithCGImage:options:
• – initWithCGLayer:
• – initWithCGLayer:options:
• – initWithContentsOfURL:
• – initWithContentsOfURL:options:
• – initWithCVImageBuffer:
• – initWithCVImageBuffer:options:
• – initWithData:
• – initWithData:options:
• – initWithImageProvider:size:format:colorSpace:options:
• – initWithTexture:size:flipped:colorSpace:

Getting Image Information

• – definition
• – extent

Class Methods

emptyImage

Creates and returns an empty image object.

+ (CIImage *)emptyImage

Return Value

An image object.

Availability

• Available in Mac 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

• Mac OS X v10.4 and later.

See Also

• – initWithBitmapData:bytesPerRow:size:format:colorSpace:

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

• Mac OS X v10.4 and later.

See Also

• + imageWithCGImage:options:
• – initWithCGImage:

Related Sample Code

• CIVideoDemoGL

Declared In

CIImage.h

imageWithCGImage:options:

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

+ (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 that contains a color space key (kCIImageColorSpace) whose value is a CGColorSpaceobject. (See CGColorSpaceRef.)

Return Value

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

Availability

• Mac OS X v10.4 and later.

See Also

• + imageWithCGImage:
• – initWithCGImage:options:

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

• Mac OS X v10.4 and later.

See Also

• + imageWithCGLayer:options:
• – initWithCGLayer:

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 that contains options for creating an image object. You can supply such options as a pixel format and a color space. See “Pixel Formats.”

Return Value

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

Availability

• Mac OS X v10.4 and later.

See Also

• + imageWithCGLayer:
• – initWithCGLayer:options:

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

See Also

• – initWithColor:

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

• Mac OS X v10.4 and later.

See Also

• + imageWithContentsOfURL:options:
• – initWithContentsOfURL:

Related Sample Code

• CIAnnotation
• CITransitionSelectorSample2

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 that contains options for creating an image object. You can supply such options as a pixel format and a color space. See “Pixel Formats.”

Return Value

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

Availability

• Mac OS X v10.4 and later.

See Also

• + imageWithContentsOfURL:
• – initWithContentsOfURL:options:

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.

Return Value

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

Availability

• Mac OS X v10.4 and later.

See Also

• + imageWithCVImageBuffer:options:
• – initWithCVImageBuffer:

Related Sample Code

• CIVideoDemoGL
• QTCarbonCoreImage101
• QTCoreImage101
• WhackedTV

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.

dict

A dictionary that contains options for creating an image object. You can supply such options as a color space. (The pixel format is supplied by the CVImageBuffer object.)

Return Value

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

Availability

• Mac OS X v10.4 and later.

See Also

• + imageWithCVImageBuffer:
• – initWithCVImageBuffer:options:

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

• Mac OS X v10.4 and later.

See Also

• + imageWithData:options:
• – initWithData:

Related Sample Code

• LayerBackedOpenGLView
• WebKitCIPlugIn

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 that contains options for creating an image object. You can supply such options as a pixel format and a color space. See “Pixel Formats”.

Return Value

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

Availability

• Mac OS X v10.4 and later.

See Also

• + imageWithData:
• – initWithData:options:

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 retains this data 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

• Mac OS X v10.4 and later.

Declared In

CIImageProvider.h

See Also

• – initWithImageProvider:size::format:colorSpace:options:

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 contents of the texture vertically.

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

• Mac OS X v10.4 and later.

See Also

• – initWithTexture:size:flipped:colorSpace:

Declared In

CIImage.h

Instance Methods

definition

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

- (CIFilterShape *)definition

Return Value

A filter shape object.

Availability

• Mac OS X v10.4 and later.

See Also

• – extent

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

• Mac OS X v10.4 and later.

See Also

• – definition

Related Sample Code

• CIVideoDemoGL
• QTCarbonCoreImage101
• QTCoreImage101
• Reducer
• UnsharpMask

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

• Mac OS X v10.4 and later.

See Also

• – imageByCroppingToRect:

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

See Also

• – imageByApplyingTransform:

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

• Mac OS X v10.4 and later.

See Also

• + imageWithBitmapData:bytesPerRow:size:format:colorSpace:

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

• Mac OS X v10.4 and later.

See Also

• – initWithCGImage:options:
• + imageWithCGImage:

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 that contains options for creating an image object. You can supply such options as a pixel format and a color space. See “Pixel Formats”.

Return Value

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

Availability

• Mac OS X v10.4 and later.

See Also

• – initWithCGImage:
• + imageWithCGImage:options:

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

• Mac OS X v10.4 and later.

See Also

• – initWithCGLayer:options:
• + imageWithCGLayer:

Related Sample Code

• CIAnnotation
• QTCarbonCoreImage101

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 that contains options for creating an image object. You can supply such options as a pixel format and a color space. See “Pixel Formats”.

Return Value

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

Availability

• Mac OS X v10.4 and later.

See Also

• – initWithCGLayer:
• + imageWithCGLayer:options:

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

See Also

• + imageWithColor:

Declared In

CIImage.h

initWithContentsOfURL:

Initializes an image object from the contents of a file.

- (id)initWithContentsOfURL:(NSURL *)url

Parameters

url

The location of the file.

Return Value

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

Availability

• Mac OS X v10.4 and later.

See Also

• – initWithContentsOfURL:options:
• + imageWithContentsOfURL:

Declared In

CIImage.h

initWithContentsOfURL:options:

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

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

Parameters

url

The location of the file.

d

A dictionary that contains options for creating an image object. You can supply such options as a pixel format and a color space. See “Pixel Formats”.

Return Value

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

Availability

• Mac OS X v10.4 and later.

See Also

• – initWithContentsOfURL:
• + imageWithContentsOfURL:options:

Declared In

CIImage.h

initWithCVImageBuffer:

Initializes an image object from the contents of CVImageBuffer object.

- (id)initWithCVImageBuffer:(CVImageBufferRef)imageBuffer

Parameters

imageBuffer

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

Return Value

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

Availability

• Mac OS X v10.4 and later.

See Also

• – initWithCVImageBuffer:options:
• + imageWithCVImageBuffer:

Related Sample Code

• VideoViewer

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. For more information, see Core Video Programming Guide and Core Video Reference.

dict

A dictionary that contains options for creating an image object. You can supply such options as a color space. (The pixel format is supplied by the CVImageBuffer object.)

Return Value

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

Availability

• Mac OS X v10.4 and later.

See Also

• – initWithCVImageBuffer:
• + imageWithCVImageBuffer:options:

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

• Mac OS X v10.4 and later.

See Also

• – initWithData:options:
• + imageWithData:

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 that contains options for creating an image object. You can supply such options as a pixel format and a color space. See “Pixel Formats”.

Return Value

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

Availability

• Mac OS X v10.4 and later.

See Also

• – initWithData:
• + imageWithData:options:

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 retains this data 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

• Mac OS X v10.4 and later.

Declared In

CIImageProvider.h

See Also

• + imageWithImageProvider:size::format:colorSpace:options:

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 contents of the texture vertically.

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

• Mac OS X v10.4 and later.

See Also

• + imageWithTexture:size:flipped:colorSpace:

Declared In

CIImage.h

Constants

Pixel Formats

Image data pixel formats.

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

Constants

CIFormat

The data type for a pixel format.

kCIFormatARGB8

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

kCIFormatRGBA16

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

kCIFormatRGBAf

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

Declared In

CIImage.h

Color Space Key

A key for the color space of an image.

extern NSString *kCIImageColorSpace;

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.

Declared In

CIImage.h

---